@crouton-kit/crouter 0.3.33 → 0.3.34

package/dist/clients/attach/input-controller.js

@@ -1,4 +1,4 @@
-// input-controller.ts — the input half of `crtr attach` (T6).
+// input-controller.ts — the input half of `crtr surface attach` (T6).
 //
 // Owns the editor's behavior: turns keystrokes + submits into `ClientToBroker`
 // command frames (sent via `hooks.onCommand`), reads pasted clipboard images to

package/dist/clients/attach/pickers.js

@@ -1,4 +1,4 @@
-// pickers.ts — native interactive pickers for `crtr attach`, built against the
+// pickers.ts — native interactive pickers for `crtr surface attach`, built against the
 // operator-view wire contract (broker read-op `data` frames). Each builder turns
 // a serialized picker payload into the REAL pi `*SelectorComponent`, wired so a
 // selection dispatches the SAME command frame the text-arg slash path sends and

package/dist/clients/attach/slash-commands.js

@@ -1,4 +1,4 @@
-// slash-commands.ts — builtin slash-command parse + dispatch for `crtr attach` (C6).
+// slash-commands.ts — builtin slash-command parse + dispatch for `crtr surface attach` (C6).
 //
 // Builtin slash commands are NOT engine-interpreted: `session.prompt('/model')`
 // ships "/model" to the LLM as literal text. So the viewer recognizes the 21
@@ -329,8 +329,7 @@ function resumeNode(ctx) {
     popup(cmd);
     return true;
 }
-/** `/view [name]`. Bare opens the picker (`crtr view pick`);
- *  `/view <name>` opens that view directly (`crtr view run <name>`). Self-contained
+/** `/view [name]`. Bare opens the picker; with a name it opens that view directly. Self-contained
  *  popup — no node-focus, no return-pane. */
 function openView(arg, ctx) {
     if (process.env['TMUX'] === undefined) {
@@ -338,11 +337,11 @@ function openView(arg, ctx) {
         return true;
     }
     const name = arg.trim();
-    const cmd = name === '' ? 'crtr view pick' : `crtr view run ${shellQuote(name)}`;
+    const cmd = name === '' ? 'crtr surface view pick' : `crtr surface view run ${shellQuote(name)}`;
     popup(cmd);
     return true;
 }
-/** `/context`. Opens `crtr node context` as a popup — a
+/** `/context`. Opens `crtr node inspect context` as a popup — a
  *  read-only nvim explorer over this node's + its subscriptions' context dirs.
  *  Self-contained popup — no node-focus, no return-pane. */
 function openContext(ctx) {
@@ -357,7 +356,7 @@ function openContext(ctx) {
         ctx.notify('/context: no node to root on (viewer has no node id)');
         return true;
     }
-    popup(`crtr node context --node ${shellQuote(nodeId)}`);
+    popup(`crtr node inspect context --node ${shellQuote(nodeId)}`);
     return true;
 }
 /** Open `cmd` as a fire-and-forget tmux display-popup (same geometry as the canvas

package/dist/clients/attach/titled-editor.d.ts

@@ -43,9 +43,13 @@ export declare class TitledEditor extends CustomEditor {
     /** Pre-styled context string painted into the RIGHT of the top border (cwd /
      *  branch / git status). Already colorized by the caller; empty → omitted. */
     info: string;
+    /** Mode badge painted into the bottom-right of the outline. Empty → omitted. */
+    mode: string;
     /** Paint the chip solid so the name reads as a label sitting on the border
      *  rule. Defaults to the reverse-video chip; attach-cmd swaps in a
      *  thinking-colored background (bold white text) on each state update. */
     titleStyle: (s: string) => string;
+    /** Mode badge colorizer, matched to the current mode type. */
+    modeStyle: (s: string) => string;
     render(width: number): string[];
 }

package/dist/clients/attach/titled-editor.js

@@ -1,4 +1,4 @@
-// titled-editor.ts — the `crtr attach` input editor with two bits of chrome pi's
+// titled-editor.ts — the `crtr surface attach` input editor with two bits of chrome pi's
 // stock editor doesn't give us:
 //   1. the session name painted INTO the top border as a solid-background chip,
 //      so it stays pinned to the editor instead of scrolling off as a free badge;
