@north-light/crouter 0.3.154

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

@@ -0,0 +1,48 @@
+import { defineLeaf } from '../../core/command.js';
+import { usage } from '../../core/errors.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+export const readLeaf = defineLeaf({
+    name: 'read',
+    description: 'read one search hit\'s full body by its ref',
+    whenToUse: 'you picked a hit from `canvas history search` (or `node inspect artifacts`) and want its full content — pass the `<node-id>:<relpath>` ref verbatim. Strips frontmatter by default; add --frontmatter to keep the YAML header.',
+    help: {
+        name: 'canvas history read',
+        summary: 'resolve a <node-id>:<relpath> ref to its full artifact body',
+        params: [
+            { kind: 'positional', name: 'ref', required: true, constraint: 'The <node-id>:<relpath> handle from `canvas history search` (e.g. mq186ky0-c754531c:reports/20260607T075536-final.md, or <node-id>:meta for a node\'s identity).' },
+            { kind: 'flag', name: 'frontmatter', type: 'bool', required: false, constraint: 'Include the artifact\'s YAML frontmatter. Stripped by default.' },
+        ],
+        output: [
+            { name: 'ref', type: 'string', required: true, constraint: 'Echo of the resolved ref.' },
+            { name: 'node', type: 'string', required: true, constraint: 'Node name + id.' },
+            { name: 'source', type: 'string', required: true, constraint: 'report | doc | roadmap | meta (+ report-kind for reports).' },
+            { name: 'ts', type: 'string', required: true, constraint: 'Artifact timestamp.' },
+            { name: 'content', type: 'string', required: true, constraint: 'Full body. Frontmatter stripped unless --frontmatter.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const ref = input['ref'].trim();
+        const includeFrontmatter = input['frontmatter'] === true;
+        // Fast local shape check; ref resolution (+ its usage/not-found errors) runs
+        // server-side in crtrd (`GET /v1/canvas/history/read`).
+        if (!ref.includes(':')) {
+            throw usage(`ref must be <node-id>:<relpath>; received: ${ref}`, {
+                received: ref,
+                next: 'Get a valid ref from `canvas history search` or `node inspect artifacts <node-id>`.',
+            });
+        }
+        try {
+            const res = await cliClient().historyRead({ ref, frontmatter: includeFrontmatter });
+            return { ref: res.ref, node: res.node, source: res.source, ts: res.ts, content: res.content };
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+    },
+    render: (r) => {
+        const head = `${r['node']}  |  source: ${r['source']}  |  ts: ${r['ts']}  |  ref: ${r['ref']}`;
+        return `${head}\n\n${String(r['content']).trim()}`;
+    },
+});

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

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

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

@@ -0,0 +1,118 @@
+import { defineLeaf } from '../../core/command.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+import { filterParams, parseFilters } from './shared.js';
+const SORTS = ['relevance', 'recency', 'oldest'];
+export const searchLeaf = defineLeaf({
+    name: 'search',
+    description: 'ranked content search across the cwd\'s node history',
+    whenToUse: 'you want to find past work by what it SAYS — a design, a final report, a roadmap, a finding — across every node that ran in this cwd, ranked by relevance. Omit the query to browse the record by recency ("what happened here lately"). Narrow with --type/--kind/--status/--since, scope elsewhere with --cwd/--all-cwds/--under/--node. Need an exact regex over bodies instead of ranking? Use `canvas history grep` — a distinct leaf, not a flag here. Use `canvas history read <ref>` to read a hit in full, `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 search',
+        summary: 'ranked/filtered/sorted content search over the per-cwd episodic record (reports + context docs + meta)',
+        params: [
+            { kind: 'positional', name: 'query', required: false, constraint: 'Whitespace-separated terms, matched case-insensitively and weighted across node name/description, report titles, and doc headings (and full bodies with --body); artifacts matching more/stronger fields rank higher. Omit to browse by recency (no relevance ranking; --sort still applies).' },
+            ...filterParams,
+            { kind: 'flag', name: 'body', type: 'bool', required: false, constraint: 'Also weigh full body text in the ranking (default weighs name/title/heading only).' },
+            { kind: 'flag', name: 'sort', type: 'enum', choices: SORTS, required: false, constraint: 'relevance (default with a query) ranks by score; recency (default without a query) / oldest order by artifact timestamp.' },
+            { kind: 'flag', name: 'snippet-lines', type: 'int', required: false, default: 1, constraint: 'Context lines per hit. Default 1.' },
+            { kind: 'flag', name: 'full', type: 'bool', required: false, constraint: 'Inline each hit\'s full body. Off by default; pair with a small --limit.' },
+            { 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: 'Ranked/sorted hits, each: {ref, node, kind, source, ts, score?, snippet}. 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 artifacts (exact).' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const query = (input['query'] ?? '').trim();
+        const weighBody = input['body'] === true;
+        const full = input['full'] === true;
+        const snippetLines = Math.max(1, input['snippetLines'] ?? 1);
+        const limit = Math.min(100, Math.max(1, input['limit'] ?? 20));
+        const cursor = input['cursor'];
+        // Filter flag validation stays client-side (pure); the corpus scan +
+        // ranking + pagination run server-side in crtrd (`POST
+        // /v1/canvas/history/search`) — buildCorpus reaches canvas.db and
+        // loadBody closures cannot cross the wire.
+        const f = parseFilters(input);
+        const terms = query.toLowerCase().split(/\s+/).filter((t) => t.length > 0);
+        const sortMode = input['sort'] ?? (terms.length > 0 ? 'relevance' : 'recency');
+        const q = { snippet_lines: snippetLines, limit, sort: sortMode };
+        if (query !== '')
+            q.query = query;
+        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 (weighBody)
+            q.weigh_body = true;
+        if (full)
+            q.full = true;
+        if (cursor !== undefined)
+            q.cursor = cursor;
+        try {
+            const res = await cliClient().historySearch(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 search -h`.',
+            };
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+    },
+    render: (r) => renderSearch(r),
+});
+function renderSearch(r) {
+    const hits = r['hits'];
+    const total = r['total'];
+    const nextCursor = r['next_cursor'];
+    const full = hits.length > 0 && Object.prototype.hasOwnProperty.call(hits[0], 'body');
+    const parts = [];
+    if (hits.length === 0) {
+        parts.push('0 hits.');
+    }
+    else if (full) {
+        parts.push(`${hits.length} of ${total} hits:`);
+        for (const h of hits) {
+            const head = `### ${h['ref']}\n- node: ${h['node']}  |  kind: ${h['kind']}  |  source: ${h['source']}  |  ts: ${h['ts']}`;
+            parts.push(`${head}\n\n${String(h['body'] ?? '').trim()}`);
+        }
+    }
+    else {
+        parts.push(`${hits.length} of ${total} hits:`);
+        const cols = Object.keys(hits[0]).filter((c) => c !== 'body');
+        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/shared.d.ts

@@ -0,0 +1,27 @@
+import type { InputParam } from '../../core/help.js';
+export declare const TYPES: string[];
+export declare const NODE_KINDS: string[];
+export declare const STATUSES: string[];
+/** ISO 8601 (`2026-06-01`) \u2192 epoch ms (absolute); relative (`7d`, `2w`, `1mo`)
+ *  \u2192 now minus the duration. Throws usage on an unparseable value. */
+export declare function parseWhen(field: string, raw: string): number;
+export declare function splitCsv(v: string | undefined): string[] | undefined;
+/** The scope/filter param schema shared by search and grep help \u2014 everything
+ *  except the query/pattern positional and each leaf's own result-shaping
+ *  flags (search: --body/--sort/--snippet-lines/--full; grep: none). */
+export declare const filterParams: InputParam[];
+export interface ParsedFilters {
+    cwd: string | undefined;
+    allCwds: boolean;
+    under: string | undefined;
+    nodes: string[] | undefined;
+    types: string[] | undefined;
+    reportKind: string | undefined;
+    kinds: string[] | undefined;
+    statuses: string[] | undefined;
+    sinceMs: number | undefined;
+    untilMs: number | undefined;
+}
+/** Parse + validate the shared scope/filter flags from a leaf's raw input.
+ *  Pure and client-side; the corpus scan itself runs server-side in crtrd. */
+export declare function parseFilters(input: Record<string, unknown>): ParsedFilters;

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

@@ -0,0 +1,76 @@
+// Shared corpus/filter parsing between `canvas history search` and
+// `canvas history grep` \u2014 both leaves scope + filter the same per-cwd episodic
+// corpus (search ranks/browses it, grep line-matches it), so the scope/filter
+// flags, their param schemas, and their CLI-side parsing/validation are one
+// seam. This is internal reuse only: neither leaf's public flag set or output
+// shape is shared, and nothing here is re-exported as a command alias.
+import { usage } from '../../core/errors.js';
+export const TYPES = ['report', 'doc', 'roadmap', 'meta', 'inbox'];
+export const NODE_KINDS = ['advisor', 'developer', 'spec', 'design', 'review', 'explore', 'plan', 'general'];
+export const STATUSES = ['active', 'idle', 'done', 'dead', 'canceled'];
+const REL_UNITS = {
+    s: 1000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+    w: 604_800_000,
+    mo: 2_592_000_000,
+    y: 31_536_000_000,
+};
+/** ISO 8601 (`2026-06-01`) \u2192 epoch ms (absolute); relative (`7d`, `2w`, `1mo`)
+ *  \u2192 now minus the duration. Throws usage on an unparseable value. */
+export function parseWhen(field, raw) {
+    const rel = raw.match(/^(\d+)(mo|[smhdwy])$/);
+    if (rel !== null)
+        return Date.now() - Number(rel[1]) * REL_UNITS[rel[2]];
+    const abs = Date.parse(raw);
+    if (!Number.isNaN(abs))
+        return abs;
+    throw usage(`--${field} must be ISO 8601 (2026-06-01) or relative (7d, 2w, 1mo); received: ${raw}`);
+}
+export function splitCsv(v) {
+    if (v === undefined || v === '')
+        return undefined;
+    return v.split(',').map((s) => s.trim()).filter((s) => s !== '');
+}
+/** The scope/filter param schema shared by search and grep help \u2014 everything
+ *  except the query/pattern positional and each leaf's own result-shaping
+ *  flags (search: --body/--sort/--snippet-lines/--full; grep: none). */
+export const filterParams = [
+    { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Search another project\'s record. Default: the calling node\'s cwd (process cwd when not a node). Mutually exclusive with --all-cwds.' },
+    { kind: 'flag', name: 'all-cwds', type: 'bool', required: false, constraint: 'Search every cwd on the canvas. Mutually exclusive with --cwd.' },
+    { kind: 'flag', name: 'under', type: 'string', required: false, constraint: 'Restrict to a node and its subscription descendants (one initiative / sub-DAG).' },
+    { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Restrict to specific node ids. Comma-separated for several.' },
+    { kind: 'flag', name: 'type', type: 'string', required: false, constraint: `Corpus to search; comma-separated for several. One of: ${TYPES.join(', ')}. report = push history; doc = context artifacts; roadmap = roadmap.md specifically; meta = node name/description/kind; inbox = raw inbox.jsonl history, cursor-independent and including full un-clipped direct-message bodies (diagnostic, not curated work). Default: report, doc, roadmap, meta \u2014 inbox is opt-in only, pass --type inbox explicitly.` },
+    { kind: 'flag', name: 'report-kind', type: 'enum', choices: ['final', 'update'], required: false, constraint: 'Narrow reports to outcome summaries (final) or progress (update). Implies --type report.' },
+    { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: `Node kind; comma-separated for several. One of: ${NODE_KINDS.join(', ')}.` },
+    { kind: 'flag', name: 'status', type: 'string', required: false, constraint: `Node lifecycle status; comma-separated for several. One of: ${STATUSES.join(', ')} (e.g. done = completed work only).` },
+    { kind: 'flag', name: 'since', type: 'string', required: false, constraint: 'Lower bound on artifact timestamp. ISO 8601 (2026-06-01) or relative (7d, 2w, 1mo).' },
+    { kind: 'flag', name: 'until', type: 'string', required: false, constraint: 'Upper bound on artifact timestamp. ISO 8601 or relative.' },
+];
+/** Parse + validate the shared scope/filter flags from a leaf's raw input.
+ *  Pure and client-side; the corpus scan itself runs server-side in crtrd. */
+export function parseFilters(input) {
+    const cwd = input['cwd'];
+    const allCwds = input['allCwds'] === true;
+    if (cwd !== undefined && allCwds)
+        throw usage('--cwd and --all-cwds are mutually exclusive.');
+    const types = splitCsv(input['type']);
+    if (types !== undefined) {
+        const bad = types.find((t) => !TYPES.includes(t));
+        if (bad !== undefined)
+            throw usage(`--type must be one of: ${TYPES.join(', ')}; received: ${bad}`);
+    }
+    return {
+        cwd,
+        allCwds,
+        under: input['under'],
+        nodes: splitCsv(input['node']),
+        types,
+        reportKind: input['reportKind'],
+        kinds: splitCsv(input['kind']),
+        statuses: splitCsv(input['status']),
+        sinceMs: input['since'] !== undefined ? parseWhen('since', input['since']) : undefined,
+        untilMs: input['until'] !== undefined ? parseWhen('until', input['until']) : undefined,
+    };
+}

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

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

package/dist/commands/canvas-history.js

@@ -0,0 +1,30 @@
+// `canvas history` — search and recall the cwd-wide content corpus: ranked
+// search over every node's reports/context docs, plus reading one hit's full
+// body by ref. One node's own artifact listing lives at `node inspect
+// artifacts` (a single-node read, not a graph-wide one). Distinct from `crtr
+// memory`, which is curated semantic knowledge held independent of any episode.
+// This branch owns CONTENT; it never duplicates the graph (use `node lifecycle
+// revive` to reopen a found node, `node inspect show` for its topology).
+import { defineBranch } from '../core/command.js';
+import { searchLeaf } from './canvas-history/search.js';
+import { grepLeaf } from './canvas-history/grep.js';
+import { readLeaf } from './canvas-history/read.js';
+/** A tiny per-cwd `<corpus>` marker for branch -h — just enough context to
+ *  anchor the help text without scanning nodes or files. Uses only the injected
+ *  node cwd env (or the process cwd outside a node), so help stays cheap. */
+function corpusBlock() {
+    const cwd = process.env['CRTR_NODE_CWD'] ?? process.cwd();
+    return `<corpus cwd="${cwd}"/>`;
+}
+export const historyBranch = defineBranch({
+    name: 'history',
+    description: 'search and recall the cwd-wide content corpus — every node\'s reports and context docs',
+    whenToUse: 'you want to find or re-read what was DONE in a cwd — a past design, a final report, a roadmap, a finding — across every node that ran there, WITHOUT already knowing which node. Use it when picking up prior work ("that caching work from last week"), recovering an artifact, or surveying a project\'s history. Already have the node id and just want everything IT left behind? Use `node inspect artifacts <id>` instead — this branch is the cwd-wide search corpus, not a per-node listing. Distinct from `crtr memory` (curated semantic knowledge, not episodes) and from `canvas dashboard`/`node inspect` (graph topology, not content).',
+    help: {
+        name: 'canvas history',
+        summary: 'search and recall the cwd-wide content corpus — every node\'s reports and context docs in this cwd',
+        model: 'The accumulated record of every node that ran in a cwd and the artifacts it left — its reports (final/update outcome summaries) and context docs (specs, designs, roadmaps, findings). `search` finds by content (ranked, filtered, sorted; omit the query to browse by recency); `grep` finds by an exact ECMAScript regex over body lines (pattern required, one hit per matching line — use this over `search` when you know the literal string/pattern, not just the topic); `read` pulls one hit\'s full body by its <node-id>:<relpath> ref. This is the episodic record of what was DONE — distinct from `crtr memory`, which is curated semantic knowledge. Already have a node id and want everything IT left behind (not a cwd-wide search)? Use `node inspect artifacts <node-id>` instead — that single-node listing moved out of this branch. A node\'s raw inbox history (`--type inbox`) is a separate, opt-in diagnostic corpus — the full cursor-independent inbox.jsonl for one node, including un-clipped direct-message bodies; reach for it only when the curated reports/docs above don\'t already answer the question. To reopen a node you found, use `node lifecycle revive`; for its place in the graph, `node inspect show`.',
+        dynamicState: corpusBlock,
+    },
+    children: [searchLeaf, grepLeaf, readLeaf],
+});

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

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

package/dist/commands/canvas-issue.js

@@ -0,0 +1,149 @@
+// `crtr canvas issue new` — capture a quick todo/idea/bug into a GitHub issue.
+//
+// Bound to the alt+c → i → (idea|bug) prefix chord: the menu opens a tmux
+// display-popup that runs this leaf in the originating pane's cwd (the popup is
+// started with `-d #{pane_current_path}`). The leaf:
+//   1. reads a free-text note from the popup's TTY (type, Ctrl-D to submit),
+//   2. asks pi headlessly for a concise issue title (same machinery as node
+//      auto-naming; falls back to the note's first line),
+//   3. files it — `gh issue create --label <type>` when the cwd is a GitHub
+//      repo, else a `<git-root>/.todos/<slug>.md` markdown note with frontmatter,
+//   4. flashes a tmux status-line toast confirming where it landed.
+//
+// The popup is opened with `-E`, so it auto-closes when this leaf exits; the
+// toast is the durable confirmation channel. Prompts/status go to stderr so the
+// rendered result (stdout) stays clean.
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { generateIssueTitle, titleSlug } from '../core/runtime/naming.js';
+import { displayMessage, paneCurrentPath } from '../core/runtime/tmux-chrome.js';
+/** Issue types the capture chord offers — each maps to a GitHub label. */
+const TYPES = {
+    idea: { color: 'a2eeef', description: 'Captured idea / enhancement' },
+    bug: { color: 'd73a4a', description: 'Captured bug report' },
+};
+/** Read the whole note from stdin, TTY or pipe alike, until EOF (Ctrl-D in the
+ *  popup). The framework's stdin param can't be used here: it short-circuits to
+ *  '' when stdin is a TTY, which is exactly the popup case. */
+function readNote() {
+    return new Promise((resolve) => {
+        const chunks = [];
+        process.stdin.on('data', (c) => chunks.push(c));
+        process.stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        process.stdin.on('error', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        process.stdin.resume();
+    });
+}
+/** Run a command in `cwd`, capturing stdout. Returns null on any non-zero exit
+ *  or spawn failure (so callers can branch on "is this a gh repo"). */
+function run(cmd, args, cwd) {
+    try {
+        const r = spawnSync(cmd, args, { cwd, encoding: 'utf8' });
+        if (r.status !== 0 || typeof r.stdout !== 'string')
+            return null;
+        return r.stdout.trim();
+    }
+    catch {
+        return null;
+    }
+}
+/** The GitHub `owner/repo` for `cwd`, or null when it is not a gh-resolvable
+ *  repo (no git remote, no gh auth, gh absent). */
+function ghRepo(cwd) {
+    const r = run('gh', ['repo', 'view', '--json', 'nameWithOwner', '-q', '.nameWithOwner'], cwd);
+    return r !== null && r !== '' ? r : null;
+}
+/** Best-effort: ensure the `<type>` label exists before creating the issue
+ *  (gh issue create fails on an unknown label). Ignores "already exists". */
+function ensureLabel(cwd, type) {
+    const { color, description } = TYPES[type];
+    spawnSync('gh', ['label', 'create', type, '--color', color, '--description', description], { cwd, encoding: 'utf8' });
+}
+export const issueNewLeaf = defineLeaf({
+    name: 'new',
+    description: 'capture a todo/idea/bug note into a GitHub issue (or a .todos/ markdown note)',
+    whenToUse: 'the alt+c \u2192 i chord runs this inside a tmux popup; rarely run by hand',
+    tier: 'hidden',
+    help: {
+        name: 'canvas issue new',
+        summary: 'Capture a free-text note as a GitHub issue labeled with its type (idea|bug). Reads the note from the popup TTY, auto-generates the title via a headless pi call, and files it with `gh issue create` when the cwd is a GitHub repo, else writes `<git-root>/.todos/<slug>.md`. Bound to the alt+c \u2192 i prefix chord.',
+        params: [
+            { 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.' },
+        ],
+        output: [
+            { name: 'created', type: 'boolean', required: true, constraint: 'True when a note was filed.' },
+            { name: 'target', type: 'string', required: false, constraint: 'Where it landed: "github" or "file".' },
+            { name: 'type', type: 'string', required: false, constraint: 'The issue type/label.' },
+            { name: 'title', type: 'string', required: false, constraint: 'The generated issue title.' },
+            { name: 'url', type: 'string', required: false, constraint: 'Issue URL when target is github.' },
+            { name: 'path', type: 'string', required: false, constraint: 'File path when target is file.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Creates a GitHub issue via `gh issue create` (and the label if missing), OR writes a markdown note under `<git-root>/.todos/`.',
+            'Flashes a tmux status-line toast confirming the capture.',
+        ],
+    },
+    run: async (input) => {
+        const type = input['type']?.trim();
+        if (type === undefined || !(type in TYPES)) {
+            throw new InputError({
+                error: 'bad_type',
+                message: `unknown issue type: ${String(input['type'])}`,
+                field: 'type',
+                next: `Valid types: ${Object.keys(TYPES).join(' | ')}.`,
+            });
+        }
+        const pane = input['pane'] ?? process.env['TMUX_PANE'];
+        const cwd = input['cwd'] ??
+            (pane !== undefined && pane !== '' ? paneCurrentPath(pane) ?? undefined : undefined) ??
+            process.cwd();
+        let note = input['body'] ?? '';
+        if (note === '') {
+            process.stderr.write(`New ${type} \u2014 type your note, then Ctrl-D to submit (Ctrl-C to cancel):\n\n`);
+            note = await readNote();
+        }
+        note = note.trim();
+        if (note === '') {
+            displayMessage('crtr: nothing captured \u2014 empty note', pane);
+            return { created: false };
+        }
+        process.stderr.write('\nCreating\u2026\n');
+        const title = await generateIssueTitle(note);
+        const repo = ghRepo(cwd);
+        if (repo !== null) {
+            ensureLabel(cwd, type);
+            const url = run('gh', ['issue', 'create', '--title', title, '--body', note, '--label', type], cwd);
+            if (url !== null && url !== '') {
+                displayMessage(`crtr: \u2713 ${type} filed \u2192 ${url}`, pane, 5000);
+                return { created: true, target: 'github', type, title, url };
+            }
+            // gh failed mid-create (e.g. auth/network) — fall through to a local note
+            // so the capture is never lost.
+            process.stderr.write('gh issue create failed; saving a local .todos note instead\n');
+        }
+        // No GitHub repo (or gh failed): write a markdown note at the git root.
+        const root = run('git', ['rev-parse', '--show-toplevel'], cwd) ?? cwd;
+        const dir = join(root, '.todos');
+        const stamp = new Date().toISOString();
+        const fileStamp = stamp.replace(/[:.]/g, '-').replace('T', '_').slice(0, 19);
+        const path = join(dir, `${fileStamp}-${titleSlug(title)}.md`);
+        const frontmatter = `---\ntype: ${type}\ntitle: ${JSON.stringify(title)}\ncreated: ${stamp}\nstatus: open\n---\n\n${note}\n`;
+        try {
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(path, frontmatter, 'utf8');
+        }
+        catch (e) {
+            displayMessage(`crtr: failed to save note: ${e.message}`, pane, 5000);
+            throw new InputError({ error: 'write_failed', message: `could not write ${path}`, next: 'Check directory permissions.' });
+        }
+        displayMessage(`crtr: \u2713 ${type} saved \u2192 .todos/${fileStamp}-${titleSlug(title)}.md`, pane, 5000);
+        return { created: true, target: 'file', type, title, path };
+    },
+});

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

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

package/dist/commands/canvas-prune.js

@@ -0,0 +1,108 @@
+// `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) older than a TTL; the edges→nodes
+// FK (ON DELETE CASCADE) GCs their edges, and each node's dir is removed too.
+// 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 = 14;
+export const canvasPruneLeaf = defineLeaf({
+    name: 'prune',
+    description: 'remove terminal nodes (dead/done/canceled) older than a TTL',
+    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) 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 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 the N most-recently-active nodes plus every protected node, deleting the oldest remaining terminal nodes. Active/idle nodes regardless of process state and nodes with an open managed worktree are NEVER deleted, so the real floor is max(N, protectedCount). Recency = telemetry.json mtime, falling back to created. 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 created more than this many days ago are pruned, except nodes with an open managed worktree. Default: ${DEFAULT_TTL_DAYS}.`,
+            },
+            {
+                kind: 'flag',
+                name: 'include-stale',
+                type: 'bool',
+                required: false,
+                default: false,
+                constraint: 'ALSO prune stale active/idle nodes past the TTL whose process is gone (pi_pid null or dead) — reaps abandoned roots the daemon never reconciled. A genuinely-running node (live pi_pid), a node with an open managed worktree, and the caller are protected.',
+            },
+            {
+                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 the N most-recently-active nodes plus every protected node, deleting the oldest remaining terminal nodes; active/idle nodes regardless of process state, open-managed-worktree 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. Nodes with an open managed worktree are excluded.',
+            'No-op on live nodes (active/idle), nodes with an open managed worktree, and 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.',
+        ],
+    },
+    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-rebuild-index.d.ts

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

package/dist/commands/canvas-rebuild-index.js

@@ -0,0 +1,46 @@
+// `crtr canvas rebuild-index` — re-derive the node-table index from on-disk metas.
+//
+// canvas.db's node rows are a derived index over `nodes/<id>/meta.json`. When the
+// db is absent or stale relative to the metas — most concretely a remote/guest
+// deployment's recreate-from-template, where node data lives on a durable Volume
+// but canvas.db lives on local disk that the recreate wipes — this verb rebuilds
+// the rows (identity columns) from the surviving metas via `rebuildIndex()`, so a
+// subsequent `node lifecycle revive` finds its node again.
+//
+// Fails loud if metas are present but the rebuild yields zero rows: a silent
+// empty db there means the revive would no-op against nothing.
+//
+// Exported as a leaf; `crtr canvas` (canvas.ts) mounts it.
+import { defineLeaf } from '../core/command.js';
+import { cliClient, rethrowAsCliError } from './api-client.js';
+export const canvasRebuildIndexLeaf = defineLeaf({
+    name: 'rebuild-index',
+    description: 're-derive node rows in canvas.db from on-disk nodes/<id>/meta.json',
+    whenToUse: 'canvas.db is missing or stale relative to the on-disk node metas and you need its node rows re-derived — most concretely after a remote/guest deployment\'s recreate-from-template, where node data survives on a durable Volume but canvas.db (local disk) was wiped, so a `node lifecycle revive` would otherwise find no row. Identity columns are rebuilt from each meta; runtime columns (status/intent/pi_pid/window/tmux) take their quiescent defaults, and subscribes_to edges are left intact',
+    help: {
+        name: 'canvas rebuild-index',
+        summary: 're-derive canvas.db node rows from on-disk metas; fails loud if metas exist but yield no rows',
+        params: [],
+        output: [
+            { name: 'metas', type: 'integer', required: true, constraint: 'How many `nodes/<id>/meta.json` files were found on disk.' },
+            { name: 'rows', type: 'integer', required: true, constraint: 'How many node rows exist in canvas.db after the rebuild.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Upserts a node row for every on-disk meta (identity columns only); runtime columns take schema defaults on freshly created rows.',
+            'Leaves subscribes_to edges intact; re-derives spawned_by provenance edges from each meta.',
+            'Throws (non-zero exit) if metas are present but the rebuild produced zero rows.',
+        ],
+    },
+    run: async () => {
+        // The rebuild + the fail-loud “metas exist but 0 rows” guard run server-side
+        // (crtrd owns canvas.db and the on-disk metas under the same CRTR_HOME).
+        try {
+            const res = await cliClient().rebuildIndex();
+            return { metas: res.metas, rows: res.rows };
+        }
+        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;