@crouton-kit/crouter 0.3.14 → 0.3.15

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

@@ -0,0 +1,107 @@
+// Run: node --import tsx/esm --test src/core/__tests__/persona.test.ts
+//
+// The persona-transition mechanism: the two-axis model (mode × lifecycle) is
+// switchable independently, and `personaDrift` detects when a node's live
+// {mode,lifecycle} has diverged from the `persona_ack` it was last given
+// guidance for (the central injector then delivers + commits).
+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 { spawnNode } from '../runtime/nodes.js';
+import { promote } from '../runtime/promote.js';
+import { getNode, updateNode } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { personaDrift, commitPersonaAck, transitionGuidance, } from '../runtime/persona.js';
+let home;
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-persona-'));
+    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'];
+});
+// ---------------------------------------------------------------------------
+// Birth: a fresh node is born acked to its own persona — no spurious drift.
+// ---------------------------------------------------------------------------
+test('a freshly spawned node has no persona drift (born acked to its own persona)', () => {
+    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null, lifecycle: 'terminal' });
+    assert.deepEqual(meta.persona_ack, { mode: 'base', lifecycle: 'terminal' });
+    assert.equal(personaDrift(meta.node_id), null, 'no drift at birth');
+});
+// ---------------------------------------------------------------------------
+// Fix 1: promote keeps lifecycle by default; --resident flips it.
+// ---------------------------------------------------------------------------
+test('promote flips mode→orchestrator and KEEPS lifecycle terminal by default', () => {
+    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null, lifecycle: 'terminal' });
+    const res = promote(meta.node_id);
+    assert.equal(res.meta.mode, 'orchestrator');
+    assert.equal(res.meta.lifecycle, 'terminal', 'lifecycle is NOT forced to resident');
+});
+test('promote with resident:true ALSO flips lifecycle→resident', () => {
+    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null, lifecycle: 'terminal' });
+    const res = promote(meta.node_id, { resident: true });
+    assert.equal(res.meta.mode, 'orchestrator');
+    assert.equal(res.meta.lifecycle, 'resident', 'resident flag flips lifecycle');
+});
+test('promote no longer returns a guidance field (injector is the single source)', () => {
+    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null, lifecycle: 'terminal' });
+    const res = promote(meta.node_id);
+    assert.equal('guidance' in res, false, 'promote() returns facts only');
+});
+// ---------------------------------------------------------------------------
+// personaDrift detect + commit.
+// ---------------------------------------------------------------------------
+test('personaDrift detects base→orchestrator after promote, then clears on commit', () => {
+    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null, lifecycle: 'terminal' });
+    promote(meta.node_id); // mode→orchestrator, lifecycle stays terminal
+    const drift = personaDrift(meta.node_id);
+    assert.ok(drift !== null, 'a transition is detected');
+    assert.deepEqual(drift?.from, { mode: 'base', lifecycle: 'terminal' });
+    assert.deepEqual(drift?.to, { mode: 'orchestrator', lifecycle: 'terminal' });
+    assert.ok((drift?.guidance ?? '').length > 0, 'guidance is built');
+    // Caller commits the ack after delivery — drift then clears (idempotent).
+    commitPersonaAck(meta.node_id, drift.to);
+    assert.equal(personaDrift(meta.node_id), null, 'no drift after the ack is committed');
+    assert.deepEqual(getNode(meta.node_id)?.persona_ack, { mode: 'orchestrator', lifecycle: 'terminal' });
+});
+test('personaDrift detects a lifecycle-only flip (terminal→resident)', () => {
+    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null, lifecycle: 'terminal' });
+    // Flip only the lifecycle axis — mode unchanged.
+    updateNode(meta.node_id, { lifecycle: 'resident' });
+    const drift = personaDrift(meta.node_id);
+    assert.ok(drift !== null);
+    assert.deepEqual(drift?.from, { mode: 'base', lifecycle: 'terminal' });
+    assert.deepEqual(drift?.to, { mode: 'base', lifecycle: 'resident' });
+    assert.match(drift?.guidance ?? '', /resident/i, 'guidance describes the resident state');
+});
+// ---------------------------------------------------------------------------
+// transitionGuidance: each lifecycle case + both-axes concatenation.
+// ---------------------------------------------------------------------------
+test('transitionGuidance terminal→resident says it is never forced to submit a final', () => {
+    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null, lifecycle: 'terminal' });
+    const g = transitionGuidance(meta.node_id, { mode: 'base', lifecycle: 'terminal' }, { mode: 'base', lifecycle: 'resident' });
+    assert.match(g, /resident/i);
+    assert.match(g, /never/i);
+    assert.doesNotMatch(g, /orchestrator/i, 'a lifecycle-only change carries no mode section');
+});
+test('transitionGuidance resident→terminal says it owes a final up the spine', () => {
+    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null, lifecycle: 'resident' });
+    const g = transitionGuidance(meta.node_id, { mode: 'base', lifecycle: 'resident' }, { mode: 'base', lifecycle: 'terminal' });
+    assert.match(g, /terminal/i);
+    assert.match(g, /push final/i);
+});
+test('transitionGuidance concatenates BOTH sections when both axes change', () => {
+    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null, lifecycle: 'terminal' });
+    promote(meta.node_id); // ensure roadmap/memory seeded for the orchestrator section
+    const g = transitionGuidance(meta.node_id, { mode: 'base', lifecycle: 'terminal' }, { mode: 'orchestrator', lifecycle: 'resident' });
+    assert.match(g, /orchestrator/i, 'carries the mode (base→orchestrator) section');
+    assert.match(g, /resident/i, 'carries the lifecycle (terminal→resident) section');
+});

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

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

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

