fix: Stop control signals from being dropped or ignored

[AlexanderZ-Band]

Why

A STOP or INTERRUPT should end the room's turn, but three layers each owned part of that and none owned all of it:

• Runtime: a turn only became controllable after its setup awaits, so a control during hydration was lost. A STOP during the contact-hub drain also re-queued events in a loop that never yielded, which froze the event loop.
• Adapters: stopping an external backend's turn was hand-written in three different shapes and missing from seven adapters, so stopped turns kept generating.
• Bridge: a STOP during startup rehydration crashed the whole bridge.

What

• Runtime: _turn_scope() is the only admission point. A scope can be terminated from the moment it is created and is settled on every exit, and TurnScope.admitted is removed. The synthetic drain returns STOPPED while the room is stopped and leaves its queue for PLAY.
• BackendTurns (in band.core.turn_lifecycle) is the shared way to stop a room's backend turn:
  • The task that owns the backend call holds running() around it, outside any timeout scope.
  • The stop is sent at most once, from a task the primitive owns, bounded by BACKEND_CANCEL_TIMEOUT_SECONDS, and never awaited on the control-processing task.
  • The room's next turn and its teardown wait for the stop to finish.
  • A stop that lands before the backend reveals its turn still reaches it: started() lets the call that starts the turn finish and stops the turn it names (codex turn/start); a continued a2a task is registered with its id up front.
  • An adapter supplies only its handle and its cancel call, through the backend_turns property; the default on_interrupt cancels through it.
• Eleven backend-driving adapters now use it:
  • ACP client, plus copilot_acp and omp_acp by inheritance: session/cancel. The next turn waits for that cancel before it resets the session or installs its handlers.
  • cursor_acp: session/cancel, inherited from the ACP client.
  • claude_sdk: CLI retirement.
  • codex: turn/interrupt.
  • copilot_sdk: session.abort().
  • opencode: watcher cancel, then a single session abort. A timeout abort stays on that owned stop, and the timeout report is not cancelled by its own stop.
  • letta: agent or conversation run cancel.
  • a2a: tasks/cancel. A bootstrap waits for a pending cancel before it rehydrates or addresses a task.
  • parlant: cancels the engine's process-session task and the preamble child that task leaves running.
• Guard: tests/framework_conformance/test_backend_stop.py fails for any band adapter that is neither probed against a recording backend nor pinned with a NoBackendTurn reason.
• Bridge: rehydration collects nudge results instead of failing on one cancellation. The bridge tests are split into kit.py plus one class per file.

Scope

Closes INT-1133 and INT-1781. Routing a control to a room that is still starting is followup INT-1782. No config, public signature or wire shape changes. TurnScope.admitted was internal. Merging this branch with main's retained-room lifecycle is followup INT-1809.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CLMomHCoGDhHacCw5hWsuA

[linear-code]

INT-1781

INT-1133

INT-1809

[AlexanderZ-Band]

Review of PR #791 (STOP/INTERRUPT ends the room's turn on every path).

Blocking: two confirmed stop-before-bind gaps (codex turn/start window, a2a continuation), the lost exception detail on failed backend stops, and test-quality issues (tautological/over-broad letta checks, scheduler-dependent opencode check, missing bridge ERROR-branch and scenario 14/16/18 coverage).

Edge-case/logic hypotheses dropped after reproduction: participant events during hydration (never reach adapters), claude_sdk retire ordering (worker cancelled first), _admit_turn closing re-check, overlapping running blocks, codex teardown drain (_retire_room refuses while stopping), bridge nudge /next window (pre-existing).

[AlexanderZ-Band]

Cycle 2 (fix-area review of 8674d21..a972bc7): converged, with no confirmed defect.

Dropped after reproduction:

• a2a continuation answered with a different task id: the a2a-sdk reference handlers reject a mismatched or terminal task id.
• codex turn/start slower than the 5s stop budget: the mechanism reproduces, but no production path reaches it (no request timeout, codex-rs answers after in-process setup, retry backoff is at most about 0.85s).

