@north-light/crouter 0.3.233 → 0.3.235

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

@@ -1,1497 +1,110 @@
-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, formatCard, SITUATIONAL_CONTEXT_CUSTOM_TYPE, } 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 { captureSessionChatCapabilities } from '../command-surface.js';
-import { promptWithAdvertisedCommandInvocation } from '../advertised-command-invocation.js';
-export { promptWithAdvertisedCommandInvocation } from '../advertised-command-invocation.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 { isReviewBoundary } from '../session-visibility.js';
-import { isUnknownModel, parseModelSpec } from '../model-selection.js';
-import { normalizeSnapshotTail } from '../broker-protocol.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`);
-}
+import { createFrameReplies } from './frame-replies.js';
+import { createEngineDriver } from './engine-drive.js';
+import { createClientHandlers } from './frame-client.js';
+import { createMemoryRefGuidance } from './frame-memory-refs.js';
+import { createAuthReloadGate } from './auth-reload.js';
+import { createEngineControlHandler } from './frame-engine-control.js';
+import { createReadHandler } from './frame-read.js';
+import { createSessionHandler } from './frame-session.js';
+import { createKickoffDriver, createPromptDispatchTracker, createTurnAcceptanceGate, } from './turn-ignition.js';
 /** Owns frame-local input state while dispatching through explicit broker collaborators. */
 export function createFrameDispatchContext(deps) {
     const { nodeId, cfg, registry, toolGroups, projection, rebind, boundaryReviewId, 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(() => promptWithAdvertisedCommandInvocation(currentSession(), frame.text, () => 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(() => promptWithAdvertisedCommandInvocation(currentSession(), frame.text, () => currentSession().prompt(frame.text, route.options)))).catch(relayError)));
-                        }
-                        return settle(trackPromptDispatch(operationIdContext.fresh(() => promptWithAdvertisedCommandInvocation(currentSession(), frame.text, () => 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 promptWithAdvertisedCommandInvocation(currentSession(), frame.text, () => 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. The write guard is hoisted here 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 } : {}),
+    // The reply vocabulary every handler below answers a client with.
+    const replies = createFrameReplies(registry);
+    const { notWritable } = replies;
+    const memoryRefs = createMemoryRefGuidance(currentSession);
+    const dispatches = createPromptDispatchTracker(currentSession);
+    const turnAcceptance = createTurnAcceptanceGate();
+    const kickoffDriver = createKickoffDriver({
+        session: currentSession,
+        dispatches,
     });
-    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 authReloadGate = createAuthReloadGate({
+        nodeId,
+        cfg,
+        replies,
+        rebind,
+        session: currentSession,
+        services: currentServices,
+        broadcastModelChanged,
+        formatModelSpec,
+        resolveLaunchModel,
+        driveKickoff: kickoffDriver.drivePending,
+    });
+    const driveEngine = createEngineDriver({
+        registry,
+        replies,
+        session: currentSession,
+        dispatches,
+        memoryRefs,
+        authReloadGate,
+        rebind,
+        projection,
+        toolGroups,
     });
-    const isPreBoundaryReviewEntry = (entryId) => boundaryReviewId !== undefined &&
-        !currentSession()
-            .sessionManager.getBranch(entryId)
-            .some((entry) => isReviewBoundary(entry, boundaryReviewId));
-    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;
-        client.snapshotTail = normalizeSnapshotTail(frame.snapshot_tail);
-        if (firstHello) {
-            client.helloed = true;
-            client.role = frame.role === 'controller' ? 'controller' : 'observer';
-            client.attends = frame.attends !== false;
-        }
-        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';
-        // Ordered context cards ahead of the body, inside this ONE frame handling,
-        // so no other client's send can interleave between a card and its body.
-        // Nothing is awaited: `sendCustomMessage` completes synchronously on both
-        // branches that apply here — idle appends to the session and starts NO turn
-        // (the body is the sole trigger), streaming queues on the same steer queue
-        // the body's `prompt({streamingBehavior:'steer'})` uses, preserving order.
-        for (const card of frame.cards ?? []) {
-            void currentSession().sendCustomMessage({ customType: SITUATIONAL_CONTEXT_CUSTOM_TYPE, content: card, display: true }, via === 'steer' ? { deliverAs: 'steer' } : undefined).catch((error) => emitEvent({ level: 'error', event: 'broker.deliver.card_failed', error }));
-        }
-        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 -------------------------------------
-            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 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(), boundaryReviewId));
-                }
-                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({ beforeSessionStart: () => captureSessionChatCapabilities(currentSession()) })
-                    .then(() => {
-                    // pi's reload() re-syncs queue modes from the shared settings.json
-                    // (its ONE post-bind syncQueueModesFromSettings call site) —
-                    // re-apply the broker's 'all' modes so a reload cannot silently
-                    // restore one-at-a-time draining (see rebind.enqueueRebind).
-                    const agent = currentSession().agent;
-                    if (agent) {
-                        agent.steeringMode = 'all';
-                        agent.followUpMode = 'all';
-                    }
-                    memoizedRefInventory = null;
-                    clearSessionCache();
-                    registry.forEachHelloed((observer) => {
-                        if (observer.role === 'observer')
-                            registry.sendFrame(observer, { type: 'resources_reloaded' });
-                    });
-                    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(formatCard('recovery', {}, 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');
-    };
+    const clientHandlers = createClientHandlers({
+        registry,
+        replies,
+        session: currentSession,
+        driveEngine,
+        turnAcceptance,
+        pendingDialogs,
+        sendWelcome,
+        replayExtraPendingDialogsTo,
+        disposeAndExit,
+    });
+    const handleEngineControlFrame = createEngineControlHandler({
+        registry,
+        replies,
+        session: currentSession,
+        services: currentServices,
+        registryOf,
+        persistModelChoice,
+        broadcastModelChanged,
+        formatModelSpec,
+    });
+    const handleReadFrame = createReadHandler({
+        registry,
+        replies,
+        session: currentSession,
+        boundaryReviewId,
+        memoryRefs,
+        formatExactModelSpec,
+    });
+    const handleSessionFrame = createSessionHandler({
+        registry,
+        replies,
+        rebind,
+        session: currentSession,
+        boundaryReviewId,
+        memoryRefs,
+        reWelcomeAll,
+    });
     return {
         handlers: {
-            hello: handleHelloFrame,
+            hello: clientHandlers.hello,
             drive: handleDriveFrame,
-            deliver: handleDeliverFrame,
-            dialog: handleDialogFrame,
+            deliver: clientHandlers.deliver,
+            dialog: clientHandlers.dialog,
             engineControl: handleEngineControlFrame,
             read: handleReadFrame,
             session: handleSessionFrame,
-            authentication: handleAuthenticationFrame,
-            bye: handleByeFrame,
-            shutdown: handleShutdownFrame,
-        },
-        kickoff(prompt) {
-            kickoffPending = prompt;
-            drivePendingKickoff();
-        },
-        notifyTurnAccepted,
-        pendingPromptDispatches: () => pendingPromptDispatches,
-        resetForSession: () => {
-            reloadAuthInFlight = null;
+            authentication: (client) => authReloadGate.handle(client),
+            bye: clientHandlers.bye,
+            shutdown: clientHandlers.shutdown,
         },
+        kickoff: (prompt) => kickoffDriver.kickoff(prompt),
+        notifyTurnAccepted: turnAcceptance.notifyAccepted,
+        pendingPromptDispatches: dispatches.pending,
+        resetForSession: authReloadGate.resetForSession,
     };
 }
 /** The socket listener calls this explicit dispatcher for every decoded client frame. */
@@ -1547,7 +160,7 @@ export function handleFrame(ctx, client, frame) {
             ctx.handlers.session(client, frame);
             return;
         case 'reload_auth':
-            ctx.handlers.authentication(client, frame);
+            ctx.handlers.authentication(client);
             return;
         case 'bye':
             ctx.handlers.bye(client);