@crouton-kit/crouter 0.3.16 → 0.3.18

package/dist/core/canvas/browse/terminal.d.ts

@@ -0,0 +1,23 @@
+export interface Key {
+    upArrow: boolean;
+    downArrow: boolean;
+    leftArrow: boolean;
+    rightArrow: boolean;
+    return: boolean;
+    escape: boolean;
+    ctrl: boolean;
+    meta: boolean;
+    tab: boolean;
+    shiftTab: boolean;
+    backspace: boolean;
+}
+export declare function parseKeypress(data: Buffer): {
+    input: string;
+    key: Key;
+};
+export declare function setupTerminal(): void;
+export declare function restoreTerminal(): void;
+export declare function getTerminalSize(): {
+    cols: number;
+    rows: number;
+};

package/dist/core/canvas/browse/terminal.js

@@ -0,0 +1,100 @@
+// terminal.ts — raw-mode helpers for the `crtr canvas browse` TUI.
+//
+// Hand-rolled (no deps), mirroring humanloop's src/tui/terminal.ts. Extends its
+// key parsing beyond up/down/return/escape/tab/backspace/ctrl + printable input:
+// adds leftArrow/rightArrow (cursor keys) and shiftTab (`\x1b[Z`) so the browser
+// can drive tree expand/collapse and tab cycling.
+function emptyKey() {
+    return {
+        upArrow: false,
+        downArrow: false,
+        leftArrow: false,
+        rightArrow: false,
+        return: false,
+        escape: false,
+        ctrl: false,
+        meta: false,
+        tab: false,
+        shiftTab: false,
+        backspace: false,
+    };
+}
+export function parseKeypress(data) {
+    const str = data.toString('utf8');
+    const key = emptyKey();
+    if (str === '\x1b[A') {
+        key.upArrow = true;
+        return { input: '', key };
+    }
+    if (str === '\x1b[B') {
+        key.downArrow = true;
+        return { input: '', key };
+    }
+    if (str === '\x1b[C') {
+        key.rightArrow = true;
+        return { input: '', key };
+    }
+    if (str === '\x1b[D') {
+        key.leftArrow = true;
+        return { input: '', key };
+    }
+    if (str === '\x1b[Z') {
+        key.shiftTab = true;
+        return { input: '', key };
+    }
+    if (str === '\r' || str === '\n') {
+        key.return = true;
+        return { input: '', key };
+    }
+    // Alt+Backspace: terminals send ESC followed by DEL/BS. Must precede the
+    // bare-ESC check so the two-byte sequence isn't swallowed as plain escape.
+    if (str === '\x1b\x7f' || str === '\x1b\b') {
+        key.meta = true;
+        key.backspace = true;
+        return { input: '', key };
+    }
+    if (str === '\x1b') {
+        key.escape = true;
+        return { input: '', key };
+    }
+    if (str === '\t') {
+        key.tab = true;
+        return { input: '', key };
+    }
+    if (str === '\x7f' || str === '\b') {
+        key.backspace = true;
+        return { input: '', key };
+    }
+    if (str.length === 1 && str.charCodeAt(0) < 32) {
+        key.ctrl = true;
+        const ch = String.fromCharCode(str.charCodeAt(0) + 64).toLowerCase();
+        return { input: ch, key };
+    }
+    // Multi-byte chunks (paste, multi-byte UTF-8, unknown escape sequences) are
+    // returned as-is in `input`; the input-mode handler sanitises them before
+    // appending to its buffer. Top-level handlers ignore strings of length > 1.
+    return { input: str, key };
+}
+export function setupTerminal() {
+    if (!process.stdin.isTTY) {
+        throw new Error('crtr canvas browse requires an interactive terminal (TTY)');
+    }
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+    process.stdout.write('\x1b[?25l'); // hide cursor
+    process.stdout.write('\x1b[?1049h'); // alt screen
+    process.stdout.write('\x1b[2J\x1b[H'); // clear
+}
+export function restoreTerminal() {
+    process.stdout.write('\x1b[?25h'); // show cursor
+    process.stdout.write('\x1b[?1049l'); // restore screen
+    process.stdin.setRawMode(false);
+    process.stdin.pause();
+}
+export function getTerminalSize() {
+    return {
+        cols: process.stdout.columns || 80,
+        rows: process.stdout.rows || 24,
+    };
+}

