@crouton-kit/crouter 0.3.18 → 0.3.20

package/dist/commands/view-run.js

@@ -0,0 +1,191 @@
+// `crtr view run <name>` — resolve, load, and host a view.
+//
+// Resolves the view across scopes (project→user→builtin), dynamically imports
+// it, then hands it to the core/tui host. The host owns the screen and the
+// non-TTY path: when stdin is NOT a TTY it prints view.dump(state) and exits 0,
+// so `crtr view run <name> | cat` works anywhere. The interactive path is
+// tmux-only (crtr is tmux-only) — outside tmux with a TTY we notify + no-op,
+// never a non-tmux fallback. --port / --target forward verbatim onto
+// host.options (camelCased, stringified); crtr does not interpret them.
+//
+// --window / --split open the view as a PERSISTENT MONITOR instead of taking
+// over the current pane: --window in a new background (non-focus-stealing)
+// tmux window, --split in a right-hand split of the current pane. Both shell a
+// plain inner `crtr view run <name>` into the new pane, which hosts the view
+// there and self-tags the pane with @crtr_view so the Alt+V then ]/[ view-cycle
+// can flip it to the next/prev view in place. Both are tmux-only by nature; in
+// a pipe (non-TTY) placement is meaningless, so they degrade to the static dump.
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { runView } from '../core/tui/host.js';
+import { resolveView, loadView, listViews } from '../core/tui/loader.js';
+// Commands reach the tmux driver through placement.ts (the sanctioned
+// model-over-driver seam, §5.1) — never `./tmux.js` directly.
+import { inTmux, currentTmux, openNodeWindow, splitWindow, piCommand, setPaneOption, } from '../core/runtime/placement.js';
+export const viewRunLeaf = defineLeaf({
+    name: 'run',
+    description: 'resolve, load, and host a view (in this pane, a new window, or a split)',
+    whenToUse: 'you want to OPEN a view by name — a full-screen raw-ANSI surface. By default it hosts in the current pane (tmux-only interactive; piped it prints a static snapshot). Pass --window to open it as a background monitor window, or --split to open it beside the current pane — both leave you where you are so a view becomes a live monitor you flip between with Alt+V then ]/[. Pass --port/--target to forward connection details. Use `crtr view list` first to see what is available, or `crtr view new` to scaffold one',
+    help: {
+        name: 'view run',
+        summary: 'host a view in the current pane, a new window (--window), or a split (--split); outside a TTY it prints the view\'s static dump and exits 0',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'View id to run (its directory name). Resolves project→user→builtin.' },
+            { kind: 'flag', name: 'window', type: 'bool', required: false, constraint: 'Open the view in a NEW background tmux window (non-focus-stealing) instead of the current pane — a persistent monitor. tmux-only; ignored (static dump) in a pipe. Mutually exclusive with --split.' },
+            { kind: 'flag', name: 'split', type: 'bool', required: false, constraint: 'Open the view in a right-hand SPLIT of the current pane instead of taking it over — a side-by-side monitor. tmux-only; ignored (static dump) in a pipe. Mutually exclusive with --window.' },
+            { kind: 'flag', name: 'port', type: 'int', required: false, constraint: 'Forwarded verbatim to the view as options.port (e.g. a CDP debugging port).' },
+            { kind: 'flag', name: 'target', type: 'string', required: false, constraint: 'Forwarded verbatim to the view as options.target (e.g. a browser tab id).' },
+        ],
+        output: [
+            { name: 'hosted', type: 'string', required: false, constraint: 'For --window/--split: "window" or "split" — where the monitor opened. Absent for an in-pane host (which holds the terminal until you quit).' },
+            { name: 'view', type: 'string', required: false, constraint: 'The view id opened (only on the --window/--split path).' },
+            { name: 'window', type: 'string', required: false, constraint: 'The new tmux window id (--window only).' },
+            { name: 'pane', type: 'string', required: false, constraint: 'The new tmux pane id (--window/--split).' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Default (no flag) inside a TTY+tmux: takes over the current pane in raw mode (alt-screen) until you quit (q/Ctrl-C), and tags the pane @crtr_view=<name> so Alt+V then ]/[ can cycle it.',
+            '--window: opens a new background tmux window running the view (does not steal focus); returns immediately.',
+            '--split: opens a right-hand split of the current pane running the view; you stay in your pane.',
+            'Outside a TTY: writes the view\'s static dump to stdout and exits 0 (no raw mode); --window/--split degrade to this.',
+            'Forwards --port/--target onto host.options for the view; mutates nothing on the canvas.',
+        ],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const port = input['port'];
+        const target = input['target'];
+        const asWindow = input['window'] === true;
+        const asSplit = input['split'] === true;
+        if (asWindow && asSplit) {
+            throw new InputError({
+                error: 'conflicting_flags',
+                message: '--window and --split are mutually exclusive',
+                next: 'Pass at most one: --window (new background window) or --split (split the current pane).',
+            });
+        }
+        const r = resolveView(name);
+        if (r === null) {
+            const avail = listViews().map((v) => v.id);
+            throw new InputError({
+                error: 'view_not_found',
+                message: `no view: ${name}`,
+                received: name,
+                next: avail.length > 0
+                    ? `Available views: ${avail.join(', ')}. Or scaffold one with \`crtr view new ${name}\`.`
+                    : `No views found. Scaffold one with \`crtr view new ${name}\`.`,
+            });
+        }
+        const options = {};
+        if (port !== undefined)
+            options.port = String(port);
+        if (target !== undefined)
+            options.target = target;
+        // --window / --split: open the view as a persistent monitor in a new pane.
+        if (asWindow || asSplit) {
+            // Placement is tmux-only. In a pipe (non-TTY) it is meaningless — degrade
+            // to the static dump (runView handles the non-TTY path internally).
+            if (!process.stdin.isTTY) {
+                const v = await loadView(r);
+                await runView(v, { options });
+                return;
+            }
+            if (!inTmux()) {
+                throw new InputError({
+                    error: 'not_in_tmux',
+                    message: '--window/--split are tmux-only — run crtr inside its tmux session',
+                    next: `Open it from inside tmux, or drop the flag to host in the current pane (or pipe for a snapshot: \`crtr view run ${name} | cat\`).`,
+                });
+            }
+            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.',
+                });
+            }
+            // The inner command re-enters this leaf with NO placement flag, so it
+            // hosts the view in its own (new) pane and self-tags it via @crtr_view.
+            const argv = ['view', 'run', name];
+            if (port !== undefined)
+                argv.push('--port', String(port));
+            if (target !== undefined)
+                argv.push('--target', target);
+            const command = piCommand(argv, 'crtr');
+            const cwd = process.cwd();
+            if (asWindow) {
+                const win = openNodeWindow({ session: here.session, name: `view:${name}`, cwd, env: {}, command });
+                if (win === null) {
+                    throw new InputError({
+                        error: 'window_open_failed',
+                        message: `tmux could not open a window for view ${name}`,
+                        next: 'Check the tmux server is reachable, then retry.',
+                    });
+                }
+                return { hosted: 'window', view: name, window: win.window, pane: win.pane };
+            }
+            // --split: a right-hand split (-h, the splitWindow default); -d keeps you put.
+            const pane = splitWindow(here.pane, { cwd, env: {}, command });
+            if (pane === null) {
+                throw new InputError({
+                    error: 'split_failed',
+                    message: `tmux could not split the pane for view ${name}`,
+                    next: 'Check the tmux server is reachable, then retry.',
+                });
+            }
+            return { hosted: 'split', view: name, pane };
+        }
+        const v = await loadView(r);
+        // The interactive path is tmux-only; the piped/non-TTY dump path works
+        // anywhere (runView handles it internally), so only guard when stdin is a
+        // TTY. Outside tmux with a TTY: notify + no-op — never a non-tmux fallback.
+        if (process.stdin.isTTY && !inTmux()) {
+            throw new InputError({
+                error: 'not_in_tmux',
+                message: 'crtr view is tmux-only — run it inside the crtr tmux session',
+                next: `Open it from inside tmux (e.g. the /view popup), or pipe for a static snapshot: \`crtr view run ${name} | cat\`.`,
+            });
+        }
+        // Self-tag this pane with the view id (+ any forwarded --port/--target) so
+        // the Alt+V then ]/[ view-cycle can switch it to the next/prev view in place
+        // AND replay the connection params it was opened with. Best-effort; tmux-only.
+        const tagPane = (process.stdin.isTTY && inTmux())
+            ? (process.env['TMUX_PANE'] ?? currentTmux()?.pane)
+            : undefined;
+        if (tagPane !== undefined && tagPane !== '') {
+            try {
+                setPaneOption(tagPane, '@crtr_view', name);
+                setPaneOption(tagPane, '@crtr_view_port', port !== undefined ? String(port) : '');
+                setPaneOption(tagPane, '@crtr_view_target', target ?? '');
+            }
+            catch { /* best-effort */ }
+        }
+        try {
+            await runView(v, { options });
+        }
+        finally {
+            // On a clean quit (q) runView returns to the shell/pi that launched this
+            // pane — clear the monitor tag so a stray Alt+V ]/[ can't respawn-pane -k
+            // (and kill) whatever now owns the pane. When the cycle itself replaces
+            // this view it SIGKILLs us mid-await (this finally never runs); cycle + the
+            // new view-run re-tag, so that path stays correct.
+            if (tagPane !== undefined && tagPane !== '') {
+                try {
+                    setPaneOption(tagPane, '@crtr_view', '');
+                }
+                catch { /* best-effort */ }
+            }
+        }
+    },
+    render: (result) => {
+        const hosted = result['hosted'];
+        if (hosted === 'window') {
+            return `<view-opened mode="window" view="${result['view']}" window="${result['window']}" pane="${result['pane']}"/>`;
+        }
+        if (hosted === 'split') {
+            return `<view-opened mode="split" view="${result['view']}" pane="${result['pane']}"/>`;
+        }
+        return '';
+    },
+});

