@crouton-kit/crouter 0.3.18 → 0.3.20

package/dist/builtin-personas/review/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: Validate or critique code, a plan, or a spec — deliver a complete, severity-rated verdict without adjudicating.
+model: opus
 ---
 
 You are a review agent. Your job is to deliver a **verdict** on the code, plan, or spec you were given — a complete, accurate account of what is and isn't sound. Be critical and precise.

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

@@ -1,3 +1,7 @@
+---
+model: opus
+---
+
 You are a **review orchestrator** — you own a review surface too large for one agent to assess well, and you deliver one coherent verdict by fanning reviews across it in parallel.
 
 Decompose the surface two ways: by **unit** (files, modules, subsystems) and by **lens** (correctness, security, architecture-fit, tests, style). Delegate each child a sharp scope — exactly what to review and which lens to apply — and give it scope, not your suspicions, so it finds problems independently instead of anchoring on a hint. Then synthesise the child reports into one verdict: deduplicated, severity-normalised so a Major from one child outranks a Minor from another, most important first. You detect across the whole surface; you do not adjudicate — report what is there and let the owner decide what gates. The synthesis is your deliverable: integrate the findings into one voice, never forward raw child output, and where two children's findings conflict, reconcile them rather than pasting both.

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

@@ -10,7 +10,7 @@ Hand any self-contained unit of work to a child instead of doing it inline — t
 
 You auto-subscribe to every child you spawn, so you're woken when it finishes; read what they reported with `crtr feed read` and dereference the reports that matter. Prefer delegating over grinding it out yourself.
 
-## When blocked or you need the human
+## When blocked, want feedback, or need a human
 Don't stall and don't guess at a decision a person should make:
 
     crtr human ask "<question>"
@@ -18,6 +18,9 @@ Don't stall and don't guess at a decision a person should make:
 ## When your task is too big for one context window
 If you discover the job is far larger than one node can hold — many phases, or work that won't fit before you run low on context — **promote yourself** instead of grinding it out:
 
-    crtr node promote --kind <kind>
+    crtr node promote --kind <kind>     # `crtr node promote -h`: what an orchestrator is, --kind, roadmap, terminal vs resident
 
-This makes you an orchestrator: you author a roadmap (`context/roadmap.md`), delegate each phase to children, and when your context fills you `crtr node yield` to refresh against that roadmap. You stay **terminal** — promotion changes your role, not your lifecycle: you still owe a final result up the spine and reap when the goal is met. It does **not** make you resident; residency is a separate, opt-in choice (`crtr node promote --resident`, or `crtr node lifecycle resident`) reserved for work whose goal is to be continuously interactive with the user. `--kind` specializes the orchestrator you revive into (developer, review, spec, design, plan, explore, general); omit it to keep your current kind. Don't promote for work that fits one window — finish it.
+Don't promote for work that fits one window — finish it.
+
+## When you are blocked on a future event or time
+You are not stuck and you are not done — you are waiting. Don't busy-loop or finish: just stop and go dormant, and the runtime wakes you when the thing you wait on happens. See *Waiting* for the details — including the one case where you instead schedule the wake yourself.

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

@@ -1,5 +1,6 @@
 ---
 whenToUse: Write a specification — pin down behavior, non-goals, interfaces, edge cases, and testable acceptance criteria from a goal.
+model: opus
 ---
 
 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.

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

@@ -1,10 +1,11 @@
 ---
 roadmapSkill: spec
+model: opus
 ---
 
 You are a **spec orchestrator** — you own a specification effort and deliver a spec a planner turns into tasks with zero guessing. You reach that through three gated stages: **SHAPE** (clarify intent with the human until the goal is unambiguous), **DESIGN** (produce the blueprint), and **REQUIREMENTS** (derive precise, testable requirements from the finished design). This is one of the few kinds where human engagement is load-bearing — Shape is interactive, and the human gates each stage before the next begins. You drive and decide; the human answers questions and signs off the artifact each stage produces.
 