package/dist/core/canvas/canvas.d.ts

@@ -86,8 +86,14 @@ export interface PruneResult {
  *  `created` is older than `ttlDays`, bounding the otherwise-unbounded growth of
  *  node rows + dirs. The edges→nodes FK (`ON DELETE CASCADE`, migration v4) GCs
  *  each pruned node's edges automatically; the on-disk `nodes/<id>/` dir is
- *  removed too. Live nodes are NEVER touched: active | idle are the daemon's
- *  domain, a DISJOINT status set, so prune and supervision can't interfere.
+ *  removed too.
+ *
+ *  With `includeStale`, ALSO prunes nominally-live (active | idle) nodes past the
+ *  TTL whose process is provably gone — `pi_pid` is NULL or no longer alive. This
+ *  reaps stale roots (a bare `crtr` whose pi died without the row transitioning),
+ *  which the daemon's supervision never reconciled. A genuinely-running node keeps
+ *  a live `pi_pid`, so it is protected, as is the CALLER ($CRTR_NODE_ID). Without
+ *  the flag, active | idle are NEVER touched (the daemon's domain).
  *
  *  The row deletes run in ONE transaction (so the sweep is all-or-nothing); the
  *  dir removals follow after COMMIT — the fs isn't transactional, and by then the
@@ -96,4 +102,5 @@ export interface PruneResult {
 export declare function pruneNodes(opts: {
     ttlDays: number;
     dryRun?: boolean;
+    includeStale?: boolean;
 }): PruneResult;

package/dist/core/canvas/canvas.js

@@ -352,12 +352,29 @@ export function rebuildIndex() {
             recordSpawn(meta.node_id, prov);
     }
 }
+/** Is `pid` a live process? `kill(pid, 0)` sends no signal — it only probes
+ *  existence/permission. ESRCH ⇒ gone; EPERM ⇒ alive but not ours (still alive). */
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
 /** Retention sweep: remove TERMINAL nodes (status dead | done | canceled) whose
  *  `created` is older than `ttlDays`, bounding the otherwise-unbounded growth of
  *  node rows + dirs. The edges→nodes FK (`ON DELETE CASCADE`, migration v4) GCs
  *  each pruned node's edges automatically; the on-disk `nodes/<id>/` dir is
- *  removed too. Live nodes are NEVER touched: active | idle are the daemon's
- *  domain, a DISJOINT status set, so prune and supervision can't interfere.
+ *  removed too.
+ *
+ *  With `includeStale`, ALSO prunes nominally-live (active | idle) nodes past the
+ *  TTL whose process is provably gone — `pi_pid` is NULL or no longer alive. This
+ *  reaps stale roots (a bare `crtr` whose pi died without the row transitioning),
+ *  which the daemon's supervision never reconciled. A genuinely-running node keeps
+ *  a live `pi_pid`, so it is protected, as is the CALLER ($CRTR_NODE_ID). Without
+ *  the flag, active | idle are NEVER touched (the daemon's domain).
  *
  *  The row deletes run in ONE transaction (so the sweep is all-or-nothing); the
  *  dir removals follow after COMMIT — the fs isn't transactional, and by then the
@@ -365,9 +382,11 @@ export function rebuildIndex() {
  *  reports the candidate set and deletes NOTHING. */
 export function pruneNodes(opts) {
     const dryRun = opts.dryRun ?? false;
+    const includeStale = opts.includeStale ?? false;
     const cutoff = new Date(Date.now() - opts.ttlDays * 86_400_000).toISOString();
+    const selfId = process.env['CRTR_NODE_ID'] ?? '';
     const db = openDb();
-    const candidates = db
+    const terminal = db
         .prepare(`SELECT node_id, status, created FROM nodes
          WHERE status IN ('dead', 'done', 'canceled') AND created < ?
          ORDER BY created`)
@@ -376,6 +395,25 @@ export function pruneNodes(opts) {
         status: r['status'],
         created: r['created'],
     }));
+    // Stale non-terminal sweep (opt-in): active | idle past the TTL whose process
+    // is provably gone (pi_pid NULL or not alive). Never the caller itself.
+    const stale = !includeStale ? [] : db
+        .prepare(`SELECT node_id, status, created, pi_pid FROM nodes
+         WHERE status IN ('active', 'idle') AND created < ?
+         ORDER BY created`)
+        .all(cutoff)
+        .filter((r) => {
+        if (r['node_id'] === selfId)
+            return false;
+        const pid = r['pi_pid'];
+        return pid === null || !pidAlive(pid);
+    })
+        .map((r) => ({
+        node_id: r['node_id'],
+        status: r['status'],
+        created: r['created'],
+    }));
+    const candidates = [...terminal, ...stale];
     if (dryRun || candidates.length === 0)
         return { pruned: candidates, dryRun };
     // One transactioned sweep — delete the rows; the FK cascades their edges.

package/dist/core/canvas/paths.d.ts

@@ -1,4 +1,7 @@
-/** Root of the global canvas home (`~/.crtr` unless `CRTR_HOME` is set). */
+/** Root of the global canvas home (`~/.crouter/canvas` unless `CRTR_HOME` is set).
+ *  Nested under the `.crouter` scope root so the whole runtime lives in one
+ *  visible top-level dir; `canvas/` keeps node-graph runtime state separate from
+ *  durable user content (skills/plugins/marketplaces/config) at the scope root. */
 export declare function crtrHome(): string;
 export declare function canvasDbPath(): string;
 export declare function nodesRoot(): string;

package/dist/core/canvas/paths.js

@@ -1,6 +1,6 @@
-// The `~/.crtr/` layout. One global, cwd-agnostic home for the whole canvas.
+// The `~/.crouter/canvas/` layout. One global, cwd-agnostic home for the whole canvas.
 //
-//   ~/.crtr/
+//   ~/.crouter/canvas/
 //     canvas.db                 sqlite (WAL) — topology only (nodes + edges)
 //     nodes/<node_id>/
 //       meta.json               source of truth for the node's row
@@ -15,10 +15,16 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { mkdirSync } from 'node:fs';
-/** Root of the global canvas home (`~/.crtr` unless `CRTR_HOME` is set). */
+import { CRTR_DIR_NAME } from '../../types.js';
+/** Root of the global canvas home (`~/.crouter/canvas` unless `CRTR_HOME` is set).
+ *  Nested under the `.crouter` scope root so the whole runtime lives in one
+ *  visible top-level dir; `canvas/` keeps node-graph runtime state separate from
+ *  durable user content (skills/plugins/marketplaces/config) at the scope root. */
 export function crtrHome() {
     const override = process.env['CRTR_HOME'];
-    return override !== undefined && override !== '' ? override : join(homedir(), '.crtr');
+    return override !== undefined && override !== ''
+        ? override
+        : join(homedir(), CRTR_DIR_NAME, 'canvas');
 }
 export function canvasDbPath() {
     return join(crtrHome(), 'canvas.db');

package/dist/core/canvas/render.d.ts

@@ -23,6 +23,16 @@ export interface DashboardRow {
     mode: string;
     ctx_tokens: number;
     asks: number;
+    /** The dir the node is pinned to (its cwd). Drives the browser's cwd-scope
+     *  filter + the All-dirs basename cue. */
+    cwd: string;
+    /** ISO 8601 birth timestamp — drives the recency sort + the relative-age cue. */
+    created: string;
+    /** The node's spawn prompt (context/initial-prompt.md), trimmed + capped. Only
+     *  populated by dashboardRowsAll (the browser snapshot) — the dashboard leaf
+     *  leaves it undefined to avoid a file read per node. Indexed by super-search
+     *  and shown in the preview panel. */
+    goal?: string;
 }
 /** One row per node visible in the sub-DAG of `rootId` (including root). */
 export declare function dashboardRows(rootId: string): DashboardRow[];

package/dist/core/canvas/render.js

@@ -16,7 +16,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { getNode, listNodes, subscriptionsOf, view } from './canvas.js';
 import { fullName } from './labels.js';
-import { jobDir } from './paths.js';
+import { jobDir, contextDir } from './paths.js';
 import { countAsks } from './attention.js';
 // ---------------------------------------------------------------------------
 // Glyphs
@@ -162,6 +162,25 @@ export function renderForest() {
     }
     return parts.join('\n\n');
 }
+/** The spawn prompt, read straight off disk (canvas-home state) and capped so a
+ *  giant initial-prompt.md can't bloat the snapshot. Mirrors how telemetry is
+ *  read here directly rather than via the runtime layer (which would invert the
+ *  canvas→runtime dependency). Never throws. */
+const GOAL_CAP = 4096;
+function readGoalText(nodeId) {
+    try {
+        const p = join(contextDir(nodeId), 'initial-prompt.md');
+        if (!existsSync(p))
+            return undefined;
+        const body = readFileSync(p, 'utf8').trim();
+        if (body === '')
+            return undefined;
+        return body.length > GOAL_CAP ? body.slice(0, GOAL_CAP) : body;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** One row per node visible in the sub-DAG of `rootId` (including root). */
 export function dashboardRows(rootId) {
     const ids = [rootId, ...view(rootId)];
@@ -178,6 +197,8 @@ export function dashboardRows(rootId) {
                 mode: node.mode,
                 ctx_tokens: tel.tokens_in ?? 0,
                 asks: countAsks(id),
+                cwd: node.cwd,
+                created: node.created,
             }];
     });
 }
