@crouton-kit/crouter 0.3.68 → 0.3.78

package/dist/core/config.js

@@ -1,6 +1,8 @@
-import { join } from 'node:path';
-import { CONFIG_FILE, STATE_FILE, defaultScopeConfig, defaultScopeState, defaultCanvasNavConfig, defaultModelLaddersConfig, defaultKindsConfig, defaultRemoteCanvasConfig } from '../types.js';
-import { readJsonIfExists, writeJson, ensureDir } from './fs-utils.js';
+import { mkdirSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { CONFIG_FILE, STATE_FILE, defaultScopeConfig, defaultScopeState, defaultModelLaddersConfig, defaultKindsConfig, defaultRemoteCanvasConfig } from '../types.js';
+import { atomicWriteJson, readJsonIfExists, writeJson, ensureDir } from './fs-utils.js';
 import { scopeRoot, requireScopeRoot, findProjectScopeRoots } from './scope.js';
 import { profileRoot } from './profiles/manifest.js';
 function configPathFor(root) {
@@ -41,10 +43,60 @@ export function readState(scope) {
         activeCanvas: existing.activeCanvas ?? null,
     };
 }
-export function writeConfig(scope, config) {
+const CONFIG_LOCK_TIMEOUT_MS = 5000;
+const CONFIG_LOCK_POLL_MS = 25;
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function withConfigPathLock(path, run) {
+    ensureDir(dirname(path));
+    const lockPath = `${path}.lock`;
+    const deadline = Date.now() + CONFIG_LOCK_TIMEOUT_MS;
+    for (;;) {
+        try {
+            mkdirSync(lockPath);
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            if (Date.now() > deadline)
+                throw new Error(`timed out waiting for config lock: ${path}`);
+            sleepSync(CONFIG_LOCK_POLL_MS);
+        }
+    }
+    try {
+        return run(path);
+    }
+    finally {
+        rmSync(lockPath, { recursive: true, force: true });
+    }
+}
+function withConfigLock(scope, run) {
     const root = requireScopeRoot(scope);
-    ensureDir(root);
-    writeJson(configPathFor(root), config);
+    return withConfigPathLock(configPathFor(root), run);
+}
+export function updateRawConfigAtomically(scope, mutate) {
+    return withConfigLock(scope, (path) => {
+        const latest = readJsonIfExists(path) ?? {};
+        const next = mutate(latest);
+        atomicWriteJson(path, next);
+        return next;
+    });
+}
+export function writeConfig(scope, config) {
+    withConfigLock(scope, (path) => atomicWriteJson(path, config));
+}
+/** 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 function writeRawConfig(scope, config) {
+    withConfigLock(scope, (path) => atomicWriteJson(path, config));
 }
 export function writeState(scope, state) {
     const root = requireScopeRoot(scope);
@@ -53,105 +105,39 @@ export function writeState(scope, state) {
 }
 export function ensureScopeInitialized(scope, root) {
     ensureDir(root);
-    const cfgPath = configPathFor(root);
-    if (!readJsonIfExists(cfgPath)) {
-        writeJson(cfgPath, defaultScopeConfig());
-    }
-}
-function prefixBindDesc(desc) {
-    return typeof desc === 'string' && desc !== '' ? { desc } : {};
-}
-function normalizePrefixMenuItem(raw) {
-    if (raw === null || typeof raw !== 'object')
-        return null;
-    const r = raw;
-    const key = typeof r.key === 'string' && r.key !== '' ? r.key : null;
-    const desc = typeof r.desc === 'string' && r.desc !== '' ? r.desc : null;
-    const action = normalizePrefixBind(r.action);
-    if (key === null || desc === null || action === null)
-        return null;
-    const out = { key, desc, action };
-    if (r.confirm === true)
-        out.confirm = true;
-    return out;
-}
-function normalizePrefixBind(raw) {
-    if (raw === null || typeof raw !== 'object')
-        return null;
-    const r = raw;
-    const desc = prefixBindDesc(r.desc);
-    const confirm = r.confirm === true ? { confirm: true } : {};
-    if (typeof r.run === 'string') {
-        if (r.run === '__graph__')
-            return { kind: 'keys', keys: '/graph', ...desc };
-        if (r.run === '__issue__') {
-            return {
-                kind: 'menu',
-                items: [
-                    { key: 'i', desc: 'idea', action: { kind: 'popup', run: 'canvas issue new --type idea' } },
-                    { key: 'b', desc: 'bug', action: { kind: 'popup', run: 'canvas issue new --type bug' } },
-                ],
-                ...desc,
-            };
-        }
-    }
-    if (r.kind === 'keys' && typeof r.keys === 'string')
-        return { kind: 'keys', keys: r.keys, ...desc };
-    if (r.kind === 'popup' && typeof r.run === 'string')
-        return { kind: 'popup', run: r.run, ...desc };
-    if (r.kind === 'menu' && Array.isArray(r.items)) {
-        const items = r.items.map(normalizePrefixMenuItem).filter((item) => item !== null);
-        if (items.length !== r.items.length)
-            return null;
-        return { kind: 'menu', items, ...desc };
-    }
-    if ((r.kind === undefined || r.kind === 'crtr') && typeof r.run === 'string') {
-        return { kind: 'crtr', run: r.run, ...confirm, ...desc };
-    }
-    if (r.kind === undefined && typeof r.keys === 'string')
-        return { kind: 'keys', keys: r.keys, ...desc };
-    return null;
-}
-function normalizeGraphBind(raw) {
-    if (raw === null || typeof raw !== 'object')
-        return null;
-    const r = raw;
-    if (typeof r.run !== 'string')
-        return null;
-    return {
-        run: r.run,
-        ...(r.confirm === true ? { confirm: true } : {}),
-        ...(typeof r.desc === 'string' && r.desc !== '' ? { desc: r.desc } : {}),
-    };
-}
-/** Deep-merge one bind table over its built-in defaults: a user adding a single
- *  bind must not wipe the rest. Each user entry is normalized before it
- *  replaces/extends a key. */
-function mergeBinds(base, over, normalize) {
-    const out = { ...base };
-    if (over !== null && typeof over === 'object') {
-        for (const [k, v] of Object.entries(over)) {
-            const normalized = normalize(v);
-            if (normalized !== null)
-                out[k] = normalized;
+    withConfigPathLock(configPathFor(root), (cfgPath) => {
+        if (readJsonIfExists(cfgPath))
+            return;
+        // Persist no materialized model ladder or keybinding defaults. `modelLadders` holds concrete model ids (e.g.
+        // "openai-codex/gpt-5.6-sol:high") that are only valid as long as they match whatever
+        // pi model registry this crouter build ships. Baking a materialized snapshot here would
+        // freeze this scope's ladder to whatever ids happened to be current the moment it was
+        // first initialized -- a later crouter/pi upgrade (or a rollback) that changes the
+        // registry can then never reach it: the stale persisted override still wins over the
+        // new build's compiled defaults in `mergeConfig`/`mergeModelLadders`, producing a
+        // fallback rung `resolveViableFallback` rejects as unregistered while the terminal
+        // error misleadingly claims the fallback provider needs authenticating (see live
+        // incident: a home's config.json was seeded with `gpt-5.6-*` ladder entries from a
+        // build newer than the one actually installed, so its own model registry never had
+        // them). Omitting the key here is safe: `readConfig`/`mergeConfig` already default-fill
+        // a missing `modelLadders` from whatever build is CURRENTLY running, and an explicit
+        // user override (`sys config set modelLadders...`) still persists and still wins.
+        // Keybindings are sparse user overrides, so an untouched scope omits that member too.
+        const { modelLadders: _omittedModelLadders, keybindings: _omittedKeybindings, ...rest } = defaultScopeConfig();
+        atomicWriteJson(cfgPath, rest);
+    });
+}
+function normalizeKeybindings(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [id, gestures] of Object.entries(raw)) {
+        if (Array.isArray(gestures) && gestures.every((gesture) => typeof gesture === 'string')) {
+            out[id] = [...gestures];
         }
     }
     return out;
 }
-/** Validate + deep-merge a user `canvasNav` block over the built-in defaults.
- *  An absent or malformed block falls back wholesale to defaults. */
-function mergeCanvasNav(raw) {
-    const defaults = defaultCanvasNavConfig();
-    if (raw === null || typeof raw !== 'object')
-        return defaults;
-    const r = raw;
-    const prefixKey = typeof r.prefixKey === 'string' && r.prefixKey.trim() !== '' ? r.prefixKey : defaults.prefixKey;
-    return {
-        prefixKey,
-        prefixBinds: mergeBinds(defaults.prefixBinds, r.prefixBinds, normalizePrefixBind),
-        graphBinds: mergeBinds(defaults.graphBinds, r.graphBinds, normalizeGraphBind),
-    };
-}
 function mergeModelLadders(raw, base = defaultModelLaddersConfig()) {
     const defaults = base;
     if (raw === null || typeof raw !== 'object')
@@ -228,18 +214,55 @@ function normalizeKindEntry(raw) {
         out.availableTo = r.availableTo;
     return out;
 }
+/** Validate one raw `kinds.<name>` entry as a sparse PATCH — an entry with no
+ *  `whenToUse` that overrides individual launch knobs (model/orchestratorModel/
+ *  tools/extensions/availableTo) of a kind some lower-precedence scope already
+ *  defines. This is what lets a scope (e.g. a profile) persist ONLY
+ *  `{ "model": "ultra" }` for a kind instead of freezing a full registry
+ *  snapshot to disk (the same staleness trap `sparseModelLaddersToPersist`
+ *  exists to avoid). Returns null when no valid field is present. */
+function normalizeKindPatch(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    const out = {};
+    if (typeof r.model === 'string' && r.model.trim() !== '')
+        out.model = r.model;
+    if (typeof r.orchestratorModel === 'string' && r.orchestratorModel.trim() !== '')
+        out.orchestratorModel = r.orchestratorModel;
+    const isStringArray = (v) => Array.isArray(v) && v.every((item) => typeof item === 'string');
+    if (isStringArray(r.tools))
+        out.tools = r.tools;
+    if (isStringArray(r.extensions))
+        out.extensions = r.extensions;
+    if (isStringArray(r.availableTo))
+        out.availableTo = r.availableTo;
+    return Object.keys(out).length > 0 ? out : null;
+}
 /** Merge a raw `kinds` block over `base` (defaulting to the builtin registry):
  *  each valid entry adds or shadows a kind by name; invalid entries are
  *  dropped, never thrown. Mirrors `mergeModelLadders`'s layer-over-defaults
  *  shape so a user/project config.json can add or override a single kind
- *  without restating the whole registry. */
+ *  without restating the whole registry. Two entry shapes:
+ *   - FULL (has `whenToUse`): defines or wholly replaces the kind, as before.
+ *   - PATCH (no `whenToUse`, ≥1 valid launch field): field-merges over the
+ *     kind the layers below already define (dropped when they don't) — the
+ *     sparse-override shape `persistDefaultKindModel` writes. */
 function mergeKinds(raw, base = defaultKindsConfig()) {
     const out = { ...base };
     if (raw !== null && typeof raw === 'object') {
         for (const [kind, value] of Object.entries(raw)) {
             const normalized = normalizeKindEntry(value);
-            if (normalized !== null)
+            if (normalized !== null) {
                 out[kind] = normalized;
+                continue;
+            }
+            const existing = out[kind];
+            if (existing === undefined)
+                continue;
+            const patch = normalizeKindPatch(value);
+            if (patch !== null)
+                out[kind] = { ...existing, ...patch };
         }
     }
     return out;
@@ -307,12 +330,12 @@ function mergeConfig(partial) {
     const max_panes_per_window = typeof rawMaxPanes === 'number' && Number.isFinite(rawMaxPanes) && rawMaxPanes >= 1
         ? Math.floor(rawMaxPanes)
         : defaults.max_panes_per_window;
-    const canvasNav = mergeCanvasNav(partial.canvasNav);
+    const keybindings = normalizeKeybindings(partial.keybindings);
     const modelLadders = mergeModelLadders(partial.modelLadders);
     const kinds = mergeKinds(partial.kinds);
     const remoteCanvas = mergeRemoteCanvas(partial.remoteCanvas);
     const spawnEnv = mergeSpawnEnv(partial.spawnEnv, defaults.spawnEnv?.allow);
-    return { schema_version, marketplaces, plugins, auto_update, max_panes_per_window, canvasNav, modelLadders, kinds, remoteCanvas, spawnEnv };
+    return { schema_version, marketplaces, plugins, auto_update, max_panes_per_window, keybindings, modelLadders, kinds, remoteCanvas, spawnEnv };
 }
 /** 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
@@ -320,7 +343,7 @@ function mergeConfig(partial) {
  *  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). */
-function readRawScopeConfig(scope) {
+export function readRawScopeConfig(scope) {
     const root = scopeRoot(scope);
     if (!root)
         return null;
@@ -440,11 +463,106 @@ export function subKindsAvailableTo(kind) {
     }
     return out.sort((a, b) => a.kind.localeCompare(b.kind));
 }
+/** Every top-level `ScopeConfig` key, diffed one-by-one by `updateConfig` so
+ *  an untouched key is never rewritten. */
+const CONFIG_TOP_LEVEL_KEYS = [
+    'schema_version', 'marketplaces', 'plugins', 'auto_update',
+    'max_panes_per_window', 'keybindings', 'modelLadders', 'kinds',
+    'remoteCanvas', 'spawnEnv',
+];
+/** The SPARSE `modelLadders` to persist after a config mutation: the raw
+ *  on-disk sparse ladder (absent rungs stay absent) plus ONLY the specific
+ *  rungs / `defaultProvider` the mutation actually changed away from the
+ *  merged baseline. Untouched default rungs are never materialized -- they
+ *  hold concrete model ids that go stale across builds (the live-Hearth freeze
+ *  bug). Returns undefined when nothing ladder-related is on disk and nothing
+ *  was touched, so the key is omitted from config.json entirely. This is what
+ *  makes a direct `sys config set modelLadders.<provider>.<strength>` persist
+ *  only the touched rung through the SAME central write path as every other
+ *  mutation, rather than a special case. */
+function sparseModelLaddersToPersist(rawLadders, baseline, mutated) {
+    const out = { ...(rawLadders ?? {}) };
+    if (out.anthropic !== undefined)
+        out.anthropic = { ...out.anthropic };
+    if (out.openai !== undefined)
+        out.openai = { ...out.openai };
+    if (mutated.defaultProvider !== baseline.defaultProvider && mutated.defaultProvider !== undefined) {
+        out.defaultProvider = mutated.defaultProvider;
+    }
+    for (const provider of ['anthropic', 'openai']) {
+        for (const strength of ['ultra', 'strong', 'medium', 'light']) {
+            if (mutated[provider][strength] !== baseline[provider][strength]) {
+                out[provider] = { ...(out[provider] ?? {}), [strength]: mutated[provider][strength] };
+            }
+        }
+    }
+    const hasContent = out.defaultProvider !== undefined || out.anthropic !== undefined || out.openai !== undefined;
+    return hasContent ? out : undefined;
+}
+/** 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 function updateConfig(scope, mutate) {
-    const cfg = readConfig(scope);
-    mutate(cfg);
-    writeConfig(scope, cfg);
-    return cfg;
+    let result;
+    updateRawConfigAtomically(scope, (latest) => {
+        const raw = latest;
+        const baseline = mergeConfig(raw);
+        const cfg = mergeConfig(raw);
+        mutate(cfg);
+        const partial = { ...raw };
+        for (const key of CONFIG_TOP_LEVEL_KEYS) {
+            if (key === 'modelLadders')
+                continue;
+            if (!isDeepStrictEqual(cfg[key], baseline[key])) {
+                partial[key] = cfg[key];
+            }
+        }
+        const ladders = sparseModelLaddersToPersist(raw.modelLadders, baseline.modelLadders, cfg.modelLadders);
+        if (ladders !== undefined)
+            partial.modelLadders = ladders;
+        else
+            delete partial.modelLadders;
+        result = cfg;
+        return partial;
+    });
+    return result;
+}
+/** 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 function persistDefaultKindModel(opts) {
+    const field = opts.orchestrator === true ? 'orchestratorModel' : 'model';
+    let root;
+    let scope;
+    if (opts.profileId !== undefined && opts.profileId !== null && opts.profileId !== '') {
+        root = profileRoot(opts.profileId);
+        scope = 'profile';
+    }
+    else {
+        root = requireScopeRoot('user');
+        scope = 'user';
+    }
+    ensureDir(root);
+    const path = configPathFor(root);
+    const raw = readJsonIfExists(path) ?? {};
+    const kinds = { ...(raw.kinds ?? {}) };
+    kinds[opts.kind] = { ...(kinds[opts.kind] ?? {}), [field]: opts.model };
+    raw['kinds'] = kinds;
+    writeJson(path, raw);
+    return { scope, path, field };
 }
 export function updateState(scope, mutate) {
     const s = readState(scope);

package/dist/core/fault-classifier.js

@@ -15,7 +15,7 @@ function classifyProviderText(message) {
         return 'overloaded';
     if (/invalid_grant|refresh token|unauthori[sz]ed|invalid.?api.?key|authentication failed|\b401\b|\b403\b/i.test(m))
         return 'auth';
-    if (/connection|econnreset|etimedout|enotfound|econnrefused|network|fetch failed|socket hang|timed? out|timeout/i.test(m))
+    if (/connection|econnreset|etimedout|enotfound|econnrefused|network|fetch failed|socket hang|timed? out|timeout|\bterminated\b|other side closed|premature close/i.test(m))
         return 'connection';
     return 'other';
 }

package/dist/core/fs-utils.d.ts

@@ -1,5 +1,6 @@
 export declare function ensureDir(dir: string): void;
 export declare function writeJson(path: string, data: unknown): void;
+export declare function atomicWriteJson(path: string, data: unknown): void;
 export declare function readJson<T = unknown>(path: string): T;
 export declare function readJsonIfExists<T = unknown>(path: string): T | null;
 export declare function readTextIfExists(path: string): string | null;

package/dist/core/fs-utils.js

@@ -1,4 +1,4 @@
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync, cpSync, readlinkSync, } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync, cpSync, readlinkSync, renameSync, chmodSync, } from 'node:fs';
 import { dirname, join, relative } from 'node:path';
 import { platform } from 'node:os';
 export function ensureDir(dir) {
@@ -8,6 +8,20 @@ export function writeJson(path, data) {
     ensureDir(dirname(path));
     writeFileSync(path, JSON.stringify(data, null, 2) + '\n', 'utf8');
 }
+export function atomicWriteJson(path, data) {
+    ensureDir(dirname(path));
+    const temp = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
+    const mode = existsSync(path) ? statSync(path).mode & 0o777 : 0o600;
+    try {
+        writeFileSync(temp, JSON.stringify(data, null, 2) + '\n', { encoding: 'utf8', mode });
+        chmodSync(temp, mode);
+        renameSync(temp, path);
+    }
+    finally {
+        if (existsSync(temp))
+            rmSync(temp, { force: true });
+    }
+}
 export function readJson(path) {
     return JSON.parse(readFileSync(path, 'utf8'));
 }

package/dist/core/keybindings/__tests__/resolve.test.d.ts

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