@crouton-kit/crouter 0.3.31 → 0.3.33

package/dist/commands/human/shared.js

@@ -8,7 +8,7 @@ export const DECK_SCHEMA_HINT = 'Deck must match the humanloop deck schema: {tit
     'source?:{sessionName?,askedBy?,blockedSince?}, ' +
     'interactions:[{id,title,subtitle?,(body?|bodyPath?),options:[{id,label,' +
     'description?}],multiSelect?,allowFreetext?,freetextLabel?,' +
-    "kind?:'notify'|'validation'|'decision'|'context'|'error'}]}.";
+    "kind?:'notify'|'decision'|'context'|'error'}]}.";
 export function resolveMaxPanes() {
     return readConfig('user').max_panes_per_window;
 }
@@ -42,7 +42,7 @@ export function resolveHumanTarget() {
 /**
  * Open the detached humanloop `_run` pane for an interaction dir, ROUTED to the
  * session the user is watching (`resolveHumanTarget`). The single spawn path
- * behind ask/approve/review (`spawnHumanJob`) and notify. `detached: true` keeps
+ * behind ask/review (`spawnHumanJob`) and notify. `detached: true` keeps
  * the user's view put — the prompt lands beside the watched node without
  * jumping their session/window. `jobId`, when given, is injected as CRTR_JOB_ID.
  */
@@ -90,7 +90,7 @@ export function followUpReview(_jobId) {
  *
  * Completion routing needs no bookkeeping here: the human node was created
  * under the asking node as its parent (spawnNode auto-subscribes the parent),
- * so the `pushFinal` the `_run` worker emits — for ask, approve, AND review —
+ * so the `pushFinal` the `_run` worker emits — for ask AND review —
  * fans the answer straight into the asking node's inbox. The pane id is recorded
  * on run.json (not returned) so `human cancel` can later kill the TUI.
  */

package/dist/commands/human.js

@@ -1,41 +1,42 @@
 // `crtr human` subtree — in-process humanloop bridge.
 //
-// Kickoff leaves (ask/approve/review) create a kind:'human' node under the
+// Kickoff leaves (ask/review) create a kind:'human' node under the
 // asking node, write deck.json/run.json into the per-cwd interaction dir, spawn
 // a detached `crtr human _run` pane, and return immediately. The human's answer
 // is pushed as the node's final report, which fans out to the asking node's
 // inbox — no polling surface. notify/show create no node. _run runs the blocking
 // humanloop call at the pane TTY and pushes the result itself.
 //
-// TTY safety: every leaf is argv-only — none declares a stdin parameter, so
-// the spawned pane's TTY stays free for humanloop's raw-mode input. Control
-// params travel via CRTR_HUMAN_DIR (set inline in the spawned command) +
-// run.json, never stdin.
+// TTY safety: kickoff/TUI leaves are argv-only, so the spawned pane's TTY stays
+// free for humanloop's raw-mode input. Control params travel via CRTR_HUMAN_DIR
+// (set inline in the spawned command) + run.json, never stdin. The noninteractive
+// resolve leaf is the only stdin-taking child and does not spawn a TUI pane.
 import { defineBranch } from '../core/command.js';
-import { humanAsk, humanApprove, humanReview, humanNotify, humanShow } from './human/prompts.js';
-import { humanInbox, humanList, humanCancel, humanRun } from './human/queue.js';
+import { humanAsk, humanReview, humanNotify, humanShow } from './human/prompts.js';
+import { humanInbox, humanList, humanDeck, humanResolve, humanCancel, humanRun } from './human/queue.js';
 export function registerHuman() {
     return defineBranch({
         name: 'human',
         rootEntry: {
             concept: 'human-in-the-loop decisions, document review, and live display',
-            desc: 'ask, approve, review, notify, show, cancel, inbox, list',
+            desc: 'ask, review, notify, show, cancel, inbox, list',
             useWhen: 'you have a question for the user, want their feedback, or are presenting them with options or a choice — always reach for human instead of guessing or assuming, or laying a choice out as prose, when a person can decide; and whenever the user wants to review a spec, plan, or requirements document, this is the command (use `human review` for anchored line-by-line comments)'
         },
         help: {
             name: 'human',
             summary: 'human-in-the-loop decisions, document review, and live display',
-            model: "Every body and displayed file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one. ask, approve, and review are kickoffs: they create a kind:'human' node under you and return instantly, never blocking — the human's response is pushed to your inbox when they answer, so keep working (or just end your turn) and you'll be woken with it. review puts a .md live on the human's screen for anchored comments and tracks the file, so edit in place rather than canceling and re-presenting. notify and show create no node.",
+            model: "Every body and displayed file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one. ask and review are kickoffs: they create a kind:'human' node under you and return instantly, never blocking — the human's response is pushed to your inbox when they answer, so keep working (or just end your turn) and you'll be woken with it. ask covers everything from a yes/no sign-off gate (two options) to an open-ended judgment call; review puts a .md live on the human's screen for anchored comments and tracks the file, so edit in place rather than canceling and re-presenting. notify and show create no node.",
         },
         children: [
             humanAsk,
-            humanApprove,
             humanReview,
             humanNotify,
             humanShow,
             humanCancel,
             humanInbox,
             humanList,
+            humanDeck,
+            humanResolve,
             humanRun,
         ],
     });

package/dist/commands/memory/find.js

@@ -57,7 +57,7 @@ export const findLeaf = defineLeaf({
         ],
         output: [
             { name: 'query', type: 'string', required: true, constraint: 'Echo of the input query.' },
-            { name: 'hits', type: 'object[]', required: true, constraint: 'Ranked mode — each: {name, kind, scope, score, short_form}, sorted by score descending. Under --grep instead — each: {path, line, text} for every body line matching the regex, sorted by path then line ascending.' },
+            { name: 'hits', type: 'object[]', required: true, constraint: 'Ranked mode — each: {name, kind, scope, path, score, short_form}, sorted by score descending; path is the absolute file on disk — edit it directly to tweak the doc. Under --grep instead — each: {path, line, text} for every body line matching the regex, sorted by path then line ascending.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands for reading a hit in full or refining the search.' },
         ],
         outputKind: 'object',
@@ -133,10 +133,11 @@ export const findLeaf = defineLeaf({
                 name: h.unit.name,
                 kind: h.unit.kind,
                 scope: h.unit.scope,
+                path: h.unit.path,
                 score: h.score,
                 short_form: h.unit.shortForm,
             })),
-            follow_up: 'Read a hit in full with `crtr memory read <name>`. Add --body to weigh body text, or --grep for an exact regex.',
+            follow_up: 'Read a hit in full with `crtr memory read <name>`, or edit its `path` directly to tweak it. Add --body to weigh body text, or --grep for an exact regex.',
         };
     },
 });

