@crouton-kit/crouter 0.3.45 → 0.3.46

package/dist/clients/attach/chat-view.d.ts

@@ -93,6 +93,10 @@ export declare class ChatView {
     private makeToolComponent;
     /** Append a child while keeping the activity/status area pinned to the bottom. */
     private append;
+    /** Approximate render width for inline mermaid diagrams. Only affects
+     *  termrender's trailing padding (stripped in the transform), so the terminal
+     *  column count is close enough without threading the live pane width here. */
+    private renderWidth;
     /** Number of chat children excluding the pinned status container. */
     private chatChildCount;
     /** Clear all chat content and re-pin an empty status container. */

package/dist/clients/attach/chat-view.js

@@ -25,6 +25,7 @@ import { AssistantMessageComponent, BashExecutionComponent, BranchSummaryMessage
 import { ContextMessageComponent } from './context-message.js';
 import { CRTR_OUTPUT_CUSTOM_TYPE, CrtrOutputMessageComponent, createCrtrBashToolDefinition, } from './crtr-output-render.js';
 import { CRTR_CYCLE_DIVIDER_CUSTOM_TYPE } from '../../core/runtime/session-cycles.js';
+import { transformMessageMermaid } from './mermaid-render.js';
 /** customType stamped on the injected `<crtr-context>` bearings block (mirrors
  *  CONTEXT_INTRO_CUSTOM_TYPE in canvas-context-intro.ts — kept as a local literal
  *  so the viewer never imports the in-process extension). */
@@ -286,7 +287,10 @@ export class ChatView {
                         // updateContent) so the rendered message shows the annotation.
                         event.message.errorMessage = errorMessage;
                     }
-                    this.streamingComponent.updateContent(event.message);
+                    // Render any complete ```mermaid fence in the settled reply to a
+                    // diagram before it reaches the markdown renderer (no-op when absent).
+                    const finalMessage = transformMessageMermaid(event.message, this.renderWidth());
+                    this.streamingComponent.updateContent(finalMessage);
                     if (stopReason === 'aborted' || stopReason === 'error') {
                         const text = errorMessage ?? 'Error';
                         for (const component of this.pendingTools.values()) {
@@ -490,7 +494,8 @@ export class ChatView {
                 break;
             }
             case 'assistant': {
-                this.append(new AssistantMessageComponent(message, this.hideThinking, getMarkdownTheme(), this.hiddenThinkingLabel));
+                // Settled history message — render its ```mermaid fences inline too.
+                this.append(new AssistantMessageComponent(transformMessageMermaid(message, this.renderWidth()), this.hideThinking, getMarkdownTheme(), this.hiddenThinkingLabel));
                 break;
             }
             // toolResult is rendered inline with its tool call (handled in applySnapshot).
@@ -518,6 +523,12 @@ export class ChatView {
         this.container.addChild(child);
         this.container.addChild(this.statusContainer);
     }
+    /** Approximate render width for inline mermaid diagrams. Only affects
+     *  termrender's trailing padding (stripped in the transform), so the terminal
+     *  column count is close enough without threading the live pane width here. */
+    renderWidth() {
+        return Math.max(40, process.stdout.columns ?? 80);
+    }
     /** Number of chat children excluding the pinned status container. */
     chatChildCount() {
         return this.container.children.filter((c) => c !== this.statusContainer).length;

package/dist/clients/attach/mermaid-render.d.ts

@@ -0,0 +1,23 @@
+/** Cheap predicate: does this text contain what looks like a mermaid fence at
+ *  all? Lets callers skip the transform (and the message rebuild) entirely for
+ *  the common no-diagram reply. */
+export declare function textHasMermaid(text: string): boolean;
+/** Replace each complete ```mermaid fence in `text` with the rendered diagram,
+ *  wrapped in a plain ``` code fence so pi's Markdown preserves its alignment.
+ *  Leaves the fence untouched when the renderer is unavailable (degrades to a
+ *  normal code block, exactly as before this feature) or when a render yields
+ *  nothing usable. `width` only affects termrender's trailing padding (mermaid
+ *  diagrams have no width control and overflow rather than truncate), which is
+ *  stripped here, so an approximate pane width is fine. */
+export declare function transformMermaidFences(text: string, width: number): string;
+/** True when any text part of an assistant message carries a mermaid fence. */
+export declare function messageHasMermaid(message: {
+    content?: unknown;
+}): boolean;
+/** Return a shallow clone of an assistant message with every text part's
+ *  mermaid fences rendered inline. Non-text parts (thinking, toolCall) are
+ *  passed through untouched, so thinking blocks and tool cards render exactly as
+ *  before. A no-mermaid message is returned unchanged (same reference). */
+export declare function transformMessageMermaid<T extends {
+    content?: unknown;
+}>(message: T, width: number): T;

package/dist/clients/attach/mermaid-render.js

@@ -0,0 +1,124 @@
+// mermaid-render.ts — inline mermaid rendering for assistant messages in the
+// `crtr surface attach` viewer.
+//
+// When an agent writes a ```mermaid fence in its reply, the raw source is
+// useless to a human watching the chat. This transforms each COMPLETE mermaid
+// fence into the diagram itself (box-drawing ASCII) before the text reaches
+// pi's markdown renderer, so the viewer shows the picture instead of the code.
+//
+// How it stays simple:
+//   • termrender renders mermaid to MONOCHROME box-drawing lines with zero ANSI
+//     escapes (verified: `--color on` output for a pure mermaid fence is
+//     byte-identical to `--color off`). So the rendered lines are safe to splice
+//     back into markdown inside a plain ``` code fence — pi's Markdown then shows
+//     them verbatim in monospace, no escape-code leakage, no re-wrapping.
+//   • `renderMarkdown` (humanloop — the sole org-wide termrender caller) is
+//     synchronous and memoized, so this is a plain string→string transform with
+//     no async swap or component lifecycle.
+//
+// Scope (v1): only ```mermaid fences. The wider termrender directive vocabulary
+// is deliberately out of scope — see the base prompt's Diagrams note.
+import { isRendererReady, renderMarkdown } from '@crouton-kit/humanloop';
+/** A complete mermaid fence: ```mermaid (opening info string) ... closing ```.
+ *  Line-anchored (m flag), non-greedy body (captured). An UNCLOSED fence (still
+ *  streaming) does not match, so mid-stream text is left raw and only settles to
+ *  a diagram once the closing ``` arrives. Indented / 4-backtick fences are out
+ *  of scope — the base prompt tells agents to write a bare ```mermaid fence. */
+const MERMAID_FENCE = /^```mermaid[^\n]*\n([\s\S]*?)\n```[ \t]*$/gm;
+/** Box-drawing, block-element, and geometric-shape ranges — the glyphs a real
+ *  mermaid-ascii render is made of. Their PRESENCE distinguishes a rendered
+ *  diagram from termrender's silent plaintext fallback, which echoes the mermaid
+ *  SOURCE verbatim (pure ASCII: `-->`, `[ ]`, `{ }`) when mermaid-ascii cannot
+ *  parse the diagram (e.g. an indented body, an unsupported node shape). */
+const DIAGRAM_GLYPH = /[\u2500-\u259F\u25A0-\u25FF]/;
+/** Strip the common leading indentation shared by every non-blank body line.
+ *  Agents routinely indent a fenced block to sit under a list item or heading,
+ *  and mermaid-ascii FAILS on a leading-indented `flowchart`/`graph` line —
+ *  dedenting first is what turns that common case from a fallback back into a
+ *  real diagram. */
+function dedent(body) {
+    const lines = body.split('\n');
+    let min = Infinity;
+    for (const line of lines) {
+        if (line.trim() === '')
+            continue;
+        min = Math.min(min, line.length - line.replace(/^[ \t]+/, '').length);
+    }
+    if (!Number.isFinite(min) || min === 0)
+        return body;
+    return lines.map((line) => (line.trim() === '' ? '' : line.slice(min))).join('\n');
+}
+/** Cheap predicate: does this text contain what looks like a mermaid fence at
+ *  all? Lets callers skip the transform (and the message rebuild) entirely for
+ *  the common no-diagram reply. */
+export function textHasMermaid(text) {
+    return text.includes('```mermaid');
+}
+function stripBlankEdges(lines) {
+    let start = 0;
+    let end = lines.length;
+    while (start < end && lines[start].trim() === '')
+        start++;
+    while (end > start && lines[end - 1].trim() === '')
+        end--;
+    return lines.slice(start, end);
+}
+/** Replace each complete ```mermaid fence in `text` with the rendered diagram,
+ *  wrapped in a plain ``` code fence so pi's Markdown preserves its alignment.
+ *  Leaves the fence untouched when the renderer is unavailable (degrades to a
+ *  normal code block, exactly as before this feature) or when a render yields
+ *  nothing usable. `width` only affects termrender's trailing padding (mermaid
+ *  diagrams have no width control and overflow rather than truncate), which is
+ *  stripped here, so an approximate pane width is fine. */
+export function transformMermaidFences(text, width) {
+    if (!textHasMermaid(text) || !isRendererReady())
+        return text;
+    return text.replace(MERMAID_FENCE, (whole, body) => {
+        try {
+            const doc = `\`\`\`mermaid\n${dedent(body)}\n\`\`\``;
+            const rendered = stripBlankEdges(renderMarkdown(doc, width).map((l) => l.replace(/\s+$/, '')));
+            // No diagram glyphs → mermaid-ascii could not render it and termrender
+            // echoed the source. Leave the original fence so pi renders it as a normal
+            // (mermaid-tagged) code block, never a stripped plain block of raw source.
+            if (rendered.length === 0 || !rendered.some((l) => DIAGRAM_GLYPH.test(l)))
+                return whole;
+            return ['```', ...rendered, '```'].join('\n');
+        }
+        catch {
+            return whole;
+        }
+    });
+}
+/** True when any text part of an assistant message carries a mermaid fence. */
+export function messageHasMermaid(message) {
+    const content = message.content;
+    if (typeof content === 'string')
+        return textHasMermaid(content);
+    if (!Array.isArray(content))
+        return false;
+    return content.some((p) => p?.type === 'text' && textHasMermaid(p.text ?? ''));
+}
+/** Return a shallow clone of an assistant message with every text part's
+ *  mermaid fences rendered inline. Non-text parts (thinking, toolCall) are
+ *  passed through untouched, so thinking blocks and tool cards render exactly as
+ *  before. A no-mermaid message is returned unchanged (same reference). */
+export function transformMessageMermaid(message, width) {
+    const content = message.content;
+    if (typeof content === 'string') {
+        if (!textHasMermaid(content))
+            return message;
+        return { ...message, content: transformMermaidFences(content, width) };
+    }
+    if (!Array.isArray(content) || !messageHasMermaid(message))
+        return message;
+    return {
+        ...message,
+        content: content.map((part) => {
+            const p = part;
+            if (p?.type === 'text' && typeof p.text === 'string' && textHasMermaid(p.text)) {
+                return { ...p, text: transformMermaidFences(p.text, width) };
+            }
+            return part;
+        }),
+    };
+}

package/dist/clients/web/source-cache.js

@@ -9,7 +9,7 @@
 // which requests are safe to share/cache within a short TTL.
 //
 // ONLY idempotent, side-effect-free `crtr` reads belong here. Writes
-// (node new / canvas revive / node msg), file reads, http requests, and any
+// (node new / node lifecycle revive / node msg), file reads, http requests, and any
 // request carrying stdin or an overridden cwd are NEVER cacheable — caching
 // those would drop a mutation or serve a stale cross-cwd read. Target-dependent
 // reads (node inspect snapshot/show for a specific id) ARE cacheable because the id

package/dist/commands/__tests__/revive-now-gate.test.js

@@ -1,11 +1,11 @@
-// Regression for issue #115: `crtr canvas revive --now` rejected exactly the
+// Regression for issue #115: `crtr node lifecycle revive --now` rejected exactly the
 // provider-fault nodes the canvas dashboard flags as ⚠ "needs you"
 // (status-glyph.ts `faultDispositionText`), because the old gate required
 // `retry.disposition === 'auto'` — the one disposition "needs you" NEVER is.
 // Run with: node --import tsx/esm --test 'src/commands/__tests__/revive-now-gate.test.ts'
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { isNowEligibleFault } from '../revive.js';
+import { isNowEligibleFault } from '../node-lifecycle-revive.js';
 import { faultNeedsYou } from '../../core/canvas/status-glyph.js';
 function fault(over) {
     return {

package/dist/commands/canvas-history/read.js

@@ -4,7 +4,7 @@ import { resolveRef } from '../../core/canvas/index.js';
 export const readLeaf = defineLeaf({
     name: 'read',
     description: 'read one search hit\'s full body by its ref',
-    whenToUse: 'you picked a hit from `canvas history search` (or `canvas history show`) and want its full content — pass the `<node-id>:<relpath>` ref verbatim. Strips frontmatter by default; add --frontmatter to keep the YAML header.',
+    whenToUse: 'you picked a hit from `canvas history search` (or `node inspect artifacts`) and want its full content — pass the `<node-id>:<relpath>` ref verbatim. Strips frontmatter by default; add --frontmatter to keep the YAML header.',
     help: {
         name: 'canvas history read',
         summary: 'resolve a <node-id>:<relpath> ref to its full artifact body',
@@ -28,7 +28,7 @@ export const readLeaf = defineLeaf({
         if (!ref.includes(':')) {
             throw usage(`ref must be <node-id>:<relpath>; received: ${ref}`, {
                 received: ref,
-                next: 'Get a valid ref from `canvas history search` or `canvas history show <node-id>`.',
+                next: 'Get a valid ref from `canvas history search` or `node inspect artifacts <node-id>`.',
             });
         }
         let resolved;
@@ -41,7 +41,7 @@ export const readLeaf = defineLeaf({
         if (resolved === null) {
             throw notFound(`no artifact for ref: ${ref}`, {
                 ref,
-                next: 'The node or file may not exist. Re-run `canvas history search` for a current ref, or `canvas history show <node-id>` to list a node\'s artifacts.',
+                next: 'The node or file may not exist. Re-run `canvas history search` for a current ref, or `node inspect artifacts <node-id>` to list a node\'s artifacts.',
             });
         }
         const source = resolved.source === 'report' && resolved.reportKind ? `report:${resolved.reportKind}` : resolved.source;

package/dist/commands/canvas-history/search.js

@@ -76,7 +76,7 @@ function sortArtifacts(arts, mode, scored) {
 export const searchLeaf = defineLeaf({
     name: 'search',
     description: 'ranked content search across the cwd\'s node history',
-    whenToUse: 'you want to find past work by what it SAYS — a design, a final report, a roadmap, a finding — across every node that ran in this cwd, ranked by relevance. Omit the query to browse the record by recency ("what happened here lately"). Narrow with --type/--kind/--status/--since, scope elsewhere with --cwd/--all-cwds/--under/--node, or switch to --grep for an exact regex over bodies. Use `canvas history read <ref>` to read a hit in full, `canvas history show <node-id>` to list one node\'s artifacts, and `canvas revive <id>` to reopen a node you found.',
+    whenToUse: 'you want to find past work by what it SAYS — a design, a final report, a roadmap, a finding — across every node that ran in this cwd, ranked by relevance. Omit the query to browse the record by recency ("what happened here lately"). Narrow with --type/--kind/--status/--since, scope elsewhere with --cwd/--all-cwds/--under/--node, or switch to --grep for an exact regex over bodies. Use `canvas history read <ref>` to read a hit in full, `node inspect artifacts <node-id>` to list one node\'s artifacts, and `node lifecycle revive <id>` to reopen a node you found.',
     help: {
         name: 'canvas history search',
         summary: 'ranked/filtered/sorted content search over the per-cwd episodic record (reports + context docs + meta)',

package/dist/commands/canvas-history.js

@@ -1,14 +1,13 @@
-// `canvas history` — search and recall the canvas's record of past work in a
-// cwd. The accumulated episodic record of every node that ran here and the
-// artifacts it left: its reports (final/update/urgent outcome summaries) and
-// context docs (specs, designs, roadmaps, findings). Distinct from `crtr
+// `canvas history` — search and recall the cwd-wide content corpus: ranked
+// search over every node's reports/context docs, plus reading one hit's full
+// body by ref. One node's own artifact listing lives at `node inspect
+// artifacts` (a single-node read, not a graph-wide one). Distinct from `crtr
 // memory`, which is curated semantic knowledge held independent of any episode.
-// This branch owns CONTENT; it never duplicates the graph (use `canvas revive`
-// to reopen a found node, `node inspect show` for its topology).
+// This branch owns CONTENT; it never duplicates the graph (use `node lifecycle
+// revive` to reopen a found node, `node inspect show` for its topology).
 import { defineBranch } from '../core/command.js';
 import { searchLeaf } from './canvas-history/search.js';
 import { readLeaf } from './canvas-history/read.js';
-import { showLeaf } from './canvas-history/show.js';
 /** A tiny per-cwd `<corpus>` marker for branch -h — just enough context to
  *  anchor the help text without scanning nodes or files. Uses only the injected
  *  node cwd env (or the process cwd outside a node), so help stays cheap. */
@@ -18,13 +17,13 @@ function corpusBlock() {
 }
 export const historyBranch = defineBranch({
     name: 'history',
-    description: 'search and recall the canvas\'s record of past work in this cwd',
-    whenToUse: 'you want to find or re-read what was DONE in a cwd — a past design, a final report, a roadmap, a finding — across every node that ran there. Use it when picking up prior work ("that caching work from last week"), recovering an artifact, or surveying a project\'s history. Distinct from `crtr memory` (curated semantic knowledge, not episodes) and from `canvas dashboard`/`node inspect` (graph topology, not content).',
+    description: 'search and recall the cwd-wide content corpus — every node\'s reports and context docs',
+    whenToUse: 'you want to find or re-read what was DONE in a cwd — a past design, a final report, a roadmap, a finding — across every node that ran there, WITHOUT already knowing which node. Use it when picking up prior work ("that caching work from last week"), recovering an artifact, or surveying a project\'s history. Already have the node id and just want everything IT left behind? Use `node inspect artifacts <id>` instead — this branch is the cwd-wide search corpus, not a per-node listing. Distinct from `crtr memory` (curated semantic knowledge, not episodes) and from `canvas dashboard`/`node inspect` (graph topology, not content).',
     help: {
         name: 'canvas history',
-        summary: 'search and recall the canvas\'s record of past work in this cwd',
-        model: 'The accumulated record of every node that ran in a cwd and the artifacts it left — its reports (final/update outcome summaries) and context docs (specs, designs, roadmaps, findings). `search` finds by content (ranked, filtered, sorted; omit the query to browse by recency); `read` pulls one hit\'s full body by its <node-id>:<relpath> ref; `show` lists everything one node left. This is the episodic record of what was DONE — distinct from `crtr memory`, which is curated semantic knowledge. A node\'s raw inbox history (`--type inbox`) is a separate, opt-in diagnostic corpus — the full cursor-independent inbox.jsonl for one node, including un-clipped direct-message bodies; reach for it only when the curated reports/docs above don\'t already answer the question. To reopen a node you found, use `canvas revive`; for its place in the graph, `node inspect show`.',
+        summary: 'search and recall the cwd-wide content corpus — every node\'s reports and context docs in this cwd',
+        model: 'The accumulated record of every node that ran in a cwd and the artifacts it left — its reports (final/update outcome summaries) and context docs (specs, designs, roadmaps, findings). `search` finds by content (ranked, filtered, sorted; omit the query to browse by recency); `read` pulls one hit\'s full body by its <node-id>:<relpath> ref. This is the episodic record of what was DONE — distinct from `crtr memory`, which is curated semantic knowledge. Already have a node id and want everything IT left behind (not a cwd-wide search)? Use `node inspect artifacts <node-id>` instead — that single-node listing moved out of this branch. A node\'s raw inbox history (`--type inbox`) is a separate, opt-in diagnostic corpus — the full cursor-independent inbox.jsonl for one node, including un-clipped direct-message bodies; reach for it only when the curated reports/docs above don\'t already answer the question. To reopen a node you found, use `node lifecycle revive`; for its place in the graph, `node inspect show`.',
         dynamicState: corpusBlock,
     },
-    children: [searchLeaf, readLeaf, showLeaf],
+    children: [searchLeaf, readLeaf],
 });

package/dist/commands/canvas-rebuild-index.js

@@ -5,7 +5,7 @@
 // deployment's recreate-from-template, where node data lives on a durable Volume
 // but canvas.db lives on local disk that the recreate wipes — this verb rebuilds
 // the rows (identity columns) from the surviving metas via `rebuildIndex()`, so a
-// subsequent `canvas revive` finds its node again.
+// subsequent `node lifecycle revive` finds its node again.
 //
 // Fails loud if metas are present but the rebuild yields zero rows: a silent
 // empty db there means the revive would no-op against nothing.
@@ -29,7 +29,7 @@ function countOnDiskMetas() {
 export const canvasRebuildIndexLeaf = defineLeaf({
     name: 'rebuild-index',
     description: 're-derive node rows in canvas.db from on-disk nodes/<id>/meta.json',
-    whenToUse: 'canvas.db is missing or stale relative to the on-disk node metas and you need its node rows re-derived — most concretely after a remote/guest deployment\'s recreate-from-template, where node data survives on a durable Volume but canvas.db (local disk) was wiped, so a `canvas revive` would otherwise find no row. Identity columns are rebuilt from each meta; runtime columns (status/intent/pi_pid/window/tmux) take their quiescent defaults, and subscribes_to edges are left intact',
+    whenToUse: 'canvas.db is missing or stale relative to the on-disk node metas and you need its node rows re-derived — most concretely after a remote/guest deployment\'s recreate-from-template, where node data survives on a durable Volume but canvas.db (local disk) was wiped, so a `node lifecycle revive` would otherwise find no row. Identity columns are rebuilt from each meta; runtime columns (status/intent/pi_pid/window/tmux) take their quiescent defaults, and subscribes_to edges are left intact',
     help: {
         name: 'canvas rebuild-index',
         summary: 're-derive canvas.db node rows from on-disk metas; fails loud if metas exist but yield no rows',

package/dist/commands/canvas.js

@@ -3,7 +3,7 @@
 // Where `node` operates on one node and `push` is a node's own spine write
 // verb, `canvas` is the bird's-eye / supervisor surface over the entire canvas:
 // render the subscription forest (`dashboard`), see who is blocked on a human
-// (`attention`), and bring a node back (`revive`). It assembles leaves/branches
+// (`attention`), and mass-reconnect disconnected nodes (`revive --all`). It assembles leaves/branches
 // the sibling command files own, so each piece declares its own help one level
 // down.
 import { defineBranch } from '../core/command.js';
@@ -33,14 +33,14 @@ export function registerCanvas() {
     return defineBranch({
         name: 'canvas',
         rootEntry: {
-            concept: 'the whole agent graph at a glance — render it, see who is blocked, revive a node',
+            concept: 'the whole agent graph at a glance — render it, see who is blocked, mass-revive disconnected nodes',
             desc: 'bird\'s-eye view and supervision of the entire canvas',
-            useWhen: 'surveying the full graph, finding blocked agents, or reviving a node',
+            useWhen: 'surveying the full graph, finding blocked agents, or mass-reviving every disconnected node at once',
         },
         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 write verb (`push`). `dashboard` renders the subscription forest as a tree; `browse` opens an interactive full-screen navigator (tabs/tree/search) over the whole canvas and resumes the chosen node; `attention` aggregates pending human asks across the graph; `revive` reopens a window for a done/idle/dead/canceled node; `history` searches and recalls the content record (reports + context docs) of past work in a cwd; `prune` bounds growth by deleting terminal nodes past a TTL.',
+            model: 'Canvas-wide operations, distinct from per-node work (`node`) and a node\'s own spine write verb (`push`). `dashboard` renders the subscription forest as a tree; `browse` opens an interactive full-screen navigator (tabs/tree/search) over the whole canvas and resumes the chosen node; `attention` aggregates pending human asks across the graph; `revive --all` mass-reconnects every disconnected node (bringing back ONE named node is `node lifecycle revive <id>` instead); `history` searches and recalls the content record (reports + context docs) of past work in a cwd; `prune` bounds growth by deleting terminal nodes past a TTL.',
         },
         children: [dashboardLeaf, canvasSnapshotLeaf, browseLeaf, attentionBranch, reviveLeaf, historyBranch, chordLeaf, issueBranch, canvasPruneLeaf, canvasRebuildIndexLeaf],
     });

package/dist/commands/node-inspect-artifacts.d.ts

@@ -0,0 +1 @@
+export declare const nodeArtifactsLeaf: import("../core/command.js").LeafDef;

package/dist/commands/{canvas-history/show.js → node-inspect-artifacts.js}

@@ -1,14 +1,14 @@
-import { defineLeaf } from '../../core/command.js';
-import { notFound } from '../../core/errors.js';
-import { getNode, nodeArtifacts } from '../../core/canvas/index.js';
+import { defineLeaf } from '../core/command.js';
+import { notFound } from '../core/errors.js';
+import { getNode, nodeArtifacts } from '../core/canvas/index.js';
 import { statSync } from 'node:fs';
 const TYPES = ['report', 'doc', 'roadmap', 'inbox'];
-export const showLeaf = defineLeaf({
-    name: 'show',
+export const nodeArtifactsLeaf = defineLeaf({
+    name: 'artifacts',
     description: 'enumerate one node\'s artifacts as refs',
     whenToUse: 'you have a node id and want to see everything it left behind — its reports and context docs as refs ready for `canvas history read`. The bridge from "found the node" to "read its artifacts". Use `node inspect show` instead for the node\'s topology/neighbors, not its content.',
     help: {
-        name: 'canvas history show',
+        name: 'node inspect artifacts',
         summary: 'list one node\'s artifacts (reports + context docs) as refs ready for `canvas history read`',
         params: [
             { kind: 'positional', name: 'node-id', required: true, constraint: 'The node whose artifacts to list.' },
@@ -55,7 +55,7 @@ export const showLeaf = defineLeaf({
         return {
             node: `${node?.name} (${nodeId})`,
             artifacts,
-            follow_up: 'Read one with `canvas history read <ref>`; reopen the node with `canvas revive ' + nodeId + '`.',
+            follow_up: 'Read one with `canvas history read <ref>`; reopen the node with `node lifecycle revive ' + nodeId + '`.',
         };
     },
     render: (r) => {

package/dist/commands/node-lifecycle-revive.d.ts

@@ -0,0 +1,12 @@
+import type { LeafDef } from '../core/command.js';
+import type { Fault } from '../core/runtime/fault.js';
+/** --now eligibility for a live, non-busy fault: a daemon-owned AUTO retry
+ *  (kick it early instead of waiting out the schedule), or any fault the
+ *  canvas dashboard flags "needs you" (`faultNeedsYou`, status-glyph.ts) — the
+ *  disposition that otherwise has NO sanctioned recovery verb (issue #115).
+ *  Both are scoped to `pi→provider`: refuses a client-owned auto retry
+ *  (redialing) already in flight, and refuses any OTHER link — notably a
+ *  `daemon→node` wedge fault, which --now can't clear (SIGTERM doesn't touch
+ *  the runaway subprocess; see `wedged-child-on-runaway-bash`). */
+export declare function isNowEligibleFault(fault: Fault | null): boolean;
+export declare const nodeReviveLeaf: LeafDef;

package/dist/commands/node-lifecycle-revive.js

@@ -0,0 +1,166 @@
+// `crtr node lifecycle revive` — bring back ONE named node.
+//
+// Bypasses the daemon: directly relaunches the broker engine for a node that is
+// done, idle, dead, or canceled. Default behavior resumes the saved pi
+// conversation by its absolute session-file path (--session <path>) when that
+// .jsonl still exists, else falls through to a fresh launch. `--fresh` skips
+// the true resume: if the `.jsonl` already exists it CYCLES in place instead
+// (same file, a fresh `crtr-cycle` branch — `resumed:false`), and only starts a
+// genuinely clean session when no `.jsonl` exists yet (also `resumed:false`).
+//
+// `--now` is the on-demand kick for a hanging node (live broker parked on an
+// eligible pi→provider fault): SIGTERM the broker so the daemon's own
+// crash→grace→resume path brings it back, instead of waiting out the schedule.
+//
+// The mass-recovery form — reconnect EVERY disconnected node at once after a
+// reboot/crash — is genuinely graph-wide and stays at `canvas revive --all`
+// (src/commands/revive.ts).
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { reviveNode } from '../core/runtime/revive.js';
+import { waitForBrokerViewSocket } from '../core/runtime/placement.js';
+import { getNode, fullName } from '../core/canvas/index.js';
+import { isPidAlive } from '../core/canvas/pid.js';
+import { readFault } from '../core/runtime/fault.js';
+import { isBusy } from '../core/runtime/busy.js';
+import { faultNeedsYou } from '../core/canvas/status-glyph.js';
+/** --now eligibility for a live, non-busy fault: a daemon-owned AUTO retry
+ *  (kick it early instead of waiting out the schedule), or any fault the
+ *  canvas dashboard flags "needs you" (`faultNeedsYou`, status-glyph.ts) — the
+ *  disposition that otherwise has NO sanctioned recovery verb (issue #115).
+ *  Both are scoped to `pi→provider`: refuses a client-owned auto retry
+ *  (redialing) already in flight, and refuses any OTHER link — notably a
+ *  `daemon→node` wedge fault, which --now can't clear (SIGTERM doesn't touch
+ *  the runaway subprocess; see `wedged-child-on-runaway-bash`). */
+export function isNowEligibleFault(fault) {
+    if (fault === null || fault.link !== 'pi→provider')
+        return false;
+    if (faultNeedsYou(fault))
+        return true;
+    return fault.retry.by === 'daemon';
+}
+export const nodeReviveLeaf = defineLeaf({
+    name: 'revive',
+    description: 'reopen a window for a done/idle/dead/canceled node',
+    whenToUse: 'you want to bring a dormant node back yourself — reopen a window for one that is done, idle, dead, or canceled: resume a node you closed with `node lifecycle close`, reopen a finished worker for a follow-up, or restart a crashed one now instead of waiting. It resumes the saved conversation by default, or can restart the node clean. You rarely need this for crashes — the daemon auto-revives those; reach for it to bring a node back on demand, to revive a canceled node the daemon will never touch on its own, or to kick a hanging one early (--now). To mass-reconnect EVERY disconnected node at once (after a reboot, a killed login/tmux session, or the daemon being down a while), use `canvas revive --all` instead',
+    help: {
+        name: 'node lifecycle revive',
+        summary: 'relaunch a node\'s broker engine (resuming its saved conversation), or kick a hanging one (--now)',
+        params: [
+            {
+                kind: 'positional',
+                name: 'node',
+                required: true,
+                constraint: 'Node id to revive.',
+            },
+            {
+                kind: 'flag',
+                name: 'fresh',
+                type: 'bool',
+                required: false,
+                default: false,
+                constraint: 'When set, do NOT do a true resume. If the node already has a session `.jsonl`, this instead CYCLES it in place — reuses that SAME file, resets the tree leaf, and roots a fresh `crtr-cycle` branch (a clean-context restart that still carries the file\'s history, output `resumed:false`). Only when no `.jsonl` exists yet does this start a genuinely brand-new session (also `resumed:false`). Default (no --fresh): a true resume — replays the existing `.jsonl` as-is (`resumed:true`).',
+            },
+            {
+                kind: 'flag',
+                name: 'now',
+                type: 'bool',
+                required: false,
+                default: false,
+                constraint: 'On-demand kick of an active-fault node (parked on a `pi→provider` fault, broker still alive). Its broker pid is alive, so an ordinary revive no-ops (double-launch guard) — --now SIGTERMs the live broker instead, so the daemon\'s crash→grace→resume path brings it back in ~20s. Valid for a live `pi→provider` fault that is either a daemon-owned auto retry (kicks it early), or ANY fault the canvas dashboard flags "needs you" (e.g. exhausted retries, an auth fault you just fixed) — that disposition otherwise has no recovery verb. Mutually exclusive with --fresh.',
+            },
+        ],
+        output: [
+            { name: 'window', type: 'string', required: false, constraint: 'Always null — the revived broker is headless and opens no tmux window. Kept for caller back-compat.' },
+            { name: 'session', type: 'string', required: false, constraint: 'The node\'s last live location session, or null — the headless broker has no tmux session of its own.' },
+            { name: 'resumed', type: 'boolean', required: false, constraint: 'True ONLY for a true resume (the existing `.jsonl` replayed as-is). False for a --fresh revive, whether that landed as an in-place CYCLE (an existing `.jsonl` reused with a fresh `crtr-cycle` branch — pi is still told --session, but this is not a resume) or a genuinely fresh launch (no `.jsonl` existed). Absent for a --now kick.' },
+            { name: 'ready', type: 'boolean', required: false, constraint: 'True when the revived broker\'s view.sock accepted a connection before return — the node is immediately attachable/drivable. Absent for a --now kick.' },
+            { name: 'kicked', type: 'boolean', required: false, constraint: 'True when --now SIGTERM\'d the hanging node\'s live broker (the daemon resumes it on the saved session within ~20s). Absent for an ordinary revive.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Launches the node\'s detached headless broker engine (no tmux window).',
+            'Updates the node\'s canvas record: status=active, intent=null.',
+            'Blocks until the broker\'s view.sock accepts a connection (up to ~30s), so a caller can attach/dial immediately on return.',
+            '--now: SIGTERMs the live broker instead of launching anything (the daemon\'s own crash-grace path resumes it).',
+        ],
+    },
+    run: async (input) => {
+        const now = input['now'] ?? false;
+        const nodeId = input['node'];
+        const fresh = input['fresh'] ?? false;
+        if (now && fresh) {
+            throw new InputError({
+                error: 'conflicting_args',
+                message: '`--now` kicks a live hanging broker (SIGTERM → daemon resumes the SAVED session); `--fresh` is meaningless there.',
+                next: 'Run `crtr node lifecycle revive <node> --now` (resumes), or `crtr node lifecycle revive <node> --fresh` (no --now) to relaunch clean.',
+            });
+        }
+        // Validate the node exists before attempting revival.
+        const meta = getNode(nodeId);
+        if (meta === null) {
+            throw new InputError({
+                error: 'not_found',
+                message: `no node: ${nodeId}`,
+                next: 'List nodes with `crtr node inspect list`.',
+            });
+        }
+        // --now: the on-demand kick for an active fault. The broker is ALIVE (so
+        // reviveNode would no-op the double-launch guard) — SIGTERM it so the daemon's
+        // ordinary crash→grace→resume path recovers it on the saved session, the same
+        // thing the daemon does at the auto-recovery grace, just on demand. Gated on
+        // a live pid and an eligible pi→provider fault (`isNowEligibleFault` above) so
+        // it can't be used to nuke a healthy node.
+        if (now) {
+            const pid = meta.pi_pid;
+            const stall = readFault(nodeId);
+            if (pid == null || !isPidAlive(pid)) {
+                throw new InputError({
+                    error: 'not_hanging',
+                    message: `${nodeId} has no live broker — nothing to kick. --now is for a HANGING node (live broker parked on an active fault).`,
+                    next: 'Revive a dormant node with `crtr node lifecycle revive ' + nodeId + '` (no --now).',
+                });
+            }
+            if (!isNowEligibleFault(stall)) {
+                throw new InputError({
+                    error: 'not_hanging',
+                    message: `${nodeId} is live but has no pi→provider fault eligible for --now (either healthy, or a client-owned retry / non-provider fault already being handled elsewhere) — --now refuses to SIGTERM a node that isn't stuck on a kickable provider fault.`,
+                    next: 'Use --now only on a node the canvas shows as hanging (⚠) with a `pi→provider` fault. For a routine relaunch, omit --now.',
+                });
+            }
+            // The daemon never kills a BUSY engine (its verdict paths all return 'leave'
+            // on a live busy marker): a node mid-turn is making progress, not wedged —
+            // refuse rather than SIGTERM it mid-flight.
+            if (isBusy(nodeId)) {
+                throw new InputError({
+                    error: 'busy',
+                    message: `${nodeId} is mid-turn right now (busy) — --now refuses to SIGTERM a working engine; it has recovered on its own.`,
+                    next: 'Re-check the canvas — if it\'s no longer marked hanging (⚠), nothing to do.',
+                });
+            }
+            try {
+                process.kill(pid, 'SIGTERM');
+            }
+            catch {
+                /* best-effort: the broker may have just died; the daemon owns the resume */
+            }
+            return {
+                window: null,
+                session: meta.tmux_session ?? null,
+                kicked: true,
+                message: `Sent SIGTERM to ${fullName(meta)} (${nodeId}, pid ${pid}). The daemon will resume it on the saved session within ~20s (crash→grace→resume).`,
+            };
+        }
+        const result = reviveNode(nodeId, { resume: !fresh });
+        // Revive returns once the broker process is launched, which can be seconds
+        // before its view.sock listens. Callers (attach, the web shell's Wake) dial
+        // immediately on return, so block here until the socket accepts.
+        const ready = await waitForBrokerViewSocket(nodeId, result.launch?.exited);
+        return {
+            window: result.window ?? undefined,
+            session: result.session,
+            resumed: result.resumed,
+            ready,
+        };
+    },
+});

package/dist/commands/node-worktree.d.ts

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