@crouton-kit/crouter 0.3.70 → 0.3.79

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/pkg/plugin-inspect.js

@@ -3,6 +3,8 @@ import { notFound } from '../../core/errors.js';
 import { paginate } from '../../core/pagination.js';
 import { listInstalledPlugins, findPluginByName, } from '../../core/resolver.js';
 import { listAllMemoryDocs } from '../../core/memory-resolver.js';
+import { validatePluginCommands, validateEffectiveCommandPlugins } from '../../core/command-plugins/discovery.js';
+import { SUBTREE_NAMES } from '../../build-root.js';
 import { resolveScopeArg, projectScopeRoot } from '../../core/scope.js';
 export const pluginList = defineLeaf({
     name: 'list',
@@ -89,9 +91,10 @@ export const pluginShow = defineLeaf({
             { name: 'enabled', type: 'boolean', required: true, constraint: 'Whether the plugin is active.' },
             { name: 'manifest', type: 'object', required: true, constraint: 'Full plugin.json contents.' },
             { name: 'docs', type: 'object[]', required: true, constraint: 'Each: {name, path}. Memory docs provided by the plugin (its `<pluginName>/` memory subtree).' },
+            { name: 'commands', type: 'object', required: false, constraint: 'Present only when the plugin declares a command manifest (manifest.commands). {manifestPath: string, executable: string | null (null when path/exec-bit validation failed), mounts: string[] (accepted top-level command names), issues: object[] ({code, path?, message, received, expected, next})}. Validated statically — the plugin binary is never executed.' },
         ],
         outputKind: 'object',
-        effects: ['None. Read-only.'],
+        effects: ['None. Read-only. Command manifests are validated statically; the plugin executable is never run.'],
     },
     run: async (input) => {
         const name = input['name'];
@@ -114,6 +117,23 @@ export const pluginShow = defineLeaf({
         }
         const prefix = `${found.name}/`;
         const docs = listAllMemoryDocs().filter((d) => d.name.startsWith(prefix));
+        let commands;
+        if (typeof found.manifest.commands === 'string' && found.manifest.commands.length > 0) {
+            const reserved = new Set(SUBTREE_NAMES);
+            // Validate against the whole effective set so cross-plugin top-level
+            // name collisions show up in this plugin's issues (a collided command is
+            // NOT mounted). A copy outside the effective set (disabled, or shadowed
+            // by a higher-precedence copy) cannot collide, so the per-plugin
+            // validator is exact for it.
+            const v = validateEffectiveCommandPlugins(reserved).find((x) => x.plugin.root === found.root) ??
+                validatePluginCommands(found, reserved);
+            commands = {
+                manifestPath: v.manifestPath,
+                executable: v.executable ?? null,
+                mounts: v.contributions.map((c) => c.node.name),
+                issues: v.issues,
+            };
+        }
         return {
             name: found.name,
             scope: found.scope,
@@ -124,6 +144,7 @@ export const pluginShow = defineLeaf({
                 name: d.name,
                 path: d.path,
             })),
+            ...(commands !== undefined ? { commands } : {}),
         };
     },
 });

package/dist/commands/pkg/plugin-manage.js

@@ -8,7 +8,25 @@ import { updateConfig, updateState, ensureScopeInitialized } from '../../core/co
 import { pathExists, ensureDir, removePath, nowIso, linkOrCopy, isSymlink } from '../../core/fs-utils.js';
 import { clone, pull, deriveNameFromUrl, currentSha, isGitRepo } from '../../core/git.js';
 import { readMarketplaceManifest, readPluginManifest } from '../../core/manifest.js';
+import { validatePluginCommands, validateEffectiveCommandPlugins } from '../../core/command-plugins/discovery.js';
+import { SUBTREE_NAMES } from '../../build-root.js';
 import { isGitUrl, setPluginEnabled, resolveInstallScope } from './shared.js';
