@crouton-kit/crouter 0.3.20 → 0.3.22

package/dist/core/__tests__/full/spike-harness.test.js

@@ -0,0 +1,117 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/full/spike-harness.test.ts
+//
+// HEADLESS RETARGET (foundation-spec §C.14 + §E). The throwaway-grade POC that a
+// faithful integration harness for the node/canvas runtime is feasible — now on
+// the BROKER path, tmux-free (no hasTmux() gate). FULL TIER: it boots a REAL
+// broker process (~5s pi-SDK load), so it lives in full/ (CI), not the fast loop. It drives the
+// REAL `crtr` CLI to spawn a `--headless` node onto the REAL headless broker host,
+// which boots a REAL detached broker PROCESS hosting the fake SDK engine via the
+// CRTR_BROKER_ENGINE seam — proving the broker exec's with the right argv+env,
+// loads the REAL `-e` canvas extensions, and that real lifecycle hooks drive real
+// canvas transitions.
+//
+// Milestones (de-risk order):
+//   1. SEAM      — piCommand substitutes CRTR_PI_BINARY only when set (pure unit).
+//   2. ROUND-TRIP— real `node new --headless` → real broker boots with CRTR_NODE_ID
+//                  + the -e canvas extensions intact (GO/NO-GO).
+//   3. REAL HOOKS— the broker loads the real stophook: session_start captures
+//                  pi_session_id + recordPid(broker pid); a `push --final` agent_end
+//                  drives status=done through the stophook's clean-exit branch.
+//
+// (1) BUG LOCKED — harness faithfulness. A real `node new --headless` must boot a
+//     real broker that loads EVERY canvas `-e` extension with none failing, the
+//     REAL stophook must capture the session id on session_start, and the REAL
+//     stophook agent_end clean-exit branch must transition the node to done.
+//
+// (2) WHY MODEL-LEVEL / HEADLESS — the broker hosts the fake engine over the SDK
+//     seam (no real LLM), boots DETACHED supervised by pid (no tmux pane), and
+//     every proof is a file the broker writes (fake-pi.boots.jsonl) or a canvas
+//     row — nothing reads a pane. ONE real boot is inherent: the POC's whole
+//     point is that a real broker PROCESS loads real extensions + fires real hooks.
+//     (The fake engine models a clean exit via the broker's shutdownHandler rather
+//     than a pi `session_shutdown` frame, so the clean done transition is driven
+//     through the stophook's `push --final` agent_end branch — the same real
+//     stophook code path that shuts a done broker down.)
+//
+// (3) HOW THE HEADLESS DRIVE STILL FAILS IF THE BUG REGRESSES — if the seam or an
+//     extension load broke, failedExt is non-empty or extPaths drifts from
+//     CANVAS_EXTENSIONS → RED; if the stophook didn't capture the session,
+//     pi_session_id stays null → RED; if the clean-exit branch didn't shut the
+//     broker down, status never reaches done → the finish wait times out.
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { createHarness } from '../helpers/harness.js';
+import { piCommand } from '../../runtime/placement.js';
+import { CANVAS_EXTENSIONS } from '../../runtime/launch.js';
+let h;
+let root;
+before(async () => {
+    h = await createHarness({ headless: true, sessionPrefix: 'crtr-spike' });
+    root = h.spawnRoot('spike acting-root');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+// ===========================================================================
+// MILESTONE 1 — the CRTR_PI_BINARY seam (pure unit; no boot, no tmux).
+// ===========================================================================
+test('M1 seam: piCommand exec\'s `pi` when CRTR_PI_BINARY is unset, substitutes when set', () => {
+    const saved = process.env['CRTR_PI_BINARY'];
+    try {
+        delete process.env['CRTR_PI_BINARY'];
+        const unset = piCommand(['-e', '/abs/ext.ts', '-n', 'label']);
+        assert.equal(unset, "pi '-e' '/abs/ext.ts' '-n' 'label'", 'unset → identical to exec pi');
+        assert.ok(unset.startsWith('pi '), 'unset → leads with the literal pi binary');
+        process.env['CRTR_PI_BINARY'] = '/tmp/fake-pi';
+        const set = piCommand(['-e', '/abs/ext.ts']);
+        assert.ok(set.startsWith('/tmp/fake-pi '), 'set → leads with the substituted binary');
+        assert.ok(!set.startsWith('pi '), 'set → no longer the literal pi');
+        assert.equal(set, "/tmp/fake-pi '-e' '/abs/ext.ts'", 'argv still shell-quoted after the substitution');
+        // A multi-word launcher is spliced verbatim (argv stays quoted).
+        process.env['CRTR_PI_BINARY'] = 'node --import tsx/esm host.ts';
+        assert.equal(piCommand(['-n', 'x']), "node --import tsx/esm host.ts '-n' 'x'", 'multi-word binary spliced ahead of the quoted argv');
+        // An explicit binary arg still overrides the env.
+        assert.ok(piCommand(['-n', 'x'], 'pi').startsWith('pi '), 'explicit binary arg wins over the env seam');
+    }
+    finally {
+        if (saved === undefined)
+            delete process.env['CRTR_PI_BINARY'];
+        else
+            process.env['CRTR_PI_BINARY'] = saved;
+    }
+});
+// ===========================================================================
+// MILESTONES 2 + 3 — real `node new --headless` → real broker → real hooks.
+// THE GO/NO-GO. One spawned broker drives both milestones (one real boot).
+// ===========================================================================
+test('M2+M3 round-trip: real `node new --headless` boots the broker via the seam, real hooks drive status=done', async () => {
+    const id = await h.spawnHeadlessChild(root, 'spike task');
+    // ---- MILESTONE 2: the round-trip reached the real broker -----------------
+    const boot = await h.awaitBoot(id);
+    const env = boot.env;
+    assert.equal(env['CRTR_NODE_ID'], id, 'CRTR_NODE_ID is the CHILD id, intact');
+    assert.equal(env['CRTR_HOME'], h.home, 'CRTR_HOME isolated value intact');
+    assert.ok(env['CRTR_KIND'], 'CRTR_KIND present');
+    assert.ok(env['CRTR_MODE'], 'CRTR_MODE present');
+    assert.ok(env['CRTR_LIFECYCLE'], 'CRTR_LIFECYCLE present');
+    assert.equal(env['CRTR_FRONT_DOOR'], '1', 'CRTR_FRONT_DOOR overlay present (broker host)');
+    // argv from buildPiArgv arrived: every canvas -e extension + the kickoff. Assert
+    // against the live CANVAS_EXTENSIONS count so this never drifts again.
+    assert.equal(boot.extPaths.length, CANVAS_EXTENSIONS.length, `all ${CANVAS_EXTENSIONS.length} canvas -e extension paths in argv`);
+    assert.ok(boot.loaded.some((p) => p.includes('canvas-stophook')), 'real stophook module loaded by the broker');
+    assert.ok(boot.loaded.some((p) => p.includes('canvas-inbox-watcher')), 'real inbox-watcher module loaded by the broker');
+    assert.equal(boot.failedExt.length, 0, `no extension failed to load: ${JSON.stringify(boot.failedExt)}`);
+    assert.equal(boot.resuming, false, 'fresh start (no --session)');
+    assert.equal(boot.prompt, 'spike task', 'kickoff prompt is the last positional');
+    // The REAL stophook session_start handler ran inside the broker and wrote shared
+    // canvas state (proves the hook chain, not just the boot).
+    const afterBoot = h.node(id);
+    assert.equal(afterBoot.pi_session_id, boot.sessionId, 'stophook captured pi_session_id');
+    assert.equal(afterBoot.status, 'active', 'child active after boot');
+    // ---- MILESTONE 3: a clean finish drives a real transition to done --------
+    // push --final flips status=done; the broker's agent_end runs the REAL stophook
+    // clean-exit branch (status already done → ctx.shutdown → broker disposes/exits).
+    await h.finish(id, 'spike done');
+    assert.equal(h.status(id), 'done', 'real stophook agent_end resolved the node to done');
+});

package/dist/core/__tests__/grace-clock.test.js

@@ -1,45 +1,45 @@
 // Run with: node --import tsx/esm --test src/core/__tests__/grace-clock.test.ts
 //
-// AXIS: the REVIVE_GRACE_MS double-spawn guard (daemon invariant 10), exercised
-// FAITHFULLY with a CONTROLLED CLOCK via the harness's injectable tick(now).
+// HEADLESS RETARGET (foundation-spec §C.10 + §E). Drives a broker-hosted
+// (paneless) node fabricated DIRECTLY in the canvas — no real tmux session, no
+// remain-on-exit pane, and NO real broker boot. The grace decision is pure
+// daemon logic, so the test never pays the ~5s SDK-boot cost.
 //
-// Why this exists (MINOR-4): the harness exposes superviseTick's injectable
-// `now` through h.tick(now), but every other faithful test calls h.tick() with
-// no arg — so the grace window (the guard that a pi observed dead-while-its-pane-
-// lives must pend through REVIVE_GRACE_MS before a revive, lest a revive land in
-// the transient old-pi-dies→fresh-pi-boots gap and DOUBLE-SPAWN) was never
-// exercised end-to-end. daemon-liveness.test.ts pins livenessVerdict purely and
-// drives superviseTick with a FABRICATED pi-death (deadPid); this drives a REAL
-// fake-pi boot, kills it under a FROZEN (remain-on-exit) pane so the pane stays
-// alive while pi is genuinely dead, then walks a deterministic clock across the
-// grace boundary.
+// (1) BUG LOCKED — the REVIVE_GRACE_MS double-spawn guard (daemon invariant 10,
+//     MINOR-4). A node whose engine pid is observed DEAD must pend through the
+//     REVIVE_GRACE_MS window before the daemon revives it; revive too early and
+//     it lands in the transient old-pi-dies→fresh-pi-boots gap and DOUBLE-SPAWNS
+//     a second vehicle on the same .jsonl.
 //
-// This file is ADDITIVE and uses ONLY the public Harness API + h.tick(now) +
-// test-local tmux/file reads (the same shape as live-mutation.test.ts's
-// firstPaneOf/demote helpers). It does NOT edit harness.ts / fake-pi-host.ts or
-// any production file, and adds no harness helper.
+// (2) WHY MODEL-LEVEL, NOT TMUX CHROME — the guard lives entirely in pure daemon
+//     logic: livenessVerdict(piPidAlive,deadFor) → REVIVE_GRACE_MS → the
+//     unhealthySince clock → revivedThisTick (crtrd.ts). For a broker the dead-pid
+//     path routes handleBrokerLiveness → handleLiveWindow VERBATIM (intent is
+//     neither refresh nor idle-release), exercising the SAME grace machinery as a
+//     tmux node. A broker is supervised purely by row.pi_pid, so a fabricated row
+//     carrying a known-DEAD pid + a recorded pi_session_id (so it routes the
+//     crash/grace path, NOT the never-booted boot-failure branch) reproduces the
+//     exact "dead but supervised" state with no process at all.
+//
+// (3) HOW THE FABRICATED DRIVE STILL FAILS IF THE BUG REGRESSES — we walk
+//     h.tick(now) across the grace boundary with a deterministic clock and assert
+//     getNode(B).cycles (reviveNode bumps cycles + runs transition('revive')
+//     BEFORE it spawns — revive.ts:114,145 — so a revive's model effect is
+//     observable INSTANTLY, no awaitBoot needed). If the pending branch is removed
+//     (revive fires on first-observed-dead), the WITHIN-GRACE tick revives →
+//     cycles bumps early → the "cycles unchanged" asserts go RED. Verified by
+//     reverting livenessVerdict's `deadFor < REVIVE_GRACE_MS` pending branch
+//     (see bug-injection report).
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { createHarness, hasTmux } from './helpers/harness.js';
+import { createHarness } from './helpers/harness.js';
 import { isPidAlive } from '../../daemon/crtrd.js';
-const SKIP = !hasTmux() ? 'tmux unavailable' : false;
-function sessionExists(session) {
-    return spawnSync('tmux', ['has-session', '-t', session], { stdio: 'ignore' }).status === 0;
-}
-/** Count the fake-pi boots recorded for a node (one line per boot in
- *  fake-pi.boots.jsonl) — the observable for "did a revive double-spawn?". */
-function bootCount(home, id) {
-    try {
-        return readFileSync(join(home, 'nodes', id, 'fake-pi.boots.jsonl'), 'utf8')
-            .split('\n')
-            .filter((l) => l.trim() !== '').length;
-    }
-    catch {
-        return 0;
-    }
+// A pid that is 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; // fall back to an implausibly-high pid
 }
 // REVIVE_GRACE_MS is 20_000 (crtrd.ts). We choose offsets well inside / well
 // past it so the test is robust to the exact value without importing it.
@@ -47,69 +47,66 @@ const NOW = 5_000_000;
 const WITHIN_GRACE = NOW + 10_000; // < 20s after first-observed-dead → still pending
 const PAST_GRACE = NOW + 25_000; //  > 20s after first-observed-dead → revive
 // ===========================================================================
-// The grace window guards against a double-spawn: while a node's pane is alive
-// but its pi has been observed dead for LESS than REVIVE_GRACE_MS, the daemon
-// must NOT revive (a revive there would race the in-flight respawn and spawn a
-// second vehicle on the same pane). Once the pi has been dead PAST the grace, a
-// revive proceeds.
+// The grace window guards against a double-spawn: while a node's engine pid has
+// been observed dead for LESS than REVIVE_GRACE_MS, the daemon must NOT revive
+// (a revive there would race the in-flight respawn and spawn a second vehicle on
+// the same conversation). Once the pid has been dead PAST the grace, a revive
+// proceeds and cycles advances.
 // ===========================================================================
-test('grace clock: a dead-pi/alive-pane node does NOT revive within REVIVE_GRACE_MS, but DOES once it elapses', { skip: SKIP, timeout: 120_000 }, async () => {
-    const h = await createHarness({ sessionPrefix: 'crtr-grace' });
+test('grace clock: a dead-pi broker does NOT revive within REVIVE_GRACE_MS, but DOES once it elapses', { timeout: 30_000 }, async () => {
+    const h = await createHarness({ headless: true, sessionPrefix: 'crtr-grace' });
     try {
-        const A = h.spawnRoot('resident root');
-        const B = await h.spawnChild(A, 'do the work', { kind: 'developer' });
-        // The boot proof carries the live fake-pi pid; the row records it via the
-        // real session_start hook. Both are the SAME process — that pid is what
-        // handleLiveWindow judges liveness on.
-        const boot = await h.awaitBoot(B);
+        const dead = deadPid();
+        assert.equal(isPidAlive(dead), false, 'fabrication precondition: the supervised pid is dead');
+        // Fabricate the EXACT "dead but supervised" broker state directly — no
+        // boot. pi_session_id is SET so handleBrokerLiveness routes the crash/grace
+        // path (handleLiveWindow), NOT the never-booted boot-failure branch; intent
+        // is null so it is neither the refresh nor the idle-release early-return.
+        const B = h.fabricateBrokerNode({
+            kind: 'developer',
+            status: 'active',
+            intent: null,
+            pi_pid: dead,
+            pi_session_id: 'sess-grace-B',
+        });
         const b0 = h.node(B);
-        assert.equal(b0.status, 'active', 'B active after boot');
-        assert.equal(b0.intent ?? null, null, 'B intent=null (NOT idle-release — the grace path, not the frozen early-return)');
-        assert.equal(b0.pi_pid, boot.pid, 'row pi_pid == the live fake-pi pid (recorded at session_start)');
-        assert.equal(bootCount(h.home, B), 1, 'exactly one boot so far');
-        // Arm remain-on-exit on B's window so that when we kill its pi the PANE
-        // survives (frozen) rather than closing — that is the only way to produce
-        // the "pane alive but pi dead" state handleLiveWindow's grace path judges.
-        const ro = spawnSync('tmux', ['set-window-option', '-t', b0.window, 'remain-on-exit', 'on'], { stdio: 'ignore' });
-        assert.equal(ro.status, 0, 'armed remain-on-exit on B\'s window');
-        // Kill the fake-pi. pi dies; the frozen pane stays alive.
-        process.kill(boot.pid, 'SIGKILL');
-        await h.waitFor(() => !isPidAlive(boot.pid), { timeoutMs: 10_000, label: 'fake-pi pid dead' });
-        assert.equal(h.paneAlive(B), true, 'pane is FROZEN alive after pi death (remain-on-exit)');
-        // --- TICK 1 @ NOW: first observation of the dead pi → 'pending'. The
+        assert.equal(b0.host_kind, 'broker', 'B is broker-hosted (paneless)');
+        assert.equal(b0.status, 'active', 'B active');
+        assert.equal(b0.intent ?? null, null, 'B intent=null (the grace path, not the idle-release early-return)');
+        assert.equal(b0.pi_pid, dead, 'row pi_pid == the known-dead pid');
+        assert.equal(b0.window ?? null, null, 'no tmux window — broker host');
+        assert.equal(b0.cycles ?? 0, 0, 'no revive yet — cycles at 0');
+        // --- TICK 1 @ NOW: first observation of the dead pid → 'pending'. The
         //     daemon records first-observed-dead and does NOT revive. ---
         await h.tick(NOW);
         {
             const b = h.node(B);
-            assert.equal(bootCount(h.home, B), 1, 'first tick: NO revive on first-observed-dead (still 1 boot)');
-            assert.equal(b.pi_pid, boot.pid, 'pi_pid unchanged — no fresh vehicle spawned');
+            assert.equal(b.cycles ?? 0, 0, 'first tick: NO revive on first-observed-dead (cycles still 0)');
+            assert.equal(b.pi_pid, dead, 'pi_pid unchanged — no fresh vehicle launched');
             assert.equal(b.status, 'active', 'B left active (pending, not revived)');
-            assert.equal(h.paneAlive(B), true, 'frozen pane still alive');
         }
         // --- TICK 2 @ NOW+10s (WITHIN the 20s grace): STILL pending. This is the
         //     double-spawn guard: a revive here would land in the respawn gap. ---
         await h.tick(WITHIN_GRACE);
         {
             const b = h.node(B);
-            assert.equal(bootCount(h.home, B), 1, 'within REVIVE_GRACE_MS: NO double-spawn — the dead pi must pend, not revive');
-            assert.equal(b.pi_pid, boot.pid, 'pi_pid STILL the dead pid — guard held');
+            assert.equal(b.cycles ?? 0, 0, 'within REVIVE_GRACE_MS: NO double-spawn — the dead pi must pend, not revive (cycles still 0)');
+            assert.equal(b.pi_pid, dead, 'pi_pid STILL the dead pid — guard held');
             assert.equal(b.status, 'active', 'B still active inside the grace window');
         }
-        // --- TICK 3 @ NOW+25s (PAST the 20s grace): now a revive proceeds — a
-        //     FRESH fake-pi boots in the frozen pane (respawn-pane -k resume). ---
+        // --- TICK 3 @ NOW+25s (PAST the 20s grace): now a revive proceeds —
+        //     reviveNode bumps cycles + transition('revive') BEFORE the (detached,
+        //     unawaited) broker spawn, so the model effect is visible immediately. ---
         await h.tick(PAST_GRACE);
-        await h.awaitBoot(B, { minCount: 2, timeoutMs: 30_000 });
-        assert.ok(bootCount(h.home, B) >= 2, 'past REVIVE_GRACE_MS: the dead pi is revived → a fresh vehicle boots');
-        await h.waitForStatus(B, 'active');
         {
             const b = h.node(B);
-            assert.equal(b.status, 'active', 'B active after the grace-window revive');
-            assert.notEqual(b.pi_pid, boot.pid, 'pi_pid advanced to the fresh vehicle — the revive landed');
+            assert.equal(b.cycles ?? 0, 1, 'past REVIVE_GRACE_MS: the dead pi is revived → cycles bumped to 1');
+            assert.equal(b.status, 'active', 'B active after the grace-window revive (transition(revive))');
+            assert.equal(b.intent ?? null, null, 'intent cleared by the revive');
+            assert.equal(b.pi_pid ?? null, null, 'pi_pid cleared by the window-backed revive (clearPid)');
         }
     }
     finally {
-        const session = h.session;
         await h.dispose();
-        assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
     }
 });

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

@@ -1,4 +1,4 @@
-import type { NodeMeta, NodeStatus, Mode, Lifecycle } from '../../canvas/types.js';
+import type { NodeMeta, NodeStatus, Mode, Lifecycle, ExitIntent } from '../../canvas/types.js';
 import type { InboxEntry } from '../../feed/inbox.js';
 /** True when a usable tmux is on PATH — tests gate on this and SKIP otherwise. */
 export declare function hasTmux(): boolean;
@@ -30,6 +30,18 @@ export interface CliResult {
 }
 export interface HarnessOpts {
     sessionPrefix?: string;
+    /** HEADLESS mode: drive ONLY broker-hosted (paneless) nodes. When set the
+     *  harness does NOT gate on tmux, does NOT eagerly create the isolated tmux
+     *  session, and skips the per-pane `set-environment` seeding — nothing in a
+     *  headless run opens a window. CRTR_NODE_SESSION is still set to the isolated
+     *  name (and dispose still kill-sessions it) because `spawnChild` in spawn.ts
+     *  calls `ensureSession()` UNCONDITIONALLY to record each node's durable
+     *  `home_session` revive target — even a broker birth, which then ignores it.
+     *  So `node new --headless` may LAZILY create that one isolated session as a
+     *  side effect, but never a window/pane; the broker boots detached, supervised
+     *  by pid. Headless tests must use `spawnHeadlessChild`, never `spawnChild`
+     *  (which opens a real window). See createHeadlessHarness(). */
+    headless?: boolean;
 }
 export interface SpawnOpts {
     kind?: string;
@@ -37,10 +49,30 @@ export interface SpawnOpts {
     lifecycle?: Lifecycle;
     id?: string;
 }
+/** Fabricate a broker-hosted node row directly — tmux-free, boot-free, NO
+ *  subprocess. Builds a full NodeMeta (identity ∪ runtime) and calls createNode,
+ *  which seeds BOTH halves in one statement (seedRow writes status/intent/pi_pid
+ *  from the meta; writeMeta persists pi_session_id). The result is a row the
+ *  daemon supervises by pid exactly as if a real broker had booted — so a test
+ *  can drive superviseTick(now) liveness decisions against arbitrary liveness
+ *  state (alive/dead pid, with/without session, any intent) with ZERO real boot.
+ *  See foundation-spec §E.2. */
+export interface FabricateOpts {
+    parent?: string | null;
+    kind?: string;
+    mode?: Mode;
+    lifecycle?: Lifecycle;
+    status?: NodeStatus;
+    intent?: ExitIntent;
+    pi_pid?: number | null;
+    pi_session_id?: string | null;
+    id?: string;
+}
 export interface Harness {
     home: string;
     session: string;
     spawnRoot(task: string, o?: SpawnOpts): string;
+    fabricateBrokerNode(o?: FabricateOpts): 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>;
@@ -84,4 +116,6 @@ export interface Harness {
     }[];
     dispose(): Promise<void>;
 }
+/** Thin wrapper: a headless-only harness (broker-hosted, paneless nodes). */
+export declare function createHeadlessHarness(opts?: HarnessOpts): Promise<Harness>;
 export declare function createHarness(opts?: HarnessOpts): Promise<Harness>;

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

@@ -103,8 +103,13 @@ async function waitFor(probe, opts = {}) {
         await new Promise((r) => setTimeout(r, intervalMs));
     }
 }
+/** Thin wrapper: a headless-only harness (broker-hosted, paneless nodes). */
+export async function createHeadlessHarness(opts = {}) {
+    return createHarness({ ...opts, headless: true });
+}
 export async function createHarness(opts = {}) {
-    if (!hasTmux())
+    const headless = opts.headless === true;
+    if (!headless && !hasTmux())
         throw new Error('createHarness: tmux not available');
     const origHome = process.env['CRTR_HOME'];
     const origPiBinary = process.env['CRTR_PI_BINARY'];
@@ -162,17 +167,23 @@ export async function createHarness(opts = {}) {
     // a custom-socket server (`tmux -L foo`) would be invisible to it; this harness
     // therefore assumes the default socket and only ever kill-sessions, never the
     // server.
-    spawnSync('tmux', ['new-session', '-d', '-s', session, '-c', CROUTER, 'sleep 100000'], {
-        stdio: 'ignore',
-    });
-    // Put CRTR_PI_BINARY in the SESSION environment so EVERY pane spawned in this
-    // session inherits it — critically the fake-pi's OWN process, so when its real
-    // stophook fires reviveInPlace (respawn-pane -k on its own pane, the refresh-
-    // yield path) the in-process piCommand there substitutes the fake-pi too.
-    spawnSync('tmux', ['set-environment', '-t', session, 'CRTR_PI_BINARY', FAKE_PI_BINARY], {
-        stdio: 'ignore',
-    });
-    spawnSync('tmux', ['set-environment', '-t', session, 'CRTR_HOME', home], { stdio: 'ignore' });
+    // HEADLESS: skip ALL eager tmux setup. No node in a headless run opens a
+    // window, so there is no pane to pre-seed an env into and no session to pre-
+    // create. (`node new --headless` may still lazily ensureSession() the isolated
+    // name for home_session — dispose kill-sessions it regardless.)
+    if (!headless) {
+        spawnSync('tmux', ['new-session', '-d', '-s', session, '-c', CROUTER, 'sleep 100000'], {
+            stdio: 'ignore',
+        });
+        // Put CRTR_PI_BINARY in the SESSION environment so EVERY pane spawned in this
+        // session inherits it — critically the fake-pi's OWN process, so when its real
+        // stophook fires reviveInPlace (respawn-pane -k on its own pane, the refresh-
+        // yield path) the in-process piCommand there substitutes the fake-pi too.
+        spawnSync('tmux', ['set-environment', '-t', session, 'CRTR_PI_BINARY', FAKE_PI_BINARY], {
+            stdio: 'ignore',
+        });
+        spawnSync('tmux', ['set-environment', '-t', session, 'CRTR_HOME', home], { stdio: 'ignore' });
+    }
     const pidsToKill = new Set();
     let nextRootSeq = 0;
     // -- env for a subprocess CLI invocation -----------------------------------
@@ -286,6 +297,27 @@ export async function createHarness(opts = {}) {
             closeDb();
             return id;
         },
+        fabricateBrokerNode(o = {}) {
+            const id = o.id ?? `brk-${process.pid}-${nextRootSeq++}`;
+            const meta = {
+                node_id: id,
+                name: id,
+                created: new Date().toISOString(),
+                cwd: CROUTER,
+                host_kind: 'broker',
+                kind: o.kind ?? 'developer',
+                mode: o.mode ?? 'base',
+                lifecycle: o.lifecycle ?? 'terminal',
+                parent: o.parent ?? null,
+                pi_session_id: o.pi_session_id ?? null,
+                status: o.status ?? 'active',
+                intent: o.intent ?? null,
+                pi_pid: o.pi_pid ?? null,
+            };
+            createNode(meta);
+            closeDb();
+            return id;
+        },
         async spawnChild(parentId, task, o = {}) {
             const before = new Set(nodeDirs());
             const args = ['node', 'new', task, '--parent', parentId, '--cwd', CROUTER];
@@ -479,6 +511,32 @@ export async function createHarness(opts = {}) {
         },
         async dispose() {
             spawnSync('tmux', ['kill-session', '-t', session], { stdio: 'ignore' });
+            // Best-effort: a superviseTick-triggered revive of a fabricated node fires
+            // a DETACHED throwaway broker (it loads the real SDK; the rmSync of home
+            // below makes a mid-boot one self-terminate when its files vanish). Kill
+            // any that recorded a pid first — scan every node's row pid + recorded
+            // boot pids and add them to the kill set.
+            closeDb();
+            for (const d of nodeDirs()) {
+                try {
+                    const n = getNode(d);
+                    if (n?.pi_pid != null)
+                        pidsToKill.add(n.pi_pid);
+                }
+                catch {
+                    /* row gone — fine */
+                }
+                for (const line of readLines(join(nodeDir(d), 'fake-pi.boots.jsonl'))) {
+                    try {
+                        const p = JSON.parse(line).pid;
+                        if (typeof p === 'number')
+                            pidsToKill.add(p);
+                    }
+                    catch {
+                        /* skip */
+                    }
+                }
+            }
             for (const p of pidsToKill) {
                 try {
                     process.kill(p, 'SIGKILL');