@north-light/crouter 0.3.154

package/dist/pi-extensions/__tests__/canvas-context-intro.test.js

@@ -0,0 +1,182 @@
+// Run with: node --import tsx/esm --test src/pi-extensions/__tests__/canvas-context-intro.test.ts
+//
+// BUG REGRESSION (crouter/CLAUDE.md testing policy):
+//   `crtr node new --fork-from <node>` caused AGENT IDENTITY CONFUSION. A fork
+//   inherits the SOURCE node's entire first-person conversation (pi COPIES it
+//   into the fork's session), so on boot the forked agent impersonated the
+//   source — it kept acting AS the source, even "monitoring itself" as a phantom
+//   child, until it happened to check CRTR_NODE_ID. Two root causes, both fixed
+//   here and pinned by these tests:
+//     1. canvas-context-intro never re-asserted the node's OWN identity, so the
+//        copied first-person narrative won.
+//     2. the idempotency guard misfired for a fork: the copied conversation
+//        already carries the SOURCE's <crtr-context> entry, so the guard treated
+//        it as "already present" and SUPPRESSED the fork's own intro entirely —
+//        the fork booted with the source's bearings (source id, source dir).
+//   Symptom write-up: nodes/mq4ns376-da6e56c9/reports/20260608T075810-final.md.
+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 { buildContextIntro, registerCanvasContextIntro, CONTEXT_INTRO_CUSTOM_TYPE, } from '../canvas-context-intro.js';
+import { createNode } from '../../core/canvas/canvas.js';
+import { closeDb } from '../../core/canvas/db.js';
+let home;
+let origNode;
+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 session entry as `sessionManager.getEntries()` would return it — a custom
+ *  message carrying a bearings block (string content). */
+function introEntry(content) {
+    return { type: 'custom_message', customType: CONTEXT_INTRO_CUSTOM_TYPE, content };
+}
+function makeFakePi() {
+    let handler;
+    return {
+        sent: [],
+        on(event, h) {
+            if (event === 'session_start')
+                handler = h;
+        },
+        sendMessage(m) {
+            this.sent.push(m);
+        },
+        registerMessageRenderer() {
+            /* display-only; irrelevant here */
+        },
+        fireSessionStart(entries) {
+            handler?.(undefined, { sessionManager: { getEntries: () => entries } });
+        },
+    };
+}
+before(() => {
+    origNode = process.env['CRTR_NODE_ID'];
+});
+beforeEach(() => {
+    closeDb();
+    if (home)
+        rmSync(home, { recursive: true, force: true });
+    home = mkdtempSync(join(tmpdir(), 'crtr-context-intro-'));
+    process.env['CRTR_HOME'] = home;
+    delete process.env['CRTR_NODE_ID'];
+});
+after(() => {
+    closeDb();
+    if (home)
+        rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+    if (origNode === undefined)
+        delete process.env['CRTR_NODE_ID'];
+    else
+        process.env['CRTR_NODE_ID'] = origNode;
+});
+test('boot intro asserts the node\'s OWN identity up front (regression: forked node impersonated source)', () => {
+    createNode(node('alpha', { name: 'fix-auth', kind: 'developer' }));
+    const intro = buildContextIntro('alpha');
+    assert.match(intro, /<crtr-bearings>/, 'opens with the bearings section');
+    assert.match(intro, /You are node alpha/, 'names the node by its own id');
+    assert.match(intro, /kind developer/, 'states the node kind');
+    // Gated (Option A): a fresh (non-fork) node's bearings are its FIRST entry, so
+    // there is no earlier narrative to disown — the disown framing (the fork callout
+    // naming the copied history "inherited reference material") is fork-only and must
+    // NOT appear here.
+    assert.ok(!/inherited reference material/.test(intro), 'a non-fork node carries no disown-the-earlier-narrative line');
+    // Identity LEADS the bearings block (no wrapper of its own), so it is the first
+    // prose the model reads — the orienting frame, not a trailing note.
+    assert.match(intro, /<crtr-bearings>\nYou are node alpha/, 'identity leads the bearings block');
+    assert.ok(intro.indexOf('<crtr-bearings>') < intro.indexOf('<project_context>'), 'bearings precede project context');
+});
+test('a FORK\'s intro names the source and disowns it (regression: fork acted AS the source)', () => {
+    // The source node whose conversation pi copied into the fork.
+    createNode(node('src7', { name: 'looking-pi-crouter', description: 'monitor-telemetry' }));
+    // The fork: fork_from provenance persisted at spawn.
+    createNode(node('fork9', { fork_from: 'src7' }));
+    const intro = buildContextIntro('fork9');
+    assert.match(intro, /You are node fork9/, 'the fork is told its OWN id');
+    assert.match(intro, /You are a FORK of src7/, 'names the fork source explicitly');
+    assert.match(intro, /You are NOT src7/, '"you are NOT the source" flag is present');
+    // Carries the source's human label so the agent recognizes the copied persona.
+    assert.match(intro, /looking-pi-crouter/, 'surfaces the source label');
+    // The fork DOES carry the disown framing — it has a real referent (copied history).
+    assert.match(intro, /inherited reference material/, 'the fork disowns the copied first-person narrative');
+    // It must NOT tell the fork it is the source node.
+    assert.ok(!/You are node src7/.test(intro), 'fork is never told it is the source node');
+    // A non-fork sibling gets the identity assertion but NO fork callout and NO
+    // disown line (gated on fork_from).
+    createNode(node('plain2'));
+    const plain = buildContextIntro('plain2');
+    assert.match(plain, /You are node plain2/);
+    assert.ok(!/FORK of/.test(plain), 'a fresh (non-fork) node carries no fork callout');
+    assert.ok(!/inherited reference material/.test(plain), 'a non-fork node carries no disown line');
+    // Regression: a raw provenance FILE PATH as fork_from (as human-work queue
+    // handlers pass) must not crash getNode() lookup inside identity assertion
+    // construction — it is not a valid node-id path segment, so it must be
+    // treated as an opaque source label instead of thrown at.
+    const pathSource = '/Users/silasrhyneer/.crouter/canvas/human-work/queue/20260717T000000-abc.json';
+    createNode(node('fork10', { fork_from: pathSource }));
+    const pathIntro = buildContextIntro('fork10');
+    assert.match(pathIntro, /You are node fork10/, 'the fork is told its OWN id');
+    assert.match(pathIntro, new RegExp(`You are a FORK of ${pathSource.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`), 'a path-valued fork source passes through as-is (no crash on getNode lookup)');
+    assert.match(pathIntro, /inherited reference material/, 'the fork disowns the copied first-person narrative');
+});
+test('session_start INJECTS the fork\'s own bearings despite the inherited source block (the misfiring-idempotency bug)', () => {
+    createNode(node('srcA'));
+    createNode(node('forkB', { fork_from: 'srcA' }));
+    // A fork boots with the SOURCE's whole conversation copied in — including the
+    // source's bearings intro entry (which names srcA, not forkB).
+    const inheritedSourceBlock = introEntry(buildContextIntro('srcA'));
+    process.env['CRTR_NODE_ID'] = 'forkB';
+    const pi = makeFakePi();
+    registerCanvasContextIntro(pi);
+    pi.fireSessionStart([inheritedSourceBlock]);
+    // The fix: the inherited block belongs to srcA, so it must NOT suppress
+    // forkB's own intro. forkB's bearings (with its identity assertion) ARE sent.
+    assert.equal(pi.sent.length, 1, 'fork injects its OWN bearings over the inherited source block');
+    assert.equal(pi.sent[0].customType, CONTEXT_INTRO_CUSTOM_TYPE);
+    assert.match(pi.sent[0].content, /You are node forkB/, 'injected bearings name the fork, not the source');
+    assert.match(pi.sent[0].content, /You are a FORK of srcA/, 'injected bearings carry the fork callout');
+    // The exact, machine-readable resume discriminator rides along (not sent to
+    // the LLM): it names THIS node, so a later resume tells our block apart from
+    // any inherited one without depending on prose.
+    assert.equal(pi.sent[0].details?.nodeId, 'forkB', 'injected block carries the exact node-id stamp');
+});
+test('resume idempotency uses the EXACT details stamp, independent of block text (regression hardening)', () => {
+    createNode(node('stampD'));
+    // A restored block that carries OUR exact stamp but whose TEXT does not mention
+    // our id. The old content-substring-only guard would re-inject (and accumulate)
+    // here; the exact `details.nodeId` match skips correctly.
+    const stampedNoIdInText = {
+        type: 'custom_message',
+        customType: CONTEXT_INTRO_CUSTOM_TYPE,
+        content: '<crtr-context dir="/elsewhere">bearings with no id in the text</crtr-context>',
+        details: { nodeId: 'stampD' },
+    };
+    process.env['CRTR_NODE_ID'] = 'stampD';
+    const pi = makeFakePi();
+    registerCanvasContextIntro(pi);
+    pi.fireSessionStart([stampedNoIdInText]);
+    assert.equal(pi.sent.length, 0, 'exact details-stamp match skips re-injection even when the text omits the id');
+});
+test('session_start stays IDEMPOTENT on a genuine resume (our own bearings already present)', () => {
+    createNode(node('resumeC'));
+    // A `--session` relaunch restores OUR conversation — our own bearings (naming
+    // resumeC) are already in history.
+    const ownBlock = introEntry(buildContextIntro('resumeC'));
+    process.env['CRTR_NODE_ID'] = 'resumeC';
+    const pi = makeFakePi();
+    registerCanvasContextIntro(pi);
+    pi.fireSessionStart([ownBlock]);
+    assert.equal(pi.sent.length, 0, 'our own bearings already present → no duplicate injection');
+});

