@crouton-kit/crouter 0.3.27 → 0.3.29

package/dist/commands/view.js

@@ -1,10 +1,12 @@
 // `crtr view` — the TUI view library.
 //
-// Views are switchable raw-ANSI terminal surfaces, each a self-contained .mjs
-// the host loads and runs. This branch assembles the leaves: `list` enumerates
-// what's available, `run` hosts one (interactive in tmux, static dump when
-// piped), `new` scaffolds a fresh view.mjs, and the hidden `pick` backs the
-// /view popup. Each leaf owns its own help one level down.
+// Views are switchable surfaces with two targets from one portable core.mjs:
+// the tmux TUI (`run`) and a React+Tailwind web page. This branch assembles the
+// TUI-side leaves: `list` enumerates what's available, `run` hosts the TUI
+// target (interactive in tmux, static dump when piped), `new` scaffolds a fresh
+// view directory, and the hidden `pick` backs the /view popup. Each leaf owns
+// its own help one level down. The web target is no longer served per-view here:
+// it is hosted by the unified `crtr web serve` (the shell's /view/<id> route).
 import { defineBranch } from '../core/command.js';
 import { viewListLeaf } from './view-list.js';
 import { viewRunLeaf } from './view-run.js';
@@ -22,7 +24,7 @@ export function registerView() {
         help: {
             name: 'view',
             summary: 'host and author switchable raw-ANSI terminal views',
-            model: '`list` when you do not know which views exist — a flat roster (id/title/description/scope) across project→user→builtin. `run <name>` opens one full-screen in the current pane (tmux-only interactive; piped it prints the view\'s static dump and exits 0), forwarding --port/--target onto the view; pass --window/--split to open it as a persistent monitor (new window / split) you flip between with Alt+V then ]/[. `cycle` switches a monitor pane to the next/prev view in place (what those keys drive). `new <name>` scaffolds a runnable view.mjs stub you edit. `pick` is a hidden raw-ANSI picker the /view popup shells. Append `-h` at any leaf for its schema.',
+            model: '`list` when you do not know which views exist — a flat roster (id/title/description/scope) across project→user→builtin. `run <name>` opens the TUI target full-screen in the current pane (tmux-only interactive; piped it prints the view\'s static dump and exits 0), forwarding --port/--target onto the view; pass --window/--split to open it as a persistent monitor (new window / split) you flip between with Alt+V then ]/[. The web target (React+Tailwind) is served by the unified `crtr web serve` (the shell\'s /view/<id> route), not per-view here. `cycle` switches a monitor pane to the next/prev view in place (what those keys drive). `new <name>` scaffolds a runnable view directory (core.mjs + tui.mjs + web.jsx + text.mjs) you edit. `pick` is a hidden raw-ANSI picker the /view popup shells. Append `-h` at any leaf for its schema.',
         },
         children: [viewListLeaf, viewRunLeaf, viewCycleLeaf, viewNewLeaf, viewPickLeaf],
     });

package/dist/commands/workspace.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerWorkspace(): BranchDef;

package/dist/commands/workspace.js

