@crouton-kit/crouter 0.3.16 → 0.3.18

package/dist/core/__tests__/placement-focus.test.js

@@ -22,6 +22,7 @@ import { createNode, getNode, setPresence } from '../canvas/canvas.js';
 import { openFocusRow, getFocusByNode, getFocusById, listFocuses, } from '../canvas/focuses.js';
 import { closeDb } from '../canvas/db.js';
 import { outgoingDisposition, retargetFocus, openFocus, focus as placementFocus, registerRootFocus, focusByPane, detachToBackground, } from '../runtime/placement.js';
+import { markBusy, isBusy } from '../runtime/busy.js';
 let home;
 let savedTmux;
 function node(id, over = {}) {
@@ -58,18 +59,27 @@ after(() => {
         process.env['TMUX'] = savedTmux;
 });
 // ---------------------------------------------------------------------------
-// 1a. PURE: outgoingDisposition — backstage (still generating) vs kill.
+// 1a. PURE: outgoingDisposition — the 4-field truth table (kill / backstage /
+// release). Each branch is provably non-vacuous (a wrong impl fails).
 // ---------------------------------------------------------------------------
-test('outgoingDisposition: a still-generating node → BACKSTAGE (F2: keeps running off-screen)', () => {
-    assert.deepEqual(outgoingDisposition({ exists: true, generating: true }), { kind: 'backstage' });
-});
-test('outgoingDisposition: a dormant/done node → KILL (Invariant P: not-focused + not-generating ⇒ no pane)', () => {
-    assert.deepEqual(outgoingDisposition({ exists: true, generating: false }), { kind: 'kill' });
-});
 test('outgoingDisposition: a HOLDER / vanished node (no row) → KILL (never backstaged)', () => {
     // A wrong impl that backstaged a holder would leak a sleep pane into crtr.
-    assert.deepEqual(outgoingDisposition({ exists: false, generating: true }), { kind: 'kill' });
-    assert.deepEqual(outgoingDisposition({ exists: false, generating: false }), { kind: 'kill' });
+    assert.deepEqual(outgoingDisposition({ exists: false, live: false, resident: false, generating: false }), { kind: 'kill' });
+    assert.deepEqual(outgoingDisposition({ exists: false, live: true, resident: true, generating: true }), { kind: 'kill' });
+});
+test('outgoingDisposition: a done/dead node (not live) → KILL (Invariant P: not-focused + not-live ⇒ no pane)', () => {
+    assert.deepEqual(outgoingDisposition({ exists: true, live: false, resident: false, generating: false }), { kind: 'kill' });
+});
+test('outgoingDisposition: a RESIDENT node (editor/root) → BACKSTAGE (human-driven, NEVER despawned on focus-away)', () => {
+    // Resident wins even when NOT mid-turn — a wrong impl here KILLS the user\'s editor.
+    assert.deepEqual(outgoingDisposition({ exists: true, live: true, resident: true, generating: false }), { kind: 'backstage' });
+    assert.deepEqual(outgoingDisposition({ exists: true, live: true, resident: true, generating: true }), { kind: 'backstage' });
+});
+test('outgoingDisposition: a still-generating terminal worker → BACKSTAGE (F2: keeps running off-screen)', () => {
+    assert.deepEqual(outgoingDisposition({ exists: true, live: true, resident: false, generating: true }), { kind: 'backstage' });
+});
+test('outgoingDisposition: a PARKED terminal viewer (live, not mid-turn) → RELEASE (despawn to dormant — the stuck-green fix)', () => {
+    assert.deepEqual(outgoingDisposition({ exists: true, live: true, resident: false, generating: false }), { kind: 'release' });
 });
 // ---------------------------------------------------------------------------
 // 2. Gated real-tmux: the hot-swap. Two isolated sessions: `user` (the user's
@@ -121,9 +131,11 @@ test('retargetFocus: outgoing GENERATING → backstaged; the viewport stays put
     await withSessions('gen', async ({ user, back, userWindow, backWindow }) => {
         const focusPane = livePane(user, userWindow); // R's focus pane (the viewport)
         const backPane = livePane(back, backWindow); // A's live backstage pane
-        // R is the outgoing occupant, generating (a live pi_pid). A is incoming.
-        createNode(node('R', { pane: focusPane, tmux_session: user, window: userWindow, status: 'active', pi_pid: process.pid, home_session: back }));
+        // R is the outgoing occupant, generating: a terminal worker MID-TURN (live
+        // pi_pid AND the busy marker set). A is incoming.
+        createNode(node('R', { pane: focusPane, tmux_session: user, window: userWindow, status: 'active', lifecycle: 'terminal', pi_pid: process.pid, home_session: back }));
         createNode(node('A', { pane: backPane, tmux_session: back, window: backWindow, status: 'active', pi_pid: process.pid, home_session: back }));
+        markBusy('R'); // R is genuinely mid-turn (isGenerating = busy && pidAlive)
         openFocusRow('f1', focusPane, user, 'R');
         const userBefore = windowIds(user).length;
         const res = retargetFocus('f1', 'A', NOREVIVE);
@@ -145,18 +157,44 @@ test('retargetFocus: outgoing GENERATING → backstaged; the viewport stays put
         assert.equal(focusByPane(backPane)?.node_id, 'A', 'the focus row tracks A after the retarget');
     });
 });
-test('retargetFocus: outgoing DORMANT (no live pi) → its now-backstage pane is REAPED (Invariant P)', { skip: !hasTmux() }, async () => {
+test('retargetFocus: outgoing DONE/dead (not live) → its now-backstage pane is REAPED (Invariant P)', { skip: !hasTmux() }, async () => {
     await withSessions('kill', async ({ user, back, userWindow, backWindow }) => {
         const focusPane = livePane(user, userWindow);
         const backPane = livePane(back, backWindow);
-        // R is NOT generating (pi_pid null) → its pane must be reaped after the swap.
-        createNode(node('R', { pane: focusPane, tmux_session: user, window: userWindow, status: 'active', pi_pid: null, home_session: back }));
+        // R is NOT live (status done) → the KILL path: its pane must be reaped after
+        // the swap, with NO lifecycle transition.
+        createNode(node('R', { pane: focusPane, tmux_session: user, window: userWindow, status: 'done', pi_pid: null, home_session: back }));
+        createNode(node('A', { pane: backPane, tmux_session: back, window: backWindow, status: 'active', pi_pid: process.pid, home_session: back }));
+        openFocusRow('f1', focusPane, user, 'R');
+        retargetFocus('f1', 'A', NOREVIVE);
+        assert.equal(getFocusByNode('A')?.focus_id, 'f1', 'A took the viewport');
+        assert.equal(paneSession(backPane), user, 'A\'s pane is in the viewport');
+        assert.equal(paneExistsReal(focusPane), false, 'R\'s now-backstage pane was KILLED (not live ⇒ no pane)');
+        assert.equal(getNode('R').status, 'done', 'R stays done (KILL does not transition status)');
+        assert.equal(getNode('R').pane, null, 'R\'s LOCATION was nulled (Invariant P)');
+        assert.equal(getNode('R').tmux_session, null);
+    });
+});
+test('retargetFocus: outgoing PARKED terminal viewer (live pi, NOT mid-turn) → RELEASED to dormant (status idle, pane reaped) — the stuck-green fix', { skip: !hasTmux() }, async () => {
+    await withSessions('park', async ({ user, back, userWindow, backWindow }) => {
+        const focusPane = livePane(user, userWindow);
+        const backPane = livePane(back, backWindow);
+        // R is a terminal node revived only for VIEWING: live pi (pidAlive) but NOT
+        // mid-turn (no busy marker). It was the stuck-green bug: misread as
+        // generating, backstaged, and left status='active' forever. It must instead
+        // be RELEASED to dormant.
+        createNode(node('R', { pane: focusPane, tmux_session: user, window: userWindow, status: 'active', lifecycle: 'terminal', pi_pid: process.pid, home_session: back }));
         createNode(node('A', { pane: backPane, tmux_session: back, window: backWindow, status: 'active', pi_pid: process.pid, home_session: back }));
+        assert.equal(isBusy('R'), false, 'precondition: R is parked between turns (not mid-turn)');
         openFocusRow('f1', focusPane, user, 'R');
         retargetFocus('f1', 'A', NOREVIVE);
         assert.equal(getFocusByNode('A')?.focus_id, 'f1', 'A took the viewport');
         assert.equal(paneSession(backPane), user, 'A\'s pane is in the viewport');
-        assert.equal(paneExistsReal(focusPane), false, 'R\'s now-backstage pane was KILLED (dormant ⇒ no pane)');
+        // The fix: focus-away flips R back to dormant (idle + idle-release) and reaps
+        // its pane — so the editor stops drawing it green/active.
+        assert.equal(getNode('R').status, 'idle', 'R was RELEASED back to dormant (no longer stuck active/green)');
+        assert.equal(getNode('R').intent, 'idle-release', 'R carries idle-release so the daemon revives it on its inbox');
+        assert.equal(paneExistsReal(focusPane), false, 'R\'s now-backstage pane was REAPED (parked viewer ⇒ no pane)');
         assert.equal(getNode('R').pane, null, 'R\'s LOCATION was nulled (Invariant P)');
         assert.equal(getNode('R').tmux_session, null);
     });

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

@@ -65,7 +65,7 @@ after(() => {
 // ---------------------------------------------------------------------------
 // #1 — relaunchRoot parks the old root, keeps edges, creates a fresh root
 // ---------------------------------------------------------------------------
-test('relaunchRoot parks the old root (done, edges intact, no wipe) and mints a fresh root', () => {
+test('relaunchRoot parks the old root (canceled, edges intact, no wipe) and mints a fresh root', () => {
     createNode(node('root', {
         parent: null,
         lifecycle: 'resident',
@@ -91,18 +91,18 @@ test('relaunchRoot parks the old root (done, edges intact, no wipe) and mints a
     assert.notEqual(newId, 'root', 'a FRESH id, not the old one');
     // Respawn was dispatched against the NEW node in the given pane.
     assert.deepEqual(respawn.calls, [{ nodeId: newId, pane: 'test-pane' }]);
-    // Old root: parked done, window detached, pi_session_id UNCHANGED (resumable).
+    // Old root: parked canceled, window detached, pi_session_id UNCHANGED (resumable).
     const old = getNode('root');
-    assert.equal(old?.status, 'done', 'old root parked done');
+    assert.equal(old?.status, 'canceled', 'old root parked canceled');
     assert.equal(old?.window, null, 'old root window detached');
     assert.equal(old?.tmux_session, null, 'old root tmux_session detached');
     assert.equal(old?.intent, null, 'old root intent cleared');
     assert.equal(old?.pi_session_id, 'root-sess', 'pi_session_id preserved (resumable)');
     assert.equal(old?.pi_session_file, '/abs/root-sess.jsonl', 'pi_session_file preserved (resumable by path)');
     assert.equal(old?.parent, null, 'old root stays a root');
-    // Descendants: DONE (not dead), but edges intact.
-    assert.equal(getNode('child')?.status, 'done', 'child marked done (not a fault)');
-    assert.equal(getNode('grand')?.status, 'done', 'grand marked done (not a fault)');
+    // Descendants: CANCELED (not dead), but edges intact.
+    assert.equal(getNode('child')?.status, 'canceled', 'child marked canceled (not a fault)');
+    assert.equal(getNode('grand')?.status, 'canceled', 'grand marked canceled (not a fault)');
     assert.deepEqual(subscriptionsOf('root').map((s) => s.node_id), ['child'], 'root→child edge intact');
     assert.deepEqual(subscriptionsOf('child').map((s) => s.node_id), ['grand'], 'child→grand edge intact');
     // Old root working state PRESERVED (history, no wipe).
@@ -152,10 +152,10 @@ test('handleNewSession on a root with a pane returns path:relaunch + parks old,
     assert.deepEqual(respawn.calls, [{ nodeId: res.newNodeId, pane: 'test-pane' }]);
     // Parked-old + fresh-new end state.
     const old = getNode('root');
-    assert.equal(old?.status, 'done', 'old root parked done');
+    assert.equal(old?.status, 'canceled', 'old root parked canceled');
     assert.equal(old?.window, null, 'old root window detached');
     assert.equal(old?.pi_session_id, 'root-sess', 'pi_session_id preserved (resumable)');
-    assert.equal(getNode('child')?.status, 'done', 'descendant reaped done');
+    assert.equal(getNode('child')?.status, 'canceled', 'descendant reaped canceled');
     const fresh = getNode(res.newNodeId);
     assert.equal(fresh?.parent, null, 'new node is a root');
     assert.equal(fresh?.status, 'active', 'fresh root active');
@@ -198,7 +198,7 @@ test('handleNewSession on a root with no pane falls back to in-place resetRoot',
     assert.equal(root?.lifecycle, 'resident');
     assert.equal(root?.pi_session_id, 'newsess');
     assert.equal(view('root').length, 0, 'root view emptied');
-    assert.equal(getNode('child')?.status, 'done', 'descendant marked done');
+    assert.equal(getNode('child')?.status, 'canceled', 'descendant marked canceled');
     assert.equal(existsSync(roadmapPath('root')), false, 'working state wiped');
 });
 // ---------------------------------------------------------------------------
@@ -210,13 +210,13 @@ test('a second relaunchRoot on an already-parked root is a no-op', () => {
     const first = relaunchRoot('root', 'test-pane', { relaunchRootInPane: respawn.fn });
     assert.ok(first !== null, 'first /new parks + relaunches');
     const afterFirst = listNodes().length;
-    // Old root is now `done`; a second session_start in the dying old pi must
+    // Old root is now `canceled`; a second session_start in the dying old pi must
     // no-op (no second parked node, no zombie new node).
     const second = relaunchRoot('root', 'test-pane', { relaunchRootInPane: respawn.fn });
     assert.equal(second, null, 'second relaunch is a no-op');
     assert.equal(listNodes().length, afterFirst, 'no second new node minted');
     assert.equal(respawn.calls.length, 1, 'respawn dispatched only once');
-    assert.equal(getNode('root')?.status, 'done', 'old root unchanged (still parked)');
+    assert.equal(getNode('root')?.status, 'canceled', 'old root unchanged (still parked)');
 });
 // ---------------------------------------------------------------------------
 // #5 — /new before the root ever spawned children
@@ -227,7 +227,7 @@ test('relaunchRoot on a childless root: reap is a no-op, new node minted', () =>
     const respawn = okRespawn();
     const res = relaunchRoot('root', 'test-pane', { relaunchRootInPane: respawn.fn });
     assert.ok(res !== null, 'new node minted without throwing');
-    assert.equal(getNode('root')?.status, 'done', 'old root parked');
+    assert.equal(getNode('root')?.status, 'canceled', 'old root parked');
     assert.equal(getNode(res.newNodeId)?.status, 'active', 'fresh root active');
 });
 // ---------------------------------------------------------------------------

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

@@ -56,9 +56,14 @@ test('resetRoot empties the root view, reaps descendants, and wipes working stat
     // Graph is empty from the root's view.
     assert.equal(view('root').length, 0, 'root view is empty after reset');
     assert.equal(subscriptionsOf('root').length, 0, 'no outgoing edges remain');
-    // Descendants are done (clean teardown, not a fault; daemon skips them).
-    assert.equal(getNode('child')?.status, 'done');
-    assert.equal(getNode('grand')?.status, 'done');
+    // Descendants are CANCELED (A5, human-confirmed 2026-06-06): an externally-
+    // reaped node — via reset/relaunch OR close — did not finish its OWN work, so
+    // it unifies on `canceled`; `done` is reserved for finalize. Daemon skips them.
+    assert.equal(getNode('child')?.status, 'canceled');
+    assert.equal(getNode('grand')?.status, 'canceled');
+    // Regression: a reset-reaped descendant ends EXACTLY {canceled, null} — byte-
+    // for-byte identical to the close path (mirrors cascade-close.test.ts's tuple).
+    assert.deepEqual({ status: getNode('grand')?.status, intent: getNode('grand')?.intent ?? null }, { status: 'canceled', intent: null }, 'reset-reaped descendant: (status,intent) === (canceled, null), same as close');
     // Working state wiped.
     assert.equal(existsSync(roadmapPath('root')), false, 'roadmap wiped');
     assert.equal(existsSync(inboxPath('root')), false, 'inbox wiped');
@@ -99,7 +104,7 @@ test('Step 7: resetRoot reaps a FOCUSED descendant through tearDownNode (closes
     // getFocusByNode('desc') would still return fD.
     assert.equal(getFocusByNode('desc'), null, 'descendant focus row closed by tearDownNode');
     const d = getNode('desc');
-    assert.equal(d.status, 'done', 'descendant reaped (done)');
+    assert.equal(d.status, 'canceled', 'descendant reaped (canceled — A5 unified)');
     assert.equal(d.pane ?? null, null, 'descendant pane nulled');
     assert.equal(d.tmux_session ?? null, null, 'descendant session nulled');
 });
@@ -115,10 +120,10 @@ test('reaped descendants keep their meta on disk (orphaned, not deleted)', () =>
     subscribe('root', 'child', true);
     setStatus('child', 'idle');
     resetRoot('root', 'new');
-    // The node record persists (we detach + mark done, we don't delete the node).
+    // The node record persists (we detach + mark canceled, we don't delete the node).
     const child = getNode('child');
     assert.ok(child, 'child meta still on disk');
-    assert.equal(child?.status, 'done');
+    assert.equal(child?.status, 'canceled');
     // It is just unreachable from the root.
     assert.equal(view('root').length, 0);
 });

package/dist/core/__tests__/spike-harness.test.d.ts

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

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

@@ -0,0 +1,241 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/spike-harness.test.ts
+//
+// SPIKE — a throwaway-grade proof that a faithful integration harness for the
+// node/canvas runtime is feasible. It drives the REAL `crtr` CLI into an
+// isolated REAL tmux session, substitutes a FAKE-PI vehicle (the fake-pi-host
+// fixture) via the CRTR_PI_BINARY seam, and proves the spawned window actually
+// exec's the fake pi with the right argv+env, that the fake loads the REAL
+// extensions, and that one real lifecycle hook drives a real canvas transition.
+//
+// Milestones (de-risk order):
+//   1. SEAM      — piCommand substitutes CRTR_PI_BINARY only when set (unit).
+//   2. ROUND-TRIP— real `node new` → isolated tmux window → fake pi boots with
+//                  CRTR_NODE_ID + the -e env intact (GO/NO-GO).
+//   3. REAL HOOKS— the fake pi loads the real stophook and a clean /quit drives
+//                  status=done via the real session_shutdown handler.
+//   4. TEARDOWN  — the isolated session + fake-pi procs are killed; no strays.
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, existsSync, readFileSync, readdirSync, writeFileSync, } 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 } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { piCommand } from '../runtime/placement.js';
+import { CANVAS_EXTENSIONS } from '../runtime/launch.js';
+// --- locations --------------------------------------------------------------
+const HERE = dirname(fileURLToPath(import.meta.url)); // src/core/__tests__
+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.
+const FAKE_PI_BINARY = `${process.execPath} --import ${TSX_ESM} ${FAKE_PI_HOST}`;
+function hasTmux() {
+    return spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0;
+}
+function tmuxSessionExists(session) {
+    return spawnSync('tmux', ['has-session', '-t', session], { stdio: 'ignore' }).status === 0;
+}
+// --- env isolation: scrub every canvas var the harness itself runs under, so
+// the spawned CLI cannot leak into the real canvas. -------------------------
+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.
+    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;
+}
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: CROUTER,
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'resident',
+        status: 'active',
+        parent: null,
+        ...over,
+    };
+}
+async function waitFor(probe, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 20_000;
+    const intervalMs = opts.intervalMs ?? 150;
+    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));
+    }
+}
+// --- harness state ----------------------------------------------------------
+let home;
+let tmpHome;
+let origHome;
+const sessionsToKill = new Set();
+const pidsToKill = new Set();
+before(() => {
+    origHome = process.env['CRTR_HOME'];
+    home = mkdtempSync(join(tmpdir(), 'crtr-spike-home-'));
+    tmpHome = mkdtempSync(join(tmpdir(), 'crtr-spike-HOME-'));
+    // The harness reads/writes the isolated canvas in-process.
+    process.env['CRTR_HOME'] = home;
+    closeDb();
+});
+after(() => {
+    for (const s of sessionsToKill)
+        spawnSync('tmux', ['kill-session', '-t', s], { stdio: 'ignore' });
+    for (const p of pidsToKill) {
+        try {
+            process.kill(p, 'SIGKILL');
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    closeDb();
+    if (home)
+        rmSync(home, { recursive: true, force: true });
+    if (tmpHome)
+        rmSync(tmpHome, { recursive: true, force: true });
+    if (origHome === undefined)
+        delete process.env['CRTR_HOME'];
+    else
+        process.env['CRTR_HOME'] = origHome;
+});
+// ===========================================================================
+// MILESTONE 1 — the CRTR_PI_BINARY seam (always runs; no tmux needed).
+// ===========================================================================
+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 CLI → isolated tmux → fake pi → real hooks.
+// THE GO/NO-GO. Shares one spawned child across both milestones.
+// ===========================================================================
+test('M2+M3 round-trip: real `node new` reaches the fake pi via the seam, and a real hook drives status=done', { skip: !hasTmux() }, async () => {
+    const session = `crtr-spike-${process.pid}-rt`;
+    sessionsToKill.add(session);
+    // Pre-create the isolated session (default tmux server — the runtime shells
+    // `tmux` with no -L, so an -L server would be invisible to the real CLI).
+    spawnSync('tmux', ['new-session', '-d', '-s', session, '-c', CROUTER, 'sleep 600'], {
+        stdio: 'ignore',
+    });
+    assert.ok(tmuxSessionExists(session), 'isolated tmux session created');
+    // Bootstrap the acting node in the isolated canvas (the parent `node new`
+    // spawns under). createNode shares the harness CRTR_HOME.
+    createNode(node('A', { name: 'acting-root' }));
+    // Drive the REAL CLI: `crtr node new` AS node A, into the isolated session,
+    // with the fake-pi seam. Body passed as a positional (dodges the stdin hang).
+    const env = cleanBaseEnv();
+    env['CRTR_HOME'] = home;
+    env['HOME'] = tmpHome;
+    env['CRTR_NODE_ID'] = 'A';
+    env['CRTR_NODE_SESSION'] = session;
+    env['CRTR_PI_BINARY'] = FAKE_PI_BINARY;
+    const res = spawnSync(process.execPath, ['--import', TSX_ESM, CLI_SRC, 'node', 'new', 'spike task', '--parent', 'A', '--cwd', CROUTER], { cwd: CROUTER, env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60_000 });
+    assert.equal(res.status, 0, `node new should exit 0\n--- stdout ---\n${res.stdout}\n--- stderr ---\n${res.stderr}`);
+    // Find the spawned child: the only node dir that isn't the acting root.
+    closeDb();
+    const nodesDir = join(home, 'nodes');
+    const childId = readdirSync(nodesDir).find((d) => d !== 'A');
+    assert.ok(childId, 'a child node dir was created by node new');
+    // ---- MILESTONE 2 assertions: the round-trip reached the fake pi --------
+    const bootPath = join(nodesDir, childId, 'fake-pi.boot.json');
+    const errPath = join(nodesDir, childId, 'fake-pi.error');
+    await waitFor(() => existsSync(bootPath), {
+        timeoutMs: 30_000,
+        label: `fake-pi boot proof at ${bootPath}${existsSync(errPath) ? ` (error file: ${readFileSync(errPath, 'utf8')})` : ''}`,
+    });
+    const boot = JSON.parse(readFileSync(bootPath, 'utf8'));
+    if (typeof boot.pid === 'number')
+        pidsToKill.add(boot.pid);
+    // env delivered via tmux -e arrived in the fake pi's process.env.
+    assert.equal(boot.env.CRTR_NODE_ID, childId, 'CRTR_NODE_ID is the CHILD id, intact');
+    assert.equal(boot.env.CRTR_HOME, home, 'CRTR_HOME isolated value intact');
+    assert.ok(boot.env.CRTR_KIND, 'CRTR_KIND present');
+    assert.ok(boot.env.CRTR_MODE, 'CRTR_MODE present');
+    assert.ok(boot.env.CRTR_LIFECYCLE, 'CRTR_LIFECYCLE present');
+    assert.equal(boot.env.CRTR_FRONT_DOOR, '1', 'CRTR_FRONT_DOOR overlay present');
+    // argv from buildPiArgv arrived: every canvas -e extension + the kickoff.
+    // Assert against the live CANVAS_EXTENSIONS count (8 at current HEAD — the
+    // placement-v3 refactor added canvas-resume) 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 fake pi');
+    assert.ok(boot.loaded.some((p) => p.includes('canvas-inbox-watcher')), 'real inbox-watcher module loaded by the fake pi');
+    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 fake pi and wrote
+    // shared canvas state (proves the hook chain, not just the boot).
+    closeDb();
+    const afterBoot = getNode(childId);
+    assert.ok(afterBoot, 'child node readable from the shared canvas');
+    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 /quit drives a real transition to done -------
+    writeFileSync(join(nodesDir, childId, 'fake-pi.cmd'), JSON.stringify({ cmd: 'shutdown' }));
+    const done = await waitFor(() => {
+        closeDb();
+        return getNode(childId)?.status === 'done' ? true : false;
+    }, { timeoutMs: 20_000, label: 'child status=done after clean /quit' });
+    assert.ok(done, 'real session_shutdown hook resolved the node to done');
+    assert.equal(getNode(childId)?.status, 'done', 'status=done via the real stophook');
+    // ---- MILESTONE 4: teardown leaves no stray session ---------------------
+    spawnSync('tmux', ['kill-session', '-t', session], { stdio: 'ignore' });
+    sessionsToKill.delete(session);
+    assert.ok(!tmuxSessionExists(session), 'isolated session killed, no stray left');
+});

package/dist/core/__tests__/subscription-delivery.test.d.ts

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