@north-light/crouter 0.3.154

package/dist/commands/attention.js

@@ -0,0 +1,223 @@
+// `crtr canvas attention` — aggregate pending human tickets across the canvas.
+//
+// A pending "ticket" is any humanloop interaction awaiting a human: a deck,
+// notification, or anchored review. Each lives in its human bridge node
+// directory and is attributed through that bridge's parent relation. This
+// subtree surfaces a direct node projection; cwd is display metadata only.
+//
+// Exported as a branch; `crtr canvas` (canvas.ts) mounts it.
+import { defineBranch, defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { cliClient, cliCanvasSource } from './api-client.js';
+/** The nodes represented in the sub-DAG rooted at `viewId` (root + view). */
+async function viewNodeSet(source, viewId) {
+    return new Set([viewId, ...(await source.view(viewId))]);
+}
+// ---------------------------------------------------------------------------
+// attention count
+// ---------------------------------------------------------------------------
+const attentionCount = defineLeaf({
+    name: 'count',
+    description: 'total pending human-ticket count (machine-parseable stdout.count)',
+    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.
+        summary: 'return the number of pending human tickets (asks, reviews, notifications); stdout.count is machine-parseable',
+        params: [
+            {
+                kind: 'flag',
+                name: 'node',
+                type: 'string',
+                required: false,
+                constraint: 'Count tickets asked by this node. Mutually exclusive with --view.',
+            },
+            {
+                kind: 'flag',
+                name: 'view',
+                type: 'string',
+                required: false,
+                constraint: 'Sum tickets for all nodes in the sub-DAG rooted at this id. Mutually exclusive with --node.',
+            },
+        ],
+        output: [
+            { name: 'count', type: 'integer', required: true, constraint: 'Total pending human tickets in the requested scope.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: scans humanloop interaction dirs.'],
+    },
+    run: async (input) => {
+        const nodeId = input['node'];
+        const viewId = input['view'];
+        if (nodeId !== undefined && viewId !== undefined) {
+            throw new InputError({
+                error: 'ambiguous_scope',
+                message: '--node and --view are mutually exclusive',
+                next: 'Use one of --node <id>, --view <id>, or neither (canvas-wide).',
+            });
+        }
+        if (nodeId !== undefined) {
+            const source = cliCanvasSource();
+            const node = await source.getNode(nodeId);
+            if (node === null) {
+                throw new InputError({
+                    error: 'not_found',
+                    message: `no node: ${nodeId}`,
+                    next: 'List nodes with `crtr node inspect list`.',
+                });
+            }
+            const counts = await cliClient().attentionCounts([nodeId]);
+            return { count: counts.counts[nodeId] ?? 0 };
+        }
+        const items = (await cliClient().attention()).items;
+        if (viewId !== undefined) {
+            const source = cliCanvasSource();
+            if ((await source.getNode(viewId)) === null) {
+                throw new InputError({
+                    error: 'not_found',
+                    message: `no node: ${viewId}`,
+                    next: 'List nodes with `crtr node inspect list`.',
+                });
+            }
+            const ids = await viewNodeSet(source, viewId);
+            const total = items.filter((it) => ids.has(it.node_id)).reduce((s, e) => s + e.count, 0);
+            return { count: total };
+        }
+        // Canvas-wide — sum every asking-node entry.
+        return { count: items.reduce((s, e) => s + e.count, 0) };
+    },
+});
+// ---------------------------------------------------------------------------
+// attention list
+// ---------------------------------------------------------------------------
+const attentionList = defineLeaf({
+    name: 'list',
+    description: 'itemised list of cwds with pending human tickets',
+    whenToUse: 'finding which agents are blocked waiting on a human — an itemised list of the cwds with pending tickets (asks, reviews, notifications), 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 that asked pending human tickets',
+        params: [
+            {
+                kind: 'flag',
+                name: 'view',
+                type: 'string',
+                required: false,
+                constraint: 'Scope the list to the sub-DAG rooted at this node id. Omit for canvas-wide.',
+            },
+        ],
+        output: [
+            {
+                name: 'items',
+                type: 'object[]',
+                required: true,
+                constraint: 'Each: {node_id, name, cwd, count}. One entry per asking node with count > 0.',
+            },
+            { name: 'total', type: 'integer', required: true, constraint: 'Sum of counts across all entries.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: scans humanloop interaction dirs.'],
+    },
+    run: async (input) => {
+        const viewId = input['view'];
+        let items = (await cliClient().attention()).items;
+        if (viewId !== undefined) {
+            const source = cliCanvasSource();
+            if ((await source.getNode(viewId)) === null) {
+                throw new InputError({
+                    error: 'not_found',
+                    message: `no node: ${viewId}`,
+                    next: 'List nodes with `crtr node inspect list`.',
+                });
+            }
+            const ids = await viewNodeSet(source, viewId);
+            items = items.filter((it) => ids.has(it.node_id));
+        }
+        const total = items.reduce((s, e) => s + e.count, 0);
+        return { items, total };
+    },
+});
+// ---------------------------------------------------------------------------
+// attention map
+// ---------------------------------------------------------------------------
+const attentionMap = defineLeaf({
+    name: 'map',
+    description: 'per-node ticket counts for a visible set, batched in one pass',
+    whenToUse: 'labelling every node in a UI with its pending-ticket 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 human-ticket 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',
+        params: [
+            {
+                kind: 'flag',
+                name: 'view',
+                type: 'string',
+                required: false,
+                constraint: 'Include this node and its whole sub-DAG (root + reports recursively). Union with --nodes. At least one of --view/--nodes is required.',
+            },
+            {
+                kind: 'flag',
+                name: 'nodes',
+                type: 'string',
+                required: false,
+                constraint: 'Comma-separated explicit node ids to include (e.g. ancestry + peers). Union with --view.',
+            },
+        ],
+        output: [
+            {
+                name: 'counts',
+                type: 'object',
+                required: true,
+                constraint: 'Map of node_id → pending human-ticket count. Every requested id is present (0 when none).',
+            },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: scans the registered humanloop node root once.'],
+    },
+    run: async (input) => {
+        const viewId = input['view'];
+        const nodesRaw = input['nodes'];
+        if (viewId === undefined && (nodesRaw === undefined || nodesRaw.trim() === '')) {
+            throw new InputError({
+                error: 'missing_scope',
+                message: 'at least one of --view <id> or --nodes <a,b,c> is required',
+                next: 'Pass --view <root> to cover a sub-DAG, --nodes <a,b,c> for an explicit set, or both.',
+            });
+        }
+        const source = cliCanvasSource();
+        const ids = new Set();
+        if (viewId !== undefined) {
+            if ((await source.getNode(viewId)) === null) {
+                throw new InputError({
+                    error: 'not_found',
+                    message: `no node: ${viewId}`,
+                    next: 'List nodes with `crtr node inspect list`.',
+                });
+            }
+            ids.add(viewId);
+            for (const id of await source.view(viewId))
+                ids.add(id);
+        }
+        if (nodesRaw !== undefined) {
+            for (const id of nodesRaw.split(',').map((s) => s.trim()).filter((s) => s !== ''))
+                ids.add(id);
+        }
+        const counts = await cliClient().attentionCounts([...ids]);
+        return { counts: counts.counts };
+    },
+});
+// ---------------------------------------------------------------------------
+// Export — mounted under `crtr canvas`
+// ---------------------------------------------------------------------------
+export const attentionBranch = defineBranch({
+    name: 'attention',
+    description: 'count/list pending human tickets across the graph',
+    whenToUse: 'checking whether any agent on the canvas is blocked waiting on a human, and where: count the pending tickets (asks, reviews, notifications) 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 tickets across the canvas',
+        model: '`count` returns a single integer (stdout.count is machine-parseable); `list` returns itemised asking-node entries. Scope with --node (one node) or --view (sub-DAG) — default is canvas-wide. A ticket is any humanloop interaction awaiting a human: an ask, a review, or a notification.',
+    },
+    children: [attentionCount, attentionList, attentionMap],
+});

