bot-bottle/docs/prds/prd-new-nonblocking-supervise.md

# PRD prd-new: Non-blocking supervise (async approval + proposal polling)

- **Status:** Draft
- **Author:** didericis
- **Created:** 2026-07-18
- **Issue:** #412

## Summary

The per-bottle supervise MCP server (`bot_bottle/supervise_server.py`)
answers `tools/call` **synchronously**: it queues the agent's proposal and
blocks the tool call polling for the operator's decision. On timeout it
returns `status: pending` and leaves the proposal queued — but it hands the
agent **no proposal id** and offers **no way to poll a specific pending
proposal**, so the only way to learn the outcome is to re-propose (a
duplicate).

This PRD makes the MCP flow non-blocking and pollable, so an approval can
happen out-of-band (a human taking minutes-to-hours in a review console)
without holding an HTTP request open or wedging the agent:

1. Include the `proposal_id` in the `pending` response.
2. Add a `check-proposal` MCP tool: a non-blocking status lookup by
   proposal id.
3. Keep the short synchronous grace window for the common "operator is
   right there" fast path.

## Problem

`handle_tools_call` → `_sv.wait_for_response(...)` blocks up to
`SUPERVISE_RESPONSE_TIMEOUT_SECONDS` (default 30s). Two problems follow:

- **Human latency ≠ tool-call latency.** A real review — rendered diff,
  RBAC routing to an approver, someone tapping approve on their phone — is
  minutes-to-hours. Holding the MCP request open that long is fragile
  (proxy/keepalive timeouts, the mitmproxy egress hop, and the agent
  harness's own tool-call timeout, which a long block can trip and stall
  the whole turn).
- **No resume path.** The pending fallback already exists, but without a
  proposal id and a poll tool the agent can't reconnect to that specific
  decision — it re-proposes, duplicating the queue entry.

This is also the precondition for the planned web-console human-review
flow (RBAC, audit retention, mobile) — see issue #412.

**Safety note:** the MCP tools only *propose* policy changes; enforcement
stays at the egress proxy and the git-gate. Returning early on `pending`
therefore opens no hole — the agent still cannot egress or push anything
unapproved.

## Goals / success criteria

- A `pending` MCP response carries the `proposal_id`.
- An agent can call `check-proposal(proposal_id)` and get the current
  state (`pending` | `approved` | `modified` | `rejected`) **without
  blocking** and **without creating a new proposal**.
- The synchronous fast path (operator approves within the grace window) is
  unchanged: the first `tools/call` still returns the decision directly.
- No change to enforcement, attribution (source-IP → bottle), or the
  operator-side queue/response schema.

## Non-goals

- The git-gate `pre-receive` path (it is synchronous by nature and cannot
  poll — its async variant is reject-fast + re-push; tracked as a
  follow-up).
- Backpressure / in-flight-proposal caps.
- MCP server→client notifications (event-driven resume).
- Any web-console UI (this PRD is the protocol groundwork it needs).

## Design

### `pending` response carries the id

`handle_tools_call`'s timeout branch formats the pending text with the
`proposal.id` and a pointer to `check-proposal`, so the agent knows what to
poll.

### `check-proposal` tool

A new read-only MCP tool (`TOOL_CHECK_PROPOSAL = "check-proposal"`),
attributed to the calling bottle by source IP exactly like the proposal
tools. Input: `{ "proposal_id": string }`. Behavior:

1. `read_response(slug, id)` →
   - **found**: archive the proposal (same terminal step the synchronous
     path takes) and return the decision via `format_response_text`;
     `isError` iff rejected.
2. **not found** → `read_proposal(slug, id)` →
   - **found**: still queued → return `status: pending`.
   - **not found**: unknown id, or already resolved-and-archived (e.g. a
     second poll) → return `status: unknown`, `isError: true`.

Both lookups already raise `FileNotFoundError` when absent
(`queue_store.py`), so the handler needs no new store methods. `check-`
`proposal` is the only path (besides the synchronous response) that
archives, so a proposal that times out to `pending` stays visible to the
operator until it is decided and then polled.

### Grace window

Left at the existing 30s default (`SUPERVISE_RESPONSE_TIMEOUT_SECONDS`),
which doubles as the instant-approve fast path. Tuning it down is an
operator setting, not a code change; noted for the console rollout.

## Implementation chunks

1. **(this PR)** `TOOL_CHECK_PROPOSAL` constant; `check-proposal` tool
   definition + `handle_check_proposal`; dispatch wiring; `proposal_id` in
   the pending text; unit tests. Files: `bot_bottle/supervise_types.py`,
   `bot_bottle/supervise.py` (re-export), `bot_bottle/supervise_server.py`,
   `tests/unit/test_supervise_server.py`.
2. **(follow-up)** git-gate `pre-receive` reject-fast + re-push.
3. **(follow-up)** per-bottle in-flight-proposal backpressure cap.
4. **(follow-up)** MCP notifications for event-driven resume; web-console
   review flow (RBAC, audit retention) on top.

## Open questions

- Should a resolved-but-unpolled proposal auto-archive after some TTL, or
  only on poll? (Leaning: only on poll, so a decision is never lost to a
  reaper before the agent sees it.)
- Does the agent harness need an explicit "you have a pending proposal"
  nudge, or is returning `pending` from the original call enough? (Deferred
  to the notifications chunk.)