package/dist/pi-extensions/__tests__/canvas-stophook-agentend.test.d.ts

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

package/dist/pi-extensions/__tests__/canvas-stophook-agentend.test.js

@@ -0,0 +1,467 @@
+// Run with: node --import tsx/esm --test src/pi-extensions/__tests__/canvas-stophook-agentend.test.ts
+//
+// The stophook stages agent_end and routes only after Pi emits agent_settled. A
+// node reaches its subscribers ONLY through its own explicit `crtr push` calls.
+// These tests pin settlement routing on the three stop outcomes:
+//   • natural stop while awaiting a live worker → idle-release, NO push
+//   • refresh-yield (intent='refresh')          → re-exec/shutdown, NO push
+//   • stalled leaf (nothing live, no final)      → reprompt still fires
+// Every assertion is on DB / disk effects (report files, inbox pointers) plus
+// the captured sendUserMessage — tmux is unavailable here, so the focus/respawn
+// helpers no-op (TMUX_PANE is cleared) and we drive a clean shutdown path.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, existsSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import registerCanvasStophook from '../canvas-stophook.js';
+import { createNode, subscribe, getNode, setStatus } from '../../core/canvas/canvas.js';
+import { openFocusRow, getFocusByNode, getFocusById, listFocuses } from '../../core/canvas/focuses.js';
+import { closeDb } from '../../core/canvas/db.js';
+import { reportsDir } from '../../core/canvas/paths.js';
+import { readInboxSince, appendInbox } from '../../core/feed/inbox.js';
+import { STALL_REPROMPT } from '../../core/runtime/stop-guard.js';
+import { markStopSignal } from '../../core/runtime/stop-signals.js';
+import { isBusy } from '../../core/runtime/busy.js';
+import { recordFault, readFault } from '../../core/runtime/fault.js';
+let home;
+let origNode;
+let origPane;
+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,
+    };
+}
+function makeFakePi() {
+    const handlers = {};
+    return {
+        injected: [],
+        on(e, h) { handlers[e] = h; },
+        sendUserMessage(content, options) { this.injected.push({ content, deliverAs: options?.deliverAs }); },
+        fire(e, ev, ctx) { handlers[e]?.(ev, ctx); },
+    };
+}
+function settle(pi, event, ctx) {
+    pi.fire('agent_end', event, ctx);
+    pi.fire('agent_settled', { type: 'agent_settled' }, ctx);
+}
+/** A natural-stop agent_end event carrying one assistant text block. */
+function stopEvent(text) {
+    return { messages: [{ role: 'assistant', stopReason: 'stop', content: [{ type: 'text', text }] }] };
+}
+/** Count of report files written under a node's reports/ dir (0 when none). */
+function reportCount(id) {
+    const dir = reportsDir(id);
+    return existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith('.md')).length : 0;
+}
+before(() => {
+    origNode = process.env['CRTR_NODE_ID'];
+    origPane = process.env['TMUX_PANE'];
+});
+beforeEach(() => {
+    closeDb();
+    if (home)
+        rmSync(home, { recursive: true, force: true });
+    home = mkdtempSync(join(tmpdir(), 'crtr-stophook-end-'));
+    process.env['CRTR_HOME'] = home;
+    // Force the clean-shutdown path (no in-place respawn) so the refresh test is
+    // deterministic even when the suite runs inside a tmux pane.
+    delete process.env['TMUX_PANE'];
+});
+after(() => {
+    closeDb();
+    if (home)
+        rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+    if (origNode === undefined)
+        delete process.env['CRTR_NODE_ID'];
+    else
+        process.env['CRTR_NODE_ID'] = origNode;
+    if (origPane === undefined)
+        delete process.env['TMUX_PANE'];
+    else
+        process.env['TMUX_PANE'] = origPane;
+});
+test('pending private fork binds both child coordinates atomically, or shuts down unbound', () => {
+    createNode(node('bound', {
+        private_fork_phase: 'fork_pending',
+        human_work_target: { work_kind: 'follow_up', dir: '/ticket', request_id: 'request-1', root: '/root' },
+        private_fork_recipe: { kickoff: 'private kickoff' },
+    }));
+    process.env['CRTR_NODE_ID'] = 'bound';
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    let boundShutdown = false;
+    pi.fire('session_start', { type: 'session_start' }, {
+        sessionManager: { getSessionId: () => 'child-id', getSessionFile: () => '/sessions/child.jsonl' },
+        shutdown: () => { boundShutdown = true; },
+    });
+    const bound = getNode('bound');
+    assert.equal(bound.private_fork_phase, 'session_started');
+    assert.equal(bound.pi_session_id, 'child-id');
+    assert.equal(bound.pi_session_file, '/sessions/child.jsonl');
+    assert.equal(boundShutdown, false, 'a fully-bound child remains live');
+    createNode(node('unbound', {
+        private_fork_phase: 'fork_pending',
+        human_work_target: { work_kind: 'follow_up', dir: '/ticket', request_id: 'request-2', root: '/root' },
+        private_fork_recipe: { kickoff: 'private kickoff' },
+    }));
+    process.env['CRTR_NODE_ID'] = 'unbound';
+    const missing = makeFakePi();
+    registerCanvasStophook(missing);
+    let missingShutdown = false;
+    missing.fire('session_start', { type: 'session_start' }, {
+        sessionManager: { getSessionId: () => 'child-id', getSessionFile: () => null },
+        shutdown: () => { missingShutdown = true; },
+    });
+    const unbound = getNode('unbound');
+    assert.equal(missingShutdown, true, 'a pending fork with no writable child session is shut down');
+    assert.equal(unbound.private_fork_phase, 'fork_pending');
+    assert.equal(unbound.pi_session_id ?? null, null);
+    assert.equal(unbound.pi_session_file ?? null, null);
+});
+test('natural stop commits idle-release only at agent_settled', { timeout: 1_000 }, () => {
+    createNode(node('root', { parent: null, lifecycle: 'resident' }));
+    createNode(node('mgr', { parent: 'root', lifecycle: 'terminal', mode: 'orchestrator' }));
+    createNode(node('worker', { parent: 'mgr', lifecycle: 'terminal', status: 'active' }));
+    subscribe('root', 'mgr', true); // root would receive any push mgr emits
+    subscribe('mgr', 'worker', true); // mgr holds an active live subscription → "awaiting"
+    process.env['CRTR_NODE_ID'] = 'mgr';
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    let shutdown = false;
+    const ctx = { shutdown: () => { shutdown = true; } };
+    pi.fire('agent_start', { type: 'agent_start' }, ctx);
+    pi.fire('agent_end', stopEvent('still waiting on the worker'), ctx);
+    assert.equal(getNode('mgr')?.status, 'active', 'agent_end is staging-only');
+    assert.equal(isBusy('mgr'), true, 'agent_end cannot clear whole-run busy state');
+    assert.equal(shutdown, false, 'agent_end cannot route a natural stop');
+    pi.fire('agent_settled', { type: 'agent_settled' }, ctx);
+    const m = getNode('mgr');
+    assert.equal(isBusy('mgr'), false, 'agent_settled clears whole-run busy state');
+    assert.equal(m?.intent, 'idle-release', 'mgr idle-released');
+    assert.equal(m?.status, 'idle', 'mgr marked idle');
+    assert.equal(shutdown, true, 'pi shut down');
+    assert.equal(reportCount('mgr'), 0, 'NO report file written');
+    assert.equal(readInboxSince('root').length, 0, 'NO inbox pointer fanned to subscriber');
+    assert.equal(pi.injected.length, 0, 'no reprompt on a legitimate idle-release');
+    // §5.1 case 6 (awaiting + UNFOCUSED → idle-release, no focus): the awaiting
+    // branch must never create/touch a focus row. Non-vacuous: an impl that ran
+    // the done-branch handoff/openFocus on an idle-release would leave a row here.
+    assert.equal(listFocuses().length, 0, 'awaiting+unfocused leaves the focuses table empty');
+});
+test('gh-451: idle-release does NOT release while a non-deferred inbox entry sits past the cursor', { timeout: 1_000 }, () => {
+    // Reproduces the #451 race: a subscriber's push landed in mgr's inbox but the
+    // in-process watcher has not yet flushed/committed the durable cursor past it
+    // (its DEBOUNCE_MS hold). If this settle released anyway, the daemon would
+    // immediately re-wake mgr on the very entry the watcher was mid-delivery on.
+    createNode(node('root', { parent: null, lifecycle: 'resident' }));
+    createNode(node('mgr', { parent: 'root', lifecycle: 'terminal', mode: 'orchestrator' }));
+    createNode(node('worker', { parent: 'mgr', lifecycle: 'terminal', status: 'active' }));
+    subscribe('root', 'mgr', true);
+    subscribe('mgr', 'worker', true); // mgr awaits a live worker → would idle-release once caught up
+    // A push landed in mgr's own inbox, strictly after its (unset) cursor —
+    // exactly the pre-flush window the watcher hasn't committed yet.
+    appendInbox('mgr', { from: 'worker', tier: 'normal', kind: 'update', label: 'worker made progress' });
+    process.env['CRTR_NODE_ID'] = 'mgr';
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    let shutdown = false;
+    const ctx = { shutdown: () => { shutdown = true; } };
+    settle(pi, stopEvent('still waiting on the worker'), ctx);
+    assert.equal(getNode('mgr')?.status, 'active', 'mgr stays active — NOT idle-released while behind the cursor');
+    assert.equal(getNode('mgr')?.intent ?? null, null, 'no idle-release intent while a non-deferred entry is unseen');
+    assert.equal(shutdown, false, 'pi stays alive so the in-process watcher can still deliver/commit');
+});
+test('gh-451: a DEFERRED-only unseen entry does not block idle-release (matches the daemon\'s own wake gate)', { timeout: 1_000 }, () => {
+    createNode(node('root', { parent: null, lifecycle: 'resident' }));
+    createNode(node('mgr', { parent: 'root', lifecycle: 'terminal', mode: 'orchestrator' }));
+    createNode(node('worker', { parent: 'mgr', lifecycle: 'terminal', status: 'active' }));
+    subscribe('root', 'mgr', true);
+    subscribe('mgr', 'worker', true);
+    appendInbox('mgr', { from: null, tier: 'deferred', kind: 'message', label: 'a scheduled deferred note' });
+    process.env['CRTR_NODE_ID'] = 'mgr';
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    let shutdown = false;
+    const ctx = { shutdown: () => { shutdown = true; } };
+    settle(pi, stopEvent('still waiting on the worker'), ctx);
+    assert.equal(getNode('mgr')?.intent, 'idle-release', 'a deferred-only unseen entry does not block release (#341 parity)');
+    assert.equal(getNode('mgr')?.status, 'idle');
+    assert.equal(shutdown, true, 'pi shuts down — deferred entries ride the next natural cycle, not this settle');
+});
+test('queued continuation finishes before natural-stop routing commits', { timeout: 1_000 }, () => {
+    createNode(node('leaf', { parent: null, lifecycle: 'terminal' }));
+    process.env['CRTR_NODE_ID'] = 'leaf';
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    let shutdown = false;
+    const ctx = { shutdown: () => { shutdown = true; } };
+    pi.fire('agent_start', { type: 'agent_start' }, ctx);
+    pi.fire('agent_end', stopEvent('first attempt ended while a continuation was queued'), ctx);
+    assert.equal(shutdown, false, 'the intermediate agent_end cannot route a natural stop');
+    assert.equal(getNode('leaf')?.status, 'active');
+    setStatus('leaf', 'done');
+    pi.fire('agent_start', { type: 'agent_start' }, ctx);
+    pi.fire('agent_end', stopEvent('queued continuation completed the assignment'), ctx);
+    pi.fire('agent_settled', { type: 'agent_settled' }, ctx);
+    assert.equal(shutdown, true, 'settlement routes from the completed continuation');
+    assert.equal(getNode('leaf')?.intent ?? null, null, 'the intermediate natural stop never idle-released the node');
+});
+// ---------------------------------------------------------------------------
+// §5.1 — the §1.7 settlement branch map on the focuses table. Every assertion is
+// on the canvas focuses/runtime rows after firing agent_settled (TMUX_PANE is
+// cleared in beforeEach). NOTE (broker-host cut): the placement read `focusOf`
+// used by the handler now GC-prunes a viewer row whose pane is not a LIVE tmux
+// pane (liveOrPrune → paneExists), so a fabricated '%pane' id is pruned on the
+// first read. To drive the handler's focus path deterministically in the
+// tmux-free fast tier we register viewer rows with a NULL pane (a registered-
+// but-not-yet-realized viewer, which liveOrPrune passes through). status='done'
+// is reached by setting the runtime row directly (the branch reads
+// getNode(nodeId).status).
+// ---------------------------------------------------------------------------
+test('§5.1.1 truly-done + focused → focus row CLOSED, NO manager takeover (broker cut deleted handFocusToManager)', () => {
+    // Regression guard for the broker-host cut: the engine is now a detached
+    // broker, not a pane, so there is no engine to hand to a manager. The old
+    // "dormant idle-release manager takes over the finished node's focus row"
+    // path (handFocusToManager) is DELETED — a truly-done focused node just
+    // tearDownNode's its own viewer and shuts down, EVEN when a dormant
+    // idle-release manager exists (the exact case that used to trigger takeover).
+    createNode(node('root', { parent: null, lifecycle: 'resident' }));
+    createNode(node('mgr', { parent: 'root', lifecycle: 'terminal', mode: 'orchestrator', status: 'idle', intent: 'idle-release' }));
+    // M starts WITH a recorded LOCATION so the done-path presence-null is observable.
+    createNode(node('M', { parent: 'mgr', lifecycle: 'terminal', pane: '%m', tmux_session: 'Suser', window: '@wm' }));
+    subscribe('mgr', 'M', true);
+    openFocusRow('fM', null, 'Suser', 'M'); // null pane → focusOf returns it → drives tearDownNode
+    process.env['CRTR_NODE_ID'] = 'M';
+    setStatus('M', 'done'); // pushed final this turn
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    let shutdown = false;
+    settle(pi, stopEvent('done — pushed final'), { shutdown: () => { shutdown = true; } });
+    // The done branch: focusOf('M') != null → tearDownNode('M') CLOSES fM. The
+    // manager is NOT handed anything (takeover deleted). Non-vacuous: a takeover
+    // impl would leave getFocusByNode('mgr').focus_id === 'fM'.
+    assert.equal(getFocusByNode('mgr'), null, 'the manager is NOT handed the finished node\'s focus (takeover deleted)');
+    assert.equal(getFocusById('fM'), null, 'the finished node\'s viewer focus row is closed');
+    assert.equal(getFocusByNode('M'), null, 'the finished node no longer occupies any focus');
+    assert.equal(shutdown, true, 'pi shut down after teardown');
+    // The done node's own presence is nulled (setPresence(null) on the done path).
+    assert.equal(getNode('M')?.pane ?? null, null, 'the finished node\'s own LOCATION pane is nulled');
+    assert.equal(getNode('M')?.window ?? null, null, 'the finished node\'s window presence is nulled too');
+});
+test('§5.1.2 truly-done + focused + NO manager (root) → focus row CLOSED (Q1)', () => {
+    // R carries a LOCATION so the close-path presence-null is observable.
+    createNode(node('R', { parent: null, lifecycle: 'terminal', pane: '%r', tmux_session: 'Suser', window: '@wr' }));
+    openFocusRow('fR', '%r', 'Suser', 'R');
+    process.env['CRTR_NODE_ID'] = 'R';
+    setStatus('R', 'done');
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    settle(pi, stopEvent('root done'), { shutdown: () => { } });
+    // managerId = R.parent(null) ?? subscribersOf(R)[0](none) = null →
+    // handFocusToManager returns false → the close path: closeFocusRow(fR) +
+    // setRemainOnExit(%r's window, false) (return-to-shell) + null R's presence.
+    // Non-vacuous: a takeover-instead-of-close impl would leave the row present;
+    // an impl that skips the MINOR presence-null leaves getNode('R').pane === '%r'.
+    assert.equal(getFocusById('fR'), null, 'a manager-less finished focus is closed, not handed off');
+    assert.equal(listFocuses().length, 0, 'no focus rows survive');
+    assert.equal(getNode('R')?.pane ?? null, null, 'the finished root\'s own LOCATION pane is nulled (close path reaps)');
+});
+test('§5.1.3 truly-done + focused + manager ALREADY focused elsewhere → focus CLOSED, manager UNMOVED', () => {
+    createNode(node('root', { parent: null, lifecycle: 'resident' }));
+    createNode(node('mgr', { parent: 'root', lifecycle: 'terminal', mode: 'orchestrator' }));
+    createNode(node('M', { parent: 'mgr', lifecycle: 'terminal', pane: '%m', tmux_session: 'Sa', window: '@wm' }));
+    subscribe('mgr', 'M', true);
+    openFocusRow('fOther', '%o', 'Sb', 'mgr'); // mgr already on its OWN viewport
+    openFocusRow('fM', '%m', 'Sa', 'M');
+    process.env['CRTR_NODE_ID'] = 'M';
+    setStatus('M', 'done');
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    settle(pi, stopEvent('M done'), { shutdown: () => { } });
+    // handFocusToManager sees getFocusByNode('mgr') != null → returns false →
+    // closeFocusRow(fM). Non-vacuous: moving mgr would either repoint its focus_id
+    // to fM (and a wrong impl that didn't close fM would leave it present) or throw
+    // UNIQUE(node_id); this pins mgr's OTHER focus untouched and M's focus gone.
+    assert.equal(getFocusById('fM'), null, "M's focus is closed");
+    assert.equal(getFocusByNode('mgr')?.focus_id, 'fOther', "the manager's other viewport is NOT stolen");
+    // MINOR: M (done) is reaped on the close path — its own presence nulled.
+    // Non-vacuous: an impl that skips the done-path setPresence-null leaves
+    // getNode('M').pane === '%m'.
+    assert.equal(getNode('M')?.pane ?? null, null, "the finished node's own LOCATION pane is nulled");
+});
+test('§5.1.4 truly-done + UNFOCUSED → no focus row created/touched, shuts down (Invariant P)', () => {
+    createNode(node('mgr', { parent: null, lifecycle: 'terminal', mode: 'orchestrator' }));
+    createNode(node('M', { parent: 'mgr', lifecycle: 'terminal' }));
+    subscribe('mgr', 'M', true);
+    process.env['CRTR_NODE_ID'] = 'M';
+    setStatus('M', 'done');
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    let shutdown = false;
+    settle(pi, stopEvent('done, never had a viewport'), { shutdown: () => { shutdown = true; } });
+    // focusOf(M) is null → the focus block is skipped entirely → just shutdown.
+    // Non-vacuous: an impl that created or handed off a focus row would leave
+    // listFocuses non-empty.
+    assert.equal(shutdown, true, 'an unfocused done node shuts down');
+    assert.equal(listFocuses().length, 0, 'no focus row was created or touched');
+});
+test('§5.1.5 awaiting + FOCUSED → STAY ALIVE: pi keeps running (no release), focus row untouched (F3)', () => {
+    createNode(node('root', { parent: null, lifecycle: 'resident' }));
+    createNode(node('mgr', { parent: 'root', lifecycle: 'terminal', mode: 'orchestrator' }));
+    createNode(node('worker', { parent: 'mgr', lifecycle: 'terminal', status: 'active' }));
+    subscribe('root', 'mgr', true);
+    subscribe('mgr', 'worker', true); // mgr awaits a live worker → would idle-release if UNfocused
+    // null pane (broker cut): focusOf passes a null-pane viewer row through, so the
+    // handler reads mgr as FOCUSED in the tmux-free fast tier (a fabricated %pane
+    // would be GC-pruned by liveOrPrune and the node would wrongly release).
+    openFocusRow('fMgr', null, 'Suser', 'mgr');
+    process.env['CRTR_NODE_ID'] = 'mgr';
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    let shutdown = false;
+    settle(pi, stopEvent('still waiting on the worker'), { shutdown: () => { shutdown = true; } });
+    // A FOCUSED awaiting node holds the user's viewport, so the awaiting branch
+    // keeps pi LIVE and dormant (the in-process inbox-watcher wakes it) instead of
+    // releasing + shutting down. It must NOT release, NOT shut down, and NOT touch
+    // the focus row. Non-vacuous: the old freeze impl flipped intent→idle-release
+    // and shut pi down; this pins all three as untouched.
+    assert.equal(getNode('mgr')?.status, 'active', 'a focused awaiting node stays active (not released)');
+    assert.equal(getNode('mgr')?.intent ?? null, null, 'no idle-release intent while focused');
+    assert.equal(shutdown, false, 'a focused awaiting node is NOT shut down — pi stays live');
+    assert.equal(getFocusByNode('mgr')?.focus_id, 'fMgr', 'the focus row is UNCHANGED — not closed, not handed off');
+});
+test('§5.1.7 resident attended (no live subs) → nothing happens; focus + status survive', () => {
+    createNode(node('root', { parent: null, lifecycle: 'resident' }));
+    openFocusRow('fR', '%r', 'Suser', 'root');
+    process.env['CRTR_NODE_ID'] = 'root';
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    let shutdown = false;
+    settle(pi, stopEvent('I have wrapped up'), { shutdown: () => { shutdown = true; } });
+    // evaluateStop on a resident → reason 'dormant' (NOT 'awaiting'), so the
+    // awaiting branch is skipped and the handler does nothing: no release, no
+    // shutdown, no focus touch. Non-vacuous: an impl that idle-released a resident
+    // would flip status→idle / intent→idle-release; one that touched focus would
+    // change/remove fR.
+    assert.equal(getNode('root')?.status, 'active', 'a resident is never forced dormant');
+    assert.equal(getNode('root')?.intent ?? null, null, 'no idle-release intent on a resident');
+    assert.equal(getFocusByNode('root')?.focus_id, 'fR', 'focus row survives untouched');
+    assert.equal(shutdown, false, 'a resident attended node is not shut down');
+});
+test('refresh-yield (intent=refresh) writes NO push — silent to subscribers', () => {
+    createNode(node('root', { parent: null, lifecycle: 'resident' }));
+    createNode(node('orch', { parent: 'root', lifecycle: 'terminal', mode: 'orchestrator', intent: 'refresh' }));
+    subscribe('root', 'orch', true);
+    process.env['CRTR_NODE_ID'] = 'orch';
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    let shutdown = false;
+    settle(pi, stopEvent('checkpoint before refreshing'), { shutdown: () => { shutdown = true; } });
+    assert.equal(shutdown, true, 'pi shut down (no tmux pane → clean shutdown)');
+    assert.equal(reportCount('orch'), 0, 'a yield is silent: NO report file');
+    assert.equal(readInboxSince('root').length, 0, 'a yield is silent: NO inbox pointer');
+    assert.equal(pi.injected.length, 0, 'no reprompt on a refresh-yield');
+});
+// ---------------------------------------------------------------------------
+// turn_end — stale-⚠ fix: reaching turn_end proves the current provider
+// round-trip and any wedge episode are both over, so both fault links clear.
+// ---------------------------------------------------------------------------
+/** A turn_end event carrying one assistant text block. */
+function turnEndEvent(text) {
+    return { message: { role: 'assistant', content: [{ type: 'text', text }] } };
+}
+test('turn_end clears a stale pi→provider fatal fault (a completed round-trip proves the episode is over)', () => {
+    createNode(node('leaf', { parent: null, lifecycle: 'terminal' }));
+    recordFault('leaf', {
+        link: 'pi→provider',
+        op: 'generation turn',
+        kind: 'other',
+        retry: { disposition: 'fatal' },
+        message: 'terminated',
+    });
+    assert.notEqual(readFault('leaf'), null, 'precondition: fault marker recorded');
+    process.env['CRTR_NODE_ID'] = 'leaf';
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    pi.fire('turn_end', turnEndEvent('all good now'), {});
+    assert.equal(readFault('leaf'), null, 'the pi→provider fault is cleared at turn_end');
+});
+test('turn_end still clears a daemon→node wedge fault (existing behavior, unchanged)', () => {
+    createNode(node('leaf', { parent: null, lifecycle: 'terminal' }));
+    recordFault('leaf', {
+        link: 'daemon→node',
+        op: 'wedge detection',
+        kind: 'wedged',
+        retry: { disposition: 'manual' },
+        message: 'no progress for 20m',
+    });
+    assert.notEqual(readFault('leaf'), null, 'precondition: wedge fault recorded');
+    process.env['CRTR_NODE_ID'] = 'leaf';
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    pi.fire('turn_end', turnEndEvent('turn completed'), {});
+    assert.equal(readFault('leaf'), null, 'the daemon→node wedge fault is still cleared at turn_end');
+});
+test('a successful final or human ask suppresses the stop reprompt without a canvas read', () => {
+    for (const [signal, shutsDown] of [['pushedFinal', true], ['askedHuman', false]]) {
+        process.env['CRTR_NODE_ID'] = 'signal-only';
+        markStopSignal('signal-only', signal);
+        const pi = makeFakePi();
+        registerCanvasStophook(pi);
+        let shutdown = false;
+        settle(pi, stopEvent(`completed ${signal}`), { shutdown: () => { shutdown = true; } });
+        assert.equal(pi.injected.length, 0, `${signal} does not re-prompt when the broker cannot read its node`);
+        assert.equal(shutdown, shutsDown, `${signal} takes its expected settled action`);
+    }
+});
+test('an in-run retry (agent_start with no new input) does not erase this run\'s stop signal', () => {
+    // Regression: pi re-fires agent_start for automatic retries and post-compaction
+    // continuations WITHIN one run. Clearing the marker there erased the ask/final
+    // recorded earlier in the same run, so settlement fell back to a canvas read
+    // and re-prompted a node that had legitimately asked the human.
+    createNode(node('mgr', { parent: null, lifecycle: 'terminal', mode: 'orchestrator' }));
+    createNode(node('leaf', { parent: 'mgr', lifecycle: 'terminal', status: 'active' }));
+    subscribe('mgr', 'leaf', true);
+    process.env['CRTR_NODE_ID'] = 'leaf';
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    const ctx = { shutdown: () => { } };
+    pi.fire('input', { type: 'input' }, ctx);
+    pi.fire('agent_start', { type: 'agent_start' }, ctx);
+    markStopSignal('leaf', 'askedHuman'); // the node ran `crtr human ask` mid-run
+    pi.fire('agent_start', { type: 'agent_start' }, ctx); // pi auto-retried after a provider error
+    settle(pi, stopEvent('waiting on the human now'), ctx);
+    assert.equal(pi.injected.length, 0, 'the ask survives the in-run retry — no stall reprompt');
+    // ...and the NEXT user-directed run does start clean.
+    markStopSignal('leaf', 'askedHuman');
+    pi.fire('input', { type: 'input' }, ctx);
+    settle(pi, stopEvent('I think I am basically done here'), ctx);
+    assert.equal(pi.injected.length, 1, 'a new input discards a leftover marker from a prior run');
+});
+test('stalled leaf (nothing live to await, no final) is still reprompted', () => {
+    createNode(node('mgr', { parent: null, lifecycle: 'terminal', mode: 'orchestrator' }));
+    createNode(node('leaf', { parent: 'mgr', lifecycle: 'terminal', status: 'active' }));
+    subscribe('mgr', 'leaf', true); // mgr subscribes to leaf; leaf itself awaits nothing
+    process.env['CRTR_NODE_ID'] = 'leaf';
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    let shutdown = false;
+    settle(pi, stopEvent('I think I am basically done here'), { shutdown: () => { shutdown = true; } });
+    assert.equal(pi.injected.length, 1, 'the stall reprompt fired');
+    assert.equal(pi.injected[0].content, STALL_REPROMPT, 'reprompt carries the stall nudge to push final / ask');
+    assert.equal(pi.injected[0].deliverAs, 'followUp', 'reprompt delivered as a followUp');
+    assert.equal(shutdown, false, 'a stalled leaf is NOT shut down — it is re-prompted to finish');
+    assert.notEqual(getNode('leaf')?.intent, 'idle-release', 'a stalled leaf does not idle-release');
+    assert.equal(reportCount('leaf'), 0, 'NO report file written on a stall');
+    assert.equal(readInboxSince('mgr').length, 0, 'NO inbox pointer fanned on a stall');
+});