@@ -103,10 +103,14 @@ export class TitledEditor extends CustomEditor {
     /** Pre-styled context string painted into the RIGHT of the top border (cwd /
      *  branch / git status). Already colorized by the caller; empty → omitted. */
     info = '';
+    /** Mode badge painted into the bottom-right of the outline. Empty → omitted. */
+    mode = '';
     /** Paint the chip solid so the name reads as a label sitting on the border
      *  rule. Defaults to the reverse-video chip; attach-cmd swaps in a
      *  thinking-colored background (bold white text) on each state update. */
     titleStyle = defaultTitleStyle;
+    /** Mode badge colorizer, matched to the current mode type. */
+    modeStyle = defaultTitleStyle;
     render(width) {
         const lines = super.render(width);
         if ((this.title || this.info) && lines.length > 0) {
@@ -114,6 +118,14 @@ export class TitledEditor extends CustomEditor {
             // border color.
             lines[0] = composeTopBorder(width, this.title, this.info, this.titleStyle, (s) => this.borderColor(s));
         }
+        if (this.mode && lines.length > 0) {
+            const badge = this.modeStyle(this.mode);
+            const badgeWidth = visibleWidth(badge);
+            if (badgeWidth + 2 < width) {
+                const last = lines.length - 1;
+                lines[last] = truncateToWidth(lines[last], width - badgeWidth, '') + badge;
+            }
+        }
         return lines;
     }
 }

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

@@ -1,4 +1,4 @@
-// view-socket.ts — the socket client half of `crtr attach` (Phase 4, T7).
+// view-socket.ts — the socket client half of `crtr surface attach` (Phase 4, T7).
 //
 // The §0 ONE-WRITER INVARIANT lives in this directory: a viewer has ONLY a
 // socket. ViewSocketClient connects to a node's ALREADY-running headless broker

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

@@ -7,26 +7,26 @@ test('coalesces the idempotent crtr --json reads the SSE burst fans out', () =>
     // duplicate subprocesses because shouldCache only matched `canvas snapshot`.
     assert.equal(isCoalescableSourceRequest(exec(['canvas', 'snapshot', '--json'])), true);
     assert.equal(isCoalescableSourceRequest(exec(['human', 'list', '--json'])), true);
-    assert.equal(isCoalescableSourceRequest(exec(['view', 'list', '--json'])), true);
-    assert.equal(isCoalescableSourceRequest(exec(['node', 'snapshot', 'abc-123', '--json'])), true);
+    assert.equal(isCoalescableSourceRequest(exec(['surface', 'view', 'list', '--json'])), true);
+    assert.equal(isCoalescableSourceRequest(exec(['node', 'inspect', 'snapshot', 'abc-123', '--json'])), true);
     assert.equal(isCoalescableSourceRequest(exec(['node', 'inspect', 'show', 'abc-123', '--json'])), true);
 });
 test('does NOT coalesce writes, side-effecting, or target-mismatched requests', () => {
     // Writes — must never be cached (would drop a mutation).
     assert.equal(isCoalescableSourceRequest(exec(['node', 'new', '--json'], { stdin: 'prompt' })), false);
     assert.equal(isCoalescableSourceRequest(exec(['canvas', 'revive', 'abc', '--json'])), false);
-    assert.equal(isCoalescableSourceRequest(exec(['node', 'msg', 'abc', '--json'], { stdin: 'hi' })), false);
+    assert.equal(isCoalescableSourceRequest(exec(['node', 'spine', 'msg', 'abc', '--json'], { stdin: 'hi' })), false);
     // human resolve / deck are on-demand writes, not the cached list read.
     assert.equal(isCoalescableSourceRequest(exec(['human', 'resolve', 'q1', '--json'])), false);
     // Any stdin or cwd override disqualifies even an allowlisted command shape.
     assert.equal(isCoalescableSourceRequest(exec(['canvas', 'snapshot', '--json'], { stdin: 'x' })), false);
-    assert.equal(isCoalescableSourceRequest(exec(['view', 'list', '--json'], { cwd: '/elsewhere' })), false);
+    assert.equal(isCoalescableSourceRequest(exec(['surface', 'view', 'list', '--json'], { cwd: '/elsewhere' })), false);
     // Non-exec requests are never cacheable.
     assert.equal(isCoalescableSourceRequest({ kind: 'file', path: '/tmp/x' }), false);
     assert.equal(isCoalescableSourceRequest({ kind: 'http', method: 'GET', url: 'http://x' }), false);
     // Non-crtr bin, missing --json, or wrong arity must not match.
     assert.equal(isCoalescableSourceRequest(exec(['human', 'list', '--json'], { bin: 'sh' })), false);
     assert.equal(isCoalescableSourceRequest(exec(['human', 'list'])), false);
-    assert.equal(isCoalescableSourceRequest(exec(['node', 'snapshot', '--json'])), false);
+    assert.equal(isCoalescableSourceRequest(exec(['node', 'inspect', 'snapshot', '--json'])), false);
     assert.equal(isCoalescableSourceRequest(exec(['node', 'inspect', 'show', '--json'])), false);
 });

