@crouton-kit/crouter 0.3.13 → 0.3.15

package/dist/daemon/crtrd.js

@@ -3,15 +3,18 @@
 // Sole responsibility: supervise tmux window exit and revive nodes. No
 // orchestration logic lives here. The daemon is a process-lifecycle watcher.
 //
-// Model
+// Model (v3: liveness is PANE-existence, not window-existence — a manual
+// move-pane/join-pane/break-pane must never read as a node death)
 //   • Poll every intervalMs (default 2000ms).
-//   • For each active|idle node: check whether its tmux window is still alive.
-//   • Window alive → healthy, skip.
-//   • Window gone + intent==='refresh' → fresh respawn (node asked to yield).
-//   • Window gone + intent==='idle-release' → node freed its own pane while
+//   • For each active|idle node: check whether its tmux PANE is still alive
+//     (isNodePaneAlive; window-existence is only a legacy/no-pane fallback).
+//   • Pane alive → reconcile its LOCATION (follow any manual move; lazy-backfill
+//     a legacy row's pane), then judge pi liveness — healthy, skip otherwise.
+//   • Pane gone + intent==='refresh' → fresh respawn (node asked to yield).
+//   • Pane gone + intent==='idle-release' → node freed its own pane while
 //     dormant; clear the stale window ref and revive (resume) when its inbox
 //     gains an unseen entry.
-//   • Window gone + any other intent → crash: mark 'dead'.
+//   • Pane gone + any other intent → crash: mark 'dead'.
 //   • Nodes with no tmux placement (inline roots) are skipped.
 //
 // Single-instance guarantee
@@ -21,11 +24,91 @@
 import { writeFileSync, readFileSync, rmSync, existsSync, mkdirSync, } from 'node:fs';
 import { join } from 'node:path';
 import { crtrHome } from '../core/canvas/paths.js';
-import { listNodes, setStatus, getNode, updateNode, } from '../core/canvas/index.js';
-import { windowAlive } from '../core/runtime/tmux.js';
+import { listNodes, getRow, setPresence, getNode, } from '../core/canvas/index.js';
+import { transition } from '../core/runtime/lifecycle.js';
+import { isNodePaneAlive, reconcile } from '../core/runtime/placement.js';
 import { reviveNode } from '../core/runtime/revive.js';
+import { pushUrgent } from '../core/feed/feed.js';
 import { readInboxSince, readCursor } from '../core/feed/inbox.js';
+/** Surface a vehicle that never booted.
+ *
+ *  `spawnChild` returns status="active" the instant the tmux window opens — it
+ *  does NOT wait for pi to come up, because boot is inherently slow (and slower
+ *  under load) and racing it would either block the spawner or false-fail a
+ *  slow-but-healthy launch. The cost of that optimism: a pi that dies before its
+ *  first session_start (so `pi_session_id` was never recorded) is invisible —
+ *  the parent believes its child is running. When the daemon later finds the
+ *  pane gone with no session ever bound, it errors LOUDLY up the spine: an
+ *  urgent push so the parent learns the child failed to launch instead of just
+ *  seeing a silent `dead`. */
+async function surfaceBootFailure(meta) {
+    const body = `⚠ Spawn failed — \`${meta.name}\` (${meta.kind}) never started.\n\n` +
+        `Its pi vehicle exited before the session came up (no pi_session_id was ever ` +
+        `recorded), so the node produced no output. This is almost always a transient ` +
+        `launch failure — e.g. resource pressure when several nodes boot at once — not ` +
+        `a fault in the task itself.\n\n` +
+        `If the work still needs doing, re-spawn it; if spawns keep dying, spawn fewer at a time.`;
+    await pushUrgent(meta.node_id, body, { from: meta.node_id });
+}
 const DEFAULT_INTERVAL_MS = 2000;
