@crouton-kit/crouter 0.3.16 → 0.3.18

package/dist/commands/node.js

@@ -15,7 +15,8 @@ import { detachToBackground, focus as placementFocus, windowAlive, windowOfPane,
 import { buildLaunchSpec } from '../core/runtime/launch.js';
 import { closeNode } from '../core/runtime/close.js';
 import { appendInbox } from '../core/feed/inbox.js';
-import { availableKinds } from '../core/personas/index.js';
+import { availableKinds, kindWhenToUse, subPersonasFor } from '../core/personas/index.js';
+import { stateBlock } from '../core/help.js';
 import { getNode, updateNode, listNodes, subscribe, unsubscribe, subscriptionsOf, subscribersOf, readContextTokens, } from '../core/canvas/index.js';
 // Past this much context, an ORCHESTRATOR that spawns a managed child is better
 // off yielding than holding its fat window open for the child's result: the
@@ -47,6 +48,52 @@ function assertKind(kind) {
         throw new InputError({ error: 'unknown_kind', message: `unknown kind: ${kind}`, field: 'kind', next: `Valid kinds: ${kinds.join(', ')}.` });
     }
 }
+/** A live `<kinds count=N>` state element — one `<kind> — <whenToUse>` line per
+ *  installed top-level persona kind (project > user > builtin), lazily built so
+ *  it reflects the caller's cwd/project scope. Appended to `node new -h` and
+ *  `node promote -h` so custom kinds appear in help. Soft-fails via the renderer.
+ *
+ *  CONTEXT-AWARE: when the CALLER is a live node (CRTR_NODE_ID set) whose kind
+ *  has sub-personas available to it, a SECOND `<sub-personas for=K count=M>`
+ *  block is appended right after — the specialist sub-personas THAT kind may
+ *  spawn (full kind string + whenToUse). Everything but the top-level `<kinds>`
+ *  block soft-fails to omission (caller block wrapped in its own try/catch). */
+function kindsStateBlock() {
+    const kinds = availableKinds();
+    const lines = kinds
+        .map((k) => {
+        const w = kindWhenToUse(k);
+        return w ? `${k} — ${w}` : k;
+    })
+        .join('\n');
+    const block = stateBlock('kinds', { count: kinds.length }, lines);
+    const sub = callerSubPersonasBlock();
+    return sub ? `${block}\n${sub}` : block;
+}
+/** When the caller is a live node whose kind has sub-personas available to it,
+ *  render a `<sub-personas for="<kind>" count=M>` block — one
+ *  `<full-kind-string> — <whenToUse>` line per sub-persona spawnable BY that
+ *  kind (e.g. `plan/reviewers/security`). Returns '' (so the second block is
+ *  omitted) when CRTR_NODE_ID is unset, getNode returns null, the caller kind
+ *  has no sub-personas, or anything throws — this is help output, never error. */
+function callerSubPersonasBlock() {
+    try {
+        const id = process.env['CRTR_NODE_ID'];
+        if (id === undefined || id === '')
+            return '';
+        const node = getNode(id);
+        if (node === null)
+            return '';
+        const subs = subPersonasFor(node.kind);
+        if (subs.length === 0)
+            return '';
+        const lines = subs.map((s) => (s.whenToUse ? `${s.kind} — ${s.whenToUse}` : s.kind)).join('\n');
+        return stateBlock('sub-personas', { for: node.kind, count: subs.length }, lines);
+    }
+    catch {
+        return '';
+    }
+}
 // ---------------------------------------------------------------------------
 // node new — spawn a terminal worker as a background window under the root
 // ---------------------------------------------------------------------------