package/dist/commands/canvas-browse.d.ts

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

package/dist/commands/canvas-browse.js

@@ -0,0 +1,95 @@
+// `crtr canvas browse` — the interactive full-screen canvas navigator.
+//
+// A raw-mode TUI over the WHOLE canvas: tabs (All/Live/Dormant/Attention/Pinned), an
+// auto-collapsed tree, and `/` fuzzy search. Enter resumes the chosen node via
+// `crtr surface node focus` (the ONLY sanctioned open — reviveNode, never `pi --session`).
+// Owns the screen, so it returns void and writes nothing to stdout itself.
+// Outside a TTY it prints the static forest and exits 0 (see runBrowse).
+import { defineLeaf } from '../core/command.js';
+import { runBrowse } from '../core/canvas/browse/app.js';
+import { cliClient, cliCanvasSource } from './api-client.js';
+import { resolveRemoteCanvasTarget } from '../core/view/remote-canvas-target.js';
+import { RemoteEventStream } from '../core/canvas/remote-event-stream.js';
+import { readState } from '../core/config.js';
+import { getDefaultProfileId } from '../core/profiles/default-binding.js';
+export const browseLeaf = defineLeaf({
+    name: 'browse',
+    description: 'open the interactive canvas navigator (tabs/tree/search)',
+    whenToUse: 'you want to VIEW and NAVIGATE the whole canvas interactively — a full-screen TUI with tabs (All/Live/Dormant/Attention/Pinned), an expandable tree (children auto-collapsed; → to expand), `/` fuzzy search, `f` to pin, `m` to message and `R` to rename a node in place, and `?` for the full keymap; Enter resumes the chosen node. Use this to find your way around a large canvas. Use `canvas dashboard` instead for a one-shot ASCII tree you can pipe, and `node inspect list` for a flat machine-readable roster',
+    help: {
+        name: 'canvas browse',
+        summary: 'interactive full-screen canvas navigator — tabs, an auto-collapsed tree, and `/` fuzzy search; Enter resumes the chosen node via `crtr surface node focus`. Outside a TTY it prints the static forest and exits',
+        params: [
+            {
+                kind: 'flag',
+                name: 'return-pane',
+                type: 'string',
+                required: false,
+                constraint: 'tmux pane id to focus the chosen node INTO (set by the /resume-node popup so the node lands back in your pi pane). Default: this pane.',
+            },
+            {
+                kind: 'flag',
+                name: 'cwd',
+                type: 'string',
+                required: false,
+                constraint: 'directory used when you toggle the optional cwd filter (c). The navigator opens with All dirs; /resume-node passes the launching node\'s cwd. Default: the invocation cwd.',
+            },
+            {
+                kind: 'flag',
+                name: 'profile-id',
+                type: 'string',
+                required: false,
+                constraint: 'Exact profile id for the initial profile filter (on by default; P toggles All profiles). Default: the launching node\'s profile via CRTR_PROFILE_ID, then this cwd\'s pinned default profile; absent means All profiles.',
+            },
+            {
+                kind: 'flag',
+                name: 'canvas',
+                type: 'string',
+                required: false,
+                constraint: 'Read from the named remote canvas target (see `crtr canvas config list`) instead of the local canvas. Overrides `crtr canvas use`.',
+            },
+        ],
+        output: [],
+        outputKind: 'object',
+        effects: [
+            'Takes over the terminal in raw mode (alt-screen) until you quit (q/Esc) or pick a node.',
+            'On Enter: resumes the selected node via `crtr surface node focus` (reviveNode — the only sanctioned open).',
+            'Read-only on the canvas db; mutates nothing but the chosen node\'s placement on resume.',
+        ],
+    },
+    run: async (input) => {
+        const cwd = input['cwd'] ?? process.cwd();
+        const profileId = input['profileId'] ??
+            process.env['CRTR_PROFILE_ID'] ??
+            getDefaultProfileId(cwd) ??
+            undefined;
+        const canvasName = input['canvas'];
+        const source = cliCanvasSource({ canvasName });
+        // The EFFECTIVE remote target name — an explicit --canvas, or (mirroring
+        // resolveCanvasSource's own precedence) the durable `crtr canvas use`
+        // selection. Only a remote target needs an event stream; resolve its
+        // credentials ONCE here (not re-derived inside app.ts, which stays
+        // credential-agnostic).
+        const effectiveCanvasName = canvasName ?? readState('user').activeCanvas ?? undefined;
+        const eventStream = effectiveCanvasName !== undefined
+            ? (() => {
+                const { previewEndpoint, relayToken } = resolveRemoteCanvasTarget(effectiveCanvasName);
+                return new RemoteEventStream(previewEndpoint, relayToken);
+            })()
+            : undefined;
+        // The `x` close-out routes through the daemon API (browse `x` = finish the
+        // root to `done`); the callback keeps app.ts off the openDb-reaching
+        // runtime/close.js.
+        await runBrowse({
+            returnPane: input['returnPane'],
+            cwd,
+            profileId,
+            source,
+            eventStream,
+            viewedNodeIds: effectiveCanvasName === undefined
+                ? async () => new Set((await cliClient().listFocuses()).map((focus) => focus.node_id))
+                : undefined,
+            closeNode: (id) => cliClient().closeNode(id, { finish: true }).then((r) => ({ closed: r.closed })),
+        });
+    },
+});