+// How long a node's pi may be observed dead-while-its-window-lives before the
+// daemon revives it. MUST exceed worst-case pi boot time: a normal in-place
+// refresh (reviveInPlace) transiently shows a dead OLD pid for the gap between
+// the old pi dying and the fresh pi booting + re-recording its pid, and we must
+// not double-spawn into that gap.
+const REVIVE_GRACE_MS = 20_000;
+// Per-node first-observed-dead timestamps, for the grace window above. In-memory
+// only — a daemon restart resets it (worst case: one extra grace interval).
+const unhealthySince = new Map();
+/** Decide what to do with a node whose tmux pane is alive, from its pi
+ *  liveness and how long it's been dead. Pure — the time-and-tmux side effects
+ *  live in handleLiveWindow; this is the unit-testable core.
+ *    piPidAlive: true=alive, false=dead, null=no pid recorded (legacy node, or a
+ *      relaunch in flight) — leave those to the pane-gone pass.
+ *    deadFor: ms since first observed dead, or null on the first observation. */
+export function livenessVerdict(piPidAlive, deadFor) {
+    if (piPidAlive !== false)
+        return 'leave';
+    if (deadFor === null || deadFor < REVIVE_GRACE_MS)
+        return 'pending';
+    return 'revive';
+}
+/** A node whose tmux PANE is alive: pane-existence does NOT prove pi is
+ *  alive (an inline root runs pi under a persistent login shell that survives
+ *  pi's death), so gauge liveness on the recorded pid and revive a dead pi once
+ *  it's been dead past the grace window. */
+function handleLiveWindow(row, now) {
+    const id = row.node_id;
+    // A deliberately-frozen focused-dormant node (intent=idle-release) keeps its
+    // pane alive via remain-on-exit (F3, §3c). Do NOT grace-revive it here — it is
+    // waiting for a worker's inbox push, which the second pass delivers. Grace-
+    // reviving would pre-empt that and churn the frozen focus pane.
+    if (row.intent === 'idle-release') {
+        unhealthySince.delete(id);
+        return;
+    }
+    const pid = row.pi_pid;
+    const piPidAlive = pid == null ? null : isPidAlive(pid);
+    if (piPidAlive !== false) {
+        unhealthySince.delete(id); // alive, or no pid to judge — nothing pending
+        return;
+    }
+    const since = unhealthySince.get(id);
+    const verdict = livenessVerdict(piPidAlive, since === undefined ? null : now - since);
+    if (verdict === 'pending') {
+        if (since === undefined)
+            unhealthySince.set(id, now);
+        return;
+    }
+    // 'revive' — pi has been dead past the grace window while its window lived on.
+    unhealthySince.delete(id);
+    // A refresh-yield wants fresh context (re-read the roadmap); any other death
+    // resumes the saved conversation. reviveNode opens a fresh window and clears
+    // pi_pid, so the next tick won't re-fire on this stale pid.
+    const resume = row.intent !== 'refresh';
+    process.stderr.write(`[crtrd] revive ${id} (pi dead, pane alive, intent=${String(row.intent)})\n`);
+    reviveNode(id, { resume });
+}
 // ---------------------------------------------------------------------------
 // Pidfile
 // ---------------------------------------------------------------------------
@@ -54,14 +137,16 @@ export function readPidfile() {
     const n = Number(raw);
     return Number.isFinite(n) && n > 0 ? n : null;
 }
