@crouton-kit/crouter 0.3.32 → 0.3.34

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 → 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',
+    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.js

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

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,57 @@
+// `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 Hearth guest
+// recreate-from-template, where node data lives on the 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 `canvas 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 { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { defineLeaf } from '../core/command.js';
+import { rebuildIndex, listNodes, nodesRoot, nodeDir } from '../core/canvas/index.js';
+function countOnDiskMetas() {
+    const root = nodesRoot();
+    if (!existsSync(root))
+        return 0;
+    let n = 0;
+    for (const id of readdirSync(root)) {
+        if (existsSync(join(nodeDir(id), 'meta.json')))
+            n++;
+    }
+    return n;
+}
+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 Hearth guest recreate-from-template, where node data survives on the durable Volume but canvas.db (local disk) was wiped, so a `canvas 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 () => {
+        const metas = countOnDiskMetas();
+        rebuildIndex();
+        const rows = listNodes().length;
+        if (metas > 0 && rows === 0) {
+            throw new Error(`rebuild-index found ${metas} on-disk meta.json file(s) under ${nodesRoot()} but produced 0 node rows in canvas.db — rebuild failed; refusing to leave an empty index`);
+        }
+        return { metas, rows };
+    },
+});

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,51 @@
+import { defineLeaf } from '../core/command.js';
+import { getNode } from '../core/canvas/index.js';
+import { dashboardRowsAll, enrichRows } from '../core/canvas/render.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',
+    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.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: queries canvas.db, focus rows, telemetry files, and human ask counts.'],
+        // Machine-readable dump for the browser canvas, not for an agent/human to
+        // glance at — collapse it in the attach viewer by default.
+        preview: { suppressOutput: true },
+    },
+    run: async () => {
+        const rows = dashboardRowsAll();
+        enrichRows(rows);
+        const nodes = rows.map((row) => {
+            const meta = getNode(row.node_id);
+            const hostKind = meta?.host_kind ?? 'tmux';
+            return {
+                node_id: row.node_id,
+                name: row.name,
+                kind: row.kind,
+                mode: row.mode,
+                lifecycle: row.lifecycle ?? meta?.lifecycle,
+                status: row.status,
+                cwd: row.cwd,
+                parent: meta?.parent ?? null,
+                created: row.created,
+                host_kind: hostKind,
+                enterable: hostKind === 'broker',
+                attention_count: row.asks,
+                ...(meta?.cycles !== undefined ? { cycles: meta.cycles } : {}),
+                ...(row.mtimeMs !== undefined ? { last_activity: new Date(row.mtimeMs).toISOString() } : {}),
+                ctx_tokens: row.ctx_tokens,
+                streaming: row.streaming ?? false,
+                hanging: row.hanging ?? null,
+                viewed: row.viewed ?? false,
+            };
+        });
+        return { generated_at: new Date().toISOString(), nodes };
+    },
+});

package/dist/commands/canvas-tmux-spread.d.ts

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

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

@@ -0,0 +1,188 @@
+// `crtr canvas tmux-spread <node>` — explode the local subtree into a tiled grid.
+//
+// Bound by the alt+c → `e` chord (config: prefixBinds['e'].run = "canvas
+// tmux-spread {self}"). It "expands" the graph you are watching: the caller's
+// own viewer pane is broken out into a BRAND-NEW window, then a surface-attach
+// viewer pane is tiled beside it for every broker-alive node in the local
+// subtree (ancestry root → self → descendants), so the user lands on a single
+// window showing the whole live subtree at once.
+//
+// SCOPE — the LOCAL SUBTREE: climbRoot(self) → the ancestry root, then every
+// node under it (subtreeIds). TARGET — "broker-alive" nodes: status in
+// (active, idle) AND isPidAlive(pi_pid); self included. CAP — 8 panes total,
+// most-recently-active first (pi session-file mtime, descending). Self's pane is
+// always shown (it is the anchor being broken out); up to 7 others fill the rest,
+// and any beyond that are an `overflow` count.
+//
+// crtr is tmux-only and this is pure viewer chrome: it reuses the placement
+// layer (openViewerWindow / registerViewerFocus) and the §5.1 import-lint front
+// door (breakPane / selectLayout re-exported through placement), never importing
+// tmux.ts directly.
+import { statSync } from 'node:fs';
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { climbRoot, subtreeIds } from '../core/canvas/nav-model.js';
+import { isPidAlive } from '../core/canvas/pid.js';
+import { getNode, setFocusPane, closeFocusRow } from '../core/canvas/index.js';
+import { inTmux, currentTmux, breakPane, selectLayout, openViewerWindow, paneLocation, paneExists, closePane, getPaneOption, switchClient, selectWindow, focusOf, focusByPane, waitForBrokerViewSocket, } from '../core/runtime/placement.js';
+/** Hard ceiling on panes in the spread window (self + up to 7 siblings). */
+const PANE_CAP = 8;
+/** Recency key for ranking: the mtime of a node's pi session `.jsonl`, captured
+ *  in `pi_session_file`. A node that never captured a session file (or whose file
+ *  is gone) sorts last (0). */
+function sessionMtime(meta) {
+    const f = meta.pi_session_file;
+    if (f === undefined || f === null || f === '')
+        return 0;
+    try {
+        return statSync(f).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+/** A node whose broker engine is currently live and attachable. */
+function brokerAlive(meta) {
+    return (meta.status === 'active' || meta.status === 'idle') && isPidAlive(meta.pi_pid ?? null);
+}
+export const tmuxSpreadLeaf = defineLeaf({
+    name: 'tmux-spread',
+    description: 'break the caller\'s pane into a new window and tile a viewer for every broker-alive node in the local subtree',
+    whenToUse: 'you want the whole live subtree you are watching on one tiled tmux window at once — bound to the alt+c → e chord; rarely run by hand',
+    help: {
+        name: 'canvas tmux-spread',
+        summary: 'Explode the local subtree into a tiled grid: break the caller\'s viewer pane into a brand-new window, then tile a surface-attach viewer pane beside it for every broker-alive node (status active/idle + live pi_pid) in the ancestry-root subtree, most-recently-active first, capped at 8 panes',
+        params: [
+            {
+                kind: 'positional',
+                name: 'node',
+                required: true,
+                constraint: 'The spread anchor (self) — its ancestry root + descendants define the subtree to tile. The alt+c chord passes {self}.',
+            },
+            {
+                kind: 'flag',
+                name: 'pane',
+                type: 'string',
+                required: false,
+                constraint: 'tmux pane id of the caller\'s viewer (the pane broken into the new window). Defaults to $TMUX_PANE.',
+            },
+        ],
+        output: [
+            { name: 'window', type: 'string', required: false, constraint: 'The new window id holding the tiled spread.' },
+            { name: 'session', type: 'string', required: false, constraint: 'The session the spread window lives in (the caller\'s session — break-pane keeps it).' },
+            { name: 'panes', type: 'number', required: true, constraint: 'How many panes the spread window ended with (self + opened siblings).' },
+            { name: 'nodes', type: 'string', required: true, constraint: 'Space-joined ids tiled into the window (self first).' },
+            { name: 'overflow', type: 'number', required: true, constraint: 'Broker-alive siblings beyond the cap that were NOT shown.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Breaks the caller\'s viewer pane into a brand-new tmux window (tmux break-pane).',
+            'Opens a surface-attach viewer pane (and a focuses row) for each shown sibling, moving any that had a viewer elsewhere into the spread.',
+            'Tiles the window and switches the client onto it.',
+        ],
+    },
+    run: async (input) => {
+        if (!inTmux()) {
+            throw new InputError({
+                error: 'no_tmux',
+                message: 'tmux-spread needs a tmux server — crtr placement is tmux-only.',
+                next: 'Run from inside a tmux session (an agent viewer pane).',
+            });
+        }
+        const anchorId = input['node'];
+        // Resolve the caller's viewer pane like placement.focus() does: an explicit
+        // --pane, else $TMUX_PANE (set when run via tmux run-shell / the alt+c
+        // chord), else the attached client's active pane (the graph-modal `e` path
+        // shells from the headless broker, which carries no $TMUX_PANE).
+        const callerPane = input['pane'] ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
+        if (callerPane === undefined || callerPane === '') {
+            throw new InputError({
+                error: 'no_pane',
+                message: 'no caller pane to break out',
+                next: 'Run from inside an agent\'s pane, or pass --pane <pane-id>.',
+            });
+        }
+        const anchor = getNode(anchorId);
+        if (anchor === null) {
+            throw new InputError({
+                error: 'not_found',
+                message: `no node: ${anchorId}`,
+                next: 'List nodes with `crtr node inspect list`.',
+            });
+        }
+        // Local subtree: ancestry root → every descendant (root itself is excluded by
+        // subtreeIds, so prepend it). Then keep only broker-alive nodes.
+        const root = climbRoot(anchorId);
+        const candidates = [root, ...subtreeIds(root)]
+            .map((id) => getNode(id))
+            .filter((m) => m !== null && brokerAlive(m));
+        // Rank the OTHER nodes most-recently-active first; self is always the anchor,
+        // so it claims one pane and up to PANE_CAP-1 siblings fill the rest.
+        const others = candidates
+            .filter((m) => m.node_id !== anchorId)
+            .sort((a, b) => sessionMtime(b) - sessionMtime(a));
+        const shown = others.slice(0, PANE_CAP - 1);
+        const overflow = others.length - shown.length;
+        // Break the caller's pane into a fresh window — the spread anchor. The pane
+        // keeps its %id, only its window changes; break-pane keeps it in the caller's
+        // session. A failure here is a real error (no half-spread fallback).
+        const broken = breakPane(callerPane);
+        if (broken === null) {
+            throw new InputError({
+                error: 'break_failed',
+                message: `tmux break-pane failed for ${callerPane}`,
+                next: 'Ensure the pane exists and tmux is healthy.',
+            });
+        }
+        const anchorPane = broken.pane;
+        const window = broken.window;
+        const session = paneLocation(anchorPane)?.session ?? null;
+        // Keep the viewer registry correct: re-point self's focus row at the moved
+        // pane's (possibly new) session cache.
+        const selfFocus = focusByPane(callerPane);
+        if (selfFocus !== null)
+            setFocusPane(selfFocus.focus_id, anchorPane, session);
+        const spreadIds = [anchorId];
+        for (const m of shown) {
+            const id = m.node_id;
+            // UNIQUE(node_id): a sibling that already has a viewer ELSEWHERE must be
+            // MOVED into the spread — vacate its old pane + row first (mirror focus()
+            // case (c)): only kill the pane if it still carries THIS node's @crtr_node
+            // tag (else it is the user's shell / another node's viewer — drop the stale
+            // row only).
+            const prior = focusOf(id);
+            if (prior !== null && prior.pane !== null) {
+                if (paneExists(prior.pane) && getPaneOption(prior.pane, '@crtr_node') === id) {
+                    closePane(prior.pane);
+                }
+                closeFocusRow(prior.focus_id);
+            }
+            // Broker is already alive, but close the cold-start race before attach.
+            await waitForBrokerViewSocket(id);
+            const row = openViewerWindow(id, session ?? '', { cwd: m.cwd, besidePane: anchorPane });
+            if (row === null)
+                continue; // tmux refused this split (e.g. no space) — best-effort skip
+            spreadIds.push(id);
+            // Re-tile after each split so the next split has room (a fixed anchor pane
+            // would otherwise halve until tmux runs out of space).
+            selectLayout(window, 'tiled');
+        }
+        selectLayout(window, 'tiled');
+        if (session !== null) {
+            switchClient(session);
+            selectWindow(session, window);
+        }
+        return {
+            window,
+            session: session ?? undefined,
+            panes: spreadIds.length,
+            nodes: spreadIds.join(' '),
+            overflow,
+        };
+    },
+    render: (out) => {
+        const o = out;
+        const tail = o.overflow > 0 ? ` (+${o.overflow} more not shown)` : '';
+        return `spread ${o.panes} pane(s) into window ${o.window ?? '?'}${tail}`;
+    },
+});

package/dist/commands/canvas.d.ts

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

package/dist/commands/canvas.js

@@ -8,13 +8,28 @@
 // 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 { browseLeaf } from './canvas-browse.js';
 import { reviveLeaf } from './revive.js';
 import { attentionBranch } from './attention.js';
 import { daemonBranch } from './daemon.js';
 import { chordLeaf } from './chord.js';
+import { tmuxSpreadLeaf } from './canvas-tmux-spread.js';
 import { canvasPruneLeaf } from './canvas-prune.js';
+import { canvasRebuildIndexLeaf } from './canvas-rebuild-index.js';
 import { historyBranch } from './canvas-history.js';
+import { issueNewLeaf } from './canvas-issue.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',
+    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',
@@ -28,6 +43,6 @@ export function registerCanvas() {
             summary: 'observe and supervise the whole agent graph',
             model: 'Canvas-wide operations, distinct from per-node work (`node`) and a node\'s own spine I/O (`push`/`feed`). `dashboard` renders the subscription forest as a tree; `browse` opens an interactive full-screen navigator (tabs/tree/search) over the whole canvas and resumes the chosen node; `attention` aggregates pending human asks across the graph; `revive` reopens a window for a done/idle/dead/canceled node; `history` searches and recalls the content record (reports + context docs) of past work in a cwd; `daemon` manages the thin crtrd supervisor that auto-revives nodes on window exit; `prune` bounds growth by deleting terminal nodes past a TTL.',
         },
-        children: [dashboardLeaf, browseLeaf, attentionBranch, reviveLeaf, historyBranch, daemonBranch, chordLeaf, canvasPruneLeaf],
+        children: [dashboardLeaf, canvasSnapshotLeaf, browseLeaf, attentionBranch, reviveLeaf, historyBranch, daemonBranch, chordLeaf, tmuxSpreadLeaf, issueBranch, canvasPruneLeaf, canvasRebuildIndexLeaf],
     });
 }