@crouton-kit/crouter 0.3.31 → 0.3.33

package/dist/commands/node.js

@@ -13,12 +13,17 @@ import { reviveNode } from '../core/runtime/revive.js';
 import { newNodeId } from '../core/runtime/nodes.js';
 import { readRoadmap } from '../core/runtime/roadmap.js';
 import { parseWhen, parseCadence, cadenceDisplay } from '../core/wake.js';
+import { nodeSnapshotLeaf } from './node-snapshot.js';
+import { nodeContextLeaf } from './node-context.js';
 import { recycleNode } from '../core/runtime/recycle.js';
+import { readFaultAsync } from '../core/runtime/fault.js';
+import { activeFaultForDisplay } from '../core/canvas/render.js';
 import { detachToBackground, focus as placementFocus, windowAlive, windowOfPane, currentTmux, getPaneOption } from '../core/runtime/placement.js';
-import { buildLaunchSpec } from '../core/runtime/launch.js';
+import { buildLaunchSpec, normalizeModel } from '../core/runtime/launch.js';
 import { closeNode } from '../core/runtime/close.js';
+import { isBrokerLive, setModelLive, persistDormantModel } from '../core/runtime/model-swap.js';
 import { appendInbox } from '../core/feed/inbox.js';
-import { availableKinds, kindWhenToUse, subPersonasFor } from '../core/personas/index.js';
+import { availableKinds, kindWhenToUse } from '../core/personas/index.js';
 import { stateBlock } from '../core/help.js';
 import { getNode, updateNode, listNodes, subscribe, unsubscribe, subscriptionsOf, subscribersOf, readContextTokens, view, armWake, listWakes, cancelWake, WakeArmError, } from '../core/canvas/index.js';
 // Past this much context, an ORCHESTRATOR that spawns a managed child is better
@@ -56,11 +61,8 @@ function assertKind(kind) {
  *  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). */
+ *  Keep this block cheap and caller-agnostic: help should not depend on the
+ *  running node's current persona env, which can lag after polymorph. */
 function kindsStateBlock() {
     const kinds = availableKinds();
     const lines = kinds
@@ -69,33 +71,7 @@ function kindsStateBlock() {
         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 '';
-    }
+    return stateBlock('kinds', { count: kinds.length }, lines);
 }
 // ---------------------------------------------------------------------------
 // node new — spawn a terminal worker as a detached headless broker under the root
