fix(#621): supervisor status injection during in-flight tool call wedges interactive session

[HenryLach]

Fixes #621.

Problem

The supervisor batch-end epilogue appends display banners via pi.sendMessage(msg, { triggerTurn: false }). In pi's sendCustomMessage, { triggerTurn: false } always takes the branch that immediately appends a custom entry to the session tree at the current leaf — even while the interactive agent is streaming. When a tool call is in flight (assistant tool_use appended, tool_result not yet appended), that append splices a user-role custom message between the tool_use and its tool_result. The next request then fails with:

Anthropic 400: messages.N.content.M: unexpected `tool_use_id` found in `tool_result`
blocks ... Each `tool_result` block must have a corresponding `tool_use` block in the
previous message.

which permanently wedges the interactive session (every retry re-sends the same broken ordering). Reproduced repeatedly in a real session, under both auto and supervised integration modes — the supervisor-integration-skipped banner is gated on (mode === "supervised" || mode === "auto") && phase !== "completed", so autonomy level is not the lever.

Fix

Gate the batch-end epilogue on interactive-agent idleness:

• SupervisorNoticeGate (supervisor-dispatch.ts): runs the epilogue immediately when idle (leaf is terminal → safe, banner renders now), else defers it to the next agent_settled boundary — the first lifecycle point at which all tool results, retries, compaction, and queued continuations have finished. Session-scoped, generation-tagged (a newer batch invalidates stale pending work), coalescing, and disabled on shutdown.
  • deliverAs:"nextTurn" is deliberately not used: it pushes into the next turn's in-memory context only, without persisting the entry or emitting message_start/end, so display banners would be silently dropped.
• stopBatchMonitoring() extracted from transitionToRoutingMode() and called eagerly when deferring, so a heartbeat-timer send cannot splice during the defer window.
• Wiring in extension.ts: one agent_settled flush (re-checks isIdle() — another extension may have started a run), one session_shutdown clear, invalidate() + generation bump on new batch, and both batch-end callbacks (doOrchStart / doOrchResume) routed through a shared runSupervisorBatchEndEpilogue() helper.

Tests

extensions/tests/supervisor-dispatch.test.ts (9 cases): idle→immediate, busy→defer, settle→flush, busy-settle→no flush, generation supersede, invalidate(), coalescing (latest wins), dispose(), flush-once.

Verification

• npm run typecheck clean
• biome clean on changed/new files (pre-existing warnings elsewhere untouched)
• Full extensions test suite: 3732 pass / 0 fail / 1 skipped, including the existing auto-integration + batch-summary suites (106) and the 9 new gate tests

Design

Design validated with a second-opinion review: agent_settled + a session-scoped, generation-aware dispatcher is the safest available design given the current pi API (there is no pi-native "persist+display a custom entry only at a safe turn boundary" mode).

Follow-up (not in this PR)

• Other background { triggerTurn: false } sends can splice via the same mechanism and should also route through the gate: heartbeat/status notices, and integration progress/result messages.
• extension.ts still registers the session_end event, which appears obsolete in current pi (only session_shutdown is defined); the gate uses session_shutdown. Worth reconciling the existing cleanup handler separately.

[HenryLach]

Recurrence on a non-batch-end path → added a comprehensive in-memory repair

After the epilogue gate landed, the 400 recurred with supervisor-batch-summary
spliced during an in-flight orch_integrate tool call — the integration-result
summary path, which the gate does not wrap (it only covers the batch-end monitor
callbacks). This confirms the class is broader than the batch-end epilogue: any of
the supervisor's background pi.sendMessage(..., {triggerTurn:false}) sites
(integration progress/result, heartbeat, routing) can splice the same way.

Rather than chase each send site, PR #622 now also repairs ordering on the pi
context event (fires before every provider request, on the pi-internal
AgentMessage[] before convertToLlm). repairToolResultOrdering() pulls each
assistant's tool results to immediately follow it and relocates any spliced-in
custom/user messages to after the tool-result group, so the outgoing request is
always valid regardless of which send site injected the stray message — a
mistimed injection can no longer wedge the session. It only transforms the
per-request context (the persisted tree is untouched), so it is idempotent and
self-correcting across reloads.

Net: the epilogue gate keeps the persisted tree clean for the common path, and the
context repair is the guaranteed safety net for all paths (present and future).
Full suite green (3741 pass / 0 fail); 18 new tests across the gate + repair.

[HenryLach]

Updated: Sage review remediations applied (commit 4b2cc8d)

Ran a Sage strategy review + code review of the two-layer fix. Applied all findings:

1. /orch-resume supersession gap (Sage caught a real lifecycle gap): doOrchStart bumped batchGeneration + invalidated the notice gate on restart, but doOrchResume did not — so an epilogue deferred mid-tool by the prior batch could fire against a resumed batch. Both paths now call a shared supersedeDeferredEpilogue() helper (extracted so they can't drift apart again — that drift was the bug).
2. repairToolResultOrdering hardening: queue-based result grouping (no data loss on duplicate results sharing a toolCallId), identity-based emitted tracking, result-before-assistant repair, safety-net no-drop guarantee, null-guarded toolUseIds.
3. CHANGELOG [Unreleased] entry incl. the behavior note that auto-integration may now start at the agent_settled boundary (bounded latency).

Tests: +24 total across context-repair.test.ts (13) and supervisor-dispatch.test.ts (11), including the FAILURE-MODE/FIXED resume-supersession pair and a compound result-before-assistant + parallel-group + splice fixture.

Sage code review verdict: no blocking issues, confidence ~0.9, release-ready.

Validation: typecheck ✅ · lint ✅ (286/671 baseline) · format ✅ · full suite ✅ 3747 pass / 0 fail / 1 skip · CLI smoke ✅