@crouton-kit/crouter 0.3.13 → 0.3.15

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

@@ -0,0 +1,238 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/placement-revive.test.ts
+//
+// STEP 5 of the placement/focus migration: placement-aware revive (§1.4) — THE
+// step that kills the "unbidden windows in my session" bug. Two proofs:
+//
+//   1. The PURE bug-death test (§5.1, the crown jewel): reviveTarget(focus,
+//      focusPaneAlive, homeSession) — the target decision in isolation, no tmux.
+//      The load-bearing assertion is the once-focused-now-unfocused CHILD: its
+//      focus is gone (focusOf == null) and home_session = 'crtr' even though the
+//      OLD meta.tmux_session was tainted to a user session → backstage 'crtr',
+//      NOT the user session. That is the audit §F/H1 defect, structurally dead.
+//
+//   2. The gated real-tmux swap-out-skipped regression (§5.2, the definitive
+//      proof): focus a node into a user session, terminate its pi (the focus
+//      pane collapses — Step 5 has no remain-on-exit yet), wake it via
+//      reviveIntoPlacement → assert ZERO new windows appear in the user session
+//      across the whole sequence; the revived node lands in home_session.
+//
+//   Plus: backstage-into-home_session (the taint is IGNORED), respawn-into-focus
+//   (F3 resume in place, no new window), and reconcileFocus following a manual
+//   move of the focus pane (Q4). The gated tests drive a benign `sleep` command,
+//   never a real pi — reviveNode delegates the placement decision to exactly the
+//   reviveIntoPlacement exercised here.
+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 { openFocusRow, getFocusByNode, getFocusById } from '../canvas/focuses.js';
+import { closeDb } from '../canvas/db.js';
+import { reviveTarget, reviveIntoPlacement, reconcileFocus } from '../runtime/placement.js';
+import { reviveInPlace } 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 focus(over = {}) {
+    return { focus_id: 'f1', pane: '%a', session: 'Suser', node_id: 'M', ...over };
+}
+function hasTmux() {
+    return spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0;
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-placement-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'];
+});
+// ---------------------------------------------------------------------------
+// 1. The PURE bug-death test (§5.1) — reviveTarget in isolation. No tmux.
+// ---------------------------------------------------------------------------
+test('reviveTarget: a node on a LIVE focus → resume IN PLACE in that focus pane', () => {
+    const d = reviveTarget(focus({ pane: '%a', session: 'Suser', node_id: 'M' }), true, 'crtr');
+    assert.deepEqual(d, { kind: 'focus-pane', pane: '%a', session: 'Suser' });
+});
+test('reviveTarget: a non-focused CHILD (home_session=crtr) → BACKSTAGE crtr (never a user session)', () => {
+    assert.deepEqual(reviveTarget(null, false, 'crtr'), { kind: 'backstage', session: 'crtr' });
+});
+test('reviveTarget: a ROOT (home_session = its own user session) → backstage THAT session (NOT the bug)', () => {
+    // A root legitimately lives in its own adopted user session; reviving it there
+    // is correct. The bug is a non-focused CHILD landing in a user session — not a
+    // root reviving into its own.
+    assert.deepEqual(reviveTarget(null, false, 'Suser-root'), { kind: 'backstage', session: 'Suser-root' });
+});
+test('THE BUG, structurally dead: a once-focused-now-unfocused CHILD → BACKSTAGE crtr, NOT the tainted user session', () => {
+    // The exact audit §F/H1 scenario. The child WAS focused, so its OLD
+    // meta.tmux_session was tainted to the user session — but the focus is gone
+    // (focusOf == null) and reviveTarget keys on home_session ('crtr'), NEVER on
+    // the tainted tmux_session. So the revive lands backstage in 'crtr'. THIS is
+    // the assertion that proves the "unbidden windows" bug cannot recur: even with
+    // a tainted tmux_session sitting in the row, the target is home_session only.
+    const d = reviveTarget(null, false, 'crtr');
+    assert.equal(d.kind, 'backstage');
+    assert.equal(d.session, 'crtr');
+    assert.notEqual(d.session, 'Suser', 'NOT the tainted user session');
+});
+test('A-MAJOR-1 dead (refresh-yield twin): a focused (tainted) child reviveInPlace propagates CRTR_ROOT_SESSION = home_session (backstage), so any child it spawns lands backstage — NOT the user session', () => {
+    // The reviveInPlace (refresh-yield) counterpart to the reviveTarget crown
+    // jewel above. A focused child M was tainted: meta.tmux_session = the USER
+    // session (focus taints it), home_session = the backstage `crtr`. Pre-fix,
+    // reviveInPlace re-execed M's pi with CRTR_ROOT_SESSION = meta.tmux_session =
+    // the user session, so any child M then spawned opened its window in the user's
+    // session (and re-tainted that grandchild's home_session). The fix sources
+    // CRTR_ROOT_SESSION from home_session — the taint-immune backstage. We capture
+    // the env reviveInPlace dispatches to the pane respawn and assert it carries
+    // the backstage, never the tainted session. Fails against the pre-fix code.
+    const back = `crtr-back-${process.pid}`;
+    const user = `crtr-user-${process.pid}`; // the focus taint that must be ignored
+    createNode(node('M', { home_session: back, tmux_session: user, window: '@7', pane: '%5' }));
+    let captured;
+    const spy = (opts) => {
+        captured = opts.env;
+        return true;
+    };
+    reviveInPlace('M', '%5', spy);
+    assert.equal(captured?.['CRTR_ROOT_SESSION'], back, 'children spawn into the backstage home_session');
+    assert.notEqual(captured?.['CRTR_ROOT_SESSION'], user, 'NEVER the tainted user session (A-MAJOR-1 dead)');
+    // The node's own LOCATION is unchanged — the re-exec is in place, the pane
+    // never moved, so it still sits in the (still-tainted) user session.
+    assert.equal(getNode('M').tmux_session, user, 'LOCATION preserved (in-place re-exec); only the child env is hardened');
+});
+test('reviveTarget: a focus whose pane has COLLAPSED (focusPaneAlive=false) → backstage, not a dead pane', () => {
+    // Step-5 limitation: a focused node that fully terminates has no remain-on-exit
+    // yet, so its focus pane collapses. focusPaneAlive=false → backstage (home),
+    // never the gone focus pane. Still SAFE: home_session, never a user session.
+    const d = reviveTarget(focus({ pane: '%gone', session: 'Suser', node_id: 'M' }), false, 'crtr');
+    assert.deepEqual(d, { kind: 'backstage', session: 'crtr' });
+});
+// ---------------------------------------------------------------------------
+// 2. Gated real-tmux placement (skip when tmux is absent). Each test isolates
+// two real sessions: `user` (the user's terminal) and `back` (the backstage that
+// stands in for `crtr`). We drive reviveIntoPlacement with a benign `sleep`
+// command, never a real pi.
+// ---------------------------------------------------------------------------
+function tmuxOut(args) {
+    return (spawnSync('tmux', args, { encoding: 'utf8' }).stdout ?? '').trim();
+}
+function windowIds(session) {
+    return tmuxOut(['list-windows', '-t', session, '-F', '#{window_id}']).split('\n').filter((s) => s !== '');
+}
+/** Hold two real, isolated sessions (`user` + `back`) open for `fn`, exposing the
+ *  user session's first window + active pane, then tear both down. */
+async function withUserAndBackstage(tag, fn) {
+    const user = `crtr-rev-user-${process.pid}-${tag}`;
+    const back = `crtr-rev-back-${process.pid}-${tag}`;
+    spawnSync('tmux', ['new-session', '-d', '-s', user, '-c', '/tmp', 'sleep 600']);
+    spawnSync('tmux', ['new-session', '-d', '-s', back, '-c', '/tmp', 'sleep 600']);
+    try {
+        const userWindow = windowIds(user)[0];
+        await fn({ user, back, userWindow });
+    }
+    finally {
+        spawnSync('tmux', ['kill-session', '-t', user], { stdio: 'ignore' });
+        spawnSync('tmux', ['kill-session', '-t', back], { stdio: 'ignore' });
+    }
+}
+/** Open a real, live extra pane inside `session:window` (a stand-in focus pane)
+ *  running `sleep`, and return its durable `%pane_id`. */
+function liveFocusPane(session, window) {
+    return tmuxOut(['split-window', '-d', '-P', '-F', '#{pane_id}', '-t', `${session}:${window}`, 'sleep 600']);
+}
+const launch = (over = {}) => ({
+    command: 'sleep 600',
+    env: {},
+    cwd: '/tmp',
+    name: 'm',
+    resuming: false,
+    ...over,
+});
+test('reviveIntoPlacement (backstage): a non-focused node opens in home_session, IGNORING its tainted tmux_session', { skip: !hasTmux() }, async () => {
+    await withUserAndBackstage('backstage', async ({ user, back }) => {
+        // A child whose tmux_session was TAINTED to the user session (as focus would
+        // have done) but which is NOT focused now. home_session = the backstage.
+        createNode(node('M', { home_session: back, tmux_session: user, window: null, pane: null }));
+        const userBefore = windowIds(user).length;
+        const backBefore = windowIds(back).length;
+        const placed = reviveIntoPlacement('M', launch());
+        assert.equal(windowIds(user).length, userBefore, 'ZERO new windows in the user session');
+        assert.equal(windowIds(back).length, backBefore + 1, 'exactly one new window in home_session (backstage)');
+        assert.equal(placed.session, back, 'placed into home_session, not the tainted user session');
+        assert.ok(placed.pane?.startsWith('%'), 'a durable pane id was recorded');
+        const m = getNode('M');
+        assert.equal(m.tmux_session, back, 'LOCATION repointed to the backstage; the taint is overwritten');
+        assert.equal(m.pane, placed.pane, 'the row pane matches the opened pane');
+    });
+});
+test('§5.2 swap-out-skipped regression: focus→terminate→wake puts ZERO new windows in the user session', { skip: !hasTmux() }, async () => {
+    await withUserAndBackstage('regress', async ({ user, back, userWindow }) => {
+        // The bug scenario, end to end:
+        //   1. M is a child focused into the user session: a real focus pane in
+        //      `user`, a focus row on it, and (the taint) tmux_session=user.
+        //   2. Its pi terminates → the focus pane COLLAPSES (Step 5 has no
+        //      remain-on-exit yet) — modelled by killing the focus pane.
+        //   3. The daemon/reviveNode wakes M → reviveIntoPlacement.
+        // The fix: M lands in home_session (backstage), NOT a new window in `user`.
+        const focusPane = liveFocusPane(user, userWindow);
+        createNode(node('M', { home_session: back, tmux_session: user, window: userWindow, pane: focusPane }));
+        openFocusRow('f1', focusPane, user, 'M');
+        const userBefore = windowIds(user).length;
+        const backBefore = windowIds(back).length;
+        // Terminate: the focus pane collapses (no remain-on-exit in Step 5).
+        spawnSync('tmux', ['kill-pane', '-t', focusPane], { stdio: 'ignore' });
+        const placed = reviveIntoPlacement('M', launch({ resuming: true }));
+        assert.equal(windowIds(user).length, userBefore, 'ZERO new windows opened in the user session across the sequence');
+        assert.equal(windowIds(back).length, backBefore + 1, 'the revived node landed in home_session (backstage)');
+        assert.equal(placed.session, back, 'reviveIntoPlacement targeted home_session, not the tainted user session');
+        assert.equal(getNode('M').tmux_session, back, 'LOCATION repointed to the backstage');
+    });
+});
+test('reviveIntoPlacement (focus-pane): a node on a LIVE focus resumes IN PLACE — no new window anywhere', { skip: !hasTmux() }, async () => {
+    await withUserAndBackstage('inplace', async ({ user, back, userWindow }) => {
+        const focusPane = liveFocusPane(user, userWindow);
+        createNode(node('M', { home_session: back, tmux_session: user, window: userWindow, pane: focusPane }));
+        openFocusRow('f1', focusPane, user, 'M');
+        const userBefore = windowIds(user).length;
+        const backBefore = windowIds(back).length;
+        const placed = reviveIntoPlacement('M', launch({ resuming: true }));
+        assert.equal(placed.pane, focusPane, 'resumed into the SAME focus pane id (respawn-pane -k, no new pane)');
+        assert.equal(windowIds(user).length, userBefore, 'no new window in the user session (resume in place)');
+        assert.equal(windowIds(back).length, backBefore, 'no new window in the backstage either');
+        assert.equal(placed.session, user, 'the focus pane lives in the user session — the F3 resume stays there (desired)');
+        assert.equal(getFocusByNode('M')?.pane, focusPane, 'the focus row still anchors the same pane');
+    });
+});
+test('reconcileFocus: follows a manual move of the focus pane to another session (Q4)', { skip: !hasTmux() }, async () => {
+    await withUserAndBackstage('recfocus', async ({ user, back, userWindow }) => {
+        // Focus pane starts in `user`; the row caches session=user.
+        const focusPane = liveFocusPane(user, userWindow);
+        openFocusRow('f1', focusPane, user, 'M');
+        // The user moves the focus pane into the backstage session (join-pane). The
+        // pane id survives; the row's cached session is now stale.
+        const backWindow = windowIds(back)[0];
+        spawnSync('tmux', ['join-pane', '-s', focusPane, '-t', `${back}:${backWindow}`], { stdio: 'ignore' });
+        reconcileFocus('f1');
+        const f = getFocusById('f1');
+        assert.equal(f?.pane, focusPane, 'pane id is invariant across the move');
+        assert.equal(f?.session, back, 'reconcileFocus FOLLOWED the move to the backstage session');
+    });
+});

