Harden the Codex turn lifecycle: bound stalls, stop abandoned upstream work, idle broker shutdown

[geoff-ux]

Summary

Stops a Codex run launched through this plugin from appearing "stuck," and makes a failed or abandoned run stop its upstream work instead of lingering. Five focused commits.

1. A wedged or dead turn no longer hangs forever (captureTurn)

captureTurn awaited state.completion, which resolves only on a terminal turn/completed notification (or the inferred-completion heuristic). It had no timeout and was not coupled to the app-server process, so two real situations left it pending forever:

• A hung MCP server. Codex blocks a turn until MCP init settles. A remote MCP server whose endpoint hangs (rather than failing fast) stalls the whole turn until its connection times out — observed at ~225s per turn for one misconfigured server, with the foreground task showing no output the entire time.
• App-server death mid-turn. handleExit only rejects in-flight RPCs; turn/start has already resolved by the time we await completion.

The wait is now bounded and the start RPC is inside the raced work, so a start that hangs or rejects before ACK is covered too. All env-overridable:

• CODEX_COMPANION_TURN_STALL_MS (default 600s) — no inbound traffic at all
• CODEX_COMPANION_TURN_TIMEOUT_MS (default 1800s) — absolute per-turn ceiling
• the app-server exitPromise — process death rejects immediately

Promise.race observes every guard from the outset, so a guard rejecting (even pre-ACK, or after the race settles) is always handled — no unhandledRejection.

2. Abandoned turns stop their upstream work

Stopping the wait is not enough on the shared broker: abandoning a turn there closed only the companion→broker socket, leaving the turn running upstream where it could keep mutating the workspace and collide with the next task. (The direct transport is fine — close() kills the app-server.) Two complementary stops:

• When the turn id is known, the companion sends a bounded turn/interrupt so the turn ends and the broker stays reusable.
• The broker self-terminates when the client owning in-progress upstream work disconnects before it finishes — whether a request is still in flight (a start that never ACKed) or a streaming turn ACKed but never reached turn/completed (e.g. the companion crashed before it could interrupt). The broker is single-flight, so no other work is at stake; it closes the upstream app-server and the next task reconnects to a fresh runtime. Covers owned and env-shared brokers uniformly. A turn that completed/was interrupted has already cleared activeStreamSocket, so a normal close does not trigger it.

3. Brokers self-shut-down when idle

The broker is keyed per-cwd and only reaped on a later ensureBrokerSession for the same cwd, with no idle self-shutdown — so a broker for a cwd never revisited (deleted worktree, ended session) ran forever and orphaned processes accumulated. It now exits after CODEX_COMPANION_BROKER_IDLE_MS (default 1800s) with no connected clients; shutdown() stops accepting connections before closing the upstream, so a client arriving at the teardown boundary is served or cleanly refused (ECONNREFUSED, which the companion retries), never accepted-then-failed.

4. The rescue forwarder surfaces errors instead of returning empty

codex-rescue.md and the codex-cli-runtime skill told the forwarder to "return nothing" on failure, masking a real failure as an empty response. It now returns the error output verbatim.

Tests

• never-completes, start-hangs, and start-rejects fake-codex behaviors.
• Fast-fail on a turn that never completes; on a start RPC that hangs (pre-ACK); and on a start RPC that rejects (pre-ACK, no unhandled rejection).
• A stalled brokered turn is interrupted upstream and tears the broker down.
• A pre-ACK abandonment makes the broker self-terminate rather than wait out its idle window.
• Broker idle self-shutdown.

All new tests pass (node --test). The watchdog, interrupt, idle-shutdown, and abandonment self-termination were also verified end-to-end against a live Codex install.

Notes

• No happy-path change: a normal turn resolves via state.completion and wins the race; a completed turn clears activeStreamSocket before close, so the broker is not torn down.
• Defaults are generous so long legitimate runs are unaffected; the env vars exist for tuning.
• For maintainers: broker teardown (idle or abandonment) closes the listener before the upstream to make the boundary served-or-retryable; a sub-millisecond accept-then-teardown window remains, shared with the existing idle path. Fully closing it would mean a broker-side request-cancellation/fencing primitive in the shared-concurrency model, which felt out of scope here — happy to follow up if you'd prefer it handled in this PR.