@@ -110,14 +86,14 @@ const nodeNew = defineLeaf({
         summary: 'spawn a terminal worker onto the canvas as a detached broker — returns its node id',
         params: [
             { kind: 'stdin', name: 'prompt', required: true, constraint: 'First user message for the spawned node. Deliver it on stdin from a quoted heredoc (`<<\'EOF\'`) or a file (`< prompt.md`).' },
-            { 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: '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. For an exact composed persona list, use `crtr sys prompt-review --list --kind <kind>`.' },
             { 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.' },
             { kind: 'flag', name: 'parent', type: 'string', required: false, constraint: 'Parent node id. Defaults to the calling node (CRTR_NODE_ID).' },
             { kind: 'flag', name: 'root', type: 'bool', required: false, constraint: 'Spawn an INDEPENDENT root instead of a managed child: no parent (top-level on the canvas), NO subscription back to you (you are NOT woken by it), resident lifecycle. It records spawned_by=you for provenance and is brought forefront so it can be driven directly. Use for a node you hand off and do not manage (e.g. a sub-orchestrator a human will discuss with).' },
             { kind: 'flag', name: 'fork-from', type: 'string', required: false, constraint: 'FORK the new node from an existing pi conversation instead of starting it fresh: pass a node id (forks from that node\'s session), an absolute session `.jsonl` path, or a partial pi session uuid. pi copies that whole history into a NEW session for the child (the source is untouched), then the prompt is delivered as the next message — i.e. the child wakes up as a continuation of that conversation. Use to branch exploratory work off a node that already built up the context you need, instead of re-deriving it. One-shot at birth: the fork resumes its own session thereafter.' },
-            { kind: 'flag', name: 'model', type: 'enum', choices: ['ultra', 'strong', 'medium', 'light'], required: false, constraint: 'Override the model the node runs on, by capability TIER: ultra (frontier), strong (opus), medium (sonnet), light (haiku). Omit to use the kind\'s persona default (explore=light, every other kind=strong). The override is durable — it survives revives and polymorphs (promote/demote).' },
+            { kind: 'flag', name: 'model', type: 'enum', choices: ['ultra', 'strong', 'medium', 'light'], required: false, constraint: 'Override the model the node runs on, by capability TIER: ultra (frontier), strong (opus), medium (sonnet), light (haiku). Omit to use the kind\'s persona default (advisor=ultra, explore=light, most other builtins=strong). The override is durable — it survives revives and polymorphs (promote/demote).' },
         ],
         output: [
             { name: 'node_id', type: 'string', required: true, constraint: 'The new node id.' },
@@ -148,7 +124,7 @@ const nodeNew = defineLeaf({
         const root = input['root'] === true;
         const forkFrom = input['forkFrom'];
         const model = input['model'];
-        const res = spawnChild({ kind, mode, cwd, name, prompt, parent, root, forkFrom, model });
+        const res = await spawnChild({ kind, mode, cwd, name, prompt, parent, root, forkFrom, model });
         return {
             node_id: res.node.node_id,
             name: res.node.name,
@@ -175,24 +151,67 @@ const nodeNew = defineLeaf({
 const nodeList = defineLeaf({
     name: 'list',
     description: 'list nodes on the canvas',
-    whenToUse: 'you want a flat roster of the nodes on the canvas, optionally sliced by status: a quick read of what exists and what is still running. Use `node inspect show` instead to drill into one node and its spine neighbors, `canvas dashboard` for the tree SHAPE, and `canvas attention` to find which nodes are blocked on a human',
+    whenToUse: 'you want a flat roster of the nodes on the canvas, sliced by any combination of attribute filters (status, kind, mode, lifecycle, cwd, hanging) and graph scope (--under a node, for that node plus its subscription descendants). The filters AND together, so "every human node in my subtree" is `--kind human --under <me>` and "every parked orchestrator" is `--mode orchestrator --hanging`. Use `node inspect show` instead to drill into one node and its spine neighbors, `canvas dashboard` for the tree SHAPE, and `canvas attention` to find which nodes are blocked on a human',
     help: {
         name: 'node inspect list',
-        summary: 'list nodes on the canvas, optionally by status',
+        summary: 'list nodes on the canvas, filtered by any combination of attribute slices and a graph-scope (--under) that AND together',
         params: [
             { kind: 'flag', name: 'status', type: 'string', required: false, constraint: 'Filter: active | idle | done | dead | canceled. Comma-separated for several. NOTE: `active` means the engine process is live (never closed), NOT that the node is generating right now — an active node is usually dormant between turns. To tell working-vs-idle, check the pi session-file mtime or CPU, not status.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Filter by persona kind (general, explore, developer, design, plan, review, spec, human, …). Comma-separated for several (OR within the flag).' },
+            { kind: 'flag', name: 'mode', type: 'string', required: false, constraint: 'Filter by mode: base | orchestrator. Comma-separated for several.' },
+            { kind: 'flag', name: 'lifecycle', type: 'string', required: false, constraint: 'Filter by lifecycle: terminal | resident. Comma-separated for several.' },
+            { kind: 'flag', name: 'cwd', type: 'string', required: false, constraint: 'Filter to nodes pinned to this exact cwd (absolute path). Roster is canvas-wide (all cwds) by default.' },
+            { kind: 'flag', name: 'under', type: 'string', required: false, constraint: 'Graph scope: restrict to this node and its subscription descendants (the sub-DAG reachable downward — its reports, theirs, …). This is "one initiative / my subtree". Combine with attribute filters, e.g. `--kind human --under <me>`.' },
+            { kind: 'flag', name: 'hanging', type: 'bool', required: false, constraint: 'Only nodes PARKED on an active fault (live broker + marker when provider-owned). Use to find stuck/rate-limited nodes awaiting auto-revive.' },
         ],
         output: [
-            { name: 'nodes', type: 'object[]', required: true, constraint: 'Rows: {node_id, name, kind, mode, lifecycle, status, cwd, parent, created}.' },
+            { name: 'nodes', type: 'object[]', required: true, constraint: 'Rows: {node_id, name, kind, mode, lifecycle, status, cwd, parent, created, hanging}. `hanging` is null normally, or {kind, message, since} when the node is PARKED on an active fault (rate-limit/overloaded/connection/other); the canvas-graph views render it with ⚠ + a countdown or state cue.' },
         ],
         outputKind: 'object',
-        effects: ['Read-only: queries canvas.db.'],
+        effects: ['Read-only: queries canvas.db (+ an active-fault marker read).'],
     },
     run: async (input) => {
-        const raw = input['status'];
-        const status = raw !== undefined && raw !== '' ? raw.split(',').map((s) => s.trim()) : undefined;
-        const nodes = listNodes(status !== undefined ? { status } : undefined);
-        return { nodes };
+        const csv = (k) => {
+            const raw = input[k];
+            return raw !== undefined && raw !== '' ? raw.split(',').map((s) => s.trim()).filter((s) => s !== '') : undefined;
+        };
+        const status = csv('status');
+        const kinds = csv('kind');
+        const modes = csv('mode');
+        const lifecycles = csv('lifecycle');
+        const cwd = input['cwd'];
+        const under = input['under'];
+        const hangingOnly = input['hanging'] === true;
+        // Graph scope (--under): self + subscription descendants. Validate the anchor
+        // so a typo'd id is a structured error, not a silently-empty roster.
+        let scope;
+        if (under !== undefined && under !== '') {
+            if (getNode(under) === null) {
+                throw new InputError({ error: 'not_found', message: `no node: ${under}`, next: 'List nodes with `crtr node inspect list`, then pass a real id to --under.' });
+            }
+            scope = new Set([under, ...view(under)]);
+        }
+        const rows = listNodes(status !== undefined ? { status } : undefined).filter((row) => {
+            if (scope !== undefined && !scope.has(row.node_id))
+                return false;
+            if (kinds !== undefined && !kinds.includes(row.kind))
+                return false;
+            if (modes !== undefined && !modes.includes(row.mode))
+                return false;
+            if (lifecycles !== undefined && !lifecycles.includes(row.lifecycle))
+                return false;
+            if (cwd !== undefined && cwd !== '' && row.cwd !== cwd)
+                return false;
+            return true;
+        });
+        // Enrich each row with its active-fault state. Daemon-owned provider faults
+        // are suppressed when the broker pid is gone; manual/client faults stay
+        // visible until cleared.
+        const nodes = await Promise.all(rows.map(async (row) => {
+            const hanging = activeFaultForDisplay(row, await readFaultAsync(row.node_id));
+            return { ...row, hanging };
+        }));
+        return { nodes: nodes.filter((n) => !hangingOnly || n.hanging !== null) };
     },
 });
 // ---------------------------------------------------------------------------
@@ -282,10 +301,10 @@ const nodeFocus = defineLeaf({
         // (revive it if dormant), then open/move its one viewer pane beside the
         // caller (or split a fresh viewer with --new-pane). The reviver is injected
         // so placement need not import revive.ts.
-        const res = placementFocus(id, {
+        const res = await placementFocus(id, {
             pane: input['pane'],
             newPane: input['newPane'] === true,
-            revive: (nid) => { reviveNode(nid, { resume: true }); },
+            revive: (nid) => reviveNode(nid, { resume: true }),
         });
         return { focused: res.focused, session: res.session, revived: res.revived, in_place: res.inPlace };
     },
@@ -439,6 +458,74 @@ const nodeClose = defineLeaf({
     },
 });
 // ---------------------------------------------------------------------------
+// node model — headless live model/provider swap for a node (no viewer attach)
+// ---------------------------------------------------------------------------
+const nodeModel = defineLeaf({
+    name: 'model',
+    description: 'swap a node\'s model/provider headlessly (durable, survives revives)',
+    whenToUse: 'you want to change which model (and thus provider) a node runs on WITHOUT opening its viewer — flip a running node to a stronger/cheaper model or a different provider, or repin a dormant node\'s model before its next revive. The choice is durable: it survives revives and polymorphs. This is the headless twin of the in-viewer `/model` slash command; reach for `node promote --model` instead when you are also changing a node\'s role',
+    help: {
+        name: 'node model',
+        summary: 'swap a node\'s model headlessly — if its broker is live, drive the switch over view.sock (no viewer attached); if dormant, repin its durable recipe for the next revive. The choice persists across revives either way.',
+        params: [
+            { kind: 'positional', name: 'spec', required: true, constraint: 'Model query: an exact `provider/id` (e.g. `openai-codex/gpt-5.5`), a capability tier (`ultra|strong|medium|light`), a bare family alias (`opus|sonnet|haiku`), or a free-text substring matched against the live registry. A free-text substring only resolves against a LIVE broker; a dormant node needs a concrete `provider/id` (or a tier/alias).' },
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node to repoint. Defaults to the node occupying --pane (or your current pane).' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane id whose node to repoint. Defaults to $TMUX_PANE / your current pane.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The node whose model was swapped.' },
+            { name: 'model', type: 'string', required: true, constraint: 'The resolved model — a concrete `provider/id` for a live broker (registry-resolved) or the normalized recipe value for a dormant node.' },
+            { name: 'applied', type: 'string', required: true, constraint: '"live" (the running broker switched immediately and persisted it) or "next-revive" (the dormant node\'s recipe was repinned; takes effect when it next revives).' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'LIVE broker: connects to the node\'s view.sock, claims controller, and drives `set_model` on the running engine; the broker persists the choice (model_override + launch.model) itself.',
+            'DORMANT node: writes model_override + launch.model directly into the node\'s durable recipe — no engine runs until its next revive.',
+        ],
+    },
+    run: async (input) => {
+        const pane = input['pane'] ?? process.env['TMUX_PANE'];
+        let id = input['node'];
+        if (id === undefined || id === '')
+            id = nodeInPane(pane);
+        if (id === undefined || id === '') {
+            throw new InputError({ error: 'no_node', message: 'no node found in this pane to repoint', next: 'Pass --node <id>, or run from inside the agent\'s pane.' });
+        }
+        const meta = getNode(id);
+        if (meta === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${id}`, next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const spec = (input['spec'] ?? '').trim();
+        if (spec === '') {
+            throw new InputError({ error: 'empty_spec', message: 'a model spec is required', field: 'spec', next: 'Pass a `provider/id`, a tier (ultra|strong|medium|light), an alias (opus|sonnet|haiku), or a substring.' });
+        }
+        if (isBrokerLive(meta)) {
+            // Live: drive the running engine over its socket. The broker resolves the
+            // query against the live registry (substrings included) and persists.
+            let model;
+            try {
+                model = await setModelLive(id, spec);
+            }
+            catch (err) {
+                throw new InputError({ error: 'switch_failed', message: `live model switch failed: ${err instanceof Error ? err.message : String(err)}`, next: 'Check the spec resolves (`provider/id`, tier, alias, or a substring of a registered model).' });
+            }
+            return { node_id: id, model, applied: 'live' };
+        }
+        // Dormant: no live registry to search, so normalizeModel only maps
+        // tiers/aliases. A bare substring that isn't a tier/alias can't resolve to a
+        // concrete id offline — reject rather than write a meaningless override.
+        const normalized = normalizeModel(spec);
+        if (!normalized.includes('/')) {
+            throw new InputError({ error: 'unresolvable_dormant', message: `'${spec}' does not resolve to a concrete model for a dormant node`, field: 'spec', next: 'Pass an exact `provider/id` (e.g. openai-codex/gpt-5.5) or a tier/alias — the live registry search is only available while the node\'s broker is up.' });
+        }
+        persistDormantModel(id, normalized);
+        return { node_id: id, model: normalized, applied: 'next-revive' };
+    },
+    render: (r) => r['applied'] === 'live'
+        ? `Switched ${r['node_id']} to ${r['model']} (live — applied now and persisted).`
+        : `Repinned ${r['node_id']} to ${r['model']} (applies on next revive).`,
+});
+// ---------------------------------------------------------------------------
 // node cycle — DFS-walk the canvas one window at a time (Alt+] / Alt+[)
 // ---------------------------------------------------------------------------
 /** Every live node in DFS pre-order across the whole forest. The spawn tree is
@@ -513,9 +600,9 @@ const nodeCycle = defineLeaf({
             return { focused: false, from: fromId };
         // Placement brings the neighbor's viewer forefront beside the caller,
         // relaunching its broker engine first if it was dormant.
-        const res = placementFocus(targetId, {
+        const res = await placementFocus(targetId, {
             pane,
-            revive: (nid) => { reviveNode(nid, { resume: true }); },
+            revive: (nid) => reviveNode(nid, { resume: true }),
         });
         return { focused: res.focused, node_id: targetId, name: target.name, from: fromId };
     },
@@ -556,13 +643,15 @@ const nodeMsg = defineLeaf({
             throw new InputError({ error: 'empty_body', message: 'a message body is required', field: 'body', next: 'Pass the message after the node id or on stdin.' });
         const tier = (input['tier'] ?? 'normal');
         const from = process.env['CRTR_NODE_ID'] ?? 'human';
+        // A long body clips in the receiver's digest; appendInbox mints a short `id`
+        // for it so the receiver can read the full text back via `feed message <id>`.
         appendInbox(id, { from, tier, kind: 'message', label: body.split('\n')[0].slice(0, 120), data: { body } });
         // A direct message wakes any node: if the target has no live window
         // (done/dead/idle-released), revive it so its inbox-watcher delivers this.
         let woke = false;
         if (!windowAlive(target.tmux_session, target.window)) {
             try {
-                reviveNode(id, { resume: true });
+                void reviveNode(id, { resume: true });
                 woke = true;
             }
             catch { /* best-effort wake */ }
@@ -657,7 +746,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. 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: '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. For an exact composed persona list, use `crtr sys prompt-review --list --kind <kind>` with the target kind. 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: 'model', type: 'enum', choices: ['ultra', 'strong'], required: false, constraint: 'Change the model you run on, by capability tier: `ultra` (frontier — reserve for high-taste judgment or enormous work: speccing, planning something large, e2e-testing something hard to test) or `strong` (opus — regular dev work). Omit to keep your current model. An orchestrator steering work is never weaker than opus, so these are the only two choices; the change is durable across future revives.' },
             { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node to promote. Defaults to the caller (CRTR_NODE_ID).' },
@@ -1335,9 +1424,96 @@ const nodeWake = defineBranch({
     },
     children: [nodeWakeAt, nodeWakeUntil, nodeWakeSpawn, nodeWakeList, nodeWakeCancel],
 });
+// ── /pyramid slash command ───────────────────────────────────────────────────
+// Rides on the `node` subtree, not because pyramid is a `node` verb, but because
+// (1) the workflow IS node orchestration — it fans out explore agents — and
+// (2) provisionExports lazy-loads only the invoked subtree (build-root.ts), so a
+// slash spec only gets (re)written to the host's command dirs when its host
+// subtree runs; `node` is the most-invoked subtree, so `/pyramid` provisions
+// reliably. The body is a self-contained agent workflow prompt (pi prompt
+// template / Claude Code command), exported one-way by host-exports.
+const pyramidSlash = {
+    name: 'pyramid',
+    description: 'Explain a topic as a live-building Minto pyramid diagram, backed by parallel explore agents.',
+    argumentHint: '<topic to explain>',
+    body: [
+        '# Pyramid explanation',
+        '',
+        'Explain **$ARGUMENTS** as a *pyramid*: lead with the answer, support it with a few key pillars, ground each pillar in evidence. You build this as a LIVE termrender diagram that fills in as parallel research lands — the user watches the skeleton grow into a complete picture.',
+        '',
+        '## The pyramid (Minto principle)',
+        '- **Apex** — ONE crisp sentence: the single governing answer/claim, the thing worth remembering.',
+        '- **Pillars** — 2–4 MECE supporting arguments that together prove the apex.',
+        '- **Base** — concrete evidence under each pillar (mechanisms, `file:line` refs, numbers, sources).',
+        '',
+        'Top-down: the reader gets the conclusion first, then descends for as much support as they want.',
+        '',
+        '## Workflow',
+        '',
+        '1. **Frame it.** Restate the topic in one line and commit to a *working* apex hypothesis (you will sharpen it). Name the 2–4 pillars you expect to need.',
+        '',
+        '2. **Scaffold the live diagram FIRST.** Write the termrender skeleton below to `./pyramid-<slug>.md` (apex = your hypothesis, pillars = titles, every base entry marked `[?]` pending). Then open it live so the user watches it build:',
+        '   ```bash',
+        '   termrender pane open ./pyramid-<slug>.md --watch   # detached tmux side-pane; re-renders on every save',
+        '   ```',
+        '   Not in tmux? Tell the user to run `termrender doc watch ./pyramid-<slug>.md` in another terminal, then continue regardless.',
+        '',
+        '3. **Investigate in parallel — do not block.** Fan out ONE explore agent per pillar/unknown AND dig into what you can answer yourself, concurrently:',
+        '   ```bash',
+        '   crtr node new "Investigate: <focused question for this pillar>. Report findings with sources / file:line refs." --kind explore',
+        '   ```',
+        '   You auto-subscribe; each finish wakes you. Never poll or wait — kick them all off, then start filling in what you already know.',
+        '',
+        '4. **Live-update as findings land.** Every time you learn something — your own digging or an explore report — EDIT the diagram file: flip a `[?]` to `[x]` (or `[!]` for a caveat/risk), add evidence under the right pillar, sharpen or rewrite the apex, drop a pillar that did not hold. Each save re-renders the pane. The diagram visibly grows skeleton → complete.',
+        '',
+        '5. **Land it.** When the apex is one crisp sentence, the pillars are MECE, and the base is concrete, do a final pass for accuracy, then give the user a 3–4 sentence spoken summary that mirrors apex → pillars. Tell them the diagram file path.',
+        '',
+        '## termrender skeleton (write this verbatim, then keep editing it)',
+        '',
+        'Apex panel on top, a divider, then the pillars as a row of boxes below — a literal pyramid: 1 claim over N supports.',
+        '```markdown',
+        ':::panel{title="<TOPIC>" color="cyan"}',
+        '**<one-line apex answer — your governing claim>**',
+        ':::',
+        '',
+        ':::divider{label="why"}',
+        ':::',
+        '',
+        '::::::columns',
+        ':::::col{width="33%"}',
+        '::::panel{title="Pillar 1 — <claim>" color="green"}',
+        ':::tree',
+        'evidence A [x]',
+        'evidence B [?]',
+        ':::',
+        '::::',
+        ':::::',
+        ':::::col{width="33%"}',
+        '::::panel{title="Pillar 2 — <claim>" color="green"}',
+        ':::tree',
+        'evidence C [?]',
+        ':::',
+        '::::',
+        ':::::',
+        ':::::col{width="34%"}',
+        '::::panel{title="Pillar 3 — <claim>" color="green"}',
+        ':::tree',
+        'evidence D [?]',
+        ':::',
+        '::::',
+        ':::::',
+        '::::::',
+        '```',
+        '',
+        '**Nesting rule (termrender will reject the file otherwise): an OUTER directive needs strictly MORE colons than the directive nested inside it.** Hence `::::::columns` (6) wraps `:::::col` (5) wraps `::::panel` (4) wraps `:::tree` (3). Every block closes with a bare run of its OWN colon count on its own line. Run `termrender doc check ./pyramid-<slug>.md` after each edit — if it errors, fix the colon counts before re-saving.',
+        '',
+        'Markers inside a tree: `[x]` → ✔ confirmed, `[!]` → ⚠ caveat/risk; `[?]` is not a marker and stays literal — use it for still-pending. Write structure only — termrender draws every box, border, and guide line; never hand-draw ASCII. Keep the apex to one sentence; push all detail into the base.',
+    ].join('\n'),
+};
 export function registerNode() {
     return defineBranch({
         name: 'node',
+        slash: pyramidSlash,
         rootEntry: {
             concept: 'a unit of the agent runtime — an agent on the canvas with its own context dir and pi vehicle. Spawning nodes is how work gets done here, not an optimization you reach for late',
             desc: 'spawn, inspect, and navigate nodes on the canvas',
@@ -1351,6 +1527,6 @@ export function registerNode() {
                 'HOW: `crtr node new "<task>" --kind <kind>` returns a node id immediately and runs the worker as a detached headless broker (no window opens; open a viewer on demand with `crtr node focus`). Match the kind to the work (see `node new -h`). You are woken when a child finishes — the wake message ALREADY IS the coalesced digest (the watcher drains your inbox to wake you), so don\'t re-run `crtr feed read` to "open" it (it would read empty, the cursor already advanced); instead dereference the report paths in that digest that matter, don\'t act on a one-line label. (`crtr feed read` is for proactively polling before a wake, or inspecting a child\'s inbox via `--node`; `--all` re-reads history with full message bodies.) Integrate, then either delegate the next units or finish.\n\n' +
                 'FINISH: a worker ends its own work with `crtr push final "<result>"` (writes the canonical result, marks done, closes the window) — stopping without it is not finishing. For a job too big for one context window, `node promote` to an orchestrator (holds a roadmap, delegates phases); when context fills, `node yield` to refresh against that roadmap.',
         },
-        children: [nodeNew, nodeInspect, nodeFocus, nodeCycle, nodeRecycle, nodeClose, nodeMsg, nodeSubscribe, nodeUnsubscribe, nodePromote, nodeDemote, nodeLifecycle, nodeYield, nodeWake],
+        children: [nodeNew, nodeInspect, nodeSnapshotLeaf, nodeContextLeaf, nodeFocus, nodeCycle, nodeRecycle, nodeClose, nodeMsg, nodeModel, nodeSubscribe, nodeUnsubscribe, nodePromote, nodeDemote, nodeLifecycle, nodeYield, nodeWake],
     });
 }

package/dist/commands/pkg/plugin-inspect.js

@@ -94,7 +94,7 @@ const pluginShow = defineLeaf({
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the plugin directory.' },
             { name: 'enabled', type: 'boolean', required: true, constraint: 'Whether the plugin is active.' },
             { name: 'manifest', type: 'object', required: true, constraint: 'Full plugin.json contents.' },
-            { name: 'skills', type: 'object[]', required: true, constraint: 'Each: {name, path}. Substrate docs provided by the plugin (its `<pluginName>/` memory subtree).' },
+            { name: 'docs', type: 'object[]', required: true, constraint: 'Each: {name, path}. Memory docs provided by the plugin (its `<pluginName>/` memory subtree).' },
         ],
         outputKind: 'object',
         effects: ['None. Read-only.'],
@@ -119,16 +119,16 @@ const pluginShow = defineLeaf({
             throw notFound(`plugin not found: ${name}`);
         }
         const prefix = `${found.name}/`;
-        const skills = listAllMemoryDocs().filter((d) => d.name.startsWith(prefix));
+        const docs = listAllMemoryDocs().filter((d) => d.name.startsWith(prefix));
         return {
             name: found.name,
             scope: found.scope,
             path: found.root,
             enabled: found.enabled,
             manifest: found.manifest,
-            skills: skills.map((s) => ({
-                name: s.name,
-                path: s.path,
+            docs: docs.map((d) => ({
+                name: d.name,
+                path: d.path,
             })),
         };
     },
@@ -136,7 +136,7 @@ const pluginShow = defineLeaf({
 export const pluginInspectBranch = defineBranch({
     name: 'inspect',
     description: 'list or show installed plugins',
-    whenToUse: 'reading installed plugin metadata to decide before you change anything — list what is installed, or show the manifest and skills of one plugin. Read-only; switch to `pkg plugin manage` to actually install, enable, disable, or remove',
+    whenToUse: 'reading installed plugin metadata to decide before you change anything — list what is installed, or show the manifest and memory docs of one plugin. Read-only; switch to `pkg plugin manage` to actually install, enable, disable, or remove',
     help: {
         name: 'pkg plugin inspect',
         summary: 'read plugin metadata without modifying state',

package/dist/commands/pkg/plugin-manage.js

@@ -146,7 +146,7 @@ const pluginRemove = defineLeaf({
 const pluginEnable = defineLeaf({
     name: 'enable',
     description: 'enable a plugin',
-    whenToUse: 'reactivating a plugin that was previously disabled so its skills resolve again',
+    whenToUse: 'reactivating a plugin that was previously disabled so its memory docs resolve again',
     help: {
         name: 'pkg plugin manage enable',
         summary: 'enable a plugin in the given scope',

package/dist/commands/pkg/plugin.js

@@ -7,8 +7,8 @@ export const pluginBranch = defineBranch({
     whenToUse: 'working with individual plugins directly — installing one from a git URL, inspecting or showing what a plugin provides, or enabling, disabling, removing, and updating an installed plugin. Use `pkg market` instead when you want a curated collection: browsing a marketplace index and installing plugins by name from it rather than handling raw git URLs yourself',
     help: {
         name: 'pkg plugin',
-        summary: 'install and manage plugins that extend crtr with skills',
-        model: 'Plugins are git repos or local directories containing a .crouter-plugin/plugin.json manifest and a skills/ directory.',
+        summary: 'install and manage plugins that extend crtr with memory docs',
+        model: 'Plugins are git repos or local directories containing a .crouter-plugin/plugin.json manifest and a memory/ directory.',
     },
     children: [pluginManageBranch, pluginInspectBranch],
 });

package/dist/commands/pkg.js

@@ -8,9 +8,9 @@ export function registerPkg() {
     return defineBranch({
         name: 'pkg',
         rootEntry: {
-            concept: 'plugins and marketplaces that supply skills',
+            concept: 'plugins and marketplaces that supply memory docs',
             desc: 'manage plugins and marketplaces',
-            useWhen: 'installing or browsing skill collections',
+            useWhen: 'installing or browsing memory-doc collections',
         },
         help: {
             name: 'pkg',

package/dist/commands/push.d.ts

@@ -1,3 +1,5 @@
 import type { BranchDef } from '../core/command.js';
+import { InputError } from '../core/io.js';
+export declare function mapFinalizeTransitionRaceError(nodeStatus: string | null | undefined, err: unknown): InputError | null;
 export declare function registerPush(): BranchDef;
 export declare function registerFeed(): BranchDef;