@crouton-kit/crouter 0.3.14 → 0.3.15

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

@@ -0,0 +1,259 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/focuses.test.ts
+//
+// STEP 4 of the placement/focus migration: the `focuses` table + canvas setters
+// + placement reads + the transitional focus.ptr dual-write bridge. Purely
+// ADDITIVE: the table is populated in lockstep with the legacy `focus.ptr`, but
+// nothing reads it as authority yet (that switch is Step 6). Covers:
+//   - migration v6 adds `focuses` to a fresh db (and a legacy v5 db migrates up);
+//     idempotent / forward-only on re-run + re-open
+//   - canvas setters/reads round-trip: open / setOccupant / setPane / close;
+//     getFocusByNode / getFocusByPane / getFocusById / listFocuses
+//   - UNIQUE(node_id): a second focus row (and an occupant UPDATE) for one node
+//     is rejected (upholds "a node occupies <=1 focus", Q5)
+//   - independent focus rows don't contend
+//   - placement focusOf / isFocused / focusByPane / focusedNodes / listFocuses
+//     agree with the rows
+//   - dual-write: setFocus populates the table; getFocus falls back to the table
+//     when focus.ptr is absent; setFocus('') clears both
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, existsSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { openFocusRow, setFocusOccupant, setFocusPane, closeFocusRow, getFocusByNode, getFocusByPane, getFocusById, listFocuses, } from '../canvas/focuses.js';
+import { openDb, closeDb, migrate, MIGRATIONS } from '../canvas/db.js';
+import { canvasDbPath, ensureHome, crtrHome } from '../canvas/paths.js';
+import { focusOf, isFocused, focusByPane, focusedNodes, listFocuses as placementListFocuses, } from '../runtime/placement.js';
+import { setFocus, getFocus } from '../runtime/presence.js';
+let home;
+// Saved/restored so the bridge always exercises its deterministic no-tmux path
+// regardless of whether the suite is run from inside a tmux session.
+let savedTmux;
+function userVersion(db) {
+    return db.prepare('PRAGMA user_version').get().user_version;
+}
+function tableNames(db) {
+    return db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all().map((r) => r.name);
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-focuses-'));
+    process.env['CRTR_HOME'] = home;
+    savedTmux = process.env['TMUX'];
+    delete process.env['TMUX'];
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+    if (savedTmux !== undefined)
+        process.env['TMUX'] = savedTmux;
+});
+// ---------------------------------------------------------------------------
+// Migration v6 — the additive `focuses` table.
+// ---------------------------------------------------------------------------
+test('a fresh db migrates to the latest version and has the focuses table', () => {
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    assert.ok(tableNames(db).includes('focuses'), 'focuses table exists on a fresh db');
+});
+test('the focuses table has the v6 shape (UNIQUE node_id, nullable pane/session)', () => {
+    const db = openDb();
+    const cols = db.prepare('PRAGMA table_info(focuses)').all();
+    const byName = new Map(cols.map((c) => [c.name, c]));
+    assert.equal(byName.get('focus_id')?.pk, 1, 'focus_id is the primary key');
+    assert.equal(byName.get('node_id')?.notnull, 1, 'node_id is NOT NULL');
+    assert.equal(byName.get('pane')?.notnull, 0, 'pane is nullable');
+    assert.equal(byName.get('session')?.notnull, 0, 'session is nullable');
+    // node_id carries a UNIQUE index.
+    const idx = db.prepare('PRAGMA index_list(focuses)').all();
+    assert.ok(idx.some((i) => i.unique === 1), 'a UNIQUE index exists (the node_id constraint)');
+});
+test('a v5 db migrates forward, adding focuses without disturbing existing data', () => {
+    // Hand-build a db at exactly v5: baseline + the four v2 runtime columns + the
+    // v5 pane column + edges WITH the v4 FK shape, user_version=5 — the shape just
+    // before v6.
+    ensureHome();
+    const raw = new DatabaseSync(canvasDbPath());
+    raw.exec(`
+    CREATE TABLE nodes (
+      node_id TEXT PRIMARY KEY, name TEXT NOT NULL, kind TEXT NOT NULL,
+      mode TEXT NOT NULL DEFAULT 'base', lifecycle TEXT NOT NULL DEFAULT 'terminal',
+      status TEXT NOT NULL DEFAULT 'active', cwd TEXT NOT NULL, parent TEXT,
+      created TEXT NOT NULL,
+      intent TEXT, pi_pid INTEGER, window TEXT, tmux_session TEXT, pane TEXT
+    );
+    CREATE TABLE edges (
+      type TEXT NOT NULL, from_id TEXT NOT NULL, to_id TEXT NOT NULL,
+      active INTEGER NOT NULL DEFAULT 1, created TEXT NOT NULL,
+      PRIMARY KEY (type, from_id, to_id),
+      FOREIGN KEY (from_id) REFERENCES nodes(node_id) ON DELETE CASCADE,
+      FOREIGN KEY (to_id)   REFERENCES nodes(node_id) ON DELETE CASCADE
+    );
+    PRAGMA user_version = 5;
+  `);
+    raw
+        .prepare('INSERT INTO nodes (node_id, name, kind, status, cwd, created, window, tmux_session, pane) VALUES (?,?,?,?,?,?,?,?,?)')
+        .run('legacy', 'Legacy', 'general', 'idle', '/tmp/work', '2020-01-01T00:00:00Z', '@9', 'crtr', '%3');
+    assert.equal(userVersion(raw), 5);
+    assert.ok(!tableNames(raw).includes('focuses'), 'precondition: no focuses table at v5');
+    raw.close();
+    // openDb() runs v6 forward.
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    assert.ok(tableNames(db).includes('focuses'), 'focuses table added by v6');
+    // The pre-existing node row is intact (the v6 migration only adds a table).
+    const row = db
+        .prepare('SELECT status, window, tmux_session, pane FROM nodes WHERE node_id = ?')
+        .get('legacy');
+    assert.equal(row['status'], 'idle', 'existing status untouched');
+    assert.equal(row['window'], '@9', 'existing window untouched');
+    assert.equal(row['tmux_session'], 'crtr', 'existing session untouched');
+    assert.equal(row['pane'], '%3', 'existing pane untouched');
+    // The fresh focuses table is empty.
+    const n = db.prepare('SELECT COUNT(*) AS n FROM focuses').get().n;
+    assert.equal(n, 0, 'a fresh focuses table starts empty');
+});
+test('the v6 migration is idempotent / forward-only on re-run and re-open', () => {
+    const db = openDb();
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    // Re-running migrate() is a no-op — the gate skips applied steps. The CREATE
+    // TABLE IF NOT EXISTS would be harmless anyway, but the gate must not re-fire.
+    assert.doesNotThrow(() => migrate(db));
+    assert.equal(userVersion(db), MIGRATIONS.length);
+    // Re-opening from disk is likewise a no-op.
+    closeDb();
+    const db2 = openDb();
+    assert.equal(userVersion(db2), MIGRATIONS.length);
+    assert.ok(tableNames(db2).includes('focuses'));
+});
+// ---------------------------------------------------------------------------
+// Canvas setters / reads — open / setOccupant / setPane / close round-trip.
+// ---------------------------------------------------------------------------
+test('open / setOccupant / close round-trip with the reads', () => {
+    openDb();
+    openFocusRow('f1', '%a', 'Sa', 'A');
+    // getFocusByNode / getFocusByPane / getFocusById all resolve the same row.
+    const byNode = getFocusByNode('A');
+    assert.deepEqual(byNode, { focus_id: 'f1', pane: '%a', session: 'Sa', node_id: 'A' });
+    assert.deepEqual(getFocusByPane('%a'), byNode);
+    assert.deepEqual(getFocusById('f1'), byNode);
+    assert.deepEqual(listFocuses(), [byNode]);
+    // setFocusOccupant hot-swaps the occupant in place (same focus_id/pane).
+    setFocusOccupant('f1', 'B');
+    assert.equal(getFocusByNode('A'), null, 'A no longer occupies the focus');
+    assert.deepEqual(getFocusByNode('B'), { focus_id: 'f1', pane: '%a', session: 'Sa', node_id: 'B' });
+    // setFocusPane re-points the pane + session cache (reconcileFocus, Step 6).
+    setFocusPane('f1', '%a2', 'Sa2');
+    assert.deepEqual(getFocusById('f1'), { focus_id: 'f1', pane: '%a2', session: 'Sa2', node_id: 'B' });
+    assert.equal(getFocusByPane('%a'), null, 'the old pane no longer resolves');
+    assert.deepEqual(getFocusByPane('%a2')?.node_id, 'B');
+    // closeFocusRow deletes the viewport.
+    closeFocusRow('f1');
+    assert.equal(getFocusByNode('B'), null);
+    assert.equal(getFocusById('f1'), null);
+    assert.deepEqual(listFocuses(), []);
+});
+test('UNIQUE(node_id): a second focus row for the same node is rejected', () => {
+    openDb();
+    openFocusRow('f1', '%a', 'Sa', 'A');
+    // A second viewport occupied by the SAME node violates UNIQUE(node_id) — this
+    // is the constraint that upholds "a node occupies <=1 focus" (Q5).
+    assert.throws(() => openFocusRow('f2', '%b', 'Sb', 'A'), /UNIQUE|constraint/i);
+    // The first row is untouched; no stray second row was created.
+    assert.deepEqual(listFocuses().map((f) => f.focus_id), ['f1']);
+});
+test('UNIQUE(node_id): hot-swapping an occupant onto an already-focused node is rejected', () => {
+    openDb();
+    openFocusRow('f1', '%a', 'Sa', 'A');
+    openFocusRow('f2', '%b', 'Sb', 'B');
+    // B already occupies f2 — moving it onto f1 via setFocusOccupant must throw
+    // (the Q5 vacate-first is retargetFocus's job, Step 6, not this setter's).
+    assert.throws(() => setFocusOccupant('f1', 'B'), /UNIQUE|constraint/i);
+    assert.deepEqual(getFocusByNode('A'), { focus_id: 'f1', pane: '%a', session: 'Sa', node_id: 'A' });
+    assert.deepEqual(getFocusByNode('B'), { focus_id: 'f2', pane: '%b', session: 'Sb', node_id: 'B' });
+});
+test('independent focus rows do not contend', () => {
+    openDb();
+    openFocusRow('f1', '%a', 'Sa', 'A');
+    openFocusRow('f2', '%b', 'Sb', 'B');
+    // Mutating one viewport leaves the other entirely intact.
+    setFocusOccupant('f1', 'C');
+    setFocusPane('f1', '%a2', 'Sa2');
+    assert.deepEqual(getFocusByNode('B'), { focus_id: 'f2', pane: '%b', session: 'Sb', node_id: 'B' });
+    closeFocusRow('f1');
+    assert.deepEqual(getFocusByNode('B'), { focus_id: 'f2', pane: '%b', session: 'Sb', node_id: 'B' });
+    assert.deepEqual(listFocuses().map((f) => f.focus_id), ['f2']);
+});
+// ---------------------------------------------------------------------------
+// Placement reads — focusOf / isFocused / focusByPane / focusedNodes / listFocuses
+// agree with the rows.
+// ---------------------------------------------------------------------------
+test('placement focus reads agree with the focus rows', () => {
+    openDb();
+    openFocusRow('f1', '%a', 'Sa', 'A');
+    openFocusRow('f2', '%b', 'Sb', 'B');
+    assert.deepEqual(focusOf('A'), { focus_id: 'f1', pane: '%a', session: 'Sa', node_id: 'A' });
+    assert.equal(focusOf('Z'), null, 'an unfocused node has no focus');
+    assert.equal(isFocused('A'), true);
+    assert.equal(isFocused('Z'), false);
+    assert.deepEqual(focusByPane('%b'), { focus_id: 'f2', pane: '%b', session: 'Sb', node_id: 'B' });
+    assert.deepEqual(focusedNodes(), new Set(['A', 'B']));
+    assert.deepEqual(placementListFocuses().map((f) => f.node_id), ['A', 'B']);
+});
+// ---------------------------------------------------------------------------
+// Dual-write bridge — setFocus populates the table; getFocus falls back to the
+// table when focus.ptr is absent; setFocus('') clears both.
+// ---------------------------------------------------------------------------
+function focusPtrPath() {
+    return join(crtrHome(), 'focus.ptr');
+}
+test('setFocus populates the focuses table in lockstep with focus.ptr', () => {
+    openDb();
+    setFocus('A');
+    assert.equal(getFocus(), 'A', 'focus.ptr reads back');
+    const row = getFocusByNode('A');
+    assert.ok(row, 'a canonical focus row mirrors the current focus');
+    assert.equal(row?.node_id, 'A');
+    assert.equal(isFocused('A'), true, 'placement.isFocused agrees');
+    assert.deepEqual(focusOf('A')?.node_id, 'A', 'placement.focusOf agrees with getFocus');
+    // Re-focusing a different node re-points the SAME canonical row (no stray rows,
+    // UNIQUE(node_id) upheld).
+    setFocus('B');
+    assert.equal(getFocus(), 'B');
+    assert.equal(getFocusByNode('A'), null, 'the old occupant is dropped');
+    assert.equal(getFocusByNode('B')?.node_id, 'B');
+    assert.equal(listFocuses().length, 1, 'still exactly one canonical row');
+});
+test('getFocus falls back to the table when focus.ptr is absent', () => {
+    openDb();
+    setFocus('A'); // writes both focus.ptr and the canonical row
+    // Simulate a missing pointer (a writer that reached only the table, or a lost
+    // file): delete focus.ptr and confirm getFocus recovers the focus from the row.
+    if (existsSync(focusPtrPath()))
+        unlinkSync(focusPtrPath());
+    assert.equal(getFocus(), 'A', 'getFocus recovers the focus from the table');
+});
+test("setFocus('') clears both the pointer and the canonical focus row", () => {
+    openDb();
+    setFocus('A');
+    assert.equal(getFocus(), 'A');
+    assert.ok(getFocusByNode('A'), 'precondition: row present');
+    setFocus('');
+    assert.equal(getFocus(), null, 'getFocus is null after clear (ptr empty, no row)');
+    assert.equal(getFocusByNode('A'), null, 'the canonical row was closed');
+    assert.deepEqual(listFocuses(), [], 'no focus rows remain');
+});
+test('a focus row written directly (no focus.ptr) is visible through getFocus + placement', () => {
+    openDb();
+    // A writer that reached only the table (the canonical bridge row), with no
+    // focus.ptr on disk at all.
+    openFocusRow('__focus_ptr__', null, null, 'X');
+    assert.ok(!existsSync(focusPtrPath()), 'precondition: no focus.ptr file');
+    assert.equal(getFocus(), 'X', 'getFocus falls back to the canonical row');
+    assert.equal(isFocused('X'), true);
+});

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

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

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