package/dist/clients/web/server.js

@@ -1,4 +1,4 @@
-// server.ts — the unified `crtr web serve` host: the crouter web UI server.
+// server.ts — the unified surface web server: the crouter web UI server.
 //
 // ONE long-running server process on the bound host that serves THREE concerns
 // on one origin (the §2 unified server):
@@ -13,7 +13,7 @@
 //   • WS   /node/<id>       → open that node's ALREADY-running broker `view.sock`
 //                             and relay frames VERBATIM both directions. The relay
 //                             adds NOTHING — the browser is the SAME protocol peer
-//                             as `crtr attach`.
+//                             as `crtr surface attach`.
 //
 // §0 ONE-WRITER INVARIANT: the WS relay is ONLY a socket relay. It NEVER calls
 // reviveNode, NEVER spawns `pi --session`, NEVER touches SessionManager, and
@@ -43,6 +43,12 @@ import { runSourceRequest } from '../../core/view/bridge.js';
 import { startEventHub } from './events.js';
 import { createDevServer } from './dev-server.js';
 import { SOURCE_CACHE_TTL_MS, isCoalescableSourceRequest } from './source-cache.js';
+// ── Hearth product seam: model-auth lane (P3.3b, Silas-approved exception) ──
+// This is the ONLY Hearth-aware import in this file. All OAuth/status/start/
+// finish product logic lives in core/hearth/model-auth-guest.ts; this module
+// provides only routing + relay-token enforcement for the lane (see the route
+// block in startWebServer below).
+import { handleHearthModelAuthRequest } from '../../core/hearth/model-auth-guest.js';
 const HERE = dirname(fileURLToPath(import.meta.url));
 /** Candidate dirs to serve the shell SPA bundle from, in priority order: an
  *  explicit override, the compiled-module-relative `dist/web-client/` (what
@@ -189,7 +195,7 @@ function serveStatic(clientDir, req, res) {
     }
     if (!existsSync(filePath)) {
         res.writeHead(503, { 'content-type': 'text/plain; charset=utf-8' });
-        res.end('crtr web shell bundle not found — run `npm run build` to emit it into ' +
+        res.end('crtr surface web shell bundle not found — run `npm run build` to emit it into ' +
             `${clientDir} (or pass --dev for Vite middleware)\n`);
         return;
     }
@@ -364,7 +370,7 @@ export async function startWebServer(opts) {
     const dev = opts.dev ?? false;
     const tokenRequired = !isLoopbackHost(host);
     if (tokenRequired && (token === undefined || token === '')) {
-        throw new Error(`crtr web serve --host ${host} requires --token for remote-capable endpoints`);
+        throw new Error(`crtr surface web serve --host ${host} requires --token for remote-capable endpoints`);
     }
     const clientDir = resolveClientDir();
     // The bridge runs view sources + command verbs locally, in the cwd crtr was
@@ -441,6 +447,24 @@ export async function startWebServer(opts) {
                 eventHub.addClient(res);
                 return;
             }
+            // ── Hearth product seam: model-auth lane ──
+            // Isolated per the P3.3a/P3.3b approved exception. ALL Hearth/OAuth logic
+            // lives in core/hearth/model-auth-guest.ts; this block is ONLY routing +
+            // the relay-token gate. CRITICAL: this lane uses the STRICT token-only
+            // predicate requestTokenMatches(req, token), never requestAllowed() —
+            // requestAllowed() also accepts a same-origin loopback request with NO
+            // token at all, which would make this lane tokenless on local/dev binds.
+            // Every /__hearth/model-auth/* request fails closed (401) without an
+            // exact relay-token match, even on loopback.
+            if (pathname.startsWith('/__hearth/model-auth/anthropic/')) {
+                if (!requestTokenMatches(req, token)) {
+                    res.writeHead(401, { 'content-type': 'text/plain; charset=utf-8' });
+                    res.end('relay token required\n');
+                    return;
+                }
+                void handleHearthModelAuthRequest(req, res);
+                return;
+            }
             // --dev: Vite middleware owns all remaining asset/HTML serving (incl. its
             // own SPA fallback). It is mounted AFTER the bridge + SSE checks above, so
             // those never fall through to Vite.
@@ -520,7 +544,7 @@ export async function startWebServer(opts) {
             // A server error AFTER listen (e.g. an accept failure) must not be an
             // unhandled 'error' that crashes the process (n9) — log + carry on.
             httpServer.on('error', (err) => {
-                process.stderr.write(`crtr web: server error: ${err.message}\n`);
+                process.stderr.write(`crtr surface web: server error: ${err.message}\n`);
             });
             const addr = httpServer.address();
             const port = typeof addr === 'object' && addr !== null ? addr.port : opts.port;

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

@@ -12,7 +12,7 @@
 // (node new / canvas 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 snapshot/inspect for a specific id) ARE cacheable because the id
+// reads (node inspect snapshot/show for a specific id) ARE cacheable because the id
 // is part of the request and therefore part of the coalescing key, so distinct
 // ids never collide.
 /** TTL for coalesced source reads. Must comfortably exceed the SSE debounce
@@ -26,8 +26,8 @@ export const SOURCE_CACHE_TTL_MS = 500;
 const CACHEABLE_READS = [
     ['canvas', 'snapshot', '--json'],
     ['human', 'list', '--json'],
-    ['view', 'list', '--json'],
-    ['node', 'snapshot', '*', '--json'],
+    ['surface', 'view', 'list', '--json'],
+    ['node', 'inspect', 'snapshot', '*', '--json'],
     ['node', 'inspect', 'show', '*', '--json'],
 ];
 function argsMatch(pattern, args) {

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

@@ -1,15 +1,15 @@
-// web-cmd.ts — the `crtr web` command leaf + registration.
+// web-cmd.ts — the `crtr surface web` command leaf + registration.
 //
 // Starts the ONE long-running unified web server (server.ts): the crouter web UI
 // host. It serves the shell SPA, the source + command bridge (POST
 // /__crtr/source), the SSE change lane (GET /__crtr/events), and a VERBATIM
 // browser ⇄ broker relay on `ws://HOST:PORT/node/<id>` (the browser becomes
-// the SAME protocol peer as `crtr attach`). The node is selected by the URL, so
+// the SAME protocol peer as surface attach). The node is selected by the URL, so
 // there is NO positional node here.
 //
 // Command shape (plan §3.6): the CLI path-walker forbids a flat top-level leaf
 // (`defineRoot.subtrees` is `BranchDef[]`), so `web` is a BRANCH wrapping a
-// single leaf: `crtr web serve`.
+// single leaf: `crtr surface web serve`.
 import { spawn } from 'node:child_process';
 import { defineBranch, defineLeaf } from '../../core/command.js';
 import { startWebServer } from './server.js';
@@ -37,7 +37,7 @@ 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 `crtr 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.',
+    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.',
     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>)',
@@ -100,7 +100,7 @@ const webServeLeaf = defineLeaf({
         const server = await startWebServer({ port, host, token, dev });
         const nodeUrlShape = `${server.url}/node/<id>`;
         const browserUrl = token !== undefined ? `${server.url}?token=${encodeURIComponent(token)}` : server.url;
-        process.stdout.write(`crtr web serving on ${server.url}${dev ? ' (--dev: Vite middleware)' : ''}\n` +
+        process.stdout.write(`crtr surface web serving on ${server.url}${dev ? ' (--dev: Vite middleware)' : ''}\n` +
             `  open a node:  ${nodeUrlShape}\n` +
             `  bridge:       POST ${server.url}/__crtr/source\n` +
             `  events (SSE): GET  ${server.url}/__crtr/events\n` +
@@ -127,12 +127,12 @@ export function registerWeb() {
         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',
             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 + `crtr` command writes over POST /__crtr/source, streams canvas-change invalidations over GET /__crtr/events (SSE), and relays a browser connection VERBATIM to a node\'s already-running broker on /node/<id> — same protocol peer as `crtr attach`. 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. 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.',
         },
         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: '`serve` starts the ONE long-running unified server on the bound host (--port, default 7878; --host defaults to 127.0.0.1; --token is required for non-loopback binds; --open to launch the browser; --dev for Vite middleware/HMR). It serves the shell SPA (static dist/web-client/ shipped, Vite middleware in --dev), the POST /__crtr/source bridge (views\' reads AND `crtr` command writes via the local exec/file/http transport), the GET /__crtr/events SSE change-invalidation lane, and on a browser ws://HOST:PORT/node/<id> connection opens that node\'s broker view.sock and relays frames VERBATIM both ways — the browser is the same protocol peer as `crtr attach` (one controller drives, extra viewers are read-only; arbitration + dialogs ride the same frames). The relay NEVER spawns pi or writes a session: the node must already have a running headless broker (focus or revive it first); all graph mutations flow through `crtr` subprocesses the bridge runs. The server keeps running until ctrl+c; the node is chosen in the browser via the URL, not on the command line.',
+            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.',
         },
         children: [webServeLeaf],
     });

package/dist/commands/canvas-issue.js

@@ -70,7 +70,7 @@ export const issueNewLeaf = defineLeaf({
         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.',
         params: [
-            { kind: 'flag', name: 'type', type: 'string', required: true, constraint: 'Issue type / label: idea | bug.' },
+            { kind: 'flag', name: 'type', type: 'enum', choices: ['idea', 'bug'], required: true, constraint: 'Issue type / label.' },
             { kind: 'flag', name: 'body', type: 'string', required: false, constraint: 'The note text. Omit to read it from stdin/the popup TTY (type, Ctrl-D to submit).' },
             { kind: 'flag', name: 'cwd', type: 'string', required: false, constraint: 'Directory whose repo the issue targets. Defaults to --pane\u2019s path, then process.cwd().' },
             { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane whose cwd/client to use for repo resolution and the confirmation toast.' },

package/dist/commands/canvas-prune.js

@@ -8,7 +8,7 @@
 //
 // Exported as a leaf; `crtr canvas` (canvas.ts) mounts it.
 import { defineLeaf } from '../core/command.js';
-import { pruneNodes } from '../core/canvas/index.js';
+import { pruneNodes, pruneToLimit } from '../core/canvas/index.js';
 import { reapEmptyNodes } from '../core/runtime/placement.js';
 const DEFAULT_TTL_DAYS = 14;
 export const canvasPruneLeaf = defineLeaf({
@@ -17,8 +17,15 @@ export const canvasPruneLeaf = defineLeaf({
     whenToUse: 'you want to bound the canvas\u2019s on-disk growth \u2014 sweep away nodes that are finished (done), crashed (dead), or closed (canceled) and older than a retention window, reclaiming their rows, edges (cascade-deleted by the schema), and `nodes/<id>/` dirs. Run it as an operator/cron chore; live nodes (active/idle) are never touched, and you can preview the sweep before it deletes anything',
     help: {
         name: 'canvas prune',
-        summary: 'delete terminal nodes older than a TTL (edges cascade, dirs removed); --dry-run to preview',
+        summary: 'delete terminal nodes older than a TTL (edges cascade, dirs removed); --max N for a count cap; --dry-run to preview',
         params: [
+            {
+                kind: 'flag',
+                name: 'max',
+                type: 'int',
+                required: false,
+                constraint: 'COUNT mode (instead of the TTL sweep): keep only the N most-recently-active nodes, deleting the oldest terminal nodes beyond the cap. LIVE nodes (active/idle with a running pi) are NEVER deleted, so the real floor is max(N, liveCount). Recency = telemetry.json mtime, falling back to created. Combine with --dry-run to preview.',
+            },
             {
                 kind: 'flag',
                 name: 'ttl',
@@ -60,6 +67,7 @@ export const canvasPruneLeaf = defineLeaf({
         ],
         outputKind: 'object',
         effects: [
+            'With --max N: COUNT mode — keep only the N most-recently-active nodes, deleting the oldest terminal beyond max(N, liveCount); live (active/idle with a running pi) nodes and the caller are never deleted. Takes precedence over the TTL/--empty sweeps.',
             'Deletes matching `nodes` rows; their edges cascade-delete via the FK; each node\u2019s `nodes/<id>/` dir is removed.',
             'No-op on live nodes (active/idle) and on terminal nodes newer than the TTL. With --include-stale: also deletes active/idle nodes past the TTL whose process is gone (pi_pid null/dead); genuinely-running nodes and the caller are kept.',
             'Under --dry-run: read-only, deletes nothing.',
@@ -70,6 +78,20 @@ export const canvasPruneLeaf = defineLeaf({
         const dryRun = input['dryRun'] ?? false;
         const includeStale = input['includeStale'] ?? false;
         const empty = input['empty'] ?? false;
+        const maxNodes = input['max'];
+        if (maxNodes !== undefined) {
+            const result = pruneToLimit({ maxNodes, dryRun });
+            return {
+                pruned: dryRun ? 0 : result.pruned.length,
+                dryRun,
+                ttlDays,
+                nodes: result.pruned.map((p) => ({
+                    node_id: p.node_id,
+                    status: p.status,
+                    created: p.created,
+                })),
+            };
+        }
         if (empty) {
             const ids = reapEmptyNodes({ dryRun });
             return {

package/dist/commands/canvas-snapshot.js

@@ -15,6 +15,9 @@ export const canvasSnapshotLeaf = defineLeaf({
         ],
         outputKind: 'object',
         effects: ['Read-only: queries canvas.db, focus rows, telemetry files, and human ask counts.'],
+        // Machine-readable dump for the browser canvas, not for an agent/human to
+        // glance at — collapse it in the attach viewer by default.
+        preview: { suppressOutput: true },
     },
     run: async () => {
         const rows = dashboardRowsAll();

package/dist/commands/canvas-tmux-spread.js

@@ -2,7 +2,7 @@
 //
 // Bound by the alt+c → `e` chord (config: prefixBinds['e'].run = "canvas
 // tmux-spread {self}"). It "expands" the graph you are watching: the caller's
-// own viewer pane is broken out into a BRAND-NEW window, then a `crtr attach`
+// own viewer pane is broken out into a BRAND-NEW window, then a surface-attach
 // viewer pane is tiled beside it for every broker-alive node in the local
 // subtree (ancestry root → self → descendants), so the user lands on a single
 // window showing the whole live subtree at once.
@@ -51,7 +51,7 @@ export const tmuxSpreadLeaf = defineLeaf({
     whenToUse: 'you want the whole live subtree you are watching on one tiled tmux window at once — bound to the alt+c → e chord; rarely run by hand',
     help: {
         name: 'canvas tmux-spread',
-        summary: 'Explode the local subtree into a tiled grid: break the caller\'s viewer pane into a brand-new window, then tile a `crtr attach` viewer pane beside it for every broker-alive node (status active/idle + live pi_pid) in the ancestry-root subtree, most-recently-active first, capped at 8 panes',
+        summary: 'Explode the local subtree into a tiled grid: break the caller\'s viewer pane into a brand-new window, then tile a surface-attach viewer pane beside it for every broker-alive node (status active/idle + live pi_pid) in the ancestry-root subtree, most-recently-active first, capped at 8 panes',
         params: [
             {
                 kind: 'positional',
@@ -77,7 +77,7 @@ export const tmuxSpreadLeaf = defineLeaf({
         outputKind: 'object',
         effects: [
             'Breaks the caller\'s viewer pane into a brand-new tmux window (tmux break-pane).',
-            'Opens a `crtr attach` viewer pane (and a focuses row) for each shown sibling, moving any that had a viewer elsewhere into the spread.',
+            'Opens a surface-attach viewer pane (and a focuses row) for each shown sibling, moving any that had a viewer elsewhere into the spread.',
             'Tiles the window and switches the client onto it.',
         ],
     },

package/dist/commands/human.js

@@ -20,7 +20,7 @@ export function registerHuman() {
         rootEntry: {
             concept: 'human-in-the-loop decisions, document review, and live display',
             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)'
+            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 for anchored line-by-line comments.'
         },
         help: {
             name: 'human',

package/dist/commands/memory/lint.js

@@ -1,16 +1,16 @@
 // `crtr memory lint` — the permanent valid-YAML gate over the bounded corpus
 // (the CTO green-checkpoint: zero frontmatter parse errors at authoring time,
 // so an invalid doc fails HERE instead of being silently isolated at runtime).
-// Bounded corpus = the substrate memory dirs (project/user/builtin). Never a
-// filesystem-wide scan.
-import { basename, relative, sep } from 'node:path';
+// Bounded corpus = the substrate memory dirs (ancestor projects/user/builtin).
+// Never a filesystem-wide scan.
+import { basename, join, relative, sep } from 'node:path';
 import { defineLeaf } from '../../core/command.js';
 import { general } from '../../core/errors.js';
 import { warn } from '../../core/output.js';
 import { pathExists, readText, walkFiles } from '../../core/fs-utils.js';
 import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
-import { listInstalledPlugins } from '../../core/resolver.js';
-import { pluginMemoryDir, scopeMemoryDir } from '../../core/scope.js';
+import { listInstalledPlugins, listInstalledPluginsInRoot } from '../../core/resolver.js';
+import { pluginMemoryDir, projectScopeRoots, scopeMemoryDir } from '../../core/scope.js';
 import { isDocKind, RUNGS } from '../../core/substrate/index.js';
 /** The parser normalizes the `always` alias to `content`, so it lints valid. */
 const VALID_RUNGS = [...RUNGS, 'always'];
