@north-light/api 0.3.579 → 0.3.587

package/dist/commands/canvas-prune.js

@@ -0,0 +1,111 @@
+// `crtr canvas prune` — bounded retention for the node graph.
+//
+// The canvas never deleted a node before this: dead/done/canceled rows + their
+// `nodes/<id>/` dirs accumulated without limit. `prune` is the retention sweep —
+// remove TERMINAL nodes (dead | done | canceled) last active before a TTL; the
+// edges→nodes FK (ON DELETE CASCADE) GCs their edges, and each node's dir is
+// removed too. crtrd also runs the default TTL sweep itself every 5 minutes.
+// Live nodes (active | idle) and nodes with an open managed worktree are never touched.
+//
+// Exported as a leaf; `crtr canvas` (canvas.ts) mounts it.
+import { defineLeaf } from '../core/command.js';
+import { cliClient, rethrowAsCliError } from './api-client.js';
+const DEFAULT_TTL_DAYS = 2;
+export const canvasPruneLeaf = defineLeaf({
+    name: 'prune',
+    description: 'remove terminal nodes (dead/done/canceled) last active more than a TTL ago',
+    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 last active more than a retention window ago, reclaiming their rows, edges (cascade-deleted by the schema), and `nodes/<id>/` dirs. crtrd already runs the default 2-day sweep of terminal nodes every 5 minutes, so run this by hand for a shorter window, a count cap, --include-stale, or --empty; live nodes (active/idle) and nodes with an open managed worktree are never touched, and you can preview the sweep before it deletes anything',
+    help: {
+        name: 'canvas prune',
+        summary: 'delete terminal nodes last active more than a TTL ago (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 every protected node, plus the most recently active terminal nodes up to N in total, deleting the rest. Active/idle nodes regardless of process state and every node listed under effects as kept are NEVER deleted, so the real floor is max(N, protectedCount). Recency = the latest lifecycle timestamp or telemetry.json mtime. Combine with --dry-run to preview.',
+            },
+            {
+                kind: 'flag',
+                name: 'ttl',
+                type: 'int',
+                required: false,
+                default: DEFAULT_TTL_DAYS,
+                constraint: `Retention window in days: only dead/done/canceled nodes last active more than this many days ago are pruned (last active = the latest lifecycle timestamp or telemetry.json mtime), except the nodes listed under effects as kept. Default: ${DEFAULT_TTL_DAYS}.`,
+            },
+            {
+                kind: 'flag',
+                name: 'include-stale',
+                type: 'bool',
+                required: false,
+                default: false,
+                constraint: 'ALSO prune stale active/idle nodes last active before the TTL whose process is gone (pi_pid null or dead) — reaps abandoned roots the daemon never reconciled. Skipped: a live pi_pid, a node sleeping until it is woken, a node with unseen wake mail, a frozen node, a node in respawn backoff, and every node listed under effects as kept.',
+            },
+            {
+                kind: 'flag',
+                name: 'empty',
+                type: 'bool',
+                required: false,
+                default: false,
+                constraint: 'Instead of the TTL sweep, reap EMPTY nodes — nodes (of any age or status) whose engine never produced an assistant message, the useless shells that just take up graph + disk space. A node mid-first-turn, the caller, and a node with an open managed worktree are spared. Combine with --dry-run to preview.',
+            },
+            {
+                kind: 'flag',
+                name: 'dry-run',
+                type: 'bool',
+                required: false,
+                default: false,
+                constraint: 'Report what WOULD be pruned without deleting anything.',
+            },
+        ],
+        output: [
+            { name: 'pruned', type: 'integer', required: true, constraint: 'How many nodes were pruned (0 under --dry-run since nothing is deleted; the candidate count is in `nodes`).' },
+            { name: 'dryRun', type: 'boolean', required: true, constraint: 'True when nothing was deleted (preview only).' },
+            { name: 'ttlDays', type: 'integer', required: true, constraint: 'The retention window used.' },
+            { name: 'nodes', type: 'object[]', required: true, constraint: 'One per pruned (or, under --dry-run, prunable) node: {node_id,status,created}.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'With --max N: COUNT mode — keep every protected node plus the most recently active terminal nodes up to N in total, deleting the rest; active/idle nodes regardless of process state 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.',
+            'Always kept, in every mode except --empty: the caller, a node with a live or launching engine, a node with durable work that must wake it (subscription, message wait, cron wake, open ticket, output request), a node a person is viewing, a frozen node, an app run (deleted only through the runs API), and a node with an open managed worktree.',
+            'No-op on live nodes (active/idle) and terminal nodes active within the TTL. With --include-stale: also deletes active/idle nodes last active before the TTL whose process is gone and that nothing will wake.',
+            'crtrd runs the default sweep (terminal nodes, 2 days, no --include-stale) automatically every 5 minutes.',
+            'Under --dry-run: read-only, deletes nothing.',
+        ],
+    },
+    run: async (input) => {
+        const ttlDays = input['ttl'] ?? DEFAULT_TTL_DAYS;
+        const dryRun = input['dryRun'] ?? false;
+        const includeStale = input['includeStale'] ?? false;
+        const empty = input['empty'] ?? false;
+        const maxNodes = input['max'];
+        // Precedence COUNT (--max) > EMPTY (--empty) > TTL sweep — the server applies
+        // the same order; sending the winning mode keeps it unambiguous. The prune
+        // itself + target-gone notifications run inside crtrd (it owns the feed).
+        const req = { dry_run: dryRun, ttl_days: ttlDays };
+        if (maxNodes !== undefined)
+            req.limit = maxNodes;
+        else if (empty)
+            req.empty = true;
+        else
+            req.include_stale = includeStale;
+        try {
+            const res = await cliClient().prune(req);
+            return {
+                pruned: res.dry_run ? 0 : res.pruned.length,
+                dryRun: res.dry_run,
+                ttlDays: res.ttl_days,
+                nodes: res.pruned.map((p) => ({
+                    node_id: p.node_id,
+                    status: p.status,
+                    created: p.created,
+                })),
+            };
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+    },
+});

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

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

