feat: update the Captain’s Bridge explanation in the background with cancellation

[yia-mw-agent]

Closes #57. Parent: #53. Builds on merged #54 and #62. Bumps 0.3.0 to 0.4.0.

What changed

"Update walkthrough" in an open Captain's Bridge now runs a bounded background preparation instead of a plain skill message.

• request_walkthrough_update (app-only, read-only): rereads the exact chat in the portable view and returns a request: random requestId, threadId, and an immutable snapshot (source fingerprint, read time, record count). No server state, no process-local binding.
• Panel dispatches one ui/message asking the first officer to start exactly one read-only subagent, with no waiting or polling and no pause of project work. The subagent reads only the request's chat and runs no project task.
• deliver_walkthrough_update: validates citations against the snapshot's records only, keeps the snapshot's fingerprint and read time (so later chat changes mark it older, never fresh), and rejects forged chat/snapshot/identity. A failure report delivers no explanation.
• The panel owns the single active request and accepts only a matching, still-active requestId. Cancel, supersession, timeout, failure, duplicate submission, foreign and late/duplicate delivery all preserve the last useful view and never retry. A synchronous guard closes the double-click race during capture (found by the new test).
• Opening the Bridge starts nothing. Lifecycle documented in mcp/captains-bridge/README.md and skills/observe-chat.

Verification

Source verification (run): TMPDIR=/tmp scripts/verify.sh passes (588 repo tests, 35 Bridge Python tests, test_view/delivery/actions/preparation.cjs); version policy check passes.

Installed-host acceptance (NOT run): this worker has no Codex. Not established by synthetic tests: delivery reaching the panel after the parent turn finishes, separate real processes in Codex, substantive work continuing during preparation, subagent interrupt on cancel, and whether the parent can be made to call deliver_walkthrough_update briefly at a boundary. If the host cannot do any of these, that exact boundary should be reported rather than claimed. The first officer owns this acceptance before review/merge.

Known limit: the server cannot itself stop a subagent or detect a superseding instruction; the first officer does both from the panel's cancel message and the skill rules. Supersession by a new Captain instruction is therefore skill-driven, not enforced in code.

[timeleft--]

All 35 Bridge Python tests and four existing JavaScript suites pass on this exact head. Three material lifecycle/provenance failures reproduce with focused regressions using the existing fixtures. Please repair the same PR, grouping these causes before Captain-host acceptance.

1. Immutable snapshot is not enforced (preparation.py:44-56). Capture a request, change an existing record's text without changing its ID/count, then deliver: it succeeds and labels that new evidence with the old fingerprint/read time. Replacing snapshot.fingerprint with 64 zeroes also succeeds. Only syntax/count are checked; the child reads the later live chat rather than a preserved preparation snapshot. Preserve or verify the actual captured evidence and turn metadata across processes, and validate against that exact snapshot. Later appended records may legitimately mark it stale; changed captured records and an inconsistent digest must not be presented as the captured evidence. Add changed-record/digest regressions and correct the claimed forged-snapshot rejection.

2. Old acknowledgement failure clears a newer request (view.html:74). Begin A, cancel while A's ui/message acknowledgement is unresolved, start B, then reject A's acknowledgement: the unconditional catch calls clearPrep(), removing B and its cancel control. This reproduces with the existing VM harness and controlled RPC promises. Scope async error/settlement effects to the attempt that owns them; add cancellation/new-request/late-ack races.

3. Timeout does not stop the worker (view.html:73). The 10-minute callback only clears panel state and says the update was stopped. Running the timer in the existing preparation suite sends no interrupt/cancel message. Request stopping the corresponding child through the supported first-officer path, invalidate delivery immediately, and accurately distinguish requested stop from confirmed/unsupported stop. Verify this path without allowing timed-out work to survive into a later project turn; add a regression covering the stop handoff, including a failed handoff.

The worker's lack of Codex is not a blocker to these source repairs. The first officer still owns the required installed-host checks before approval/merge, including originating-panel routing, substantive work continuing, actual cancel/interrupt, supersession, separate processes and the parent-finishes-first boundary. Do not claim synthetic tests establish those behaviors.

[timeleft--]

The prior three defects are resolved in this head: independent 38 Python tests and four JavaScript suites pass, including captured-record verification, request-owned late acknowledgement behavior and timeout stop handoff. Required real-host lifecycle acceptance remains pending; it has not been waived.

PR #63 has now merged child #58 as main 8b803d3. Please merge current main into this existing worker branch (no rebase or force-push), preserve the merged layout/timing disclosure and host-theme contrast repairs together with this background lifecycle, and run the repository-local version updater after the base update as required by AGENTS.md/version policy. The current exact head fails mw-version.py check against current origin/main with 'branch is behind current base; update the branch and rerun the updater'. Both previous candidates used 0.4.0; the updated feature candidate must satisfy the policy against the new 0.4.0 base. Run the appropriate regression and packaging checks, push the same PR, and leave the existing audit. Captain owns real installed Codex tests; do not invent a worker host receipt or add another root/viewer.

