@north-light/crouter 0.3.154

package/dist/core/config.js

@@ -0,0 +1,620 @@
+import { mkdirSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { CONFIG_FILE, STATE_FILE, CONDENSED_HISTORY_MODES, 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) {
+    return join(root, CONFIG_FILE);
+}
+function statePathFor(root) {
+    return join(root, STATE_FILE);
+}
+export function configPath(scope) {
+    const root = scopeRoot(scope);
+    return root ? configPathFor(root) : null;
+}
+export function statePath(scope) {
+    const root = scopeRoot(scope);
+    return root ? statePathFor(root) : null;
+}
+export function readConfig(scope) {
+    const root = scopeRoot(scope);
+    if (!root)
+        return defaultScopeConfig();
+    return readConfigAtRoot(root);
+}
+/** Read the config that lives at an EXACT scope-root dir, rather than the
+ *  resolved nearest root for a scope. Lets a caller iterate each visible
+ *  project root's own config when several are in scope (nested `.crouter` dirs
+ *  or a profile-widened stack), instead of collapsing them onto the nearest. */
+export function readConfigAtRoot(root) {
+    const existing = readJsonIfExists(configPathFor(root));
+    if (!existing)
+        return defaultScopeConfig();
+    return mergeConfig(existing);
+}
+export function readState(scope) {
+    const root = scopeRoot(scope);
+    if (!root)
+        return defaultScopeState();
+    const existing = readJsonIfExists(statePathFor(root));
+    if (!existing)
+        return defaultScopeState();
+    return {
+        marketplaces: existing.marketplaces ?? {},
+        plugins: existing.plugins ?? {},
+        last_self_check: existing.last_self_check,
+        bootstrap_done: existing.bootstrap_done,
+        activeCanvas: existing.activeCanvas ?? null,
+    };
+}
+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);
+    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);
+    ensureDir(root);
+    writeJson(statePathFor(root), state);
+}
+export function ensureScopeInitialized(scope, root) {
+    ensureDir(root);
+    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, brokerThresholds, ...rest } = defaultScopeConfig();
+        // Broker thresholds are host-wide daemon policy, so only user scope
+        // persists them. Project config must never acquire a machine setting.
+        atomicWriteJson(cfgPath, scope === 'user' ? { ...rest, brokerThresholds } : 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;
+}
+function mergeModelLadders(raw, base = defaultModelLaddersConfig()) {
+    const defaults = base;
+    if (raw === null || typeof raw !== 'object')
+        return defaults;
+    const r = raw;
+    const out = {
+        anthropic: { ...defaults.anthropic },
+        openai: { ...defaults.openai },
+        ...(defaults.defaultProvider !== undefined ? { defaultProvider: defaults.defaultProvider } : {}),
+    };
+    if (r.defaultProvider === 'anthropic' || r.defaultProvider === 'openai') {
+        out.defaultProvider = r.defaultProvider;
+    }
+    for (const provider of ['anthropic', 'openai']) {
+        const over = r[provider];
+        if (over === null || typeof over !== 'object')
+            continue;
+        for (const [strength, value] of Object.entries(over)) {
+            if ((strength === 'ultra' || strength === 'strong' || strength === 'medium' || strength === 'light') && typeof value === 'string') {
+                out[provider][strength] = value;
+            }
+        }
+    }
+    return out;
+}
+/** True when `pattern` (a `spawnEnv.allow` entry) matches EVERY possible env
+ *  var name — a bare `*`, or any run of nothing but `*` characters (`**`,
+ *  `***`, …). This is the one glob shape that reopens the inherit-all hole
+ *  the whole spawn-env boundary exists to close, so it is rejected loud
+ *  rather than silently treated as literal or silently dropped (per
+ *  `cto-rejects-fallback-hedges`: fix the config, don't hedge around it). */
+function isInheritAllGlob(pattern) {
+    return pattern !== '' && pattern.replace(/\*/g, '') === '';
+}
+/** Merge a raw `spawnEnv.allow` list over `base` (defaulting to empty):
+ *  additive/union, not override — each scope only ADDS a name/glob it
+ *  explicitly admits across the broker spawn-env boundary (`buildBrokerEnv`),
+ *  never removes a lower-precedence scope's entry. Non-string entries are
+ *  dropped, never thrown, mirroring `mergeKinds`/`mergeModelLadders` — but an
+ *  inherit-all glob (`isInheritAllGlob`) throws immediately at config read: it
+ *  is not a shape any legitimate entry can mean, and silently accepting or
+ *  dropping it would either reopen the leak or hide a config mistake. */
+function mergeSpawnEnv(raw, base = []) {
+    const r = raw;
+    const extra = Array.isArray(r?.allow) ? r.allow.filter((v) => typeof v === 'string') : [];
+    for (const pattern of extra) {
+        if (isInheritAllGlob(pattern)) {
+            throw new Error(`spawnEnv.allow: "${pattern}" matches every env var name (inherit-all) — this is exactly the leak the spawn-env boundary closes. Name the specific vars/prefixes you actually need instead (e.g. "AWS_*", "GIT_ASKPASS").`);
+        }
+    }
+    return { allow: [...new Set([...base, ...extra])] };
+}
+/** Validate one raw `kinds.<name>` entry into a `KindConfig`, or drop it
+ *  (return null) rather than throwing — an invalid kind entry in config.json
+ *  must not break config parsing for every other kind. `whenToUse` is the
+ *  only required field. */
+function normalizeKindEntry(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    if (typeof r.whenToUse !== 'string' || r.whenToUse.trim() === '')
+        return null;
+    const out = { whenToUse: r.whenToUse };
+    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 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. 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) {
+                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;
+}
+/** Validate one raw `remoteCanvas.targets.<name>` entry, or drop it (return
+ *  null) rather than throwing — same rule `normalizeKindEntry` follows. A
+ *  valid entry needs a non-empty `previewEndpoint` and `relayTokenRef`; the
+ *  token itself is never stored here (see `RemoteCanvasTarget`). */
+function normalizeRemoteCanvasTarget(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    if (typeof r.previewEndpoint !== 'string' || r.previewEndpoint.trim() === '')
+        return null;
+    if (typeof r.relayTokenRef !== 'string' || r.relayTokenRef.trim() === '')
+        return null;
+    const out = { previewEndpoint: r.previewEndpoint, relayTokenRef: r.relayTokenRef };
+    if (typeof r.cpOrigin === 'string' && r.cpOrigin.trim() !== '')
+        out.cpOrigin = r.cpOrigin;
+    return out;
+}
+/** Merge a raw `remoteCanvas` block over the built-in defaults (no targets):
+ *  each valid `targets.<name>` entry adds or shadows a target by name;
+ *  invalid entries are dropped, never thrown. Mirrors `mergeKinds`'s
+ *  layer-over-defaults shape. */
+function mergeRemoteCanvas(raw, base = defaultRemoteCanvasConfig()) {
+    const out = { ...base.targets };
+    if (raw !== null && typeof raw === 'object') {
+        const r = raw;
+        if (r.targets !== null && typeof r.targets === 'object') {
+            for (const [name, value] of Object.entries(r.targets)) {
+                const normalized = normalizeRemoteCanvasTarget(value);
+                if (normalized !== null)
+                    out[name] = normalized;
+            }
+        }
+    }
+    return { targets: out };
+}
+function normalizeMode(value, fallback) {
+    if (value === true)
+        return 'notify';
+    if (value === false)
+        return false;
+    if (value === 'notify' || value === 'apply')
+        return value;
+    return fallback;
+}
+function normalizePositiveInteger(value, fallback) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 1
+        ? value
+        : fallback;
+}
+function mergeBrokerThresholds(raw, defaults) {
+    const partial = raw !== null && typeof raw === 'object'
+        ? raw
+        : {};
+    const warning = normalizePositiveInteger(partial.warning, defaults.warning);
+    const automaticReviveCap = normalizePositiveInteger(partial.automaticReviveCap, defaults.automaticReviveCap);
+    return warning <= automaticReviveCap
+        ? { warning, automaticReviveCap }
+        : { ...defaults };
+}
+function mergeConfig(partial) {
+    const defaults = defaultScopeConfig();
+    const schema_version = defaults.schema_version;
+    const marketplaces = partial.marketplaces === undefined ? {} : partial.marketplaces;
+    const plugins = partial.plugins === undefined ? {} : partial.plugins;
+    const configuredClis = partial.configuredClis === undefined ? {} : partial.configuredClis;
+    const au = partial.auto_update;
+    const rawInterval = au && typeof au.interval_hours === 'number' ? au.interval_hours : undefined;
+    const interval_hours = rawInterval !== undefined && Number.isFinite(rawInterval) && rawInterval >= 0
+        ? rawInterval
+        : defaults.auto_update.interval_hours;
+    const auto_update = {
+        crtr: normalizeMode(au?.crtr, defaults.auto_update.crtr),
+        content: normalizeMode(au?.content, defaults.auto_update.content),
+        interval_hours,
+    };
+    const rawMaxPanes = partial.max_panes_per_window;
+    const max_panes_per_window = normalizePositiveInteger(rawMaxPanes, defaults.max_panes_per_window);
+    const brokerThresholds = mergeBrokerThresholds(partial.brokerThresholds, defaults.brokerThresholds);
+    const completion_bell = typeof partial.completion_bell === 'boolean' ? partial.completion_bell : defaults.completion_bell;
+    const live_cycles = normalizePositiveInteger(partial.live_cycles, defaults.live_cycles);
+    const condensed_history = CONDENSED_HISTORY_MODES.includes(partial.condensed_history)
+        ? partial.condensed_history
+        : defaults.condensed_history;
+    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, configuredClis, auto_update, max_panes_per_window, brokerThresholds, completion_bell, live_cycles, condensed_history, 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
+ *  scopes onto each other WITHOUT each scope's own default-fill masking a
+ *  lower-precedence scope's real customization (see that function's comment
+ *  for why `readConfig(scope)`, which already defaults-fills, is unusable
+ *  for cross-scope layering). */
+export function readRawConfigAtRoot(root) {
+    return readJsonIfExists(configPathFor(root));
+}
+export function readRawScopeConfig(scope) {
+    const root = scopeRoot(scope);
+    return root ? readRawConfigAtRoot(root) : null;
+}
+/** Raw partial config at `<profileRoot(profileId)>/config.json`, or null when
+ *  no profile is selected, the profile id no longer resolves (deleted/
+ *  invalid), or it has no config.json. `profileRoot` centralizes the id-shape
+ *  + containment checks (never a raw path join), and any resolution failure
+ *  is swallowed here — launch config resolution is a hot path that must never
+ *  throw on a stale `CRTR_PROFILE_ID`. */
+function readRawProfileConfig(profileId) {
+    if (profileId === null || profileId === '')
+        return null;
+    try {
+        return readJsonIfExists(configPathFor(profileRoot(profileId)));
+    }
+    catch {
+        return null;
+    }
+}
+/** Raw partial configs for the whole project-scope STACK (`findProjectScopeRoots`
+ *  — every ancestor `.crouter/`, widened by a selected profile's `projects`),
+ *  ordered FARTHEST-first so `readMergedLaunchConfig` can layer them on last
+ *  and have the NEAREST root win — mirroring the resolver's nearest-project-
+ *  strongest replacement precedence. Walks from `targetCwd`/`targetProfileId`
+ *  — the SCOPE THE CONFIG IS FOR, not necessarily the calling process's own
+ *  ambient cwd/profile (see `readMergedLaunchConfig`). */
+function readRawProjectScopeConfigs(targetCwd, targetProfileId) {
+    const nearestFirst = findProjectScopeRoots(targetCwd, targetProfileId);
+    const farthestFirst = [...nearestFirst].reverse();
+    const out = [];
+    for (const root of farthestFirst) {
+        const raw = readJsonIfExists(configPathFor(root));
+        if (raw !== null)
+            out.push(raw);
+    }
+    return out;
+}
+/** Merge launch knobs (`kinds`, `modelLadders`) across scopes in
+ *  project stack > profile > user > builtin precedence — the same precedence
+ *  order used for memory resolution. A kind or ladder cell declared at a
+ *  more-specific scope shadows the same key from a less-specific scope; the
+ *  project STACK (`findProjectScopeRoots` — every ancestor `.crouter/`,
+ *  widened by a selected profile's `projects`) layers nearest-root-strongest;
+ *  a key no scope declares falls through to the builtin default registry
+ *  (`defaultScopeConfig().kinds` / `.modelLadders`).
+ *
+ *  Layers RAW (un-defaulted) partial config per scope, not `readConfig(scope)`
+ *  — `readConfig` already fills in every default kind for a scope that
+ *  customizes even one, so naively overlaying two already-defaulted
+ *  `ScopeConfig.kinds` objects would let an untouched project-scope kind
+ *  (silently defaulted) clobber a real user-scope customization of that same
+ *  kind. Layering the raw partials avoids that.
+ *
+ *  Callers (launch, kind registry) go through this function rather than
+ *  `readConfig` directly, so `ScopeConfig.kinds`/`modelLadders`/tools/
+ *  extensions/`availableTo` all honor the same profile + multi-project
+ *  precedence.
+ *
+ *  `targetCwd`/`targetProfileId` default to this PROCESS's own ambient cwd
+ *  and `CRTR_PROFILE_ID` — correct for a caller resolving config for itself
+ *  (front-door commands, kind listing). A caller resolving config on behalf
+ *  of a DIFFERENT node (the broker spawn-env boundary or cron executor — both
+ *  run inside the daemon, whose ambient cwd/profile is the daemon's own, not
+ *  the target node's) MUST pass the target's own cwd/profile explicitly, or
+ *  `spawnEnv.allow` resolves from the wrong scope entirely (the C-1
+ *  follow-up fix this parameterization exists for). */
+export function readMergedLaunchConfig(targetCwd = process.cwd(), targetProfileId = process.env['CRTR_PROFILE_ID'] || null) {
+    const defaults = defaultScopeConfig();
+    const userRaw = readRawScopeConfig('user');
+    const profileRaw = readRawProfileConfig(targetProfileId);
+    const projectRawsFarthestFirst = readRawProjectScopeConfigs(targetCwd, targetProfileId);
+    let kinds = mergeKinds(userRaw?.kinds, defaults.kinds);
+    let modelLadders = mergeModelLadders(userRaw?.modelLadders, defaults.modelLadders);
+    let spawnEnv = mergeSpawnEnv(userRaw?.spawnEnv, defaults.spawnEnv?.allow);
+    if (profileRaw !== null) {
+        kinds = mergeKinds(profileRaw.kinds, kinds);
+        modelLadders = mergeModelLadders(profileRaw.modelLadders, modelLadders);
+        spawnEnv = mergeSpawnEnv(profileRaw.spawnEnv, spawnEnv.allow);
+    }
+    for (const raw of projectRawsFarthestFirst) {
+        kinds = mergeKinds(raw.kinds, kinds);
+        modelLadders = mergeModelLadders(raw.modelLadders, modelLadders);
+        spawnEnv = mergeSpawnEnv(raw.spawnEnv, spawnEnv.allow);
+    }
+    return { kinds, modelLadders, spawnEnv };
+}
+/** The effective `KindConfig` for one full kind string (top-level, e.g.
+ *  `developer`, or sub-kind, e.g. `plan/reviewers/security`), across
+ *  project > user > builtin precedence. Returns `undefined` for a kind no
+ *  scope registers — existence is deliberately NOT validated here (kind
+ *  existence/launch-menu enumeration is a Phase 3 caller concern); this only
+ *  resolves the config for a kind the caller already knows about. */
+export function resolveKindConfig(kind) {
+    return readMergedLaunchConfig().kinds[kind];
+}
+/** The sub-kinds available to spawn FROM a given top-level kind — every
+ *  registered sub-kind (full path contains `/`) whose `availableTo` (default:
+ *  its own top-level ancestor, e.g. `plan/reviewers/security` defaults to
+ *  `['plan']`) includes `kind` or `'*'`. The single source both `sys
+ *  prompt-review --list`'s `subPersonas` metadata and the live sub-persona
+ *  spawn-menu splice (`core/substrate/render.ts`) read, so the two can never
+ *  drift apart. Sorted by full kind name for stable rendering. */
+export function subKindsAvailableTo(kind) {
+    const registry = readMergedLaunchConfig().kinds;
+    const out = [];
+    for (const [full, cfg] of Object.entries(registry)) {
+        const slash = full.indexOf('/');
+        if (slash === -1)
+            continue;
+        const topAncestor = full.slice(0, slash);
+        const availableTo = cfg.availableTo ?? [topAncestor];
+        if (!(availableTo.includes('*') || availableTo.includes(kind)))
+            continue;
+        out.push({ kind: full, whenToUse: cfg.whenToUse });
+    }
+    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', 'configuredClis', 'auto_update',
+    'max_panes_per_window', 'brokerThresholds', 'completion_bell', 'live_cycles', 'condensed_history', '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. */
+function mutateConfigAtPath(path, mutate) {
+    return withConfigPathLock(path, (lockedPath) => {
+        const raw = readJsonIfExists(lockedPath) ?? {};
+        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;
+        atomicWriteJson(lockedPath, partial);
+        return cfg;
+    });
+}
+/** Persist an EXPLICIT sparse `modelLadders` intent at one config root: the
+ *  patch's rungs (and `defaultProvider`) are merged over whatever sparse ladder
+ *  is already on disk, and every untouched rung stays absent so it keeps
+ *  re-deriving from the running build's registry.
+ *
+ *  Ladder edits must come through here rather than `updateConfig`, because that
+ *  path infers what to persist by diffing the mutated config against the merged
+ *  baseline: setting a rung to the value that happens to be today's compiled
+ *  default produces an empty diff and silently persists nothing, so the choice
+ *  evaporates as soon as the default moves. Explicit intent is recorded as
+ *  written. Mirrors `persistDefaultKindModel`. */
+export function persistModelLadders(root, patch) {
+    const path = configPathFor(root);
+    ensureDir(root);
+    withConfigPathLock(path, (lockedPath) => {
+        const raw = readJsonIfExists(lockedPath) ?? {};
+        const current = (raw.modelLadders ?? {});
+        const next = { ...current };
+        if (patch.defaultProvider !== undefined)
+            next.defaultProvider = patch.defaultProvider;
+        for (const provider of ['anthropic', 'openai']) {
+            const rungs = patch[provider];
+            if (rungs !== undefined)
+                next[provider] = { ...(current[provider] ?? {}), ...rungs };
+        }
+        atomicWriteJson(lockedPath, { ...raw, modelLadders: next });
+    });
+}
+/** Mutate one exact config root. Setup uses this for profile and explicit
+ * project targets that cannot be represented by the user/project Scope enum. */
+export function updateConfigAtRoot(root, mutate) {
+    return mutateConfigAtPath(configPathFor(root), mutate);
+}
+export function updateConfig(scope, mutate) {
+    return updateConfigAtRoot(requireScopeRoot(scope), mutate);
+}
+/** Persist one sparse kind-model field at an exact config root. The sparse
+ * patch keeps every unrelated kind and launch knob inherited from lower
+ * scopes instead of freezing a materialized registry snapshot. */
+export function persistDefaultKindModel(opts) {
+    const field = opts.orchestrator === true ? 'orchestratorModel' : 'model';
+    const path = configPathFor(opts.root);
+    ensureDir(opts.root);
+    withConfigPathLock(path, (lockedPath) => {
+        const raw = readJsonIfExists(lockedPath) ?? {};
+        const kinds = { ...(raw.kinds ?? {}) };
+        kinds[opts.kind] = { ...(kinds[opts.kind] ?? {}), [field]: opts.model };
+        atomicWriteJson(lockedPath, { ...raw, kinds });
+    });
+    return { path, field };
+}
+export function updateState(scope, mutate) {
+    const s = readState(scope);
+    mutate(s);
+    writeState(scope, s);
+    return s;
+}

package/dist/core/configured-clis/cache.d.ts

@@ -0,0 +1,16 @@
+import type { ConfiguredCliRegistration } from './registration.js';
+/** Minimal metadata stored with a cached manifest. */
+export interface CacheMetadata {
+    /** The endpoint this manifest was fetched from; a mismatch invalidates the cache. */
+    endpoint: string;
+}
+/** Read the cached manifest bytes if present. Returns null if absent or unreadable. */
+export declare function readConfiguredCliCacheManifest(registration: ConfiguredCliRegistration): Uint8Array | null;
+/** Write a manifest to cache atomically. Replaces any prior manifest and stores minimal metadata. */
+export declare function writeConfiguredCliCacheManifest(registration: ConfiguredCliRegistration, rawManifest: Uint8Array): void;
+/** Check if cache metadata exists and matches the current endpoint.
+ *  Returns true if both manifest and metadata exist with matching endpoint;
+ *  false if absent, unreadable, or endpoint mismatch. */
+export declare function isCacheMetadataValid(registration: ConfiguredCliRegistration): boolean;
+/** Remove the cache directory for a registration. */
+export declare function removeConfiguredCliCache(registration: ConfiguredCliRegistration): void;