package/dist/commands/canvas-roster.js

@@ -0,0 +1,69 @@
+import { defineLeaf } from '../core/command.js';
+import { cliClient, rethrowAsCliError } from './api-client.js';
+export const canvasRosterLeaf = defineLeaf({
+    name: 'roster',
+    description: 'emit the lean canvas topology roster as structured data',
+    whenToUse: 'you need a fast, set-based roster of every canvas node + subscription edges (`subscribes_to`) for a browser or viewer poll loop; use `canvas snapshot` for the enriched on-demand view (ctx tokens, streaming, hanging, last activity)',
+    tier: 'hidden',
+    help: {
+        name: 'canvas roster',
+        summary: 'lean, set-based canvas topology roster (recurring poll target)',
+        params: [],
+        output: [
+            { name: 'generated_at', type: 'string', required: true, constraint: 'ISO timestamp when the roster was generated.' },
+            {
+                name: 'nodes',
+                type: 'object[]',
+                required: true,
+                constraint: 'Lean node rows plus attention_count for the returned node set.',
+            },
+            {
+                name: 'subscriptions',
+                type: 'object',
+                required: true,
+                constraint: 'Authoritative subscribes_to adjacency map: each node id maps to its publisher/child node ids in edge order.',
+            },
+            {
+                name: 'edges',
+                type: 'object[]',
+                required: true,
+                constraint: 'Subscription edges with from_id, to_id, active, and created fields.',
+            },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Read-only: two indexed canvas.db scans server-side (nodes, subscription watches) plus a bounded attention-count read for the returned node ids.',
+        ],
+        // Machine-readable dump for the browser/attach roster poll, not for an
+        // agent/human to glance at — collapse it in the attach viewer by default.
+        preview: { suppressOutput: true },
+    },
+    run: async () => {
+        // The lean roster (rosterNodes + rosterEdges, exactly two indexed queries,
+        // no enrichRows/per-row getNode) is built server-side in crtrd
+        // (`GET /v1/canvas/roster`). Attention counts stay a SEPARATE bounded read
+        // (`POST /v1/canvas/attention/counts`) — never folded into the roster query
+        // itself, which must stay indexed-scan-only.
+        const dto = await cliClient().canvasRoster().catch((err) => rethrowAsCliError(err));
+        const ids = dto.nodes.map((n) => n.node_id);
+        let counts = {};
+        try {
+            counts = ids.length > 0 ? (await cliClient().attentionCounts(ids)).counts : {};
+        }
+        catch {
+            // Ticket counts decorate the authoritative roster topology.
+        }
+        const nodes = dto.nodes.map((n) => ({ ...n, attention_count: counts[n.node_id] ?? 0 }));
+        const subscriptions = {};
+        for (const n of dto.nodes)
+            subscriptions[n.node_id] = [];
+        for (const e of dto.edges) {
+            const list = subscriptions[e.from_id];
+            if (list !== undefined)
+                list.push(e.to_id);
+            else
+                subscriptions[e.from_id] = [e.to_id];
+        }
+        return { generated_at: dto.generated_at, nodes, subscriptions, edges: dto.edges };
+    },
+});

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

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

