@crouton-kit/crouter 0.3.15 → 0.3.17

package/dist/core/__tests__/flagship-lifecycle.test.js

@@ -0,0 +1,273 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/flagship-lifecycle.test.ts
+//
+// FLAGSHIP end-to-end lifecycle test — the faithful integration harness driving
+// a full node-graph scenario through the REAL CLI, a REAL isolated tmux session,
+// the REAL extension hooks (fired inside the fake-pi vehicle), and the REAL
+// daemon decision pass (superviseTick, in-process). Every assertion reads the
+// canvas data layer and is checked against the state-model ORACLE.
+//
+// Scenario (each hop asserted):
+//   A (base→orchestrator, RESIDENT root) spawns terminal child B.
+//   B spawns child C, then goes DORMANT (terminal idle-release, unfocused→pane closes).
+//   C finishes → ONE-HOP wakes B (A is NOT woken — the oracle's wake contract).
+//   B PROMOTES to orchestrator (terminal), takes a turn (persona drift), then
+//   YIELDS and revives in place (refresh-yield).
+//   B spawns child D; D finishes; B pushes its final up to A.
+//
+// 2×2 coverage (mode {base,orchestrator} × lifecycle {terminal,resident}):
+//   • base×resident       — A's PERSISTED ROW SHAPE at S1 (a harness-set fixture,
+//                           NOT a real bootRoot — see S1 + MINOR-1 caveat below).
+//                           The resident BEHAVIOR (does not idle-release) is
+//                           exercised faithfully in live-mutation.test.ts.
+//   • orchestrator×resident — A after promote (top-level orchestrator)
+//   • base×terminal       — B/C/D workers (GENUINE managed-child birth at S3)
+//   • orchestrator×terminal — B after promote (sub-orchestrator)
+//
+// ── Known coverage boundaries (DELIBERATE, documented gaps) ────────────────
+// This flagship + the live-mutation/cascade/subscription siblings cover the
+// HAPPY-PATH lifecycle and the live-mutation axis faithfully. The following
+// fault/grace/focus paths are OUT OF SCOPE for the faithful tier in this pass
+// (some are backstopped at the in-process unit tier, cited):
+//   • crash → dead (a vehicle that boots then its pane vanishes mid-run) — unit:
+//     daemon-liveness.test.ts "pane GONE … crash → dead".
+//   • boot-failure push (a vehicle that never boots → surfaceBootFailure urgent
+//     push up the spine) — no faithful coverage here.
+//   • focused-FREEZE (F3: a focused-dormant node frozen via remain-on-exit,
+//     pane-alive but pi-dead) — unit: daemon-liveness.test.ts "idle-release +
+//     live (frozen) pane …"; the grace-window double-spawn guard around it is
+//     exercised faithfully in grace-clock.test.ts.
+//   • node lifecycle --detach (A3: orphaned-focus-row hazard) — untested.
+//   • node msg / focus / cycle wake of a dormant node (A7) — untested faithfully.
+// These are intentional boundaries, not oversights.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { createHarness, hasTmux } from './helpers/harness.js';
+import { STALL_REPROMPT } from '../runtime/stop-guard.js';
+function sessionExists(session) {
+    return spawnSync('tmux', ['has-session', '-t', session], { stdio: 'ignore' }).status === 0;
+}
+test('flagship: full node lifecycle — spawn, dormancy, one-hop wake, promote, yield, finish', { skip: !hasTmux() ? 'tmux unavailable' : false, timeout: 180_000 }, async () => {
+    const h = await createHarness({ sessionPrefix: 'crtr-flagship' });
+    try {
+        // ===================================================================
+        // S1 — A's PERSISTED ROW SHAPE: base × RESIDENT (the user's front door).
+        //   ⚠ MINOR-1 caveat: this is NOT a real root birth. The harness mints A
+        //   via in-process createNode over a hand-built meta whose defaults ARE
+        //   mode:'base'/lifecycle:'resident' — the REAL birth/boot path (bootRoot)
+        //   execs pi inline and never returns, so it is structurally unreachable
+        //   from the harness (harness-design Wall #7). These four asserts therefore
+        //   PIN THE PERSISTED ROW SHAPE the rest of the scenario builds on — they
+        //   do NOT prove the real resident-birth path. The resident-at-birth 2×2
+        //   quadrant is out of reach; the resident *behavior* (no idle-release) is
+        //   exercised faithfully in live-mutation.test.ts, and the genuine real
+        //   birth of a managed child (→ terminal) IS exercised at S3 below.
+        // ===================================================================
+        const A = h.spawnRoot('top-level orchestrator');
+        {
+            const a = h.node(A);
+            assert.equal(a.mode, 'base', 'A row shape: base');
+            assert.equal(a.lifecycle, 'resident', 'A row shape: resident (fixture, not a real boot)');
+            assert.equal(a.status, 'active', 'A active');
+            assert.equal(a.intent ?? null, null, 'A no intent');
+        }
+        // ===================================================================
+        // S2 — A promotes: orchestrator × RESIDENT (top-level orchestrator).
+        //      mode flips; lifecycle/status/intent untouched (no transition()).
+        // ===================================================================
+        {
+            const res = h.cli(A, ['node', 'promote']);
+            assert.equal(res.code, 0, `promote A exit 0\n${res.stderr}`);
+            const a = h.node(A);
+            assert.equal(a.mode, 'orchestrator', 'A → orchestrator');
+            assert.equal(a.lifecycle, 'resident', 'A stays resident (no --resident)');
+            assert.equal(a.status, 'active', 'A still active (promote does not transition)');
+            assert.equal(a.intent ?? null, null, 'A intent untouched by promote');
+        }
+        // ===================================================================
+        // S3 — A spawns terminal child B: base × TERMINAL. The spawn seed wires
+        //      the spine — A auto-subscribes ACTIVE to B, B spawned_by A.
+        // ===================================================================
+        const B = await h.spawnChild(A, 'do the work', { kind: 'developer' });
+        {
+            const b = h.node(B);
+            assert.equal(b.mode, 'base', 'B born base');
+            assert.equal(b.lifecycle, 'terminal', 'B born terminal (managed child)');
+            assert.equal(b.status, 'active', 'B active after boot');
+            assert.equal(b.intent ?? null, null, 'B no intent');
+            assert.equal(b.parent, A, 'B spawned_by / parent = A');
+            // The load-bearing spine seed: A subscribes_to B (active).
+            const subsToB = h.subscribers(B);
+            assert.deepEqual(subsToB, [{ node_id: A, active: true }], 'A is B\'s sole ACTIVE subscriber (spawn seed)');
+            assert.equal(h.inbox(A).length, 0, 'A inbox empty (spawn pushes nothing)');
+        }
+        // ===================================================================
+        // S4 — B spawns child C (base × terminal). B now holds an active live
+        //      subscription to C → B is legitimately "awaiting" if it stops.
+        // ===================================================================
+        const C = await h.spawnChild(B, 'a subtask');
+        {
+            const c = h.node(C);
+            assert.equal(c.mode, 'base', 'C base');
+            assert.equal(c.lifecycle, 'terminal', 'C terminal');
+            assert.equal(c.status, 'active', 'C active');
+            assert.deepEqual(h.subscribers(C), [{ node_id: B, active: true }], 'B is C\'s sole ACTIVE subscriber (spawn seed)');
+            assert.deepEqual(h.subscriptions(B), [{ node_id: C, active: true }], 'B subscribes_to C (active)');
+            assert.equal(h.status(B), 'active', 'B still active');
+        }
+        // ===================================================================
+        // S5 — B goes DORMANT. It stops while awaiting C → terminal idle-release:
+        //      transition('release') → idle / idle-release; ctx.shutdown kills pi;
+        //      UNFOCUSED → the backstage pane CLOSES (fully dormant).
+        // ===================================================================
+        await h.stop(B);
+        await h.waitForStatus(B, 'idle');
+        {
+            const b = h.node(B);
+            assert.equal(b.status, 'idle', 'B idle (released)');
+            assert.equal(b.intent, 'idle-release', 'B intent=idle-release');
+        }
+        await h.waitForPaneGone(B);
+        assert.equal(h.paneAlive(B), false, 'B unfocused → pane closed on idle-release');
+        assert.equal(h.status(C), 'active', 'C still active while B sleeps');
+        // A untouched — a dormant terminal worker does not disturb its manager.
+        assert.equal(h.status(A), 'active', 'A still active');
+        assert.equal(h.inbox(A).length, 0, 'A inbox still empty');
+        // ===================================================================
+        // S6 — C FINISHES (push final). Pointer fans to subscribersOf(C) = {B}
+        //      ONLY. C → done/done. A is NOT a subscriber of C → A inbox stays
+        //      empty. This is the one-hop wake contract at the push site.
+        // ===================================================================
+        await h.finish(C, 'C result body');
+        {
+            const c = h.node(C);
+            assert.equal(c.status, 'done', 'C done');
+            assert.equal(c.intent, 'done', 'C intent=done');
+            assert.equal(h.paneAlive(C), false, 'C pane closed on done');
+            const bInbox = h.inbox(B);
+            const cFinal = bInbox.find((e) => e.from === C && e.kind === 'final');
+            assert.ok(cFinal, 'B inbox received C\'s final pointer (one hop)');
+            // ORACLE: ONE-HOP. A is not woken — only B (the direct subscriber) hears C.
+            assert.equal(h.inbox(A).length, 0, 'A inbox empty — A NOT woken by C (one-hop)');
+        }
+        // ===================================================================
+        // S7 — WAKE B. The in-process daemon second pass sees B idle/idle-release,
+        //      pi dead, an unseen inbox entry → reviveNode(resume). B → active,
+        //      intent cleared (revive). Its FRESH watcher delivers C's report.
+        // ===================================================================
+        const injBeforeWake = h.injected(B).length;
+        await h.tick(); // one superviseTick: 1st pass nulls the stale window, 2nd revives on inbox
+        await h.waitForStatus(B, 'active');
+        {
+            const b = h.node(B);
+            assert.equal(b.status, 'active', 'B revived → active');
+            assert.equal(b.intent ?? null, null, 'B intent cleared by revive');
+        }
+        await h.awaitBoot(B, { minCount: 2 }); // the resume boot (spawn boot + wake boot)
+        const wakeDigests = await h.awaitWake(B, { sinceCount: injBeforeWake, match: /C result body/ });
+        assert.ok(wakeDigests.some((d) => /C result body/.test(d)), 'B\'s real inbox-watcher delivered C\'s report after the wake');
+        // Still one-hop: A remained dormant-as-resident and was never touched.
+        assert.equal(h.inbox(A).length, 0, 'A inbox STILL empty after B woke (one-hop confirmed)');
+        assert.equal(h.status(A), 'active', 'A unchanged');
+        // ===================================================================
+        // S8 — B PROMOTES: base → orchestrator, lifecycle TERMINAL unchanged
+        //      (no --resident). orchestrator × terminal (the sub-orchestrator).
+        // ===================================================================
+        {
+            const res = h.cli(B, ['node', 'promote', '--kind', 'developer']);
+            assert.equal(res.code, 0, `promote B exit 0\n${res.stderr}`);
+            const b = h.node(B);
+            assert.equal(b.mode, 'orchestrator', 'B → orchestrator');
+            assert.equal(b.lifecycle, 'terminal', 'B stays TERMINAL (promote is mode-only)');
+            assert.equal(b.status, 'active', 'B still active');
+            assert.equal(b.intent ?? null, null, 'B intent untouched by promote');
+        }
+        // ===================================================================
+        // S9 — B takes a TURN. turn_end detects the base→orchestrator persona
+        //      drift and injects the orchestration guidance as a 'steer', then
+        //      commits the ack. agent_end then stalls (no live sub, no final) →
+        //      STALL_REPROMPT (followUp). Both are real stophook branches.
+        // ===================================================================
+        const injBeforeTurn = h.injected(B).length;
+        await h.turn(B, 'orchestrating');
+        const turnInjected = await h.waitFor(() => {
+            const fresh = h.injected(B).slice(injBeforeTurn);
+            // MINOR-3: match the steer by CONTENT (/ORCHESTRATOR/i), not deliverAs
+            // alone — mirroring live-mutation.test.ts's orchestrationSteers() — so
+            // this pins the orchestration guidance specifically, not "some steer."
+            const steer = fresh.find((e) => e.deliverAs === 'steer' && /ORCHESTRATOR/i.test(e.content));
+            const reprompt = fresh.find((e) => e.content.includes(STALL_REPROMPT));
+            return steer && reprompt ? fresh : null;
+        }, { timeoutMs: 15_000, label: 'B turn injected persona-drift steer + stall reprompt' });
+        assert.ok(turnInjected.some((e) => e.deliverAs === 'steer' && /ORCHESTRATOR/i.test(e.content)), 'turn_end injected the base→orchestrator persona-drift guidance (steer with ORCHESTRATOR content)');
+        assert.ok(turnInjected.some((e) => e.content.includes(STALL_REPROMPT)), 'agent_end stalled (orchestrator, no live sub, no final) → STALL_REPROMPT');
+        assert.equal(h.status(B), 'active', 'B still active after the turn (reprompt keeps it alive)');
+        // ===================================================================
+        // S10 — B YIELDS + revives. node yield → intent=refresh (active kept);
+        //       agent_end (b') runs reviveInPlace (respawn-pane -k) IN the fake-pi
+        //       pane; the fresh pi's session_start clears refresh → active. mode
+        //       and lifecycle survive the refresh.
+        // ===================================================================
+        await h.yieldNode(B, 'refresh against the roadmap');
+        {
+            const b = h.node(B);
+            assert.equal(b.status, 'active', 'B active after refresh-yield');
+            assert.equal(b.intent ?? null, null, 'B intent=refresh cleared by the fresh boot');
+            assert.equal(b.mode, 'orchestrator', 'B mode survives the refresh');
+            assert.equal(b.lifecycle, 'terminal', 'B lifecycle survives the refresh');
+        }
+        // ===================================================================
+        // S11 — B spawns child D (base × terminal). New spine seed B→D active.
+        // ===================================================================
+        const D = await h.spawnChild(B, 'a second subtask');
+        {
+            const d = h.node(D);
+            assert.equal(d.mode, 'base', 'D base');
+            assert.equal(d.lifecycle, 'terminal', 'D terminal');
+            assert.equal(d.status, 'active', 'D active');
+            assert.ok(h.subscriptions(B).some((s) => s.node_id === D && s.active), 'B subscribes_to D (active)');
+        }
+        // ===================================================================
+        // S12 — D FINISHES → pointer to B (its only subscriber).
+        // ===================================================================
+        await h.finish(D, 'D result body');
+        {
+            assert.equal(h.node(D).status, 'done', 'D done');
+            const dFinal = h.inbox(B).find((e) => e.from === D && e.kind === 'final');
+            assert.ok(dFinal, 'B inbox received D\'s final pointer');
+        }
+        // ===================================================================
+        // S13 — B pushes its FINAL up the spine → done/done; the pointer fans to
+        //       subscribersOf(B) = {A}. NOW A finally hears B (its own explicit
+        //       push — the only way the chain propagates a hop).
+        // ===================================================================
+        {
+            const res = h.cli(B, ['push', 'final', 'all work complete']);
+            assert.equal(res.code, 0, `B push final exit 0\n${res.stderr}`);
+            const b = h.node(B);
+            assert.equal(b.status, 'done', 'B done after push final');
+            assert.equal(b.intent, 'done', 'B intent=done');
+            const aInbox = h.inbox(A);
+            assert.equal(aInbox.length, 1, 'A inbox now has exactly B\'s final (one hop, on B\'s push)');
+            assert.equal(aInbox[0].from, B, 'A\'s entry is from B');
+            assert.equal(aInbox[0].kind, 'final', 'A\'s entry is a final');
+        }
+        // Close B's window faithfully (done branch shutdown).
+        await h.stop(B);
+        await h.waitForPaneGone(B);
+        assert.equal(h.paneAlive(B), false, 'B pane closed on done');
+        // A — the resident top-level orchestrator — is still alive and well.
+        {
+            const a = h.node(A);
+            assert.equal(a.status, 'active', 'A still active at the end');
+            assert.equal(a.mode, 'orchestrator', 'A still orchestrator');
+            assert.equal(a.lifecycle, 'resident', 'A still resident');
+        }
+    }
+    finally {
+        const session = h.session;
+        await h.dispose();
+        // Teardown leaves NO stray session.
+        assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
+    }
+});

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

