@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/core/__tests__/fixtures/fake-engine.d.ts

@@ -1,3 +1,4 @@
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
 /** Test seam (M-1 regression): a FRESH-start kickoff prompt carrying this token
  *  makes the fake engine THROW inside bindExtensions BEFORE it fires
  *  session_start — the exact failure mode that records no pid and no session, so
@@ -64,10 +65,23 @@ interface ResourceLoader {
         runtime: ExtRuntime;
     };
 }
+interface TreeEntry {
+    type: 'message';
+    id: string;
+    parentId: string | null;
+    timestamp: string;
+    message: AgentMessage;
+}
+interface SessionTreeNode {
+    entry: TreeEntry;
+    children: SessionTreeNode[];
+}
 declare class FakeSession {
     private readonly sm;
     private readonly loader;
     private readonly dir;
+    private readonly tree;
+    private promptFailuresRemaining;
     private extensions;
     private readonly injected;
     private uiContext;
@@ -78,14 +92,25 @@ declare class FakeSession {
     private timer;
     private readonly listeners;
     private readonly messageLog;
+    private turnEndLeafId;
     constructor(sm: SessionManager, loader: ResourceLoader | undefined);
-    get messages(): unknown[];
+    get messages(): AgentMessage[];
     get sessionManager(): {
         buildSessionContext: () => {
-            messages: unknown[];
+            messages: AgentMessage[];
             thinkingLevel: string;
             model: null;
         };
+        getLeafId: () => string | null;
+        getEntry: (id: string) => TreeEntry | undefined;
+        getTree: () => SessionTreeNode[];
+        getUserMessagesForForking: () => Array<{
+            entryId: string;
+            text: string;
+            timestamp?: string;
+        }>;
+        getSessionId: () => string;
+        getSessionFile: () => string;
     };
     get sessionId(): string;
     get sessionFile(): string | undefined;
@@ -98,6 +123,7 @@ declare class FakeSession {
     }): Promise<void>;
     get isStreaming(): boolean;
     getSessionStats(): Record<string, unknown>;
+    private syncTreeSnapshot;
     setSessionName(_name: string): void;
     prompt(text: string, _options?: unknown): Promise<void>;
     steer(_text: string): Promise<void>;
@@ -106,8 +132,8 @@ declare class FakeSession {
     /** In-place tree rewind (broker `navigate_tree`). Mirrors the real SDK's
      *  contract: the session file is unchanged, the live history is truncated,
      *  and the navigated-to user message's text comes back as `editorText`. The
-     *  fake's "rewind" drops the last accrued turn so a re-welcome snapshot is
-     *  observably shorter (the navigate-tree-rewelcome regression lock). */
+     *  fake's "rewind" re-anchors the active branch without deleting the abandoned
+     *  tail so the welcome snapshot can prove the one-nudge property. */
     navigateTree(targetId: string, _options?: unknown): Promise<{
         editorText?: string;
         cancelled: boolean;

package/dist/core/__tests__/fixtures/fake-engine.js

@@ -104,7 +104,7 @@ export class SessionManager {
 // ---------------------------------------------------------------------------
 // AgentSessionEvent stream synthesis (T8 / G1, G3, G4, G8). The fake emits a
 // REALISTIC streaming assistant turn through session.subscribe — the SAME channel
-// the real pi engine feeds the broker's fan-out — so the frames a `crtr attach`
+// the real pi engine feeds the broker's fan-out — so the frames a `crtr surface attach`
 // client receives are byte-for-byte real AgentSessionEvents. The EMITTED event
 // shapes are typed against the real `AgentSessionEvent` union from pi (whose full
 // 17 variants are message_start/update/end, tool_execution_start/update/end,
@@ -140,10 +140,86 @@ function assistantMessage(text, pad = 0) {
 function textDelta(partial, delta) {
     return { type: 'text_delta', contentIndex: 0, delta, partial };
 }
+class SessionTree {
+    entries = new Map();
+    children = new Map();
+    leafId = null;
+    append(message) {
+        const entry = {
+            type: 'message',
+            id: randomUUID().slice(0, 8),
+            parentId: this.leafId,
+            timestamp: new Date().toISOString(),
+            message,
+        };
+        this.entries.set(entry.id, entry);
+        const siblings = this.children.get(entry.parentId) ?? [];
+        siblings.push(entry.id);
+        this.children.set(entry.parentId, siblings);
+        this.leafId = entry.id;
+        return entry;
+    }
+    navigateTree(targetId) {
+        const entry = this.entries.get(targetId);
+        if (entry === undefined)
+            throw new Error(`[fake-engine] navigateTree: unknown entry ${targetId}`);
+        this.leafId = targetId;
+        return { cancelled: false, editorText: this.textOf(entry.message) };
+    }
+    getLeafId() {
+        return this.leafId;
+    }
+    getEntry(id) {
+        return this.entries.get(id);
+    }
+    getTree() {
+        return (this.children.get(null) ?? []).map((id) => this.node(id)).filter((node) => node !== null);
+    }
+    getUserMessagesForForking() {
+        return [...this.entries.values()]
+            .filter((entry) => entry.message.role === 'user')
+            .map((entry) => ({ entryId: entry.id, text: this.textOf(entry.message), timestamp: entry.timestamp }));
+    }
+    buildSessionContext() {
+        return { messages: this.branchMessages(), thinkingLevel: 'off', model: null };
+    }
+    branchMessages() {
+        const ids = [];
+        let cur = this.leafId;
+        while (cur !== null) {
+            const entry = this.entries.get(cur);
+            if (entry === undefined)
+                break;
+            ids.push(cur);
+            cur = entry.parentId;
+        }
+        ids.reverse();
+        return ids.map((id) => this.entries.get(id)?.message).filter((m) => m !== undefined);
+    }
+    node(id) {
+        const entry = this.entries.get(id);
+        if (entry === undefined)
+            return null;
+        return {
+            entry,
+            children: (this.children.get(id) ?? []).map((child) => this.node(child)).filter((node) => node !== null),
+        };
+    }
+    textOf(message) {
+        const content = Array.isArray(message.content) ? message.content : [];
+        for (const part of content) {
+            if (typeof part?.text === 'string' && part.text !== '')
+                return part.text;
+        }
+        return '';
+    }
+}
 class FakeSession {
     sm;
     loader;
     dir;
+    tree = new SessionTree();
+    promptFailuresRemaining;
     extensions = [];
     injected = [];
     uiContext;
@@ -156,25 +232,35 @@ class FakeSession {
     // accumulating message history the catch-up snapshot serializes (G3).
     listeners = new Set();
     messageLog = [];
+    turnEndLeafId = null;
     constructor(sm, loader) {
         this.sm = sm;
         this.loader = loader;
         this.dir = nodeDirFromEnv();
+        const configured = Number(process.env['CRTR_FAKE_ENGINE_PROMPT_FAILS'] ?? '0');
+        this.promptFailuresRemaining = Number.isFinite(configured) && configured > 0 ? Math.floor(configured) : 0;
+        this.syncTreeSnapshot();
     }
     // --- broker-read getters. buildSnapshot (on a client hello) reads messages/
     //     stats/model: T8 clients attach and assert on welcome.snapshot, so messages
     //     returns the accrued history; stats/model stay cheap stubs. ---------------
     get messages() {
-        return this.messageLog;
+        return this.tree.buildSessionContext().messages;
     }
     // The broker's catch-up snapshot reconstructs history from the persisted
     // session tree (sessionManager.buildSessionContext) — the single source of
     // truth, since `session.messages` can be sliced by pi's retry/overflow/
     // compaction recovery. Mirror that surface so the fake's snapshot still serves
-    // the accrued history (G2/G3). The fake's persisted analog IS messageLog.
+    // the accrued history (G2/G3). The fake's persisted analog is the active branch.
     get sessionManager() {
         return {
-            buildSessionContext: () => ({ messages: this.messageLog, thinkingLevel: 'off', model: null }),
+            buildSessionContext: () => this.tree.buildSessionContext(),
+            getLeafId: () => this.tree.getLeafId(),
+            getEntry: (id) => this.tree.getEntry(id),
+            getTree: () => this.tree.getTree(),
+            getUserMessagesForForking: () => this.tree.getUserMessagesForForking(),
+            getSessionId: () => this.sm.getSessionId(),
+            getSessionFile: () => this.sm.getSessionFile(),
         };
     }
     get sessionId() {
@@ -200,19 +286,33 @@ class FakeSession {
     getSessionStats() {
         return { messages: 0, tokens: 0 };
     }
+    syncTreeSnapshot() {
+        try {
+            writeFileSync(join(this.dir, 'fake-pi.tree.json'), JSON.stringify({
+                leafId: this.tree.getLeafId(),
+                activeBranch: this.tree.buildSessionContext().messages,
+                tree: this.tree.getTree(),
+                userMessagesForForking: this.tree.getUserMessagesForForking(),
+            }, null, 2));
+        }
+        catch {
+            /* best effort */
+        }
+    }
     // --- naming is cosmetic (broker calls it in a try/catch) ---------------------
     setSessionName(_name) {
         /* no-op recording stub */
     }
     // --- controller-drive stubs (no controller connects in these tests) ----------
     prompt(text, _options) {
-        // The broker calls this for BOTH the fresh-start kickoff AND a controller's
-        // `prompt` frame (G1/G4). Either way emit a realistic streaming turn on the
-        // subscribe channel; the broker fans it out to every attached viewer VERBATIM.
-        // This is the SUBSCRIBE channel only — it does NOT run the canvas stophook
-        // (that fires via the separate extension-handler channel in dispatch()/fire()),
-        // so it never tears the broker down. The broker fire-and-forgets the promise.
-        return this.emitTurn(text);
+        // The broker calls this for the controller-less retry path. Emit the turn
+        // on the broker's subscribe channel and also run the real extension hooks so
+        // the canvas stophook records the fault marker and the broker can schedule
+        // the next retry.
+        const fail = this.promptFailuresRemaining > 0;
+        if (fail)
+            this.promptFailuresRemaining--;
+        return this.emitTurn(text, { fail, runHooks: true });
     }
     steer(_text) {
         return Promise.resolve();
@@ -226,11 +326,12 @@ class FakeSession {
     /** In-place tree rewind (broker `navigate_tree`). Mirrors the real SDK's
      *  contract: the session file is unchanged, the live history is truncated,
      *  and the navigated-to user message's text comes back as `editorText`. The
-     *  fake's "rewind" drops the last accrued turn so a re-welcome snapshot is
-     *  observably shorter (the navigate-tree-rewelcome regression lock). */
+     *  fake's "rewind" re-anchors the active branch without deleting the abandoned
+     *  tail so the welcome snapshot can prove the one-nudge property. */
     navigateTree(targetId, _options) {
-        this.messageLog.pop();
-        return Promise.resolve({ cancelled: false, editorText: `rewound-to:${targetId}` });
+        const result = this.tree.navigateTree(targetId);
+        this.syncTreeSnapshot();
+        return Promise.resolve(result);
     }
     // --- the single engine event stream the broker fans out (broker.ts subscribes
     //     here and broadcasts each event VERBATIM to every attached viewer) --------
@@ -266,6 +367,7 @@ class FakeSession {
         const updates = opts.updates ?? 3;
         const pad = opts.padBytes ?? 0;
         const withTool = opts.tool ?? true;
+        const fail = opts.fail === true;
         const small = assistantMessage(text);
         // A normal turn yields with setImmediate (fast). A sized flood (G8, pad>0) is
         // PACED with a small real delay so a fast (reading) viewer always drains each
@@ -274,6 +376,9 @@ class FakeSession {
         // pace the burst outruns the reader's event loop and sheds the fast viewer too.
         const yieldTick = () => pad > 0 ? new Promise((r) => setTimeout(r, 3)) : new Promise((r) => setImmediate(r));
         this.streaming = true;
+        if (opts.runHooks === true) {
+            await this.fire('agent_start', {}, this.buildCtx());
+        }
         this.emit({ type: 'agent_start' });
         this.emit({ type: 'turn_start' });
         this.emit({ type: 'message_start', message: small });
@@ -337,14 +442,39 @@ class FakeSession {
         }
         if (this.disposed)
             return;
-        const finalMsg = assistantMessage(text);
+        const userMsg = {
+            role: 'user',
+            content: [{ type: 'text', text }],
+            timestamp: Date.now(),
+        };
+        this.tree.append(userMsg);
+        this.syncTreeSnapshot();
+        const finalMsg = fail
+            ? { ...assistantMessage(text), stopReason: 'error', errorMessage: 'Connection error.' }
+            : assistantMessage(text);
         this.emit({ type: 'message_end', message: finalMsg });
         this.emit({ type: 'turn_end', message: finalMsg, toolResults: [] });
         this.messageLog.push(finalMsg);
+        const anchorBeforeFinal = this.tree.getLeafId();
+        this.turnEndLeafId = anchorBeforeFinal;
+        this.tree.append(finalMsg);
+        this.syncTreeSnapshot();
+        if (opts.runHooks === true) {
+            const hookCtx = this.buildCtx();
+            await this.fire('turn_end', { message: finalMsg, toolResults: [] }, hookCtx);
+            const hookMessages = fail
+                ? [...this.tree.buildSessionContext().messages, finalMsg]
+                : this.tree.buildSessionContext().messages.slice();
+            await this.fire('agent_end', { messages: hookMessages, willRetry: false }, hookCtx);
+        }
+        this.turnEndLeafId = null;
         this.streaming = false;
         // agent_end on the SUBSCRIBE channel is a relayed frame ONLY (willRetry=false);
         // it never runs the stophook, so the broker stays alive (G2/G3/G4/G8).
-        this.emit({ type: 'agent_end', messages: this.messageLog.slice(), willRetry: false });
+        const agentEndMessages = fail
+            ? [...this.tree.buildSessionContext().messages, finalMsg]
+            : this.tree.buildSessionContext().messages.slice();
+        this.emit({ type: 'agent_end', messages: agentEndMessages, willRetry: false });
     }
     dispose() {
         this.disposed = true;
@@ -470,6 +600,7 @@ class FakeSession {
             sessionManager: {
                 getSessionId: () => this.sm.getSessionId(),
                 getSessionFile: () => this.sm.getSessionFile(),
+                getLeafId: () => this.turnEndLeafId ?? this.tree.getLeafId(),
             },
             getContextUsage: () => ({ tokens: 1000 }),
             // Wired to the broker's shutdownHandler: the stophook calls ctx.shutdown()
@@ -557,7 +688,15 @@ class FakeSession {
                 this.streaming = false;
                 await this.fire('agent_end', {
                     messages: [
-                        { role: 'assistant', stopReason: cmd.reason ?? 'stop', content: [{ type: 'text', text: cmd.text ?? '' }] },
+                        {
+                            role: 'assistant',
+                            stopReason: cmd.reason ?? 'stop',
+                            // A real engine attaches errorMessage on a stopReason:'error'
+                            // turn; the stophook classifies it for the active-fault marker.
+                            // Forward it so a test can drive a CONNECTION stall faithfully.
+                            ...(cmd.errorMessage === undefined ? {} : { errorMessage: cmd.errorMessage }),
+                            content: [{ type: 'text', text: cmd.text ?? '' }],
+                        },
                     ],
                 }, ctx);
                 break;

package/dist/core/__tests__/fixtures/fake-pi-host.js

@@ -255,7 +255,16 @@ async function dispatch(cmd) {
             streaming = false;
             await fire('agent_end', {
                 messages: [
-                    { role: 'assistant', stopReason: cmd.reason ?? 'stop', content: [{ type: 'text', text: cmd.text ?? '' }] },
+                    {
+                        role: 'assistant',
+                        stopReason: cmd.reason ?? 'stop',
+                        // A real engine attaches errorMessage on a stopReason:'error' turn;
+                        // the stophook classifies it (connection/rate-limit/…) for the
+                        // active-fault marker. Forward it so a test can drive a CONNECTION
+                        // stall faithfully.
+                        ...(cmd.errorMessage === undefined ? {} : { errorMessage: cmd.errorMessage }),
+                        content: [{ type: 'text', text: cmd.text ?? '' }],
+                    },
                 ],
             }, ctx);
             ack(id, { ok: true });

package/dist/core/__tests__/full/broker-attach-limits.test.js

@@ -3,7 +3,7 @@
 // FULL TIER (real-boot-bound): tmux-free, but it boots a REAL broker process
 // (~5s pi-SDK load), so it lives in full/ (CI), not the fast local loop.
 //
-// T8 — the `crtr attach` acceptance gate, gates G4/G7/G8/G9 (controller
+// T8 — the `crtr surface attach` acceptance gate, gates G4/G7/G8/G9 (controller
 // arbitration, decoder overflow caps, backpressure shedding, and the load-bearing
 // ONE-WRITER proof). Split out of broker-lifecycle.test.ts; the gates are the
 // original acceptance gate, unchanged.

package/dist/core/__tests__/full/broker-attach-stream.test.js

@@ -3,7 +3,7 @@
 // FULL TIER (real-boot-bound): tmux-free, but it boots a REAL broker process
 // (~5s pi-SDK load), so it lives in full/ (CI), not the fast local loop.
 //
-// T8 — the `crtr attach` acceptance gate, gates G1/G1b/G2/G3 (controller drive,
+// T8 — the `crtr surface attach` acceptance gate, gates G1/G1b/G2/G3 (controller drive,
 // relay/coalescing, detach survival, catch-up snapshot). Split out of
 // broker-lifecycle.test.ts; the gates are the original acceptance gate, unchanged.
 //

package/dist/core/__tests__/full/broker-crash-teardown.test.js

@@ -12,7 +12,7 @@
 //     • items 4–6: a CRASHED broker (pid killed out from under the daemon) must
 //       grace-revive RESUMING the saved .jsonl, ONE-WRITER (the crashed pid is
 //       dead BEFORE the revive launches and never resurrects; the revived pid is
-//       distinct); and a clean `node close` tears the broker down (shutdown frame
+//       distinct); and a clean `node lifecycle close` tears the broker down (shutdown frame
 //       → exit, socket unlinked, status canceled, daemon leaves it).
 //     • M-1/M-2: a broker that DIES before session_start records NO pid and NO
 //       session EVER. Read pid==null unconditionally as "still booting" and the
@@ -40,7 +40,8 @@
 //     RED. Verified by reverting that branch (see bug-injection report).
 import { test, before, after } from 'node:test';
 import assert from 'node:assert/strict';
-import { existsSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { createHarness } from '../helpers/harness.js';
 import { subscribe } from '../../canvas/canvas.js';
 import { isPidAlive } from '../../canvas/pid.js';
@@ -84,13 +85,17 @@ test('CRASH → grace-revive RESUME (one-writer), then clean teardown on close',
     assert.ok(newPid != null && isPidAlive(newPid), 'the revived broker pid is alive');
     assert.notEqual(newPid, oldPid, 'the revived pid is distinct from the crashed one');
     assert.equal(isPidAlive(oldPid), false, 'one-writer: the crashed pid never resurrected');
-    // --- Item 5: clean teardown of the (revived, live) broker. node close marks
+    // --- Item 5: clean teardown of the (revived, live) broker. node lifecycle close marks
     //     canceled BEFORE teardown (crash-safe order), then hostFor(broker).teardown
     //     sends the `shutdown` frame → the broker disposes + exits, socket unlinked. ---
+    const sessionFile = h.node(id).pi_session_file;
+    assert.ok(sessionFile !== null && sessionFile !== undefined, 'revived broker has a session file');
+    mkdirSync(join(sessionFile, '..'), { recursive: true });
+    writeFileSync(sessionFile, JSON.stringify({ type: 'message', message: { role: 'assistant', content: [{ type: 'text', text: 'hi' }] } }) + '\n');
     const sock = h.brokerSock(id);
     await h.waitFor(() => existsSync(sock), { label: 'revived broker created its view.sock' });
-    const res = h.cli(root, ['node', 'close', '--node', id]);
-    assert.equal(res.code, 0, `node close should exit 0\n--stderr--\n${res.stderr}`);
+    const res = h.cli(root, ['node', 'lifecycle', 'close', '--node', id]);
+    assert.equal(res.code, 0, `node lifecycle close should exit 0\n--stderr--\n${res.stderr}`);
     await h.waitFor(() => !isPidAlive(newPid), { label: 'broker process exited on shutdown frame' });
     await h.waitFor(() => !existsSync(sock), { label: 'broker unlinked its socket on exit' });
     assert.equal(h.status(id), 'canceled', 'the closed node is canceled');

package/dist/core/__tests__/full/broker-model-changed-broadcast.test.js

@@ -3,7 +3,7 @@
 // FULL TIER (real-boot-bound): tmux-free, but it boots a REAL broker process,
 // so it lives in full/ (CI), not the fast local loop.
 //
-// BUG-REGRESSION (real, observed 2026-06-11 in `crtr attach`): switching the
+// BUG-REGRESSION (real, observed 2026-06-11 in `crtr surface attach`): switching the
 // model (/model <provider/id> or the picker) visibly did nothing — the viewer's
 // status bar kept showing the OLD model until some unrelated event happened to
 // arrive.

package/dist/core/__tests__/full/broker-navigate-tree-rewelcome.test.js

@@ -3,7 +3,7 @@
 // FULL TIER (real-boot-bound): tmux-free, but it boots a REAL broker process,
 // so it lives in full/ (CI), not the fast local loop.
 //
-// BUG-REGRESSION (real, observed 2026-06-11 in `crtr attach`): double-Esc (or
+// BUG-REGRESSION (real, observed 2026-06-11 in `crtr surface attach`): double-Esc (or
 // /tree) opened the session-tree picker, but SELECTING an entry visibly did
 // nothing — the viewer stayed on the old transcript instead of traveling back
 // to the chosen point in time.

package/dist/core/__tests__/full/broker-pane-resolution.test.js

@@ -6,7 +6,7 @@
 //
 // (1) Gap 1 — `nodeInPane()` (src/commands/node.ts) resolved a pane via
 //     window→node ONLY. A broker engine runs DETACHED with window=null, and its
-//     on-screen presence is a `crtr attach` VIEWER pane, so the window lookup
+//     on-screen presence is a `crtr surface attach` VIEWER pane, so the window lookup
 //     never found it: `node cycle`/`recycle`/`close`/`demote`/`lifecycle` all
 //     broke when the current pane was a broker viewer. The fix has attach
 //     self-tag its pane `@crtr_node=<id>` and nodeInPane resolve that tag first.

package/dist/core/__tests__/full/cascade-close.test.js

@@ -1,10 +1,10 @@
 // Run with: node --import tsx/esm --test src/core/__tests__/cascade-close.test.ts
 //
 // CASCADE CLOSE + exclusive-subtree ownership — a FAITHFUL integration test of
-// `crtr node close` on a MIDDLE node, driven through the REAL CLI against a REAL
+// `crtr node lifecycle close` on a MIDDLE node, driven through the REAL CLI against a REAL
 // isolated tmux session with REAL fake-pi vehicles in REAL panes, asserting off
 // the canvas data layer and checked against the state-model ORACLE
-// (state-model.md §4 `node close`, §5 cascade-close ownership, invariant 3,
+// (state-model.md §4 `node lifecycle close`, §5 cascade-close ownership, invariant 3,
 // ambiguity A5).
 //
 // WHY this exists alongside the unit `close.test.ts`: that test exercises
@@ -32,11 +32,11 @@
 //     └── S                sideways sibling subtree — MUST survive
 //         └── G
 //
-//   close(B) ⇒ exclusive subtree {B,C,D,E} reaped; A,S,G untouched.
+//   close(B) ⇒ exclusive subtree {B,C,D,E} canceled; A,S,G untouched.
 //
 // CRITICAL DELIVERABLE (ambiguity A5): the EXACT terminal status a cascade-
-// reaped descendant receives under `node close`. CURRENT behavior, asserted
-// end-to-end below: status === 'canceled', intent === null (cleared) — for the
+// closed descendant receives under `node lifecycle close`. With the fixtures made
+// non-empty below: status === 'canceled', intent === null (cleared) — for the
 // cascade ROOT and EVERY descendant alike (`transition(id,'cancel')`,
 // close.ts → lifecycle.ts cancel row: status='canceled', intent=null, from '*').
 // This differs from the ancestor-RESET path (`reapDescendants` → `reap` → 'done')
@@ -52,12 +52,18 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { createHarness, hasTmux } from '../helpers/harness.js';
 import { isPidAlive } from '../../canvas/pid.js';
 function sessionExists(session) {
     return spawnSync('tmux', ['has-session', '-t', session], { stdio: 'ignore' }).status === 0;
 }
-test('cascade close: middle-node close reaps EXACTLY its subtree (canceled), ancestor + sideways untouched, edges persist', { skip: !hasTmux() ? 'tmux unavailable' : false, timeout: 180_000 }, async () => {
+function seedAssistantSession(sessionFile) {
+    mkdirSync(join(sessionFile, '..'), { recursive: true });
+    writeFileSync(sessionFile, JSON.stringify({ type: 'message', message: { role: 'assistant', content: [{ type: 'text', text: 'hi' }] } }) + '\n');
+}
+test('cascade close: middle-node lifecycle close cancels EXACTLY its subtree, ancestor + sideways untouched, edges persist', { skip: !hasTmux() ? 'tmux unavailable' : false, timeout: 180_000 }, async () => {
     const h = await createHarness({ sessionPrefix: 'crtr-cascade' });
     try {
         // ===================================================================
@@ -73,16 +79,23 @@ test('cascade close: middle-node close reaps EXACTLY its subtree (canceled), anc
         const D = await h.spawnChild(B, 'B child two'); // breadth: B has {C, D}
         const S = await h.spawnChild(A, 'sideways sibling of B'); // sideways subtree
         const G = await h.spawnChild(S, 'child of the sideways sibling');
-        const subtree = [B, C, D, E]; // B's exclusive subtree (the expected reap set)
+        const subtree = [B, C, D, E]; // B's exclusive subtree (the expected cancel set)
         const sideways = [S, G]; // a sibling subtree — must be wholly untouched
+        // Make the close-path fixtures NON-EMPTY so close exercises cancel+notice
+        // semantics instead of the new reap-empty path.
+        for (const id of subtree) {
+            const sessionFile = h.node(id).pi_session_file;
+            assert.ok(sessionFile !== null && sessionFile !== undefined, `${id} has a session file`);
+            seedAssistantSession(sessionFile);
+        }
         // Pre-close sanity: every node live + present, spine wired as drawn.
         {
             for (const id of [B, C, D, E, S, G]) {
-                assert.equal(h.status(id), 'active', `${id} active before close`);
+                assert.ok(h.status(id) === 'active' || h.status(id) === 'idle', `${id} live before close`);
                 const pid = h.node(id).pi_pid;
                 assert.ok(pid != null && isPidAlive(pid), `${id} broker engine alive before close`);
             }
-            assert.equal(h.status(A), 'active', 'A (root) active before close');
+            assert.ok(h.status(A) === 'active' || h.status(A) === 'idle', 'A (root) live before close');
             // Spine: A→{B,S}, B→{C,D}, C→{E}, S→{G} (all active spawn-seed edges).
             const subIds = (n) => h.subscriptions(n).map((s) => s.node_id).sort();
             assert.deepEqual(subIds(A), [B, S].sort(), 'A subscribes_to B and S');
@@ -105,19 +118,19 @@ test('cascade close: middle-node close reaps EXACTLY its subtree (canceled), anc
         const aInboxBefore = h.inbox(A);
         assert.ok(aInboxBefore.some((e) => e.from === B && e.kind === 'update'), "A's inbox holds B's pre-close update (non-vacuous 'intact' baseline)");
         // ===================================================================
-        // CLOSE the MIDDLE node B, through the REAL CLI (`crtr node close --node B`,
+        // CLOSE the MIDDLE node B, through the REAL CLI (`crtr node lifecycle close --node B`,
         // run AS the root A). closeNode is synchronous in the subprocess: by the
         // time it returns, rows are flipped and panes are killed.
         // ===================================================================
-        const closeRes = h.cli(A, ['node', 'close', '--node', B]);
-        assert.equal(closeRes.code, 0, `node close exit 0\n${closeRes.stderr}`);
+        const closeRes = h.cli(A, ['node', 'lifecycle', 'close', '--node', B]);
+        assert.equal(closeRes.code, 0, `node lifecycle close exit 0\n${closeRes.stderr}`);
         // The CLI's own rendered report (plain markdown): cascade root B, exactly
         // 4 closed, 0 spared (no spared clause is emitted when none were spared).
         assert.match(closeRes.stdout, new RegExp(`^Closed ${B} and its exclusive subtree — 4 node\\(s\\) closed\\.`), `close report names B as root, count=4, spared=0\n${closeRes.stdout}`);
         // ===================================================================
         // ASSERT 1 — the A5 DELIVERABLE: the EXACT terminal status of every
-        // cascade-reaped node. CURRENT behavior: status='canceled', intent=null,
-        // for the ROOT (B) and EVERY descendant {C,D,E} identically.
+        // cascade-closed node. With the fixtures now non-empty, close exercises
+        // cancel+notice semantics and the rows remain present as canceled husks.
         // ===================================================================
         for (const id of subtree) {
             const n = h.node(id);
@@ -125,11 +138,11 @@ test('cascade close: middle-node close reaps EXACTLY its subtree (canceled), anc
             assert.strictEqual(n.intent ?? null, null, `${id} intent cleared to null on cancel`);
         }
         // Pin the exact field tuple once more, explicitly, for the human decision:
-        // a cascade-reaped descendant under `node close` reads (canceled, null) —
+        // a cascade-closed descendant under `node lifecycle close` reads (canceled, null) —
         // NOT (done, done) and NOT (done, null). This is the confirmed A5 fact.
         {
             const e = h.node(E); // the deepest descendant
-            assert.deepEqual({ status: e.status, intent: e.intent ?? null }, { status: 'canceled', intent: null }, "deepest reaped descendant E: (status,intent) === ('canceled', null)");
+            assert.deepEqual({ status: e.status, intent: e.intent ?? null }, { status: 'canceled', intent: null }, "deepest closed descendant E: (status,intent) === ('canceled', null)");
         }
         // ===================================================================
         // ASSERT 2 — broker ENGINE torn down for the ENTIRE subtree (the real
@@ -146,7 +159,7 @@ test('cascade close: middle-node close reaps EXACTLY its subtree (canceled), anc
         }
         // ===================================================================
         // ASSERT 3 — EXCLUSIVE-SUBTREE OWNERSHIP: nothing ABOVE (A) and nothing
-        // SIDEWAYS (S, G) was reaped. close(B) reaped EXACTLY B's own subtree.
+        // SIDEWAYS (S, G) was reaped. close(B) canceled EXACTLY B's own subtree.
         // ===================================================================
         // Ancestor A — lifecycle untouched (still the live resident root), but A is
         // the SURVIVING manager of the close-root B, so the wake doctrine fix WAKES
@@ -168,7 +181,7 @@ test('cascade close: middle-node close reaps EXACTLY its subtree (canceled), anc
         }
         // Sideways subtree S→G — wholly alive: status active AND broker engine alive.
         for (const id of sideways) {
-            assert.equal(h.status(id), 'active', `${id} (sideways) still active — not reaped`);
+            assert.equal(h.status(id), 'active', `${id} (sideways) still active — not canceled`);
             const pid = h.node(id).pi_pid;
             assert.ok(pid != null && isPidAlive(pid), `${id} (sideways) broker engine still alive`);
         }

package/dist/core/__tests__/full/detach-focus.test.js

@@ -5,7 +5,7 @@
 // BROKER-CUT ADAPTATION (taste/broker-is-the-host, 2026-06-10): every node is a
 // detached headless broker. After a09b71f a managed child opens NO viewer on
 // spawn — a viewer is opened on demand via `node focus`, registering its
-// `crtr attach` VIEWER pane in the focuses table. The engine is NOT in a pane, so the
+// `crtr surface attach` VIEWER pane in the focuses table. The engine is NOT in a pane, so the
 // pre-cut "relocate the still-running pi pane to the backstage" behavior —
 // detachToBackground's engine break-pane/release path, and its isGenerating()
 // gate that released a non-generating node to dormant — is DELETED. The Bug-1
@@ -60,7 +60,7 @@ test('node demote --detach: flips terminal in place, CLOSES the viewer pane + fo
         assert.equal(b0.status, 'active', 'B active after boot');
         const brokerPid = b0.pi_pid;
         assert.ok(brokerPid != null && isPidAlive(brokerPid), 'B broker engine alive before detach');
-        // Put B genuinely "on screen": `node focus` opens its one `crtr attach`
+        // Put B genuinely "on screen": `node focus` opens its one `crtr surface attach`
         // VIEWER pane beside a caller pane in the harness session, registering the
         // viewer focus row (§A.3) — the on-demand viewer the detach then tears down.
         const caller = makePane(h.session);

package/dist/core/__tests__/full/human-new-window-regression.test.js

@@ -1,6 +1,6 @@
 // Run with: node --import tsx/esm --test src/core/__tests__/human-new-window-regression.test.ts
 //
-// BUG REGRESSION: `crtr human ask|approve|review|notify` opened NO pane at all.
+// BUG REGRESSION: `crtr human ask|review|notify` opened NO pane at all.
 //
 // spawnAndDetach's 'new-window' placement passed a tmux PANE id straight to
 // `new-window -t` (`new-window -d -a -t %<pane>`). tmux REJECTS a pane id for