@crouton-kit/crouter 0.3.70 → 0.3.78

package/dist/clients/attach/titled-editor.js

@@ -6,16 +6,16 @@
 //      on each state update), mirroring pi's `getThinkingBorderColor`.
 // Both are pure render-layer chrome; nothing here touches the socket or session.
 import { CustomEditor } from '@earendil-works/pi-coding-agent';
-import { truncateToWidth, visibleWidth, } from '@earendil-works/pi-tui';
-/** The thinking color scale is a deliberate cool→warm ramp between a blue and
- *  its orange complement, evenly spaced across the five active levels so each
- *  step stays readable without jumping through unrelated hues. `off` falls
- *  back to the caller's default border color. The endpoints are deliberately
- *  deep (not bright) hues: the same colors double as the title-chip BACKGROUND
- *  under bold white text, so every step must clear ~4.5:1 white-on-color
- *  contrast — a lighter blue/orange washes the label out. */
+import { CURSOR_MARKER, truncateToWidth, visibleWidth, } from '@earendil-works/pi-tui';
+/** The standard thinking levels form a deliberate cool→warm ramp between blue
+ *  and its orange complement. `max` is a distinct, intense cyan endpoint so it
+ *  never falls back to the neutral default border. `off` alone falls back to
+ *  the caller's default border color. The colors double as title-chip
+ *  BACKGROUNDS under bold white text, so each must remain dark enough for the
+ *  label to read clearly. */
 const THINKING_START = [46, 92, 190]; // deep blue
 const THINKING_END = [166, 98, 24]; // deep amber
