@crouton-kit/crouter 0.3.14 → 0.3.15

package/dist/builtin-skills/skills/crouter-development/personas/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: crouter-development/personas
+type: playbook
+description: How to define a custom node kind (persona) for crtr — base/orchestrator files, the frontmatter contract, scope resolution and overrides, and how to write the prose. Use when adding a new `--kind`, overriding a builtin agent, or debugging persona resolution.
+keywords: [persona, node kind, --kind, orchestrator, base, system prompt]
+---
+
+# Authoring crtr personas (custom node kinds)
+
+A **persona** is what `--kind` resolves to: the markdown that becomes a node's system prompt plus the launch knobs (model/tools/extensions/lifecycle). Defining one adds a new spawnable agent type to the canvas.
+
+Audience: LLM agents creating or overriding a crtr node kind.
+
+## When to add a kind (vs reuse a builtin)
+
+Builtins cover the common shapes: `explore spec design plan developer review general`.
+
+- **Reuse a builtin** when the work fits one. Don't fork `developer` to tweak one sentence.
+- **Add a kind** for a recurring specialist with its own deliverable + reporting contract that no builtin matches — e.g. `researcher`, `migration`, `release`.
+- **Override a builtin** by creating a same-named dir at user/project scope — it *shadows* the builtin (precedence below), it doesn't edit the shipped file.
+
+Never edit `src/builtin-personas/` for a local need — that ships to everyone. Override at scope instead.
+
+## Layout
+
+```
+<root>/personas/
+├── <kind>/
+│   ├── base.md               # worker persona (mode=base)
+│   └── orchestrator.md       # orchestrator persona (mode=orchestrator) — optional
+├── orchestration-kernel.md   # shared; @include-d by orchestrator files
+└── runtime-base.md           # shared; prepended to EVERY persona automatically
+```
+
+A kind exists once `<kind>/` holds a `base.md` **or** `orchestrator.md`. `crtr node new --kind <x>` validates against the discovered set and errors with the valid list — your fast existence check.
+
+## Scope + precedence
+
+Resolution is **project > user > builtin**, resolved per file:
+
+| Scope | Path |
+|---|---|
+| project | `<project>/.crouter/personas/<kind>/` — checked into the repo |
+| user | `~/.crouter/personas/<kind>/` — personal, all your projects |
+| builtin | ships with the CLI |
+
+Personas are **scope-root content, not plugin content** — they don't ship via plugins or marketplaces (the loader only searches `<scope>/personas/`). To share a kind, commit it to a repo's `.crouter/personas/` (project) or copy it into `~/.crouter/personas/` (user).
+
+## The two files
+
+**`base.md`** — the worker. Second person. State scope → method → deliverable, and end by reporting via `crtr push final`. Default lifecycle `terminal` (finishes in one window). → how to write one: `[[crouter-development/personas/base-prompt]]`.
+
+**`orchestrator.md`** — the owner that delegates to children and never does the work itself. Name the child kinds it drives and set per-phase exit criteria. **Must end with `@include orchestration-kernel.md`** — the loader inlines it; without it the orchestrator boots with no fan-out protocol. Default lifecycle `resident`. → how to write one: `[[crouter-development/personas/orchestrator-prompt]]`.
+
+If a kind has only `base.md`, `--mode orchestrator` composes `base.md body + kernel` and forces `resident` — so write `orchestrator.md` only when the worker and owner prose genuinely differ.
+
+## Frontmatter contract
+
+YAML frontmatter on either file supplies launch knobs; the body is the system prompt.
+
+| Field | Type | Effect |
+|---|---|---|
+| `lifecycle` | `terminal`\|`resident` | terminal = finishes + reaps; resident = interactive/long-lived. Defaults: base→terminal, orchestrator→resident. |
+| `model` | string | pi model override (normalized). Omit to inherit the default. |
+| `tools` | string[] | pi tool allowlist. Omit for all tools. |
+| `extensions` | string[] | pi extensions, **added after** the always-on canvas extensions. |
+| `skills` | string[] | skills attached at launch. |
+| `roadmapSkill` | string | orchestrator only — a skill whose body is injected as roadmap-shaping guidance when the node runs as an orchestrator. |
+
+`resolve()` never throws: a missing/empty persona falls back to `"You are a <kind> agent…"` defaults, so a node always boots. `runtime-base.md` (the push/finish/delegate/feed/ask protocol) is prepended to every persona — **don't restate it in the body.**
+
+## @include
+
+`@include <filename>` inlines another persona-root file, resolved through the same project>user>builtin chain. Used for `orchestration-kernel.md`; drop an `orchestration-kernel.md` at user/project scope to change orchestrator protocol fleet-wide.
+
+## Dev loop
+
+```bash
+mkdir -p ~/.crouter/personas/researcher
+$EDITOR ~/.crouter/personas/researcher/base.md         # frontmatter + prose
+crtr node new --kind researcher "map the auth flow"    # spawn; a bad --kind prints the valid kinds
+```
+
+No scaffold command — create the dir + files by hand. Copy a builtin (`explore/base.md`, `developer/orchestrator.md`) as a starting template.
+
+## Failure modes
+
+- **Orchestrator with no `@include orchestration-kernel.md`** — boots without the fan-out protocol; can't delegate. Always include it.
+- **Restating runtime-base** — the push/finish/delegate protocol is already prepended. Duplicating it wastes context and drifts out of sync.
+- **`lifecycle: resident` on a worker `base.md`** — the node never finishes. Reserve `resident` for interactive/long-lived kinds.
+- **Editing `src/builtin-personas/` for a local need** — ships to everyone. Override at user/project scope.
+- **Kind not listed after creating the dir** — neither `base.md` nor `orchestrator.md` is present, or the filename is wrong. The dir alone doesn't register a kind.
+
+## Related
+
+`[[crouter-development/plugins]]` packages *skills* for distribution — personas are distributed differently (committed to a scope's `personas/`), so a kind is never part of a plugin.

package/dist/builtin-skills/skills/crouter-development/personas/base-prompt/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: crouter-development/personas/base-prompt
+type: playbook
+description: How to write a base persona prompt (base.md) — the system prompt for a single-window worker node. Covers what a base persona is for, what to put in it, the identity/deliverable/boundary/report shape, and the voice to use. Use when writing or revising a <kind>/base.md.
+keywords: [base persona, base.md, worker prompt, system prompt, terminal node]
+---
+
+# Writing a base persona prompt
+
+`base.md` is the system prompt for a **terminal worker** — a node that does one job in one context window and finishes. Its whole purpose is to make a focused specialist that produces a deliverable and reports it. This skill is the philosophy of what belongs in a base persona; for file mechanics and frontmatter, see `[[crouter-development/personas]]`.
+
+Audience: LLM agents writing a `<kind>/base.md`.
+
+## What a base persona is for
+
+A base worker **does the work itself and ends.** It is not a manager. The persona points a fresh, capable model at one kind of task and makes it produce the right artifact without supervision. Everything in the body serves that: who it is, what good output looks like, what's out of bounds, and how it hands the result back.
+
+A base persona is a **system prompt**, not a task. Write the durable role — the identity and standards that hold for *every* task of this kind — and let the spawn-time prompt carry the specific task. Never bake one task's details into the persona.
+
+## The four things to put in it
+
+In order. Most base personas are 1–3 short paragraphs total.
+
+1. **Identity — one line, second person.** Open `"You are a <role> agent."` This is a system-prompt identity declaration; `"You are X"` is correct here (it would be wrong in a task prompt). Name the role sharply — "fast codebase exploration agent", "code review agent" — so the model knows which hat it wears.
+
+2. **The deliverable and its shape.** State *what good output is*, not a step-by-step procedure. Name the artifact and its structure: design names its sections, review names its severity tiers, explore demands `file:line` citations. You set the target the model steers toward — describe the target, not a checklist of moves to reach it. Fix the *what*; delegate the *how* to the model's judgment.
+
+3. **The boundaries that keep it in its lane.** One or two constraints that carve this kind out from its neighbors: explore is "read-only — do not modify"; design and plan "do not implement"; developer "throw errors early, no silent fallbacks". These earn their negative framing because the model has a real prior toward crossing the line — a design agent *will* start writing code if you don't fence it off. Keep them to genuine lane boundaries; don't pile on don'ts the model wouldn't trip over anyway.
+
+4. **The report.** Close by stating the deliverable is reported via `crtr push final` — the one runtime rule worth reinforcing in the body, because stopping without it is the most common worker failure. Everything else in the protocol (delegating, the feed, escalating) is already prepended by `runtime-base.md`; do not re-teach it.
+
+## Keep it shallow
+
+A base worker may spawn a helper or two for a targeted sub-task, but most of the work must be its own. If a kind's job routinely needs broad fan-out, it isn't a base worker — it's an orchestrator (`[[crouter-development/personas/orchestrator-prompt]]`). The base persona should make a do-er, not a delegator; say so explicitly when the kind is tempting to over-delegate (developer: "keep the delegation shallow").
+
+## Voice
+
+- **Second person + imperative.** "You are X." "Answer the question." "Do not modify files." Direct instruction for a direct worker.
+- **Positive framing for standards.** Describe the output you want, not a list of failures to avoid — "quote concrete `file:line` references" beats "don't be vague".
+- **Reserve hard rules.** CAPS / MUST only for the genuine non-negotiable — usually the finish rule and the lane boundary. If everything is critical, nothing is.
+- **Density.** This loads as the system prompt on *every* spawn of the kind. No preamble, no fluff — every line is the identity, the deliverable, a boundary, or the report.
+
+## Failure modes
+
+- **Procedure instead of target.** A numbered how-to ages badly and fights the model's judgment. State the deliverable's shape; let it choose the path.
+- **Restating runtime-base.** Re-teaching delegation/feed/escalation duplicates the prepended protocol and drifts out of sync. Reference only `push final`, as the deliverable.
+- **Task leakage.** Specifics of one task baked into the persona make every future spawn wear yesterday's job. Keep the body to the durable role.
+- **No report close.** A base persona that never names `crtr push final` produces workers that go quiet and get re-prompted. Always close on the deliverable.
+- **A manager in worker's clothing.** If the body spends more ink on delegation than on doing, you've written an orchestrator — split it.

package/dist/builtin-skills/skills/crouter-development/personas/orchestrator-prompt/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: crouter-development/personas/orchestrator-prompt
+type: playbook
+description: How to write an orchestrator persona prompt (orchestrator.md) — the system prompt for a resident coordinator node. Covers the kernel-vs-kind split, what belongs in the per-kind body, naming the child pipeline, the roadmapSkill pointer, and the @include rule. Use when writing or revising a <kind>/orchestrator.md.
+keywords: [orchestrator persona, orchestrator.md, orchestration-kernel, roadmapSkill, resident node]
+---
+
+# Writing an orchestrator persona prompt
+
+`orchestrator.md` is the system prompt for a **resident coordinator** — a long-lived node that owns a goal too large for one window and delivers it by decomposing, delegating, integrating, and surviving context refreshes. This skill is the philosophy of what belongs in an orchestrator persona; for file mechanics and frontmatter, see `[[crouter-development/personas]]`.
+
+Audience: LLM agents writing a `<kind>/orchestrator.md`.
+
+## The one rule that shapes everything: kernel vs kind
+
+Every orchestrator persona ends with `@include orchestration-kernel.md`. The kernel already teaches the **universal orchestrator protocol** — the wake loop, the roadmap structure and discipline, long-term memory, working in phases, delegating outcomes, steering what comes back, engaging the human, and the pre-finish checklist. It is long and complete.
+
+So your `orchestrator.md` body carries **only the delta** — what is specific to this kind. If a line you're about to write is true of orchestrators in general, the kernel already says it; cut it. Subtract before you add: the body is usually 1–3 short paragraphs *on top of* the kernel, not a re-derivation of how to orchestrate.
+
+## What the per-kind body puts in
+
+1. **Identity — the kind's ownership.** Open `"You are a **<kind> orchestrator** — …"` and say what this kind *owns*: a feature-sized goal (developer), a specification effort (spec), a review surface (review), a research question (explore). Bold the role. One sentence on what "owning it" means here.
+
+2. **The child kinds it drives, and the pipeline.** Name the specialists this orchestrator delegates to and the order it runs them: developer drives `explore → spec → plan → developer → review` as a "spec → plan → implement → review → fix → validate" pipeline; spec runs `SHAPE → DESIGN → REQUIREMENTS` stages; review fans `review` children across units. The flow is the kind's signature — make it explicit so delegation isn't ad hoc.
+
+3. **A pointer to the methodology skill — don't inline it.** Set `roadmapSkill: <skill>` in frontmatter and tell the body to read `crtr skill read <kind>` before shaping the roadmap. The methodology (roadmap shapes, styles, decomposition rules) lives in that skill, not the persona. The persona points; the skill teaches.
+
+4. **The kind's quality bar.** State the domain-specific exit criteria the kernel can't: developer's "implementation is done when provably correct against the spec, review done when a non-implementer cleared all Major/Critical findings, validation done end-to-end in the real runtime." This is where you set the ceiling for *this* kind of work.
+
+5. **What integration means here.** Every orchestrator's deliverable is the *synthesis*, never the child transcripts — but say what synthesis looks like for this kind: explore reconciles findings into one architecture answer; review deduplicates and severity-normalises into one verdict; design verifies every contract is honored on both sides. "Integrate, don't concatenate," made concrete.
+
+## The recurring sizing rule
+
+When a unit is itself too big for one window, the orchestrator creates that child **directly as `--mode orchestrator`**, not a base worker it counts on to self-promote. This appears in nearly every orchestrator persona because it's domain-flavored — *which* child kind gets promoted differs by orchestrator. State it for yours; a node born an orchestrator is strictly more capable than one hoping to become one.
+
+## Voice
+
+- **Second person identity, then operations.** "You are a **developer orchestrator**…" then "Run the build as a delegation pipeline…".
+- **Positive, concrete framing.** Name the pipeline and the exit criteria; don't enumerate things not to do. The one earned negative is the load-bearing boundary — "never by writing the code yourself" — which counters a real model prior to just do the work.
+- **Reserve hard rules** for genuine non-negotiables (the no-self-execution boundary, the no-self-promotion sizing rule). Density matters: this loads on every revive.
+- **End with the include.** `@include orchestration-kernel.md` on its own line, last. Without it the orchestrator boots with no protocol and cannot run the loop.
+
+## Failure modes
+
+- **Re-teaching the kernel.** Re-explaining the wake loop, roadmap sections, yielding, or memory duplicates the kernel and drifts. If it's universal, delete it.
+- **Missing `@include`.** No kernel = no loop, no roadmap discipline, no finish checklist. Always include it, last.
+- **Inlining the methodology.** Roadmap shapes belong in the `roadmapSkill`, not the persona. Point at it.
+- **No named pipeline.** An orchestrator that doesn't name its child kinds and their order produces scattershot delegation. The flow is the value.
+- **Forgetting the no-self-execution rule.** Without an explicit boundary, the model drifts into doing the work itself and exhausts its context with the goal half-met — the exact failure orchestrators exist to avoid.

package/dist/builtin-skills/skills/planning/SKILL.md

@@ -12,7 +12,7 @@ Every planning effort produces either a flat plan or a decomposed plan (index +
 
 **Use a flat plan** when the work is a single coherent domain, involves fewer than ~6 files, and can be written at consistent task granularity without exceeding roughly 150–200 lines. A flat plan has an overview, ordered phases, and a verification section. No sub-plans. One file.
 
-**Use a decomposed plan** when the change spans multiple domains (e.g., data layer, API surface, UI), involves 6+ files, or would require a master plan that cannot be written at consistent granularity without ballooning. In this case: produce an index plan (the navigable master) and delegate each domain slice to a `plan`-kind child node, giving each child its slice scope, the relevant portion of the spec, and its place in the dependency graph. The index plan is the synthesis artifact — it lists all sub-plans by path, defines phases and their dependencies, and contains a task table the implementation orchestrator can execute directly. Detail lives in sub-plans; the master is not allowed to carry it.
+**Use a decomposed plan** when the change spans multiple domains (e.g., data layer, API surface, UI), involves 6+ files, or would require a master plan that cannot be written at consistent granularity without ballooning. In this case: produce an index plan (the navigable master) and delegate each domain slice to a `plan`-kind child node, giving each child its slice scope, the relevant portion of the spec, and its place in the dependency graph. A slice that itself decomposes further — multiple sub-domains, more than one window's worth of planning — goes to a `plan` sub-orchestrator created directly (`crtr node new --kind plan --mode orchestrator`), not a base child relied on to promote itself. The index plan is the synthesis artifact — it lists all sub-plans by path, defines phases and their dependencies, and contains a task table the implementation orchestrator can execute directly. Detail lives in sub-plans; the master is not allowed to carry it.
 
 **The decomposition trigger is domain boundary, not size alone.** Three backend files and three frontend files are two domains even if the total count is modest — plan them separately and synthesize, because the integration seam is where bugs live and one agent reading both halves won't catch them as cleanly as two agents each going deep.
 

package/dist/builtin-skills/skills/spec/SKILL.md

@@ -20,7 +20,7 @@ Gate: human confirms readiness to proceed to design.
 
 Design produces the blueprint: components and their topology, end-to-end flows, files and directories affected, locked decisions, and open questions resolved. The altitude is infra/services — no function signatures, no algorithm descriptions, no implementation ordering. Design answers "what shape does this take?" — planning answers "how is it built?"
 
-Small or simple design work (one surface, clear scope, few components) can be done by a single `design`-kind child node. Large or complex design work — multi-surface features, multiple interacting subsystems, significant architectural choices — must be delegated to a **design orchestrator** (a resident `design`-kind node), which decomposes the design internally and returns a finished artifact. The trigger for spawning a design orchestrator rather than a base design node: if the design effort has more than one distinct phase or more than ~5 interacting components, use an orchestrator.
+Small or simple design work (one surface, clear scope, few components) can be done by a single `design`-kind child node. Large or complex design work — multi-surface features, multiple interacting subsystems, significant architectural choices — must be delegated to a **design orchestrator** (a `design`-kind node created directly with `--mode orchestrator`), which decomposes the design internally and returns a finished artifact. The trigger for spawning a design orchestrator rather than a base design node: if the design effort has more than one distinct phase or more than ~5 interacting components, use an orchestrator.
 
 Gate: human approves the rendered design artifact.
 
@@ -64,7 +64,7 @@ After yield-and-revive, `## Strategy / phases` plus `## Active context` must let
 
 Spawn a base `design` node (terminal) when: the design surface is bounded, one component or subsystem, no multi-phase structure required. The node produces `context/design.md` and `context/design.json` and returns.
 
-Spawn a `design` orchestrator (resident) when: the feature spans multiple subsystems, has distinct implementation phases that need separate design treatment, or the design effort is itself likely to fill one context window before it's finished. Pass it the shape brief as its goal; it owns the decomposition and integration internally and reports a finished design artifact when done.
+Spawn a `design` orchestrator (resident) when: the feature spans multiple subsystems, has distinct implementation phases that need separate design treatment, or the design effort is itself likely to fill one context window before it's finished. Create it directly as an orchestrator — `crtr node new --kind design --mode orchestrator` — rather than spawning a base design node and counting on it to promote itself once it discovers the surface is too big; self-promotion is unreliable, and a node born an orchestrator is strictly more capable than one hoping to become one. Pass it the shape brief as its goal; it owns the decomposition and integration internally and reports a finished design artifact when done.
 
 In either case, the spec orchestrator waits for the design to land and the human to approve it before proceeding.
 

package/dist/cli.js

@@ -1,36 +1,13 @@
 #!/usr/bin/env node
-import { defineRoot, runCli } from './core/command.js';
-import { registerSkill } from './commands/skill.js';
-import { registerPkg } from './commands/pkg.js';
-import { registerHuman } from './commands/human.js';
-import { registerSys } from './commands/sys.js';
-import { registerPush, registerFeed } from './commands/push.js';
-import { registerNode } from './commands/node.js';
-import { registerCanvas } from './commands/canvas.js';
+import { runCli } from './core/command.js';
+import { buildRoot } from './build-root.js';
 import { maybeBootRoot } from './core/runtime/front-door.js';
 import { maybeAutoUpdate } from './core/auto-update.js';
 import { ensureBootSkill, ensureOfficialMarketplace, ensureProjectScope, ensureSlashCommands } from './core/bootstrap.js';
-// Root owns only the tagline and globals. Every subtree's concept line,
-// selection rubric, and any dynamic block it contributes to root -h are
-// declared on the subtree itself (its rootEntry) and assembled here by
-// defineRoot. Add a subtree to this list and it appears at root; nothing about
-// it is restated here.
-const root = defineRoot({
-    tagline: 'crtr: agentic planning runtime.',
-    globals: [
-        { name: '-h', desc: 'print help for any node — append to any subcommand path' },
-    ],
-    subtrees: [
-        registerSkill(),
-        registerPkg(),
-        registerHuman(),
-        registerSys(),
-        registerNode(),
-        registerPush(),
-        registerFeed(),
-        registerCanvas(),
-    ],
-});
+// The full command tree is assembled in build-root.ts (shared with the
+// listing-completeness test). Root owns only the tagline; every subtree
+// declares its own representation.
+const root = buildRoot();
 // The front door: bare `crtr` (or `crtr [dir] ["prompt"]`) boots a resident
 // root node and execs pi in this terminal. Recognized subcommands fall through
 // to the normal dispatcher. Must run before anything that assumes a subcommand.

package/dist/commands/attention.js

@@ -13,13 +13,15 @@
 // Exported as a branch; `crtr canvas` (canvas.ts) mounts it.
 import { defineBranch, defineLeaf } from '../core/command.js';
 import { InputError } from '../core/io.js';
-import { getNode } from '../core/canvas/index.js';
-import { countAsks, pendingAsksForView, asksAcrossCanvas, } from '../core/canvas/attention.js';
+import { getNode, view } from '../core/canvas/index.js';
+import { countAsks, pendingAsksForView, asksAcrossCanvas, asksForNodes, } from '../core/canvas/attention.js';
 // ---------------------------------------------------------------------------
 // attention count
 // ---------------------------------------------------------------------------
 const attentionCount = defineLeaf({
     name: 'count',
+    description: 'total pending ask count (machine-parseable stdout.count)',
+    whenToUse: 'getting a single pending-ask count for a script or nav chrome to read (stdout.count is machine-parseable); scope with --node or --view, or default to canvas-wide',
     help: {
         name: 'canvas attention count',
         // stdout.count is parsed directly by the nav chrome — keep the contract.
@@ -90,6 +92,8 @@ const attentionCount = defineLeaf({
 // ---------------------------------------------------------------------------
 const attentionList = defineLeaf({
     name: 'list',
+    description: 'itemised list of cwds with pending asks',
+    whenToUse: 'finding which agents are blocked waiting on a human — an itemised list of the cwds with pending asks, oldest first, so you know where to go answer. Scope to a sub-DAG with --view or list canvas-wide. Use `canvas attention count` instead when a script just needs the number, or `canvas attention map` for per-node counts to label a UI',
     help: {
         name: 'canvas attention list',
         summary: 'list nodes with pending human asks, grouped by cwd, oldest first',
@@ -135,18 +139,83 @@ const attentionList = defineLeaf({
     },
 });
 // ---------------------------------------------------------------------------
+// attention map
+// ---------------------------------------------------------------------------
+const attentionMap = defineLeaf({
+    name: 'map',
+    description: 'per-node ask counts for a visible set, batched in one pass',
+    whenToUse: 'labelling every node in a UI with its pending-ask count in one batched pass — the form nav chrome polls (one process, one JSON blob) instead of N count shell-outs',
+    help: {
+        name: 'canvas attention map',
+        summary: 'per-node pending-ask counts for a visible set of nodes in ONE pass — the batched form the nav chrome polls (one process, one JSON blob) instead of N count shell-outs',
+        params: [
+            {
+                kind: 'flag',
+                name: 'view',
+                type: 'string',
+                required: false,
+                constraint: 'Include this node and its whole sub-DAG (root + reports recursively). Union with --nodes. At least one of --view/--nodes is required.',
+            },
+            {
+                kind: 'flag',
+                name: 'nodes',
+                type: 'string',
+                required: false,
+                constraint: 'Comma-separated explicit node ids to include (e.g. ancestry + peers). Union with --view.',
+            },
+        ],
+        output: [
+            {
+                name: 'counts',
+                type: 'object',
+                required: true,
+                constraint: 'Map of node_id → pending ask count. Every requested id is present (0 when none).',
+            },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: scans each distinct cwd\'s humanloop interaction dir once.'],
+    },
+    run: async (input) => {
+        const viewId = input['view'];
+        const nodesRaw = input['nodes'];
+        if (viewId === undefined && (nodesRaw === undefined || nodesRaw.trim() === '')) {
+            throw new InputError({
+                error: 'missing_scope',
+                message: 'at least one of --view <id> or --nodes <a,b,c> is required',
+                next: 'Pass --view <root> to cover a sub-DAG, --nodes <a,b,c> for an explicit set, or both.',
+            });
+        }
+        const ids = new Set();
+        if (viewId !== undefined) {
+            if (getNode(viewId) === null) {
+                throw new InputError({
+                    error: 'not_found',
+                    message: `no node: ${viewId}`,
+                    next: 'List nodes with `crtr node inspect list`.',
+                });
+            }
+            ids.add(viewId);
+            for (const id of view(viewId))
+                ids.add(id);
+        }
+        if (nodesRaw !== undefined) {
+            for (const id of nodesRaw.split(',').map((s) => s.trim()).filter((s) => s !== ''))
+                ids.add(id);
+        }
+        return { counts: asksForNodes([...ids]) };
+    },
+});
+// ---------------------------------------------------------------------------
 // Export — mounted under `crtr canvas`
 // ---------------------------------------------------------------------------
 export const attentionBranch = defineBranch({
     name: 'attention',
+    description: 'count/list pending human asks across the graph',
+    whenToUse: 'checking whether any agent on the canvas is blocked waiting on a human, and where: count the pending asks, list the cwds that have them, or map per-node counts. Scope with --node or --view, or go canvas-wide. Use `canvas dashboard` instead for the graph SHAPE, or `node inspect list` for a plain node roster',
     help: {
         name: 'canvas attention',
         summary: 'aggregate pending human asks across the canvas',
         model: 'Human asks are stored per-cwd by humanloop. `count` returns a single integer (stdout.count is parsed by nav chrome); `list` returns itemised entries. Scope with --node (one node) or --view (sub-DAG) — default is canvas-wide.',
-        children: [
-            { name: 'count', desc: 'total pending ask count (machine-parseable stdout.count)', useWhen: 'polling from a script or nav chrome' },
-            { name: 'list', desc: 'itemised list of cwds with pending asks', useWhen: 'finding which agents need a human response' },
-        ],
     },
-    children: [attentionCount, attentionList],
+    children: [attentionCount, attentionList, attentionMap],
 });

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

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

package/dist/commands/canvas-prune.js

@@ -0,0 +1,66 @@
+// `crtr canvas prune` — bounded retention for the node graph.
+//
+// The canvas never deleted a node before this: dead/done/canceled rows + their
+// `nodes/<id>/` dirs accumulated without limit. `prune` is the retention sweep —
+// remove TERMINAL nodes (dead | done | canceled) older than a TTL; the edges→nodes
+// FK (ON DELETE CASCADE) GCs their edges, and each node's dir is removed too.
+// Live nodes (active | idle, the daemon's domain) are never touched.
+//
+// Exported as a leaf; `crtr canvas` (canvas.ts) mounts it.
+import { defineLeaf } from '../core/command.js';
+import { pruneNodes } from '../core/canvas/index.js';
+const DEFAULT_TTL_DAYS = 14;
+export const canvasPruneLeaf = defineLeaf({
+    name: 'prune',
+    description: 'remove terminal nodes (dead/done/canceled) older than a TTL',
+    whenToUse: 'you want to bound the canvas\u2019s on-disk growth \u2014 sweep away nodes that are finished (done), crashed (dead), or closed (canceled) and older than a retention window, reclaiming their rows, edges (cascade-deleted by the schema), and `nodes/<id>/` dirs. Run it as an operator/cron chore; live nodes (active/idle) are never touched. Pass `--dry-run` first to see exactly what would go, `--ttl <days>` to widen or tighten the window',
+    help: {
+        name: 'canvas prune',
+        summary: 'delete terminal nodes older than a TTL (edges cascade, dirs removed); --dry-run to preview',
+        params: [
+            {
+                kind: 'flag',
+                name: 'ttl',
+                type: 'int',
+                required: false,
+                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: 'dry-run',
+                type: 'bool',
+                required: false,
+                default: false,
+                constraint: 'Report what WOULD be pruned without deleting anything.',
+            },
+        ],
+        output: [
+            { name: 'pruned', type: 'integer', required: true, constraint: 'How many nodes were pruned (0 under --dry-run since nothing is deleted; the candidate count is in `nodes`).' },
+            { name: 'dryRun', type: 'boolean', required: true, constraint: 'True when nothing was deleted (preview only).' },
+            { name: 'ttlDays', type: 'integer', required: true, constraint: 'The retention window used.' },
+            { name: 'nodes', type: 'object[]', required: true, constraint: 'One per pruned (or, under --dry-run, prunable) node: {node_id,status,created}.' },
+        ],
+        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.',
+            '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 });
+        return {
+            pruned: dryRun ? 0 : result.pruned.length,
+            dryRun,
+            ttlDays,
+            nodes: result.pruned.map((p) => ({
+                node_id: p.node_id,
+                status: p.status,
+                created: p.created,
+            })),
+        };
+    },
+});

package/dist/commands/canvas.js

@@ -11,6 +11,9 @@ import { dashboardLeaf } from './dashboard.js';
 import { reviveLeaf } from './revive.js';
 import { attentionBranch } from './attention.js';
 import { daemonBranch } from './daemon.js';
+import { tmuxSpreadLeaf } from './tmux-spread.js';
+import { chordLeaf } from './chord.js';
+import { canvasPruneLeaf } from './canvas-prune.js';
 export function registerCanvas() {
     return defineBranch({
         name: 'canvas',
@@ -22,14 +25,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 node; `daemon` manages the thin crtrd supervisor that auto-revives nodes on window exit.',
-            children: [
-                { name: 'dashboard', desc: 'render the canvas as a subscription tree', useWhen: 'inspecting the whole graph at a glance' },
-                { name: 'attention', desc: 'count/list pending human asks across the graph', useWhen: 'checking whether any agent is blocked on a human' },
-                { name: 'revive', desc: 'reopen a window for a done/idle/dead node', useWhen: 'manually waking a node (the daemon does this automatically)' },
-                { name: 'daemon', desc: 'manage the crtrd supervisor process', useWhen: 'starting, checking, or stopping background supervision' },
-            ],
+            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.',
         },
-        children: [dashboardLeaf, attentionBranch, reviveLeaf, daemonBranch],
+        children: [dashboardLeaf, attentionBranch, reviveLeaf, tmuxSpreadLeaf, daemonBranch, chordLeaf, canvasPruneLeaf],
     });
 }

package/dist/commands/chord.d.ts

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