package/dist/commands/view.d.ts

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

package/dist/commands/view.js

@@ -0,0 +1,29 @@
+// `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.
+import { defineBranch } from '../core/command.js';
+import { viewListLeaf } from './view-list.js';
+import { viewRunLeaf } from './view-run.js';
+import { viewCycleLeaf } from './view-cycle.js';
+import { viewNewLeaf } from './view-new.js';
+import { viewPickLeaf } from './view-pick.js';
+export function registerView() {
+    return defineBranch({
+        name: 'view',
+        rootEntry: {
+            concept: 'switchable raw-ANSI terminal views — full-screen surfaces hosted in a pane, each a self-contained module',
+            desc: 'list, run, and author TUI views',
+            useWhen: 'you want a live full-screen surface (a monitor, an inbox, a dashboard) rather than one-shot command output — run a view by name, list what exists, or scaffold a new one. Views have no pi session; they render + take keystrokes until you quit.',
+        },
+        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.',
+        },
+        children: [viewListLeaf, viewRunLeaf, viewCycleLeaf, viewNewLeaf, viewPickLeaf],
+    });
+}

package/dist/core/__tests__/broker-attach-limits.test.d.ts

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

package/dist/core/__tests__/broker-attach-limits.test.js

@@ -0,0 +1,157 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/broker-attach-limits.test.ts
+//
+// T8 — the `crtr attach` acceptance gate, gates G4/G7/G8/G9 (controller
+// arbitration, decoder overflow caps, backpressure shedding, and the load-bearing
+// ONE-WRITER proof). Split out of broker-lifecycle.test.ts (see its header for
+// the full file map); the tests are the original acceptance gate, unchanged, on
+// their own isolated harness. Each test drives the REAL detached broker process +
+// REAL view.sock with the enriched fake engine, using the PRODUCTION
+// ViewSocketClient (helpers/broker-clients.ts) as the controller/observer — raw
+// node:net only where the client lifecycle is awkward (G7 oversized line, G8
+// stalled viewer). The engine is hosted IN-PROCESS by the broker, so engine pid
+// == broker pid == node.pi_pid == boot.pid.
+import { test, before, after, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { join } from 'node:path';
+import { createHarness, hasTmux } from './helpers/harness.js';
+import { isPidAlive } from '../canvas/pid.js';
+import { createAttachKit, delay, tok, frameHas, brokerLogText, lsofHolders, } from './helpers/broker-clients.js';
+let h;
+let root;
+const kit = createAttachKit(() => h);
+const { attach, attachUntil, connectRaw } = kit;
+before(async () => {
+    if (!hasTmux())
+        return;
+    h = await createHarness({ sessionPrefix: 'crtr-brklim' });
+    root = h.spawnRoot('broker-attach-limits suite root');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+afterEach(() => {
+    kit.closeAll();
+});
+const brokerPid = (id) => h.node(id).pi_pid;
+// ---------------------------------------------------------------------------
+// G4 — arbitration + observer read. Guards: 2nd client is admitted observer, an
+// observer prompt is rejected not_controller, BOTH clients receive the relay.
+// Failure mode: two controllers, or an observer driving the engine, or fan-out
+// that misses a viewer.
+// ---------------------------------------------------------------------------
+test('G4 — second client is observer; observer prompt → error{not_controller}; both receive the stream', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — G4');
+    const c1 = await attach(id, 'controller', 'g4-ctrl');
+    assert.equal(c1.welcome.role, 'controller', 'first client holds control');
+    const c2 = await attach(id, 'controller', 'g4-second'); // requests control; held → observer
+    assert.equal(c2.welcome.role, 'observer', 'second client is admitted read-only observer (first-attach-wins)');
+    c2.send({ type: 'prompt', text: 'observer must not drive' });
+    const err = await c2.waitFrame((f) => f.type === 'error', 'G4 observer prompt rejected');
+    assert.equal(err.code, 'not_controller', 'G4: observer prompt → error{not_controller}');
+    const token = tok('G4-BROADCAST');
+    c1.send({ type: 'prompt', text: token });
+    await c1.waitFrame((f) => f.type === 'agent_end' && frameHas(f, token), 'G4 controller received the stream');
+    await c2.waitFrame((f) => f.type === 'agent_end' && frameHas(f, token), 'G4 observer ALSO received the stream');
+});
+// ---------------------------------------------------------------------------
+// G7 — decoder overflow (guards C5 OOM). A client line over BROKER_READ_CAPS is
+// cap-and-dropped; the broker survives and other clients are unaffected. Failure
+// mode: an unbounded decoder buffer growing the broker to OOM.
+// ---------------------------------------------------------------------------
+test('G7 — an oversized client line is dropped (frame_overflow), the broker survives, other clients unaffected', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — G7');
+    const pid = brokerPid(id);
+    const boots = h.bootCount(id);
+    const survivor = await attach(id, 'observer', 'g7-survivor');
+    // 26 MiB with NO newline > BROKER_READ_CAPS.maxLineBytes (24 MiB) → the bounded
+    // FrameDecoder throws FrameOverflowError; the broker drops the peer.
+    const bad = await connectRaw(id, { read: true });
+    bad.writeRaw(Buffer.alloc(26 * 1024 * 1024, 0x78));
+    await bad.waitClosed('G7 oversized peer dropped by the broker');
+    await h.waitFor(() => /frame overflow/.test(brokerLogText(h, id)) || null, { label: 'G7 broker logged the frame-overflow drop' });
+    // The broker survives and the other client is unaffected: a fresh turn relays.
+    const token = tok('G7-AFTER');
+    h.fakeCmd(id, { cmd: 'stream', text: token });
+    await survivor.waitFrame((f) => f.type === 'agent_end' && frameHas(f, token), 'G7 survivor still receives live frames');
+    assert.equal(isPidAlive(pid), true, 'G7: the broker survived the overflow');
+    assert.equal(brokerPid(id), pid, 'G7: broker pid unchanged');
+    assert.equal(h.bootCount(id), boots, 'G7: no reboot');
+});
+// ---------------------------------------------------------------------------
+// G8 — backpressure leak (guards M1). A stalled (non-reading) viewer is shed at
+// the HWM (32 MiB byte cap) while the broker + other viewers are unaffected.
+// Failure mode: an indefinitely-growing per-viewer queue (broker OOM) or a slow
+// viewer back-pressuring the shared engine.
+// ---------------------------------------------------------------------------
+test('G8 — a stalled viewer is dropped at the backpressure HWM; the broker + fast viewers are unaffected', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — G8');
+    const pid = brokerPid(id);
+    const fast = await attach(id, 'observer', 'g8-fast'); // reads normally
+    // A helloed viewer that NEVER reads (paused socket). It must be in the broadcast
+    // set before the flood; hello, then a short beat for the broker to process it.
+    const stalled = await connectRaw(id, { read: false });
+    stalled.send({ type: 'hello', role: 'observer', client_id: 'g8-stalled' });
+    await delay(400);
+    // A fast event stream: ~60 MiB across 240 message_update frames. The stalled
+    // viewer's per-viewer backlog crosses the 32 MiB byte cap → dropped; the fast
+    // viewer drains between frames (per-update yield) and survives.
+    //
+    // The DROP SIGNAL is the broker's own log line, NOT the stalled socket's 'close':
+    // a PAUSED node socket does not surface the peer FIN/close until it is resumed,
+    // so the broker-side `backpressure high-water mark exceeded` line is the
+    // deterministic, race-free proof that the slow viewer was shed at the HWM.
+    const token = tok('G8-FLOOD');
+    h.fakeCmd(id, { cmd: 'stream', text: token, updates: 240, padBytes: 256 * 1024, tool: false });
+    await h.waitFor(() => /backpressure high-water mark exceeded/.test(brokerLogText(h, id)) || null, { label: 'G8 broker shed the stalled viewer at the HWM', timeoutMs: 30_000 });
+    // The fast viewer drained the WHOLE stream (agent_end is the terminal frame) —
+    // proving only the stalled viewer was shed, while the fast one was unaffected.
+    await fast.waitFrame((f) => f.type === 'agent_end' && frameHas(f, token), 'G8 fast viewer received the whole stream', 30_000);
+    assert.equal(isPidAlive(pid), true, 'G8: the broker survived the slow-viewer flood');
+    assert.equal(brokerPid(id), pid, 'G8: broker pid unchanged (the engine was not back-pressured into a restart)');
+});
+// ---------------------------------------------------------------------------
+// G9 — the load-bearing ONE-WRITER assertion. Across attach→detach→reattach the
+// broker pid AND engine pid (the same, in-process) are UNCHANGED and no second
+// engine is ever spawned; the viewer holds ONLY the socket (never the .jsonl).
+// Failure mode: a viewer that spawns/forks a second engine or opens the session
+// .jsonl — the corruption the headless design exists to prevent.
+// ---------------------------------------------------------------------------
+test('G9 — one-writer: broker/engine pid stable across attach→detach→reattach; no second engine; viewer holds only the socket', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — G9');
+    const pid0 = brokerPid(id);
+    const boots0 = h.bootCount(id);
+    const c1 = await attach(id, 'controller', 'g9-a');
+    const a = tok('G9-A');
+    c1.send({ type: 'prompt', text: a });
+    await c1.waitFrame((f) => f.type === 'agent_end' && frameHas(f, a), 'G9 first turn relayed');
+    c1.send({ type: 'bye' });
+    c1.close();
+    await delay(300);
+    assert.equal(brokerPid(id), pid0, 'G9: broker/engine pid unchanged after detach');
+    assert.equal(isPidAlive(pid0), true, 'G9: the one engine is still alive after detach');
+    assert.equal(h.bootCount(id), boots0, 'G9: no second engine spawned across detach');
+    // attachUntil (not a fixed sleep) synchronizes on the controller handoff: the
+    // detach's controllerId=null lands a beat after close, so retry until the
+    // reattach is admitted controller before driving the second prompt.
+    const c2 = await attachUntil(id, 'controller', 'g9-b', (x) => x.welcome.role === 'controller', 'G9 reattach re-takes control');
+    assert.equal(c2.welcome.role, 'controller', 'G9: the reattached client drives the SAME engine as controller');
+    const b = tok('G9-B');
+    c2.send({ type: 'prompt', text: b });
+    await c2.waitFrame((f) => f.type === 'agent_end' && frameHas(f, b), 'G9 reattached controller drives the SAME engine');
+    assert.equal(brokerPid(id), pid0, 'G9: STILL the same broker/engine pid after reattach (one writer, never two)');
+    assert.equal(isPidAlive(pid0), true, 'G9: the single engine is alive across the full cycle');
+    assert.equal(h.bootCount(id), boots0, 'G9: exactly one engine boot across attach→detach→reattach');
+    // fd-check (best-effort): the viewer host (this test process) must NOT hold the
+    // session .jsonl — only the broker may. With the fake engine the .jsonl is not
+    // held open continuously, so the meaningful assertion is that the VIEWER never
+    // appears among its holders (and any holder that exists is the broker).
+    const jsonl = join(h.home, 'nodes', id, 'fake-session.jsonl');
+    const holders = lsofHolders(jsonl);
+    if (holders !== null) {
+        assert.ok(!holders.includes(process.pid), 'G9: the attach client (this process) does NOT hold the session .jsonl');
+        for (const holder of holders) {
+            assert.equal(holder, pid0, 'G9: the ONLY holder of the session .jsonl is the broker/engine');
+        }
+    }
+});

