@crouton-kit/crouter 0.3.18 → 0.3.20

package/dist/core/__tests__/frame-decoder-perf.test.js

@@ -0,0 +1,198 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/frame-decoder-perf.test.ts
+//
+// Bug-regression suite for the FrameDecoder O(n²) typing-lag bug (2026-06-09).
+//
+// OBSERVED BUG: typing in `crtr attach` lagged after the headless-broker change.
+// Root cause #1: FrameDecoder.push() did `this.buf += str` and re-scanned the
+// WHOLE accumulated buffer (`this.buf.indexOf('\n')` + Buffer.byteLength over
+// the consumed prefix) on every ~64 KiB socket chunk, so one large frame (the
+// multi-MiB `welcome` snapshot, a big tool result) cost O(frame × chunks) —
+// measured ~254 ms of event-loop stall decoding a 16 MiB frame, with the stall
+// growing ~5× per size doubling. The decoder runs on BOTH the viewer and broker
+// read paths, so the stall blocked keystroke handling directly.
+//
+// The fix holds the carried partial line as an array of chunk strings and scans
+// each incoming chunk exactly once — amortized O(total bytes). Same 16 MiB frame:
+// ~12 ms.
+//
+// These tests lock in (a) behavioral equivalence with the old decoder across
+// randomized chunkings — frames, blank-line skip, malformed-JSON drop, multibyte
+// splits, and both FrameOverflowError caps with identical byte accounting — and
+// (b) the linear growth curve, so the quadratic shape cannot silently return.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { StringDecoder } from 'node:string_decoder';
+import { FrameDecoder, FrameOverflowError, CLIENT_READ_CAPS, } from '../runtime/broker-protocol.js';
+// ---------------------------------------------------------------------------
+// The PRE-FIX decoder, verbatim (git ed49e60), as the equivalence oracle.
+// ---------------------------------------------------------------------------
+class ReferenceFrameDecoder {
+    caps;
+    buf = '';
+    bufBytes = 0;
+    utf8 = new StringDecoder('utf8');
+    constructor(caps) {
+        this.caps = caps;
+    }
+    push(chunk) {
+        const str = typeof chunk === 'string' ? chunk : this.utf8.write(chunk);
+        this.buf += str;
+        this.bufBytes += Buffer.byteLength(str);
+        if (this.bufBytes > this.caps.maxTotalBytes) {
+            throw new FrameOverflowError('total', this.bufBytes, this.caps.maxTotalBytes);
+        }
+        const out = [];
+        let nl;
+        while ((nl = this.buf.indexOf('\n')) >= 0) {
+            const consumed = this.buf.slice(0, nl + 1);
+            this.bufBytes -= Buffer.byteLength(consumed);
+            const line = this.buf.slice(0, nl).trim();
+            this.buf = this.buf.slice(nl + 1);
+            if (line === '')
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch {
+                /* drop malformed */
+            }
+        }
+        if (this.bufBytes > this.caps.maxLineBytes) {
+            throw new FrameOverflowError('line', this.bufBytes, this.caps.maxLineBytes);
+        }
+        return out;
+    }
+}
+// Deterministic PRNG so a failure reproduces.
+let seed = 0xc0ffee;
+const rnd = () => {
+    seed = (seed * 1103515245 + 12345) & 0x7fffffff;
+    return seed / 0x7fffffff;
+};
+const randInt = (lo, hi) => lo + Math.floor(rnd() * (hi - lo + 1));
+const MULTIBYTE = ['é', '漢', '🎉', '𝕏', 'ü', '한'];
+const randText = (len) => {
+    let s = '';
+    while (s.length < len) {
+        s += rnd() < 0.2 ? MULTIBYTE[randInt(0, MULTIBYTE.length - 1)] : String.fromCharCode(randInt(97, 122));
+    }
+    return s;
+};
+function run(dec, stream, cuts) {
+    const frames = [];
+    let prev = 0;
+    try {
+        for (const cut of [...cuts, stream.length]) {
+            if (cut <= prev)
+                continue;
+            frames.push(...dec.push(stream.subarray(prev, cut)));
+            prev = cut;
+        }
+        return { frames, err: null };
+    }
+    catch (e) {
+        if (e instanceof FrameOverflowError)
+            return { frames, err: `${e.kind}:${e.bytes}:${e.cap}` };
+        throw e;
+    }
+}
+test('FrameDecoder — behavior-equivalent to the pre-fix decoder across randomized chunkings (frames, blank lines, malformed JSON, multibyte splits, both overflow caps)', () => {
+    for (let t = 0; t < 1500; t++) {
+        // Small caps in ~30% of trials exercise both FrameOverflowError kinds with
+        // identical byte accounting; generous caps exercise the happy path.
+        const caps = rnd() < 0.3
+            ? { maxLineBytes: randInt(50, 1500), maxTotalBytes: randInt(100, 4000) }
+            : { maxLineBytes: 1 << 20, maxTotalBytes: 1 << 21 };
+        const pieces = [];
+        for (let i = 0, n = randInt(1, 12); i < n; i++) {
+            const kind = rnd();
+            if (kind < 0.55)
+                pieces.push(JSON.stringify({ type: 'x', t: randText(randInt(0, 2000)) }) + '\n');
+            else if (kind < 0.7)
+                pieces.push('\n'); // blank-line skip
+            else if (kind < 0.8)
+                pieces.push('   \n'); // whitespace-only skip
+            else if (kind < 0.9)
+                pieces.push('{not json' + randText(randInt(0, 50)) + '\n'); // malformed drop
+            else
+                pieces.push(randText(randInt(0, 300))); // trailing partial, no newline
+        }
+        const stream = Buffer.from(pieces.join(''));
+        // Byte-level cut points — these can and do split multibyte chars.
+        const cuts = Array.from({ length: randInt(0, 20) }, () => randInt(0, stream.length)).sort((a, b) => a - b);
+        const expected = run(new ReferenceFrameDecoder(caps), stream, cuts);
+        const actual = run(new FrameDecoder(caps), stream, cuts);
+        assert.deepEqual(actual, expected, `trial ${t}: caps=${JSON.stringify(caps)} cuts=${JSON.stringify(cuts)} stream=${JSON.stringify(stream.toString('utf8').slice(0, 300))}`);
+    }
+});
+test('FrameDecoder — mixed string/Buffer pushes stay equivalent', () => {
+    for (let t = 0; t < 300; t++) {
+        const caps = { maxLineBytes: 1 << 20, maxTotalBytes: 1 << 21 };
+        const ref = new ReferenceFrameDecoder(caps);
+        const dec = new FrameDecoder(caps);
+        const refF = [];
+        const decF = [];
+        for (let i = 0, n = randInt(1, 10); i < n; i++) {
+            const s = rnd() < 0.5 ? JSON.stringify({ i, t: randText(randInt(0, 200)) }) + '\n' : randText(randInt(0, 100));
+            const input = rnd() < 0.5 ? s : Buffer.from(s);
+            refF.push(...ref.push(input));
+            decF.push(...dec.push(input));
+        }
+        assert.deepEqual(decF, refF, `mixed trial ${t}`);
+    }
+});
+test('FrameDecoder — a frame exactly AT each cap passes; one byte over throws (cap accounting exact)', () => {
+    // line cap: an unterminated partial exactly at maxLineBytes is fine…
+    {
+        const caps = { maxLineBytes: 100, maxTotalBytes: 1000 };
+        const dec = new FrameDecoder(caps);
+        assert.deepEqual(dec.push('x'.repeat(100)), []);
+        // …and the 101st byte trips it, reporting the full buffered size.
+        assert.throws(() => dec.push('x'), (e) => e instanceof FrameOverflowError && e.kind === 'line' && e.bytes === 101 && e.cap === 100);
+    }
+    // total cap: carry + chunk exactly at maxTotalBytes is fine; one over throws.
+    {
+        const caps = { maxLineBytes: 1000, maxTotalBytes: 100 };
+        const dec = new FrameDecoder(caps);
+        assert.deepEqual(dec.push('x'.repeat(60)), []);
+        assert.deepEqual(dec.push('x'.repeat(40 - 60 > 0 ? 0 : 40)), []); // 60 + 40 = 100, at cap
+        assert.throws(() => dec.push('x'), (e) => e instanceof FrameOverflowError && e.kind === 'total' && e.bytes === 101 && e.cap === 100);
+    }
+    // multibyte accounting: bytes, not chars (é = 2 bytes).
+    {
+        const caps = { maxLineBytes: 10, maxTotalBytes: 1000 };
+        const dec = new FrameDecoder(caps);
+        assert.throws(() => dec.push('é'.repeat(6)), // 12 bytes > 10, only 6 chars
+        (e) => e instanceof FrameOverflowError && e.kind === 'line' && e.bytes === 12);
+    }
+});
+test('FrameDecoder — large-frame decode is linear, not quadratic (the observed attach-lag regression)', () => {
+    // Decode a single N-MiB frame in 64 KiB chunks; compare per-MiB cost at 2 MiB
+    // vs 8 MiB. Quadratic shape ⇒ per-MiB cost grows ~4× per 4× size (measured
+    // 5.5×+ pre-fix); linear stays ~flat. Threshold 3× is far above linear noise
+    // and far below the quadratic signature, so this fails ONLY on a complexity
+    // regression, not on a slow CI box.
+    const CHUNK = 64 * 1024;
+    const decodeMs = (mib) => {
+        const overhead = Buffer.byteLength('{"type":"welcome","blob":""}\n');
+        const frame = Buffer.from(`{"type":"welcome","blob":"${'x'.repeat(mib * 1024 * 1024 - overhead)}"}\n`);
+        let best = Infinity;
+        for (let rep = 0; rep < 3; rep++) {
+            const dec = new FrameDecoder(CLIENT_READ_CAPS);
+            const t0 = performance.now();
+            let n = 0;
+            for (let off = 0; off < frame.length; off += CHUNK) {
+                n += dec.push(frame.subarray(off, Math.min(off + CHUNK, frame.length))).length;
+            }
+            const ms = performance.now() - t0;
+            assert.equal(n, 1, 'decoded exactly one frame');
+            if (ms < best)
+                best = ms;
+        }
+        return best;
+    };
+    decodeMs(1); // warmup
+    const perMibSmall = decodeMs(2) / 2;
+    const perMibLarge = decodeMs(8) / 8;
+    assert.ok(perMibLarge < perMibSmall * 3, `per-MiB decode cost grew superlinearly: ${perMibSmall.toFixed(2)}ms/MiB @2MiB → ${perMibLarge.toFixed(2)}ms/MiB @8MiB (quadratic regression)`);
+});

