@crouton-kit/crouter 0.3.20 → 0.3.22

package/dist/core/__tests__/child-death-wake.test.js

@@ -1,39 +1,46 @@
 // Run with: node --import tsx/esm --test src/core/__tests__/child-death-wake.test.ts
 //
-// D-1 BUG REGRESSION + node/canvas LIFECYCLE — "the runtime wakes a dormant
-// parent on ANY terminal child outcome."
+// HEADLESS RETARGET (foundation-spec §C.7 + §E). D-1 BUG REGRESSION — "the
+// runtime wakes a dormant parent on EVERY terminal child outcome, and ONLY on a
+// genuine one." Drives the REAL daemon decision pass (superviseTick) + the REAL
+// closeNode against canvas rows fabricated DIRECTLY in an isolated home — NO real
+// tmux session, NO remain-on-exit pane, NO broker boot.
 //
-// The bug (D-1 finding, context/d1-finding.md): a parent that delegates and
-// then JUST STOPS — retaining its inbox-wait, arming no self-wake — was woken
-// ONLY when a child `push final`s or never boots. A child that crashes AFTER
-// booting, is daemon-finalized after a quiet turn, or is `node close`d marked
-// the child dead/done/canceled with NO push to the parent, so a purely-inbox-
-// waiting parent hung dormant forever. The wake doctrine ("delegate and stop;
-// the runtime wakes you") is only honest if EVERY terminal child outcome reaches
-// the parent — this locks that in.
+// (1) BUG LOCKED — the D-1 finding (context/d1-finding.md): a parent that
+//     delegated and then JUST STOPPED (inbox-wait retained, no self-wake armed)
+//     was woken ONLY when a child `push final`d or never booted. A child that
+//     CRASHED after booting, was daemon-FINALIZED on a quiet turn, or was `node
+//     close`d marked the child dead/done/canceled with NO push to the parent — so
+//     a purely-inbox-waiting parent hung dormant forever. The fix fans a system
+//     inbox entry to subscribersOf(child) on those three previously-silent
+//     terminal outcomes (surfaceChildDeath crash/finalize + close.ts), mirroring
+//     surfaceBootFailure. THE CRUX: it must fire ONLY on genuine death — NEVER on
+//     healthy dormancy (a child that ended its turn still awaiting a LIVE
+//     grandchild, or holding a pending self-wake, is alive-and-dormant; waking its
+//     parent then re-creates the spurious-wake storm the doctrine exists to kill).
 //
-// The fix fans a system inbox entry to subscribersOf(child) on three previously-
-// silent terminal outcomes — mirroring surfaceBootFailure:
-//   • daemon CRASH after boot   (crtrd pane-gone, mid-generation → 'dead')
-//   • daemon FINALIZE on quiet   (crtrd pane-gone, turn ended, nothing live → 'done')
-//   • `node close`               (close.ts, the surviving manager outside the set)
+// (2) WHY MODEL-LEVEL, NOT TMUX CHROME — the wake travels through ONE pure
+//     data-layer channel the d1-finding identified: a system entry appended to
+//     the parent's inbox.jsonl (push() → appendInbox, no tmux). The death-vs-
+//     dormancy boundary is pure daemon logic — finishedTurn (isBusy) +
+//     hasActiveLiveSubscription || hasPendingSelfWake, the SAME boundary the
+//     stop-guard draws (crtrd.ts). The daemon reaches the pane-gone routing for
+//     ANY node whose pane is not alive; a row carrying a bogus pane id reads
+//     "gone" (paneExists echoes empty for an unknown/absent pane — and with no
+//     tmux server at all, the probe simply fails to false) with NO live session
+//     to stand up. So the exact "booted child, pane gone, branch on what it was
+//     doing" state reproduces with no real pane, and the parent stays an inline
+//     node (no placement → the supervise loop's inline-root carve-out skips it),
+//     so nothing in the test opens or needs a window.
 //