-/** True if a process with `pid` is currently alive (signal-0 probe). */
+/** True if a process with `pid` is currently alive (signal-0 probe). `kill(pid,
+ *  0)` throws ESRCH when the process is gone; EPERM means it exists but isn't
+ *  ours — still alive. */
 export function isPidAlive(pid) {
     try {
         process.kill(pid, 0);
         return true;
     }
-    catch {
-        return false;
+    catch (e) {
+        return e.code === 'EPERM';
     }
 }
 /** True when a crtrd process is already running (pidfile exists + pid alive). */
@@ -72,7 +157,7 @@ export function isDaemonRunning() {
 // ---------------------------------------------------------------------------
 // Supervisor tick
 // ---------------------------------------------------------------------------
-async function superviseTick() {
+export async function superviseTick(now = Date.now()) {
     let rows;
     try {
         rows = listNodes({ status: ['active', 'idle'] });
@@ -83,33 +168,62 @@ async function superviseTick() {
     }
     for (const row of rows) {
         try {
-            // listNodes returns the lightweight NodeRow; we need the full NodeMeta
-            // for tmux_session, window, intent, and pi_session_id.
-            const meta = getNode(row.node_id);
-            if (meta === null)
-                continue; // vanished between list and get
-            // Nodes without tmux placement are inline roots — not daemon-managed.
-            if (meta.tmux_session == null || meta.window == null)
+            // Runtime (tmux_session, window, intent, pi_pid) is now authoritative IN
+            // the row — no per-node getNode re-read. Only the boot-failure split below
+            // still needs identity (pi_session_id), read on demand there.
+            // Nodes with no tmux placement at all are inline roots — not daemon-
+            // managed. Pane-anchored: a node still counts as placed if it has a pane
+            // even when its derived window/session cache is null.
+            if (row.tmux_session == null && row.window == null && row.pane == null)
                 continue;
-            if (windowAlive(meta.tmux_session, meta.window))
-                continue; // healthy
-            // Window is gone. Branch on why.
-            if (meta.intent === 'refresh') {
+            if (isNodePaneAlive(row)) {
+                // The pane is up — but that alone doesn't mean pi is. Reconcile first
+                // (follow any manual pane move, and lazy-backfill a legacy row's pane
+                // from its live window), then judge pi liveness off the fresh row. The
+                // alive-gate means reconcile here only ever FOLLOWS/backfills — never
+                // nulls the LOCATION out from under the gone-branches below.
+                reconcile(row.node_id);
+                handleLiveWindow(getRow(row.node_id) ?? row, now);
+                continue;
+            }
+            // The pane is gone. Branch on why.
+            unhealthySince.delete(row.node_id); // pane-gone path owns it now
+            if (row.intent === 'refresh') {
                 // The node set intent=refresh before stopping — a clean yield. Respawn
                 // fresh so it re-reads its roadmap/context dir.
                 process.stderr.write(`[crtrd] revive ${row.node_id} (refresh-yield)\n`);
                 reviveNode(row.node_id, { resume: false });
             }
-            else if (meta.intent === 'idle-release') {
+            else if (row.intent === 'idle-release') {
                 // The node freed its own window on purpose while dormant. Drop the stale
                 // window ref and keep it 'idle'; the inbox-poll pass below revives it
                 // (resume) the moment a subscribed worker delivers.
-                updateNode(row.node_id, { window: null });
+                setPresence(row.node_id, { tmux_session: row.tmux_session, window: null });
             }
             else {
-                // Window vanished without the node completing or refreshing — a crash.
-                process.stderr.write(`[crtrd] dead ${row.node_id} (window gone, intent=${String(meta.intent)})\n`);
-                setStatus(row.node_id, 'dead');
+                // The pane vanished without the node completing or refreshing. Split the
+                // two ways that happens: a vehicle that NEVER BOOTED (pi exited before
+                // its first session_start, so pi_session_id is still null) versus a
+                // genuine mid-run CRASH (it had booted, so pi_session_id is set). Both
+                // are dead, but a never-booted node is a spawn failure the parent was
+                // never told about — surface it up the spine instead of dying quietly.
+                transition(row.node_id, 'crash');
+                // Boot-failed vs crashed turns on pi_session_id, an IDENTITY field — the
+                // one place this pass still reads meta. surfaceBootFailure also wants the
+                // full meta (name/kind) for its message.
+                const meta = getNode(row.node_id);
+                if (meta !== null && meta.pi_session_id == null) {
+                    process.stderr.write(`[crtrd] boot-failed ${row.node_id} (pane gone before pi ever started)\n`);
+                    try {
+                        await surfaceBootFailure(meta);
+                    }
+                    catch (err) {
+                        process.stderr.write(`[crtrd] surfaceBootFailure ${row.node_id} error: ${err.message}\n`);
+                    }
+                }
+                else {
+                    process.stderr.write(`[crtrd] dead ${row.node_id} (pane gone, intent=${String(row.intent)})\n`);
+                }
             }
         }
         catch (err) {
@@ -123,15 +237,19 @@ async function superviseTick() {
     // exit; any entry past it is undelivered work — resume the node to handle it.
     for (const row of rows) {
         try {
-            const meta = getNode(row.node_id);
-            if (meta === null)
+            // Re-read the ROW for fresh runtime (the first pass may have mutated it);
+            // no meta needed — status/intent/window/tmux_session all live in the row.
+            const r = getRow(row.node_id);
+            if (r === null)
                 continue;
-            if (meta.status !== 'idle' || meta.intent !== 'idle-release')
+            if (r.status !== 'idle' || r.intent !== 'idle-release')
                 continue;
-            // If a window is somehow alive, the in-process watcher owns delivery.
-            if (meta.window != null && windowAlive(meta.tmux_session ?? '', meta.window)) {
+            // The in-process inbox-watcher only owns delivery while pi is actually LIVE.
+            // A frozen focused-dormant pane (remain-on-exit, F3) is pane-ALIVE but
+            // pi-DEAD — no watcher — so the daemon must wake it. Gate the skip on pi
+            // liveness, NOT pane presence (which would skip a frozen pane forever, §3c).
+            if (r.pi_pid != null && isPidAlive(r.pi_pid))
                 continue;
-            }
             const entries = readInboxSince(row.node_id, readCursor(row.node_id));
             if (entries.length > 0) {
                 process.stderr.write(`[crtrd] revive ${row.node_id} (idle-release, inbox)\n`);

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,266 @@
+// Run with: node --import tsx/esm --test src/pi-extensions/__tests__/canvas-stophook-agentend.test.ts
+//
+// The stophook's agent_end routing no longer auto-pushes anything: a node
+// reaches its subscribers ONLY through its own explicit `crtr push` calls.
+// These tests pin that 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 } from '../../core/feed/inbox.js';
+import { STALL_REPROMPT } from '../../core/runtime/stop-guard.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); },
+    };
+}
+/** 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('natural stop while awaiting a live worker → idle-release with NO push (no report, no inbox pointer)', () => {
+    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;
+    pi.fire('agent_end', stopEvent('still waiting on the worker'), { shutdown: () => { shutdown = true; } });
+    const m = getNode('mgr');
+    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');
+});
+// ---------------------------------------------------------------------------
+// §5.1 — the §1.7 agent_end branch map on the focuses table. Every assertion is
+// on the canvas focuses/runtime rows after firing agent_end (TMUX_PANE is
+// cleared in beforeEach, so the focus helpers in the handler are pure DB and the
+// '%pane' ids below are never read by tmux). status='done' is reached by setting
+// the runtime row directly (the branch reads getNode(nodeId).status).
+// ---------------------------------------------------------------------------
+test('§5.1.1 truly-done + focused + manager-not-focused → MANAGER TAKEOVER of the focus row', () => {
+    createNode(node('root', { parent: null, lifecycle: 'resident' }));
+    createNode(node('mgr', { parent: 'root', lifecycle: 'terminal', mode: 'orchestrator' }));
+    // M starts WITH a recorded LOCATION so the MINOR presence-null is observable.
+    createNode(node('M', { parent: 'mgr', lifecycle: 'terminal', pane: '%m', tmux_session: 'Suser', window: '@wm' }));
+    subscribe('mgr', 'M', true);
+    openFocusRow('fM', '%m', 'Suser', 'M');
+    process.env['CRTR_NODE_ID'] = 'M';
+    setStatus('M', 'done'); // pushed final this turn
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    let shutdown = false;
+    pi.fire('agent_end', stopEvent('done — pushed final'), { shutdown: () => { shutdown = true; } });
+    // managerId = M.parent = 'mgr' (not focused elsewhere, no live pane here → the
+    // DORMANT-takeover path) → handFocusToManager repoints fM's occupant M→mgr. The
+    // daemon later revives mgr INTO M's frozen focus pane. Non-vacuous: a no-op (no
+    // handoff) impl leaves M as occupant, so getFocusByNode('mgr') is null AND
+    // getFocusByNode('M') still names fM — both asserts fail.
+    assert.equal(getFocusByNode('mgr')?.focus_id, 'fM', 'focus row taken over by the manager');
+    assert.equal(getFocusByNode('M'), null, 'the finished node no longer occupies any focus');
+    assert.equal(shutdown, true, 'pi shut down after the handoff');
+    // MINOR: after a successful takeover M (done) owns no pane (Invariant P) — its
+    // own presence is nulled so two rows never reference %m. 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');
+    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);
+    pi.fire('agent_end', 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);
+    pi.fire('agent_end', 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;
+    pi.fire('agent_end', 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 → idle-release FREEZE: the focus row SURVIVES 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 → idle-release
+    openFocusRow('fMgr', '%g', 'Suser', 'mgr');
+    process.env['CRTR_NODE_ID'] = 'mgr';
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    pi.fire('agent_end', stopEvent('still waiting on the worker'), { shutdown: () => { } });
+    // The awaiting branch only transition('release')s — it must NOT close or
+    // repoint the focus (that is the done branch). Non-vacuous: a wrong impl that
+    // routed an idle-release through the done-branch handoff/close would change or
+    // remove fMgr.
+    assert.equal(getNode('mgr')?.intent, 'idle-release', 'mgr idle-released (frozen)');
+    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;
+    pi.fire('agent_end', 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;
+    pi.fire('agent_end', 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');
+});
+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;
+    pi.fire('agent_end', 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');
+});

package/dist/pi-extensions/canvas-commands.d.ts

@@ -0,0 +1,34 @@
+interface AutocompleteItem {
+    value: string;
+    label?: string;
+}
+interface CommandUI {
+    notify(message: string, type?: 'info' | 'warning' | 'error'): void;
+    setStatus(key: string, text: string | undefined): void;
+}
+interface CommandCtx {
+    ui: CommandUI;
+}
+interface CustomMessage {
+    customType: string;
+    content: string;
+    display?: boolean;
+}
+interface PiLike {
+    registerCommand(name: string, options: {
+        description?: string;
+        getArgumentCompletions?: (prefix: string) => AutocompleteItem[] | null;
+        handler: (args: string, ctx: CommandCtx) => Promise<void>;
+    }): void;
+    sendMessage(message: CustomMessage, options?: {
+        triggerTurn?: boolean;
+    }): void;
+}
+/**
+ * Register the canvas slash-commands on `pi`.
+ *
+ * Returns immediately when CRTR_NODE_ID is absent — the extension is fully
+ * inert in a non-canvas pi session.
+ */
+export declare function registerCanvasCommands(pi: PiLike): void;
+export default registerCanvasCommands;