@@ -0,0 +1,91 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/fork.test.ts
+//
+// Covers `crtr node new --fork-from`: the spawn-time branch where a new node is
+// born as a COPY of an existing pi conversation. Two pure layers are unit-tested
+// here — `buildPiArgv` emitting `--fork` (vs `--session`), and `resolveForkSource`
+// turning a node id / path / uuid into the `--fork <path|id>` argument. The tmux
+// spawn itself is exercised elsewhere (it needs a live pi + tmux).
+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 } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { buildPiArgv } from '../runtime/launch.js';
+import { resolveForkSource } from '../runtime/spawn.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,
+    };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-fork-'));
+    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'];
+});
+// ---------------------------------------------------------------------------
+// buildPiArgv — `--fork` is the spawn-time branch (not `--session`)
+// ---------------------------------------------------------------------------
+test('buildPiArgv emits --fork <src> and delivers the kickoff prompt', () => {
+    const m = node('n');
+    const { argv } = buildPiArgv(m, { prompt: 'continue from here', forkFrom: '/abs/src.jsonl' });
+    const i = argv.indexOf('--fork');
+    assert.ok(i >= 0, 'argv carries --fork');
+    assert.equal(argv[i + 1], '/abs/src.jsonl', 'forks from the resolved source');
+    assert.ok(!argv.includes('--session'), 'a fork never also resumes');
+    assert.equal(argv[argv.length - 1], 'continue from here', 'the kickoff prompt is the last positional');
+});
+test('buildPiArgv prefers --fork over --session when both are somehow set', () => {
+    const m = node('n');
+    const { argv } = buildPiArgv(m, { forkFrom: '/abs/src.jsonl', resumeSessionPath: '/abs/own.jsonl' });
+    assert.ok(argv.includes('--fork'), 'fork wins');
+    assert.ok(!argv.includes('--session'), 'resume is suppressed when forking');
+});
+test('buildPiArgv without forkFrom is unchanged (fresh launch, no --fork)', () => {
+    const m = node('n');
+    const { argv } = buildPiArgv(m, { prompt: 'go' });
+    assert.ok(!argv.includes('--fork'), 'no fork on an ordinary fresh launch');
+    assert.ok(!argv.includes('--session'), 'no resume either');
+});
+// ---------------------------------------------------------------------------
+// resolveForkSource — node id / path / uuid → the `--fork` argument
+// ---------------------------------------------------------------------------
+test('resolveForkSource resolves a node id to its absolute session FILE', () => {
+    createNode(node('src', { pi_session_id: 'uuid-1', pi_session_file: '/abs/src.jsonl' }));
+    assert.equal(resolveForkSource('src'), '/abs/src.jsonl');
+});
+test('resolveForkSource falls back to the bare session id when no file captured', () => {
+    createNode(node('src', { pi_session_id: 'uuid-1' }));
+    assert.equal(resolveForkSource('src'), 'uuid-1');
+});
+test('resolveForkSource throws when the node has no pi session to fork yet', () => {
+    createNode(node('fresh'));
+    assert.throws(() => resolveForkSource('fresh'), /no pi session yet/);
+});
+test('resolveForkSource passes a path straight through', () => {
+    assert.equal(resolveForkSource('/some/where/sess.jsonl'), '/some/where/sess.jsonl');
+});
+test('resolveForkSource passes an unknown bare/partial uuid through to pi', () => {
+    assert.equal(resolveForkSource('019e8ce3-322e'), '019e8ce3-322e');
+});
+test('resolveForkSource rejects an empty reference', () => {
+    assert.throws(() => resolveForkSource('   '), /requires a node id/);
+});