package/dist/core/__tests__/placement-teardown.test.d.ts

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

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

@@ -0,0 +1,183 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/placement-teardown.test.ts
+//
+// STEP 7 of the placement/focus migration: the lifecycle-successor + teardown
+// verbs (§1.6/§2.3, flow (e)). Two PURE surfaces (no tmux — pane ids below are
+// never realized, so closePane no-ops and only the DB effects are asserted):
+//
+//   • handFocusToManager(focusId, managerId) — the §1.6 manager-takeover, a PURE
+//     DB occupant swap. Returns true (TAKEOVER) only when there is a distinct,
+//     not-already-focused manager; false (caller closes the focus) in each of the
+//     three guard cases. Each guard is asserted distinctly.
+//   • tearDownNode(nodeId) — close/reset teardown: close the focus row it
+//     occupies, null its LOCATION, and clear focus.ptr when it was the current
+//     focus.
+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 { openFocusRow, getFocusByNode, getFocusById } from '../canvas/focuses.js';
+import { closeDb } from '../canvas/db.js';
+import { handFocusToManager, tearDownNode } from '../runtime/placement.js';
+import { setFocus, getFocus } from '../runtime/presence.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;
+}
+function tmuxOut(args) {
+    return (spawnSync('tmux', args, { encoding: 'utf8' }).stdout ?? '').trim();
+}
+function paneSession(pane) {
+    return tmuxOut(['display-message', '-p', '-t', pane, '#{session_name}']);
+}
+function windowCount(session) {
+    return tmuxOut(['list-windows', '-t', session, '-F', '#{window_id}']).split('\n').filter((s) => s !== '').length;
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-placement-teardown-'));
+    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'];
+});
+// ---------------------------------------------------------------------------
+// handFocusToManager (pure DB) — §1.6 manager-takeover + its three false-guards.
+// ---------------------------------------------------------------------------
+test('handFocusToManager: distinct, free manager → TAKEOVER (repoints the row, returns true)', () => {
+    openFocusRow('f', '%m', 'Sa', 'M');
+    createNode(node('mgr'));
+    assert.equal(handFocusToManager('f', 'mgr'), true, 'a valid manager takes the focus');
+    assert.equal(getFocusByNode('mgr')?.focus_id, 'f', 'the row now shows the manager');
+    assert.equal(getFocusByNode('M'), null, 'the finished node no longer occupies it');
+    // Non-vacuous: a no-op impl returns false / leaves M as occupant → both the
+    // return value and the occupant assert fail.
+});
+test('handFocusToManager: managerId null → false, occupant UNCHANGED', () => {
+    openFocusRow('f', '%m', 'Sa', 'M');
+    assert.equal(handFocusToManager('f', null), false, 'no manager → caller must close the focus');
+    assert.equal(getFocusById('f')?.node_id, 'M', 'occupant unchanged');
+    // Non-vacuous: an impl that skipped the null guard would either return true or
+    // setFocusOccupant(f, null) → NOT NULL violation; the clean false + unchanged
+    // occupant fail against both.
+});
+test('handFocusToManager: manager IS the focus occupant → false (no self-handoff)', () => {
+    openFocusRow('f', '%m', 'Sa', 'M');
+    assert.equal(handFocusToManager('f', 'M'), false, 'handing a node its own focus is a no-op false');
+    assert.equal(getFocusById('f')?.node_id, 'M', 'occupant unchanged');
+    // Non-vacuous: an impl missing the `managerId === f.node_id` guard would return
+    // true.
+});
+test('handFocusToManager: manager already focused ELSEWHERE → false, neither focus moved (UNIQUE node_id)', () => {
+    openFocusRow('fM', '%m', 'Sa', 'M');
+    openFocusRow('fMgr', '%g', 'Sb', 'mgr'); // mgr already occupies its own viewport
+    assert.equal(handFocusToManager('fM', 'mgr'), false, 'a busy manager is not moved — caller closes');
+    assert.equal(getFocusById('fM')?.node_id, 'M', "M's focus is not handed over");
+    assert.equal(getFocusByNode('mgr')?.focus_id, 'fMgr', "mgr's other focus is untouched");
+    // Non-vacuous: an impl missing the already-focused guard would setFocusOccupant
+    // (fM, mgr) → UNIQUE(node_id) violation (mgr already in fMgr), so the expected
+    // clean false + both rows intact fail.
+});
+// ---------------------------------------------------------------------------
+// MAJOR 1 — the LIVE-vs-DORMANT manager split inside handFocusToManager.
+// ---------------------------------------------------------------------------
+test('handFocusToManager: LIVE backstage manager → swaps its pane INTO the focus slot (MAJOR 1)', { skip: !hasTmux() }, () => {
+    // Two real sessions: `user` (the viewport %m sits frozen in) + `back` (where
+    // the manager's pi runs live, the normal multi-child state). The swap is a
+    // real tmux op, so this needs a live server (gated like the other §5.2 tests).
+    const user = `crtr-hfm-user-${process.pid}`;
+    const back = `crtr-hfm-back-${process.pid}`;
+    spawnSync('tmux', ['new-session', '-d', '-s', user, '-c', '/tmp', 'sleep 600']);
+    spawnSync('tmux', ['new-session', '-d', '-s', back, '-c', '/tmp', 'sleep 600']);
+    try {
+        const userWindow = tmuxOut(['list-windows', '-t', user, '-F', '#{window_id}']).split('\n')[0];
+        const backWindow = tmuxOut(['list-windows', '-t', back, '-F', '#{window_id}']).split('\n')[0];
+        const focusPane = tmuxOut(['display-message', '-p', '-t', `${user}:${userWindow}`, '#{pane_id}']); // M's frozen focus pane (%m, the viewport)
+        const mgrPane = tmuxOut(['split-window', '-d', '-P', '-F', '#{pane_id}', '-t', `${back}:${backWindow}`, 'sleep 600']); // mgr's LIVE backstage pane
+        createNode(node('M', { pane: focusPane, tmux_session: user, window: userWindow, status: 'done' }));
+        createNode(node('mgr', { pane: mgrPane, tmux_session: back, window: backWindow, status: 'active', pi_pid: process.pid }));
+        openFocusRow('f', focusPane, user, 'M');
+        const userWinsBefore = windowCount(user);
+        assert.equal(handFocusToManager('f', 'mgr'), true, 'a LIVE manager takes the focus');
+        // Pure-DB takeover (also covered ungated above): occupant repointed M → mgr.
+        assert.equal(getFocusByNode('mgr')?.focus_id, 'f', 'the manager occupies the focus row');
+        assert.equal(getFocusByNode('M'), null, 'the finished node no longer occupies it');
+        // The synchronous swap (MAJOR 1): the focus row re-anchors to mgr's pane,
+        // which has physically moved into the user viewport; the old focus pane (%m)
+        // swapped down into the backstage slot; mgr's presence is the OLD focus slot.
+        assert.equal(getFocusById('f')?.pane, mgrPane, 'focus row re-anchored to the manager pane (swap)');
+        assert.equal(paneSession(mgrPane), user, 'the manager pane physically moved into the user viewport');
+        assert.equal(getNode('mgr').window, userWindow, 'manager presence window == the OLD focus slot window');
+        assert.equal(getNode('mgr').tmux_session, user, 'manager presence session == the viewport');
+        assert.equal(paneSession(focusPane), back, '%m (the dead node\'s pane) swapped DOWN into the backstage slot');
+        assert.equal(windowCount(user), userWinsBefore, 'no new user window — a swap, not an open (screen position invariant)');
+        // Non-vacuous: the pre-MAJOR-1 impl only repointed the occupant and deferred
+        // the physical revive to the daemon — but the daemon revives ONLY dormant
+        // managers, so a LIVE one is never brought in. That impl leaves the focus row
+        // pane == focusPane, mgrPane still in `back`, %m frozen in the viewport, and
+        // mgr's presence at the backstage — every swap assert above fails against it.
+    }
+    finally {
+        spawnSync('tmux', ['kill-session', '-t', user], { stdio: 'ignore' });
+        spawnSync('tmux', ['kill-session', '-t', back], { stdio: 'ignore' });
+    }
+});
+test('handFocusToManager: DORMANT manager (dead pane) → occupant repointed, NO swap, focus pane UNCHANGED', () => {
+    openFocusRow('f', '%focus', 'Suser', 'M');
+    // The manager has a pane recorded but it is NOT a live tmux pane (its dead-pi
+    // window collapsed). isNodePaneAlive(mgr) is therefore false, so the live-swap
+    // is skipped — the external daemon later respawns it into the frozen %focus.
+    createNode(node('mgr', { pane: '%mgr-dead', tmux_session: 'back', window: '@wb', pi_pid: process.pid }));
+    assert.equal(handFocusToManager('f', 'mgr'), true, 'still a takeover (occupant repointed)');
+    assert.equal(getFocusByNode('mgr')?.focus_id, 'f', 'the manager occupies the focus row (DB repoint)');
+    assert.equal(getFocusByNode('M'), null, 'the finished node no longer occupies it');
+    // The split: with no physical swap, the focus row stays anchored on the ORIGINAL
+    // frozen focus pane (the pane the daemon will respawn the manager INTO) and the
+    // manager's backstage presence is left untouched.
+    assert.equal(getFocusById('f')?.pane, '%focus', 'focus row pane NOT re-anchored to the manager pane (no swap)');
+    assert.equal(getNode('mgr').pane, '%mgr-dead', 'manager presence pane unchanged');
+    assert.equal(getNode('mgr').window, '@wb', 'manager presence window unchanged (never moved into a viewport)');
+    // Non-vacuous: an impl that re-anchored the focus row to the manager pane in
+    // the DB (or wrote the manager's presence to the viewport) regardless of a real
+    // physical swap would set f.pane='%mgr-dead' and mgr.window=the focus window —
+    // both asserts fail. Proves the swap gates on PANE LIVENESS, not merely on the
+    // manager having a pane.
+});
+// ---------------------------------------------------------------------------
+// tearDownNode (pure DB; no tmux — pane is null so closePane never runs).
+// ---------------------------------------------------------------------------
+test('tearDownNode: closes the focus row, nulls the LOCATION, and clears focus.ptr', () => {
+    createNode(node('M', { pane: null, window: null }));
+    openFocusRow('fM', null, 'Sa', 'M');
+    setFocus('M'); // M is the current focus.ptr
+    tearDownNode('M');
+    assert.equal(getFocusByNode('M'), null, 'the focus row M occupied is closed');
+    const m = getNode('M');
+    assert.equal(m.pane ?? null, null, 'pane nulled');
+    assert.equal(m.window ?? null, null, 'window nulled');
+    assert.equal(m.tmux_session ?? null, null, 'session nulled');
+    const cur = getFocus();
+    assert.ok(cur === null || cur === '', 'focus.ptr cleared (M was the current focus)');
+    // Non-vacuous: an impl that skips closeFocusRow leaves fM → getFocusByNode('M')
+    // is non-null; one that skips the setFocus('') clear leaves focus.ptr at 'M'.
+});

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

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

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

