@north-light/crouter 0.3.154

package/dist/core/runtime/broker.js

@@ -0,0 +1,3711 @@
+// broker.ts — the headless node broker (design §4, §5; plan T4).
+//
+// One broker process per node — the SOLE host. It hosts ONE pi engine IN-PROCESS
+// via the SDK (createAgentSession), is the SOLE writer of the node's session
+// `.jsonl`, listens on `nodeDir(id)/view.sock`, fans the single engine event
+// stream out to N viewers, serializes the drive commands of EVERY writable
+// viewer through one frame loop, and fans blocking extension dialogs out to all
+// of them (first answer wins). The engine has no terminal of its own; a
+// tmux pane (or web tab) is only a viewer of this socket. It
+// runs one turn-cycle and, when the engine settles (the stophook calls
+// ctx.shutdown(), or the engine goes idle), disposes the engine and exits 0 —
+// the daemon then routes revival per the intent the bound stophook set.
+//
+// Engine resolution flows through broker-sdk.ts (`loadBrokerEngine`) so the T11
+// `CRTR_BROKER_ENGINE` test seam can swap a fake engine in. The resource loader
+// + model registry are real SDK construction helpers (NOT part of the swappable
+// 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 { 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 { 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 { 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, equivalentOtherProviderModel, isProviderPinnedModelToken, nextLadderModel, normalizeModel, 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, MANAGED_PROVIDER_ROTATION_POLICY_UI, } from './managed-provider-cooling.js';
+import { AUTH_FAULT_RECOVERY_BODY, CONNECTION_FAULT_RECOVERY_BODY, PROVIDER_FAULT_RECOVERY_BODY } from './fault-recovery-nudge.js';
+import { markFatalOnExhaust, nextFaultRetry, policyFor } from './fault-recovery.js';
+import { probeOnline as probeOnlineReal } from './connectivity.js';
+import { CRTR_CYCLE_CUSTOM_TYPE, cycleAwareMessages } from './session-cycles.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 { clearPreferredModel, isManagedProvider, readRotationConfig, readSubscriptionPool, rememberPreferredModel, resolveProviderCandidates } from '../subscription-state.js';
+import { encodeFrame, FrameDecoder, FrameOverflowError, BROKER_READ_CAPS, } from './broker-protocol.js';
+const THINKING_LEVELS = new Set(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
+/**
+ * pi 0.82 made `ModelRuntime` the canonical model/auth surface and demoted
+ * `ModelRegistry` to the synchronous facade over it (`find`/`getAll`/
+ * `getAvailable`/`hasConfiguredAuth` off the runtime's snapshot). The broker's
+ * model policy is synchronous throughout, so every read goes through this
+ * facade; it is a thin wrapper over the LIVE runtime, so constructing one per
+ * call reads current state rather than a captured view.
+ */
+function registryOf(services) {
+    return new ModelRegistry(services.modelRuntime);
+}
+/** The auth.json/models.json pair backing one agent dir's model runtime. */
+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;
+}
+/**
+ * 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;
+    const suffix = thinkingLevel !== undefined && thinkingLevel !== '' && thinkingLevel !== 'off' ? `:${thinkingLevel}` : '';
+    return `${model.provider}/${model.id}${suffix}`;
+}
+/** The ask-time fork recipe requires an explicit thinking level: `:off` is a
+ * real captured choice, not an omitted default that a future runtime may infer
+ * differently. */
+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
+ *  one) so unanswered dialogs — including ones whose writable viewers all detach
+ *  — 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');
+// ---------------------------------------------------------------------------
+// M3 (scout mq5thyli): the active engine session, exposed so broker-cli's FATAL
+// handlers (uncaughtException / unhandledRejection / the runBroker reject) can
+// dispose it before process.exit. The bash tool spawns children `detached` (own
+// pgid); only session.dispose() (→ abortBash / agent.abort → killProcessTree)
+// reaps them. The graceful exit path already disposes; without this the crash
+// path would `process.exit(1)` and ORPHAN every in-flight bash subprocess.
+// ---------------------------------------------------------------------------
+let activeSession = null;
+/** Dispose the live engine session if one exists (idempotent). Called by
+ *  broker-cli's fatal handlers before exit so a crash never orphans detached
+ *  bash children. No-op before the session is built or after a clean dispose. */
+export function disposeActiveSession() {
+    const s = activeSession;
+    activeSession = null;
+    if (s !== null) {
+        try {
+            s.dispose();
+        }
+        catch {
+            /* dispose must not block the fatal exit */
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// runBroker — the broker process body (plan T4 steps 1–6)
+// ---------------------------------------------------------------------------
+export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), startupTs = new Date().toISOString()) {
+    // A clean-abort certificate belongs only to the dead broker that wrote it.
+    // Fleet classification consumes it before launching this successor.
+    clearCleanAbort(nodeId);
+    // The canonical broker event source (job/log.jsonl) is bound before any other
+    // work in this function — no path/env/state setup may precede it, and the
+    // binder independently validates nodeId before constructing that path.
+    bindBrokerEventSource(nodeId);
+    // One low-volume, node-correlated boot trace. It deliberately carries only
+    // timing and runtime identity — never prompts, commands, tokens, or secrets.
+    // broker-cli captures startupAt/startupTs before dynamically loading this
+    // module, so module_loaded's elapsed value includes the cold broker import
+    // graph, and cli_entry carries the exact process-spawn wall-clock time.
+    operationIdContext.fresh(() => {
+        emitEvent({
+            level: 'info',
+            event: 'broker.startup.cli_entry',
+            ts: startupTs,
+            duration_ms: 0,
+            fields: { runtime_version: process.version, engine_version: null, model: null },
+        });
+        emitEvent({
+            level: 'info',
+            event: 'broker.startup.module_loaded',
+            duration_ms: Number(process.hrtime.bigint() - startupAt) / 1_000_000,
+            fields: { runtime_version: process.version, engine_version: null, model: null },
+        });
+    });
+    // Structured, duplicate-suppressed startup milestones reached only once the
+    // engine is streaming a turn. `engineVersion` is populated below once
+    // assertEngineVersion resolves it; the milestones fire well after that.
+    const markedStartupEvents = new Set();
+    let engineVersion = null;
+    const emitStartupMilestone = (event, model = null) => {
+        if (markedStartupEvents.has(event))
+            return;
+        markedStartupEvents.add(event);
+        // Under CRTR_TIMING the same milestone also lands on the cross-process
+        // front-door timeline (stderr → this broker's broker.log), so it can be
+        // read next to the cli/viewer markers instead of only in the job log.
+        mark(event, { duration_ms: Number(process.hrtime.bigint() - startupAt) / 1_000_000 });
+        emitEvent({
+            level: 'info',
+            event,
+            duration_ms: Number(process.hrtime.bigint() - startupAt) / 1_000_000,
+            fields: { runtime_version: process.version, engine_version: engineVersion, model },
+        });
+    };
+    // Defensive: any `crtr` child the engine/extensions spawn must inherit the
+    // front-door recursion guard (runtime/CLAUDE.md fork-bomb invariant). The host
+    // (T6) also sets this; we set it again so the broker is self-sufficient.
+    process.env[FRONT_DOOR_ENV] = '1';
+    // A successful in-turn crtr command stamps this process id into its stop
+    // signal, so a crash-revived broker cannot consume a prior broker's outcome.
+    process.env['CRTR_BROKER_PID'] = String(process.pid);
+    // The broker is PANELESS and detached, but a broker spawned by a tmux-resident
+    // parent inherits the parent's TMUX_PANE/TMUX in its env (the launcher spawns
+    // with {...process.env}). Left in place, every `crtr` command the engine runs
+    // (bash tool, goal-capture naming, a child spawn) would resolve `currentTmux()`
+    // to the PARENT's pane/session and act there — e.g. open viewers beside, or
+    // close, the parent's pane. Strip both so this broker's children see no tmux
+    // context and take their paneless path.
+    delete process.env['TMUX_PANE'];
+    delete process.env['TMUX'];
+    // 1. Version tripwire + load the launch recipe the host serialized.
+    const engine = await loadBrokerEngine();
+    assertEngineVersion(engine.VERSION);
+    engineVersion = engine.VERSION;
+    // M4 / M6 (scout mq5thyli) — DELIBERATELY SKIPPED on the 0.78.1 pin. Both
+    // `configureHttpDispatcher` (M4: proxy support + the undici decompression fix)
+    // and `runMigrations` (M6: config/auth migration for a box where the pi CLI
+    // never ran) are CLI-only helpers that the pinned SDK does NOT re-export: the
+    // package's `exports` map is `.`-only, neither symbol is in `dist/index.d.ts`,
+    // a deep import (`.../dist/core/http-dispatcher.js`) is blocked with
+    // ERR_PACKAGE_PATH_NOT_EXPORTED, and the only exports-map entries are `.` and
+    // `./hooks` (neither carries these symbols). Per the "verify export; skip-with-
+    // note if absent" directive we do not vendor or reach around the export wall.
+    // Revisit when the SDK pin bumps to a version that re-exports them publicly.
+    const dir = nodeDir(nodeId);
+    const launchFile = join(dir, 'broker-launch.json');
+    const inv = JSON.parse(readFileSync(launchFile, 'utf8'));
+    const cfg = piInvocationToSdkConfig(inv); // also merges inv.env
+    // 2–4. Build the engine session via the SERVICES path (C3) — see
+    //       buildBrokerSession below. Register it so the FATAL exit path (M3) can
+    //       dispose it and reap detached bash children.
+    // `session` + `services` are MUTABLE holders (T3 session-rebind): when the
+    // controller drives new_session/switch_session/fork, the AgentSessionRuntime
+    // tears down the old session and builds the next one, then runs our rebind
+    // callback which reassigns these. Every closure below (buildSnapshot,
+    // driveEngine, handleFrame, disposeAndExit) reads through them, so they all
+    // follow the live session automatically. `runtime` is undefined for an engine
+    // that does not expose the replacement API (the fake-engine fixture).
+    // eslint-disable-next-line prefer-const
+    let { session, services, resuming, runtime } = await buildBrokerSession(engine, cfg);
+    // 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();
+    // 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
+    // extension hook that reads `ctx.ui.theme` throws "Theme not initialized" —
+    // and the extension runner SILENTLY swallows that throw and discards the
+    // hook's returned payload. The visible symptom was the OAuth billing adapter's
+    // before_provider_request handler throwing, so its injected Claude-Code billing
+    // header was dropped and subscription turns 400'd ("draws from extra usage").
+    // headless ⇒ no file watcher (false). Idempotent global; call once at boot.
+    // Always replace an inherited PI_PACKAGE_DIR: a viewer launched from a pnpm
+    // path may pass its `.pnpm` package copy down to the daemon/broker, but that
+    // copy can omit the JSON theme assets. The broker must use crouter's actual
+    // bundled package root, exactly like its incidental pi subprocesses.
+    try {
+        process.env['PI_PACKAGE_DIR'] = resolveBundledPiPackageDir();
+        initTheme(services.settingsManager.getTheme(), false);
+    }
+    catch (err) {
+        emitEvent({
+            level: 'error',
+            event: 'broker.theme.initialization_failed',
+            error: err,
+        });
+    }
+    // Diagnose stale local-path pi packages without persisting the human-facing
+    // formatter's prose. The front door retains that actionable presentation.
+    try {
+        for (const missing of findMissingPackagePaths(getAgentDir())) {
+            emitEvent({
+                level: 'warn',
+                event: 'broker.startup.warning',
+                fields: {
+                    stage: 'package_health',
+                    source: missing.source,
+                    resolved_path: missing.resolved,
+                },
+            });
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+    // N3: the node's display name is re-applied by the rebind lane below so it
+    // survives a session replacement (new_session/switch_session/fork), not only at
+    // boot.
+    // -------------------------------------------------------------------------
+    // Socket fan-out state
+    // -------------------------------------------------------------------------
+    const sockPath = viewSocketPath(nodeId);
+    const attachPath = join(jobDir(nodeId), 'attach.json');
+    const clients = new Set();
+    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 disposed = 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);
+        }
+        return out;
+    };
+    // 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 */
+        }
+    };
+    // 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}` },
+        });
+        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)`);
+            return;
+        }
+        client.queuedFrames += 1;
+        client.pendingBytes += bytes;
+        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;
+            });
+        }
+        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);
+    };
+    // ---------------------------------------------------------------------------
+    // 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 failedRetryProviders = 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;
+    // Guards the reload_auth re-drive (below) against overlapping /login frames
+    // re-running resolveLaunchModel + setModel + kickoff concurrently; the
+    // reload/refresh/ack/broadcast ahead of it stay idempotent and always run.
+    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 (cfg.modelExact) locks the session to the single
+        // captured model — never cross-provider-retry, not even the
+        // modelProviderPinned restore-toward-pin exception below. Unavailability
+        // must fail the turn, not substitute a different model.
+        if (cfg.modelExact === true)
+            return;
+        const currentSpec = formatModelSpec(session.model, session.thinkingLevel);
+        if (currentSpec === null)
+            return;
+        const next = equivalentOtherProviderModel(currentSpec, failedRetryProviders);
+        if (next === null)
+            return;
+        // An explicit provider pin forbids turn-time rotation AWAY to another
+        // provider — EXCEPT a switch back TOWARD the recorded restoration pin (a
+        // launch that fell back off a cooling pinned provider records the requested
+        // managed model). Restoring to the pinned provider honors the pin rather
+        // than violating it; every other rotation stays suppressed.
+        if (cfg.modelProviderPinned === true) {
+            const pin = readRotationConfig().preferredModel;
+            const targetSpec = parseModelSpec(next.model).modelSpec;
+            const targetProvider = targetSpec.slice(0, targetSpec.indexOf('/'));
+            const targetId = targetSpec.slice(targetSpec.indexOf('/') + 1);
+            if (pin?.providerId !== targetProvider || pin.modelId !== targetId)
+                return;
+        }
+        const fallbackPromise = (async () => {
+            const requestedSpec = parseModelSpec(next.model).modelSpec;
+            const slash = requestedSpec.indexOf('/');
+            const model = slash > 0
+                ? registryOf(candidateServices).find(requestedSpec.slice(0, slash), requestedSpec.slice(slash + 1))
+                : undefined;
+            const requested = parseModelSpec(next.model);
+            const pool = isManagedProvider(requested.modelSpec.slice(0, requested.modelSpec.indexOf('/')))
+                ? readSubscriptionPool(requested.modelSpec.slice(0, requested.modelSpec.indexOf('/')))
+                : [];
+            const resolved = resolveProviderCandidates([{
+                    providerId: requested.modelSpec.slice(0, requested.modelSpec.indexOf('/')),
+                    modelId: requested.modelSpec.slice(requested.modelSpec.indexOf('/') + 1),
+                    thinkingLevel: requested.thinkingLevel,
+                    registered: model !== undefined,
+                    authenticated: model !== undefined && (isManagedProvider(requested.modelSpec.slice(0, requested.modelSpec.indexOf('/')))
+                        ? pool.length > 0
+                        : registryOf(candidateServices).hasConfiguredAuth(model)),
+                    coolingUntil: pool.length > 0 && pool.every((entry) => (entry.rateLimitedUntil || 0) > Date.now())
+                        ? Math.min(...pool.map((entry) => entry.rateLimitedUntil || 0))
+                        : undefined,
+                }]);
+            if (resolved.candidates.length === 0 || model === undefined) {
+                emitEvent({
+                    level: 'debug',
+                    event: 'broker.runtime.diagnostic',
+                    fields: { message: `provider fallback skipped: ${next.model} is ${resolved.rejected[0]?.reason ?? 'unavailable'}` },
+                });
+                return;
+            }
+            // Snapshot the restoration intent before the asynchronous model change;
+            // this retry must not replace a launch-recorded requested pin.
+            const preferred = readRotationConfig().preferredModel;
+            await candidateSession.setModel(model);
+            if (installedGeneration !== generation || session !== candidateSession)
+                return;
+            if (requested.thinkingLevel !== undefined)
+                candidateSession.setThinkingLevel(requested.thinkingLevel);
+            const currentProvider = currentSpec.slice(0, currentSpec.indexOf('/'));
+            const currentModelId = parseModelSpec(currentSpec).modelSpec.slice(currentSpec.indexOf('/') + 1);
+            // A launch fallback already records its requested managed model as the
+            // restoration pin. Keep that intent through turn-time retries; reaching
+            // it makes the temporary pin fulfilled. A normal retry has no such pin,
+            // so retain the failed managed model for provider-rotation to restore.
+            const switchedProvider = requested.modelSpec.slice(0, requested.modelSpec.indexOf('/'));
+            const switchedModelId = requested.modelSpec.slice(switchedProvider.length + 1);
+            if (preferred?.providerId === switchedProvider && preferred.modelId === switchedModelId) {
+                clearPreferredModel();
+            }
+            else if (preferred === undefined && isManagedProvider(currentProvider)) {
+                rememberPreferredModel({ providerId: currentProvider, modelId: currentModelId });
+            }
+            failedRetryProviders.add(next.fromProvider);
+            broadcastModelChanged(false);
+            emitEvent({
+                level: 'debug',
+                event: 'broker.runtime.diagnostic',
+                fields: { message: `provider fallback after ${kind}: ${currentSpec} → ${formatModelSpec(candidateSession.model, candidateSession.thinkingLevel) ?? next.model}` },
+            });
+        })()
+            .catch((err) => {
+            emitEvent({
+                level: 'debug',
+                event: 'broker.runtime.diagnostic',
+                fields: { message: `provider fallback failed: ${err instanceof Error ? err.message : String(err)}` },
+            });
+        })
+            .finally(() => {
+            if (installedGeneration === generation)
+                providerFallbackInFlight = null;
+        });
+        providerFallbackInFlight = fallbackPromise;
+    };
+    // A 404 not_found is NOT one of pi's auto-retried kinds (it retries 429/5xx
+    // only) and never resolves on its own — the configured model id is wrong or
+    // decommissioned (e.g. the default `anthropic/ultra` pointing at a model the
+    // account can't reach). Left alone the node errors out, the stophook parks it
+    // as a stall, and the daemon force-recycles it onto the SAME bad model in a
+    // loop. Instead: fail the node over to the strong-anthropic ladder model and
+    // re-drive the turn so the work continues. broadcastModelChanged persists the
+    // swap into the durable launch recipe, so a later revive uses the good model
+    // too. Fires on the terminal-error message (stopReason 'error'), the signal a
+    // non-retried request surfaces.
+    //
+    // The SAME treatment covers a provider whose credential could not be resolved
+    // (`Provider is not configured: <id>`). That error is classified `other`, i.e.
+    // fatal, so without this the node parks and every wake re-fails on the same
+    // unusable provider — the only escape being a human running `crtr node config
+    // --model`. Here it substitutes an equivalent model on the OTHER provider (the
+    // same ladder cell `maybeSwitchProviderForRetry` uses), proves that target is
+    // actually authenticated before switching, and re-drives.
+    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;
+        if (cfg.modelProviderPinned === true)
+            return;
+        // An exact-consult launch must fail closed on a 404 for its locked model,
+        // never auto-fail-over to the strong-anthropic ladder.
+        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;
+        notFoundModels.add(currentSpec);
+        // The strong-anthropic ladder cell — "whatever the current strong anthropic
+        // provider model is" (config modelLadders.anthropic.strong), not hardcoded.
+        // An unusable PROVIDER (as opposed to a missing model id) prefers the
+        // same-strength cell on the other provider, so a node keeps the capability
+        // it was launched with instead of being promoted or demoted by the swap.
+        const equivalent = unconfigured ? equivalentOtherProviderModel(currentSpec, failedRetryProviders)?.model : undefined;
+        const target = normalizeModel(equivalent ?? 'anthropic/strong');
+        // Don't loop: the failed model already IS the target, or the target itself
+        // 404'd earlier this session. Leave it to the normal stall/recycle path.
+        if (target === currentSpec || notFoundModels.has(target)) {
+            emitEvent({
+                level: 'debug',
+                event: 'broker.runtime.diagnostic',
+                fields: { message: `not_found fallback skipped: ${currentSpec} has no healthy strong-anthropic target (${target})` },
+            });
+            return;
+        }
+        const fallbackPromise = (async () => {
+            const targetSpec = parseModelSpec(target).modelSpec;
+            const slash = targetSpec.indexOf('/');
+            const model = slash > 0
+                ? registryOf(candidateServices).find(targetSpec.slice(0, slash), targetSpec.slice(slash + 1))
+                : undefined;
+            if (model === undefined) {
+                emitEvent({
+                    level: 'debug',
+                    event: 'broker.runtime.diagnostic',
+                    fields: { message: `${unconfigured ? 'unconfigured-provider' : 'not_found'} fallback skipped: ${target} is not registered` },
+                });
+                return;
+            }
+            // Swapping onto a second provider that ALSO has no credential would just
+            // repeat the fault under a different name, so prove this one resolves.
+            if (unconfigured && !registryOf(candidateServices).hasConfiguredAuth(model)) {
+                emitEvent({
+                    level: 'debug',
+                    event: 'broker.runtime.diagnostic',
+                    fields: { message: `unconfigured-provider fallback skipped: ${target} is not authenticated either` },
+                });
+                return;
+            }
+            const requested = parseModelSpec(target);
+            await candidateSession.setModel(model);
+            if (installedGeneration !== generation || session !== candidateSession)
+                return;
+            if (requested.thinkingLevel !== undefined)
+                candidateSession.setThinkingLevel(requested.thinkingLevel);
+            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(unconfigured
+                ? `The previous model (${currentSpec}) had no usable provider credential, so you were automatically switched to ${resolved}. Continue the task from where the failed turn left off.`
+                : `The previous model (${currentSpec}) was unavailable (provider 404 not_found), so you were automatically switched to ${resolved}. Continue the task from where the failed turn left off.`));
+        })()
+            .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') {
+            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 — then relay verbatim.
+        flushPendingUpdate();
+        broadcast(event);
+    };
+    // Persist a live model switch into the node's durable launch recipe so it
+    // survives a yield/revive. pi's `/model` (→ set_model/cycle_model) only
+    // mutates the in-memory engine; without this the node reverts to its
+    // persona/spawn model on the next revive. We write the full `provider/id`
+    // (which normalizeModel passes through unchanged) 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-pin decision for THIS model
+    // change — decided by the caller from the change's RAW pre-normalize token
+    // (an explicit set_model). Omitted — an algorithmic model change (cycle_model,
+    // cycle_ladder, a provider-fallback/not-found/cooling re-drive) — the existing
+    // pin is carried through UNCHANGED via the `meta.launch` spread, exactly as
+    // before: those changes never re-decide a pin the user didn't ask to change.
+    //
+    // `cfg.modelProviderPinned` is this broker's LIVE authoritative pin state —
+    // every in-process policy read (the retry-fallback gate, the model-not-found
+    // gate, and pinnedToFirst on a reload_auth re-drive) consults it directly, not
+    // the boot-time launch recipe. Mutate it here, synchronously, BEFORE the
+    // best-effort durable write below, so an explicit set_model takes effect for
+    // the very next policy decision even when the canvas row is unreachable
+    // (a degenerate/ephemeral node). Only ever reached from the success path of a
+    // completed `set_model` — never before the engine call it decided from has
+    // actually succeeded.
+    const persistModelChoice = (pinnedOverride) => {
+        if (pinnedOverride !== undefined)
+            cfg.modelProviderPinned = pinnedOverride;
+        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
+                ? { ...meta.launch, model: spec, ...(pinnedOverride !== undefined ? { modelProviderPinned: pinnedOverride } : {}) }
+                : undefined;
+            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) => {
+        if (persist)
+            persistModelChoice(pinnedOverride);
+        broadcast({ type: 'model_changed', model: isUnknownModel(session.model) ? undefined : session.model, spec: formatModelSpec(session.model, session.thinkingLevel) });
+    };
+    const buildSnapshot = () => ({
+        messages: snapshotMessages(session),
+        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,
+        },
+    });
+    // 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 disposeAndExit = (_reason, status = 0) => {
+        if (disposed)
+            return;
+        disposed = true;
+        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);
+    };
+    // 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,
+        providerRotationPolicy: () => cfg.modelExact === true
+            ? { allowCrossProviderFallback: false, reason: 'model-exact' }
+            : cfg.modelProviderPinned === true
+                ? { allowCrossProviderFallback: false, reason: 'provider-pinned' }
+                : { allowCrossProviderFallback: true },
+        // 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;
+                }
+            }
+            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;
+            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) });
+        };
+        // 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 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)));
+            }
+            case 'steer': {
+                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();
+                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 } : {}),
+    });
+    /** 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 forkPoints = session.getUserMessagesForForking().map((u) => ({
+            id: u.entryId,
+            text: u.text,
+            timestamp: sm.getEntry(u.entryId)?.timestamp,
+        }));
+        return {
+            type: 'data',
+            id,
+            kind: 'get_tree',
+            tree: sm.getTree(),
+            currentLeafId: sm.getLeafId(),
+            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));
+                })
+                    .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();
+                })
+                    .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();
+                })
+                    .catch(engineErrorTo(client));
+                break;
+            }
+            case 'cycle_thinking': {
+                if (notWritable(client, 'cycle the thinking level'))
+                    break;
+                try {
+                    session.cycleThinkingLevel();
+                    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);
+                    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;
+                // 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;
+                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 the shared auth.json + a model-registry refresh. It
+                // does NOT steer the conversation, so there is nothing to role-gate —
+                // which is what lets the daemon's canvas-wide fan (one /login propagated
+                // to every live broker) ride an observer connection.
+                try {
+                    // pi 0.82: crouter's CredentialStore reads auth.json fresh under the
+                    // lock on every call, so there is no cached credential view left to
+                    // reload — only the runtime's models/availability snapshot has to be
+                    // recomputed, and that is asynchronous. Every consumer below awaits
+                    // the same promise so none of them reads a pre-login snapshot.
+                    const authRefreshed = registryOf(services).refresh().catch((err) => {
+                        emitEvent({ level: 'warn', event: 'broker.auth_reload.refresh_failed', error: err });
+                    });
+                    ackTo(client, 'reload_auth');
+                    void authRefreshed.then(() => broadcastModelChanged());
+                    // Tier 3 re-drive: a model-less boot (no viable candidate at launch)
+                    // stays live so the user can /login; once auth actually changes,
+                    // re-run the SAME launch policy against the now-refreshed services
+                    // and, if a model now resolves, adopt it and fire the deferred
+                    // kickoff. handleFrame is not async (broker.ts) so this runs as a
+                    // detached IIFE, the same async-in-sync-switch pattern used above
+                    // for provider/not-found fallback.
+                    const authGeneration = installedGeneration;
+                    if (sessionHasNoModel() && authGeneration !== undefined && reloadAuthInFlight === null) {
+                        const authSession = session;
+                        const authServices = services;
+                        reloadAuthInFlight = authGeneration;
+                        void (async () => {
+                            try {
+                                await authRefreshed;
+                                const resolved = await resolveLaunchModel(authServices, cfg);
+                                if (resolved !== undefined) {
+                                    await authSession.setModel(resolved.model);
+                                    if (installedGeneration !== authGeneration || session !== authSession)
+                                        return;
+                                    if (resolved.thinkingLevel !== undefined)
+                                        authSession.setThinkingLevel(resolved.thinkingLevel);
+                                    broadcastModelChanged();
+                                    drivePendingKickoff();
+                                }
+                            }
+                            catch (err) {
+                                emitEvent({
+                                    level: 'error',
+                                    event: 'broker.auth_reload.redrive_failed',
+                                    error: err,
+                                });
+                            }
+                            finally {
+                                if (reloadAuthInFlight === authGeneration)
+                                    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 {
+                                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;
+            }
+            for (const raw of frames) {
+                try {
+                    handleFrame(client, raw);
+                }
+                catch {
+                    /* one bad frame never crashes the broker */
+                }
+            }
+        });
+        const drop = () => {
+            clients.delete(client);
+            persistAttachState(); // 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.
+            // Only an answer, the timeout, or an abort resolves one.
+        };
+        socket.on('close', drop);
+        socket.on('error', () => {
+            /* close follows; drop there */
+        });
+    });
+    server.on('error', (err) => {
+        // A recursive error raised during/after disposeAndExit's own server.close()
+        // (or any other exit already in flight) must not emit a second canonical
+        // failure or dispose twice.
+        if (disposed)
+            return;
+        emitEvent({ level: 'error', event: 'broker.socket.failed', error: err });
+        disposeAndExit('socket-error', 1);
+    });
+    server.listen(sockPath, () => {
+        // A launch prompt delivers only after the listener is accepting, so a
+        // root-spawn readiness proof and prompt admission share one boundary. This
+        // includes the one continuation carried by a clean runtime-abort resume.
+        // A model-less tier-3 boot (session.model === undefined) leaves the prompt
+        // pending in kickoffPending; drivePendingKickoff is a no-op until the
+        // 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();
+        }
+    });
+    // Initialize presence to the truthful zero state at boot — this also
+    // overwrites a stale attach.json a crashed prior incarnation left behind.
+    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
+    // leave the durable clean-abort certificate that changes recovery to resume.
+    // A timeout/rejection deliberately leaves no certificate, preserving dirty
+    // crash → recovery-cycle behavior and the fleet's shared SIGKILL deadline.
+    const ABORT_BEFORE_EXIT_MS = 2_500;
+    let signalExitInFlight = false;
+    const abortAndExit = async (reason) => {
+        if (disposed || signalExitInFlight)
+            return;
+        signalExitInFlight = true;
+        const busy = agentRunActive || session.isStreaming || 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) {
+                await new Promise((resolve) => setTimeout(resolve, 25));
+            }
+            if (session.isStreaming) {
+                const remaining = deadline - Date.now();
+                if (remaining > 0) {
+                    let timer;
+                    try {
+                        const settled = await Promise.race([
+                            session.abort().then(() => true, () => false),
+                            new Promise((resolve) => { timer = setTimeout(() => resolve(false), remaining); }),
+                        ]);
+                        if (settled)
+                            markCleanAbort(nodeId);
+                    }
+                    finally {
+                        if (timer !== undefined)
+                            clearTimeout(timer);
+                    }
+                }
+            }
+            else if (pendingPromptDispatches > 0 || agentRunActive) {
+                // 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.
+                markBusy(nodeId);
+            }
+        }
+        disposeAndExit(reason);
+    };
+    process.on('SIGTERM', () => { void abortAndExit('SIGTERM'); });
+    process.on('SIGINT', () => { void abortAndExit('SIGINT'); });
+}
+// ---------------------------------------------------------------------------
+// snapshotMessages — the catch-up snapshot's ordered message history.
+//
+// The broker is the SOLE writer of the node's session `.jsonl`, so the session
+// manager's persisted tree (`buildSessionContext`) is the canonical, complete,
+// ordered history — byte-identical to what a dormant reader (crouter-web's static
+// normalizer) reconstructs from the same file. We serve THAT, NOT the agent's
+// live `session.messages` (`agent.state.messages`), because pi's recovery paths
+// mutate the live array away from the persisted history: auto-retry, context-
+// overflow recovery, and compaction each SLICE the errored/superseded assistant
+// message out of `state.messages` while DELIBERATELY keeping it on disk ("keep in
+// session for history", agent-session.js). So `session.messages` can OMIT — or, via
+// branch/compaction reshaping, reorder — a turn the `.jsonl` still holds. Pre-
+// close that drift is invisible (the live stream and the live array agree); after
+// a revive the welcome snapshot built from the reloaded array would diverge from
+// the on-disk history a dormant viewer just saw. Reconstructing from the session
+// manager makes the live snapshot == the persisted history (single source of
+// truth); the relayed live stream then continues from there.
+//
+// `AgentSession.sessionManager` is a public readonly field of the real pi SDK; the
+// fake-engine test fixture mirrors the same `sessionManager.buildSessionContext()`
+// surface (plus, where present, the tree accessors `cycleAwareMessages` reads).
+// A refresh-yielded node keeps every prior cycle in the SAME `.jsonl` as sibling
+// branches (session-cycles.ts) — `cycleAwareMessages` replays them ahead of the
+// live cycle's context so the welcome snapshot renders one continuous
+// conversation instead of just the post-yield window; single-cycle sessions and
+// the fake-engine fixture (no tree accessors) fall through to plain
+// `buildSessionContext().messages` unchanged.
+export function snapshotMessages(session) {
+    // Cast: the real SDK's `SessionEntry.data` is `unknown` (untyped custom-entry
+    // payload), narrower than `CycleSessionManagerLike`'s structural read of the
+    // `crtr-cycle` marker's `{cycle, fromLeaf}` shape — the fields we read off it
+    // are ones ONLY this module's own `appendCustomEntry` call (above) ever writes.
+    return cycleAwareMessages(session.sessionManager);
+}
+// ---------------------------------------------------------------------------
+// resolveLaunchModel — the SOLE launch model-selection policy, module-scoped
+// so both buildForManager (initial boot, inside buildBrokerSession below) and
+// the reload_auth re-drive (inside runBroker, a DIFFERENT function scope) can
+// invoke the identical decision against a live `services`/`cfg` without
+// re-running session/service creation. Returns undefined when NO candidate is
+// viable at all (tier 3) — this is NOT a fault; the caller decides what to do
+// with it (construct a model-less session at boot, or leave a running session
+// alone on a failed re-drive attempt).
+// ---------------------------------------------------------------------------
+async function resolveLaunchModel(services, cfg) {
+    // Resolve one viable model against the SERVICES registry, which includes
+    // extension-provided providers. `resolveProviderCandidates` is the SOLE
+    // launch selection path — the same viability policy governs turn-time retry
+    // and rotation fallback — so launch selection can never diverge from
+    // rotation. A requested model gets first refusal (its provider pinned when
+    // the caller pinned it), then the authenticated registry order decides.
+    const requested = cfg.model ? parseModelSpec(cfg.model) : undefined;
+    const faultLaunchModel = (message) => {
+        recordFaultForCurrentNode({
+            link: 'crtr→pi',
+            op: 'model resolution at launch',
+            kind: 'model-not-found',
+            retry: { disposition: 'fatal' },
+            message,
+        });
+        throw new Error(`[broker] FATAL: ${message}`);
+    };
+    if (requested !== undefined && requested.modelSpec.indexOf('/') <= 0) {
+        faultLaunchModel(`model '${cfg.model}' has no 'provider/id' form and cannot be resolved`);
+    }
+    const requestedProvider = requested?.modelSpec.slice(0, requested.modelSpec.indexOf('/'));
+    const requestedId = requested?.modelSpec.slice(requested.modelSpec.indexOf('/') + 1);
+    const registry = registryOf(services);
+    // The requested model's SAME-STRENGTH cell on the OTHER provider — the one
+    // substitution that preserves the caller's intent, since a persona asks for a
+    // STRENGTH (`explore: openai/light`) and the ladder only picks the id. It is
+    // candidate #2, ahead of raw registry order: without it, an unavailable
+    // `openai/light` fell through to whatever the registry happened to list first
+    // (`anthropic/claude-fable-5` — the most expensive model there is) for a scout
+    // that asked for the cheapest. This is the SAME mapping turn-time rotation
+    // already falls back through (`equivalentOtherProviderModel`), so launch
+    // selection and rotation now degrade identically instead of divergently.
+    const ladderFallback = cfg.modelExact === true || cfg.model === undefined
+        ? null
+        : equivalentOtherProviderModel(cfg.model);
+    const ladderCandidate = (() => {
+        if (ladderFallback === null)
+            return undefined;
+        const spec = parseModelSpec(ladderFallback.model);
+        const slash = spec.modelSpec.indexOf('/');
+        if (slash <= 0)
+            return undefined;
+        const provider = spec.modelSpec.slice(0, slash);
+        const id = spec.modelSpec.slice(slash + 1);
+        if (provider === requestedProvider && id === requestedId)
+            return undefined;
+        return { provider, id, thinkingLevel: spec.thinkingLevel };
+    })();
+    const requestedModel = requestedProvider !== undefined && requestedId !== undefined
+        ? registry.find(requestedProvider, requestedId)
+        : undefined;
+    // Enumerate every REGISTERED model (not just the authenticated set) so the
+    // resolver itself classifies each candidate's registered/authenticated/
+    // cooling state and reports a per-candidate rejection reason. Requested
+    // first, then the rest of the registry in order.
+    // cfg.modelExact locks launch selection to ONLY the requested candidate —
+    // the rest of the registry is never spread in, so no cross-model/cross-
+    // provider substitution is even reachable below.
+    const orderedModels = [
+        ...(requestedProvider !== undefined && requestedId !== undefined
+            ? [{ provider: requestedProvider, id: requestedId, model: requestedModel, thinkingLevel: requested?.thinkingLevel }]
+            : []),
+        ...(ladderCandidate !== undefined
+            ? [{
+                    provider: ladderCandidate.provider,
+                    id: ladderCandidate.id,
+                    model: registry.find(ladderCandidate.provider, ladderCandidate.id),
+                    thinkingLevel: ladderCandidate.thinkingLevel,
+                }]
+            : []),
+        ...(cfg.modelExact === true ? [] : registry.getAll()
+            .filter((candidate) => (candidate.provider !== requestedProvider || candidate.id !== requestedId)
+            && (ladderCandidate === undefined || candidate.provider !== ladderCandidate.provider || candidate.id !== ladderCandidate.id))
+            .map((candidate) => ({
+            provider: candidate.provider,
+            id: candidate.id,
+            model: candidate,
+            thinkingLevel: undefined,
+        }))),
+    ];
+    // Tier 1/2 policy: a non-managed candidate is only automatic-fallback-eligible
+    // when NO managed provider has an authenticated (pool-occupied) credential
+    // ANYWHERE in the ordered set — regardless of that managed candidate's
+    // current cooling state. A cooling-but-authenticated managed pool still
+    // blocks automatic fallback to a non-managed provider (preserves 4be8be6's
+    // intent: don't silently abandon a paid managed subscription for a
+    // pay-per-token key just because it's rate-limited right now). Only when
+    // there is NO managed-authenticated candidate at all does a registered +
+    // authenticated non-managed model become an acceptable automatic launch
+    // fallback (tier 2); only when even that is unavailable does launch fall all
+    // the way through to a model-less boot (tier 3, below).
+    const hasManagedAuthenticated = orderedModels.some((candidate) => {
+        if (!isManagedProvider(candidate.provider))
+            return false;
+        if (candidate.model === undefined)
+            return false; // not registered
+        return readSubscriptionPool(candidate.provider).length > 0;
+    });
+    const selection = resolveProviderCandidates(orderedModels.map((candidate, index) => {
+        // Managed providers authenticate off their subscription pool's accounts, not
+        // static credentials; a fully-cooling pool marks the candidate cooling.
+        const pool = isManagedProvider(candidate.provider) ? readSubscriptionPool(candidate.provider) : [];
+        const explicit = index === 0 && requestedProvider !== undefined && requestedId !== undefined;
+        return {
+            providerId: candidate.provider,
+            modelId: candidate.id,
+            thinkingLevel: candidate.thinkingLevel,
+            registered: candidate.model !== undefined,
+            // Non-managed models are valid automatic fallback when explicitly
+            // requested, when the candidate IS a managed provider itself, or (tier
+            // 2) when no managed-authenticated candidate exists anywhere in this
+            // launch's candidate set.
+            automaticFallback: explicit || isManagedProvider(candidate.provider) || !hasManagedAuthenticated,
+            authenticated: candidate.model !== undefined && (isManagedProvider(candidate.provider)
+                ? pool.length > 0
+                : registry.hasConfiguredAuth(candidate.model)),
+            coolingUntil: pool.length > 0 && pool.every((entry) => (entry.rateLimitedUntil || 0) > Date.now())
+                ? Math.min(...pool.map((entry) => entry.rateLimitedUntil || 0))
+                : undefined,
+        };
+    }), Date.now(), 
+    // An explicit provider pin forbids cross-provider fallback for an
+    // unregistered/unauthenticated request; only a transient managed cooldown
+    // on the pinned provider still boots a viable alternative.
+    { pinnedToFirst: cfg.modelProviderPinned === true && requested !== undefined });
+    const selected = selection.candidates[0];
+    if (selected === undefined) {
+        const rejectionText = selection.rejected.length > 0
+            ? selection.rejected.map(({ candidate, reason }) => `'${candidate.providerId}/${candidate.modelId}' ${reason === 'non-managed-fallback' ? 'non-managed provider is not an automatic fallback' : reason}`).join('; ')
+            : 'no candidates were supplied';
+        // An exact-consult launch must FAIL rather than fall through to a
+        // model-less session — an unavailable captured model faults the launch
+        // (crash), never a silent degrade/substitution.
+        if (cfg.modelExact === true) {
+            return faultLaunchModel(`exact-consult model '${cfg.model}' is unavailable — refusing to substitute (${rejectionText})`);
+        }
+        // Tier 3: no viable candidate at all (genuine zero-auth, OR every managed
+        // pool is cooling AND no non-managed provider is authenticated). This is
+        // NOT a fault — the caller constructs a model-less session so the
+        // socket/listener still comes up and the user can /login; reload_auth
+        // re-invokes this same helper to re-drive once auth changes.
+        emitEvent({
+            level: 'warn',
+            event: 'broker.model.none_viable',
+            fields: {
+                rejected_candidates: selection.rejected.slice(0, 16).map(({ candidate, reason }) => ({
+                    provider: candidate.providerId,
+                    model: candidate.modelId,
+                    reason,
+                })),
+                rejected_candidates_omitted: Math.max(0, selection.rejected.length - 16),
+            },
+        });
+        return undefined;
+    }
+    const model = registry.find(selected.providerId, selected.modelId);
+    if (model === undefined) {
+        return faultLaunchModel(`selected model '${selected.providerId}/${selected.modelId}' disappeared during launch`);
+    }
+    const thinkingLevel = selected.thinkingLevel;
+    // A launch that does not get the model it asked for is a SUBSTITUTION, and it
+    // used to be entirely silent: the session simply came up on another model and
+    // the only trace was the pi `model_change` entry in the .jsonl. One line, only
+    // on the rare path, carrying the per-candidate rejection reasons that decided
+    // it — so "why is this node on the wrong model" is answerable from the log.
+    if (requestedProvider !== undefined &&
+        requestedId !== undefined &&
+        (selected.providerId !== requestedProvider || selected.modelId !== requestedId)) {
+        emitEvent({
+            level: 'warn',
+            event: 'broker.model.launch_fallback',
+            fields: {
+                requested: `${requestedProvider}/${requestedId}`,
+                selected: `${selected.providerId}/${selected.modelId}`,
+                ladder_equivalent: ladderFallback === null ? null : ladderFallback.model,
+                rejected_candidates: selection.rejected.slice(0, 8).map(({ candidate, reason }) => ({
+                    provider: candidate.providerId,
+                    model: candidate.modelId,
+                    reason,
+                })),
+            },
+        });
+    }
+    if (requestedProvider !== undefined &&
+        requestedId !== undefined &&
+        isManagedProvider(requestedProvider) &&
+        requestedModel !== undefined &&
+        (selected.providerId !== requestedProvider || selected.modelId !== requestedId)) {
+        // This launch fallback is temporary: retain the requested managed pin for
+        // provider-rotation's before_agent_start restoration once it is ready.
+        rememberPreferredModel({ providerId: requestedProvider, modelId: requestedId });
+    }
+    return { model, thinkingLevel };
+}
+/**
+ * Wrap a live ModelRuntime so a model-less `createAgentSessionFromServices`
+ * call can't have the SDK's own `findInitialModel` silently pick a model
+ * behind crouter's launch policy. Both `getModel()` (step 3: settingsManager's
+ * durable `defaultProvider`/`defaultModel` — persisted into a GLOBAL
+ * settings.json by every `session.setModel()` call the broker itself already
+ * makes at broker.ts:609/675/1606/1650, so this is a live bypass on any
+ * machine that has ever picked a model, not a theoretical corner case) and
+ * `getAvailable()` (step 4: registry default) must both be intercepted —
+ * wrapping only `getAvailable()` leaves `getModel()`'s step-3 path (and the
+ * resume path's model restore, sdk.js:88) wide open. Everything else
+ * (`getModels`, `hasConfiguredAuth`, `refresh`, …) passes through untouched via
+ * `Reflect.get`. Used ONLY
+ * for the one model-less construction call; the `services` returned to every
+ * other caller (reload_auth, hasConfiguredAuth checks, …) keeps the REAL
+ * unwrapped registry.
+ *
+ * CONSTRUCTION-ONLY MASK: the SDK stores `options.services.modelRuntime` as the
+ * session's private `_modelRuntime` for its ENTIRE lifetime and never replaces
+ * it (agent-session-services.js:104-119, sdk.js:253). A permanent mask would
+ * leave list_models (getAvailable→[]), cycle_model, and provider-rotation
+ * fallback (getModel()→undefined) broken forever for any model-less-booted node,
+ * even after a later /login selects a model. Model selection can only happen
+ * DURING construction, so this proxy self-heals: it masks while `masked`, then
+ * `reveal()` (called immediately after createAgentSessionFromServices returns)
+ * flips the SAME retained proxy to a transparent passthrough forever after.
+ */
+function modelLessRegistry(real) {
+    let masked = true;
+    const runtime = new Proxy(real, {
+        get(target, prop, receiver) {
+            // `getAvailable` is async on ModelRuntime; findInitialModel awaits it.
+            if (masked && prop === 'getAvailable')
+                return async () => [];
+            if (masked && prop === 'getModel')
+                return () => undefined;
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+    return { runtime, reveal: () => { masked = false; } };
+}
+// ---------------------------------------------------------------------------
+// buildBrokerSession (plan T4 steps 2–4) — turn the launch recipe into a live
+// engine session via the pi SDK SERVICES path. Exported so the C3/C4 real-SDK
+// regression tests can drive the EXACT production wiring (not the mock).
+// ---------------------------------------------------------------------------
+export async function buildBrokerSession(engine, cfg) {
+    // 2. Build cwd-bound runtime services via the SERVICES path (C3) — NOT plain
+    //    createAgentSession. createAgentSessionServices builds + reloads the
+    //    resource loader (the `-e` canvas extensions + --append-system-prompt) and
+    //    REGISTERS extension-provided model providers into the ModelRegistry (it is
+    //    also where extension flag values would be applied — the broker recipe
+    //    carries none today). Plain createAgentSession does NEITHER, so a node whose
+    //    model comes from a custom-provider extension would get NO model. Mirrors pi
+    //    main.js (createAgentSessionServices → …FromServices).
+    //
+    //    C4 note: the pinned SDK (0.78.1) has NO project-trust concept at all —
+    //    project context files (AGENTS.md/CLAUDE.md) load UNCONDITIONALLY (gated
+    //    only by `noContextFiles`, left default-false), so the headless "trust
+    //    resolves false → context silently dropped" gap cannot occur here. WHEN the
+    //    SDK pin bumps to 0.79.0+ (which adds project-trust), pass an explicit
+    //    `settingsManager: SettingsManager.create(cfg.cwd, getAgentDir(), { projectTrusted: true })`
+    //    so headless trust defaults TRUSTED — and do NOT re-introduce the CLI's
+    //    resolveProjectTrust, which returns false with no TTY.
+    //
+    //    T3 session-rebind: services + model + session creation is factored into
+    //    `buildForManager` so it can serve BOTH the initial boot AND the
+    //    AgentSessionRuntime factory it is reused as below (new_session/
+    //    switch_session/fork rebuild the session by re-invoking it for a new
+    //    SessionManager). Mirrors pi main.js's `createRuntime`.
+    const agentDir = getAgentDir();
+    const buildForManager = async (o) => {
+        // pi 0.82 owns credentials through an app-supplied CredentialStore. Hand it
+        // crouter's, which serves managed providers straight from the subscription
+        // pool and everything else from auth.json — both read fresh under their lock
+        // on every call, because the rotation extension, `/provider-sub`, and the
+        // daemon's login fan all write out of band mid-session and pi's own default
+        // store would serve a cached view with no reload seam.
+        const { authPath, modelsPath } = modelRuntimePaths(o.agentDir);
+        const modelRuntime = await ModelRuntime.create({
+            credentials: new PoolCredentialStore(authPath),
+            modelsPath,
+        });
+        const services = await engine.createAgentSessionServices({
+            cwd: o.cwd,
+            agentDir: o.agentDir,
+            modelRuntime,
+            resourceLoaderOptions: {
+                additionalExtensionPaths: cfg.extensionPaths,
+                appendSystemPrompt: cfg.appendSystemPromptPath !== undefined ? [cfg.appendSystemPromptPath] : undefined,
+                // Suppress pi's <project_context> AGENTS.md/CLAUDE.md injection in the
+                // SYSTEM PROMPT unconditionally — crouter reads project guidance through
+                // the document substrate instead (a migrated AGENTS.md doc rides the
+                // <memory kind="knowledge"> block in the first-message bearings; see
+                // bearings.ts and `crtr sys sync project-guidance`), never pi's own file-based loader.
+                noContextFiles: true,
+            },
+        });
+        const extensionResult = services.resourceLoader.getExtensions();
+        // buildBrokerSession also supports standalone SDK consumers (for example a
+        // custom-provider extension test) that are not canvas nodes. Production
+        // canvas invocations always carry the full mandatory set after preflight;
+        // once any canvas hook is requested, require every one to load.
+        if (cfg.extensionPaths.some((path) => CANVAS_EXTENSIONS.includes(path))) {
+            const loadedPaths = new Set(extensionResult.extensions.map((extension) => extension.path));
+            const missingHooks = CANVAS_EXTENSIONS.filter((path) => !loadedPaths.has(path));
+            if (missingHooks.length > 0) {
+                const errors = extensionResult.errors
+                    .filter((error) => CANVAS_EXTENSIONS.includes(error.path))
+                    .map((error) => `${error.path}: ${error.error}`)
+                    .join('; ');
+                throw new Error(`[broker] FATAL: mandatory canvas extensions failed to load: ${missingHooks.join(', ')}${errors === '' ? '' : ` (${errors})`}`);
+            }
+        }
+        // 3. Resolve one viable model — resolveLaunchModel (module-scoped above) is
+        // the SOLE launch selection policy, shared with the reload_auth re-drive so
+        // a later /login re-runs the identical decision against this same `services`.
+        const resolved = await resolveLaunchModel(services, cfg);
+        // Tier 3: no viable candidate at all. Do NOT fault — construct a live
+        // model-less session so the socket/listener still comes up and the user can
+        // /login; suppress the SDK's own findInitialModel auto-selection
+        // (modelLessRegistry) so a stale global settings.json default or an
+        // available-but-policy-rejected model can't sneak in behind crouter's back.
+        const model = resolved?.model;
+        const thinkingLevel = resolved?.thinkingLevel;
+        const modelLess = resolved === undefined ? modelLessRegistry(services.modelRuntime) : undefined;
+        const constructionServices = modelLess !== undefined
+            ? { ...services, modelRuntime: modelLess.runtime }
+            : services;
+        const created = await engine.createAgentSessionFromServices({
+            services: constructionServices,
+            sessionManager: o.sessionManager,
+            model,
+            thinkingLevel,
+            tools: cfg.tools,
+            sessionStartEvent: o.sessionStartEvent,
+        });
+        // CONSTRUCTION-ONLY MASK — see modelLessRegistry: reveal now that model
+        // selection (construction-time only) is done, so a later /login re-drive's
+        // list_models/cycle_model/provider-rotation see the real registry.
+        modelLess?.reveal();
+        return { ...created, services };
+    };
+    // 4. Select the SessionManager: FORK (spawn-time --fork), OPEN (resume), or
+    //    CREATE (fresh). The broker is the sole writer of the resulting .jsonl.
+    const resumePath = cfg.resumeSessionPath;
+    const forking = cfg.forkFrom !== undefined && cfg.forkFrom !== '';
+    if (!forking &&
+        (resumePath === undefined || resumePath === '') &&
+        cfg.resumeSessionId !== undefined &&
+        cfg.resumeSessionId !== '') {
+        // SessionManager.open() takes a FILE path — it only path-normalizes; it does
+        // NOT resolve a bare uuid to its .jsonl the way pi's CLI does (via
+        // SessionManager.list). A bare-id-only resume would open a nonexistent
+        // <cwd>/<uuid> and silently start an EMPTY session. Fail loud: revive always
+        // passes the .jsonl path, so a bare id means an old node that never captured
+        // pi_session_file — mis-resuming it silently is worse than a crash.
+        throw new Error(`[broker] resume requires a session .jsonl PATH; got only a bare id ` +
+            `'${cfg.resumeSessionId}' (pi_session_file was never captured for this node)`);
+    }
+    // A fork is a fresh spawn (resuming=false) so its kickoff firstPrompt fires: a
+    // `node new --fork-from <id>` gives the new node the source's full history AND a
+    // new task to start on. An ordinary resume supplies no prompt, but a
+    // broker-certified runtime-abort resume deliberately carries a continuation.
+    //
+    // A refresh-yield CYCLES instead: `cfg.newCycle` (the `--crtr-new-cycle` token)
+    // marks a revive that reuses this SAME `.jsonl` rather than resuming it — the
+    // session manager opens the file, then resets the leaf and roots a `crtr-cycle`
+    // marker entry (data: `{cycle, fromLeaf}`) as the new cycle's ROOT before the
+    // session is built. Custom entries never enter LLM context, so the freshly
+    // rooted branch is exactly as clean as a brand-new session; `cycleAwareMessages`
+    // (session-cycles.ts) is the display-side counterpart that replays every prior
+    // cycle for snapshot rendering. cycling ⇒ resuming=false, so the kickoff
+    // firstPrompt fires below just like a true fresh launch.
+    const hasSessionPath = !forking && resumePath !== undefined && resumePath !== '';
+    const cycling = hasSessionPath && cfg.newCycle === true;
+    const resuming = hasSessionPath && !cycling;
+    let sessionManager;
+    if (forking) {
+        // Spawn-time fork via pi's REAL fork seam, SessionManager.forkFrom — the exact
+        // method pi's own `--fork` CLI flag uses (main.js forkSessionOrExit). It writes
+        // a NEW session file with a NEW id and a `parentSession` header pointing at the
+        // source, then copies the source's history into it. NOT a naïve `.jsonl` copy
+        // (which would collide session ids and drop the fork metadata), and NOT
+        // runtime.fork() (which forks an entry WITHIN an already-loaded session — there
+        // is no current session to fork at boot). The caller (spawn.ts resolveForkSource)
+        // resolves cfg.forkFrom to an absolute source .jsonl before launch, so a bad ref
+        // fails loudly here (forkFrom throws on an empty/invalid/header-less source).
+        sessionManager = engine.SessionManager.forkFrom(cfg.forkFrom, cfg.cwd);
+    }
+    else if (resuming || cycling) {
+        sessionManager = engine.SessionManager.open(resumePath);
+        if (cycling) {
+            const fromLeaf = sessionManager.getLeafId();
+            sessionManager.resetLeaf();
+            sessionManager.appendCustomEntry(CRTR_CYCLE_CUSTOM_TYPE, {
+                cycle: Number(process.env['CRTR_CYCLES']),
+                fromLeaf,
+            });
+        }
+    }
+    else {
+        sessionManager = engine.SessionManager.create(cfg.cwd);
+    }
+    // When the engine exposes the replacement API (real SDK), wrap the builder in an
+    // AgentSessionRuntime so new_session/switch_session/fork work; the runtime
+    // re-invokes `buildForManager` for each new SessionManager. The fake-engine
+    // fixture omits it — fall back to a single direct build (those three ops then
+    // reply error{engine_error}).
+    if (engine.createAgentSessionRuntime !== undefined) {
+        const factory = async (o) => {
+            const r = await buildForManager({
+                cwd: o.cwd,
+                agentDir: o.agentDir,
+                sessionManager: o.sessionManager,
+                sessionStartEvent: o.sessionStartEvent,
+            });
+            return { ...r, diagnostics: r.services.diagnostics ?? [] };
+        };
+        const runtime = await engine.createAgentSessionRuntime(factory, {
+            cwd: cfg.cwd,
+            agentDir,
+            sessionManager,
+        });
+        return { session: runtime.session, services: runtime.services, resuming, runtime };
+    }
+    const r = await buildForManager({ cwd: cfg.cwd, agentDir, sessionManager });
+    return { session: r.session, services: r.services, resuming, runtime: undefined };
+}
+export function makeBrokerUiContext(deps) {
+    // The dialog router. C2 (scout mq5thyli): the design §5.4 premise — that an
+    // unattended dialog auto-resolves on its OWN timeout — is FALSE. `timeout` is
+    // OPTIONAL on dialog opts, editor() takes none, and almost no real extension
+    // passes one (permission-gate / confirm-destructive / plan-mode / subagent all
+    // omit it). A timeout-reliant unattended node therefore deadlocks the agent
+    // turn FOREVER. So with NO WRITABLE client attached we fall back to the SDK's
+    // noOp UI behavior — resolve to the default (deny / cancel / undefined)
+    // IMMEDIATELY, never arming a timer, never waiting. With one or more, the dialog
+    // is fanned out to all of them under a broker-side timeout+abort, so viewers
+    // that attach but never answer cannot hang the turn either.
+    const dialogPromise = (defaultValue, request, parse, opts) => {
+        if (opts?.signal?.aborted)
+            return Promise.resolve(defaultValue);
+        // Snapshot the writable set ONCE, at raise time — the fan-out targets and the
+        // zero-answerer decision must agree.
+        const targets = deps.writable();
+        // C2 (Wave-0, KEEP): nobody can answer at raise time → noOp, resolved at once.
+        // No timer, no wait, no deadlock.
+        if (targets.length === 0)
+            return Promise.resolve(defaultValue);
+        // At least one writable client: register the dialog FIRST (so a client that
+        // attaches mid-dialog gets it replayed and joins the race), fan it out to every
+        // target, and ALWAYS arm a broker-side timeout (C2 anti-deadlock): viewers that
+        // never answer — or all detach — can never hang the turn. Honor a shorter
+        // per-dialog timeout if the extension passed one; otherwise the broker default.
+        // On fire it resolves to the SAFE default (deny/cancel/undefined). A detach
+        // does NOT cancel this — only an answer, the timeout, or an abort.
+        //
+        // EVERY settlement path runs the same `cleanup` (drop the entry, so a later
+        // answer for this id is a no-op) and then broadcasts `extension_ui_dismiss`
+        // keyed to this id, so all peers close their copy of exactly this dialog and
+        // nothing else.
+        return new Promise((resolve) => {
+            let timer;
+            const cleanup = () => {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                opts?.signal?.removeEventListener('abort', onAbort);
+                deps.pending.delete(request.id);
+            };
+            const onAbort = () => {
+                cleanup();
+                // The extension aborted this request out-of-band (e.g. an OAuth loopback
+                // callback won the race against a still-open manual-paste dialog). Tell
+                // every peer to tear down THIS overlay by id — an unanswered dialog whose
+                // broker entry we just dropped would otherwise linger onscreen with nothing
+                // left to answer it. Keyed to request.id so only the abandoned dialog is
+                // dismissed, never an unrelated one.
+                deps.broadcast({ type: 'extension_ui_dismiss', id: request.id });
+                resolve(defaultValue);
+            };
+            opts?.signal?.addEventListener('abort', onAbort, { once: true });
+            // N1: honor the extension's EXPLICIT per-dialog timeout if it passed one
+            // (longer or shorter than the broker default is fine — both are bounded);
+            // otherwise fall back to the broker default. The broker never RELIES on the
+            // extension having passed one (C2).
+            const ms = opts?.timeout !== undefined ? opts.timeout : DEFAULT_DIALOG_TIMEOUT_MS;
+            timer = setTimeout(() => {
+                cleanup();
+                // Same correlated teardown as onAbort: the broker resolved this dialog on
+                // its own timeout, so every peer's overlay (none of which has an
+                // independent timer) must be dismissed by id or it lingers forever.
+                deps.broadcast({ type: 'extension_ui_dismiss', id: request.id });
+                resolve(defaultValue);
+            }, ms);
+            if (typeof timer.unref === 'function')
+                timer.unref();
+            deps.pending.set(request.id, {
+                request,
+                resolve: (r) => {
+                    cleanup();
+                    // The first answer settled it; tell every OTHER client that was fanned
+                    // this dialog (and the answerer, for whom it is an idempotent no-op) to
+                    // close its copy. Without this, peers would sit on an overlay whose
+                    // answer can never arrive.
+                    deps.broadcast({ type: 'extension_ui_dismiss', id: request.id });
+                    resolve(parse(r));
+                },
+            });
+            for (const target of targets)
+                deps.forward(target, request);
+        });
+    };
+    const noop = () => { };
+    const ctx = {
+        [MANAGED_PROVIDER_ROTATION_POLICY_UI]: deps.providerRotationPolicy ?? (() => ({ allowCrossProviderFallback: true })),
+        // The broker-owned known-stream-wait control (see BrokerDialogDeps): a
+        // deliberate provider cooldown is KNOWN liveness, so the provider extension
+        // reaches this through the stable symbol to pause the dead-stream watchdog for
+        // the wait's duration. A no-op when the host supplied none.
+        [KNOWN_STREAM_WAIT_UI]: deps.onKnownStreamWait ?? ((_deadlineMs) => () => { }),
+        // pi's ExtensionUIContext exposes `theme`; package extensions (e.g. the OAuth
+        // billing adapter's status rendering) read it from ANY lifecycle hook. The
+        // SDK's noOpUIContext returns the process-global theme proxy here; we mirror
+        // that by reading the same global symbol (populated by initTheme() at broker
+        // boot — see runBroker). Without this property `ctx.ui.theme` is undefined and
+        // the hook throws, which the runner silently swallows while dropping the hook's
+        // returned payload (the OAuth 400 root cause).
+        get theme() {
+            const t = globalThis[Symbol.for('@earendil-works/pi-coding-agent:theme')];
+            if (t === undefined || t === null) {
+                throw new Error('Theme not initialized. Call initTheme() first.');
+            }
+            return t;
+        },
+        select: (title, options, opts) => dialogPromise(undefined, { type: 'extension_ui_request', id: randomUUID(), method: 'select', title, options, timeout: opts?.timeout }, (r) => ('cancelled' in r && r.cancelled ? undefined : 'value' in r ? r.value : undefined), opts),
+        confirm: (title, message, opts) => dialogPromise(false, { type: 'extension_ui_request', id: randomUUID(), method: 'confirm', title, message, timeout: opts?.timeout }, (r) => ('cancelled' in r && r.cancelled ? false : 'confirmed' in r ? r.confirmed : false), opts),
+        input: (title, placeholder, opts) => dialogPromise(undefined, { type: 'extension_ui_request', id: randomUUID(), method: 'input', title, placeholder, timeout: opts?.timeout }, (r) => ('cancelled' in r && r.cancelled ? undefined : 'value' in r ? r.value : undefined), opts),
+        editor: (title, prefill) => dialogPromise(undefined, { type: 'extension_ui_request', id: randomUUID(), method: 'editor', title, prefill }, (r) => ('cancelled' in r && r.cancelled ? undefined : 'value' in r ? r.value : undefined)),
+        // Non-blocking extension-UI relay: broadcast these to all viewers instead of
+        // dropping them, in pi's OWN `extension_ui_request` envelope (rpc-mode.js
+        // emits these three identically). The viewer owns the slots that render them,
+        // and the broker retains their last value for the welcome snapshot. The other
+        // non-blocking methods stay inert.
+        setStatus: (key, text) => deps.broadcast({
+            type: 'extension_ui_request',
+            id: randomUUID(),
+            method: 'setStatus',
+            statusKey: key,
+            statusText: text,
+        }),
+        setWidget: (key, content, options) => {
+            // setWidget's component-factory overload cannot be serialized over the
+            // socket (R1 caveat) — drop it and relay only the string[] form, exactly as
+            // pi's own RPC setWidget carries only `widgetLines`.
+            if (typeof content === 'function')
+                return;
+            deps.broadcast({
+                type: 'extension_ui_request',
+                id: randomUUID(),
+                method: 'setWidget',
+                widgetKey: key,
+                widgetLines: content,
+                widgetPlacement: options?.placement,
+            });
+        },
+        setTitle: (title) => deps.broadcast({ type: 'extension_ui_request', id: randomUUID(), method: 'setTitle', title }),
+        notify: (message, type) => {
+            const notifyType = type === 'warn' ? 'warning' : type;
+            deps.broadcast({ type: 'extension_ui_request', id: randomUUID(), method: 'notify', message, notifyType });
+        },
+        onTerminalInput: () => noop,
+        setWorkingMessage: noop,
+        setWorkingVisible: noop,
+        setWorkingIndicator: noop,
+        setHiddenThinkingLabel: noop,
+        setFooter: noop,
+        setHeader: noop,
+        custom: () => Promise.resolve(undefined),
+        pasteToEditor: noop,
+        setEditorText: noop,
+        getEditorText: () => '',
+        addAutocompleteProvider: noop,
+        setEditorComponent: noop,
+        getEditorComponent: () => undefined,
+        getAllThemes: () => [],
+        getTheme: () => undefined,
+        setTheme: noop,
+        getToolsExpanded: () => false,
+        setToolsExpanded: noop,
+    };
+    return ctx;
+}