package/dist/commands/canvas-snapshot.js

@@ -0,0 +1,34 @@
+import { defineLeaf } from '../core/command.js';
+import { cliClient, rethrowAsCliError } from './api-client.js';
+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',
+        params: [],
+        output: [
+            { name: 'generated_at', type: 'string', required: true, constraint: 'ISO timestamp when the snapshot was generated.' },
+            { name: 'nodes', type: 'object[]', required: true, constraint: 'NodeSummary rows for browser canvas rendering.' },
+            { name: 'subscriptions', type: 'object', required: true, constraint: 'Authoritative subscribes_to adjacency map: each node id maps to its publisher/child node ids in edge order.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: queries canvas.db, focus rows, telemetry files, and pending human-reply 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 () => {
+        // The enriched roster (dashboardRowsAll + enrichRows) and the subscribes_to
+        // adjacency are built server-side in crtrd (`GET /v1/canvas/snapshot`).
+        try {
+            const dto = await cliClient().canvasSnapshot();
+            return { generated_at: dto.generated_at, nodes: dto.nodes, subscriptions: dto.subscriptions };
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+    },
+});

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

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

package/dist/commands/canvas-use.js

@@ -0,0 +1,61 @@
+// `crtr canvas use` — durably select which remote-capable read commands
+// (such as `node inspect list/show`) default onto: a named remote
+// target, or back to local. A single leaf, not a branch — there is exactly
+// one decision here (pick a target, or go local), not a family of verbs.
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { updateState } from '../core/config.js';
+import { getRemoteCanvasTarget } from '../core/remote-canvas-target.js';
+const SCOPE = 'user';
+export const canvasUseLeaf = defineLeaf({
+    name: 'use',
+    description: 'select the durable default canvas for read commands (a remote target, or local)',
+    whenToUse: 'switching what remote-capable read commands such as `node inspect list/show` read from by default, without passing `--canvas <name>` on every invocation \u2014 select a remote target registered via `crtr canvas config add`, or switch back to local. A command\u2019s own `--canvas <name>` flag always overrides this for that one call.',
+    help: {
+        name: 'canvas use',
+        summary: 'select the durable default canvas (a registered remote target, or local) for read commands',
+        params: [
+            { kind: 'positional', name: 'name', required: false, constraint: 'A remote canvas target registered via `crtr canvas config add`. Mutually exclusive with --local; exactly one of the two is required.' },
+            { kind: 'flag', name: 'local', type: 'bool', required: false, constraint: 'Switch back to the local canvas. Mutually exclusive with <name>.' },
+        ],
+        output: [],
+        outputKind: 'object',
+        effects: ['Writes state.json\u2019s activeCanvas (user scope).'],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const local = input['local'] === true;
+        if (name !== undefined && local) {
+            throw new InputError({
+                error: 'ambiguous_scope',
+                message: '<name> and --local are mutually exclusive',
+                next: 'Pass a target name to go remote, or --local to go local \u2014 not both.',
+            });
+        }
+        if (name === undefined && !local) {
+            throw new InputError({
+                error: 'missing_target',
+                message: 'nothing to select \u2014 pass a target name or --local',
+                next: 'Pass a target name (see `crtr canvas config list`) to go remote, or --local to go local.',
+            });
+        }
+        if (local) {
+            await updateState(SCOPE, (s) => {
+                s.activeCanvas = null;
+            });
+            return {};
+        }
+        if (getRemoteCanvasTarget(name, SCOPE) === undefined) {
+            throw new InputError({
+                error: 'not_found',
+                message: `no remote canvas target named '${name}'`,
+                next: 'List configured targets with `crtr canvas config list`, or register one with `crtr canvas config add`.',
+            });
+        }
+        await updateState(SCOPE, (s) => {
+            s.activeCanvas = name;
+        });
+        return {};
+    },
+    render: () => 'Canvas selection updated.'
+});

