@crouton-kit/crouter 0.3.35 → 0.3.37

package/dist/clients/web/web-cmd.js

@@ -36,11 +36,11 @@ function openBrowser(url) {
 }
 const webServeLeaf = defineLeaf({
     name: 'serve',
-    description: 'start the crouter web UI server — the shell, the source/command bridge, and a browser ⇄ broker relay',
-    whenToUse: 'you want the crouter web UI: a browser shell to watch the canvas and drive headless nodes, instead of a terminal pane. It starts ONE long-running server (default 127.0.0.1) that serves the shell SPA, the source + command bridge (POST /__crtr/source — views\' reads AND `crtr` command writes), an SSE change-invalidation lane (GET /__crtr/events), and a VERBATIM browser ⇄ broker relay on /node/<id> (the browser becomes the same protocol peer as surface attach: one controller drives, extra viewers follow read-only). If you bind a non-loopback host, pass --token so the remote-capable bridge, SSE, and relay endpoints can authorize the page. The relay NEVER starts an engine — each node must already have a running headless broker (focus or revive it first); all writes flow through `crtr` subprocesses the bridge runs. Pass --dev for Vite middleware (HMR) while iterating on the shell. The server runs until ctrl+c; the node is picked in the browser via the URL, not on the command line.',
+    description: 'start the crouter web UI server — the browser alternative to a tmux pane for watching the canvas and driving headless nodes',
+    whenToUse: 'you want the crouter web UI in a browser instead of a tmux pane — watching the canvas and driving headless nodes from a page rather than a terminal surface. Binds 127.0.0.1 by default; pass --host to bind elsewhere, in which case --token is required so the page can authorize. Pass --dev only if you are iterating on the shell itself (Vite HMR) rather than just running it. The node is picked in the browser via the URL, not on the command line; the server runs until ctrl+c.',
     help: {
         name: 'web serve',
-        summary: 'start the long-running crouter web UI server: serves the shell SPA, the POST /__crtr/source bridge, the GET /__crtr/events SSE lane, and a VERBATIM browser ⇄ node-broker relay (browser picks the node via /node/<id>)',
+        summary: 'start the crouter web UI server — the browser alternative to a tmux pane for watching the canvas and driving headless nodes',
         params: [
             {
                 kind: 'flag',
@@ -125,14 +125,14 @@ export function registerWeb() {
     return defineBranch({
         name: 'web',
         rootEntry: {
-            concept: 'the crouter web UI server — one host serving the browser shell, the source/command bridge, an SSE change lane, and a VERBATIM relay to nodes\' running brokers',
+            concept: 'the crouter web UI server — the browser alternative to a tmux pane for watching the canvas and driving headless nodes',
             desc: 'serve the crouter web UI for the canvas and headless nodes',
-            useWhen: 'you want the crouter web UI in a browser instead of a tmux pane: watch the canvas and drive headless nodes. It runs one long-lived server that serves the shell SPA, runs view sources and crtr command writes over POST /__crtr/source, streams canvas-change invalidations over GET /__crtr/events, and relays a browser connection VERBATIM to a node\'s already-running broker on /node/<id>. The node is selected in the browser via the URL; if the server is bound off-loopback, the page must carry a token so the relay and bridge can authorize.',
+            useWhen: 'you want the crouter web UI in a browser instead of a tmux pane: watch the canvas and drive headless nodes from a page. Binds 127.0.0.1 by default; a non-loopback bind requires a token so the page can authorize. The node is selected in the browser via the URL, not on the command line.',
         },
         help: {
             name: 'web',
-            summary: 'serve the crouter web UI: the shell SPA, the source/command bridge, the SSE change lane, and a VERBATIM relay to headless nodes\' brokers',
-            model: 'The branch is a long-running browser surface. `serve` starts the unified server on the bound host and port, serves the shell SPA, exposes the source/command bridge and SSE change lane, and relays browser frames to a node\'s running broker. The node is chosen in the browser via the URL; the server itself only hosts the surface and never spawns an engine.',
+            summary: 'serve the crouter web UI — the browser alternative to a tmux pane for the canvas and headless nodes',
+            model: 'The branch is a long-running browser surface, an alternative to a tmux pane. `serve` binds a host and port (loopback by default; --token required off-loopback) and runs until interrupted. The node is chosen in the browser via the URL, not on the command line; the server itself only hosts the surface and never spawns an engine.',
         },
         children: [webServeLeaf],
     });

package/dist/commands/__tests__/human.test.js

@@ -100,7 +100,7 @@ describe('human show: params', () => {
     });
 });
 // ---------------------------------------------------------------------------
-// human ask — --context-file (context-file kind, key=deckFile) + --wait bool
+// human ask — --context-file (context-file kind, key=deckFile)
 //
 // NOTE: The argv parser hardcodes the CLI token as `--context-file` regardless
 // of the param's `name` field. The `name` field ("deckFile") becomes the key
@@ -111,7 +111,6 @@ describe('human show: params', () => {
 describe('human ask: params', () => {
     const params = [
         { kind: 'context-file', name: 'deckFile', required: true, constraint: 'Humanloop deck JSON.' },
-        { kind: 'flag', name: 'wait', type: 'bool', required: false, constraint: 'Presence-only.' },
     ];
     test('--context-file parses JSON file and yields input.deckFile', async () => {
         const deck = { interactions: [{ id: 'q', title: 'Go?', options: [{ id: 'yes', label: 'Yes' }] }] };
@@ -132,18 +131,6 @@ describe('human ask: params', () => {
         writeFileSync(p, 'not json at all');
         await assert.rejects(() => parseArgv(params, ['--context-file', p]), (err) => { assert.match(err.message, /not valid JSON/); return true; });
     });
-    test('--wait absent → false', async () => {
-        const deck = { interactions: [] };
-        const path = tmpJson(deck);
-        const result = await parseArgv(params, ['--context-file', path]);
-        assert.equal(result['wait'], false);
-    });
-    test('--wait present → true', async () => {
-        const deck = { interactions: [] };
-        const path = tmpJson(deck);
-        const result = await parseArgv(params, ['--context-file', path, '--wait']);
-        assert.equal(result['wait'], true);
-    });
 });
 // ---------------------------------------------------------------------------
 // human ask — shorthand question + strict --context-file deck
@@ -159,7 +146,6 @@ describe('human ask: shorthand', () => {
     test('parses a positional question into input.question', async () => {
         const result = await parseArgv(humanAsk.help.params ?? [], ['Should we ship today?']);
         assert.equal(result['question'], 'Should we ship today?');
-        assert.equal(result['wait'], false);
     });
     test('parses --context-file into input.deck while keeping the strict deck path', async () => {
         const deck = {

package/dist/commands/attention.js

@@ -1,9 +1,11 @@
 // `crtr canvas attention` — aggregate pending human asks across the canvas.
 //
 // Pending asks are stored per-cwd by humanloop. This subtree surfaces two
-// views:
-//   count  — a single integer (stdout.count is parsed by nav chrome)
+// public views:
+//   count  — a single integer (stdout.count is machine-parseable)
 //   list   — itemised entries with cwd, node id, and per-cwd ask count
+// `map` (hidden) is the batched per-node form the attach viewer's nav chrome
+// polls; it is not an agent-facing decision.
 //
 // All three scope modes share the same underlying helpers in attention.ts:
 //   --node <id>   → countAsks(id)             (one cwd)
@@ -21,7 +23,7 @@ import { countAsks, pendingAsksForView, asksAcrossCanvas, asksForNodes, } from '
 const attentionCount = defineLeaf({
     name: 'count',
     description: 'total pending ask count (machine-parseable stdout.count)',
-    whenToUse: 'getting a single pending-ask count for a script or nav chrome to read; scope it to a node or a sub-DAG, or default to canvas-wide',
+    whenToUse: 'a lightweight summary when you just need the number, not which cwds are blocked — scope it to a node or a sub-DAG, or default to canvas-wide. Use `list` when you need to act on where to go answer.',
     help: {
         name: 'canvas attention count',
         // stdout.count is parsed directly by the nav chrome — keep the contract.
@@ -93,7 +95,7 @@ const attentionCount = defineLeaf({
 const attentionList = defineLeaf({
     name: 'list',
     description: 'itemised list of cwds with pending asks',
-    whenToUse: 'finding which agents are blocked waiting on a human — an itemised list of the cwds with pending asks, oldest first, so you know where to go answer. Scope it to a sub-DAG or list canvas-wide. Use `canvas attention count` instead when a script just needs the number, or `canvas attention map` for per-node counts to label a UI',
+    whenToUse: 'finding which agents are blocked waiting on a human — an itemised list of the cwds with pending asks, oldest first, so you know where to go answer. Scope it to a sub-DAG or list canvas-wide. Use `canvas attention count` instead when you just need the number.',
     help: {
         name: 'canvas attention list',
         summary: 'list nodes with pending human asks, grouped by cwd, oldest first',
@@ -145,6 +147,7 @@ const attentionMap = defineLeaf({
     name: 'map',
     description: 'per-node ask counts for a visible set, batched in one pass',
     whenToUse: 'labelling every node in a UI with its pending-ask count in one batched pass — the form nav chrome polls (one process, one JSON blob) instead of N count shell-outs',
+    tier: 'hidden',
     help: {
         name: 'canvas attention map',
         summary: 'per-node pending-ask counts for a visible set of nodes in ONE pass — the batched form the nav chrome polls (one process, one JSON blob) instead of N count shell-outs',
@@ -211,11 +214,11 @@ const attentionMap = defineLeaf({
 export const attentionBranch = defineBranch({
     name: 'attention',
     description: 'count/list pending human asks across the graph',
-    whenToUse: 'checking whether any agent on the canvas is blocked waiting on a human, and where: count the pending asks, list the cwds that have them, or map per-node counts. Scope it to a node or a sub-DAG, or go canvas-wide. Use `canvas dashboard` instead for the graph SHAPE, or `node inspect list` for a plain node roster',
+    whenToUse: 'checking whether any agent on the canvas is blocked waiting on a human, and where: count the pending asks or list the cwds that have them. Scope it to a node or a sub-DAG, or go canvas-wide. Use `canvas dashboard` instead for the graph SHAPE, or `node inspect list` for a plain node roster',
     help: {
         name: 'canvas attention',
         summary: 'aggregate pending human asks across the canvas',
-        model: 'Human asks are stored per-cwd by humanloop. `count` returns a single integer (stdout.count is parsed by nav chrome); `list` returns itemised entries. Scope with --node (one node) or --view (sub-DAG) — default is canvas-wide.',
+        model: '`count` returns a single integer (stdout.count is machine-parseable); `list` returns itemised entries — the cwds with pending asks, oldest first. Scope with --node (one node) or --view (sub-DAG) — default is canvas-wide.',
     },
     children: [attentionCount, attentionList, attentionMap],
 });

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

@@ -1,7 +1,7 @@
 import { defineLeaf } from '../../core/command.js';
 import { usage } from '../../core/errors.js';
 import { buildCorpus, } from '../../core/canvas/index.js';
-const TYPES = ['report', 'doc', 'roadmap', 'meta'];
+const TYPES = ['report', 'doc', 'roadmap', 'meta', 'inbox'];
 const NODE_KINDS = ['advisor', 'developer', 'spec', 'design', 'review', 'explore', 'plan', 'general'];
 const STATUSES = ['active', 'idle', 'done', 'dead', 'canceled'];
 const SORTS = ['relevance', 'recency', 'oldest'];
@@ -86,7 +86,7 @@ export const searchLeaf = defineLeaf({
             { kind: 'flag', name: 'all-cwds', type: 'bool', required: false, constraint: 'Search every cwd on the canvas. Mutually exclusive with --cwd.' },
             { kind: 'flag', name: 'under', type: 'string', required: false, constraint: 'Restrict to a node and its subscription descendants (one initiative / sub-DAG).' },
             { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Restrict to specific node ids. Comma-separated for several.' },
-            { kind: 'flag', name: 'type', type: 'string', required: false, constraint: `Corpus to search; comma-separated for several. One of: ${TYPES.join(', ')}. report = push history; doc = context artifacts; roadmap = roadmap.md specifically; meta = node name/description/kind. Default: all.` },
+            { kind: 'flag', name: 'type', type: 'string', required: false, constraint: `Corpus to search; comma-separated for several. One of: ${TYPES.join(', ')}. report = push history; doc = context artifacts; roadmap = roadmap.md specifically; meta = node name/description/kind; inbox = raw inbox.jsonl history, cursor-independent and including full un-clipped direct-message bodies (diagnostic, not curated work). Default: report, doc, roadmap, meta — inbox is opt-in only, pass --type inbox explicitly.` },
             { kind: 'flag', name: 'report-kind', type: 'enum', choices: ['final', 'update'], required: false, constraint: 'Narrow reports to outcome summaries (final) or progress (update). Implies --type report.' },
             { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: `Node kind; comma-separated for several. One of: ${NODE_KINDS.join(', ')}.` },
             { kind: 'flag', name: 'status', type: 'string', required: false, constraint: `Node lifecycle status; comma-separated for several. One of: ${STATUSES.join(', ')} (e.g. done = completed work only).` },

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

@@ -2,7 +2,7 @@ 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'];
+const TYPES = ['report', 'doc', 'roadmap', 'inbox'];
 export const showLeaf = defineLeaf({
     name: 'show',
     description: 'enumerate one node\'s artifacts as refs',
@@ -12,12 +12,12 @@ export const showLeaf = defineLeaf({
         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.' },
-            { kind: 'flag', name: 'type', type: 'enum', choices: [...TYPES], required: false, constraint: 'Narrow to one corpus: report | doc | roadmap. Default: all.' },
+            { kind: 'flag', name: 'type', type: 'enum', choices: [...TYPES], required: false, constraint: 'Narrow to one corpus: report | doc | roadmap | inbox. Default: report, doc, roadmap (inbox is opt-in only — the node\'s raw inbox.jsonl history, cursor-independent and including full un-clipped direct-message bodies; a diagnostic surface, not curated past work).' },
             { kind: 'flag', name: 'sort', type: 'enum', choices: ['recency', 'oldest'], required: false, constraint: 'Order by artifact timestamp. Default recency.' },
         ],
         output: [
             { name: 'node', type: 'string', required: true, constraint: 'Node name + id.' },
-            { name: 'artifacts', type: 'object[]', required: true, constraint: 'Each: {ref, source, ts, detail}. source = report:<kind> | doc | roadmap. detail = report title / doc heading + size. ref passes verbatim to `canvas history read`.' },
+            { name: 'artifacts', type: 'object[]', required: true, constraint: 'Each: {ref, source, ts, detail}. source = report:<kind> | doc | roadmap | inbox. detail = report title / doc heading + size (inbox: `[kind] label`, no size). ref passes verbatim to `canvas history read`.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
         ],
         outputKind: 'object',

package/dist/commands/canvas-history.js

@@ -23,7 +23,7 @@ export const historyBranch = defineBranch({
     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. To reopen a node you found, use `canvas revive`; for its place in the graph, `node inspect show`.',
+        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`.',
         dynamicState: corpusBlock,
     },
     children: [searchLeaf, readLeaf, showLeaf],

package/dist/commands/canvas-issue.js

@@ -66,6 +66,7 @@ export const issueNewLeaf = defineLeaf({
     name: 'new',
     description: 'capture a todo/idea/bug note into a GitHub issue (or a .todos/ markdown note)',
     whenToUse: 'the alt+c \u2192 i chord runs this inside a tmux popup; rarely run by hand',
+    tier: 'hidden',
     help: {
         name: 'canvas issue new',
         summary: 'Capture a free-text note as a GitHub issue labeled with its type (idea|bug). Reads the note from the popup TTY, auto-generates the title via a headless pi call, and files it with `gh issue create` when the cwd is a GitHub repo, else writes `<git-root>/.todos/<slug>.md`. Bound to the alt+c \u2192 i prefix chord.',

package/dist/commands/canvas-snapshot.js

@@ -5,6 +5,7 @@ export const canvasSnapshotLeaf = defineLeaf({
     name: 'snapshot',
     description: 'emit the browser canvas roster as structured data',
     whenToUse: 'you need a machine-readable roster of every canvas node for a browser or local tool; use dashboard for the human-readable tree',
+    tier: 'hidden',
     help: {
         name: 'canvas snapshot',
         summary: 'machine-readable snapshot of the whole canvas roster',

package/dist/commands/canvas.js

@@ -1,20 +1,18 @@
 // `crtr canvas` — observe and supervise the whole graph.
 //
-// Where `node` operates on one node and `push`/`feed` are a node's own spine
-// I/O, `canvas` is the bird's-eye / supervisor surface over the entire canvas:
+// 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`), bring a node back (`revive`), and manage the supervisor
-// process (`daemon`). It assembles leaves/branches the sibling command files
-// own, so each piece declares its own help one level down.
+// (`attention`), and bring a node back (`revive`). 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';
 import { dashboardLeaf } from './dashboard.js';
 import { canvasSnapshotLeaf } from './canvas-snapshot.js';
 import { browseLeaf } from './canvas-browse.js';
 import { reviveLeaf } from './revive.js';
 import { attentionBranch } from './attention.js';
-import { daemonBranch } from './daemon.js';
 import { chordLeaf } from './chord.js';
-import { tmuxSpreadLeaf } from './canvas-tmux-spread.js';
 import { canvasPruneLeaf } from './canvas-prune.js';
 import { canvasRebuildIndexLeaf } from './canvas-rebuild-index.js';
 import { historyBranch } from './canvas-history.js';
@@ -23,6 +21,7 @@ export const issueBranch = defineBranch({
     name: 'issue',
     description: 'capture a quick todo/idea/bug into a GitHub issue (or a .todos/ note)',
     whenToUse: 'the alt+c \u2192 i chord uses this; capture a passing thought without leaving your pane',
+    tier: 'hidden',
     help: {
         name: 'canvas issue',
         summary: 'capture a quick todo/idea/bug into a GitHub issue',
@@ -34,15 +33,15 @@ 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, supervise the daemon',
+            concept: 'the whole agent graph at a glance — render it, see who is blocked, revive a node',
             desc: 'bird\'s-eye view and supervision of the entire canvas',
-            useWhen: 'surveying the full graph, finding blocked agents, or managing revival/the daemon',
+            useWhen: 'surveying the full graph, finding blocked agents, or reviving a node',
         },
         help: {
             name: 'canvas',
             summary: 'observe and supervise the whole agent graph',
-            model: 'Canvas-wide operations, distinct from per-node work (`node`) and a node\'s own spine I/O (`push`/`feed`). `dashboard` renders the subscription forest as a tree; `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; `daemon` manages the thin crtrd supervisor that auto-revives nodes on window exit; `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` 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.',
         },
-        children: [dashboardLeaf, canvasSnapshotLeaf, browseLeaf, attentionBranch, reviveLeaf, historyBranch, daemonBranch, chordLeaf, tmuxSpreadLeaf, issueBranch, canvasPruneLeaf, canvasRebuildIndexLeaf],
+        children: [dashboardLeaf, canvasSnapshotLeaf, browseLeaf, attentionBranch, reviveLeaf, historyBranch, chordLeaf, issueBranch, canvasPruneLeaf, canvasRebuildIndexLeaf],
     });
 }

package/dist/commands/chord.js

@@ -154,6 +154,7 @@ export const chordLeaf = defineLeaf({
     name: 'chord',
     description: 'tmux prefix-menu dispatcher (bound by alt+c; not run by hand)',
     whenToUse: 'never directly — the alt+c menu routes node-relative actions through it',
+    tier: 'hidden',
     help: {
         name: 'canvas chord',
         summary: 'tmux prefix-menu dispatcher — resolve the node in --pane, interpolate --run against it, and exec `crtr <argv>`. Bound by the alt+c menu; not meant to be run by hand.',

package/dist/commands/human/prompts.js

@@ -40,7 +40,6 @@ export const humanAsk = defineLeaf({
         params: [
             { kind: 'positional', name: 'question', type: 'string', required: false, constraint: 'Bare-question shorthand for a simple open-text ask. Mutually exclusive with `--context-file`.' },
             { kind: 'context-file', name: 'deck', required: false, constraint: 'Strict complex-ask deck JSON. Use this when you need multiple interactions, options, or other deck structure. Mutually exclusive with the question shorthand.', shape: DECK_SCHEMA_HINT },
-            { kind: 'flag', name: 'wait', type: 'bool', required: false, constraint: 'Accepted for symmetry with the job contract; the kickoff never blocks.' },
         ],
         output: [
             { name: 'job_id', type: 'string', required: true, constraint: 'Node id of this human interaction. Its answer is pushed to your inbox when the human responds.' },

package/dist/commands/human/queue.js

@@ -520,6 +520,7 @@ export const humanResolve = defineLeaf({
     name: 'resolve',
     description: 'resolve one humanloop deck from stdin answers',
     whenToUse: 'a browser or local tool is submitting answers for a pending human interaction; this writes through the crouter/humanloop finalize path',
+    tier: 'hidden',
     help: {
         name: 'human resolve',
         summary: 'write deck answers atomically and deliver them back to the asking node',

package/dist/commands/node-snapshot.js

@@ -63,6 +63,7 @@ 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',
+    tier: 'hidden',
     help: {
         name: 'node inspect snapshot',
         summary: 'read-only dormant node snapshot in the broker welcome shape',

package/dist/commands/node.js

@@ -400,15 +400,15 @@ const nodeShow = defineLeaf({
     },
 });
 // ---------------------------------------------------------------------------
-// node inspect — read the graph (list, show, snapshot, context)
+// node inspect — read the graph (list, show, context)
 // ---------------------------------------------------------------------------
 const nodeInspect = defineBranch({
     name: 'inspect',
-    description: 'read the graph (list, show, snapshot, context)',
-    whenToUse: 'reading the graph: enumerate nodes on the canvas (`list`), inspect one and its spine neighbors (`show`), or pull a dormant session snapshot with `node inspect snapshot` / browse on-disk context dirs with `node inspect context` while reading a node. Use `canvas dashboard` instead to render the tree SHAPE, or `canvas attention` to find which nodes are blocked on a human',
+    description: 'read the graph (list, show, context)',
+    whenToUse: 'reading the graph: enumerate nodes on the canvas (`list`), inspect one and its spine neighbors (`show`), or browse on-disk context dirs with `node inspect context` while reading a node. Use `canvas dashboard` instead to render the tree SHAPE, or `canvas attention` to find which nodes are blocked on a human',
     help: {
         name: 'node inspect',
-        summary: 'read the canvas graph — enumerate nodes, inspect one, or pull snapshot/context views for a node (including dormant session snapshots and on-disk context dirs)',
+        summary: 'read the canvas graph — enumerate nodes, inspect one, or browse on-disk context dirs for a node',
     },
     children: [nodeList, nodeShow, nodeSnapshotLeaf, nodeContextLeaf],
 });
@@ -962,10 +962,10 @@ function resolveMsgTarget(input) {
 const nodeMsg = defineLeaf({
     name: 'msg',
     description: 'message any node now, or arm a trigger that messages/revives it later',
-    whenToUse: 'you want to address a specific node directly — steer it mid-flight, hand it a correction, ping it, pass it new information, or schedule any of that for later — regardless of subscriptions. Default delivers immediately and revives a dormant target; `--at`/`--every` arm a clock trigger instead of acting now; `--fresh` revives with no inbox entry; `--self --until` puts a deadline backstop on your current inbox-wait; `--when` arms a daemon-evaluated predicate for an external condition (CI, a deploy) you cannot otherwise be pushed for. Use `node subscribe` instead to wire ONGOING push delivery rather than a one-off, `push` to report UP your own spine, and `node new` to schedule the BIRTH of a node rather than message an existing one',
+    whenToUse: 'you want to address a specific node directly — steer it mid-flight, hand it a correction, ping it, pass it new information, or schedule any of that for later — regardless of subscriptions. Default delivers immediately and revives a dormant target; `--at`/`--every` arm a clock trigger instead of acting now; `--fresh` revives with no inbox entry; `--self --until` binds a deadline that changes your task policy if no push arrives by then; `--when` arms a daemon-evaluated predicate for an external condition (CI, a deploy) you cannot otherwise be pushed for. Use `node subscribe` instead to wire ONGOING push delivery rather than a one-off, `push` to report UP your own spine, and `node new` to schedule the BIRTH of a node rather than message an existing one',
     help: {
         name: 'node msg',
-        summary: 'message a node now, or arm a trigger (clock or predicate) that messages/revives it later. No trigger flag → immediate inbox delivery (or immediate fresh revive with --fresh). --at/--every → clock trigger. --self --until → self-only deadline backstop on the current inbox-wait. --when → daemon-evaluated predicate, fires once on exit 0',
+        summary: 'message a node now, or arm a trigger (clock or predicate) that messages/revives it later. No trigger flag → immediate inbox delivery (or immediate fresh revive with --fresh). --at/--every → clock trigger. --self --until → self-only deadline: fires whichever comes first, an inbox message or this time, and that outcome is what should change your next action. --when → daemon-evaluated predicate, fires once on exit 0',
         params: [
             { kind: 'stdin', name: 'body', required: false, constraint: 'Message body. Positional or stdin. Required for a plain or clock-triggered message and for --until. Forbidden with --fresh. Optional with --when — if omitted, the predicate\'s captured stdout becomes the body when it fires.' },
             { kind: 'flag', name: 'to', type: 'string', required: false, constraint: 'Target an existing node by id. Exactly one of --to/--self is required.' },
@@ -975,7 +975,7 @@ const nodeMsg = defineLeaf({
             { kind: 'flag', name: 'at', type: 'string', required: false, constraint: 'Arm a one-shot clock trigger at this future time instead of acting now — a duration ("5m","1h30m"), a zoned ISO ("2026-06-07T09:00:00Z"), or a bare ISO ("2026-06-07T09:00", host-local or in --tz). Required unless --every is given (the cadence then sets the first fire). Mutually exclusive with --when.' },
             { kind: 'flag', name: 'every', type: 'string', required: false, constraint: 'Arm a recurring clock trigger on this cadence — a duration ("6h","30m") or a 5-field cron / @alias ("0 9 * * *","@daily"). Combine with --at to anchor the first fire, then recur normally. Min cadence 60s. With --when, this instead sets the PREDICATE EVALUATION cadence (required), not a repeating action.' },
             { kind: 'flag', name: 'when', type: 'string', required: false, constraint: 'Arm a daemon-evaluated bash predicate instead of a clock trigger: exit 0 fires the message once, non-zero leaves it armed for the next evaluation. Requires --every (eval cadence) and --timeout (wall-clock bound). Mutually exclusive with --at, --fresh, and --until.' },
-            { kind: 'flag', name: 'until', type: 'string', required: false, constraint: 'Self-only: bind a deadline to your current dormancy — you wake on the first inbox message, or at this time if none arrives (whichever fires first cancels the other). One-shot, urgent tier, ≤ 1 per node (a new --until replaces any prior). Mutually exclusive with --at, --every, --when, --fresh, --tier, and --timeout. Requires --self and a body.' },
+            { kind: 'flag', name: 'until', type: 'string', required: false, constraint: 'Self-only: bind a deadline that decides your next action — you wake on the first inbox message, or at this time if none arrives (whichever fires first cancels the other), and the body is the policy to follow in the no-message case. One-shot, urgent tier, ≤ 1 per node (a new --until replaces any prior). Mutually exclusive with --at, --every, --when, --fresh, --tier, and --timeout. Requires --self and a body.' },
             { kind: 'flag', name: 'timeout', type: 'string', required: false, constraint: 'Wall-clock bound for a --when predicate — a duration or absolute time after which the trigger is consumed and the owner gets one urgent notice. Required with --when; rejected otherwise.' },
             { kind: 'flag', name: 'tz', type: 'string', required: false, constraint: 'IANA zone for a calendar --every, a bare-ISO --at, or a bare-ISO --until (default: host-local). Valid only alongside --at/--every/--until; rejected with --when, and rejected when acting immediately (no trigger flags) since none of those have anything to parse it against.' },
         ],
@@ -1225,8 +1225,9 @@ const nodeMsg = defineLeaf({
         }
         const tier = (hasTier ? tierRaw : 'normal');
         const from = process.env['CRTR_NODE_ID'] ?? 'human';
-        // A long body clips in the receiver's digest; appendInbox mints a short `id`
-        // for it so the receiver can read the full text back via `feed message <id>`.
+        // A body over the preview bound spills to a ref file; appendInbox clips the
+        // inline preview and the receiver dereferences the ref for the full text,
+        // same as any other report.
         appendInbox(targetId, { from, tier, kind: 'message', label: body.split('\n')[0].slice(0, 120), data: { body: body } });
         // A direct message wakes any node: if the target has no live window
         // (done/dead/idle-released), revive it so its inbox-watcher delivers this.
@@ -1510,7 +1511,7 @@ const nodeYield = defineLeaf({
 const nodeTriggersList = defineLeaf({
     name: 'list',
     description: 'list pending triggers for a scope (default self)',
-    whenToUse: 'before re-arming or finishing, to see what you already have armed and reap stale ones. Defaults to your own triggers, with a --node or --canvas scope for anything wider',
+    whenToUse: 'seeing what triggers (clock or predicate) are currently armed — your own, another node\'s, or the whole canvas. Defaults to your own triggers, with a --node or --canvas scope for anything wider',
     help: {
         name: 'node triggers list',
         summary: 'list pending triggers (clock and predicate, incl. deferred spawns) for a scope — id, owner, target, action/mode, type, next fire/eval, cadence, timeout, label, predicate diagnostics. Fired one-shots are gone; a recurrence shows its NEXT fire/eval, not past slots',
@@ -1602,7 +1603,7 @@ const nodeTriggersList = defineLeaf({
 const nodeTriggersCancel = defineLeaf({
     name: 'cancel',
     description: 'cancel a pending trigger by id (idempotent)',
-    whenToUse: 'a wait you no longer need — a poll whose goal is met, a deferred spawn you reconsidered, a deadline you are replacing. Idempotent: canceling an already-fired or already-canceled id is a no-op. Closing/reaping a node already reaps its own triggers and the detached ones it armed; reach for this to drop a single trigger, or to reap a detached spawn/cron a finished or crashed node left running',
+    whenToUse: 'a wait you no longer need — a poll whose goal is met, a deferred spawn you reconsidered, a deadline you are replacing. Idempotent: canceling an already-fired or already-canceled id is a no-op.',
     help: {
         name: 'node triggers cancel',
         summary: 'cancel a pending trigger by id — it never fires/evaluates again and leaves the list. Idempotent (canceling an already-gone id is a no-op, not an error)',

package/dist/commands/push.d.ts

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