package/dist/core/__tests__/helpers/broker-clients.d.ts

@@ -0,0 +1,43 @@
+import { type Socket } from 'node:net';
+import type { Harness } from './harness.js';
+import { ViewSocketClient } from '../../../clients/attach/view-socket.js';
+import { type BrokerToClient, type ClientToBroker, type ClientRole, type WelcomeFrame } from '../../runtime/broker-protocol.js';
+export declare const delay: (ms: number) => Promise<void>;
+export declare const tok: (s: string) => string;
+export declare const frameHas: (f: BrokerToClient, token: string) => boolean;
+export declare function brokerLogText(h: Harness, id: string): string;
+/** lsof the holders of `path`, or null when lsof is unavailable (skip the fd
+ *  check). Exit-non-zero with empty stdout means "no holders". */
+export declare function lsofHolders(path: string): number[] | null;
+export interface Attached {
+    client: ViewSocketClient;
+    frames: BrokerToClient[];
+    welcome: WelcomeFrame;
+    send(frame: ClientToBroker): void;
+    waitFrame(pred: (f: BrokerToClient) => boolean, label: string, timeoutMs?: number): Promise<BrokerToClient>;
+    close(): void;
+}
+export interface RawClient {
+    socket: Socket;
+    frames: BrokerToClient[];
+    closed: () => boolean;
+    send(frame: ClientToBroker): void;
+    writeRaw(data: Buffer | string): void;
+    waitClosed(label: string, timeoutMs?: number): Promise<void>;
+    close(): void;
+}
+export interface AttachKit {
+    /** Connect a ViewSocketClient to a node's running broker, hello, await welcome. */
+    attach(id: string, role: ClientRole, clientId: string): Promise<Attached>;
+    /** Attach (as `role`) and retry until the welcome satisfies `pred`. */
+    attachUntil(id: string, role: ClientRole, clientId: string, pred: (a: Attached) => boolean, label: string): Promise<Attached>;
+    /** A raw node:net peer. read:false leaves the socket PAUSED (G8 stalled viewer). */
+    connectRaw(id: string, opts: {
+        read: boolean;
+    }): Promise<RawClient>;
+    /** Close every client opened since the last closeAll — wire into afterEach. */
+    closeAll(): void;
+}
+/** Build the attach kit against a lazily-resolved harness (the harness is
+ *  created in the file's before() hook, after the kit is constructed). */
+export declare function createAttachKit(getH: () => Harness): AttachKit;

