@crouton-kit/crouter 0.3.29 → 0.3.30

package/dist/build-root.d.ts

@@ -1,8 +1,16 @@
 import type { RootDef } from './core/command.js';
-/** Assemble the full crtr command tree. Root owns only the tagline; every
- *  subtree declares its own root representation via its rootEntry, and every
- *  branch assembles its child listing from the child defs (each child owns its
- *  description/whenToUse/tier). No globals: -h is taught by each child's
- *  whenToUse CTA and the capability-discovery rule in the root footer, so a
- *  standalone "-h: print help" stub would be redundant. */
-export declare function buildRoot(): RootDef;
+/** Every shipped subtree name. Cheap (no module loading) — the front-door
+ *  recursion guard and the dispatcher's first-token routing need only names. */
+export declare const SUBTREE_NAMES: string[];
+/** Build a root that contains only the subtree `first` dispatches into.
+ *  Returns the FULL root when `first` is not a recognized subtree — bare `crtr`,
+ *  `-h`/`--help`, `--version`, and any unknown leading token all need the
+ *  complete tree (root -h lists every subtree; the unknown-path error names
+ *  every valid child). This keeps every help/error surface byte-identical while
+ *  the common leaf-dispatch path loads exactly one subtree. */
+export declare function resolveRoot(first: string | undefined): Promise<RootDef>;
+/** Assemble the full crtr command tree (all subtrees). Used for root -h, the
+ *  unknown-path error, bare-root boot, and the listing-completeness test. Root
+ *  owns only the tagline; every subtree declares its own root representation via
+ *  its rootEntry. */
+export declare function buildRoot(): Promise<RootDef>;

package/dist/build-root.js

@@ -1,38 +1,50 @@
 import { defineRoot } from './core/command.js';
