@crouton-kit/crouter 0.3.13 → 0.3.15

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

@@ -0,0 +1,328 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/relaunch.test.ts
+//
+// Covers the `/new`-in-a-root relaunch (option C) + clean-exit termination
+// semantics. tmux/respawn is unavailable in CI, so the respawn is an INJECTED
+// test double (RelaunchDeps.relaunchRootInPane) and every assertion is on the
+// DB / edge / disk effects.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, existsSync, writeFileSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, getNode, subscribe, subscriptionsOf, view, listNodes, } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { reportsDir, inboxPath, contextDir } from '../canvas/paths.js';
+import { roadmapPath } from '../runtime/roadmap.js';
+import { relaunchRoot, handleNewSession, markCleanExitDone, reapDescendants, } from '../runtime/reset.js';
+import { getFocus } from '../runtime/presence.js';
+import { renderForest } from '../canvas/render.js';
+let home;
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+/** A respawn double that records its calls and never throws (dispatch ok). */
+function okRespawn() {
+    const calls = [];
+    return {
+        calls,
+        fn: (nodeId, pane) => { calls.push({ nodeId, pane }); },
+    };
+}
+/** A respawn double that simulates a dispatch failure (throws). */
+function throwingRespawn() {
+    const calls = [];
+    return {
+        calls,
+        fn: (nodeId, pane) => {
+            calls.push({ nodeId, pane });
+            throw new Error('respawn-pane dispatch failed');
+        },
+    };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-relaunch-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+// ---------------------------------------------------------------------------
+// #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', () => {
+    createNode(node('root', {
+        parent: null,
+        lifecycle: 'resident',
+        mode: 'orchestrator',
+        pi_session_id: 'root-sess',
+        pi_session_file: '/abs/root-sess.jsonl',
+        tmux_session: 'crtr',
+        window: '@7',
+    }));
+    createNode(node('child', { parent: 'root' }));
+    createNode(node('grand', { parent: 'child' }));
+    subscribe('root', 'child', true);
+    subscribe('child', 'grand', true);
+    // Working state on the old root that parking must PRESERVE (no wipe).
+    writeFileSync(roadmapPath('root'), '# Roadmap\nold goal\n');
+    writeFileSync(inboxPath('root'), '{"ts":"x","from":"child","tier":"normal","kind":"update","label":"hi"}\n');
+    writeFileSync(join(reportsDir('root'), '20260101T000000-update.md'), 'a report');
+    const respawn = okRespawn();
+    const res = relaunchRoot('root', 'test-pane', { relaunchRootInPane: respawn.fn });
+    assert.ok(res !== null, 'relaunchRoot returns the new node id');
+    const newId = res.newNodeId;
+    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).
+    const old = getNode('root');
+    assert.equal(old?.status, 'done', 'old root parked done');
+    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)');
+    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).
+    assert.equal(existsSync(roadmapPath('root')), true, 'roadmap preserved');
+    assert.equal(existsSync(inboxPath('root')), true, 'inbox preserved');
+    assert.equal(existsSync(join(reportsDir('root'), '20260101T000000-update.md')), true, 'report preserved');
+    // New root: fresh base resident, active, intent=refresh, empty context dir,
+    // spawned_by=old, focused.
+    const fresh = getNode(newId);
+    assert.equal(fresh?.parent, null, 'new node is a root');
+    assert.equal(fresh?.mode, 'base');
+    assert.equal(fresh?.lifecycle, 'resident');
+    assert.equal(fresh?.status, 'active');
+    assert.equal(fresh?.intent, 'refresh', 'safety-net intent until boot');
+    assert.equal(fresh?.spawned_by, 'root', 'audit-only successor link to old root');
+    assert.equal(fresh?.pi_pid, null, 'no pi yet');
+    assert.equal(fresh?.tmux_session, 'crtr', 'adopted the old root window location');
+    assert.equal(fresh?.window, '@7');
+    assert.ok(fresh?.launch, 'a fresh base launch spec was written');
+    assert.equal(readdirSync(contextDir(newId)).length, 0, 'fresh empty context dir');
+    assert.equal(getFocus(), newId, 'focus follows content to the new root');
+});
+// ---------------------------------------------------------------------------
+// #1b — handleNewSession success branch: root WITH a pane routes to relaunch
+// ---------------------------------------------------------------------------
+test('handleNewSession on a root with a pane returns path:relaunch + parks old, mints fresh', () => {
+    createNode(node('root', {
+        parent: null,
+        lifecycle: 'resident',
+        mode: 'orchestrator',
+        pi_session_id: 'root-sess',
+        tmux_session: 'crtr',
+        window: '@7',
+    }));
+    createNode(node('child', { parent: 'root' }));
+    subscribe('root', 'child', true);
+    const respawn = okRespawn();
+    const res = handleNewSession('root', 'newsess', 'test-pane', { relaunchRootInPane: respawn.fn });
+    // The policy router's success return shape: relaunch + a fresh new node id.
+    assert.equal(res.path, 'relaunch', 'root + pane routes to option C relaunch');
+    assert.ok(res.newNodeId, 'newNodeId set on the relaunch path');
+    assert.notEqual(res.newNodeId, 'root', 'a FRESH id, not the old root');
+    // Respawn dispatched against the new node in the pane.
+    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?.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');
+    const fresh = getNode(res.newNodeId);
+    assert.equal(fresh?.parent, null, 'new node is a root');
+    assert.equal(fresh?.status, 'active', 'fresh root active');
+    assert.equal(fresh?.spawned_by, 'root', 'audit-only successor link to old root');
+    assert.equal(getFocus(), res.newNodeId, 'focus follows to the fresh root');
+});
+// ---------------------------------------------------------------------------
+// #2 — handleNewSession on a non-root → session-id refresh only
+// ---------------------------------------------------------------------------
+test('handleNewSession on a non-root child only refreshes its session id', () => {
+    createNode(node('root', { parent: null }));
+    createNode(node('child', { parent: 'root', pi_session_id: 'old', pi_session_file: '/abs/old.jsonl' }));
+    subscribe('root', 'child', true);
+    const before = listNodes().length;
+    const res = handleNewSession('child', 'fresh', 'test-pane', {}, '/abs/fresh.jsonl');
+    assert.equal(res.path, 'reset-child');
+    assert.equal(res.newNodeId, undefined, 'no new node minted');
+    assert.equal(getNode('child')?.pi_session_id, 'fresh', 'session id refreshed');
+    assert.equal(getNode('child')?.pi_session_file, '/abs/fresh.jsonl', 'session FILE refreshed (path-based resume)');
+    assert.equal(getNode('child')?.status, 'active', 'child not reaped');
+    assert.equal(listNodes().length, before, 'no node added');
+});
+// ---------------------------------------------------------------------------
+// #3 — handleNewSession on a root with no pane → in-place reset fallback
+// ---------------------------------------------------------------------------
+test('handleNewSession on a root with no pane falls back to in-place resetRoot', () => {
+    createNode(node('root', { parent: null, lifecycle: 'resident', mode: 'orchestrator' }));
+    createNode(node('child', { parent: 'root' }));
+    subscribe('root', 'child', true);
+    writeFileSync(roadmapPath('root'), '# Roadmap\n');
+    const before = listNodes().length;
+    const res = handleNewSession('root', 'newsess', undefined);
+    assert.equal(res.path, 'reset-root', 'documented degradation: in-place reset');
+    assert.equal(res.newNodeId, undefined, 'NO new node created');
+    assert.equal(listNodes().length, before, 'no node added (same id re-pointed)');
+    // Same id re-pointed to a pristine base resident.
+    const root = getNode('root');
+    assert.equal(root?.status, 'active');
+    assert.equal(root?.mode, 'base');
+    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(existsSync(roadmapPath('root')), false, 'working state wiped');
+});
+// ---------------------------------------------------------------------------
+// #4 — rapid double /new guard
+// ---------------------------------------------------------------------------
+test('a second relaunchRoot on an already-parked root is a no-op', () => {
+    createNode(node('root', { parent: null, lifecycle: 'resident' }));
+    const respawn = okRespawn();
+    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
+    // 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)');
+});
+// ---------------------------------------------------------------------------
+// #5 — /new before the root ever spawned children
+// ---------------------------------------------------------------------------
+test('relaunchRoot on a childless root: reap is a no-op, new node minted', () => {
+    createNode(node('root', { parent: null, lifecycle: 'resident', tmux_session: 'crtr', window: '@1' }));
+    assert.deepEqual(reapDescendants('root'), [], 'no descendants to reap');
+    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(res.newNodeId)?.status, 'active', 'fresh root active');
+});
+// ---------------------------------------------------------------------------
+// #6 — respawn dispatch failure → rollback + resetRoot
+// ---------------------------------------------------------------------------
+test('a respawn dispatch failure rolls the whole transaction back and degrades to resetRoot', () => {
+    createNode(node('root', {
+        parent: null,
+        lifecycle: 'resident',
+        mode: 'orchestrator',
+        pi_session_id: 'root-sess',
+        tmux_session: 'crtr',
+        window: '@3',
+    }));
+    const respawn = throwingRespawn();
+    const res = handleNewSession('root', 'newsess', 'test-pane', { relaunchRootInPane: respawn.fn });
+    assert.equal(res.path, 'reset-root', 'degraded to in-place reset');
+    // Old root: FULLY restored by the transaction rollback (active, with its
+    // window/session intact), then re-pointed by the resetRoot degrade path.
+    const old = getNode('root');
+    assert.equal(old?.status, 'active', 'old root back to active');
+    assert.equal(old?.window, '@3', 'window restored');
+    assert.equal(old?.tmux_session, 'crtr', 'session restored');
+    assert.equal(old?.mode, 'base', 'resetRoot re-pointed to base');
+    assert.equal(old?.pi_session_id, 'newsess', 'resetRoot rebound the new session id');
+    // No partial state: the half-built new node's ROW was rolled back WITH the
+    // transaction — no zombie active node, and (unlike the old hand-rolled
+    // compensation, which left a leaked `dead` row) no leftover row at all.
+    const actives = listNodes({ status: ['active'] }).map((r) => r.node_id);
+    assert.deepEqual(actives, ['root'], 'only the old root is active — no zombie');
+    assert.equal(listNodes({ status: ['dead'] }).length, 0, 'no dead zombie — new node row rolled back');
+    assert.equal(listNodes().length, 1, 'only the old root row exists — the mint was fully undone');
+    assert.equal(getFocus(), 'root', 'focus restored to the old root');
+});
+// ---------------------------------------------------------------------------
+// #7 — markCleanExitDone guard table (termination rule)
+// ---------------------------------------------------------------------------
+test('markCleanExitDone: quit on an active/intent-null node marks it done', () => {
+    createNode(node('n', { status: 'active', intent: null }));
+    assert.equal(markCleanExitDone('n', 'quit'), true);
+    assert.equal(getNode('n')?.status, 'done');
+});
+test('markCleanExitDone does NOT clobber an idle-released node', () => {
+    createNode(node('n', { status: 'idle', intent: 'idle-release' }));
+    assert.equal(markCleanExitDone('n', 'quit'), false);
+    assert.equal(getNode('n')?.status, 'idle', 'unchanged');
+    assert.equal(getNode('n')?.intent, 'idle-release', 'intent unchanged');
+});
+test('markCleanExitDone does NOT clobber a node mid-refresh-yield', () => {
+    createNode(node('n', { status: 'active', intent: 'refresh' }));
+    assert.equal(markCleanExitDone('n', 'quit'), false);
+    assert.equal(getNode('n')?.status, 'active', 'unchanged');
+    assert.equal(getNode('n')?.intent, 'refresh', 'intent unchanged');
+});
+test('markCleanExitDone does NOT re-mark an already-done node', () => {
+    createNode(node('n', { status: 'done', intent: null }));
+    assert.equal(markCleanExitDone('n', 'quit'), false);
+    assert.equal(getNode('n')?.status, 'done', 'unchanged');
+});
+test('markCleanExitDone is a no-op for every non-quit reason', () => {
+    for (const reason of ['new', 'reload', 'resume', 'fork']) {
+        closeDb();
+        rmSync(home, { recursive: true, force: true });
+        createNode(node('n', { status: 'active', intent: null }));
+        assert.equal(markCleanExitDone('n', reason), false, `${reason} → no-op`);
+        assert.equal(getNode('n')?.status, 'active', `${reason} leaves node unchanged`);
+    }
+});
+test('markCleanExitDone is a no-op for an unknown node', () => {
+    assert.equal(markCleanExitDone('ghost', 'quit'), false);
+});
+// ---------------------------------------------------------------------------
+// #8 — a parked / quit (done) node is invisible to the daemon's supervised set
+// ---------------------------------------------------------------------------
+test('a done node (parked or cleanly quit) is not in the supervised set', () => {
+    // A done node with a live-LOOKING window — the daemon never sees it because
+    // it only ever supervises listNodes({status:['active','idle']}).
+    createNode(node('parked', { parent: null, status: 'done', tmux_session: 'crtr', window: '@9' }));
+    createNode(node('live', { parent: null, status: 'active', tmux_session: 'crtr', window: '@1' }));
+    const supervised = listNodes({ status: ['active', 'idle'] }).map((r) => r.node_id);
+    assert.ok(!supervised.includes('parked'), 'parked done node excluded from supervision');
+    assert.ok(supervised.includes('live'), 'live root still supervised');
+});
+// ---------------------------------------------------------------------------
+// #9 — renderForest excludes parked / dead / canceled roots
+// ---------------------------------------------------------------------------
+test('renderForest renders only LIVE (active|idle) roots', () => {
+    const mk = (id, status) => {
+        createNode(node(id, { parent: null, status, name: id, kind: 'general' }));
+    };
+    mk('liveroot', 'active');
+    mk('idleroot', 'idle');
+    mk('parkedroot', 'done');
+    mk('deadroot', 'dead');
+    mk('cancelroot', 'canceled');
+    const out = renderForest();
+    assert.ok(out.includes('liveroot'), 'active root rendered');
+    assert.ok(out.includes('idleroot'), 'idle root rendered');
+    assert.ok(!out.includes('parkedroot'), 'parked (done) root hidden');
+    assert.ok(!out.includes('deadroot'), 'dead root hidden');
+    assert.ok(!out.includes('cancelroot'), 'canceled root hidden');
+});

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