+/** Validate a just-installed/updated plugin's command manifest, if it declares
+ *  one. Returns undefined for plugins without a `commands` pointer. Never
+ *  executes the plugin binary — validation is fully static. */
+function commandReport(name, scope) {
+    const plugin = findPluginByName(name, scope);
+    if (plugin === null || typeof plugin.manifest.commands !== 'string' || plugin.manifest.commands.length === 0) {
+        return undefined;
+    }
+    const reserved = new Set(SUBTREE_NAMES);
+    // Report from the effective set so a cross-plugin top-level collision is
+    // visible at install time (a collided command is NOT mounted). A copy
+    // outside the effective set (disabled, or shadowed) cannot collide.
+    const v = validateEffectiveCommandPlugins(reserved).find((x) => x.plugin.root === plugin.root) ??
+        validatePluginCommands(plugin, reserved);
+    return { mounts: v.contributions.map((c) => c.node.name), issues: v.issues };
+}
 function classifyInstallRef(raw) {
     if (raw.startsWith('./') || raw.startsWith('../') || raw.startsWith('/')) {
         return { kind: 'local', value: raw };
@@ -203,10 +221,12 @@ function updateOnePlugin(plugin, marketplaceCache, opts) {
     }
     const manifest = readPluginManifest(plugin.root);
     updatePluginVersion(plugin.scope, plugin.name, marketplaceVersion ?? manifest?.version);
+    const commands = commandReport(plugin.name, plugin.scope);
     return {
         name: plugin.name,
         updated: contentUpdate.updated,
         sha: contentUpdate.sha,
+        ...(commands !== undefined ? { commands } : {}),
     };
 }
 export const pluginInstall = defineLeaf({
@@ -225,9 +245,13 @@ export const pluginInstall = defineLeaf({
             { name: 'name', type: 'string', required: true, constraint: 'Plugin name as installed.' },
             { name: 'scope', type: 'string', required: true, constraint: 'Scope the plugin was installed into.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the installed plugin directory.' },
+            { name: 'commands', type: 'object', required: false, constraint: 'Present only when the plugin declares a command manifest. {mounts: string[] (accepted top-level command names now live for the next invocation), issues: object[] (typed validation issues that rejected a contribution — {code, path?, message, received, expected, next})}. Validated statically; the plugin binary is never executed.' },
         ],
         outputKind: 'object',
-        effects: ['Clones, links, or copies the plugin into the scope plugins directory. Registers the plugin in config.json with enabled=true. Marketplace installs refresh the source marketplace before resolving the plugin entry.'],
+        effects: [
+            'Clones, links, or copies the plugin into the scope plugins directory. Registers the plugin in config.json with enabled=true. Marketplace installs refresh the source marketplace before resolving the plugin entry.',
+            'If the plugin declares a command manifest, its commands go live on the next crtr invocation. A command leaf runs the plugin\'s own executable as trusted local code with your authority — only when you explicitly invoke that leaf, never on install, help, or discovery.',
+        ],
     },
     run: async (input) => {
         const rawRef = input['installRef'];
@@ -235,13 +259,11 @@ export const pluginInstall = defineLeaf({
         const gitRef = input['ref'];
         const scope = resolveInstallScope(scopeInput);
         const classified = classifyInstallRef(rawRef);
-        if (classified.kind === 'marketplace') {
-            return installFromMarketplace(classified.value, scope);
-        }
-        if (classified.kind === 'local') {
-            return installFromLocal(classified.value, scope);
-        }
-        return installFromGit(classified.value, gitRef, scope);
+        const installed = classified.kind === 'marketplace' ? installFromMarketplace(classified.value, scope)
+            : classified.kind === 'local' ? installFromLocal(classified.value, scope)
+                : installFromGit(classified.value, gitRef, scope);
+        const commands = commandReport(installed.name, installed.scope);
+        return commands !== undefined ? { ...installed, commands } : installed;
     },
 });
 export const pluginRemove = defineLeaf({
@@ -351,7 +373,7 @@ export const pluginUpdate = defineLeaf({
             { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Plugin name to update. Omit to update all installed plugins.' },
         ],
         output: [
-            { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per plugin processed: {name, updated, sha}.' },
+            { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per plugin processed: {name, updated, sha, commands?}. commands is present only for plugins declaring a command manifest: {mounts: string[] (accepted top-level command names), issues: object[] ({code, path?, message, received, expected, next})} — validated statically, never executing the plugin binary.' },
         ],
         outputKind: 'object',
         effects: ['Runs git pull in plugin or marketplace directories when they are git checkouts. Updates plugin version and last_updated state.'],

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);
+});