@@ -0,0 +1,244 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/placement-focus.test.ts
+//
+// STEP 6 of the placement/focus migration: retargetFocus / openFocus / focus +
+// remain-on-exit + root-boot focus #1 + the focus.ptr bridge staying consistent.
+//
+// Two proof tiers (mirrors placement-revive.test.ts):
+//   1. PURE (no tmux): outgoingDisposition (backstage-vs-kill) and the focus.ptr
+//      dual-write bridge piggybacking on a real focus row WITHOUT clobbering it
+//      (the Step-6 bridge fix). Each is provably non-vacuous (a wrong impl fails).
+//   2. Gated real-tmux: the hot-swap itself — screen position invariant (ZERO new
+//      user windows), the two post-swap LOCATIONs, outgoing backstaged (still
+//      generating) vs reaped (dormant), the Q5 vacate-old-focus path, openFocus
+//      splitting a holder viewport, and the front-door round-trip with UNIQUE
+//      node_id upheld. The swap is a real tmux op, so a faithful assertion needs
+//      a live server; gated {skip:!hasTmux()} like §5.2.
+import { test, before, after, beforeEach } 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 { spawnSync } from 'node:child_process';
+import { createNode, getNode, setPresence } from '../canvas/canvas.js';
+import { openFocusRow, getFocusByNode, getFocusById, listFocuses, } from '../canvas/focuses.js';
+import { closeDb } from '../canvas/db.js';
+import { crtrHome } from '../canvas/paths.js';
+import { outgoingDisposition, retargetFocus, openFocus, focus as placementFocus, registerRootFocus, focusByPane, } from '../runtime/placement.js';
+import { setFocus, getFocus } from '../runtime/presence.js';
+let home;
+let savedTmux;
+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-placement-focus-'));
+    process.env['CRTR_HOME'] = home;
+    savedTmux = process.env['TMUX'];
+    delete process.env['TMUX']; // pure tests exercise the deterministic no-tmux path
+});
+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;
+});
+// ---------------------------------------------------------------------------
+// 1a. PURE: outgoingDisposition — backstage (still generating) vs kill.
+// ---------------------------------------------------------------------------
+test('outgoingDisposition: a still-generating node → BACKSTAGE (F2: keeps running off-screen)', () => {
+    assert.deepEqual(outgoingDisposition({ exists: true, generating: true }), { kind: 'backstage' });
+});
+test('outgoingDisposition: a dormant/done node → KILL (Invariant P: not-focused + not-generating ⇒ no pane)', () => {
+    assert.deepEqual(outgoingDisposition({ exists: true, generating: false }), { kind: 'kill' });
+});
+test('outgoingDisposition: a HOLDER / vanished node (no row) → KILL (never backstaged)', () => {
+    // A wrong impl that backstaged a holder would leak a sleep pane into crtr.
+    assert.deepEqual(outgoingDisposition({ exists: false, generating: true }), { kind: 'kill' });
+    assert.deepEqual(outgoingDisposition({ exists: false, generating: false }), { kind: 'kill' });
+});
+// ---------------------------------------------------------------------------
+// 1b. PURE: the focus.ptr dual-write bridge PIGGYBACKS on a real focus row
+// (Step-6 fix) — setFocus must NOT clobber the pane-correct row retargetFocus
+// wrote. The OLD bridge closed `existing` unconditionally, replacing the real
+// row with a `__focus_ptr__` row; asserting the focus_id survives fails it.
+// ---------------------------------------------------------------------------
+test('focus.ptr bridge: setFocus piggybacks on a REAL focus row (never clobbers it)', () => {
+    // Simulate a real row written by retargetFocus/openFocus (a non-bridge id).
+    openFocusRow('real-f', '%a', 'Suser', 'A');
+    setFocus('A'); // the consistency mirror retargetFocus calls at the end
+    assert.equal(getFocus(), 'A', 'focus.ptr names the node');
+    const row = getFocusByNode('A');
+    assert.ok(row, 'A still occupies a focus');
+    assert.equal(row?.focus_id, 'real-f', 'the REAL row survived (not replaced by a bridge row)');
+    assert.equal(row?.pane, '%a', 'the pane-correct row is intact');
+    assert.equal(listFocuses().length, 1, 'no duplicate bridge row was inserted (UNIQUE node_id)');
+});
+test('focus.ptr bridge: a plain setFocus (no real row) still creates the bridge row + getFocus reads it', () => {
+    setFocus('Z');
+    if (existsSync(join(crtrHome(), 'focus.ptr')))
+        unlinkSync(join(crtrHome(), 'focus.ptr'));
+    assert.equal(getFocus(), 'Z', 'getFocus falls back to the canonical bridge row when the ptr is gone');
+});
+// ---------------------------------------------------------------------------
+// 2. Gated real-tmux: the hot-swap. Two isolated sessions: `user` (the user's
+// terminal) + `back` (stand-in for the backstage `crtr`). Panes run `sleep`,
+// never a real pi; node pi_pid is set explicitly to control "generating".
+// ---------------------------------------------------------------------------
+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 !== '');
+}
+function paneExistsReal(pane) {
+    return tmuxOut(['display-message', '-p', '-t', pane, '#{pane_id}']) === pane;
+}
+function paneSession(pane) {
+    return tmuxOut(['display-message', '-p', '-t', pane, '#{session_name}']);
+}
+/** A live extra pane in `session:window` running sleep; returns its `%pane_id`. */
+function livePane(session, window) {
+    return tmuxOut(['split-window', '-d', '-P', '-F', '#{pane_id}', '-t', `${session}:${window}`, 'sleep 600']);
+}
+const NOREVIVE = () => {
+    throw new Error('reviver should not be called when the node has a live pin pane');
+};
+/** A reviver that opens a real backstage `sleep` window for the node and points
+ *  its presence at it — the stand-in for reviveIntoPlacement's backstage branch. */
+function backstageReviver(back) {
+    return (id) => {
+        const out = tmuxOut(['new-window', '-d', '-a', '-P', '-F', '#{window_id}\t#{pane_id}', '-t', `${back}:`, 'sleep 600']);
+        const [w, p] = out.split('\t');
+        setPresence(id, { pane: p, tmux_session: back, window: w });
+    };
+}
+async function withSessions(tag, fn) {
+    const user = `crtr-pf-user-${process.pid}-${tag}`;
+    const back = `crtr-pf-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 {
+        await fn({ user, back, userWindow: windowIds(user)[0], backWindow: windowIds(back)[0] });
+    }
+    finally {
+        spawnSync('tmux', ['kill-session', '-t', user], { stdio: 'ignore' });
+        spawnSync('tmux', ['kill-session', '-t', back], { stdio: 'ignore' });
+    }
+}
+test('retargetFocus: outgoing GENERATING → backstaged; the viewport stays put (ZERO new user windows)', { skip: !hasTmux() }, async () => {
+    await withSessions('gen', async ({ user, back, userWindow, backWindow }) => {
+        const focusPane = livePane(user, userWindow); // R's focus pane (the viewport)
+        const backPane = livePane(back, backWindow); // A's live backstage pane
+        // R is the outgoing occupant, generating (a live pi_pid). A is incoming.
+        createNode(node('R', { pane: focusPane, tmux_session: user, window: userWindow, status: 'active', pi_pid: process.pid, home_session: back }));
+        createNode(node('A', { pane: backPane, tmux_session: back, window: backWindow, status: 'active', pi_pid: process.pid, home_session: back }));
+        openFocusRow('f1', focusPane, user, 'R');
+        const userBefore = windowIds(user).length;
+        const res = retargetFocus('f1', 'A', NOREVIVE);
+        assert.equal(res.focused, true);
+        assert.equal(res.revived, false, 'A had a live pin pane — no revive');
+        assert.equal(windowIds(user).length, userBefore, 'ZERO new windows in the user session (screen position invariant)');
+        // A took over the viewport: it keeps its pane id, now in the user session.
+        assert.equal(getFocusByNode('A')?.focus_id, 'f1', 'A now occupies the focus');
+        assert.equal(getFocusByNode('A')?.pane, backPane, 'the focus row anchors A\'s (now-in-viewport) pane');
+        assert.equal(getNode('A').pane, backPane, 'A\'s LOCATION pane id is unchanged (swap preserves %id)');
+        assert.equal(paneSession(backPane), user, 'A\'s pane physically moved to the user viewport');
+        assert.equal(getNode('A').tmux_session, user, 'A\'s LOCATION session is the viewport');
+        // R was backstaged (still generating), keeping its pane id, now in `back`.
+        assert.equal(getFocusByNode('R'), null, 'R no longer occupies any focus');
+        assert.equal(getNode('R').pane, focusPane, 'R kept its pane id');
+        assert.equal(paneExistsReal(focusPane), true, 'R\'s pane is alive (NOT reaped — it is still generating)');
+        assert.equal(paneSession(focusPane), back, 'R\'s pane physically moved to the backstage');
+        assert.equal(getNode('R').tmux_session, back, 'R\'s LOCATION session is the backstage');
+        assert.equal(getFocus(), 'A', 'focus.ptr followed the retarget');
+    });
+});
+test('retargetFocus: outgoing DORMANT (no live pi) → its now-backstage pane is REAPED (Invariant P)', { skip: !hasTmux() }, async () => {
+    await withSessions('kill', async ({ user, back, userWindow, backWindow }) => {
+        const focusPane = livePane(user, userWindow);
+        const backPane = livePane(back, backWindow);
+        // R is NOT generating (pi_pid null) → its pane must be reaped after the swap.
+        createNode(node('R', { pane: focusPane, tmux_session: user, window: userWindow, status: 'active', pi_pid: null, home_session: back }));
+        createNode(node('A', { pane: backPane, tmux_session: back, window: backWindow, status: 'active', pi_pid: process.pid, home_session: back }));
+        openFocusRow('f1', focusPane, user, 'R');
+        retargetFocus('f1', 'A', NOREVIVE);
+        assert.equal(getFocusByNode('A')?.focus_id, 'f1', 'A took the viewport');
+        assert.equal(paneSession(backPane), user, 'A\'s pane is in the viewport');
+        assert.equal(paneExistsReal(focusPane), false, 'R\'s now-backstage pane was KILLED (dormant ⇒ no pane)');
+        assert.equal(getNode('R').pane, null, 'R\'s LOCATION was nulled (Invariant P)');
+        assert.equal(getNode('R').tmux_session, null);
+    });
+});
+test('retargetFocus Q5: focusing a node already focused ELSEWHERE vacates its old focus (it MOVES, no dup)', { skip: !hasTmux() }, async () => {
+    await withSessions('q5', async ({ user, back, userWindow, backWindow }) => {
+        // R sits in focus f1 (the user viewport). M is focused in f2 (a second pane).
+        const focusPane = livePane(user, userWindow);
+        const mPane = livePane(back, backWindow); // M's current focus pane (live)
+        createNode(node('R', { pane: focusPane, tmux_session: user, window: userWindow, status: 'active', pi_pid: process.pid, home_session: back }));
+        createNode(node('M', { pane: mPane, tmux_session: back, window: backWindow, status: 'active', pi_pid: process.pid, home_session: back }));
+        openFocusRow('f1', focusPane, user, 'R');
+        openFocusRow('f2', mPane, back, 'M');
+        // Focus M into f1 (the user viewport): M occupies f2 ≠ f1 → vacate f2.
+        const res = retargetFocus('f1', 'M', backstageReviver(back));
+        assert.equal(res.focused, true);
+        assert.equal(getFocusById('f2'), null, 'the OLD focus f2 was vacated (closed)');
+        assert.equal(paneExistsReal(mPane), false, 'M\'s old focus pane was killed (the node moved)');
+        const mFocus = getFocusByNode('M');
+        assert.equal(mFocus?.focus_id, 'f1', 'M now occupies ONLY f1 (UNIQUE node_id upheld)');
+        assert.equal(listFocuses().filter((f) => f.node_id === 'M').length, 1, 'exactly one focus shows M');
+        assert.equal(res.revived, true, 'M was revived into the backstage after its old pane was killed');
+    });
+});
+test('openFocus: splits a NEW viewport pane beside the caller (a holder row), NOT a new window', { skip: !hasTmux() }, async () => {
+    await withSessions('open', async ({ user, userWindow }) => {
+        const callerPane = tmuxOut(['display-message', '-p', '-t', `${user}:${userWindow}`, '#{pane_id}']);
+        const userWinBefore = windowIds(user).length;
+        const f = openFocus(callerPane, {});
+        assert.ok(f, 'openFocus returned a focus row');
+        assert.equal(windowIds(user).length, userWinBefore, 'a SPLIT, not a new window (Q3 side-by-side)');
+        assert.ok(f.pane?.startsWith('%'), 'the row anchors the new split pane');
+        assert.equal(paneExistsReal(f.pane), true, 'the holder pane is live');
+        assert.ok(f.node_id.startsWith('__hold_'), 'occupied by a holder until a node is retargeted in');
+        // remain-on-exit is armed on the viewport window (F3).
+        const win = tmuxOut(['display-message', '-p', '-t', f.pane, '#{window_id}']);
+        assert.equal(tmuxOut(['show-window-options', '-t', win, 'remain-on-exit']), 'remain-on-exit on', 'remain-on-exit armed (F3)');
+    });
+});
+test('focus front-door: round-trip open(register #1) → retarget in place → the focus follows the viewport', { skip: !hasTmux() }, async () => {
+    await withSessions('frontdoor', async ({ user, back, userWindow, backWindow }) => {
+        const rootPane = tmuxOut(['display-message', '-p', '-t', `${user}:${userWindow}`, '#{pane_id}']);
+        const aPane = livePane(back, backWindow);
+        createNode(node('R', { pane: rootPane, tmux_session: user, window: userWindow, status: 'active', pi_pid: process.pid, home_session: user }));
+        createNode(node('A', { pane: aPane, tmux_session: back, window: backWindow, status: 'active', pi_pid: process.pid, home_session: back }));
+        // Root boot registers focus #1 on the root's own pane.
+        const f1 = registerRootFocus('R', rootPane, user, userWindow);
+        assert.ok(f1, 'focus #1 registered');
+        assert.equal(focusByPane(rootPane)?.node_id, 'R');
+        // node focus A from the root's pane → retarget IN PLACE (same focus row).
+        const res = placementFocus('A', { pane: rootPane, callerNode: 'R', revive: NOREVIVE });
+        assert.equal(res.inPlace, true);
+        assert.equal(getFocusByNode('A')?.focus_id, f1.focus_id, 'the SAME focus row now shows A (no new focus)');
+        assert.equal(listFocuses().length, 1, 'still exactly one focus (retarget, not open)');
+        assert.equal(getFocusByNode('R'), null, 'R yielded the viewport');
+        // The focus followed the viewport: focusByPane on A's (now-in-viewport) pane resolves it.
+        assert.equal(focusByPane(aPane)?.node_id, 'A', 'the focus row tracks A\'s pane');
+    });
+});

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

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

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

@@ -0,0 +1,212 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/placement-reconcile.test.ts
+//
+// STEP 3 of the placement/focus migration: pane-anchored reconciliation (Q6) —
+// the robustness step. A manual move-pane/join-pane/break-pane must NEVER read
+// as a node death; liveness becomes pane-existence, and reconcile makes crtr
+// FOLLOW a move instead of fighting it. Covers:
+//   - reconcileDecision (PURE, no tmux): pane moved → cache FOLLOWS; pane gone →
+//     LOCATION nulled; never returns a stale window; legacy no-pane + live window
+//     → backfills the pane from paneOfWindow.
+//   - reconcile (impure shell over a real temp-db row, tmux absent): exercises
+//     the gone / no-op paths through setPresence.
+//   - isNodePaneAlive: pane present → paneExists path; pane null + window →
+//     windowAlive fallback (with a real, live tmux window when available).
+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, getRow } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { reconcileDecision, reconcile, isNodePaneAlive, } from '../runtime/placement.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,
+    };
+}
+function hasTmux() {
+    return spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0;
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-placement-'));
+    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'];
+});
+// ---------------------------------------------------------------------------
+// reconcileDecision — the PURE robustness core (§2.4, Q6). No tmux.
+// ---------------------------------------------------------------------------
+const cached = (over = {}) => ({
+    pane: '%5',
+    tmux_session: 'crtr',
+    window: '@1',
+    ...over,
+});
+const probe = (over = {}) => ({
+    paneLoc: null,
+    windowPane: null,
+    ...over,
+});
+test('reconcileDecision: pane MOVED → cache FOLLOWS to the new session/window (same pane id)', () => {
+    const d = reconcileDecision(cached({ pane: '%5', tmux_session: 'crtr', window: '@1' }), probe({ paneLoc: { session: 'user-sess', window: '@9' } }));
+    assert.deepEqual(d, { kind: 'follow', pane: '%5', tmux_session: 'user-sess', window: '@9' });
+});
+test('reconcileDecision: pane GONE (paneLocation null) → LOCATION nulled', () => {
+    const d = reconcileDecision(cached({ pane: '%5' }), probe({ paneLoc: null }));
+    assert.deepEqual(d, { kind: 'gone' });
+});
+test('reconcileDecision: pane present + cache already current → no-op (never a stale write)', () => {
+    const d = reconcileDecision(cached({ pane: '%5', tmux_session: 'crtr', window: '@1' }), probe({ paneLoc: { session: 'crtr', window: '@1' } }));
+    assert.deepEqual(d, { kind: 'none' });
+});
+test('reconcileDecision: NEVER returns a stale window — a follow always carries the LIVE location', () => {
+    // Window renumbered under the same pane (@1 → @4); follow must report @4, the
+    // live value, not the cached @1.
+    const d = reconcileDecision(cached({ pane: '%5', tmux_session: 'crtr', window: '@1' }), probe({ paneLoc: { session: 'crtr', window: '@4' } }));
+    assert.equal(d.kind, 'follow');
+    assert.equal(d.window, '@4', 'follow carries the live window, never the stale cache');
+});
+test('reconcileDecision: legacy no-pane + live window → BACKFILLS the pane from paneOfWindow', () => {
+    const d = reconcileDecision(cached({ pane: null, tmux_session: 'crtr', window: '@1' }), probe({ windowPane: '%7' }));
+    assert.deepEqual(d, { kind: 'backfill', pane: '%7', tmux_session: 'crtr', window: '@1' });
+});
+test('reconcileDecision: no pane + no live window pane → no-op (nothing to anchor on)', () => {
+    assert.deepEqual(reconcileDecision(cached({ pane: null, tmux_session: 'crtr', window: '@1' }), probe({ windowPane: null })), { kind: 'none' }, 'window has no resolvable active pane → nothing to backfill');
+});
+test('reconcileDecision: no pane + no window at all → no-op (a dormant/inline-root row)', () => {
+    assert.deepEqual(reconcileDecision(cached({ pane: null, tmux_session: null, window: null }), probe({ windowPane: '%7' })), { kind: 'none' }, 'no window to anchor a backfill on → no-op even if a stray windowPane was read');
+});
+// ---------------------------------------------------------------------------
+// reconcile / isNodePaneAlive — the impure shells. These call the real tmux
+// driver, so the machine may have a live tmux server with arbitrary panes; we
+// must never assume a hardcoded pane/session id is dead. Two robust strategies:
+//   • "absent" assertions use a UNIQUELY-named session that cannot exist
+//     (windowAlive/paneOfWindow on it are deterministically empty — robust
+//     whether or not a server is running).
+//   • "present/dead-pane" assertions create a real session and a real pane,
+//     killing it to get a guaranteed-dead `%id`. Gated on hasTmux().
+// ---------------------------------------------------------------------------
+/** A session name guaranteed not to exist on any server. */
+const ghostSession = `crtr-ghost-${process.pid}`;
+/** Run `fn` with a fresh detached session; tear it down after. */
+async function withSession(tag, fn) {
+    const session = `crtr-placement-${process.pid}-${tag}`;
+    spawnSync('tmux', ['new-session', '-d', '-s', session, '-c', '/tmp', 'sleep 600']);
+    try {
+        await fn(session);
+    }
+    finally {
+        spawnSync('tmux', ['kill-session', '-t', session], { stdio: 'ignore' });
+    }
+}
+function tmuxOut(args) {
+    return (spawnSync('tmux', args, { encoding: 'utf8' }).stdout ?? '').trim();
+}
+/** A guaranteed-DEAD `%pane_id` inside a still-live `window` of `session`: split
+ *  a fresh pane, capture its id, kill it. The window survives via its original
+ *  pane, so the id is dead while its old window is alive. */
+function makeDeadPane(session, window) {
+    const dead = tmuxOut(['split-window', '-d', '-P', '-F', '#{pane_id}', '-t', `${session}:${window}`, 'sleep 600']);
+    spawnSync('tmux', ['kill-pane', '-t', dead], { stdio: 'ignore' });
+    return dead;
+}
+test('reconcile: an unknown node is a silent no-op', () => {
+    assert.doesNotThrow(() => reconcile('ghost'));
+});
+test('reconcile: no pane + a non-existent window → no-op (cache left intact, not nulled)', () => {
+    // A ghost session can never resolve an active pane → backfill cannot fire and
+    // reconcile leaves the (already pane-less) cache exactly as it was.
+    createNode(node('n', { pane: null, tmux_session: ghostSession, window: '@1' }));
+    reconcile('n');
+    const r = getRow('n');
+    assert.equal(r?.pane, null, 'still no pane');
+    assert.equal(r?.tmux_session, ghostSession, 'session left intact (no-op, not nulled)');
+    assert.equal(r?.window, '@1', 'window left intact');
+});
+test('reconcile: a DEAD pane → LOCATION nulled (gone branch)', { skip: !hasTmux() }, async () => {
+    await withSession('gone', async (session) => {
+        const window = tmuxOut(['display-message', '-p', '-t', `${session}:`, '#{window_id}']);
+        const dead = makeDeadPane(session, window);
+        createNode(node('n', { pane: dead, tmux_session: session, window }));
+        reconcile('n');
+        const r = getRow('n');
+        assert.equal(r?.pane, null, 'pane nulled');
+        assert.equal(r?.tmux_session, null, 'session nulled');
+        assert.equal(r?.window, null, 'window nulled');
+    });
+});
+// ---------------------------------------------------------------------------
+// isNodePaneAlive — pane-existence primary, windowAlive fallback.
+// ---------------------------------------------------------------------------
+test('isNodePaneAlive: an unknown node id is not alive', () => {
+    assert.equal(isNodePaneAlive('ghost'), false);
+});
+test('isNodePaneAlive: pane null + a non-existent window → not alive (windowAlive fallback false)', () => {
+    createNode(node('legacy', { pane: null, tmux_session: ghostSession, window: '@1' }));
+    assert.equal(isNodePaneAlive('legacy'), false, 'no pane + dead window → fallback false');
+});
+test('isNodePaneAlive: a DEAD pane is NOT alive (paneExists path), id or row alike', { skip: !hasTmux() }, async () => {
+    await withSession('dead', async (session) => {
+        const window = tmuxOut(['display-message', '-p', '-t', `${session}:`, '#{window_id}']);
+        const dead = makeDeadPane(session, window);
+        createNode(node('n', { pane: dead, tmux_session: session, window }));
+        assert.equal(isNodePaneAlive('n'), false, 'a killed pane → not alive (by id)');
+        assert.equal(isNodePaneAlive(getRow('n')), false, 'same verdict passed a NodeRow directly');
+    });
+});
+// ---------------------------------------------------------------------------
+// Real-tmux behavior (gated): the windowAlive fallback + lazy backfill, and a
+// live pane FOLLOWING a manual move (the Q6 robustness core).
+// ---------------------------------------------------------------------------
+test('isNodePaneAlive: pane null + a LIVE window → alive via the windowAlive fallback (+ lazy backfill)', { skip: !hasTmux() }, async () => {
+    await withSession('alive', async (session) => {
+        const window = tmuxOut(['list-windows', '-t', session, '-F', '#{window_id}']).split('\n')[0];
+        createNode(node('legacy', { pane: null, tmux_session: session, window }));
+        assert.equal(isNodePaneAlive('legacy'), true, 'no pane but a live window → alive (legacy fallback)');
+        // reconcile lazily backfills that legacy row's pane from the live window.
+        reconcile('legacy');
+        const got = getNode('legacy');
+        assert.ok(got?.pane != null && got.pane.startsWith('%'), 'reconcile backfilled the pane from paneOfWindow');
+        assert.equal(got?.tmux_session, session, 'session preserved through the backfill');
+        assert.equal(got?.window, window, 'window preserved through the backfill');
+    });
+});
+test('isNodePaneAlive + reconcile: a LIVE pane is alive and FOLLOWS a join-pane move to another window', { skip: !hasTmux() }, async () => {
+    await withSession('move', async (session) => {
+        // Original window W0 and its active pane P.
+        const w0 = tmuxOut(['display-message', '-p', '-t', `${session}:`, '#{window_id}']);
+        const pane = tmuxOut(['display-message', '-p', '-t', `${session}:${w0}`, '#{pane_id}']);
+        // A second window W1 to move P into.
+        const w1 = tmuxOut(['new-window', '-d', '-P', '-F', '#{window_id}', '-t', `${session}:`, 'sleep 600']);
+        assert.ok(pane.startsWith('%') && w0.startsWith('@') && w1.startsWith('@') && w0 !== w1);
+        createNode(node('m', { pane, tmux_session: session, window: w0 }));
+        assert.equal(isNodePaneAlive('m'), true, 'a live pane reads alive');
+        // Manually join P into W1 — the Q6 robustness scenario. P's id survives; W0
+        // (now empty) closes. This must NOT read as a death.
+        spawnSync('tmux', ['join-pane', '-s', pane, '-t', `${session}:${w1}`], { stdio: 'ignore' });
+        assert.equal(isNodePaneAlive('m'), true, 'a manual join-pane is NOT a death — the pane still exists');
+        // reconcile FOLLOWS the move: same pane id, new window.
+        reconcile('m');
+        const got = getNode('m');
+        assert.equal(got?.pane, pane, 'pane id is invariant across the move');
+        assert.equal(got?.window, w1, 'window FOLLOWED the join-pane to W1');
+        assert.equal(got?.tmux_session, session, 'still the same session');
+    });
+});

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

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