The remaining nits and suggestions are posted inline.

[bandzalkin]

Scope

Adversarial and architectural review of 6546c2c against 69e15a2. Four new reproduced blocking findings are inline (F1–F4). Prior resolved findings and accepted decisions were reconciled, not duplicated.

Constraints

Cancellation must stop backend work without blocking control processing, preserve originating-turn identity, and fence replacement work until stopping settles. Current main (d7ab342) also contains the retained-room ownership cutover from #709.

Decisions

Keep BackendTurns as the remote-cancellation mechanism, but enforce settlement before preparing replacement turn state, retain ownership across timeout transitions, and include engine-owned child generation in completion. Integrate with main's canonical retained-room owner rather than restoring obsolete retirement machinery.

Findings and proof

F1–F4 are P2 merge blockers: OpenCode timeout-abort ownership, Parlant child-generation ownership, ACP rollover isolation, and A2A bootstrap identity. Details and smallest corrections are inline. Focused tests: 510 passed, 4 skipped. Broader affected-consumer tests: 3,681 passed, 72 skipped. Ruff lint/format and Pyrefly passed. Additional behavioral probes reproduced every finding; F1 was compared against the base. Four real-engine Parlant probe outputs matched their expectations, but the additional child-task probe exposed F2. The Parlant pytest lane could not collect in the partial-dependency environment, so engine probes ran directly. No live-provider billing or production late delivery was exercised; no full-repository or merged-result sign-off is claimed.

Runtime admission/setup, synthetic STOP draining and bridge cancellation-isolation attacks were disproved. The PR also currently has merge conflicts in lifecycle owners and related tests; the resolved integration needs fresh verification and review.

Architectural verdict

HELD — not merge-ready. Resolve F1–F4 and the current-main integration conflicts, then verify and re-review the resulting revision.

[bandzalkin]

Scope

Re-review of 4d8c5cffa789fdc980df2a59eaefa04ce2ffb5d6, focusing on the fixes since 6546c2cc; aggregate PR base 69e15a20. Previous discussions and dispositions were reconciled.

Constraints

Backend cancellation must retain ownership until settlement, fence replacement-turn preparation, and include engine-owned child generation.

Decisions

Keep the shared BackendTurns mechanism. The OpenCode timeout-abort ownership fix (F1), ACP rollover barrier (F3), and A2A bootstrap barrier (F4) address the prior findings in the exercised paths. Parlant's child ownership remains incomplete.

Findings and proof

One failed-fix finding is inline on the current diff: F2 remains blocking, linked to its original discussion. No separate new blocker was confirmed. OpenCode held-abort STOP/INTERRUPT probes passed; ACP/A2A rollover regressions passed. The real Parlant 3.3.2 probe failed at preamble discovery, and independent real-engine diagnostics confirmed surviving child generation and accumulation across turns. Details are inline.

Focused checks: 371 passed, 4 skipped. Broader core/runtime/bridge/ACP/conformance checks: 3,867 passed, 73 skipped. Changed-file Ruff lint/format and project Pyrefly passed. The dev-environment skips include Parlant; its engine was exercised separately with a parked model boundary. The Parlant pytest lane could not collect in the isolated dev-parlant environment because conformance setup required the absent langgraph extra. No full-repository, live-provider, or merged-result sign-off is claimed.

GitHub still reports CONFLICTING / DIRTY; the resolved integration requires fresh verification and review.

Architectural verdict

HELD — not merge-ready. Correct F2, resolve the merge conflicts, and verify/re-review the resulting revision.

[AlexanderZ-Band]

The merge-conflict note in the 2026-10-15 re-review is real: this branch still conflicts with main after the retained-room owner (#709), stopped-room polling (#804), and the OpenAI adapter split (#802). The overlapping lifecycle files are listed on INT-1809. That integration is outside the Parlant preamble-identity fix. Tracked in https://linear.app/thenvoi/issue/INT-1809/integrate-pr-791s-backend-stop-with-mains-retained-room-owner