@pugi/cli 0.1.0-alpha.18 → 0.1.0-alpha.20

package/dist/core/repl/session.js

@@ -37,6 +37,8 @@ import { getJobRegistry } from '../jobs/registry.js';
 import { extractAskTags, extractPlanReviewTags, signatureForAsk, } from './ask.js';
 import { existsSync, readdirSync, statSync } from 'node:fs';
 import { resolve as resolvePath } from 'node:path';
+import { CancellationToken } from './cancellation.js';
+import { DispatchFSM } from './dispatch-fsm.js';
 const MAX_TRANSCRIPT_ROWS = 500;
 const MAX_TOOL_CALLS = 200;
 const MAX_RECONNECT_ATTEMPTS = 10;
@@ -134,6 +136,22 @@ export class ReplSession {
      * with `[store]` errors on every keystroke.
      */
     storeErrorEmitted = false;
+    /**
+     * Privacy mode fetched on bootstrap from /api/admin/privacy/mode and
+     * surfaced via `renderPrivacyBanner` (one-line system message after
+     * splash). Cached on the session so the in-REPL `/privacy` slash
+     * command can render the live mode without a second round-trip on
+     * the input box's thread. Null means "not yet fetched" (still
+     * connecting) OR "fetch failed" (offline / unauthenticated). The
+     * `/privacy` slash falls back to the contract doc with an "unknown"
+     * banner when null.
+     *
+     * Triple-review P1 fix (2026-05-25): the prior build defined
+     * `renderPrivacyBanner` but never called it, and `/privacy` always
+     * rendered with `null` mode. The contract was advertised but the
+     * operator had no mode visibility.
+     */
+    privacyMode = null;
     /**
      * α6.5 Tier 0 / Tier 1 / chokidar wiring. The bootstrap builds the
      * skeleton + working set + watcher once and hands them to the
@@ -204,6 +222,67 @@ export class ReplSession {
      * complete envelope lands OR the turn ends. (α6.3.)
      */
     askBuffer = new Map();
+    /**
+     * α6.9 dispatch FSM. One instance owned by the session; transitions
+     * are mirrored into `state.dispatchState` via an onEnter listener so
+     * subscribers see every change. Resets to `idle` after a terminal
+     * transition (`completed` / `failed` / `aborted`) so the next brief
+     * starts clean. Idle is the start state.
+     */
+    // Not readonly: resetFsmToIdle swaps the instance in place on the
+    // next brief after a terminal transition (the FSM does not allow
+    // direct `completed -> awaiting_response`, so we mint a fresh
+    // machine). External read-only access stays via `getDispatchState()`
+    // accessor - callers cannot reach into this private field.
+    fsm = new DispatchFSM();
+    /**
+     * α6.9 cancellation token for the currently in-flight dispatch.
+     * Minted on `dispatchBrief()` and released on terminal transitions.
+     * When non-null, calling `cancel()` aborts the token, closes the SSE
+     * stream, and transitions the FSM to `aborting` → `aborted`.
+     *
+     * Null when `dispatchState === 'idle'` — no dispatch to cancel.
+     */
+    currentDispatchToken = null;
+    /**
+     * R2 P1 fix (Codex triple-review 2026-05-25): monotonic dispatch
+     * sequence id. Incremented on every `dispatchBrief()`. The
+     * agent.spawned handler stamps the current value into
+     * `taskDispatchSeq[event.taskId]`. Terminal handlers
+     * (agent.completed / blocked / failed) check the stamped value
+     * against `dispatchSeq` and short-circuit if the event belongs to
+     * a SUPERSEDED dispatch. Without this gate a stale terminal event
+     * from a prior dispatch would drive the new FSM to terminal and
+     * null the new dispatch's token, leaving brief #2 uncancellable.
+     */
+    dispatchSeq = 0;
+    /**
+     * Per-task dispatch-sequence stamp. Populated on agent.spawned with
+     * the live `dispatchSeq` value. Consulted by terminal handlers to
+     * decide whether the event belongs to the current dispatch (seq
+     * matches) or a superseded one (seq is stale). Entries are NOT
+     * removed on terminal events because a late event from the same
+     * task should still be classified correctly; the map is small
+     * (one entry per spawned subagent in the session lifetime) and
+     * cleared on close().
+     */
+    taskDispatchSeq = new Map();
+    /**
+     * R3 P1 fix (Codex triple-review 2026-05-25): wall-clock guard used to
+     * drop SSE events whose `event.timestamp` predates the current
+     * dispatch. The R2 seq gate alone fails when a LATE `agent.spawned`
+     * from brief #1 arrives AFTER brief #2 mints a new dispatch token:
+     * the late spawn would stamp the OLD taskId with the NEW dispatchSeq
+     * (because `this.dispatchSeq` already advanced), so any subsequent
+     * terminal event for that task would look like it belongs to the new
+     * dispatch and would null the new token.
+     *
+     * Recorded inside `dispatchBrief()` BEFORE bumping `dispatchSeq`, so
+     * any event with `event.timestamp` strictly before this value is
+     * guaranteed to belong to a superseded dispatch and is dropped silently.
+     * Zero means "no dispatch has started yet" and disables the gate.
+     */
+    currentDispatchStartTime = 0;
     /**
      * Tracks taskIds that had an `<pugi-ask>` or `<pugi-plan-review>`
      * envelope mid-stream the last time the parser ran on the buffer. If
@@ -241,7 +320,20 @@ export class ReplSession {
             pendingAskSource: null,
             pendingPlanReview: null,
             pendingPlanReviewSource: null,
+            dispatchState: 'idle',
+            dispatchToolLabel: null,
         };
+        // α6.9: mirror every FSM transition into the public state so the
+        // status-bar surface can rerender on the next frame. Local listener
+        // is intentionally cheap — just a patch + clear the per-state tool
+        // label when leaving `tool_running`.
+        this.fsm.onEnter('idle', () => this.patch({ dispatchState: 'idle', dispatchToolLabel: null }));
+        this.fsm.onEnter('awaiting_response', () => this.patch({ dispatchState: 'awaiting_response', dispatchToolLabel: null }));
+        this.fsm.onEnter('tool_running', () => this.patch({ dispatchState: 'tool_running' }));
+        this.fsm.onEnter('aborting', () => this.patch({ dispatchState: 'aborting', dispatchToolLabel: null }));
+        this.fsm.onEnter('aborted', () => this.patch({ dispatchState: 'aborted', dispatchToolLabel: null }));
+        this.fsm.onEnter('completed', () => this.patch({ dispatchState: 'completed', dispatchToolLabel: null }));
+        this.fsm.onEnter('failed', () => this.patch({ dispatchState: 'failed', dispatchToolLabel: null }));
     }
     /* ------------- subscribe / state -------------- */
     subscribe(callback) {
@@ -270,18 +362,72 @@ export class ReplSession {
             });
             this.patch({ sessionId, connection: 'connecting' });
             this.openStream();
+            // alpha 6.13 privacy banner. Fire-and-forget - never blocks the
+            // input box on the network round-trip. The banner is a single
+            // system-line so the operator sees the active mode under the
+            // splash without an extra slash command. Mode is cached on the
+            // session so `/privacy` later renders the live value without a
+            // second fetch. Failure to fetch (offline, unauthenticated,
+            // admin-api down) is silent - the operator can still type
+            // `/privacy` to see the contract.
+            void this.fetchAndAnnouncePrivacyMode().catch(() => undefined);
         }
         catch (error) {
             this.appendSystemLine(`Could not open Pugi session: ${this.errorMessage(error)}`);
             this.patch({ connection: 'offline' });
         }
     }
