@crouton-kit/crouter 0.3.15 → 0.3.17

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__/home-session.test.js

@@ -18,7 +18,7 @@ import { createNode, getNode, updateNode } from '../canvas/canvas.js';
 import { nodeMetaPath } from '../canvas/paths.js';
 import { closeDb } from '../canvas/db.js';
 import { resolveBirthSession, homeSessionOf } from '../runtime/nodes.js';
-import { nodeSession } from '../runtime/tmux.js';
+import { nodeSession } from '../runtime/nodes.js';
 import { relaunchRoot } from '../runtime/reset.js';
 import { demoteNode } from '../runtime/demote.js';
 let home;

package/dist/core/__tests__/lifecycle.test.js

@@ -67,18 +67,11 @@ test('finalize: illegal from done|dead|canceled → throws, status untouched', (
     }
 });
 // ---------------------------------------------------------------------------
-// reap → done + intent cleared, legal from ANY status (forced teardown)
-// ---------------------------------------------------------------------------
-test('reap: any status → done + intent cleared', () => {
-    for (const from of ALL) {
-        mk(`n_${from}`, from, 'refresh');
-        const m = transition(`n_${from}`, 'reap');
-        assert.equal(m.status, 'done', `reap from ${from}`);
-        assert.equal(m.intent, null, `reap from ${from} clears intent`);
-    }
-});
-// ---------------------------------------------------------------------------
-// cancel → canceled + intent cleared, legal from ANY status
+// cancel → canceled + intent cleared, legal from ANY status (forced teardown).
+// A5 (human-confirmed 2026-06-06): the `reap` event was COLLAPSED into `cancel`
+// — they were identical (status differed only; both intent=null, from=ANY, no
+// side effects in transition()). Every external reap (close cascade AND
+// reset/relaunch) now routes through `cancel`; `done` is reserved for finalize.
 // ---------------------------------------------------------------------------
 test('cancel: any status → canceled + intent cleared', () => {
     for (const from of ALL) {
@@ -172,7 +165,7 @@ test('boot: illegal from done|dead|canceled → throws', () => {
 // unknown node → throws for every event
 // ---------------------------------------------------------------------------
 test('transition on an unknown node throws', () => {
-    for (const ev of ['finalize', 'reap', 'cancel', 'crash', 'yield', 'release', 'revive', 'boot']) {
+    for (const ev of ['finalize', 'cancel', 'crash', 'yield', 'release', 'revive', 'boot']) {
         assert.throws(() => transition('ghost', ev), /unknown node/);
     }
 });

package/dist/core/__tests__/live-mutation.test.d.ts

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