-import { registerMemory } from './commands/memory.js';
-import { registerPkg } from './commands/pkg.js';
-import { registerHuman } from './commands/human.js';
-import { registerSys } from './commands/sys.js';
-import { registerPush, registerFeed } from './commands/push.js';
-import { registerNode } from './commands/node.js';
-import { registerCanvas } from './commands/canvas.js';
-import { registerView } from './commands/view.js';
-import { registerAttach } from './clients/attach/attach-cmd.js';
-import { registerWorkspace } from './commands/workspace.js';
-import { registerWeb } from './clients/web/web-cmd.js';
-/** Assemble the full crtr command tree. Root owns only the tagline; every
- *  subtree declares its own root representation via its rootEntry, and every
- *  branch assembles its child listing from the child defs (each child owns its
- *  description/whenToUse/tier). No globals: -h is taught by each child's
- *  whenToUse CTA and the capability-discovery rule in the root footer, so a
- *  standalone "-h: print help" stub would be redundant. */
-export function buildRoot() {
-    return defineRoot({
-        tagline: 'crtr: agentic planning runtime.',
-        globals: [],
-        subtrees: [
-            registerMemory(),
-            registerPkg(),
-            registerHuman(),
-            registerSys(),
-            registerNode(),
-            registerPush(),
-            registerFeed(),
-            registerCanvas(),
-            registerView(),
-            registerAttach(),
-            registerWorkspace(),
-            registerWeb(),
-        ],
-    });
+const TAGLINE = 'crtr: agentic planning runtime.';
+/** Lazy registry: subtree name → dynamic importer that builds its BranchDef.
+ *  The whole point is that each `import()` only compiles that one subtree's
+ *  module graph. The hot path (`crtr node focus …`, `crtr feed`, …) dispatches
+ *  into a single leaf, so it must load ONE subtree — not the attach-TUI
+ *  (babel/highlight.js), the web/vite command, and every other subtree it never
+ *  touches. `crtr` cold-start is dominated by Node module loading; keeping the
+ *  other 11 subtrees off the path is the biggest, lowest-risk win.
+ *
+ *  Naming note: `push` and `feed` are two subtrees from one module — importing
+ *  it once yields both registers. */
+const SUBTREE_LOADERS = {
+    memory: async () => (await import('./commands/memory.js')).registerMemory(),
+    pkg: async () => (await import('./commands/pkg.js')).registerPkg(),
+    human: async () => (await import('./commands/human.js')).registerHuman(),
+    sys: async () => (await import('./commands/sys.js')).registerSys(),
+    node: async () => (await import('./commands/node.js')).registerNode(),
+    push: async () => (await import('./commands/push.js')).registerPush(),
+    feed: async () => (await import('./commands/push.js')).registerFeed(),
+    canvas: async () => (await import('./commands/canvas.js')).registerCanvas(),
+    view: async () => (await import('./commands/view.js')).registerView(),
+    attach: async () => (await import('./clients/attach/attach-cmd.js')).registerAttach(),
+    workspace: async () => (await import('./commands/workspace.js')).registerWorkspace(),
+    web: async () => (await import('./clients/web/web-cmd.js')).registerWeb(),
+};
+/** Every shipped subtree name. Cheap (no module loading) — the front-door
+ *  recursion guard and the dispatcher's first-token routing need only names. */
+export const SUBTREE_NAMES = Object.keys(SUBTREE_LOADERS);
+/** Build a root that contains only the subtree `first` dispatches into.
+ *  Returns the FULL root when `first` is not a recognized subtree — bare `crtr`,
+ *  `-h`/`--help`, `--version`, and any unknown leading token all need the
+ *  complete tree (root -h lists every subtree; the unknown-path error names
+ *  every valid child). This keeps every help/error surface byte-identical while
+ *  the common leaf-dispatch path loads exactly one subtree. */
+export async function resolveRoot(first) {
+    const loader = first !== undefined ? SUBTREE_LOADERS[first] : undefined;
+    if (loader !== undefined) {
+        return defineRoot({ tagline: TAGLINE, globals: [], subtrees: [await loader()] });
+    }
+    return buildRoot();
+}
+/** Assemble the full crtr command tree (all subtrees). Used for root -h, the
+ *  unknown-path error, bare-root boot, and the listing-completeness test. Root
+ *  owns only the tagline; every subtree declares its own root representation via
+ *  its rootEntry. */
+export async function buildRoot() {
+    const subtrees = await Promise.all(SUBTREE_NAMES.map((n) => SUBTREE_LOADERS[n]()));
+    return defineRoot({ tagline: TAGLINE, globals: [], subtrees });
 }

package/dist/cli.js

@@ -1,25 +1,30 @@
 #!/usr/bin/env node
 import { runCli } from './core/command.js';
-import { buildRoot } from './build-root.js';
+import { resolveRoot } from './build-root.js';
 import { maybeBootRoot } from './core/runtime/front-door.js';
 import { maybeAutoUpdate } from './core/auto-update.js';
 import { ensureOfficialMarketplace, ensureProjectScope } from './core/bootstrap.js';
 import { provisionExports } from './core/skill-sync/export.js';
-// The full command tree is assembled in build-root.ts (shared with the
-// listing-completeness test). Root owns only the tagline; every subtree
-// declares its own representation.
-const root = buildRoot();
-// The front door: bare `crtr` (or `crtr [dir] ["prompt"]`) boots a resident
-// root node and execs pi in this terminal. Recognized subcommands fall through
-// to the normal dispatcher. Must run before anything that assumes a subcommand.
-if (maybeBootRoot(root, process.argv)) {
-    // bootRoot exec'd pi inline and exited; unreachable.
+async function main() {
+    // Lazy command tree: load only the subtree this invocation dispatches into.
+    // resolveRoot returns the full tree only for help/version/bare/unknown, where
+    // every subtree is genuinely needed (root -h, the unknown-path error). The
+    // hot leaf-dispatch path loads one subtree, keeping the other 11 (and their
+    // heavy deps — the attach TUI, web/vite) off cold-start.
+    const root = await resolveRoot(process.argv[2]);
+    // The front door: bare `crtr` (or `crtr [dir] ["prompt"]`) boots a resident
+    // root node and execs pi in this terminal. Recognized subcommands fall through
+    // to the normal dispatcher. Must run before anything that assumes a subcommand.
+    if (maybeBootRoot(root, process.argv)) {
+        // bootRoot exec'd pi inline and exited; unreachable.
+    }
+    ensureOfficialMarketplace(process.argv);
+    provisionExports(root);
+    ensureProjectScope(process.argv);
+    maybeAutoUpdate(process.argv);
+    await runCli(root, process.argv);
 }
-ensureOfficialMarketplace(process.argv);
-provisionExports(root);
-ensureProjectScope(process.argv);
-maybeAutoUpdate(process.argv);
-runCli(root, process.argv).catch((err) => {
+main().catch((err) => {
     const msg = err instanceof Error ? err.message : String(err);
     process.stderr.write(`crtr: ${msg}\n`);
     process.exit(1);

package/dist/commands/chord.js

@@ -8,8 +8,7 @@
 // `crtr <argv>`. This keeps the menu static while the behaviour stays fully
 // config-driven (no per-node menu rebuild).
 //
-// Two special cases bypass the bind table:
-//   • a digit key 1..9 → focus report N (the Nth live report of the pane node)
+// One special case bypasses the bind table:
 //   • a bind whose `run` is the sentinel `__graph__` → send-keys `/graph` into
 //     the pane (toggles the in-pi GRAPH modal); the menu emits this directly so
 //     the dispatcher only handles it defensively.
@@ -23,7 +22,7 @@ import { InputError } from '../core/io.js';
 import { readConfig } from '../core/config.js';
 import { sendKeysEnter } from '../core/runtime/tmux-chrome.js';
 import { nodeInPane } from './node.js';
-import { getNode, subscribersOf, subscriptionsOf, view, fullName, } from '../core/canvas/index.js';
+import { getNode, subscribersOf, view, fullName, } from '../core/canvas/index.js';
 const pexec = promisify(execFile);
 /** Template vars available to a `run` string. Single-valued vars interpolate
  *  in place (preserving spaces, e.g. a node name); `{subtree}` is multi-valued
@@ -76,7 +75,7 @@ export const chordLeaf = defineLeaf({
                 name: 'key',
                 type: 'string',
                 required: true,
-                constraint: 'The chord key pressed after alt+c (e.g. m, e, or a digit 1-9 for focus report N).',
+                constraint: 'The chord key pressed after alt+c (e.g. g or m).',
             },
         ],
         output: [
@@ -99,26 +98,6 @@ export const chordLeaf = defineLeaf({
                 next: 'Run from inside an agent\'s pane, or pass --pane <pane-id>.',
             });
         }
-        // Digit keys 1..9 → focus the Nth live report (generated, not a bind entry).
-        if (/^[1-9]$/.test(key)) {
-            const n = parseInt(key, 10);
-            const reports = subscriptionsOf(selfId)
-                .map((r) => r.node_id)
-                .filter((id) => {
-                const s = getNode(id)?.status;
-                return s === 'active' || s === 'idle';
-            });
-            const target = reports[n - 1];
-            if (target === undefined)
-                return { ran: false, key, node_id: selfId, action: 'noop' };
-            try {
-                await pexec('crtr', ['node', 'focus', target], { timeout: 15_000 });
-            }
-            catch {
-                /* best-effort */
-            }
-            return { ran: true, key, node_id: selfId, action: `node focus ${target}` };
-        }
         const bind = readConfig('user').canvasNav.prefixBinds[key];
         if (bind === undefined)
             return { ran: false, key, node_id: selfId, action: 'noop' };

package/dist/core/__tests__/listing-completeness.test.js

@@ -9,8 +9,8 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { buildRoot } from '../../build-root.js';
-test('every non-hidden listing child declares description + whenToUse', () => {
-    const root = buildRoot();
+test('every non-hidden listing child declares description + whenToUse', async () => {
+    const root = await buildRoot();
     const missing = [];
     const walk = (branch, path) => {
         for (const child of branch.help.listing ?? []) {

package/dist/core/runtime/placement.d.ts

@@ -23,11 +23,11 @@ export declare function listFocuses(): FocusRow[];
  *  targeting it. */
 export declare function graphSurfaceTarget(nodeId: string): FocusRow | null;
 /** Synchronously wait until a broker's view.sock accepts a connection. The spawn
- *  and focus flows are sync (the command layer calls them directly), so the
- *  readiness probe lives in a short child Node process that can use async net
- *  events while this process blocks in `spawnSync`. Success proves more than file
- *  existence: it is robust to a stale leftover socket the launching broker has
- *  not unlinked yet, because only an accepting listener exits 0. */
+ *  and focus flows are sync (the command layer calls them directly), so the async
+ *  net poll runs in a worker THREAD while this thread blocks on `Atomics.wait` —
+ *  in-process, no child Node cold-start. Success proves more than file existence:
+ *  it is robust to a stale leftover socket the launching broker has not unlinked
+ *  yet, because only an accepting listener yields a `connect`. */
 export declare function waitForBrokerViewSocket(nodeId: string): boolean;
 /** A reviver: ensure a node's broker ENGINE is alive (idempotent → reviveNode →
  *  headlessBrokerHost.launch). Injected so placement.ts need not import revive.ts

package/dist/core/runtime/placement.js

@@ -23,7 +23,7 @@
 //     model-over-driver so the §5.1 import-lint ("only placement.ts /
 //     tmux-chrome.ts import tmux.ts") holds — every other module reaches the
 //     driver verbs through here.
-import { spawnSync } from 'node:child_process';
+import { Worker } from 'node:worker_threads';
 import { join } from 'node:path';
 import { getNode, openFocusRow, closeFocusRow, getFocusByNode, getFocusByPane, getFocusById, listFocuses as listFocusRows, view, } from '../canvas/index.js';
 import { paneExists, paneLocation, ensureSession, openNodeWindow, splitWindow, closePane, currentTmux, switchClient, selectWindow, getPaneOption, } from './tmux.js';
@@ -115,19 +115,17 @@ export function graphSurfaceTarget(nodeId) {
 // ---------------------------------------------------------------------------
 const BROKER_FOCUS_SOCKET_WAIT_MS = 30_000;
 const BROKER_FOCUS_SOCKET_RETRY_MS = 100;
-/** Synchronously wait until a broker's view.sock accepts a connection. The spawn
- *  and focus flows are sync (the command layer calls them directly), so the
- *  readiness probe lives in a short child Node process that can use async net
- *  events while this process blocks in `spawnSync`. Success proves more than file
- *  existence: it is robust to a stale leftover socket the launching broker has
- *  not unlinked yet, because only an accepting listener exits 0. */
-export function waitForBrokerViewSocket(nodeId) {
-    const sockPath = join(nodeDir(nodeId), 'view.sock');
-    const probe = `
+// The probe runs inside a worker thread (see waitForBrokerViewSocket). Async net
+// events drive the same poll loop; the worker reports its verdict into a shared
+// Int32 (0 = pending, 1 = accepted, 2 = gave up) and Atomics.notify wakes the
+// blocked main thread. eval:true ⇒ CommonJS, so `require` and workerData apply.
+const VIEW_SOCKET_PROBE_WORKER = `
 const net = require('node:net');
-const sockPath = process.argv[1];
-const deadline = Date.now() + Number(process.argv[2]);
-const delay = Number(process.argv[3]);
+const { workerData, parentPort } = require('node:worker_threads');
+const { buffer, sockPath, waitMs, retryMs } = workerData;
+const result = new Int32Array(buffer);
+const deadline = Date.now() + waitMs;
+const report = (code) => { Atomics.store(result, 0, code); Atomics.notify(result, 0); };
 function attempt() {
   let socket;
   let settled = false;
@@ -135,9 +133,9 @@ function attempt() {
     if (settled) return;
     settled = true;
     if (socket !== undefined) socket.destroy();
-    if (ok) process.exit(0);
-    if (Date.now() >= deadline) process.exit(1);
-    setTimeout(attempt, delay);
+    if (ok) { report(1); return; }
+    if (Date.now() >= deadline) { report(2); return; }
+    setTimeout(attempt, retryMs);
   };
   try {
     socket = net.createConnection(sockPath);
@@ -147,18 +145,31 @@ function attempt() {
   }
   socket.once('connect', () => finish(true));
   socket.once('error', () => finish(false));
-  socket.setTimeout(delay, () => finish(false));
+  socket.setTimeout(retryMs, () => finish(false));
 }
 attempt();
+void parentPort;
 `;
-    const r = spawnSync(process.execPath, ['--input-type=commonjs', '-e', probe, sockPath, String(BROKER_FOCUS_SOCKET_WAIT_MS), String(BROKER_FOCUS_SOCKET_RETRY_MS)], {
-        stdio: 'ignore',
-        timeout: BROKER_FOCUS_SOCKET_WAIT_MS + 1_000,
-        // Keep the probe deterministic: NODE_OPTIONS like --input-type=module or
-        // --inspect-brk can break/hang a tiny `node -e` readiness check.
-        env: { ...process.env, NODE_OPTIONS: '' },
+/** Synchronously wait until a broker's view.sock accepts a connection. The spawn
+ *  and focus flows are sync (the command layer calls them directly), so the async
+ *  net poll runs in a worker THREAD while this thread blocks on `Atomics.wait` —
+ *  in-process, no child Node cold-start. Success proves more than file existence:
+ *  it is robust to a stale leftover socket the launching broker has not unlinked
+ *  yet, because only an accepting listener yields a `connect`. */
+export function waitForBrokerViewSocket(nodeId) {
+    const sockPath = join(nodeDir(nodeId), 'view.sock');
+    const buffer = new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT);
+    const result = new Int32Array(buffer);
+    const worker = new Worker(VIEW_SOCKET_PROBE_WORKER, {
+        eval: true,
+        workerData: { buffer, sockPath, waitMs: BROKER_FOCUS_SOCKET_WAIT_MS, retryMs: BROKER_FOCUS_SOCKET_RETRY_MS },
     });
-    return r.status === 0;
+    worker.unref();
+    // Block until the worker reports (or a hard timeout matching the old
+    // spawnSync). 'not-equal' covers the worker finishing before we wait.
+    Atomics.wait(result, 0, 0, BROKER_FOCUS_SOCKET_WAIT_MS + 1_000);
+    void worker.terminate();
+    return Atomics.load(result, 0) === 1;
 }
 function newFocusId() {
     return `f-${newNodeId()}`;

package/dist/core/runtime/tmux.d.ts

@@ -178,8 +178,8 @@ export declare function switchClient(session: string): boolean;
  *  empty, same limitation as the menu's `/promote` item. Best-effort. */
 export declare function sendKeysEnter(pane: string, text: string): boolean;
 /** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails.
- *  The built-in items (promote/demote/detach/close/browse) are static; the canvas-nav
- *  chords (graph/manager/expand/report-N + any custom prefixBind) are appended
+ *  The built-in items (promote/resume/demote/detach/close) are static; the canvas-nav
+ *  chords (default g→graph, m→manager + any custom prefixBind) are appended
  *  from `canvasNav.prefixBinds`, each routed through `crtr canvas chord` (or, for
  *  the `__graph__` sentinel, a `send-keys '/graph'`) so the menu stays static
  *  while behaviour is config-driven. */

package/dist/core/runtime/tmux.js

@@ -336,8 +336,8 @@ export function sendKeysEnter(pane, text) {
  *  `prefixBind` may not claim these (the built-in item wins). */
 const RESERVED_MENU_KEYS = new Set(['o', 'r', 'd', 'D', 'x']);
 /** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails.
- *  The built-in items (promote/demote/detach/close/browse) are static; the canvas-nav
- *  chords (graph/manager/expand/report-N + any custom prefixBind) are appended
+ *  The built-in items (promote/resume/demote/detach/close) are static; the canvas-nav
+ *  chords (default g→graph, m→manager + any custom prefixBind) are appended
  *  from `canvasNav.prefixBinds`, each routed through `crtr canvas chord` (or, for
  *  the `__graph__` sentinel, a `send-keys '/graph'`) so the menu stays static
  *  while behaviour is config-driven. */
@@ -363,7 +363,7 @@ export function installMenuBinding() {
         // marks them canceled); revivable. Output discarded — the keypress just acts.
         { name: 'close agent + subtree', key: 'x', cmd: `run-shell "crtr node close --pane '#{pane_id}' >/dev/null 2>&1"` },
     ];
-    // Canvas-nav chords from config (default: g→graph, m→manager, e→expand). The
+    // Canvas-nav chords from config (default: g→graph, m→manager). The
     // `__graph__` sentinel toggles the in-pi GRAPH modal via send-keys; every
     // other bind shells the chord dispatcher, which resolves the pane's node and
     // interpolates the bind at popup time. Keys colliding with the built-ins are
@@ -382,26 +382,16 @@ export function installMenuBinding() {
             : `run-shell "crtr canvas chord --pane '#{pane_id}' --key ${key} >/dev/null 2>&1"`;
         items.push({ name, key, cmd });
     }
-    // Focus report N: nine generated chord items (1..9), each resolved by the
-    // dispatcher to subscriptionsOf(self)[N-1] at popup time.
-    for (let n = 1; n <= 9; n++) {
-        items.push({
-            name: `focus report ${n}`,
-            key: `${n}`,
-            cmd: `run-shell "crtr canvas chord --pane '#{pane_id}' --key ${n} >/dev/null 2>&1"`,
-        });
-    }
-    // Alt+C TOGGLE: re-pressing Alt+C while the menu is open should DISMISS it.
-    // display-menu is modal, so the root `M-c` binding is shadowed while the menu
-    // is up; tmux instead assembles the re-pressed Esc+c into the meta key `M-c`
-    // and delivers it to the menu's own key handler. An unhandled key is ignored
-    // (the menu just stays open) and the trailing `c` never leaks to the editor
-    // (verified empirically in tmux 3.6b: no native ESC-cancel + c-leak occurs for
-    // an atomic keypress). We catch that `M-c` with a menu item keyed to it whose
-    // command is empty — selecting it runs nothing and closes the menu. The row
-    // doubles as the menu's self-documenting dismiss hint. Placed last so it reads
-    // as chrome below the actions; `M-c` collides with no mnemonic above.
-    items.push({ name: 'close menu', key: 'M-c', cmd: '' });
+    // Dismiss hint. A tmux display-menu always closes on its native cancel keys
+    // (Escape / q / C-c), encoding-independent. We do NOT try to catch a re-pressed
+    // Alt+C: under `extended-keys on` (common, and what pi negotiates) the second
+    // Alt+C reaches the overlay as a CSI-u key (`\033[99;3u`) that tmux's menu does
+    // NOT match against an `M-c` mnemonic item, so a "close menu" row keyed M-c
+    // never fires and the menu just sits open (verified in tmux 3.6b: legacy Esc+c
+    // closes, CSI-u does not). Instead, a disabled (`-` prefix → dim, unselectable)
+    // last row tells the user the close keys that always work. Placed last so it
+    // reads as chrome below the actions.
+    items.push({ name: '-esc / q to close', key: '', cmd: '' });
     // tmux's -x sets the menu's LEFT edge. To sit the box INSIDE the pane's
     // top-right corner, shift x left by the box width (longest line + tmux chrome:
     // borders + padding + the right-aligned mnemonic-key column) via format math.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.29",
+  "version": "0.3.30",
   "description": "crtr — fast access to skills, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",