+const THINKING_MAX = [0, 145, 170]; // intense cyan
 function interpolateRgb(start, end, t) {
     return [
         Math.round(start[0] + (end[0] - start[0]) * t),
@@ -30,7 +30,55 @@ const THINKING_RGB = {
     medium: interpolateRgb(THINKING_START, THINKING_END, 2 / 4),
     high: interpolateRgb(THINKING_START, THINKING_END, 3 / 4),
     xhigh: interpolateRgb(THINKING_START, THINKING_END, 4 / 4),
+    max: THINKING_MAX,
 };
+/** Named colours `/color` accepts, as RGB — mirrors the tmux colour-name table
+ *  (so the chip and the pane border read as the same hue). */
+const NAMED_RGB = {
+    black: [0, 0, 0],
+    red: [205, 49, 49],
+    green: [13, 188, 121],
+    yellow: [229, 229, 16],
+    blue: [36, 114, 200],
+    magenta: [188, 63, 188],
+    cyan: [17, 168, 205],
+    white: [229, 229, 229],
+    orange: [228, 152, 68],
+    grey: [128, 128, 128],
+    gray: [128, 128, 128],
+    brightred: [241, 76, 76],
+    brightgreen: [35, 209, 139],
+    brightyellow: [245, 245, 67],
+    brightblue: [59, 142, 234],
+    brightmagenta: [214, 112, 214],
+    brightcyan: [41, 184, 219],
+};
+/** Build a title-chip styler for a `/color` token (a tmux colour name, `#rrggbb`,
+ *  or `colourN`): the colour as the chip BACKGROUND with contrast-picked bold
+ *  text, matching the thinking-chip treatment. `undefined` for an unrenderable
+ *  token (e.g. `default`) — the caller keeps its fallback style. */
+export function colorChipStyle(token) {
+    const t = token.trim().toLowerCase();
+    const c256 = /^colour(\d{1,3})$/.exec(t);
+    if (c256 !== null)
+        return (s) => `\x1b[48;5;${c256[1]}m\x1b[97m\x1b[1m ${s} \x1b[0m`;
+    let rgb;
+    const hex = /^#([0-9a-f]{6})$/.exec(t);
+    if (hex !== null) {
+        const h = hex[1];
+        rgb = [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)];
+    }
+    else {
+        rgb = NAMED_RGB[t];
+    }
+    if (rgb === undefined)
+        return undefined;
+    const [r, g, b] = rgb;
+    // Pick black-on-light / white-on-dark so the name stays readable on any hue.
+    const luma = 0.299 * r + 0.587 * g + 0.114 * b;
+    const fg = luma > 160 ? '\x1b[30m' : '\x1b[97m';
+    return (s) => `\x1b[48;2;${r};${g};${b}m${fg}\x1b[1m ${s} \x1b[0m`;
+}
 /** The default (thinking `off`) title chip: reverse video + a space of padding
  *  each side, so the name reads as a label sitting on the border rule. Used as
  *  the fallback when no thinking color applies. */
@@ -71,6 +119,39 @@ export function composeTopBorder(width, title, info, titleStyle, borderColor) {
     const fill = Math.max(0, width - chipW - visibleWidth(infoChip));
     return chip + borderColor('─'.repeat(fill)) + infoChip;
 }
+/** The stock pi-tui editor paints its fake cursor as a solid reverse-video
+ *  block (`\x1b[7m…\x1b[0m`) unconditionally — in a wall of attach panes every
+ *  pane shows an identical solid white cursor, and nothing tells you which one
+ *  keys actually go to. When the hosting pane/terminal is UNFOCUSED we rewrite
+ *  that cell into a MUTED cursor, mirroring how real terminals de-emphasize
+ *  the hardware cursor on blur. A pixel-true full-cell outline isn't possible
+ *  in text cells, and hollow-box glyphs (▯/⍘/□) render undersized, so the
+ *  muted form is a full-size block in a dim gray background — same footprint
+ *  as the focused cursor, clearly not the bright active one (ruling: tried the
+ *  glyphs, Silas preferred the dim block). The rewrite anchors on pi-tui's
+ *  zero-width CURSOR_MARKER (emitted right before the fake cursor while the
+ *  editor component has TUI focus) so it can never touch reverse video
+ *  elsewhere in the line. Returns undefined when the line carries no cursor.
+ *  Exported pure for tests. */
+const SOLID_CURSOR_PREFIX = '\x1b[7m';
+const SOLID_CURSOR_RESET = '\x1b[0m';
+/** Dim gray bg, default fg — the char under the cursor stays readable. */
+const MUTED_CURSOR_ON = '\x1b[48;5;240m';
+export function outlineCursorLine(line) {
+    const m = line.indexOf(CURSOR_MARKER);
+    if (m === -1)
+        return undefined;
+    const start = m + CURSOR_MARKER.length;
+    if (!line.startsWith(SOLID_CURSOR_PREFIX, start))
+        return undefined;
+    const gStart = start + SOLID_CURSOR_PREFIX.length;
+    const end = line.indexOf(SOLID_CURSOR_RESET, gStart);
+    if (end === -1)
+        return undefined;
+    const grapheme = line.slice(gStart, end);
+    const replacement = `${MUTED_CURSOR_ON}${grapheme}\x1b[0m`;
+    return line.slice(0, start) + replacement + line.slice(end + SOLID_CURSOR_RESET.length);
+}
 export class TitledEditor extends CustomEditor {
     /** crtr's OWN keybindings manager — the same one CustomEditor matches `app.*`
      *  against. We keep a reference so `handleInput` can resolve the newline chord
@@ -114,8 +195,22 @@ export class TitledEditor extends CustomEditor {
     titleStyle = defaultTitleStyle;
     /** Mode badge colorizer, matched to the current mode type. */
     modeStyle = defaultTitleStyle;
+    /** Whether the hosting tmux pane / terminal window has FOCUS (terminal focus
+     *  reporting, DECSET 1004 — attach-cmd flips this on `\x1b[I` / `\x1b[O`).
+     *  Distinct from TUI component focus: the editor keeps component focus while
+     *  its pane is blurred. False → the fake cursor renders as an outline. */
+    paneFocused = true;
     render(width) {
         const lines = super.render(width);
+        if (!this.paneFocused) {
+            for (let i = 0; i < lines.length; i++) {
+                const hollowed = outlineCursorLine(lines[i]);
+                if (hollowed !== undefined) {
+                    lines[i] = hollowed;
+                    break;
+                }
+            }
+        }
         if ((this.title || this.info) && lines.length > 0) {
             // Replace the stock top border; dashes in the current (thinking-aware)
             // border color.

package/dist/commands/canvas-browse.js

@@ -1,6 +1,6 @@
 // `crtr canvas browse` — the interactive full-screen canvas navigator.
 //
-// A raw-mode TUI over the WHOLE canvas: tabs (All/Live/Dormant/Flagged), an
+// A raw-mode TUI over the WHOLE canvas: tabs (All/Live/Dormant/Attention/Pinned), an
 // auto-collapsed tree, and `/` fuzzy search. Enter resumes the chosen node via
 // `crtr node focus` (the ONLY sanctioned open — reviveNode, never `pi --session`).
 // Owns the screen, so it returns void and writes nothing to stdout itself.
@@ -14,7 +14,7 @@ import { readState } from '../core/config.js';
 export const browseLeaf = defineLeaf({
     name: 'browse',
     description: 'open the interactive canvas navigator (tabs/tree/search)',
-    whenToUse: 'you want to VIEW and NAVIGATE the whole canvas interactively — a full-screen TUI with tabs (All/Live/Dormant/Flagged), an expandable tree (children auto-collapsed; → to expand), and `/` fuzzy search that auto-expands ancestors of matches; Enter resumes the chosen node. Use this to find your way around a large canvas. Use `canvas dashboard` instead for a one-shot ASCII tree you can pipe, and `node inspect list` for a flat machine-readable roster',
+    whenToUse: 'you want to VIEW and NAVIGATE the whole canvas interactively — a full-screen TUI with tabs (All/Live/Dormant/Attention/Pinned), an expandable tree (children auto-collapsed; → to expand), `/` fuzzy search, `f` to pin, `m` to message and `R` to rename a node in place, and `?` for the full keymap; Enter resumes the chosen node. Use this to find your way around a large canvas. Use `canvas dashboard` instead for a one-shot ASCII tree you can pipe, and `node inspect list` for a flat machine-readable roster',
     help: {
         name: 'canvas browse',
         summary: 'interactive full-screen canvas navigator — tabs, an auto-collapsed tree, and `/` fuzzy search; Enter resumes the chosen node via `crtr node focus`. Outside a TTY it prints the static forest and exits',

package/dist/commands/memory/lint.js

@@ -11,6 +11,8 @@ import { pathExists, readText, walkFiles } from '../../core/fs-utils.js';
 import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
 import { listInstalledPlugins, listInstalledPluginsInRoot } from '../../core/resolver.js';
 import { pluginMemoryDir, projectScopeRoots, scopeMemoryDir } from '../../core/scope.js';
+import { loadProfileManifest, profileMemoryDir } from '../../core/profiles/manifest.js';
+import { getDefaultProfileId } from '../../core/profiles/default-binding.js';
 import { isDocKind, RUNGS } from '../../core/substrate/index.js';
 /** The parser normalizes the `always` alias to `content`, so it lints valid. */
 const VALID_RUNGS = [...RUNGS, 'always'];
@@ -101,14 +103,14 @@ function lintFile(file, substrateStore, findings) {
 export const lintLeaf = defineLeaf({
     name: 'lint',
     description: 'validate frontmatter across the whole bounded document corpus',
-    whenToUse: 'you authored or migrated documents and want the authoring-time gate: strict-parse every doc in the bounded corpus (the substrate memory stores) and fail loudly on any invalid YAML or substrate schema violation. Run it before shipping doc changes; CI-friendly (non-zero exit on any finding).',
+    whenToUse: 'you authored or migrated documents and want the authoring-time gate: strict-parse every doc in the bounded corpus (the substrate memory stores) and fail loudly on any invalid YAML or substrate schema violation; also flags any dir the selected profile manages that lacks an AGENTS.md operating guide. Run it before shipping doc changes; CI-friendly (non-zero exit on any finding).',
     help: {
         name: 'memory lint',
         summary: 'strict-parse frontmatter across the bounded corpus; non-zero exit on any finding',
         params: [],
         output: [
             { name: 'checked', type: 'number', required: true, constraint: 'Files linted across all corpora.' },
-            { name: 'corpora', type: 'object', required: true, constraint: 'Per-corpus file counts: {memory_stores}.' },
+            { name: 'corpora', type: 'object', required: true, constraint: 'Per-corpus counts: {memory_stores (files), profile_projects (managed dirs checked for AGENTS.md)}.' },
             { name: 'findings', type: 'object[]', required: true, constraint: 'One row per failure: {path, error}. Empty when green.' },
         ],
         outputKind: 'object',
@@ -121,10 +123,14 @@ export const lintLeaf = defineLeaf({
         // A source's corpus is its NATIVE memory dir plus each enabled plugin's memory dir —
         // plugin docs are substrate docs and lint through the same schema gate.
         //    MEMORY.md index files are not substrate docs — YAML-parse only.
+        //    Hidden dirs are skipped to mirror doc enumeration (a dot-segment
+        //    path never yields a doc name, so e.g. the maintainer store shipped
+        //    at builtin-memory/.crouter can never register) — lint must not
+        //    flag files the substrate can never load.
         const lintDir = (dir) => {
             if (!dir || !pathExists(dir))
                 return;
-            for (const file of walkFiles(dir, (n) => n.endsWith('.md'))) {
+            for (const file of walkFiles(dir, (n) => n.endsWith('.md'), (d) => d.startsWith('.'))) {
                 if (!relative(dir, file).split(sep).join('/'))
                     continue;
                 memoryCount += 1;
@@ -145,6 +151,34 @@ export const lintLeaf = defineLeaf({
                     lintDir(pluginMemoryDir(plugin));
             }
         }
+        // Profile coverage: the selected profile's manifest names the dirs the
+        // operator manages. Lint the profile's own store, and require every
+        // managed project dir to carry an always-loaded operating guide
+        // (.crouter/memory/AGENTS.md) — a managed dir without one boots every
+        // agent there blind, so its absence is an authoring finding like any
+        // schema violation. (The managed dirs' stores themselves already lint
+        // above: projectScopeRoots folds the profile's project pointers in.)
+        let profileProjects = 0;
+        const profileIdOrName = process.env['CRTR_PROFILE_ID'] || getDefaultProfileId(process.cwd());
+        if (profileIdOrName) {
+            try {
+                const { profileId, manifest } = loadProfileManifest(profileIdOrName);
+                lintDir(profileMemoryDir(profileId));
+                for (const dir of manifest.projects) {
+                    profileProjects += 1;
+                    if (!pathExists(join(dir, '.crouter', 'memory', 'AGENTS.md'))) {
+                        findings.push({
+                            path: dir,
+                            error: `profile "${manifest.name}" manages this dir but it has no .crouter/memory/AGENTS.md — author its always-loaded operating guide (name the doc AGENTS, target the dir with --dir; run \`crtr memory write -h\` first)`,
+                        });
+                    }
+                }
+            }
+            catch {
+                // Unresolvable profile (deleted/corrupt manifest): profile coverage
+                // just doesn't apply — the file corpus above already linted fully.
+            }
+        }
         const checked = memoryCount;
         if (findings.length > 0) {
             // Human/agent path renders only the message — surface every offender as
@@ -154,12 +188,12 @@ export const lintLeaf = defineLeaf({
             throw general(`memory lint: ${findings.length} finding(s) across ${checked} files`, {
                 checked,
                 findings: findings.map((f) => ({ path: f.path, error: f.error })),
-                next: 'Fix each doc (quote YAML values containing `: `; use a valid kind/rung/gate), then re-run `crtr memory lint`.',
+                next: 'Fix each doc (quote YAML values containing `: `; use a valid kind/rung/gate); for a profile-managed dir missing AGENTS.md, author one — run `crtr memory write -h` — then re-run `crtr memory lint`.',
             });
         }
         return {
             checked,
-            corpora: { memory_stores: memoryCount },
+            corpora: { memory_stores: memoryCount, profile_projects: profileProjects },
             findings: [],
             follow_up: 'Corpus green — zero invalid frontmatter docs.',
         };

package/dist/commands/memory/write.js

@@ -15,6 +15,7 @@ export const writeLeaf = defineLeaf({
             'Store reusable current truth, not session notes. Useful memories are non-obvious procedures, gotchas, durable preferences, cross-repo conventions, and amendments to plans/specs that future agents must honor. Put plan/spec amendments under path names like `projects/<topic>/...`; add `projects/<topic>/INDEX.md` with `name` visibility so the topic is discoverable without loading the whole body. Do not store chat summaries, implementation history, or facts already recorded in the repo.\n\n' +
             'Set both visibility rungs explicitly on create. There is no kind default. `none`, `name`, `preview`, and `content` move from least to most loaded: `none` keeps the doc out of auto-load and on-read surfaces, `name` is the bare doc tag only, `preview` is the name + envelope + routing line (`when-and-why-to-read`), and `content` inlines the whole body when the body is short enough to justify it. Each axis is independent; usually one carries a real rung and the other is `none`. When a doc is short enough to state in a single sentence — a one-line preference, or a knowledge fact that fits in a sentence — skip `preview` and use `name` or `content` directly: the routing line would run longer than the doc itself, so a `preview` rung just adds words. Sentence-length `content` docs are not just acceptable, they are correct. Never pad a memory to be more verbose than the rule or fact it carries.\n\n' +
             'Choose the scope. `project` is for facts any agent in one repo needs. `user` is for person-wide facts and preferences that should follow the user everywhere. `profile` is for the profile’s bundle of dirs: cross-repo conventions, how the pieces relate, or the user’s stance toward that body of work. `node` is the narrowest — the this-node store (`nodes/<CRTR_NODE_ID>/context/memory/`), scratch memory only this running node sees; it rides straight into this node’s knowledge block and dies with the node. When unsure, choose the narrowest scope that will still reach the next agent who needs it.\n\n' +
+            'AGENTS.md is the one special doc: a store’s always-loaded operating guide, and every dir a profile manages should carry one (`crtr memory lint` flags the gaps). Name the doc AGENTS, target the exact dir with --dir, and set system-prompt-visibility to `content` so every agent working there boots with it. It is a front door, not a manual — constraints and gotchas, the key commands, a few sentences of architecture orientation, and only the conventions that differ from defaults. Every line is paid by every session in that dir forever: prefer a pointer (“when X, run Y -h / read Z, because W”) over inlined how-to, and cut any line that would not change an agent’s behavior.\n\n' +
             'Choose the hook — boot vs file-read. Behavior and how-to procedure surface at boot. Knowledge about code belongs next to the code: put the file in that directory’s .crouter/memory/ (`--dir <project-dir>` targets it exactly, from anywhere) and it fires positionally when files there are read, costing nothing at boot. A knowledge doc about a person or process has no code directory to anchor to, so on-read triggering is meaningless — route it through boot instead and set the boot rung to `preview` when you want the routing line to surface.\n\n' +
             'Write the routing line (--when-and-why-to-read) first, before storing anything: "When <circumstance>, this <kind> should be read because <payoff>." The test is whether a stranger mid-task can decide from that one line alone whether to spend the read. If you cannot name the concrete situation that triggers it, you do not yet understand the memory — ask the user one sharp question instead of improvising. Never paraphrase the advice in the routing line; keep it about when to read and why the read is worth it.\n\n' +
             'Gate and read-when share the same predicate language: a field map is AND-ed across fields; dotted fields resolve nested values; field matchers may be scalar, array, or object. Scalar matchers do exact equality, with arrays matching any element. Array matchers do membership or intersection. Object matchers accept `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, and `lte`. Combinators are `all`, `any`, and `not`; sibling field matchers next to them are AND-ed in. An empty condition is inert. An unknown op never matches.\n\n' +

package/dist/commands/node.js

@@ -911,6 +911,10 @@ const nodeConfig = defineLeaf({
                 lifecycle: newLifecycle,
                 hasManager: meta.parent !== null,
                 model: meta.model_override ?? undefined,
+                // The TARGET node's cwd + profile — profile-scope kind defaults must
+                // resolve for the node being reconfigured, not the calling process.
+                cwd: meta.cwd,
+                profileId: meta.profile_id,
             });
             meta = updateNode(nodeId, {
                 ...(kindSpec !== undefined ? { kind: newKind } : {}),
@@ -1655,6 +1659,8 @@ function setLifecycle(id, value, opts) {
         lifecycle: value,
         hasManager: target.parent !== null,
         model: target.model_override ?? undefined,
+        cwd: target.cwd,
+        profileId: target.profile_id,
     });
     const meta = updateNode(id, { lifecycle: value, launch });
     // --detach: stop foregrounding the agent by closing its viewer pane (the
@@ -1723,6 +1729,7 @@ const nodeYield = defineLeaf({
     help: {
         name: 'node yield',
         summary: 'request a context refresh — you will be respawned fresh against your roadmap on your next stop (a base node auto-promotes to orchestrator first); optionally change your kind or model as you refresh',
+        guide: 'A yield discards everything that lives only in this window, so externalize first: checkpoint context/roadmap.md, and if you are holding a question for the human you have not actually posed, post it via `crtr human ask` before yielding — an in-flight ask survives the refresh and its answer wakes your fresh revive — then note the pending ask in your yield message so the fresh window knows what the answer settles.',
         params: [
             { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Respecialize as you refresh — change your kind to this (developer, review, spec, design, plan, explore, general); a base node also auto-promotes into an orchestrator of this kind. Defaults to your current kind.' },
             { kind: 'flag', name: 'model', type: 'enum', choices: ['ultra', 'strong'], required: false, constraint: 'Change the model your fresh revive runs on, by capability tier: `ultra` (frontier — reserve for high-taste judgment or enormous work: speccing, planning something large, e2e-testing something hard to test) or `strong` (opus — regular dev work). Omit to keep your current model. A node steering work is never weaker than opus, so these are the only two choices; the change is durable across future revives.' },
@@ -1976,13 +1983,13 @@ export function registerNode() {
         rootEntry: {
             concept: 'a unit of the agent runtime — an agent on the canvas with its own context dir and pi vehicle. Spawning nodes is how work gets done here, not an optimization you reach for late',
             desc: 'spawn, inspect, and navigate nodes on the canvas',
-            useWhen: 'delegating work, or walking the subscription graph. CRITICAL, and your default reflex — spawning a child is the first move on almost any task, not a fallback. Your own context window is the scarce resource: before you read files into it to understand, implement, debug, or change code you do not already know, hand that to a fresh node and get back just the conclusion, matching the node kind to the work. Keep inline only a fact you already know. Fan out independent units as CONCURRENT children — a wake with idle workers is wasted; serialize only true dependencies, and never let two live children edit the same files. Once you delegate a unit, do not also run it yourself: you auto-subscribe on spawn, so its finish wakes you. Use the help surface for the exact node contract before invoking it.'
+            useWhen: 'delegating a genuinely independent subtask, or walking the subscription graph. Base nodes work hands-on; orchestrators fan out. Give each child a bounded outcome distinct from your whole assignment so delegation moves work toward completion instead of recursively passing it down. Once delegated, do not duplicate the child’s work; its finish wakes you. Use the help surface for the exact node contract before invoking it.'
         },
         help: {
             name: 'node',
             summary: 'spawn and navigate canvas nodes',
             model: 'Every agent is a node in one directed graph (the canvas); `subscribes_to` is the spine — spawn a child and you auto-subscribe (active) to it, so its finish wakes you.\n\n' +
-                'WHEN TO DELEGATE: hand any self-contained unit of work to a child instead of doing it inline — it keeps your own context window (your scarce resource) free for steering. Spawn independent units in PARALLEL; a wake with idle workers is wasted. Serialize only true dependencies, and never let two live children edit the same files.\n\n' +
+                'WHEN TO DELEGATE: base nodes work hands-on and spawn only genuinely independent subtasks; orchestrators decompose and fan out. A child owns a bounded outcome distinct from the caller’s whole assignment. Spawn independent units in PARALLEL, serialize true dependencies, and never let two live children edit the same files.\n\n' +
                 'HOW: the new leaf returns a node id immediately and runs the worker as a detached headless broker; no viewer opens unless a surface asks for one. Match the kind to the work and read the leaf schema before invoking. You are woken when a child finishes — the wake message ALREADY IS the coalesced digest, so dereference the report paths in that digest that matter instead of acting on a one-line label. Integrate, then either delegate the next units or finish.\n\n' +
                 'FINISH: a worker ends its own work with a final push, which writes the canonical result, marks done, and closes the window; stopping without it is not finishing. For a job too big for one context window, promote to an orchestrator; when context fills, yield to refresh against that roadmap.',
         },

package/dist/commands/surface-tmux-spread.js

@@ -2,9 +2,7 @@
 //
 // A genuine viewer-placement decision (tile every live viewer in a subtree into
 // one window), so it lives under `surface` alongside view/attach/workspace/web.
-// Also bound to the `/graph` view's `e` key (src/pi-extensions/canvas-nav.ts),
-// which shells this leaf directly for the cursor node. It "expands" the graph
-// you are watching: the caller's
+// The command expands the graph being watched: the caller's
 // own viewer pane is broken out into a BRAND-NEW window, then a surface-attach
 // viewer pane is tiled beside it for every broker-alive node in the local
 // subtree (ancestry root → self → descendants), so the user lands on a single

package/dist/commands/sys/__tests__/config-keybindings.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/sys/__tests__/config-keybindings.test.js

@@ -0,0 +1,55 @@
+import { after, before, beforeEach, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { configBranch } from '../config.js';
+import { ensureScopeInitialized } from '../../../core/config.js';
+import { resetScopeCache } from '../../../core/scope.js';
+function leaf(name) {
+    const found = (configBranch.children ?? []).find((child) => child.name === name);
+    if (found === undefined || found.kind !== 'leaf')
+        throw new Error(`no leaf '${name}' under sys config`);
+    return found;
+}
+let home;
+let realHome;
+before(() => { realHome = process.env['HOME']; });
+beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-config-keybindings-'));
+    process.env['HOME'] = home;
+});
+after(() => {
+    if (realHome === undefined)
+        delete process.env['HOME'];
+    else
+        process.env['HOME'] = realHome;
+});
+test.afterEach(() => rmSync(home, { recursive: true, force: true }));
+test('a new project scope initializes through the config lock', () => {
+    const project = mkdtempSync(join(tmpdir(), 'crtr-config-project-'));
+    const previous = process.cwd();
+    try {
+        process.chdir(project);
+        resetScopeCache();
+        const root = join(project, '.crouter');
+        ensureScopeInitialized('project', root);
+        assert.equal(JSON.parse(readFileSync(join(root, 'config.json'), 'utf8')).keybindings, undefined);
+    }
+    finally {
+        process.chdir(previous);
+        resetScopeCache();
+        rmSync(project, { recursive: true, force: true });
+    }
+});
+test('sys config exposes whole user keybindings read-only and routes edits to setup', async () => {
+    mkdirSync(join(home, '.crouter'), { recursive: true });
+    writeFileSync(join(home, '.crouter', 'config.json'), JSON.stringify({
+        keybindings: { 'crtr.graph.down': ['down'] },
+    }));
+    const result = await leaf('get').run({ key: 'keybindings', scope: 'user' });
+    assert.deepEqual(result['value'], { 'crtr.graph.down': ['down'] });
+    await assert.rejects(() => leaf('get').run({ key: 'keybindings.crtr.graph.down', scope: 'user' }), /whole user-scope object/);
+    await assert.rejects(() => leaf('set').run({ key: 'keybindings', value: '{}' }), /crtr sys setup/);
+    assert.doesNotMatch(JSON.stringify(configBranch), /canvasNav/);
+});

package/dist/commands/sys/__tests__/config-model-ladders.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/sys/__tests__/config-model-ladders.test.js

@@ -0,0 +1,121 @@
+// config-model-ladders.test.ts — regression coverage for the live Hearth
+// incident where a home's config.json had `openai-codex/gpt-5.6-*` baked into
+// `modelLadders` while the guest's own installed model registry only had
+// `gpt-5.5`. Root cause: both `ensureScopeInitialized` (fresh scope) and
+// `sys config set modelLadders...` (a targeted edit) persisted the FULLY
+// materialized ladder (all 4 strengths x 2 providers) rather than only the
+// genuine override, freezing whatever concrete model ids happened to be
+// compiled into the crouter build that ran at that moment. A later
+// crouter/pi upgrade (or rollback) that changes the registry can then never
+// reach the frozen rungs again.
+import { test, before, after, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ensureScopeInitialized, readConfig, updateConfig } from '../../../core/config.js';
+import { configBranch } from '../config.js';
+function leaf(name) {
+    const found = (configBranch.children ?? []).find((c) => c.name === name);
+    if (found === undefined || found.kind !== 'leaf')
+        throw new Error(`no leaf '${name}' under sys config`);
+    return found;
+}
+let home;
+let realHome;
+before(() => {
+    realHome = process.env['HOME'];
+});
+beforeEach(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-config-ladders-'));
+    process.env['HOME'] = home;
+});
+// Every test allocates its own temp HOME in beforeEach, so each must be removed
+// in afterEach -- a single `after` would leak all but the last dir.
+afterEach(() => {
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    if (realHome !== undefined)
+        process.env['HOME'] = realHome;
+    else
+        delete process.env['HOME'];
+});
+test('ensureScopeInitialized does NOT bake concrete modelLadders model ids into a fresh config.json', () => {
+    const root = join(home, '.crouter');
+    ensureScopeInitialized('user', root);
+    const cfgPath = join(root, 'config.json');
+    assert.equal(existsSync(cfgPath), true);
+    const raw = JSON.parse(readFileSync(cfgPath, 'utf8'));
+    // The file must exist (so `sys config path` has something to point at) but
+    // must NOT freeze a modelLadders snapshot -- that key should be absent so
+    // `readConfig` always re-derives it live from whichever build is running.
+    assert.equal(raw.modelLadders, undefined);
+    // readConfig must still default-fill a full, usable ladder despite the
+    // omission -- a config-less scope is never worse off.
+    const cfg = readConfig('user');
+    assert.equal(typeof cfg.modelLadders.anthropic.strong, 'string');
+    assert.equal(typeof cfg.modelLadders.openai.strong, 'string');
+});
+test('sys config set modelLadders.<provider>.<strength> persists ONLY the touched rung, not the whole materialized ladder', async () => {
+    const root = join(home, '.crouter');
+    ensureScopeInitialized('user', root);
+    await leaf('set').run({ key: 'modelLadders.openai.strong', value: 'openai-codex/gpt-5.5:high' });
+    const cfgPath = join(root, 'config.json');
+    const raw = JSON.parse(readFileSync(cfgPath, 'utf8'));
+    assert.equal(raw.modelLadders.openai.strong, 'openai-codex/gpt-5.5:high');
+    // The other three openai rungs, and the entire anthropic ladder, must stay
+    // UNSET on disk -- baking them in would freeze this scope to today's
+    // compiled defaults for rungs the user never touched, the exact staleness
+    // bug that produced the live `gpt-5.6` vs. installed-`gpt-5.5` mismatch.
+    assert.equal(raw.modelLadders.openai.ultra, undefined);
+    assert.equal(raw.modelLadders.openai.medium, undefined);
+    assert.equal(raw.modelLadders.openai.light, undefined);
+    assert.equal(raw.modelLadders.anthropic, undefined);
+    // readConfig still resolves a full ladder: the one override layered over
+    // live compiled defaults for everything else.
+    const cfg = readConfig('user');
+    assert.equal(cfg.modelLadders.openai.strong, 'openai-codex/gpt-5.5:high');
+    assert.equal(typeof cfg.modelLadders.openai.ultra, 'string');
+    assert.equal(typeof cfg.modelLadders.anthropic.strong, 'string');
+});
+test('an unrelated updateConfig mutation (as fresh bootstrap does) does NOT freeze modelLadders to disk', () => {
+    const root = join(home, '.crouter');
+    ensureScopeInitialized('user', root);
+    // Mimic `ensureOfficialMarketplace`'s bootstrap write: updateConfig mutating an
+    // unrelated field on a fresh scope. This must not materialize a full ladder.
+    updateConfig('user', (c) => {
+        c.marketplaces['crouter-official-marketplace'] = {
+            url: 'https://example.invalid/x.git',
+            ref: 'main',
+            installed_at: '2026-01-01T00:00:00.000Z',
+        };
+    });
+    const cfgPath = join(root, 'config.json');
+    const raw = JSON.parse(readFileSync(cfgPath, 'utf8'));
+    assert.equal(raw.modelLadders, undefined);
+    assert.ok(raw.marketplaces['crouter-official-marketplace']);
+});
+test('a non-ladder sys config set does NOT freeze modelLadders to disk', async () => {
+    const root = join(home, '.crouter');
+    ensureScopeInitialized('user', root);
+    await leaf('set').run({ key: 'max_panes_per_window', value: '5' });
+    const cfgPath = join(root, 'config.json');
+    const raw = JSON.parse(readFileSync(cfgPath, 'utf8'));
+    // The touched key persists; modelLadders stays absent so a later build's
+    // registry change still reaches every rung.
+    assert.equal(raw.max_panes_per_window, 5);
+    assert.equal(raw.modelLadders, undefined);
+});
+test('a second sys config set for a different rung does not clobber an earlier override', async () => {
+    const root = join(home, '.crouter');
+    ensureScopeInitialized('user', root);
+    await leaf('set').run({ key: 'modelLadders.openai.strong', value: 'openai-codex/gpt-5.5:high' });
+    await leaf('set').run({ key: 'modelLadders.anthropic.light', value: 'anthropic/claude-haiku-4-5:high' });
+    const cfgPath = join(root, 'config.json');
+    const raw = JSON.parse(readFileSync(cfgPath, 'utf8'));
+    assert.equal(raw.modelLadders.openai.strong, 'openai-codex/gpt-5.5:high');
+    assert.equal(raw.modelLadders.anthropic.light, 'anthropic/claude-haiku-4-5:high');
+    assert.equal(raw.modelLadders.openai.ultra, undefined);
+    assert.equal(raw.modelLadders.anthropic.strong, undefined);
+});

package/dist/commands/sys/config.js

@@ -1,5 +1,5 @@
 import { defineBranch, defineLeaf } from '../../core/command.js';
-import { readConfig, writeConfig, configPath as coreConfigPath } from '../../core/config.js';
+import { readConfig, updateConfig, configPath as coreConfigPath } from '../../core/config.js';
 import { usage, notFound } from '../../core/errors.js';
 import { scopeRoot, listScopes } from '../../core/scope.js';
 import { resolveScope } from './shared.js';
@@ -11,7 +11,6 @@ const TOP_LEVEL_KEYS = new Set([
     'marketplaces',
     'plugins',
     'max_panes_per_window',
-    'canvasNav',
     'modelLadders',
 ]);
 const MODEL_PROVIDERS = new Set(['anthropic', 'openai']);
@@ -44,6 +43,9 @@ function parseConfigValue(raw) {
 function setNestedValue(cfg, key, rawValue, value) {
     const parts = key.split('.');
     const topKey = parts[0];
+    if (topKey === 'keybindings') {
+        throw usage('keybindings are edited only through `crtr sys setup`');
+    }
     if (!TOP_LEVEL_KEYS.has(topKey)) {
         throw usage(`unknown config key: ${topKey} (expected: ${[...TOP_LEVEL_KEYS].join('|')})`);
     }
@@ -69,16 +71,6 @@ function setNestedValue(cfg, key, rawValue, value) {
         cfg.max_panes_per_window = Math.floor(value);
         return;
     }
-    if (topKey === 'canvasNav') {
-        // Only the scalar prefixKey is settable here; the prefixBinds/graphBinds
-        // record tables are edited directly in config.json (run `crtr sys config
-        // path` to locate it).
-        if (key === 'canvasNav.prefixKey') {
-            cfg.canvasNav.prefixKey = rawValue;
-            return;
-        }
-        throw usage(`canvasNav.${parts.slice(1).join('.') || '*'} is a record table — edit config.json directly (run \`crtr sys config path\`). Only canvasNav.prefixKey is settable via this command.`);
-    }
     if (topKey === 'modelLadders') {
         if (parts.length === 2 && parts[1] === 'defaultProvider') {
             if (!isModelProvider(rawValue)) {
@@ -121,12 +113,12 @@ function setNestedValue(cfg, key, rawValue, value) {
 const configGet = defineLeaf({
     name: 'get',
     description: 'read a config value by key',
-    whenToUse: 'you want to read a single config value by its dotted key — the current auto_update policy, max_panes_per_window, the canvasNav prefix key, or model ladders — optionally from a specific scope. Use sys config set instead to change a value, sys config path to locate the file for hand-editing.',
+    whenToUse: 'you want to inspect one config value — including the whole user keybindings object — optionally from a specific scope. Use sys setup to edit keybindings and sys config set for supported scalar settings.',
     help: {
         name: 'sys config get',
         summary: 'read a config value by dotted key',
         params: [
-            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: 'Dotted key path. Top-level keys: auto_update, marketplaces, plugins, max_panes_per_window, canvasNav, modelLadders (read whole; edit canvasNav.prefixBinds/graphBinds in config.json directly).' },
+            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: 'Dotted key path. Top-level keys: auto_update, marketplaces, plugins, max_panes_per_window, modelLadders, or the whole keybindings object. Keybindings are edited only through sys setup.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Scope to read from. Default: user.' },
         ],
         output: [
@@ -140,6 +132,9 @@ const configGet = defineLeaf({
     run: async (input) => {
         const key = input['key'];
         const scope = resolveScope(input['scope']);
+        if (key.startsWith('keybindings.') || (key === 'keybindings' && scope !== 'user')) {
+            throw notFound('keybindings are available only as the whole user-scope object');
+        }
         const cfg = readConfig(scope);
         const value = getNestedValue(cfg, key);
         if (value === undefined) {
@@ -151,12 +146,12 @@ const configGet = defineLeaf({
 const configSet = defineLeaf({
     name: 'set',
     description: 'write a config value by key',
-    whenToUse: 'you want to change a crtr setting — flip auto_update.crtr or auto_update.content to notify, apply, or off, raise max_panes_per_window, rebind canvasNav.prefixKey, or set model ladders — written to the user or project scope. Use sys config get instead to read a value; the canvasNav record tables are not settable here, so edit config.json directly (sys config path) for those.',
+    whenToUse: 'you want to change a supported scalar crtr setting in user or project scope. Use sys setup instead for keybindings, and sys config get to inspect values.',
     help: {
         name: 'sys config set',
         summary: 'write a config value by dotted key',
         params: [
-            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: 'Dotted key path. Supported: auto_update.crtr, auto_update.content, auto_update.interval_hours, max_panes_per_window, canvasNav.prefixKey, modelLadders.defaultProvider, modelLadders.<anthropic|openai>.<ultra|strong|medium|light>. The canvasNav.prefixBinds/graphBinds record tables are not settable here — edit config.json directly (`crtr sys config path`).' },
+            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: 'Dotted key path. Supported: auto_update.crtr, auto_update.content, auto_update.interval_hours, max_panes_per_window, modelLadders.defaultProvider, modelLadders.<anthropic|openai>.<ultra|strong|medium|light>. Keybindings are edited only through sys setup.' },
             { kind: 'flag', name: 'value', type: 'string', required: true, constraint: 'value VALUE — string, required. Stored as-is if quoted; coerced to number or boolean when unambiguous.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Scope to write to. Default: user.' },
         ],
@@ -174,9 +169,11 @@ const configSet = defineLeaf({
         const scope = resolveScope(input['scope']);
         // Flags are stringly-typed; coerce to number or boolean when unambiguous
         const parsed = parseConfigValue(rawValue);
-        const cfg = readConfig(scope);
-        setNestedValue(cfg, key, rawValue, parsed);
-        writeConfig(scope, cfg);
+        // Mutate + persist through the central raw-partial path. `updateConfig`
+        // writes only the keys this set actually touched -- a non-ladder set never
+        // freezes a materialized `modelLadders`, and a direct
+        // `modelLadders.<provider>.<strength>` set persists only the touched rung.
+        const cfg = updateConfig(scope, (c) => setNestedValue(c, key, rawValue, parsed));
         // Read back the written value for echo
         const written = getNestedValue(cfg, key);
         return { key, value: written, scope };
@@ -185,7 +182,7 @@ const configSet = defineLeaf({
 const configPath = defineLeaf({
     name: 'path',
     description: 'print path(s) to config.json',
-    whenToUse: 'you need the absolute path to config.json — typically to hand-edit settings sys config set cannot reach, like the canvasNav.prefixBinds and graphBinds record tables.',
+    whenToUse: 'you need the absolute path to a user or project config.json for inspection or backup.',
     help: {
         name: 'sys config path',
         summary: 'print absolute path(s) to config.json',
@@ -225,7 +222,7 @@ const configPath = defineLeaf({
 export const configBranch = defineBranch({
     name: 'config',
     description: 'read and write configuration',
-    whenToUse: 'inspecting or changing crtr settings — read a value with sys config get, change one with sys config set (auto_update policy, max_panes_per_window, canvasNav.prefixKey, model ladders), or locate config.json with sys config path to hand-edit the record tables set cannot reach.',
+    whenToUse: 'inspecting crtr settings, changing supported scalar values, or locating config.json. Keybinding changes belong in sys setup.',
     help: {
         name: 'sys config',
         summary: 'read and write crtr configuration, including model ladders',