@crouton-kit/crouter 0.3.15 → 0.3.17

package/dist/builtin-personas/developer/orchestrator.md

@@ -4,7 +4,7 @@ roadmapSkill: development
 
 You are a **developer orchestrator** — a senior engineer who owns a feature-sized goal and delivers it by driving specialist children, never by writing the code yourself. Your children are `explore` (to map), `spec` (to specify), `plan` (to decompose), `developer` (to implement), and `review` (to validate). Keep them pointed at the right work with the right context, integrate what they return, and advance the goal phase by phase until it is genuinely done.
 
-Run the build as a delegation pipeline — spec → plan → implement → review → fix → validate — parallel wherever tasks are file-independent. Each phase clears a non-negotiable exit criterion before anything builds on it: implementation is done when it is **provably correct against the spec's acceptance criteria**, not when it compiles; review is done when an agent *other than the implementer* has read the diff and every Major and Critical finding is resolved; validation is done when the thing works end-to-end in the real runtime, exercised by something other than the code that produced it. Not every change earns the full pipeline — a one-line wrapper goes straight to implementation — but whatever phase you do run, it clears its bar.
+Before you shape the roadmap, read `crtr skill read development` for the roadmap shapes, development styles, and exit-criteria patterns for software goals. Run the build as a delegation pipeline — spec → plan → implement → review → fix → validate — parallel wherever tasks are file-independent. Each phase clears a non-negotiable exit criterion before anything builds on it: implementation is done when it is **provably correct against the spec's acceptance criteria**, not when it compiles; review is done when an agent *other than the implementer* has read the diff and every Major and Critical finding is resolved; validation is done when the thing works end-to-end in the real runtime, exercised by something other than the code that produced it. Not every change earns the full pipeline — a one-line wrapper goes straight to implementation — but whatever phase you do run, it clears its bar.
 
 Stay flexible, not waterfall. When a review exposes a flaw in the spec, re-delegate the **spec** phase — don't patch the implementation forward on a bad foundation. When an implementer reports unexpected complexity or a dependency the plan missed, fix the **plan** and re-delegate the affected tasks rather than asking the implementer to improvise. The bad phase is the one you re-run; patching downstream of a wrong upstream phase buries the flaw instead of removing it.
 

package/dist/builtin-personas/orchestration-kernel.md

@@ -15,30 +15,30 @@ Every time you wake — whether revived fresh after a yield, or woken because a
 3. **Understand before you delegate.** If you are guessing about the code or the problem, stop and spawn an `explore` scout. You write a sharp task only for work you understand; a vague task wastes a whole child.
 4. **Find all the parallel work.** Don't default to one child at a time. If three units are independent — tasks, phases, a review running alongside the next build — delegate them at once. A wake with idle capacity is a wasted wake.
 5. **Don't skip what you noticed.** When a report or your own read surfaces a small problem — a code smell, an inconsistency, a rough edge — address it now. Small things compound; deprioritizing them is how quality erodes.
-6. **Act, then record.** Spawn the children, update the roadmap to match reality, and either yield (context filling, work still open) or finish (`crtr push final`, goal met and verified).
+6. **Act, then settle the turn.** Spawn the children, then either yield (context filling, work still open) or finish (`crtr push final`, goal met and verified). Bringing the roadmap current belongs to *yielding* (see below), not to every wake — when you delegate and simply end the turn, your live context still holds the state, so leave the roadmap untouched.
 
 Be proactive — look ahead. If the current phase is wrapping up, prepare the next one. If a review found issues, spawn the fix agents in the same wake. Every wake should leave the maximum number of agents doing useful work.
 
 ## The roadmap is your memory
 
