@crouton-kit/crouter 0.3.27 → 0.3.29

package/dist/core/runtime/broker.js

@@ -1,11 +1,12 @@
 // broker.ts — the headless node broker (design §4, §5; plan T4).
 //
-// One broker process per `--headless` node. It hosts ONE pi engine IN-PROCESS
+// 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 a single controller's drive commands, and
-// routes blocking extension dialogs. It is the headless analog of pi-in-a-pane:
-// it runs one turn-cycle and, when the engine settles (the stophook calls
+// routes blocking extension dialogs. 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.
 //
@@ -16,10 +17,13 @@
 // 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 { getAgentDir, initTheme, } from '@earendil-works/pi-coding-agent';
 import { jobDir, nodeDir } from '../canvas/paths.js';
+import { getNode, updateNode } from '../canvas/index.js';
 import { FRONT_DOOR_ENV } from './front-door.js';
 import { piInvocationToSdkConfig } from './launch.js';
 import { assertEngineVersion, loadBrokerEngine } from './broker-sdk.js';
@@ -83,14 +87,13 @@ export async function runBroker(nodeId) {
     // 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';
-    // The broker is PANELESS. A `--headless` child spawned by a tmux-resident
-    // parent inherits the parent's TMUX_PANE/TMUX in its env (T6 spawns with
-    // {...process.env}); left in place, the bound stophook's refresh-yield branch
-    // (canvas-stophook.ts) would call reviveInPlace on the PARENT's %pane_id
-    // (respawn-pane -k) — hijacking the parent's pane with a fresh pi, killing the
-    // parent and orphaning this broker. Strip both so every stophook pane-branch
-    // takes its no-pane path (→ ctx.shutdown() → our shutdownHandler → clean exit;
-    // the daemon then respawns the node as a broker).
+    // 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.
@@ -110,12 +113,6 @@ export async function runBroker(nodeId) {
     const launchFile = join(dir, 'broker-launch.json');
     const inv = JSON.parse(readFileSync(launchFile, 'utf8'));
     const cfg = piInvocationToSdkConfig(inv); // also merges inv.env
-    // Fork-on-spawn is the runtime.fork() path (createAgentSessionRuntime), not
-    // wired headless in Phase 3. Fail loud rather than silently mis-resume.
-    if (cfg.forkFrom !== undefined && cfg.forkFrom !== '') {
-        throw new Error(`[broker] --fork is not supported by the headless broker in Phase 3 ` +
-            `(forkFrom=${cfg.forkFrom}); the SDK fork path is createAgentSessionRuntime.fork()`);
-    }
     // 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.
@@ -157,12 +154,25 @@ export async function runBroker(nodeId) {
     let controllerId = null;
     let disposed = false;
     let server;
+    // Liveness-aware: a controllerId whose client's transport is already gone counts
+    // as NO controller, so control self-heals the instant a controller's peer departs
+    // — WITHOUT waiting for the socket 'close' event. On a unix socket a peer
+    // destroy() delivers EOF (readableEnded) promptly, but the matching 'close' can
+    // lag arbitrarily while undrainable pending writes to the gone peer flush; under
+    // load that lag stranded control on a dead client and froze admission (a fresh
+    // controller hello was denied for the whole window — the one-writer reattach
+    // deadlock the G9 gate locks). Treating an ended/destroyed/unwritable holder as
+    // free closes that window at every read of the controller (admission included).
     const controllerClient = () => {
         if (controllerId === null)
             return null;
-        for (const c of clients)
-            if (c.id === controllerId)
-                return c;
+        for (const c of clients) {
+            if (c.id !== controllerId)
+                continue;
+            if (c.socket.destroyed || c.socket.readableEnded || !c.socket.writable)
+                return null;
+            return c;
+        }
         return null;
     };
     // Persist viewer presence to job/attach.json on every viewer state change
@@ -309,8 +319,42 @@ export async function runBroker(nodeId) {
         persistAttachState(); // every control change is a viewer-state change
         broadcast({ type: 'control_changed', controller_id: controllerId });
     };
+    // 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).
+    const persistModelChoice = () => {
+        const nodeId = process.env['CRTR_NODE_ID'];
+        const m = session.model;
+        if (nodeId === undefined || nodeId === '' || m === null || m === undefined)
+            return;
+        const spec = `${m.provider}/${m.id}`;
+        try {
+            const meta = getNode(nodeId);
+            if (meta === null)
+                return;
+            const launch = meta.launch !== undefined ? { ...meta.launch, model: spec } : 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 = () => {
+        persistModelChoice();
+        broadcast({ type: 'model_changed', model: session.model?.id });
+    };
     const buildSnapshot = () => ({
-        messages: session.messages,
+        messages: snapshotMessages(session),
         stats: session.getSessionStats(),
         state: {
             sessionId: session.sessionId,
@@ -339,6 +383,7 @@ export async function runBroker(nodeId) {
             role: client.role,
             controller_id: controllerId,
             pending_dialog: first !== undefined ? first.request : null,
+            agentDir: getAgentDir(),
         }, true);
     };
     // T4 re-route on become-controller: a dialog raised while a prior controller was
@@ -407,6 +452,7 @@ export async function runBroker(nodeId) {
         controller: controllerClient,
         forward: (client, request) => sendFrame(client, request),
         pending: pendingDialogs,
+        broadcast,
     });
     // -------------------------------------------------------------------------
     // 3+4 (plan): bind the FULL canvas extensions (mode 'print') AND fan the single
@@ -520,18 +566,29 @@ export async function runBroker(nodeId) {
     // -------------------------------------------------------------------------
     /** Reject a non-controller for a controller-only op. Returns true when rejected
      *  (the caller should `break`). */
-    const notController = (client, what) => {
+    const notController = (client, what, id) => {
         if (client.id === controllerId)
             return false;
         sendFrame(client, {
             type: 'error',
             code: 'not_controller',
             message: `only the controlling client may ${what}`,
+            // M1: echo a correlated request's id so its pending-by-id promise rejects
+            // rather than hanging (e.g. a non-controller `dequeue`).
+            ...(id !== undefined ? { id } : {}),
         });
         return true;
     };
     const ackTo = (client, op, ok = true, detail) => sendFrame(client, { type: 'ack', for: op, ok, ...(detail !== undefined ? { detail } : {}) });
-    const engineErrorTo = (client) => (err) => sendFrame(client, { type: 'error', code: 'engine_error', message: String(err) });
+    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. */
@@ -541,6 +598,63 @@ export async function runBroker(nodeId) {
             return undefined;
         return services.modelRegistry.find(spec.slice(0, slash), spec.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 = services.modelRegistry.getAll();
+        }
+        catch {
+            return undefined;
+        }
+        let availableKeys;
+        try {
+            availableKeys = new Set(services.modelRegistry.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;
+    };
     /** The merged command list for `get_commands` (C6/M9): the engine's registered
      *  extension + skill commands and file-based prompt templates, MERGED with the
      *  vendored BUILTIN_SLASH_COMMANDS (RPC omits builtins). Returned to the viewer
@@ -569,6 +683,128 @@ export async function runBroker(nodeId) {
         }
         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 controller-gated
+    // (read-only, like get_commands), so the web bridge's observer connection can
+    // populate pickers too.
+    // -------------------------------------------------------------------------
+    const toModelRef = (m) => m === undefined ? null : { provider: m.provider, id: m.id };
+    const modelKey = (m) => `${m.provider}/${m.id}`;
+    const buildListModelsData = (id) => {
+        const reg = session.modelRegistry;
+        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: session.modelRegistry.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() ?? '',
+            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(),
+            autoRetry: session.autoRetryEnabled,
+            model: toModelRef(session.model),
+        };
+        return { type: 'data', id, kind: 'get_settings', settings };
+    };
+    const buildSessionsData = async (id, scope) => {
+        const sm = session.sessionManager;
+        const raw = scope === 'all'
+            ? await engine.SessionManager.listAll()
+            : await engine.SessionManager.list(sm.getCwd(), sm.getSessionDir());
+        const sessions = raw.map((s) => ({
+            ...s,
+            created: s.created.toISOString(),
+            modified: s.modified.toISOString(),
+        }));
+        return {
+            type: 'data',
+            id,
+            kind: 'list_sessions',
+            scope,
+            sessions,
+            currentSessionFile: session.sessionFile,
+        };
+    };
     /** Run a session-replacing op (new_session/switch_session/fork). The runtime
      *  rebinds extensions + re-subscribes via setRebindSession before it resolves,
      *  so on success we just re-snapshot every viewer onto the new session. */
@@ -594,9 +830,11 @@ export async function runBroker(nodeId) {
             case 'hello': {
                 client.id = frame.client_id;
                 client.helloed = true;
-                // First-attach-wins controller (§5.3): admit as controller iff one was
-                // requested and none is currently held; otherwise read-only observer.
-                if (frame.role === 'controller' && controllerId === null) {
+                // First-attach-wins (§5.3), but only against a LIVE controller: admit as
+                // controller iff none is currently held by a live client (controllerClient
+                // is liveness-aware, so a controllerId stranded on a departed peer reads as
+                // free here). Otherwise read-only observer.
+                if (frame.role === 'controller' && controllerClient() === null) {
                     client.role = 'controller';
                     controllerId = client.id;
                 }
@@ -631,19 +869,24 @@ export async function runBroker(nodeId) {
                 break;
             }
             case 'request_control': {
-                if (controllerId === null) {
-                    controllerId = client.id;
-                    client.role = 'controller';
-                    broadcastControlChanged();
-                    reroutePendingDialogsTo(client); // T4: hand the new controller pending dialogs
-                }
-                else {
-                    sendFrame(client, {
-                        type: 'error',
-                        code: 'control_held',
-                        message: 'another client holds control',
-                    });
-                }
+                // §D preemptive handoff (last-requester-wins): a control request ALWAYS
+                // succeeds, reassigning control to the requester and demoting the prior
+                // controller to observer. This makes a tmux pane and a web tab true peers —
+                // either can take control of a node the other currently drives — which is
+                // the broker-is-the-host invariant (the prior cooperative-only model could
+                // not preempt an idle/abandoned controller, the common case). The prior
+                // controller demotes itself on receiving the control_changed broadcast
+                // (attach-cmd.ts already does this; the web client implements the same
+                // rule). Idempotent when the requester already holds control.
+                if (client.id === controllerId)
+                    break;
+                const prior = controllerClient();
+                if (prior !== null)
+                    prior.role = 'observer';
+                controllerId = client.id;
+                client.role = 'controller';
+                broadcastControlChanged();
+                reroutePendingDialogsTo(client); // T4: hand the new controller pending dialogs
                 break;
             }
             case 'release_control': {
@@ -663,7 +906,9 @@ export async function runBroker(nodeId) {
                     break;
                 let model;
                 try {
-                    model = findModelSpec(frame.model);
+                    // Accept both an exact `provider/id` (from the picker) and a free-text
+                    // query (`/model opus`) — resolveModelQuery falls back to a search match.
+                    model = resolveModelQuery(frame.model);
                 }
                 catch (err) {
                     // N2: registry.find should never throw on the real SDK, but a degenerate
@@ -675,17 +920,53 @@ export async function runBroker(nodeId) {
                     sendFrame(client, {
                         type: 'error',
                         code: 'engine_error',
-                        message: `model '${frame.model}' not found in the registry`,
+                        message: `no model matching '${frame.model}' in the registry`,
                     });
                     break;
                 }
-                void session.setModel(model).then(() => ackTo(client, 'set_model')).catch(engineErrorTo(client));
+                void session
+                    .setModel(model)
+                    .then(() => {
+                    ackTo(client, 'set_model');
+                    broadcastModelChanged();
+                })
+                    .catch(engineErrorTo(client));
                 break;
             }
             case 'cycle_model': {
                 if (notController(client, 'cycle the model'))
                     break;
-                void session.cycleModel().then(() => ackTo(client, 'cycle_model')).catch(engineErrorTo(client));
+                void session
+                    .cycleModel(frame.direction)
+                    .then(() => {
+                    ackTo(client, 'cycle_model');
+                    broadcastModelChanged();
+                })
+                    .catch(engineErrorTo(client));
+                break;
+            }
+            case 'cycle_thinking': {
+                if (notController(client, 'cycle the thinking level'))
+                    break;
+                try {
+                    session.cycleThinkingLevel();
+                    ackTo(client, 'cycle_thinking');
+                }
+                catch (err) {
+                    engineErrorTo(client)(err);
+                }
+                break;
+            }
+            case 'dequeue': {
+                if (notController(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': {
@@ -761,12 +1042,68 @@ export async function runBroker(nodeId) {
                 }
                 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 '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 'navigate_tree': {
                 if (notController(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) => ackTo(client, 'navigate_tree', !r.cancelled))
+                    .then((r) => {
+                    if (!r.cancelled)
+                        reWelcomeAll();
+                    ackTo(client, 'navigate_tree', !r.cancelled, r.editorText);
+                })
                     .catch(engineErrorTo(client));
                 break;
             }
@@ -814,6 +1151,74 @@ export async function runBroker(nodeId) {
                 runReplacement(client, 'fork', (rt) => rt.fork(frame.entryId));
                 break;
             }
+            case 'clone': {
+                if (notController(client, 'clone the session'))
+                    break;
+                const sm = session.sessionManager;
+                const leafId = sm.getLeafId();
+                if (leafId === null) {
+                    ackTo(client, 'clone', false, 'no current leaf to clone from');
+                    break;
+                }
+                let newPath;
+                try {
+                    newPath = sm.createBranchedSession(leafId);
+                }
+                catch (err) {
+                    engineErrorTo(client)(err);
+                    break;
+                }
+                if (newPath === undefined) {
+                    ackTo(client, 'clone', false, 'createBranchedSession returned no path');
+                    break;
+                }
+                runReplacement(client, 'clone', (rt) => rt.switchSession(newPath));
+                break;
+            }
+            case 'share': {
+                if (notController(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': {
+                if (notController(client, 'reload auth'))
+                    break;
+                try {
+                    services.authStorage.reload();
+                    services.modelRegistry.refresh();
+                    ackTo(client, 'reload_auth');
+                    broadcastModelChanged();
+                }
+                catch (err) {
+                    engineErrorTo(client)(err);
+                }
+                break;
+            }
             case 'bye':
                 client.socket.end();
                 break;
@@ -907,17 +1312,36 @@ export async function runBroker(nodeId) {
     }
 }
 // ---------------------------------------------------------------------------
+// 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, so this is a single path with no engine-capability fallback.
+export function snapshotMessages(session) {
+    return session.sessionManager.buildSessionContext().messages;
+}
+// ---------------------------------------------------------------------------
 // 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) {
-    // Fork-on-spawn is the runtime.fork() path (createAgentSessionRuntime), not
-    // wired headless in Phase 3. Fail loud rather than silently mis-resume.
-    if (cfg.forkFrom !== undefined && cfg.forkFrom !== '') {
-        throw new Error(`[broker] --fork is not supported by the headless broker in Phase 3 ` +
-            `(forkFrom=${cfg.forkFrom}); the SDK fork path is createAgentSessionRuntime.fork()`);
-    }
     // 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
@@ -978,9 +1402,12 @@ export async function buildBrokerSession(engine, cfg) {
         });
         return { ...created, services };
     };
-    // 4. Open (resume) or create (fresh) the session — the broker is the sole writer.
+    // 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;
-    if ((resumePath === undefined || resumePath === '') &&
+    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
@@ -992,10 +1419,29 @@ export async function buildBrokerSession(engine, cfg) {
         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)`);
     }
-    const resuming = resumePath !== undefined && resumePath !== '';
-    const sessionManager = resuming
-        ? engine.SessionManager.open(resumePath)
-        : engine.SessionManager.create(cfg.cwd);
+    // A fork is a fresh spawn (resuming=false) so the 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. A resume replays the inbox instead and sends no kickoff.
+    const resuming = !forking && resumePath !== undefined && resumePath !== '';
+    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) {
+        sessionManager = engine.SessionManager.open(resumePath);
+    }
+    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
@@ -1101,18 +1547,33 @@ export function makeBrokerUiContext(deps) {
         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 (§5 Unit A task 3): broadcast these to all
+        // viewers as display frames instead of dropping them. The viewer (Unit E) owns
+        // the slots that render them. The other non-blocking methods stay inert.
+        setStatus: (key, text) => deps.broadcast({ type: 'display_status', key, 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: 'display_widget',
+                key,
+                lines: content,
+                placement: options?.placement ?? 'aboveEditor',
+            });
+        },
+        setTitle: (title) => deps.broadcast({ type: 'display_title', title }),
         // Inert print-mode surface (never reached by a Model hook in Phase 3).
         notify: noop,
         onTerminalInput: () => noop,
-        setStatus: noop,
         setWorkingMessage: noop,
         setWorkingVisible: noop,
         setWorkingIndicator: noop,
         setHiddenThinkingLabel: noop,
-        setWidget: noop,
         setFooter: noop,
         setHeader: noop,
-        setTitle: noop,
         custom: () => Promise.resolve(undefined),
         pasteToEditor: noop,
         setEditorText: noop,