@crouter/api 0.3.387 → 0.3.388

package/dist/core/config.js

@@ -0,0 +1,1120 @@
+import { envProfileId } from '../shared/env.js';
+import { basename, join } from 'node:path';
+import { existsSync, mkdirSync, statSync } from 'node:fs';
+import { isDeepStrictEqual } from 'node:util';
+import { CONFIG_FILE, STATE_FILE, CONDENSED_HISTORY_MODES, MOUSE_MODE_DEFAULTS, WHIP_MESSAGE_MODES, DEFAULT_WHIP_MESSAGES, defaultScopeConfig, defaultScopeState, defaultModelLaddersConfig, defaultKindsConfig, defaultRemoteCanvasConfig } from '../types.js';
+import { BINDING_CATALOG, BINDING_IDS, isAttachPaneBinding } from './keybindings/catalog.js';
+import { notFound } from './errors.js';
+import { emitEvent } from './events/emit.js';
+import { atomicWriteJson, readJsonIfExists, ensureDir } from './fs-utils.js';
+import { scopeRoot, requireScopeRoot, findProjectScopeRoots, userScopeRoot } from './scope.js';
+import { listInstalledPluginsInRoot } from './installed-plugins.js';
+import { profileMemoryDir, listProfiles } from './profiles/manifest.js';
+import { canonicalRoot, projectStore, userStore } from './scoped-state/paths.js';
+import { convertLegacyScopedStore, initializeFreshScopedStore } from './scoped-state/migrate.js';
+import { mutateRawSettings, readBookkeeping, readRawSettings, readRawSettingsWithRevision, replaceRawSettings, writeBookkeeping, writeRawSettings } from './scoped-state/settings.js';
+import { withExclusiveDirectoryLock } from './exclusive-lock.js';
+import { SCOPE_CONFIG_KEYS } from './user-settings.js';
+import { normalizeWorkingGerunds } from '../shared/working-activity.js';
+import { mergePageComponentLayers, normalizePageComponents } from './human/page-catalog.js';
+function configPathFor(root) {
+    return join(root, CONFIG_FILE);
+}
+function withConfigPathLock(path, run) {
+    // A project config write must fail if its root was removed, not recreate it.
+    return withExclusiveDirectoryLock(`${path}.lock`, () => run(path), { timeoutError: () => new Error(`timed out waiting for config lock: ${path}`) });
+}
+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;
+}
+function settingsOwnerForRoot(root) {
+    const canonical = canonicalRoot(root);
+    const userRoot = canonicalRoot(userScopeRoot());
+    if (canonical === userRoot)
+        return { store: userStore(userRoot), key: 'user', kind: 'user', root: userRoot };
+    // Project roots can be classified without opening the user store. This keeps a
+    // fresh project usable when an unrelated legacy user root still needs conversion.
+    if (basename(canonical) === '.crouter') {
+        convertLegacyScopedStore({ kind: 'project', root: canonical });
+        return { store: projectStore(canonical), key: 'project', kind: 'project', root: canonical };
+    }
+    for (const profile of listProfiles()) {
+        const profilePath = canonicalRoot(profileMemoryDir(profile.profileId));
+        if (canonical === profilePath)
+            return { store: userStore(userRoot), key: `profile:${profile.profileId}`, kind: 'profile', root: profilePath, profileId: profile.profileId };
+    }
+    throw new Error(`settings root is not a recognized owner: ${root}`);
+}
+function readRawAtRoot(root) {
+    // Project configuration is a file; reading it must not initialize SQL state
+    // (or its lock directory) after the project disappears.
+    if (basename(root) === '.crouter') {
+        let canonical;
+        try {
+            canonical = canonicalRoot(root);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        }
+        if (canonical !== canonicalRoot(userScopeRoot()))
+            return readJsonIfExists(configPathFor(root));
+    }
+    return readRawSettings(settingsOwnerForRoot(root));
+}
+function writeRawAtRoot(root, raw) {
+    const owner = settingsOwnerForRoot(root);
+    if (owner.kind === 'project') {
+        withConfigPathLock(configPathFor(owner.root), (path) => atomicWriteJson(path, raw, { createParent: false }));
+        return;
+    }
+    writeRawSettings(owner, raw);
+}
+function mutateRawAtRoot(root, mutate) {
+    const owner = settingsOwnerForRoot(root);
+    if (owner.kind === 'project')
+        return withConfigPathLock(configPathFor(owner.root), (path) => { const result = mutate(readJsonIfExists(path) ?? {}); atomicWriteJson(path, result.next, { createParent: false }); return result.value; });
+    return mutateRawSettings(owner, (raw) => mutate(raw));
+}
+const brokerSnapshotState = globalThis;
+const brokerSnapshotKey = Symbol.for('crtr.broker.config-snapshot');
+export function installBrokerConfigSnapshot(snapshot) {
+    brokerSnapshotState[brokerSnapshotKey] = snapshot;
+}
+export function brokerConfigSnapshot() {
+    return brokerSnapshotState[brokerSnapshotKey];
+}
+export function readConfig(scope) {
+    const snapshot = brokerSnapshotState[brokerSnapshotKey];
+    if (snapshot) {
+        if (scope !== 'user')
+            throw new Error(`broker config snapshot has no ${scope} scope`);
+        return snapshot.user;
+    }
+    const root = scopeRoot(scope);
+    return root ? readConfigAtRoot(root) : defaultScopeConfig();
+}
+export function readConfigAtRoot(root) { const existing = readRawAtRoot(root); return existing ? mergeConfig(existing) : defaultScopeConfig(); }
+export function readState(scope) {
+    const root = scopeRoot(scope);
+    if (!root)
+        return defaultScopeState();
+    try {
+        return readBookkeeping(settingsOwnerForRoot(root));
+    }
+    catch (error) {
+        if (scope === 'project' && !existsSync(root))
+            return defaultScopeState();
+        throw error;
+    }
+}
+export class InvalidRawSettingsError extends Error {
+    constructor(cause) {
+        super(`settings cannot be merged: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.name = 'InvalidRawSettingsError';
+    }
+}
+function rawSettingsOwnerForTarget(target) {
+    if (target.scope === 'user')
+        return settingsOwnerForRoot(userScopeRoot());
+    if (!listProfiles().some((profile) => profile.profileId === target.profileId)) {
+        throw notFound(`profile not found: ${target.profileId}`, { received: target.profileId, next: 'Run `crtr profile list` to see available profiles.' });
+    }
+    return settingsOwnerForRoot(profileMemoryDir(target.profileId));
+}
+export function readRawSettingsForTarget(target) {
+    return readRawSettingsWithRevision(rawSettingsOwnerForTarget(target));
+}
+export function replaceRawSettingsForTarget(target, next, ifRevision) {
+    return replaceRawSettings(rawSettingsOwnerForTarget(target), next, ifRevision, (settings) => {
+        try {
+            mergeConfig(settings);
+        }
+        catch (error) {
+            throw new InvalidRawSettingsError(error);
+        }
+    });
+}
+export function updateRawConfigAtomically(scope, mutate) { const root = requireScopeRoot(scope); return mutateRawAtRoot(root, (latest) => { const next = mutate(latest); return { value: next, next }; }); }
+export function writeConfig(scope, config) { writeRawAtRoot(requireScopeRoot(scope), config); }
+export function writeRawConfig(scope, config) { writeRawAtRoot(requireScopeRoot(scope), config); }
+export function writeState(scope, state) { const root = requireScopeRoot(scope); writeBookkeeping(settingsOwnerForRoot(root), state); }
+export function ensureScopeInitialized(scope, root) {
+    if (scope === 'project') {
+        try {
+            mkdirSync(root);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST' || !statSync(root).isDirectory())
+                throw error;
+        }
+    }
+    else
+        ensureDir(root);
+    const owner = scope === 'user' ? settingsOwnerForRoot(userScopeRoot()) : settingsOwnerForRoot(root);
+    initializeFreshScopedStore({ kind: owner.kind === 'user' ? 'user' : 'project', root: owner.store.root });
+    if (owner.kind === 'project' && readJsonIfExists(configPathFor(owner.root)) === null) {
+        // A project config holds only what the project overrides. Seeding it with
+        // the full default document would make every default (kinds, display
+        // toggles, auto_update) a project-level override that silently shadows the
+        // user's own settings for every directory beneath it — reads default-fill
+        // missing keys from the running build, so a sparse file loses nothing.
+        writeRawAtRoot(owner.root, { schema_version: defaultScopeConfig().schema_version });
+    }
+}
+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;
+}
+const ATTACH_PANE_BINDING_IDS = new Set(BINDING_CATALOG.filter(isAttachPaneBinding).map((definition) => definition.id));
+/** Normalize the user-owned list of attach actions allowed to bridge through an
+ * occupied tmux root binding. Unknown and non-attach ids have no effect. */
+export function normalizeTmuxPassthrough(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return [...new Set(raw.filter((id) => typeof id === 'string' && BINDING_IDS.has(id) && ATTACH_PANE_BINDING_IDS.has(id)))];
+}
+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;
+}
+function validStrength(value) {
+    return value === 'ultra' || value === 'strong' || value === 'medium' || value === 'light';
+}
+const MODEL_STRENGTHS = ['ultra', 'strong', 'medium', 'light'];
+function routeRecord() {
+    return Object.create(null);
+}
+function setRouteRecord(record, routeId, value) {
+    Object.defineProperty(record, routeId, { value, writable: true, enumerable: true, configurable: true });
+}
+function copyRouteRecord(record) {
+    const copy = routeRecord();
+    for (const [routeId, value] of Object.entries(record ?? {}))
+        setRouteRecord(copy, routeId, value);
+    return copy;
+}
+function routeInvalid(routeId, rule) {
+    emitEvent({ level: 'warn', event: 'config.model_routes.invalid', fields: { route_id: routeId, rule } });
+}
+/** Overlay raw route patches first so a higher scope may replace one cell of a
+ * complete lower route. Completeness belongs to the resulting effective route,
+ * never an individual raw scope patch. */
+function mergeModelRoutePatches(raw, base = {}) {
+    const out = copyRouteRecord(base);
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return out;
+    for (const [routeId, value] of Object.entries(raw)) {
+        if (routeId.trim() === '') {
+            routeInvalid(routeId, 'route id must be a non-empty string');
+            continue;
+        }
+        if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+            routeInvalid(routeId, 'route must be an object');
+            continue;
+        }
+        const patch = value;
+        const current = out[routeId];
+        const route = { ...current };
+        let rule;
+        for (const field of ['family', 'credentialSource', 'providerId']) {
+            const candidate = patch[field];
+            if (candidate === undefined)
+                continue;
+            if (typeof candidate !== 'string' || candidate.trim() === '') {
+                rule = `${field} must be a non-empty string`;
+                break;
+            }
+            route[field] = candidate;
+        }
+        if (rule === undefined && patch.models !== undefined) {
+            if (patch.models === null || typeof patch.models !== 'object' || Array.isArray(patch.models))
+                rule = 'models must be an object';
+            else {
+                const models = { ...current?.models };
+                for (const [strength, spec] of Object.entries(patch.models)) {
+                    if (!validStrength(strength)) {
+                        rule = `models.${strength} is not a model strength`;
+                        break;
+                    }
+                    if (typeof spec !== 'string' || spec.trim() === '') {
+                        rule = `models.${strength} must be a non-empty provider/id ref`;
+                        break;
+                    }
+                    const slash = spec.indexOf('/');
+                    if (slash <= 0 || slash === spec.length - 1) {
+                        rule = `models.${strength} must be provider/id`;
+                        break;
+                    }
+                    models[strength] = spec;
+                }
+                route.models = models;
+            }
+        }
+        if (rule === undefined && route.models !== undefined && route.providerId !== undefined) {
+            for (const [strength, spec] of Object.entries(route.models)) {
+                if (spec.slice(0, spec.indexOf('/')) !== route.providerId) {
+                    rule = `models.${strength} provider prefix must equal providerId`;
+                    break;
+                }
+            }
+        }
+        if (rule !== undefined) {
+            routeInvalid(routeId, rule);
+            continue;
+        }
+        setRouteRecord(out, routeId, route);
+    }
+    return out;
+}
+/** Resolve complete routes after every scope has overlaid its sparse raw patch.
+ * Sparse standalone routes are read for one compatibility release only: they
+ * retain their historical candidate behavior, emit a repair warning, and never
+ * gain invented cells. New writes cannot create them. */
+function resolveModelRoutes(routes) {
+    const complete = routeRecord();
+    const legacy = routeRecord();
+    for (const [routeId, route] of Object.entries(routes)) {
+        if (route.family === undefined || route.credentialSource === undefined || route.providerId === undefined || route.models === undefined) {
+            routeInvalid(routeId, 'route must include family, credentialSource, providerId, and models');
+            continue;
+        }
+        const missing = MODEL_STRENGTHS.filter((strength) => route.models[strength] === undefined);
+        if (missing.length > 0) {
+            routeInvalid(routeId, `incomplete route; missing strengths: ${missing.join(', ')}`);
+            setRouteRecord(legacy, routeId, { family: route.family, credentialSource: route.credentialSource, providerId: route.providerId, models: route.models });
+            continue;
+        }
+        setRouteRecord(complete, routeId, {
+            family: route.family,
+            credentialSource: route.credentialSource,
+            providerId: route.providerId,
+            models: route.models,
+        });
+    }
+    return { complete, legacy };
+}
+function assertCompleteModelRoute(routeId, route) {
+    if (routeId.trim() === '')
+        throw new Error('model route id must be a non-empty string');
+    for (const field of ['family', 'credentialSource', 'providerId']) {
+        if (typeof route[field] !== 'string' || route[field].trim() === '')
+            throw new Error(`model route "${routeId}" ${field} must be a non-empty string`);
+    }
+    const missing = MODEL_STRENGTHS.filter((strength) => route.models?.[strength] === undefined);
+    if (missing.length > 0)
+        throw new Error(`model route "${routeId}" is incomplete; missing strengths: ${missing.join(', ')}`);
+    for (const strength of MODEL_STRENGTHS) {
+        const spec = route.models[strength];
+        if (typeof spec !== 'string' || spec.trim() === '')
+            throw new Error(`model route "${routeId}" models.${strength} must be a non-empty provider/id ref`);
+        const slash = spec.indexOf('/');
+        if (slash <= 0 || slash === spec.length - 1)
+            throw new Error(`model route "${routeId}" models.${strength} must be provider/id`);
+        if (spec.slice(0, slash) !== route.providerId)
+            throw new Error(`model route "${routeId}" models.${strength} provider prefix must equal providerId`);
+    }
+}
+function mergeModelRouting(raw, base) {
+    if (raw === undefined)
+        return base;
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return base;
+    const value = raw;
+    const strings = (items) => Array.isArray(items) && items.every((item) => typeof item === 'string' && item.trim() !== '') ? [...items] : undefined;
+    const strengths = Array.isArray(value.strengthFallback) && value.strengthFallback.every((item) => validStrength(item)) ? [...value.strengthFallback] : undefined;
+    return {
+        ...(strings(value.credentialSourceOrder) !== undefined ? { credentialSourceOrder: strings(value.credentialSourceOrder) } : {}),
+        ...(strings(value.familyOrder) !== undefined ? { familyOrder: strings(value.familyOrder) } : {}),
+        ...(strengths !== undefined ? { strengthFallback: strengths } : {}),
+    };
+}
+/** 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])] };
+}
+/** Per-provider options, merged SHALLOWLY per provider id so a nearer scope
+ *  that sets one option does not erase a sibling option from a farther scope. */
+function mergeProviderOptions(raw, base = {}) {
+    const merged = {};
+    for (const [providerId, options] of Object.entries(base))
+        merged[providerId] = { ...options };
+    if (raw !== null && typeof raw === 'object') {
+        for (const [providerId, options] of Object.entries(raw)) {
+            if (options === null || typeof options !== 'object')
+                continue;
+            const next = { ...merged[providerId] };
+            const fastMode = options.fastMode;
+            if (typeof fastMode === 'boolean')
+                next.fastMode = fastMode;
+            merged[providerId] = next;
+        }
+    }
+    return merged;
+}
+/** The one bare-command-name rule, shared by the read path (`normalizeBin`)
+ *  and the strict install gate (`invalidPluginBinReasons`): a name a shell can
+ *  invoke verbatim and a filesystem can hold as a single symlink entry — no
+ *  separator, no leading dot, no whitespace, no quoting ever required. */
+const BIN_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** Bare names crouter owns on every node's PATH. A contribution may not take
+ *  one: shadowing the CLI a node drives its own canvas with breaks the runtime
+ *  contract rather than extending it. */
+const RESERVED_BIN_NAMES = new Set(['crtr', 'crtrd']);
+/** The one bare-command-name validator shared by `bin` and plugin `requires`.
+ *  `bin` alone reserves crouter's own commands; a plugin may require any safe
+ *  executable name because it does not contribute or shadow that command. */
+function bareCommandNameIssue(name, field) {
+    if (field === 'bin' && RESERVED_BIN_NAMES.has(name))
+        return `${field}.${name} is reserved by crouter — pick another bare command name`;
+    if (!BIN_NAME_PATTERN.test(name))
+        return `${field}.${name} is not a safe bare command name (expected ${BIN_NAME_PATTERN.source})`;
+    return undefined;
+}
+/** Validate raw `bin` declaration shape without touching the filesystem.
+ *  Install uses these findings as a hard gate for plugin manifests; scope
+ *  resolution reports them through `crtr sys doctor` and continues. */
+export function binDeclarationIssues(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return [{ name: 'bin', message: 'bin must be a JSON object mapping bare command name to a relative path' }];
+    }
+    const issues = [];
+    for (const [name, target] of Object.entries(raw)) {
+        const nameIssue = bareCommandNameIssue(name, 'bin');
+        if (nameIssue !== undefined)
+            issues.push({ name, message: nameIssue });
+        if (typeof target !== 'string' || target.trim() === '') {
+            issues.push({ name, message: `bin.${name} must be a non-empty relative path to an executable inside the contributor root` });
+        }
+    }
+    return issues;
+}
+/** Normalize one raw `bin` block (a scope `config.json`'s or a plugin
+ *  manifest's) to name → root-relative path. Invalid entries never become
+ *  commands; `binDeclarationIssues` keeps them visible to Doctor. */
+export function normalizeBin(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [name, target] of Object.entries(raw)) {
+        if (bareCommandNameIssue(name, 'bin') !== undefined)
+            continue;
+        if (typeof target !== 'string' || target.trim() === '')
+            continue;
+        out[name] = target;
+    }
+    return out;
+}
+const HUMAN_ACTION_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+/** Validate `humanActions` declaration shape without touching the filesystem.
+ * Filesystem checks happen only when resolving an action or running Doctor. */
+export function humanActionDeclarationIssues(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return [{ name: 'humanActions', reason: 'humanActions must be a JSON object mapping action names to {argv, cwd}', block: true }];
+    }
+    const issues = [];
+    for (const [name, value] of Object.entries(raw)) {
+        const reasons = [];
+        if (!HUMAN_ACTION_NAME_PATTERN.test(name)) {
+            reasons.push(`action name must match ${HUMAN_ACTION_NAME_PATTERN.source}`);
+        }
+        if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+            reasons.push('action must be an object with argv and cwd');
+        }
+        else {
+            const action = value;
+            const extras = Object.keys(action).filter((key) => key !== 'argv' && key !== 'cwd');
+            if (extras.length > 0)
+                reasons.push(`action has unsupported field${extras.length === 1 ? '' : 's'}: ${extras.join(', ')}`);
+            if (!Array.isArray(action.argv) || action.argv.length === 0 || !action.argv.every((arg) => typeof arg === 'string' && arg.length > 0)) {
+                reasons.push('argv must be a non-empty array of non-empty strings');
+            }
+            if (typeof action.cwd !== 'string' || action.cwd.length === 0) {
+                reasons.push('cwd is required and must be a non-empty string');
+            }
+        }
+        if (reasons.length > 0)
+            issues.push({ name, reason: reasons.join('; ') });
+    }
+    return issues;
+}
+/** Normalize valid action declarations for scope-local config inspection.
+ * Invalid entries remain available through raw reads so resolution and Doctor
+ * can report them rather than silently treating them as absent. */
+export function normalizeHumanActions(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const invalid = new Set(humanActionDeclarationIssues(raw).map((issue) => issue.name));
+    const out = {};
+    for (const [name, value] of Object.entries(raw)) {
+        if (invalid.has(name))
+            continue;
+        const action = value;
+        out[name] = { argv: [...action.argv], cwd: action.cwd };
+    }
+    return out;
+}
+/** STRICT install-time validation for a plugin-declared `bin` block. Target
+ *  filesystem state is checked later by Doctor because it can change after
+ *  install. */
+export function invalidPluginBinReasons(raw) {
+    return binDeclarationIssues(raw).map((issue) => issue.message);
+}
+/** Normalize a plugin manifest's advisory executable requirements. Invalid
+ *  declarations stay out of the read path; source installs reject them through
+ *  `invalidPluginRequiresReasons`. */
+export function normalizeRequires(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [name, hint] of Object.entries(raw)) {
+        if (bareCommandNameIssue(name, 'requires') !== undefined)
+            continue;
+        if (typeof hint !== 'string' || hint.trim() === '' || /[\r\n]/.test(hint))
+            continue;
+        out[name] = hint;
+    }
+    return out;
+}
+/** STRICT install-time validation for a plugin's advisory `requires` block.
+ *  A missing executable is advisory; only malformed declarations fail install. */
+export function invalidPluginRequiresReasons(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return ['requires must be a JSON object mapping a bare executable name to a one-line install hint'];
+    }
+    const reasons = [];
+    for (const [name, hint] of Object.entries(raw)) {
+        const nameIssue = bareCommandNameIssue(name, 'requires');
+        if (nameIssue !== undefined)
+            reasons.push(nameIssue);
+        if (typeof hint !== 'string' || hint.trim() === '') {
+            reasons.push(`requires.${name} must be a non-empty one-line install hint`);
+        }
+        else if (/[\r\n]/.test(hint)) {
+            reasons.push(`requires.${name} must be a one-line install hint`);
+        }
+    }
+    return reasons;
+}
+/** Collect the valid `KindConfig` fields of one raw `kinds.<name>` entry —
+ *  every field is optional here, `whenToUse` included; mistyped fields are
+ *  dropped, never thrown (an invalid field in config.json must not break
+ *  config parsing for every other kind — the loud gate is install time, see
+ *  `invalidPluginKindsReasons`). Returns null when no valid field is present.
+ *  Whether `whenToUse` is REQUIRED is `mergeKinds`'s call: only an entry that
+ *  introduces a kind no lower layer defines needs one. */
+function normalizeKindFields(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    const out = {};
+    if (typeof r.whenToUse === 'string' && r.whenToUse.trim() !== '')
+        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 Object.keys(out).length > 0 ? out : null;
+}
+/** Merge a raw `kinds` block over `base` (defaulting to the builtin registry):
+ *  invalid entries are dropped, never thrown. Mirrors `mergeModelLadders`'s
+ *  layer-over-defaults shape so a config layer can add or override a single
+ *  kind without restating the whole registry. One rule, no entry shapes:
+ *   - A kind some lower layer already defines: the entry FIELD-MERGES over it
+ *     — any subset of fields, `whenToUse` included, so overriding just the
+ *     spawn-menu guidance of a builtin kind never strips its model tier
+ *     (the sparse-override shape `persistDefaultKindModel` writes).
+ *   - A NEW kind: the entry defines it and must carry `whenToUse` (a kind
+ *     with no spawn-menu gloss is meaningless); dropped otherwise.
+ *  Deliberately NOT expressible: wholly replacing a lower layer's kind — a
+ *  field can be overridden but never removed by omission. */
+function mergeKinds(raw, base = defaultKindsConfig()) {
+    const out = { ...base };
+    if (raw !== null && typeof raw === 'object') {
+        for (const [kind, value] of Object.entries(raw)) {
+            const fields = normalizeKindFields(value);
+            if (fields === null)
+                continue;
+            const existing = out[kind];
+            if (existing !== undefined) {
+                out[kind] = { ...existing, ...fields };
+            }
+            else if (fields.whenToUse !== undefined) {
+                out[kind] = fields;
+            }
+        }
+    }
+    return out;
+}
+/** Layer the `kinds` contributions of every ENABLED plugin installed under
+ *  `scopeRootPath` over `base`, plugin name-sorted for determinism (directory
+ *  listing order is filesystem-dependent). Each plugin's block goes through
+ *  the same `mergeKinds` a scope `config.json` does — full entries add or
+ *  shadow, patches field-merge, invalid entries drop. Called by
+ *  `readMergedLaunchConfig` BELOW the host scope's own raw `kinds`, so the
+ *  scope's config.json always overrides its plugins. */
+function layerPluginKinds(scope, scopeRootPath, base) {
+    if (scopeRootPath === null)
+        return base;
+    const plugins = listInstalledPluginsInRoot(scope, scopeRootPath)
+        .filter((p) => p.enabled && p.manifest.kinds !== undefined)
+        .sort((a, b) => a.name.localeCompare(b.name));
+    let out = base;
+    for (const plugin of plugins)
+        out = mergeKinds(plugin.manifest.kinds, out);
+    return out;
+}
+/** The ACTIVE page-component catalog every authoring, validation, daemon,
+ *  inbox, and TUI consumer resolves: the user scope's own `page_components`
+ *  entries plus the contributions of every ENABLED plugin installed under that
+ *  same root, plugin name-sorted for determinism (directory listing order is
+ *  filesystem-dependent). Installing, updating, or removing a plugin therefore
+ *  adds, changes, or retires its components with no config edit.
+ *
+ *  User scope only, deliberately: this catalog is read from the daemon, the
+ *  CLI, and the inbox TUI, whose ambient cwds differ, and a page slot whose
+ *  validity depended on which directory a process happened to start in would
+ *  validate in one surface and fail in another. `page_components` has always
+ *  been a user-scope block (`readConfig('user')`); its plugin channel keeps
+ *  that boundary.
+ *
+ *  Throws on a duplicate kind or derived JSX tag across sources, and on a
+ *  plugin whose block is malformed — matching the existing catalog validation
+ *  style, where a bad `page_components` block already fails config read rather
+ *  than silently dropping a component the product expects to be authorable.
+ *  Install-time validation (`invalidPageComponentsReasons`) is what keeps a
+ *  malformed block from ever reaching this path. */
+export function resolvePageComponents() {
+    const layers = [{ origin: 'config.json', components: readConfig('user').page_components }];
+    const root = scopeRoot('user');
+    if (root !== null) {
+        const plugins = listInstalledPluginsInRoot('user', root)
+            .filter((plugin) => plugin.enabled && plugin.manifest.page_components !== undefined)
+            .sort((a, b) => a.name.localeCompare(b.name));
+        for (const plugin of plugins) {
+            const label = `plugin "${plugin.name}" page_components`;
+            layers.push({ origin: `plugin "${plugin.name}"`, components: normalizePageComponents(plugin.manifest.page_components, label) });
+        }
+    }
+    return mergePageComponentLayers(layers);
+}
+const KIND_CONFIG_KEYS = new Set(['whenToUse', 'model', 'orchestratorModel', 'tools', 'extensions', 'availableTo']);
+/** STRICT install-time validation for a plugin-declared `kinds` block —
+ *  the loud counterpart to `mergeKinds`'s silent read-time dropping. Read
+ *  paths must never throw on bad config, but an INSTALL delivering a bad
+ *  block must fail the install, not ship a kind that silently never
+ *  registers. Returns one human-readable reason per defect; empty = valid.
+ *  Used by the archive-bundle validator (`command-plugins/bundle.ts`) on
+ *  `bundle.json`'s optional `kinds` member. */
+export function invalidPluginKindsReasons(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return ['kinds must be a JSON object keyed by kind name'];
+    }
+    const reasons = [];
+    const isStringArray = (v) => Array.isArray(v) && v.every((item) => typeof item === 'string');
+    for (const [kind, value] of Object.entries(raw)) {
+        if (kind.trim() === '') {
+            reasons.push('kinds contains an empty kind name');
+            continue;
+        }
+        if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+            reasons.push(`kinds.${kind} must be a JSON object`);
+            continue;
+        }
+        const entry = value;
+        for (const key of Object.keys(entry)) {
+            if (!KIND_CONFIG_KEYS.has(key))
+                reasons.push(`kinds.${kind}.${key} is not a KindConfig field (expected one of: ${[...KIND_CONFIG_KEYS].join(', ')})`);
+        }
+        if (entry['whenToUse'] !== undefined && (typeof entry['whenToUse'] !== 'string' || entry['whenToUse'].trim() === '')) {
+            reasons.push(`kinds.${kind}.whenToUse must be a non-empty string`);
+        }
+        for (const field of ['model', 'orchestratorModel']) {
+            if (entry[field] !== undefined && (typeof entry[field] !== 'string' || entry[field].trim() === '')) {
+                reasons.push(`kinds.${kind}.${field} must be a non-empty string`);
+            }
+        }
+        for (const field of ['tools', 'extensions', 'availableTo']) {
+            if (entry[field] !== undefined && !isStringArray(entry[field])) {
+                reasons.push(`kinds.${kind}.${field} must be an array of strings`);
+            }
+        }
+        if (normalizeKindFields(value) === null) {
+            reasons.push(`kinds.${kind} has no valid KindConfig field — an entry must set at least one of: ${[...KIND_CONFIG_KEYS].join(', ')} (whenToUse is required when the kind exists in no lower layer)`);
+        }
+    }
+    return reasons;
+}
+/** Validate one raw `remoteCanvas.targets.<name>` entry, or drop it (return
+ *  null) rather than throwing — same rule `normalizeKindFields` 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 mergeLifecycle(raw, defaults) {
+    const partial = raw !== null && typeof raw === 'object'
+        ? raw
+        : {};
+    return { unattendedParkMs: normalizePositiveInteger(partial.unattendedParkMs, defaults.unattendedParkMs) };
+}
+function normalizeWhipMessages(raw) {
+    if (!Array.isArray(raw))
+        return [...DEFAULT_WHIP_MESSAGES];
+    const messages = raw.filter((message) => typeof message === 'string' && message.trim() !== '').map((message) => message.trim());
+    return messages.length > 0 ? messages : [...DEFAULT_WHIP_MESSAGES];
+}
+function mergeApi(raw, defaults) {
+    if (raw === null || typeof raw !== 'object')
+        return { ...defaults };
+    const tcp = raw.tcp;
+    return { tcp: typeof tcp === 'string' ? tcp : defaults.tcp };
+}
+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 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 auto_open_child_viewers = typeof partial.auto_open_child_viewers === 'boolean'
+        ? partial.auto_open_child_viewers
+        : defaults.auto_open_child_viewers;
+    const brokerThresholds = mergeBrokerThresholds(partial.brokerThresholds, defaults.brokerThresholds);
+    const lifecycle = mergeLifecycle(partial.lifecycle, defaults.lifecycle);
+    const completion_bell = typeof partial.completion_bell === 'boolean' ? partial.completion_bell : defaults.completion_bell;
+    const working_gerunds = partial.working_gerunds === undefined
+        ? [...defaults.working_gerunds]
+        : normalizeWorkingGerunds(partial.working_gerunds);
+    const whip_mode = typeof partial.whip_mode === 'boolean' ? partial.whip_mode : defaults.whip_mode;
+    const page_components = normalizePageComponents(partial.page_components);
+    const page_surface = typeof partial.page_surface === 'boolean' ? partial.page_surface : defaults.page_surface;
+    const whip_messages = normalizeWhipMessages(partial.whip_messages);
+    const whip_message_mode = WHIP_MESSAGE_MODES.includes(partial.whip_message_mode)
+        ? partial.whip_message_mode
+        : defaults.whip_message_mode;
+    const mouse_mode_default = MOUSE_MODE_DEFAULTS.includes(partial.mouse_mode_default)
+        ? partial.mouse_mode_default
+        : defaults.mouse_mode_default;
+    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 bash_tool_purpose = typeof partial.bash_tool_purpose === 'boolean' ? partial.bash_tool_purpose : defaults.bash_tool_purpose;
+    const fold_finished_tools = typeof partial.fold_finished_tools === 'boolean' ? partial.fold_finished_tools : defaults.fold_finished_tools;
+    const summarize_tool_calls = typeof partial.summarize_tool_calls === 'boolean' ? partial.summarize_tool_calls : defaults.summarize_tool_calls;
+    const detailed_tool_recaps = typeof partial.detailed_tool_recaps === 'boolean' ? partial.detailed_tool_recaps : defaults.detailed_tool_recaps;
+    const keybindings = normalizeKeybindings(partial.keybindings);
+    const tmux_passthrough = normalizeTmuxPassthrough(partial.tmux_passthrough);
+    const modelLadders = mergeModelLadders(partial.modelLadders);
+    const providerOptions = mergeProviderOptions(partial.providerOptions, defaults.providerOptions);
+    const routes = resolveModelRoutes(mergeModelRoutePatches(partial.modelRoutes));
+    const modelRoutes = routes.complete;
+    const modelRouting = mergeModelRouting(partial.modelRouting, undefined);
+    const kinds = mergeKinds(partial.kinds);
+    const remoteCanvas = mergeRemoteCanvas(partial.remoteCanvas);
+    const api = mergeApi(partial.api, defaults.api);
+    const paths = partial.paths;
+    if (paths?.user_files !== undefined && (typeof paths.user_files !== 'string' || !paths.user_files.startsWith('/'))) {
+        throw new Error('paths.user_files must be an absolute path');
+    }
+    const store = partial.store;
+    const runtime = partial.runtime;
+    if (runtime?.person_uids !== undefined && (!Array.isArray(runtime.person_uids)
+        || !runtime.person_uids.every((uid) => Number.isSafeInteger(uid) && uid >= 0))) {
+        throw new Error('runtime.person_uids must be an array of nonnegative integer uids');
+    }
+    const spawnEnv = mergeSpawnEnv(partial.spawnEnv, defaults.spawnEnv?.allow);
+    const bin = normalizeBin(partial.bin);
+    const humanActions = normalizeHumanActions(partial.humanActions);
+    return { bin, humanActions, schema_version, marketplaces, plugins, auto_update, max_panes_per_window, auto_open_child_viewers, brokerThresholds, lifecycle, completion_bell, working_gerunds, whip_mode, page_components, page_surface, whip_messages, whip_message_mode, mouse_mode_default, live_cycles, condensed_history, bash_tool_purpose, fold_finished_tools, summarize_tool_calls, detailed_tool_recaps, keybindings, tmux_passthrough, modelLadders, providerOptions, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(Object.keys(routes.legacy).length > 0 ? { legacyModelRoutes: routes.legacy } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), kinds, remoteCanvas, api, ...(paths ? { paths } : {}), ...(store ? { store } : {}), ...(runtime ? { runtime } : {}), 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 readRawAtRoot(root);
+}
+export function readRawScopeConfig(scope) {
+    const root = scopeRoot(scope);
+    return root ? readRawConfigAtRoot(root) : null;
+}
+/** Raw SQL-backed profile settings, or null when the profile is absent. */
+function readRawProfileConfig(profileId) {
+    if (profileId === null || profileId === '')
+        return null;
+    try {
+        return readRawAtRoot(profileMemoryDir(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();
+    // A root with no config.json still contributes: its installed plugins may
+    // declare kinds, so the ROOT rides along and `raw` stays null.
+    return farthestFirst.map((root) => ({ root, raw: readRawAtRoot(root) }));
+}
+/** Merge launch knobs (`kinds`, `modelLadders`) across scopes in
+ *  project stack > profile > user > builtin precedence — the same precedence
+ *  order used for memory resolution. For `kinds` only, each plugin-bearing
+ *  scope (user, each project root) additionally layers its enabled plugins'
+ *  manifest `kinds` blocks directly BELOW that scope's own raw config — see
+ *  `layerPluginKinds`. 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 = envProfileId() || null) {
+    const snapshot = brokerSnapshotState[brokerSnapshotKey];
+    if (snapshot)
+        return snapshot.launch;
+    const defaults = defaultScopeConfig();
+    const userRaw = readRawScopeConfig('user');
+    const profileRaw = readRawProfileConfig(targetProfileId);
+    const projectLayersFarthestFirst = readRawProjectScopeConfigs(targetCwd, targetProfileId);
+    // Kinds layer per scope as: that scope's enabled PLUGINS first, then the
+    // scope's own raw config — so a plugin can add or shadow a kind (registry
+    // entry in its manifest + gated persona docs in its memory tree) and the
+    // scope's config.json still overrides its plugins. Other launch knobs
+    // (ladders/routes/spawnEnv) have no plugin channel.
+    let kinds = mergeKinds(userRaw?.kinds, layerPluginKinds('user', scopeRoot('user'), defaults.kinds));
+    let modelLadders = mergeModelLadders(userRaw?.modelLadders, defaults.modelLadders);
+    let providerOptions = mergeProviderOptions(userRaw?.providerOptions, defaults.providerOptions);
+    let modelRoutePatches = mergeModelRoutePatches(userRaw?.modelRoutes);
+    let modelRouting = mergeModelRouting(userRaw?.modelRouting, undefined);
+    let spawnEnv = mergeSpawnEnv(userRaw?.spawnEnv, defaults.spawnEnv?.allow);
+    if (profileRaw !== null) {
+        kinds = mergeKinds(profileRaw.kinds, kinds);
+        modelLadders = mergeModelLadders(profileRaw.modelLadders, modelLadders);
+        providerOptions = mergeProviderOptions(profileRaw.providerOptions, providerOptions);
+        modelRoutePatches = mergeModelRoutePatches(profileRaw.modelRoutes, modelRoutePatches);
+        modelRouting = mergeModelRouting(profileRaw.modelRouting, modelRouting);
+        spawnEnv = mergeSpawnEnv(profileRaw.spawnEnv, spawnEnv.allow);
+    }
+    for (const { root, raw } of projectLayersFarthestFirst) {
+        kinds = mergeKinds(raw?.kinds, layerPluginKinds('project', root, kinds));
+        if (raw === null)
+            continue;
+        modelLadders = mergeModelLadders(raw.modelLadders, modelLadders);
+        providerOptions = mergeProviderOptions(raw.providerOptions, providerOptions);
+        modelRoutePatches = mergeModelRoutePatches(raw.modelRoutes, modelRoutePatches);
+        modelRouting = mergeModelRouting(raw.modelRouting, modelRouting);
+        spawnEnv = mergeSpawnEnv(raw.spawnEnv, spawnEnv.allow);
+    }
+    const routes = resolveModelRoutes(modelRoutePatches);
+    return {
+        kinds,
+        modelLadders,
+        providerOptions,
+        ...(Object.keys(routes.complete).length > 0 ? { modelRoutes: routes.complete } : {}),
+        ...(Object.keys(routes.legacy).length > 0 ? { legacyModelRoutes: routes.legacy } : {}),
+        ...(modelRouting !== undefined ? { modelRouting } : {}),
+        spawnEnv,
+    };
+}
+/** The effective `KindConfig` for one full kind string (top-level, e.g.
+ *  `developer`, or sub-kind, e.g. `audit/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 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. `audit/security` defaults to
+ *  `['audit']`) includes `kind` or `'*'`. The single source both `sys
+ *  prompt-review --list`'s `subPersonas` metadata and the live sub-persona
+ *  spawn-menu splice (`core/substrate/delivery/render-boot.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));
+}
+/** 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` never 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 mutateConfigAtRoot(root, mutate) {
+    return mutateRawAtRoot(root, (raw) => {
+        const baseline = mergeConfig(raw);
+        const cfg = mergeConfig(raw);
+        mutate(cfg);
+        const partial = { ...raw };
+        for (const key of SCOPE_CONFIG_KEYS)
+            if (key !== 'modelLadders' && !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;
+        return { value: cfg, next: partial };
+    });
+}
+/** 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) {
+    mutateRawAtRoot(root, (raw) => { const current = (raw.modelLadders ?? {}); const next = { ...current }; if (patch.defaultProvider !== undefined)
+        next.defaultProvider = patch.defaultProvider; for (const provider of ['anthropic', 'openai'])
+        if (patch[provider] !== undefined)
+            next[provider] = { ...(current[provider] ?? {}), ...patch[provider] }; return { value: undefined, next: { ...raw, modelLadders: next } }; });
+}
+/** Persist one complete route at one exact config root. The route is the only
+ * raw route entry touched; unrelated routes and local ladder defaults remain
+ * absent. Pass `undefined` to remove this scope's entry, which resumes lower
+ * scope inheritance rather than introducing a tombstone. */
+export function persistModelRoute(root, routeId, route) {
+    if (route !== undefined)
+        assertCompleteModelRoute(routeId, route);
+    else if (routeId.trim() === '')
+        throw new Error('model route id must be a non-empty string');
+    mutateRawAtRoot(root, (raw) => { const routes = copyRouteRecord((raw.modelRoutes ?? {})); if (route === undefined)
+        delete routes[routeId];
+    else
+        setRouteRecord(routes, routeId, { ...route, models: { ...route.models } }); const next = { ...raw }; if (Object.keys(routes).length === 0)
+        delete next.modelRoutes;
+    else
+        next.modelRoutes = routes; return { value: undefined, 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 mutateConfigAtRoot(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';
+    mutateRawAtRoot(opts.root, (raw) => { const kinds = { ...(raw.kinds ?? {}), [opts.kind]: { ...(raw.kinds ?? {})[opts.kind], [field]: opts.model } }; return { value: undefined, next: { ...raw, kinds: kinds } }; });
+    return { path: configPathFor(opts.root), field };
+}
+export function updateState(scope, mutate) {
+    const s = readState(scope);
+    mutate(s);
+    writeState(scope, s);
+    return s;
+}