🤖 fix: stop sub-agent progress reports from arriving late and stale - #4100

Summary

Sub-agent agent_report progress updates could reach the parent 8–40 minutes late, and — for a reawakened (workspace-turn continuation) child — kept arriving after the child's terminal report, each burning a full parent turn just to be dismissed as "a delayed interim report". This PR makes progress reports cut the parent's turn promptly even when a hidden turn-end entry sits ahead of them, and drops queued in-progress updates when the continuation that produced them settles.

Background

Diagnosed from the session shown in the report (Build React Native Xum mobile app, child Mobile UI Engineer). The child was reawakened via task_send_message; timeline (host clock):

Two independent causes:

1. Head-of-queue gating. MessageQueue.getNextDispatchableMode() (since 🤖 feat: refine transient transcript interactions #3790) only looks at the FIFO head, so the stream's hasQueuedMessages("tool-end") stop condition stays false while a hidden turn-end entry is at the head. Every child→ancestor peer message defaults to turn-end, so any progress report queued behind one waits for the parent's natural turn end. (The peer messages themselves were later refused as "sender no longer active" — they never delivered, they only blocked.)
2. Missing cleanup on continuation settlement. handleAgentReport removes queued agent-report:<child>: entries when a child's original run reports, but the workspace-turn continuation path (WorkspaceTurnManager.settleWorkspaceTurn) never did, so stale updates survived the terminal report.

Implementation

• MessageQueue: new internal option promoteAheadOfHiddenTurnEnd. A tool-end entry flagged with it is inserted ahead of the contiguous run of hidden (non-user-authored) turn-end predecessors, stopping at the first user-authored or tool-end entry — the user's visible "wait for turn end" choice is never pulled forward (the 🤖 feat: refine transient transcript interactions #3790 invariant). Reorders re-run revalidateWorkspaceTurnCorrelations() exactly like prioritizeNextUserEntry. addInternal now returns the entry so addOnce attaches the dedupe key to the promoted entry rather than the tail.
• reportAgentProgress: sets the flag and scopes the dedupe key to the active continuation execution (agent-report:<child>:<executionId>:<toolCallId>), so a settlement drops exactly the updates it superseded and never a successor execution's. Prefix/reason literals are centralized in src/constants/agentMessaging.ts.
• WorkspaceTurnManager.settleWorkspaceTurn: inside the settlement lock, before waiters resolve, removes agent-report:<child>:<handleId>: entries from the owner's queue, so a parent whose task_await just returned cannot be cut at its next step boundary by an update it already outran.
• Supersession must not fail the parent's own turn (Codex round 1): when the parent itself runs as a delegated workspace turn, each queued report carries continuation-failure callbacks. Both removal sites pass skipCancelCallbacks: true (new TurnAdmissionHost option), and wakeParentWorkspaceWithSyntheticMessage no-ops those callbacks for superseded wakes.
• Entries already dequeued into PREPARING (Codex round 2): progress sends carry a synchronous supersession probe through the existing admissionStale mechanism (stale once the child's status mirror shows reported/interrupted, or — for a continuation — a terminal execution status or a mirror that moved to a successor generation; all persisted before removal runs; a send-time consistency check falls back to removal-only supersession if the mirror ever lags), so AgentSession's turn-admission gates refuse a stale entry that prefix removal could no longer see. A probe already true at send time refuses the update outright.
• Promotion-aware correlation (Codex round 4): a promoted tool-end send judges whether a queued predecessor supersedes its workspace-turn correlation only against the entries it stays behind (MessageQueue.hasAllWorkspaceTurnContinuationsAheadOfPromotedToolEnd, sharing the trailing-run helper with the promotion), so a queued heartbeat cannot strip the correlation of a report that dispatches ahead of it. handleAgentReport also drops queued updates right after the reported commit rather than after artifact/goal/patch work. Interrupted transitions (recordTaskInterrupted, the choke point for task_stop and interrupt cascades) drop the child's queued updates the same way.

Validation

• Replayed the affected session's chat.jsonl files to reconstruct the timeline above (per-tool executionStartedAt vs. parent delivery timestamps).
• New unit tests: queue promotion (head becomes tool-end; user-authored turn-end barrier; FIFO preserved behind earlier tool-end entries; skipped continuation correlation stripped), execution-scoped key + flag on reportAgentProgress, and settlement-time removal ordered before waiter resolution.
• make static-check green; taskService, workspaceTurnManager*, workspaceService, messageQueue suites: 1142 pass / 0 fail.

Risks

• Queue ordering (medium, parent/child orchestration). Hidden turn-end entries can now dispatch later than a progress report queued after them. This only affects non-user-authored entries; peer messages already tolerate reordering (correlation revalidation is the same path used by "Send now" and the dispatch-mode dropdown). getQueueCutSupersedeEvidence still classifies a turn-end queued head as other_input (fail-toward-notify).
• Dropped updates (low). Removal is execution-scoped and happens only at terminal settlement, mirroring the existing original-run behavior; foreground waiters and the direct-parent envelope still deliver the terminal result.

Generated with xum • Model: anthropic:claude-fable-5-1 • Thinking: xhigh • Cost: $18.84