@crouton-kit/crouter 0.3.16 → 0.3.18

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

@@ -0,0 +1,115 @@
+// 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).
+//
+// 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.
+//
+// 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.
+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 { 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;
+    }
+}
+// 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.
+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.
+// ===========================================================================
+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' });
+    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 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
+        //     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.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.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). ---
+        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');
+        }
+    }
+    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

@@ -0,0 +1,78 @@
+import type { NodeMeta, NodeStatus, Mode, Lifecycle } 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;
+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;
+}
+export interface SpawnOpts {
+    kind?: string;
+    mode?: Mode;
+    lifecycle?: Lifecycle;
+    id?: string;
+}
+export interface Harness {
+    home: string;
+    session: string;
+    spawnRoot(task: string, o?: SpawnOpts): string;
+    spawnChild(parentId: string, task: string, o?: SpawnOpts): Promise<string>;
+    cli(nodeId: string | null, args: string[]): CliResult;
+    turn(nodeId: string, text?: string): Promise<void>;
+    stop(nodeId: string, reason?: 'stop' | 'length' | 'aborted' | 'error'): Promise<void>;
+    finish(nodeId: string, finalText: string): Promise<void>;
+    yieldNode(nodeId: string, note: string): Promise<void>;
+    tick(now?: 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[];
+    subscribers(nodeId: string): {
+        node_id: string;
+        active: boolean;
+    }[];
+    subscriptions(nodeId: string): {
+        node_id: string;
+        active: boolean;
+    }[];
+    dispose(): Promise<void>;
+}
+export declare function createHarness(opts?: HarnessOpts): Promise<Harness>;

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

@@ -0,0 +1,406 @@
+// helpers/harness.ts — a reusable, FAITHFUL integration-test driver for the
+// node/canvas runtime.
+//
+// It drives the REAL `crtr` CLI (as subprocesses, AS specific nodes) into a
+// REAL but isolated tmux session, substitutes the fake-pi vehicle (fixtures/
+// fake-pi-host.ts) for the LLM `pi` via the CRTR_PI_BINARY seam, fires the REAL
+// extension hooks inside that fake-pi over a polled control channel, and runs
+// the daemon decision pass in-process via superviseTick(now). Every assertion
+// reads straight off the canvas data layer. NOTHING here mocks the runtime.
+//
+// See harness-design.md §4/§5 and vehicle-and-hooks.md §6 for the architecture
+// this implements. The ONE production seam used is CRTR_PI_BINARY in
+// piCommand (src/core/runtime/tmux.ts) — no production file is modified.
+//
+// Isolation contract (harness-design.md §4a):
+//   • The harness itself runs AS a canvas node, so its OWN process.env carries
+//     the REAL canvas vars. We override CRTR_HOME (+ CRTR_PI_BINARY) for our own
+//     in-process reads/revives, and scrub every canvas var from each subprocess
+//     env. closeDb() rebinds sqlite to the isolated home before every read.
+//   • The isolated tmux session lives on the DEFAULT server (the runtime shells
+//     `tmux` with no -L, so an -L server would be invisible to the real CLI and
+//     to superviseTick). We only ever kill-session, never kill-server.
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, existsSync, readFileSync, readdirSync, writeFileSync, renameSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { createNode, getNode, subscribersOf, subscriptionsOf, } from '../../canvas/canvas.js';
+import { closeDb } from '../../canvas/db.js';
+import { isNodePaneAlive } from '../../runtime/placement.js';
+import { superviseTick } from '../../../daemon/crtrd.js';
+import { readInboxSince } from '../../feed/inbox.js';
+// --- locations --------------------------------------------------------------
+const HERE = dirname(fileURLToPath(import.meta.url)); // src/core/__tests__/helpers
+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');
+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.
+const FAKE_PI_BINARY = `${process.execPath} --import ${TSX_ESM} ${FAKE_PI_HOST}`;
+/** True when a usable tmux is on PATH — tests gate on this and SKIP otherwise. */
+export function hasTmux() {
+    return spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0;
+}
+function tmuxSessionExists(session) {
+    return spawnSync('tmux', ['has-session', '-t', session], { stdio: 'ignore' }).status === 0;
+}
+// Every canvas/tmux var the harness itself runs under — scrubbed from each child
+// env so a spawned CLI cannot leak the REAL canvas into the isolated test.
+const CANVAS_ENV_KEYS = [
+    'CRTR_NODE_ID',
+    'CRTR_HOME',
+    'CRTR_ROOT_SESSION',
+    'CRTR_NODE_SESSION',
+    'CRTR_PARENT_NODE_ID',
+    'CRTR_FRONT_DOOR',
+    'CRTR_KIND',
+    'CRTR_MODE',
+    'CRTR_LIFECYCLE',
+    'CRTR_NODE_CWD',
+    'CRTR_PI_BINARY',
+    'TMUX',
+    'TMUX_PANE',
+];
+function cleanBaseEnv() {
+    const e = {};
+    for (const [k, v] of Object.entries(process.env))
+        if (v !== undefined)
+            e[k] = v;
+    for (const k of CANVAS_ENV_KEYS)
+        delete e[k];
+    // Contain per-invocation bootstrap + auto-update side effects (they write to
+    // ~/.crouter / ~/.claude / ~/.pi, NOT under CRTR_HOME — HOME is contained too).
+    e['CRTR_NO_BOOTSTRAP'] = '1';
+    e['CRTR_NO_AUTO_UPDATE'] = '1';
+    e['CRTR_NO_BOOT_SKILL'] = '1';
+    e['CRTR_NO_MODE_CMDS'] = '1';
+    e['CRTR_NO_AUTO_INIT'] = '1';
+    return e;
+}
+async function waitFor(probe, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 20_000;
+    const intervalMs = opts.intervalMs ?? 100;
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const v = probe();
+        if (v)
+            return v;
+        if (Date.now() > deadline)
+            throw new Error(`waitFor timed out: ${opts.label ?? 'condition'}`);
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+}
+export async function createHarness(opts = {}) {
+    if (!hasTmux())
+        throw new Error('createHarness: tmux not available');
+    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 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
+    // OUR env makes in-process revives (superviseTick → reviveNode → openNodeWindow)
+    // bake the fake-pi into the command string.
+    process.env['CRTR_HOME'] = home;
+    process.env['CRTR_PI_BINARY'] = FAKE_PI_BINARY;
+    delete process.env['CRTR_NODE_SESSION'];
+    closeDb();
+    // 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
+    // the DEFAULT tmux server only. The runtime CLI shells `tmux` with no `-L`, so
+    // 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' });
+    const pidsToKill = new Set();
+    let nextRootSeq = 0;
+    // -- env for a subprocess CLI invocation -----------------------------------
+    function childEnv(nodeId) {
+        const e = cleanBaseEnv();
+        e['CRTR_HOME'] = home;
+        e['HOME'] = tmpHome;
+        e['CRTR_NODE_SESSION'] = session;
+        e['CRTR_PI_BINARY'] = FAKE_PI_BINARY;
+        if (nodeId !== null)
+            e['CRTR_NODE_ID'] = nodeId;
+        return e;
+    }
+    function nodeDir(id) {
+        return join(home, 'nodes', id);
+    }
+    function nodeDirs() {
+        try {
+            return readdirSync(join(home, 'nodes'));
+        }
+        catch {
+            return [];
+        }
+    }
+    function readLines(path) {
+        try {
+            return readFileSync(path, 'utf8')
+                .split('\n')
+                .filter((l) => l.trim() !== '');
+        }
+        catch {
+            return [];
+        }
+    }
+    function cli(nodeId, args) {
+        const res = spawnSync(process.execPath, ['--import', TSX_ESM, CLI_SRC, ...args], {
+            cwd: CROUTER,
+            env: childEnv(nodeId),
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: 60_000,
+        });
+        closeDb();
+        let json;
+        try {
+            json = JSON.parse(res.stdout ?? '');
+        }
+        catch {
+            /* not json */
+        }
+        return { code: res.status ?? -1, stdout: res.stdout ?? '', stderr: res.stderr ?? '', json };
+    }
+    // -- control channel -------------------------------------------------------
+    function sendCmd(nodeId, cmd) {
+        const dir = nodeDir(nodeId);
+        const tmp = join(dir, 'fake-pi.cmd.tmp');
+        writeFileSync(tmp, JSON.stringify(cmd));
+        renameSync(tmp, join(dir, 'fake-pi.cmd')); // atomic: host never reads a partial
+    }
+    function eventCount(nodeId, event) {
+        return readLines(join(nodeDir(nodeId), 'fake-pi.events.jsonl')).filter((l) => {
+            try {
+                return JSON.parse(l).event === event;
+            }
+            catch {
+                return false;
+            }
+        }).length;
+    }
+    function bootCount(nodeId) {
+        return readLines(join(nodeDir(nodeId), 'fake-pi.boots.jsonl')).length;
+    }
+    function injected(nodeId) {
+        return readLines(join(nodeDir(nodeId), 'fake-pi.injected.jsonl'))
+            .map((l) => {
+            try {
+                return JSON.parse(l);
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((x) => x !== null);
+    }
+    // Wait for the host to have BEGUN dispatching agent_end (recorded before its
+    // handlers run, so it survives a handler that tears the process down).
+    async function awaitAgentEnd(nodeId, base, label) {
+        await waitFor(() => eventCount(nodeId, 'agent_end') > base, {
+            timeoutMs: 20_000,
+            label,
+        });
+    }
+    const harness = {
+        home,
+        session,
+        spawnRoot(task, o = {}) {
+            const id = o.id ?? `root-${process.pid}-${nextRootSeq++}`;
+            const meta = {
+                node_id: id,
+                name: o.id ?? (task.slice(0, 24) || id),
+                created: new Date().toISOString(),
+                cwd: CROUTER,
+                kind: o.kind ?? 'general',
+                mode: o.mode ?? 'base',
+                lifecycle: o.lifecycle ?? 'resident',
+                status: 'active',
+                parent: 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];
+            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(`spawnChild(${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(`spawnChild: expected exactly 1 new node dir, got [${added.join(', ')}]`);
+            }
+            const childId = added[0];
+            await harness.awaitBoot(childId);
+            return childId;
+        },
+        cli,
+        async turn(nodeId, text = '') {
+            const base = eventCount(nodeId, 'agent_end');
+            sendCmd(nodeId, { cmd: 'turn', id: `turn-${Date.now()}`, text });
+            await awaitAgentEnd(nodeId, base, `turn agent_end for ${nodeId}`);
+        },
+        async stop(nodeId, reason = 'stop') {
+            const base = eventCount(nodeId, 'agent_end');
+            sendCmd(nodeId, { cmd: 'stop', id: `stop-${Date.now()}`, reason });
+            await awaitAgentEnd(nodeId, base, `stop agent_end for ${nodeId}`);
+        },
+        async finish(nodeId, finalText) {
+            const res = cli(nodeId, ['push', 'final', finalText]);
+            if (res.code !== 0) {
+                throw new Error(`finish(${nodeId}): push final failed (code ${res.code})\n${res.stderr}`);
+            }
+            // Fire agent_end so the now-done node runs the real (b) done branch
+            // (null presence + ctx.shutdown → window closes), exactly as real pi would.
+            const base = eventCount(nodeId, 'agent_end');
+            sendCmd(nodeId, { cmd: 'stop', id: `finish-${Date.now()}` });
+            await awaitAgentEnd(nodeId, base, `finish agent_end for ${nodeId}`);
+            await harness.waitForPaneGone(nodeId);
+        },
+        async yieldNode(nodeId, note) {
+            const res = cli(nodeId, ['node', 'yield', note]);
+            if (res.code !== 0) {
+                throw new Error(`yieldNode(${nodeId}): node yield failed (code ${res.code})\n${res.stderr}`);
+            }
+            // node yield set intent=refresh (active, kept). Fire agent_end so the real
+            // (b') branch runs reviveInPlace (respawn-pane -k) IN the fake-pi's pane —
+            // a FRESH fake-pi boots (resume); its session_start clears intent=refresh.
+            const baseBoots = bootCount(nodeId);
+            sendCmd(nodeId, { cmd: 'stop', id: `yield-${Date.now()}` });
+            await waitFor(() => bootCount(nodeId) > baseBoots, {
+                timeoutMs: 30_000,
+                label: `fresh boot after yield for ${nodeId}`,
+            });
+            await waitFor(() => {
+                closeDb();
+                const n = getNode(nodeId);
+                return n?.intent == null && n?.status === 'active';
+            }, { timeoutMs: 20_000, label: `intent=refresh cleared after yield for ${nodeId}` });
+            await harness.awaitBoot(nodeId, { minCount: baseBoots + 1 });
+        },
+        async tick(now) {
+            closeDb();
+            await superviseTick(now);
+            closeDb();
+        },
+        async awaitBoot(nodeId, o = {}) {
+            const minCount = o.minCount ?? 1;
+            const bootsPath = join(nodeDir(nodeId), 'fake-pi.boots.jsonl');
+            const errPath = join(nodeDir(nodeId), 'fake-pi.error');
+            const lines = await waitFor(() => {
+                const ls = readLines(bootsPath);
+                return ls.length >= minCount ? ls : null;
+            }, {
+                timeoutMs: o.timeoutMs ?? 30_000,
+                label: `fake-pi boot >= ${minCount} for ${nodeId}` +
+                    (existsSync(errPath) ? ` (error file: ${readFileSync(errPath, 'utf8')})` : ''),
+            });
+            const boot = JSON.parse(lines[lines.length - 1]);
+            if (typeof boot.pid === 'number')
+                pidsToKill.add(boot.pid);
+            return boot;
+        },
+        async awaitWake(nodeId, o = {}) {
+            const sinceCount = o.sinceCount ?? 0;
+            const match = o.match;
+            const fresh = await waitFor(() => {
+                const all = injected(nodeId).slice(sinceCount);
+                if (all.length === 0)
+                    return null;
+                if (match && !all.some((e) => match.test(e.content)))
+                    return null;
+                return all;
+            }, { timeoutMs: o.timeoutMs ?? 15_000, label: `wake delivery for ${nodeId}` });
+            return fresh.map((e) => e.content);
+        },
+        async waitForStatus(nodeId, status, timeoutMs = 20_000) {
+            await waitFor(() => {
+                closeDb();
+                return getNode(nodeId)?.status === status;
+            }, { timeoutMs, label: `status=${status} for ${nodeId}` });
+        },
+        async waitForPaneGone(nodeId, timeoutMs = 20_000) {
+            await waitFor(() => {
+                closeDb();
+                return !isNodePaneAlive(nodeId);
+            }, { timeoutMs, label: `pane gone for ${nodeId}` });
+        },
+        waitFor,
+        node(nodeId) {
+            closeDb();
+            return getNode(nodeId);
+        },
+        status(nodeId) {
+            closeDb();
+            return getNode(nodeId)?.status ?? null;
+        },
+        paneAlive(nodeId) {
+            closeDb();
+            return isNodePaneAlive(nodeId);
+        },
+        inbox(nodeId) {
+            closeDb();
+            return readInboxSince(nodeId);
+        },
+        injected,
+        subscribers(nodeId) {
+            closeDb();
+            return subscribersOf(nodeId).map((s) => ({ node_id: s.node_id, active: s.active }));
+        },
+        subscriptions(nodeId) {
+            closeDb();
+            return subscriptionsOf(nodeId).map((s) => ({ node_id: s.node_id, active: s.active }));
+        },
+        async dispose() {
+            spawnSync('tmux', ['kill-session', '-t', session], { stdio: 'ignore' });
+            for (const p of pidsToKill) {
+                try {
+                    process.kill(p, 'SIGKILL');
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+            closeDb();
+            rmSync(home, { recursive: true, force: true });
+            rmSync(tmpHome, { recursive: true, force: true });
+            if (origHome === undefined)
+                delete process.env['CRTR_HOME'];
+            else
+                process.env['CRTR_HOME'] = origHome;
+            if (origPiBinary === undefined)
+                delete process.env['CRTR_PI_BINARY'];
+            else
+                process.env['CRTR_PI_BINARY'] = origPiBinary;
+            if (origNodeSession === undefined)
+                delete process.env['CRTR_NODE_SESSION'];
+            else
+                process.env['CRTR_NODE_SESSION'] = origNodeSession;
+        },
+    };
+    return harness;
+}

package/dist/core/__tests__/human-surface-target.test.d.ts

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