@@ -0,0 +1,116 @@
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, getRow, subscribe, recordSpawn, subscribersOf, subscriptionsOf, pruneNodes, } from '../canvas/canvas.js';
+import { closeDb, openDb } from '../canvas/db.js';
+import { nodeDir } from '../canvas/paths.js';
+let home;
+const DAY = 86_400_000;
+const old = () => new Date(Date.now() - 30 * DAY).toISOString();
+const now = () => new Date().toISOString();
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: now(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+function totalEdges() {
+    return openDb().prepare('SELECT COUNT(*) AS n FROM edges').get().n;
+}
+/** The standard fixture: three prunable terminal nodes (old), three survivors
+ *  (two old-but-live, one recent-but-dead), and edges that touch a pruned node
+ *  so cascade is observable. */
+function seedFixture() {
+    createNode(node('old-dead', { status: 'dead', created: old() }));
+    createNode(node('old-done', { status: 'done', created: old() }));
+    createNode(node('old-canceled', { status: 'canceled', created: old() }));
+    createNode(node('old-active', { status: 'active', created: old() }));
+    createNode(node('old-idle', { status: 'idle', created: old() }));
+    createNode(node('recent-dead', { status: 'dead', created: now() }));
+    // A survivor subscribes to a pruned node (cascade on to_id) …
+    subscribe('old-active', 'old-dead', true);
+    // … and a pruned node's audit edge to another pruned node (cascade on both).
+    recordSpawn('old-done', 'old-dead');
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-prune-'));
+    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'];
+});
+test('prune removes terminal nodes past the TTL and keeps live + recent ones', () => {
+    seedFixture();
+    assert.equal(totalEdges(), 2);
+    const result = pruneNodes({ ttlDays: 14 });
+    // The three old terminal nodes are pruned; nothing else.
+    assert.equal(result.dryRun, false);
+    assert.deepEqual(result.pruned.map((p) => p.node_id).sort(), ['old-canceled', 'old-dead', 'old-done']);
+    // Pruned rows are gone …
+    for (const id of ['old-dead', 'old-done', 'old-canceled']) {
+        assert.equal(getRow(id), null, `${id} row should be pruned`);
+    }
+    // … and the survivors remain (live-but-old + recent-but-dead).
+    for (const id of ['old-active', 'old-idle', 'recent-dead']) {
+        assert.ok(getRow(id) !== null, `${id} should survive`);
+    }
+});
+test('pruning cascade-deletes the pruned nodes\u2019 edges', () => {
+    seedFixture();
+    assert.equal(totalEdges(), 2);
+    pruneNodes({ ttlDays: 14 });
+    // Both edges touched a pruned node (old-dead) → both cascade away.
+    assert.equal(totalEdges(), 0);
+    // The surviving subscriber's edge to the pruned publisher is gone.
+    assert.deepEqual(subscriptionsOf('old-active'), []);
+    assert.deepEqual(subscribersOf('old-dead'), []);
+});
+test('pruning removes each pruned node\u2019s on-disk dir, leaves survivors\u2019 dirs', () => {
+    seedFixture();
+    assert.ok(existsSync(nodeDir('old-dead')));
+    assert.ok(existsSync(nodeDir('old-active')));
+    pruneNodes({ ttlDays: 14 });
+    assert.ok(!existsSync(nodeDir('old-dead')), 'pruned dir should be removed');
+    assert.ok(!existsSync(nodeDir('old-done')));
+    assert.ok(!existsSync(nodeDir('old-canceled')));
+    assert.ok(existsSync(nodeDir('old-active')), 'survivor dir should remain');
+    assert.ok(existsSync(nodeDir('recent-dead')));
+});
+test('--dry-run reports candidates but deletes nothing', () => {
+    seedFixture();
+    const before = totalEdges();
+    const result = pruneNodes({ ttlDays: 14, dryRun: true });
+    // Candidates are reported …
+    assert.equal(result.dryRun, true);
+    assert.deepEqual(result.pruned.map((p) => p.node_id).sort(), ['old-canceled', 'old-dead', 'old-done']);
+    // … but NOTHING is deleted: rows, edges, and dirs all intact.
+    for (const id of ['old-dead', 'old-done', 'old-canceled']) {
+        assert.ok(getRow(id) !== null, `${id} must survive a dry run`);
+        assert.ok(existsSync(nodeDir(id)), `${id} dir must survive a dry run`);
+    }
+    assert.equal(totalEdges(), before);
+});
+test('prune and the daemon operate on disjoint status sets', () => {
+    // active|idle (the daemon's domain) are NEVER pruned, even when ancient.
+    createNode(node('ancient-active', { status: 'active', created: old() }));
+    createNode(node('ancient-idle', { status: 'idle', created: old() }));
+    const result = pruneNodes({ ttlDays: 14 });
+    assert.equal(result.pruned.length, 0);
+    assert.ok(getRow('ancient-active') !== null);
+    assert.ok(getRow('ancient-idle') !== null);
+});