-// THE CRUX (the whole risk): the wake must fire ONLY on genuine death/close —
-// NEVER on healthy dormancy. A child that ended its turn STILL waiting (an active
-// live grandchild, or a pending self-wake) is alive-and-dormant, not dead; waking
-// its parent then would re-create the spurious-wake storm the doctrine exists to
-// kill (the concrete case: a developer child that finished its edits, spawned its
-// own reviewer, and went dormant waiting on it — its parent must stay asleep).
-// The daemon draws that boundary EXACTLY where the stop-guard does:
-// hasActiveLiveSubscription || hasPendingSelfWake ⇒ healthy dormancy ⇒ release,
-// no wake.
-//
-// Faithful: REAL canvas data layer, REAL tmux panes, the REAL daemon decision
-// pass (superviseTick) and the REAL closeNode. The wake travels through the ONE
-// channel the d1-finding identified — an entry appended to the parent's
-// inbox.jsonl — so each direction asserts that channel: the system entry appears
-// (parent woken: its dormant pi is then revived by the daemon's second pass,
-// observed via a cycles bump) or it does NOT (parent stays asleep, cycles flat).
+// (3) HOW THE FABRICATED DRIVE STILL FAILS IF THE BUG REGRESSES — each direction
+//     asserts the inbox channel: a genuine terminal outcome (crash/finalize/close)
+//     MUST land a system entry from the child in the parent's inbox; healthy
+//     dormancy MUST leave it empty. Drop the crash-branch surfaceChildDeath call
+//     and the CRASH assertion goes RED (no entry); drop the stillWaiting guard and
+//     a healthy-dormant child finalizes → the CRUX asserts go RED (a spurious
+//     entry appears). Verified by reverting the crash-branch surfaceChildDeath
+//     call (see bug-injection report).
 import { test, before, after, beforeEach } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdtempSync, rmSync } from 'node:fs';
@@ -61,15 +68,39 @@ function node(id, over = {}) {
         ...over,
     };
 }
-function hasTmux() {
-    return spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0;
-}
 /** A pid that is guaranteed dead. */
 function deadPid() {
     const r = spawnSync('true', [], { stdio: 'ignore' });
     return r.pid ?? 0x7ffffffe;
 }