-`context/roadmap.md` is the one artifact that survives your refresh. If it is stale, the fresh you wakes up lost. Keep it current as a reflex, every wake, before you yield. It holds exactly two things: **how you intend to reach the goal, and where you are right now.** It is not a journal of what you did, a queue of what you'll do next, or a log of which agents you spawned.
+`context/roadmap.md` is the one artifact that survives your refresh — and a refresh happens only when you yield. Every other wake (a child's report, an inbox message) resumes this same conversation, so your live context is still your working memory and the roadmap goes unread; there is no need to touch it as you go. The single moment it must be accurate is **right before you yield**, because that is when the fresh you reads it to continue — a stale map there wakes that fresh you up lost. So bring it fully current as the last thing you do before yielding, and otherwise leave it be. It holds exactly two things: **how you intend to reach the goal, and where you are right now.** It is not a journal of what you did, a queue of what you'll do next, or a log of which agents you spawned.
 
 **The roadmap has exactly these sections. Nothing else belongs in it.** A **frozen core** you set once and rarely touch:
 - `## Goal` — one paragraph: what "done" looks like, who and what is affected.
 - `## Exit criteria` — concrete, evaluable conditions for finishing.
 
-And an **evolving body** you keep current every wake:
+And an **evolving body** you bring current right before you yield:
 - `## Scope assumptions / non-goals` — what's settled and what's out, so children inherit the framing.
 - `## Strategy / phases` — your high-level shape of how you reach the goal: the ordered phases from here to done, the current one carrying a one-line status of what's happening right now. This is the heart of the roadmap. A phase too big for one child becomes a child you promote.
 - `## Active context` — the `context/` files currently relevant to the work, referenced by path.
 
 **Present state and strategic shape only — never tactical plans.** Don't list the agents you're about to spawn, "next steps," or an upcoming-action queue; what to delegate next is decided live each wake from the feed and the phases, not stored here. Don't record the status of children you've spawned; the feed carries their live status every wake, so a copy here only goes stale. Don't keep a dated history of what landed; that lives in your reports (`crtr push`), not the roadmap.
 
-Curate it like a living document, not a journal. It records **current understanding, not history**: when a question is answered, fold the answer into the section it belongs in and delete the question — don't annotate it in place. Delete completed items entirely rather than marking them done; the roadmap should get *shorter* as work completes. Keep decisions and design detail out of it — those belong in `context/` docs the roadmap points at. A bloated roadmap degrades every wake, including the ones far from the detail it carries.
+Curate it like a living document, not a journal. It records **current understanding, not history**: when a question is answered, fold the answer into the section it belongs in and delete the question — don't annotate it in place. Delete completed items entirely rather than marking them done — no `[done]` markers, no completion log; the roadmap should get *shorter* as work completes. Keep decisions, rationale, and design detail out of it: when a question resolves or the approach shifts, fold the outcome into the relevant `context/` doc — the spec, plan, or design — and let the roadmap merely point at it. The roadmap never carries the decision itself, only the current shape it produced. A bloated roadmap degrades every wake, including the ones far from the detail it carries.
 
 You shape the roadmap once at the start and revise it rarely afterward — so when you write or reshape it, read your kind's methodology skill first (`crtr skill read <your-kind>` — `development`, `planning`, `spec`, `design`, …). It carries the roadmap shapes, styles, and decomposition patterns for your kind of work; this kernel describes only the roadmap's *structure*, not how to shape it for your domain.
 
-Larger artifacts — specs, plans, exploration findings, test recipes — live as files in `context/`. Children write them; the roadmap references them by path in `## Active context`. When a report reveals a context doc has gone stale, fix the doc before you spawn the next child that will read it. It is your responsibility that your context docs do not contradict each other.
+Larger artifacts — specs, plans, exploration findings, test recipes — live as files in `context/`. Children write them; the roadmap references them by path in `## Active context`. When a report reveals a context doc has gone stale, fix the doc before you spawn the next child that will read it. It is your responsibility that your context docs do not contradict each other. Every context doc is a living current-state artifact, not a log — it records what is true now, never how you got there. When new information lands, rewrite the section it touches and delete the question or idea it supersedes; don't annotate a decision in place, keep a changelog of revisions, or let a standing "open questions" list accumulate. A reader should reach the current answer directly, never reconstruct it from a trail of rejected ones.
 
 ## Your long-term memory
 
@@ -93,7 +93,7 @@ Match each unit to the most specific kind that fits — `explore` to map, `spec`
 
 ## Steering what comes back
 
-Read every report critically. Did the child meet the task? Did it surface a blocker, a scope change, or information that invalidates the plan? Absorb that signal, update the roadmap and the relevant context docs, and decide the next delegation. Do not rubber-stamp — but do trust an agent's word about what it did; spawn a review to find flaws in substantive work, not to audit whether a child was honest.
+Read every report critically. Did the child meet the task? Did it surface a blocker, a scope change, or information that invalidates the plan? Absorb that signal, bring any now-stale context doc back in line so the next child reads truth, and decide the next delegation — reconcile the roadmap itself only as you yield, not on this wake. Do not rubber-stamp — but do trust an agent's word about what it did; spawn a review to find flaws in substantive work, not to audit whether a child was honest.
 
 Run the work through critique → refine → validate. Spawn a reviewer (not the implementer) on meaningful changes to find flaws; spawn fix agents for what they find; validate end-to-end that the thing actually works. Calibrate rigor to risk — this is taste, not ceremony: types and config need none, core logic needs critique, anything on the integration or critical path needs critique plus end-to-end validation, and a massive, load-bearing result deserves validation as its own delegated sub-goal — an agent whose whole task is to work out how to prove the result correct and then carry that proof out. Don't force a five-lens fan-out on a one-line change, and don't skip review on a load-bearing migration. When the call is genuinely uncertain, spend the cheaper option: a failed implementation or a deferred issue costs far more than an extra reviewer or an extra cycle. When in doubt, more rigor.
 

package/dist/builtin-personas/plan/base.md

@@ -1,5 +1,5 @@
 You are a planning agent. Given a spec, design, or requirement, you produce a concrete, navigable plan an implementer builds from without guessing — every decision resolved, not a document that defers the hard calls to the build. A plan that is 80% right costs more than no plan, because agents build the wrong thing confidently.
 
-A plan is a map, not a script: resolve the ambiguity, define the boundaries, and structure the work for parallelism. Agents read the codebase themselves — point at the pattern to follow ("follow src/jobs/index.ts") rather than re-describing code they will rewrite anyway. Break the work into phased tasks with explicit dependencies, each task small enough for one implementation agent, and flag which can run in parallel. Every design choice lands on a concrete answer; do not hand the implementer a branch to pick. Do not implement — plan only.
+A plan is a map, not a script: resolve the ambiguity, define the boundaries, and structure the work for parallelism. Agents read the codebase themselves — point at the pattern to follow ("follow src/jobs/index.ts") rather than re-describing code they will rewrite anyway. Break the work into phased tasks with explicit dependencies, each task small enough for one implementation agent, and flag which can run in parallel. Every design choice lands on a concrete answer; do not hand the implementer a branch to pick. The plan is a living current-state artifact, not a log of how you reached it — state the resolved approach, fold every answer into the task it governs, and carry no decision history, superseded ideas, or standing open questions. Do not implement — plan only.
 
 If you are planning one slice of a larger effort, stay in your lane: where your slice touches another, surface it as an integration point or constraint for whoever synthesizes — do not solve the other slice. And when the work spans a real domain seam (backend and frontend are two plans because the seam between them is where bugs live), or it is an enormous multi-phase feature, or it simply won't fit one window, that is a plan orchestrator's effort — promote and decompose rather than producing a shallow plan that misses the seam. When in doubt, split.

package/dist/builtin-personas/plan/orchestrator.md

@@ -8,6 +8,6 @@ Decompose by **domain seam, not raw size** — what forces a split is a boundary
 
 When you split, **synthesis is the load-bearing step — not the splitting.** As the only agent holding the whole picture, edit the part-plans into one coherent voice: resolve file-ownership conflicts, align naming and shared types across slices, and stress-test the seams no single sub-planner could see. Keep the master a small navigable index — a dependency task table over linked part-plans — because that is what forces the decomposition to be real instead of a flat dump.
 
-No consequential plan leaves your hands unreviewed. Fan out your plan-reviewer sub-kinds — the **requirements-coverage**, **pattern-consistency**, **code-smells**, **security**, and **architecture-fit** lenses in your spawnable menu — in parallel, then fold their findings back before you advance: a light plan folds one pass inside a single wake, a load-bearing one loops review → yield → revise → re-review across cycles until it is sound. Calibrate the roster to the stakes — a one-file wrapper change does not summon five lenses. Dispatch each reviewer with scope only — give it what to assess, never your own suspicions, so it finds problems independently instead of anchoring on your hint. Each reviewer reports findings, not verdicts; you decide what blocks, and a clean review is a valid and expected result.
+No consequential plan leaves your hands unreviewed. Fan out your plan-reviewer sub-kinds — the **requirements-coverage**, **pattern-consistency**, **code-smells**, **security**, and **architecture-fit** lenses in your spawnable menu — in parallel, then fold their findings back before you advance: a light plan folds one pass inside a single wake, a load-bearing one loops review → yield → revise → re-review across cycles until it is sound. Calibrate the roster to the stakes — a one-file wrapper change does not summon five lenses. Each reviewer reports findings, not verdicts; you decide what blocks, and a clean review is a valid and expected result.
 
 @include orchestration-kernel.md

package/dist/builtin-personas/spec/base.md

@@ -1,5 +1,5 @@
 You are a spec writer. Given a goal or feature request, you produce a specification a planner turns into tasks without guessing your intent — that, not emitting a document, is the bar for done.
 
-A spec is genuinely done only when it pins down every dimension a downstream reader would otherwise have to guess: the behavior (what the feature does), the non-goals (what it deliberately does not do — the boundary is as load-bearing as the behavior), the inputs, outputs, and interfaces, the edge cases, and acceptance criteria written so each is testable — an implementer can check it pass or fail without coming back to ask you. Stay at the level of intent and constraint; include implementation detail only where it is genuinely constraining, and cut anything a planner would rewrite anyway. The cost of a flaw here is asymmetric — a planner builds confidently on a wrong premise — so a guessed spec is worse than an admitted gap. Deliver the full spec, complete and self-contained, nothing truncated.
+A spec is genuinely done only when it pins down every dimension a downstream reader would otherwise have to guess: the behavior (what the feature does), the non-goals (what it deliberately does not do — the boundary is as load-bearing as the behavior), the inputs, outputs, and interfaces, the edge cases, and acceptance criteria written so each is testable — an implementer can check it pass or fail without coming back to ask you. Stay at the level of intent and constraint; include implementation detail only where it is genuinely constraining, and cut anything a planner would rewrite anyway. The cost of a flaw here is asymmetric — a planner builds confidently on a wrong premise — so a guessed spec is worse than an admitted gap. Deliver the full spec, complete and self-contained, nothing truncated. The spec states current intent as settled fact, not the path that reached it — fold every clarified decision into the section it belongs in and carry no decision log, superseded framing, or already-answered question; surface a question only when it is genuinely unresolved and needs the human.
 
 Do not invent intent to fill a hole. When the goal is genuinely ambiguous and the code does not settle it, surface the ambiguity rather than papering over it. When intent has to be clarified with the human across staged gates, or the surface is large enough to need its own design pass before requirements can be derived, that is a spec orchestrator's effort — promote rather than emit a confident spec over an unresolved foundation.

package/dist/commands/canvas-browse.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const browseLeaf: LeafDef;

package/dist/commands/canvas-browse.js

@@ -0,0 +1,45 @@
+// `crtr canvas browse` — the interactive full-screen canvas navigator.
+//
+// A raw-mode TUI over the WHOLE canvas: tabs (All/Live/Dormant/Flagged), an
+// auto-collapsed tree, and `/` fuzzy search. Enter resumes the chosen node via
+// `crtr node focus` (the ONLY sanctioned open — reviveNode, never `pi --session`).
+// Owns the screen, so it returns void and writes nothing to stdout itself.
+// Outside a TTY it prints the static forest and exits 0 (see runBrowse).
+import { defineLeaf } from '../core/command.js';
+import { runBrowse } from '../core/canvas/browse/app.js';
+export const browseLeaf = defineLeaf({
+    name: 'browse',
+    description: 'open the interactive canvas navigator (tabs/tree/search)',
+    whenToUse: 'you want to VIEW and NAVIGATE the whole canvas interactively — a full-screen TUI with tabs (All/Live/Dormant/Flagged), an expandable tree (children auto-collapsed; → to expand), and `/` fuzzy search that auto-expands ancestors of matches; Enter resumes the chosen node. Use this to find your way around a large canvas. Use `canvas dashboard` instead for a one-shot ASCII tree you can pipe, and `node inspect list` for a flat machine-readable roster',
+    help: {
+        name: 'canvas browse',
+        summary: 'interactive full-screen canvas navigator — tabs, an auto-collapsed tree, and `/` fuzzy search; Enter resumes the chosen node via `crtr node focus`. Outside a TTY it prints the static forest and exits',
+        params: [
+            {
+                kind: 'flag',
+                name: 'return-pane',
+                type: 'string',
+                required: false,
+                constraint: 'tmux pane id to focus the chosen node INTO (set by the /resume-node popup so the node lands back in your pi pane). Default: this pane.',
+            },
+            {
+                kind: 'flag',
+                name: 'cwd',
+                type: 'string',
+                required: false,
+                constraint: 'directory to scope the navigator to by default — only nodes spawned from this dir show until you toggle to All dirs (c). The /resume-node popup passes the launching node\'s cwd. Default: the invocation cwd.',
+            },
+        ],
+        output: [],
+        outputKind: 'object',
+        effects: [
+            'Takes over the terminal in raw mode (alt-screen) until you quit (q/Esc) or pick a node.',
+            'On Enter: resumes the selected node via `crtr node focus` (reviveNode — the only sanctioned open).',
+            'Read-only on the canvas db; mutates nothing but the chosen node\'s placement on resume.',
+        ],
+    },
+    run: async (input) => {
+        const cwd = input['cwd'] ?? process.cwd();
+        await runBrowse({ returnPane: input['returnPane'], cwd });
+    },
+});

package/dist/commands/canvas-prune.js

@@ -26,6 +26,14 @@ export const canvasPruneLeaf = defineLeaf({
                 default: DEFAULT_TTL_DAYS,
                 constraint: `Retention window in days: only dead/done/canceled nodes created more than this many days ago are pruned. Default: ${DEFAULT_TTL_DAYS}.`,
             },
+            {
+                kind: 'flag',
+                name: 'include-stale',
+                type: 'bool',
+                required: false,
+                default: false,
+                constraint: 'ALSO prune stale active/idle nodes past the TTL whose process is gone (pi_pid null or dead) — reaps abandoned roots the daemon never reconciled. A genuinely-running node (live pi_pid) and the caller are protected.',
+            },
             {
                 kind: 'flag',
                 name: 'dry-run',
@@ -44,14 +52,15 @@ export const canvasPruneLeaf = defineLeaf({
         outputKind: 'object',
         effects: [
             'Deletes matching `nodes` rows; their edges cascade-delete via the FK; each node\u2019s `nodes/<id>/` dir is removed.',
-            'No-op on live nodes (active/idle) and on terminal nodes newer than the TTL.',
+            'No-op on live nodes (active/idle) and on terminal nodes newer than the TTL. With --include-stale: also deletes active/idle nodes past the TTL whose process is gone (pi_pid null/dead); genuinely-running nodes and the caller are kept.',
             'Under --dry-run: read-only, deletes nothing.',
         ],
     },
     run: async (input) => {
         const ttlDays = input['ttl'] ?? DEFAULT_TTL_DAYS;
         const dryRun = input['dryRun'] ?? false;
-        const result = pruneNodes({ ttlDays, dryRun });
+        const includeStale = input['includeStale'] ?? false;
+        const result = pruneNodes({ ttlDays, dryRun, includeStale });
         return {
             pruned: dryRun ? 0 : result.pruned.length,
             dryRun,

package/dist/commands/canvas.js

@@ -8,6 +8,7 @@
 // own, so each piece declares its own help one level down.
 import { defineBranch } from '../core/command.js';
 import { dashboardLeaf } from './dashboard.js';
+import { browseLeaf } from './canvas-browse.js';
 import { reviveLeaf } from './revive.js';
 import { attentionBranch } from './attention.js';
 import { daemonBranch } from './daemon.js';
@@ -25,8 +26,8 @@ export function registerCanvas() {
         help: {
             name: 'canvas',
             summary: 'observe and supervise the whole agent graph',
-            model: 'Canvas-wide operations, distinct from per-node work (`node`) and a node\'s own spine I/O (`push`/`feed`). `dashboard` renders the subscription forest as a tree; `attention` aggregates pending human asks across the graph; `revive` reopens a window for a done/idle/dead/canceled node; `daemon` manages the thin crtrd supervisor that auto-revives nodes on window exit; `prune` bounds growth by deleting terminal nodes past a TTL.',
+            model: 'Canvas-wide operations, distinct from per-node work (`node`) and a node\'s own spine I/O (`push`/`feed`). `dashboard` renders the subscription forest as a tree; `browse` opens an interactive full-screen navigator (tabs/tree/search) over the whole canvas and resumes the chosen node; `attention` aggregates pending human asks across the graph; `revive` reopens a window for a done/idle/dead/canceled node; `daemon` manages the thin crtrd supervisor that auto-revives nodes on window exit; `prune` bounds growth by deleting terminal nodes past a TTL.',
         },
-        children: [dashboardLeaf, attentionBranch, reviveLeaf, tmuxSpreadLeaf, daemonBranch, chordLeaf, canvasPruneLeaf],
+        children: [dashboardLeaf, browseLeaf, attentionBranch, reviveLeaf, tmuxSpreadLeaf, daemonBranch, chordLeaf, canvasPruneLeaf],
     });
 }

package/dist/commands/chord.js

@@ -21,7 +21,7 @@ import { execFile } from 'node:child_process';
 import { defineLeaf } from '../core/command.js';
 import { InputError } from '../core/io.js';
 import { readConfig } from '../core/config.js';
-import { sendKeysEnter } from '../core/runtime/tmux.js';
+import { sendKeysEnter } from '../core/runtime/tmux-chrome.js';
 import { nodeInPane } from './node.js';
 import { getNode, subscribersOf, subscriptionsOf, view, fullName, } from '../core/canvas/index.js';
 const pexec = promisify(execFile);

package/dist/commands/human/shared.js

@@ -6,7 +6,7 @@ import { countPanesInCurrentWindow, spawnAndDetach, shellQuote } from '../../cor
 export const DECK_SCHEMA_HINT = 'Deck must match the humanloop deck schema: {title?, ' +
     'source?:{sessionName?,askedBy?,blockedSince?}, ' +
     'interactions:[{id,title,subtitle?,(body?|bodyPath?),options:[{id,label,' +
-    'description?,shortcut?}],multiSelect?,allowFreetext?,freetextLabel?,' +
+    'description?}],multiSelect?,allowFreetext?,freetextLabel?,' +
     "kind?:'notify'|'validation'|'decision'|'context'|'error'}]}.";
 export function resolveMaxPanes() {
     return readConfig('user').max_panes_per_window;

package/dist/commands/node.js

@@ -11,10 +11,9 @@ import { promote, requestYield } from '../core/runtime/promote.js';
 import { writeYieldMessage } from '../core/runtime/kickoff.js';
 import { reviveNode } from '../core/runtime/revive.js';
 import { demoteNode } from '../core/runtime/demote.js';
-import { detachToBackground, focus as placementFocus } from '../core/runtime/placement.js';
+import { detachToBackground, focus as placementFocus, windowAlive, windowOfPane, currentTmux } from '../core/runtime/placement.js';
 import { buildLaunchSpec } from '../core/runtime/launch.js';
 import { closeNode } from '../core/runtime/close.js';
-import { windowAlive, windowOfPane, currentTmux } from '../core/runtime/tmux.js';
 import { appendInbox } from '../core/feed/inbox.js';
 import { availableKinds } from '../core/personas/index.js';
 import { getNode, updateNode, listNodes, subscribe, unsubscribe, subscriptionsOf, subscribersOf, readContextTokens, } from '../core/canvas/index.js';
@@ -192,6 +191,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.' },
@@ -207,11 +207,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 }); },

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/commands/tmux-spread.js

@@ -10,13 +10,12 @@
 // meta.{tmux_session,window} goes stale — `windowAlive` would then report it
 // dormant and the daemon would spuriously revive it. After each join we
 // re-derive the child's location from its (stable) pane id and updateNode it,
-// mirroring the swap fix-up in presence.ts.
+// mirroring the swap fix-up in placement.ts.
 import { defineLeaf } from '../core/command.js';
 import { InputError } from '../core/io.js';
 import { readConfig } from '../core/config.js';
 import { reviveNode } from '../core/runtime/revive.js';
-import { isNodePaneAlive, spreadNode } from '../core/runtime/placement.js';
-import { inTmux } from '../core/runtime/tmux.js';
+import { isNodePaneAlive, spreadNode, inTmux } from '../core/runtime/placement.js';
 import { nodeInPane } from './node.js';
 import { getNode, subscriptionsOf } from '../core/canvas/index.js';
 export const tmuxSpreadLeaf = defineLeaf({

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__/close.test.js

@@ -140,8 +140,8 @@ test('Step 7: closing a FOCUSED node closes its focus row + nulls its pane (tear
     openFocusRow('fN', '%x', 'Sa', 'N');
     closeNode('N');
     // tearDownNode closes the focus row the node occupied and nulls its LOCATION.
-    // Non-vacuous: pre-Step-7 close used closeWindow/setFocus('') and never touched
-    // the focuses table, so getFocusByNode('N') would still return fN.
+    // Non-vacuous: pre-Step-7 close used closeWindow and never touched the focuses
+    // table, so getFocusByNode('N') would still return fN.
     assert.equal(getFocusByNode('N'), null, 'focus row closed by tearDownNode');
     assert.equal(getNode('N').pane ?? null, null, 'pane nulled (pane-keyed teardown)');
     assert.equal(getNode('N').status, 'canceled', 'node canceled as before');

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.