@north-light/api 0.3.580 → 0.3.588

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

@@ -0,0 +1,99 @@
+import { defineLeaf } from '../../core/command.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+import { applyFilters, filterParams, parseFilters } from './shared.js';
+const SORTS = ['relevance', 'recency', 'oldest'];
+export const searchLeaf = defineLeaf({
+    name: 'search',
+    description: 'ranked search over past inboxes and conversations in a cwd',
+    whenToUse: 'you want to find what was SAID to or by nodes that ran in this cwd — a message a node received, a turn in its conversation — ranked by relevance. Omit the query to browse by recency. Narrow with --type/--kind/--status/--since, scope elsewhere with --cwd/--all-cwds/--under/--node. Need an exact regex over bodies instead? Use `canvas history grep`. Reports and documents are `crtr canvas search`, not this.',
+    help: {
+        name: 'canvas history search',
+        summary: 'ranked/filtered/sorted search over past inboxes (default) and conversation transcripts in a cwd',
+        params: [
+            { kind: 'positional', name: 'query', required: false, constraint: 'Whitespace-separated terms, matched case-insensitively and weighted across node name/description and each entry\'s or message\'s lead line (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 node name/description and the lead line 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>:inbox/<n> or <node-id>:session/<n> 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 entries and messages (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;
+        applyFilters(q, f);
+        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 `crtr canvas history read <ref>`; narrow with `crtr 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,34 @@
+import type { InputParam } from '../../core/help.js';
+export declare const TYPES: string[];
+export declare const ORIGINS: string[];
+export declare const ROLES: 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;
+    kinds: string[] | undefined;
+    statuses: string[] | undefined;
+    sinceMs: number | undefined;
+    untilMs: number | undefined;
+    origins: string[] | undefined;
+    roles: string[] | undefined;
+    from: string | 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;
+/** Copy every parsed filter onto a wire query. search, grep, and stats share
+ *  the whole filter vocabulary, so the mapping lives once. */
+export declare function applyFilters(q: Record<string, unknown>, f: ParsedFilters): void;

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

@@ -0,0 +1,135 @@
+// Shared corpus/filter parsing between `canvas history search` and
+// `canvas history grep` \u2014 both leaves scope + filter the same per-cwd conversation
+// 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 = ['transcript', 'inbox'];
+export const ORIGINS = [
+    'human', 'inbox', 'wake', 'revive', 'restart-continuation',
+    'stop-guard', 'park', 'recovery', 'context-nudge', 'kickoff', 'unknown',
+];
+export const ROLES = ['user', 'assistant', 'toolResult'];
+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 both. One of: ${TYPES.join(', ')}. inbox = every delivery a node received, with un-clipped message bodies; transcript = the conversation itself, message by message. Default: inbox.` },
+    { 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.' },
+    { kind: 'flag', name: 'origin', type: 'string', required: false, constraint: `What drove a message to arrive; comma-separated for several. One of: ${ORIGINS.join(', ')}. Applies to transcript + inbox artifacts, which are the only ones that arrive — passing it therefore excludes every generated turn on its own. \`unknown\` is a message carrying no stamp, and is its own bucket rather than a fallback.` },
+    { kind: 'flag', name: 'role', type: 'string', required: false, constraint: `Transcript message role; comma-separated for several. One of: ${ROLES.join(', ')}.` },
+    { kind: 'flag', name: 'from', type: 'string', required: false, constraint: 'Case-insensitive substring against sender attribution — the node that sent a delivery. Applies to transcript + inbox artifacts.' },
+];
+/** 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}`);
+    }
+    const origins = splitCsv(input['origin']);
+    if (origins !== undefined) {
+        const bad = origins.find((o) => !ORIGINS.includes(o));
+        if (bad !== undefined)
+            throw usage(`--origin must be one of: ${ORIGINS.join(', ')}; received: ${bad}`);
+    }
+    const roles = splitCsv(input['role']);
+    if (roles !== undefined) {
+        const bad = roles.find((r) => !ROLES.includes(r));
+        if (bad !== undefined)
+            throw usage(`--role must be one of: ${ROLES.join(', ')}; received: ${bad}`);
+    }
+    // Session files are large and there is no persistent index, so the whole
+    // conversation corpus is reachable only through a narrowed scan. The guard
+    // lives in the failure rather than in a permanently visible constraint:
+    // agents who never search transcripts never pay to understand it.
+    if (types !== undefined && types.includes('transcript')) {
+        const narrowed = input['node'] !== undefined || input['under'] !== undefined || input['since'] !== undefined;
+        if (!narrowed) {
+            throw usage('--type transcript needs a narrowing flag: pass --node, --under, or --since.', { next: 'Transcripts are the full conversation corpus — scanning every node in a cwd reads every session file. Narrow first.' });
+        }
+    }
+    return {
+        cwd,
+        allCwds,
+        under: input['under'],
+        nodes: splitCsv(input['node']),
+        types,
+        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,
+        origins,
+        roles,
+        from: input['from'],
+    };
+}
+/** Copy every parsed filter onto a wire query. search, grep, and stats share
+ *  the whole filter vocabulary, so the mapping lives once. */
+export function applyFilters(q, f) {
+    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.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 (f.origins !== undefined)
+        q['origins'] = f.origins;
+    if (f.roles !== undefined)
+        q['roles'] = f.roles;
+    if (f.from !== undefined)
+        q['from'] = f.from;
+}

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

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

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

@@ -0,0 +1,68 @@
+// `canvas history stats` — the grouped-count projection over the same corpus
+// search and grep scan. A distinct leaf rather than a flag on search because
+// the output shape differs: counts by one dimension, not a hit list. Grouping
+// by origin is what turns the per-message stamps into a census — "what actually
+// drove work here" — without a second command family.
+import { defineLeaf } from '../../core/command.js';
+import { usage } from '../../core/errors.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+import { applyFilters, filterParams, parseFilters } from './shared.js';
+const GROUP_KEYS = ['origin', 'node', 'kind', 'day', 'type', 'role'];
+export const statsLeaf = defineLeaf({
+    name: 'stats',
+    description: 'grouped counts over the cwd\'s node history — the projection view',
+    whenToUse: 'you want the SHAPE of the record rather than individual hits — how much of it came from where, who produced it, or when it happened. Group by origin to census what drove agents to run (cron wakes, inbox deliveries, recovery re-drives, people), by node/kind to see who produced the work, by day for volume over time, by type for corpus composition. Takes every scope and filter `canvas history search` takes, so any query you can search you can also count. Want the matching artifacts themselves? Use `canvas history search` or `canvas history grep`.',
+    help: {
+        name: 'canvas history stats',
+        summary: 'counts by one dimension over past inboxes and conversations — origin census, per-node volume, activity by day',
+        params: [
+            { kind: 'flag', name: 'group-by', type: 'enum', choices: GROUP_KEYS, required: false, default: 'type', constraint: 'The dimension to count by. origin = what drove an inbound message (transcript + inbox only); role = transcript message role; node / kind = who produced it; day = artifact date; type = corpus composition.' },
+            ...filterParams,
+        ],
+        output: [
+            { name: 'group_by', type: 'string', required: true, constraint: 'The dimension counted.' },
+            { name: 'groups', type: 'object[]', required: true, constraint: '{key, count}, descending by count then key.' },
+            { name: 'total', type: 'int', required: true, constraint: 'Artifacts that carried the grouped dimension. Lower than `scanned` when grouping by one not every artifact has (origin, role).' },
+            { name: 'scanned', type: 'int', required: true, constraint: 'Artifacts matched by the filters before grouping.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const by = input['groupBy'] ?? 'type';
+        if (!GROUP_KEYS.includes(by)) {
+            throw usage(`--group-by must be one of: ${GROUP_KEYS.join(', ')}; received: ${by}`);
+        }
+        // Filter validation stays client-side (pure); the corpus scan + grouping
+        // run server-side in crtrd, where canvas.db and the session files live.
+        const f = parseFilters(input);
+        const q = { group_by: by };
+        applyFilters(q, f);
+        try {
+            const res = await cliClient().historyStats(q);
+            return { group_by: res.group_by, groups: res.groups, total: res.total, scanned: res.scanned };
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+    },
+    render: (r) => {
+        const groups = r['groups'];
+        const by = String(r['group_by']);
+        const total = r['total'];
+        const scanned = r['scanned'];
+        if (groups.length === 0) {
+            return `0 artifacts carried \`${by}\` (${scanned} scanned).`;
+        }
+        const width = Math.max(...groups.map((g) => g.key.length));
+        const max = groups[0].count;
+        const rows = groups
+            .map((g) => {
+            const bar = '█'.repeat(Math.max(1, Math.round((g.count / max) * 24)));
+            return `  ${g.key.padEnd(width)}  ${String(g.count).padStart(6)}  ${bar}`;
+        })
+            .join('\n');
+        const tail = total === scanned ? `${total} artifacts` : `${total} of ${scanned} scanned carried \`${by}\``;
+        return `by ${by}:\n\n${rows}\n\n- ${tail}`;
+    },
+});

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,29 @@
+// `canvas history` — past conversations and inboxes: search, grep, count, and
+// read the messages nodes received and the turns of their conversations.
+// Reports and documents are graph objects, read through `crtr canvas search` /
+// `crtr canvas read`, never here.
+import { envNodeCwd } from '../shared/env.js';
+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';
+import { statsLeaf } from './canvas-history/stats.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 = envNodeCwd() ?? process.cwd();
+    return `<corpus cwd="${cwd}"/>`;
+}
+export const historyBranch = defineBranch({
+    name: 'history',
+    description: 'past conversations and inboxes — search, grep, count, and read what nodes were told and said',
+    whenToUse: 'you want what was SAID in a cwd\'s past runs — a message a node received, a turn of its conversation, what drove it to wake — without already knowing which node. Reports and documents are `crtr canvas search` / `crtr canvas read`, not this.',
+    help: {
+        name: 'canvas history',
+        summary: 'past conversations and inboxes; reports and documents are `crtr canvas search`/`read`',
+        model: 'Two corpora, selected with `--type`: `inbox` (default) is every delivery a node received, with un-clipped message bodies; `transcript` is the conversation itself, message by message, each inbound turn carrying the origin that drove it (`--origin`, `--role`, `--from`, and `stats --group-by origin` for the census). Transcripts require a narrowing flag because there is no index. `search` ranks or browses; `grep` matches an exact ECMAScript regex per body line; `read` pulls one hit by its ref (`<node-id>:inbox/<n>`, `<node-id>:session`, `<node-id>:session/<n>`); `stats` counts the same filtered corpus by one dimension. Every leaf takes the same scope and filters. Reports and documents are graph objects: find them with `crtr canvas search`, read them with `crtr canvas read`.',
+        dynamicState: corpusBlock,
+    },
+    children: [searchLeaf, grepLeaf, readLeaf, statsLeaf],
+});

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,148 @@
+// `crtr canvas issue new` — capture a quick todo/idea/bug into a GitHub issue.
+//
+// Bound to the alt+c → c → (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 paneCwd = pane !== undefined && pane !== '' ? paneCurrentPath(pane) : null;
+        const cwd = input['cwd'] ?? paneCwd ?? 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;