-Before you shape the roadmap or open any stage, read `crtr skill read spec` for the stage gates, the rule for delegating design to a base vs. orchestrator child, and what a finished spec contains. Delegate the design stage to a `design` child — a base node for a bounded surface, a design orchestrator when it spans multiple surfaces or phases.
+Before you shape the roadmap or open any stage, read `crtr memory read spec` for the stage gates, the rule for delegating design to a base vs. orchestrator child, and what a finished spec contains. Delegate the design stage to a `design` child — a base node for a bounded surface, a design orchestrator when it spans multiple surfaces or phases.
 
 Yield for a fresh window between stages, and derive requirements from the *rendered design text in isolation*, never from the design conversation that produced it — a requirements pass that inherits the design's working context reproduces its blind spots instead of testing them. The effort is done only when every stage has cleared its human gate and the requirements are testable enough that a planner needs nothing further from you.
 

package/dist/builtin-personas/waiting.md

@@ -0,0 +1,8 @@
+## Waiting is a way to end a turn
+
+Finishing is for a goal that is *met*. When your goal is sound but your next step is blocked on something that has not happened yet — a child's report, a human, a CI run, tomorrow morning — you are not finished, you are **waiting**. Waiting is free: you end your turn, hold no window, and burn no compute, and the runtime brings you back the instant the thing you wait on happens. A dormant node is waiting, not finished.
+
+- **Never finish to stop waiting.** `crtr push final` reaps you and cancels your pending one-shot wakes. Reaching for it because you have nothing to do *right now* throws the goal away and leaves a human to re-kick the work. If the goal is not met, wait — do not finish.
+- **Never busy-wait.** Do not hold your window open to re-poll a URL or watch a clock. A wait that costs a live window is a defect — just stop: end your turn and go dormant.
+- **For anything the runtime delivers — a child's report, a human's reply, a sibling's message — just stop.** Go dormant; the runtime wakes you the moment it lands. There is nothing to arm, poll, or verify, and a deadline set to "check in" on a delegate is a belt-and-suspenders the runtime makes unnecessary — your children auto-wake you when they push. A pending wait is reason enough to go dormant: you are released dormant, not re-prompted to finish.
+- **Schedule a wake yourself only when nothing can push to you** — recurring or scheduled standing work, or polling an external the spine can't deliver (CI, a deploy, a clock). With no event to wait for, a self-scheduled wake is the only way to wait at all: `crtr node wake -h`.

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

@@ -23,7 +23,7 @@ So your `orchestrator.md` body carries **only the delta** — what is specific t
 
 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.
+3. **A pointer to the methodology skill — don't inline it.** Set `roadmapSkill: <skill>` in frontmatter and tell the body to read `crtr memory 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.
 

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

@@ -104,7 +104,7 @@ ln -s $(pwd) ~/.crouter/plugins/my-plugin
 # Verify
 crtr pkg plugin inspect list                       # my-plugin appears
 crtr pkg plugin inspect show my-plugin             # lists its skills