package/dist/core/__tests__/push-final-guard.test.d.ts

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

package/dist/core/__tests__/push-final-guard.test.js

@@ -0,0 +1,71 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/push-final-guard.test.ts
+//
+// N1 — a 2nd `crtr push final` in one turn is an illegal finalize-from-done that
+// transition() throws on. The push leaf must surface that as a CLEAN user-facing
+// InputError ('already_finalized'), NOT let the raw Error fall through to the
+// `internal` "crtr bug" path. Verifies the guard fires before push() runs.
+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 { createNode, setStatus } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { registerPush } from '../../commands/push.js';
+import { InputError } from '../io.js';
+let home;
+const prevNodeId = process.env['CRTR_NODE_ID'];
+function node(id) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+    };
+}
+/** The `final` tier leaf, fished out of the push branch. */
+function finalLeaf() {
+    const leaf = registerPush().children.find((c) => c.name === 'final');
+    assert.ok(leaf !== undefined && leaf.kind === 'leaf', 'push final leaf exists');
+    return leaf;
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-pushfinal-'));
+    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'];
+    if (prevNodeId === undefined)
+        delete process.env['CRTR_NODE_ID'];
+    else
+        process.env['CRTR_NODE_ID'] = prevNodeId;
+});
+test('push final on an already-done node throws a clean InputError, not a raw transition error', async () => {
+    const id = 'doneNode';
+    createNode(node(id));
+    setStatus(id, 'done'); // simulate the first push final already finalized it
+    process.env['CRTR_NODE_ID'] = id;
+    await assert.rejects(() => finalLeaf().run({ body: 'second final result' }), (e) => {
+        assert.ok(e instanceof InputError, 'a clean command-level error (renders on stdout)');
+        assert.equal(e.payload.error, 'already_finalized');
+        assert.match(e.payload.message, /already done/);
+        return true;
+    });
+});
+test('push final on a dead node is also caught cleanly', async () => {
+    const id = 'deadNode';
+    createNode(node(id));
+    setStatus(id, 'dead');
+    process.env['CRTR_NODE_ID'] = id;
+    await assert.rejects(() => finalLeaf().run({ body: 'x' }), (e) => e instanceof InputError && e.payload.error === 'already_finalized');
+});

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

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