@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/core/__tests__/on-read-dedup-resume.test.js

@@ -20,6 +20,7 @@ import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync } from 'node:
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { closeDb } from '../canvas/db.js';
+import { resetScopeCache } from '../scope.js';
 import { injectedDocsPath } from '../canvas/paths.js';
 import { spawnNode } from '../runtime/nodes.js';
 import { renderOnReadDocs } from '../substrate/on-read.js';
@@ -27,20 +28,32 @@ import { loadInjectedDocs, saveInjectedDocs, clearInjectedDocs, } from '../subst
 const FIXTURE_BODY = 'Fixture body that must surface exactly once.';
 let home;
 let work;
+let prevHomeEnv;
 before(() => {
     home = mkdtempSync(join(tmpdir(), 'crtr-onread-home-'));
     process.env['CRTR_HOME'] = home;
+    prevHomeEnv = process.env['HOME'];
 });
 beforeEach(() => {
     closeDb();
+    resetScopeCache();
     rmSync(home, { recursive: true, force: true });
+    if (prevHomeEnv === undefined)
+        delete process.env['HOME'];
+    else
+        process.env['HOME'] = prevHomeEnv;
     work = mkdtempSync(join(tmpdir(), 'crtr-onread-work-'));
 });
 after(() => {
     closeDb();
+    resetScopeCache();
     rmSync(home, { recursive: true, force: true });
     rmSync(work, { recursive: true, force: true });
     delete process.env['CRTR_HOME'];
+    if (prevHomeEnv === undefined)
+        delete process.env['HOME'];
+    else
+        process.env['HOME'] = prevHomeEnv;
 });
 test('injected-store round-trips and clears', () => {
     const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
@@ -51,6 +64,33 @@ test('injected-store round-trips and clears', () => {
     assert.ok(!existsSync(injectedDocsPath(node)), 'clear removes the file');
     assert.deepEqual([...loadInjectedDocs(node)], [], 'load after clear is empty');
 });
+test('user-global memory docs do not fire positionally for every file under home', () => {
+    const fakeHome = mkdtempSync(join(tmpdir(), 'crtr-onread-user-home-'));
+    process.env['HOME'] = fakeHome;
+    resetScopeCache();
+    const node = spawnNode({ kind: 'general', cwd: join(fakeHome, 'work'), parent: null }).node_id;
+    const userMemDir = join(fakeHome, '.crouter', 'memory');
+    mkdirSync(userMemDir, { recursive: true });
+    writeFileSync(join(userMemDir, 'noisy-global.md'), '---\nkind: preference\n' +
+        'when-and-why-to-read: When reading any file, this preference should be read because this fixture must not fire positionally\n' +
+        'file-read-visibility: content\n---\n' +
+        'NOISY USER BODY\n');
+    const projectMemDir = join(fakeHome, 'work', '.crouter', 'memory');
+    mkdirSync(projectMemDir, { recursive: true });
+    writeFileSync(join(projectMemDir, 'local.md'), '---\nkind: knowledge\n' +
+        'when-and-why-to-read: When reading project files, this reference should be read because local project memories remain positional\n' +
+        'file-read-visibility: content\n---\n' +
+        'LOCAL PROJECT BODY\n');
+    const readFile = join(fakeHome, 'work', 'ideas.md');
+    writeFileSync(readFile, 'turn off xml closer\n');
+    const rendered = renderOnReadDocs(node, readFile, new Set());
+    assert.ok(!rendered.includes('NOISY USER BODY'), 'user-global doc is not positional');
+    assert.ok(rendered.includes('LOCAL PROJECT BODY'), 'project doc still fires positionally');
+    assert.ok(rendered.includes('<memory kind="knowledge" name="local"'), 'memory docs render as memory tags');
+    assert.ok(!rendered.includes('triggered-by='), 'read target is not repeated on child items');
+    assert.ok(!rendered.includes('<auto-loaded-context file='), 'read target is not repeated on the wrapper');
+    rmSync(fakeHome, { recursive: true, force: true });
+});
 test('on-read doc surfaces once, stays deduped across a revive(resume), re-surfaces after a fresh launch', () => {
     const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
     // A positional substrate doc in a `.crouter/memory/` ancestor of the read file.

package/dist/core/__tests__/preview-registry-sync.test.js

@@ -0,0 +1,36 @@
+// Drift guard for the attach-viewer's bundle-safe preview registry.
+// Run with: node --import tsx/esm --test src/core/__tests__/preview-registry-sync.test.ts
+//
+// src/core/preview-registry.ts is a hand-maintained, zero-import mirror of
+// every leaf's `help.preview.suppressOutput` — it has to be hand-maintained
+// (not computed) because the attach viewer can never import the live command
+// tree (build-root.ts pulls in every subtree, including the web client's
+// Tailwind native binary — see command-preview-implementation.md). This test
+// is the only thing that keeps the mirror honest: it walks the real,
+// buildRoot()-assembled tree (safe here — this is a test, not the attach
+// bundle) and asserts the set of leaves declaring `suppressOutput: true`
+// matches the registry exactly.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { buildRoot } from '../../build-root.js';
+import { SUPPRESS_OUTPUT_LEAVES } from '../preview-registry.js';
+test('preview-registry.ts matches every leaf declaring help.preview.suppressOutput', async () => {
+    const root = await buildRoot();
+    const declared = new Set();
+    const walk = (branch) => {
+        for (const child of branch.children) {
+            if (child.kind === 'branch') {
+                walk(child);
+            }
+            else {
+                const leaf = child;
+                if (leaf.help.preview?.suppressOutput === true)
+                    declared.add(leaf.help.name);
+            }
+        }
+    };
+    for (const subtree of root.subtrees)
+        walk(subtree);
+    assert.deepEqual([...declared].sort(), [...SUPPRESS_OUTPUT_LEAVES].sort(), 'src/core/preview-registry.ts is out of sync with the leaves that declare ' +
+        'help.preview.suppressOutput — update SUPPRESS_OUTPUT_LEAVES to match.');
+});

package/dist/core/__tests__/prune-to-limit.test.js

@@ -0,0 +1,91 @@
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, getRow, recordPid, pruneToLimit, } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { nodeDir } from '../canvas/paths.js';
+let home;
+// A timestamp `secondsAgo` before now — created order doubles as recency order
+// here (no telemetry.json is written, so recencyMs falls back to created epoch).
+const at = (secondsAgo) => new Date(Date.now() - secondsAgo * 1000).toISOString();
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: at(0),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'dead',
+        ...over,
+    };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-prune-limit-'));
+    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'];
+    delete process.env['CRTR_NODE_ID'];
+});
+test('keeps all live nodes even when liveCount exceeds the cap', () => {
+    // 5 live (active/idle with a running pi) + 2 old terminal; cap of 3.
+    // target = max(3, 5) = 5, so NO live node is ever deleted; the 2 terminal
+    // fall beyond rank 5 and are pruned.
+    for (let i = 0; i < 5; i++) {
+        createNode(node(`live-${i}`, { status: 'active', created: at(i) }));
+        recordPid(`live-${i}`, process.pid); // process.pid is alive → isPidAlive true
+    }
+    createNode(node('old-a', { status: 'dead', created: at(100) }));
+    createNode(node('old-b', { status: 'done', created: at(101) }));
+    const result = pruneToLimit({ maxNodes: 3 });
+    assert.equal(result.dryRun, false);
+    assert.deepEqual(result.pruned.map((p) => p.node_id).sort(), ['old-a', 'old-b']);
+    for (let i = 0; i < 5; i++) {
+        assert.ok(getRow(`live-${i}`) !== null, `live-${i} must survive past the cap`);
+    }
+});
+test('deletes the oldest terminal nodes beyond max(cap, liveCount)', () => {
+    // 1 live + 5 terminal of descending recency; cap of 3 → target = max(3,1) = 3.
+    // Ranked by recency DESC: live-0, term-0, term-1 (top 3, kept), then
+    // term-2, term-3, term-4 (rank >= 3, pruned).
+    createNode(node('live-0', { status: 'idle', created: at(0) }));
+    recordPid('live-0', process.pid);
+    for (let i = 0; i < 5; i++) {
+        createNode(node(`term-${i}`, { status: 'dead', created: at(10 + i) }));
+    }
+    const result = pruneToLimit({ maxNodes: 3 });
+    assert.deepEqual(result.pruned.map((p) => p.node_id).sort(), ['term-2', 'term-3', 'term-4']);
+    // The kept set: the live node + the two newest terminal.
+    for (const id of ['live-0', 'term-0', 'term-1']) {
+        assert.ok(getRow(id) !== null, `${id} must survive`);
+        assert.ok(existsSync(nodeDir(id)), `${id} dir must survive`);
+    }
+    // The pruned set: rows AND dirs gone.
+    for (const id of ['term-2', 'term-3', 'term-4']) {
+        assert.equal(getRow(id), null, `${id} row should be pruned`);
+        assert.ok(!existsSync(nodeDir(id)), `${id} dir should be removed`);
+    }
+});
+test('--dry-run reports candidates but deletes nothing', () => {
+    for (let i = 0; i < 5; i++) {
+        createNode(node(`term-${i}`, { status: 'dead', created: at(i) }));
+    }
+    const result = pruneToLimit({ maxNodes: 3, dryRun: true });
+    assert.equal(result.dryRun, true);
+    assert.deepEqual(result.pruned.map((p) => p.node_id).sort(), ['term-3', 'term-4']);
+    // Nothing deleted — all rows + dirs intact.
+    for (let i = 0; i < 5; i++) {
+        assert.ok(getRow(`term-${i}`) !== null, `term-${i} must survive a dry run`);
+        assert.ok(existsSync(nodeDir(`term-${i}`)), `term-${i} dir must survive a dry run`);
+    }
+});

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