package/dist/core/__tests__/broker-attach-stream.test.d.ts

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

package/dist/core/__tests__/broker-attach-stream.test.js

@@ -0,0 +1,125 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/broker-attach-stream.test.ts
+//
+// T8 — the `crtr attach` acceptance gate, gates G1/G1b/G2/G3 (controller drive,
+// relay/coalescing, detach survival, catch-up snapshot). Split out of
+// broker-lifecycle.test.ts (see its header for the full file map); the tests are
+// the original acceptance gate, unchanged, on their own isolated harness. Each
+// test drives the REAL detached broker process + REAL view.sock with the enriched
+// fake engine, using the PRODUCTION ViewSocketClient (helpers/broker-clients.ts)
+// as the controller/observer. The engine is hosted IN-PROCESS by the broker, so
+// engine pid == broker pid == node.pi_pid == boot.pid; "engine pid unchanged" ==
+// broker pid unchanged + no new boot. Each test's lead comment names its gate #
+// and the failure mode it guards.
+import { test, before, after, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { createHarness, hasTmux } from './helpers/harness.js';
+import { isPidAlive } from '../canvas/pid.js';
+import { createAttachKit, delay, tok, frameHas } from './helpers/broker-clients.js';
+let h;
+let root;
+const kit = createAttachKit(() => h);
+const { attach, attachUntil } = kit;
+before(async () => {
+    if (!hasTmux())
+        return;
+    h = await createHarness({ sessionPrefix: 'crtr-brkstrm' });
+    root = h.spawnRoot('broker-attach-stream suite root');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+afterEach(() => {
+    kit.closeAll();
+});
+const brokerPid = (id) => h.node(id).pi_pid;
+// ---------------------------------------------------------------------------
+// G1 — controller drive + live relay. Guards: a controller's `prompt` runs the
+// engine AND the streaming AgentSessionEvents are fanned out to the client
+// VERBATIM. Failure mode: a broken relay/fan-out (viewer sees nothing).
+// ---------------------------------------------------------------------------
+test('G1 — controller prompt runs the engine and the streamed AgentSessionEvents relay to the client', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — G1');
+    const c = await attach(id, 'controller', 'g1-ctrl');
+    assert.equal(c.welcome.role, 'controller', 'first controller is admitted as controller');
+    const token = tok('G1-PROMPT');
+    c.send({ type: 'prompt', text: token });
+    // The full streaming turn relays: agent_end carrying the token proves the turn
+    // ran AND its terminal frame reached the client; the intermediate types prove
+    // the stream (not just a final blob) was fanned out.
+    await c.waitFrame((f) => f.type === 'agent_end' && frameHas(f, token), 'G1 agent_end carrying the prompt token');
+    for (const t of ['message_start', 'message_update', 'tool_execution_start', 'tool_execution_end', 'message_end', 'turn_end', 'agent_start', 'turn_start']) {
+        assert.ok(c.frames.some((f) => f.type === t), `G1: client received a relayed ${t} frame`);
+    }
+    assert.ok(c.frames.some((f) => f.type === 'message_start' && frameHas(f, token)), 'G1: a relayed message carries the prompt token');
+});
+// ---------------------------------------------------------------------------
+// G1b — message_update coalescing preserves ordering (regression for the F2
+// attach typing-lag fix, 2026-06-09). The broker holds the latest message_update
+// on a ~75ms timer; any OTHER event must flush it FIRST, so a viewer can never
+// observe message_update AFTER its message_end (which would resurrect stale
+// streaming text over the final message), and the LAST coalesced update must not
+// be silently dropped at end-of-turn. Failure modes: a flush ordered after the
+// non-update event, or a pending update discarded when message_end wins the race.
+// ---------------------------------------------------------------------------
+test('G1b — coalesced message_update never arrives after message_end; updates still relayed', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — G1b');
+    const c = await attach(id, 'controller', 'g1b-ctrl');
+    const token = tok('G1B');
+    // 12 updates at the fake engine's setImmediate pace — far faster than the 75ms
+    // coalesce window, so coalescing genuinely engages (fewer relayed than emitted).
+    h.fakeCmd(id, { cmd: 'stream', text: token, updates: 12 });
+    await c.waitFrame((f) => f.type === 'agent_end' && frameHas(f, token), 'G1b turn relayed');
+    const types = c.frames.map((f) => f.type);
+    const lastUpdate = types.lastIndexOf('message_update');
+    const msgEnd = types.indexOf('message_end');
+    assert.ok(lastUpdate >= 0, 'G1b: at least one message_update relayed (coalescing must not starve updates)');
+    assert.ok(msgEnd >= 0, 'G1b: message_end relayed');
+    assert.ok(lastUpdate < msgEnd, `G1b: a message_update arrived AFTER message_end (update@${lastUpdate} vs end@${msgEnd}) — the coalescer flushed out of order`);
+    // tool/turn/agent frames must also never precede a stale held update.
+    for (const t of ['tool_execution_start', 'turn_end', 'agent_end']) {
+        const i = types.indexOf(t);
+        assert.ok(i < 0 || lastUpdate < i, `G1b: message_update relayed after ${t}`);
+    }
+});
+// ---------------------------------------------------------------------------
+// G2 — detach leaves the engine running. Guards: `bye`/close drops ONE listener,
+// never the engine. Failure mode: a detach that disposes the broker/engine.
+// ---------------------------------------------------------------------------
+test('G2 — detach (bye+close) leaves the broker alive + the engine still emitting; engine pid unchanged', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — G2');
+    const pid = brokerPid(id);
+    const boots = h.bootCount(id);
+    const c = await attach(id, 'controller', 'g2-ctrl');
+    const p = tok('G2-PROMPT');
+    c.send({ type: 'prompt', text: p });
+    await c.waitFrame((f) => f.type === 'agent_end' && frameHas(f, p), 'G2 turn relayed before detach');
+    c.send({ type: 'bye' });
+    c.close();
+    await delay(300); // let the broker process the 'close'
+    assert.equal(isPidAlive(pid), true, 'G2: broker still alive after detach');
+    assert.equal(brokerPid(id), pid, 'G2: engine (== broker) pid UNCHANGED across detach');
+    assert.equal(h.bootCount(id), boots, 'G2: no reboot — no second engine spawned');
+    // Still emitting: drive a turn with no client, then a fresh observer's snapshot
+    // carries it (the engine kept running and processing after the detach).
+    const after = tok('G2-AFTER-DETACH');
+    h.fakeCmd(id, { cmd: 'stream', text: after });
+    const o = await attachUntil(id, 'observer', 'g2-obs', (a) => JSON.stringify(a.welcome.snapshot.messages).includes(after), 'G2 post-detach message in snapshot');
+    assert.ok(o.welcome.snapshot.messages.length > 0, 'G2: the engine produced a message after the detach');
+    assert.equal(isPidAlive(pid), true, 'G2: broker still alive after the post-detach turn');
+});
+// ---------------------------------------------------------------------------
+// G3 — catch-up snapshot. Guards: messages produced with NO viewer attached are
+// in welcome.snapshot on reattach, and live events resume. Failure mode: a viewer
+// that reattaches blind to history / gets no further events.
+// ---------------------------------------------------------------------------
+test('G3 — messages produced while detached appear in welcome.snapshot on reattach; live events resume', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — G3');
+    const past = tok('G3-DETACHED');
+    h.fakeCmd(id, { cmd: 'stream', text: past }); // produced with zero viewers attached
+    const o = await attachUntil(id, 'observer', 'g3-obs', (a) => JSON.stringify(a.welcome.snapshot.messages).includes(past), 'G3 detached message in snapshot');
+    assert.ok(JSON.stringify(o.welcome.snapshot.messages).includes(past), 'G3: welcome.snapshot.messages contains the message produced while detached');
+    const live = tok('G3-LIVE');
+    h.fakeCmd(id, { cmd: 'stream', text: live });
+    await o.waitFrame((f) => f.type === 'agent_end' && frameHas(f, live), 'G3 live events resume after reattach');
+});