@@ -1,9 +1,8 @@
 // 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:
+// The `focuses` table (canvas.db, migration v6) + its canvas setters + the
+// placement reads that compose over them. The table is the CANONICAL focus store
+// — there is no focus.ptr file and no dual-write bridge. 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;
@@ -13,23 +12,17 @@
 //   - 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 { mkdtempSync, rmSync } 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 { canvasDbPath, ensureHome } 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;
 }
@@ -39,8 +32,6 @@ function tableNames(db) {
 before(() => {
     home = mkdtempSync(join(tmpdir(), 'crtr-focuses-'));
     process.env['CRTR_HOME'] = home;
-    savedTmux = process.env['TMUX'];
-    delete process.env['TMUX'];
 });
 beforeEach(() => {
     closeDb();
@@ -50,8 +41,6 @@ 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.
@@ -205,55 +194,3 @@ test('placement focus reads agree with the focus rows', () => {
     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__/grace-clock.test.d.ts

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

package/dist/core/__tests__/grace-clock.test.js

@@ -0,0 +1,115 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/grace-clock.test.ts
+//
+// AXIS: the REVIVE_GRACE_MS double-spawn guard (daemon invariant 10), exercised
+// FAITHFULLY with a CONTROLLED CLOCK via the harness's injectable tick(now).
+//
+// Why this exists (MINOR-4): the harness exposes superviseTick's injectable
+// `now` through h.tick(now), but every other faithful test calls h.tick() with
+// no arg — so the grace window (the guard that a pi observed dead-while-its-pane-
+// lives must pend through REVIVE_GRACE_MS before a revive, lest a revive land in
+// the transient old-pi-dies→fresh-pi-boots gap and DOUBLE-SPAWN) was never
+// exercised end-to-end. daemon-liveness.test.ts pins livenessVerdict purely and
+// drives superviseTick with a FABRICATED pi-death (deadPid); this drives a REAL
+// fake-pi boot, kills it under a FROZEN (remain-on-exit) pane so the pane stays
+// alive while pi is genuinely dead, then walks a deterministic clock across the
+// grace boundary.
+//
+// This file is ADDITIVE and uses ONLY the public Harness API + h.tick(now) +
+// test-local tmux/file reads (the same shape as live-mutation.test.ts's
+// firstPaneOf/demote helpers). It does NOT edit harness.ts / fake-pi-host.ts or
+// any production file, and adds no harness helper.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHarness, hasTmux } from './helpers/harness.js';
+import { isPidAlive } from '../../daemon/crtrd.js';
+const SKIP = !hasTmux() ? 'tmux unavailable' : false;
+function sessionExists(session) {
+    return spawnSync('tmux', ['has-session', '-t', session], { stdio: 'ignore' }).status === 0;
+}
+/** Count the fake-pi boots recorded for a node (one line per boot in
+ *  fake-pi.boots.jsonl) — the observable for "did a revive double-spawn?". */
+function bootCount(home, id) {
+    try {
+        return readFileSync(join(home, 'nodes', id, 'fake-pi.boots.jsonl'), 'utf8')
+            .split('\n')
+            .filter((l) => l.trim() !== '').length;
+    }
+    catch {
+        return 0;
+    }
+}
+// REVIVE_GRACE_MS is 20_000 (crtrd.ts). We choose offsets well inside / well
+// past it so the test is robust to the exact value without importing it.
+const NOW = 5_000_000;
+const WITHIN_GRACE = NOW + 10_000; // < 20s after first-observed-dead → still pending
+const PAST_GRACE = NOW + 25_000; //  > 20s after first-observed-dead → revive
+// ===========================================================================
+// The grace window guards against a double-spawn: while a node's pane is alive
+// but its pi has been observed dead for LESS than REVIVE_GRACE_MS, the daemon
+// must NOT revive (a revive there would race the in-flight respawn and spawn a
+// second vehicle on the same pane). Once the pi has been dead PAST the grace, a
+// revive proceeds.
+// ===========================================================================
+test('grace clock: a dead-pi/alive-pane node does NOT revive within REVIVE_GRACE_MS, but DOES once it elapses', { skip: SKIP, timeout: 120_000 }, async () => {
+    const h = await createHarness({ sessionPrefix: 'crtr-grace' });
+    try {
+        const A = h.spawnRoot('resident root');
+        const B = await h.spawnChild(A, 'do the work', { kind: 'developer' });
+        // The boot proof carries the live fake-pi pid; the row records it via the
+        // real session_start hook. Both are the SAME process — that pid is what
+        // handleLiveWindow judges liveness on.
+        const boot = await h.awaitBoot(B);
+        const b0 = h.node(B);
+        assert.equal(b0.status, 'active', 'B active after boot');
+        assert.equal(b0.intent ?? null, null, 'B intent=null (NOT idle-release — the grace path, not the frozen early-return)');
+        assert.equal(b0.pi_pid, boot.pid, 'row pi_pid == the live fake-pi pid (recorded at session_start)');
+        assert.equal(bootCount(h.home, B), 1, 'exactly one boot so far');
+        // Arm remain-on-exit on B's window so that when we kill its pi the PANE
+        // survives (frozen) rather than closing — that is the only way to produce
+        // the "pane alive but pi dead" state handleLiveWindow's grace path judges.
+        const ro = spawnSync('tmux', ['set-window-option', '-t', b0.window, 'remain-on-exit', 'on'], { stdio: 'ignore' });
+        assert.equal(ro.status, 0, 'armed remain-on-exit on B\'s window');
+        // Kill the fake-pi. pi dies; the frozen pane stays alive.
+        process.kill(boot.pid, 'SIGKILL');
+        await h.waitFor(() => !isPidAlive(boot.pid), { timeoutMs: 10_000, label: 'fake-pi pid dead' });
+        assert.equal(h.paneAlive(B), true, 'pane is FROZEN alive after pi death (remain-on-exit)');
+        // --- TICK 1 @ NOW: first observation of the dead pi → 'pending'. The
+        //     daemon records first-observed-dead and does NOT revive. ---
+        await h.tick(NOW);
+        {
+            const b = h.node(B);
+            assert.equal(bootCount(h.home, B), 1, 'first tick: NO revive on first-observed-dead (still 1 boot)');
+            assert.equal(b.pi_pid, boot.pid, 'pi_pid unchanged — no fresh vehicle spawned');
+            assert.equal(b.status, 'active', 'B left active (pending, not revived)');
+            assert.equal(h.paneAlive(B), true, 'frozen pane still alive');
+        }
+        // --- TICK 2 @ NOW+10s (WITHIN the 20s grace): STILL pending. This is the
+        //     double-spawn guard: a revive here would land in the respawn gap. ---
+        await h.tick(WITHIN_GRACE);
+        {
+            const b = h.node(B);
+            assert.equal(bootCount(h.home, B), 1, 'within REVIVE_GRACE_MS: NO double-spawn — the dead pi must pend, not revive');
+            assert.equal(b.pi_pid, boot.pid, 'pi_pid STILL the dead pid — guard held');
+            assert.equal(b.status, 'active', 'B still active inside the grace window');
+        }
+        // --- TICK 3 @ NOW+25s (PAST the 20s grace): now a revive proceeds — a
+        //     FRESH fake-pi boots in the frozen pane (respawn-pane -k resume). ---
+        await h.tick(PAST_GRACE);
+        await h.awaitBoot(B, { minCount: 2, timeoutMs: 30_000 });
+        assert.ok(bootCount(h.home, B) >= 2, 'past REVIVE_GRACE_MS: the dead pi is revived → a fresh vehicle boots');
+        await h.waitForStatus(B, 'active');
+        {
+            const b = h.node(B);
+            assert.equal(b.status, 'active', 'B active after the grace-window revive');
+            assert.notEqual(b.pi_pid, boot.pid, 'pi_pid advanced to the fresh vehicle — the revive landed');
+        }
+    }
+    finally {
+        const session = h.session;
+        await h.dispose();
+        assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
+    }
+});

package/dist/core/__tests__/helpers/harness.d.ts

@@ -0,0 +1,78 @@
+import type { NodeMeta, NodeStatus, Mode, Lifecycle } from '../../canvas/types.js';
+import type { InboxEntry } from '../../feed/inbox.js';
+/** True when a usable tmux is on PATH — tests gate on this and SKIP otherwise. */
+export declare function hasTmux(): boolean;
+export interface WaitOpts {
+    timeoutMs?: number;
+    intervalMs?: number;
+    label?: string;
+}
+export interface Injected {
+    content: string;
+    deliverAs?: string;
+}
+export interface BootProof {
+    pid: number;
+    nodeId: string;
+    resuming: boolean;
+    prompt: string | null;
+    extPaths: string[];
+    loaded: string[];
+    failedExt: string[];
+    env: Record<string, string | null>;
+    [k: string]: unknown;
+}
+export interface CliResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+    json?: unknown;
+}
+export interface HarnessOpts {
+    sessionPrefix?: string;
+}
+export interface SpawnOpts {
+    kind?: string;
+    mode?: Mode;
+    lifecycle?: Lifecycle;
+    id?: string;
+}
+export interface Harness {
+    home: string;
+    session: string;
+    spawnRoot(task: string, o?: SpawnOpts): string;
+    spawnChild(parentId: string, task: string, o?: SpawnOpts): Promise<string>;
+    cli(nodeId: string | null, args: string[]): CliResult;
+    turn(nodeId: string, text?: string): Promise<void>;
+    stop(nodeId: string, reason?: 'stop' | 'length' | 'aborted' | 'error'): Promise<void>;
+    finish(nodeId: string, finalText: string): Promise<void>;
+    yieldNode(nodeId: string, note: string): Promise<void>;
+    tick(now?: number): Promise<void>;
+    awaitBoot(nodeId: string, o?: {
+        minCount?: number;
+        timeoutMs?: number;
+    }): Promise<BootProof>;
+    awaitWake(nodeId: string, o?: {
+        sinceCount?: number;
+        timeoutMs?: number;
+        match?: RegExp;
+    }): Promise<string[]>;
+    waitForStatus(nodeId: string, status: NodeStatus, timeoutMs?: number): Promise<void>;
+    waitForPaneGone(nodeId: string, timeoutMs?: number): Promise<void>;
+    waitFor<T>(probe: () => T | undefined | null | false, o?: WaitOpts): Promise<T>;
+    node(nodeId: string): NodeMeta | null;
+    status(nodeId: string): NodeStatus | null;
+    paneAlive(nodeId: string): boolean;
+    inbox(nodeId: string): InboxEntry[];
+    injected(nodeId: string): Injected[];
+    subscribers(nodeId: string): {
+        node_id: string;
+        active: boolean;
+    }[];
+    subscriptions(nodeId: string): {
+        node_id: string;
+        active: boolean;
+    }[];
+    dispose(): Promise<void>;
+}
+export declare function createHarness(opts?: HarnessOpts): Promise<Harness>;