@@ -11,7 +11,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createNode, setStatus } from '../canvas/canvas.js';
 import { closeDb } from '../canvas/db.js';
-import { registerPush } from '../../commands/push.js';
+import { registerPush, mapFinalizeTransitionRaceError } from '../../commands/push.js';
 import { InputError } from '../io.js';
 let home;
 const prevNodeId = process.env['CRTR_NODE_ID'];
@@ -69,3 +69,9 @@ test('push final on a dead node is also caught cleanly', async () => {
     process.env['CRTR_NODE_ID'] = id;
     await assert.rejects(() => finalLeaf().run({ body: 'x' }), (e) => e instanceof InputError && e.payload.error === 'already_finalized');
 });
+test('a raw finalize-transition race is normalized to already_finalized', () => {
+    const mapped = mapFinalizeTransitionRaceError('canceled', new Error("illegal lifecycle transition: 'finalize' from status='canceled' (node raceNode)"));
+    assert.ok(mapped instanceof InputError, 'the raw transition error is converted');
+    assert.equal(mapped?.payload.error, 'already_finalized');
+    assert.equal(mapped?.payload.message, 'This node is already canceled — `push final` finishes a node once and cannot finalize it again.');
+});

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

@@ -36,7 +36,7 @@ function makeDeps(pid) {
     const deps = {
         launchBroker: (nodeId) => {
             launched.push(nodeId);
-            return { pid };
+            return { pid, exited: new Promise(() => { }) };
         },
         waitForViewSocket: () => true,
         respawnViewer: () => true,
@@ -57,7 +57,7 @@ after(() => {
     rmSync(home, { recursive: true, force: true });
     delete process.env['CRTR_HOME'];
 });
-test('relaunchRoot parks the old root done and mints a fresh active root, reaping descendants', () => {
+test('relaunchRoot parks the old root done and mints a fresh active root, reaping descendants', async () => {
     // root → child → grandchild (a parent that subscribes to its workers).
     createNode(node('root', { parent: null, lifecycle: 'resident', cwd: '/tmp/proj' }));
     createNode(node('child', { parent: 'root' }));
@@ -65,7 +65,7 @@ test('relaunchRoot parks the old root done and mints a fresh active root, reapin
     subscribe('root', 'child', true);
     subscribe('child', 'grand', true);
     const { deps, launched } = makeDeps(4242);
-    const res = relaunchRoot('root', deps);
+    const res = await relaunchRoot('root', deps);
     // A fresh, DIFFERENT node id was minted and booted.
     assert.ok(res, 'relaunchRoot returns the new node id');
     const newId = res.newNodeId;
@@ -86,14 +86,14 @@ test('relaunchRoot parks the old root done and mints a fresh active root, reapin
     assert.equal(getNode('child')?.status, 'canceled', 'descendant child canceled');
     assert.equal(getNode('grand')?.status, 'canceled', 'descendant grandchild canceled');
 });
-test('relaunchRoot on a boot failure leaves the old root + descendants fully intact', () => {
+test('relaunchRoot on a boot failure leaves the old root + descendants fully intact', async () => {
     // The mint-and-boot-FIRST ordering: a launch failure (pid=null) must occur
     // BEFORE the old root is parked or its descendants reaped.
     createNode(node('root', { parent: null, lifecycle: 'resident' }));
     createNode(node('child', { parent: 'root' }));
     subscribe('root', 'child', true);
     const { deps, launched } = makeDeps(null); // broker never starts
-    const res = relaunchRoot('root', deps);
+    const res = await relaunchRoot('root', deps);
     assert.equal(res, null, 'a boot failure returns null');
     // Old root + descendant untouched: still live, ready to keep running.
     assert.equal(getNode('root')?.status, 'active', 'old root left active + untouched');
@@ -102,13 +102,13 @@ test('relaunchRoot on a boot failure leaves the old root + descendants fully int
     assert.equal(launched.length, 1, 'one broker launch was attempted');
     assert.equal(getNode(launched[0])?.status, 'dead', 'the half-born new node is crashed (dead)');
 });
-test('relaunchRoot is a no-op for a non-root child and an already-parked root', () => {
+test('relaunchRoot is a no-op for a non-root child and an already-parked root', async () => {
     createNode(node('root', { parent: null, lifecycle: 'resident' }));
     createNode(node('child', { parent: 'root' }));
     createNode(node('done-root', { parent: null, status: 'done' }));
     const { deps, launched } = makeDeps(1);
-    assert.equal(relaunchRoot('child', deps), null, 'a child is not a relaunchable root');
-    assert.equal(relaunchRoot('done-root', deps), null, 'a done root is not relaunched again (double /new)');
-    assert.equal(relaunchRoot('ghost', deps), null, 'an unknown node is a no-op');
+    assert.equal(await relaunchRoot('child', deps), null, 'a child is not a relaunchable root');
+    assert.equal(await relaunchRoot('done-root', deps), null, 'a done root is not relaunched again (double /new)');
+    assert.equal(await relaunchRoot('ghost', deps), null, 'an unknown node is a no-op');
     assert.deepEqual(launched, [], 'no broker was booted for any of the no-op cases');
 });

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

@@ -1,11 +1,11 @@
 // Run with: node --import tsx/esm --test src/core/__tests__/revive.test.ts
 //
 // HEADLESS RETARGET (foundation-spec §C.13 + §E). Covers the session-picker fix
-// (resume by ABSOLUTE session-file path, cwd-immune, falling back to the bare
-// uuid for older nodes) AND the double-revive guard that keeps two pi processes
-// off one session file. The argv selection is unit-tested via the pure
-// `resumeArgs` + `buildPiArgv`; the guard + the cycle-counter bump are now driven
-// against a fabricated BROKER-hosted node — ZERO real tmux, ZERO real boot.
+// (resume by ABSOLUTE session-file path, cwd-immune) and the double-revive guard
+// that keeps two pi processes off one session file. The argv selection is
+// unit-tested via the pure `resumeArgs` + `buildPiArgv`; the guard + the
+// cycle-counter bump are now driven against a fabricated BROKER-hosted node —
+// ZERO real tmux, ZERO real boot.
 //
 // (1) BUG LOCKED — the double-revive guard (revive.ts:114): a node already up
 //     (its engine container alive AND its pi pid live) must NOT be re-launched —
@@ -30,13 +30,14 @@
 //     goes RED.
 import { test, before, after, beforeEach } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import { createNode } from '../canvas/canvas.js';
 import { closeDb } from '../canvas/db.js';
 import { buildPiArgv } from '../runtime/launch.js';
+import { headlessBrokerHost } from '../runtime/host.js';
 import { resumeArgs, reviveNode } from '../runtime/revive.js';
 import { createHarness } from './helpers/harness.js';
 let home;
@@ -92,41 +93,54 @@ after(() => {
 // ---------------------------------------------------------------------------
 // resumeArgs — the pure resume-source selection
 // ---------------------------------------------------------------------------
-test('resumeArgs prefers the absolute file path and keeps the id as fallback', () => {
-    const m = node('n', { pi_session_id: 'uuid-123', pi_session_file: '/abs/sess.jsonl' });
-    assert.deepEqual(resumeArgs(m, true), {
-        resumeSessionId: 'uuid-123',
-        resumeSessionPath: '/abs/sess.jsonl',
-    });
+test('resumeArgs resumes by the absolute file path when it exists on disk', () => {
+    mkdirSync(home, { recursive: true });
+    const sessionFile = join(home, 'resume-args-exists.jsonl');
+    writeFileSync(sessionFile, '{}\n', 'utf8');
+    const m = node('n', { pi_session_id: 'uuid-123', pi_session_file: sessionFile });
+    assert.deepEqual(resumeArgs(m, true), { resumeSessionPath: sessionFile });
 });
-test('resumeArgs falls back to the bare id when no file was captured (older node)', () => {
+test('resumeArgs selects nothing (falls through to fresh) when no file was ever captured (older node)', () => {
     const m = node('n', { pi_session_id: 'uuid-123', pi_session_file: null });
-    assert.deepEqual(resumeArgs(m, true), {
-        resumeSessionId: 'uuid-123',
-        resumeSessionPath: undefined,
+    assert.deepEqual(resumeArgs(m, true), {});
+});
+test('resumeArgs selects nothing (falls through to fresh) when the recorded file does not exist on disk', () => {
+    // The related P6 finding: pi_session_file can be recorded in meta with
+    // nothing ever written there (the first-boot engine died before
+    // session_start). A bare id is NOT a safe fallback either —
+    // headlessBrokerHost's preflight fatally rejects it — so this must select
+    // NEITHER source, not silently hand pi a path that isn't there.
+    const m = node('n', {
+        pi_session_id: 'uuid-123',
+        pi_session_file: join(home, 'never-written.jsonl'),
     });
+    assert.deepEqual(resumeArgs(m, true), {});
 });
 test('resumeArgs selects neither source on a no-resume (refresh) revive', () => {
-    const m = node('n', { pi_session_id: 'uuid-123', pi_session_file: '/abs/sess.jsonl' });
+    mkdirSync(home, { recursive: true });
+    const sessionFile = join(home, 'resume-args-refresh.jsonl');
+    writeFileSync(sessionFile, '{}\n', 'utf8');
+    const m = node('n', { pi_session_id: 'uuid-123', pi_session_file: sessionFile });
     assert.deepEqual(resumeArgs(m, false), {});
 });
 // ---------------------------------------------------------------------------
 // buildPiArgv — the `--session` argument the revive builds
 // ---------------------------------------------------------------------------
-test('buildPiArgv resumes by ABSOLUTE path when pi_session_file is set (not the uuid)', () => {
-    const m = node('n', { pi_session_id: 'uuid-123', pi_session_file: '/abs/sess.jsonl' });
+test('buildPiArgv resumes by ABSOLUTE path when pi_session_file exists on disk', () => {
+    mkdirSync(home, { recursive: true });
+    const sessionFile = join(home, 'build-argv-exists.jsonl');
+    writeFileSync(sessionFile, '{}\n', 'utf8');
+    const m = node('n', { pi_session_id: 'uuid-123', pi_session_file: sessionFile });
     const { argv } = buildPiArgv(m, resumeArgs(m, true));
     const i = argv.indexOf('--session');
     assert.ok(i >= 0, 'argv carries --session');
-    assert.equal(argv[i + 1], '/abs/sess.jsonl', 'resumes by absolute file path');
-    assert.ok(!argv.includes('uuid-123'), 'the bare uuid is NOT used when a path exists');
+    assert.equal(argv[i + 1], sessionFile, 'resumes by absolute file path');
+    assert.ok(!argv.includes('uuid-123'), 'the bare uuid is never used to resume');
 });
-test('buildPiArgv falls back to --session <uuid> when no path is stored', () => {
+test('buildPiArgv passes no --session when no path is stored (falls through to fresh)', () => {
     const m = node('n', { pi_session_id: 'uuid-123', pi_session_file: null });
     const { argv } = buildPiArgv(m, resumeArgs(m, true));
-    const i = argv.indexOf('--session');
-    assert.ok(i >= 0, 'argv carries --session');
-    assert.equal(argv[i + 1], 'uuid-123', 'resumes by bare uuid (older node)');
+    assert.ok(!argv.includes('--session'), 'no bare-uuid resume — a bare id is fatally rejected by broker preflight');
 });
 test('buildPiArgv passes no --session on a fresh (no-resume) launch', () => {
     const m = node('n', { pi_session_id: 'uuid-123', pi_session_file: '/abs/sess.jsonl' });
@@ -139,11 +153,14 @@ test('buildPiArgv passes no --session on a fresh (no-resume) launch', () => {
 // (kind/mode/lifecycle come back as the node's *current* self).
 // ---------------------------------------------------------------------------
 test('a resumed revive replays the persisted LaunchSpec (model, tools, extensions, prompt, env)', () => {
+    mkdirSync(home, { recursive: true });
+    const sessionFile = join(home, 'launchspec-replay.jsonl');
+    writeFileSync(sessionFile, '{}\n', 'utf8');
     const m = node('n', {
         kind: 'developer',
         mode: 'orchestrator',
         pi_session_id: 'uuid-9',
-        pi_session_file: '/abs/sess.jsonl',
+        pi_session_file: sessionFile,
         launch: {
             model: 'anthropic/sonnet',
             tools: ['bash', 'read'],
@@ -166,7 +183,7 @@ test('a resumed revive replays the persisted LaunchSpec (model, tools, extension
     assert.equal(argv[ti + 1], 'bash,read');
     assert.ok(argv.includes('--append-system-prompt'), 'system prompt replayed');
     const si = argv.indexOf('--session');
-    assert.equal(argv[si + 1], '/abs/sess.jsonl', 'still resumes by file path');
+    assert.equal(argv[si + 1], sessionFile, 'still resumes by file path');
     // Env contract: launch-spec env merged over the node identity env.
     assert.equal(env['FOO'], 'bar');
     assert.equal(env['CRTR_NODE_ID'], 'n');
@@ -211,11 +228,15 @@ test('reviveNode PROCEEDS when the broker engine is DOWN (dead pid) — cycle co
         // circuit → reviveNode proceeds. It bumps cycles BEFORE the detached (fake-
         // engine) launch, so the bump is observable instantly; the throwaway broker is
         // killed by dispose().
+        const sessionFile = join(home, 'sessions', 'crtr-revive-proceed.jsonl');
+        mkdirSync(join(home, 'sessions'), { recursive: true });
+        writeFileSync(sessionFile, '{}\n', 'utf8');
         const M = h.fabricateBrokerNode({
             status: 'active',
             intent: null,
             pi_pid: deadPid(),
             pi_session_id: 'uuid-1',
+            pi_session_file: sessionFile,
         });
         assert.equal(h.node(M).cycles ?? 0, 0, 'fabricated at cycle 0 (no revive yet)');
         reviveNode(M, { resume: true });
@@ -225,3 +246,55 @@ test('reviveNode PROCEEDS when the broker engine is DOWN (dead pid) — cycle co
         await h.dispose();
     }
 });
+test('reviveNode fresh-fallback clears the stale session identity (Major-3: no phantom stranded-relaunch)', async () => {
+    const h = await createHarness({ headless: true, sessionPrefix: 'crtr-revive-freshfb' });
+    try {
+        // resume=true was ASKED, but the recorded .jsonl is gone from disk, so
+        // resumeArgs falls through to a FRESH launch. The stale pi_session_id /
+        // pi_session_file must be cleared BEFORE launch: if this fresh broker then
+        // dies before session_start (no new pid, no new session), the daemon keys on
+        // pi_session_id — a leftover id would be misread as a stranded relaunch and
+        // retried forever instead of surfaced as a boot failure.
+        const missingFile = join(home, 'sessions', 'never-written.jsonl');
+        const M = h.fabricateBrokerNode({
+            status: 'active',
+            intent: null,
+            pi_pid: deadPid(),
+            pi_session_id: 'uuid-stale',
+            pi_session_file: missingFile,
+        });
+        const res = reviveNode(M, { resume: true });
+        assert.equal(res.resumed, false, 'a missing .jsonl forces a fresh (non-resuming) launch');
+        const after = h.node(M);
+        assert.equal(after.pi_session_id, null, 'stale pi_session_id cleared before the fresh launch');
+        assert.equal(after.pi_session_file, null, 'stale pi_session_file cleared before the fresh launch');
+    }
+    finally {
+        await h.dispose();
+    }
+});
+test('reviveNode crashes and clears pid when launch/preflight throws', async () => {
+    const h = await createHarness({ headless: true, sessionPrefix: 'crtr-revive-fail' });
+    const originalLaunch = headlessBrokerHost.launch;
+    try {
+        const sessionFile = join(home, 'sessions', 'crtr-revive-fail.jsonl');
+        mkdirSync(join(home, 'sessions'), { recursive: true });
+        writeFileSync(sessionFile, '{}\n', 'utf8');
+        const M = h.fabricateBrokerNode({
+            status: 'active',
+            intent: null,
+            pi_pid: deadPid(),
+            pi_session_id: 'uuid-2',
+            pi_session_file: sessionFile,
+        });
+        headlessBrokerHost.launch = (_nodeId, _inv, _opts) => { throw new Error('boom'); };
+        assert.throws(() => reviveNode(M, { resume: true }), /refusing to revive/i);
+        const after = h.node(M);
+        assert.equal(after.status, 'dead', 'failed revive marks the node dead');
+        assert.equal(after.pi_pid, null, 'failed revive clears the stale pid');
+    }
+    finally {
+        headlessBrokerHost.launch = originalLaunch;
+        await h.dispose();
+    }
+});

package/dist/core/__tests__/spawn-root.test.js

@@ -10,7 +10,8 @@ import { createNode, getNode, getRow, subscribersOf } from '../canvas/canvas.js'
 import { closeDb } from '../canvas/db.js';
 import { nodeDir } from '../canvas/paths.js';
 import { spawnNode } from '../runtime/nodes.js';
-import { resolveSpawner } from '../runtime/spawn.js';
+import { spawnChild, resolveSpawner } from '../runtime/spawn.js';
+import { headlessBrokerHost } from '../runtime/host.js';
 let home;
 function spawner(id) {
     return {
@@ -81,3 +82,25 @@ test('unknown parent: spawnNode throws and mints NO node dir / row (validate bef
     assert.equal(getRow(orphanId), null, 'no index row written for the orphan');
     assert.equal(existsSync(nodeDir(orphanId)), false, 'no node dir scaffolded for the orphan');
 });
+test('spawnChild crashes the node when launch/preflight throws', async () => {
+    const parentId = 'A';
+    createNode(spawner(parentId));
+    const originalLaunch = headlessBrokerHost.launch;
+    let launchedNodeId = null;
+    try {
+        headlessBrokerHost.launch = (nodeId, _inv, _opts) => {
+            launchedNodeId = nodeId;
+            throw new Error('boom');
+        };
+        await assert.rejects(async () => spawnChild({ kind: 'developer', cwd: '/tmp/work', parent: parentId, prompt: 'task' }), /refusing to launch/i);
+        assert.ok(launchedNodeId !== null, 'the launch hook saw the spawned node id');
+        const after = getNode(launchedNodeId);
+        assert.equal(after.status, 'dead', 'failed spawn marks the node dead');
+        assert.equal(after.pi_pid, null, 'failed spawn clears the stale pid');
+    }
+    finally {
+        headlessBrokerHost.launch = originalLaunch;
+        closeDb();
+        rmSync(home, { recursive: true, force: true });
+    }
+});

package/dist/core/__tests__/stop-guard.test.js

@@ -80,3 +80,13 @@ test('pushedFinal → finished; askedHuman → escalated (both short-circuit bef
     assert.deepEqual(evaluateStop('t', { pushedFinal: true, askedHuman: false }), { action: 'allow', reason: 'finished' });
     assert.deepEqual(evaluateStop('t', { pushedFinal: false, askedHuman: true }), { action: 'allow', reason: 'escalated' });
 });
+test('already-terminal stored statuses are allowed without a stall reprompt', () => {
+    for (const [id, status] of [
+        ['doneNode', 'done'],
+        ['deadNode', 'dead'],
+        ['canceledNode', 'canceled'],
+    ]) {
+        createNode(node(id, { parent: 'mgr', lifecycle: 'terminal', status }));
+        assert.deepEqual(evaluateStop(id, noSignals), { action: 'allow', reason: 'finished' });
+    }
+});

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

@@ -0,0 +1,72 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/stranded-relaunch.test.ts
+//
+// BUG-REGRESSION (observed 2026-06-15 on the live canvas). A broker-hosted node
+// whose row carries pi_pid=NULL but pi_session_id SET was read by
+// handleNodeLiveness as "a relaunch in flight — leave it" UNCONDITIONALLY, with
+// no timeout. reviveNode clears pi_pid right after launch and the fresh engine
+// re-records it within a tick or two — but a relaunch whose broker DIED in that
+// gap (after the pid-clear, before re-record) never re-records, so the node sat
+// 'active' with no engine FOREVER and its parent waited on a dead child. Six such
+// stranded resident roots had accumulated and the daemon would never recover or
+// reap any of them.
+//
+// THE FIX — give the pid==null + session-set case the SAME REVIVE_GRACE_MS boot
+// grace as the never-booted case: a healthy relaunch always re-records its pid
+// well inside the grace (and the pid-alive branch clears the clock); if the grace
+// ELAPSES with still no pid, the relaunch is dead → grace-revive RESUME on the
+// saved session. The 20s grace doubles as the double-spawn guard.
+//
+// WHY MODEL-LEVEL, NOT TMUX CHROME — the stranding lives entirely in pure daemon
+// logic (the pid==null branch of handleNodeLiveness + the unhealthySince clock).
+// A fabricated broker row carrying pi_pid=null + a recorded pi_session_id
+// reproduces the exact stranded state with no process at all; h.tick(now) walks a
+// deterministic clock across the grace boundary and getNode().cycles (reviveNode
+// bumps cycles + transition('revive') BEFORE the detached spawn) makes the revive
+// observable instantly.
+//
+// HOW IT FAILS IF THE BUG REGRESSES — restore the unconditional
+// `if (meta.pi_session_id != null) return;` and the PAST-grace tick never revives
+// → cycles stays 0 → the final assert goes RED.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createHarness } from './helpers/harness.js';
+// REVIVE_GRACE_MS is 20_000 (crtrd.ts). Offsets well inside / well past it keep
+// the test robust to the exact value without importing it.
+const NOW = 7_000_000;
+const WITHIN_GRACE = NOW + 10_000; // < 20s after first-observed-null → still pending
+const PAST_GRACE = NOW + 25_000; //  > 20s after first-observed-null → revive
+test('stranded relaunch: pid=null + session set is revived once the boot grace elapses, not left active forever', { timeout: 30_000 }, async () => {
+    const h = await createHarness({ headless: true, sessionPrefix: 'crtr-stranded' });
+    try {
+        // The EXACT stranded state: a broker row that booted once (pi_session_id
+        // captured) whose relaunch then died after the pid-clear — pi_pid NULL,
+        // intent null (so it is neither the refresh nor the idle-release path).
+        const B = h.fabricateBrokerNode({
+            kind: 'developer',
+            status: 'active',
+            intent: null,
+            pi_pid: null,
+            pi_session_id: 'sess-stranded-B',
+        });
+        const b0 = h.node(B);
+        assert.equal(b0.host_kind, 'broker', 'B is broker-hosted (paneless)');
+        assert.equal(b0.pi_pid ?? null, null, 'row pi_pid is null (relaunch never re-recorded)');
+        assert.equal(b0.pi_session_id, 'sess-stranded-B', 'session is set (booted once)');
+        assert.equal(b0.cycles ?? 0, 0, 'no revive yet — cycles at 0');
+        // --- TICK 1 @ NOW: first observation of null pid → start the boot grace
+        //     clock, do NOT revive (a healthy relaunch re-records its pid here). ---
+        await h.tick(NOW);
+        assert.equal(h.node(B).cycles ?? 0, 0, 'first tick: no revive — grace clock started');
+        // --- TICK 2 @ NOW+10s (WITHIN grace): still pending. This is the
+        //     double-spawn guard — a healthy relaunch would have re-recorded by now. ---
+        await h.tick(WITHIN_GRACE);
+        assert.equal(h.node(B).cycles ?? 0, 0, 'within REVIVE_GRACE_MS: still no revive (healthy relaunch grace, not a strand yet)');
+        // --- TICK 3 @ NOW+25s (PAST grace): the relaunch is dead → grace-revive
+        //     RESUME on the saved session; reviveNode bumps cycles immediately. ---
+        await h.tick(PAST_GRACE);
+        assert.equal(h.node(B).cycles ?? 0, 1, 'past REVIVE_GRACE_MS: the stranded relaunch is revived (cycles bumped) — NOT left active forever');
+    }
+    finally {
+        await h.dispose();
+    }
+});

package/dist/core/__tests__/tmux-surface.test.js

@@ -68,7 +68,11 @@ test('§2.2 driver invariant: every placement verb in tmux.ts passes an explicit
         found++;
         const verb = m[1];
         const arr = enclosingArray(src, m.index);
-        assert.ok(arr.includes(`'-t'`), `tmux verb '${verb}' is invoked WITHOUT an explicit -t target — a latent ` +
+        // The invariant is "name a specific tmux object, never fall back to the
+        // GLOBAL current one". `-t` targets a destination; `break-pane` (and the
+        // deleted swap/join/move-pane) instead name their SOURCE with `-s` — which
+        // satisfies the invariant identically. Accept either explicit target flag.
+        assert.ok(arr.includes(`'-t'`) || arr.includes(`'-s'`), `tmux verb '${verb}' is invoked WITHOUT an explicit -t/-s target — a latent ` +
             `instance of the unbidden-window bug (§2.2). Offending args array:\n${arr}`);
     }
     // Sanity: the driver really does contain placement verbs (so a refactor that