@north-light/crouter 0.3.172 → 0.3.174

package/dist/core/runtime/broker/frame-dispatch.js

@@ -0,0 +1,1537 @@
+import { execFile } from 'node:child_process';
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { AUTH_FAULT_RECOVERY_BODY } from '../../../shared/generated-context.js';
+import { emitEvent } from '../../events/emit.js';
+import { operationIdContext } from '../../events/operation-id.js';
+import { buildRefInventory } from '../../memory/inline-ref-inventory.js';
+import { buildGuidance } from '../../memory/inline-ref-guidance.js';
+import { clearSessionCache } from '../../substrate/session-cache.js';
+import { configuredLadderProviders, isProviderPinnedModelToken, nextLadderModel, normalizeModel, } from '../launch.js';
+import { clearFault, readFault } from '../fault.js';
+import { isManagedProvider, readSubscriptionPool, } from '../../subscription-state.js';
+import { SessionListCache } from '../session-list-cache.js';
+import { sessionListCachePath } from '../../canvas/paths.js';
+import { REVIEW_BOUNDARY_CUSTOM_TYPE } from '../session-visibility.js';
+import { isUnknownModel, parseModelSpec } from '../model-selection.js';
+import { buildCommandList, buildGetTreeData, buildListMemoryRefsData, buildListModelsData, buildScopedModelsData, buildSessionsData, buildSettingsData, modelKey, } from './read-ops.js';
+export const REVIEW_BOUNDARY_NAVIGATION_CODE = 'review_boundary_navigation';
+export class ReviewBoundaryNavigationError extends Error {
+    targetId;
+    code = REVIEW_BOUNDARY_NAVIGATION_CODE;
+    constructor(targetId) {
+        super(`review companion cannot navigate before the visible transcript boundary (target: ${targetId})`);
+        this.targetId = targetId;
+        this.name = 'ReviewBoundaryNavigationError';
+    }
+}
+/**
+ * Route a writable client's `prompt`/`follow_up` frame against the LIVE session
+ * state. The client picks its frame type off a possibly-STALE `isStreaming`
+ * snapshot, so the broker is authoritative and the client's choice is a HINT:
+ *
+ *  - m-B (streaming-safe prompt): a `prompt` arriving mid-stream needs
+ *    PromptOptions.streamingBehavior ("Required if streaming"; prompt() throws
+ *    without it). "steer" mirrors pi interactive-mode's own
+ *    Enter-while-streaming submit (`prompt(text, { streamingBehavior: "steer" })`).
+ *  - m-C (idle-safe follow_up): pi's followUp() only enqueues into a RUNNING
+ *    agent loop — on an idle session nothing ever drains the queue and the text
+ *    is silently lost. An idle `follow_up` therefore runs as a prompt now.
+ *
+ * driveEngine calls this synchronously with `session.isStreaming`, so the
+ * routed state cannot go stale between the check and the engine call.
+ * C1: images ride as a field on PromptOptions (pi: `prompt(text, { images })`).
+ */
+export function resolveEngineRoute(frame, isStreaming) {
+    if (frame.type === 'follow_up' && isStreaming)
+        return { call: 'followUp' };
+    const options = {};
+    if (frame.images !== undefined)
+        options.images = frame.images;
+    if (isStreaming)
+        options.streamingBehavior = 'steer';
+    return { call: 'prompt', options };
+}
+/**
+ * True iff `text` would be consumed by pi's OWN leading-name preflight before
+ * `session.prompt/steer/followUp` ever sees it as prose — an extension command
+ * (`session.extensionRunner.getCommand`), a `/skill:name` skill, or a `/name`
+ * prompt template (mirrors `_tryExecuteExtensionCommand` / `_expandSkillCommand`
+ * / `expandPromptTemplate` in the pinned SDK verbatim, including the exact
+ * name-parsing substrings). Inline memory-reference guidance must NEVER fire
+ * for these — the leading token routes to the engine's own command surface,
+ * not prose referencing a memory doc. Each lookup is independently wrapped so
+ * an engine missing one accessor (the fake, or a degraded session) degrades
+ * that check to "not a match" rather than aborting the whole classification —
+ * matching `buildCommandList`'s existing "no live extensionRunner" tolerance.
+ */
+export function isLeadingEngineCommand(text, session) {
+    if (text.startsWith('/')) {
+        const spaceIndex = text.indexOf(' ');
+        const commandName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
+        try {
+            if (session.extensionRunner?.getCommand(commandName))
+                return true;
+        }
+        catch {
+            /* engine without a live extensionRunner (e.g. the fake) — not a match */
+        }
+    }
+    if (text.startsWith('/skill:')) {
+        const spaceIndex = text.indexOf(' ');
+        const skillName = spaceIndex === -1 ? text.slice(7) : text.slice(7, spaceIndex);
+        try {
+            if (session.resourceLoader?.getSkills().skills.some((s) => s.name === skillName))
+                return true;
+        }
+        catch {
+            /* engine without a live resourceLoader — not a match */
+        }
+    }
+    if (text.startsWith('/')) {
+        const match = text.match(/^\/([^\s]+)(?:\s+([\s\S]*))?$/);
+        const templateName = match?.[1];
+        if (templateName !== undefined) {
+            try {
+                if (session.promptTemplates?.some((t) => t.name === templateName))
+                    return true;
+            }
+            catch {
+                /* engine without a live promptTemplates getter — not a match */
+            }
+        }
+    }
+    return false;
+}
+/** A `steer` frame normally maps directly to pi's steer queue. Engine commands,
+ * skills, and templates must instead pass through prompt()'s leading-command
+ * preflight; with streamingBehavior:'steer', ordinary expanded text still lands
+ * in the same queue. */
+export function resolveSteerCall(text, session) {
+    return isLeadingEngineCommand(text, session) ? 'prompt' : 'steer';
+}
+/**
+ * Enumerate every leading-token STRING this session's engine would
+ * independently consume as a leading command/skill/template dispatch BEFORE
+ * inline memory-reference guidance ever applies — the read-op sibling of
+ * `isLeadingEngineCommand`'s point-lookup, gathered as a full enumeration for
+ * viewer-side suppression instead of a per-submission membership check. Same
+ * three sources, same shape of the leading match `isLeadingEngineCommand`
+ * checks (bare extension-command invocation names and prompt-template names,
+ * `skill:<name>` for skills), so `/${token}` round-trips through
+ * `isLeadingEngineCommand(text, session)` for every emitted token (locked by
+ * a test). Kept STRICTLY separate from `buildCommandList` (command
+ * completion) and the ref inventory (`RefMeta` rows) — this is neither.
+ */
+export function engineLeadingCommandTokens(session) {
+    const out = [];
+    try {
+        for (const c of session.extensionRunner?.getRegisteredCommands() ?? [])
+            out.push(c.invocationName);
+    }
+    catch {
+        /* engine without a live extensionRunner (e.g. the fake) — none */
+    }
+    try {
+        for (const s of session.resourceLoader?.getSkills().skills ?? [])
+            out.push(`skill:${s.name}`);
+    }
+    catch {
+        /* engine without a live resourceLoader — none */
+    }
+    try {
+        for (const t of session.promptTemplates ?? [])
+            out.push(t.name);
+    }
+    catch {
+        /* engine without a live promptTemplates getter — none */
+    }
+    return out;
+}
+/**
+ * Choose how the hidden `crtr-memory-refs` guidance custom message rides
+ * alongside a human frame's own engine call (design Flow B). Pure over the
+ * frame's routing outcome — never reads live session state itself, so a
+ * caller can decide the delivery mode from the exact same `route`
+ * `resolveEngineRoute` already computed for the human call.
+ *
+ *  - `steer` frame              -> 'steer' (always; no route call exists).
+ *  - a TRUE mid-stream follow_up (`routeCall === 'followUp'`) -> 'followUp'.
+ *  - every other `prompt`/`follow_up` routed as `routeCall === 'prompt'`:
+ *    idle -> 'nextTurn' (the ONLY case guidance precedes the human call —
+ *    pi's `prompt()` reads+clears its pending-nextTurn queue synchronously
+ *    into the SAME turn as the new user message); streaming (m-B
+ *    steer-while-streaming) -> 'steer', never 'nextTurn' (that would attach
+ *    to a later, unrelated turn).
+ */
+export function chooseGuidanceDeliveryMode(frameType, routeCall, isStreaming) {
+    if (frameType === 'steer')
+        return 'steer';
+    if (routeCall === 'followUp')
+        return 'followUp';
+    return isStreaming ? 'steer' : 'nextTurn';
+}
+/**
+ * Deliver a `nextTurn` guidance custom message ATOMICALLY around the idle-
+ * prompt call it's meant to ride alongside. Pi's `_pendingNextTurnMessages`
+ * queue (the only public seam for `deliverAs:'nextTurn'`) is drained ONLY deep
+ * inside `session.prompt()`, well after several await points — extension-
+ * command interception, the `input` extension transform, a streaming reroute,
+ * model/auth validation, pre-turn compaction — that can return or throw BEFORE
+ * the drain ever runs. `sendCustomMessage`'s nextTurn branch pushes
+ * synchronously and unconditionally, so any of those early exits strands the
+ * pushed guidance in the queue to attach itself to whichever LATER, unrelated
+ * prompt happens to reach the drain first.
+ *
+ * There is no public SDK seam to observe or cancel a pending nextTurn message
+ * (`_pendingNextTurnMessages` is TS-`private` only — a plain runtime field, not
+ * `#private`), so this reaches into that one field and removes EXACTLY the
+ * entry this call pushed, identified by object identity via a locally-
+ * generated marker riding the message's own `details` field (never surfaced to
+ * the model, and irrelevant if the message WAS consumed normally — `details`
+ * is just carried through like any other field once folded into a real turn).
+ * Runs UNCONDITIONALLY after the human call settles, success or failure/early-
+ * return alike — a "successful" `prompt()` promise can just as easily be an
+ * early return that skipped the drain (an intercepted extension command, an
+ * `input` transform, a streaming reroute) as a genuine consumed turn, so only
+ * checking `.catch` is not enough.
+ */
+export async function promptWithNextTurnGuidance(session, guidance, runPrompt) {
+    // Must survive Pi's structured-clone step when the queued custom message is
+    // folded into the turn. A Symbol reaches that step in `details` and aborts
+    // the real prompt with "could not be cloned" before the provider runs.
+    const marker = `crtr-memory-refs-pending:${randomUUID()}`;
+    let queued = false;
+    try {
+        await session.sendCustomMessage({ customType: 'crtr-memory-refs', content: guidance, display: false, details: marker }, { deliverAs: 'nextTurn' });
+        queued = true;
+    }
+    catch (err) {
+        emitEvent({
+            level: 'warn',
+            event: 'broker.memory_refs.guidance_send_failed',
+            error: err,
+        });
+    }
+    try {
+        await runPrompt();
+    }
+    finally {
+        if (queued)
+            clearOwnPendingNextTurnGuidance(session, marker);
+    }
+}
+/** Splice out exactly the pending-nextTurn entry `marker` identifies (object-
+ *  identity match on `details`), if it is still present — a no-op (and safe)
+ *  if `session.prompt()` already drained it normally, or if the session/field
+ *  shape doesn't match (defensive against an engine without the field, e.g. a
+ *  future SDK bump or a structurally-different test double). */
+function clearOwnPendingNextTurnGuidance(session, marker) {
+    const pending = session._pendingNextTurnMessages;
+    if (!Array.isArray(pending))
+        return;
+    const idx = pending.findIndex((m) => m?.details === marker);
+    if (idx !== -1)
+        pending.splice(idx, 1);
+}
+/** True iff a parsed JSONL branch-entry line is a hidden (`display:false`)
+ *  custom message — the general display boundary crossed if left in an
+ *  exported branch (not just `crtr-memory-refs` guidance; any hidden custom
+ *  content). Covers both persisted shapes a branch entry can take: a
+ *  `type:'custom_message'` entry (display at the entry's own top level) and a
+ *  `type:'message'` entry wrapping a `role:'custom'` message (display nested
+ *  under `.message`). */
+export function isHiddenJsonlBranchEntry(entry) {
+    if (entry === null || typeof entry !== 'object')
+        return false;
+    const e = entry;
+    if (e.type === 'custom_message' && e.display === false)
+        return true;
+    if (e.type === 'message' && e.message?.role === 'custom' && e.message.display === false)
+        return true;
+    return false;
+}
+/** Rewrite an already-exported JSONL file in place, dropping every hidden
+ *  (`display:false`) branch entry while re-chaining `parentId` so the
+ *  remaining entries stay a single valid linear branch — applying the general
+ *  display:false boundary to `session.exportToJsonl`'s own output, which
+ *  serializes every entry verbatim regardless of display. The header line
+ *  (line 1) is copied through untouched. */
+export function stripHiddenEntriesFromJsonlExport(filePath) {
+    const raw = readFileSync(filePath, 'utf8');
+    const lines = raw.split('\n').filter((l) => l !== '');
+    if (lines.length === 0)
+        return;
+    const [headerLine, ...entryLines] = lines;
+    let prevId = null;
+    const kept = [];
+    for (const line of entryLines) {
+        const entry = JSON.parse(line);
+        if (isHiddenJsonlBranchEntry(entry))
+            continue;
+        kept.push(JSON.stringify({ ...entry, parentId: prevId }));
+        if (typeof entry.id === 'string')
+            prevId = entry.id;
+    }
+    writeFileSync(filePath, `${[headerLine, ...kept].join('\n')}\n`);
+}
+/** Owns frame-local input state while dispatching through explicit broker collaborators. */
+export function createFrameDispatchContext(deps) {
+    const { nodeId, cfg, registry, toolGroups, projection, rebind, reviewCompanion, pendingDialogs, sendWelcome, replayExtraPendingDialogsTo, reWelcomeAll, disposeAndExit, persistModelChoice, broadcastModelChanged, registryOf, formatModelSpec, formatExactModelSpec, resolveLaunchModel, } = deps;
+    const currentSession = () => rebind.session();
+    const currentServices = () => rebind.services();
+    let kickoffPending;
+    let kickoffInFlight = false;
+    let reloadAuthInFlight = null;
+    let authFaultRedriveInFlight = false;
+    const turnAcceptedWaiters = new Set();
+    const notifyTurnAccepted = () => {
+        const waiters = [...turnAcceptedWaiters];
+        turnAcceptedWaiters.clear();
+        for (const waiter of waiters)
+            waiter();
+    };
+    const sessionHasNoModel = () => currentSession().model === undefined ||
+        isUnknownModel(currentSession().model);
+    const drivePendingKickoff = () => {
+        if (kickoffPending === undefined || kickoffInFlight || sessionHasNoModel())
+            return;
+        const prompt = kickoffPending;
+        kickoffPending = undefined;
+        kickoffInFlight = true;
+        trackPromptDispatch(operationIdContext.fresh(() => currentSession()
+            .prompt(prompt)
+            .catch((err) => {
+            emitEvent({
+                level: 'error',
+                event: 'broker.prompt.first_failed',
+                error: err,
+            });
+        })
+            .finally(() => {
+            kickoffInFlight = false;
+        })));
+    };
+    // Drive the engine on behalf of a writable client.
+    // -------------------------------------------------------------------------
+    // ---------------------------------------------------------------------------
+    // Inline memory-reference inventory (design: inline memory references) — a
+    // single broker-level memo shared by BOTH the `list_memory_refs` read-op
+    // reply and per-submission guidance resolution below, so a burst of reads +
+    // submissions between reloads never re-walks the corpus per call. Cleared
+    // (work item 3) only on a SUCCESSFUL `currentSession().reload()` — a failed reload
+    // leaves the prior memo intact, since nothing about the corpus is known to
+    // have changed.
+    // ---------------------------------------------------------------------------
+    let memoizedRefInventory = null;
+    const getRefInventory = () => {
+        if (memoizedRefInventory === null)
+            memoizedRefInventory = buildRefInventory();
+        return memoizedRefInventory;
+    };
+    /** Resolve the hidden guidance text for a human frame's verbatim text, or
+     *  `null` when no guidance should be sent (a leading engine command/skill/
+     *  template, no resolvable refs, or a degraded inventory/guidance build —
+     *  work item 6: any failure here degrades to "no guidance", logged once as a
+     *  structured warning, and NEVER blocks/alters the human delivery below). */
+    const resolveFrameGuidance = (text) => {
+        try {
+            if (isLeadingEngineCommand(text, currentSession()))
+                return null;
+            return buildGuidance(text, getRefInventory().names);
+        }
+        catch (err) {
+            emitEvent({
+                level: 'warn',
+                event: 'broker.memory_refs.guidance_resolve_failed',
+                error: err,
+            });
+            return null;
+        }
+    };
+    // Prompt dispatches whose promise has not yet settled. `currentSession().prompt()`
+    // does async setup (input transforms, model/auth validation, compaction)
+    // BEFORE `_isAgentRunActive` flips, so for a short window after a routed
+    // deliver the engine reads idle and `currentSession().abort()` is a silent no-op — an
+    // id-bearing abort racing that window would miss the turn entirely (verified
+    // live). The counter lets it distinguish "genuinely idle" from "turn still
+    // igniting" and wait for the run to become abortable.
+    let pendingPromptDispatches = 0;
+    const trackPromptDispatch = (p) => {
+        pendingPromptDispatches++;
+        const tracked = Promise.resolve(p);
+        void tracked.finally(() => {
+            pendingPromptDispatches--;
+        });
+        return tracked;
+    };
+    /**
+     * Drive the engine for one client frame. For a prompt/follow_up frame this
+     * returns a promise that settles with the engine call's OUTCOME — `undefined`
+     * when the call succeeded, the rejection value when it did not — so a caller
+     * that must report success (the `deliver` ack) can read it instead of assuming
+     * the dispatch worked. Every other frame type keeps the fire-and-forget shape
+     * and returns `undefined`.
+     */
+    const driveEngine = (client, frame) => {
+        // The engine call's failure, captured for the returned outcome. relayError
+        // still relays the error frame; recording it is what lets the caller ack
+        // from the outcome rather than from the fact that a call was made at all.
+        let failure;
+        const relayError = (err) => {
+            failure = err;
+            registry.sendFrame(client, {
+                type: 'error',
+                code: 'engine_error',
+                message: String(err),
+            });
+        };
+        // `prompt { interrupt: true }` is one atomic viewer intention: end whatever
+        // is producing now, then start this as a new turn. A normal mid-stream
+        // prompt deliberately steers into pi's queue; the whip must not.
+        if (frame.type === 'prompt' && frame.interrupt === true) {
+            return (async () => {
+                if (currentSession().isBashRunning) {
+                    currentSession().abortBash();
+                }
+                else {
+                    // A prompt can be in pi's async setup before isStreaming flips. Match
+                    // the correlated interrupt's guard so a whip cannot silently miss it.
+                    if (!currentSession().isStreaming && pendingPromptDispatches > 0) {
+                        const deadline = Date.now() + 5_000;
+                        while (Date.now() < deadline &&
+                            !currentSession().isStreaming &&
+                            pendingPromptDispatches > 0) {
+                            await new Promise((resolve) => setTimeout(resolve, 25));
+                        }
+                    }
+                    if (currentSession().isStreaming)
+                        await currentSession().abort();
+                }
+                return driveEngine(client, {
+                    type: 'prompt',
+                    text: frame.text,
+                    ...(frame.images !== undefined ? { images: frame.images } : {}),
+                });
+            })().catch((err) => {
+                relayError(err);
+                return failure;
+            });
+        }
+        // Hidden `crtr-memory-refs` guidance rides ALONGSIDE the human frame's own
+        // engine call, never rewriting `frame.text` — see resolveFrameGuidance /
+        // chooseGuidanceDeliveryMode above. A failed SEND (as opposed to a failed
+        // resolve, handled above) is likewise logged-and-swallowed: it must never
+        // reach `relayError`, which is reserved for the human call's own outcome.
+        const sendGuidance = (guidance, deliverAs) => currentSession()
+            .sendCustomMessage({ customType: 'crtr-memory-refs', content: guidance, display: false }, { deliverAs })
+            .catch((err) => {
+            emitEvent({
+                level: 'warn',
+                event: 'broker.memory_refs.guidance_send_failed',
+                error: err,
+            });
+        });
+        switch (frame.type) {
+            case 'prompt':
+            case 'follow_up': {
+                // Settle on the engine call's outcome: `failure` is set by relayError
+                // before the caught promise resolves, so reading it after the chain is
+                // the call's verdict.
+                const settle = (p) => p.then(() => failure);
+                const dispatch = () => {
+                    const route = resolveEngineRoute(frame, currentSession().isStreaming);
+                    const guidance = resolveFrameGuidance(frame.text);
+                    if (guidance === null) {
+                        if (route.call === 'prompt') {
+                            // A routed prompt STARTS a turn — including an idle follow_up
+                            // escalated by m-C — so it gets a fresh operation id. A true
+                            // (mid-stream) followUp rides the current turn's operation, like
+                            // steer.
+                            return settle(trackPromptDispatch(operationIdContext.fresh(() => currentSession()
+                                .prompt(frame.text, route.options)
+                                .catch(relayError))));
+                        }
+                        // C1: pi's followUp() takes images as a POSITIONAL 2nd arg (`followUp(text, images?)`).
+                        return settle(currentSession()
+                            .followUp(frame.text, frame.images)
+                            .catch(relayError));
+                    }
+                    const deliverAs = chooseGuidanceDeliveryMode(frame.type, route.call, currentSession().isStreaming);
+                    if (route.call === 'prompt') {
+                        if (deliverAs === 'nextTurn') {
+                            // The ONLY ordering where guidance precedes the human call — pi's
+                            // prompt() reads+clears its pending-nextTurn queue synchronously
+                            // at call time, injecting it into the SAME turn as the new user
+                            // message. promptWithNextTurnGuidance queues the guidance and then
+                            // ATOMICALLY clears its own pending entry if prompt() settles
+                            // without ever reaching that drain (an early throw/return leaves
+                            // nothing stranded to leak into a later, unrelated turn).
+                            return settle(trackPromptDispatch(promptWithNextTurnGuidance(currentSession(), guidance, () => operationIdContext.fresh(() => currentSession().prompt(frame.text, route.options))).catch(relayError)));
+                        }
+                        return settle(trackPromptDispatch(operationIdContext.fresh(() => currentSession()
+                            .prompt(frame.text, route.options)
+                            .catch(relayError)
+                            .then(() => sendGuidance(guidance, deliverAs)))));
+                    }
+                    // deliverAs is always 'followUp' here per chooseGuidanceDeliveryMode's
+                    // contract (a followUp routeCall never yields 'nextTurn').
+                    return settle(currentSession()
+                        .followUp(frame.text, frame.images)
+                        .catch(relayError)
+                        .then(() => sendGuidance(guidance, deliverAs)));
+                };
+                // /login acknowledges before its asynchronous local refresh completes.
+                // An idle turn must not overtake that refresh and launch on the stale
+                // route; true mid-stream follow-ups keep their immediate queue behavior.
+                const authReload = currentSession().isStreaming
+                    ? undefined
+                    : reloadAuthInFlight?.promise;
+                if (authReload === undefined)
+                    return dispatch();
+                const waitingGeneration = rebind.installedGeneration();
+                const waitingSession = currentSession();
+                return authReload.then(() => {
+                    if (rebind.installedGeneration() !== waitingGeneration ||
+                        currentSession() !== waitingSession) {
+                        relayError(new Error('currentSession() changed while prompt waited for authentication reload'));
+                        return failure;
+                    }
+                    return dispatch();
+                });
+            }
+            case 'steer': {
+                // A viewer submits ordinary text as `steer` while the agent is running,
+                // including a slash command injected by the tmux prefix menu. pi's
+                // steer() deliberately rejects registered extension commands because
+                // they cannot be queued; prompt() performs the command preflight first
+                // and executes it immediately even while streaming. It also expands a
+                // matching skill/template before applying the same steer behavior.
+                if (resolveSteerCall(frame.text, currentSession()) === 'prompt') {
+                    void currentSession()
+                        .prompt(frame.text, {
+                        images: frame.images,
+                        streamingBehavior: 'steer',
+                    })
+                        .catch(relayError);
+                    break;
+                }
+                const guidance = resolveFrameGuidance(frame.text);
+                // C1: pi's steer() takes images as a POSITIONAL 2nd arg (`steer(text, images?)`).
+                if (guidance === null) {
+                    void currentSession()
+                        .steer(frame.text, frame.images)
+                        .catch(relayError);
+                    break;
+                }
+                void currentSession()
+                    .steer(frame.text, frame.images)
+                    .catch(relayError)
+                    .then(() => sendGuidance(guidance, 'steer'));
+                break;
+            }
+            case 'abort': {
+                // esc/abort cancels whatever is live: a running `!` command (abortBash)
+                // takes precedence over the agent turn, mirroring pi interactive mode.
+                if (currentSession().isBashRunning) {
+                    currentSession().abortBash();
+                    if (frame.id !== undefined)
+                        ackTo(client, 'abort', true, 'bash', frame.id);
+                    break;
+                }
+                if (frame.id === undefined) {
+                    // A viewer's Esc — unchanged instant semantics, no ack.
+                    void currentSession().abort().catch(relayError);
+                    break;
+                }
+                // An id-bearing abort (a one-shot daemon interrupt) must close the
+                // pre-turn window: a routed deliver whose prompt() is still in async
+                // setup reads as idle and abort() would silently miss it. If a prompt
+                // dispatch is pending, wait (bounded) for the run to become abortable
+                // — or for every dispatch to settle without one (an early return) —
+                // then abort and ack with what was actually interrupted.
+                void (async () => {
+                    try {
+                        if (!currentSession().isStreaming && pendingPromptDispatches > 0) {
+                            const deadline = Date.now() + 5_000;
+                            while (Date.now() < deadline &&
+                                !currentSession().isStreaming &&
+                                pendingPromptDispatches > 0) {
+                                await new Promise((r) => setTimeout(r, 25));
+                            }
+                        }
+                        const detail = currentSession().isStreaming ? 'turn' : 'idle';
+                        await currentSession().abort();
+                        ackTo(client, 'abort', true, detail, frame.id);
+                    }
+                    catch (err) {
+                        engineErrorTo(client, frame.id)(err);
+                    }
+                })();
+                break;
+            }
+            case 'bash': {
+                // `!`/`!!` bash: run via currentSession().executeBash (records a bashExecution
+                // context message, starts NO agent turn) and relay its lifecycle to ALL
+                // viewers as bash_start/bash_output/bash_end so each renders the live
+                // component. Serialized like pi's interactive mode — reject a second `!`
+                // while one is already running rather than racing _bashAbortController.
+                const command = frame.command;
+                if (command.trim() === '')
+                    break;
+                if (currentSession().isBashRunning) {
+                    registry.sendFrame(client, {
+                        type: 'error',
+                        code: 'bash_busy',
+                        message: 'A bash command is already running',
+                    });
+                    break;
+                }
+                const exclude = frame.excludeFromContext === true;
+                // Order before any held assistant message_update, so a `!` run mid-stream
+                // never renders ahead of the update it follows.
+                projection.flush();
+                // The live bash component is a visible transcript boundary, even though
+                // its persisted bashExecution message arrives later via the currentSession().
+                toolGroups.finishOpenToolGroup();
+                registry.broadcast({
+                    type: 'bash_start',
+                    command,
+                    excludeFromContext: exclude,
+                });
+                void currentSession()
+                    .executeBash(command, (chunk) => registry.broadcast({ type: 'bash_output', chunk }), {
+                    excludeFromContext: exclude,
+                })
+                    .then((result) => {
+                    registry.broadcast({
+                        type: 'bash_end',
+                        exitCode: result.exitCode,
+                        cancelled: result.cancelled,
+                        truncated: result.truncated,
+                        fullOutputPath: result.fullOutputPath,
+                    });
+                })
+                    .catch(relayError);
+                break;
+            }
+        }
+    };
+    // -------------------------------------------------------------------------
+    // Command-op helpers (T3, §2.3). The write guard is hoisted here (it was
+    // inlined twice) and reused by all mutating ops; the ack/error replies
+    // and a few resolvers keep the per-op cases one-liners.
+    // -------------------------------------------------------------------------
+    /** Reject a read-only client for a mutating op. The decision reads this
+     *  client's OWN fixed role — there is no shared writer slot, so any number of
+     *  writable clients pass concurrently. Returns true when rejected (the caller
+     *  should `break`). */
+    const notWritable = (client, what, id) => {
+        if (client.role === 'controller')
+            return false;
+        registry.sendFrame(client, {
+            type: 'error',
+            code: 'read_only',
+            message: `a read-only client may not ${what}`,
+            // M1: echo a correlated request's id so its pending-by-id promise rejects
+            // rather than hanging (e.g. a read-only `dequeue`).
+            ...(id !== undefined ? { id } : {}),
+        });
+        return true;
+    };
+    const ackTo = (client, op, ok = true, detail, id) => registry.sendFrame(client, {
+        type: 'ack',
+        for: op,
+        ok,
+        ...(detail !== undefined ? { detail } : {}),
+        ...(id !== undefined ? { id } : {}),
+    });
+    const engineErrorTo = (client, id) => (err) => registry.sendFrame(client, {
+        type: 'error',
+        code: 'engine_error',
+        message: String(err),
+        // M1: a correlated read-op / dequeue failure echoes its id so the viewer's
+        // pending-by-id promise rejects instead of hanging; uncorrelated callers
+        // pass no id (unchanged behavior).
+        ...(id !== undefined ? { id } : {}),
+    });
+    const isPreBoundaryReviewEntry = (entryId) => reviewCompanion &&
+        !currentSession()
+            .sessionManager.getBranch(entryId)
+            .some((entry) => entry.type === 'custom_message' &&
+            entry.customType === REVIEW_BOUNDARY_CUSTOM_TYPE);
+    const reviewBoundaryRefusalTo = (client, targetId) => {
+        const refusal = new ReviewBoundaryNavigationError(targetId);
+        registry.sendFrame(client, {
+            type: 'error',
+            code: refusal.code,
+            message: refusal.message,
+        });
+    };
+    /** Resolve a `provider/id` model spec against the LIVE currentServices() registry (which
+     *  carries any extension-registered providers). Pure: returns undefined on a
+     *  malformed spec or an unknown model. */
+    const findModelSpec = (spec) => {
+        const { modelSpec } = parseModelSpec(spec);
+        const slash = modelSpec.indexOf('/');
+        if (slash <= 0)
+            return undefined;
+        return registryOf(currentServices()).find(modelSpec.slice(0, slash), modelSpec.slice(slash + 1));
+    };
+    /** Resolve a model from a free-text query — `/model opus`, `/model fable`. Tries
+     *  the exact `provider/id` spec first; failing that, searches the registry the
+     *  way the picker's search box does (case-insensitive substring on the model id
+     *  and the `provider/id` key) and returns the BEST match, preferring authed/
+     *  available models. Returns undefined only when nothing matches. */
+    const resolveModelQuery = (query) => {
+        const exact = findModelSpec(query);
+        if (exact)
+            return exact;
+        const q = query.trim().toLowerCase();
+        if (q === '')
+            return undefined;
+        let all;
+        try {
+            all = registryOf(currentServices()).getAll();
+        }
+        catch {
+            return undefined;
+        }
+        let availableKeys;
+        try {
+            availableKeys = new Set(registryOf(currentServices()).getAvailable().map(modelKey));
+        }
+        catch {
+            availableKeys = new Set();
+        }
+        // Rank: exact id (100) > exact provider/id (90) > id prefix (80) > id
+        // substring (60) > provider/id substring (40); +5 if the model is available.
+        const rank = (m) => {
+            const id = m.id.toLowerCase();
+            const key = modelKey(m).toLowerCase();
+            let base = -1;
+            if (id === q)
+                base = 100;
+            else if (key === q)
+                base = 90;
+            else if (id.startsWith(q))
+                base = 80;
+            else if (id.includes(q))
+                base = 60;
+            else if (key.includes(q))
+                base = 40;
+            else
+                return -1;
+            return base + (availableKeys.has(modelKey(m)) ? 5 : 0);
+        };
+        let best;
+        let bestRank = 0;
+        for (const m of all) {
+            const r = rank(m);
+            if (r > bestRank) {
+                bestRank = r;
+                best = m;
+            }
+        }
+        return best;
+    };
+    // Cache per-currentSession() wire info keyed by (path, mtime, size) so reopening the
+    // picker does not re-read the whole corpus (see currentSession()-list-cache.ts).
+    const sessionListCache = new SessionListCache(sessionListCachePath());
+    sessionListCache.prewarm(currentSession().sessionManager.getSessionDir());
+    const handleHelloFrame = (client, frame) => {
+        // Admit at the REQUESTED role — unconditionally. `controller` is a
+        // per-client write capability, not a singleton slot, so an arriving
+        // writable client never demotes (or is demoted by) an already-attached
+        // one: attached terminal panes are all writable at once.
+        //
+        // A repeated hello on an already-helloed socket must not RE-role it: the
+        // role is fixed for the socket's lifetime, so every downstream gate and
+        // every already-fanned-out dialog keep the authority the first welcome
+        // stated. A duplicate hello still re-sends the catch-up snapshot.
+        const firstHello = !client.helloed;
+        client.id = frame.client_id;
+        if (firstHello) {
+            client.helloed = true;
+            client.role = frame.role === 'controller' ? 'controller' : 'observer';
+        }
+        sendWelcome(client);
+        if (firstHello)
+            registry.persistAttachState(); // a helloed viewer arrived
+        // welcome carried the FIRST pending dialog; replay any extras so a writable
+        // client attaching mid-dialog can answer every in-flight dialog.
+        if (client.role === 'controller')
+            replayExtraPendingDialogsTo(client);
+    };
+    const handleDriveFrame = (client, frame) => {
+        if (notWritable(client, 'drive the engine'))
+            return;
+        driveEngine(client, frame);
+    };
+    const handleDeliverFrame = (client, frame) => {
+        // Interactive delivery from a one-shot server client (crtrd's
+        // `POST /messages` `delivery:'interactive'` path). Routed HERE,
+        // broker-side, because only the broker authoritatively knows streaming
+        // state: the synthesized `prompt` frame reuses resolveEngineRoute's m-B
+        // routing (idle → prompt(); mid-stream → prompt({streamingBehavior:
+        // 'steer'}), pi's own Enter-while-streaming submit) plus the memory-refs
+        // guidance path — byte-identical behavior to a viewer's Enter. Acked
+        // once ACCEPTED (correlated by the frame's id) so the daemon returns
+        // deterministically; `detail` reports which route was taken.
+        //
+        // The ack reports the engine call's OUTCOME, never merely the fact that
+        // a call was made: `currentSession().prompt()` rejects outright when the model's
+        // provider has no credential, and acking unconditionally reported
+        // `delivered:true` for a message the engine had refused — the caller's
+        // one-shot client then closed before the error frame arrived and the
+        // message vanished with no trace. A prompt route therefore acks on the
+        // race between acceptance (agent_start) and rejection; a steer route
+        // joins a turn already running, so no new agent_start is coming and its
+        // ack stays at routing time.
+        if (notWritable(client, 'drive the engine', frame.id))
+            return;
+        const via = currentSession().isStreaming ? 'steer' : 'prompt';
+        let delivered = false;
+        const ackAccepted = () => {
+            if (delivered)
+                return;
+            delivered = true;
+            ackTo(client, 'deliver', true, via, frame.id);
+        };
+        if (via === 'prompt')
+            turnAcceptedWaiters.add(ackAccepted);
+        const outcome = driveEngine(client, {
+            type: 'prompt',
+            text: frame.text,
+            ...(frame.images !== undefined ? { images: frame.images } : {}),
+        });
+        if (via === 'steer' || outcome === undefined) {
+            turnAcceptedWaiters.delete(ackAccepted);
+            ackAccepted();
+            return;
+        }
+        void outcome.then((failure) => {
+            turnAcceptedWaiters.delete(ackAccepted);
+            if (failure === undefined) {
+                ackAccepted();
+                return;
+            }
+            // The error frame already went to the client, but a one-shot deliver
+            // client is gone by then — record it where it survives.
+            emitEvent({
+                level: 'error',
+                event: 'broker.prompt.deliver_failed',
+                error: failure,
+            });
+            if (delivered)
+                return;
+            delivered = true;
+            ackTo(client, 'deliver', false, String(failure), frame.id);
+        });
+    };
+    const handleDialogFrame = (client, frame) => {
+        if (notWritable(client, 'answer dialogs'))
+            return;
+        // First response for this id wins: `resolve` settles the entry and deletes
+        // it, so every later response from a peer that was also fanned this dialog
+        // finds nothing here and is a silent no-op.
+        pendingDialogs.get(frame.id)?.resolve(frame);
+    };
+    const handleEngineControlFrame = (client, frame) => {
+        switch (frame.type) {
+            // --- extended engine-command ops (T3, §1.2 floor set) ------------------
+            case 'set_model': {
+                if (notWritable(client, 'set the model'))
+                    break;
+                const requested = parseModelSpec(frame.model);
+                let model;
+                let normalized;
+                try {
+                    // Tier/alias specs (`opus`, `strong`, `anthropic/strong`, …) MUST resolve
+                    // through the config ladder before touching the registry: the fuzzy
+                    // registry search rank-ties `opus` between claude-3-opus-20240229 and
+                    // claude-opus-4-8, and the deprecated 2024 model wins on catalog order.
+                    // Concrete `provider/id` specs and genuine substrings (`fable`) pass
+                    // through normalizeModel unchanged and take the exact/search path below.
+                    normalized = parseModelSpec(normalizeModel(requested.modelSpec));
+                    model = resolveModelQuery(normalized.modelSpec);
+                }
+                catch (err) {
+                    // N2: registry.find should never throw on the real SDK, but a degenerate
+                    // engine must still get a reply rather than a silently-dropped frame.
+                    engineErrorTo(client)(err);
+                    break;
+                }
+                if (model === undefined) {
+                    registry.sendFrame(client, {
+                        type: 'error',
+                        code: 'engine_error',
+                        message: `no model matching '${frame.model}' in the registry`,
+                    });
+                    break;
+                }
+                void currentSession()
+                    .setModel(model)
+                    .then(async () => {
+                    // The caller's explicit `:thinking` wins; else the ladder cell's.
+                    const thinking = requested.thinkingLevel ?? normalized.thinkingLevel;
+                    if (thinking !== undefined)
+                        currentSession().setThinkingLevel(thinking);
+                    // frame.pinned, when the sender pre-normalized `frame.model` (e.g.
+                    // setModelLive), carries the RAW-token pin decision explicitly.
+                    // Otherwise frame.model itself IS the raw/explicit token (a
+                    // slash-command arg, or a concrete picker pick) and derives it.
+                    await broadcastModelChanged(true, frame.pinned !== undefined
+                        ? frame.pinned
+                        : isProviderPinnedModelToken(frame.model), true);
+                    ackTo(client, 'set_model');
+                })
+                    .catch(engineErrorTo(client));
+                break;
+            }
+            case 'deliver_custom_message': {
+                if (notWritable(client, 'deliver a custom message'))
+                    break;
+                // Never triggers a turn either way. `nextTurn` folds the message into
+                // whatever turn comes next (situational context); omitting it pushes
+                // straight onto the message list so it lands FIRST in a still-empty
+                // currentSession() (a freshly-claimed spare's bearings). The inbox watcher's own
+                // situational send uses `followUp` + triggerTurn because there its job
+                // IS to wake the node.
+                void currentSession()
+                    .sendCustomMessage({
+                    customType: frame.customType,
+                    content: frame.content,
+                    display: true,
+                    ...(frame.details !== undefined
+                        ? { details: frame.details }
+                        : {}),
+                }, ...(frame.deliverAs !== undefined
+                    ? [{ deliverAs: frame.deliverAs }]
+                    : []))
+                    .then(() => ackTo(client, 'deliver_custom_message'))
+                    .catch(engineErrorTo(client));
+                break;
+            }
+            case 'cycle_model': {
+                if (notWritable(client, 'cycle the model'))
+                    break;
+                void currentSession()
+                    .cycleModel(frame.direction)
+                    .then(async () => {
+                    await broadcastModelChanged(true, undefined, true);
+                    ackTo(client, 'cycle_model');
+                })
+                    .catch(engineErrorTo(client));
+                break;
+            }
+            case 'cycle_ladder': {
+                if (notWritable(client, 'cycle the model ladder'))
+                    break;
+                // Resolve the next interleaved-ladder rung from the current model+thinking
+                // spec, then reuse the set_model path (registry resolve + thinking apply).
+                // The cycle only offers signed-in provider columns — same rule as the
+                // setup wizard's Models panel: pool occupancy for a managed provider
+                // (read live, so a login that landed mid-currentSession() counts immediately),
+                // else the registry's auth status. When nobody is signed in the helper
+                // returns every provider, so the cycle stays walkable pre-login.
+                const offeredProviders = (() => {
+                    try {
+                        const registry = registryOf(currentServices());
+                        return configuredLadderProviders((providerId) => (isManagedProvider(providerId) &&
+                            readSubscriptionPool(providerId).length > 0) ||
+                            registry.getProviderAuthStatus(providerId).configured);
+                    }
+                    catch {
+                        return undefined; // auth state unreadable — cycle the full ladder
+                    }
+                })();
+                const currentSpec = formatModelSpec(currentSession().model, currentSession().thinkingLevel) ?? '';
+                const nextSpec = parseModelSpec(nextLadderModel(currentSpec, frame.direction === 'backward' ? -1 : 1, offeredProviders));
+                let ladderModel;
+                try {
+                    ladderModel = resolveModelQuery(nextSpec.modelSpec);
+                }
+                catch (err) {
+                    engineErrorTo(client)(err);
+                    break;
+                }
+                if (ladderModel === undefined) {
+                    registry.sendFrame(client, {
+                        type: 'error',
+                        code: 'engine_error',
+                        message: `ladder model '${nextSpec.modelSpec}' not in the registry`,
+                    });
+                    break;
+                }
+                void currentSession()
+                    .setModel(ladderModel)
+                    .then(async () => {
+                    if (nextSpec.thinkingLevel !== undefined)
+                        currentSession().setThinkingLevel(nextSpec.thinkingLevel);
+                    await broadcastModelChanged(true, undefined, true);
+                    ackTo(client, 'cycle_ladder');
+                })
+                    .catch(engineErrorTo(client));
+                break;
+            }
+            case 'cycle_thinking': {
+                if (notWritable(client, 'cycle the thinking level'))
+                    break;
+                void (async () => {
+                    currentSession().cycleThinkingLevel();
+                    await persistModelChoice(undefined, true);
+                    ackTo(client, 'cycle_thinking');
+                })().catch(engineErrorTo(client));
+                break;
+            }
+            case 'dequeue': {
+                if (notWritable(client, 'dequeue messages', frame.id))
+                    break;
+                try {
+                    const { steering, followUp } = currentSession().clearQueue();
+                    registry.sendFrame(client, {
+                        type: 'data',
+                        id: frame.id,
+                        kind: 'dequeue',
+                        steering,
+                        followUp,
+                    });
+                }
+                catch (err) {
+                    engineErrorTo(client, frame.id)(err);
+                }
+                break;
+            }
+            case 'set_thinking_level': {
+                if (notWritable(client, 'set the thinking level'))
+                    break;
+                void (async () => {
+                    currentSession().setThinkingLevel(frame.level);
+                    await persistModelChoice(undefined, true);
+                    ackTo(client, 'set_thinking_level');
+                })().catch(engineErrorTo(client));
+                break;
+            }
+            case 'set_auto_retry': {
+                if (notWritable(client, 'set auto-retry'))
+                    break;
+                try {
+                    currentSession().setAutoRetryEnabled(frame.enabled);
+                    ackTo(client, 'set_auto_retry');
+                }
+                catch (err) {
+                    engineErrorTo(client)(err);
+                }
+                break;
+            }
+            case 'set_auto_compaction': {
+                if (notWritable(client, 'set auto-compaction'))
+                    break;
+                try {
+                    currentSession().setAutoCompactionEnabled(frame.enabled);
+                    ackTo(client, 'set_auto_compaction');
+                }
+                catch (err) {
+                    engineErrorTo(client)(err);
+                }
+                break;
+            }
+            case 'compact': {
+                if (notWritable(client, 'compact the currentSession()'))
+                    break;
+                void currentSession()
+                    .compact(frame.instructions)
+                    .then(() => ackTo(client, 'compact'))
+                    .catch(engineErrorTo(client));
+                break;
+            }
+            case 'set_session_name': {
+                if (notWritable(client, 'rename the currentSession()'))
+                    break;
+                try {
+                    currentSession().setSessionName(frame.name);
+                    ackTo(client, 'set_session_name');
+                }
+                catch (err) {
+                    engineErrorTo(client)(err);
+                }
+                break;
+            }
+        }
+    };
+    const handleReadFrame = (client, frame) => {
+        switch (frame.type) {
+            case 'get_commands': {
+                // OBSERVERS may call this: the merged command inventory is static
+                // (extensions + templates + skills + builtins) and drives nothing in the
+                // engine, so it is not a controller-gated op. Terminal observer
+                // connections use it to populate the command palette.
+                // The merged command list rides in ack.detail as JSON (the foundation's
+                // AckFrame.detail field) — the viewer (T6) JSON.parses it when for ===
+                // 'get_commands'. Keeps every command op a uniform ack reply.
+                try {
+                    ackTo(client, 'get_commands', true, JSON.stringify(buildCommandList(currentSession())));
+                }
+                catch (err) {
+                    engineErrorTo(client)(err);
+                }
+                break;
+            }
+            // --- read-op picker data (§5 Unit A) ----------------------------------
+            // NOT controller-gated: read-only, like get_commands. Terminal observer
+            // connections populate pickers through these too.
+            case 'list_models': {
+                try {
+                    registry.sendFrame(client, buildListModelsData(frame.id, currentSession()));
+                }
+                catch (err) {
+                    engineErrorTo(client, frame.id)(err);
+                }
+                break;
+            }
+            case 'list_scoped_models': {
+                try {
+                    registry.sendFrame(client, buildScopedModelsData(frame.id, currentSession()));
+                }
+                catch (err) {
+                    engineErrorTo(client, frame.id)(err);
+                }
+                break;
+            }
+            case 'list_memory_refs': {
+                try {
+                    registry.sendFrame(client, buildListMemoryRefsData(frame.id, getRefInventory().refs, engineLeadingCommandTokens(currentSession())));
+                }
+                catch (err) {
+                    engineErrorTo(client, frame.id)(err);
+                }
+                break;
+            }
+            case 'get_tree': {
+                try {
+                    registry.sendFrame(client, buildGetTreeData(frame.id, currentSession(), reviewCompanion));
+                }
+                catch (err) {
+                    engineErrorTo(client, frame.id)(err);
+                }
+                break;
+            }
+            case 'get_settings': {
+                try {
+                    registry.sendFrame(client, buildSettingsData(frame.id, currentSession()));
+                }
+                catch (err) {
+                    engineErrorTo(client, frame.id)(err);
+                }
+                break;
+            }
+            case 'list_sessions': {
+                // Session listing reads the currentSession() dir off disk — async; reply when it
+                // resolves (or relay the error, correlated by id so the viewer doesn't hang).
+                void buildSessionsData(frame.id, frame.scope ?? 'cwd', currentSession(), sessionListCache)
+                    .then((d) => registry.sendFrame(client, d))
+                    .catch(engineErrorTo(client, frame.id));
+                break;
+            }
+            case 'get_human_fork_coordinates': {
+                // NOT controller-gated: this is a pure observer read. Branch creation is
+                // intentionally delegated to a detached SDK manager in the ask publisher;
+                // calling createBranchedSession here corrupts this live manager's identity.
+                try {
+                    const sm = currentSession().sessionManager;
+                    const sourceFile = sm.getSessionFile();
+                    const leafId = sm.getLeafId();
+                    if (sourceFile === undefined ||
+                        sourceFile === '' ||
+                        leafId === null) {
+                        engineErrorTo(client, frame.id)(new Error('no persisted source currentSession() leaf'));
+                        break;
+                    }
+                    registry.sendFrame(client, {
+                        type: 'data',
+                        id: frame.id,
+                        kind: 'human_fork_coordinates',
+                        sourceFile,
+                        sourceSessionId: sm.getSessionId(),
+                        leafId,
+                        modelSpec: formatExactModelSpec(currentSession().model, currentSession().thinkingLevel),
+                    });
+                }
+                catch (err) {
+                    engineErrorTo(client, frame.id)(err);
+                }
+                break;
+            }
+        }
+    };
+    const handleSessionFrame = (client, frame) => {
+        switch (frame.type) {
+            case 'navigate_tree': {
+                if (notWritable(client, 'navigate the currentSession() tree'))
+                    break;
+                if (isPreBoundaryReviewEntry(frame.targetId)) {
+                    reviewBoundaryRefusalTo(client, frame.targetId);
+                    break;
+                }
+                // navigateTree rewinds IN-PLACE (same currentSession() file, new leaf) and emits no
+                // relayed event, so every viewer must be re-snapshotted onto the rewound
+                // transcript — same reWelcomeAll the currentSession()-replacing ops use. The ack's
+                // detail carries the navigated-to user message's text (pi parity: the
+                // interactive tree navigator restores it to the editor for re-editing).
+                void currentSession()
+                    .navigateTree(frame.targetId, frame.options)
+                    .then((r) => {
+                    if (!r.cancelled)
+                        reWelcomeAll();
+                    ackTo(client, 'navigate_tree', !r.cancelled, r.editorText);
+                })
+                    .catch(engineErrorTo(client));
+                break;
+            }
+            case 'reload': {
+                if (notWritable(client, 'reload'))
+                    break;
+                // A SUCCESSFUL reload invalidates the memoized ref inventory (work item
+                // 3) so the next read-op/submission re-walks the corpus, AND clears the
+                // shared substrate parse cache buildRefInventory reads through —
+                // otherwise a fresh buildRefInventory() call would still see the stale
+                // cached docs. A FAILED reload (`.catch`) leaves both untouched: nothing
+                // about the corpus is known to have changed.
+                void currentSession()
+                    .reload()
+                    .then(() => {
+                    memoizedRefInventory = null;
+                    clearSessionCache();
+                    ackTo(client, 'reload');
+                })
+                    .catch(engineErrorTo(client));
+                break;
+            }
+            case 'export': {
+                if (notWritable(client, 'export the currentSession()'))
+                    break;
+                if (frame.format === 'jsonl') {
+                    try {
+                        const outPath = currentSession().exportToJsonl(frame.path);
+                        stripHiddenEntriesFromJsonlExport(outPath);
+                        ackTo(client, 'export');
+                    }
+                    catch (err) {
+                        engineErrorTo(client)(err);
+                    }
+                }
+                else {
+                    void currentSession()
+                        .exportToHtml(frame.path)
+                        .then(() => ackTo(client, 'export'))
+                        .catch(engineErrorTo(client));
+                }
+                break;
+            }
+            case 'new_session': {
+                if (notWritable(client, 'start a new currentSession()'))
+                    break;
+                rebind.runReplacement(client, 'new_session', (rt) => rt.newSession());
+                break;
+            }
+            case 'switch_session': {
+                if (notWritable(client, 'switch sessions'))
+                    break;
+                rebind.runReplacement(client, 'switch_session', (rt) => rt.switchSession(frame.path));
+                break;
+            }
+            case 'fork': {
+                if (notWritable(client, 'fork the currentSession()'))
+                    break;
+                if (isPreBoundaryReviewEntry(frame.entryId)) {
+                    reviewBoundaryRefusalTo(client, frame.entryId);
+                    break;
+                }
+                rebind.runReplacement(client, 'fork', (rt) => rt.fork(frame.entryId));
+                break;
+            }
+            case 'clone': {
+                if (notWritable(client, 'clone the currentSession()'))
+                    break;
+                rebind.runReplacement(client, 'clone', async (rt) => {
+                    const sm = currentSession().sessionManager;
+                    const leafId = sm.getLeafId();
+                    if (leafId === null) {
+                        return { cancelled: true, detail: 'no current leaf to clone from' };
+                    }
+                    const newPath = sm.createBranchedSession(leafId);
+                    if (newPath === undefined) {
+                        return {
+                            cancelled: true,
+                            detail: 'createBranchedSession returned no path',
+                        };
+                    }
+                    return rt.switchSession(newPath);
+                });
+                break;
+            }
+            case 'share': {
+                if (notWritable(client, 'share the currentSession()'))
+                    break;
+                const tmpPath = join(tmpdir(), `pi-share-${Date.now()}.html`);
+                void currentSession()
+                    .exportToHtml(tmpPath)
+                    .then(() => new Promise((resolve, reject) => {
+                    execFile('gh', ['gist', 'create', '--secret', tmpPath], { timeout: 30_000, maxBuffer: 1024 * 1024 }, (err, stdout) => {
+                        try {
+                            if (existsSync(tmpPath))
+                                unlinkSync(tmpPath);
+                        }
+                        catch {
+                            /* cleanup */
+                        }
+                        if (err) {
+                            reject(err);
+                            return;
+                        }
+                        resolve(stdout.trim());
+                    });
+                }))
+                    .then((url) => {
+                    ackTo(client, 'share', true, url);
+                })
+                    .catch((err) => {
+                    const msg = String(err?.message ?? err);
+                    ackTo(client, 'share', false, msg.includes('not found') ||
+                        msg.includes('gh: command not found') ||
+                        msg.includes('ENOENT')
+                        ? '`gh` CLI not found — install GitHub CLI and authenticate with `gh auth login`'
+                        : `share failed: ${msg}`);
+                });
+                break;
+            }
+        }
+    };
+    const handleAuthenticationFrame = (client, frame) => {
+        // Open to any client, observers included: reload_auth is an idempotent
+        // local re-read of shared credentials + the runtime's availability
+        // snapshot. It does not steer the conversation, so the daemon's
+        // canvas-wide /login fan can ride an observer connection.
+        try {
+            ackTo(client, 'reload_auth');
+            const authGeneration = rebind.installedGeneration();
+            const existingAuthReload = reloadAuthInFlight;
+            let authReloadPromise;
+            if (existingAuthReload !== null &&
+                existingAuthReload.generation === authGeneration) {
+                authReloadPromise = existingAuthReload.promise;
+            }
+            if (authGeneration !== undefined && authReloadPromise === undefined) {
+                const authSession = currentSession();
+                const authServices = currentServices();
+                authReloadPromise = (async () => {
+                    // Credentials are read fresh by PoolCredentialStore; only the
+                    // ModelRuntime snapshot needs rebuilding. Authentication reloads
+                    // never fetch provider catalogs over the network.
+                    await authServices.modelRuntime.refresh({ allowNetwork: false });
+                    if (rebind.installedGeneration() !== authGeneration ||
+                        currentSession() !== authSession)
+                        return;
+                    const modelLess = authSession.model === undefined ||
+                        isUnknownModel(authSession.model);
+                    const reconcilesLogicalRoute = cfg.modelExact !== true &&
+                        cfg.modelProviderPinned !== true &&
+                        (process.env['CRTR_MODEL_INTENT'] ?? '').trim() !== '';
+                    if (modelLess || reconcilesLogicalRoute) {
+                        const resolved = await resolveLaunchModel(authServices, cfg);
+                        if (rebind.installedGeneration() !== authGeneration ||
+                            currentSession() !== authSession)
+                            return;
+                        if (resolved !== undefined) {
+                            const currentSpec = formatModelSpec(authSession.model, authSession.thinkingLevel);
+                            const resolvedSpec = formatModelSpec(resolved.model, resolved.thinkingLevel);
+                            if (resolvedSpec !== null && resolvedSpec !== currentSpec) {
+                                await authSession.setModel(resolved.model);
+                                if (rebind.installedGeneration() !== authGeneration ||
+                                    currentSession() !== authSession)
+                                    return;
+                                authSession.setThinkingLevel((resolved.thinkingLevel ?? 'off'));
+                            }
+                        }
+                    }
+                    if (rebind.installedGeneration() !== authGeneration ||
+                        currentSession() !== authSession)
+                        return;
+                    // Persist an algorithmic route choice without clearing the logical
+                    // intent that makes future reconciliation possible.
+                    await broadcastModelChanged();
+                    drivePendingKickoff();
+                })().catch((err) => {
+                    emitEvent({
+                        level: 'warn',
+                        event: 'broker.auth_reload.reconcile_failed',
+                        error: err,
+                    });
+                });
+                const work = {
+                    generation: authGeneration,
+                    promise: authReloadPromise,
+                };
+                reloadAuthInFlight = work;
+                void authReloadPromise.finally(() => {
+                    if (reloadAuthInFlight === work)
+                        reloadAuthInFlight = null;
+                });
+            }
+            const authFault = readFault(nodeId);
+            const authFaultGeneration = rebind.installedGeneration();
+            const authFaultSession = currentSession();
+            if (authFault?.link === 'pi→provider' &&
+                authFault.kind === 'auth' &&
+                !authFaultSession.isStreaming &&
+                !authFaultRedriveInFlight) {
+                authFaultRedriveInFlight = true;
+                void (async () => {
+                    try {
+                        if (authReloadPromise !== undefined)
+                            await authReloadPromise;
+                        if (rebind.installedGeneration() !== authFaultGeneration ||
+                            currentSession() !== authFaultSession)
+                            return;
+                        const anchorEntryId = authFault.anchorEntryId;
+                        if (anchorEntryId !== undefined) {
+                            try {
+                                const leafId = authFaultSession.sessionManager.getLeafId?.() ?? null;
+                                if (leafId !== anchorEntryId)
+                                    await authFaultSession.navigateTree(anchorEntryId);
+                                if (rebind.installedGeneration() !== authFaultGeneration ||
+                                    currentSession() !== authFaultSession)
+                                    return;
+                            }
+                            catch (err) {
+                                emitEvent({
+                                    level: 'warn',
+                                    event: 'broker.auth_fault.rewind_skipped',
+                                    error: err,
+                                });
+                            }
+                        }
+                        const fresh = readFault(nodeId);
+                        if (rebind.installedGeneration() !== authFaultGeneration ||
+                            currentSession() !== authFaultSession ||
+                            authFaultSession.isStreaming ||
+                            fresh?.link !== 'pi→provider' ||
+                            fresh.kind !== 'auth' ||
+                            fresh.since !== authFault.since)
+                            return;
+                        clearFault(nodeId, { link: 'pi→provider' });
+                        await authFaultSession.prompt(AUTH_FAULT_RECOVERY_BODY);
+                    }
+                    catch (err) {
+                        emitEvent({
+                            level: 'error',
+                            event: 'broker.auth_fault.redrive_failed',
+                            error: err,
+                        });
+                    }
+                    finally {
+                        authFaultRedriveInFlight = false;
+                    }
+                })();
+            }
+        }
+        catch (err) {
+            engineErrorTo(client)(err);
+        }
+    };
+    const handleByeFrame = (client) => {
+        client.socket.end();
+    };
+    const handleShutdownFrame = () => {
+        disposeAndExit('shutdown-frame');
+    };
+    return {
+        handlers: {
+            hello: handleHelloFrame,
+            drive: handleDriveFrame,
+            deliver: handleDeliverFrame,
+            dialog: handleDialogFrame,
+            engineControl: handleEngineControlFrame,
+            read: handleReadFrame,
+            session: handleSessionFrame,
+            authentication: handleAuthenticationFrame,
+            bye: handleByeFrame,
+            shutdown: handleShutdownFrame,
+        },
+        kickoff(prompt) {
+            kickoffPending = prompt;
+            drivePendingKickoff();
+        },
+        notifyTurnAccepted,
+        pendingPromptDispatches: () => pendingPromptDispatches,
+        resetForSession: () => {
+            reloadAuthInFlight = null;
+        },
+    };
+}
+/** The socket listener calls this explicit dispatcher for every decoded client frame. */
+export function handleFrame(ctx, client, frame) {
+    switch (frame.type) {
+        case 'hello':
+            ctx.handlers.hello(client, frame);
+            return;
+        case 'prompt':
+        case 'steer':
+        case 'follow_up':
+        case 'abort':
+        case 'bash':
+            ctx.handlers.drive(client, frame);
+            return;
+        case 'deliver':
+            ctx.handlers.deliver(client, frame);
+            return;
+        case 'extension_ui_response':
+            ctx.handlers.dialog(client, frame);
+            return;
+        case 'set_model':
+        case 'deliver_custom_message':
+        case 'cycle_model':
+        case 'cycle_ladder':
+        case 'cycle_thinking':
+        case 'dequeue':
+        case 'set_thinking_level':
+        case 'set_auto_retry':
+        case 'set_auto_compaction':
+        case 'compact':
+        case 'set_session_name':
+            ctx.handlers.engineControl(client, frame);
+            return;
+        case 'get_commands':
+        case 'list_models':
+        case 'list_scoped_models':
+        case 'list_memory_refs':
+        case 'get_tree':
+        case 'get_settings':
+        case 'list_sessions':
+        case 'get_human_fork_coordinates':
+            ctx.handlers.read(client, frame);
+            return;
+        case 'navigate_tree':
+        case 'reload':
+        case 'export':
+        case 'new_session':
+        case 'switch_session':
+        case 'fork':
+        case 'clone':
+        case 'share':
+            ctx.handlers.session(client, frame);
+            return;
+        case 'reload_auth':
+            ctx.handlers.authentication(client, frame);
+            return;
+        case 'bye':
+            ctx.handlers.bye(client);
+            return;
+        case 'shutdown':
+            ctx.handlers.shutdown();
+            return;
+    }
+}