@north-light/crouter 0.3.154

package/dist/core/__tests__/full/issue-146-yield-spawn-focus.test.js

@@ -0,0 +1,107 @@
+// Run with: CRTR_MAX_LIVE_BROKERS=1000 node --import tsx/esm --test src/core/__tests__/full/issue-146-yield-spawn-focus.test.ts
+//
+// Issue #146 composed regression: a parent yields while a child launch is in flight,
+// its first cycling broker dies before session_start, and real `surface node focus`
+// then requests a strict resume. The locked revive arbiter must keep the durable refresh
+// authoritative, retry as a fresh cycle, and commit its intent/note only after the
+// retry reaches session_start.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createHarness, hasTmux, TMUX_TIMEOUT_MS, } from '../helpers/harness.js';
+import { isPidAlive } from '../../canvas/pid.js';
+import { updateNode } from '../../canvas/canvas.js';
+import { readYieldMessage, yieldMessagePath } from '../../runtime/kickoff.js';
+import { FAIL_BEFORE_SESSION_START_ONCE } from '../fixtures/fake-engine.js';
+const SKIP = !hasTmux() ? 'tmux unavailable' : false;
+function makeCallerPane(session) {
+    const result = spawnSync('tmux', ['split-window', '-d', '-t', session, '-P', '-F', '#{pane_id}', 'sleep 100000'], { encoding: 'utf8', timeout: TMUX_TIMEOUT_MS });
+    const pane = (result.stdout ?? '').trim();
+    assert.ok(pane.startsWith('%'), `expected a tmux pane id, got "${pane}" (stderr: ${result.stderr})`);
+    return pane;
+}
+function outputField(stdout, name) {
+    return stdout.match(new RegExp(`^- ${name}:\\s*(.*)$`, 'm'))?.[1]?.trim();
+}
+test('yield + concurrent child spawn + failed cycle + focus preserves fresh-refresh authority', { skip: SKIP, timeout: 180_000 }, async () => {
+    const h = await createHarness({ sessionPrefix: 'crtr-issue146' });
+    try {
+        const root = h.spawnRoot('issue 146 acting root');
+        const parent = await h.spawnHeadlessChild(root, 'issue 146 orchestrator parent', {
+            kind: 'developer',
+            mode: 'orchestrator',
+        });
+        // Keep this test-only orchestrator resident so the fake engine's automatic
+        // kickoff turn cannot legitimately idle-release it after session_start; the
+        // assertions below can then observe the confirmation commit itself.
+        updateNode(parent, { lifecycle: 'resident' });
+        const initial = h.node(parent);
+        const oldPid = initial.pi_pid;
+        const baseBoots = h.bootCount(parent);
+        const baseCycles = initial.cycles ?? 0;
+        assert.ok(initial.pi_session_file != null && existsSync(initial.pi_session_file), 'parent booted with a real session file');
+        assert.equal(isPidAlive(oldPid), true, 'parent broker is alive before yielding');
+        // spawnHeadlessChild drives real `node new` synchronously, then yields while
+        // awaiting the child broker boot. Start it without awaiting so parent yield
+        // overlaps that boot exactly as the reported issue did.
+        const childBoot = h.spawnHeadlessChild(parent, 'issue 146 concurrent child');
+        const note = `Issue #146 ${FAIL_BEFORE_SESSION_START_ONCE} retain this yield handoff`;
+        const yielded = h.cli(parent, ['node', 'yield', note]);
+        assert.equal(yielded.code, 0, `node yield should succeed\n--stderr--\n${yielded.stderr}`);
+        assert.equal(h.node(parent)?.intent, 'refresh', 'yield durably records refresh intent');
+        const child = await childBoot;
+        assert.ok(h.subscriptions(parent).some((entry) => entry.node_id === child && entry.active), 'parent remains actively subscribed to the concurrently spawned child');
+        // End the old engine turn through the real stophook. Its ChildProcess exit
+        // automatically enqueues policy row 3 (refresh → respawn-fresh); no
+        // liveness tick or grace is involved. The short-lived-exit throttle may
+        // defer the replacement briefly, so observe the new pid rather than a
+        // fixed clock.
+        await h.stop(parent);
+        await h.waitFor(() => !isPidAlive(oldPid), { label: 'yielded parent broker exited' });
+        assert.equal(h.node(parent)?.intent, 'refresh', 'refresh intent survives the old broker exit');
+        const failedCyclePid = await h.waitFor(() => {
+            const pid = h.node(parent)?.pi_pid;
+            return pid != null && pid !== oldPid ? pid : null;
+        }, { label: 'exit-event refresh launch recorded its broker pid', timeoutMs: 30_000 });
+        await h.waitFor(() => !isPidAlive(failedCyclePid), {
+            label: 'one-shot cycling broker died before session_start',
+        });
+        // Capture before focus but assert afterward. This keeps the competing real
+        // focus path non-vacuous even if one of these durable preconditions regresses.
+        const preFocus = {
+            cycles: h.node(parent)?.cycles,
+            intent: h.node(parent)?.intent ?? null,
+            cyclePending: h.node(parent)?.cycle_pending,
+            note: readYieldMessage(parent),
+            noteExists: existsSync(yieldMessagePath(parent)),
+            boots: h.bootCount(parent),
+        };
+        const callerPane = makeCallerPane(h.session);
+        const focused = h.cli(root, ['surface', 'node', 'focus', parent, '--pane', callerPane]);
+        const confirmed = await h.awaitBoot(parent, { minCount: baseBoots + 1, timeoutMs: 120_000 });
+        const final = h.node(parent);
+        assert.equal(focused.code, 0, `surface node focus should succeed\n--stderr--\n${focused.stderr}`);
+        assert.equal(outputField(focused.stdout, 'revived'), 'true', 'real focus drives the production resume=true revive entrypoint');
+        assert.equal(preFocus.boots, baseBoots, 'failed cycling launch never reached session_start');
+        assert.equal(preFocus.cycles, baseCycles + 1, 'first actual refresh launch increments cycles exactly once');
+        assert.equal(preFocus.intent, 'refresh', 'refresh intent survives the pre-session_start failure');
+        assert.equal(preFocus.cyclePending, true, 'failed cycling launch remains pending before confirmation');
+        assert.equal(preFocus.note?.trim(), note, 'failed launch leaves the complete yield handoff durable');
+        assert.equal(preFocus.noteExists, true, 'yield handoff file remains present before confirmation');
+        assert.equal(confirmed.resuming, false, 'focus cannot reopen the old session while refresh is pending');
+        assert.ok(confirmed.prompt !== null && confirmed.prompt.includes(note), 'successful cycling retry receives the original yield note');
+        assert.equal(final.cycles, baseCycles + 2, 'focus retry increments from the locked latest cycle exactly once');
+        assert.equal(final.cycle_pending, false, 'confirmed session_start clears the pending-cycle marker');
+        assert.equal(final.intent ?? null, null, 'confirmed session_start commits the refresh intent');
+        assert.equal(readYieldMessage(parent), null, 'confirmed session_start clears the one-shot yield handoff');
+        assert.equal(existsSync(yieldMessagePath(parent)), false, 'yield handoff file is gone only after confirmation');
+        const childState = h.node(child);
+        assert.equal(childState.status, 'active', 'concurrent child remains booted');
+        assert.ok(childState.pi_pid != null && isPidAlive(childState.pi_pid), 'concurrent child broker remains alive');
+        assert.ok(h.subscriptions(parent).some((entry) => entry.node_id === child && entry.active), 'parent-child subscription survives the parent refresh');
+    }
+    finally {
+        await h.dispose();
+    }
+});

