@crouton-kit/crouter 0.3.13 → 0.3.15

package/dist/core/canvas/index.js

@@ -1,6 +1,9 @@
 // The canvas: one global graph of nodes + edges. Phase 0 of the pi-native
 // agent runtime. Topology in sqlite (WAL), node flesh on disk.
 export * from './types.js';
+export * from './labels.js';
 export * from './paths.js';
 export * from './canvas.js';
+export * from './focuses.js';
+export * from './telemetry.js';
 export { openDb, closeDb } from './db.js';

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

@@ -0,0 +1,27 @@
+import type { NodeMeta } from './types.js';
+/** The minimal shape `fullName` needs — satisfied by NodeMeta and by anything
+ *  else carrying name + kind (description optional). */
+export interface NamedNode {
+    name: string;
+    kind: string;
+    description?: string;
+}
+/** A node's human label: its explicit handle plus the pi-generated description
+ *  of its first task, e.g. `fix-auth refactor-login-flow`. The handle is
+ *  dropped when it's just the kind default (non-informative, and the kind is
+ *  surfaced elsewhere), so a default-named node reads as its description alone
+ *  (`refactor-login-flow`). Falls back to the bare name when no description
+ *  exists yet (a node not yet named, e.g. a bare root before its first
+ *  message). Never empty. */
+export declare function fullName(node: NamedNode): string;
+/** The pi session display name — the editor label in the top-left. Format is
+ *  `<kind> (<mode>) <fullName> <cycle>` where `<fullName>` is the node's handle
+ *  plus the pi-generated description of its first task (see fullName) and
+ *  `<cycle>` is the revive count (meta.cycles). So `developer (orchestrator)
+ *  fix-auth refactor-auth-flow 2` reads as a developer orchestrator on its 2nd
+ *  cycle working the auth refactor. The name segment is omitted while it
+ *  collapses to the bare kind (a bare root before its first message is named).
+ *  Recomputed from meta on every revive (and pushed live via pi.setSessionName
+ *  when a bare root is named mid-session), so a base→orchestrator polymorph, a
+ *  fresh cycle, or a first-message naming all update the label. */
+export declare function editorLabel(meta: NodeMeta): string;

package/dist/core/canvas/labels.js

@@ -0,0 +1,36 @@
+// labels.ts — human-facing node labels derived from a node's meta.
+//
+// One source of truth for "what do we call this node on screen". `fullName`
+// combines the node's explicit handle (meta.name) with the pi-generated
+// description of its first task (meta.description) — the same string the editor
+// label, the canvas dashboard tree, the nav spine, and the tmux window tab all
+// render, so a node reads identically everywhere it appears.
+/** A node's human label: its explicit handle plus the pi-generated description
+ *  of its first task, e.g. `fix-auth refactor-login-flow`. The handle is
+ *  dropped when it's just the kind default (non-informative, and the kind is
+ *  surfaced elsewhere), so a default-named node reads as its description alone
+ *  (`refactor-login-flow`). Falls back to the bare name when no description
+ *  exists yet (a node not yet named, e.g. a bare root before its first
+ *  message). Never empty. */
+export function fullName(node) {
+    const desc = (node.description ?? '').trim();
+    const handle = node.name && node.name !== node.kind ? node.name : '';
+    const combined = [handle, desc].filter((s) => s !== '').join(' ');
+    return combined !== '' ? combined : node.name;
+}
+/** The pi session display name — the editor label in the top-left. Format is
+ *  `<kind> (<mode>) <fullName> <cycle>` where `<fullName>` is the node's handle
+ *  plus the pi-generated description of its first task (see fullName) and
+ *  `<cycle>` is the revive count (meta.cycles). So `developer (orchestrator)
+ *  fix-auth refactor-auth-flow 2` reads as a developer orchestrator on its 2nd
+ *  cycle working the auth refactor. The name segment is omitted while it
+ *  collapses to the bare kind (a bare root before its first message is named).
+ *  Recomputed from meta on every revive (and pushed live via pi.setSessionName
+ *  when a bare root is named mid-session), so a base→orchestrator polymorph, a
+ *  fresh cycle, or a first-message naming all update the label. */
+export function editorLabel(meta) {
+    const base = `${meta.kind} (${meta.mode})`;
+    const full = fullName(meta);
+    const cycle = meta.cycles ?? 0;
+    return full !== '' && full !== meta.kind ? `${base} ${full} ${cycle}` : `${base} ${cycle}`;
+}

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