package/dist/core/__tests__/home-session.test.d.ts

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

package/dist/core/__tests__/home-session.test.js

@@ -0,0 +1,153 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/home-session.test.ts
+//
+// STEP 1 of the placement/focus migration: the durable REVIVE-HOME field.
+// `home_session` separates a node's revive target from its live LOCATION so a
+// later step can kill the focus taint. This step only ADDS + POPULATES +
+// DEFAULTS the field — no behavior change. Covers:
+//   - home_session round-trips through meta.json (it IS durable identity)
+//   - the birth-session decision (`resolveBirthSession`) for the child /
+//     inline-root / --root cases each site sets home_session from
+//   - demote-recycle + relaunch (pane-recycle) births populate home_session
+//   - a legacy meta with NO home_session defaults to tmux_session ?? nodeSession()
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, getNode, updateNode } from '../canvas/canvas.js';
+import { nodeMetaPath } from '../canvas/paths.js';
+import { closeDb } from '../canvas/db.js';
+import { resolveBirthSession, homeSessionOf } from '../runtime/nodes.js';
+import { nodeSession } from '../runtime/tmux.js';
+import { relaunchRoot } from '../runtime/reset.js';
+import { demoteNode } from '../runtime/demote.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: 'resident',
+        status: 'active',
+        ...over,
+    };
+}
+/** Make ensureDaemon (called by demoteNode) a no-op by faking a live daemon
+ *  pidfile pointing at THIS test process — so no real daemon is ever spawned. */
+function fakeLiveDaemon() {
+    writeFileSync(join(home, 'crtrd.pid'), String(process.pid), 'utf8');
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-homesession-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_ROOT_SESSION'];
+    delete process.env['CRTR_NODE_SESSION'];
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+    delete process.env['CRTR_ROOT_SESSION'];
+    delete process.env['CRTR_NODE_SESSION'];
+});
+// ---------------------------------------------------------------------------
+// Persistence: home_session is DURABLE IDENTITY (meta.json), round-tripped by
+// createNode / getNode / updateNode — and NOT a runtime field.
+// ---------------------------------------------------------------------------
+test('home_session round-trips through meta.json and the hydrated view', () => {
+    createNode(node('n', { home_session: 'crtr', tmux_session: 'user-sess', window: '@1' }));
+    // On disk: meta.json carries home_session (identity), NOT the runtime LOCATION.
+    const raw = JSON.parse(readFileSync(nodeMetaPath('n'), 'utf8'));
+    assert.equal(raw['home_session'], 'crtr', 'home_session persisted to meta.json (durable identity)');
+    assert.ok(!('tmux_session' in raw), 'tmux_session stays a runtime field, not in meta.json');
+    // Hydrated view returns it; the live LOCATION is independent.
+    const m = getNode('n');
+    assert.equal(m?.home_session, 'crtr', 'getNode hydrates home_session');
+    assert.equal(m?.tmux_session, 'user-sess', 'home_session is distinct from the live LOCATION');
+});
+test('updateNode patches home_session (the demote rewriter path) and preserves it', () => {
+    createNode(node('n', { home_session: 'crtr' }));
+    updateNode('n', { home_session: 'recycled-sess' });
+    assert.equal(getNode('n')?.home_session, 'recycled-sess', 'home_session rewritten by updateNode');
+    // An unrelated identity patch leaves home_session intact (RMW round-trip).
+    updateNode('n', { description: 'a-handle' });
+    assert.equal(getNode('n')?.home_session, 'recycled-sess', 'home_session survives an unrelated identity edit');
+});
+// ---------------------------------------------------------------------------
+// The legacy / back-compat DEFAULT: a meta with no home_session reads back
+// tmux_session ?? nodeSession().
+// ---------------------------------------------------------------------------
+test('homeSessionOf: a present home_session is returned verbatim', () => {
+    createNode(node('n', { home_session: 'home-sess', tmux_session: 'live-sess' }));
+    assert.equal(homeSessionOf('n'), 'home-sess', 'the stored revive-home wins over the live LOCATION');
+});
+test('homeSessionOf: legacy meta (no home_session) defaults to tmux_session', () => {
+    createNode(node('legacy', { tmux_session: 'live-sess' }));
+    assert.equal(getNode('legacy')?.home_session, undefined, 'no home_session on a legacy node');
+    assert.equal(homeSessionOf('legacy'), 'live-sess', 'defaults to the last live LOCATION');
+});
+test('homeSessionOf: legacy meta with no LOCATION either defaults to nodeSession()', () => {
+    createNode(node('legacy', { tmux_session: null }));
+    assert.equal(homeSessionOf('legacy'), nodeSession(), 'falls through to the shared backstage');
+});
+test('homeSessionOf: the backstage default honors CRTR_NODE_SESSION', () => {
+    process.env['CRTR_NODE_SESSION'] = 'my-backstage';
+    createNode(node('legacy'));
+    assert.equal(homeSessionOf('legacy'), 'my-backstage', 'nodeSession() default is env-overridable');
+});
+test('homeSessionOf: unknown node falls back to the backstage', () => {
+    assert.equal(homeSessionOf('ghost'), nodeSession());
+});
+// ---------------------------------------------------------------------------
+// The birth-session decision each site sets home_session from. Pure, so the
+// child / inline-root / --root births are testable without a live tmux (the
+// real spawnChild/bootRoot are tmux + pi + process.exit coupled).
+// ---------------------------------------------------------------------------
+test('birth: a managed child homes to the shared backstage (nodeSession), never a user session', () => {
+    // No CRTR_ROOT_SESSION inherited, not adopting the caller.
+    assert.equal(resolveBirthSession({ adoptCaller: false, here: { session: 'user-sess' }, rootSession: undefined }), nodeSession(), 'a child ignores the caller session and homes to crtr');
+});
+test('birth: a managed child inherits CRTR_ROOT_SESSION as its backstage', () => {
+    assert.equal(resolveBirthSession({ adoptCaller: false, here: null, rootSession: 'crtr-subtree' }), 'crtr-subtree', 'the inherited root session is the child backstage');
+});
+test('birth: an independent --root inside tmux homes to the caller current session', () => {
+    assert.equal(resolveBirthSession({ adoptCaller: true, here: { session: 'user-sess' }, rootSession: 'crtr' }), 'user-sess', 'a --root adopts the caller session where the spawner is working');
+});
+test('birth: a --root NOT inside tmux falls back to the backstage', () => {
+    assert.equal(resolveBirthSession({ adoptCaller: true, here: null, rootSession: undefined }), nodeSession(), 'no caller session → the backstage');
+});
+test('birth: the inline front door (bootRoot) homes to its adopted session', () => {
+    // bootRoot adopts the caller session when inside tmux, else nodeSession().
+    assert.equal(resolveBirthSession({ adoptCaller: true, here: { session: 'term-sess' }, rootSession: undefined }), 'term-sess', 'inline root adopts the terminal it took over');
+    assert.equal(resolveBirthSession({ adoptCaller: true, here: null, rootSession: undefined }), nodeSession(), 'inline root with no tmux homes to the backstage');
+});
+// ---------------------------------------------------------------------------
+// Pane-recycle births populate home_session. relaunchRoot (option C) is fully
+// unit-testable (injected respawn, no tmux); demoteNode runs to completion with
+// no tmux (respawn dispatch just fails) once the daemon spawn is neutralized.
+// ---------------------------------------------------------------------------
+test('relaunch birth: the fresh root homes to the recycled pane session', () => {
+    createNode(node('root', { parent: null, lifecycle: 'resident', tmux_session: 'crtr', window: '@7' }));
+    // No live tmux → paneLocation(pane) is null → loc falls back to the old root's
+    // tmux_session ('crtr'); home_session must adopt it.
+    const res = relaunchRoot('root', 'test-pane', { relaunchRootInPane: () => { } });
+    assert.ok(res !== null, 'relaunchRoot minted a fresh root');
+    assert.equal(getNode(res.newNodeId)?.home_session, 'crtr', 'fresh root homes to the recycled pane session');
+});
+test('demote birth: the recycled root populates home_session (backstage when no pane location)', async () => {
+    createNode(node('M', { parent: null, lifecycle: 'resident', tmux_session: 'crtr', window: '@3' }));
+    fakeLiveDaemon(); // createNode ensured the home dir; now neutralize ensureDaemon
+    // No live tmux → paneLocation('%0') is null → home_session defaults to the
+    // backstage. The respawn dispatch fails (no tmux), but the fresh root is still
+    // born — and must carry a populated home_session.
+    const res = await demoteNode('M', '%0');
+    assert.ok(res.newRoot !== null, 'demote minted a fresh root');
+    assert.equal(getNode(res.newRoot)?.home_session, nodeSession(), 'recycled root homes to the backstage');
+});

package/dist/core/__tests__/human-cancel-guard.test.d.ts

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

package/dist/core/__tests__/human-cancel-guard.test.js

@@ -0,0 +1,49 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/human-cancel-guard.test.ts
+//
+// N2 — humanCancel on an already-canceled (but unresolved) interaction node must
+// short-circuit to {canceled:false, reason:'already_resolved'} instead of falling
+// through to transition('finalize'), which is illegal from status='canceled' and
+// would throw. Guards the one-line hardening in queue.ts's status guard.
+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 { humanCancel } from '../../commands/human/queue.js';
+let home;
+function node(id) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+    };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-humancancel-'));
+    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('cancel on an already-canceled node is a no-op, never throws on the finalize', async () => {
+    const id = 'canceledJob';
+    createNode(node(id));
+    setStatus(id, 'canceled'); // canceled but no response.json written yet
+    const res = (await humanCancel.run({ job_id: id }));
+    assert.equal(res['canceled'], false);
+    assert.equal(res['reason'], 'already_resolved');
+    assert.equal(res['job_id'], id);
+});

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

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