@@ -0,0 +1,161 @@
+// workspace.ts — `crtr workspace enter`: the agent-centric editor layout.
+//
+// Turns the current tmux window into an editor view for attached headless nodes:
+// a narrow LEFT rail (the `workspace-sidebar` view — this graph + other live
+// agents in this cwd, with ⚑ inbox flags) beside a CHAT pane (`crtr attach`).
+// Selecting a node in the rail swaps it into the chat pane.
+//
+// Layout build (the only two driver acts, both through placement's seam):
+//   1. splitWindow(here, before+size) → the rail pane, left of here, runs
+//      `crtr view run workspace-sidebar`.
+//   2. `crtr node focus <node> --pane <here>` → swaps the chat node's attach
+//      viewer into here's slot (here's old content relocates to the backstage).
+// The rail finds the chat pane by DISCOVERY (the `@crtr_node` tag attach sets),
+// so it is robust to that swap — no launch-time pane id is threaded into it.
+//
+// Command shape: the path-walker forbids a flat top-level leaf (same constraint
+// as attach), so this is a BRANCH wrapping one leaf: `crtr workspace enter`.
+import { execFile } from 'node:child_process';
+import { defineBranch, defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { getNode, listNodes } from '../core/canvas/index.js';
+import { inTmux, currentTmux, splitWindow, piCommand } from '../core/runtime/placement.js';
+const RAIL_WIDTH = 32;
+/** Newest LIVE (active|idle) forest root started in `cwd` — the default node the
+ *  chat pane attaches to when `--node` is omitted. A root has no parent inside
+ *  the cwd-scoped set. Returns null when this cwd has no live root. */
+function defaultChatNode(cwd) {
+    const rows = listNodes({ status: ['active', 'idle'] }).filter((r) => r.cwd === cwd);
+    if (rows.length === 0)
+        return null;
+    const ids = new Set(rows.map((r) => r.node_id));
+    const roots = rows.filter((r) => r.parent === null || !ids.has(r.parent));
+    const pool = roots.length > 0 ? roots : rows;
+    pool.sort((a, b) => (a.created < b.created ? 1 : -1)); // newest first
+    return pool[0].node_id;
+}
+const workspaceEnterLeaf = defineLeaf({
+    name: 'enter',
+    description: 'enter the editor view — a node rail beside a chat pane, in this window',
+    whenToUse: 'you want to work in the agent-centric editor layout: a left rail listing this graph + the other live agents in this working directory (with ⚑ inbox flags) beside a chat pane attached to a node. Selecting a node in the rail swaps it into the chat pane. Opens in the CURRENT tmux window. tmux-only.',
+    help: {
+        name: 'workspace enter',
+        summary: 'split the current window into a left node-rail (the workspace-sidebar view) + a chat pane (crtr attach); ↵ in the rail swaps a node into the chat. tmux-only.',
+        params: [
+            {
+                kind: 'flag',
+                name: 'node',
+                type: 'string',
+                required: false,
+                constraint: 'Node to attach in the chat pane. Default: the newest live root in this cwd (rail-only, empty chat, if none).',
+            },
+            {
+                kind: 'flag',
+                name: 'width',
+                type: 'int',
+                required: false,
+                default: RAIL_WIDTH,
+                constraint: `Rail width in columns (default ${RAIL_WIDTH}).`,
+            },
+        ],
+        output: [
+            { name: 'rail', type: 'string', required: false, constraint: 'tmux pane id of the rail.' },
+            { name: 'chat', type: 'string', required: false, constraint: 'node id attached in the chat pane (absent if none).' },
+            { name: 'note', type: 'string', required: false, constraint: 'Set only on the non-TTY/piped path.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Splits a narrow LEFT pane in the current window running the workspace-sidebar view.',
+            'Swaps the chosen (or default) node into the current pane as a chat (crtr node focus), relocating the current pane to the backstage.',
+            'Outside a TTY/tmux: prints a notice and exits 0 (no layout change).',
+        ],
+    },
+    run: async (input) => {
+        const node = input['node'];
+        const width = input['width'] ?? RAIL_WIDTH;
+        if (!process.stdout.isTTY) {
+            return { note: 'crtr workspace enter builds a tmux layout — run it in a tmux pane (a TTY), not a pipe.' };
+        }
+        if (!inTmux()) {
+            throw new InputError({
+                error: 'not_in_tmux',
+                message: 'crtr workspace is tmux-only — run it inside the crtr tmux session',
+                next: 'Open it from inside tmux.',
+            });
+        }
+        const here = currentTmux();
+        if (here === null) {
+            throw new InputError({
+                error: 'no_tmux_location',
+                message: 'could not resolve the current tmux pane',
+                next: 'Run this inside a tmux pane.',
+            });
+        }
+        // Resolve the chat node (explicit --node, else newest live root here).
+        let chatNode = null;
+        if (node !== undefined && node !== '') {
+            if (getNode(node) === null) {
+                throw new InputError({
+                    error: 'not_found',
+                    message: `no node: ${node}`,
+                    received: node,
+                    next: 'List nodes with `crtr node inspect list`.',
+                });
+            }
+            chatNode = node;
+        }
+        else {
+            chatNode = defaultChatNode(process.cwd());
+        }
+        // 1. The rail — a narrow split to the LEFT of here. It discovers the chat
+        //    pane itself (the @crtr_node tag), so no pane id is threaded in.
+        const railCmd = piCommand(['view', 'run', 'workspace-sidebar', '--target', here.pane], 'crtr');
+        const rail = splitWindow(here.pane, {
+            cwd: process.cwd(),
+            env: {},
+            command: railCmd,
+            before: true,
+            size: Math.max(16, width),
+        });
+        if (rail === null) {
+            throw new InputError({
+                error: 'split_failed',
+                message: 'tmux could not split the rail pane',
+                next: 'Check the tmux server is reachable, then retry.',
+            });
+        }
+        // 2. The chat — swap the node's attach viewer into here's slot. Best-effort:
+        //    the rail is already up, so a focus failure degrades to a rail-only view
+        //    the user can drive (↵ a node) rather than aborting the whole layout.
+        if (chatNode !== null) {
+            await new Promise((resolve) => {
+                execFile('crtr', ['node', 'focus', chatNode, '--pane', here.pane], () => resolve());
+            });
+        }
+        return chatNode !== null ? { rail, chat: chatNode } : { rail };
+    },
+    render: (result) => {
+        if (result['note'] !== undefined)
+            return String(result['note']);
+        const chat = result['chat'];
+        return chat !== undefined
+            ? `Workspace ready — rail ${result['rail']}, chat attached to ${chat}.`
+            : `Workspace ready — rail ${result['rail']}. No live agent here yet; press ↵ on a node in the rail to open one.`;
+    },
+});
+export function registerWorkspace() {
+    return defineBranch({
+        name: 'workspace',
+        rootEntry: {
+            concept: 'the agent-centric editor view — a node rail beside a chat pane, in one tmux window',
+            desc: 'enter the editor layout for attached headless nodes',
+            useWhen: 'you want an editor-style workspace in tmux: a left rail of this graph + other live agents in this cwd (with ⚑ inbox flags) next to a chat pane attached to a node, where selecting a node in the rail swaps it into the chat. tmux-only.',
+        },
+        help: {
+            name: 'workspace',
+            summary: 'enter the agent-centric editor view (node rail + chat pane) in the current tmux window',
+            model: '`enter` splits the current window into a narrow left rail (the workspace-sidebar view — this graph + other live agents in this cwd, ⚑ inbox flags) and a chat pane (`crtr attach`) attached to a node (--node, or the newest live root here). ↵ in the rail swaps the selected node into the chat pane. tmux-only; piped it prints a notice and exits 0.',
+        },
+        children: [workspaceEnterLeaf],
+    });
+}

package/dist/core/__tests__/broker-double-spawn.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/broker-double-spawn.test.js

@@ -0,0 +1,143 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/broker-double-spawn.test.ts
+//
+// BUG-REGRESSION (broker-universal-host cut, design §C "double-spawn verdict";
+// taste/broker-is-the-host). Two coupled invariants the cut introduced:
+//
+//   1. A pre-cut row carries host_kind='tmux' (or null). While its RAW pi pid is
+//      still ALIVE the daemon must NEVER relaunch it — a relaunch would put a
+//      SECOND vehicle on the same .jsonl (the double-spawn). Liveness is the
+//      recorded engine pid alone; an alive pid is always 'leave'.
+//   2. When that pid dies and the node revives, it comes back as a BROKER and the
+//      row's host_kind is lazily COERCED tmux→'broker' (reviveNode, revive.ts
+//      ~91-97) so inspect/history read honest values and the daemon never
+//      branches it back to a tmux host.
+//
+// Three legs, strongest→cheapest: the pure verdict (D1a), the direct reviveNode
+// coerce (D1b), and the full daemon integration over a real live→dead pid (D1c).
+// Regression check: if the cut's coerce is removed, D1b/D1c go RED (host_kind
+// stays 'tmux'); if an alive pid is ever revived, D1c's "no relaunch" asserts go
+// RED (cycles bumps / host_kind flips while the pid is still alive).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawn, spawnSync } from 'node:child_process';
+import { createHeadlessHarness } from './helpers/harness.js';
+import { createNode } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { reviveNode } from '../runtime/revive.js';
+import { livenessVerdict, isPidAlive } from '../../daemon/crtrd.js';
+// A pid reaped (dead) by the time spawnSync returns — the "dead but supervised"
+// pid the grace path judges.
+function deadPid() {
+    const r = spawnSync('true', [], { stdio: 'ignore' });
+    return r.pid ?? 0x7ffffffe;
+}
+/** Fabricate a PRE-CUT host_kind='tmux' row directly (the harness's
+ *  fabricateBrokerNode hardcodes host_kind:'broker', so we mirror its body here
+ *  with host_kind:'tmux' — no harness edit). The result is a row the daemon
+ *  supervises by pid exactly as a legacy tmux node would be. */
+function fabricateTmuxNode(o) {
+    const meta = {
+        node_id: o.id,
+        name: o.id,
+        created: new Date().toISOString(),
+        cwd: process.cwd(),
+        host_kind: 'tmux',
+        kind: 'developer',
+        mode: 'base',
+        lifecycle: 'terminal',
+        parent: null,
+        pi_session_id: o.pi_session_id,
+        status: 'active',
+        intent: null,
+        pi_pid: o.pi_pid,
+    };
+    createNode(meta);
+    closeDb();
+    return o.id;
+}
+// REVIVE_GRACE_MS is 20_000 (crtrd.ts); pick offsets well inside / well past it.
+const T_ALIVE = 6_000_000;
+const T_DEAD = 6_100_000; // first dead observation
+const T_PAST = T_DEAD + 25_000; // > 20s after first-observed-dead → revive
+// ---------------------------------------------------------------------------
+// D1a — pure verdict: an alive pid is NEVER relaunched (no double-spawn).
+// ---------------------------------------------------------------------------
+test('D1a livenessVerdict: an ALIVE pid is left alone (never a double-spawn); a DEAD pid pends then revives', () => {
+    assert.equal(livenessVerdict(true, null), 'leave', 'alive pid, first obs → leave');
+    assert.equal(livenessVerdict(true, 10_000_000), 'leave', 'alive pid is NEVER relaunched');
+    assert.equal(livenessVerdict(false, null), 'pending', 'dead, first obs → pending (double-spawn guard)');
+    assert.equal(livenessVerdict(false, 1_000), 'pending', 'dead, within grace → pending');
+    assert.equal(livenessVerdict(false, 10_000_000), 'revive', 'dead past grace → revive');
+});
+// ---------------------------------------------------------------------------
+// D1b — direct reviveNode coerce: a tmux row flips to 'broker' on revive.
+// ---------------------------------------------------------------------------
+test('D1b reviveNode coerces a pre-cut host_kind=tmux row to broker', async () => {
+    const h = await createHeadlessHarness({ sessionPrefix: 'crtr-d1b' });
+    try {
+        const id = fabricateTmuxNode({ id: 'd1b-node', pi_pid: deadPid(), pi_session_id: 'sess-d1b' });
+        assert.equal(h.node(id).host_kind, 'tmux', 'precondition: row is a legacy tmux host');
+        // reviveNode's lazy coerce runs at the top, before any launch (revive.ts ~91-97).
+        reviveNode(id, { resume: true });
+        assert.equal(h.node(id).host_kind, 'broker', 'tmux→broker coerced on revive (the daemon never branches it back)');
+    }
+    finally {
+        await h.dispose();
+    }
+});
+// ---------------------------------------------------------------------------
+// D1c — full integration: an ALIVE tmux pid is NOT relaunched; once it dies the
+// node revives as a broker (host_kind coerced, cycles bumped).
+// ---------------------------------------------------------------------------
+test('D1c daemon: a live tmux pi is never double-spawned; on death it revives as a broker', { timeout: 30_000 }, async () => {
+    const h = await createHeadlessHarness({ sessionPrefix: 'crtr-d1c' });
+    // A real live subprocess whose pid stands in for the raw pi vehicle.
+    const child = spawn('sleep', ['300'], { stdio: 'ignore' });
+    const livePid = child.pid;
+    try {
+        assert.equal(isPidAlive(livePid), true, 'precondition: the raw pi pid is alive');
+        // pi_session_id SET so the dead-pid path routes the crash/grace revive, NOT
+        // the never-booted boot-failure branch.
+        const id = fabricateTmuxNode({ id: 'd1c-node', pi_pid: livePid, pi_session_id: 'sess-d1c' });
+        assert.equal(h.node(id).host_kind, 'tmux', 'precondition: pre-cut tmux host');
+        assert.equal(h.node(id).cycles ?? 0, 0, 'no revive yet');
+        // --- TICK while the pi is ALIVE: must be a no-op. The daemon never
+        //     relaunches a live pid, so reviveNode is never called → NO coerce, NO
+        //     cycle bump, pid unchanged. This is the double-spawn guard. ---
+        await h.tick(T_ALIVE);
+        {
+            const n = h.node(id);
+            assert.equal(n.host_kind, 'tmux', 'live pid: host_kind NOT coerced (reviveNode never ran → no double-spawn)');
+            assert.equal(n.cycles ?? 0, 0, 'live pid: NO revive (cycles still 0)');
+            assert.equal(n.pi_pid, livePid, 'live pid: pi_pid unchanged — no second vehicle launched');
+        }
+        // Kill the raw pi and wait until the daemon would observe it dead.
+        child.kill('SIGKILL');
+        await h.waitFor(() => (isPidAlive(livePid) ? null : true), { label: 'raw pi dead', timeoutMs: 10_000 });
+        // --- TICK: first dead observation → pending (within grace). No revive. ---
+        await h.tick(T_DEAD);
+        {
+            const n = h.node(id);
+            assert.equal(n.cycles ?? 0, 0, 'first-observed-dead: pends, no revive yet');
+            assert.equal(n.host_kind, 'tmux', 'still tmux until the revive actually fires');
+        }
+        // --- TICK past the grace: the crash/grace revive fires → reviveNode coerces
+        //     host_kind tmux→broker and bumps cycles (observable instantly, the
+        //     model effect lands before the detached broker spawn — grace-clock). ---
+        await h.tick(T_PAST);
+        {
+            const n = h.node(id);
+            assert.equal(n.cycles ?? 0, 1, 'past grace: revived → cycles bumped to 1');
+            assert.equal(n.host_kind, 'broker', 'past grace: host_kind coerced tmux→broker on revive');
+        }
+    }
+    finally {
+        try {
+            child.kill('SIGKILL');
+        }
+        catch {
+            /* already gone */
+        }
+        await h.dispose();
+    }
+});

package/dist/core/__tests__/broker-fork-seam.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/broker-fork-seam.test.js

@@ -0,0 +1,102 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/broker-fork-seam.test.ts
+//
+// BUG-REGRESSION (broker-universal-host cut, design §B.broker; U1 report
+// mq8ftenr-5d55313d). Before the cut, the headless broker had NO fork path — its
+// session selection THREW `--fork is not supported by the headless broker`. After
+// the cut EVERY node is a broker, so `node new --fork-from <id>` would always hit
+// that throw. The fix routes the broker's fork through pi's REAL fork seam,
+// SessionManager.forkFrom (broker.ts buildBrokerSession, the `forking` branch) —
+// the same method pi's own `--fork` CLI flag uses.
+//
+// This test drives the BROKER's OWN fork branch (broker.ts buildBrokerSession,
+// the `forking` branch ~1106) end to end: it calls `buildBrokerSession` with
+// `cfg.forkFrom` set to a real source session .jsonl — the EXACT path a
+// `node new --fork-from <id>` boot takes through the broker — and asserts the
+// resulting live session is a genuine fork: a NEW session id (not a colliding
+// copy) and a `parentSession` header pointing at the source, with the source's
+// history copied in. Because it invokes `buildBrokerSession` (not
+// `SessionManager.forkFrom` directly), it goes RED if broker.ts's fork branch
+// reverts to `throw "--fork is not supported by the headless broker"` — it
+// guards its own stated regression.
+//
+// Like the C3/C4 real-SDK wiring tests, it drives the REAL engine (broker-sdk's
+// static SDK re-exports) — NOT the CRTR_BROKER_ENGINE fake the lifecycle suite
+// uses, whose fixture omits forkFrom and so could never exercise this branch. It
+// runs offline (fork + session/services assembly are all local: no network/auth).
+//
+// (fork.test.ts covers the pure argv/resolve layers — buildPiArgv emitting
+// `--fork`, resolveForkSource turning a ref into a path. THIS file covers the
+// broker runtime branch those layers feed.)
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createAgentSessionServices, createAgentSessionFromServices, SessionManager, VERSION, } from '../runtime/broker-sdk.js';
+import { buildBrokerSession } from '../runtime/broker.js';
+// The REAL engine — bypasses the CRTR_BROKER_ENGINE fake entirely (the whole
+// point: the fake omits forkFrom, so only the real SDK can prove the branch).
+const realEngine = {
+    createAgentSessionServices,
+    createAgentSessionFromServices,
+    SessionManager,
+    VERSION,
+};
+let dir;
+before(() => {
+    dir = mkdtempSync(join(tmpdir(), 'crtr-fork-seam-'));
+});
+after(() => {
+    rmSync(dir, { recursive: true, force: true });
+});
+/** A minimal but VALID pi session .jsonl (the exact on-disk shape v3 emits): a
+ *  `session` header line + two `message` entries. This is what a node that has
+ *  run a turn or two carries on disk — the source the broker forks from. */
+function writeSourceSession(path, srcId) {
+    const lines = [
+        JSON.stringify({ type: 'session', version: 3, id: srcId, timestamp: '2026-06-10T20:27:32.891Z', cwd: dir }),
+        JSON.stringify({ type: 'message', id: 'a42170e1', parentId: null, timestamp: '2026-06-10T20:27:32.893Z', message: { role: 'user', content: 'source turn one' } }),
+        JSON.stringify({ type: 'message', id: 'f309b932', parentId: 'a42170e1', timestamp: '2026-06-10T20:27:32.893Z', message: { role: 'assistant', content: 'source reply one' } }),
+    ];
+    writeFileSync(path, lines.join('\n') + '\n');
+    return 2; // entry count (the two message lines)
+}
+test('D2 broker fork branch: buildBrokerSession(cfg.forkFrom) yields a NEW id + parentSession header, copying history (never throws "fork not supported")', async () => {
+    // 1. A real source session on disk.
+    const srcFile = join(dir, 'src.jsonl');
+    const srcId = '019eb338-029b-7536-b3eb-d33bd6f641a8';
+    const srcEntryCount = writeSourceSession(srcFile, srcId);
+    // 2. Drive the BROKER's fork branch: buildBrokerSession with cfg.forkFrom set —
+    //    the same recipe a `node new --fork-from <id>` boot produces. The OLD broker
+    //    THREW in this branch ("--fork is not supported by the headless broker"), so
+    //    if broker.ts:~1106 reverts to that throw, this rejects and the test goes RED.
+    const cfg = { cwd: dir, extensionPaths: [], forkFrom: srcFile };
+    let session;
+    let resuming;
+    await assert.doesNotReject(async () => {
+        const built = await buildBrokerSession(realEngine, cfg);
+        session = built.session;
+        resuming = built.resuming;
+    }, 'the broker fork branch must NOT throw "fork is not supported by the headless broker"');
+    assert.ok(session !== undefined, 'buildBrokerSession returned a live session for the fork');
+    try {
+        // 3. A fork boots as a FRESH spawn (resuming=false) so the kickoff firstPrompt
+        //    fires — the new node gets the source history AND a new task to start on.
+        assert.equal(resuming, false, 'a fork is a fresh spawn (resuming=false) so the kickoff fires');
+        // 4. Real fork metadata on the broker's selected SessionManager, not a
+        //    colliding .jsonl copy.
+        const sm = session.sessionManager;
+        assert.notEqual(sm.getSessionId(), srcId, 'the fork is a NEW session id (not a copy that would collide on resume)');
+        const header = sm.getHeader();
+        assert.equal(header?.parentSession, srcFile, 'the fork header records parentSession pointing at the source .jsonl');
+        // 5. The source history is carried into the fork (fork copies, not empty
+        //    start). The broker boot may append its own session-start entry, so the
+        //    fork holds AT LEAST the source's messages — a naïve empty session would
+        //    have zero.
+        assert.ok(sm.getEntries().length >= srcEntryCount, `the fork carries the source conversation history forward ` +
+            `(>= ${srcEntryCount} source entries; got ${sm.getEntries().length})`);
+    }
+    finally {
+        session.dispose();
+    }
+});

package/dist/core/__tests__/broker-sdk-wiring.test.js

@@ -107,6 +107,7 @@ test('C2 — zero-viewer UI context resolves dialogs to deny/cancel immediately
             throw new Error('C2: must NOT forward a dialog when no controller is attached');
         },
         pending: new Map(),
+        broadcast: () => { },
     });
     // confirm() WITH a large timeout: the fix must resolve at once (deny), NOT after
     // the timeout — the old timeout-reliant path would have waited 60s (or, with no