[timeleft--]

Reviewed current head fdcedbacdef12a616e5f4b01fae5954d87515622. The earlier provenance, stale-settlement and stop-request fixes remain present, and the merge from main preserves PR63 navigation and contrast repairs.

PR65 has now merged as 0013ed73e67f26526717b7b8a6e02c6b398b727c, delivering direct read-only Refresh and version 0.5.0. The mandatory current-base check now fails: branch is behind current base; update the branch and rerun the updater.

Merge current origin/main into this existing branch, preserve both PR63 and PR65 behavior, run the repository-local version updater (the feature must advance from current main 0.5.0), then run normal verification and push the same PR. Do not rebase, force-push or replace the PR. Captain-host background lifecycle acceptance remains required before approval; the first officer owns that check after the integrated candidate is installed.

[timeleft--]

The installed combined candidate contains this exact PR64 head unchanged. Required source checks and the existing synthetic lifecycle tests pass, but the real Codex host exposes a material delivery boundary.

A single read-only preparation agent read the originating chat with valid paging and called deliver_walkthrough_update once. The server returned a validated walkthrough with the captured fingerprint/read time and matching request identity. The parent had already finished. The originating panel retained the old explanation and updating notice, then reached its 10-minute timeout; the timeout message reached the first officer in a subsequent turn. Interrupting the agent reported that it had already completed. Its result was discarded. A preceding failure result likewise did not settle the originating panel. No successful background rendering or running-worker interruption is claimed.

Resolve this on the existing PR using the existing implementation and tests. Probe the supported host delivery seam before building another mechanism: either deliver and settle the still-active originating panel through a supported route, including the parent-finishes-first boundary, or explicitly report this Codex boundary as unsupported and end the attempt as issue #57 requires. Do not leave an already completed or failed preparation displaying progress until an unrelated timeout. Preserve validated provenance, request ownership, cancellation invalidation, direct agent-free Refresh, the merged layout fixes, and the no-retry/no-project-execution behavior. Document the measured host limit accurately, distinguishing delivery to the server from rendering in the original panel.

Use the same canonical worker root/PR and normal version/review checks; do not replace the prototype, add a second queue/observer, edit installed caches, or invent a host success receipt. The Captain has rejected repeated reload/restart/expansion loops. Reuse current source and browser receipts where unchanged; no further user activation loop is an acceptance strategy. First officer owns any remaining real-host check.

[timeleft--]

Reviewed exact repaired head 24e7de9. The changed preparation JavaScript suite, version policy and whitespace checks pass; unchanged source/installed-host evidence remains reusable. The README now records the measured parent-finishes-first boundary accurately.

The requested unsupported-host alternative is not yet complete. Only warning text changed: startPrep still captures and dispatches an attempt on the known unsupported Codex route, and only the same ten-minute timer ends it. Issue #57 explicitly permits reporting an unsupported host boundary and ending the attempt; implement that bounded alternative for this measured route instead of retaining the ineffective wait. Preserve the preparation/delivery interfaces and tests, provenance, cancellation guards, and direct read-only Refresh. Do not build a new queue or retry mechanism, and do not require another user reload to rediscover the same host boundary.

Also remove the timeout claim that an already-finished agent means its result reached the server. Agent completion alone establishes neither a successful deliver call nor validated delivery; the panel does not know that outcome. State only the known host limitation, preserve the last view, and distinguish stop requested from confirmed. Add a focused check that the unsupported route ends without capture/dispatch or a ten-minute progress lifecycle, and retain a permitted supported route if one is actually available.

This is the same existing worker PR/root. Reuse unchanged source/browser receipts and run the normal version checks. First officer will prepare one integrated candidate after the source repair; repeated activation cycles are not required or authorized as a substitute for repair.

[timeleft--]

Reviewed exact worker head 058330c against issue #57, including its explicit alternative for an unsupported host boundary. The prior source and provenance/race repairs remain intact. Independent 65 Bridge Python tests, all five JavaScript suites, current-base version policy and whitespace checks pass; all six required GitHub source checks pass.

The installed Codex probe established that a validated child result did not reach the originating panel after the parent finished. Background rendering and running-worker interruption are not claimed. This repair now ends the unsupported route immediately, before snapshot capture, agent dispatch or a timer, and preserves the last view. The timeout no longer infers delivery merely from agent completion. The existing preparation/delivery interfaces and race tests remain available for an explicitly capable host; that opt-in path has synthetic coverage only.

The changed source renderer was also exercised in an isolated browser: the unsupported message appears promptly, no message is sent, and the prior walkthrough remains readable. Unchanged installed Refresh/navigation/theme and separate-process evidence is reused. No new reload was used to rediscover the measured boundary. The documentation records the limit. This accepts the required unsupported-host alternative, not working background updates in the current Codex host.

No material findings remain on this head. Container-preview/publication readiness remains separate, and final installation/update acceptance belongs to child #61. The existing combined PR66 must incorporate this accepted revision and the resulting main/version before its own review.