@@ -107,8 +107,8 @@ export const lintLeaf = defineLeaf({
     run: async () => {
         const findings = [];
         let memoryCount = 0;
-        // Substrate memory stores (project/user/builtin), schema-aware. A scope's
-        // corpus is its NATIVE memory dir plus each enabled plugin's memory dir —
+        // Substrate memory stores (ancestor projects/user/builtin), schema-aware.
+        // A source's corpus is its NATIVE memory dir plus each enabled plugin's memory dir —
         // plugin docs are substrate docs and lint through the same schema gate.
         //    MEMORY.md index files are not substrate docs — YAML-parse only.
         const lintDir = (dir) => {
@@ -121,7 +121,14 @@ export const lintLeaf = defineLeaf({
                 lintFile(file, basename(file) !== 'MEMORY.md', findings);
             }
         };
-        for (const scope of ['project', 'user', 'builtin']) {
+        for (const root of projectScopeRoots()) {
+            lintDir(join(root, 'memory'));
+            for (const plugin of listInstalledPluginsInRoot('project', root)) {
+                if (plugin.enabled)
+                    lintDir(pluginMemoryDir(plugin));
+            }
+        }
+        for (const scope of ['user', 'builtin']) {
             lintDir(scopeMemoryDir(scope));
             for (const plugin of listInstalledPlugins(scope)) {
                 if (plugin.enabled)

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

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

package/dist/commands/memory/origin.js

@@ -0,0 +1,88 @@
+import { defineLeaf } from '../../core/command.js';
+import { CrtrError, notFound } from '../../core/errors.js';
+import { resolveMemoryDoc } from '../../core/memory-resolver.js';
+import { getNode } from '../../core/canvas/canvas.js';
+import { contextDir } from '../../core/canvas/paths.js';
+export const originLeaf = defineLeaf({
+    name: 'origin',
+    description: 'deref a memory document back to the node + conversation that created it',
+    whenToUse: 'you are looking at a stored memory and want to know WHERE it came from — which node authored it, in what conversation, when, and in which project. Reads the `origin` provenance block the runtime stamps at creation and derefs the node pointer to its live session conversation, context dir, and current state. Docs hand-authored or created before provenance capture carry no origin — the command says so rather than guessing.',
+    help: {
+        name: 'memory origin',
+        summary: 'resolve a doc name to its creation provenance and deref the originating node',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`). Resolved across scopes: project > user > builtin.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'Resolved document name.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the document on disk.' },
+            { name: 'origin_recorded', type: 'boolean', required: true, constraint: 'true when the doc carries an `origin` provenance block; false for hand-authored or pre-provenance docs.' },
+            { name: 'created', type: 'string', required: false, constraint: 'ISO timestamp the doc was created. Absent when origin_recorded is false.' },
+            { name: 'cwd', type: 'string', required: false, constraint: 'Working directory the authoring conversation ran in.' },
+            { name: 'node', type: 'string', required: false, constraint: 'Node id that authored the doc, or null when written by a human at the CLI (no node).' },
+            { name: 'node_present', type: 'boolean', required: false, constraint: 'true when that node still exists on the canvas (deref below is live); false when it has been pruned.' },
+            { name: 'node_kind', type: 'string', required: false, constraint: 'Kind of the authoring node (only when node_present).' },
+            { name: 'node_mode', type: 'string', required: false, constraint: 'Mode of the authoring node (only when node_present).' },
+            { name: 'node_status', type: 'string', required: false, constraint: 'Current lifecycle status of the authoring node (only when node_present).' },
+            { name: 'node_description', type: 'string', required: false, constraint: 'The authoring node\u2019s description (only when node_present).' },
+            { name: 'session_file', type: 'string', required: false, constraint: 'Absolute path to the originating conversation\u2019s pi session .jsonl (only when node_present and a session was captured) \u2014 read it to see the conversation that produced the doc.' },
+            { name: 'context_dir', type: 'string', required: false, constraint: 'Absolute path to the authoring node\u2019s context dir (its shared document store).' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands to inspect the origin.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const nameRaw = input['name'];
+        let doc;
+        try {
+            doc = resolveMemoryDoc(nameRaw);
+        }
+        catch (e) {
+            if (!(e instanceof CrtrError && e.code === 'not_found'))
+                throw e;
+        }
+        if (doc === undefined) {
+            throw notFound(`memory document not found: ${nameRaw}`, {
+                memory: nameRaw,
+                next: 'Run `crtr memory find <query>` to discover documents, or `crtr memory list` to browse the inventory.',
+            });
+        }
+        const origin = doc.frontmatter?.['origin'];
+        if (origin === undefined || typeof origin !== 'object') {
+            return {
+                name: doc.name,
+                path: doc.path,
+                origin_recorded: false,
+                follow_up: 'No provenance recorded \u2014 this doc was hand-authored or created before provenance capture. Read its body with `crtr memory read ' +
+                    doc.name +
+                    '`.',
+            };
+        }
+        const str = (v) => (typeof v === 'string' ? v : null);
+        const nodeId = str(origin['node']);
+        const node = nodeId !== null ? getNode(nodeId) : null;
+        const sessionFile = str(node?.pi_session_file);
+        const followUp = node !== null
+            ? `Read the originating conversation at \`${sessionFile ?? '(no session captured)'}\`, browse its shared docs at \`${contextDir(nodeId)}\`, or attach live with \`crtr surface attach ${nodeId}\`.`
+            : nodeId !== null
+                ? `The authoring node \`${nodeId}\` has been pruned from the canvas; its context dir may persist at \`${contextDir(nodeId)}\`.`
+                : 'Authored by a human at the CLI \u2014 no node conversation to deref.';
+        return {
+            name: doc.name,
+            path: doc.path,
+            origin_recorded: true,
+            created: str(origin['created']) ?? undefined,
+            cwd: str(origin['cwd']) ?? undefined,
+            node: nodeId ?? undefined,
+            node_present: nodeId !== null ? node !== null : undefined,
+            node_kind: node?.kind ?? undefined,
+            node_mode: node?.mode ?? undefined,
+            node_status: node?.status ?? undefined,
+            node_description: node?.description ?? undefined,
+            session_file: sessionFile ?? undefined,
+            context_dir: nodeId !== null ? contextDir(nodeId) : undefined,
+            follow_up: followUp,
+        };
+    },
+});

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

@@ -26,6 +26,14 @@ export declare function coerceReadWhen(raw: string): Record<string, unknown>;
 /** Coerce a `--applies-to` string to the schema's glob form: a comma-separated
  *  list becomes an array, a single glob stays a string. */
 export declare function coerceAppliesTo(raw: string): unknown;
+/** Provenance for a doc at the moment it is created: when, where, and which
+ *  node's conversation authored it. Read from the env the runtime injects into
+ *  every node's pi process (CRTR_NODE_ID/KIND/MODE/NODE_CWD); when invoked
+ *  outside a node (a human at the CLI) only `created` + `cwd` are recorded.
+ *  Stamped ONCE at create and preserved verbatim on every later update —
+ *  `crtr memory origin <name>` derefs the `node` pointer back to the live node
+ *  (its session conversation, context dir, current state). */
+export declare function buildOrigin(): Record<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

package/dist/commands/memory/shared.js

@@ -102,7 +102,9 @@ export function coerceAppliesTo(raw) {
     return parts.length === 1 ? parts[0] : parts;
 }
 // Canonical frontmatter field order for a substrate document. Known fields come
-// first in this order; any preserved-on-update extras append after.
+// first in this order; any preserved-on-update extras append after. `origin` is
+// provenance the runtime stamps at creation (never the author) — it sorts last
+// of the known fields so the authoring contract stays at the top of the block.
 const FRONTMATTER_ORDER = [
     'kind',
     'when-and-why-to-read',
@@ -112,7 +114,26 @@ const FRONTMATTER_ORDER = [
     'gate',
     'applies-to',
     'read-when',
+    'origin',
 ];
+/** Provenance for a doc at the moment it is created: when, where, and which
+ *  node's conversation authored it. Read from the env the runtime injects into
+ *  every node's pi process (CRTR_NODE_ID/KIND/MODE/NODE_CWD); when invoked
+ *  outside a node (a human at the CLI) only `created` + `cwd` are recorded.
+ *  Stamped ONCE at create and preserved verbatim on every later update —
+ *  `crtr memory origin <name>` derefs the `node` pointer back to the live node
+ *  (its session conversation, context dir, current state). */
+export function buildOrigin() {
+    const env = process.env;
+    const origin = {
+        created: new Date().toISOString(),
+        cwd: env['CRTR_NODE_CWD'] ?? process.cwd(),
+    };
+    const nodeId = env['CRTR_NODE_ID'];
+    if (nodeId !== undefined && nodeId !== '')
+        origin['node'] = nodeId;
+    return origin;
+}
 /** 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