package/dist/commands/canvas.d.ts

@@ -0,0 +1,3 @@
+import type { BranchDef } from '../core/command.js';
+export declare const issueBranch: BranchDef;
+export declare function registerCanvas(): BranchDef;

package/dist/commands/canvas.js

@@ -0,0 +1,57 @@
+// `crtr canvas` — observe and supervise the whole graph.
+//
+// Where `node` operates on one node and `push` is a node's own spine write
+// verb, `canvas` is the bird's-eye / supervisor surface over the entire canvas:
+// render the subscription forest (`dashboard`), see who is blocked on a human
+// (`attention`), and mass-reconnect disconnected nodes (`revive --all`). It assembles leaves/branches
+// the sibling command files own, so each piece declares its own help one level
+// down.
+import { defineBranch } from '../core/command.js';
+import { dashboardLeaf } from './dashboard.js';
+import { canvasSnapshotLeaf } from './canvas-snapshot.js';
+import { canvasRosterLeaf } from './canvas-roster.js';
+import { browseLeaf } from './canvas-browse.js';
+import { reviveLeaf } from './revive.js';
+import { attentionBranch } from './attention.js';
+import { chordLeaf } from './chord.js';
+import { canvasPruneLeaf } from './canvas-prune.js';
+import { historyBranch } from './canvas-history.js';
+import { issueNewLeaf } from './canvas-issue.js';
+import { canvasConfigBranch } from './canvas-config.js';
+import { canvasUseLeaf } from './canvas-use.js';
+import { readLeaf } from './canvas/read.js';
+import { listLeaf } from './canvas/list.js';
+import { searchLeaf } from './canvas/search.js';
+import { watchLeaf } from './canvas/watch.js';
+import { unwatchLeaf } from './canvas/unwatch.js';
+import { shareLeaf } from './canvas/share.js';
+import { edgesLeaf } from './canvas/edges.js';
+import { analyticsLeaf } from './canvas-analytics.js';
+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',
+        model: 'Quick brain-dump capture, bound to the alt+c \u2192 i \u2192 (idea|bug) prefix chord. `new` reads a free-text note, auto-generates the title via a headless pi call, and files it with `gh issue create --label <type>` when the pane\u2019s cwd is a GitHub repo, else writes `<git-root>/.todos/<slug>.md`. Meant for the chord/popup, not hand-running.',
+    },
+    children: [issueNewLeaf],
+});
+export function registerCanvas() {
+    return defineBranch({
+        name: 'canvas',
+        rootEntry: {
+            concept: 'every object in the agent graph — documents, nodes, jobs and their owners — read, listed, searched and watched by name, plus the whole-graph views: `dashboard` prints the subscription tree once, `browse` is the interactive navigator, `attention` shows who is blocked, `revive --all` mass-revives disconnected nodes',
+            desc: 'read, list, search and watch objects; whole-graph views and supervision',
+            useWhen: 'reading a document, node or job by name, finding one you cannot name, watching an object for changes, surveying the full graph, finding blocked agents, or mass-reviving every disconnected node; documents are written with `crtr doc`; run `crtr canvas -h`',
+        },
+        help: {
+            name: 'canvas',
+            summary: 'read, find and watch objects; observe and supervise the whole agent graph',
+            model: 'Every document, node, bash job and owner (person, app, repo, plugin, profile) is an object with an id and a name, and the same verbs work on all of them. `read` returns one object by name or id and makes you a watcher of it; `list` filters objects by type, kind, owner, privacy or name prefix; `search` finds them by text; `edges` shows what an object links to, who acted on it and who watches it; `watch`/`unwatch` add or remove your watch without reading. `list`, `search` and `edges` record nothing. Documents are written, edited and moved with `crtr doc`, and pointed at as `[[name]]`. Canvas-wide views, 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 over the whole canvas and resumes the chosen node; `attention` aggregates pending replies from the user across the graph; `revive --all` mass-reconnects every disconnected node (bringing back ONE named node is `node lifecycle revive <id>` instead); `history` searches past node conversations; `prune` bounds growth by deleting terminal nodes past a TTL; `analytics` opens the read-only Analytics page (graph sizes, agent time, document reads, API-price estimate) for a person. `config` registers/lists remote canvas targets (preview endpoint + relay token); `use` switches remote-capable read commands such as `node inspect` onto a configured target or back to local.',
+        },
+        children: [readLeaf, listLeaf, searchLeaf, watchLeaf, unwatchLeaf, shareLeaf, edgesLeaf, dashboardLeaf, canvasSnapshotLeaf, canvasRosterLeaf, browseLeaf, attentionBranch, reviveLeaf, historyBranch, chordLeaf, issueBranch, canvasPruneLeaf, canvasConfigBranch, canvasUseLeaf, analyticsLeaf],
+    });
+}