@@ -5,6 +5,7 @@ import { mkdtempSync, rmSync, existsSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createNode, getNode, subscribe, setStatus, subscriptionsOf, view, } from '../canvas/canvas.js';
+import { openFocusRow, getFocusByNode } from '../canvas/focuses.js';
 import { closeDb } from '../canvas/db.js';
 import { reportsDir, inboxPath } from '../canvas/paths.js';
 import { roadmapPath } from '../runtime/roadmap.js';
@@ -48,16 +49,16 @@ test('resetRoot empties the root view, reaps descendants, and wipes working stat
     writeFileSync(inboxPath('root'), '{"ts":"x","from":"child","tier":"normal","kind":"update","label":"hi"}\n');
     writeFileSync(join(reportsDir('root'), '20260101T000000-update.md'), 'stale report');
     assert.equal(view('root').length, 2, 'precondition: root sees 2 descendants');
-    const res = resetRoot('root', 'new-sess');
+    const res = resetRoot('root', 'new-sess', '/abs/sessions/new.jsonl');
     assert.equal(res.reset, true);
     assert.deepEqual(res.detached, ['child'], 'root detaches its direct subscription');
     assert.deepEqual(res.reaped.sort(), ['child', 'grand'], 'whole sub-DAG reaped');
     // 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 dead (daemon will skip them).
-    assert.equal(getNode('child')?.status, 'dead');
-    assert.equal(getNode('grand')?.status, 'dead');
+    // Descendants are done (clean teardown, not a fault; daemon skips them).
+    assert.equal(getNode('child')?.status, 'done');
+    assert.equal(getNode('grand')?.status, 'done');
     // Working state wiped.
     assert.equal(existsSync(roadmapPath('root')), false, 'roadmap wiped');
     assert.equal(existsSync(inboxPath('root')), false, 'inbox wiped');
@@ -68,6 +69,7 @@ test('resetRoot empties the root view, reaps descendants, and wipes working stat
     assert.equal(root?.status, 'active');
     assert.equal(root?.intent, null);
     assert.equal(root?.pi_session_id, 'new-sess');
+    assert.equal(root?.pi_session_file, '/abs/sessions/new.jsonl', 'session FILE rebound too');
     assert.ok(root?.launch, 'a fresh base launch spec was written');
 });
 test('resetRoot on a non-root only refreshes the session id (no reap)', () => {
@@ -75,15 +77,32 @@ test('resetRoot on a non-root only refreshes the session id (no reap)', () => {
     createNode(node('child', { parent: 'root', pi_session_id: 'old' }));
     subscribe('root', 'child', true);
     subscribe('child', 'root', false); // contrived: ensure child has an outgoing edge
-    const res = resetRoot('child', 'fresh');
+    const res = resetRoot('child', 'fresh', '/abs/sessions/fresh.jsonl');
     assert.equal(res.reset, false, 'a non-root is not a graph reset');
     assert.deepEqual(res.reaped, []);
     assert.deepEqual(res.detached, []);
     assert.equal(getNode('child')?.pi_session_id, 'fresh', 'session id still refreshed');
+    assert.equal(getNode('child')?.pi_session_file, '/abs/sessions/fresh.jsonl', 'session FILE refreshed too');
     assert.equal(getNode('child')?.status, 'active', 'child not reaped');
     // The root that subscribes to the child is untouched.
     assert.equal(getNode('root')?.status, 'active');
 });
+test('Step 7: resetRoot reaps a FOCUSED descendant through tearDownNode (closes its focus row + nulls presence)', () => {
+    createNode(node('root', { parent: null, lifecycle: 'resident', mode: 'orchestrator' }));
+    createNode(node('desc', { parent: 'root', pane: '%d' }));
+    subscribe('root', 'desc', true);
+    openFocusRow('fD', '%d', 'Suser', 'desc');
+    resetRoot('root', 'new-sess');
+    // reapDescendants now routes each descendant through tearDownNode, so a focused
+    // descendant's focus row is closed and its LOCATION nulled. Non-vacuous:
+    // pre-Step-7 reap used closeWindow and never touched the focuses table, so
+    // 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.pane ?? null, null, 'descendant pane nulled');
+    assert.equal(d.tmux_session ?? null, null, 'descendant session nulled');
+});
 test('resetRoot is a no-op for an unknown node', () => {
     const res = resetRoot('ghost', 'x');
     assert.equal(res.reset, false);
@@ -96,10 +115,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 dead, we don't delete the node).
+    // The node record persists (we detach + mark done, we don't delete the node).
     const child = getNode('child');
     assert.ok(child, 'child meta still on disk');
-    assert.equal(child?.status, 'dead');
+    assert.equal(child?.status, 'done');
     // It is just unreachable from the root.
     assert.equal(view('root').length, 0);
 });

package/dist/core/__tests__/revive.test.d.ts

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

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

@@ -0,0 +1,217 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/revive.test.ts
+//
+// Covers the session-picker fix: a revive must resume by ABSOLUTE session-file
+// path (cwd-immune) when one was captured, falling back to the bare uuid for
+// older nodes — and the double-revive guard that keeps two pi processes off one
+// session file. The argv selection is unit-tested via the pure `resumeArgs` +
+// `buildPiArgv`; the guard is exercised against a REAL tmux window (gated on
+// tmux availability, like daemon-liveness.test.ts).
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { createNode, getNode } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { buildPiArgv } from '../runtime/launch.js';
+import { resumeArgs, reviveNode } from '../runtime/revive.js';
+let home;
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'developer',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+function hasTmux() {
+    return spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0;
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-revive-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+// ---------------------------------------------------------------------------
+// resumeArgs — the pure resume-source selection
+// ---------------------------------------------------------------------------
+test('resumeArgs prefers the absolute file path and keeps the id as fallback', () => {
+    const m = node('n', { pi_session_id: 'uuid-123', pi_session_file: '/abs/sess.jsonl' });
+    assert.deepEqual(resumeArgs(m, true), {
+        resumeSessionId: 'uuid-123',
+        resumeSessionPath: '/abs/sess.jsonl',
+    });
+});
+test('resumeArgs falls back to the bare id when no file was captured (older node)', () => {
+    const m = node('n', { pi_session_id: 'uuid-123', pi_session_file: null });
+    assert.deepEqual(resumeArgs(m, true), {
+        resumeSessionId: 'uuid-123',
+        resumeSessionPath: undefined,
+    });
+});
+test('resumeArgs selects neither source on a no-resume (refresh) revive', () => {
+    const m = node('n', { pi_session_id: 'uuid-123', pi_session_file: '/abs/sess.jsonl' });
+    assert.deepEqual(resumeArgs(m, false), {});
+});
+// ---------------------------------------------------------------------------
+// buildPiArgv — the `--session` argument the revive builds
+// ---------------------------------------------------------------------------
+test('buildPiArgv resumes by ABSOLUTE path when pi_session_file is set (not the uuid)', () => {
+    const m = node('n', { pi_session_id: 'uuid-123', pi_session_file: '/abs/sess.jsonl' });
+    const { argv } = buildPiArgv(m, resumeArgs(m, true));
+    const i = argv.indexOf('--session');
+    assert.ok(i >= 0, 'argv carries --session');
+    assert.equal(argv[i + 1], '/abs/sess.jsonl', 'resumes by absolute file path');
+    assert.ok(!argv.includes('uuid-123'), 'the bare uuid is NOT used when a path exists');
+});
+test('buildPiArgv falls back to --session <uuid> when no path is stored', () => {
+    const m = node('n', { pi_session_id: 'uuid-123', pi_session_file: null });
+    const { argv } = buildPiArgv(m, resumeArgs(m, true));
+    const i = argv.indexOf('--session');
+    assert.ok(i >= 0, 'argv carries --session');
+    assert.equal(argv[i + 1], 'uuid-123', 'resumes by bare uuid (older node)');
+});
+test('buildPiArgv passes no --session on a fresh (no-resume) launch', () => {
+    const m = node('n', { pi_session_id: 'uuid-123', pi_session_file: '/abs/sess.jsonl' });
+    const { argv } = buildPiArgv(m, { prompt: 'go' });
+    assert.ok(!argv.includes('--session'), 'a fresh launch never resumes');
+    assert.ok(argv.includes('go'), 'the kickoff prompt is the last positional');
+});
+// ---------------------------------------------------------------------------
+// buildPiArgv — the resumed argv replays the persisted launch spec faithfully
+// (kind/mode/lifecycle come back as the node's *current* self).
+// ---------------------------------------------------------------------------
+test('a resumed revive replays the persisted LaunchSpec (model, tools, extensions, prompt, env)', () => {
+    const m = node('n', {
+        kind: 'developer',
+        mode: 'orchestrator',
+        pi_session_id: 'uuid-9',
+        pi_session_file: '/abs/sess.jsonl',
+        launch: {
+            model: 'anthropic/sonnet',
+            tools: ['bash', 'read'],
+            extensions: ['/ext/a.js', '/ext/b.js'],
+            systemPrompt: 'You are a developer orchestrator.',
+            env: { FOO: 'bar' },
+        },
+    });
+    createNode(m); // scaffolds the node dir so the system prompt persists to a file
+    const { argv, env } = buildPiArgv(m, resumeArgs(m, true));
+    // Persona extensions, in order.
+    const ea = argv.indexOf('/ext/a.js');
+    const eb = argv.indexOf('/ext/b.js');
+    assert.ok(ea >= 0 && eb > ea, 'extensions replayed in order');
+    assert.equal(argv[ea - 1], '-e');
+    // Model + tools + system prompt + resume target.
+    const mi = argv.indexOf('--model');
+    assert.equal(argv[mi + 1], 'anthropic/sonnet');
+    const ti = argv.indexOf('--tools');
+    assert.equal(argv[ti + 1], 'bash,read');
+    assert.ok(argv.includes('--append-system-prompt'), 'system prompt replayed');
+    const si = argv.indexOf('--session');
+    assert.equal(argv[si + 1], '/abs/sess.jsonl', 'still resumes by file path');
+    // Env contract: launch-spec env merged over the node identity env.
+    assert.equal(env['FOO'], 'bar');
+    assert.equal(env['CRTR_NODE_ID'], 'n');
+    assert.equal(env['CRTR_KIND'], 'developer');
+    assert.equal(env['CRTR_MODE'], 'orchestrator');
+});
+// ---------------------------------------------------------------------------
+// Double-revive guard — reviveNode no-ops when the window is already alive
+// (gated on tmux, which CI may not have; the guard needs a genuinely-live window
+// to short-circuit before any tmux mutation).
+// ---------------------------------------------------------------------------
+/** Hold a real, live tmux window open for the duration of `fn`, then tear down. */
+async function withLiveWindow(tag, fn) {
+    const session = `crtr-revivetest-${process.pid}-${tag}`;
+    spawnSync('tmux', ['new-session', '-d', '-s', session, '-c', '/tmp', 'sleep 600']);
+    try {
+        const r = spawnSync('tmux', ['list-windows', '-t', session, '-F', '#{window_id}'], { encoding: 'utf8' });
+        const window = (r.stdout ?? '').trim().split('\n')[0];
+        await fn(session, window);
+    }
+    finally {
+        spawnSync('tmux', ['kill-session', '-t', session], { stdio: 'ignore' });
+    }
+}
+function windowCount(session) {
+    const r = spawnSync('tmux', ['list-windows', '-t', session, '-F', '#{window_id}'], { encoding: 'utf8' });
+    return (r.stdout ?? '').trim().split('\n').filter((s) => s !== '').length;
+}
+test('reviveNode no-ops when the node pane is alive AND its pi is LIVE (double-revive guard)', { skip: !hasTmux() }, async () => {
+    await withLiveWindow('guard', async (session, window) => {
+        // pi_pid = this process: a genuinely LIVE pi. The guard now keys on pane-
+        // alive AND pi-alive (Step 7), so this models "another path already revived
+        // it" — a no-op (re-launching would double-spawn onto the same session file).
+        createNode(node('M', {
+            tmux_session: session,
+            window,
+            cycles: 3,
+            pi_pid: process.pid,
+            pi_session_id: 'uuid-1',
+            pi_session_file: '/abs/m.jsonl',
+        }));
+        const before = windowCount(session);
+        const res = reviveNode('M', { resume: true });
+        assert.equal(res.window, window, 'returns the existing live window');
+        assert.equal(res.session, session, 'returns the existing session');
+        assert.equal(res.resumed, false, 'guard path does not re-resume');
+        assert.equal(windowCount(session), before, 'no new window opened');
+        assert.equal(getNode('M')?.cycles, 3, 'cycle counter NOT bumped (guard returned early)');
+    });
+});
+test('reviveNode PROCEEDS when the pane is alive but the pi is DEAD (F3 frozen-pane resume)', { skip: !hasTmux() }, async () => {
+    // The Step-7 guard fix: a FROZEN focus pane (remain-on-exit) is pane-alive but
+    // pi-DEAD — the resume-into-focus case. The OLD pane-only guard would no-op
+    // here (the bug that left a frozen focused-dormant node stuck); the new guard
+    // gates on pi liveness too, so reviveNode proceeds (bumps the cycle counter).
+    await withLiveWindow('frozen', async (session, window) => {
+        createNode(node('M', {
+            tmux_session: session,
+            window,
+            cycles: 3,
+            pi_pid: 0x7ffffffe, // implausible/dead pid → a frozen pane with no live pi
+            pi_session_id: 'uuid-1',
+            pi_session_file: '/abs/m.jsonl',
+        }));
+        reviveNode('M', { resume: true });
+        assert.equal(getNode('M')?.cycles, 4, 'cycle counter BUMPED — the guard did NOT short-circuit a frozen pane');
+    });
+});
+// ---------------------------------------------------------------------------
+// Step 5 (§5.3): reviveNode DELEGATES placement to reviveIntoPlacement — a
+// non-focused node targets its home_session, NEVER its (focus-tainted)
+// tmux_session. This is the reviveNode-level bug-kill proof. Gated to run when
+// tmux is ABSENT, so openNodeWindow no-ops (returns null) and no real pi is
+// launched — the placement DECISION (session + LOCATION) is set synchronously
+// regardless of whether a window actually opens, so the assertions are exact.
+// (The WITH-tmux window-placement behaviour is proven in placement-revive.test.ts.)
+// ---------------------------------------------------------------------------
+test('reviveNode delegates to home_session for a non-focused node, IGNORING the tainted tmux_session (§5.3)', { skip: hasTmux() }, async () => {
+    const back = `crtr-back-${process.pid}`;
+    const tainted = `crtr-user-${process.pid}`; // the focus taint that must be ignored
+    // A non-focused child: home_session is the backstage; tmux_session was tainted
+    // to a user session by a prior focus and never corrected. No focus row exists.
+    createNode(node('M', { home_session: back, tmux_session: tainted, window: '@7', pane: null }));
+    const res = reviveNode('M', { resume: false });
+    assert.equal(res.session, back, 'revive targets home_session, not the tainted user session');
+    assert.notEqual(res.session, tainted, 'NEVER the tainted tmux_session');
+    const m = getNode('M');
+    assert.equal(m.tmux_session, back, 'LOCATION repointed to the backstage (taint overwritten)');
+    assert.equal(m.window, null, 'no tmux present → openNodeWindow no-op, window null (decision still recorded)');
+    assert.equal(m.cycles, 1, 'a real (non-guard) revive bumped the cycle counter');
+});

package/dist/core/__tests__/spawn-root.test.d.ts

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