@@ -60,7 +107,7 @@ const nodeNew = defineLeaf({
         summary: 'spawn a terminal worker onto the canvas as a background window — returns its node id',
         params: [
             { kind: 'stdin', name: 'prompt', required: true, constraint: 'First user message for the spawned node. Piped on stdin or passed as a positional.' },
-            { kind: 'flag', name: 'kind', type: 'string', required: false, default: 'general', constraint: 'Persona kind — match the work: explore (map/investigate a codebase), spec (write a spec), design (architect a solution), plan (break work into steps), developer (implement a change), review (validate/critique), general (anything else).' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, default: 'general', constraint: 'Persona kind — match the work to the kind. The <kinds> list below names every installable kind and when to use each; the <sub-personas> block (when present) names the specialist sub-personas available to YOU, each spawnable by its full kind string (e.g. plan/reviewers/security).' },
             { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, default: 'base', constraint: 'Persona mode. base for a worker that finishes in one window; orchestrator to create the child directly as a sub-orchestrator (it boots with the orchestrator persona + a seeded roadmap and fans its scope out) — use it when the unit is too large for one window, e.g. a big review, instead of spawning a base worker and counting on it to promote itself.' },
             { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Dir the node is pinned to. Defaults to the caller cwd.' },
             { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Display name (tmux window + resume picker). Defaults to the kind.' },
@@ -76,9 +123,10 @@ const nodeNew = defineLeaf({
             { name: 'status', type: 'string', required: true, constraint: 'Always "active" on spawn.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Decision road sign for the caller: the child runs independently and its finish wakes you on its own, so never wait or poll on it — either pick up other work now or end your turn. If you are an orchestrator already deep in context (>100k), it instead steers you to `crtr node yield` now so your fresh revive absorbs the child\'s result. Read it, then act.' },
         ],
+        dynamicState: () => kindsStateBlock(),
         outputKind: 'object',
         effects: [
-            'Creates a node under ~/.crtr/nodes/<id>/ and indexes it in canvas.db.',
+            'Creates a node under ~/.crouter/canvas/nodes/<id>/ and indexes it in canvas.db.',
             'Default (managed child): parent auto-subscribes (active) and is woken on the child\'s pushes. With --root: no subscription — records a spawned_by edge for provenance only.',
             'Opens a tmux window running pi: a background (non-focus-stealing) window in the shared crtr session for a child; with --root, a new window in your current session (in-tmux) or the shared session (outside tmux), with the client switched to it.',
         ],
@@ -191,6 +239,7 @@ const nodeFocus = defineLeaf({
         params: [
             { kind: 'positional', name: 'node', required: true, constraint: 'Node id to focus.' },
             { kind: 'flag', name: 'new-pane', type: 'bool', required: false, constraint: 'Open the node in a NEW viewport SIDE-BY-SIDE with your current pane (a second focus) instead of swapping it into your pane. Two agents on screen at once (F4).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id to focus INTO (default: caller TMUX_PANE). Used by the canvas browser popup to focus back into the originating pane.' },
         ],
         output: [
             { name: 'focused', type: 'boolean', required: true, constraint: 'True when the node was brought into view.' },
@@ -206,11 +255,23 @@ const nodeFocus = defineLeaf({
         const node = getNode(id);
         if (node === null)
             throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        // A kind:'human' node is a control-plane ASK (a humanloop deck on the human's
+        // screen), NOT a pi conversation — it has no session. Reviving one boots a
+        // confused blank "you have been revived" pi, so refuse rather than focus it.
+        // (The nav/resume UIs already hide human nodes; this guards a hand-typed id.)
+        if (node.kind === 'human') {
+            throw new InputError({
+                error: 'not_focusable',
+                message: `node ${id} is a human-ask (kind:human), not a conversation — it has no pi session to focus.`,
+                next: `The pending question is already on the human's screen; see it with \`crtr human list\` / \`crtr human inbox\`, or retract it with \`crtr human cancel ${id}\`.`,
+            });
+        }
         // Placement owns the whole act (§2.3): resolve the caller's focus (or open a
         // new viewport with --new-pane), revive the target into the backstage if it
         // is dormant, then hot-swap it onto the focus. The reviver is injected so
         // placement need not import revive.ts.
         const res = placementFocus(id, {
+            pane: input['pane'],
             newPane: input['newPane'] === true,
             callerNode: process.env['CRTR_NODE_ID'],
             revive: (nid) => { reviveNode(nid, { resume: true }); },
@@ -548,7 +609,7 @@ const nodePromote = defineLeaf({
         name: 'node promote',
         summary: 'promote yourself to an orchestrator — do this when your task outgrows one context window (many phases to delegate and persist across refreshes); not for work that fits one window, and not merely because you spawned a child. Mode only — lifecycle stays as-is unless you pass --resident',
         params: [
-            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Specialize as this kind of orchestrator: developer (own feature delivery), review, spec, design, plan, explore, general. Defaults to your current kind. Promoting from a generic kind? CHOOSE a concrete one — it sets the orchestrator persona you revive into.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Specialize as this kind of orchestrator. The <kinds> list below names every installable kind and when to use each; the <sub-personas> block (when present) names the specialist sub-personas available to YOU, spawnable by full kind string. Defaults to your current kind. Promoting from a generic kind? CHOOSE a concrete one — it sets the orchestrator persona you revive into.' },
             { kind: 'flag', name: 'resident', type: 'bool', required: false, constraint: 'ALSO flip lifecycle→resident: make the node interactable — it stays dormant, woken by inbox/human, and is never forced to submit a final. Omit to stay terminal/orchestrator (delegates + holds a roadmap, but still owes a final up the spine and reaps when done).' },
             { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node to promote. Defaults to the caller (CRTR_NODE_ID).' },
         ],
@@ -564,6 +625,7 @@ const nodePromote = defineLeaf({
             { name: 'user_memory_path', type: 'string', required: true, constraint: 'Absolute path to your USER-GLOBAL memory index (<crtrHome>/memory/MEMORY.md) — who the human is, how they like to work; loaded into every orchestrator everywhere.' },
             { name: 'project_memory_path', type: 'string', required: true, constraint: 'Absolute path to your PROJECT memory index (<crtrHome>/projects/<key>/memory/MEMORY.md) — facts bound to this repo; loaded into every orchestrator working here.' },
         ],
+        dynamicState: () => kindsStateBlock(),
         outputKind: 'object',
         effects: ['Flips mode→orchestrator + kind→chosen (lifecycle unchanged unless --resident, which also flips lifecycle→resident); rewrites the launch spec to that kind\'s orchestrator persona; seeds context/roadmap.md scaffold + all three scoped memory stores (user-global, project, node-local) if absent.', 'Your new-role guidance is injected automatically at the turn boundary by the persona injector — the command no longer returns it.'],
     },

package/dist/commands/skill/author.js

@@ -13,7 +13,7 @@ import { VALID_TYPES, resolveWriteScope } from './shared.js';
 export const authorGuide = defineLeaf({
     name: 'guide',
     description: 'load authoring workflow + skeleton for a type',
-    whenToUse: 'writing a new skill and you want the authoring workflow plus the template skeleton — call it once with no --type for the template picker, then again with --type for the full workflow and skeleton of that type.',
+    whenToUse: 'REQUIRED reading before you author a new skill OR edit an existing one — it carries the SKILL.md format, the description-drives-discovery rule (when-to-use lives in the frontmatter description, never the body), the voice constraints, and the per-type workflow. Call it once with no --type for the template picker, then again with --type for that type\'s full workflow and skeleton. Editing an existing skill counts: read this first, because the format and voice rules govern every change, not just new files.',
     help: {
         name: 'skill author guide',
         summary: 'load the skill authoring workflow — two stages: omit type to pick one, pass type for its full skeleton',
@@ -140,7 +140,7 @@ export const authorScaffold = defineLeaf({
 export const authorBranch = defineBranch({
     name: 'author',
     description: 'create and scaffold skills',
-    whenToUse: 'you have a reusable workflow, methodology, or hard-won convention worth capturing so future agents adopt it instead of re-deriving it — author carries you from picking a template through scaffolding the file. Reach for it when a task just taught you a repeatable procedure, when the same guidance keeps getting re-explained across sessions, or when the house conventions for a tool deserve to be written down once. Start with `crtr skill author guide` for the template picker and authoring workflow; use `crtr skill author scaffold` to stub the SKILL.md file.',
+    whenToUse: 'you have a reusable workflow, methodology, or hard-won convention worth capturing so future agents adopt it instead of re-deriving it — author carries you from picking a template through scaffolding the file. Reach for it when a task just taught you a repeatable procedure, when the same guidance keeps getting re-explained across sessions, or when the house conventions for a tool deserve to be written down once. Always start with `crtr skill author guide` — required reading before you author OR edit any skill (the SKILL.md format, the description-vs-body rule, and the voice constraints all live there) — then use `crtr skill author scaffold` to stub the SKILL.md file.',
     help: {
         name: 'skill author',
         summary: 'create and scaffold new skills',

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

@@ -0,0 +1,199 @@
+// 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
+// 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,
+// ambiguity A5).
+//
+// WHY this exists alongside the unit `close.test.ts`: that test exercises
+// `closeNode()` in-process against the data layer with FABRICATED pane strings
+// (`pane:'%x'`) — it proves the closing-set fixpoint and the status flip, but it
+// never kills a real tmux pane, never boots a real vehicle, and never closes a
+// MIDDLE node with a live sideways-sibling subtree. This test fills exactly that
+// gap: it builds a real tree, closes the middle, and proves the reap is EXACTLY
+// the closed node's own subtree — nothing above (the ancestor) or sideways (a
+// sibling subtree) is touched, and real panes actually die.
+//
+// The tree (covers BOTH required shapes in one topology):
+//
+//     A (resident root, in-process)
+//     ├── B   ◄── CLOSE TARGET (the middle node)
+//     │   ├── C
+//     │   │   └── E        depth  : A→B→C→E  (deep chain)
+//     │   └── D            breadth: B has two children {C, D}
+//     └── S                sideways sibling subtree — MUST survive
+//         └── G
+//
+//   close(B) ⇒ exclusive subtree {B,C,D,E} reaped; 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
+// 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')
+// — same act, different terminal status: A5's open question. We assert the close
+// side and report the confirmed fact; we do NOT change it.
+//
+// FLAG vs the task brief: the brief expected "subscription+parent edges removed"
+// on close. CURRENT behavior + the ORACLE (§4: "Nothing is deleted: pi sessions +
+// edges persist → revivable") + the CLI help ("their pi sessions and canvas edges
+// persist for a later revive") all say edges PERSIST. This test asserts the
+// CURRENT (persist) behavior and the report flags the contradiction; production
+// is NOT changed.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { createHarness, hasTmux } from './helpers/harness.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 () => {
+    const h = await createHarness({ sessionPrefix: 'crtr-cascade' });
+    try {
+        // ===================================================================
+        // BUILD — the real tree. A is the in-process resident root (no pane);
+        // B,C,D,E,S,G are real managed children, each a real fake-pi in a real
+        // backstage pane (spawnChild awaits each boot). Every `node new` seeds the
+        // spine edge parent→child (active) + the spawned_by/parent provenance.
+        // ===================================================================
+        const A = h.spawnRoot('cascade-close root');
+        const B = await h.spawnChild(A, 'middle node — the close target', { kind: 'developer' });
+        const C = await h.spawnChild(B, 'B child one');
+        const E = await h.spawnChild(C, 'deep leaf under C'); // depth: A→B→C→E
+        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 sideways = [S, G]; // a sibling subtree — must be wholly untouched
+        // 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.equal(h.paneAlive(id), true, `${id} has a live pane before close`);
+            }
+            assert.equal(h.status(A), 'active', 'A (root) active 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');
+            assert.deepEqual(subIds(B), [C, D].sort(), 'B subscribes_to C and D');
+            assert.deepEqual(subIds(C), [E], 'C subscribes_to E');
+            assert.deepEqual(subIds(S), [G], 'S subscribes_to G');
+            // provenance edges (spawned_by / parent)
+            for (const [child, parent] of [[B, A], [C, B], [E, C], [D, B], [S, A], [G, S]]) {
+                assert.equal(h.node(child).parent, parent, `${child}.parent = ${parent}`);
+            }
+        }
+        // Make A's inbox NON-EMPTY before the close so "ancestor inbox intact" is a
+        // non-vacuous assertion: B pushes a routine update up its spine → A (B's
+        // sole active subscriber). A is the in-process root with no live watcher,
+        // so the pointer simply accumulates and must survive the close untouched.
+        {
+            const res = h.cli(B, ['push', 'update', 'progress from B before close']);
+            assert.equal(res.code, 0, `B push update exit 0\n${res.stderr}`);
+        }
+        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`,
+        // 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}`);
+        // The CLI's own rendered report: cascade root B, exactly 4 closed, 0 spared.
+        assert.match(closeRes.stdout, new RegExp(`<closed id="${B}" count="4" spared="0"\\s*/>`), `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.
+        // ===================================================================
+        for (const id of subtree) {
+            const n = h.node(id);
+            assert.equal(n.status, 'canceled', `${id} terminal status === 'canceled' (cancel event)`);
+            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) —
+        // 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 2 — real panes destroyed for the ENTIRE subtree (invariant 12-ish:
+        // a torn-down node owns no pane). tearDownNode killed each real tmux pane.
+        // ===================================================================
+        for (const id of subtree) {
+            await h.waitForPaneGone(id);
+            assert.equal(h.paneAlive(id), false, `${id} real pane destroyed by close`);
+        }
+        // ===================================================================
+        // ASSERT 3 — EXCLUSIVE-SUBTREE OWNERSHIP: nothing ABOVE (A) and nothing
+        // SIDEWAYS (S, G) was reaped. close(B) reaped EXACTLY B's own subtree.
+        // ===================================================================
+        // Ancestor A — fully untouched: still the live resident root, inbox intact.
+        {
+            const a = h.node(A);
+            assert.equal(a.status, 'active', 'A (ancestor) still active — untouched by the cascade');
+            assert.equal(a.lifecycle, 'resident', 'A still resident');
+            assert.equal(a.intent ?? null, null, 'A intent untouched');
+            assert.deepEqual(h.inbox(A), aInboxBefore, "A's inbox is byte-for-byte intact across the close (cascade touches only closed nodes' inboxes)");
+        }
+        // Sideways subtree S→G — wholly alive: status active AND real panes alive.
+        for (const id of sideways) {
+            assert.equal(h.status(id), 'active', `${id} (sideways) still active — not reaped`);
+            assert.equal(h.paneAlive(id), true, `${id} (sideways) real pane still alive`);
+        }
+        // The strong "EXACTLY its own subtree" closure: every node in the graph is
+        // either in B's subtree (canceled) or untouched (active) — no over-reach.
+        {
+            const reaped = new Set(subtree);
+            for (const id of [A, B, C, D, E, S, G]) {
+                const want = reaped.has(id) ? 'canceled' : 'active';
+                assert.equal(h.status(id), want, `${id} status === '${want}' (no over-/under-reach)`);
+            }
+        }
+        // ===================================================================
+        // ASSERT 4 — EDGES PERSIST (CURRENT behavior + ORACLE §4). close is a pause,
+        // not a delete: a closed node keeps its spine + provenance edges so it can
+        // be revived. (FLAGGED in the report: the task brief expected "edges
+        // removed" — that contradicts current behavior; we assert persistence.)
+        // ===================================================================
+        {
+            const subIds = (n) => h.subscriptions(n).map((s) => s.node_id).sort();
+            // Ancestor's spine edge to the closed middle node survives.
+            assert.ok(h.subscriptions(A).some((s) => s.node_id === B && s.active), 'A→B subscription edge PERSISTS after close (revivable)');
+            // Intra-subtree spine edges survive too.
+            assert.deepEqual(subIds(B), [C, D].sort(), 'B→{C,D} edges persist');
+            assert.deepEqual(subIds(C), [E], 'C→E edge persists');
+            // Provenance (spawned_by / parent) survives.
+            for (const [child, parent] of [[B, A], [C, B], [E, C], [D, B]]) {
+                assert.equal(h.node(child).parent, parent, `${child}.parent = ${parent} persists`);
+            }
+            // Sideways edges obviously untouched.
+            assert.deepEqual(subIds(S), [G], 'S→G edge untouched');
+        }
+        // ===================================================================
+        // ASSERT 5 — each closed node got its cancellation notice (the resume
+        // breadcrumb), appended AFTER its watcher died (close.ts step 3). The root
+        // B reads "CLOSED by the user"; descendants read "CANCELED — an ancestor…".
+        // ===================================================================
+        {
+            const bNotice = h.inbox(B).at(-1);
+            assert.equal(bNotice.from, null, "B's cancel notice is a system message");
+            assert.match(bNotice.label, /CLOSED by the user/, 'B (cascade root) reads the CLOSED notice');
+            assert.equal(bNotice.data?.['cascade_root'], B, "B notice records the cascade root");
+            const eNotice = h.inbox(E).at(-1);
+            assert.match(eNotice.label, /CANCELED/, 'E (descendant) reads the CANCELED notice');
+            assert.equal(eNotice.data?.['cascade_root'], B, "E notice records B as the cascade root");
+        }
+    }
+    finally {
+        const session = h.session;
+        await h.dispose();
+        assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
+    }
+});

package/dist/core/__tests__/daemon-boot.test.js

@@ -7,6 +7,7 @@ import { createNode, getNode, subscribe } from '../canvas/canvas.js';
 import { closeDb } from '../canvas/db.js';
 import { readInboxSince } from '../feed/inbox.js';
 import { superviseTick } from '../../daemon/crtrd.js';
+import { markBusy, clearBusy } from '../runtime/busy.js';
 let home;
 function node(id, over = {}) {
     return {
@@ -77,9 +78,15 @@ test('a crash after boot is marked dead without a boot-failure push', async () =
         intent: null,
     }));
     spawnEdge('P2', 'C2');
+    // MID-GENERATION when the window vanished (busy marker present, agent_end
+    // never cleared it) → a genuine mid-run crash. Without the marker a booted,
+    // unsubscribed pane-gone node would FINALIZE to 'done' instead (it would read
+    // as a finished node dismissed) — see the gone-pane routing in crtrd.ts.
+    markBusy('C2');
     await superviseTick();
     assert.equal(getNode('C2').status, 'dead', 'crashed child is dead');
     assert.equal(readInboxSince('P2').length, 0, 'a real crash does not push a boot-failure pointer');
+    clearBusy('C2');
 });
 // A still-booting node whose window is alive must be left untouched — boot is
 // slow, and an alive window means pi may still be coming up.

package/dist/core/__tests__/daemon-liveness.test.js

@@ -4,9 +4,10 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { createNode, getNode } from '../canvas/canvas.js';
+import { createNode, getNode, subscribe } from '../canvas/canvas.js';
 import { closeDb } from '../canvas/db.js';
 import { appendInbox } from '../feed/inbox.js';
+import { markBusy, clearBusy } from '../runtime/busy.js';
 import { superviseTick, isPidAlive, livenessVerdict, } from '../../daemon/crtrd.js';
 let home;
 function node(id, over = {}) {
@@ -149,8 +150,9 @@ test('pane GONE while its old window is still alive → the gone-branch fires (c
         spawnSync('tmux', ['kill-pane', '-t', dead], { stdio: 'ignore' });
         // The window is alive, but the node is anchored on that dead pane. Under the
         // old window-keyed liveness this node would read healthy (window alive + live
-        // pid). Pane-keyed: the pane is gone → the crash branch fires. pi_session_id
-        // is set so it's a clean crash, not a boot-failure push.
+        // pid). Pane-keyed: the pane is gone → the gone-branch fires. The node is
+        // MID-GENERATION (busy marker present — agent_start touched it, agent_end
+        // never cleared it), so the gone-branch routes to crash → 'dead'.
         createNode(node('G', {
             pane: dead,
             tmux_session: session,
@@ -159,8 +161,61 @@ test('pane GONE while its old window is still alive → the gone-branch fires (c
             pi_session_id: 'booted',
             intent: null,
         }));
+        markBusy('G'); // pane killed inside a turn → genuine mid-run crash
         await superviseTick();
-        assert.equal(getNode('G').status, 'dead', 'a gone pane fires the gone-branch even with a live window + pid');
+        assert.equal(getNode('G').status, 'dead', 'a gone pane mid-generation fires the gone-branch → crash (dead)');
+        clearBusy('G');
+    });
+});
+// ---------------------------------------------------------------------------
+// Gone-pane routing: a pane-gone node in the crash branch is no longer an
+// unconditional 'dead'. It routes on what the node was DOING at pane-kill time:
+//   • mid-generation (busy marker PRESENT)               → crash  ('dead')
+//   • finished its turn, awaiting nothing live           → finalize ('done')
+//   • finished its turn, still awaiting a LIVE child     → crash  ('dead'), for now
+// (The mid-generation → dead leg is covered by node 'G' above.)
+// ---------------------------------------------------------------------------
+test('pane gone + booted + busy ABSENT + no live subscription → finalize (done): the pane was closed to dismiss a finished node', { skip: !hasTmux() }, async () => {
+    await withLivePane('fin1', async (session, window) => {
+        const sp = spawnSync('tmux', ['split-window', '-d', '-P', '-F', '#{pane_id}', '-t', `${session}:${window}`, 'sleep 600'], { encoding: 'utf8' });
+        const dead = (sp.stdout ?? '').trim();
+        spawnSync('tmux', ['kill-pane', '-t', dead], { stdio: 'ignore' });
+        // Booted (pi_session_id set), no busy marker (agent_end cleared it → the turn
+        // finished), and no subscription to any live node. Closing the pane was a
+        // dismissal of a node that already did its own work → finalize to 'done'.
+        createNode(node('FIN', {
+            pane: dead,
+            tmux_session: session,
+            window,
+            pi_pid: process.pid,
+            pi_session_id: 'booted',
+            intent: null,
+        }));
+        // no markBusy: the turn ended cleanly.
+        await superviseTick();
+        assert.equal(getNode('FIN').status, 'done', 'a finished, unsubscribed node whose pane was closed finalizes to done');
+    });
+});
+test('pane gone + booted + busy ABSENT but AWAITING a LIVE child → crash (dead), for now', { skip: !hasTmux() }, async () => {
+    await withLivePane('fin2', async (session, window) => {
+        const sp = spawnSync('tmux', ['split-window', '-d', '-P', '-F', '#{pane_id}', '-t', `${session}:${window}`, 'sleep 600'], { encoding: 'utf8' });
+        const dead = (sp.stdout ?? '').trim();
+        spawnSync('tmux', ['kill-pane', '-t', dead], { stdio: 'ignore' });
+        // A live child the parent is subscribed to: hasActiveLiveSubscription === true.
+        createNode(node('CHILD', { status: 'active', pi_session_id: 'booted' }));
+        createNode(node('PARENT', {
+            pane: dead,
+            tmux_session: session,
+            window,
+            pi_pid: process.pid,
+            pi_session_id: 'booted',
+            intent: null,
+        }));
+        subscribe('PARENT', 'CHILD', true); // active subscription to a LIVE node
+        // Parent finished its turn (no busy marker) but is still awaiting a live
+        // child → NOT a finalize. Routes to crash ('dead') for now.
+        await superviseTick();
+        assert.equal(getNode('PARENT').status, 'dead', 'a finished node still awaiting a live child crashes (dead), not finalizes');
     });
 });
 // ---------------------------------------------------------------------------

package/dist/core/__tests__/dead-pane-regression.test.js

@@ -0,0 +1,151 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/dead-pane-regression.test.ts
+//
+// PLACEMENT-FAMILY DEAD-PANE REGRESSION GUARD.
+//
+// The bug (fixed this session, committed in HEAD `src/core/spawn.ts`): the
+// `human` command tree opens its humanloop TUI in a tmux pane via
+// `spawnAndDetach` (a `split-window` into the CURRENT window). The canvas
+// runtime arms `remain-on-exit on` at the WINDOW scope on a node's vehicle /
+// focus window (the F3 freeze, `runtime/tmux.ts` setRemainOnExit). A
+// `split-window` pane opened into such a window INHERITS the `on`, so when the
+// TUI worker (`crtr human _run`) exits 0 (clean), tmux keeps the pane around as
+// a dead "[Exited]" pane instead of destroying it — a lingering dead pane.
+//
+// The fix: after the split, `spawnAndDetach` forces `remain-on-exit off` at PANE
+// scope on the new pane (`set-option -p -t <pane> remain-on-exit off`). That
+// destroys the pane on a clean exit WITHOUT touching the window's value (so a
+// focus freeze still works) or the user's global config.
+//
+// This file drives the REAL production `spawnAndDetach` against a REAL but
+// isolated tmux session — no mocks. It is ADDITIVE: it adds no harness/fixture
+// capability and edits no production file. The canvas harness
+// (`helpers/harness.ts`) cannot reach this path — it drives canvas nodes via
+// `openNodeWindow` (new-window backstage), never the `spawnAndDetach`
+// split-window/human-pane path — so the tmux drivers below are LOCAL to this
+// file (candidates for harness consolidation: a `splitDetachPane` + pane-scoped
+// `paneAlive`/`paneIsDead`/`waitForPaneGone` keyed on a raw %pane id).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { hasTmux } from './helpers/harness.js';
+import { spawnAndDetach } from '../spawn.js';
+const SKIP = !hasTmux();
+// --- LOCAL tmux drivers (keyed on a raw %pane id, not a canvas node) --------
+function tmux(args) {
+    const r = spawnSync('tmux', args, { encoding: 'utf8' });
+    return { code: r.status ?? -1, out: (r.stdout ?? '').trim(), err: (r.stderr ?? '').trim() };
+}
+/** Every pane in the session (across windows) with its dead flag. */
+function sessionPanes(session) {
+    const r = tmux(['list-panes', '-s', '-t', session, '-F', '#{pane_id} #{pane_dead}']);
+    if (r.code !== 0)
+        return [];
+    return r.out
+        .split('\n')
+        .filter((l) => l.trim() !== '')
+        .map((l) => {
+        const [id, dead] = l.split(' ');
+        return { id: id, dead: dead === '1' };
+    });
+}
+function paneAlive(session, pane) {
+    return sessionPanes(session).some((p) => p.id === pane && !p.dead);
+}
+function paneExists(session, pane) {
+    return sessionPanes(session).some((p) => p.id === pane);
+}
+function paneIsDead(session, pane) {
+    return sessionPanes(session).find((p) => p.id === pane)?.dead ?? false;
+}
+async function waitUntil(probe, label, timeoutMs = 15_000, intervalMs = 100) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (probe())
+            return;
+        if (Date.now() > deadline)
+            throw new Error(`waitUntil timed out: ${label}`);
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+}
+test('dead-pane regression: spawnAndDetach into a remain-on-exit-ON window is DESTROYED on clean exit', { skip: SKIP ? 'tmux unavailable' : false, timeout: 60_000 }, async () => {
+    const session = `crtr-deadpane-${process.pid}-${Date.now().toString(36)}`;
+    const origTmux = process.env['TMUX'];
+    let tmuxOverridden = false;
+    try {
+        // --- isolated session on whatever server the current env targets -------
+        const created = tmux(['new-session', '-d', '-s', session, '-c', process.cwd(), 'sleep 100000']);
+        assert.equal(created.code, 0, `create isolated session failed: ${created.err}`);
+        const info = tmux([
+            'display-message', '-p', '-t', `${session}:`,
+            '#{pane_id}\t#{window_id}\t#{socket_path}',
+        ]);
+        assert.equal(info.code, 0, `display-message failed: ${info.err}`);
+        const [basePane, baseWindow, socketPath] = info.out.split('\t');
+        assert.ok(basePane && baseWindow && socketPath, `parsed session info: ${info.out}`);
+        // --- arm the BUG PRECONDITION: window default remain-on-exit ON --------
+        // (mirrors the canvas runtime's F3 freeze on a node's vehicle/focus window).
+        const armed = tmux(['set-window-option', '-t', baseWindow, 'remain-on-exit', 'on']);
+        assert.equal(armed.code, 0, `arm window remain-on-exit on failed: ${armed.err}`);
+        assert.equal(tmux(['show-window-options', '-t', baseWindow, 'remain-on-exit']).out, 'remain-on-exit on', 'precondition: the window into which we split has remain-on-exit ON');
+        // spawnAndDetach gates on isInTmux() (Boolean(process.env.TMUX)) and shells
+        // `tmux` with no -L, so point TMUX at THIS session's socket — both our
+        // helpers and spawnAndDetach then drive the same server holding `session`.
+        process.env['TMUX'] = `${socketPath},0,0`;
+        tmuxOverridden = true;
+        // ====================================================================
+        // MAIN — the REAL production spawnAndDetach split into the ON window.
+        // ====================================================================
+        const res = spawnAndDetach({
+            command: 'sleep 1', // a clean-exiting (status 0) worker — stands in for `crtr human _run`
+            cwd: process.cwd(),
+            placement: 'split-h',
+            killAfterSeconds: 0, // no self-kill of the originating pane
+            targetPane: basePane, // pin the split to our isolated window (never the user's pane)
+        });
+        assert.equal(res.status, 'spawned', `spawnAndDetach should spawn: ${res.message}`);
+        const pane = res.paneId;
+        assert.ok(pane && pane.startsWith('%'), `spawnAndDetach returned a %pane id: ${pane}`);
+        // (a) the pane landed alive in the remain-on-exit-ON window.
+        assert.equal(paneAlive(session, pane), true, 'spawned pane is alive right after the split');
+        // (b) THE FIX: the spawned pane carries a PANE-SCOPED remain-on-exit OFF
+        //     override — the exact line under regression
+        //     (`set-option -p -t <pane> remain-on-exit off`). If a refactor drops
+        //     it, this fails loudly.
+        assert.equal(tmux(['show-options', '-p', '-t', pane, 'remain-on-exit']).out, 'remain-on-exit off', 'FIX present: pane-scoped remain-on-exit OFF on the spawnAndDetach pane');
+        // (c) the override is pane-scoped only — the WINDOW value is untouched, so
+        //     a real focus-freeze on this window still works.
+        assert.equal(tmux(['show-window-options', '-t', baseWindow, 'remain-on-exit']).out, 'remain-on-exit on', 'window remain-on-exit untouched (override is pane-scoped, focus freeze intact)');
+        // (d) THE GUARANTEE: on the worker's CLEAN exit the pane is DESTROYED,
+        //     never lingering as a dead [Exited] pane.
+        await waitUntil(() => !paneExists(session, pane), 'spawnAndDetach pane destroyed on clean exit');
+        assert.equal(paneExists(session, pane), false, 'spawnAndDetach pane DESTROYED on clean exit (not lingering)');
+        // ====================================================================
+        // CONTROL — prove the guard is NON-VACUOUS: the SAME split WITHOUT the
+        // pane-scoped override (i.e. pre-fix behavior) lingers as a dead pane.
+        // ====================================================================
+        const ctl = tmux([
+            'split-window', '-h', '-d', '-P', '-F', '#{pane_id}',
+            '-t', basePane, '-c', process.cwd(), 'sleep 1',
+        ]);
+        assert.equal(ctl.code, 0, `control split failed: ${ctl.err}`);
+        const ctlPane = ctl.out;
+        assert.ok(ctlPane.startsWith('%'), `control pane id: ${ctlPane}`);
+        // No pane-scoped override → inherits the window's remain-on-exit ON →
+        // after its clean exit the pane is kept as DEAD rather than destroyed.
+        await waitUntil(() => paneIsDead(session, ctlPane), 'control pane reaches dead state after clean exit');
+        assert.equal(paneExists(session, ctlPane), true, 'CONTROL: un-fixed pane LINGERS (still listed) after clean exit');
+        assert.equal(paneIsDead(session, ctlPane), true, 'CONTROL: the lingering pane is DEAD — confirms remain-on-exit ON causes the exact bug the fix prevents');
+    }
+    finally {
+        // Tear down on the SAME server the session lives on (TMUX still points there),
+        // then restore the original TMUX env.
+        tmux(['kill-session', '-t', session]);
+        if (tmuxOverridden) {
+            if (origTmux === undefined)
+                delete process.env['TMUX'];
+            else
+                process.env['TMUX'] = origTmux;
+        }
+        assert.equal(spawnSync('tmux', ['has-session', '-t', session], { stdio: 'ignore' }).status === 0, false, 'isolated session killed — no stray');
+    }
+});

package/dist/core/__tests__/fixtures/fake-pi-host.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};