package/dist/core/__tests__/full/park-clock-release.test.d.ts

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

package/dist/core/__tests__/full/park-clock-release.test.js

@@ -0,0 +1,56 @@
+// Regression: a boot-revived settled node that receives no new work must still
+// traverse bounded release. This is the construction that prevents the observed
+// 57-broker / ~5.4GB leak: session_start, not agent_settled, arms the clock.
+import { after, before, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { updateNode } from '../../canvas/index.js';
+import { isPidAlive } from '../../canvas/pid.js';
+import { reviveNode } from '../../runtime/revive.js';
+import { createHarness } from '../helpers/harness.js';
+let h;
+let root;
+before(async () => {
+    h = await createHarness({ headless: true, sessionPrefix: 'crtr-park-clock' });
+    root = h.spawnRoot('park-clock suite root');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+test('a revived settled node with no work releases and leaves no broker', { timeout: 30_000 }, async () => {
+    const nodeId = h.fabricateBrokerNode({
+        id: 'settled-no-work',
+        parent: root,
+        status: 'idle',
+        intent: 'idle-release',
+    });
+    // The bound must comfortably exceed the remainder of session_start dispatch:
+    // the stophook arms the clock inside its own session_start handler, and a
+    // bound shorter than the still-running dispatch lets the release timer
+    // preempt at a later handler's await point — the broker then exits before
+    // the boot proof lands and awaitBoot never observes the boot. Production's
+    // 15-minute bound can never preempt a boot; keep the test override above
+    // dispatch time but far below the waitFor budget.
+    updateNode(nodeId, {
+        launch: {
+            extensions: [],
+            tools: [],
+            systemPrompt: '',
+            env: { CRTR_TEST_UNATTENDED_PARK_MS: '1500' },
+        },
+    });
+    reviveNode(nodeId, { resume: true });
+    const boot = await h.awaitBoot(nodeId);
+    assert.equal(h.fleet.has(nodeId), true, 'the revived broker is fleet-owned');
+    await h.waitFor(() => {
+        const node = h.node(nodeId);
+        return node?.status === 'idle' && node.intent === 'idle-release' && !isPidAlive(boot.pid);
+    }, { timeoutMs: 10_000, intervalMs: 20, label: 'park-clock release and broker exit' });
+    // The pid vanishing is not the fleet learning about it: wait for the child
+    // 'exit' delivery + its policy job, which is what actually frees the slot.
+    await h.awaitFleetExit(nodeId);
+    assert.equal(h.fleet.has(nodeId), false, 'exit policy forgets the idle-release broker');
+    assert.equal(h.node(nodeId)?.intent, 'idle-release', 'the row remains durably dormant');
+    await h.tick();
+    assert.equal(h.fleet.has(nodeId), false, 'a supervision tick does not revive without inbox work');
+});

package/dist/core/__tests__/full/yield-message-transaction.test.d.ts

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

package/dist/core/__tests__/full/yield-message-transaction.test.js

@@ -0,0 +1,70 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/full/yield-message-transaction.test.ts
+//
+// Regression: one-shot <yield-message/> handoff must survive pre-session_start cycle
+// death and only clear once session_start confirms a successful boot. This test
+// runs against the real broker process (headless harness) and a deterministic
+// one-shot pre-start fault injection so a single retry is exercised in-band.
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync } from 'node:fs';
+import { createHarness } from '../helpers/harness.js';
+import { isPidAlive } from '../../canvas/pid.js';
+import { readYieldMessage, yieldMessagePath } from '../../runtime/kickoff.js';
+import { FAIL_BEFORE_SESSION_START_ONCE } from '../fixtures/fake-engine.js';
+let h;
+let root;
+before(async () => {
+    h = await createHarness({ headless: true, sessionPrefix: 'crtr-bug146' });
+    root = h.spawnRoot('bug146-suite root');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+// 30s (approved full-tier cap): three real broker boots plus the exit-policy
+// respawn throttle's first ~5s backoff before the successful retry.
+test('yield-message survives one pre-session_start retry and clears on session_start', { timeout: 30_000 }, async () => {
+    const note = `Issue #146 pre-session_start replay ${FAIL_BEFORE_SESSION_START_ONCE} keeps the wake note`;
+    const id = await h.spawnHeadlessChild(root, 'headless worker — yield message transactional retry');
+    const baseBoot = h.bootCount(id);
+    const baseCycles = h.node(id).cycles ?? 0;
+    const oldPid = h.node(id).pi_pid;
+    const rc = h.cli(id, ['node', 'yield', note]);
+    assert.equal(rc.code, 0, `node yield should succeed\n--stderr--\n${rc.stderr}`);
+    // `node yield` arms intent=refresh; the current turn ending is what lets the
+    // stophook release the old broker. Its real ChildProcess exit enqueues policy
+    // row 3 and launches the fresh cycle (after any short-lived-exit backoff), so
+    // there is no liveness tick or grace clock.
+    await h.stop(id);
+    await h.waitFor(() => !isPidAlive(oldPid), { label: 'yielded broker exited before session_start' });
+    // The initial refresh attempt launches and fails before session_start,
+    // leaving the note still present in node context.
+    const failedCyclePid = await h.waitFor(() => {
+        const pid = h.node(id)?.pi_pid;
+        return pid != null && pid !== oldPid ? pid : null;
+    }, { label: 'exit-event refresh attempt recorded its broker pid', timeoutMs: 30_000 });
+    await h.waitFor(() => !isPidAlive(failedCyclePid), { label: 'one-shot cycling broker died before session_start' });
+    const afterFirstExit = h.node(id);
+    assert.equal(afterFirstExit?.cycles, baseCycles + 1, 'the first refresh attempt advances cycles');
+    assert.equal(afterFirstExit?.cycle_pending, true, 'cycle_pending remains true until session_start confirms');
+    assert.equal(readYieldMessage(id), note, 'yield note stays present after pre-session_start failure');
+    assert.equal(existsSync(yieldMessagePath(id)), true, 'yield file survives the failed cycle');
+    // That failed attempt's real exit classifies row 7 (cycle_pending) and keeps
+    // the retry in cycle mode until session_start confirms. The respawn throttle
+    // may delay it briefly, but no poll is required.
+    const boot = await h.awaitBoot(id, { minCount: baseBoot + 1, timeoutMs: 120_000 });
+    const afterRetry = h.node(id);
+    assert.equal(afterRetry?.cycles, baseCycles + 2, 'the retry advances once from the latest locked cycle');
+    assert.equal(afterRetry?.cycle_pending, false, 'session_start cleared cycle_pending');
+    assert.equal(readYieldMessage(id), null, 'yield note cleared only after confirmed session_start');
+    assert.equal(existsSync(yieldMessagePath(id)), false, 'yield file removed after confirmed boot');
+    assert.ok(boot.prompt !== null, 'successful retry records a kickoff prompt');
+    assert.equal(boot.prompt.includes(note), true, 'the successful retry kickoff still contains the yield note');
+    assert.match(boot.prompt, /<goal file="[^"]+">/, 'a no-roadmap base refresh includes its original goal');
+    assert.equal(boot.prompt.includes('headless worker — yield message transactional retry'), true, 'the kickoff carries the original base-node mandate');
+    assert.equal(boot.resuming, false, 'yield refresh roots a fresh cycle instead of strictly resuming');
+    const updated = h.node(id);
+    assert.equal(updated?.mode, 'base', 'a plain yield refresh remains base');
+    assert.ok(updated?.pi_session_id != null, 'successful retry recorded a session id');
+});
+// Keep this file one purpose and one assertion surface: real runtime replay.

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 { BrokerClient } from '../../broker-client/index.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: BrokerClient;
+    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 BrokerClient 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,182 @@
+// 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 { BrokerClient } from '../../broker-client/index.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);
+// Reads the canonical event log (job/log.jsonl) — the sole write path for
+// broker.runtime.diagnostic events (e.g. viewer-drop reasons) since the
+// logging hard cut. job/broker.log is raw stdout/stderr residue only and no
+// longer carries these reasons; do not fall back to it.
+export function brokerLogText(h, id) {
+    try {
+        return readFileSync(join(h.home, 'nodes', id, 'job', 'log.jsonl'), '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 BrokerClient 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 BrokerClient(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, such as snapshot accrual or
+    // persisted presence after a socket closes. 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/fleet.d.ts

@@ -0,0 +1,12 @@
+import { DaemonFleet, type DaemonFleetOpts } from '../../../daemon/fleet.js';
+export interface TestFleet {
+    fleet: DaemonFleet;
+    /** Await lane quiescence: every job enqueued so far (including jobs those
+     *  jobs enqueued) has settled. */
+    drain(): Promise<void>;
+}
+/** Construct a DaemonFleet on a private serial lane and bind it as THIS
+ *  process's fleet. Call in `before`/`beforeEach`; `bindFleet` throws on a
+ *  conflicting rebind, so the previous binding is reset first (same idiom as
+ *  resetEventSourceForTests). Pass `now` to inject the throttle clock. */
+export declare function bindTestFleet(opts?: Partial<Pick<DaemonFleetOpts, 'epoch' | 'now'>>): TestFleet;

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

@@ -0,0 +1,45 @@
+// helpers/fleet.ts — an in-process fleet binding for direct-tier tests.
+//
+// Post-cutover, every broker launch resolves `boundFleet()` (host.ts) and
+// `superviseTick`'s first line is `boundFleet()` — an unbound process throws by
+// design (D-2: launches happen only inside crtrd, or a test harness that
+// explicitly bound a fleet). Any test that calls reviveNode/spawnChild/
+// superviseTick in-process must bind one of these first.
+//
+// The binding is a REAL DaemonFleet on a private serial lane, mirroring the
+// daemon's own construction (crtrd.ts runDaemon): registration, the fleet.has
+// revive guard, exit-policy jobs, and the respawn throttle all behave exactly
+// as in production — only the lane is local so a test can `drain()` it to a
+// deterministic quiescent point instead of racing timers.
+import { DaemonFleet } from '../../../daemon/fleet.js';
+import { bindFleet, resetFleetForTests } from '../../runtime/fleet.js';
+/** Construct a DaemonFleet on a private serial lane and bind it as THIS
+ *  process's fleet. Call in `before`/`beforeEach`; `bindFleet` throws on a
+ *  conflicting rebind, so the previous binding is reset first (same idiom as
+ *  resetEventSourceForTests). Pass `now` to inject the throttle clock. */
+export function bindTestFleet(opts = {}) {
+    resetFleetForTests();
+    let lane = Promise.resolve();
+    const fleet = new DaemonFleet({
+        epoch: opts.epoch ?? 'test-epoch',
+        enqueue: (job) => {
+            lane = lane.then(() => job()).then(() => { }, (err) => {
+                // Policy jobs contain their own error handling; anything escaping is
+                // a genuine bug — surface it, never wedge the lane.
+                console.error('[test-fleet] lane job failed:', err);
+            });
+        },
+        ...(opts.now !== undefined ? { now: opts.now } : {}),
+    });
+    bindFleet(fleet);
+    return {
+        fleet,
+        async drain() {
+            let tail;
+            do {
+                tail = lane;
+                await tail;
+            } while (tail !== lane);
+        },
+    };
+}

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

@@ -0,0 +1,128 @@
+import { DaemonFleet } from '../../../daemon/fleet.js';
+import { type FleetExitStatus } from '../../runtime/fleet.js';
+import type { NodeMeta, NodeStatus, Mode, Lifecycle, ExitIntent } from '../../canvas/types.js';
+import type { InboxEntry } from '../../feed/inbox.js';
+export declare const TMUX_TIMEOUT_MS = 10000;
+/** True when a usable tmux is on PATH — tests gate on this and SKIP otherwise. */
+export declare function hasTmux(): boolean;
+export interface WaitOpts {
+    timeoutMs?: number;
+    intervalMs?: number;
+    label?: string;
+}
+export interface Injected {
+    content: string;
+    deliverAs?: string;
+}
+export interface BootProof {
+    pid: number;
+    nodeId: string;
+    resuming: boolean;
+    prompt: string | null;
+    extPaths: string[];
+    loaded: string[];
+    failedExt: string[];
+    env: Record<string, string | null>;
+    [k: string]: unknown;
+}
+export interface CliResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+    json?: unknown;
+}
+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/CRTR_ROOT_SESSION are still
+     *  scrubbed/restored for env hygiene, but no longer route placement: a managed
+     *  child opens NO viewer (it boots a detached broker, supervised by pid), and a
+     *  --root opens one viewer in the caller's current session. Headless tests must
+     *  use `spawnHeadlessChild`, never `spawnChild`. See createHeadlessHarness(). */
+    headless?: boolean;
+}
+export interface SpawnOpts {
+    kind?: string;
+    mode?: Mode;
+    lifecycle?: Lifecycle;
+    model?: string;
+    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;
+    pi_session_file?: string | null;
+    id?: string;
+}
+export interface Harness {
+    home: string;
+    /** Isolated HOME inherited by fake broker processes (provider state lives here). */
+    agentHome: 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>;
+    spawnHeadlessChildNoBoot(parentId: string, task: string, o?: SpawnOpts): Promise<string>;
+    turn(nodeId: string, text?: string): Promise<void>;
+    stop(nodeId: string, reason?: 'stop' | 'length' | 'aborted' | 'error', errorMessage?: string): Promise<void>;
+    finish(nodeId: string, finalText: string): Promise<void>;
+    tick(now?: number): Promise<void>;
+    fleet: DaemonFleet;
+    deliverExit(nodeId: string, status?: FleetExitStatus): Promise<void>;
+    drainFleet(): Promise<void>;
+    awaitFleetExit(nodeId: string, timeoutMs?: number): Promise<void>;
+    awaitBoot(nodeId: string, o?: {
+        minCount?: number;
+        timeoutMs?: number;
+    }): Promise<BootProof>;
+    awaitWake(nodeId: string, o?: {
+        sinceCount?: number;
+        timeoutMs?: number;
+        match?: RegExp;
+    }): Promise<string[]>;
+    waitForStatus(nodeId: string, status: NodeStatus, timeoutMs?: number): Promise<void>;
+    waitForPaneGone(nodeId: string, timeoutMs?: number): Promise<void>;
+    waitFor<T>(probe: () => T | undefined | null | false, o?: WaitOpts): Promise<T>;
+    node(nodeId: string): NodeMeta | null;
+    status(nodeId: string): NodeStatus | null;
+    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;
+    }[];
+    subscriptions(nodeId: string): {
+        node_id: string;
+        active: boolean;
+    }[];
+    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>;