@@ -8,6 +8,10 @@ export declare function jobDir(nodeId: string): string;
 export declare function reportsDir(nodeId: string): string;
 export declare function nodeMetaPath(nodeId: string): string;
 export declare function inboxPath(nodeId: string): string;
+/** Passive-subscription accumulator. Pushes from publishers this node subscribes
+ *  to PASSIVELY land here instead of inbox.jsonl — the inbox-watcher never polls
+ *  it, so they never wake the node. Drained as XML pre-text on the next message. */
+export declare function passivePath(nodeId: string): string;
 export declare function transcriptPath(nodeId: string): string;
 export declare function sessionPtrPath(nodeId: string): string;
 /** Create the full directory skeleton for a node. Idempotent. */

package/dist/core/canvas/paths.js

@@ -44,6 +44,12 @@ export function nodeMetaPath(nodeId) {
 export function inboxPath(nodeId) {
     return join(nodeDir(nodeId), 'inbox.jsonl');
 }
+/** Passive-subscription accumulator. Pushes from publishers this node subscribes
+ *  to PASSIVELY land here instead of inbox.jsonl — the inbox-watcher never polls
+ *  it, so they never wake the node. Drained as XML pre-text on the next message. */
+export function passivePath(nodeId) {
+    return join(nodeDir(nodeId), 'passive.jsonl');
+}
 export function transcriptPath(nodeId) {
     return join(nodeDir(nodeId), 'transcript.jsonl');
 }

package/dist/core/canvas/render.js

@@ -15,6 +15,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 { countAsks } from './attention.js';
 // ---------------------------------------------------------------------------
@@ -25,6 +26,7 @@ const STATUS_GLYPH = {
     idle: '○',
     done: '✓',
     dead: '✗',
+    canceled: '⊘',
 };
 function readNodeTelemetry(nodeId) {
     const path = join(jobDir(nodeId), 'telemetry.json');
@@ -58,7 +60,7 @@ function nodeLine(nodeId, indent, connector) {
     const ctx = fmtCtx(tel.tokens_in);
     const asks = countAsks(nodeId);
     const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
-    return `${indent}${connector}${glyph} ${node.name} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}`;
+    return `${indent}${connector}${glyph} ${fullName(node)} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}`;
 }
 /**
  * Recursively walk the subscription sub-DAG rooted at `nodeId`, appending
@@ -110,7 +112,7 @@ export function renderTree(rootId) {
     const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
     const glyph = STATUS_GLYPH[node.status] ?? '?';
     const out = [];
-    out.push(`${glyph} ${node.name} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}`);
+    out.push(`${glyph} ${fullName(node)} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}`);
     // visited starts with root already rendered (walkTree doesn't re-emit root).
     const visited = new Set([rootId]);
     const children = subscriptionsOf(rootId);
@@ -138,14 +140,24 @@ export function renderForest() {
     // a spawned_by edge + subscribe). Fall back to parent===null because querying
     // the full edge table would require opening the db here.
     //
-    // Fine to use parent===null: roots are created by `node session` / `node new`
+    // Fine to use parent===null: roots are created by bare `crtr` / `node new --root`
     // without a parent; non-roots always have a parent.
-    const roots = all.filter((n) => n.parent === null);
-    // If for some reason we have no parent===null nodes (unusual: e.g., all nodes
-    // were created by hand with a parent), fall back to all nodes.
-    const renderRoots = roots.length > 0 ? roots : all;
+    //
+    // Filter to LIVE roots: each `/new` parks a `done` root (option C relaunch)
+    // with parent===null, so an unfiltered forest would render every parked root
+    // as a sibling tree and clutter the dashboard. Showing only active|idle roots
+    // drops parked (`done`) roots and, as a bonus, stray `dead`/`canceled` roots.
+    // Parked roots stay reachable by id (inspect / revive / focus).
+    const roots = all.filter((n) => n.parent === null && (n.status === 'active' || n.status === 'idle'));
+    // No LIVE roots: render an empty/placeholder forest rather than resurrecting
+    // parked (`done`) / dead / canceled roots. The live-only filter is the intent;
+    // falling back to all-status roots would re-clutter the dashboard with the very
+    // parked trees the filter drops (e.g. a sole root `/quit`'d with no `/new`).
+    // Parked roots stay reachable by id (inspect / revive / focus).
+    if (roots.length === 0)
+        return '(no live roots)';
     const parts = [];
-    for (const r of renderRoots) {
+    for (const r of roots) {
         parts.push(renderTree(r.node_id));
     }
     return parts.join('\n\n');
@@ -160,7 +172,7 @@ export function dashboardRows(rootId) {
         const tel = readNodeTelemetry(id);
         return [{
                 node_id: id,
-                name: node.name,
+                name: fullName(node),
                 status: node.status,
                 kind: node.kind,
                 mode: node.mode,
@@ -173,9 +185,12 @@ export function dashboardRows(rootId) {
 export function dashboardRowsAll() {
     return listNodes().flatMap((row) => {
         const tel = readNodeTelemetry(row.node_id);
+        // listNodes() returns the db projection (no description); read the meta to
+        // get the full label. Falls back to the row name if the meta is gone.
+        const meta = getNode(row.node_id);
         return [{
                 node_id: row.node_id,
-                name: row.name,
+                name: meta !== null ? fullName(meta) : row.name,
                 status: row.status,
                 kind: row.kind,
                 mode: row.mode,

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

@@ -0,0 +1,14 @@
+export interface Telemetry {
+    tokens_in?: number;
+    tokens_out?: number;
+    /** Live context-window size from the last turn_end (pi's getContextUsage). */
+    context_tokens?: number;
+    model?: string;
+    updated_at?: string;
+}
+/** Read a node's telemetry record. Missing/corrupt → {}. Never throws. */
+export declare function readTelemetry(nodeId: string): Telemetry;
+/** The node's current context-window size in tokens, or null when unknown.
+ *  Prefers the live `context_tokens` gauge; falls back to cumulative
+ *  `tokens_in` (the dashboard's coarse proxy) only when no live gauge exists. */
+export declare function readContextTokens(nodeId: string): number | null;

package/dist/core/canvas/telemetry.js

@@ -0,0 +1,35 @@
+// telemetry.ts — read a node's job/telemetry.json (written by canvas-stophook
+// on every turn_end). Best-effort throughout: a missing or corrupt file yields
+// an empty record, never a throw.
+//
+//   tokens_in / tokens_out  cumulative, non-cached throughput across the session.
+//   context_tokens          the LIVE context-window gauge (pi's footer figure)
+//                           captured on the last turn_end — the accurate measure
+//                           of how full the node's window currently is. Absent
+//                           until the first turn_end records a usable gauge.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { jobDir } from './paths.js';
+/** Read a node's telemetry record. Missing/corrupt → {}. Never throws. */
+export function readTelemetry(nodeId) {
+    const path = join(jobDir(nodeId), 'telemetry.json');
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/** The node's current context-window size in tokens, or null when unknown.
+ *  Prefers the live `context_tokens` gauge; falls back to cumulative
+ *  `tokens_in` (the dashboard's coarse proxy) only when no live gauge exists. */
+export function readContextTokens(nodeId) {
+    const tel = readTelemetry(nodeId);
+    if (typeof tel.context_tokens === 'number')
+        return tel.context_tokens;
+    if (typeof tel.tokens_in === 'number')
+        return tel.tokens_in;
+    return null;
+}

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

@@ -1,6 +1,7 @@
 /** What a node is doing right now. UI shows active+idle; `done` is hidden but
- *  revivable; only `dead` is a fault. */
-export type NodeStatus = 'active' | 'idle' | 'done' | 'dead';
+ *  revivable; `canceled` is a user-closed node (also hidden, also revivable —
+ *  not a fault); only `dead` is a fault. */
+export type NodeStatus = 'active' | 'idle' | 'done' | 'dead' | 'canceled';
 /** Does stopping finalize the node? terminal = worker (finalizes on push --final);
  *  resident = manager/orchestrator (stays dormant, woken by inbox). */
 export type Lifecycle = 'terminal' | 'resident';
@@ -25,11 +26,21 @@ export interface LaunchSpec {
     /** Extra env injected into the pi process. */
     env: Record<string, string>;
 }
-/** A node's `meta.json` — source of truth for its canvas row. Files for flesh,
- *  sqlite for skeleton: the db indexes the queryable subset of these fields. */
-export interface NodeMeta {
+/** A node's DURABLE IDENTITY — the subset that `meta.json` persists on disk.
+ *  Written rarely (birth, polymorph, session-id capture, naming); never touched
+ *  by a status flip, an intent change, a focus swap, or a pid stamp. The db row
+ *  indexes the queryable identity columns; `rebuildIndex()` re-derives them from
+ *  here. (Live runtime state lives in NodeRuntime, authoritative in the row.) */
+export interface NodeIdentity {
     node_id: string;
     name: string;
+    /** A 2-4 word kebab-case handle derived from the node's first prompt (named
+     *  headlessly by pi; see runtime/naming.ts). Shown in the editor label. */
+    description?: string;
+    /** How many times this node has been (re)launched — born at 0, bumped on
+     *  every revive. The trailing N in the editor label, so a refresh/crash cycle
+     *  reads at a glance. */
+    cycles?: number;
     created: string;
     /** The dir this node is pinned to — its cwd (where pi runs, bash executes). */
     cwd: string;
@@ -37,24 +48,93 @@ export interface NodeMeta {
     kind: string;
     mode: Mode;
     lifecycle: Lifecycle;
-    status: NodeStatus;
-    /** spawned_by target — who created me. Audit only; null for user-opened roots. */
+    /** The last persona state {mode,lifecycle} the node was GIVEN transition
+     *  guidance for. Meta-only (not a db column). Born equal to the node's initial
+     *  {mode,lifecycle} at spawn so a fresh node never gets spurious guidance. The
+     *  persona injector (runtime/persona.ts) compares the live {mode,lifecycle}
+     *  against this and, on drift, injects guidance for the new state then commits
+     *  it here. */
+    persona_ack?: {
+        mode: Mode;
+        lifecycle: Lifecycle;
+    };
+    /** Spine parent — my manager (who subscribes to me); drives canvas nesting +
+     *  orphaning. null for a root (top-level, no manager). */
     parent?: string | null;
+    /** Provenance — who spawned me (the `spawned_by` edge). Decoupled from
+     *  `parent` so an INDEPENDENT root (parent=null) still records its lineage.
+     *  Audit only; null for a user-opened root. Defaults to `parent` for a child. */
+    spawned_by?: string | null;
     /** New subscriptions this node opens default to passive when true. */
     passive_default?: boolean;
-    /** Why the node last stopped (done | refresh). Drives reap-vs-revive. */
-    intent?: ExitIntent;
-    /** The pi session id for `--resume`. */
+    /** REVIVE-HOME — the tmux session a node is (re)opened into when it must
+     *  generate but is NOT focused (the durable revive target, distinct from the
+     *  live LOCATION held by the runtime `tmux_session`). Set once at birth
+     *  (managed child → the shared backstage `nodeSession()`; inline root → the
+     *  adopted caller session; independent `--root` → the caller session), and
+     *  rewritten only by demote-recycle. Durable identity (like `cwd`), never
+     *  touched by a focus swap — this is what keeps a background revive off the
+     *  user's session. Legacy metas omit it; readers default to
+     *  `tmux_session ?? nodeSession()` (see `homeSessionOf`). */
+    home_session?: string;
+    /** The pi session id for `--session <id>` revival. */
     pi_session_id?: string | null;
+    /** Absolute path to pi's session `.jsonl` file, captured at session_start via
+     *  ctx.sessionManager.getSessionFile(). Preferred over pi_session_id when
+     *  resuming: pi resolves a BARE `--session <id>` relative to the launch cwd
+     *  first (and shows an interactive cross-project "Fork? [y/N]" prompt when the
+     *  revive cwd differs from the session's creation cwd), whereas an absolute
+     *  PATH is opened directly — immune to any cwd discrepancy. Null for older
+     *  nodes booted before this field existed → revive falls back to the bare id. */
+    pi_session_file?: string | null;
     /** Full pi launch recipe; rewritten on every polymorph. */
     launch?: LaunchSpec;
+}
+/** A node's LIVE RUNTIME state — authoritative in the WAL'd `nodes` row, each
+ *  field mutated by exactly one atomic single-statement `UPDATE` (setStatus /
+ *  setIntent / setPresence / recordPid+clearPid). NOT persisted to meta.json and
+ *  NOT re-derivable by `rebuildIndex()` — it describes live process/presence
+ *  state that is meaningless after the event that would lose the db; the daemon
+ *  reconciles it from tmux reality, not from a stale file. */
+export interface NodeRuntime {
+    /** What the node is doing right now. */
+    status: NodeStatus;
+    /** Why the node last stopped (done | refresh | idle-release). Drives reap-vs-revive.
+     *  Optional on the hydrated view (a fresh construction omits it); the row
+     *  column is always present, defaulting null. */
+    intent?: ExitIntent;
+    /** OS pid of the live pi process, recorded on boot (stophook session_start).
+     *  The daemon's authoritative liveness signal: an inline root runs pi as a
+     *  child of a persistent login shell, so its tmux window outlives a dead pi —
+     *  window-existence alone can't detect the death, but a dead pid can. Cleared
+     *  to null by a window-backed relaunch (reviveNode) until the fresh pi
+     *  re-records it; left intact by an in-place respawn (reviveInPlace) so a
+     *  failed respawn surfaces as a dead pid. */
+    pi_pid?: number | null;
     /** Presence: the tmux session (its root's home) and window this node renders
      *  in while active. Cleared when the node goes done/dead and its window closes.
-     *  (Phase 5 promotes this to a dedicated presence registry.) */
+     *  The row IS the presence registry (one atomic setPresence per move).
+     *  v3: a DERIVED CACHE of `pane`'s current location — reconciled from the pane,
+     *  never trusted when a user move could have desynced them. */
     tmux_session?: string | null;
     window?: string | null;
+    /** LOCATION's authoritative handle — the durable tmux `%pane_id` this node's
+     *  pane is anchored on. tmux preserves it across `move-pane`/`join-pane`/
+     *  `break-pane` and window renumbering, so `window`/`tmux_session` above are a
+     *  cache reconciled from it and pane-existence is the liveness probe. A
+     *  not-focused + not-generating node has `pane = null` (no pane). Authoritative
+     *  in the row exactly like `window`/`tmux_session` — a RUNTIME field, NOT meta
+     *  identity — written by the one atomic `setPresence` UPDATE. */
+    pane?: string | null;
 }
-/** The queryable projection of a NodeMeta stored as a canvas.db row. */
+/** The hydrated node view `getNode()` returns: durable identity (from meta.json)
+ *  ∪ live runtime (from the row). Keeps the historical `NodeMeta` name and field
+ *  set so every `meta.X` read across the codebase typechecks unchanged — but
+ *  `writeMeta` serializes only the NodeIdentity subset and the runtime fields are
+ *  hydrated from the authoritative row. */
+export type NodeMeta = NodeIdentity & NodeRuntime;
+/** The queryable projection of a node stored as a canvas.db row: the indexed
+ *  identity columns PLUS the authoritative runtime columns. */
 export interface NodeRow {
     node_id: string;
     name: string;
@@ -65,6 +145,13 @@ export interface NodeRow {
     cwd: string;
     parent: string | null;
     created: string;
+    /** Authoritative runtime columns (see NodeRuntime). */
+    intent: ExitIntent;
+    pi_pid: number | null;
+    window: string | null;
+    tmux_session: string | null;
+    /** The durable LOCATION handle (the tmux `%pane_id`); see NodeRuntime.pane. */
+    pane: string | null;
 }
 /** An edge as stored. For `subscribes_to`, `from` is the subscriber and `to`
  *  is the publisher (A subscribes_to B ⇒ A receives B's output). For
@@ -78,6 +165,22 @@ export interface Edge {
     active: boolean;
     created: string;
 }
+/** A FOCUS row as stored in the `focuses` table (canvas.db, migration v6): one
+ *  durable on-screen viewport the user looks at, bound to one node. Plural —
+ *  many focuses live at once across windows and sessions (the plural
+ *  generalization of the old single `focus.ptr`). Anchored on the durable tmux
+ *  `%pane_id`; `session` is a derived cache reconciled from the pane. `node_id`
+ *  is UNIQUE — a node occupies at most one focus (Q5). */
+export interface FocusRow {
+    /** Stable internal id for the viewport (the table's primary key). */
+    focus_id: string;
+    /** The durable `%pane_id` realizing the focus, or null before it is placed. */
+    pane: string | null;
+    /** Derived cache of the user session the pane lives in (reconciled from pane). */
+    session: string | null;
+    /** The node this focus shows. UNIQUE → a node occupies ≤1 focus. */
+    node_id: string;
+}
 /** A subscription as seen from one endpoint. */
 export interface SubscriptionRef {
     /** The node id at the other end of the edge. */

package/dist/core/command.d.ts

@@ -1,4 +1,4 @@
-import type { RootHelp, RootEntry, BranchHelp, LeafHelp, InputParam } from './help.js';
+import type { RootHelp, RootEntry, BranchHelp, LeafHelp, InputParam, SubTier } from './help.js';
 import { CrtrError } from './errors.js';
 /** Opt-in flag that surfaces a node as an editor slash command (a pi prompt
  *  template / Claude Code command). When set, the bootstrap auto-writes a
@@ -19,6 +19,15 @@ export interface SlashSpec {
 export interface LeafDef {
     kind: 'leaf';
     name: string;
+    /** Short description for this node's <subcommand> row in its parent's -h. */
+    description?: string;
+    /** Selection rubric for the parent's listing — plainly states when to reach
+     *  for this command (expansive with examples for judgment-heavy ones, concise
+     *  for single-purpose). Rendered verbatim, no prefix. */
+    whenToUse?: string;
+    /** Visibility tier in ancestor listings (see SubTier). Default 'normal';
+     *  'hidden' keeps an internal leaf out of every listing. */
+    tier?: SubTier;
     help: LeafHelp;
     /** Opt into editor slash-command exposure (see SlashSpec). */
     slash?: SlashSpec;
@@ -31,6 +40,15 @@ export interface LeafDef {
 export interface BranchDef {
     kind: 'branch';
     name: string;
+    /** Short description for this node's <subcommand> row in its parent's -h.
+     *  Unused on a top-level subtree (its root representation is its rootEntry). */
+    description?: string;
+    /** Selection rubric for the parent's listing — plainly states when to reach
+     *  for this command (expansive with examples for judgment-heavy ones, concise
+     *  for single-purpose). Rendered verbatim, no prefix. */
+    whenToUse?: string;
+    /** Visibility tier in ancestor listings (see SubTier). Default 'normal'. */
+    tier?: SubTier;
     help: BranchHelp;
     /** How this subtree represents itself one level up. Present on top-level
      *  subtrees (assembled into root -h by defineRoot); omitted on nested
@@ -47,6 +65,9 @@ export interface RootDef {
 }
 export declare function defineLeaf(opts: {
     name: string;
+    description?: string;
+    whenToUse?: string;
+    tier?: SubTier;
     help: LeafHelp;
     slash?: SlashSpec;
     run: (input: Record<string, unknown>) => Promise<Record<string, unknown> | void>;
@@ -54,6 +75,9 @@ export declare function defineLeaf(opts: {
 }): LeafDef;
 export declare function defineBranch(opts: {
     name: string;
+    description?: string;
+    whenToUse?: string;
+    tier?: SubTier;
     help: BranchHelp;
     rootEntry?: RootEntry;
     slash?: SlashSpec;

package/dist/core/command.js

@@ -17,16 +17,43 @@ export function defineLeaf(opts) {
     return {
         kind: 'leaf',
         name: opts.name,
+        description: opts.description,
+        whenToUse: opts.whenToUse,
+        tier: opts.tier,
         help: opts.help,
         slash: opts.slash,
         run: opts.run,
         render: opts.render,
     };
 }
+/** Number of a node's own non-hidden subcommands (direct children). Leaves and
+ *  childless branches return 0. */
+function visibleSubCount(def) {
+    if (def.kind !== 'branch')
+        return 0;
+    return (def.help.listing ?? []).filter((c) => c.tier !== 'hidden').length;
+}
 export function defineBranch(opts) {
+    // Assemble the parent-level listing straight from the child defs — each node
+    // owns its own description/whenToUse/tier, so the parent copies nothing
+    // (principle 16). Bottom-up construction guarantees a child branch's listing
+    // is already computed, so subCount is available here.
+    opts.help.listing = opts.children.map((c) => {
+        const subCount = visibleSubCount(c);
+        return {
+            name: c.name,
+            description: c.description ?? '',
+            whenToUse: c.whenToUse ?? '',
+            tier: c.tier ?? 'normal',
+            ...(subCount > 0 ? { subCount } : {}),
+        };
+    });
     return {
         kind: 'branch',
         name: opts.name,
+        description: opts.description,
+        whenToUse: opts.whenToUse,
+        tier: opts.tier,
         help: opts.help,
         rootEntry: opts.rootEntry,
         slash: opts.slash,
@@ -60,13 +87,27 @@ export function defineRoot(opts) {
     // and dynamic block all travel with it.
     const commands = opts.subtrees
         .filter((s) => s.rootEntry !== undefined)
-        .map((s) => ({
-        name: s.name,
-        concept: s.rootEntry.concept,
-        desc: s.rootEntry.desc,
-        useWhen: s.rootEntry.useWhen,
-        dynamicState: s.rootEntry.dynamicState,
-    }));
+        .map((s) => {
+        // Promote this subtree's common/important children into root, and count
+        // how many other (non-hidden) direct subcommands stay behind `<name> -h`.
+        const visible = (s.help.listing ?? []).filter((c) => c.tier !== 'hidden');
+        const promoted = visible
+            .filter((c) => c.tier === 'common' || c.tier === 'important')
+            .map((c) => ({
+            path: `${s.name} ${c.name}`,
+            // important carries its shortform desc; common shows the bare path.
+            desc: c.tier === 'important' ? c.description : undefined,
+        }));
+        return {
+            name: s.name,
+            concept: s.rootEntry.concept,
+            desc: s.rootEntry.desc,
+            useWhen: s.rootEntry.useWhen,
+            dynamicState: s.rootEntry.dynamicState,
+            subcommands: promoted.length > 0 ? promoted : undefined,
+            otherSubcommandCount: visible.length - promoted.length,
+        };
+    });
     const help = {
         tagline: opts.tagline,
         commands,

package/dist/core/config.js

@@ -1,5 +1,5 @@
 import { join } from 'node:path';
-import { CONFIG_FILE, STATE_FILE, SCHEMA_VERSION, defaultScopeConfig, defaultScopeState } from '../types.js';
+import { CONFIG_FILE, STATE_FILE, SCHEMA_VERSION, defaultScopeConfig, defaultScopeState, defaultCanvasNavConfig } from '../types.js';
 import { readJsonIfExists, writeJson, ensureDir } from './fs-utils.js';
 import { scopeRoot, requireScopeRoot } from './scope.js';
 import { diag } from './io.js';
@@ -74,6 +74,39 @@ export function ensureScopeInitialized(scope, root) {
         writeJson(cfgPath, defaultScopeConfig());
     }
 }
+/** Deep-merge one bind table over its built-in defaults: a user adding a single
+ *  bind must not wipe the rest. Each user entry is validated (a `run` string is
+ *  required) before it replaces/extends a key. */
+function mergeBinds(base, over) {
+    const out = { ...base };
+    if (over !== null && typeof over === 'object') {
+        for (const [k, v] of Object.entries(over)) {
+            if (v !== null && typeof v === 'object' && typeof v.run === 'string') {
+                const b = v;
+                out[k] = {
+                    run: b.run,
+                    ...(b.confirm === true ? { confirm: true } : {}),
+                    ...(typeof b.desc === 'string' ? { desc: b.desc } : {}),
+                };
+            }
+        }
+    }
+    return out;
+}
+/** Validate + deep-merge a user `canvasNav` block over the built-in defaults.
+ *  An absent or malformed block falls back wholesale to defaults. */
+function mergeCanvasNav(raw) {
+    const defaults = defaultCanvasNavConfig();
+    if (raw === null || typeof raw !== 'object')
+        return defaults;
+    const r = raw;
+    const prefixKey = typeof r.prefixKey === 'string' && r.prefixKey.trim() !== '' ? r.prefixKey : defaults.prefixKey;
+    return {
+        prefixKey,
+        prefixBinds: mergeBinds(defaults.prefixBinds, r.prefixBinds),
+        graphBinds: mergeBinds(defaults.graphBinds, r.graphBinds),
+    };
+}
 function normalizeMode(value, fallback) {
     if (value === true)
         return 'notify';
@@ -103,7 +136,8 @@ function mergeConfig(partial) {
     const max_panes_per_window = typeof rawMaxPanes === 'number' && Number.isFinite(rawMaxPanes) && rawMaxPanes >= 1
         ? Math.floor(rawMaxPanes)
         : defaults.max_panes_per_window;
-    return { schema_version, marketplaces, plugins, skills, auto_update, max_panes_per_window };
+    const canvasNav = mergeCanvasNav(partial.canvasNav);
+    return { schema_version, marketplaces, plugins, skills, auto_update, max_panes_per_window, canvasNav };
 }
 export function updateConfig(scope, mutate) {
     const cfg = readConfig(scope);