@@ -196,6 +217,9 @@ export function dashboardRowsAll() {
                 mode: row.mode,
                 ctx_tokens: tel.tokens_in ?? 0,
                 asks: countAsks(row.node_id),
+                cwd: row.cwd,
+                created: row.created,
+                goal: readGoalText(row.node_id),
             }];
     });
 }

package/dist/core/canvas/types.js

@@ -1,7 +1,7 @@
 // The canvas vocabulary — the node + edge model the whole runtime hangs on.
 //
-// One global canvas (`~/.crtr/canvas.db`) holds the topology (nodes + edges);
-// each node's flesh lives on disk under `~/.crtr/nodes/<id>/`. A node's
+// One global canvas (`~/.crouter/canvas/canvas.db`) holds the topology (nodes +
+// edges); each node's flesh lives on disk under `~/.crouter/canvas/nodes/<id>/`. A node's
 // `meta.json` is the source of truth for its own row; the db is a queryable
 // index over those metas, plus the authoritative store for the mutable
 // `subscribes_to` edges (which no single meta owns).

package/dist/core/feed/inbox.d.ts

@@ -45,8 +45,5 @@ export declare function writeCursor(nodeId: string, iso: string): void;
  *     [<kind>]                                ← ref-less msg: full body inlined
  *       <body line>
  *     …
