@crouton-kit/crouter 0.3.27 → 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__/human-stranded-deliver.test.d.ts

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

package/dist/core/__tests__/human-stranded-deliver.test.js

@@ -0,0 +1,108 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/human-stranded-deliver.test.ts
+//
+// BUG REGRESSION (human-ask broker round-trip): a headless-broker asker strips
+// $TMUX, so the detached `crtr human _run` worker — whose `pushFinal` is the SOLE
+// deliver-back + reap step — never spawned. Worse, the `crtr human inbox` drain
+// path writes response.json directly (humanloop's inbox()) and ALSO never calls
+// pushFinal, so an answered deck strands on disk: the asker never learns the
+// answer and the bridge node leaks active forever.
+//
+// This locks the SECONDARY heal: finalizeResolvedInteraction must, for a still-
+// LIVE bridge node whose interaction is resolved on disk, deliver the answer to
+// the asker (parent auto-subscribed) and reap the bridge node — exactly what the
+// _run worker's pushFinal would have done. Idempotent (no double-deliver once
+// done); a canceled-on-disk response reaps without delivering a result.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, subscribe, getNode } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { readInboxSince } from '../feed/inbox.js';
+import { interactionDir, interactionsRoot } from '../artifact.js';
+import { atomicWriteJson, deckPath } from '@crouton-kit/humanloop';
+import { finalizeResolvedInteraction } from '../../commands/human/queue.js';
+let home;
+// A unique cwd so interactionDir (keyed off the REAL homedir + mangled cwd, NOT
+// CRTR_HOME) lands in an isolated, cleanable subtree.
+let workCwd;
+function node(id, parent) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: workCwd,
+        kind: 'developer',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        parent,
+    };
+}
+/** Seed an interaction dir on disk the way the kickoff + a resolution would. */
+function seed(jobId, run, response) {
+    const idir = interactionDir(jobId, workCwd);
+    mkdirSync(idir, { recursive: true });
+    atomicWriteJson(deckPath(idir), { interactions: [] });
+    atomicWriteJson(join(idir, 'run.json'), run);
+    atomicWriteJson(join(idir, 'response.json'), response);
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-stranded-'));
+    process.env['CRTR_HOME'] = home;
+    workCwd = mkdtempSync(join(tmpdir(), 'crtr-stranded-cwd-'));
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    rmSync(interactionsRoot(workCwd), { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    rmSync(interactionsRoot(workCwd), { recursive: true, force: true });
+    rmSync(workCwd, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('answered-but-undelivered ask delivers back to the asker and reaps the bridge', async () => {
+    // Asker A, bridge B under A (parent auto-subscribes to its child bridge).
+    createNode(node('A', null));
+    createNode(node('B', 'A'));
+    subscribe('A', 'B');
+    seed('B', { mode: 'ask', job_id: 'B' }, { responses: [{ id: 'q', selectedOptionId: 'resync', freetext: 'go ahead' }], completedAt: '2026-06-10T22:27:07.000Z' });
+    const acted = await finalizeResolvedInteraction('B');
+    assert.equal(acted, true, 'should have delivered + reaped');
+    // Bridge reaped.
+    assert.equal(getNode('B')?.status, 'done', 'bridge node must be reaped to done');
+    // Answer fanned into the asker's inbox, carrying the choice.
+    const inbox = readInboxSince('A');
+    assert.equal(inbox.length >= 1, true, 'asker inbox must receive the answer pointer');
+    const blob = JSON.stringify(inbox);
+    assert.match(blob, /resync/, 'delivered answer should carry the human selection');
+    // Idempotent: a second sweep is a no-op (node already done — no double-deliver).
+    const again = await finalizeResolvedInteraction('B');
+    assert.equal(again, false, 'must not re-deliver an already-finalized interaction');
+});
+test('a canceled-on-disk response reaps the bridge without delivering a result', async () => {
+    createNode(node('A', null));
+    createNode(node('B', 'A'));
+    subscribe('A', 'B');
+    seed('B', { mode: 'ask', job_id: 'B' }, { canceled: true, canceledAt: '2026-06-10T22:42:04.000Z', reason: 'stale' });
+    const acted = await finalizeResolvedInteraction('B');
+    assert.equal(acted, true);
+    assert.equal(getNode('B')?.status, 'done', 'a canceled stranded bridge must still be reaped');
+    // The asker gets a quiet "no answer is coming" note, not a result.
+    const blob = JSON.stringify(readInboxSince('A'));
+    assert.match(blob, /no answer is coming/);
+});
+test('an unresolved (no response.json) live bridge is left untouched', async () => {
+    createNode(node('A', null));
+    createNode(node('B', 'A'));
+    subscribe('A', 'B');
+    const idir = interactionDir('B', workCwd);
+    mkdirSync(idir, { recursive: true });
+    atomicWriteJson(join(idir, 'run.json'), { mode: 'ask', job_id: 'B' });
+    assert.equal(await finalizeResolvedInteraction('B'), false);
+    assert.equal(getNode('B')?.status, 'active', 'still-pending bridge must stay live');
+});

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.d.ts

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

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

@@ -0,0 +1,81 @@
+// Bug-regression: on-read doc injection "fires a second time per session".
+//
+// The on-read substrate hook dedups so a doc surfaces at most once per
+// conversation. That dedup set USED to live only in the pi process heap (cleared
+// on session_start). But a node's logical session — the .jsonl transcript —
+// spans MULTIPLE pi processes: a dormancy → revive(resume) cycle exits the old
+// process and launches a fresh `pi --session` that REUSES the same transcript.
+// The fresh process started with an empty set, so any doc already injected
+// before dormancy got injected AGAIN on the next read.
+//
+// The fix persists the set to nodes/<id>/injected-docs.json: a resume rehydrates
+// it (dedup holds), and only the FRESH-transcript launch paths clear it. These
+// tests lock in both halves: the store round-trip, and the dedup surviving a
+// simulated revive(resume) while re-surfacing after a fresh launch.
+//
+// Run: node --import tsx/esm --test src/core/__tests__/on-read-dedup-resume.test.ts
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { closeDb } from '../canvas/db.js';
+import { injectedDocsPath } from '../canvas/paths.js';
+import { spawnNode } from '../runtime/nodes.js';
+import { renderOnReadDocs } from '../substrate/on-read.js';
+import { loadInjectedDocs, saveInjectedDocs, clearInjectedDocs, } from '../substrate/injected-store.js';
+const FIXTURE_BODY = 'Fixture body that must surface exactly once.';
+let home;
+let work;
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-onread-home-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    work = mkdtempSync(join(tmpdir(), 'crtr-onread-work-'));
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    rmSync(work, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('injected-store round-trips and clears', () => {
+    const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
+    assert.deepEqual([...loadInjectedDocs(node)], [], 'cold load is empty');
+    saveInjectedDocs(node, new Set(['/a', '/b']));
+    assert.deepEqual([...loadInjectedDocs(node)].sort(), ['/a', '/b'], 'save then load round-trips');
+    clearInjectedDocs(node);
+    assert.ok(!existsSync(injectedDocsPath(node)), 'clear removes the file');
+    assert.deepEqual([...loadInjectedDocs(node)], [], 'load after clear is empty');
+});
+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.
+    const memDir = join(work, '.crouter', 'memory');
+    mkdirSync(memDir, { recursive: true });
+    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`);
+    const readFile = join(work, 'src', 'file.ts');
+    mkdirSync(join(work, 'src'), { recursive: true });
+    writeFileSync(readFile, 'export const x = 1;\n');
+    // --- pi process #1: cold load; first read surfaces the doc ---
+    const seen = loadInjectedDocs(node);
+    const first = renderOnReadDocs(node, readFile, seen);
+    assert.match(first, new RegExp(FIXTURE_BODY.replace(/[.]/g, '\\.')), 'first read surfaces the doc body');
+    saveInjectedDocs(node, seen);
+    // Same process, repeat read of the same file → deduped in-memory.
+    assert.ok(!renderOnReadDocs(node, readFile, seen).includes(FIXTURE_BODY), 'same-process repeat read is deduped');
+    // --- dormancy → revive(resume): NEW process rehydrates the set from disk ---
+    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, 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 {};