package/dist/core/__tests__/broker-crash-teardown.test.d.ts

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

package/dist/core/__tests__/broker-crash-teardown.test.js

@@ -0,0 +1,116 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/broker-crash-teardown.test.ts
+//
+// Broker crash / teardown / boot-failure — acceptance items 4–6 of the headless-
+// broker migration plus the M-1/M-2 boot-failure regression. Split out of
+// broker-lifecycle.test.ts (see its header for the full file map); the tests are
+// the original acceptance gate, unchanged, on their own isolated harness:
+//   4 survive a broker crash via grace-revive RESUME on the saved .jsonl         → "CRASH"
+//   5 tear down cleanly — close → shutdown frame → exit, socket unlinked         → "clean teardown"
+//   6 ONE-WRITER (R2) — never two engine pids alive across crash→grace-revive    → "CRASH"
+//   M-1/M-2 a broker that dies before session_start is reaped, not stranded      → "boot failure"
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHarness, hasTmux } from './helpers/harness.js';
+import { isPidAlive } from '../canvas/pid.js';
+import { FAIL_BEFORE_SESSION_START } from './fixtures/fake-engine.js';
+// crtrd.ts module const (not exported). The fresh-pi-boot grace window the daemon
+// waits before grace-reviving a pi observed dead. Reference: crtrd.ts
+// `REVIVE_GRACE_MS = 20_000`.
+const REVIVE_GRACE_MS = 20_000;
+let h;
+let root;
+before(async () => {
+    if (!hasTmux())
+        return;
+    h = await createHarness({ sessionPrefix: 'crtr-brkcrash' });
+    root = h.spawnRoot('broker-crash suite root');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+// ===========================================================================
+// Item 4 + 6 — broker CRASH → grace-revive RESUME on the saved .jsonl; ONE-
+// WRITER: the crashed pid is dead BEFORE the revive launches and never
+// resurrects, and the revived pid is distinct (never two engine pids at once).
+// ===========================================================================
+test('CRASH → grace-revive RESUME; one-writer (old pid dead before new, never resurrects)', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — crash');
+    const oldPid = h.node(id).pi_pid;
+    assert.equal(isPidAlive(oldPid), true, 'broker alive before the crash');
+    assert.equal(h.node(id).intent ?? null, null, 'fresh broker has a null intent (not refresh/idle-release)');
+    const boots = h.bootCount(id);
+    // Kill the broker out from under the daemon (a crash). Use a fixed clock so the
+    // grace window is exercised deterministically.
+    process.kill(oldPid, 'SIGKILL');
+    await h.waitFor(() => !isPidAlive(oldPid), { label: 'crashed broker pid is dead' });
+    // ONE-WRITER: the old engine pid is dead BEFORE any revive can launch.
+    assert.equal(isPidAlive(oldPid), false, 'crashed pid dead before the daemon revives');
+    const NOW = 5_000_000;
+    await h.tick(NOW); // pid dead, intent null → handleBrokerLiveness → handleLiveWindow marks pending
+    assert.equal(h.bootCount(id), boots, 'inside the grace window → NOT yet revived');
+    await h.tick(NOW + REVIVE_GRACE_MS + 1); // grace elapsed → reviveNode(resume:true)
+    const boot2 = await h.awaitBoot(id, { minCount: boots + 1 });
+    assert.equal(boot2.resuming, true, 'grace-revive RESUMES the saved .jsonl');
+    const newPid = h.node(id).pi_pid;
+    assert.ok(newPid != null && isPidAlive(newPid), 'the revived broker pid is alive');
+    assert.notEqual(newPid, oldPid, 'the revived pid is distinct from the crashed one');
+    assert.equal(isPidAlive(oldPid), false, 'one-writer: the crashed pid never resurrected');
+});
+// ===========================================================================
+// Item 5 — clean teardown: close → hostFor(meta).teardown → `shutdown` frame →
+// broker disposes + exits, socket unlinked, status canceled, daemon leaves it.
+// ===========================================================================
+test('clean teardown — node close → broker shutdown frame → exit, socket unlinked, not revived', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — teardown');
+    const pid = h.node(id).pi_pid;
+    const sock = h.brokerSock(id);
+    await h.waitFor(() => existsSync(sock), { label: 'broker created its view.sock' });
+    // Close via the REAL CLI (resolves the node from --node; the subprocess carries
+    // no TMUX_PANE). closeNode marks canceled BEFORE teardown (crash-safe order),
+    // then hostFor(broker).teardown sends the `shutdown` frame.
+    const res = h.cli(root, ['node', 'close', '--node', id]);
+    assert.equal(res.code, 0, `node close should exit 0\n--stderr--\n${res.stderr}`);
+    await h.waitFor(() => !isPidAlive(pid), { label: 'broker process exited on shutdown frame' });
+    await h.waitFor(() => !existsSync(sock), { label: 'broker unlinked its socket on exit' });
+    assert.equal(h.status(id), 'canceled', 'the closed node is canceled');
+    // listNodes only surfaces active|idle, so a canceled broker is never supervised.
+    await h.tick();
+    assert.equal(h.status(id), 'canceled', 'still canceled after a daemon tick');
+    assert.equal(isPidAlive(pid), false, 'the broker stays dead — never revived');
+});
+// ===========================================================================
+// M-1 regression — a broker that DIES before session_start must surface a boot
+// failure, not strand the node forever. Before the fix handleBrokerLiveness read
+// pid==null UNCONDITIONALLY as "still booting", so a broker that threw before
+// recording a pid/session left the node 'active' with no engine FOREVER and the
+// parent waited on a dead child. The daemon must instead crash it past the boot
+// grace + push a boot-failure up the spine. (Also proves M-2: the broker's fatal
+// diagnostic reaches job/broker.log instead of /dev/null.)
+// ===========================================================================
+test('boot failure — a broker that dies before session_start is reaped, not stranded (review M-1/M-2)', { skip: !hasTmux() }, async () => {
+    // A headless child whose broker throws before session_start (no pid, no session
+    // EVER recorded). spawnHeadlessChildNoBoot does not awaitBoot (there is none).
+    const id = await h.spawnHeadlessChildNoBoot(root, `headless worker — boot fail ${FAIL_BEFORE_SESSION_START}`);
+    // M-2: the broker logs its fatal stack to job/broker.log and exits(1). Without
+    // the stdio redirect this diagnostic would be lost to /dev/null.
+    const brokerLog = join(h.home, 'nodes', id, 'job', 'broker.log');
+    await h.waitFor(() => existsSync(brokerLog) && /simulated pre-session_start boot failure/.test(readFileSync(brokerLog, 'utf8')), { label: 'broker logged its pre-session_start failure to job/broker.log' });
+    // The node is stuck 'active' with a null pid and a null session — the strand.
+    const n0 = h.node(id);
+    assert.equal(n0.pi_pid ?? null, null, 'no broker pid was ever recorded');
+    assert.equal(n0.pi_session_id ?? null, null, 'no session was ever recorded');
+    // Inside the boot grace the daemon LEAVES it (could be the sub-second boot gap).
+    const NOW = 9_000_000;
+    await h.tick(NOW);
+    assert.equal(h.status(id), 'active', 'inside the boot grace → daemon leaves it (boot gap)');
+    // Past the boot grace with STILL no pid and no session → crash + boot failure.
+    await h.tick(NOW + REVIVE_GRACE_MS + 1);
+    await h.waitForStatus(id, 'dead');
+    assert.equal(h.status(id), 'dead', 'a never-booted broker is reaped, not stranded active forever');
+    // …and the parent (an active subscriber of the child) was told up the spine.
+    const note = h.inbox(root).find((e) => /never started/.test(e.label ?? ''));
+    assert.ok(note !== undefined, 'the parent received a boot-failure notice up the spine');
+});