@north-light/crouter 0.3.173 → 0.3.175

package/dist/core/runtime/broker.js

@@ -17,63 +17,41 @@
 // engine seam — the fake engine receives the real, extension-loaded loader so
 // the real canvas-stophook fires session_start).
 import { createServer } from 'node:net';
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
-import { execFile } from 'node:child_process';
-import { tmpdir } from 'node:os';
+import { existsSync, readFileSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { mark } from '../timing.js';
 import { getAgentDir, initTheme, ModelRegistry, ModelRuntime, } from '@earendil-works/pi-coding-agent';
-import { isContextOverflow } from '@earendil-works/pi-ai';
-import { jobDir, nodeDir, sessionListCachePath, viewSocketPath } from '../canvas/paths.js';
+import { nodeDir, viewSocketPath } from '../canvas/paths.js';
 import { bindBrokerEventSource } from '../events/source.js';
 import { emitEvent } from '../events/emit.js';
 import { operationIdContext } from '../events/operation-id.js';
 import { findMissingPackagePaths } from './package-health.js';
-import { SessionListCache } from './session-list-cache.js';
-import { getNode, updateNode } from '../canvas/index.js';
-import { readConfig } from '../config.js';
-import { atomicWriteJson, readJsonIfExists } from '../fs-utils.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 { FRONT_DOOR_ENV } from './front-door.js';
-import { CANVAS_EXTENSIONS, configuredLadderProviders, isProviderPinnedModelToken, nextLadderModel, normalizeModel, piInvocationToSdkConfig, } from './launch.js';
+import { CANVAS_EXTENSIONS, piInvocationToSdkConfig, } from './launch.js';
 import { assertEngineVersion, loadBrokerEngine } from './broker-sdk.js';
 import { resolveBundledPiPackageDir } from './pi-cli.js';
-import { classify } from '../fault-classifier.js';
 import { PoolCredentialStore } from '../pool-credential-store.js';
-import { clearFault, isModelNotFoundError, isProviderUnconfiguredError, readFault, recordFault, recordFaultForCurrentNode } from './fault.js';
 import { clearCleanAbort, markBusy, markCleanAbort } from './busy.js';
-import { extractCoolingDeadline } from './managed-provider-cooling.js';
-import { AUTH_FAULT_RECOVERY_BODY, CONNECTION_FAULT_RECOVERY_BODY, PROVIDER_FAULT_RECOVERY_BODY, formatModelFallbackRecovery, generatedContextText, } from '../../shared/generated-context.js';
-import { assistantVisibleText, isTrueUserMessage, normalizeToolGroupSummaryRecord, } from '../../shared/tool-groups.js';
-import { headlessToolGroupSummary, serializeToolGroup } from './tool-group-summary.js';
-import { markFatalOnExhaust, nextFaultRetry, policyFor } from './fault-recovery.js';
+import { recordFaultForCurrentNode } from './fault.js';
+import { modelRequestFromConfig, selectInitialModelRoute, unregisteredConcreteModel } from '../model-routes.js';
+import { KNOWN_STREAM_WAIT_UI } from './stream-watchdog.js';
 import { probeOnline as probeOnlineReal } from './connectivity.js';
-import { CRTR_CYCLE_CUSTOM_TYPE, cycleAwareMessages, withoutYieldAbort } from './session-cycles.js';
-import { boundaryRootedTree, REVIEW_BOUNDARY_CUSTOM_TYPE, visibleMessages } from './session-visibility.js';
-import { BUILTIN_SLASH_COMMANDS, piSessionsRoot } from './pi-vendored.js';
-import { StreamWatchdog, resolveStreamWatchdogMs, releaseKnownStreamWait, KNOWN_STREAM_WAIT_UI } from './stream-watchdog.js';
-import { isDeterministicCommandExpansion } from './command-expansion.js';
-import { DEFAULT_WORKING_ACTIVITY, randomWorkingActivity } from '../../shared/working-activity.js';
-import { isManagedProvider, readSubscriptionPool, resolveProviderCandidates } from '../subscription-state.js';
-import { expandModelCandidates, modelRequestFromConfig, probeRouteAvailability, selectInitialModelRoute } from '../model-routes.js';
-import { encodeFrame, FrameDecoder, FrameOverflowError, BROKER_READ_CAPS, } from './broker-protocol.js';
+import { CRTR_CYCLE_CUSTOM_TYPE, cycleAwareMessages } from './session-cycles.js';
+import { visibleMessages } from './session-visibility.js';
+import { isUnknownModel } from './model-selection.js';
+import { BrokerClientRegistry } from './broker/client-registry.js';
+import { ToolGroupTracker } from './broker/tool-groups.js';
+import { FaultRetry } from './broker/fault-retry.js';
+import { EventProjection } from './broker/event-projection.js';
+import { createFrameDispatchContext, handleFrame } from './broker/frame-dispatch.js';
+import { RebindDriver } from './broker/rebind.js';
+import { brokerExtensionState, commitBrokerModel } from './broker/daemon-ops.js';
+import { FrameOverflowError, } from './broker-protocol.js';
 /** A review companion may only navigate or fork within a branch whose ancestry
  * has crossed its durable transcript boundary. The broker sends this typed local
  * failure as a dedicated error frame without invoking pi's tree mutation. */
-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';
-    }
-}
-const THINKING_LEVELS = new Set(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
+export { ReviewBoundaryNavigationError, REVIEW_BOUNDARY_NAVIGATION_CODE } from './broker/frame-dispatch.js';
 /**
  * pi 0.82 made `ModelRuntime` the canonical model/auth surface and demoted
  * `ModelRegistry` to the synchronous facade over it (`find`/`getAll`/
@@ -89,282 +67,6 @@ function registryOf(services) {
 function modelRuntimePaths(agentDir) {
     return { authPath: join(agentDir, 'auth.json'), modelsPath: join(agentDir, 'models.json') };
 }
-function parseModelSpec(spec) {
-    const i = spec.lastIndexOf(':');
-    if (i <= 0)
-        return { modelSpec: spec };
-    const suffix = spec.slice(i + 1);
-    if (!THINKING_LEVELS.has(suffix))
-        return { modelSpec: spec };
-    return { modelSpec: spec.slice(0, i), thinkingLevel: suffix };
-}
-/**
- * The pinned pi SDK never yields `session.model === undefined` for a model-less
- * boot: Agent.createMutableAgentState() falls back to a hardcoded
- * `{ provider:'unknown', id:'unknown', api:'unknown', … }` stub (DEFAULT_MODEL)
- * whenever no model is supplied at construction, and `session.model` returns it
- * verbatim. This mirrors the SDK's own (non-exported) interactive-mode.js
- * `isUnknownModel()` so the broker recognizes that stub as "no model" wherever it
- * guards the model-less launch path (kickoff deferral, reload_auth re-drive) and
- * refuses to record/broadcast it as a real `unknown/unknown` model.
- */
-export function isUnknownModel(model) {
-    return (model !== null &&
-        model !== undefined &&
-        model.provider === 'unknown' &&
-        model.id === 'unknown' &&
-        model.api === 'unknown');
-}
-/**
- * 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`);
-}
 function formatModelSpec(model, thinkingLevel) {
     if (model === null || model === undefined || isUnknownModel(model))
         return null;
@@ -378,33 +80,9 @@ function formatExactModelSpec(model, thinkingLevel) {
     const base = formatModelSpec(model, undefined);
     return base === null ? null : `${base}:${thinkingLevel === undefined || thinkingLevel === '' ? 'off' : thinkingLevel}`;
 }
-function faultRetryProbe() {
-    const mode = process.env['CRTR_FAULT_RETRY_PROBE'];
-    if (mode === 'always')
-        return async () => true;
-    if (mode === 'never')
-        return async () => false;
-    return probeOnlineReal;
-}
 // ---------------------------------------------------------------------------
 // Tunables (T3 backpressure / T4 dialog anti-deadlock)
 // ---------------------------------------------------------------------------
-/** Per-viewer outbound high-water mark (M1). A viewer whose unflushed backlog
- *  exceeds EITHER bound is DROPPED (socket destroyed) rather than allowed to
- *  apply indefinite backpressure to the shared engine. Modeled on pi's RPC
- *  output-guard: bound the queue, shed the slow viewer. */
-const MAX_QUEUED_FRAMES = 1000;
-const MAX_PENDING_BYTES = 32 * 1024 * 1024; // 32 MiB
-/** F2 (attach typing-lag fix, 2026-06-09): coalesce window for relayed
- *  `message_update` frames. pi emits one per content delta and each carries the
- *  FULL accumulated assistant message, so a verbatim relay re-serializes (and
- *  every viewer re-parses + re-renders) the whole message per token — O(len²)
- *  bytes over a long reply, and measured ~3× the viewer's render CPU vs 75 ms
- *  coalescing. Only the LATEST pending update matters (each supersedes the
- *  last), so the relay keeps one and flushes it on this timer — or immediately,
- *  BEFORE any other event type, preserving ordering (an update never arrives
- *  after its message_end). */
-const MESSAGE_UPDATE_COALESCE_MS = 75;
 /** Broker-side default dialog timeout (C2 anti-deadlock, T4). When an extension
  *  dialog is forwarded to every writable client, the broker ALWAYS arms a timeout
  *  (this default, or a shorter per-dialog `opts.timeout` if the extension passed
@@ -412,36 +90,6 @@ const MESSAGE_UPDATE_COALESCE_MS = 75;
  *  — can never hang the agent turn forever. On fire it resolves to the SAFE default
  *  (deny for confirm; cancel/undefined for select/input/editor). */
 const DEFAULT_DIALOG_TIMEOUT_MS = 120_000; // 120 s
-/** Admission bound for `runReplacement` (one active head + at most one queued
- *  follow-up) and the mutation-through-rebind deadline each admitted head gets
- *  once it becomes the tail's head. The SDK has no cancellation primitive for
- *  newSession/switchSession/fork/bindExtensions, so an admitted replacement that
- *  neither settles nor completes within its deadline leaves runtime/shared state
- *  indeterminate — the only safe response is broker-terminal exit, never a retry
- *  and never letting a queued replacement start against that uncertain state. */
-const MAX_ADMITTED_REPLACEMENTS = 2; // active + at most one queued
-const REPLACEMENT_DEADLINE_MS = 30_000;
-/** Locally branded sentinel `runReplacement`'s deadline race resolves to when
- *  the budget elapses before the runtime promise settles — never compared via
- *  string matching. */
-const REPLACEMENT_DEADLINE_EXCEEDED = Symbol('replacement-deadline-exceeded');
-const PENDING_TOOL_SUMMARY_KEY_MAX_CHARS = 1_000;
-const PENDING_TOOL_SUMMARY_SEGMENT_MAX_CHARS = 10_000;
-function normalizePendingToolGroupSummary(value) {
-    if (value === null || typeof value !== 'object' || Array.isArray(value))
-        return null;
-    const record = value;
-    if (Object.keys(record).sort().join(',') !== 'key,segment,version')
-        return null;
-    if (record.version !== 1 || typeof record.key !== 'string' || typeof record.segment !== 'string')
-        return null;
-    if (record.key.length === 0 ||
-        record.key.length > PENDING_TOOL_SUMMARY_KEY_MAX_CHARS ||
-        record.segment.length === 0 ||
-        record.segment.length > PENDING_TOOL_SUMMARY_SEGMENT_MAX_CHARS)
-        return null;
-    return { version: 1, key: record.key, segment: record.segment };
-}
 // ---------------------------------------------------------------------------
 // M3 (scout mq5thyli): the active engine session, exposed so broker-cli's FATAL
 // handlers (uncaughtException / unhandledRejection / the runBroker reject) can
@@ -567,14 +215,14 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
     // Review identity is immutable for the broker's lifetime. Snapshot producers
     // close over this one construction-time classification rather than re-reading
     // canvas metadata for every welcome or session replacement.
-    const reviewCompanion = getNode(nodeId)?.review_binding != null;
+    const reviewCompanion = (await brokerExtensionState(nodeId)).node.review_binding != null;
     // M3: name the boot session as the process-fatal disposal target immediately —
     // enqueueRebind reassigns this on every later replacement, but without this
     // initial assignment `activeSession` stays null (and disposeActiveSession() a
     // no-op) for every exit that happens before the FIRST session replacement,
     // which is the common case.
     activeSession = session;
-    const retryProbe = faultRetryProbe();
+    const retryProbe = probeOnlineReal;
     // Initialize pi's process-global theme. The pi binary does this at boot
     // (main.js: initTheme(settingsManager.getTheme(), appMode === 'interactive')),
     // but the SDK convenience path the broker uses does NOT. Without it, ANY
@@ -621,2714 +269,278 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
     // survives a session replacement (new_session/switch_session/fork), not only at
     // boot.
     // -------------------------------------------------------------------------
-    // Socket fan-out state
+    // Socket fan-out, dialogs, and transcript tool groups
     // -------------------------------------------------------------------------
     const sockPath = viewSocketPath(nodeId);
-    const attachPath = join(jobDir(nodeId), 'attach.json');
-    const clients = new Set();
+    const registry = new BrokerClientRegistry(nodeId);
     const pendingDialogs = new Map();
-    // Fire-and-forget extension display state must survive a viewer detach. The
-    // extension may paint a widget (notably the inactivity brief) while nobody is
-    // attached; retain the latest keyed state so the next hello can replay it
-    // immediately after welcome instead of making "persistent" mean "only if you
-    // happened to be watching when the frame fired".
-    const displayStatuses = new Map();
-    const displayWidgets = new Map();
-    let displayTitle;
-    let workingActivity = DEFAULT_WORKING_ACTIVITY;
-    const toolSummariesPath = join(jobDir(nodeId), 'tool-summaries.json');
-    const pendingToolSummaryPath = join(jobDir(nodeId), 'pending-tool-summary.json');
-    const toolGroupSummaries = new Map();
-    try {
-        const persisted = readJsonIfExists(toolSummariesPath);
-        for (const [key, summary] of Object.entries(normalizeToolGroupSummaryRecord(persisted))) {
-            toolGroupSummaries.set(key, summary);
-        }
-    }
-    catch {
-        // A malformed sidecar merely withholds summaries; transcript tools remain visible.
-    }
-    const summaryAttempted = new Set(toolGroupSummaries.keys());
-    const generatingToolGroups = new Map();
-    const toolGroupsByCallId = new Map();
-    const summaryTasks = new Set();
-    let openToolGroup;
-    let lastToolGroupBoundaryProse = '';
-    let sawAssistantProse = false;
+    const toolGroups = new ToolGroupTracker(nodeId, (frame) => registry.broadcast(frame));
     let disposed = false;
     let disposePending = false;
-    let agentRunActive = false;
-    let shutdownRequested = false;
     let server;
-    // Every client whose `hello` claimed the writable role and whose transport is
-    // still usable. Liveness matters because on a unix socket a peer destroy()
-    // delivers EOF (readableEnded) promptly while the matching 'close' can lag
-    // arbitrarily behind undrainable pending writes — a departed peer must not be
-    // counted as an answerer a dialog fan-out waits on. Roles are FIXED per client,
-    // so this is a pure filter, never an arbitration.
-    const writableClients = () => {
-        const out = [];
-        for (const c of clients) {
-            if (!c.helloed || c.role !== 'controller')
-                continue;
-            if (c.socket.destroyed || c.socket.readableEnded || !c.socket.writable)
-                continue;
-            out.push(c);
+    let uiContext;
+    let rebind;
+    let faultRetry;
+    let projection;
+    let notifyTurnAccepted = () => { };
+    let resetFrameState = () => { };
+    rebind = new RebindDriver({
+        nodeId, cfg, session, services, runtime, registry, toolGroups,
+        uiContext: () => uiContext,
+        faultRetry: () => faultRetry,
+        projection: () => projection,
+        setActiveSession: (candidate) => { activeSession = candidate; },
+        disposeAndExit: (reason, status) => disposeAndExit(reason, status),
+        onSessionRebind: () => resetFrameState(),
+        reWelcomeAll: () => reWelcomeAll(),
+    });
+    // Pi's model controls mutate only the live engine. Commit the concrete model
+    // and thinking choice through crtrd before acknowledging or broadcasting it,
+    // so the daemon remains the only durable canvas owner.
+    const persistModelChoice = async (pinnedOverride, userSelected = false) => {
+        const liveSession = rebind.session();
+        const spec = formatModelSpec(liveSession.model, liveSession.thinkingLevel);
+        if (spec === null)
+            return null;
+        const result = await commitBrokerModel(nodeId, { spec, pinnedOverride, userSelected });
+        if (userSelected) {
+            delete process.env['CRTR_MODEL_INTENT'];
+            cfg.model = result.modelOverride;
         }
-        return out;
+        return result.modelOverride;
     };
-    // Persist viewer presence to job/attach.json when the set of helloed viewers
-    // changes (a hello is accepted, or a client drops/is shed) so out-of-process
-    // readers (the GRAPH view's attached-row tint) can see whether a human is
-    // watching this paneless node. Presence is a truthful COUNT and nothing more —
-    // there is no owner to record. Plain writeFileSync, matching telemetry.json's
-    // convention; best-effort — presence writing must never crash the broker.
-    // disposeAndExit unlinks the file, so a clean exit never leaves a stale claim
-    // (readers additionally trust it only while the node is 'active', fencing off
-    // a crash-orphaned file).
-    const persistAttachState = () => {
-        try {
-            let viewers = 0;
-            for (const c of clients)
-                if (c.helloed)
-                    viewers += 1;
-            const dirPath = jobDir(nodeId);
-            if (!existsSync(dirPath))
-                mkdirSync(dirPath, { recursive: true });
-            writeFileSync(attachPath, JSON.stringify({ viewers, updated: new Date().toISOString() }, null, 2), 'utf8');
-        }
-        catch {
-            /* presence is best-effort; never crash the broker */
-        }
+    // Pi emits no AgentSessionEvent for a model switch, so after a successful
+    // set_model/cycle_model the broker announces it itself. A durable change is
+    // broadcast only after crtrd returns the committed override.
+    const broadcastModelChanged = async (persist = true, pinnedOverride, userSelected = false) => {
+        const liveSession = rebind.session();
+        const liveSpec = formatModelSpec(liveSession.model, liveSession.thinkingLevel);
+        const spec = persist ? await persistModelChoice(pinnedOverride, userSelected) : liveSpec;
+        registry.broadcast({ type: 'model_changed', model: isUnknownModel(liveSession.model) ? undefined : liveSession.model, spec });
     };
-    // Shed a client — destroy the socket + remove it — used by both the M1
-    // backpressure drop and the G7 frame-overflow drop. 'close' (→ drop) follows
-    // the destroy.
-    const dropClient = (client, reason) => {
-        if (!clients.has(client))
-            return; // already gone
-        // info, not debug: shedding a viewer (M1 backpressure / G7 frame overflow)
-        // must be visible in the canonical log without CRTR_LOG=debug — debug-level
-        // events are dropped by emitEvent outside that env, which silently hid
-        // every shed.
-        emitEvent({
-            level: 'info',
-            event: 'broker.runtime.diagnostic',
-            fields: { message: `dropping viewer ${client.id || '(pre-hello)'} — ${reason}` },
+    faultRetry = new FaultRetry({
+        nodeId,
+        cfg,
+        retryProbe,
+        currentSession: () => rebind.session(),
+        currentServices: () => rebind.services(),
+        installedGeneration: () => rebind.installedGeneration(),
+        registryOf,
+        formatModelSpec,
+        broadcastModelChanged,
+    });
+    projection = new EventProjection({
+        registry,
+        faultRetry,
+        installedGeneration: () => rebind.installedGeneration(),
+        currentSession: () => rebind.session(),
+        notifyTurnAccepted: () => notifyTurnAccepted(),
+        emitStartupMilestone,
+        formatModelSpec,
+        refreshIntent: async () => (await brokerExtensionState(nodeId)).node.intent === 'refresh',
+        onRefreshIntentError: (error) => {
+            emitEvent({ level: 'error', event: 'broker.daemon_state.read_failed', error });
+            disposeAndExit('daemon-state-read-failed', 1);
+        },
+    });
+    const buildSnapshot = () => {
+        const liveSession = rebind.session();
+        return ({
+            messages: snapshotMessages(liveSession, reviewCompanion),
+            stats: liveSession.getSessionStats(),
+            // pi's `get_state` (rpc-mode.js), field for field, from the same getters.
+            // The ONE divergence: a model-less session (undefined OR the SDK
+            // unknown-stub) reports no model, matching broadcastModelChanged — never a
+            // fictitious `unknown` selection.
+            state: {
+                model: isUnknownModel(liveSession.model) ? undefined : liveSession.model,
+                thinkingLevel: liveSession.thinkingLevel,
+                isStreaming: liveSession.isStreaming,
+                isCompacting: liveSession.isCompacting,
+                steeringMode: liveSession.steeringMode,
+                followUpMode: liveSession.followUpMode,
+                sessionFile: liveSession.sessionFile,
+                sessionId: liveSession.sessionId,
+                sessionName: liveSession.sessionName,
+                autoCompactionEnabled: liveSession.autoCompactionEnabled,
+                messageCount: liveSession.messages.length,
+                pendingMessageCount: liveSession.pendingMessageCount,
+            },
+            // Broker-owned levels (see BrokerSnapshot.display). Copied out so a later
+            // mutation of the retained maps cannot alias a frame already serialized.
+            display: {
+                ...registry.displaySnapshot(),
+            },
+            toolGroupSummaries: toolGroups.summaries(),
+            workingActivity: projection.currentWorkingActivity(),
         });
-        clients.delete(client);
-        persistAttachState(); // a viewer was shed
-        try {
-            client.socket.destroy();
-        }
-        catch {
-            /* ignore */
-        }
     };
-    // `bypassHwm` (F1): the catch-up `welcome` carries the full message history and
-    // can legitimately be tens of MiB — far larger than a steady-state live frame.
-    // It is still ACCOUNTED (so a genuinely stalled client that also floods on live
-    // events is still shed by the NEXT frame's check), but it must never be the
-    // REASON a healthy client is dropped before it has had a chance to drain it.
-    const sendFrame = (client, frame, bypassHwm = false) => {
-        let data;
-        try {
-            data = encodeFrame(frame);
-        }
-        catch {
-            return; // an unserializable frame must never crash the broker
-        }
-        const bytes = Buffer.byteLength(data);
-        // M1 high-water mark: a viewer that has fallen too far behind on draining its
-        // socket is shed rather than allowed to grow the broker's memory unbounded.
-        if (!bypassHwm &&
-            (client.queuedFrames + 1 > MAX_QUEUED_FRAMES ||
-                client.pendingBytes + bytes > MAX_PENDING_BYTES)) {
-            dropClient(client, `backpressure high-water mark exceeded (queued=${client.queuedFrames}, pending=${client.pendingBytes}B)`);
+    // Send a client its catch-up snapshot. welcome.pending_dialog carries a single
+    // still-in-flight dialog to a WRITABLE client attaching mid-dialog; an observer
+    // can never answer one, so observers get null. The pendingDialogs map is
+    // insertion-ordered — the first entry is the canonical one carried here; any
+    // extras are replayed explicitly by the caller (rare: concurrent dialogs).
+    const sendWelcome = (client) => {
+        const first = client.role === 'controller' ? pendingDialogs.values().next().value : undefined;
+        registry.sendFrame(client, {
+            type: 'welcome',
+            snapshot: buildSnapshot(),
+            role: client.role,
+            pending_dialog: first !== undefined ? first.request : null,
+            agentDir: getAgentDir(),
+        }, true);
+        // No display_* replay: the retained extension state rides IN the snapshot
+        // (`snapshot.display`), so catch-up is one atomic frame. A viewer attaching
+        // after an idle brief was painted still sees it on first paint, and there is
+        // no window between `welcome` and the replay where chrome renders blank.
+    };
+    // Attach-mid-dialog replay: a dialog raised before this client attached is
+    // still pending (a peer detaching never cancels one — see makeBrokerUiContext),
+    // so a writable client joining afterwards is handed every in-flight dialog and
+    // becomes a full peer in the race to answer it. `welcome.pending_dialog` already
+    // carried the FIRST entry, so this replays only the extras.
+    const replayExtraPendingDialogsTo = (client) => {
+        const pend = [...pendingDialogs.values()];
+        for (let i = 1; i < pend.length; i++)
+            registry.sendFrame(client, pend[i].request);
+    };
+    // After a session-replacing op (new_session/switch_session/fork) the engine's
+    // entire message history changed, so every attached viewer must rebuild from a
+    // fresh snapshot of the NEW session.
+    const reWelcomeAll = () => {
+        registry.forEachHelloed(sendWelcome);
+    };
+    // -------------------------------------------------------------------------
+    // The single exit helper (plan §0): dispose the engine, close + unlink the
+    // socket, exit 0. Idempotent — every trigger converges here.
+    // -------------------------------------------------------------------------
+    const completeExit = (status) => {
+        if (disposed)
             return;
-        }
-        client.queuedFrames += 1;
-        client.pendingBytes += bytes;
+        disposed = true;
+        // Daemon teardown cannot wait for a recap's 45-second model timeout. Preserve
+        // exactly the newest already-capped input so the successor broker can finish
+        // it, persist the normal summary, and remove the handoff record.
+        toolGroups.persistPendingSummary();
+        projection.dispose();
+        // disposeActiveSession atomically clears the process-global pointer before
+        // disposing — whichever engine session (committed or an in-flight rebind
+        // candidate) it currently names, matching broker-cli's fatal-handler primitive.
+        disposeActiveSession();
         try {
-            // The per-write completion callback fires when THIS chunk is flushed to the
-            // OS — a finer-grained drain signal than a socket-wide 'drain' event, and it
-            // keeps the accounting exact. write()'s boolean return is the coarse
-            // "buffer full" hint; the per-chunk callback is what we account on.
-            client.socket.write(data, () => {
-                client.queuedFrames -= 1;
-                client.pendingBytes -= bytes;
-            });
+            server?.close();
         }
         catch {
-            // Dead socket: undo this frame's accounting; 'close' → drop() cleans the rest.
-            client.queuedFrames -= 1;
-            client.pendingBytes -= bytes;
-        }
-    };
-    const broadcast = (frame) => {
-        for (const c of clients)
-            if (c.helloed)
-                sendFrame(c, frame);
-    };
-    /** Retain and broadcast extension UI frames. The three display METHODS of pi's
-     *  `extension_ui_request` envelope are levels, so their last value is kept for
-     *  the welcome snapshot; updating a keyed entry moves it to the end, matching
-     *  pi's insertion-ordered widget behavior. Every other method (notify, the
-     *  blocking dialogs) simply passes through. */
-    const broadcastUi = (frame) => {
-        if (frame.type === 'extension_ui_request') {
-            if (frame.method === 'setStatus') {
-                displayStatuses.delete(frame.statusKey);
-                if (frame.statusText !== undefined)
-                    displayStatuses.set(frame.statusKey, frame.statusText);
-            }
-            else if (frame.method === 'setWidget') {
-                displayWidgets.delete(frame.widgetKey);
-                if (frame.widgetLines !== undefined) {
-                    displayWidgets.set(frame.widgetKey, {
-                        lines: [...frame.widgetLines],
-                        placement: frame.widgetPlacement ?? 'aboveEditor',
-                    });
-                }
-            }
-            else if (frame.method === 'setTitle') {
-                displayTitle = frame.title;
-            }
-        }
-        broadcast(frame);
-    };
-    /** Record and asynchronously summarize the maximal non-boundary region between
-     * visible prose messages. A boundary can land while a tool is still running,
-     * so closed groups retain their call ids until every result has joined the
-     * same serialized segment; only then may they become collapsible. */
-    const ensureOpenToolGroup = () => {
-        if (openToolGroup === undefined) {
-            openToolGroup = {
-                toolCount: 0,
-                pieces: [],
-                boundaryProse: lastToolGroupBoundaryProse,
-                pendingToolIds: new Set(),
-                closed: false,
-                summarizeWhenSettled: false,
-            };
+            /* ignore */
         }
-        return openToolGroup;
-    };
-    const clearPendingToolGroupSummary = (input) => {
+        // Destroy every viewer socket without waiting for close events.
+        registry.dispose();
         try {
-            const persisted = normalizePendingToolGroupSummary(readJsonIfExists(pendingToolSummaryPath));
-            if (persisted?.key === input.key && persisted.segment === input.segment)
-                unlinkSync(pendingToolSummaryPath);
+            if (existsSync(sockPath))
+                unlinkSync(sockPath);
         }
         catch {
-            // The durable summary is already authoritative. A stale handoff may cost a
-            // no-op read on the next boot, but must not revoke the recap just written.
+            /* ignore */
         }
+        // A clean exit never leaves a stale presence claim behind.
+        registry.clearAttachState();
+        process.exit(status);
     };
-    const generateToolGroupSummary = (input) => {
-        const { key, segment } = input;
-        if (summaryAttempted.has(key) || generatingToolGroups.has(key))
+    const disposeAndExit = (reason, status = 0) => {
+        if (disposed)
             return;
-        summaryAttempted.add(key);
-        generatingToolGroups.set(key, input);
-        let task;
-        task = headlessToolGroupSummary(segment)
-            .then((summary) => {
-            if (summary === null)
-                return;
-            toolGroupSummaries.set(key, summary);
-            try {
-                atomicWriteJson(toolSummariesPath, Object.fromEntries(toolGroupSummaries));
-            }
-            catch {
-                // A delivery without durable state would disappear on reattach, so do
-                // not advertise it. The calls remain folded normally instead.
-                toolGroupSummaries.delete(key);
+        const graceful = reason === 'shutdown-hook' || reason === 'shutdown-after-settle';
+        // A graceful shutdown (yield, dormancy, daemon restart) is the final
+        // boundary of the conversation's last tool group. Group state lives only in
+        // this process, so a group left open here is unsummarizable forever and its
+        // calls render raw in every future view of the transcript. Close it now —
+        // generateSettledToolGroup registers its task synchronously, so the wait
+        // below covers the summary it launches. Any pending tool arguments are
+        // included without inventing a result; the visible abort remains outside
+        // the recap and Ctrl+O retains every underlying call row.
+        if (graceful)
+            toolGroups.finishOpenToolGroup(true);
+        // A normal terminal shutdown follows a visible boundary that may have just
+        // launched a capped (45s) headless summary. Keep the broker and its child
+        // alive until those already-started tasks persist/broadcast, rather than
+        // process.exit() orphaning pi and losing the sidecar. Abrupt failures and
+        // signals retain their existing immediate teardown behavior.
+        if (graceful && toolGroups.hasSummaryTasks()) {
+            if (disposePending)
                 return;
-            }
-            clearPendingToolGroupSummary(input);
-            broadcast({ type: 'tool_group_summary', key, summary });
-        })
-            .catch(() => undefined)
-            .finally(() => {
-            generatingToolGroups.delete(key);
-            summaryTasks.delete(task);
-        });
-        summaryTasks.add(task);
-    };
-    const generateSettledToolGroup = (group) => {
-        if (!group.closed || group.pendingToolIds.size > 0 || group.key === undefined || !group.summarizeWhenSettled)
+            disposePending = true;
+            void toolGroups.waitForSummaryTasks().finally(() => completeExit(status));
             return;
-        generateToolGroupSummary({
-            version: 1,
-            key: group.key,
-            segment: serializeToolGroup(group.boundaryProse, group.pieces),
-        });
+        }
+        completeExit(status);
     };
+    // -------------------------------------------------------------------------
+    // Extension-dialog routing (C2). makeBrokerUiContext owns the dialogPromise;
+    // here we just give it the three broker-side hooks it needs: the live set of
+    // writable clients (empty = nobody can answer → noOp fallback), how to forward a
+    // dialog to one of them, and the pending-dialog registry whichever one answers
+    // first settles through. The zero-writable path NEVER hangs and NEVER waits on a
+    // per-dialog timeout (design §5.4's timeout premise is false — see
+    // makeBrokerUiContext).
+    // -------------------------------------------------------------------------
+    uiContext = makeBrokerUiContext({
+        writable: () => registry.writableClients(),
+        forward: (client, request) => registry.sendFrame(client, request),
+        pending: pendingDialogs,
+        broadcast: (frame) => registry.broadcastUi(frame),
+        // A deliberate managed-provider cooldown wait is known liveness, not a wedged
+        // stream: pause the dead-stream watchdog for its duration. Only pause for a
+        // finite future deadline, and resume ONLY while the same turn is still
+        // awaiting the provider (streaming, no tool running) so a wait that outlived
+        // its turn can't rearm a stale session; otherwise fully reset.
+        onKnownStreamWait: (deadlineMs) => projection.knownStreamWait(deadlineMs),
+    });
+    // Bind the rebind driver before accepting socket frames. It owns subscription
+    // replacement and its bounded runtime-mutation admission lane.
+    rebind.setRebindSession();
+    await rebind.enqueueRebind(session, services);
+    const frameDispatch = createFrameDispatchContext({
+        nodeId, cfg, registry, toolGroups, projection, rebind, reviewCompanion,
+        pendingDialogs, sendWelcome, replayExtraPendingDialogsTo, reWelcomeAll, disposeAndExit,
+        persistModelChoice, broadcastModelChanged, registryOf, formatModelSpec,
+        formatExactModelSpec, resolveLaunchModel,
+    });
+    notifyTurnAccepted = frameDispatch.notifyTurnAccepted;
+    resetFrameState = frameDispatch.resetForSession;
+    // -------------------------------------------------------------------------
+    // 4 (plan): the socket listener — unlink any stale socket first.
+    // -------------------------------------------------------------------------
     try {
-        const pending = normalizePendingToolGroupSummary(readJsonIfExists(pendingToolSummaryPath));
-        if (pending === null) {
-            if (existsSync(pendingToolSummaryPath)) {
-                unlinkSync(pendingToolSummaryPath);
-                emitEvent({
-                    level: 'warn',
-                    event: 'broker.startup.warning',
-                    fields: { stage: 'pending_tool_summary', message: 'removed an invalid pending tool summary' },
-                });
-            }
-        }
-        else if (toolGroupSummaries.has(pending.key)) {
-            unlinkSync(pendingToolSummaryPath);
-        }
-        else {
-            generateToolGroupSummary(pending);
-        }
+        if (existsSync(sockPath))
+            unlinkSync(sockPath);
     }
-    catch (error) {
-        emitEvent({
-            level: 'warn',
-            event: 'broker.startup.warning',
-            fields: {
-                stage: 'pending_tool_summary',
-                message: error instanceof Error ? error.message : String(error),
-            },
-        });
+    catch {
+        /* a fresh listen below will surface a real problem */
     }
-    const finishOpenToolGroup = (settleInterruptedTools = false) => {
-        const group = openToolGroup;
-        openToolGroup = undefined;
-        if (group === undefined)
-            return;
-        group.closed = true;
-        // An abort is itself the visible evidence that any pending calls did not
-        // finish. Their recorded arguments still belong to the recap, and Ctrl+O
-        // retains the full rows, so let the completed pre-abort span summarize.
-        if (settleInterruptedTools) {
-            for (const id of group.pendingToolIds)
-                toolGroupsByCallId.delete(id);
-            group.pendingToolIds.clear();
-        }
-        // Configuration is read at the boundary, not when a slow tool later settles.
-        group.summarizeWhenSettled = readConfig('user').summarize_tool_calls;
-        generateSettledToolGroup(group);
-    };
-    const visibleBoundary = (prose) => {
-        finishOpenToolGroup();
-        lastToolGroupBoundaryProse = prose;
-    };
-    const observeToolGroupEvent = (event) => {
-        // The viewer turns every compaction_end into a summary, cancellation, or
-        // error line, each of which is a hard transcript seam.
-        if (event.type === 'compaction_end') {
-            finishOpenToolGroup();
-            return;
-        }
-        // A failed automatic retry is rendered as ChatView's visible error line.
-        // Successful retries only clear activity and remain within the same group.
-        if (event.type === 'auto_retry_end' && event.success !== true) {
-            finishOpenToolGroup();
-            return;
-        }
-        // The attach viewer renders aborted and errored assistant endings as visible
-        // transcript seams. Close and settle the pre-abort group here so pending tool
-        // arguments can be summarized without pulling the seam into the recap.
-        if (event.type === 'message_end') {
-            const message = event.message;
-            if (message !== null && typeof message === 'object') {
-                const item = message;
-                if (item.role === 'assistant' && (item.stopReason === 'aborted' || item.stopReason === 'error')) {
-                    finishOpenToolGroup(true);
-                }
-            }
-            return;
-        }
-        if (event.type === 'tool_execution_start') {
-            const group = ensureOpenToolGroup();
-            const id = typeof event.toolCallId === 'string' ? event.toolCallId : '';
-            if (group.key === undefined && id !== '')
-                group.key = id;
-            if (id !== '') {
-                group.pendingToolIds.add(id);
-                toolGroupsByCallId.set(id, group);
+    server = createServer((socket) => {
+        const client = registry.create(socket);
+        socket.on('data', (chunk) => {
+            let frames;
+            try {
+                frames = client.decoder.push(chunk);
             }
-            group.toolCount += 1;
-            group.pieces.push({ type: 'tool', name: typeof event.toolName === 'string' ? event.toolName : 'tool', args: event.args });
-            return;
-        }
-        if (event.type === 'tool_execution_end') {
-            const id = typeof event.toolCallId === 'string' ? event.toolCallId : '';
-            const group = id === '' ? openToolGroup : toolGroupsByCallId.get(id);
-            if (group !== undefined) {
-                group.pieces.push({
-                    type: 'result',
-                    name: typeof event.toolName === 'string' ? event.toolName : 'tool',
-                    result: event.result,
-                    isError: event.isError === true,
-                });
-                if (id !== '') {
-                    group.pendingToolIds.delete(id);
-                    toolGroupsByCallId.delete(id);
+            catch (err) {
+                // G7: a client frame over the bounded decoder caps (FrameOverflowError) is
+                // cap-and-dropped — best-effort error frame, then destroy the peer. The
+                // broker survives. The try/catch is around push() itself (not just the
+                // per-frame loop) because push() throws BEFORE returning any frames.
+                if (err instanceof FrameOverflowError) {
+                    registry.sendFrame(client, { type: 'error', code: 'frame_overflow', message: err.message });
+                    registry.dropClient(client, `frame overflow: ${err.message}`);
+                }
+                else {
+                    registry.dropClient(client, `decoder error: ${String(err)}`);
                 }
-                generateSettledToolGroup(group);
-            }
-            return;
-        }
-        if (event.type !== 'message_start' && event.type !== 'message_update')
-            return;
-        const message = event.message;
-        if (message === null || typeof message !== 'object')
-            return;
-        const item = message;
-        const role = item.role;
-        if (role === 'assistant') {
-            if (event.type === 'message_start')
-                sawAssistantProse = false;
-            const prose = assistantVisibleText(item);
-            if (!sawAssistantProse && prose.trim() !== '') {
-                sawAssistantProse = true;
-                visibleBoundary(prose);
-            }
-            return;
-        }
-        if (event.type !== 'message_start')
-            return;
-        if (role === 'compactionSummary' || role === 'branchSummary' || role === 'bashExecution' || role === 'status' || role === 'error' || item.customType === 'crtr-cycle-divider') {
-            finishOpenToolGroup();
-            return;
-        }
-        if (isTrueUserMessage(item)) {
-            visibleBoundary(generatedContextText(item));
-            return;
-        }
-        if (item.display === false)
-            return;
-        const text = generatedContextText(item);
-        const isBearingsOrRevive = item.customType === 'crtr-context' || (role === 'user' && text.startsWith('You have been revived fresh after a context refresh'));
-        if (isBearingsOrRevive) {
-            if (openToolGroup !== undefined && text !== '')
-                openToolGroup.pieces.push({ type: 'text', text });
-            return;
-        }
-        // Generated inbox/situational/nudge and visible custom output are part of
-        // the between-message activity and may begin a group before its first tool.
-        const group = ensureOpenToolGroup();
-        if (text !== '')
-            group.pieces.push({ type: 'text', text });
-    };
-    // ---------------------------------------------------------------------------
-    // F2: message_update coalescing. `relayEvent` is the single entry point for
-    // engine events headed to viewers: a message_update is held (latest wins) and
-    // flushed on a short timer; ANY other event flushes the held update first,
-    // synchronously, so cross-type ordering is exactly the engine's. The timer is
-    // unref'd — it must never hold the broker process open past dispose.
-    // ---------------------------------------------------------------------------
-    let pendingUpdate = null;
-    let pendingUpdateTimer = null;
-    let faultRetryTimer = null;
-    let nextSubscriptionGeneration = 0;
-    let installedGeneration;
-    // Dead-provider-stream detector (see stream-watchdog.ts): poked while a turn
-    // is awaiting the provider (NOT while a tool executes — a silent long tool
-    // must not trip it), cleared at agent_end. Fires at most once per stall,
-    // aborting the session so the fault-retry machinery (armed at agent_settled)
-    // re-drives the turn instead of the broker wedging until the daemon's
-    // 20-minute hard kick.
-    const streamWatchdogMs = resolveStreamWatchdogMs();
-    const streamWatchdog = new StreamWatchdog((armedGeneration) => {
-        const generation = installedGeneration;
-        if (generation === undefined || armedGeneration !== generation.id)
-            return;
-        emitEvent({
-            level: 'debug',
-            event: 'broker.runtime.diagnostic',
-            fields: { message: `stream watchdog: no engine event for ${streamWatchdogMs}ms while streaming — aborting stalled provider stream` },
-        });
-        void generation.session.abort().catch((err) => {
-            emitEvent({
-                level: 'debug',
-                event: 'broker.runtime.diagnostic',
-                fields: { message: `stream watchdog abort failed: ${String(err)}` },
-            });
-        });
-    }, streamWatchdogMs);
-    const flushPendingUpdate = () => {
-        if (pendingUpdateTimer !== null) {
-            clearTimeout(pendingUpdateTimer);
-            pendingUpdateTimer = null;
-        }
-        if (pendingUpdate !== null) {
-            const frame = pendingUpdate;
-            pendingUpdate = null;
-            broadcast(frame);
-        }
-    };
-    const clearFaultRetryTimer = () => {
-        if (faultRetryTimer === null)
-            return;
-        clearTimeout(faultRetryTimer);
-        faultRetryTimer = null;
-    };
-    const failedRetryRoutes = new Set();
-    let providerFallbackInFlight = null;
-    // Models that have already produced a 404 not_found this session. Guards the
-    // not-found fallback below against an infinite swap→re-drive→404 loop when the
-    // fallback TARGET is itself unavailable (or equals the model that just failed).
-    const notFoundModels = new Set();
-    let notFoundFallbackInFlight = null;
-    // Tier 3 model-less boot: the first-prompt kickoff can't fire at listen time
-    // when the session booted with no model at all. Hold the prompt text here and
-    // fire it once a model actually becomes available (reload_auth re-drive,
-    // below) instead of the old unconditional call. For the common model-present
-    // path this fires immediately at listen time — byte-identical to the prior
-    // behavior.
-    let kickoffPending;
-    let kickoffInFlight = false;
-    // One /login can fan the same reload into this broker through several clients.
-    // Coalesce those frames onto one local auth refresh + route reconciliation so
-    // an idle prompt can await the exact work promised by the reload ack.
-    let reloadAuthInFlight = null;
-    // A fresh auth reload is also the explicit recovery trigger for a turn parked
-    // on a fatal provider-auth fault. Keep at most one rewind + prompt in flight
-    // when the daemon and an attached viewer both fan the same login update.
-    let authFaultRedriveInFlight = false;
-    // A model-less boot is EITHER a literal `undefined` model (the fake engine) OR
-    // the real SDK's unknown-stub (see isUnknownModel) — the real pinned engine
-    // NEVER yields `undefined`, so every model-less guard must accept both.
-    const sessionHasNoModel = () => session.model === undefined || isUnknownModel(session.model);
-    const drivePendingKickoff = () => {
-        if (kickoffPending === undefined || kickoffInFlight || sessionHasNoModel())
-            return;
-        const prompt = kickoffPending;
-        kickoffPending = undefined;
-        kickoffInFlight = true;
-        trackPromptDispatch(operationIdContext.fresh(() => session.prompt(prompt)
-            .catch((err) => {
-            emitEvent({
-                level: 'error',
-                event: 'broker.prompt.first_failed',
-                error: err,
-            });
-        })
-            .finally(() => {
-            kickoffInFlight = false;
-        })));
-    };
-    const maybeSwitchProviderForRetry = (event) => {
-        if (event.type !== 'auto_retry_start')
-            return;
-        const retry = event;
-        const kind = classify('pi→provider', retry.errorMessage ?? '').kind;
-        if (kind !== 'rate-limit' && kind !== 'connection')
-            return;
-        if (providerFallbackInFlight !== null)
-            return;
-        const generation = installedGeneration;
-        if (generation === undefined)
-            return;
-        const candidateSession = session;
-        const candidateServices = services;
-        // An exact-consult launch locks the session to its one captured model.
-        // Other requests advance only through their declared route expansion.
-        if (cfg.modelExact === true)
-            return;
-        const currentSpec = formatModelSpec(session.model, session.thinkingLevel);
-        if (currentSpec === null)
-            return;
-        const routeRequest = modelRequestFromConfig(cfg.model, process.env['CRTR_MODEL_INTENT'], false);
-        if (routeRequest !== undefined) {
-            const routes = expandModelCandidates(routeRequest, process.env['CRTR_NODE_CWD'] ?? cfg.cwd, process.env['CRTR_PROFILE_ID']);
-            const current = parseModelSpec(currentSpec);
-            const liveRank = routes.find((candidate) => `${candidate.providerId}/${candidate.modelId}` === current.modelSpec && candidate.thinkingLevel === current.thinkingLevel)?.rank;
-            const nextRoute = liveRank === undefined ? undefined : routes.slice(liveRank + 1).find((candidate) => !failedRetryRoutes.has(candidate.routeId) && resolveProviderCandidates([{ ...candidate, ...probeRouteAvailability(candidate, registryOf(candidateServices)), automaticFallback: true }]).candidates.length > 0);
-            if (nextRoute === undefined)
-                return;
-            const fallbackPromise = (async () => {
-                const target = registryOf(candidateServices).find(nextRoute.providerId, nextRoute.modelId);
-                if (!target)
-                    return;
-                await candidateSession.setModel(target);
-                if (installedGeneration !== generation || session !== candidateSession)
-                    return;
-                candidateSession.setThinkingLevel((nextRoute.thinkingLevel ?? 'off'));
-                failedRetryRoutes.add(nextRoute.routeId);
-                broadcastModelChanged(false);
-            })().catch((err) => { emitEvent({ level: 'debug', event: 'broker.runtime.diagnostic', fields: { message: `provider route fallback failed: ${err instanceof Error ? err.message : String(err)}` } }); }).finally(() => {
-                if (installedGeneration === generation)
-                    providerFallbackInFlight = null;
-            });
-            providerFallbackInFlight = fallbackPromise;
-            return;
-        }
-    };
-    // A 404 or unconfigured provider is terminal to pi's ordinary retry loop.
-    // Advance once through the request's declared route expansion, then re-drive
-    // the turn on the selected viable route. The raw registry never supplies this
-    // recovery path: it is an explicit routing decision, not a last-resort guess.
-    const maybeFallbackOnUnusableModel = (event) => {
-        if (event.type !== 'message_end')
-            return;
-        const msg = event.message;
-        if (msg === undefined || msg.role !== 'assistant' || msg.stopReason !== 'error')
-            return;
-        const unconfigured = isProviderUnconfiguredError(msg.errorMessage ?? '');
-        if (!unconfigured && !isModelNotFoundError(msg.errorMessage ?? ''))
-            return;
-        // Exact-consult launches fail closed. A concrete request's expansion already
-        // contains only the identical model through its eligible credential sources.
-        if (cfg.modelExact === true)
-            return;
-        if (notFoundFallbackInFlight !== null)
-            return;
-        const generation = installedGeneration;
-        if (generation === undefined)
-            return;
-        const candidateSession = session;
-        const candidateServices = services;
-        const currentSpec = formatModelSpec(session.model, session.thinkingLevel);
-        if (currentSpec === null)
-            return;
-        const current = parseModelSpec(currentSpec);
-        // A 404 rejects the provider/model itself, not only one thinking setting.
-        notFoundModels.add(current.modelSpec);
-        const routeRequest = modelRequestFromConfig(cfg.model, process.env['CRTR_MODEL_INTENT'], false);
-        const routes = routeRequest ? expandModelCandidates(routeRequest, process.env['CRTR_NODE_CWD'] ?? cfg.cwd, process.env['CRTR_PROFILE_ID']) : [];
-        const liveRank = routes.find((candidate) => `${candidate.providerId}/${candidate.modelId}` === current.modelSpec && candidate.thinkingLevel === current.thinkingLevel)?.rank;
-        const nextRoute = liveRank === undefined ? undefined : routes.slice(liveRank + 1).find((candidate) => {
-            if (notFoundModels.has(`${candidate.providerId}/${candidate.modelId}`))
-                return false;
-            return resolveProviderCandidates([{ ...candidate, ...probeRouteAvailability(candidate, registryOf(candidateServices)), automaticFallback: true }]).candidates.length > 0;
-        });
-        if (!nextRoute)
-            return;
-        const target = `${nextRoute.providerId}/${nextRoute.modelId}${nextRoute.thinkingLevel ? `:${nextRoute.thinkingLevel}` : ''}`;
-        const fallbackPromise = (async () => {
-            const model = registryOf(candidateServices).find(nextRoute.providerId, nextRoute.modelId);
-            if (model === undefined) {
-                emitEvent({
-                    level: 'debug',
-                    event: 'broker.runtime.diagnostic',
-                    fields: { message: `${unconfigured ? 'unconfigured-provider' : 'not_found'} fallback skipped: ${target} is not registered` },
-                });
-                return;
-            }
-            await candidateSession.setModel(model);
-            if (installedGeneration !== generation || session !== candidateSession)
-                return;
-            candidateSession.setThinkingLevel((nextRoute.thinkingLevel ?? 'off'));
-            broadcastModelChanged();
-            const resolved = formatModelSpec(candidateSession.model, candidateSession.thinkingLevel) ?? target;
-            emitEvent({
-                level: 'debug',
-                event: 'broker.runtime.diagnostic',
-                fields: { message: `${unconfigured ? 'unconfigured-provider' : 'not_found'} fallback: ${currentSpec} unavailable → ${resolved}; re-driving turn` },
-            });
-            // Re-drive: a 404 left the turn errored, so the model swap alone changes
-            // nothing until the next prompt — re-issue so the now-healthy model picks
-            // the task back up. We fire on message_end, BEFORE the errored turn has
-            // fully settled, so wait for the engine to go idle first: prompt() THROWS
-            // if called while streaming without a streamingBehavior, which would swap
-            // the model but silently skip the continuation.
-            await candidateSession.agent.waitForIdle();
-            if (installedGeneration !== generation || session !== candidateSession)
-                return;
-            // The parked fatal describes a model this session no longer uses. Clearing
-            // it after the errored turn has settled (waitForIdle is past agent_end, so
-            // publishSettledProviderFault has already written it) keeps a recovered
-            // node from reviving straight back into fault-recovery chrome.
-            if (unconfigured)
-                clearFault(nodeId, { link: 'pi→provider' });
-            await operationIdContext.fresh(() => session.prompt(formatModelFallbackRecovery(currentSpec, resolved, unconfigured ? 'credential' : 'not-found')));
-        })()
-            .catch((err) => {
-            emitEvent({
-                level: 'debug',
-                event: 'broker.runtime.diagnostic',
-                fields: { message: `${unconfigured ? 'unconfigured-provider' : 'not_found'} fallback failed: ${err instanceof Error ? err.message : String(err)}` },
-            });
-        })
-            .finally(() => {
-            if (installedGeneration === generation)
-                notFoundFallbackInFlight = null;
-        });
-        notFoundFallbackInFlight = fallbackPromise;
-    };
-    const isActiveAutoFault = (fault) => {
-        if (fault === null)
-            return false;
-        if (fault.retry.disposition !== 'auto')
-            return false;
-        if (fault.retry.by !== 'daemon')
-            return false;
-        return fault.kind === 'connection' || fault.kind === 'rate-limit' || fault.kind === 'overloaded';
-    };
-    const faultRetryDelayMs = (fault, now) => {
-        if (fault.retry.nextAt !== undefined) {
-            const ms = Date.parse(fault.retry.nextAt) - now;
-            return Number.isFinite(ms) ? Math.max(0, ms) : null;
-        }
-        const plan = nextFaultRetry(fault, now);
-        return plan?.delayMs ?? null;
-    };
-    // Node timers accept only a signed int32 delay. Long fault deadlines (for
-    // example an invalid credential's remediation backoff) are chunked so they
-    // cannot overflow into an immediate retry.
-    const MAX_TIMEOUT_MS = 2_147_483_647;
-    const clearAndArmFaultRetry = (delayMs, generation) => {
-        if (installedGeneration !== generation)
-            return;
-        clearFaultRetryTimer();
-        const chunkMs = Math.min(Math.max(0, delayMs), MAX_TIMEOUT_MS);
-        const remainingMs = Math.max(0, delayMs - chunkMs);
-        faultRetryTimer = setTimeout(() => {
-            faultRetryTimer = null;
-            if (installedGeneration !== generation)
-                return;
-            if (remainingMs > 0) {
-                clearAndArmFaultRetry(remainingMs, generation);
-                return;
-            }
-            void runFaultRetry().catch((err) => {
-                emitEvent({
-                    level: 'debug',
-                    event: 'broker.runtime.diagnostic',
-                    fields: { message: `fault retry fire failed: ${err instanceof Error ? err.message : String(err)}` },
-                });
-            });
-        }, chunkMs);
-        if (typeof faultRetryTimer.unref === 'function')
-            faultRetryTimer.unref();
-    };
-    const scheduleFaultRetry = () => {
-        const generation = installedGeneration;
-        if (generation === undefined || session.isStreaming)
-            return;
-        if (faultRetryTimer !== null)
-            return;
-        const fault = readFault(nodeId);
-        if (!isActiveAutoFault(fault)) {
-            clearFaultRetryTimer();
-            return;
-        }
-        const delayMs = faultRetryDelayMs(fault, Date.now());
-        if (delayMs === null)
-            return;
-        clearAndArmFaultRetry(delayMs, generation);
-    };
-    const publishSettledProviderFault = (generation) => {
-        const agentEnd = generation.stagedProviderAgentEnd;
-        const overflowFailure = generation.stagedOverflowFailure;
-        generation.stagedProviderAgentEnd = null;
-        generation.stagedOverflowFailure = null;
-        const settledSession = generation.session;
-        const messages = Array.isArray(agentEnd?.messages) ? agentEnd.messages : [];
-        const last = [...messages].reverse().find((message) => typeof message === 'object' && message !== null && message.role === 'assistant');
-        if (overflowFailure !== null) {
-            // The settled terminal outcome supersedes any auto marker retained while
-            // the broker re-drove this same turn; fault priority must not preserve a
-            // now-obsolete retry plan over Pi's definitive recovery result.
-            clearFault(nodeId, { link: 'pi→provider' });
-            recordFault(nodeId, {
-                link: 'pi→provider',
-                op: 'context overflow recovery',
-                kind: 'context-overflow',
-                retry: { disposition: 'fatal' },
-                message: overflowFailure.errorMessage,
-                anchorEntryId: settledSession.sessionManager.getLeafId?.() ?? undefined,
-            });
-            return;
-        }
-        if (last?.stopReason !== 'error')
-            return;
-        const raw = typeof last.errorMessage === 'string'
-            ? last.errorMessage
-            : 'engine error (no errorMessage recorded)';
-        const uncompactedOverflow = isContextOverflow(last, settledSession.model?.contextWindow);
-        const classified = classify('pi→provider', last);
-        const coolingDeadline = extractCoolingDeadline(last);
-        if (uncompactedOverflow)
-            clearFault(nodeId, { link: 'pi→provider' });
-        recordFault(nodeId, {
-            link: 'pi→provider',
-            op: 'generation turn',
-            kind: uncompactedOverflow ? 'context-overflow' : classified.kind,
-            retry: uncompactedOverflow
-                ? { disposition: 'fatal' }
-                : classified.disposition === 'auto'
-                    ? { disposition: 'auto', by: 'daemon', ...(coolingDeadline !== undefined ? { nextAt: new Date(coolingDeadline).toISOString() } : {}) }
-                    : { disposition: classified.disposition },
-            message: raw,
-            anchorEntryId: settledSession.sessionManager.getLeafId?.() ?? undefined,
-        });
-    };
-    const runFaultRetry = async () => {
-        const generation = installedGeneration;
-        if (generation === undefined)
-            return;
-        const candidateSession = generation.session;
-        if (candidateSession.isStreaming)
-            return;
-        const initial = readFault(nodeId);
-        if (!isActiveAutoFault(initial))
-            return;
-        let fault = initial;
-        if (initial.kind === 'connection') {
-            const online = await retryProbe();
-            // The probe can take seconds. A turn may have started, or the marker may
-            // have been cleared/replaced/recovered, in that window. Re-validate
-            // against fresh state before re-arming or consuming an attempt —
-            // otherwise a stale retry resurrects a recovered episode or double-drives
-            // a now-streaming session.
-            if (installedGeneration !== generation || session !== candidateSession || candidateSession.isStreaming)
-                return;
-            const fresh = readFault(nodeId);
-            if (!isActiveAutoFault(fresh) || fresh.since !== initial.since)
-                return;
-            if (!online) {
-                clearAndArmFaultRetry(policyFor(fresh.kind).baseDelayMs, generation);
-                return;
-            }
-            fault = fresh;
-        }
-        const now = Date.now();
-        const attempt = fault.retry.attempt ?? 0;
-        const policy = policyFor(fault.kind);
-        if (attempt >= policy.max) {
-            recordFault(nodeId, markFatalOnExhaust(fault));
-            return;
-        }
-        const plan = nextFaultRetry(fault, now);
-        if (plan === null) {
-            recordFault(nodeId, markFatalOnExhaust(fault));
-            return;
-        }
-        const anchorEntryId = fault.anchorEntryId;
-        if (anchorEntryId !== undefined) {
-            try {
-                const leafId = candidateSession.sessionManager.getLeafId?.() ?? null;
-                if (leafId !== anchorEntryId) {
-                    await candidateSession.navigateTree(anchorEntryId);
-                    if (installedGeneration !== generation || session !== candidateSession)
-                        return;
-                }
-            }
-            catch (err) {
-                emitEvent({
-                    level: 'debug',
-                    event: 'broker.runtime.diagnostic',
-                    fields: { message: `fault retry rewind skipped: ${err instanceof Error ? err.message : String(err)}` },
-                });
-            }
-        }
-        if (installedGeneration !== generation || session !== candidateSession)
-            return;
-        recordFault(nodeId, plan.fault);
-        await operationIdContext.fresh(() => session.prompt(fault.kind === 'connection' ? CONNECTION_FAULT_RECOVERY_BODY : PROVIDER_FAULT_RECOVERY_BODY));
-    };
-    // Waiters for "the engine ACCEPTED a prompt and a turn is now running". A
-    // routed prompt's own promise settles only when the whole TURN ends, which is
-    // minutes too late to ack a deliver; agent_start is the engine's own signal
-    // that the call got past its model/auth gate. The deliver ack races these two.
-    const turnAcceptedWaiters = new Set();
-    const notifyTurnAccepted = () => {
-        if (turnAcceptedWaiters.size === 0)
-            return;
-        const waiters = [...turnAcceptedWaiters];
-        turnAcceptedWaiters.clear();
-        for (const waiter of waiters)
-            waiter();
-    };
-    const relayEvent = (event, generation) => {
-        maybeSwitchProviderForRetry(event);
-        maybeFallbackOnUnusableModel(event);
-        const type = event.type;
-        if (type === 'agent_start') {
-            try {
-                workingActivity = randomWorkingActivity(readConfig('user').working_gerunds);
-            }
-            catch {
-                workingActivity = DEFAULT_WORKING_ACTIVITY;
-            }
-            // Announce the selected label before relaying pi's verbatim agent_start so
-            // every viewer paints this turn with the same random choice.
-            broadcast({ type: 'working_activity', activity: workingActivity });
-            notifyTurnAccepted();
-            emitStartupMilestone('broker.startup.agent_start', formatModelSpec(session.model, session.thinkingLevel));
-        }
-        if (type === 'message_update') {
-            const message = event.message;
-            if (message?.role === 'assistant')
-                emitStartupMilestone('broker.startup.provider_first_delta', formatModelSpec(session.model, session.thinkingLevel));
-        }
-        if (type === 'message_end') {
-            const message = event.message;
-            if (message?.role === 'assistant')
-                emitStartupMilestone('broker.startup.assistant_message_end', formatModelSpec(session.model, session.thinkingLevel));
-        }
-        if (type === 'agent_start' || type === 'turn_start')
-            clearFaultRetryTimer();
-        // The watchdog covers ONLY time awaiting the provider. `session.isStreaming`
-        // stays true through tool execution, so a legitimately silent tool lasting
-        // longer than the timeout would otherwise be aborted mid-run: disarm while
-        // any tool executes and rearm once the last one ends. Multiple tools can run
-        // concurrently, so track in-flight ids and only rearm when the set drains.
-        if (type === 'agent_end') {
-            // Clear the in-flight set too: an abnormal run can emit agent_end after a
-            // tool_execution_start with no matching tool_execution_end. A leftover id
-            // would keep executingTools non-empty forever, gating every future poke
-            // (size === 0) and permanently disarming the watchdog until a rebind.
-            generation.executingTools.clear();
-            streamWatchdog.reset();
-        }
-        else if (type === 'tool_execution_start') {
-            generation.executingTools.add(event.toolCallId ?? '');
-            streamWatchdog.clear();
-        }
-        else if (type === 'tool_execution_end') {
-            generation.executingTools.delete(event.toolCallId ?? '');
-            if (generation.executingTools.size === 0 && generation.session.isStreaming)
-                streamWatchdog.poke(generation.id);
-        }
-        else if (generation.session.isStreaming && generation.executingTools.size === 0) {
-            streamWatchdog.poke(generation.id);
-        }
-        if (type === 'message_update') {
-            pendingUpdate = event; // latest full-message update supersedes the held one
-            if (pendingUpdateTimer === null) {
-                pendingUpdateTimer = setTimeout(flushPendingUpdate, MESSAGE_UPDATE_COALESCE_MS);
-                if (typeof pendingUpdateTimer.unref === 'function')
-                    pendingUpdateTimer.unref();
-            }
-            return;
-        }
-        // Any non-update event: flush the held update FIRST so a viewer never sees
-        // (e.g.) message_end before the update it supersedes. A refresh-yield aborts
-        // its own turn; the visible cycle divider names that boundary, so do not also
-        // render it as an operation failure.
-        flushPendingUpdate();
-        if (type === 'message_end' && getNode(nodeId)?.intent === 'refresh') {
-            const messageEnd = event;
-            broadcast({ ...messageEnd, message: withoutYieldAbort(messageEnd.message) });
-            return;
-        }
-        broadcast(event);
-    };
-    // Persist the live model + thinking level into the node's durable launch
-    // recipe so a daemon restart/revive recreates the settings the user sees.
-    // pi's model/thinking controls only mutate the in-memory engine; without this
-    // the node reverts to its persona/spawn settings on the next broker boot. We
-    // write the full `provider/id:thinking` spec to BOTH model_override (so
-    // polymorphs preserve it via buildLaunchSpec) and launch.model (the recipe
-    // buildPiArgv replays on revive). Best-effort: a degenerate/ephemeral node
-    // with no canvas row just skips persistence. CRTR_NODE_ID is set in the
-    // broker's own env (merged by piInvocationToSdkConfig at boot).
-    // `pinnedOverride`, when passed, is the durable launch-recipe decision for
-    // an explicit model change, derived from its raw pre-normalize token. A
-    // `userSelected` change also clears the older logical route intent: otherwise
-    // resolveLaunchModel ignores the newly persisted concrete spec at reboot and
-    // resolves the persona's original family/strength again. Algorithmic provider
-    // fallback leaves that intent intact.
-    const persistModelChoice = (pinnedOverride, userSelected = false) => {
-        const nodeId = process.env['CRTR_NODE_ID'];
-        const spec = formatModelSpec(session.model, session.thinkingLevel);
-        if (nodeId === undefined || nodeId === '' || spec === null)
-            return;
-        try {
-            const meta = getNode(nodeId);
-            if (meta === null)
-                return;
-            const launch = meta.launch === undefined
-                ? undefined
-                : userSelected
-                    ? (() => {
-                        const { modelIntent: _modelIntent, env, ...rest } = meta.launch;
-                        const { CRTR_MODEL_INTENT: _intentEnv, ...remainingEnv } = env;
-                        return {
-                            ...rest,
-                            model: spec,
-                            ...(pinnedOverride !== undefined ? { modelProviderPinned: pinnedOverride } : {}),
-                            env: remainingEnv,
-                        };
-                    })()
-                    : { ...meta.launch, model: spec, ...(pinnedOverride !== undefined ? { modelProviderPinned: pinnedOverride } : {}) };
-            if (userSelected) {
-                delete process.env['CRTR_MODEL_INTENT'];
-                cfg.model = spec;
-            }
-            updateNode(nodeId, { model_override: spec, ...(launch !== undefined ? { launch } : {}) });
-        }
-        catch {
-            // Persistence is best-effort; the live switch already succeeded.
-        }
-    };
-    // pi emits no AgentSessionEvent for a model switch, so after a successful
-    // set_model/cycle_model the broker announces it itself — otherwise the new
-    // model reaches no viewer (the requester gets only a bare ack) and every
-    // footer shows the stale model until the next unrelated event.
-    const broadcastModelChanged = (persist = true, pinnedOverride, userSelected = false) => {
-        if (persist)
-            persistModelChoice(pinnedOverride, userSelected);
-        broadcast({ type: 'model_changed', model: isUnknownModel(session.model) ? undefined : session.model, spec: formatModelSpec(session.model, session.thinkingLevel) });
-    };
-    const buildSnapshot = () => ({
-        messages: snapshotMessages(session, reviewCompanion),
-        stats: session.getSessionStats(),
-        // pi's `get_state` (rpc-mode.js), field for field, from the same getters.
-        // The ONE divergence: a model-less session (undefined OR the SDK
-        // unknown-stub) reports no model, matching broadcastModelChanged — never a
-        // fictitious `unknown` selection.
-        state: {
-            model: isUnknownModel(session.model) ? undefined : session.model,
-            thinkingLevel: session.thinkingLevel,
-            isStreaming: session.isStreaming,
-            isCompacting: session.isCompacting,
-            steeringMode: session.steeringMode,
-            followUpMode: session.followUpMode,
-            sessionFile: session.sessionFile,
-            sessionId: session.sessionId,
-            sessionName: session.sessionName,
-            autoCompactionEnabled: session.autoCompactionEnabled,
-            messageCount: session.messages.length,
-            pendingMessageCount: session.pendingMessageCount,
-        },
-        // Broker-owned levels (see BrokerSnapshot.display). Copied out so a later
-        // mutation of the retained maps cannot alias a frame already serialized.
-        display: {
-            statuses: Object.fromEntries(displayStatuses),
-            widgets: Object.fromEntries([...displayWidgets].map(([k, w]) => [k, { lines: [...w.lines], placement: w.placement }])),
-            title: displayTitle,
-        },
-        toolGroupSummaries: Object.fromEntries(toolGroupSummaries),
-        workingActivity,
-    });
-    // Send a client its catch-up snapshot. welcome.pending_dialog carries a single
-    // still-in-flight dialog to a WRITABLE client attaching mid-dialog; an observer
-    // can never answer one, so observers get null. The pendingDialogs map is
-    // insertion-ordered — the first entry is the canonical one carried here; any
-    // extras are replayed explicitly by the caller (rare: concurrent dialogs).
-    const sendWelcome = (client) => {
-        const first = client.role === 'controller' ? pendingDialogs.values().next().value : undefined;
-        sendFrame(client, {
-            type: 'welcome',
-            snapshot: buildSnapshot(),
-            role: client.role,
-            pending_dialog: first !== undefined ? first.request : null,
-            agentDir: getAgentDir(),
-        }, true);
-        // No display_* replay: the retained extension state rides IN the snapshot
-        // (`snapshot.display`), so catch-up is one atomic frame. A viewer attaching
-        // after an idle brief was painted still sees it on first paint, and there is
-        // no window between `welcome` and the replay where chrome renders blank.
-    };
-    // Attach-mid-dialog replay: a dialog raised before this client attached is
-    // still pending (a peer detaching never cancels one — see makeBrokerUiContext),
-    // so a writable client joining afterwards is handed every in-flight dialog and
-    // becomes a full peer in the race to answer it. `welcome.pending_dialog` already
-    // carried the FIRST entry, so this replays only the extras.
-    const replayExtraPendingDialogsTo = (client) => {
-        const pend = [...pendingDialogs.values()];
-        for (let i = 1; i < pend.length; i++)
-            sendFrame(client, pend[i].request);
-    };
-    // After a session-replacing op (new_session/switch_session/fork) the engine's
-    // entire message history changed, so every attached viewer must rebuild from a
-    // fresh snapshot of the NEW session.
-    const reWelcomeAll = () => {
-        for (const c of clients)
-            if (c.helloed)
-                sendWelcome(c);
-    };
-    // -------------------------------------------------------------------------
-    // The single exit helper (plan §0): dispose the engine, close + unlink the
-    // socket, exit 0. Idempotent — every trigger converges here.
-    // -------------------------------------------------------------------------
-    const completeExit = (status) => {
-        if (disposed)
-            return;
-        disposed = true;
-        // Daemon teardown cannot wait for a recap's 45-second model timeout. Preserve
-        // exactly the newest already-capped input so the successor broker can finish
-        // it, persist the normal summary, and remove the handoff record.
-        const pendingSummary = [...generatingToolGroups.values()].at(-1);
-        if (pendingSummary !== undefined) {
-            try {
-                atomicWriteJson(pendingToolSummaryPath, pendingSummary);
-            }
-            catch (error) {
-                emitEvent({
-                    level: 'warn',
-                    event: 'broker.runtime.diagnostic',
-                    fields: {
-                        message: `failed to persist pending tool summary: ${error instanceof Error ? error.message : String(error)}`,
-                    },
-                });
-            }
-        }
-        streamWatchdog.reset();
-        // disposeActiveSession atomically clears the process-global pointer before
-        // disposing — whichever engine session (committed or an in-flight rebind
-        // candidate) it currently names, matching broker-cli's fatal-handler primitive.
-        disposeActiveSession();
-        try {
-            server?.close();
-        }
-        catch {
-            /* ignore */
-        }
-        // Finite and best-effort: destroy every currently tracked client socket so
-        // teardown below can't race a viewer write, then drop the set. Do not wait
-        // for 'close' events.
-        for (const client of clients) {
-            try {
-                client.socket.destroy();
-            }
-            catch {
-                /* ignore */
-            }
-        }
-        clients.clear();
-        try {
-            if (existsSync(sockPath))
-                unlinkSync(sockPath);
-        }
-        catch {
-            /* ignore */
-        }
-        try {
-            // A clean exit never leaves a stale presence claim behind.
-            if (existsSync(attachPath))
-                unlinkSync(attachPath);
-        }
-        catch {
-            /* ignore */
-        }
-        process.exit(status);
-    };
-    const disposeAndExit = (reason, status = 0) => {
-        if (disposed)
-            return;
-        const graceful = reason === 'shutdown-hook' || reason === 'shutdown-after-settle';
-        // A graceful shutdown (yield, dormancy, daemon restart) is the final
-        // boundary of the conversation's last tool group. Group state lives only in
-        // this process, so a group left open here is unsummarizable forever and its
-        // calls render raw in every future view of the transcript. Close it now —
-        // generateSettledToolGroup registers its task synchronously, so the wait
-        // below covers the summary it launches. Any pending tool arguments are
-        // included without inventing a result; the visible abort remains outside
-        // the recap and Ctrl+O retains every underlying call row.
-        if (graceful)
-            finishOpenToolGroup(true);
-        // A normal terminal shutdown follows a visible boundary that may have just
-        // launched a capped (45s) headless summary. Keep the broker and its child
-        // alive until those already-started tasks persist/broadcast, rather than
-        // process.exit() orphaning pi and losing the sidecar. Abrupt failures and
-        // signals retain their existing immediate teardown behavior.
-        if (graceful && summaryTasks.size > 0) {
-            if (disposePending)
-                return;
-            disposePending = true;
-            void Promise.allSettled([...summaryTasks]).finally(() => completeExit(status));
-            return;
-        }
-        completeExit(status);
-    };
-    // A stophook can request shutdown while pi is still unwinding a completed
-    // turn. Let that turn reach agent_settled first: inbox delivery commits its
-    // durable cursor there, and only there. Explicit operator shutdown and OS
-    // signals remain abrupt through disposeAndExit.
-    const requestShutdown = () => {
-        if (disposed || shutdownRequested)
-            return;
-        if (!agentRunActive) {
-            disposeAndExit('shutdown-hook');
-            return;
-        }
-        shutdownRequested = true;
-    };
-    // -------------------------------------------------------------------------
-    // Extension-dialog routing (C2). makeBrokerUiContext owns the dialogPromise;
-    // here we just give it the three broker-side hooks it needs: the live set of
-    // writable clients (empty = nobody can answer → noOp fallback), how to forward a
-    // dialog to one of them, and the pending-dialog registry whichever one answers
-    // first settles through. The zero-writable path NEVER hangs and NEVER waits on a
-    // per-dialog timeout (design §5.4's timeout premise is false — see
-    // makeBrokerUiContext).
-    // -------------------------------------------------------------------------
-    const uiContext = makeBrokerUiContext({
-        writable: writableClients,
-        forward: (client, request) => sendFrame(client, request),
-        pending: pendingDialogs,
-        broadcast: broadcastUi,
-        // A deliberate managed-provider cooldown wait is known liveness, not a wedged
-        // stream: pause the dead-stream watchdog for its duration. Only pause for a
-        // finite future deadline, and resume ONLY while the same turn is still
-        // awaiting the provider (streaming, no tool running) so a wait that outlived
-        // its turn can't rearm a stale session; otherwise fully reset.
-        onKnownStreamWait: (deadlineMs) => {
-            if (!Number.isFinite(deadlineMs) || deadlineMs <= Date.now())
-                return () => { };
-            const generation = installedGeneration;
-            if (generation === undefined)
-                return () => { };
-            const waitingSession = generation.session;
-            streamWatchdog.pause();
-            return () => {
-                if (installedGeneration !== generation || session !== waitingSession)
-                    return;
-                releaseKnownStreamWait(streamWatchdog, generation.id, waitingSession.isStreaming, generation.executingTools.size > 0);
-            };
-        },
-    });
-    // -------------------------------------------------------------------------
-    // 3+4 (plan): bind the FULL canvas extensions (mode 'rpc') AND fan the single
-    // engine event stream to all clients, VERBATIM — both wrapped in one
-    // ticketed rebind lane so a session-replacing op (new_session/switch_session/fork)
-    // can re-run them against the NEW session. This mirrors pi's rpc-mode callback:
-    // the AgentSessionRuntime tears down the old
-    // session, builds the next, then calls this back; we re-bind extensions and
-    // re-subscribe so the canvas hooks + the fan-out follow the live session.
-    //
-    // bindExtensions fires session_start → the stophook records pi_session_id/file
-    // + recordPid(pid); the shutdownHandler is the precise broker-exit trigger (the
-    // stophook calls ctx.shutdown() only in its done / idle-release / refresh
-    // branches, NOT on reprompt). A requested in-turn shutdown exits after the
-    // subscriber observes agent_settled, while every other branch stays alive. The
-    // relay must not infer shutdown from raw agent_end: that would override the
-    // stophook's routing decision. shutdownHandler + the inbound `shutdown` frame
-    // are the only exit triggers.
-    //
-    // m7: the subscriber body is wrapped in try/catch — a synchronous throw out of
-    // a subscriber otherwise propagates as a run failure that would crash the broker.
-    // -------------------------------------------------------------------------
-    let unsubscribe;
-    const removeInstalledSubscription = () => {
-        const installed = unsubscribe;
-        installed?.();
-        unsubscribe = undefined;
-        installedGeneration = undefined;
-    };
-    let rebindTail = Promise.resolve();
-    let latestRebindRequest = 0;
-    const captureSystemPrompt = (candidateSession) => {
-        try {
-            const dir = jobDir(nodeId);
-            mkdirSync(dir, { recursive: true });
-            writeFileSync(join(dir, 'system-prompt.md'), candidateSession.systemPrompt, 'utf8');
-        }
-        catch {
-            /* non-fatal: diagnostic only */
-        }
-    };
-    const executeSubscriptionCallback = (generation, event) => {
-        try {
-            if (event.type === 'agent_start')
-                agentRunActive = true;
-            if (event.type === 'agent_end') {
-                generation.stagedProviderAgentEnd = event;
-                // A continuation after failed compaction owns the final settled outcome.
-                generation.stagedOverflowFailure = null;
-            }
-            if (event.type === 'compaction_end' &&
-                event.reason === 'overflow' &&
-                event.willRetry === false &&
-                typeof event.errorMessage === 'string') {
-                generation.stagedOverflowFailure = { errorMessage: event.errorMessage };
-            }
-            if (event.type === 'agent_settled') {
-                agentRunActive = false;
-                publishSettledProviderFault(generation);
-                if (shutdownRequested) {
-                    disposeAndExit('shutdown-after-settle');
-                    return;
-                }
-            }
-            observeToolGroupEvent(event);
-            relayEvent(event, generation);
-            if (event.type === 'agent_settled')
-                scheduleFaultRetry();
-        }
-        catch (err) {
-            emitEvent({
-                level: 'debug',
-                event: 'broker.runtime.diagnostic',
-                fields: { message: `event relay threw: ${String(err)}` },
-            });
-        }
-    };
-    const enqueueRebind = (candidateSession, candidateServices) => {
-        const ticket = ++latestRebindRequest;
-        const task = rebindTail.then(async () => {
-            if (ticket !== latestRebindRequest)
-                return;
-            installedGeneration?.executingTools.clear();
-            removeInstalledSubscription();
-            // This candidate is now the engine session a mid-rebind fatal cleanup must
-            // dispose — set before the awaited bindExtensions so a timeout/fatal during
-            // that await disposes the candidate rather than the stale committed session.
-            // Shared session/services ownership still only commits below, post-await.
-            activeSession = candidateSession;
-            streamWatchdog.reset();
-            agentRunActive = false;
-            if (pendingUpdateTimer !== null) {
-                clearTimeout(pendingUpdateTimer);
-                pendingUpdateTimer = null;
-            }
-            pendingUpdate = null;
-            clearFaultRetryTimer();
-            providerFallbackInFlight = null;
-            notFoundFallbackInFlight = null;
-            reloadAuthInFlight = null;
-            openToolGroup = undefined;
-            toolGroupsByCallId.clear();
-            sawAssistantProse = false;
-            await candidateSession.bindExtensions({
-                uiContext,
-                // 'rpc' — NOT 'print'. Per pi docs/rpc.md:1078 this is exactly our shape:
-                // a headless engine whose UI methods are functional through a remote client
-                // (our uiContext relays them as `display_*` / `extension_ui_request` frames).
-                // 'print' would tell every extension `ctx.mode === 'print'` — pi's own label
-                // for "extensions run but can't prompt" — while we hand them a uiContext that
-                // can. (`ctx.hasUI` is derived from uiContext identity, not from mode, so it
-                // was already true; this fixes the mode label the extensions actually read.)
-                // The `ctx.mode === 'tui'` guards in canvas-view/-resume/-commands stay dead.
-                mode: 'rpc',
-                shutdownHandler: requestShutdown,
-            });
-            if (ticket !== latestRebindRequest)
-                return;
-            removeInstalledSubscription();
-            session = candidateSession;
-            services = candidateServices;
-            if (cfg.editorName !== undefined && cfg.editorName !== '') {
-                try {
-                    candidateSession.setSessionName(cfg.editorName);
-                }
-                catch {
-                    /* non-fatal: naming is cosmetic */
-                }
-            }
-            const generation = {
-                id: ++nextSubscriptionGeneration,
-                session: candidateSession,
-                fallback: { blocked: false },
-                stagedProviderAgentEnd: null,
-                stagedOverflowFailure: null,
-                executingTools: new Set(),
-            };
-            unsubscribe = session.subscribe((event) => {
-                if (installedGeneration !== generation)
-                    return;
-                const ambientId = operationIdContext.current();
-                if (ambientId !== undefined) {
-                    executeSubscriptionCallback(generation, event);
-                    return;
-                }
-                const fallback = generation.fallback;
-                if (event.type === 'turn_start' && fallback.storedId !== undefined) {
-                    fallback.storedId = undefined;
-                    fallback.blocked = true;
-                    operationIdContext.fresh(() => {
-                        emitEvent({
-                            level: 'warn',
-                            event: 'broker.turn.fallback_overlap',
-                            fields: { generation: generation.id, engine_event: event.type },
-                        });
-                        executeSubscriptionCallback(generation, event);
-                    });
-                    return;
-                }
-                if (event.type === 'turn_start' && !fallback.blocked) {
-                    operationIdContext.fresh((operationId) => {
-                        fallback.storedId = operationId;
-                        executeSubscriptionCallback(generation, event);
-                    });
-                    return;
-                }
-                const storedId = fallback.storedId;
-                if (storedId !== undefined && !fallback.blocked) {
-                    operationIdContext.run(storedId, () => {
-                        executeSubscriptionCallback(generation, event);
-                        if (event.type === 'agent_settled' && fallback.storedId === storedId) {
-                            fallback.storedId = undefined;
-                        }
-                    });
-                    return;
-                }
-                executeSubscriptionCallback(generation, event);
-            });
-            installedGeneration = generation;
-            captureSystemPrompt(candidateSession);
-        });
-        rebindTail = task.catch(() => undefined);
-        return task;
-    };
-    // Register the rebind BEFORE the first bind so a replacement triggered during
-    // startup is honored; then use the same ticketed lane for the initial install.
-    runtime?.setRebindSession((candidateSession) => enqueueRebind(candidateSession, runtime.services));
-    await enqueueRebind(session, services);
-    // -------------------------------------------------------------------------
-    // 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 `session.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;
-    };
-    const buildListMemoryRefsData = (id) => ({
-        type: 'data',
-        id,
-        kind: 'list_memory_refs',
-        refs: getRefInventory().refs,
-        engineLeadingCommandNames: engineLeadingCommandTokens(session),
-    });
-    /** 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, session))
-                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. `session.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 `session.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;
-            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 (session.isBashRunning) {
-                    session.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 (!session.isStreaming && pendingPromptDispatches > 0) {
-                        const deadline = Date.now() + 5_000;
-                        while (Date.now() < deadline && !session.isStreaming && pendingPromptDispatches > 0) {
-                            await new Promise((resolve) => setTimeout(resolve, 25));
-                        }
-                    }
-                    if (session.isStreaming)
-                        await session.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) => session
-            .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, session.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(() => session.prompt(frame.text, route.options).catch(relayError))));
-                        }
-                        // C1: pi's followUp() takes images as a POSITIONAL 2nd arg (`followUp(text, images?)`).
-                        return settle(session.followUp(frame.text, frame.images).catch(relayError));
-                    }
-                    const deliverAs = chooseGuidanceDeliveryMode(frame.type, route.call, session.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(session, guidance, () => operationIdContext.fresh(() => session.prompt(frame.text, route.options))).catch(relayError)));
-                        }
-                        return settle(trackPromptDispatch(operationIdContext.fresh(() => session.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(session.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 = session.isStreaming ? undefined : reloadAuthInFlight?.promise;
-                if (authReload === undefined)
-                    return dispatch();
-                const waitingGeneration = installedGeneration;
-                const waitingSession = session;
-                return authReload.then(() => {
-                    if (installedGeneration !== waitingGeneration || session !== waitingSession) {
-                        relayError(new Error('session 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, session) === 'prompt') {
-                    void session.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 session.steer(frame.text, frame.images).catch(relayError);
-                    break;
-                }
-                void session.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 (session.isBashRunning) {
-                    session.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 session.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 (!session.isStreaming && pendingPromptDispatches > 0) {
-                            const deadline = Date.now() + 5_000;
-                            while (Date.now() < deadline && !session.isStreaming && pendingPromptDispatches > 0) {
-                                await new Promise((r) => setTimeout(r, 25));
-                            }
-                        }
-                        const detail = session.isStreaming ? 'turn' : 'idle';
-                        await session.abort();
-                        ackTo(client, 'abort', true, detail, frame.id);
-                    }
-                    catch (err) {
-                        engineErrorTo(client, frame.id)(err);
-                    }
-                })();
-                break;
-            }
-            case 'bash': {
-                // `!`/`!!` bash: run via session.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 (session.isBashRunning) {
-                    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.
-                flushPendingUpdate();
-                // The live bash component is a visible transcript boundary, even though
-                // its persisted bashExecution message arrives later via the session.
-                finishOpenToolGroup();
-                broadcast({ type: 'bash_start', command, excludeFromContext: exclude });
-                void session
-                    .executeBash(command, (chunk) => broadcast({ type: 'bash_output', chunk }), {
-                    excludeFromContext: exclude,
-                })
-                    .then((result) => {
-                    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;
-        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) => sendFrame(client, {
-        type: 'ack',
-        for: op,
-        ok,
-        ...(detail !== undefined ? { detail } : {}),
-        ...(id !== undefined ? { id } : {}),
-    });
-    const engineErrorTo = (client, id) => (err) => 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 &&
-        !session.sessionManager.getBranch(entryId).some((entry) => entry.type === 'custom_message' && entry.customType === REVIEW_BOUNDARY_CUSTOM_TYPE);
-    const reviewBoundaryRefusalTo = (client, targetId) => {
-        const refusal = new ReviewBoundaryNavigationError(targetId);
-        sendFrame(client, {
-            type: 'error',
-            code: refusal.code,
-            message: refusal.message,
-        });
-    };
-    /** Resolve a `provider/id` model spec against the LIVE services 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(services).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(services).getAll();
-        }
-        catch {
-            return undefined;
-        }
-        let availableKeys;
-        try {
-            availableKeys = new Set(registryOf(services).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;
-    };
-    const buildCommandList = () => {
-        const out = [];
-        for (const b of BUILTIN_SLASH_COMMANDS) {
-            out.push({ name: b.name, description: b.description, source: 'builtin' });
-        }
-        try {
-            for (const c of session.extensionRunner.getRegisteredCommands()) {
-                const expansion = c.expansion;
-                out.push({
-                    name: c.invocationName,
-                    description: c.description ?? '',
-                    source: 'command',
-                    ...(isDeterministicCommandExpansion(expansion) ? { expansion } : {}),
-                });
-            }
-        }
-        catch {
-            /* an engine without a live extensionRunner (e.g. the fake) — builtins only */
-        }
-        try {
-            for (const t of session.promptTemplates) {
-                out.push({ name: t.name, description: t.description, source: 'template', template: t.content });
-            }
-        }
-        catch {
-            /* ignore */
-        }
-        return out;
-    };
-    // -------------------------------------------------------------------------
-    // Read-op data builders (operator-view picker payloads, §5 Unit A). Each is a
-    // PURE getter read against the live engine session — the data a native pi
-    // picker's constructor needs, serialized for the viewer. Not role-gated
-    // (read-only, like get_commands), so the web bridge's observer connection can
-    // populate pickers too.
-    // -------------------------------------------------------------------------
-    // A model-less session's model is EITHER undefined OR the SDK unknown-stub;
-    // both map to the WireModelRef no-model value (null), so list_models.current
-    // and get_settings.settings.model never disclose a fictitious `unknown/unknown`.
-    const toModelRef = (m) => m === undefined || isUnknownModel(m) ? null : { provider: m.provider, id: m.id };
-    const modelKey = (m) => `${m.provider}/${m.id}`;
-    const buildListModelsData = (id) => {
-        const reg = registryOf(session);
-        let availableIds = [];
-        try {
-            availableIds = reg.getAvailable().map(modelKey);
-        }
-        catch {
-            /* getAvailable touches auth config; degrade to "none known available" */
-        }
-        return {
-            type: 'data',
-            id,
-            kind: 'list_models',
-            models: reg.getAll(),
-            current: toModelRef(session.model),
-            availableIds,
-            scopedModels: session.scopedModels.map((s) => ({
-                model: s.model,
-                thinkingLevel: s.thinkingLevel,
-            })),
-            enabledModelIds: session.settingsManager.getEnabledModels() ?? null,
-        };
-    };
-    const buildScopedModelsData = (id) => ({
-        type: 'data',
-        id,
-        kind: 'list_scoped_models',
-        allModels: registryOf(session).getAll(),
-        enabledModelIds: session.settingsManager.getEnabledModels() ?? null,
-    });
-    const buildGetTreeData = (id) => {
-        const sm = session.sessionManager;
-        const tree = reviewCompanion ? boundaryRootedTree(sm.getTree()) : sm.getTree();
-        const visibleEntryIds = new Set();
-        const collectEntryIds = (nodes) => {
-            for (const node of nodes) {
-                visibleEntryIds.add(node.entry.id);
-                collectEntryIds(node.children);
-            }
-        };
-        collectEntryIds(tree);
-        const forkPoints = session.getUserMessagesForForking()
-            .filter((u) => visibleEntryIds.has(u.entryId))
-            .map((u) => ({
-            id: u.entryId,
-            text: u.text,
-            timestamp: sm.getEntry(u.entryId)?.timestamp,
-        }));
-        const currentLeafId = sm.getLeafId();
-        return {
-            type: 'data',
-            id,
-            kind: 'get_tree',
-            tree,
-            currentLeafId: currentLeafId !== null && visibleEntryIds.has(currentLeafId) ? currentLeafId : null,
-            forkPoints,
-        };
-    };
-    const buildSettingsData = (id) => {
-        const sm = session.settingsManager;
-        // Theme names are enumerable broker-side via the resource loader. The theme
-        // SUBMENU itself is viewer-local (theme is a viewer-only concern), but the
-        // settings menu still shows currentTheme/availableThemes, so include them.
-        let availableThemes = [];
-        try {
-            availableThemes = session.resourceLoader
-                .getThemes()
-                .themes.map((t) => t.name ?? '')
-                .filter((n) => n !== '');
-        }
-        catch {
-            /* loader without themes — viewer falls back to its local theme registry */
-        }
-        const settings = {
-            autoCompact: session.autoCompactionEnabled,
-            showImages: sm.getShowImages(),
-            imageWidthCells: sm.getImageWidthCells(),
-            autoResizeImages: sm.getImageAutoResize(),
-            blockImages: sm.getBlockImages(),
-            enableSkillCommands: sm.getEnableSkillCommands(),
-            steeringMode: session.steeringMode,
-            followUpMode: session.followUpMode,
-            transport: sm.getTransport(),
-            httpIdleTimeoutMs: sm.getHttpIdleTimeoutMs(),
-            thinkingLevel: session.thinkingLevel,
-            availableThinkingLevels: session.getAvailableThinkingLevels(),
-            currentTheme: sm.getTheme() ?? '',
-            // Light/dark appearance is a property of the terminal the VIEWER is attached
-            // to; the headless broker has none, so emit a placeholder. The viewer owns
-            // the theme submenu and resolves real terminal appearance locally.
-            terminalTheme: 'dark',
-            availableThemes,
-            hideThinkingBlock: sm.getHideThinkingBlock(),
-            collapseChangelog: sm.getCollapseChangelog(),
-            enableInstallTelemetry: sm.getEnableInstallTelemetry(),
-            doubleEscapeAction: sm.getDoubleEscapeAction(),
-            treeFilterMode: sm.getTreeFilterMode(),
-            showHardwareCursor: sm.getShowHardwareCursor(),
-            editorPaddingX: sm.getEditorPaddingX(),
-            autocompleteMaxVisible: sm.getAutocompleteMaxVisible(),
-            quietStartup: sm.getQuietStartup(),
-            clearOnShrink: sm.getClearOnShrink(),
-            showTerminalProgress: sm.getShowTerminalProgress(),
-            warnings: sm.getWarnings(),
-            defaultProjectTrust: sm.getDefaultProjectTrust(),
-            showCacheMissNotices: sm.getShowCacheMissNotices(),
-            outputPad: sm.getOutputPad(),
-            autoRetry: session.autoRetryEnabled,
-            model: toModelRef(session.model),
-        };
-        return { type: 'data', id, kind: 'get_settings', settings };
-    };
-    // Cache per-session wire info keyed by (path, mtime, size) so reopening the
-    // picker doesn't re-read the whole corpus (see session-list-cache.ts).
-    const sessionListCache = new SessionListCache(sessionListCachePath());
-    // Pre-warm the cwd scope (the picker's default tab) in the background so the
-    // first /resume open on this fresh broker is already warm.
-    sessionListCache.prewarm(session.sessionManager.getSessionDir());
-    const buildSessionsData = async (id, scope) => {
-        const sm = session.sessionManager;
-        const sessionDir = sm.getSessionDir();
-        const sessions = scope === 'all'
-            ? await sessionListCache.listAll(piSessionsRoot())
-            : await sessionListCache.listDir(sessionDir);
-        return {
-            type: 'data',
-            id,
-            kind: 'list_sessions',
-            scope,
-            sessions,
-            currentSessionFile: session.sessionFile,
-        };
-    };
-    /** Runtime-mutating viewer replacements are serialized through their complete
-     *  rebind, re-welcome, and client settlement. Admission is bounded to at most
-     *  one active head plus one queued follow-up (`MAX_ADMITTED_REPLACEMENTS`); a
-     *  request over that cap is a definite, correlated rejection that never touches
-     *  the tail. Each admitted head gets one `REPLACEMENT_DEADLINE_MS` budget
-     *  covering the full runtime mutation through its awaited rebind. The SDK has
-     *  no cancellation primitive for these mutations, so a rejection or an expired
-     *  deadline after admission leaves runtime/shared state indeterminate — the
-     *  only truthful response is broker-terminal exit, never a retry, and the tail
-     *  never advances to the queued closure against that uncertain state. */
-    let replacementTail = Promise.resolve();
-    let admittedReplacements = 0;
-    const runReplacement = (client, op, run) => {
-        if (runtime === undefined) {
-            sendFrame(client, {
-                type: 'error',
-                code: 'engine_error',
-                message: 'session replacement unsupported at this engine pin',
-            });
-            return;
-        }
-        if (admittedReplacements >= MAX_ADMITTED_REPLACEMENTS) {
-            operationIdContext.fresh(() => {
-                emitEvent({
-                    level: 'warn',
-                    event: 'broker.session_replacement.rejected',
-                    outcome: 'skipped',
-                    fields: {
-                        op,
-                        reason: 'capacity',
-                        admitted: MAX_ADMITTED_REPLACEMENTS,
-                        cap: MAX_ADMITTED_REPLACEMENTS,
-                    },
-                });
-            });
-            ackTo(client, op, false, `session replacement busy (${MAX_ADMITTED_REPLACEMENTS} active or queued)`);
-            return;
-        }
-        admittedReplacements++;
-        const task = replacementTail.then(async () => {
-            try {
-                // The whole attempt — success, cancellation, rejection, and timeout —
-                // executes inside one fresh operation scope so its outcome event (of
-                // whichever kind fires) carries one coherent operation id.
-                await operationIdContext.fresh(async () => {
-                    const startedAt = process.hrtime.bigint();
-                    let timer;
-                    try {
-                        const deadline = new Promise((resolve) => {
-                            timer = setTimeout(() => resolve(REPLACEMENT_DEADLINE_EXCEEDED), REPLACEMENT_DEADLINE_MS);
-                        });
-                        const outcome = await Promise.race([run(runtime), deadline]);
-                        if (outcome === REPLACEMENT_DEADLINE_EXCEEDED) {
-                            emitEvent({
-                                level: 'error',
-                                event: 'broker.session_replacement.timed_out',
-                                outcome: 'failed',
-                                duration_ms: Number(process.hrtime.bigint() - startedAt) / 1_000_000,
-                                fields: { op, deadline_ms: REPLACEMENT_DEADLINE_MS, mutation_outcome: 'indeterminate' },
-                            });
-                            ackTo(client, op, false, 'session replacement timed out; broker restarting because session state is indeterminate');
-                            disposeAndExit('session-replacement-timeout', 1);
-                            return;
-                        }
-                        if (!outcome.cancelled)
-                            reWelcomeAll();
-                        ackTo(client, op, !outcome.cancelled, outcome.cancelled ? outcome.detail ?? 'cancelled by extension' : undefined);
-                    }
-                    catch (err) {
-                        emitEvent({
-                            level: 'error',
-                            event: 'broker.session_replacement.failed',
-                            outcome: 'failed',
-                            error: err,
-                            fields: { op, mutation_outcome: 'indeterminate' },
-                        });
-                        ackTo(client, op, false, 'session replacement failed; broker restarting because session state is indeterminate');
-                        disposeAndExit('session-replacement-failed', 1);
-                    }
-                    finally {
-                        clearTimeout(timer);
-                    }
-                });
-            }
-            finally {
-                admittedReplacements--;
-            }
-        });
-        replacementTail = task.catch(() => undefined);
-    };
-    const handleFrame = (client, frame) => {
-        switch (frame.type) {
-            case 'hello': {
-                // 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: N terminal panes and browser tabs 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)
-                    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);
-                break;
-            }
-            case 'prompt':
-            case 'steer':
-            case 'follow_up':
-            case 'abort':
-            case 'bash': {
-                if (notWritable(client, 'drive the engine'))
-                    break;
-                driveEngine(client, frame);
-                break;
-            }
-            case 'deliver': {
-                // 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: `session.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))
-                    break;
-                const via = session.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();
-                    break;
-                }
-                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);
-                });
-                break;
-            }
-            case 'extension_ui_response': {
-                if (notWritable(client, 'answer dialogs'))
-                    break;
-                // 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);
-                break;
-            }
-            // --- 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) {
-                    sendFrame(client, {
-                        type: 'error',
-                        code: 'engine_error',
-                        message: `no model matching '${frame.model}' in the registry`,
-                    });
-                    break;
-                }
-                void session
-                    .setModel(model)
-                    .then(() => {
-                    // The caller's explicit `:thinking` wins; else the ladder cell's.
-                    const thinking = requested.thinkingLevel ?? normalized.thinkingLevel;
-                    if (thinking !== undefined)
-                        session.setThinkingLevel(thinking);
-                    ackTo(client, 'set_model');
-                    // 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.
-                    broadcastModelChanged(true, frame.pinned !== undefined ? frame.pinned : isProviderPinnedModelToken(frame.model), true);
-                })
-                    .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
-                // session (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 session
-                    .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 session
-                    .cycleModel(frame.direction)
-                    .then(() => {
-                    ackTo(client, 'cycle_model');
-                    broadcastModelChanged(true, undefined, true);
-                })
-                    .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-session 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(services);
-                        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(session.model, session.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) {
-                    sendFrame(client, {
-                        type: 'error',
-                        code: 'engine_error',
-                        message: `ladder model '${nextSpec.modelSpec}' not in the registry`,
-                    });
-                    break;
-                }
-                void session
-                    .setModel(ladderModel)
-                    .then(() => {
-                    if (nextSpec.thinkingLevel !== undefined)
-                        session.setThinkingLevel(nextSpec.thinkingLevel);
-                    ackTo(client, 'cycle_ladder');
-                    broadcastModelChanged(true, undefined, true);
-                })
-                    .catch(engineErrorTo(client));
-                break;
-            }
-            case 'cycle_thinking': {
-                if (notWritable(client, 'cycle the thinking level'))
-                    break;
-                try {
-                    session.cycleThinkingLevel();
-                    persistModelChoice(undefined, true);
-                    ackTo(client, 'cycle_thinking');
-                }
-                catch (err) {
-                    engineErrorTo(client)(err);
-                }
-                break;
-            }
-            case 'dequeue': {
-                if (notWritable(client, 'dequeue messages', frame.id))
-                    break;
-                try {
-                    const { steering, followUp } = session.clearQueue();
-                    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;
-                try {
-                    session.setThinkingLevel(frame.level);
-                    persistModelChoice(undefined, true);
-                    ackTo(client, 'set_thinking_level');
-                }
-                catch (err) {
-                    engineErrorTo(client)(err);
-                }
-                break;
-            }
-            case 'set_auto_retry': {
-                if (notWritable(client, 'set auto-retry'))
-                    break;
-                try {
-                    session.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 {
-                    session.setAutoCompactionEnabled(frame.enabled);
-                    ackTo(client, 'set_auto_compaction');
-                }
-                catch (err) {
-                    engineErrorTo(client)(err);
-                }
-                break;
-            }
-            case 'compact': {
-                if (notWritable(client, 'compact the session'))
-                    break;
-                void session
-                    .compact(frame.instructions)
-                    .then(() => ackTo(client, 'compact'))
-                    .catch(engineErrorTo(client));
-                break;
-            }
-            case 'set_session_name': {
-                if (notWritable(client, 'rename the session'))
-                    break;
-                try {
-                    session.setSessionName(frame.name);
-                    ackTo(client, 'set_session_name');
-                }
-                catch (err) {
-                    engineErrorTo(client)(err);
-                }
-                break;
-            }
-            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. The web bridge fetches it on
-                // its observer-by-default upstream connection to populate the 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()));
-                }
-                catch (err) {
-                    engineErrorTo(client)(err);
-                }
-                break;
-            }
-            // --- read-op picker data (§5 Unit A) ----------------------------------
-            // NOT controller-gated: read-only, like get_commands. The web bridge's
-            // observer connection populates pickers through these too.
-            case 'list_models': {
-                try {
-                    sendFrame(client, buildListModelsData(frame.id));
-                }
-                catch (err) {
-                    engineErrorTo(client, frame.id)(err);
-                }
-                break;
-            }
-            case 'list_scoped_models': {
-                try {
-                    sendFrame(client, buildScopedModelsData(frame.id));
-                }
-                catch (err) {
-                    engineErrorTo(client, frame.id)(err);
-                }
-                break;
-            }
-            case 'list_memory_refs': {
-                try {
-                    sendFrame(client, buildListMemoryRefsData(frame.id));
-                }
-                catch (err) {
-                    engineErrorTo(client, frame.id)(err);
-                }
-                break;
-            }
-            case 'get_tree': {
-                try {
-                    sendFrame(client, buildGetTreeData(frame.id));
-                }
-                catch (err) {
-                    engineErrorTo(client, frame.id)(err);
-                }
-                break;
-            }
-            case 'get_settings': {
-                try {
-                    sendFrame(client, buildSettingsData(frame.id));
-                }
-                catch (err) {
-                    engineErrorTo(client, frame.id)(err);
-                }
-                break;
-            }
-            case 'list_sessions': {
-                // Session listing reads the session 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')
-                    .then((d) => 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 = session.sessionManager;
-                    const sourceFile = sm.getSessionFile();
-                    const leafId = sm.getLeafId();
-                    if (sourceFile === undefined || sourceFile === '' || leafId === null) {
-                        engineErrorTo(client, frame.id)(new Error('no persisted source session leaf'));
-                        break;
-                    }
-                    sendFrame(client, {
-                        type: 'data',
-                        id: frame.id,
-                        kind: 'human_fork_coordinates',
-                        sourceFile,
-                        sourceSessionId: sm.getSessionId(),
-                        leafId,
-                        modelSpec: formatExactModelSpec(session.model, session.thinkingLevel),
-                    });
-                }
-                catch (err) {
-                    engineErrorTo(client, frame.id)(err);
-                }
-                break;
-            }
-            case 'navigate_tree': {
-                if (notWritable(client, 'navigate the session tree'))
-                    break;
-                if (isPreBoundaryReviewEntry(frame.targetId)) {
-                    reviewBoundaryRefusalTo(client, frame.targetId);
-                    break;
-                }
-                // navigateTree rewinds IN-PLACE (same session file, new leaf) and emits no
-                // relayed event, so every viewer must be re-snapshotted onto the rewound
-                // transcript — same reWelcomeAll the session-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 session
-                    .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 session
-                    .reload()
-                    .then(() => {
-                    memoizedRefInventory = null;
-                    clearSessionCache();
-                    ackTo(client, 'reload');
-                })
-                    .catch(engineErrorTo(client));
-                break;
-            }
-            case 'export': {
-                if (notWritable(client, 'export the session'))
-                    break;
-                if (frame.format === 'jsonl') {
-                    try {
-                        const outPath = session.exportToJsonl(frame.path);
-                        stripHiddenEntriesFromJsonlExport(outPath);
-                        ackTo(client, 'export');
-                    }
-                    catch (err) {
-                        engineErrorTo(client)(err);
-                    }
-                }
-                else {
-                    void session
-                        .exportToHtml(frame.path)
-                        .then(() => ackTo(client, 'export'))
-                        .catch(engineErrorTo(client));
-                }
-                break;
-            }
-            case 'new_session': {
-                if (notWritable(client, 'start a new session'))
-                    break;
-                runReplacement(client, 'new_session', (rt) => rt.newSession());
-                break;
-            }
-            case 'switch_session': {
-                if (notWritable(client, 'switch sessions'))
-                    break;
-                runReplacement(client, 'switch_session', (rt) => rt.switchSession(frame.path));
-                break;
-            }
-            case 'fork': {
-                if (notWritable(client, 'fork the session'))
-                    break;
-                if (isPreBoundaryReviewEntry(frame.entryId)) {
-                    reviewBoundaryRefusalTo(client, frame.entryId);
-                    break;
-                }
-                runReplacement(client, 'fork', (rt) => rt.fork(frame.entryId));
-                break;
-            }
-            case 'clone': {
-                if (notWritable(client, 'clone the session'))
-                    break;
-                runReplacement(client, 'clone', async (rt) => {
-                    const sm = session.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 session'))
-                    break;
-                const tmpPath = join(tmpdir(), `pi-share-${Date.now()}.html`);
-                void session.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;
-            }
-            case 'reload_auth': {
-                // 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 = installedGeneration;
-                    const existingAuthReload = reloadAuthInFlight;
-                    let authReloadPromise;
-                    if (existingAuthReload !== null && existingAuthReload.generation === authGeneration) {
-                        authReloadPromise = existingAuthReload.promise;
-                    }
-                    if (authGeneration !== undefined && authReloadPromise === undefined) {
-                        const authSession = session;
-                        const authServices = services;
-                        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 (installedGeneration !== authGeneration || session !== 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 (installedGeneration !== authGeneration || session !== 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 (installedGeneration !== authGeneration || session !== authSession)
-                                            return;
-                                        authSession.setThinkingLevel((resolved.thinkingLevel ?? 'off'));
-                                    }
-                                }
-                            }
-                            if (installedGeneration !== authGeneration || session !== authSession)
-                                return;
-                            // Persist an algorithmic route choice without clearing the logical
-                            // intent that makes future reconciliation possible.
-                            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 = installedGeneration;
-                    const authFaultSession = session;
-                    if (authFault?.link === 'pi→provider'
-                        && authFault.kind === 'auth'
-                        && !authFaultSession.isStreaming
-                        && !authFaultRedriveInFlight) {
-                        authFaultRedriveInFlight = true;
-                        void (async () => {
-                            try {
-                                if (authReloadPromise !== undefined)
-                                    await authReloadPromise;
-                                if (installedGeneration !== authFaultGeneration || session !== authFaultSession)
-                                    return;
-                                const anchorEntryId = authFault.anchorEntryId;
-                                if (anchorEntryId !== undefined) {
-                                    try {
-                                        const leafId = authFaultSession.sessionManager.getLeafId?.() ?? null;
-                                        if (leafId !== anchorEntryId)
-                                            await authFaultSession.navigateTree(anchorEntryId);
-                                        if (installedGeneration !== authFaultGeneration || session !== authFaultSession)
-                                            return;
-                                    }
-                                    catch (err) {
-                                        emitEvent({ level: 'warn', event: 'broker.auth_fault.rewind_skipped', error: err });
-                                    }
-                                }
-                                const fresh = readFault(nodeId);
-                                if (installedGeneration !== authFaultGeneration
-                                    || session !== 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);
-                }
-                break;
-            }
-            case 'bye':
-                client.socket.end();
-                break;
-            case 'shutdown':
-                disposeAndExit('shutdown-frame');
-                break;
-        }
-    };
-    // -------------------------------------------------------------------------
-    // 4 (plan): the socket listener — unlink any stale socket first.
-    // -------------------------------------------------------------------------
-    try {
-        if (existsSync(sockPath))
-            unlinkSync(sockPath);
-    }
-    catch {
-        /* a fresh listen below will surface a real problem */
-    }
-    server = createServer((socket) => {
-        const client = {
-            id: '',
-            role: 'observer',
-            socket,
-            decoder: new FrameDecoder(BROKER_READ_CAPS),
-            helloed: false,
-            pendingBytes: 0,
-            queuedFrames: 0,
-        };
-        clients.add(client);
-        socket.on('data', (chunk) => {
-            let frames;
-            try {
-                frames = client.decoder.push(chunk);
-            }
-            catch (err) {
-                // G7: a client frame over the bounded decoder caps (FrameOverflowError) is
-                // cap-and-dropped — best-effort error frame, then destroy the peer. The
-                // broker survives. The try/catch is around push() itself (not just the
-                // per-frame loop) because push() throws BEFORE returning any frames.
-                if (err instanceof FrameOverflowError) {
-                    sendFrame(client, { type: 'error', code: 'frame_overflow', message: err.message });
-                    dropClient(client, `frame overflow: ${err.message}`);
-                }
-                else {
-                    dropClient(client, `decoder error: ${String(err)}`);
-                }
-                return;
+                return;
             }
             for (const raw of frames) {
                 try {
-                    handleFrame(client, raw);
+                    handleFrame(frameDispatch, client, raw);
                 }
                 catch {
                     /* one bad frame never crashes the broker */
@@ -3336,8 +548,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
             }
         });
         const drop = () => {
-            clients.delete(client);
-            persistAttachState(); // a viewer disconnected
+            registry.removeClient(client); // a viewer disconnected
             // A writable client detaching does NOT cancel in-flight dialogs — they stay
             // pending under the broker-side default timeout, so a peer that is still
             // attached (or one that attaches next and gets the replay) can still answer.
@@ -3366,13 +577,12 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
         // reload_auth re-drive resolves a model, at which point it fires. For the
         // common model-present path this fires immediately — unchanged behavior.
         if (cfg.firstPrompt !== undefined && cfg.firstPrompt !== '') {
-            kickoffPending = cfg.firstPrompt;
-            drivePendingKickoff();
+            frameDispatch.kickoff(cfg.firstPrompt);
         }
     });
     // Initialize presence to the truthful zero state at boot — this also
     // overwrites a stale attach.json a crashed prior incarnation left behind.
-    persistAttachState();
+    registry.persistAttachState();
     // A daemon fleet bounce gives a busy Pi a short, bounded chance to persist
     // its aborted turn before teardown. `session.abort()` resolves only after Pi
     // reaches idle (and thus after its message_end persistence); only then may we
@@ -3385,23 +595,23 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
         if (disposed || signalExitInFlight)
             return;
         signalExitInFlight = true;
-        const busy = agentRunActive || session.isStreaming || pendingPromptDispatches > 0;
+        const busy = rebind.isAgentRunActive() || rebind.session().isStreaming || frameDispatch.pendingPromptDispatches() > 0;
         if (busy) {
             const deadline = Date.now() + ABORT_BEFORE_EXIT_MS;
             // prompt() has a real async pre-turn window where abort() silently no-ops.
             // Wait only within the daemon's fixed teardown budget for it to become
             // abortable. A still-pending setup is deliberately marked dirty below so
             // recovery starts a cycle instead of silently losing the prompt on resume.
-            while (pendingPromptDispatches > 0 && !session.isStreaming && Date.now() < deadline) {
+            while (frameDispatch.pendingPromptDispatches() > 0 && !rebind.session().isStreaming && Date.now() < deadline) {
                 await new Promise((resolve) => setTimeout(resolve, 25));
             }
-            if (session.isStreaming) {
+            if (rebind.session().isStreaming) {
                 const remaining = deadline - Date.now();
                 if (remaining > 0) {
                     let timer;
                     try {
                         const settled = await Promise.race([
-                            session.abort().then(() => true, () => false),
+                            rebind.session().abort().then(() => true, () => false),
                             new Promise((resolve) => { timer = setTimeout(() => resolve(false), remaining); }),
                         ]);
                         if (settled)
@@ -3413,7 +623,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
                     }
                 }
             }
-            else if (pendingPromptDispatches > 0 || agentRunActive) {
+            else if (frameDispatch.pendingPromptDispatches() > 0 || rebind.isAgentRunActive()) {
                 // The engine never reached an abortable persisted turn in the budget.
                 // Preserve the existing dirty-death recovery cycle rather than certifying
                 // a session that may not contain the prompt it was preparing.
@@ -3475,10 +685,17 @@ async function resolveLaunchModel(services, cfg) {
     const routeRequest = modelRequestFromConfig(cfg.model, process.env['CRTR_MODEL_INTENT'], cfg.modelExact === true);
     if (routeRequest === undefined)
         return undefined;
-    const selection = selectInitialModelRoute(routeRequest, registryOf(services), {
+    const registry = registryOf(services);
+    const routeOptions = {
         cwd: process.env['CRTR_NODE_CWD'] ?? cfg.cwd,
         profileId: process.env['CRTR_PROFILE_ID'],
-    });
+    };
+    const unknown = unregisteredConcreteModel(routeRequest, registry, routeOptions);
+    if (unknown !== undefined) {
+        recordFaultForCurrentNode({ link: 'crtr→pi', op: 'model resolution at launch', kind: 'model-not-found', retry: { disposition: 'fatal' }, message: `model '${unknown.request.spec}' is not registered in the serving model registry` });
+        throw new Error(`[broker] FATAL: model '${unknown.request.spec}' is not registered in the serving model registry`);
+    }
+    const selection = selectInitialModelRoute(routeRequest, registry, routeOptions);
     const selected = selection.selected;
     if (selected !== undefined) {
         const candidate = selected.candidate;