- *
- * A header line announces the total count and instructs the receiver to
- * dereference only what matters.
  */
 export declare function coalesce(entries: InboxEntry[]): string;

package/dist/core/feed/inbox.js

@@ -139,14 +139,10 @@ function renderEntry(e) {
  *     [<kind>]                                ← ref-less msg: full body inlined
  *       <body line>
  *     …
- *
- * A header line announces the total count and instructs the receiver to
- * dereference only what matters.
  */
 export function coalesce(entries) {
     if (entries.length === 0)
         return '(inbox empty)';
-    const header = `${entries.length} update${entries.length === 1 ? '' : 's'} since last read — dereference what matters.\n`;
     // Group by `from` (null → 'system').
     const groups = new Map();
     for (const e of entries) {
@@ -160,5 +156,5 @@ export function coalesce(entries) {
         const lines = items.map(renderEntry);
         sections.push(`From ${sender} — ${items.length} update${items.length === 1 ? '' : 's'}:\n${lines.join('\n')}`);
     }
-    return header + sections.join('\n\n');
+    return sections.join('\n\n');
 }

package/dist/core/help.d.ts

@@ -162,6 +162,12 @@ export interface LeafHelp {
     /** Every persistent change the command makes to the world. For read-only
      *  leaves use exactly: ["None. Read-only."] */
     effects: string[];
+    /** Bounded runtime aggregate as a complete self-named state element (build it
+     *  with stateBlock), e.g. `<kinds count="7">…</kinds>`. Lazily evaluated at
+     *  render time so it reflects the caller's cwd/project scope; appended after
+     *  the schema. Renderer soft-fails to omission if it returns null or throws.
+     *  Mirrors BranchHelp.dynamicState. */
+    dynamicState?: () => string | null;
 }
 /** Build a self-named runtime-state element: `<tag attr="v">body</tag>`. The
  *  subtree that owns the state authors it through this, so the tag name and any

package/dist/core/help.js

@@ -238,5 +238,12 @@ export function renderLeafArgv(h) {
     for (const e of h.effects) {
         lines.push(`  ${e}`);
     }
+    // Optional bounded runtime-state block (e.g. the live <kinds> list), appended
+    // after the schema. Soft-fails to omission on null/throw, mirroring renderBranch.
+    const state = evalDynamic(h.dynamicState);
+    if (state !== null) {
+        lines.push('');
+        lines.push(state);
+    }
     return lines.join('\n');
 }

package/dist/core/personas/index.d.ts

@@ -2,11 +2,12 @@
  * Persona composer public surface.
  *
  * Re-exports:
- *   - loadPersona / loadKernel / availableKinds   (loader — raw file access)
+ *   - loadPersona / loadKernel / availableKinds / kindWhenToUse / subPersonasFor
+ *                                (loader — raw file access)
  *   - resolve                    (high-level composer)
  *   - ResolvedPersona            (return type of resolve)
  */
-export { loadPersona, loadKernel, availableKinds, loadLifecycleFragment, loadSpineFragment } from './loader.js';
-export type { LoadedPersona } from './loader.js';
+export { loadPersona, loadKernel, availableKinds, kindWhenToUse, subPersonasFor, loadLifecycleFragment, loadSpineFragment } from './loader.js';
+export type { LoadedPersona, SubPersona } from './loader.js';
 export { resolve } from './resolve.js';
 export type { ResolvedPersona } from './resolve.js';

package/dist/core/personas/index.js

@@ -2,9 +2,10 @@
  * Persona composer public surface.
  *
  * Re-exports:
- *   - loadPersona / loadKernel / availableKinds   (loader — raw file access)
+ *   - loadPersona / loadKernel / availableKinds / kindWhenToUse / subPersonasFor
+ *                                (loader — raw file access)
  *   - resolve                    (high-level composer)
  *   - ResolvedPersona            (return type of resolve)
  */
-export { loadPersona, loadKernel, availableKinds, loadLifecycleFragment, loadSpineFragment } from './loader.js';
+export { loadPersona, loadKernel, availableKinds, kindWhenToUse, subPersonasFor, loadLifecycleFragment, loadSpineFragment } from './loader.js';
 export { resolve } from './resolve.js';

package/dist/core/personas/loader.d.ts

@@ -5,9 +5,10 @@
  * Resolution order (highest → lowest precedence): project > user > builtin.
  *
  * Layout on disk:
- *   <root>/personas/<kind>/base.md
+ *   <root>/personas/<kind>/PERSONA.md
  *   <root>/personas/<kind>/orchestrator.md
  *   <root>/personas/orchestration-kernel.md
+ *   <root>/personas/<kind>/<...>/PERSONA.md   (nested sub-personas)
  *
  * The builtin root is src/builtin-personas (or dist/builtin-personas in the
  * compiled build), resolved relative to this module — mirrors the pattern used
@@ -55,29 +56,46 @@ export declare function loadLifecycleFragment(lifecycle: 'terminal' | 'resident'
  */
 export declare function loadSpineFragment(hasManager: boolean): string;
 /**
- * Enumerate the kinds with at least one persona file (base.md or
+ * Enumerate the kinds with at least one persona file (PERSONA.md or
  * orchestrator.md) across all scope roots (project/user/builtin). Used to
- * validate a requested `--kind` and to list the valid choices.
+ * validate a requested `--kind` and to list the valid choices. Only the
+ * IMMEDIATE children of each root count — nested sub-personas never pollute
+ * the global kind list (see subPersonasFor).
  */
 export declare function availableKinds(): string[];
-export interface SubKind {
+/**
+ * The one-line "when to use this node type" gloss for `kind`, read from its
+ * `<kind>/PERSONA.md` `whenToUse` frontmatter (resolved project > user >
+ * builtin). Returns '' when the kind has no PERSONA.md or no `whenToUse`.
+ * Drives the dynamic kind list in `node new -h` / `node promote -h`.
+ */
+export declare function kindWhenToUse(kind: string): string;
+export interface SubPersona {
     /** Full kind string to spawn, e.g. 'plan/reviewers/security'. */
     kind: string;
     /** Leaf name, e.g. 'security'. */
     name: string;
-    /** One-line "what it reviews", from the sub-kind base.md `summary` frontmatter (or ''). */
-    summary: string;
+    /** One-line "when to use", from the sub-persona PERSONA.md `whenToUse` frontmatter (or ''). */
+    whenToUse: string;
 }
 /**
- * Enumerate the reviewer sub-kinds owned by `parentKind` — the specialist
- * personas at `<root>/<parentKind>/reviewers/<name>/base.md`, scanned across all
- * scope roots (project > user > builtin; highest precedence wins per name).
+ * Enumerate the sub-personas AVAILABLE TO `kind` — the nested specialist
+ * personas (e.g. `plan/reviewers/security`) a `kind` node may spawn, surfaced
+ * in its composed prompt (resolve.ts) and nowhere else.
+ *
+ * A sub-persona is any descendant dir (ANY depth) under a top-level kind dir
+ * that holds a PERSONA.md, EXCLUDING the top-level PERSONA.md itself. Its
+ * availability is its `availableTo` frontmatter: an explicit list of kind
+ * strings, or the wildcard `"*"`/`"all"` (visible to every kind); absent, it
+ * defaults to its own top-level ancestor kind. So the five `plan/reviewers/*`
+ * (no `availableTo`) are visible only to `plan`, while a sub-persona under
+ * `developer/` can declare `availableTo: [plan]` to surface in plan's menu —
+ * which is why ALL top-level kinds' descendants are scanned, not just `<kind>/`.
  *
- * Sub-kinds are intentionally NOT global kinds: `availableKinds()` scans only the
- * immediate children of each persona root, so `<parentKind>/reviewers/*` never
- * leaks into the global list. A sub-kind is reachable only by its full kind
- * string and is surfaced only in its parent kind's composed prompt (resolve.ts).
- * Kind-parametric: any kind owns a roster simply by adding
- * `<kind>/reviewers/<name>/base.md` — no code change.
+ * Sub-personas are intentionally NOT global kinds: `availableKinds()` scans only
+ * the immediate children of each root, so a nested sub-persona never leaks into
+ * the global list; it is reachable only by its full kind string. Precedence is
+ * project > user > builtin keyed on the FULL kind string — the highest root that
+ * defines a given kind string wins (and owns its `availableTo`).
  */
-export declare function subKindsFor(parentKind: string): SubKind[];
+export declare function subPersonasFor(kind: string): SubPersona[];