@crouton-kit/crouter 0.3.68 → 0.3.78

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

@@ -26,9 +26,11 @@ export const PROMPT_LINES = 3;
 export const REPLY_LINES = 3;
 export const PREVIEW_BODY = PROMPT_LINES + REPLY_LINES;
 export const PREVIEW_HEIGHT = PREVIEW_BODY + 2;
-//   header = title + tab bar + status line + column header + separator (+ search input)
-export function headerHeight(search) {
-    return 5 + (search ? 1 : 0);
+//   header = title + tab bar + status line + column header + separator (+ input line)
+// `inputLine` is true whenever a text-input mode is open (search / rename / message)
+// — each adds one prompt row above the column header.
+export function headerHeight(inputLine) {
+    return 5 + (inputLine ? 1 : 0);
 }
 // ── Row table layout ──────────────────────────────────────────────────────────
 // A row is three zones: a fixed-width STATUS rail (glyph + word) on the left, the
@@ -57,6 +59,7 @@ const FG_CYAN = '36';
 const FG_GRAY = '90'; // bright-black
 const FG_BRIGHT_YELLOW = '93';
 const FG_BRIGHT_CYAN = '96'; // query-match highlight (ties to the cyan search accent)
+const FG_MAGENTA = '35'; // pin star (distinct from the yellow ⚑ asks flag)
 // STATUS_GLYPH + STATUS_COLOR are imported from ../status-glyph.js (the shared
 // canvas-graph map). STATUS_COLOR there is NUMERIC SGR (e.g. 32) — wrap with
 // `sgr()` where a string ANSI code is needed (Span fg / template literals accept
@@ -232,7 +235,7 @@ function assembleRow(left, right, width, color, lineBase, fill) {
 }
 /** One table row: `<status rail>  <indent><collapse> <name> <flags>` ........ `<meta>`.
  *  `showCwd` adds the project column (All-dirs view); `now` drives the age. */
-function rowLine(row, tree, width, isCursor, query, caps, showCwd, now) {
+function rowLine(row, tree, width, isCursor, query, caps, showCwd, now, isPinned) {
     const node = tree.nodes.get(row.id);
     if (node === undefined)
         return '';
@@ -254,12 +257,15 @@ function rowLine(row, tree, width, isCursor, query, caps, showCwd, now) {
     // label live in the rail). Dim yellow so it reads as secondary detail.
     if (r.hanging != null)
         flags.push({ text: ` · ${faultSummary(r.hanging, now)}`, style: { fg: FG_YELLOW, dim: true } });
+    // Pin marker travels just before the name so a starred node is scannable in any
+    // tab/sort. Magenta keeps it distinct from the yellow ⚑ asks flag.
+    const pinMark = isPinned ? [{ text: '★ ', style: { fg: FG_MAGENTA, bold: true } }] : [];
     const status = statusRail(r);
     const right = metaCluster(r, now, showCwd);
     const treeLead = `${indent}${collapse} `;
-    // Clip the NAME (only) so gutter + status + tree + name + flags + meta all fit;
-    // the cluster is dropped first (assembleRow) when even a 4-col name won't fit it.
-    const fixed = spansWidth([gutter]) + spansWidth(status) + [...treeLead].length + spansWidth(flags);
+    // Clip the NAME (only) so gutter + status + tree + pin + name + flags + meta all
+    // fit; the cluster is dropped first (assembleRow) when even a 4-col name won't fit.
+    const fixed = spansWidth([gutter]) + spansWidth(status) + [...treeLead].length + spansWidth(pinMark) + spansWidth(flags);
     const rightW = spansWidth(right);
     const nameMax = Math.max(4, width - fixed - rightW - 1);
     const nameStyle = { dim: !isCursor && terminal, bold: isCursor }; // dim terminal names; bold the cursor row
@@ -267,6 +273,7 @@ function rowLine(row, tree, width, isCursor, query, caps, showCwd, now) {
         gutter,
         ...status,
         { text: treeLead, style: { dim: true } },
+        ...pinMark,
         ...nameSpans(clip(r.name, nameMax), query, nameStyle),
         ...flags,
     ];
@@ -403,16 +410,63 @@ function previewPanel(r, width, caps, now, query) {
     }
     return out;
 }
+/** The keybinding help overlay — a full-screen cheatsheet that replaces the body
+ *  while `?` is held open. Grouped by intent so the whole key surface is legible in
+ *  one glance (the footer only ever advertises the common few). */
+const HELP_ROWS = [
+    ['Move', '↑/↓  j/k', 'up / down'],
+    ['', 'g / G', 'top / bottom'],
+    ['', '.', 'jump to this node (recenter)'],
+    ['Tree', '→/←  h/l', 'expand / collapse'],
+    ['', 'space', 'toggle fold'],
+    ['Tabs', 'Tab / 1-5', 'All · Live · Dormant · Attention · Pinned'],
+    ['Find', '/', 'fuzzy search (name · kind · id · prompts)'],
+    ['Pin', 'f', 'star / unstar — floats to top, Pinned tab'],
+    ['Open', '⏎', 'resume the node'],
+    ['Act', 'm', 'message the node (no resume)'],
+    ['', 'R', 'rename the node'],
+    ['', 'x', 'close-out node + subtree'],
+    ['', 'K', 'revive now (a hanging node)'],
+    ['View', 's', 'cycle sort (attention/tree/relevance/recency)'],
+    ['', 'c', 'toggle cwd scope'],
+    ['', 'r', 'toggle residents-only'],
+    ['', 'p', 'toggle preview panel'],
+    ['Quit', 'q / Esc', ''],
+];
+function renderHelp(size, caps) {
+    const cols = Math.max(20, size.cols);
+    const rows = Math.max(8, size.rows);
+    const width = cols - 1;
+    const lines = [];
+    lines.push(`${BOLD}Canvas navigator — keys${RESET}`);
+    lines.push('');
+    const dim = (s) => `${DIM}${s}${RESET}`;
+    for (const [group, keys, desc] of HELP_ROWS) {
+        const g = group.padEnd(6);
+        const k = keys.padEnd(12);
+        const line = `  ${dim(g)}${BOLD}${k}${RESET}${desc === '' ? '' : `  ${dim(desc)}`}`;
+        lines.push(clip(line, width));
+    }
+    lines.push('');
+    lines.push(dim('  ? or any key to close'));
+    while (lines.length < rows - 1)
+        lines.push('');
+    const body = lines.map((l) => `${l}${ESC}K`).join('\r\n');
+    return `${ESC}H${body}${ESC}J`;
+}
 /**
  * Render the whole frame. Returns a single string that, written as-is, repaints
  * the screen in place. `caps` gates all hue (defaults to a no-color frame so
  * existing callers / non-TTY paths stay color-free).
  */
 export function renderFrame(state, size, caps = { color: false, color256: false }) {
+    if (state.help === true)
+        return renderHelp(size, caps);
     const cols = Math.max(20, size.cols);
     const rows = Math.max(8, size.rows);
     const width = cols - 1; // leave the last column for \x1b[K
     const now = Date.now();
+    const inputMode = state.search || state.rename === true || state.message === true;
     const lines = [];
     // line 1 — title + right-aligned status summary (each glyph in its status hue).
     const title = `${BOLD}Canvas${RESET} — ${state.totalNodes} nodes`;
@@ -428,10 +482,12 @@ export function renderFrame(state, size, caps = { color: false, color256: false
     lines.push(tabBar(state.tab, caps.color));
     // line 3 — status line (scope · sort · filter).
     lines.push(statusLine(state));
-    // line 4 — search input, only while actively typing a search.
-    if (state.search) {
-        const slash = caps.color ? `${ESC}${FG_CYAN}m/${RESET}` : '/';
-        lines.push(`${slash} ${state.query}▎`);
+    // line 4 — the text-input prompt, only while a search / rename / message is open.
+    if (inputMode) {
+        const prefix = state.rename === true ? 'rename ▸' : state.message === true ? 'msg ▸' : '/';
+        const buf = state.rename === true ? (state.renameBuf ?? '') : state.message === true ? (state.messageBuf ?? '') : state.query;
+        const p = caps.color ? `${ESC}${FG_CYAN}m${prefix}${RESET}` : prefix;
+        lines.push(`${p} ${buf}▎`);
     }
     // column header (table labels) + separator.
     const showCwd = state.cwdScope === null; // project column only matters across dirs
@@ -451,7 +507,8 @@ export function renderFrame(state, size, caps = { color: false, color256: false
     }
     else {
         for (let i = start; i < end; i++) {
-            lines.push(rowLine(state.visible[i], state.tree, width, i === state.cursor, state.query, caps, showCwd, now));
+            const vr = state.visible[i];
+            lines.push(rowLine(vr, state.tree, width, i === state.cursor, state.query, caps, showCwd, now, state.pinned.has(vr.id)));
         }
         for (let i = end - start; i < viewport; i++)
             lines.push('');
@@ -477,11 +534,11 @@ export function renderFrame(state, size, caps = { color: false, color256: false
         const selRow = state.visible[state.cursor];
         const cursorRow = selRow !== undefined ? state.tree.nodes.get(selRow.id)?.row : undefined;
         const hangingHint = cursorRow?.hanging != null ? 'K revive now  ' : '';
-        const footer = state.search
+        const footer = inputMode
             ? '⏎ commit  Esc cancel  ⌫ delete'
             : state.readOnly === true
-                ? '↑↓ move  →/← tree  Tab tabs  / search  s sort  c cwd  r residents  p preview  q quit  — read-only remote canvas'
-                : `${hangingHint}↑↓ move  →/← tree  ⏎ resume  x close  Tab tabs  / search  s sort  c cwd  r residents  p preview  q quit`;
+                ? '↑↓ move  →/← tree  / search  f pin  Tab tabs  ? more  q quit  — read-only remote canvas'
+                : `${hangingHint}↑↓ move  ⏎ resume  / search  f pin  m msg  x close  R rename  ? more  q quit`;
         lines.push(`${DIM}${clip(footer, width)}${RESET}`);
     }
     // Assemble: home, each line cleared to EOL, then clear below.

package/dist/core/canvas/nav-model.js

@@ -1,16 +1,10 @@
-// nav-model.ts — the pure model/render layer of the canvas graph-nav chrome.
+// nav-model.ts — the pure model/render layer for attach's canvas chrome.
 //
-// Extracted from src/pi-extensions/canvas-nav.ts so a SINGLE source feeds both
-// the legacy pi extension (canvas-nav) and the headless `crtr surface attach` viewer.
 // Everything here is pi-API-free: it reads the canvas (sqlite + meta.json + node
-// telemetry) and produces ANSI-styled strings + a flattened graph model. The
-// extension-host wiring (widgets, key taps, the ask-poll timer, run/focus
-// shelling) stays in canvas-nav.ts and drives these functions.
-//
-// Mutable interaction state that the legacy extension held at module scope —
-// the per-node ask counts and the manual fold overrides — is threaded through
-// parameters here (see `asks` and `FoldState`) so this layer owns no singletons
-// and each consumer keeps its own state.
+// telemetry) and produces ANSI-styled strings plus a flattened graph model.
+// Per-view interaction state, including ask counts and manual fold overrides, is
+// threaded through parameters (see `asks` and `FoldState`) so this layer owns no
+// singletons and each consumer keeps its own state.
 import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';

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

@@ -23,6 +23,11 @@ export declare function canvasDbPath(): string;
  *  local-disk hosts. Parent dir is created on use so both paths just work. */
 export declare function viewSocketPath(nodeId: string): string;
 export declare function nodesRoot(): string;
+/** Global, cwd-agnostic broker cache of per-session picker metadata, keyed by
+ *  absolute `.jsonl` path. Shared across every node's broker (paths are absolute)
+ *  and survives broker restarts so the first `/resume` open after a restart is
+ *  also fast. Machine-local performance state — safe to delete; rebuilt on demand. */
+export declare function sessionListCachePath(): string;
 export declare function nodeDir(nodeId: string): string;
 export declare function contextDir(nodeId: string): string;
 /** Replace the literal env-var tokens `$CRTR_CONTEXT_DIR` / `$CRTR_NODE_ID` in

package/dist/core/canvas/paths.js

@@ -63,6 +63,13 @@ export function viewSocketPath(nodeId) {
 export function nodesRoot() {
     return join(crtrHome(), 'nodes');
 }
+/** Global, cwd-agnostic broker cache of per-session picker metadata, keyed by
+ *  absolute `.jsonl` path. Shared across every node's broker (paths are absolute)
+ *  and survives broker restarts so the first `/resume` open after a restart is
+ *  also fast. Machine-local performance state — safe to delete; rebuilt on demand. */
+export function sessionListCachePath() {
+    return join(crtrHome(), 'session-list-cache.json');
+}
 export function nodeDir(nodeId) {
     return join(nodesRoot(), nodeId);
 }

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

@@ -74,16 +74,20 @@ export declare function identitiesMatch(a: string, b: string): boolean;
  *      `identitiesMatch` says so, else `'dead'` (positively reused). */
 export type RecordedPidLiveness = 'alive' | 'dead' | 'indeterminate';
 export declare function recordedPidLiveness(pid: number | null | undefined, expectedIdentity: string | null | undefined): RecordedPidLiveness;
-/** Boolean teardown-direction adapter over `recordedPidLiveness`, kept so
- *  every pre-existing signalling caller stays behavior-identical: `dead` is
- *  the ONLY thing that reads false. `indeterminate` (can't confirm either
- *  way) reads true alongside `alive` — never signal a maybe-ours pid on mere
- *  uncertainty, matching this module's universal discipline (a POSITIVE
- *  mismatch is the only thing that changes behavior, never an absence of
- *  evidence). Callers that need to distinguish "confirmed alive" from
- *  "can't confirm" (e.g. a double-launch guard, where treating uncertainty as
- *  alive risks silently skipping a needed relaunch) must call
- *  `recordedPidLiveness` directly instead of this adapter. */
+/** Boolean confirmed-dead-direction adapter over `recordedPidLiveness`:
+ *  `dead` is the ONLY thing that reads false. `indeterminate` (can't confirm
+ *  either way) reads true alongside `alive` — never act on a maybe-ours pid
+ *  on mere uncertainty, matching this module's universal discipline (a
+ *  POSITIVE verdict is the only thing that changes behavior, never an
+ *  absence of evidence). This is the correct read for BOTH signalling
+ *  callers (never signal on uncertainty) and the double-launch guard in
+ *  `reviveNode` (never RELAUNCH on uncertainty — the identity probe is a
+ *  fork+exec that fails precisely under the OOM pressure where an extra
+ *  broker is most destructive, while a truly dead pid always reads `dead`
+ *  via the fork-free signal-0 path; see the guard's comment for the live
+ *  incident this closed). Callers that need "confirmed alive" three-valued
+ *  precision (e.g. the daemon's grace-clock bookkeeping) call
+ *  `recordedPidLiveness` directly. */
 export declare function isRecordedPidAlive(pid: number | null | undefined, expectedIdentity: string | null | undefined): boolean;
 /** SIGTERM a process GROUP by pid (the negative-pid convention) — best-effort,
  *  swallowing ESRCH (already gone). Shared by triggers.ts (cancel-time reap of

package/dist/core/canvas/pid.js

@@ -132,16 +132,20 @@ export function recordedPidLiveness(pid, expectedIdentity) {
         logPidLivenessDecision(pid, alive, expectedIdentity, 'value', matches ? 'identity matches expected → alive' : 'identity differs from expected → REUSED → dead', matches ? 'alive' : 'dead', actual);
     return matches ? 'alive' : 'dead';
 }
-/** Boolean teardown-direction adapter over `recordedPidLiveness`, kept so
- *  every pre-existing signalling caller stays behavior-identical: `dead` is
- *  the ONLY thing that reads false. `indeterminate` (can't confirm either
- *  way) reads true alongside `alive` — never signal a maybe-ours pid on mere
- *  uncertainty, matching this module's universal discipline (a POSITIVE
- *  mismatch is the only thing that changes behavior, never an absence of
- *  evidence). Callers that need to distinguish "confirmed alive" from
- *  "can't confirm" (e.g. a double-launch guard, where treating uncertainty as
- *  alive risks silently skipping a needed relaunch) must call
- *  `recordedPidLiveness` directly instead of this adapter. */
+/** Boolean confirmed-dead-direction adapter over `recordedPidLiveness`:
+ *  `dead` is the ONLY thing that reads false. `indeterminate` (can't confirm
+ *  either way) reads true alongside `alive` — never act on a maybe-ours pid
+ *  on mere uncertainty, matching this module's universal discipline (a
+ *  POSITIVE verdict is the only thing that changes behavior, never an
+ *  absence of evidence). This is the correct read for BOTH signalling
+ *  callers (never signal on uncertainty) and the double-launch guard in
+ *  `reviveNode` (never RELAUNCH on uncertainty — the identity probe is a
+ *  fork+exec that fails precisely under the OOM pressure where an extra
+ *  broker is most destructive, while a truly dead pid always reads `dead`
+ *  via the fork-free signal-0 path; see the guard's comment for the live
+ *  incident this closed). Callers that need "confirmed alive" three-valued
+ *  precision (e.g. the daemon's grace-clock bookkeeping) call
+ *  `recordedPidLiveness` directly. */
 export function isRecordedPidAlive(pid, expectedIdentity) {
     return recordedPidLiveness(pid, expectedIdentity) !== 'dead';
 }

package/dist/core/config.d.ts

@@ -1,11 +1,32 @@
-import type { Scope, ScopeConfig, ScopeState, KindConfig, ModelLaddersConfig } from '../types.js';
+import type { Scope, ScopeConfig, ScopeState, CanvasNavConfig, KindConfig, ModelLaddersConfig } from '../types.js';
 export declare function configPath(scope: Scope): string | null;
 export declare function statePath(scope: Scope): string | null;
-export declare function readConfig(scope: Scope): ScopeConfig;
+export type ConsumerCompatibleScopeConfig = ScopeConfig & {
+    readonly canvasNav: CanvasNavConfig;
+};
+export declare function readConfig(scope: Scope): ConsumerCompatibleScopeConfig;
 export declare function readState(scope: Scope): ScopeState;
+type RawConfig = Record<string, unknown>;
+export declare function updateRawConfigAtomically(scope: Scope, mutate: (latest: RawConfig) => RawConfig): RawConfig;
 export declare function writeConfig(scope: Scope, config: ScopeConfig): void;
+/** Persist a RAW PARTIAL config to a scope's config.json exactly as given.
+ *  Unlike `writeConfig`, this makes no promise that every field is present --
+ *  callers pass the sparse partial that should live on disk, so an untouched
+ *  key stays absent (and `readConfig`/`mergeConfig` re-derive it live from
+ *  whichever build is running). This is the single central primitive every
+ *  mutation path funnels through so no writer ever freezes a fully
+ *  materialized `modelLadders` (concrete model ids that go stale across
+ *  builds -- the live-Hearth freeze bug) onto disk. */
+export declare function writeRawConfig(scope: Scope, config: Partial<ScopeConfig>): void;
 export declare function writeState(scope: Scope, state: ScopeState): void;
 export declare function ensureScopeInitialized(scope: Scope, root: string): void;
+/** Raw (un-defaulted) partial config for one scope, or null if the scope has
+ *  no root or no config.json. Used by `readMergedLaunchConfig` to layer
+ *  scopes onto each other WITHOUT each scope's own default-fill masking a
+ *  lower-precedence scope's real customization (see that function's comment
+ *  for why `readConfig(scope)`, which already defaults-fills, is unusable
+ *  for cross-scope layering). */
+export declare function readRawScopeConfig(scope: Scope): Partial<ScopeConfig> | null;
 export interface MergedLaunchConfig {
     kinds: Record<string, KindConfig>;
     modelLadders: ModelLaddersConfig;
@@ -65,5 +86,35 @@ export declare function subKindsAvailableTo(kind: string): {
     kind: string;
     whenToUse: string;
 }[];
+/** Apply `mutate` to a scope's MERGED config (so callers can read + write any
+ *  field), then persist only a RAW PARTIAL: every top-level key the mutation
+ *  left untouched keeps its exact on-disk raw value (absent stays absent, a
+ *  sparse override stays sparse), and only keys the mutation actually changed
+ *  are written. `modelLadders` gets sub-field-granular sparse handling via
+ *  `sparseModelLaddersToPersist`. Result: a fresh bootstrap or any unrelated
+ *  `sys config set` no longer freezes a full concrete `modelLadders` to disk,
+ *  and a direct ladder-rung set still persists only the touched rung -- all
+ *  through one lock-protected atomic update path. */
 export declare function updateConfig(scope: Scope, mutate: (cfg: ScopeConfig) => void): ScopeConfig;
+/** Persist a model as the DEFAULT for a kind — the `/model`-picker "defaults
+ *  going forward" write. Writes a SPARSE `kinds.<kind>` patch (just the one
+ *  model field, merged by `normalizeKindPatch`/`mergeKinds` over whatever the
+ *  lower scopes define — never a frozen full kind entry) into the PROFILE's
+ *  config.json when the node runs under a profile, else the user scope's.
+ *  Mode-aware: an orchestrator's pick lands on `orchestratorModel` (base
+ *  workers of the same kind keep their own default), a base node's on `model`.
+ *  Callers pass a model string in any form `normalizeModel` accepts; portable
+ *  ladder tokens (`ultra`, `anthropic/strong`) are preferred by callers since
+ *  they never go stale across builds. */
+export declare function persistDefaultKindModel(opts: {
+    kind: string;
+    model: string;
+    orchestrator?: boolean;
+    profileId?: string | null;
+}): {
+    scope: 'profile' | 'user';
+    path: string;
+    field: 'model' | 'orchestratorModel';
+};
 export declare function updateState(scope: Scope, mutate: (s: ScopeState) => void): ScopeState;
+export {};