package/dist/core/__tests__/helpers/broker-clients.js

@@ -0,0 +1,178 @@
+// helpers/broker-clients.ts — the shared attach-client kit for the broker
+// lifecycle/attach-gate suite (plan T8/T11). Extracted VERBATIM from the original
+// single-file broker-lifecycle.test.ts when it was split into per-area files so
+// node:test's file-level parallelism applies (each file holds its own isolated
+// harness); the helpers are unchanged in behavior.
+//
+// The kit wraps the PRODUCTION attach client (pure node:net + the broker codec,
+// no TUI) as the in-test controller/observer so the G1–G9 gate exercises the REAL
+// client too (§0 one-writer: a viewer holds ONLY a socket), plus a raw node:net
+// peer for the cases where the client lifecycle is awkward (G7 oversized line,
+// G8 stalled viewer).
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createConnection } from 'node:net';
+import { spawnSync } from 'node:child_process';
+import { ViewSocketClient } from '../../../clients/attach/view-socket.js';
+import { CLIENT_READ_CAPS, FrameDecoder, encodeFrame, } from '../../runtime/broker-protocol.js';
+export const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+export const tok = (s) => `${s}-${Math.random().toString(36).slice(2, 8)}`;
+export const frameHas = (f, token) => JSON.stringify(f).includes(token);
+export function brokerLogText(h, id) {
+    try {
+        return readFileSync(join(h.home, 'nodes', id, 'job', 'broker.log'), 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+/** lsof the holders of `path`, or null when lsof is unavailable (skip the fd
+ *  check). Exit-non-zero with empty stdout means "no holders". */
+export function lsofHolders(path) {
+    if (spawnSync('which', ['lsof'], { stdio: 'ignore' }).status !== 0)
+        return null;
+    const out = (spawnSync('lsof', ['-t', '--', path], { encoding: 'utf8' }).stdout ?? '').trim();
+    if (out === '')
+        return [];
+    return out
+        .split('\n')
+        .map((l) => Number(l.trim()))
+        .filter((n) => Number.isFinite(n));
+}
+/** Build the attach kit against a lazily-resolved harness (the harness is
+ *  created in the file's before() hook, after the kit is constructed). */
+export function createAttachKit(getH) {
+    const liveClients = [];
+    // Connect a ViewSocketClient to a node's running broker, hello, await welcome.
+    // awaitBoot returns once the boot proof is written — which is BEFORE the broker's
+    // server.listen() binds view.sock — so a fresh attach can momentarily race the
+    // bind; retry the connect on BrokerUnavailable until it is listening.
+    async function attach(id, role, clientId) {
+        const h = getH();
+        await h.waitFor(() => existsSync(h.brokerSock(id)), { label: `view.sock for ${id}`, timeoutMs: 20_000 });
+        const frames = [];
+        let client;
+        for (let attempt = 0;; attempt++) {
+            client = new ViewSocketClient(id);
+            client.on('frame', (f) => frames.push(f));
+            try {
+                await new Promise((resolve, reject) => {
+                    client.once('connect', resolve);
+                    client.once('error', reject);
+                    client.connect();
+                });
+                break;
+            }
+            catch (err) {
+                client.close();
+                if (attempt >= 30)
+                    throw err;
+                await delay(100);
+            }
+        }
+        client.on('error', () => { }); // post-connect error sink (never throw uncaught)
+        // Register cleanup the instant the socket is connected — BEFORE the hello/welcome
+        // round-trip — so a welcome timeout cannot leak a connected socket past the test.
+        liveClients.push({ close: () => client.close() });
+        const waitFrame = (pred, label, timeoutMs = 15_000) => h.waitFor(() => frames.find(pred) ?? null, { label, timeoutMs });
+        client.send({ type: 'hello', role, client_id: clientId });
+        let welcome;
+        try {
+            welcome = (await waitFrame((f) => f.type === 'welcome', `welcome for ${clientId}`));
+        }
+        catch (err) {
+            client.close();
+            throw err;
+        }
+        return { client, frames, welcome, send: (f) => client.send(f), waitFrame, close: () => client.close() };
+    }
+    // Attach (as `role`) and retry until the welcome satisfies `pred` — used where the
+    // observable lands a beat after a prior action (G3 snapshot accrual, G5b control
+    // handoff after a controller detaches). Deterministic: it polls an observable.
+    async function attachUntil(id, role, clientId, pred, label) {
+        for (let attempt = 0;; attempt++) {
+            const a = await attach(id, role, `${clientId}-${attempt}`);
+            if (pred(a))
+                return a;
+            a.close();
+            if (attempt >= 40)
+                throw new Error(`attachUntil timed out: ${label}`);
+            await delay(150);
+        }
+    }
+    // A raw node:net peer. read:true decodes incoming frames; read:false leaves the
+    // socket PAUSED (no 'data' listener, never resumed) so it never drains — the
+    // stalled viewer (G8) whose backlog the broker must shed at the HWM.
+    async function connectRaw(id, opts) {
+        const h = getH();
+        await h.waitFor(() => existsSync(h.brokerSock(id)), { label: `view.sock for ${id}`, timeoutMs: 20_000 });
+        const frames = [];
+        const decoder = new FrameDecoder(CLIENT_READ_CAPS);
+        let isClosed = false;
+        const socket = await new Promise((resolve, reject) => {
+            const s = createConnection(h.brokerSock(id));
+            s.once('connect', () => resolve(s));
+            s.once('error', reject);
+        });
+        socket.on('close', () => {
+            isClosed = true;
+        });
+        socket.on('error', () => {
+            /* close follows */
+        });
+        if (opts.read) {
+            socket.on('data', (chunk) => {
+                try {
+                    for (const f of decoder.push(chunk))
+                        frames.push(f);
+                }
+                catch {
+                    /* a client-side overflow is irrelevant here */
+                }
+            });
+        }
+        const rc = {
+            socket,
+            frames,
+            closed: () => isClosed,
+            send: (f) => {
+                try {
+                    socket.write(encodeFrame(f));
+                }
+                catch {
+                    /* dead */
+                }
+            },
+            writeRaw: (d) => {
+                try {
+                    socket.write(d);
+                }
+                catch {
+                    /* dead */
+                }
+            },
+            waitClosed: (label, timeoutMs = 15_000) => h.waitFor(() => (isClosed ? true : null), { label, timeoutMs }).then(() => undefined),
+            close: () => {
+                try {
+                    socket.destroy();
+                }
+                catch {
+                    /* ignore */
+                }
+            },
+        };
+        liveClients.push(rc);
+        return rc;
+    }
+    function closeAll() {
+        for (const c of liveClients.splice(0)) {
+            try {
+                c.close();
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    }
+    return { attach, attachUntil, connectRaw, closeAll };
+}

package/dist/core/__tests__/helpers/harness.d.ts

@@ -43,6 +43,8 @@ export interface Harness {
     spawnRoot(task: string, o?: SpawnOpts): string;
     spawnChild(parentId: string, task: string, o?: SpawnOpts): Promise<string>;
     cli(nodeId: string | null, args: string[]): CliResult;
+    spawnHeadlessChild(parentId: string, task: string, o?: SpawnOpts): Promise<string>;
+    spawnHeadlessChildNoBoot(parentId: string, task: string, o?: SpawnOpts): Promise<string>;
     turn(nodeId: string, text?: string): Promise<void>;
     stop(nodeId: string, reason?: 'stop' | 'length' | 'aborted' | 'error'): Promise<void>;
     finish(nodeId: string, finalText: string): Promise<void>;
@@ -65,6 +67,13 @@ export interface Harness {
     paneAlive(nodeId: string): boolean;
     inbox(nodeId: string): InboxEntry[];
     injected(nodeId: string): Injected[];
+    fakeCmd(nodeId: string, cmd: Record<string, unknown>): void;
+    dialogResults(nodeId: string): {
+        resolved: unknown;
+        ms: number;
+    }[];
+    brokerSock(nodeId: string): string;
+    bootCount(nodeId: string): number;
     subscribers(nodeId: string): {
         node_id: string;
         active: boolean;

package/dist/core/__tests__/helpers/harness.js

@@ -36,6 +36,11 @@ const HERE = dirname(fileURLToPath(import.meta.url)); // src/core/__tests__/help
 const CROUTER = join(HERE, '..', '..', '..', '..'); // package root
 const CLI_SRC = join(CROUTER, 'src', 'cli.ts');
 const FAKE_PI_HOST = join(HERE, '..', 'fixtures', 'fake-pi-host.ts');
+// The in-process fake BrokerEngine (the SDK analog of the fake-pi vehicle). The
+// REAL broker loads it via the CRTR_BROKER_ENGINE seam (broker-sdk.ts). Point at
+// the absolute `.ts` path — the broker runs under tsx (see NODE_OPTIONS below),
+// which resolves it.
+const FAKE_ENGINE = join(HERE, '..', 'fixtures', 'fake-engine.ts');
 const TSX_ESM = createRequire(import.meta.url).resolve('tsx/esm');
 // A multi-word launcher, baked verbatim ahead of the (shell-quoted) argv by the
 // seam. Absolute paths so it works regardless of the spawned window's cwd.
@@ -53,6 +58,7 @@ const CANVAS_ENV_KEYS = [
     'CRTR_NODE_ID',
     'CRTR_HOME',
     'CRTR_ROOT_SESSION',
+    'CRTR_SUBTREE',
     'CRTR_NODE_SESSION',
     'CRTR_PARENT_NODE_ID',
     'CRTR_FRONT_DOOR',
@@ -61,6 +67,10 @@ const CANVAS_ENV_KEYS = [
     'CRTR_LIFECYCLE',
     'CRTR_NODE_CWD',
     'CRTR_PI_BINARY',
+    // Scrubbed then re-added (controlled) in childEnv, mirroring CRTR_PI_BINARY —
+    // so the headless-broker seam can't leak the REAL engine into the isolated
+    // test, and the CLI subprocess that spawns a broker carries the FAKE one.
+    'CRTR_BROKER_ENGINE',
     'TMUX',
     'TMUX_PANE',
 ];
@@ -99,7 +109,18 @@ export async function createHarness(opts = {}) {
     const origHome = process.env['CRTR_HOME'];
     const origPiBinary = process.env['CRTR_PI_BINARY'];
     const origNodeSession = process.env['CRTR_NODE_SESSION'];
-    const home = mkdtempSync(join(tmpdir(), 'crtr-harness-home-'));
+    const origNodeOptions = process.env['NODE_OPTIONS'];
+    const origBrokerEngine = process.env['CRTR_BROKER_ENGINE'];
+    // The headless broker binds a unix socket at <home>/nodes/<id>/view.sock. A
+    // unix socket path (sun_path) has a ~104-char OS limit, and macOS's per-user
+    // $TMPDIR (/var/folders/<…>/T/, ~49 chars) alone pushes that path past the
+    // limit — server.listen() then fails EINVAL and the broker's loop drains
+    // (boots, never serves). NOT a production concern (~/.crouter/canvas/… is
+    // short); a test-only artifact of the long temp base. Use a SHORT base + short
+    // prefix for the canvas home so broker sockets fit. tmpHome (HOME) hosts no
+    // socket, so it can stay on the standard temp base.
+    const shortTmpBase = existsSync('/tmp') ? '/tmp' : tmpdir();
+    const home = mkdtempSync(join(shortTmpBase, 'crh-'));
     const tmpHome = mkdtempSync(join(tmpdir(), 'crtr-harness-HOME-'));
     const session = `${opts.sessionPrefix ?? 'crtr-harness'}-${process.pid}-${Date.now().toString(36)}`;
     // The harness reads/writes the isolated canvas in-process. CRTR_PI_BINARY in
@@ -108,7 +129,32 @@ export async function createHarness(opts = {}) {
     process.env['CRTR_HOME'] = home;
     process.env['CRTR_PI_BINARY'] = FAKE_PI_BINARY;
     delete process.env['CRTR_NODE_SESSION'];
+    // The headless broker (host.ts) launches `node <broker-cli.js> <id>` with a
+    // plain `process.execPath` (no tsx) and resolveBrokerEntry returns a `.js`
+    // path that, under the src test tree, only exists as `.ts`. Putting
+    // `--import <tsx/esm>` in the broker's NODE_OPTIONS makes the spawned broker
+    // run under tsx (resolving broker-cli.js→.ts AND the `.ts` fake engine). We set
+    // it on OUR process.env so it propagates to BOTH broker-launch callers: the
+    // in-process daemon revive (headlessBrokerHost.launch spreads {...process.env})
+    // and the initial `node new --headless` CLI subprocess (cleanBaseEnv copies it,
+    // since NODE_OPTIONS is deliberately NOT in CANVAS_ENV_KEYS). NODE_OPTIONS is
+    // read at process START, so setting it on the already-running harness does NOT
+    // re-trigger tsx here — it only propagates to spawned children (verified).
+    process.env['NODE_OPTIONS'] = [process.env['NODE_OPTIONS'], `--import ${TSX_ESM}`]
+        .filter((s) => s !== undefined && s !== '')
+        .join(' ');
+    process.env['CRTR_BROKER_ENGINE'] = FAKE_ENGINE;
     closeDb();
+    // Neutralize ensureDaemon (spawn.ts calls it on every `node new`): write a
+    // fake-live-daemon pidfile pointing at OUR (always-alive) pid, so
+    // isDaemonRunning() is true and no REAL crtrd is spawned against the isolated
+    // home. Required now that the broker's NODE_OPTIONS=--import tsx propagates to
+    // the crtrd spawn (pre-broker, the tsx-less `node crtrd-cli.js` spawn silently
+    // failed, so no daemon ever started); a stray real daemon would race the
+    // in-process superviseTick + the fixed-clock crash/grace scenarios. The harness
+    // drives the daemon pass itself via `tick()`. (fakeLiveDaemon pattern,
+    // home-session.test.ts.) home/ is rmSync'd in dispose.
+    writeFileSync(join(home, 'crtrd.pid'), String(process.pid), 'utf8');
     // Pre-create the isolated session on the DEFAULT server so teardown always
     // has a target and `node new`'s ensureSession no-ops.
     // ISOLATION ASSUMPTION (see header + MINOR-6): isolation is by SESSION NAME on
@@ -136,6 +182,7 @@ export async function createHarness(opts = {}) {
         e['HOME'] = tmpHome;
         e['CRTR_NODE_SESSION'] = session;
         e['CRTR_PI_BINARY'] = FAKE_PI_BINARY;
+        e['CRTR_BROKER_ENGINE'] = FAKE_ENGINE;
         if (nodeId !== null)
             e['CRTR_NODE_ID'] = nodeId;
         return e;
@@ -258,6 +305,42 @@ export async function createHarness(opts = {}) {
             await harness.awaitBoot(childId);
             return childId;
         },
+        async spawnHeadlessChild(parentId, task, o = {}) {
+            const before = new Set(nodeDirs());
+            const args = ['node', 'new', task, '--parent', parentId, '--cwd', CROUTER, '--headless'];
+            if (o.kind)
+                args.push('--kind', o.kind);
+            if (o.mode)
+                args.push('--mode', o.mode);
+            const res = cli(parentId, args);
+            if (res.code !== 0) {
+                throw new Error(`spawnHeadlessChild(${parentId}) failed (code ${res.code})\n--stdout--\n${res.stdout}\n--stderr--\n${res.stderr}`);
+            }
+            const added = nodeDirs().filter((d) => !before.has(d));
+            if (added.length !== 1) {
+                throw new Error(`spawnHeadlessChild: expected exactly 1 new node dir, got [${added.join(', ')}]`);
+            }
+            const childId = added[0];
+            await harness.awaitBoot(childId);
+            return childId;
+        },
+        async spawnHeadlessChildNoBoot(parentId, task, o = {}) {
+            const before = new Set(nodeDirs());
+            const args = ['node', 'new', task, '--parent', parentId, '--cwd', CROUTER, '--headless'];
+            if (o.kind)
+                args.push('--kind', o.kind);
+            if (o.mode)
+                args.push('--mode', o.mode);
+            const res = cli(parentId, args);
+            if (res.code !== 0) {
+                throw new Error(`spawnHeadlessChildNoBoot(${parentId}) failed (code ${res.code})\n--stdout--\n${res.stdout}\n--stderr--\n${res.stderr}`);
+            }
+            const added = nodeDirs().filter((d) => !before.has(d));
+            if (added.length !== 1) {
+                throw new Error(`spawnHeadlessChildNoBoot: expected exactly 1 new node dir, got [${added.join(', ')}]`);
+            }
+            return added[0];
+        },
         cli,
         async turn(nodeId, text = '') {
             const base = eventCount(nodeId, 'agent_end');
@@ -367,6 +450,25 @@ export async function createHarness(opts = {}) {
             return readInboxSince(nodeId);
         },
         injected,
+        fakeCmd(nodeId, cmd) {
+            sendCmd(nodeId, cmd);
+        },
+        dialogResults(nodeId) {
+            return readLines(join(nodeDir(nodeId), 'fake-pi.dialog.jsonl'))
+                .map((l) => {
+                try {
+                    return JSON.parse(l);
+                }
+                catch {
+                    return null;
+                }
+            })
+                .filter((x) => x !== null);
+        },
+        brokerSock(nodeId) {
+            return join(nodeDir(nodeId), 'view.sock');
+        },
+        bootCount,
         subscribers(nodeId) {
             closeDb();
             return subscribersOf(nodeId).map((s) => ({ node_id: s.node_id, active: s.active }));
@@ -400,6 +502,14 @@ export async function createHarness(opts = {}) {
                 delete process.env['CRTR_NODE_SESSION'];
             else
                 process.env['CRTR_NODE_SESSION'] = origNodeSession;
+            if (origNodeOptions === undefined)
+                delete process.env['NODE_OPTIONS'];
+            else
+                process.env['NODE_OPTIONS'] = origNodeOptions;
+            if (origBrokerEngine === undefined)
+                delete process.env['CRTR_BROKER_ENGINE'];
+            else
+                process.env['CRTR_BROKER_ENGINE'] = origBrokerEngine;
         },
     };
     return harness;