@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/commands/view-cycle.js

@@ -1,4 +1,4 @@
-// `crtr view cycle <dir>` — switch the view hosted in a monitor pane to the
+// `crtr surface view cycle` — switch the view hosted in a monitor pane to the
 // next/prev available view, in place. Backs the Alt+V then ] (next) / Alt+V
 // then [ (prev) chord installed by installViewNavBindings, mirroring how
 // `node cycle` backs Alt+] / Alt+[ for the node graph (view = the bracket
@@ -7,7 +7,7 @@
 // A view monitor pane is self-identifying: `view run` tags it with the tmux
 // pane option @crtr_view=<id>. Cycle reads that tag, computes the next/prev id
 // in `listViews()` order (the SAME set `view list` enumerates), and respawns
-// the pane on `crtr view run <next-id>` — `respawn-pane -k` kills the current
+// the pane on the surface-view run command — `respawn-pane -k` kills the current
 // view process and re-execs in the SAME pane (cycle itself runs in tmux's
 // run-shell context, NOT inside the pane, so the kill never targets the caller).
 // The respawned run re-tags the pane, so a rapid re-cycle reads the right id.
@@ -22,7 +22,7 @@ import { inTmux, currentTmux, getPaneOption, setPaneOption, paneCurrentPath, res
 export const viewCycleLeaf = defineLeaf({
     name: 'cycle',
     description: 'switch the monitor pane to the next/prev view in place',
-    whenToUse: 'flipping a view monitor to the next/prev available view without re-running a command (bound to Alt+V then ] forward / Alt+V then [ back). The pane must already be hosting a view — opened with `crtr view run <name>` (or --window/--split). Use `crtr view run <name>` to open a specific view, or `crtr view list` to see the cycle order',
+    whenToUse: 'flipping a view monitor to the next or previous available view without re-running a command (bound to Alt+V then ] forward / Alt+V then [ back). The pane must already be hosting a view and the view list must contain a different target. Use run to open a specific view, or list to see the cycle order',
     help: {
         name: 'view cycle',
         summary: 'switch the view hosted in a monitor pane to the next/previous available view, in place — the views walked one monitor at a time, in `view list` order (bound to Alt+V then ] forward / Alt+V then [ back)',
@@ -37,7 +37,7 @@ export const viewCycleLeaf = defineLeaf({
         ],
         outputKind: 'object',
         effects: [
-            'Respawns the target pane (respawn-pane -k) running `crtr view run <next-id>`; the prior view process is replaced in place.',
+            'Respawns the target pane in place running the next view; the prior view process is replaced.',
             'Re-tags the pane @crtr_view=<next-id>. No-op outside tmux or when the pane is not a view monitor.',
         ],
     },
@@ -96,7 +96,7 @@ export const viewCycleLeaf = defineLeaf({
         // the MONITOR (pane), not the view, and are harmless to views that ignore them.
         const keepPort = getPaneOption(pane, '@crtr_view_port');
         const keepTarget = getPaneOption(pane, '@crtr_view_target');
-        const argv = ['view', 'run', targetId];
+        const argv = ['surface', 'view', 'run', targetId];
         if (keepPort !== undefined && keepPort !== '')
             argv.push('--port', keepPort);
         if (keepTarget !== undefined && keepTarget !== '')

package/dist/commands/view-list.js

@@ -1,4 +1,4 @@
-// `crtr view list` — enumerate every resolvable view across scopes.
+// `crtr surface view list` — enumerate every resolvable view across scopes.
 //
 // Lists id · title · description · scope. Loads each view's core.mjs to read its
 // manifest title/description; a malformed view is shown with an error marker (it
@@ -9,7 +9,7 @@ import { listViews, loadCore } from '../core/view/loader.js';
 export const viewListLeaf = defineLeaf({
     name: 'list',
     description: 'enumerate available views (id · title · description · scope)',
-    whenToUse: 'you want to see which views exist before running one — a flat roster across project, user, and builtin scopes. Pipeable plain text; pass --json for the raw array. Use `crtr view run <id>` to open one, `crtr view new <name>` to scaffold one',
+    whenToUse: 'you want to see which views exist before running one — a flat roster across project, user, and builtin scopes. Pipeable plain text; pass --json for the raw array. Use run to open one and new to scaffold one',
     help: {
         name: 'view list',
         summary: 'list every resolvable view (id, title, description, scope); pipeable plain text',
@@ -48,7 +48,7 @@ export const viewListLeaf = defineLeaf({
     render: (result) => {
         const rows = result['views'] ?? [];
         if (rows.length === 0) {
-            return 'No views found. Scaffold one with `crtr view new <name>`.';
+            return 'No views found. Scaffold one with the view new leaf.';
         }
         const idW = Math.max(...rows.map((r) => r.id.length), 2);
         const titleW = Math.max(...rows.map((r) => r.title.length), 5);

package/dist/commands/view-new.js

@@ -1,10 +1,10 @@
-// `crtr view new <name>` — scaffold a runnable dual-target view into a scope dir.
+// `crtr surface view new` — scaffold a runnable dual-target view into a scope dir.
 //
 // Writes the four contract files (core.mjs + tui.mjs + web.jsx + text.mjs) under
 // <viewsDir(scope)>/<name>/ from the stubs in prompts/view.ts (mkdir -p first).
 // Refuses if a view of that name already resolves. The scaffold runs as-is via
-// `crtr view run <name>` (TUI) and `crtr view serve <name>` (web). Mirrors how
-// skill authoring scaffolds (resolve scope → ensure dir → write → point at run).
+// the surface view host (TUI/static) and the surface web server. Mirrors the
+// scope → ensure dir → write → point-at-run shape of other authoring commands.
 import { mkdirSync, existsSync } from 'node:fs';
 import { writeFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -16,7 +16,7 @@ import { viewScaffold } from '../prompts/view.js';
 export const viewNewLeaf = defineLeaf({
     name: 'new',
     description: 'scaffold a runnable dual-target view directory into a scope dir',
-    whenToUse: 'you want to author a new view — this writes the four contract files (core.mjs + tui.mjs + web.jsx + text.mjs, with the contract documented inline) into the user or project scope, ready to open immediately with `crtr view run <name>` (TUI) or `crtr view serve <name>` (web) and to edit from there. Reach for it to start a new view rather than hand-writing the directory',
+    whenToUse: 'you want to author a new view — this writes the four contract files (core.mjs + tui.mjs + web.jsx + text.mjs, with the contract documented inline) into the user or project scope, ready to open in either host and to edit from there. Reach for it to start a new view rather than hand-writing the directory',
     help: {
         name: 'view new',
         summary: 'scaffold <viewsDir(scope)>/<name>/{core,tui,text}.mjs + web.jsx from the stubs; refuses if the name already resolves',
@@ -24,7 +24,7 @@ export const viewNewLeaf = defineLeaf({
             { kind: 'positional', name: 'name', required: true, constraint: 'View id / directory name. Must not already resolve as a view.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Where to scaffold. Default: project if available, else user.' },
             { kind: 'flag', name: 'title', type: 'string', required: false, constraint: 'Manifest title (header + picker). Default: the name.' },
-            { kind: 'flag', name: 'description', type: 'string', required: false, constraint: 'Manifest description (picker + `view list`). Default: empty.' },
+            { kind: 'flag', name: 'description', type: 'string', required: false, constraint: 'Manifest description (picker and list). Default: empty.' },
         ],
         output: [
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the scaffolded view directory.' },
@@ -69,6 +69,6 @@ export const viewNewLeaf = defineLeaf({
         for (const [filename, content] of Object.entries(files)) {
             writeFileSync(join(dir, filename), content, 'utf8');
         }
-        return { path: dir, files: Object.keys(files), scope, run: `crtr view run ${name}` };
+        return { path: dir, files: Object.keys(files), scope, run: `crtr surface view run ${name}` };
     },
 });

package/dist/commands/view-pick.js

@@ -1,7 +1,7 @@
-// `crtr view pick` — hidden raw-ANSI picker over the available views.
+// `crtr surface view pick` — hidden raw-ANSI picker over the available views.
 //
 // Backs the /view popup: a minimal full-screen list of listViews(); j/k move,
-// Enter hands off to `crtr view run <id>` (execFileSync, stdio inherit — a
+// Enter hands off to the surface-view run command (execFileSync, stdio inherit — a
 // one-way handoff, the picker exits as the view takes over, same pattern as
 // browse's selectAndFocus), q/Esc/Ctrl-C quit. Outside a TTY it prints the
 // plain list and exits 0. Reuses the core/tui terminal + draw primitives.
@@ -14,7 +14,7 @@ export const viewPickLeaf = defineLeaf({
     name: 'pick',
     tier: 'hidden',
     description: 'raw-ANSI view picker (used by the /view popup)',
-    whenToUse: 'internal — the /view popup shells this to choose a view, then it execs `crtr view run <id>`. You normally run `crtr view run <name>` or `crtr view list` directly',
+    whenToUse: 'internal — the picker chooses a view for the popup, then hands off to the view host. You normally use run or list directly',
     help: {
         name: 'view pick',
         summary: 'interactive picker over available views; Enter runs the chosen view. Outside a TTY it prints the list and exits',
@@ -23,7 +23,7 @@ export const viewPickLeaf = defineLeaf({
         outputKind: 'object',
         effects: [
             'Inside a TTY: takes over the terminal in raw mode until you pick (Enter) or quit (q/Esc/Ctrl-C).',
-            'On Enter: execs `crtr view run <id>` (stdio inherited) — a one-way handoff; the picker exits.',
+            'On Enter: hands off to the chosen view host (stdio inherited) — a one-way handoff; the picker exits.',
             'Outside a TTY: prints the plain view list and exits 0.',
         ],
     },
@@ -38,7 +38,7 @@ export const viewPickLeaf = defineLeaf({
             return;
         }
         if (views.length === 0) {
-            process.stdout.write('No views found. Scaffold one with `crtr view new <name>`.\n');
+            process.stdout.write('No views found. Scaffold one with the view new leaf.\n');
             return;
         }
         const caps = detectColorCaps();
@@ -81,7 +81,7 @@ export const viewPickLeaf = defineLeaf({
             const launch = (id) => {
                 cleanup();
                 try {
-                    execFileSync('crtr', ['view', 'run', id], { stdio: 'inherit' });
+                    execFileSync('crtr', ['surface', 'view', 'run', id], { stdio: 'inherit' });
                 }
                 catch {
                     // The view takes the terminal over; a sync handoff may be interrupted.

package/dist/commands/view-run.js

@@ -1,10 +1,10 @@
-// `crtr view run <name>` — resolve, load, and host a view's TUI target.
+// `crtr surface view run` — resolve, load, and host a view's TUI target.
 //
 // Resolves the view across scopes (project→user→builtin), loads its core.mjs +
 // tui.mjs (+ optional text.mjs), then hands them to the dual-target core host.
 // The host owns the screen and the non-TTY path: when stdin is NOT a TTY it
-// prints the text presenter's dump and exits 0, so `crtr view run <name> | cat`
-// works anywhere. A view that ships no core.mjs is not a view — run fails with a
+// prints the text presenter's dump and exits 0, so a pipe gets a static
+// snapshot. A view that ships no core.mjs is not a view — run fails with a
 // clear error naming the contract, never a fallback. The interactive path is
 // tmux-only (crtr is tmux-only) — outside tmux with a TTY we notify + no-op,
 // never a non-tmux fallback. --port / --target forward verbatim onto
@@ -13,7 +13,7 @@
 // --window / --split open the view as a PERSISTENT MONITOR instead of taking
 // over the current pane: --window in a new background (non-focus-stealing)
 // tmux window, --split in a right-hand split of the current pane. Both shell a
-// plain inner `crtr view run <name>` into the new pane, which hosts the view
+// plain inner surface-view run command into the new pane, which hosts the view
 // there and self-tags the pane with @crtr_view so the Alt+V then ]/[ view-cycle
 // can flip it to the next/prev view in place. Both are tmux-only by nature; in
 // a pipe (non-TTY) placement is meaningless, so they degrade to the static dump.
@@ -27,7 +27,7 @@ import { inTmux, currentTmux, openNodeWindow, splitWindow, piCommand, setPaneOpt
 export const viewRunLeaf = defineLeaf({
     name: 'run',
     description: 'resolve, load, and host a view (in this pane, a new window, or a split)',
-    whenToUse: 'you want to OPEN a view by name — a full-screen raw-ANSI surface. By default it hosts in the current pane (tmux-only interactive; piped it prints a static snapshot). Pass --window to open it as a background monitor window, or --split to open it beside the current pane — both leave you where you are so a view becomes a live monitor you flip between with Alt+V then ]/[. Pass --port/--target to forward connection details. Use `crtr view list` first to see what is available, or `crtr view new` to scaffold one',
+    whenToUse: 'you want to open a view by name — a full-screen raw-ANSI surface. By default it hosts in the current pane (tmux-only interactive; piped it prints a static snapshot). Pass --window to open it as a background monitor window, or --split to open it beside the current pane so it stays available as a live monitor. Pass --port/--target to forward connection details. Use list first to see what is available, or new to scaffold one',
     help: {
         name: 'view run',
         summary: 'host a view in the current pane, a new window (--window), or a split (--split); outside a TTY it prints the view\'s static dump and exits 0',
@@ -35,8 +35,8 @@ export const viewRunLeaf = defineLeaf({
             { kind: 'positional', name: 'name', required: true, constraint: 'View id to run (its directory name). Resolves project→user→builtin.' },
             { kind: 'flag', name: 'window', type: 'bool', required: false, constraint: 'Open the view in a NEW background tmux window (non-focus-stealing) instead of the current pane — a persistent monitor. tmux-only; ignored (static dump) in a pipe. Mutually exclusive with --split.' },
             { kind: 'flag', name: 'split', type: 'bool', required: false, constraint: 'Open the view in a right-hand SPLIT of the current pane instead of taking it over — a side-by-side monitor. tmux-only; ignored (static dump) in a pipe. Mutually exclusive with --window.' },
-            { kind: 'flag', name: 'port', type: 'int', required: false, constraint: 'Forwarded verbatim to the view as options.port (e.g. a CDP debugging port).' },
-            { kind: 'flag', name: 'target', type: 'string', required: false, constraint: 'Forwarded verbatim to the view as options.target (e.g. a browser tab id).' },
+            { kind: 'flag', name: 'port', type: 'int', required: false, constraint: 'Forwarded verbatim to the view as options.port for views that connect to a network service.' },
+            { kind: 'flag', name: 'target', type: 'string', required: false, constraint: 'Forwarded verbatim to the view as options.target for views that need an external target identifier.' },
         ],
         output: [
             { name: 'hosted', type: 'string', required: false, constraint: 'For --window/--split: "window" or "split" — where the monitor opened. Absent for an in-pane host (which holds the terminal until you quit).' },
@@ -76,7 +76,7 @@ export const viewRunLeaf = defineLeaf({
                     error: 'view_invalid',
                     message: `'${name}' is not a valid view: ${dir} has no core.mjs`,
                     received: name,
-                    next: `A view is a directory containing core.mjs (the portable core) plus optional tui.mjs (render + keymap), web.jsx, and text.mjs. Scaffold the shape with \`crtr view new ${name}\`.`,
+                    next: 'A view is a directory containing core.mjs (the portable core) plus optional tui.mjs (render + keymap), web.jsx, and text.mjs. Use the surface view new leaf to scaffold the shape.',
                 });
             }
             const avail = listViews().map((v) => v.id);
@@ -85,8 +85,8 @@ export const viewRunLeaf = defineLeaf({
                 message: `no view: ${name}`,
                 received: name,
                 next: avail.length > 0
-                    ? `Available views: ${avail.join(', ')}. Or scaffold one with \`crtr view new ${name}\`.`
-                    : `No views found. Scaffold one with \`crtr view new ${name}\`.`,
+                    ? `Available views: ${avail.join(', ')}. Or scaffold one with the surface view new leaf.`
+                    : 'No views found. Scaffold one with the surface view new leaf.',
             });
         }
         const options = {};
@@ -116,7 +116,7 @@ export const viewRunLeaf = defineLeaf({
                 throw new InputError({
                     error: 'not_in_tmux',
                     message: '--window/--split are tmux-only — run crtr inside its tmux session',
-                    next: `Open it from inside tmux, or drop the flag to host in the current pane (or pipe for a snapshot: \`crtr view run ${name} | cat\`).`,
+                    next: 'Open it from inside tmux, or drop the placement flag to host in the current pane. For a static snapshot, pipe the command output.',
                 });
             }
             const here = currentTmux();
@@ -129,7 +129,7 @@ export const viewRunLeaf = defineLeaf({
             }
             // The inner command re-enters this leaf with NO placement flag, so it
             // hosts the view in its own (new) pane and self-tags it via @crtr_view.
-            const argv = ['view', 'run', name];
+            const argv = ['surface', 'view', 'run', name];
             if (port !== undefined)
                 argv.push('--port', String(port));
             if (target !== undefined)
@@ -164,8 +164,8 @@ export const viewRunLeaf = defineLeaf({
         if (process.stdin.isTTY && !inTmux()) {
             throw new InputError({
                 error: 'not_in_tmux',
-                message: 'crtr view is tmux-only — run it inside the crtr tmux session',
-                next: `Open it from inside tmux (e.g. the /view popup), or pipe for a static snapshot: \`crtr view run ${name} | cat\`.`,
+                message: 'crtr surface view is tmux-only — run it inside the crtr tmux session',
+                next: 'Open it from inside tmux, or pipe the command output for a static snapshot.',
             });
         }
         // Self-tag this pane with the view id (+ any forwarded --port/--target) so

package/dist/commands/view.js

@@ -1,4 +1,4 @@
-// `crtr view` — the TUI view library.
+// `crtr surface view` — the TUI view library.
 //
 // Views are switchable surfaces with two targets from one portable core.mjs:
 // the tmux TUI (`run`) and a React+Tailwind web page. This branch assembles the
@@ -6,7 +6,7 @@
 // target (interactive in tmux, static dump when piped), `new` scaffolds a fresh
 // view directory, and the hidden `pick` backs the /view popup. Each leaf owns
 // its own help one level down. The web target is no longer served per-view here:
-// it is hosted by the unified `crtr web serve` (the shell's /view/<id> route).
+// it is hosted by the unified surface web server (the shell's /view/<id> route).
 import { defineBranch } from '../core/command.js';
 import { viewListLeaf } from './view-list.js';
 import { viewRunLeaf } from './view-run.js';
@@ -24,7 +24,7 @@ export function registerView() {
         help: {
             name: 'view',
             summary: 'host and author switchable raw-ANSI terminal views',
-            model: '`list` when you do not know which views exist — a flat roster (id/title/description/scope) across project→user→builtin. `run <name>` opens the TUI target full-screen in the current pane (tmux-only interactive; piped it prints the view\'s static dump and exits 0), forwarding --port/--target onto the view; pass --window/--split to open it as a persistent monitor (new window / split) you flip between with Alt+V then ]/[. The web target (React+Tailwind) is served by the unified `crtr web serve` (the shell\'s /view/<id> route), not per-view here. `cycle` switches a monitor pane to the next/prev view in place (what those keys drive). `new <name>` scaffolds a runnable view directory (core.mjs + tui.mjs + web.jsx + text.mjs) you edit. `pick` is a hidden raw-ANSI picker the /view popup shells. Append `-h` at any leaf for its schema.',
+            model: 'The branch divides into listing, hosting, cycling, authoring, and the hidden picker. `list` is the roster; `run` hosts a named view in the current pane or a monitor pane; `cycle` advances a monitor in place; `new` scaffolds a view directory; `pick` backs the popup. The browser target is part of the web surface, not this branch.',
         },
         children: [viewListLeaf, viewRunLeaf, viewCycleLeaf, viewNewLeaf, viewPickLeaf],
     });

package/dist/commands/workspace.js

@@ -2,19 +2,19 @@
 //
 // Turns the current tmux window into an editor view for attached headless nodes:
 // a narrow LEFT rail (the `workspace-sidebar` view — this graph + other live
-// agents in this cwd, with ⚑ inbox flags) beside a CHAT pane (`crtr attach`).
+// agents in this cwd, with ⚑ inbox flags) beside a CHAT pane (surface attach).
 // Selecting a node in the rail swaps it into the chat pane.
 //
 // Layout build (the only two driver acts, both through placement's seam):
 //   1. splitWindow(here, before+size) → the rail pane, left of here, runs
-//      `crtr view run workspace-sidebar`.
+//      the workspace-sidebar view host.
 //   2. `crtr node focus <node> --pane <here>` → swaps the chat node's attach
 //      viewer into here's slot (here's old content relocates to the backstage).
 // The rail finds the chat pane by DISCOVERY (the `@crtr_node` tag attach sets),
 // so it is robust to that swap — no launch-time pane id is threaded into it.
 //
-// Command shape: the path-walker forbids a flat top-level leaf (same constraint
-// as attach), so this is a BRANCH wrapping one leaf: `crtr workspace enter`.
+// Command shape: under `crtr surface workspace`, this is a BRANCH wrapping one
+// leaf: `enter`.
 import { execFile } from 'node:child_process';
 import { defineBranch, defineLeaf } from '../core/command.js';
 import { InputError } from '../core/io.js';
@@ -37,10 +37,10 @@ function defaultChatNode(cwd) {
 const workspaceEnterLeaf = defineLeaf({
     name: 'enter',
     description: 'enter the editor view — a node rail beside a chat pane, in this window',
-    whenToUse: 'you want to work in the agent-centric editor layout: a left rail listing this graph + the other live agents in this working directory (with ⚑ inbox flags) beside a chat pane attached to a node. Selecting a node in the rail swaps it into the chat pane. Opens in the CURRENT tmux window. tmux-only.',
+    whenToUse: 'you want to work in the agent-centric editor layout: a left rail listing this graph plus the other live agents in this working directory (with ⚑ inbox flags) beside a chat pane attached to a node. Selecting a node in the rail swaps it into the chat pane. Opens in the current tmux window. tmux-only.',
     help: {
         name: 'workspace enter',
-        summary: 'split the current window into a left node-rail (the workspace-sidebar view) + a chat pane (crtr attach); ↵ in the rail swaps a node into the chat. tmux-only.',
+        summary: 'split the current window into a left node-rail (the workspace-sidebar view) + a chat pane (surface attach); ↵ in the rail swaps a node into the chat. tmux-only.',
         params: [
             {
                 kind: 'flag',
@@ -74,12 +74,12 @@ const workspaceEnterLeaf = defineLeaf({
         const node = input['node'];
         const width = input['width'] ?? RAIL_WIDTH;
         if (!process.stdout.isTTY) {
-            return { note: 'crtr workspace enter builds a tmux layout — run it in a tmux pane (a TTY), not a pipe.' };
+            return { note: 'surface workspace enter builds a tmux layout — run it in a tmux pane (a TTY), not a pipe.' };
         }
         if (!inTmux()) {
             throw new InputError({
                 error: 'not_in_tmux',
-                message: 'crtr workspace is tmux-only — run it inside the crtr tmux session',
+                message: 'surface workspace is tmux-only — run it inside the crtr tmux session',
                 next: 'Open it from inside tmux.',
             });
         }
@@ -109,7 +109,7 @@ const workspaceEnterLeaf = defineLeaf({
         }
         // 1. The rail — a narrow split to the LEFT of here. It discovers the chat
         //    pane itself (the @crtr_node tag), so no pane id is threaded in.
-        const railCmd = piCommand(['view', 'run', 'workspace-sidebar', '--target', here.pane], 'crtr');
+        const railCmd = piCommand(['surface', 'view', 'run', 'workspace-sidebar', '--target', here.pane], 'crtr');
         const rail = splitWindow(here.pane, {
             cwd: process.cwd(),
             env: {},
@@ -154,7 +154,7 @@ export function registerWorkspace() {
         help: {
             name: 'workspace',
             summary: 'enter the agent-centric editor view (node rail + chat pane) in the current tmux window',
-            model: '`enter` splits the current window into a narrow left rail (the workspace-sidebar view — this graph + other live agents in this cwd, ⚑ inbox flags) and a chat pane (`crtr attach`) attached to a node (--node, or the newest live root here). ↵ in the rail swaps the selected node into the chat pane. tmux-only; piped it prints a notice and exits 0.',
+            model: 'The branch is a two-pane editor layout: a narrow left rail and a chat pane. The rail shows this graph plus the other live agents in the working directory, and selecting a node swaps it into chat. tmux-only; piped input prints a notice and exits 0.',
         },
         children: [workspaceEnterLeaf],
     });

package/dist/core/__tests__/boot.test.js

@@ -0,0 +1,140 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/boot.test.ts
+//
+// BUG LOCKED (Hearth P6 Bug B — a sandbox/VM destroy+recreate, or a host
+// reboot, leaves stale `pi_pid` values in the durable canvas.db; a pid-reuse
+// collision on the fresh boot can fool `isPidAlive` into reading a dead
+// broker as alive, wedging the node forever). reconcileBootLiveness is the
+// fix: detect the boot change and clear every stale pid BEFORE any liveness
+// check trusts it.
+//
+// Exercises the pure decision core (bootChanged) and the impure, single-writer
+// sweep (reconcileBootLiveness) against a real isolated CRTR_HOME + canvas.db —
+// no real reboot, no real uptime: both take an injected BootIdentity (kernel
+// boot_id + wall-clock epoch) so a boot change is simulated by handing a
+// different identity between calls.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, getRow, recordPid } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { bootChanged, reconcileBootLiveness } from '../canvas/boot.js';
+let home;
+/** Build a BootIdentity for injection. `bootId` null models the non-Linux
+ *  fallback (wall-clock window); a string models the exact kernel boot_id. */
+function ident(bootId, bootEpochMs) {
+    return { bootId, bootEpochMs };
+}
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'developer',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-boot-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+// ---------------------------------------------------------------------------
+// bootChanged — pure core
+// ---------------------------------------------------------------------------
+test('bootChanged: no persisted history is never a change (never clears a genuinely live pid)', () => {
+    assert.equal(bootChanged(ident('boot-A', 1_000_000), null), false);
+});
+test('bootChanged: same kernel boot_id is the SAME boot (daemon restart, no reboot)', () => {
+    assert.equal(bootChanged(ident('boot-A', 1_000_000 + 5_000), ident('boot-A', 1_000_000)), false, 'identical boot_id — same boot regardless of epoch');
+});
+test('bootChanged: a DIFFERENT boot_id under 60s wall-delta is still detected (Major-2 regression)', () => {
+    // A genuinely fast reboot/recreate: boot B starts only 42s after boot A
+    // (Hearth\'s measured recreate window), well inside the 60s wall tolerance.
+    // The exact kernel boot_id catches it with NO reliance on the wall-clock
+    // window — the case the old epoch-only compare false-negatived.
+    assert.equal(bootChanged(ident('boot-B', 1_000_000 + 42_000), ident('boot-A', 1_000_000)), true, 'distinct boot_id 42s apart — a real quick recreate, detected');
+});
+test('bootChanged: same boot_id with a huge epoch jump is NOT a boot change (NTP step within a boot)', () => {
+    assert.equal(bootChanged(ident('boot-A', 1_000_000 + 10 * 60_000), ident('boot-A', 1_000_000)), false, 'boot_id trumps the wall clock — an NTP correction mid-boot never false-positives');
+});
+test('bootChanged: wall-clock fallback (no boot_id) — epochs within tolerance are the SAME boot', () => {
+    assert.equal(bootChanged(ident(null, 1_000_000 + 5_000), ident(null, 1_000_000)), false, '5s drift — same boot');
+});
+test('bootChanged: wall-clock fallback (no boot_id) — epochs far apart are a DIFFERENT boot', () => {
+    assert.equal(bootChanged(ident(null, 1_000_000 + 10 * 60_000), ident(null, 1_000_000)), true, '10min apart — different boot');
+});
+// ---------------------------------------------------------------------------
+// reconcileBootLiveness — the impure sweep against a real canvas.db
+// ---------------------------------------------------------------------------
+test('reconcileBootLiveness: first-ever call seeds the marker and clears nothing', () => {
+    const m = node('n1');
+    createNode(m);
+    recordPid('n1', 12345);
+    const result = reconcileBootLiveness(ident('boot-A', 1_000_000));
+    assert.deepEqual(result, { changed: false, cleared: [] });
+    assert.equal(getRow('n1')?.pi_pid, 12345, 'a first-ever run never clears an existing pid');
+});
+test('reconcileBootLiveness: same boot (same boot_id) leaves pids untouched — MUST NOT weaken the normal daemon-restart case', () => {
+    const m = node('n1');
+    createNode(m);
+    recordPid('n1', 12345);
+    reconcileBootLiveness(ident('boot-A', 1_000_000)); // seed
+    const result = reconcileBootLiveness(ident('boot-A', 1_000_000 + 3_000)); // 3s later, same boot
+    assert.deepEqual(result, { changed: false, cleared: [] });
+    assert.equal(getRow('n1')?.pi_pid, 12345, 'a live pid on the same boot is never cleared');
+});
+test('reconcileBootLiveness: a boot change clears every recorded pid, regardless of status', () => {
+    const active = node('active-1', { status: 'active' });
+    const idle = node('idle-1', { status: 'idle' });
+    const dead = node('dead-1', { status: 'dead' }); // the guard reads pi_pid unconditionally
+    const noPid = node('no-pid-1', { status: 'active' });
+    for (const m of [active, idle, dead, noPid])
+        createNode(m);
+    recordPid('active-1', 111);
+    recordPid('idle-1', 222);
+    recordPid('dead-1', 333);
+    // no-pid-1 deliberately left without a recorded pid.
+    reconcileBootLiveness(ident('boot-A', 1_000_000)); // seed boot A
+    const result = reconcileBootLiveness(ident('boot-B', 1_000_000 + 60 * 60_000)); // boot B
+    assert.equal(result.changed, true);
+    assert.deepEqual(result.cleared.sort(), ['active-1', 'dead-1', 'idle-1']);
+    assert.equal(getRow('active-1')?.pi_pid, null);
+    assert.equal(getRow('idle-1')?.pi_pid, null);
+    assert.equal(getRow('dead-1')?.pi_pid, null, 'cleared even though status is dead — the double-launch guard reads pi_pid unconditionally');
+    assert.equal(getRow('no-pid-1')?.pi_pid, null, 'already null — no-op, not an error');
+});
+test('reconcileBootLiveness: a fast recreate (distinct boot_id, 42s wall) still sweeps (Major-2 regression)', () => {
+    const m = node('n1');
+    createNode(m);
+    recordPid('n1', 111);
+    reconcileBootLiveness(ident('boot-A', 1_000_000)); // seed boot A
+    const result = reconcileBootLiveness(ident('boot-B', 1_000_000 + 42_000)); // 42s later — inside the wall window, but new boot_id
+    assert.equal(result.changed, true, 'distinct boot_id detected even 42s apart');
+    assert.deepEqual(result.cleared, ['n1']);
+    assert.equal(getRow('n1')?.pi_pid, null);
+});
+test('reconcileBootLiveness: after reconciling, the SAME boot no longer re-triggers (idempotent)', () => {
+    const m = node('n1');
+    createNode(m);
+    recordPid('n1', 111);
+    reconcileBootLiveness(ident('boot-A', 1_000_000)); // seed boot A
+    reconcileBootLiveness(ident('boot-B', 1_000_000 + 60 * 60_000)); // boot change → clears + persists boot B
+    recordPid('n1', 999); // a fresh broker re-records its pid post-revive
+    const result = reconcileBootLiveness(ident('boot-B', 1_000_000 + 60 * 60_000 + 2_000)); // still boot B, 2s later
+    assert.deepEqual(result, { changed: false, cleared: [] });
+    assert.equal(getRow('n1')?.pi_pid, 999, 'a pid recorded AFTER reconciliation, within the same boot, is never touched');
+});

package/dist/core/__tests__/broker-preflight.test.js

@@ -0,0 +1,85 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/broker-preflight.test.ts
+//
+// Bug-regression: preflight broker launch validation should resolve the default
+// broker package, reject broken custom engines, and fail before a detached broker
+// process is spawned when session args are invalid or missing.
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { preflightBrokerLaunch } from '../runtime/host.js';
+const HERE = dirname(fileURLToPath(import.meta.url));
+const FAKE_ENGINE = join(HERE, 'fixtures', 'fake-engine.ts');
+let home;
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-preflight-'));
+    process.env['CRTR_HOME'] = home;
+});
+after(() => {
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+function assertLaunchWrote(nodeId, inv) {
+    const launchPath = join(home, 'nodes', nodeId, 'broker-launch.json');
+    const parsed = JSON.parse(readFileSync(launchPath, 'utf8'));
+    assert.deepEqual(parsed, inv, 'the launch recipe exists and parses as JSON');
+}
+test('preflightBrokerLaunch uses the installed default broker package when no engine override is set', () => {
+    const nodeId = 'preflight-default-engine';
+    const inv = {
+        argv: ['hello'],
+        env: {},
+    };
+    const prev = process.env['CRTR_BROKER_ENGINE'];
+    delete process.env['CRTR_BROKER_ENGINE'];
+    try {
+        assert.doesNotThrow(() => preflightBrokerLaunch(nodeId, inv, '/tmp/work'));
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env['CRTR_BROKER_ENGINE'];
+        else
+            process.env['CRTR_BROKER_ENGINE'] = prev;
+    }
+    assertLaunchWrote(nodeId, inv);
+});
+test('preflightBrokerLaunch fails fast when the broker engine module cannot be resolved', () => {
+    const nodeId = 'preflight-bad-engine';
+    const inv = {
+        argv: ['hello'],
+        env: { CRTR_BROKER_ENGINE: '@crouton-kit/does-not-exist' },
+    };
+    assert.throws(() => preflightBrokerLaunch(nodeId, inv, '/tmp/work'), /cannot resolve broker engine/i);
+    assertLaunchWrote(nodeId, inv);
+});
+test('preflightBrokerLaunch validates the exact broker engine env passed to the detached broker', () => {
+    const nodeId = 'preflight-empty-engine';
+    const inv = {
+        argv: ['hello'],
+        env: { CRTR_BROKER_ENGINE: '   ' },
+    };
+    assert.throws(() => preflightBrokerLaunch(nodeId, inv, '/tmp/work'), /cannot resolve broker engine/i);
+    assertLaunchWrote(nodeId, inv);
+});
+test('preflightBrokerLaunch fails fast when a bare --session id would be rejected by the broker', () => {
+    const nodeId = 'preflight-bare-session';
+    const inv = {
+        argv: ['--session', 'uuid-123'],
+        env: { CRTR_BROKER_ENGINE: FAKE_ENGINE },
+    };
+    assert.throws(() => preflightBrokerLaunch(nodeId, inv, '/tmp/work'), /bare --session id/i);
+    assertLaunchWrote(nodeId, inv);
+});
+test('preflightBrokerLaunch fails fast when a plainly-encoded session file path is missing', () => {
+    const nodeId = 'preflight-missing-session';
+    const inv = {
+        argv: ['--session', join(home, 'sessions', 'missing.jsonl')],
+        env: { CRTR_BROKER_ENGINE: FAKE_ENGINE },
+    };
+    assert.throws(() => preflightBrokerLaunch(nodeId, inv, '/tmp/work'), /missing session file/i);
+    const launchPath = join(home, 'nodes', nodeId, 'broker-launch.json');
+    const parsed = JSON.parse(readFileSync(launchPath, 'utf8'));
+    assert.deepEqual(parsed, inv, 'the launch recipe exists and parses as JSON');
+});

package/dist/core/__tests__/broker-sdk-wiring.test.js

@@ -12,9 +12,6 @@
 //        model provider is registered into the ModelRegistry and resolves onto
 //        the session. Plain createAgentSession never calls registerProvider, so a
 //        custom-provider node would get NO model.
-//   C4 — a project AGENTS.md is injected into the assembled system prompt (the
-//        services path loads project context; 0.78.1 has no project-trust gate so
-//        context is unconditionally loaded — see buildBrokerSession's C4 note).
 //   C2 — with ZERO viewers attached, the broker UI context resolves confirm() /
 //        select() / input() / editor() to deny/cancel IMMEDIATELY (noOp), instead
 //        of relying on a per-dialog timeout and hanging the agent turn forever.
@@ -23,7 +20,7 @@
 // dialog routing are all local. No tmux, no broker process — direct unit drives.
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -71,20 +68,12 @@ test('C3 — services path registers an extension model provider; the broker ses
         rmSync(cwd, { recursive: true, force: true });
     }
 });
-// ===========================================================================
-// C4 — project context (AGENTS.md) is injected into the system prompt. The
-// services path loads project context files; on the 0.78.1 pin there is no
-// project-trust gate, so they load unconditionally (and buildBrokerSession does
-// NOT re-introduce the CLI's headless trust resolver, which would drop them).
-// ===========================================================================
-test('C4 — a project AGENTS.md is injected into the assembled system prompt', async () => {
-    const cwd = mkdtempSync(join(tmpdir(), 'crtr-c4-'));
+test('C3b — broker splits model thinking suffix before SDK registry lookup', async () => {
+    const cwd = mkdtempSync(join(tmpdir(), 'crtr-c3b-'));
     try {
-        const marker = 'C4_AGENTS_MARKER_' + Math.random().toString(36).slice(2);
-        writeFileSync(join(cwd, 'AGENTS.md'), `# Project rules\n\n${marker}\n`);
-        const { session } = await buildBrokerSession(realEngine, cfg(cwd));
+        const { session } = await buildBrokerSession(realEngine, cfg(cwd, { extensionPaths: [C3_EXT], model: 'c3prov/c3model:high' }));
         try {
-            assert.ok(session.systemPrompt.includes(marker), 'C4: project AGENTS.md content is present in the assembled system prompt');
+            assert.equal(session.model?.id, 'c3model', 'C3b: suffixed model specs resolve by model id instead of falling back to SDK default');
         }
         finally {
             session.dispose();
@@ -94,6 +83,11 @@ test('C4 — a project AGENTS.md is injected into the assembled system prompt',
         rmSync(cwd, { recursive: true, force: true });
     }
 });
+// (C4 — project AGENTS.md/CLAUDE.md injection — was removed: crouter now sets
+// `noContextFiles: true` in buildBrokerSession and re-renders project context
+// into the first-message <crtr-context> bearings instead of pi's system prompt
+// (broker.ts). That behavior is covered by context-intro.test.ts's "project
+// instructions ride the bearings, not the system prompt" test.)
 // ===========================================================================
 // C2 — zero-viewer dialogs resolve to deny/cancel IMMEDIATELY (noOp), never
 // hanging the turn and never waiting on a per-dialog timeout. Drives the REAL