-const cyclesOf = (id) => getNode(id)?.cycles ?? 0;
+// A pane id no tmux server knows: paneExists echoes empty for it → isNodePaneAlive
+// is false → the supervise loop routes the row down its pane-gone branch with NO
+// live session required (and with no server at all the probe fails to false too).
+const GONE_PANE = '%999999';
+/** A booted child whose pane is GONE — the daemon's pane-gone routing input.
+ *  `intent:null` so it takes the user-close branch (neither refresh nor
+ *  idle-release); pi dead so the zombie-kill is skipped; pi_session_id set so it
+ *  is "booted" (not the never-booted boot-failure leg). The caller layers on the
+ *  busy marker / subscriptions that decide crash vs finalize vs release. */
+function paneGoneChild(id, over = {}) {
+    createNode(node(id, {
+        pane: GONE_PANE,
+        tmux_session: 'crtr-cdw',
+        window: '@1',
+        pi_pid: deadPid(),
+        pi_session_id: 'booted',
+        intent: null,
+        status: 'active',
+        ...over,
+    }));
+}
+/** A dormant inbox-waiting PARENT — an INLINE node (no tmux placement), so the
+ *  supervise loop's inline-root carve-out skips it entirely: it is only the wake
+ *  TARGET, asserted via its inbox. */
+function inboxWaitingParent(id) {
+    createNode(node(id, { status: 'active' }));
+}
+const wakeFromChild = (parent, child) => readInboxSince(parent).find((e) => e.from === child);
 before(() => {
     home = mkdtempSync(join(tmpdir(), 'crtr-child-death-wake-'));
     process.env['CRTR_HOME'] = home;
@@ -83,163 +114,80 @@ after(() => {
     rmSync(home, { recursive: true, force: true });
     delete process.env['CRTR_HOME'];
 });
-/** Run `fn` with a real, live tmux session + its window's live `%pane_id`. The
- *  PARENT occupies this (frozen) pane while pi-dead + idle-released — the
- *  faithful shape of an unfocused dormant orchestrator the daemon's second pass
- *  revives on an unseen inbox entry. */
-async function withLivePane(tag, fn) {
-    const session = `crtr-cdw-${process.pid}-${tag}`;
-    spawnSync('tmux', ['new-session', '-d', '-s', session, '-c', '/tmp', 'sleep 600']);
-    try {
-        const w = spawnSync('tmux', ['list-windows', '-t', session, '-F', '#{window_id}'], { encoding: 'utf8' });
-        const window = (w.stdout ?? '').trim().split('\n')[0];
-        const p = spawnSync('tmux', ['display-message', '-p', '-t', `${session}:${window}`, '#{pane_id}'], { encoding: 'utf8' });
-        const pane = (p.stdout ?? '').trim();
-        await fn(session, window, pane);
-    }
-    finally {
-        spawnSync('tmux', ['kill-session', '-t', session], { stdio: 'ignore' });
-    }
-}
-/** A guaranteed-DEAD pane id inside `window`: split a fresh pane, then kill it.
- *  The window survives via its original pane. This is how a child's pane reads
- *  "gone" to the daemon while the session/window are still alive. */
-function deadPaneIn(session, window) {
-    const sp = spawnSync('tmux', ['split-window', '-d', '-P', '-F', '#{pane_id}', '-t', `${session}:${window}`, 'sleep 600'], { encoding: 'utf8' });
-    const dead = (sp.stdout ?? '').trim();
-    spawnSync('tmux', ['kill-pane', '-t', dead], { stdio: 'ignore' });
-    return dead;
-}
-/** A dormant, unfocused PARENT: pi-dead, idle-released, frozen on the live pane,
- *  home_session set so the daemon's second pass can revive it. */
-function dormantParent(id, session, window, pane) {
-    createNode(node(id, {
-        pane,
-        tmux_session: session,
-        window,
-        pi_pid: deadPid(),
-        pi_session_id: 'booted',
-        intent: 'idle-release',
-        status: 'idle',
-        home_session: session,
-    }));
-}
 // ===========================================================================
-// POSITIVE — a genuine terminal child outcome WAKES the dormant parent.
+// POSITIVE — a genuine terminal child outcome WAKES the inbox-waiting parent.
 // ===========================================================================
-test('CRASH after boot (mid-generation, pane gone) wakes the dormant inbox-waiting parent', { skip: !hasTmux() ? 'tmux unavailable' : false, timeout: 60_000 }, async () => {
-    await withLivePane('crash', async (session, window, pane) => {
-        dormantParent('PARENT', session, window, pane);
-        const dead = deadPaneIn(session, window);
-        createNode(node('CHILD', {
-            pane: dead, tmux_session: session, window,
-            pi_pid: deadPid(), pi_session_id: 'booted', intent: null, status: 'active',
-        }));
-        subscribe('PARENT', 'CHILD', true); // the spawn-time spine edge
-        markBusy('CHILD'); // pane died INSIDE a turn → genuine mid-run crash
-        const before = cyclesOf('PARENT');
-        await superviseTick();
-        assert.equal(getNode('CHILD').status, 'dead', 'CHILD crashed → dead');
-        // THE WAKE CHANNEL: a system entry from CHILD lands in PARENT's inbox.
-        const wake = readInboxSince('PARENT').find((e) => e.from === 'CHILD');
-        assert.ok(wake, 'crash fanned a system inbox entry to the dormant parent (mirrors surfaceBootFailure)');
-        assert.match(wake.label, /died/i, 'the entry tells the parent WHICH child died and how');
-        // END-TO-END: the dormant parent is REVIVED on the same tick (second pass).
-        assert.equal(cyclesOf('PARENT'), before + 1, 'dormant PARENT revived on the same tick — no longer hangs');
-        clearBusy('CHILD');
-    });
+test('CRASH after boot (mid-generation, pane gone) wakes the inbox-waiting parent', async () => {
+    inboxWaitingParent('PARENT');
+    paneGoneChild('CHILD');
+    subscribe('PARENT', 'CHILD', true); // the spawn-time spine edge
+    markBusy('CHILD'); // pane died INSIDE a turn → genuine mid-run crash
+    await superviseTick();
+    assert.equal(getNode('CHILD').status, 'dead', 'CHILD crashed → dead');
+    // THE WAKE CHANNEL: a system entry from CHILD lands in PARENT's inbox.
+    const wake = wakeFromChild('PARENT', 'CHILD');
+    assert.ok(wake, 'crash fanned a system inbox entry to the dormant parent (mirrors surfaceBootFailure)');
+    assert.match(wake.label, /died/i, 'the entry tells the parent WHICH child died and how');
+    clearBusy('CHILD');
 });
-test('quiet-turn FINALIZE (pane gone, nothing live to wait for) wakes the dormant parent', { skip: !hasTmux() ? 'tmux unavailable' : false, timeout: 60_000 }, async () => {
-    await withLivePane('finalize', async (session, window, pane) => {
-        dormantParent('PARENT', session, window, pane);
-        const dead = deadPaneIn(session, window);
-        // Booted, turn finished (NO busy marker), no live subscription, no pending
-        // self-wake → the daemon finalizes it (done): a dismissal of a finished node.
-        createNode(node('CHILD', {
-            pane: dead, tmux_session: session, window,
-            pi_pid: deadPid(), pi_session_id: 'booted', intent: null, status: 'active',
-        }));
-        subscribe('PARENT', 'CHILD', true);
-        const before = cyclesOf('PARENT');
-        await superviseTick();
-        assert.equal(getNode('CHILD').status, 'done', 'CHILD finalized → done');
-        const wake = readInboxSince('PARENT').find((e) => e.from === 'CHILD');
-        assert.ok(wake, 'finalize fanned a system inbox entry to the dormant parent');
-        assert.match(wake.label, /without a final report/i, 'the entry tells the parent the child ended with no final');
-        assert.equal(cyclesOf('PARENT'), before + 1, 'dormant PARENT revived on the same tick');
-    });
+test('quiet-turn FINALIZE (pane gone, nothing live to wait for) wakes the inbox-waiting parent', async () => {
+    inboxWaitingParent('PARENT');
+    // Booted, turn finished (NO busy marker), no live subscription, no pending
+    // self-wake → the daemon finalizes it (done): a dismissal of a finished node.
+    paneGoneChild('CHILD');
+    subscribe('PARENT', 'CHILD', true);
+    await superviseTick();
+    assert.equal(getNode('CHILD').status, 'done', 'CHILD finalized → done');
+    const wake = wakeFromChild('PARENT', 'CHILD');
+    assert.ok(wake, 'finalize fanned a system inbox entry to the dormant parent');
+    assert.match(wake.label, /without a final report/i, 'the entry tells the parent the child ended with no final');
 });
-test('node close of a child wakes its SURVIVING manager (the parent outside the closing set)', { skip: !hasTmux() ? 'tmux unavailable' : false, timeout: 60_000 }, async () => {
-    await withLivePane('close', async (session, window, pane) => {
-        dormantParent('PARENT', session, window, pane);
-        const childPane = deadPaneIn(session, window); // any pane handle; closeNode tears it down
-        createNode(node('CHILD', {
-            pane: childPane, tmux_session: session, window,
-            pi_session_id: 'booted', status: 'active',
-        }));
-        subscribe('PARENT', 'CHILD', true); // PARENT is a manager OUTSIDE the close set
-        // Closing CHILD: closingSet({CHILD}) cannot pull in PARENT (PARENT is a
-        // SUBSCRIBER of CHILD, never a descendant), so PARENT survives + must wake.
-        const res = closeNode('CHILD');
-        assert.deepEqual(res.closed, ['CHILD'], 'only CHILD is closed; PARENT spared');
-        assert.equal(getNode('CHILD').status, 'canceled', 'CHILD canceled by close');
-        const wake = readInboxSince('PARENT').find((e) => e.from === 'CHILD');
-        assert.ok(wake, 'node close fanned a child-closed entry to the surviving manager (D-1: previously none)');
-        assert.match(wake.label, /closed/i, 'the entry names the closed child');
-        // The dormant parent is then revived by the daemon's second pass.
-        const before = cyclesOf('PARENT');
-        await superviseTick();
-        assert.equal(cyclesOf('PARENT'), before + 1, 'dormant PARENT revived on the close entry — no longer hangs');
-    });
+test('node close of a child wakes its SURVIVING manager (the parent outside the closing set)', async () => {
+    inboxWaitingParent('PARENT');
+    // A booted child; closeNode tears its (paneless-for-the-test) engine down.
+    createNode(node('CHILD', { pane: GONE_PANE, tmux_session: 'crtr-cdw', window: '@1', pi_session_id: 'booted', status: 'active' }));
+    subscribe('PARENT', 'CHILD', true); // PARENT is a manager OUTSIDE the close set
+    // Closing CHILD: closingSet({CHILD}) cannot pull in PARENT (PARENT is a
+    // SUBSCRIBER of CHILD, never a descendant), so PARENT survives + must wake.
+    const res = closeNode('CHILD');
+    assert.deepEqual(res.closed, ['CHILD'], 'only CHILD is closed; PARENT spared');
+    assert.equal(getNode('CHILD').status, 'canceled', 'CHILD canceled by close');
+    const wake = wakeFromChild('PARENT', 'CHILD');
+    assert.ok(wake, 'node close fanned a child-closed entry to the surviving manager (D-1: previously none)');
+    assert.match(wake.label, /closed/i, 'the entry names the closed child');
 });
 // ===========================================================================
 // NEGATIVE — HEALTHY DORMANCY must NOT wake the parent (the correctness crux).
 // ===========================================================================
-test('CRUX: a child dormant while awaiting its OWN live grandchild does NOT wake the parent', { skip: !hasTmux() ? 'tmux unavailable' : false, timeout: 60_000 }, async () => {
-    await withLivePane('dorm-sub', async (session, window, pane) => {
-        dormantParent('PARENT', session, window, pane);
-        const dead = deadPaneIn(session, window);
-        // CHILD finished its turn (no busy) and its pane is gone, BUT it actively
-        // subscribes to a LIVE grandchild — exactly the developer-spawned-reviewer
-        // case. This is HEALTHY dormancy, not death.
-        createNode(node('CHILD', {
-            pane: dead, tmux_session: session, window,
-            pi_pid: deadPid(), pi_session_id: 'booted', intent: null, status: 'active',
-        }));
-        createNode(node('GRANDCHILD', { status: 'active', pi_session_id: 'booted' })); // live, no pane (inline)
-        subscribe('PARENT', 'CHILD', true);
-        subscribe('CHILD', 'GRANDCHILD', true); // CHILD awaits a LIVE grandchild
-        const before = cyclesOf('PARENT');
-        await superviseTick();
-        // CHILD is RELEASED (revivable), NOT finalized — the daemon must not orphan
-        // its in-flight grandchild and must not wake the parent.
-        assert.equal(getNode('CHILD').status, 'idle', 'CHILD released (revivable), NOT finalized');
-        assert.equal(getNode('CHILD').intent, 'idle-release', 'CHILD routed to idle-release');
-        assert.equal(readInboxSince('PARENT').length, 0, 'PARENT inbox EMPTY — healthy dormancy raises no wake');
-        assert.equal(cyclesOf('PARENT'), before, 'dormant PARENT stays asleep (no revive) — no spurious wake');
-    });
+test('CRUX: a child dormant while awaiting its OWN live grandchild does NOT wake the parent', async () => {
+    inboxWaitingParent('PARENT');
+    // CHILD finished its turn (no busy) and its pane is gone, BUT it actively
+    // subscribes to a LIVE grandchild — exactly the developer-spawned-reviewer
+    // case. This is HEALTHY dormancy, not death.
+    paneGoneChild('CHILD');
+    createNode(node('GRANDCHILD', { status: 'active', pi_session_id: 'booted' })); // live, inline
+    subscribe('PARENT', 'CHILD', true);
+    subscribe('CHILD', 'GRANDCHILD', true); // CHILD awaits a LIVE grandchild
+    await superviseTick();
+    // CHILD is RELEASED (revivable), NOT finalized — the daemon must not orphan
+    // its in-flight grandchild and must not wake the parent.
+    assert.equal(getNode('CHILD').status, 'idle', 'CHILD released (revivable), NOT finalized');
+    assert.equal(getNode('CHILD').intent, 'idle-release', 'CHILD routed to idle-release');
+    assert.equal(readInboxSince('PARENT').length, 0, 'PARENT inbox EMPTY — healthy dormancy raises no wake');
 });
-test('CRUX: a child dormant on a pending self-wake (no live sub) does NOT wake the parent', { skip: !hasTmux() ? 'tmux unavailable' : false, timeout: 60_000 }, async () => {
-    await withLivePane('dorm-wake', async (session, window, pane) => {
-        dormantParent('PARENT', session, window, pane);
-        const dead = deadPaneIn(session, window);
-        createNode(node('CHILD', {
-            pane: dead, tmux_session: session, window,
-            pi_pid: deadPid(), pi_session_id: 'booted', intent: null, status: 'active',
-        }));
-        subscribe('PARENT', 'CHILD', true);
-        // CHILD has NO live subscription, but holds a pending self-wake (far-future
-        // so the wakeups pass never fires it this tick). hasPendingSelfWake(CHILD)
-        // ⇒ the daemon treats it as STILL WAITING (the stop-guard's boundary), so
-        // it RELEASES instead of finalizing. NON-VACUOUS: drop the hasPendingSelfWake
-        // guard and CHILD finalizes → PARENT is spuriously woken.
-        const future = new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toISOString();
-        armWake({ wakeup_id: 'wk-cdw-child', node_id: 'CHILD', owner_id: 'CHILD', fire_at: future, kind: 'bare' });
-        const before = cyclesOf('PARENT');
-        await superviseTick();
-        assert.equal(getNode('CHILD').status, 'idle', 'CHILD with a pending self-wake is RELEASED, not finalized');
-        assert.equal(getNode('CHILD').intent, 'idle-release', 'CHILD routed to idle-release (its clock will wake it)');
-        assert.equal(readInboxSince('PARENT').length, 0, 'PARENT inbox EMPTY — a pending clock is healthy dormancy');
-        assert.equal(cyclesOf('PARENT'), before, 'dormant PARENT stays asleep — pending self-wake is not death');
-    });
+test('CRUX: a child dormant on a pending self-wake (no live sub) does NOT wake the parent', async () => {
+    inboxWaitingParent('PARENT');
+    paneGoneChild('CHILD');
+    subscribe('PARENT', 'CHILD', true);
+    // CHILD has NO live subscription, but holds a pending self-wake (far-future so
+    // the wakeups pass never fires it this tick). hasPendingSelfWake(CHILD) ⇒ the
+    // daemon treats it as STILL WAITING (the stop-guard's boundary), so it RELEASES
+    // instead of finalizing. NON-VACUOUS: drop the hasPendingSelfWake guard and
+    // CHILD finalizes → PARENT is spuriously woken.
+    const future = new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toISOString();
+    armWake({ wakeup_id: 'wk-cdw-child', node_id: 'CHILD', owner_id: 'CHILD', fire_at: future, kind: 'bare' });
+    await superviseTick();
+    assert.equal(getNode('CHILD').status, 'idle', 'CHILD with a pending self-wake is RELEASED, not finalized');
+    assert.equal(getNode('CHILD').intent, 'idle-release', 'CHILD routed to idle-release (its clock will wake it)');
+    assert.equal(readInboxSince('PARENT').length, 0, 'PARENT inbox EMPTY — a pending clock is healthy dormancy');
 });

package/dist/core/__tests__/context-intro.test.js

@@ -1,10 +1,8 @@
 // Tests for the <crtr-context> bearings preamble:
 //   1. Worker and orchestrator bearings carry the `## References` block
-//      (substrate reference docs + node-local docs as `###` sub-sections) in
-//      place of the removed `<memory>` block — no `label · dir` stanzas, no
-//      `(empty)` markers, no MEMORY.md index inlining. Orchestrators add the
-//      across-cycles framing; promotion delivers that same orchestrator
-//      context-dir framing to a node that spawned base.
+//      (substrate reference docs + node-local docs as `###` sub-sections).
+//      Orchestrators add the across-cycles framing; promotion delivers that
+//      same orchestrator context-dir framing to a node that spawned base.
 //   2. canvas-context-intro injects the block as its own session message at
 //      session_start (before the first prompt), idempotent across resumes.
 //
@@ -36,53 +34,51 @@ after(() => {
     delete process.env['CRTR_HOME'];
     delete process.env['CRTR_NODE_ID'];
 });
-test('worker bearings: base framing + ## References block (no <memory>, no label·dir stanzas), NO across-cycles framing', () => {
-    // Bug-regression: review finding M1 — buildContextBearings was changed from
-    // buildMemoryBlock (<memory> + label·dir per-store stanzas) to
-    // renderReferencesBlock (## References + ### <name> sub-sections). This test
-    // locks in the new contract.
+test('worker bearings: base framing + ## References block, NO across-cycles framing', () => {
+    // Bug-regression: review finding M1 — buildContextBearings renders the
+    // ## References block (renderReferencesBlock): ## References + ### <name>
+    // sub-sections. This test locks in that contract.
     const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
     // Seed a node-local substrate doc so the ## References block is non-empty.
     const dir = memoryDir(meta.node_id);
     mkdirSync(dir, { recursive: true });
-    writeFileSync(join(dir, 'test-ref.md'), '---\nkind: reference\nwhen: when testing\nwhy: regression fixture\nsystem-prompt-visibility: preview\n---\nTest body.\n');
+    writeFileSync(join(dir, 'test-ref.md'), '---\nkind: reference\nwhen-and-why-to-read: When testing, this reference should be read because it is a regression fixture\nsystem-prompt-visibility: preview\n---\nTest body.\n');
     const block = buildContextIntro(meta.node_id);
     assert.match(block, new RegExp(`<crtr-context dir="${contextDir(meta.node_id)}">`));
     assert.match(block, /shared document store, not a task tracker/, 'base = shared docs, not tasks');
-    // New contract: NO <memory> block — replaced by ## References.
+    // Reference content renders ONLY as ## References + ### sub-sections.
     assert.doesNotMatch(block, /<memory>/, 'no <memory> block');
-    // New contract: NO label·dir stanza headers (the removed per-store format).
+    // Per-store stanza headers (label · dir) never appear.
     assert.doesNotMatch(block, /user-global · /, 'no user-global label·dir stanza');
     assert.doesNotMatch(block, /node-local · /, 'no node-local label·dir stanza');
-    // New contract: NO (empty) placeholder (the removed empty-store marker).
+    // No (empty) placeholder marker.
     assert.doesNotMatch(block, /\(empty\)/, 'no (empty) placeholder');
-    // Reference content renders as ## References + ### sub-sections — no other shape.
     assert.match(block, /## References\n\n###/, '## References followed by ### sub-sections');
     // A terminal worker must NOT carry the orchestrator across-cycles framing.
     assert.doesNotMatch(block, /refresh cycles/, 'no across-cycles framing for a terminal worker');
     assert.match(block, /<\/crtr-context>/);
 });
-test('orchestrator bearings: across-cycles framing + node-local substrate docs ride into ## References; the MEMORY.md index never renders', () => {
-    // Bug-regression: review finding M1 — buildContextBearings replaced the old
-    // <memory> pointer-line block with ## References. Node-local substrate docs
-    // render as ### sub-sections at their rung; the old index file never surfaces.
+test('orchestrator bearings: across-cycles framing + node-local substrate docs ride into ## References; a non-substrate .md file is never inlined', () => {
+    // Bug-regression: review finding M1 — buildContextBearings renders ## References.
+    // Node-local substrate docs render as ### sub-sections at their rung; a
+    // non-substrate .md file (no frontmatter `kind`) never surfaces.
     const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
     promote(meta.node_id); // flip to orchestrator mode — the across-cycles gate
     const dir = memoryDir(meta.node_id);
     mkdirSync(dir, { recursive: true });
-    // Write a MEMORY.md file to verify it is never surfaced in the block.
+    // Write a non-substrate MEMORY.md file to verify it is never surfaced in the block.
     const legacyIndexPath = join(dir, 'MEMORY.md');
     writeFileSync(legacyIndexPath, '# memory index — one pointer line per memory; how-to in "Your long-term memory".\n\n- [Flaky build](flaky-build.md) — first run fails\n');
     // A node-local substrate doc DOES ride into ## References at its rung.
-    writeFileSync(join(dir, 'flaky-build.md'), '---\nkind: reference\nwhen: when the build flakes\nwhy: first run fails\nsystem-prompt-visibility: preview\n---\nFirst run always fails; rerun once.\n');
+    writeFileSync(join(dir, 'flaky-build.md'), '---\nkind: reference\nwhen-and-why-to-read: When the build flakes, this reference should be read because the first run fails\nsystem-prompt-visibility: preview\n---\nFirst run always fails; rerun once.\n');
     const block = buildContextIntro(meta.node_id);
     assert.match(block, /shared document store, not a task tracker/, 'still carries the base framing');
     assert.match(block, /refresh cycles/, 'orchestrator gets the across-cycles framing');
     assert.doesNotMatch(block, /<memory>/, 'no <memory> block');
     assert.match(block, /## References\n/, 'references block present');
     assert.match(block, /### flaky-build\n/, 'node-local doc gets its ### sub-section');
-    assert.match(block, /when the build flakes, read this reference\. first run fails\./, 'preview rung renders the routing line');
-    // The index file itself never renders: no header comment, no pointer line, no path.
+    assert.match(block, /When the build flakes, this reference should be read because the first run fails\./, 'preview rung renders the routing line');
+    // The non-substrate file never renders: no header line, no pointer line, no path.
     assert.ok(!block.includes('# memory index'), 'the index header comment is NOT inlined');
     assert.ok(!block.includes('- [Flaky build](flaky-build.md)'), 'index pointer lines are NOT inlined');
     assert.ok(!block.includes(legacyIndexPath), 'no absolute index (MEMORY.md) path');
@@ -90,9 +86,9 @@ test('orchestrator bearings: across-cycles framing + node-local substrate docs r
     assert.match(block, /<\/crtr-context>/);
 });
 test('orchestrator bearings: no per-store stanzas or (empty) markers; a rung-none node-local doc still surfaces as a ### title stub', () => {
-    // Bug-regression: review findings M1 + M6 — the three-store `label · dir`
-    // stanzas and (empty) markers are gone, and node-local docs are NOT filtered
-    // on rung: a migrated node-local reference defaults
+    // Bug-regression: review findings M1 + M6 — the ## References block carries no
+    // per-store `label · dir` stanzas or (empty) markers, and node-local docs are
+    // NOT filtered on rung: a migrated node-local reference defaults
     // system-prompt-visibility: none and must still ride into ## References as
     // its bare title (never its body).
     const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
@@ -101,7 +97,7 @@ test('orchestrator bearings: no per-store stanzas or (empty) markers; a rung-non
     mkdirSync(dir, { recursive: true });
     writeFileSync(join(dir, 'rung-none-fact.md'), '---\nkind: reference\n---\nbody that must not render at the none rung\n');
     const block = buildContextIntro(meta.node_id);
-    // No per-store stanza headers, no (empty) markers, no index paths.
+    // No per-store stanza headers, no (empty) markers, no MEMORY.md paths.
     assert.ok(!block.includes(`node-local · ${memoryDir(meta.node_id)}`), 'no node-local stanza header');
     assert.ok(!block.includes('user-global · '), 'no user-global stanza header');
     assert.ok(!block.includes('project · '), 'no project stanza header');