@crouton-kit/crouter 0.3.28 → 0.3.29

package/dist/core/__tests__/helpers/harness.js

@@ -28,7 +28,7 @@ import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
 import { createNode, getNode, subscribersOf, subscriptionsOf, } from '../../canvas/canvas.js';
 import { closeDb } from '../../canvas/db.js';
-import { isNodePaneAlive } from '../../runtime/placement.js';
+import { isFocused } from '../../runtime/placement.js';
 import { superviseTick } from '../../../daemon/crtrd.js';
 import { readInboxSince } from '../../feed/inbox.js';
 // --- locations --------------------------------------------------------------
@@ -85,8 +85,7 @@ function cleanBaseEnv() {
     // ~/.crouter / ~/.claude / ~/.pi, NOT under CRTR_HOME — HOME is contained too).
     e['CRTR_NO_BOOTSTRAP'] = '1';
     e['CRTR_NO_AUTO_UPDATE'] = '1';
-    e['CRTR_NO_BOOT_SKILL'] = '1';
-    e['CRTR_NO_MODE_CMDS'] = '1';
+    e['CRTR_NO_EXPORTS'] = '1';
     e['CRTR_NO_AUTO_INIT'] = '1';
     return e;
 }
@@ -161,7 +160,7 @@ export async function createHarness(opts = {}) {
     // home-session.test.ts.) home/ is rmSync'd in dispose.
     writeFileSync(join(home, 'crtrd.pid'), String(process.pid), 'utf8');
     // Pre-create the isolated session on the DEFAULT server so teardown always
-    // has a target and `node new`'s ensureSession no-ops.
+    // has a kill-sessions target.
     // ISOLATION ASSUMPTION (see header + MINOR-6): isolation is by SESSION NAME on
     // the DEFAULT tmux server only. The runtime CLI shells `tmux` with no `-L`, so
     // a custom-socket server (`tmux -L foo`) would be invisible to it; this harness
@@ -169,16 +168,14 @@ export async function createHarness(opts = {}) {
     // server.
     // HEADLESS: skip ALL eager tmux setup. No node in a headless run opens a
     // window, so there is no pane to pre-seed an env into and no session to pre-
-    // create. (`node new --headless` may still lazily ensureSession() the isolated
-    // name for home_session — dispose kill-sessions it regardless.)
+    // create.
     if (!headless) {
         spawnSync('tmux', ['new-session', '-d', '-s', session, '-c', CROUTER, 'sleep 100000'], {
             stdio: 'ignore',
         });
-        // Put CRTR_PI_BINARY in the SESSION environment so EVERY pane spawned in this
-        // session inherits it — critically the fake-pi's OWN process, so when its real
-        // stophook fires reviveInPlace (respawn-pane -k on its own pane, the refresh-
-        // yield path) the in-process piCommand there substitutes the fake-pi too.
+        // Put CRTR_PI_BINARY in the SESSION environment so EVERY pane/process spawned
+        // in this session inherits it — so any pi the runtime launches (boot, revive)
+        // resolves to the fake-pi vehicle, not a real pi.
         spawnSync('tmux', ['set-environment', '-t', session, 'CRTR_PI_BINARY', FAKE_PI_BINARY], {
             stdio: 'ignore',
         });
@@ -310,6 +307,7 @@ export async function createHarness(opts = {}) {
                 lifecycle: o.lifecycle ?? 'terminal',
                 parent: o.parent ?? null,
                 pi_session_id: o.pi_session_id ?? null,
+                pi_session_file: o.pi_session_file ?? null,
                 status: o.status ?? 'active',
                 intent: o.intent ?? null,
                 pi_pid: o.pi_pid ?? null,
@@ -339,7 +337,13 @@ export async function createHarness(opts = {}) {
         },
         async spawnHeadlessChild(parentId, task, o = {}) {
             const before = new Set(nodeDirs());
-            const args = ['node', 'new', task, '--parent', parentId, '--cwd', CROUTER, '--headless'];
+            // POST-CUT: `--headless` is gone — EVERY node is a broker. spawnChild may
+            // still open a background `crtr attach` viewer WINDOW (the §A.3 spawn UX),
+            // but that viewer connects to the broker over view.sock as a SEPARATE
+            // process and never touches the engine — so the broker-socket gates here
+            // (zero-viewer dialogs, controller arbitration, one-writer) are unaffected
+            // by it. The node itself is supervised by pid alone.
+            const args = ['node', 'new', task, '--parent', parentId, '--cwd', CROUTER];
             if (o.kind)
                 args.push('--kind', o.kind);
             if (o.mode)
@@ -358,7 +362,7 @@ export async function createHarness(opts = {}) {
         },
         async spawnHeadlessChildNoBoot(parentId, task, o = {}) {
             const before = new Set(nodeDirs());
-            const args = ['node', 'new', task, '--parent', parentId, '--cwd', CROUTER, '--headless'];
+            const args = ['node', 'new', task, '--parent', parentId, '--cwd', CROUTER];
             if (o.kind)
                 args.push('--kind', o.kind);
             if (o.mode)
@@ -396,27 +400,6 @@ export async function createHarness(opts = {}) {
             await awaitAgentEnd(nodeId, base, `finish agent_end for ${nodeId}`);
             await harness.waitForPaneGone(nodeId);
         },
-        async yieldNode(nodeId, note) {
-            const res = cli(nodeId, ['node', 'yield', note]);
-            if (res.code !== 0) {
-                throw new Error(`yieldNode(${nodeId}): node yield failed (code ${res.code})\n${res.stderr}`);
-            }
-            // node yield set intent=refresh (active, kept). Fire agent_end so the real
-            // (b') branch runs reviveInPlace (respawn-pane -k) IN the fake-pi's pane —
-            // a FRESH fake-pi boots (resume); its session_start clears intent=refresh.
-            const baseBoots = bootCount(nodeId);
-            sendCmd(nodeId, { cmd: 'stop', id: `yield-${Date.now()}` });
-            await waitFor(() => bootCount(nodeId) > baseBoots, {
-                timeoutMs: 30_000,
-                label: `fresh boot after yield for ${nodeId}`,
-            });
-            await waitFor(() => {
-                closeDb();
-                const n = getNode(nodeId);
-                return n?.intent == null && n?.status === 'active';
-            }, { timeoutMs: 20_000, label: `intent=refresh cleared after yield for ${nodeId}` });
-            await harness.awaitBoot(nodeId, { minCount: baseBoots + 1 });
-        },
         async tick(now) {
             closeDb();
             await superviseTick(now);
@@ -461,8 +444,8 @@ export async function createHarness(opts = {}) {
         async waitForPaneGone(nodeId, timeoutMs = 20_000) {
             await waitFor(() => {
                 closeDb();
-                return !isNodePaneAlive(nodeId);
-            }, { timeoutMs, label: `pane gone for ${nodeId}` });
+                return !isFocused(nodeId);
+            }, { timeoutMs, label: `viewer gone for ${nodeId}` });
         },
         waitFor,
         node(nodeId) {
@@ -475,7 +458,7 @@ export async function createHarness(opts = {}) {
         },
         paneAlive(nodeId) {
             closeDb();
-            return isNodePaneAlive(nodeId);
+            return isFocused(nodeId);
         },
         inbox(nodeId) {
             closeDb();

package/dist/core/__tests__/human-node-not-supervised.test.d.ts

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

package/dist/core/__tests__/human-node-not-supervised.test.js

@@ -0,0 +1,83 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/human-node-not-supervised.test.ts
+//
+// BUG REGRESSION (issue #2 — "Headless node can't reach human-ask: human-kind
+// TUI dies at boot"): a headless orchestrator's every `crtr human ask` node died
+// at boot with "pi vehicle exited before the session came up".
+//
+// ROOT CAUSE: a kind:'human' row is NOT a broker-hosted agent node — it is a
+// bookkeeping row for the `crtr human` bridge. Its decision/review TUI runs in a
+// detached `crtr human _run` pane (NOT a pi engine), and the row's lifecycle is
+// driven entirely by that worker's `pushFinal` (or `human cancel`). So it never
+// records a `pi_pid` or `pi_session_id`. After the headless hard-cut made the
+// broker the universal node host, superviseTick supervised EVERY active|idle row
+// as a broker engine: it read the human row (pid==null, session==null) as a
+// never-booted broker, waited out the boot grace, then crash'd it and fired
+// surfaceBootFailure up the spine — killing the human prompt before the person
+// could ever answer.
+//
+// THE FIX: superviseTick drops kind:'human' rows from all three passes. This
+// drives the REAL daemon decision pass against a human row fabricated directly in
+// an isolated home — two ticks spanning well past the boot grace, which is
+// exactly what crashed it before the fix.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, getNode, subscribe } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { readInboxSince } from '../feed/inbox.js';
+import { superviseTick } from '../../daemon/crtrd.js';
+let home;
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-human-not-supervised-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('a kind:"human" bridge row is NEVER boot-failed by the daemon (it has no broker engine)', async () => {
+    // The exact shape spawnNode({kind:'human'}) mints: active, host_kind broker,
+    // but NO pi engine ever booted — so pi_pid and pi_session_id stay null.
+    createNode(node('HUMAN', {
+        kind: 'human',
+        lifecycle: 'terminal',
+        host_kind: 'broker',
+        pi_pid: null,
+        pi_session_id: null,
+        intent: null,
+    }));
+    // The asking node is auto-subscribed to its human bridge node at spawn, so a
+    // surfaceBootFailure (pushUrgent) would land in ASKER's inbox. Give it a booted
+    // session so the daemon leaves IT alone — it is only here to catch a push.
+    createNode(node('ASKER', { status: 'active', pi_session_id: 'booted' }));
+    subscribe('ASKER', 'HUMAN', true);
+    // Two ticks spanning WELL past the boot grace (REVIVE_GRACE_MS): tick 1 would
+    // arm the boot-grace clock, tick 2 (far in the future) would fire the crash +
+    // surfaceBootFailure. This is the precise sequence that killed every human-ask
+    // node before the fix.
+    const t0 = Date.now();
+    await superviseTick(t0);
+    await superviseTick(t0 + 10_000_000);
+    assert.equal(getNode('HUMAN').status, 'active', 'human bridge row stays alive — never crash-reaped as a dead broker');
+    assert.equal(readInboxSince('ASKER').length, 0, 'no surfaceBootFailure urgent push — the asker is never told its human prompt "never started"');
+});

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

@@ -144,28 +144,10 @@ test('revive: any status → active + intent cleared', () => {
     }
 });
 // ---------------------------------------------------------------------------
-// boot → active, intent UNCHANGED (reviveInPlace keeps the refresh safety net),
-// legal only from active|idle
-// ---------------------------------------------------------------------------
-test('boot: active|idle → active, intent preserved (refresh net survives)', () => {
-    for (const from of LIVE) {
-        mk(`n_${from}`, from, 'refresh');
-        const m = transition(`n_${from}`, 'boot');
-        assert.equal(m.status, 'active', `boot from ${from}`);
-        assert.equal(m.intent, 'refresh', `boot from ${from} keeps intent (proof-of-boot net)`);
-    }
-});
-test('boot: illegal from done|dead|canceled → throws', () => {
-    for (const from of TERMINAL) {
-        mk(`n_${from}`, from);
-        assert.throws(() => transition(`n_${from}`, 'boot'), /illegal lifecycle transition/);
-    }
-});
-// ---------------------------------------------------------------------------
 // unknown node → throws for every event
 // ---------------------------------------------------------------------------
 test('transition on an unknown node throws', () => {
-    for (const ev of ['finalize', 'cancel', 'crash', 'yield', 'release', 'revive', 'boot']) {
+    for (const ev of ['finalize', 'cancel', 'crash', 'yield', 'release', 'revive']) {
         assert.throws(() => transition('ghost', ev), /unknown node/);
     }
 });

package/dist/core/__tests__/live-mutation-verbs.test.js

@@ -14,8 +14,8 @@
 //       mints a DIFFERENT fresh general/base/resident root.
 //     • A4: a base→orchestrator yield auto-promotes (mode→orchestrator) and sets
 //       intent=refresh but NEVER commits persona_ack — the drift is left pending
-//       and, because a yield's agent_end goes straight to reviveInPlace with NO
-//       preceding turn_end, the only steer-delivery site is bypassed.
+//       and, because a yield's agent_end goes straight to the refresh-revive with
+//       NO preceding turn_end, the only steer-delivery site is bypassed.
 // (2) WHY MODEL-LEVEL, NOT PANE/WINDOW — demote writes lifecycle on the row
 //     (setLifecycle→updateNode); recycle's FINISH+MINT half is pushFinal +
 //     spawnNode (pure model) — only its pane-respawn is tmux (a deliberately-
@@ -29,7 +29,7 @@
 //     / pending-drift asserts go RED.
 //
 // STOPHOOK CAVEAT — split (option b). The original drove a LIVE fake-pi so the
-// REAL stophook enacted recycle's pane teardown and A4's reviveInPlace ack-drain
+// REAL stophook enacted recycle's viewer teardown and A4's refresh-revive ack-drain
 // at agent_end. Fabrication cannot run those hooks. So: recycle is driven through
 // the real recycleNode (its FINISH+MINT model half runs fully; the pane respawn
 // is the only tmux artifact, intentionally skipped → recycled:false). For A4 the
@@ -117,7 +117,7 @@ test('node demote flips lifecycle→terminal IN PLACE; node recycle is FINISH+RE
 // ===========================================================================
 // (b) A4 BOUNDARY — promote-then-yield emits a steer that is discarded. A
 //     `node yield` on a base node auto-promotes (mode→orchestrator, ack NOT
-//     committed) and its agent_end goes STRAIGHT to reviveInPlace (b') with NO
+//     committed) and its agent_end goes STRAIGHT to the refresh-revive with NO
 //     preceding turn_end — so the only steer-delivery site (turn_end) is
 //     BYPASSED. The deterministic, host-independent facts the yield verb leaves
 //     behind pin the boundary:
@@ -125,7 +125,7 @@ test('node demote flips lifecycle→terminal IN PLACE; node recycle is FINISH+RE
 //       (2) intent=refresh set.
 //       (3) persona_ack STILL base — the verb never commits it (only an injector
 //           or the refresh drain does); the drift is left PENDING.
-//     The ack's silent advance at the refresh drain (reviveInPlace→drainBearings
+//     The ack's silent advance at the refresh drain (refresh-revive→drainBearings
 //     →commitPersonaAck) is locked by persona.test.ts; because no turn_end ever
 //     fires on the yield path, that ack moves WITHOUT the orchestration steer
 //     ever being delivered — the A4 LOSS.

package/dist/core/__tests__/memory-resolver.test.js

@@ -35,7 +35,7 @@ let projectDir;
 let prevCwd;
 const PLUGIN = 'fixplug';
 function doc(name) {
-    return `---\nkind: skill\nwhen-and-why-to-read: fixture doc ${name}\n---\n\n# ${name}\n`;
+    return `---\nkind: knowledge\nwhen-and-why-to-read: fixture doc ${name}\n---\n\n# ${name}\n`;
 }
 before(() => {
     prevCwd = process.cwd();

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

@@ -56,7 +56,7 @@ test('on-read doc surfaces once, stays deduped across a revive(resume), re-surfa
     // A positional substrate doc in a `.crouter/memory/` ancestor of the read file.
     const memDir = join(work, '.crouter', 'memory');
     mkdirSync(memDir, { recursive: true });
-    writeFileSync(join(memDir, 'onread-fixture.md'), '---\nkind: reference\n' +
+    writeFileSync(join(memDir, 'onread-fixture.md'), '---\nkind: knowledge\n' +
         'when-and-why-to-read: When reading work files, this reference should be read because it is the on-read regression fixture\n' +
         'file-read-visibility: content\n---\n' +
         `${FIXTURE_BODY}\n`);
@@ -74,7 +74,7 @@ test('on-read doc surfaces once, stays deduped across a revive(resume), re-surfa
     const seenAfterRevive = loadInjectedDocs(node);
     assert.deepEqual(seenAfterRevive, seen, 'revive(resume) rehydrates the persisted dedup set');
     assert.ok(!renderOnReadDocs(node, readFile, seenAfterRevive).includes(FIXTURE_BODY), 'resumed process does NOT re-inject the doc (the bug)');
-    // --- fresh launch (revive resume=false / reviveInPlace) clears the set ---
+    // --- fresh launch (revive resume=false, e.g. a refresh-yield) clears the set ---
     clearInjectedDocs(node);
     const seenFresh = loadInjectedDocs(node);
     assert.ok(renderOnReadDocs(node, readFile, seenFresh).includes(FIXTURE_BODY), 'a fresh transcript surfaces the doc again');

package/dist/core/__tests__/refresh-stall-recycle.test.d.ts

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

package/dist/core/__tests__/refresh-stall-recycle.test.js

@@ -0,0 +1,88 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/refresh-stall-recycle.test.ts
+//
+// BUG-REGRESSION (broker-universal-host cut, design §H refresh-authority; U7
+// report mq8gq8we-4cadd8e6; stuck-refresh, parent mq7s5o93). A `node yield` /
+// refresh records intent='refresh' and relies on the in-process stophook to call
+// shutdown at stop. But the engine can be left ALIVE forever — it hangs at a huge
+// context, OR a STALE in-process stophook (pi extensions never reload, so a
+// days-old resident carries an old hook) ignores intent='refresh' and never calls
+// shutdown. Engine alive + turn over + intent pending forever. The daemon only
+// revives DEAD engines, so without §H the node is permanently stuck. The DAEMON
+// is the authority: when intent='refresh' persists on a LIVE engine whose turn is
+// over, past YIELD_STALL_GRACE_MS, it force-kills the engine (SIGTERM) so the
+// dead-pid refresh path then revives it fresh.
+//
+// Two legs: the pure truth table (D4a — yieldStallVerdict) and the daemon
+// integration over a real live pid the daemon must SIGTERM (D4b — superviseTick
+// with an injected clock). Regression check: drop §H and D4b's "engine killed"
+// assert goes RED (the live refresh pid lives forever, never recycled).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { createHeadlessHarness } from './helpers/harness.js';
+import { yieldStallVerdict, YIELD_STALL_GRACE_MS, isPidAlive } from '../../daemon/crtrd.js';
+// ---------------------------------------------------------------------------
+// D4a — the pure refresh-stall truth table.
+// ---------------------------------------------------------------------------
+test('D4a yieldStallVerdict: kill ONLY a live, not-busy, refresh engine past the grace', () => {
+    const G = YIELD_STALL_GRACE_MS;
+    // The one 'kill' case: engine alive, intent=refresh, turn over (not busy), past grace.
+    assert.equal(yieldStallVerdict(true, 'refresh', false, G), 'kill', 'alive+refresh+!busy+>=grace → kill');
+    assert.equal(yieldStallVerdict(true, 'refresh', false, G + 60_000), 'kill', 'well past grace → kill');
+    // Within the grace → pending (the healthy stophook window).
+    assert.equal(yieldStallVerdict(true, 'refresh', false, null), 'pending', 'first observation → pending');
+    assert.equal(yieldStallVerdict(true, 'refresh', false, G - 1), 'pending', 'within grace → pending');
+    // A working engine is NEVER killed, even past the grace.
+    assert.equal(yieldStallVerdict(true, 'refresh', true, G + 60_000), 'leave', 'busy (mid-turn) → leave');
+    // Not a refresh → not our concern.
+    assert.equal(yieldStallVerdict(true, 'idle-release', false, G + 60_000), 'leave', 'intent≠refresh → leave');
+    assert.equal(yieldStallVerdict(true, null, false, G + 60_000), 'leave', 'no pending intent → leave');
+    // A dead/unknown pid is the ordinary revive path's job, not this one.
+    assert.equal(yieldStallVerdict(false, 'refresh', false, G + 60_000), 'leave', 'dead pid → leave (dead-pid path owns it)');
+    assert.equal(yieldStallVerdict(null, 'refresh', false, G + 60_000), 'leave', 'unknown pid → leave');
+});
+// ---------------------------------------------------------------------------
+// D4b — daemon integration: a stuck refresh on a LIVE engine is force-recycled.
+// ---------------------------------------------------------------------------
+const T0 = 7_000_000;
+const T_KILL = T0 + YIELD_STALL_GRACE_MS + 1; // one ms past the grace from t0
+test('D4b daemon force-recycles a stuck refresh: a live, not-busy refresh engine past the grace is SIGTERM\'d', { timeout: 30_000 }, async () => {
+    const h = await createHeadlessHarness({ sessionPrefix: 'crtr-d4b' });
+    // A real live subprocess standing in for the hung/stale-hook engine. `sleep`
+    // dies on SIGTERM, so the daemon's force-kill is directly observable.
+    const child = spawn('sleep', ['300'], { stdio: 'ignore' });
+    const enginePid = child.pid;
+    try {
+        assert.equal(isPidAlive(enginePid), true, 'precondition: the refresh engine is alive');
+        // intent='refresh' + LIVE pid + turn over (no busy marker by default) →
+        // the §H stall state the daemon must break.
+        const id = h.fabricateBrokerNode({
+            kind: 'developer',
+            status: 'active',
+            intent: 'refresh',
+            pi_pid: enginePid,
+            pi_session_id: 'sess-d4b',
+        });
+        assert.equal(h.node(id).intent, 'refresh', 'precondition: intent=refresh pending');
+        // --- TICK @ t0: arms the stall clock (yieldStallSince). No kill yet. ---
+        await h.tick(T0);
+        assert.equal(isPidAlive(enginePid), true, 'within grace: the engine is NOT killed (clock just armed)');
+        // --- TICK past the grace: the daemon concludes the refresh stalled and
+        //     SIGTERMs the engine itself (§H force-recycle). ---
+        await h.tick(T_KILL);
+        await h.waitFor(() => (isPidAlive(enginePid) ? null : true), {
+            label: 'daemon SIGTERM killed the stuck refresh engine',
+            timeoutMs: 10_000,
+        });
+        assert.equal(isPidAlive(enginePid), false, 'past grace: the daemon force-killed the stuck refresh engine (§H)');
+    }
+    finally {
+        try {
+            child.kill('SIGKILL');
+        }
+        catch {
+            /* already gone */
+        }
+        await h.dispose();
+    }
+});

package/dist/core/__tests__/relaunch-root.test.d.ts

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

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

@@ -0,0 +1,114 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/relaunch-root.test.ts
+//
+// Bug regression (commit 07e704e, "broker becomes universal host"): `/new` on a
+// ROOT used to do an in-place SAME-id reset (resetRoot reaped + wiped + re-pointed
+// the same node id) instead of starting a genuinely new node. Model B fixes it:
+// relaunchRoot parks the old root `done` (kept as history, NOT canceled) and mints
+// a FRESH node id + broker, re-pointing the viewer pane. These tests lock in that
+// behavior via the injectable deps seam, so they run tmux-free and broker-free.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, getNode, subscribe } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { relaunchRoot } from '../runtime/reset.js';
+let home;
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+/** A tmux-free / broker-free deps seam. `pid` controls the new broker launch:
+ *  a number = success, null = a boot failure. Records the node ids launchBroker
+ *  was called with, so the boot-failure test can find the half-born new node. */
+function makeDeps(pid) {
+    const launched = [];
+    const deps = {
+        launchBroker: (nodeId) => {
+            launched.push(nodeId);
+            return { pid };
+        },
+        waitForViewSocket: () => true,
+        respawnViewer: () => true,
+        teardownBroker: () => { },
+    };
+    return { deps, launched };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-relaunch-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('relaunchRoot parks the old root done and mints a fresh active root, reaping descendants', () => {
+    // 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' }));
+    createNode(node('grand', { parent: 'child' }));
+    subscribe('root', 'child', true);
+    subscribe('child', 'grand', true);
+    const { deps, launched } = makeDeps(4242);
+    const res = 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;
+    assert.notEqual(newId, 'root', 'a genuinely NEW node id (not a same-id reset — the bug)');
+    assert.deepEqual(launched, [newId], 'the new node id is the one we booted a broker for');
+    // (1) Old root parked DONE — kept as history, NOT canceled (explicit CTO call).
+    assert.equal(getNode('root')?.status, 'done', 'old root parked done (kept as history)');
+    // (2) The new node is an active, top-level resident inheriting the old root's
+    //     kind + cwd.
+    const fresh = getNode(newId);
+    assert.equal(fresh?.status, 'active', 'new node is active');
+    assert.equal(fresh?.parent, null, 'new node is a root (no spine parent)');
+    assert.equal(fresh?.kind, 'general', 'new node inherits the old root kind');
+    assert.equal(fresh?.cwd, '/tmp/proj', 'new node inherits the old root cwd');
+    assert.equal(fresh?.lifecycle, 'resident', 'a relaunched root is resident');
+    // (3) Descendants reaped → canceled (A5: an externally-reaped node did not
+    //     finish its OWN work; done is reserved for finalize).
+    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', () => {
+    // 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);
+    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');
+    assert.equal(getNode('child')?.status, 'active', 'descendant left active + untouched');
+    // The half-born new node was crashed (so the daemon never watches a zombie).
+    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', () => {
+    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.deepEqual(launched, [], 'no broker was booted for any of the no-op cases');
+});