package/dist/commands/chord.d.ts

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

package/dist/commands/chord.js

@@ -0,0 +1,241 @@
+// `crtr canvas chord` — the tmux prefix-menu dispatcher.
+//
+// The alt+c display-menu can't see the cursor node or read config at popup time
+// — it only knows the active pane. So the menu hands this leaf a resolved `--run`
+// string plus the originating pane id; this dispatcher resolves the node in that
+// pane, interpolates the node vars, and execs `crtr <argv>` with no shell.
+//
+// execFile/spawn (never `sh -c`) keeps the argv literal, so shell metacharacters
+// in config data cannot inject.
+import { spawn, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { cliCanvasSource, getNodeOrNull } from './api-client.js';
+import { fullName } from '../core/canvas/labels.js';
+import { getPaneOption } from '../core/runtime/tmux-chrome.js';
+const pexec = promisify(execFile);
+/** The live node whose viewer pane carries the `@crtr_node` tag. Reimplemented
+ *  here rather than importing node.ts's `nodeInPane` (which reaches openDb via the
+ *  canvas accessors) so this dispatcher's import graph stays db-free. Under the
+ *  headless-broker model every engine runs DETACHED (window=null), so the pane tag
+ *  is the ONLY node handle. A stale tag is ignored
+ *  (the tagged node must still be live), validated through the daemon API. */
+async function nodeInPane(pane) {
+    if (pane === undefined || pane === '')
+        return undefined;
+    const tagged = getPaneOption(pane, '@crtr_node');
+    if (tagged === undefined || tagged === '')
+        return undefined;
+    const meta = await getNodeOrNull(tagged);
+    if (meta !== null && (meta.status === 'active' || meta.status === 'idle'))
+        return tagged;
+    return undefined;
+}
+/** Template vars available to a `run` string. Single-valued vars interpolate
+ *  in place (preserving spaces, e.g. a node name); `{pane}` is the active tmux
+ *  pane id; `{subtree}` is multi-valued and a bare `{subtree}` token expands to
+ *  several argv elements. */
+async function buildVars(selfId, pane) {
+    const source = cliCanvasSource();
+    const [node, subs, viewIds] = await Promise.all([
+        source.getNode(selfId),
+        source.subscribersOf(selfId),
+        source.view(selfId),
+    ]);
+    const manager = subs[0]?.node_id ?? '';
+    return {
+        id: selfId,
+        self: selfId,
+        pane,
+        lane: selfId,
+        name: node !== null ? fullName(node) : selfId,
+        manager,
+        subtree: viewIds.join(' '),
+    };
+}
+function parseRun(run) {
+    const out = [];
+    let cur = '';
+    let quoted = null;
+    let escaped = false;
+    let inToken = false;
+    const push = () => {
+        if (!inToken)
+            return;
+        out.push(cur);
+        cur = '';
+        inToken = false;
+    };
+    for (let i = 0; i < run.length; i++) {
+        const ch = run[i];
+        if (escaped) {
+            cur += ch;
+            inToken = true;
+            escaped = false;
+            continue;
+        }
+        if (quoted === 'single') {
+            if (ch === "'") {
+                quoted = null;
+            }
+            else {
+                cur += ch;
+                inToken = true;
+            }
+            continue;
+        }
+        if (quoted === 'double') {
+            if (ch === '"') {
+                quoted = null;
+            }
+            else if (ch === '\\') {
+                escaped = true;
+            }
+            else {
+                cur += ch;
+                inToken = true;
+            }
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            push();
+            continue;
+        }
+        if (ch === "'") {
+            quoted = 'single';
+            inToken = true;
+            continue;
+        }
+        if (ch === '"') {
+            quoted = 'double';
+            inToken = true;
+            continue;
+        }
+        if (ch === '\\') {
+            escaped = true;
+            inToken = true;
+            continue;
+        }
+        cur += ch;
+        inToken = true;
+    }
+    if (escaped) {
+        cur += '\\';
+        inToken = true;
+    }
+    if (quoted !== null) {
+        throw new InputError({
+            error: 'bad_run',
+            message: 'invalid canvas run string: unterminated quote',
+            next: 'Fix the bind in config.json and try again.',
+        });
+    }
+    push();
+    return out;
+}
+/** Split a `run` string argv-style and interpolate the template vars. A bare
+ *  `{subtree}` token expands to several argv elements; every other placeholder
+ *  is substituted in place (kept as one element so a multi-word name survives
+ *  as a single argument under execFile). */
+function interpolateArgv(run, vars) {
+    const out = [];
+    for (const tok of parseRun(run)) {
+        if (tok === '{subtree}') {
+            for (const part of (vars['subtree'] ?? '').split(/\s+/).filter((p) => p !== ''))
+                out.push(part);
+            continue;
+        }
+        out.push(tok.replace(/\{(\w+)\}/g, (_, name) => vars[name] ?? ''));
+    }
+    return out;
+}
+async function dispatch(argv, interactive) {
+    if (argv.length === 0)
+        return;
+    if (interactive) {
+        await new Promise((resolve) => {
+            try {
+                const child = spawn('crtr', argv, { stdio: 'inherit' });
+                child.once('error', () => resolve());
+                child.once('close', () => resolve());
+            }
+            catch {
+                resolve();
+            }
+        });
+        return;
+    }
+    try {
+        await pexec('crtr', argv, { timeout: 15_000 });
+    }
+    catch {
+        /* best-effort: the keystroke just acts; errors are surfaced by the inner cmd */
+    }
+}
+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.',
+        params: [
+            {
+                kind: 'flag',
+                name: 'pane',
+                type: 'string',
+                required: false,
+                constraint: 'tmux pane id whose node the chord acts on. Defaults to $TMUX_PANE / your current pane.',
+            },
+            {
+                kind: 'flag',
+                name: 'run',
+                type: 'string',
+                required: true,
+                constraint: 'The argv string to run as crtr, after node vars resolve.',
+            },
+            {
+                kind: 'flag',
+                name: 'interactive',
+                type: 'bool',
+                required: false,
+                constraint: 'When true, inherit stdio so popup forms can read from the popup tty.',
+            },
+        ],
+        output: [
+            { name: 'ran', type: 'boolean', required: true, constraint: 'True when an action was dispatched.' },
+            { name: 'node_id', type: 'string', required: false, constraint: 'The node the chord resolved against.' },
+            { name: 'action', type: 'string', required: false, constraint: 'What ran: a crtr argv string or "noop".' },
+        ],
+        outputKind: 'object',
+        effects: ['Runs a `crtr` subcommand per the resolved bind.'],
+    },
+    run: async (input) => {
+        const rawPane = input['pane'];
+        const pane = rawPane !== undefined && rawPane !== '' ? rawPane : process.env['TMUX_PANE'];
+        const run = input['run']?.trim();
+        const interactive = input['interactive'] === true;
+        if (run === undefined || run === '') {
+            throw new InputError({
+                error: 'missing_run',
+                message: 'no run string provided',
+                next: 'Pass --run <argv-string> from the menu renderer.',
+            });
+        }
+        const selfId = await nodeInPane(pane);
+        if (selfId === undefined) {
+            throw new InputError({
+                error: 'no_node',
+                message: 'no node found in this pane',
+                next: 'Run from inside an agent\'s pane, or pass --pane <pane-id>.',
+            });
+        }
+        const argv = interpolateArgv(run, await buildVars(selfId, pane ?? ''));
+        if (argv.length === 0)
+            return { ran: false, node_id: selfId, action: 'noop' };
+        await dispatch(argv, interactive);
+        return { ran: true, node_id: selfId, action: `crtr ${argv.join(' ')}` };
+    },
+});

package/dist/commands/cron.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerCron(): BranchDef;