-crtr skill find list --plugin my-plugin            # just my-plugin's skills
+crtr memory list --plugin my-plugin            # just my-plugin's skills
 crtr sys doctor                                    # validates manifest + every skill
 ```
 
@@ -124,7 +124,7 @@ Standard semver:
 
 ## Enable/disable
 
-`crtr pkg plugin manage disable <name>` flips the per-scope config without removing files. Disabled plugins are hidden from `crtr skill find list` and don't resolve via `crtr skill read <name>`. Re-enable with `crtr pkg plugin manage enable <name>`.
+`crtr pkg plugin manage disable <name>` flips the per-scope config without removing files. Disabled plugins are hidden from `crtr memory list` and don't resolve via `crtr memory read <name>`. Re-enable with `crtr pkg plugin manage enable <name>`.
 
 Individual skills inside an enabled plugin can also be disabled: `crtr skill state disable <plugin>/<skill>`.
 

package/dist/builtin-views/_lib/states.mjs

@@ -0,0 +1,161 @@
+// @ts-check
+/**
+ * Standard view states — the four states every crtr view must *design* rather
+ * than leave bare (design §4): loading-skeleton, empty-reward, error-keeps-its-
+ * shape, and the guided not-ready takeover.
+ *
+ * Copy-pasteable BODY HELPERS: this is a sibling lib the builtin views import
+ * RELATIVELY (`import { loadingState } from '../_lib/states.mjs'`). It imports
+ * NOTHING from crtr — the view passes in the `draw` + content `rect` the host
+ * already handed it, and these paint the state into `draw`.
+ *
+ * Discipline (design §2): all color is NUMERIC SGR codes ('32' green, '31' red,
+ * '36' cyan, '33' yellow); color NEVER carries meaning alone — every colored
+ * element pairs its hue with a glyph or weight so it survives NO_COLOR / dumb
+ * terminals. Hue is the framework's job to gate (draw.ts gates fg/bg on caps);
+ * structural weight (bold/dim) always renders.
+ *
+ * @module _lib/states
+ */
+
+/** @typedef {import('../../core/tui/draw.js').Draw} Draw */
+/** @typedef {import('../../core/tui/draw.js').Rect} Rect */
+/** @typedef {import('../../core/tui/draw.js').Span} Span */
+/** @typedef {import('../../core/tui/draw.js').Style} Style */
+
+// ── internal ──────────────────────────────────────────────────────────────────
+
+/** @param {Span[]} spans @returns {number} */
+function spanWidth(spans) {
+  let n = 0;
+  for (const s of spans) n += Array.from(s.text).length;
+  return n;
+}
+
+/** @param {string|string[]|undefined|null} v @returns {string[]} */
+function toLines(v) {
+  if (v == null) return [];
+  if (Array.isArray(v)) return v.map((s) => String(s == null ? '' : s));
+  return [String(v)];
+}
+
+/**
+ * Place a vertically + horizontally centered stack of span-lines in `rect`.
+ * Each entry is one line's spans; rows that fall outside the rect are skipped.
+ * @param {Draw} draw @param {Rect} rect @param {Span[][]} lines
+ */
+function centeredStack(draw, rect, lines) {
+  if (!rect || rect.width <= 0 || rect.height <= 0 || lines.length === 0) return;
+  const start = rect.row + Math.max(0, Math.floor((rect.height - lines.length) / 2));
+  lines.forEach((spans, i) => {
+    const row = start + i;
+    if (row < rect.row || row >= rect.row + rect.height) return;
+    const w = spanWidth(spans);
+    const col = rect.col + Math.max(0, Math.floor((rect.width - w) / 2));
+    draw.spans(row, col, spans, rect.col + rect.width - col);
+  });
+}
+
+// ── states ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Loading — paint a SKELETON of where content will land (dim `····` placeholder
+ * rows), not a lone centered "Loading…". The layout is legible before data
+ * arrives. Pair with the host's `⟳ working` chip + a `setStatus('Loading…')`.
+ *
+ * @param {Draw} draw
+ * @param {Rect} rect
+ * @param {{ rows?: number, label?: string }} [opts]
+ *   rows  — how many skeleton rows (default 4); label — optional dim caption below.
+ */
+export function loadingState(draw, rect, opts = {}) {
+  if (!rect || rect.width <= 0 || rect.height <= 0) return;
+  const n = Math.max(1, Math.min(opts.rows ?? 4, rect.height));
+  const snippetLens = [10, 8, 12, 7, 11];
+  for (let i = 0; i < n; i++) {
+    const row = rect.row + i;
+    const label = '·'.repeat(4);
+    const snipLen = Math.min(snippetLens[i % snippetLens.length], Math.max(0, rect.width - 8));
+    /** @type {Span[]} */
+    const spans = [{ text: label, style: { dim: true } }];
+    if (snipLen > 0) spans.push({ text: '  ' + '·'.repeat(snipLen), style: { dim: true } });
+    draw.spans(row, rect.col + 1, spans, rect.width - 1);
+  }
+  if (opts.label) {
+    const below = { row: rect.row + n + 1, col: rect.col, width: rect.width, height: Math.max(0, rect.height - n - 1) };
+    centeredStack(draw, below, [[{ text: opts.label, style: { dim: true } }]]);
+  }
+}
+
+/**
+ * Empty — the reward state. A small centered stack: a green `✓`, a default-weight
+ * headline, then dim secondary lines. Inbox-zero is a reward, not a void.
+ *
+ * @param {Draw} draw
+ * @param {Rect} rect
+ * @param {{ glyph?: string, headline?: string, secondary?: string|string[] }} [opts]
+ */
+export function emptyState(draw, rect, opts = {}) {
+  const glyph = opts.glyph ?? '✓';
+  const headline = opts.headline ?? 'All caught up';
+  /** @type {Span[][]} */
+  const lines = [
+    [{ text: glyph + '  ', style: { fg: '32' } }, { text: headline }], // green glyph + default headline
+    [{ text: '' }],
+  ];
+  for (const t of toLines(opts.secondary)) lines.push([{ text: t, style: { dim: true } }]);
+  centeredStack(draw, rect, lines);
+}
+
+/**
+ * Error — a centered error block, used ONLY when there is no last-known content
+ * to keep (on a refresh error with a still-good view, raise a banner instead).
+ * `✗` + headline in red/bold, the cause in default weight, a dim retry hint.
+ *
+ * @param {Draw} draw
+ * @param {Rect} rect
+ * @param {{ headline?: string, cause?: string|string[], hint?: string }} [opts]
+ */
+export function errorState(draw, rect, opts = {}) {
+  const headline = opts.headline ?? 'Something went wrong';
+  const cause = toLines(opts.cause);
+  const hint = opts.hint ?? 'Press g to retry.';
+  /** @type {Span[][]} */
+  const lines = [
+    [{ text: '✗  ', style: { fg: '31', bold: true } }, { text: headline, style: { fg: '31', bold: true } }],
+    [{ text: '' }],
+  ];
+  for (const t of cause) lines.push([{ text: t }]);
+  if (cause.length) lines.push([{ text: '' }]);
+  if (hint) lines.push([{ text: hint, style: { dim: true } }]);
+  centeredStack(draw, rect, lines);
+}
+
+/**
+ * Not-ready / guided takeover — the full-content recovery substrate (design §5).
+ * A centered stack: a state glyph (its hue passed by the caller, mono-safe via
+ * the glyph itself), a bold headline naming the state, a dim explanation, and the
+ * explicit next step (an auto-progress note the view writes, or a key to press).
+ *
+ * @param {Draw} draw
+ * @param {Rect} rect
+ * @param {{ glyph?: string, glyphFg?: string, headline?: string, explanation?: string|string[], nextStep?: string }} [opts]
+ *   glyphFg — NUMERIC SGR code for the glyph hue (e.g. '36' cyan working, '31' red blocked).
+ */
+export function notReadyState(draw, rect, opts = {}) {
+  const glyph = opts.glyph ?? '⊙';
+  /** @type {Style} */
+  const glyphStyle = opts.glyphFg ? { fg: opts.glyphFg, bold: true } : { bold: true };
+  const headline = opts.headline ?? 'Not ready';
+  /** @type {Span[][]} */
+  const lines = [
+    [{ text: glyph + '  ', style: glyphStyle }, { text: headline, style: { bold: true } }],
+    [{ text: '' }],
+  ];
+  for (const t of toLines(opts.explanation)) lines.push([{ text: t, style: { dim: true } }]);
+  if (opts.nextStep) {
+    lines.push([{ text: '' }]);
+    lines.push([{ text: opts.nextStep }]); // default weight — the call to action
+  }
+  centeredStack(draw, rect, lines);
+}

package/dist/builtin-views/canvas/client.mjs

@@ -0,0 +1,303 @@
+// @ts-check
+/**
+ * Canvas data layer for the crtr `canvas` view (the monitor archetype).
+ *
+ * Self-contained ESM, Node-builtins-only. Imports NOTHING from crtr so it ships
+ * verbatim (`cp -R src/builtin-views dist/builtin-views`) and is dynamically
+ * `import()`ed by the view at runtime where there is no TS toolchain.
+ *
+ * It shells the `crtr` binary itself — exactly as the LinkedIn view shells
+ * `capture`. Two read-only `--json` leaves give the whole graph:
+ *   - `crtr node inspect list --json`   → every node row, incl. `parent` (so the
+ *                                          view rebuilds the forest) + `lifecycle`.
+ *   - `crtr canvas attention list --json` → which nodes have pending human asks
+ *                                          (the "blocked on a human" signal).
+ * Both are read-only (query canvas.db) and exit 0. No `--json` affordance was
+ * missing — every command we need already emits machine-readable JSON.
+ *
+ * NOTHING here throws. Every exported function returns a `Result<T>`; failures
+ * surface as a typed `ClientError` so the view renders guidance, not a crash.
+ *
+ * NOTE on the crtr help-gate: that gate is a pi-side `bash` tool-call
+ * interceptor — it inspects the AGENT's command string. A `crtr` spawned from
+ * inside the view host (a grandchild of `node dist/cli.js view run`) is not a
+ * tool call pi can see, so these shell-outs are never gated.
+ *
+ * @module canvas/client
+ */
+
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+/**
+ * One canvas node, flattened from `node inspect list --json`.
+ * @typedef {Object} CanvasNode
+ * @property {string} nodeId      Full node id (`<time>-<hash>`).
+ * @property {string} name        Display name.
+ * @property {string} kind        Node kind (general/developer/explore/human/…).
+ * @property {string} mode        base | orchestrator.
+ * @property {string} lifecycle   resident | terminal.
+ * @property {string} status      active | idle | done | dead | canceled.
+ * @property {string|null} parent Spawn/subscription parent id (null ⇒ a forest root).
+ * @property {string} created     ISO 8601 birth timestamp (drives child ordering).
+ */
+
+/**
+ * One cwd with pending human asks, from `canvas attention list --json`. The
+ * `nodeId` is the cwd's representative node — the node the attention system
+ * points at.
+ * @typedef {Object} AttentionItem
+ * @property {string} nodeId
+ * @property {string} name
+ * @property {string} cwd
+ * @property {number} count    Pending ask count.
+ */
+
+/**
+ * Typed failure. `kind` drives the guidance banner the view shows.
+ * @typedef {{kind:'crtr-missing', message:string}
+ *   | {kind:'crtr-failed', message:string}
+ *   | {kind:'parse', message:string}
+ *   | {kind:'error', message:string}} ClientError
+ */
+
+/**
+ * Never-throw return contract.
+ * @template T
+ * @typedef {{ok:true, data:T} | {ok:false, error:ClientError}} Result
+ */
+
+// ── Result helpers ───────────────────────────────────────────────────────────
+
+/** @template T @param {T} data @returns {Result<T>} */
+function ok(data) {
+  return { ok: true, data };
+}
+
+/** @param {ClientError} error @returns {{ok:false, error:ClientError}} */
+function fail(error) {
+  return { ok: false, error };
+}
+
+// ── Locating the `crtr` binary ───────────────────────────────────────────────
+
+/**
+ * One candidate way to invoke crtr: a binary plus any fixed prefix args.
+ * @typedef {Object} Candidate
+ * @property {string} bin
+ * @property {string[]} prefix
+ */
+
+/**
+ * Candidates, in order: explicit override → PATH `crtr` → PATH `crouter` → the
+ * dev fallback `node <dist/cli.js>` resolved relative to THIS file (which, when
+ * shipped, lives at `dist/builtin-views/canvas/client.mjs`, so `../../cli.js` is
+ * `dist/cli.js`). We try the next only when a candidate fails to spawn (ENOENT);
+ * a candidate that spawns and exits nonzero is authoritative.
+ * @returns {Candidate[]}
+ */
+function crtrCandidates() {
+  /** @type {Candidate[]} */
+  const out = [];
+  if (process.env.CRTR_BIN) out.push({ bin: process.env.CRTR_BIN, prefix: [] });
+  out.push({ bin: 'crtr', prefix: [] });
+  out.push({ bin: 'crouter', prefix: [] });
+  try {
+    const here = dirname(fileURLToPath(import.meta.url)); // …/dist/builtin-views/canvas
+    const cli = join(here, '..', '..', 'cli.js'); // …/dist/cli.js
+    if (existsSync(cli)) out.push({ bin: process.execPath, prefix: [cli] });
+  } catch {
+    /* import.meta.url unavailable — skip the dev fallback */
+  }
+  return out;
+}
+
+// ── Process runner (never throws) ────────────────────────────────────────────
+
+/**
+ * @typedef {Object} RunResult
+ * @property {boolean} spawned   False ⇒ no candidate binary could be spawned.
+ * @property {number}  exitCode  Process exit code (0 on success; -1 if not spawned).
+ * @property {string}  stdout
+ * @property {string}  stderr
+ */
+
+/**
+ * Run one candidate. Resolves (never rejects). ENOENT ⇒ `spawned:false` so the
+ * caller can try the next candidate.
+ * @param {Candidate} c
+ * @param {string[]} argv
+ * @returns {Promise<RunResult>}
+ */
+function runOnce(c, argv) {
+  return new Promise((resolve) => {
+    execFile(
+      c.bin,
+      [...c.prefix, ...argv],
+      { maxBuffer: 64 * 1024 * 1024, encoding: 'utf8' },
+      (err, stdout, stderr) => {
+        const out = typeof stdout === 'string' ? stdout : '';
+        const errOut = typeof stderr === 'string' ? stderr : '';
+        if (err && /** @type {any} */ (err).code === 'ENOENT') {
+          resolve({ spawned: false, exitCode: -1, stdout: out, stderr: errOut });
+          return;
+        }
+        const code = err
+          ? typeof /** @type {any} */ (err).code === 'number'
+            ? /** @type {any} */ (err).code
+            : 1
+          : 0;
+        resolve({ spawned: true, exitCode: code, stdout: out, stderr: errOut });
+      }
+    );
+  });
+}
+
+/**
+ * Run `crtr` with the given argv, walking candidates until one spawns.
+ * @param {string[]} argv
+ * @returns {Promise<RunResult>}
+ */
+async function runCrtr(argv) {
+  /** @type {RunResult} */
+  let last = { spawned: false, exitCode: -1, stdout: '', stderr: '' };
+  for (const c of crtrCandidates()) {
+    last = await runOnce(c, argv);
+    if (last.spawned) return last;
+  }
+  return last; // never spawned
+}
+
+/** @returns {ClientError} */
+function crtrMissingError() {
+  return {
+    kind: 'crtr-missing',
+    message:
+      "crtr not found — tried CRTR_BIN, PATH 'crtr'/'crouter', and the local cli.js. " +
+      'Install crtr or set CRTR_BIN.',
+  };
+}
+
+/**
+ * Pull a human message out of crtr stderr: prefer the last `ERROR:` line, else
+ * the last non-empty line, else a generic fallback.
+ * @param {string} stderr
+ * @returns {string}
+ */
+function extractMessage(stderr) {
+  const lines = String(stderr || '')
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (/^ERROR:/i.test(lines[i])) return lines[i].replace(/^ERROR:\s*/i, '').trim();
+  }
+  if (lines.length) return lines[lines.length - 1];
+  return 'crtr command failed';
+}
+
+/**
+ * Map a failed crtr invocation to a typed {@link ClientError}.
+ * @param {string} stderr
+ * @returns {ClientError}
+ */
+function classifyError(stderr) {
+  const s = String(stderr || '');
+  if (/help-gate:\s*blocked/i.test(s)) {
+    return { kind: 'error', message: 'crtr help-gate blocked the call (run the command with -h once).' };
+  }
+  return { kind: 'crtr-failed', message: extractMessage(s) };
+}
+
+/**
+ * Run a crtr `--json` leaf and parse stdout as JSON.
+ * @param {string[]} argv
+ * @returns {Promise<Result<any>>}
+ */
+async function runJson(argv) {
+  const r = await runCrtr(argv);
+  if (!r.spawned) return fail(crtrMissingError());
+  if (r.exitCode !== 0) return fail(classifyError(r.stderr || r.stdout));
+  const out = String(r.stdout || '').trim();
+  if (out === '') return ok(null);
+  try {
+    return ok(JSON.parse(out));
+  } catch {
+    return fail({ kind: 'parse', message: `could not parse \`crtr ${argv.join(' ')}\` output as JSON` });
+  }
+}
+
+// ── Field mappers ────────────────────────────────────────────────────────────
+
+/** @param {unknown} v @returns {string} */
+function str(v) {
+  return v == null ? '' : String(v);
+}
+
+/** @param {any} n @returns {CanvasNode} */
+function toNode(n) {
+  const o = n || {};
+  return {
+    nodeId: str(o.node_id),
+    name: str(o.name) || '(unnamed)',
+    kind: str(o.kind) || '?',
+    mode: str(o.mode) || '?',
+    lifecycle: str(o.lifecycle) || '?',
+    status: str(o.status) || '?',
+    parent: o.parent ? str(o.parent) : null,
+    created: str(o.created),
+  };
+}
+
+/** @param {any} i @returns {AttentionItem} */
+function toAttention(i) {
+  const o = i || {};
+  return {
+    nodeId: str(o.node_id),
+    name: str(o.name),
+    cwd: str(o.cwd),
+    count: typeof o.count === 'number' ? o.count : 0,
+  };
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Every node on the canvas (all statuses). The view rebuilds the forest from the
+ * `parent` edges and filters to active trees itself.
+ * @returns {Promise<Result<CanvasNode[]>>}
+ */
+export async function fetchNodes() {
+  const r = await runJson(['node', 'inspect', 'list', '--json']);
+  if (!r.ok) return r;
+  const arr = r.data && Array.isArray(r.data.nodes) ? r.data.nodes : [];
+  return ok(arr.map(toNode));
+}
+
+/**
+ * Pending human asks across the canvas (the "blocked on a human" signal).
+ * @returns {Promise<Result<{items:AttentionItem[], total:number}>>}
+ */
+export async function fetchAttention() {
+  const r = await runJson(['canvas', 'attention', 'list', '--json']);
+  if (!r.ok) return r;
+  const items = r.data && Array.isArray(r.data.items) ? r.data.items : [];
+  const total = r.data && typeof r.data.total === 'number' ? r.data.total : 0;
+  return ok({ items: items.map(toAttention), total });
+}
+
+/**
+ * Introspection helper (not used at runtime): the exact crtr commands this
+ * client shells, so the shape can be eyeballed without a live canvas.
+ * @returns {Record<string,string>}
+ */
+export function describeCommands() {
+  return {
+    fetchNodes: 'crtr node inspect list --json',
+    fetchAttention: 'crtr canvas attention list --json',
+  };
+}