@north-light/crouter 0.3.154

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

@@ -0,0 +1,575 @@
+// 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) 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): a node whose broker is
+//     already up — i.e. it has a live FLEET ENTRY (design D-1: a fleet entry IS
+//     liveness) — must NOT be re-launched: a second pi on the same .jsonl
+//     corrupts the conversation. The complement: a revive that DOES proceed
+//     bumps the node's `cycles` BEFORE it spawns (revive.ts cycles++, then
+//     transition('revive'), then launch).
+//
+// (2) WHY MODEL-LEVEL, NOT TMUX CHROME — the guard reads `boundFleet().has`,
+//     so registering a fabricated fleet entry for a fabricated broker row
+//     reproduces the exact "already up" state the guard short-circuits on —
+//     no pane, no window, no tmux server, no pid probe. The real invariant is
+//     the model effect: `cycles` UNCHANGED on the guard path, and bumped to 1
+//     when the revive proceeds (revive.ts bumps cycles synchronously before
+//     the detached launch — observable INSTANTLY, no awaitBoot).
+//
+// (3) HOW THE DRIVE STILL FAILS IF THE BUG REGRESSES — remove the guard's
+//     short-circuit and the fleet-entry revive bumps cycles (1, not 0) → the
+//     guard assert goes RED; break the cycles++ and the proceed test (expecting 1)
+//     goes RED.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn, spawnSync } from 'node:child_process';
+import { createNode, getNode, subscribe, updateNode, clearPid } from '../canvas/canvas.js';
+import { armFollowUpWork } from '../canvas/human-work-outbox.js';
+import { readInboxSince } from '../feed/inbox.js';
+import { closeDb } from '../canvas/db.js';
+import { buildPiArgv, CANVAS_EXTENSIONS } from '../runtime/launch.js';
+import { CANVAS_INBOX_WATCHER_PATH } from '../runtime/canvas-extensions.js';
+import { headlessBrokerHost } from '../runtime/host.js';
+import { resumeArgs, reviveNode } from '../runtime/revive.js';
+import { REVIVE_KICKOFF_SENTINEL, writeGoal } from '../runtime/kickoff.js';
+import { seedRoadmap } from '../runtime/roadmap.js';
+import { InputError } from '../io.js';
+import { createHarness } from './helpers/harness.js';
+import { bindTestFleet } from './helpers/fleet.js';
+import { resetFleetForTests } from '../runtime/fleet.js';
+const EXTRA_EXTENSION_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', 'fixtures', 'extra-extension.ts');
+let home;
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'developer',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+/** A pid that is guaranteed dead — a crashed broker the guard must NOT see as up. */
+function deadPid() {
+    const r = spawnSync('true', [], { stdio: 'ignore' });
+    return r.pid ?? 0x7ffffffe;
+}
+/** A pid ALIVE for the test but EXPENDABLE — NEVER process.pid: the harness's
+ *  dispose() SIGKILLs every recorded pi_pid, which would take the test runner
+ *  down. A detached `sleep` is the live-engine stand-in; dispose reaps it. */
+const livePids = [];
+function disposableLivePid() {
+    const c = spawn('sleep', ['600'], { stdio: 'ignore', detached: true });
+    c.unref();
+    livePids.push(c.pid);
+    return c.pid;
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-revive-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+    for (const pid of livePids) {
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch {
+            /* already reaped by dispose() — fine */
+        }
+    }
+});
+// ---------------------------------------------------------------------------
+// resumeArgs — the pure resume-source selection
+// ---------------------------------------------------------------------------
+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 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), {});
+});
+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 CYCLES the existing file (same path + newCycle) on a no-resume (refresh) revive', () => {
+    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), { resumeSessionPath: sessionFile, newCycle: true });
+});
+test('resumeArgs selects neither source on a refresh revive with no `.jsonl` on disk yet', () => {
+    const m = node('n', {
+        pi_session_id: 'uuid-123',
+        pi_session_file: join(home, 'refresh-never-written.jsonl'),
+    });
+    assert.deepEqual(resumeArgs(m, false), {});
+});
+// ---------------------------------------------------------------------------
+// buildPiArgv — the `--session` argument the revive builds
+// ---------------------------------------------------------------------------
+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], sessionFile, 'resumes by absolute file path');
+    assert.ok(!argv.includes('uuid-123'), 'the bare uuid is never used to resume');
+});
+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));
+    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' });
+    const { argv } = buildPiArgv(m, { prompt: 'go' });
+    assert.ok(!argv.includes('--session'), 'a fresh launch never resumes');
+    assert.ok(argv.includes('go'), 'the kickoff prompt is the last positional');
+});
+test('buildPiArgv restores mandatory canvas extensions when persisted launch metadata is empty', () => {
+    const m = node('n', {
+        launch: {
+            model: 'openai/sonnet',
+            tools: [],
+            extensions: [],
+            systemPrompt: 'historical replay',
+            env: {},
+        },
+    });
+    const { argv } = buildPiArgv(m, { prompt: 'go' });
+    const seen = new Map();
+    const extensions = [];
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '-e') {
+            const next = argv[i + 1];
+            if (typeof next === 'string') {
+                seen.set(next, (seen.get(next) ?? 0) + 1);
+                extensions.push(next);
+            }
+        }
+    }
+    const required = new Set(CANVAS_EXTENSIONS);
+    const mandatory = [];
+    for (const ext of CANVAS_EXTENSIONS) {
+        mandatory.push(ext);
+        assert.equal(seen.get(ext), 1, `mandatory extension present exactly once: ${ext}`);
+    }
+    assert.deepEqual(extensions.slice(0, required.size), mandatory, 'mandatory extensions are loaded first and once');
+});
+test('buildPiArgv replaces the historical stophook-first prefix without loading old-generation hooks twice', () => {
+    const historicalNames = [
+        'canvas-stophook', 'canvas-inbox-watcher', 'canvas-recap',
+        'canvas-goal-capture', 'canvas-passive-context', 'canvas-context-intro',
+        'canvas-doc-substrate', 'canvas-structured-output', 'canvas-bash-valve',
+    ];
+    const m = node('n', {
+        launch: {
+            model: 'openai/sonnet',
+            tools: [],
+            extensions: [
+                ...historicalNames.map((name) => `/old-generation/pi-extensions/${name}.js`),
+                EXTRA_EXTENSION_PATH,
+            ],
+            systemPrompt: 'historical extension order',
+            env: {},
+        },
+    });
+    const { argv } = buildPiArgv(m, { prompt: 'go' });
+    const extensions = argv.flatMap((arg, index) => arg === '-e' && typeof argv[index + 1] === 'string' ? [argv[index + 1]] : []);
+    assert.deepEqual(extensions, [...CANVAS_EXTENSIONS, EXTRA_EXTENSION_PATH]);
+    assert.equal(extensions.some((path) => path.startsWith('/old-generation/')), false);
+});
+test('buildPiArgv preserves user extensions while deduplicating mandatory hooks', () => {
+    const m = node('n', {
+        launch: {
+            model: 'openai/sonnet',
+            tools: [],
+            extensions: [EXTRA_EXTENSION_PATH, CANVAS_INBOX_WATCHER_PATH],
+            systemPrompt: 'user extras replay',
+            env: {},
+        },
+    });
+    const { argv } = buildPiArgv(m, { prompt: 'go' });
+    const extensions = [];
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '-e') {
+            const next = argv[i + 1];
+            if (typeof next === 'string')
+                extensions.push(next);
+        }
+    }
+    const mandatoryCount = CANVAS_EXTENSIONS.length;
+    assert.equal(extensions.slice(0, mandatoryCount).length, CANVAS_EXTENSIONS.length, 'mandatory extensions are still the boot prefix');
+    for (let i = 0; i < CANVAS_EXTENSIONS.length; i++) {
+        assert.equal(extensions[i], CANVAS_EXTENSIONS[i], `mandatory extension ${i} remains in order`);
+    }
+    assert.equal(extensions.includes(EXTRA_EXTENSION_PATH), true, 'custom extension preserved');
+    assert.equal(extensions.filter((ext) => ext === CANVAS_INBOX_WATCHER_PATH).length, 1, 'mandatory inbox watcher is deduplicated against user list');
+});
+// ---------------------------------------------------------------------------
+// buildPiArgv — the resumed argv replays the persisted launch spec faithfully
+// (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: sessionFile,
+        launch: {
+            model: 'anthropic/sonnet',
+            tools: ['bash', 'read'],
+            extensions: ['/ext/a.js', '/ext/b.js'],
+            systemPrompt: 'You are a developer orchestrator.',
+            env: { FOO: 'bar' },
+        },
+    });
+    createNode(m); // scaffolds the node dir so the system prompt persists to a file
+    const { argv, env } = buildPiArgv(m, resumeArgs(m, true));
+    // Persona extensions, in order.
+    const ea = argv.indexOf('/ext/a.js');
+    const eb = argv.indexOf('/ext/b.js');
+    assert.ok(ea >= 0 && eb > ea, 'extensions replayed in order');
+    assert.equal(argv[ea - 1], '-e');
+    // Model + tools + system prompt + resume target.
+    const mi = argv.indexOf('--model');
+    assert.equal(argv[mi + 1], 'anthropic/sonnet');
+    const ti = argv.indexOf('--tools');
+    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], 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');
+    assert.equal(env['CRTR_KIND'], 'developer');
+    assert.equal(env['CRTR_MODE'], 'orchestrator');
+});
+// ---------------------------------------------------------------------------
+// Double-revive guard — reviveNode no-ops when the node has a live FLEET ENTRY
+// (design D-1: the entry IS liveness). Fabricated as a BROKER node with a
+// fabricated entry registered in the harness's in-process fleet, so the guard
+// is exercised with NO tmux and NO real boot. An entry → guard short-circuits
+// (cycles flat); no entry → revive proceeds (cycles bumped before the launch).
+// ---------------------------------------------------------------------------
+test('reviveNode no-ops when the node has a live fleet entry — double-revive guard', async () => {
+    const h = await createHarness({ headless: true, sessionPrefix: 'crtr-revive-guard' });
+    try {
+        // Register a fabricated fleet entry: this models "another path already
+        // revived it" — `headlessBrokerHost.launch` registers the handle
+        // synchronously, so a live entry means a broker is already on this .jsonl
+        // and re-launching would double-spawn onto it. No pid probe is involved
+        // anywhere — the entry alone is the authority.
+        const M = h.fabricateBrokerNode({
+            status: 'active',
+            intent: null,
+            pi_pid: deadPid(),
+            pi_session_id: 'uuid-1',
+        });
+        h.fleet.register(M, { pid: 424242, exited: new Promise(() => { }) });
+        const before = h.node(M).cycles ?? 0;
+        const res = reviveNode(M, { resume: true });
+        assert.equal(res.resumed, false, 'guard path does not re-resume');
+        assert.equal(h.node(M).cycles ?? 0, before, 'cycle counter NOT bumped (guard returned early)');
+    }
+    finally {
+        await h.dispose();
+    }
+});
+test('reviveNode PROCEEDS when the node has NO fleet entry — cycle counter bumps 0→1', async () => {
+    const h = await createHarness({ headless: true, sessionPrefix: 'crtr-revive-proceed' });
+    try {
+        // A crashed broker: its exit removed its fleet entry (the row's stale dead
+        // pid is mere metadata) → the guard does NOT short-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');
+        const stalePid = deadPid();
+        mkdirSync(join(home, 'sessions'), { recursive: true });
+        writeFileSync(sessionFile, '{}\n', 'utf8');
+        const M = h.fabricateBrokerNode({
+            status: 'active',
+            intent: null,
+            pi_pid: stalePid,
+            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 });
+        const after = h.node(M);
+        assert.equal(after.cycles, 1, 'a real (non-guard) revive bumped the cycle counter to 1');
+        assert.notEqual(after.pi_pid, stalePid, 'revive records the fresh broker pid immediately, not the stale dead pid');
+        assert.equal(after.pi_pid == null ? false : after.pi_pid > 0, true, 'revive leaves no pid=null boot window for the daemon to false-crash');
+    }
+    finally {
+        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 stalePid = deadPid();
+        const M = h.fabricateBrokerNode({
+            status: 'active',
+            intent: null,
+            pi_pid: stalePid,
+            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');
+        assert.notEqual(after.pi_pid, stalePid, 'fresh fallback records the new broker pid immediately');
+        assert.equal(after.pi_pid == null ? false : after.pi_pid > 0, true, 'fresh fallback leaves no pid=null boot window for the daemon to false-crash');
+    }
+    finally {
+        await h.dispose();
+    }
+});
+test('private fork revival uses immutable provenance once, then only its bound child session', () => {
+    const originalLaunch = headlessBrokerHost.launch;
+    // No harness here — bind a standalone in-process fleet so reviveNode's
+    // boundFleet() resolves; the launch stub below registers with it exactly as
+    // the real host does (registration is the launch seam's contract).
+    const tf = bindTestFleet();
+    const privateId = 'private-fork';
+    const forkFile = join(home, 'private-source.jsonl');
+    const childFile = join(home, 'private-child.jsonl');
+    const exactModel = 'openai-codex/gpt-5.3-codex:xhigh';
+    const kickoff = 'private immutable kickoff';
+    const launches = [];
+    try {
+        mkdirSync(home, { recursive: true });
+        writeFileSync(forkFile, '{}\n', 'utf8');
+        createNode(node(privateId, {
+            kind: 'general',
+            cwd: home,
+            fork_from: forkFile,
+            human_work_target: { work_kind: 'follow_up', dir: '/ticket', request_id: 'request-1', root: '/root' },
+            private_fork_phase: 'fork_pending',
+            private_fork_recipe: { kickoff },
+            launch: { model: exactModel, modelExact: true, tools: [], extensions: [], env: {} },
+        }));
+        // reviveNode's locked launch-gate (Major-3) requires a still-armed matching
+        // human-work row before it will launch a private fork — arm one here to
+        // mirror the real handleFollowUpStart/handleVisualStart claim it recheck.
+        armFollowUpWork({ nodeId: privateId, dir: '/ticket', root: '/root', requestId: 'request-1' });
+        headlessBrokerHost.launch = (nodeId, inv) => {
+            launches.push({ argv: [...inv.argv], env: { ...inv.env } });
+            const handle = { pid: disposableLivePid(), exited: new Promise(() => { }) };
+            // Mirror the real host contract: the entry IS liveness (design D-1).
+            tf.fleet.register(nodeId, handle);
+            return handle;
+        };
+        reviveNode(privateId, { resume: false });
+        const pending = launches[0];
+        const forkIndex = pending.argv.indexOf('--fork');
+        assert.equal(pending.argv[forkIndex + 1], forkFile, 'pending claim forks exactly from immutable provenance');
+        assert.equal(pending.argv.at(-1), kickoff, 'pending claim uses its persisted kickoff');
+        assert.equal(pending.argv[pending.argv.indexOf('--model') + 1], exactModel, 'pending claim preserves its exact model');
+        reviveNode(privateId, { resume: false });
+        assert.equal(launches.length, 1, 'live first launch (a live fleet entry) makes a concurrent revive a no-op');
+        writeFileSync(childFile, '{}\n', 'utf8');
+        // Model the first broker's death: its exit removes the fleet entry (and the
+        // stophook clears the recorded pid) — the next revive may proceed.
+        tf.fleet.forget(privateId);
+        clearPid(privateId);
+        updateNode(privateId, {
+            pi_session_id: 'child-session',
+            pi_session_file: childFile,
+            private_fork_phase: 'session_started',
+        });
+        reviveNode(privateId, { resume: false });
+        const started = launches[1];
+        const sessionIndex = started.argv.indexOf('--session');
+        assert.equal(started.argv[sessionIndex + 1], childFile, 'bound claim resumes only its writable child session');
+        assert.equal(started.argv.includes('--fork'), false, 'bound claim never forks provenance again');
+        assert.equal(started.argv.includes(kickoff), false, 'bound claim never replays its one-shot kickoff');
+        assert.equal(started.argv.includes('--crtr-new-cycle'), false, 'bound claim ignores a no-resume request rather than cycling');
+    }
+    finally {
+        headlessBrokerHost.launch = originalLaunch;
+        resetFleetForTests();
+    }
+});
+// Regression for #519: a recorded cwd that no longer exists (e.g. a closed
+// managed worktree whose tombstone dir was later reaped) must fail loud with a
+// typed, user-visible `cwd_missing` error naming the path — not an opaque
+// `[broker] refusing to revive ...: broker host returned no pid` masked as a
+// 500 `internal error` by the daemon's error mapper. The check runs BEFORE
+// the launch try-block, so it must not crash the node or fan a doctrine wake
+// (unlike a genuine launch/preflight failure, covered below) — a caller can
+// fix the cwd and retry without the node first going through 'dead'.
+test('reviveNode throws a typed cwd_missing error and does NOT crash the node when the recorded cwd is gone', async () => {
+    const h = await createHarness({ headless: true, sessionPrefix: 'crtr-revive-cwdmissing' });
+    try {
+        const missingCwd = join(home, 'never-created-cwd');
+        const M = h.fabricateBrokerNode({
+            status: 'active',
+            intent: null,
+            pi_pid: deadPid(),
+        });
+        updateNode(M, { cwd: missingCwd });
+        assert.throws(() => reviveNode(M, { resume: true }), (e) => e instanceof InputError && e.payload.error === 'cwd_missing' && e.message.includes(missingCwd), 'reviveNode must throw a typed InputError naming the missing cwd path');
+        const after = h.node(M);
+        assert.equal(after.status, 'active', 'a cwd-missing preflight refusal must NOT crash the node (fixable in place, not a dead engine)');
+    }
+    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();
+    }
+});
+// ---------------------------------------------------------------------------
+// Crash-to-dead doctrine wake — a launch-refusal marks the node dead; a
+// manager waiting dormant on it must be told, or it hangs forever (the
+// daemon no longer supervises a dead node). Mirrors closeNode's step-4 fan-out.
+// ---------------------------------------------------------------------------
+test('reviveNode fans a doctrine wake to subscribers when launch/preflight throws (crash-to-dead)', async () => {
+    const h = await createHarness({ headless: true, sessionPrefix: 'crtr-revive-crashwake' });
+    const originalLaunch = headlessBrokerHost.launch;
+    try {
+        const root = h.spawnRoot('crash-wake suite root');
+        const sessionFile = join(home, 'sessions', 'crtr-revive-crashwake.jsonl');
+        mkdirSync(join(home, 'sessions'), { recursive: true });
+        writeFileSync(sessionFile, '{}\n', 'utf8');
+        const M = h.fabricateBrokerNode({
+            parent: root,
+            status: 'active',
+            intent: null,
+            pi_pid: deadPid(),
+            pi_session_id: 'uuid-3',
+            pi_session_file: sessionFile,
+        });
+        // spawnChild-equivalent auto-subscription — done explicitly since this node
+        // was fabricated directly, not spawned through the CLI.
+        subscribe(root, M, true);
+        headlessBrokerHost.launch = (_nodeId, _inv, _opts) => { throw new Error('boom'); };
+        assert.throws(() => reviveNode(M, { resume: true }), /refusing to revive/i);
+        assert.equal(h.node(M).status, 'dead', 'failed revive marks the node dead');
+        const entries = readInboxSince(root, undefined);
+        const notice = entries.find((e) => e.data?.['reason'] === 'child-crashed' && e.data?.['child'] === M);
+        assert.ok(notice !== undefined, 'the surviving parent got a doctrine wake for the dead child');
+        assert.equal(notice.from, M, 'the notice is attributed to the crashed child');
+    }
+    finally {
+        headlessBrokerHost.launch = originalLaunch;
+        await h.dispose();
+    }
+});
+// Regression: a daemon restart used to hand an UNSTARTED node the fresh-revive
+// kickoff. pi writes no `.jsonl` until the first turn, so a node the user never
+// messaged has a recorded session path that does not exist on disk → the
+// resume falls through to a fresh launch → the kickoff told it, falsely, that
+// it had lost in-memory context and must rebuild from disk, where there is
+// nothing. It woke, flailed over an empty context dir and reported itself
+// confused. Such a relaunch is a BIRTH: replay the spawn mandate if there is
+// one, else boot promptless and take no turn at all.
+test('an unstarted node relaunches as a birth, not a "revived fresh" kickoff', () => {
+    const originalLaunch = headlessBrokerHost.launch;
+    const tf = bindTestFleet();
+    const launches = [];
+    try {
+        mkdirSync(home, { recursive: true });
+        headlessBrokerHost.launch = (nodeId, inv) => {
+            launches.push([...inv.argv]);
+            const handle = { pid: disposableLivePid(), exited: new Promise(() => { }) };
+            tf.fleet.register(nodeId, handle);
+            return handle;
+        };
+        const missing = join(home, 'sessions', 'never-written.jsonl');
+        // (1) Bare interactive node — nothing on disk anywhere: launch promptless.
+        createNode(node('bare-unstarted', { cwd: home, pi_session_id: 'uuid-a', pi_session_file: missing }));
+        reviveNode('bare-unstarted', { resume: true });
+        const bare = launches[0];
+        assert.equal(bare.some((a) => a.startsWith(REVIVE_KICKOFF_SENTINEL)), false, 'an unstarted node is never told it lost context it never had');
+        assert.deepEqual(bare, buildPiArgv(getNode('bare-unstarted'), {}).argv, 'a promptless boot — the argv carries no trailing prompt positional at all');
+        // (2) Spawned with a mandate whose first turn never persisted: replay it.
+        createNode(node('mandate-unstarted', { cwd: home, pi_session_id: 'uuid-b', pi_session_file: missing }));
+        writeGoal('mandate-unstarted', 'do the thing');
+        reviveNode('mandate-unstarted', { resume: true });
+        assert.equal(launches[1].at(-1), 'do the thing', 'a birth replays the spawn mandate');
+        // (3) Real durable progress on disk → still a genuine fresh revive.
+        createNode(node('progressed', { cwd: home, pi_session_id: 'uuid-c', pi_session_file: missing }));
+        seedRoadmap('progressed', { goal: 'ship it' });
+        reviveNode('progressed', { resume: true });
+        assert.equal(launches[2].at(-1).startsWith(REVIVE_KICKOFF_SENTINEL), true, 'a node with a roadmap still rebuilds from the kickoff');
+    }
+    finally {
+        headlessBrokerHost.launch = originalLaunch;
+        resetFleetForTests();
+    }
+});

package/dist/core/__tests__/scope-crouter-home-fence.test.d.ts

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

package/dist/core/__tests__/scope-crouter-home-fence.test.js

@@ -0,0 +1,55 @@
+// The scope ancestor walk (`collectAncestorScopeRoots` → `findProjectScopeRoots`)
+// must never climb at or above `homedir()`. When HOME is relocated and nested
+// under a directory tree that itself contains a `.crouter/` (a mock-VM home
+// under the real host home, or any relocated-HOME sandbox), the unfenced walk
+// climbs ABOVE homedir() and sweeps in the above-HOME `.crouter` as a bogus
+// "project ancestor" — leaking that host's entire user-global memory store into
+// every nested-HOME node's assembled knowledge/preference catalog. This test
+// pins the fence: an ancestor `.crouter/` sitting ABOVE the relocated HOME must
+// NOT be collected as a project scope root, while a legitimate project
+// `.crouter/` BETWEEN the cwd and HOME still is.
+//
+// Mirrors src/core/__tests__/on-read-crouter-home-fence.test.ts.
+//
+// Run: node --import tsx/esm --test src/core/__tests__/scope-crouter-home-fence.test.ts
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { findProjectScopeRoots, resetScopeCache } from '../scope.js';
+let sandbox;
+let prevHomeEnv;
+before(() => {
+    prevHomeEnv = process.env['HOME'];
+});
+beforeEach(() => {
+    resetScopeCache();
+    // A sandbox that CONTAINS the relocated HOME, so the ancestor walk from a cwd
+    // under HOME can (without the fence) climb above HOME into the sandbox.
+    sandbox = mkdtempSync(join(tmpdir(), 'crtr-scope-fence-'));
+});
+after(() => {
+    resetScopeCache();
+    rmSync(sandbox, { recursive: true, force: true });
+    if (prevHomeEnv === undefined)
+        delete process.env['HOME'];
+    else
+        process.env['HOME'] = prevHomeEnv;
+});
+test('an ancestor .crouter ABOVE a relocated HOME is not collected as a project scope root', () => {
+    // Simulated host user-global store, sitting ABOVE the relocated home.
+    const hostUserRoot = join(sandbox, '.crouter');
+    mkdirSync(join(hostUserRoot, 'memory'), { recursive: true });
+    // The relocated HOME, nested one level under the sandbox.
+    const home = join(sandbox, 'vm-home');
+    process.env['HOME'] = home;
+    // A legitimate project `.crouter/` between the node cwd and HOME.
+    const projectDir = join(home, 'work', 'proj');
+    const projectRoot = join(projectDir, '.crouter');
+    mkdirSync(join(projectRoot, 'memory'), { recursive: true });
+    resetScopeCache();
+    const roots = findProjectScopeRoots(projectDir, null);
+    assert.ok(!roots.includes(hostUserRoot), `above-HOME .crouter must NOT be collected as a project ancestor; got: ${JSON.stringify(roots)}`);
+    assert.ok(roots.includes(projectRoot), `legitimate project .crouter between cwd and HOME must still be collected; got: ${JSON.stringify(roots)}`);
+});

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

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