@@ -144,6 +145,7 @@ test('M2 — a forwarded dialog stays pending on controller detach, resolving on
         },
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         pending: pending,
+        broadcast: () => { },
     });
     // Controller attached → confirm() forwards + registers a pending dialog (with the
     // request retained for welcome.pending_dialog / re-route, T4) and does NOT

package/dist/core/__tests__/broker-snapshot-history.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/broker-snapshot-history.test.js

@@ -0,0 +1,105 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/broker-snapshot-history.test.ts
+//
+// BUG-REGRESSION (real, observed; surfaced during the crouter-web build, proven
+// broker-side). After a revive resumes a previously-CLOSED pi session, the
+// broker's `welcome` snapshot must present the SAME ordered, complete turn
+// history the persisted session `.jsonl` holds — no omitted or reordered turn.
+//
+// ROOT CAUSE: the broker's `buildSnapshot` served `session.messages`
+// (= `agent.state.messages`, the agent's LIVE in-memory array). pi's recovery
+// paths — auto-retry, context-overflow recovery, and compaction — 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 a turn the `.jsonl` still
+// holds. crouter-web's static normalizer reads the full ordered history correctly
+// (pi `SessionManager.buildSessionContext` over the file), so a dormant viewer
+// saw the complete turn — then, after a revive, the broker's live welcome
+// snapshot served the diverged (omitted) array. The fix makes the snapshot
+// reconstruct from the persisted session tree (the SAME source the normalizer
+// uses), so live == persisted == disk (single source of truth).
+//
+// This drives the REAL pi SDK offline (no tmux, no broker process, no network) —
+// exactly the seam where the bug lives: it builds a real resumed broker session,
+// SIMULATES pi's retry slice by popping the last assistant off the live
+// `agent.state.messages` (leaving the persisted tree intact), and asserts the
+// snapshot follows the persisted history, not the sliced live array.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createAgentSessionServices, createAgentSessionFromServices, SessionManager, VERSION, } from '../runtime/broker-sdk.js';
+import { buildBrokerSession, snapshotMessages } from '../runtime/broker.js';
+const realEngine = {
+    createAgentSessionServices,
+    createAgentSessionFromServices,
+    SessionManager,
+    VERSION,
+};
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function userMsg(text) {
+    return { role: 'user', content: [{ type: 'text', text }] };
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function assistantMsg(text, stopReason = 'stop') {
+    return {
+        role: 'assistant',
+        content: [{ type: 'text', text }],
+        api: 'anthropic-messages',
+        provider: 'anthropic',
+        model: 'sonnet',
+        usage: { input: 1, output: 1, cacheRead: 0, cacheWrite: 0, totalTokens: 2, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+        stopReason,
+        timestamp: Date.now(),
+    };
+}
+test('broker welcome snapshot serves the persisted history, not pi\u2019s sliced live array (omit-on-revive regression)', async () => {
+    const cwd = mkdtempSync(join(tmpdir(), 'crtr-snaphist-'));
+    try {
+        // 1. Build a real persisted session whose tail mimics an auto-retried turn:
+        //    user \u2192 errored assistant (kept on disk) \u2192 retried assistant. This is what
+        //    pi's `.jsonl` holds after a retryable error (529 / overflow / network).
+        const seed = SessionManager.create(cwd);
+        seed.appendMessage(userMsg('q1'));
+        seed.appendMessage(assistantMsg('a1'));
+        seed.appendMessage(userMsg('q2 — triggers a retryable error'));
+        seed.appendMessage(assistantMsg('errored attempt', 'error')); // kept in session for history
+        seed.appendMessage(assistantMsg('retried answer')); // the successful retry
+        const sessionFile = seed.getSessionFile();
+        assert.ok(sessionFile, 'seed session persisted a .jsonl');
+        // The persisted, ordered history a dormant reader / crouter-web normalizer sees.
+        const persisted = SessionManager.open(sessionFile).buildSessionContext().messages;
+        assert.equal(persisted.length, 5, 'disk holds all five messages incl. the errored attempt');
+        // 2. Revive: the broker resumes the closed session via the SERVICES path.
+        const { session } = await buildBrokerSession(realEngine, {
+            cwd,
+            extensionPaths: [],
+            resumeSessionPath: sessionFile,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        });
+        try {
+            assert.equal(session.messages.length, 5, 'at boot the live array == persisted history');
+            // 3. Simulate pi's auto-retry/overflow slice: it removes the errored
+            //    assistant from agent.state.messages but KEEPS it on disk. We reproduce
+            //    that exact mutation on the live array (the persisted tree is untouched).
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const live = session.agent.state.messages;
+            const popped = live.pop(); // drop the last assistant from the LIVE array only
+            assert.equal(popped.role, 'assistant', 'sliced an assistant off the live array');
+            assert.equal(session.messages.length, 4, 'the live array now OMITS the persisted turn');
+            // 4. The bug: pre-fix `buildSnapshot` served `session.messages` (4) \u2014 omitting
+            //    a turn the .jsonl still holds. The fix serves the persisted history (5),
+            //    byte-identical to the normalizer.
+            const snap = snapshotMessages(session);
+            assert.equal(snap.length, persisted.length, 'snapshot presents the COMPLETE persisted history (omit-on-revive regression)');
+            assert.notEqual(snap.length, session.messages.length, 'snapshot does NOT echo the sliced live array');
+            assert.deepEqual(snap, persisted, 'snapshot is byte-identical to the static normalizer\u2019s buildSessionContext (single source of truth)');
+        }
+        finally {
+            session.dispose();
+        }
+    }
+    finally {
+        rmSync(cwd, { recursive: true, force: true });
+    }
+});