+    /**
+     * Fetch the tenant's current privacy mode from
+     * `GET /api/admin/privacy/mode`, cache it on the session, and emit
+     * a one-line system banner so the operator sees their active mode
+     * right under the bootstrap splash. Failure is silent - missing
+     * banner is preferable to a noisy "could not fetch privacy mode"
+     * line on every login.
+     *
+     * Triple-review P1 fix (2026-05-25): without this call,
+     * `renderPrivacyBanner` was defined but never reached the wire, and
+     * `/privacy` always rendered with `null` mode.
+     */
+    async fetchAndAnnouncePrivacyMode() {
+        const { renderPrivacyBanner, isPrivacyMode } = await import('./privacy-banner.js');
+        try {
+            const url = `${this.options.apiUrl.replace(/\/+$/, '')}/api/admin/privacy/mode`;
+            const res = await fetch(url, {
+                headers: {
+                    authorization: `Bearer ${this.options.apiKey}`,
+                    accept: 'application/json',
+                },
+            });
+            if (!res.ok) {
+                // Silent fail - banner is decoration, not a blocking surface.
+                return;
+            }
+            const payload = (await res.json());
+            const mode = payload.mode;
+            if (typeof mode === 'string' && isPrivacyMode(mode)) {
+                this.privacyMode = mode;
+                this.appendSystemLine(renderPrivacyBanner(mode));
+            }
+        }
+        catch {
+            // Silent fail - offline / DNS / unauth all collapse to no banner.
+        }
+    }
     /**
      * Tear down the SSE stream and stop the reconnect timer. The session
      * id stays valid server-side; `pugi resume <id>` reopens later.
      */
     close() {
         this.closed = true;
+        // α6.9: fire the cancellation token before tearing down the stream
+        // so any in-flight tool sees the abort signal AND any pending
+        // PostBrief promise can short-circuit. Idempotent — token.abort()
+        // is a no-op when already aborted.
+        if (this.currentDispatchToken) {
+            this.currentDispatchToken.abort();
+            this.currentDispatchToken = null;
+        }
         if (this.streamHandle) {
             this.streamHandle.close();
             this.streamHandle = undefined;
@@ -290,6 +436,11 @@ export class ReplSession {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = undefined;
         }
+        // R2 P1: drop the per-task seq stamps on close(). The map is
+        // small but clearing prevents accidental seq-comparison drift if
+        // a resurrected session reuses taskIds (admin-api currently mints
+        // unique ids, but the gate stays robust on either contract).
+        this.taskDispatchSeq.clear();
         // Detach watcher listeners so any chokidar event landing between
         // session.close() and the bootstrap-owned watcher.close() does NOT
         // run a handler on a dead session. The handlers themselves also
@@ -301,6 +452,101 @@ export class ReplSession {
             this.watcher.off('capExceeded', this.filewatchCapHandler);
         }
     }
+    /* ------------- α6.9 cancellation surface -------------- */
+    /**
+     * Operator-driven abort for the in-flight dispatch. Idempotent — a
+     * second call while already in `aborting` / `aborted` is a no-op.
+     *
+     * Steps (in order):
+     *
+     *   1. Snapshot the current state. If terminal or idle, no-op.
+     *   2. Transition the FSM to `aborting` so the bottom-bar shows the
+     *      pending shutdown immediately (the operator gets feedback
+     *      before any IO completes).
+     *   3. Abort the cancellation token. This fans out to every listener
+     *      that was attached during the dispatch — chiefly the SSE
+     *      stream wrapper (which calls `streamHandle.close()`) and any
+     *      mid-flight tool executor that polled `isAborted`.
+     *   4. Append a system line so the conversation reads "Aborted." at
+     *      the operator's last input position.
+     *   5. Transition to `aborted` (terminal). The next operator brief
+     *      mints a fresh token + transitions back to
+     *      `awaiting_response`.
+     *
+     * Returns `true` when an abort was actually issued (state was
+     * non-terminal + non-idle), `false` otherwise.
+     */
+    cancel() {
+        const current = this.fsm.current;
+        if (this.fsm.isTerminal || current === 'idle')
+            return false;
+        // Step 2: transient state (UI sees `aborting` between abort signal
+        // and full shutdown).
+        this.fsm.transition('aborting', 'operator_abort');
+        // Step 3: fire the token so any mid-flight tool executor that
+        // polled `isAborted` shuts down. Token is single-use — clear the
+        // ref AFTER both the abort fan-out AND the stream teardown so any
+        // onAbort listener calling getCurrentDispatchToken() during the
+        // teardown observes the (now-aborted) token rather than null.
+        // Contract: listeners fire first, stream closes second, token
+        // field nulls third. (P2 cancel-ordering fix.)
+        const token = this.currentDispatchToken;
+        if (token) {
+            token.abort();
+        }
+        // Step 3b: tear down the SSE stream so no further `agent.step`
+        // events update the agent tree under the aborted dispatch. The
+        // stream reopens on the NEXT brief via `openStream()` (driven by
+        // dispatchBrief's reset-to-idle path). The session id stays valid
+        // server-side; admin-api keeps the dispatch around for forensic
+        // replay but the client stops listening.
+        if (this.streamHandle) {
+            this.streamHandle.close();
+            this.streamHandle = undefined;
+        }
+        // P2 Codex: clear the SSE cursor on deliberate cancel. The
+        // admin-api Last-Event-ID replay would otherwise re-feed any
+        // buffered events from the cancelled dispatch into the next
+        // brief's stream, polluting the agent tree with ghosts of the
+        // aborted turn. The new brief mints a fresh server-side cursor
+        // anyway, so `undefined` is the correct subscribe arg.
+        this.lastEventId = undefined;
+        // Null the token AFTER stream teardown (see step 3 comment).
+        this.currentDispatchToken = null;
+        // Mark any agents that are still "running" as failed/aborted so
+        // the agent-tree pane reflects reality. We use the existing
+        // `failed` status (the tree pane already knows how to render it)
+        // with a clear detail string so the operator sees WHY.
+        this.patch({
+            agents: this.state.agents.map((a) => a.status === 'queued' || a.status === 'thinking'
+                ? { ...a, status: 'failed', detail: 'aborted by operator' }
+                : a),
+        });
+        // Step 4: visible operator-facing confirmation. Brand voice gate:
+        // single ASCII line, no em-dashes, no emoji.
+        this.appendSystemLine('Aborted.');
+        // Step 5: terminal transition. The FSM will accept a fresh
+        // dispatch on the next brief.
+        this.fsm.transition('aborted', 'operator_abort');
+        // Clear briefStartedAtEpochMs so the status-bar clock resets.
+        this.patch({ briefStartedAtEpochMs: undefined });
+        return true;
+    }
+    /**
+     * Current FSM state. Surfaced for the REPL UI to read on first paint
+     * (subscribe + initial state are decoupled).
+     */
+    getDispatchState() {
+        return this.fsm.current;
+    }
+    /**
+     * Current cancellation token. Returned for the tool execution path
+     * (file-tools.ts) so it can pass the token down into a ToolContext
+     * extension. Null when no dispatch is in flight.
+     */
+    getCurrentDispatchToken() {
+        return this.currentDispatchToken;
+    }
     /* ------------- input handling -------------- */
     /**
      * Run one line of operator input through the slash command parser
@@ -396,12 +642,40 @@ export class ReplSession {
                 this.patch({ pendingAsk: askTag, pendingAskSource: 'local' });
                 return verdict;
             }
+            case 'privacy': {
+                // alpha 6.13: print the full mode contract + current banner
+                // inline. The current mode is resolved lazily by the helper -
+                // when unauthenticated or offline the banner falls back to
+                // "(unknown - mode lookup pending)" and the contract doc still
+                // renders so the operator can read the alternatives.
+                await this.dispatchPrivacy();
+                return verdict;
+            }
             case 'stub': {
                 this.appendSystemLine(verdict.message);
                 return verdict;
             }
         }
     }
+    /**
+     * In-REPL `/privacy` - alpha 6.13. Prints the full 3-mode contract
+     * doc + the current mode banner inline. The current mode is fetched
+     * via the admin-api /api/admin/privacy/mode endpoint when the
+     * operator is authenticated; otherwise the banner falls back to
+     * "(unknown)" and the contract doc still renders so the operator
+     * can compare modes without leaving the REPL.
+     */
+    async dispatchPrivacy() {
+        const { renderPrivacyContractDoc } = await import('./privacy-banner.js');
+        // Triple-review P1 fix (2026-05-25): use the bootstrap-cached mode
+        // so the operator sees the LIVE current mode in the banner header
+        // instead of "(unknown)". The fetch happens once on session start;
+        // if it failed (offline / unauth) the cache stays null and the
+        // banner falls back to "(unknown)" - same UX as before, just with
+        // the happy path actually delivering the mode.
+        const doc = renderPrivacyContractDoc(this.privacyMode);
+        this.appendSystemLine(doc);
+    }
     /**
      * In-REPL `/resume` - α6.4. Lists the 10 most recent sessions from
      * the local SessionStore and prints them as a numbered system menu.
@@ -863,6 +1137,92 @@ export class ReplSession {
         }
         this.appendOperatorLine(brief);
         this.patch({ briefStartedAtEpochMs: this.now() });
+        // α6.9 + R3 P1 (Codex triple-review 2026-05-25): supersede the
+        // prior dispatch when one is in flight. Steps in order:
+        //
+        //   1. Abort the old CancellationToken so any in-flight tool
+        //      holding `ctx.cancellation` sees `isAborted = true` and bails
+        //      (the R2 fix; preserves the file-tools cancellation gate).
+        //   2. Drive the OLD FSM through `aborting -> aborted` terminal.
+        //      This is load-bearing for the R3 race: a LATE event arriving
+        //      on the old FSM (`agent.spawned`, `agent.step`, terminal,
+        //      etc.) before the timestamp gate trips would otherwise still
+        //      attempt to transition the new FSM. Driving the old FSM to a
+        //      terminal state means the FSM check in
+        //      `advanceFsmOnDispatchEnd` (`isTerminal`) short-circuits as a
+        //      defense-in-depth layer.
+        //   3. `resetFsmToIdle()` mints a fresh FSM so the new dispatch
+        //      starts clean. The FSM legal-transition matrix forbids
+        //      `aborted -> awaiting_response`, so the reset is required.
+        //   4. Record `currentDispatchStartTime` BEFORE bumping
+        //      `dispatchSeq` + clearing `taskDispatchSeq`. The timestamp
+        //      gate in `handleServerEvent` checks
+        //      `event.timestamp < currentDispatchStartTime` to drop late
+        //      events from any superseded dispatch (including the late
+        //      `agent.spawned` that the R2 seq gate could not catch).
+        //   5. Clear `taskDispatchSeq` so any stamp left over from the old
+        //      dispatch cannot influence seq comparisons for the new turn.
+        //   6. Bump `dispatchSeq` and mint a fresh `CancellationToken`.
+        //
+        // If no prior dispatch is in flight (clean idle / terminal entry),
+        // the supersede block is skipped; we only reset the FSM if it sits
+        // in a terminal state from the prior turn.
+        if (this.currentDispatchToken) {
+            // Step 1: abort the old token. Listeners (including the
+            // file-tools cancellation gate) fan out before we replace the
+            // field below.
+            this.currentDispatchToken.abort();
+            // Step 2: walk the old FSM to terminal. Guard against an FSM
+            // that already sits in `aborting` or a terminal state - the
+            // legal-transition matrix forbids `aborting -> aborting` and
+            // forbids any outgoing transition from terminal states.
+            if (!this.fsm.isTerminal) {
+                if (this.fsm.current !== 'aborting') {
+                    this.fsm.transition('aborting', 'superseded_by_new_brief');
+                }
+                this.fsm.transition('aborted', 'superseded_by_new_brief');
+            }
+            // Step 3: fresh FSM so the new dispatch can walk
+            // `idle -> awaiting_response` cleanly.
+            this.resetFsmToIdle();
+        }
+        else if (this.fsm.isTerminal) {
+            // Prior turn ended naturally (completed / failed / aborted) with
+            // no live token left around. Reset only the FSM.
+            this.resetFsmToIdle();
+        }
+        // Step 4: record the dispatch start time BEFORE bumping the seq.
+        // The timestamp gate in `handleServerEvent` reads this value to
+        // decide whether an inbound event predates the live dispatch and
+        // should be dropped. Recording before the seq bump is critical:
+        // any concurrent SSE event landing between this line and the seq
+        // bump must still see a strictly-monotonic timestamp boundary.
+        this.currentDispatchStartTime = this.now();
+        // Step 5: clear the per-task seq stamps. Any leftover stamp from a
+        // superseded dispatch would otherwise look like it matched the new
+        // dispatchSeq (because the late `agent.spawned` for that taskId
+        // could stamp the OLD taskId with the NEW seq), nulling the new
+        // token via a stale terminal event. The timestamp gate is the
+        // primary defense; the clear is belt-and-braces.
+        this.taskDispatchSeq.clear();
+        // Step 6: bump seq + mint fresh token.
+        this.dispatchSeq += 1;
+        this.currentDispatchToken = new CancellationToken();
+        // The FSM is now `idle` (either fresh-start or post-reset). Walk
+        // to `awaiting_response` so the bottom-bar surface picks up the
+        // new dispatch state immediately.
+        if (this.fsm.current === 'idle') {
+            this.fsm.transition('awaiting_response', 'brief_dispatched');
+        }
+        // α6.9: re-open the SSE stream if a prior `cancel()` tore it
+        // down. Without this, the new brief would dispatch on admin-api
+        // but the client would never observe `agent.spawned` / `step` /
+        // `completed` — the operator would see a stalled status bar
+        // forever. Idempotent: openStream() short-circuits when a handle
+        // already exists or the session is closed.
+        if (!this.streamHandle && !this.closed) {
+            this.openStream();
+        }
         try {
             await this.options.transport.postBrief({
                 apiUrl: this.options.apiUrl,
@@ -873,8 +1233,79 @@ export class ReplSession {
         }
         catch (error) {
             this.appendSystemLine(`Brief dispatch refused: ${this.errorMessage(error)}`);
+            // α6.9: a failed brief POST never produced a turn, so we move
+            // the FSM straight to `failed` so the bottom-bar surfaces the
+            // outcome and the next brief can mint a fresh token.
+            this.markDispatchFailed('post_brief_failed');
         }
     }
+    /**
+     * α6.9: reset the FSM to `idle` after a terminal transition so the
+     * next brief can start. The FSM does not allow direct
+     * `completed -> awaiting_response`, so we mint a fresh FSM by
+     * overwriting the field. Listeners on the old FSM are dropped (they
+     * cannot fire again — terminal states have no outgoing transitions).
+     * The state.dispatchState patch happens via the new FSM's listeners
+     * which we re-attach immediately.
+     */
+    resetFsmToIdle() {
+        // Re-attach the same listeners on a fresh FSM instance. We cannot
+        // mutate `this.fsm` because it is `readonly`; but we mark it as
+        // mutable for this single reset path.
+        const next = new DispatchFSM();
+        next.onEnter('idle', () => this.patch({ dispatchState: 'idle', dispatchToolLabel: null }));
+        next.onEnter('awaiting_response', () => this.patch({ dispatchState: 'awaiting_response', dispatchToolLabel: null }));
+        next.onEnter('tool_running', () => this.patch({ dispatchState: 'tool_running' }));
+        next.onEnter('aborting', () => this.patch({ dispatchState: 'aborting', dispatchToolLabel: null }));
+        next.onEnter('aborted', () => this.patch({ dispatchState: 'aborted', dispatchToolLabel: null }));
+        next.onEnter('completed', () => this.patch({ dispatchState: 'completed', dispatchToolLabel: null }));
+        next.onEnter('failed', () => this.patch({ dispatchState: 'failed', dispatchToolLabel: null }));
+        // Swap the instance - the FSM does not allow direct
+        // `<terminal> -> awaiting_response`, so the next brief needs a
+        // fresh machine to walk from `idle`. Clean assignment (no cast)
+        // because `fsm` is no longer declared readonly.
+        this.fsm = next;
+        // State patch so subscribers see the idle transition immediately.
+        this.patch({ dispatchState: 'idle', dispatchToolLabel: null });
+    }
+    /**
+     * α6.9: short-circuit the FSM to `failed` on a non-recoverable
+     * dispatch error (network refusal, malformed event, etc). Idempotent
+     * — a second call from a terminal state is a no-op.
+     */
+    markDispatchFailed(reason) {
+        if (this.fsm.isTerminal)
+            return;
+        if (this.fsm.current === 'idle')
+            return;
+        // From `awaiting_response` or `tool_running` we can transition to
+        // `failed` directly per the legal-transition matrix. From `aborting`
+        // the only legal move is `aborted`, so skip — the abort path is
+        // already in motion.
+        if (this.fsm.current === 'aborting')
+            return;
+        this.fsm.transition('failed', reason);
+        // α6.9 P1 fix (Claude triple-review): postBrief threw between
+        // openStream() and dispatch registration server-side. The local
+        // SSE handle is open but listening for events under a dispatchId
+        // the admin-api never created. If we leave it open, any inbound
+        // event for a future dispatch on the same session would drive
+        // the FSM from terminal `failed` -> illegal target and throw
+        // IllegalDispatchTransitionError. Tear down so the next brief
+        // re-opens cleanly via dispatchBrief's openStream() gate.
+        //
+        // R2 P2 fix (Claude triple-review 2026-05-25): tear down the
+        // stream BEFORE nulling the token. Same ordering contract as
+        // `cancel()`: any onAbort listener fired during teardown should
+        // observe the (now-aborted) token via getCurrentDispatchToken()
+        // rather than null. Nulling the token first would race the
+        // teardown's listener fan-out against a stale null read.
+        if (this.streamHandle) {
+            this.streamHandle.close();
+            this.streamHandle = undefined;
+        }
+        this.currentDispatchToken = null;
+    }
     async dispatchStop(persona) {
         const sessionId = this.state.sessionId;
         if (!sessionId) {
@@ -1050,6 +1481,31 @@ export class ReplSession {
     }
     /* ------------- event reducer -------------- */
     handleServerEvent(event) {
+        // R3 P1 fix (Codex triple-review 2026-05-25): wall-clock gate that
+        // drops events from a SUPERSEDED dispatch. The R2 seq gate alone
+        // could not catch a LATE `agent.spawned` for an old taskId arriving
+        // AFTER `dispatchBrief` already bumped `dispatchSeq`. The late
+        // spawn would stamp the OLD taskId with the NEW seq, so the
+        // subsequent terminal event for that task looked current and
+        // nulled the freshly minted token. Comparing `event.timestamp`
+        // against `currentDispatchStartTime` (recorded BEFORE the seq
+        // bump) catches the late event before it can corrupt the seq map
+        // or drive the live FSM.
+        //
+        // `Date.parse` returns NaN on malformed input; we treat NaN as
+        // "unknown timestamp, do not drop" so a transport bug never
+        // silently swallows events. Zero `currentDispatchStartTime` means
+        // no dispatch has started yet (start() path) — same fail-open.
+        const eventTs = event.timestamp ? Date.parse(event.timestamp) : 0;
+        if (Number.isFinite(eventTs)
+            && eventTs > 0
+            && this.currentDispatchStartTime > 0
+            && eventTs < this.currentDispatchStartTime) {
+            // Late event from a superseded dispatch. Drop silently — the
+            // operator already saw the new brief land, and the new dispatch
+            // owns the surface now.
+            return;
+        }
         switch (event.type) {
             case 'agent.spawned': {
                 const persona = safePersonaName(event.role);
@@ -1086,6 +1542,12 @@ export class ReplSession {
                 else {
                     this.patch({ agents: [node, ...this.state.agents] });
                 }
+                // R2 P1 fix (Codex triple-review 2026-05-25): stamp the live
+                // dispatch sequence onto this taskId so terminal handlers can
+                // tell apart a "current dispatch" event from a "superseded
+                // dispatch" event. See `dispatchSeq` + `taskDispatchSeq`
+                // field comments.
+                this.taskDispatchSeq.set(event.taskId, this.dispatchSeq);
                 // The conversation pane already prefixes persona rows with the
                 // persona name in the persona's hue colour. Skip embedding the
                 // name in the body text to avoid the `Marcus Marcus dispatched`
@@ -1128,6 +1590,12 @@ export class ReplSession {
                 });
                 if (synthesised) {
                     this.appendToolCall(synthesised);
+                    // α6.9: a fresh tool call moves the FSM to `tool_running`
+                    // when the dispatch is still active. The status-bar surface
+                    // also gets a short label (`tool: read`, `tool: bash`, etc).
+                    // Aborting / terminal states are not allowed to transition
+                    // here — we silently skip rather than throw.
+                    this.advanceFsmOnToolStart(synthesised.tool);
                 }
                 this.patch({
                     agents: this.state.agents.map((a) => a.taskId === event.taskId
@@ -1164,6 +1632,12 @@ export class ReplSession {
                         ? { ...a, status: 'shipped', detail: 'shipped' }
                         : a),
                 });
+                // α6.9: transition the FSM to `completed` when no other
+                // dispatch is still in flight. The check uses the agents list
+                // POST-patch so any sibling task in `queued` / `thinking` keeps
+                // the dispatch alive; the FSM only goes terminal when the last
+                // agent ships.
+                this.advanceFsmOnDispatchEnd('completed', 'agent_completed', event.taskId);
                 if (target) {
                     // If the persona actually produced a reply via incremental
                     // agent.step events, render that reply in the transcript so
@@ -1224,6 +1698,11 @@ export class ReplSession {
                 if (target) {
                     this.appendPersonaLine(target.personaSlug, `blocked: ${event.detail}`);
                 }
+                // α6.9: `blocked` is a graceful refusal, not a crash — treat it
+                // as a `completed` outcome from the FSM's perspective so the
+                // operator sees the bottom-bar settle back to `idle` after the
+                // last block clears.
+                this.advanceFsmOnDispatchEnd('completed', 'agent_blocked', event.taskId);
                 return;
             }
             case 'agent.failed': {
@@ -1242,10 +1721,87 @@ export class ReplSession {
                 if (target) {
                     this.appendPersonaLine(target.personaSlug, `failed: ${event.error}`);
                 }
+                // α6.9: terminal `failed` transition when no sibling task
+                // remains. Same defer-until-last-agent semantics as
+                // `completed` so the bottom-bar surface tracks the dispatch
+                // collectively.
+                this.advanceFsmOnDispatchEnd('failed', 'agent_failed', event.taskId);
                 return;
             }
         }
     }
+    /**
+     * α6.9 helper: advance the FSM to `tool_running` when a tool call
+     * lands mid-dispatch. Guarded against terminal / aborting states so
+     * a late tool event after `cancel()` does not throw on an illegal
+     * transition. The `tool` label drives the bottom-bar's
+     * `tool: <kind>` granularity.
+     */
+    advanceFsmOnToolStart(tool) {
+        const current = this.fsm.current;
+        if (this.fsm.isTerminal)
+            return;
+        if (current === 'aborting')
+            return;
+        if (current === 'idle')
+            return;
+        // Only `awaiting_response -> tool_running` is a hard move. From
+        // `tool_running` we patch the label without a state transition so
+        // a multi-tool turn shows the latest tool's label without churning
+        // the FSM through transient idle states.
+        if (current === 'awaiting_response') {
+            this.fsm.transition('tool_running', `tool_${tool}`);
+        }
+        this.patch({ dispatchToolLabel: `tool: ${tool}` });
+    }
+    /**
+     * α6.9 helper: advance the FSM toward a terminal outcome when the
+     * LAST in-flight agent's lifecycle ends. The dispatch is "still
+     * running" when any other agent in the tree is in `queued` /
+     * `thinking`; the FSM only goes terminal when the last one settles.
+     *
+     * Idempotent + guarded against illegal transitions: a late event
+     * after a manual `cancel()` finds the FSM already in `aborted` and
+     * is silently dropped.
+     */
+    advanceFsmOnDispatchEnd(outcome, reason, taskId) {
+        // R2 P1 fix (Codex triple-review 2026-05-25): a terminal event
+        // for a SUPERSEDED dispatch must NOT advance the live FSM or null
+        // the live token. If the event carries a taskId and the stamped
+        // dispatchSeq for that task is older than the current dispatchSeq,
+        // the event belongs to a prior dispatch that was replaced by a
+        // newer `dispatchBrief()`. Silently drop the FSM advance.
+        if (taskId !== undefined) {
+            const taskSeq = this.taskDispatchSeq.get(taskId);
+            if (taskSeq !== undefined && taskSeq < this.dispatchSeq) {
+                // Stale dispatch event - the live dispatch is a newer turn.
+                // Skip the FSM advance + token null so brief #N+1 stays
+                // cancellable and the new turn's lifecycle is not corrupted.
+                return;
+            }
+        }
+        if (this.fsm.isTerminal)
+            return;
+        if (this.fsm.current === 'aborting')
+            return;
+        if (this.fsm.current === 'idle')
+            return;
+        // Defer until every agent has settled so a multi-agent dispatch
+        // collectively transitions once on the LAST settle.
+        const stillActive = this.state.agents.some((a) => a.status === 'queued' || a.status === 'thinking');
+        if (stillActive)
+            return;
+        // From `tool_running` we must walk through `awaiting_response`
+        // first (the legal-transition matrix forbids
+        // tool_running -> completed). The intermediate step is a one-tick
+        // pass through and immediately settles to terminal.
+        if (this.fsm.current === 'tool_running') {
+            this.fsm.transition('awaiting_response', `${reason}_drained`);
+        }
+        this.fsm.transition(outcome, reason);
+        this.currentDispatchToken = null;
+        this.patch({ briefStartedAtEpochMs: undefined });
+    }
     /* ------------- transcript helpers -------------- */
     /**
      * Look up the persona slug for a running task. Used by the tool call