package/dist/commands/memory/list.js

@@ -14,7 +14,7 @@ export const listLeaf = defineLeaf({
             { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Filter to a single scope. Default: all resolved scopes.' },
         ],
         output: [
-            { name: 'items', type: 'object[]', required: true, constraint: 'One row per document. Each: {name, title, short_form, kind, scope, is_dir}. A directory INDEX.md surfaces as a dir entry (is_dir true, name = the directory path with a trailing slash); is_dir is false for an ordinary doc. short_form is the abbreviated hook — shown here and nowhere else. Sorted by scope then kind then name ascending.' },
+            { name: 'items', type: 'object[]', required: true, constraint: 'One row per document. Each: {name, title, short_form, kind, scope, path, is_dir}. path is the absolute file on disk — edit it directly to tweak the doc. A directory INDEX.md surfaces as a dir entry (is_dir true, name = the directory path with a trailing slash, path = its INDEX.md); is_dir is false for an ordinary doc. short_form is the abbreviated hook — shown here and nowhere else. Sorted by scope then kind then name ascending.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands — read a document in full or narrow the inventory.' },
         ],
         outputKind: 'object',
@@ -43,7 +43,7 @@ export const listLeaf = defineLeaf({
             // slash, flagged is_dir, so the inventory distinguishes it from a doc.
             const isDir = isIndexName(sub.name);
             const name = isDir ? indexDirOf(sub.name) + '/' : sub.name;
-            addItem({ name, kind: sub.kind, scope: sub.scope, shortForm: sub.shortForm, isDir });
+            addItem({ name, kind: sub.kind, scope: sub.scope, path: sub.path, shortForm: sub.shortForm, isDir });
         }
         items.sort((a, b) => {
             const sr = scopeRank(a.scope) - scopeRank(b.scope);
@@ -61,9 +61,10 @@ export const listLeaf = defineLeaf({
                 short_form: d.shortForm,
                 kind: d.kind,
                 scope: d.scope,
+                path: d.path,
                 is_dir: d.isDir,
             })),
-            follow_up: 'Read one in full with `crtr memory read <name>`. Narrow with --kind / --scope, or search a topic with `crtr memory find <query>`.',
+            follow_up: 'Read one in full with `crtr memory read <name>`, or edit its `path` directly to tweak it. Narrow with --kind / --scope, or search a topic with `crtr memory find <query>`.',
         };
     },
 });

