Flows: survive a harness tool timeout on Codex #1095

Problem

On Codex, a review round longer than five minutes ends in a harness error instead of kcap's benign "still running" reply, and the driver is left without the flow id.

What the driver received, 300 seconds into start_review_flow:

tool call error: tool call failed for `kcap-flows/start_review_flow`

Caused by:
    timed out awaiting tools/call after 300s

The reviewer was healthy and submitted its findings about six minutes later. The driver did wait patiently up to that point, and it correctly did not restart the flow — but with no id it could not call get_review_flow_status, so it went looking for one through analytics queries, session search and server source until the user stopped it and pasted the id in by hand.

Three things combine here:

1. The graceful cap is sized for one harness. PollCap in McpFlowsServer is 8 minutes, chosen to sit under the 10-minute MCP_TOOL_TIMEOUT the Claude Code plugin pins. Codex aborts at 300 seconds, and the Codex MCP registration writes no tool_timeout_sec for kcap-flows. So the "Flow still running for flow_run_id … call get_review_flow_status" reply — the one that carries both the id and the recovery step — is unreachable on Codex for any round over five minutes.
2. The flow id only travels in the response of the blocking call. A harness abort means it is never delivered. Context compaction can lose it later, too.
3. Nothing tells the agent what a harness timeout means. The error text is the harness's, so kcap cannot reword it. The review-flows skill explains the benign "Flow still running" text but says nothing about a harness-level tool timeout, and neither do the tool descriptions.

Proposal

Make the id recoverable. Make flow_run_id optional on get_review_flow_status and get_flow_status: when omitted, resolve the calling session's most recent open flow (with session_id passed explicitly, as the other kcap MCP servers take it). An agent's first move after a timeout is to call status, so the recovery should live there rather than in a separate list tool it has to discover mid-failure. When a session has more than one open flow, return the candidates instead of guessing. Needs the server lookup route — kurrent-io/kcap-server#1982.

Fit the cap under the harness, both ways:

• Write tool_timeout_sec = 600 into the Codex kcap-flows entry kcap owns, including for entries an earlier setup already created.
• Derive the blocking window from the MCP clientInfo reported at initialize, with a conservative default (under 300 s) for a client kcap does not recognise. The config value is user-editable and other harnesses have their own limits, so the server should not rely on it alone.

Say it before it happens. In the descriptions of start_review_flow, submit_review_round, start_flow and send_to_participant, and in the review-flows and agent-flows skills: the call blocks for minutes; a harness tool timeout means the flow is still running server-side; do not restart it and do not investigate — call the status tool with wait: true.

Acceptance

• A Codex-driven round longer than five minutes returns the benign "still running" reply, not a harness error.
• After a harness abort of start_review_flow, a bare get_review_flow_status(wait: true) reaches the run and returns its result.
• The same bare call recovers a flow after the driver's context was compacted.
• kcap setup on a machine with an existing Codex registration adds the timeout without disturbing entries it does not own.
• README and skill text describe the optional flow_run_id and the timeout guidance.

Not proposed

Returning the id immediately from start_* and moving all waiting to the status tool would remove the problem class, but costs a tool call per round and invites the driver to wander off instead of waiting. With the id recoverable and the cap fitted, it is not needed.