package/dist/commands/canvas-config.d.ts

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

package/dist/commands/canvas-config.js

@@ -0,0 +1,210 @@
+// `crtr canvas config` — register, list, inspect, and remove named remote
+// canvas targets (a preview endpoint + a relay token kept in the 0600
+// secrets store, never persisted to config.json or logged). `add` requires
+// `--relay-token -` (stdin-only) — a literal argv value is rejected with a
+// generic error (never echoing what was received, since it may be a real
+// secret) so the token can never land in shell history or process listings.
+// Selecting one for read commands is `crtr canvas use`, a sibling leaf, not a
+// child here.
+import { defineBranch, defineLeaf } from '../core/command.js';
+import { InputError, readStdinRaw } from '../core/io.js';
+import { readConfig, updateConfig } from '../core/config.js';
+import { readSecrets, setRelayToken, deleteRelayToken, fingerprint } from '../core/secrets.js';
+const SCOPE = 'user';
+/** Masks one target's token presence/fingerprint from an ALREADY-loaded
+ *  `SecretsStore` — never re-reads/reparses `secrets.json` per target
+ *  (`list`/`show` load it once and pass it in here). */
+function maskedTarget(name, target, secrets) {
+    const token = secrets.relayTokens[target.relayTokenRef];
+    return {
+        name,
+        previewEndpoint: target.previewEndpoint,
+        relayTokenRef: target.relayTokenRef,
+        ...(target.cpOrigin ? { cpOrigin: target.cpOrigin } : {}),
+        tokenStored: token !== undefined && token !== '',
+        ...(token !== undefined && token !== '' ? { fingerprint: fingerprint(token) } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// canvas config add
+// ---------------------------------------------------------------------------
+const canvasConfigAdd = defineLeaf({
+    name: 'add',
+    description: 'register a remote canvas target (preview endpoint + relay token)',
+    whenToUse: 'wiring up a remote canvas so `node inspect`, `canvas browse`, or `surface attach --canvas` can read it \u2014 stores the preview endpoint in config.json and the raw relay token in the 0600 secrets store (never together, never persisted to config.json or logged). Re-running with the same name overwrites both.',
+    help: {
+        name: 'canvas config add',
+        summary: 'register (or overwrite) a named remote canvas target',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Target name \u2014 the id every other `canvas config`/`canvas use`/`--canvas` reference uses.' },
+            { kind: 'flag', name: 'preview', type: 'string', required: true, constraint: 'The Blaxel preview endpoint base URL (e.g. https://<hash>.preview.bl.run).' },
+            { kind: 'flag', name: 'relay-token', type: 'string', required: true, constraint: 'Must be exactly `-` — the raw token is read from stdin, never argv (keeps it out of shell history). Any other value is rejected.' },
+            { kind: 'flag', name: 'cp', type: 'string', required: false, constraint: 'Optional control-plane origin, when this target has one distinct from the preview endpoint.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'The target name just registered.' },
+            { name: 'previewEndpoint', type: 'string', required: true, constraint: 'The stored preview endpoint.' },
+            { name: 'relayTokenRef', type: 'string', required: true, constraint: 'The secrets-store key the token was written under (equals name).' },
+            { name: 'cpOrigin', type: 'string', required: false, constraint: 'The stored control-plane origin, when --cp was given.' },
+            { name: 'tokenStored', type: 'boolean', required: true, constraint: 'Always true on success \u2014 confirms the token was written to the 0600 store.' },
+        ],
+        outputKind: 'object',
+        effects: ['Writes remoteCanvas.targets.<name> to config.json (previewEndpoint, relayTokenRef, cpOrigin).', 'Writes the raw token to the 0600 secrets store under relayTokenRef \u2014 never to config.json or stdout.'],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const previewEndpoint = input['preview'];
+        const rawFlag = input['relayToken'];
+        const cp = input['cp'];
+        if (rawFlag !== '-') {
+            throw new InputError({
+                error: 'invalid_relay_token_arg',
+                message: 'relay token must be piped on stdin — pass `--relay-token -`',
+                field: 'relay-token',
+                next: 'Re-run with `--relay-token -` and pipe the raw token on stdin (e.g. `echo "$TOKEN" | crtr canvas config add <name> --preview <url> --relay-token -`).',
+            });
+        }
+        const token = (await readStdinRaw()).trim();
+        if (token === '') {
+            throw new InputError({
+                error: 'empty_token',
+                message: 'relay token is empty',
+                field: 'relay-token',
+                next: 'Pass a non-empty token, or `--relay-token -` and pipe it on stdin.',
+            });
+        }
+        const target = { previewEndpoint, relayTokenRef: name, ...(cp ? { cpOrigin: cp } : {}) };
+        updateConfig(SCOPE, (cfg) => {
+            cfg.remoteCanvas.targets[name] = target;
+        });
+        setRelayToken(name, token, SCOPE);
+        return { name, previewEndpoint, relayTokenRef: name, ...(cp ? { cpOrigin: cp } : {}), tokenStored: true };
+    },
+    render: (r) => `Registered remote canvas target '${r['name']}' → ${r['previewEndpoint']} (token stored).`,
+});
+// ---------------------------------------------------------------------------
+// canvas config list
+// ---------------------------------------------------------------------------
+const canvasConfigList = defineLeaf({
+    name: 'list',
+    description: 'list registered remote canvas targets',
+    whenToUse: 'checking which remote canvas targets exist before `canvas use`/`--canvas <name>` \u2014 never prints a raw token, only a non-reversible fingerprint.',
+    help: {
+        name: 'canvas config list',
+        summary: 'list every registered remote canvas target (masked \u2014 no raw tokens)',
+        output: [
+            {
+                name: 'targets',
+                type: 'object[]',
+                required: true,
+                constraint: 'Each: {name, previewEndpoint, relayTokenRef, cpOrigin?, tokenStored, fingerprint?}. fingerprint is a non-reversible sha256 prefix, present only when a token is stored.',
+            },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: reads config.json and the secrets-store token presence/fingerprint (never the raw token).'],
+    },
+    run: async () => {
+        const cfg = readConfig(SCOPE);
+        const secrets = readSecrets(SCOPE);
+        const targets = Object.entries(cfg.remoteCanvas.targets).map(([name, t]) => maskedTarget(name, t, secrets));
+        return { targets };
+    },
+    render: (r) => {
+        const targets = r['targets'];
+        if (targets.length === 0)
+            return 'No remote canvas targets configured.';
+        return targets
+            .map((t) => `${t['name']} — ${t['previewEndpoint']} (${t['tokenStored'] ? `token ${t['fingerprint']}` : 'no token stored'})`)
+            .join('\n');
+    },
+});
+// ---------------------------------------------------------------------------
+// canvas config show
+// ---------------------------------------------------------------------------
+const canvasConfigShow = defineLeaf({
+    name: 'show',
+    description: 'show one registered remote canvas target',
+    whenToUse: 'inspecting a single remote canvas target\u2019s config \u2014 masked the same way as `list`.',
+    help: {
+        name: 'canvas config show',
+        summary: 'show one remote canvas target (masked \u2014 no raw token)',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Target name.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'The target name.' },
+            { name: 'previewEndpoint', type: 'string', required: true, constraint: 'The stored preview endpoint.' },
+            { name: 'relayTokenRef', type: 'string', required: true, constraint: 'The secrets-store key holding the token.' },
+            { name: 'cpOrigin', type: 'string', required: false, constraint: 'The stored control-plane origin, when this target has one distinct from the preview endpoint.' },
+            { name: 'tokenStored', type: 'boolean', required: true, constraint: 'Whether a token is currently stored under relayTokenRef.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only.'],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const cfg = readConfig(SCOPE);
+        const target = cfg.remoteCanvas.targets[name];
+        if (target === undefined) {
+            throw new InputError({
+                error: 'not_found',
+                message: `no remote canvas target named '${name}'`,
+                next: 'List configured targets with `crtr canvas config list`.',
+            });
+        }
+        return maskedTarget(name, target, readSecrets(SCOPE));
+    },
+    render: (r) => `${r['name']} — ${r['previewEndpoint']} (${r['tokenStored'] ? `token ${r['fingerprint']}` : 'no token stored'})`,
+});
+// ---------------------------------------------------------------------------
+// canvas config remove
+// ---------------------------------------------------------------------------
+const canvasConfigRemove = defineLeaf({
+    name: 'remove',
+    description: 'remove a registered remote canvas target and its stored token',
+    whenToUse: 'decommissioning a remote canvas target \u2014 drops it from config.json and deletes its raw token from the secrets store.',
+    help: {
+        name: 'canvas config remove',
+        summary: 'remove a remote canvas target and its stored token',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Target name.' },
+        ],
+        output: [
+            { name: 'removed', type: 'string', required: true, constraint: 'The target name removed.' },
+        ],
+        outputKind: 'object',
+        effects: ['Deletes remoteCanvas.targets.<name> from config.json.', 'Deletes the stored token under relayTokenRef from the secrets store.'],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const cfg = readConfig(SCOPE);
+        const target = cfg.remoteCanvas.targets[name];
+        if (target === undefined) {
+            throw new InputError({
+                error: 'not_found',
+                message: `no remote canvas target named '${name}'`,
+                next: 'List configured targets with `crtr canvas config list`.',
+            });
+        }
+        updateConfig(SCOPE, (c) => {
+            delete c.remoteCanvas.targets[name];
+        });
+        deleteRelayToken(target.relayTokenRef, SCOPE);
+        return { removed: name };
+    },
+    render: (r) => `Removed remote canvas target '${r['removed']}'.`,
+});
+// ---------------------------------------------------------------------------
+// Export — mounted under `crtr canvas`
+// ---------------------------------------------------------------------------
+export const canvasConfigBranch = defineBranch({
+    name: 'config',
+    description: 'register/list/inspect/remove remote canvas targets',
+    whenToUse: 'setting up or auditing a remote canvas target (preview endpoint + relay token) before selecting one with `crtr canvas use`.',
+    help: {
+        name: 'canvas config',
+        summary: 'manage named remote canvas targets',
+        model: 'A remote canvas target is a preview endpoint + a relay token registered under a name. `add` registers one (token goes to the 0600 secrets store, never config.json); `list`/`show` display masked entries (fingerprint only, never the raw token); `remove` deletes both the config entry and the stored token. Select a target for read commands with `crtr canvas use <name>`, or back to local with `crtr canvas use --local`.',
+    },
+    children: [canvasConfigAdd, canvasConfigList, canvasConfigShow, canvasConfigRemove],
+});

package/dist/commands/canvas-history/grep.d.ts

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

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

@@ -0,0 +1,104 @@
+import { defineLeaf } from '../../core/command.js';
+import { usage } from '../../core/errors.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+import { filterParams, parseFilters } from './shared.js';
+export const grepLeaf = defineLeaf({
+    name: 'grep',
+    description: 'exact regex line search across the cwd\'s node history',
+    whenToUse: 'you know the exact string or pattern you\'re looking for — an error message, a literal identifier, a code fragment — and want every matching body LINE across every node that ran in this cwd, not a relevance ranking. The pattern is required (an ECMAScript regex, case-insensitive). Narrow with --type/--kind/--status/--since, scope elsewhere with --cwd/--all-cwds/--under/--node. Want ranked/browse search instead? Use `canvas history search` — a distinct leaf, not a flag here. Use `canvas history read <ref>` to read a hit\'s full body, `node inspect artifacts <node-id>` to list one node\'s artifacts, and `node lifecycle revive <id>` to reopen a node you found.',
+    help: {
+        name: 'canvas history grep',
+        summary: 'required-pattern regex line search over the per-cwd episodic record (reports + context docs + meta)',
+        params: [
+            { kind: 'positional', name: 'pattern', required: true, constraint: 'An ECMAScript regex, matched case-insensitively against each body line. One hit per matching line.' },
+            ...filterParams,
+            { kind: 'flag', name: 'limit', type: 'int', required: false, default: 20, constraint: 'Page size. Default 20, hard max 100.' },
+            { kind: 'flag', name: 'cursor', type: 'string', required: false, constraint: 'Opaque token from a prior next_cursor; omit on the first call.' },
+        ],
+        output: [
+            { name: 'hits', type: 'object[]', required: true, constraint: '{ref, node, ts, line, text} per matching body line, sorted by ref then line. ref is the <node-id>:<relpath> handle passed verbatim to `canvas history read`.' },
+            { name: 'next_cursor', type: 'string|null', required: true, constraint: 'Token for the next page; null is the only end-of-list signal.' },
+            { name: 'total', type: 'int', required: true, constraint: 'Total matching lines (exact).' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const pattern = (input['pattern'] ?? '').trim();
+        const limit = Math.min(100, Math.max(1, input['limit'] ?? 20));
+        const cursor = input['cursor'];
+        if (pattern === '')
+            throw usage('pattern is required — the regex to match against body lines.');
+        try {
+            const validate = new RegExp(pattern);
+            void validate;
+        }
+        catch {
+            throw usage(`invalid regex pattern: ${pattern}`);
+        }
+        // Filter flag validation stays client-side (pure); the corpus scan +
+        // regex match + pagination run server-side in crtrd (`POST
+        // /v1/canvas/history/grep`) — buildCorpus reaches canvas.db and loadBody
+        // closures cannot cross the wire.
+        const f = parseFilters(input);
+        const q = { pattern, limit };
+        if (f.cwd !== undefined)
+            q.cwd = f.cwd;
+        if (f.allCwds)
+            q.all_cwds = true;
+        if (f.under !== undefined)
+            q.under = f.under;
+        if (f.nodes !== undefined)
+            q.nodes = f.nodes;
+        if (f.types !== undefined)
+            q.types = f.types;
+        if (f.reportKind !== undefined)
+            q.report_kind = f.reportKind;
+        if (f.kinds !== undefined)
+            q.kinds = f.kinds;
+        if (f.statuses !== undefined)
+            q.statuses = f.statuses;
+        if (f.sinceMs !== undefined)
+            q.since_ms = f.sinceMs;
+        if (f.untilMs !== undefined)
+            q.until_ms = f.untilMs;
+        if (cursor !== undefined)
+            q.cursor = cursor;
+        try {
+            const res = await cliClient().historyGrep(q);
+            return {
+                hits: res.hits,
+                next_cursor: res.next_cursor,
+                total: res.total,
+                follow_up: 'Read a hit with `canvas history read <ref>`; narrow with `canvas history grep -h`.',
+            };
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+    },
+    render: (r) => renderGrep(r),
+});
+function renderGrep(r) {
+    const hits = r['hits'];
+    const total = r['total'];
+    const nextCursor = r['next_cursor'];
+    const parts = [];
+    if (hits.length === 0) {
+        parts.push('0 hits.');
+    }
+    else {
+        parts.push(`${hits.length} of ${total} hits:`);
+        const cols = Object.keys(hits[0]);
+        const head = `| ${cols.join(' | ')} |`;
+        const sep = `| ${cols.map(() => '---').join(' | ')} |`;
+        const body = hits
+            .map((h) => `| ${cols.map((c) => String(h[c] ?? '').replace(/\|/g, '\\|').replace(/\n/g, ' ')).join(' | ')} |`)
+            .join('\n');
+        parts.push(`${head}\n${sep}\n${body}`);
+    }
+    parts.push(`- next_cursor: ${nextCursor ?? 'null'}\n- total: ${total}`);
+    parts.push(String(r['follow_up']));
+    return parts.join('\n\n');
+}

package/dist/commands/canvas-history/read.d.ts

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