package/dist/commands/memory/read.js

@@ -7,7 +7,7 @@ import { MEMORY_KINDS } from './shared.js';
 export const readLeaf = defineLeaf({
     name: 'read',
     description: 'load a memory document body by name',
-    whenToUse: 'a task in front of you matches a stored document and you already know its name — read it before improvising. Resolves the path-derived name across scopes by precedence (project > user > builtin), with leaf-name fallback like skills. You name the document by its crtr identifier, never a file path — do not cat or find the markdown off disk. Reach for `crtr memory find` first when you do not yet know which document applies.',
+    whenToUse: 'a task in front of you matches a stored document and you already know its name — read it before improvising. Resolves the path-derived name across scopes by precedence (project > user > builtin), with leaf-name fallback. You name the document by its crtr identifier, never a file path — do not cat or find the markdown off disk. Reach for `crtr memory find` first when you do not yet know which document applies.',
     help: {
         name: 'memory read',
         summary: 'resolve a path-derived name to its document body, frontmatter stripped unless --frontmatter',
@@ -20,7 +20,7 @@ export const readLeaf = defineLeaf({
             { name: 'name', type: 'string', required: true, constraint: 'Resolved document name.' },
             { name: 'kind', type: 'string', required: true, constraint: 'Resolved kind: knowledge or preference.' },
             { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was resolved from: project, user, or builtin.' },
-            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the document on disk.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the document on disk — edit this file directly to tweak the doc in place.' },
             { name: 'content', type: 'string', required: true, constraint: 'Document body. Frontmatter stripped unless --frontmatter is set.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Hints at variant flags or next commands.' },
         ],
@@ -58,7 +58,7 @@ export const readLeaf = defineLeaf({
                     scope: doc.scope,
                     path: doc.path,
                     content,
-                    follow_up: 'Add --frontmatter to include the YAML header. Browse the inventory with `crtr memory list`.',
+                    follow_up: 'Read the raw file at `path` to view the YAML frontmatter or edit this memory. Browse the inventory with `crtr memory list`.',
                 };
             }
         }

package/dist/commands/memory/shared.d.ts

@@ -29,8 +29,5 @@ export declare function coerceAppliesTo(raw: string): unknown;
 /** Serialize a substrate frontmatter record + body into a complete `.md`
  *  document. Frontmatter is emitted as a `---` fenced YAML block (the `yaml`
  *  package — the same one the parser uses — so nested gate maps and applies-to
- *  arrays round-trip), in canonical field order with preserved extras last. The
- *  skill-shaped `serializeFrontmatter` in core can only represent
- *  name/description/type/keywords, so it cannot carry the substrate fields —
- *  hence this focused serializer. */
+ *  arrays round-trip), in canonical field order with preserved extras last. */
 export declare function serializeMemoryDoc(frontmatter: Record<string, unknown>, body: string): string;

package/dist/commands/memory/shared.js

@@ -1,8 +1,8 @@
-// Shared constants + helpers for the `crtr memory` command family (task B2).
-// The leaf handlers (list/read/find/write) consume the resolver, substrate
-// schema, scope, and skill-resolver modules and build their documented output
-// objects on top of the small helpers here. Nothing in this file forks on kind
-// or re-implements the schema/gate/resolver — it only composes them.
+// Shared constants + helpers for the `crtr memory` command family. The leaf
+// handlers (list/read/find/write) consume the resolver, substrate schema, and
+// scope modules and build their documented output objects on top of the small
+// helpers here. Nothing in this file forks on kind or re-implements the
+// schema/gate/resolver — it only composes them.
 import { join } from 'node:path';
 import { stringify as yamlStringify, parse as yamlParse } from 'yaml';
 import { usage } from '../../core/errors.js';
@@ -116,10 +116,7 @@ const FRONTMATTER_ORDER = [
 /** Serialize a substrate frontmatter record + body into a complete `.md`
  *  document. Frontmatter is emitted as a `---` fenced YAML block (the `yaml`
  *  package — the same one the parser uses — so nested gate maps and applies-to
- *  arrays round-trip), in canonical field order with preserved extras last. The
- *  skill-shaped `serializeFrontmatter` in core can only represent
- *  name/description/type/keywords, so it cannot carry the substrate fields —
- *  hence this focused serializer. */
+ *  arrays round-trip), in canonical field order with preserved extras last. */
 export function serializeMemoryDoc(frontmatter, body) {
     const ordered = {};
     for (const key of FRONTMATTER_ORDER) {

package/dist/commands/memory/write.js

@@ -12,7 +12,7 @@ export const writeLeaf = defineLeaf({
         summary: 'create or update memory/<name>.md at the resolved scope from frontmatter flags + a stdin body',
         guide: 'The body is the easy part; the craft is ROUTING — every frontmatter flag decides who sees this doc, when, and at what context cost. Each rung up is paid by every future agent at every boot or read, forever, so default each rung DOWN.\n\n' +
             'Pick the kind. knowledge = anything you CONSULT \u2014 how to DO something (a repeatable procedure/playbook) OR what is TRUE / how something WORKS (a fact about the user, a system\u2019s behavior, code docs); preference = how to BEHAVE (a directive, a standing correction). The test that splits them: does it DIRECT behavior ("always lint after authoring" \u2192 preference) or INFORM what you know ("Silas likes chicken", "the daemon never reloads dist/" \u2192 knowledge)? A correction yields a preference; a learned fact or a repeatable procedure yields knowledge.\n\n' +
-            'Set the rungs \u2014 BOTH --system-prompt-visibility (boot) and --file-read-visibility (on-read) are REQUIRED on create. There is no default: the right rung is a case-by-case call, never a function of kind. The ladder, lowest to highest: `none` for niche docs almost nothing should pull into context; `name` for the common case \u2014 references and skills that are relatively uncommon but an agent (or the user, by name) may reach for; `preview` for docs important enough that their routing line is worth its token cost every session (preferences usually land here); `content` (full body injected) for a doc that would be `preview` except its body is already so short you may as well inline it whole. `content` is rare \u2014 when a `content` doc grows past a bullet or two, downgrade it to `preview`. Each axis is independent: usually one carries a real rung and the other is `none` (see the hook paragraph next).\n\n' +
+            'Set the rungs \u2014 BOTH --system-prompt-visibility (boot) and --file-read-visibility (on-read) are REQUIRED on create. There is no default: the right rung is a case-by-case call, never a function of kind. The ladder, lowest to highest: `none` for niche docs almost nothing should pull into context; `name` for the common case \u2014 knowledge docs that are relatively uncommon but an agent (or the user, by name) may reach for; `preview` for docs important enough that their routing line is worth its token cost every session (preferences usually land here); `content` (full body injected) for a doc that would be `preview` except its body is already so short you may as well inline it whole. `content` is rare \u2014 when a `content` doc grows past a bullet or two, downgrade it to `preview`. Each axis is independent: usually one carries a real rung and the other is `none` (see the hook paragraph next).\n\n' +
             'Choose the hook \u2014 boot vs file-read. There are exactly two moments a doc can surface. Behavior (preferences) and how-to procedure are relevant whatever file is open \u2192 surface at boot. Knowledge about code belongs NEXT TO the code: put the file in that directory\u2019s .crouter/memory/ and it fires positionally when files there are read, costing nothing at boot. The exception that matters: a knowledge doc about a PERSON or PROCESS has no code directory to anchor to, so on-read triggering is meaningless \u2014 set --system-prompt-visibility preview so its routing line surfaces at boot instead.\n\n' +
             'Write the routing line (--when-and-why-to-read) FIRST, before storing anything: "When <circumstance the agent is in>, this <kind> should be read because <what the read buys>." The test: can a stranger mid-task decide from that one line alone whether to spend the read? If you cannot name the concrete situation that triggers it, you do not yet understand the memory \u2014 ask the user ONE sharp question instead of improvising. ("Remember I like chicken" routes cleanly \u2192 food/meal decisions; "be careful with the API" does not \u2192 which API, careful how, against what failure?) And NEVER paraphrase the advice in the routing line \u2014 a preview that gives away the gist makes every future agent skip the real read. BAD: "\u2026because it carries the placement policy \u2014 -h first, memory only for dev-mode material." GOOD: "\u2026because it carries the standing placement policy."\n\n' +
             'Find before write. `crtr memory find <topic>` first; grow ONE doc per recurring circumstance rather than minting near-duplicates \u2014 extend `food-preferences`, do not create `likes-chicken`. Group related docs with path names (area/topic). Do not store what is already recorded (code structure, git history, CLAUDE.md) or what only matters to this conversation.\n\n' +
@@ -35,7 +35,7 @@ export const writeLeaf = defineLeaf({
             { name: 'name', type: 'string', required: true, constraint: 'The path-derived document name written.' },
             { name: 'kind', type: 'string', required: true, constraint: 'Kind recorded in frontmatter.' },
             { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was written to: user or project.' },
-            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the written document.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the written document — edit this file directly for later body tweaks instead of re-running write.' },
             { name: 'created', type: 'boolean', required: true, constraint: 'true when a new document was created, false when an existing one was updated in place.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands — read it back or list the inventory.' },
         ],
@@ -97,7 +97,7 @@ export const writeLeaf = defineLeaf({
             scope,
             path,
             created,
-            follow_up: `Read it back with \`crtr memory read ${name}\`, or browse the inventory with \`crtr memory list\`.`,
+            follow_up: `Read it back with \`crtr memory read ${name}\`, edit ${path} directly for later tweaks, or browse the inventory with \`crtr memory list\`.`,
         };
     },
 });

package/dist/commands/memory.js

@@ -1,8 +1,5 @@
-// `crtr memory` subtree — the document substrate (knowledge and
-// preferences) accessed via the CLI. Four flat leaves: list, read, find, write.
-// SKELETON ONLY (task B1): the `-h` contracts here are final; the leaf handlers
-// are stubs that B2 fills in. Mirrors `skill.ts` minus the loaded-skills
-// catalog dynamicState.
+// `crtr memory` subtree — the document substrate (knowledge and preferences)
+// accessed via the CLI. Flat leaves: list, read, find, write, lint.
 import { defineBranch } from '../core/command.js';
 import { listLeaf } from './memory/list.js';
 import { readLeaf } from './memory/read.js';
@@ -15,12 +12,12 @@ export function registerMemory() {
         rootEntry: {
             concept: 'a memory document you read on demand — knowledge or a preference',
             desc: 'list, read, search, and write memory documents',
-            useWhen: 'a task matches stored knowledge or a preference — read it before improvising. `crtr memory read <name>` loads one by name; `crtr memory list` browses the inventory; `crtr memory find` searches by topic when you do not yet know the name. Names are path-derived crtr identifiers, not file paths — never cat or find the markdown off disk.',
+            useWhen: 'a task matches stored knowledge or a preference — read it before improvising. `crtr memory read <name>` loads one by name; `crtr memory list` browses the inventory; `crtr memory find` searches by topic when you do not yet know the name. Names are path-derived crtr identifiers, not file paths — to READ a doc go through these commands, never cat or find the markdown off disk. To EDIT one in place, every command emits the doc’s absolute `path` — edit that file directly.',
         },
         help: {
             name: 'memory',
             summary: 'list, read, search, and write memory documents — knowledge and preferences',
-            model: '`list` for a human inventory of what is stored — one line per document, the only surface that shows short-form. `read` (leaf) loads one document body by name, resolved project > user > builtin with leaf-name fallback; --frontmatter keeps the YAML header. `find` when you do not yet know which document applies — it ranks by relevance over name/when/why/short-form, --body to also weigh bodies, --grep for an exact regex over bodies. `write` creates or updates memory/<name>.md at a scope from frontmatter flags + a body piped on stdin. `lint` strict-parses the whole bounded corpus and fails on any invalid frontmatter — run it after authoring. A directory may carry an `INDEX.md` with the same frontmatter schema as any doc; the dir then renders as one entry at the INDEX\'s rung, and that rung is a ceiling for its whole subtree (`none` hides the dir) — when a doc mysteriously is not surfacing, check its ancestors\' INDEX rungs and its gate. Append `-h` at any leaf for its full schema, and `crtr memory write -h` for the authoring guide.',
+            model: '`list` for a human inventory of what is stored — one line per document, the only surface that shows short-form. `read` (leaf) loads one document body by name, resolved project > user > builtin with leaf-name fallback; --frontmatter keeps the YAML header. `find` when you do not yet know which document applies — it ranks by relevance over name/when/why/short-form, --body to also weigh bodies, --grep for an exact regex over bodies. `write` creates or updates memory/<name>.md at a scope from frontmatter flags + a body piped on stdin — use it for new docs and frontmatter changes; for a quick body tweak, edit the `path` every leaf emits directly. `lint` strict-parses the whole bounded corpus and fails on any invalid frontmatter — run it after authoring. A directory may carry an `INDEX.md` with the same frontmatter schema as any doc; the dir then renders as one entry at the INDEX\'s rung, and that rung is a ceiling for its whole subtree (`none` hides the dir) — when a doc mysteriously is not surfacing, check its ancestors\' INDEX rungs and its gate. Append `-h` at any leaf for its full schema, and `crtr memory write -h` for the authoring guide.',
         },
         children: [listLeaf, readLeaf, findLeaf, writeLeaf, lintLeaf],
     });

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

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

package/dist/commands/node-context.js

@@ -0,0 +1,172 @@
+// `crtr node context` — browse this node's context and reports dirs and those of
+// every node it subscribes to, in one read-only nvim file explorer.
+//
+// crtr makes a STRONG CLAIM that nvim is installed (see crouter/CLAUDE.md): the
+// file explorer + file viewer are nvim, not a hand-rolled view-contract surface.
+// We synthesize a temp dir of LABELLED NODE DIRS — `self` first, then one per
+// subscription — and place `context` / `reports` symlinks inside each label dir
+// for the node's existing on-disk dirs. We then open `nvim -R` on the temp tree
+// (read-only: this is a viewer into siblings' state, edits never write back).
+// The symlinks are torn down when nvim exits; the real node dirs are untouched.
+//
+// The /context popup (src/pi-extensions/canvas-context.ts) shells this leaf inside
+// a tmux display-popup, exactly as /view shells `crtr view pick`. Piped / non-TTY
+// it prints the resolved roster (node · path · file count) and exits 0.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, symlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { getNode, subscriptionsOf } from '../core/canvas/index.js';
+import { contextDir, nodeDir, reportsDir } from '../core/canvas/paths.js';
+/** Make a node label safe as a directory name (netrw shows it verbatim). */
+function sanitize(s) {
+    return s.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'node';
+}
+/** Shallow file count for the roster (cheap; 0 when the dir is empty/absent). */
+function countFiles(dir) {
+    try {
+        return readdirSync(dir).length;
+    }
+    catch {
+        return 0;
+    }
+}
+function nodeFiles(nodeId) {
+    return countFiles(contextDir(nodeId)) + countFiles(reportsDir(nodeId));
+}
+/** Resolve the current node + every node it subscribes to into browse roots,
+ *  keeping any node whose `context/` or `reports/` dir exists on disk. `self`
+ *  is always first and labelled `self`. */
+function resolveRoots(selfId) {
+    const roots = [];
+    const selfMeta = getNode(selfId);
+    const selfContext = contextDir(selfId);
+    const selfReports = reportsDir(selfId);
+    if (existsSync(selfContext) || existsSync(selfReports)) {
+        roots.push({
+            nodeId: selfId,
+            label: `self-${sanitize(selfMeta?.name ?? selfId.slice(0, 8))}`,
+            dir: nodeDir(selfId),
+            self: true,
+            fileCount: nodeFiles(selfId),
+            contextDir: selfContext,
+            reportsDir: selfReports,
+        });
+    }
+    for (const sub of subscriptionsOf(selfId)) {
+        const context = contextDir(sub.node_id);
+        const reports = reportsDir(sub.node_id);
+        if (!existsSync(context) && !existsSync(reports))
+            continue;
+        const meta = getNode(sub.node_id);
+        const short = sub.node_id.slice(0, 8);
+        roots.push({
+            nodeId: sub.node_id,
+            label: `${sanitize(meta?.name ?? sub.node_id)}-${short}`,
+            dir: nodeDir(sub.node_id),
+            self: false,
+            fileCount: nodeFiles(sub.node_id),
+            contextDir: context,
+            reportsDir: reports,
+        });
+    }
+    return roots;
+}
+/** Is `nvim` on PATH and runnable? */
+function nvimAvailable() {
+    const r = spawnSync('nvim', ['--version'], { stdio: 'ignore' });
+    return r.error === undefined && (r.status === 0 || r.status === null);
+}
+/** Build a temp dir of labelled node dirs. Self's label is prefixed `0-` so it
+ *  sorts first in netrw; each label dir contains `context` and `reports` symlinks
+ *  for whichever of those dirs exist on disk. */
+function buildSymlinkTree(roots) {
+    const tree = mkdtempSync(join(tmpdir(), 'crtr-context-'));
+    for (const r of roots) {
+        const name = r.self ? `0-${r.label}` : r.label;
+        const nodeRoot = join(tree, name);
+        mkdirSync(nodeRoot, { recursive: true });
+        try {
+            if (r.contextDir !== undefined && existsSync(r.contextDir)) {
+                symlinkSync(r.contextDir, join(nodeRoot, 'context'), 'dir');
+            }
+            if (r.reportsDir !== undefined && existsSync(r.reportsDir)) {
+                symlinkSync(r.reportsDir, join(nodeRoot, 'reports'), 'dir');
+            }
+        }
+        catch {
+            /* best-effort: a label collision or symlink failure just drops that node */
+        }
+    }
+    return tree;
+}
+export const nodeContextLeaf = defineLeaf({
+    name: 'context',
+    description: 'browse this node + its subscriptions’ context and reports dirs in an nvim popup',
+    whenToUse: 'you want to SEE what the nodes you subscribe to have written — open a read-only nvim file explorer over this node’s context and reports dirs and every subscribed node’s context and reports dirs at once. The /context popup shells this. Piped it prints the roster instead',
+    help: {
+        name: 'node context',
+        summary: 'open a read-only nvim file explorer over this node’s context and reports dirs and those of every node it subscribes to',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node id to root on. Defaults to $CRTR_NODE_ID (the calling node).' },
+        ],
+        output: [
+            { name: 'roots', type: 'object[]', required: true, constraint: 'Resolved browse roots: {node_id, label, dir, self, files}. Returned on the piped/non-TTY path.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'TTY: builds a temp dir of labelled node dirs, symlinking each available `context`/`reports` dir inside it, then execs `nvim -R` on the tree; the temp links are removed on exit (real dirs untouched).',
+            'Requires nvim on PATH (a crtr strong dependency). Missing nvim -> error with an install hint.',
+            'Non-TTY / piped: prints the resolved roster and exits 0; opens nothing.',
+        ],
+    },
+    run: async (input) => {
+        const selfId = input['node']?.trim() || process.env['CRTR_NODE_ID'];
+        if (selfId === undefined || selfId === '') {
+            throw new InputError({
+                error: 'no_node',
+                message: 'no current node: $CRTR_NODE_ID is unset and --node was not given',
+                field: 'node',
+                next: 'Run this from inside a canvas node (the /context popup does), or pass --node <id>.',
+            });
+        }
+        if (getNode(selfId) === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${selfId}`, field: 'node', next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const roots = resolveRoots(selfId);
+        const rosterOut = roots.map((r) => ({ node_id: r.nodeId, label: r.label, dir: r.dir, self: r.self, files: r.fileCount }));
+        // Non-TTY: print the roster and exit. Opens nothing.
+        if (!process.stdout.isTTY) {
+            return { roots: rosterOut };
+        }
+        if (!nvimAvailable()) {
+            throw new InputError({
+                error: 'nvim_missing',
+                message: 'nvim is not on PATH — `crtr node context` opens the context explorer in nvim',
+                next: 'Install Neovim (macOS: `brew install neovim`; Debian/Ubuntu: `apt install neovim`), then retry.',
+            });
+        }
+        const tree = buildSymlinkTree(roots);
+        try {
+            // `nvim -R .` opens netrw (or the user's dir handler) read-only, cwd = the
+            // symlink tree, so the explorer roots on `self` + each subscription.
+            spawnSync('nvim', ['-R', '.'], { cwd: tree, stdio: 'inherit' });
+        }
+        finally {
+            rmSync(tree, { recursive: true, force: true }); // removes symlinks only; targets untouched
+        }
+        return { roots: rosterOut };
+    },
+    render: (result) => {
+        const roots = result['roots'] ?? [];
+        if (roots.length === 0)
+            return 'No node dirs to show (no subscriptions with written context or reports, and this node’s own context/reports dirs are empty/absent).';
+        const lines = roots.map((r) => {
+            const tag = r['self'] === true ? ' (self)' : '';
+            return `  ${String(r['label'])}${tag}\t${String(r['files'])} files\t${String(r['dir'])}`;
+        });
+        return [`Context roots (${roots.length}):`, ...lines].join('\n');
+    },
+});

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

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

package/dist/commands/node-snapshot.js

@@ -0,0 +1,123 @@
+import { copyFileSync, existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { getNode } from '../core/canvas/index.js';
+import { sessionPtrPath } from '../core/canvas/paths.js';
+import { SessionManager } from '../core/runtime/broker-sdk.js';
+import { BUILTIN_SLASH_COMMANDS } from '../core/runtime/pi-vendored.js';
+function resolveSessionFile(nodeId, metaFile) {
+    if (typeof metaFile === 'string' && metaFile !== '' && existsSync(metaFile))
+        return metaFile;
+    const ptr = sessionPtrPath(nodeId);
+    if (!existsSync(ptr))
+        return null;
+    const raw = readFileSync(ptr, 'utf8').trim();
+    if (raw === '')
+        return null;
+    if (existsSync(raw))
+        return raw;
+    return null;
+}
+function emptyStats(sessionId, sessionFile) {
+    return {
+        sessionFile,
+        sessionId,
+        userMessages: 0,
+        assistantMessages: 0,
+        toolCalls: 0,
+        toolResults: 0,
+        totalMessages: 0,
+        tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+        cost: 0,
+    };
+}
+function statsFromMessages(messages, sessionId, sessionFile) {
+    const stats = emptyStats(sessionId, sessionFile);
+    stats.totalMessages = messages.length;
+    for (const message of messages) {
+        if (message.role === 'user')
+            stats.userMessages++;
+        else if (message.role === 'assistant') {
+            stats.assistantMessages++;
+            const content = Array.isArray(message.content) ? message.content : [];
+            stats.toolCalls += content.filter((c) => c !== null && typeof c === 'object' && c.type === 'toolCall').length;
+            const usage = message.usage;
+            if (usage !== undefined) {
+                stats.tokens.input += usage.input ?? 0;
+                stats.tokens.output += usage.output ?? 0;
+                stats.tokens.cacheRead += usage.cacheRead ?? 0;
+                stats.tokens.cacheWrite += usage.cacheWrite ?? 0;
+                stats.cost += usage.cost?.total ?? 0;
+            }
+        }
+        else if (message.role === 'toolResult') {
+            stats.toolResults++;
+        }
+    }
+    stats.tokens.total = stats.tokens.input + stats.tokens.output + stats.tokens.cacheRead + stats.tokens.cacheWrite;
+    return stats;
+}
+export const nodeSnapshotLeaf = defineLeaf({
+    name: 'snapshot',
+    description: 'read a dormant node session snapshot without launching its broker',
+    whenToUse: 'you need a read-only broker-compatible snapshot of a dormant node; it copies the session JSONL before parsing and never revives the node',
+    help: {
+        name: 'node snapshot',
+        summary: 'read-only dormant node snapshot in the broker welcome shape',
+        params: [{ kind: 'positional', name: 'id', type: 'string', required: true, constraint: 'Canvas node id.' }],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The node id.' },
+            { name: 'snapshot', type: 'object', required: true, constraint: 'BrokerSnapshot-compatible {messages, stats, state}.' },
+            { name: 'commands', type: 'object[]', required: true, constraint: "Builtin slash commands only: {name,description,source:'builtin'}." },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: copies the session JSONL to a temp dir, parses the copy, then deletes the temp dir. Does not launch or revive brokers.'],
+    },
+    run: async (input) => {
+        const nodeId = input['id'];
+        const node = getNode(nodeId);
+        if (node === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${nodeId}`, field: 'id', next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const sessionFile = resolveSessionFile(nodeId, node.pi_session_file);
+        if (sessionFile === null) {
+            throw new InputError({ error: 'no_session', message: `node has no readable session file: ${nodeId}`, field: 'id', next: 'Revive the node first, or choose a node that has captured pi_session_file.' });
+        }
+        const tempDir = mkdtempSync(join(tmpdir(), 'crtr-node-snapshot-'));
+        try {
+            const copy = join(tempDir, basename(sessionFile));
+            copyFileSync(sessionFile, copy);
+            const manager = SessionManager.open(copy);
+            const context = manager.buildSessionContext();
+            const messages = context.messages;
+            const sessionId = manager.getSessionId();
+            const sessionName = manager.getSessionName();
+            const snapshot = {
+                messages,
+                stats: statsFromMessages(messages, sessionId, sessionFile),
+                state: {
+                    sessionId,
+                    sessionFile,
+                    model: context.model?.modelId,
+                    isStreaming: false,
+                    thinkingLevel: context.thinkingLevel,
+                    steeringMode: 'one-at-a-time',
+                    followUpMode: 'one-at-a-time',
+                    sessionName,
+                    autoCompactionEnabled: true,
+                    pendingMessageCount: 0,
+                },
+            };
+            return {
+                node_id: nodeId,
+                snapshot,
+                commands: BUILTIN_SLASH_COMMANDS.map((c) => ({ ...c, source: 'builtin' })),
+            };
+        }
+        finally {
+            rmSync(tempDir, { recursive: true, force: true });
+        }
+    },
+});