akm-cli 0.9.0-rc.1 → 0.9.0-rc.2

package/dist/core/config/config.js

@@ -4,11 +4,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import { ConfigError } from "../errors.js";
-import { backupExistingConfig, parseConfigText, withConfigLock, writeConfigAtomic } from "./config-io.js";
-import { CURRENT_CONFIG_VERSION, compareConfigVersion, migrateConfigShape } from "./config-migration.js";
-import { AkmConfigSchema } from "./config-schema.js";
+import { ensureMigrationBackupWithConfigLockHeld } from "../migration-backup.js";
+import { acquireConfigLock, backupExistingConfig, parseConfigText, readConfigText, withConfigLock, writeConfigAtomic, } from "./config-io.js";
+import { AkmConfigSchema, CURRENT_CONFIG_VERSION } from "./config-schema.js";
+import { deepMergeConfig } from "./deep-merge.js";
 export { stripJsonComments } from "./config-io.js";
-import { getCacheDir, getConfigPath } from "../paths.js";
+import { materializeLlmConnection, resolveLlmEngineUse } from "../../integrations/agent/engine-resolution.js";
+import { getConfigPath } from "../paths.js";
 import { warn } from "../warn.js";
 // Canonical harness-id source of truth (#565) — runtime value re-export.
 export { VALID_HARNESS_IDS } from "./config-types.js";
@@ -48,6 +50,7 @@ export function resolveBatchSize(configured, contextLength) {
 }
 // ── Defaults ────────────────────────────────────────────────────────────────
 export const DEFAULT_CONFIG = {
+    configVersion: "0.9.0",
     semanticSearchMode: "auto",
     registries: [
         { url: "https://raw.githubusercontent.com/itlackey/akm-registry/main/index.json", name: "akm-registry" },
@@ -70,9 +73,12 @@ export function loadUserConfig() {
     try {
         stat = fs.statSync(configPath);
     }
-    catch {
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw new ConfigError(`Unable to read config at ${configPath}: ${err instanceof Error ? err.message : String(err)}`, "INVALID_CONFIG_FILE");
+        }
         cachedConfig = undefined;
-        return applyRuntimeEnvApiKeys({ ...DEFAULT_CONFIG });
+        return { ...DEFAULT_CONFIG };
     }
     // Cache key: mtimeMs + size. Tests that write rapidly back-to-back inside
     // the mtime resolution window MUST call resetConfigCache() between writes —
@@ -87,15 +93,14 @@ export function loadUserConfig() {
     try {
         text = fs.readFileSync(configPath, "utf8");
     }
-    catch {
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw new ConfigError(`Unable to read config at ${configPath}: ${err instanceof Error ? err.message : String(err)}`, "INVALID_CONFIG_FILE");
+        }
         cachedConfig = undefined;
-        return applyRuntimeEnvApiKeys({ ...DEFAULT_CONFIG });
+        return { ...DEFAULT_CONFIG };
     }
-    // Auto-migration: rewrite legacy shapes to disk on cache miss so the schema
-    // sees canonical input. AKM_NO_AUTO_MIGRATE=1 skips the disk rewrite (still
-    // applies in-memory).
-    text = maybeAutoMigrateConfigFile(configPath, text);
-    const finalConfig = applyRuntimeEnvApiKeys(parseAndValidate(text, configPath));
+    const finalConfig = parseAndValidateConfigText(text, configPath);
     // Re-stat after potential write-back so the cache key reflects the new mtime.
     let finalStat = stat;
     try {
@@ -113,26 +118,31 @@ export function loadUserConfig() {
     return finalConfig;
 }
 /**
- * Parse raw config text, run the legacy-shape migration
- * ({@link migrateConfigShape}), then validate via Zod
+ * Parse raw config text and validate via Zod.
  * ({@link AkmConfigSchema}). Returns the merged-with-defaults AkmConfig.
  *
  * The migration handles all one-time 0.7→0.8 transforms (legacy keys,
  * boolean→string coercions, openviking rename); the schema then validates
  * the canonical shape and throws on anything it doesn't recognise.
  */
-function parseAndValidate(text, sourcePath) {
-    // Migration absorbs 0.7→0.8 input transforms (semanticSearchMode bool→string,
-    // stashes[] → sources[], openviking removal); the schema then sees a
-    // canonical shape. Migration is idempotent on already-migrated input.
-    const migrated = migrateConfigShape(parseConfigText(text, sourcePath)).result;
-    const parsed = AkmConfigSchema.safeParse(migrated);
+export function parseAndValidateConfigText(text, sourcePath) {
+    const raw = parseConfigText(text, sourcePath);
+    if (raw.configVersion !== CURRENT_CONFIG_VERSION) {
+        throw new ConfigError(`Unsupported configVersion${sourcePath ? ` at ${sourcePath}` : ""}: expected "${CURRENT_CONFIG_VERSION}".`, "UNSUPPORTED_CONFIG_VERSION", "Recreate engines and improve.strategies manually for AKM 0.9.0; profile-based configuration is not translated automatically.");
+    }
+    const parsed = AkmConfigSchema.safeParse(raw);
     if (!parsed.success) {
         const lines = parsed.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
         const where = sourcePath ? ` at ${sourcePath}` : "";
         throw new ConfigError(`Invalid config${where}:\n${lines}`, "INVALID_CONFIG_FILE");
     }
-    return mergeLoadedConfig(DEFAULT_CONFIG, parsed.data);
+    const merged = deepMergeConfig(DEFAULT_CONFIG, parsed.data);
+    const finalResult = AkmConfigSchema.safeParse(merged);
+    if (!finalResult.success) {
+        const lines = finalResult.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+        throw new ConfigError(`Invalid merged config${sourcePath ? ` at ${sourcePath}` : ""}:\n${lines}`, "INVALID_CONFIG_FILE");
+    }
+    return finalResult.data;
 }
 export function getSources(config) {
     return config.sources ?? [];
@@ -140,144 +150,24 @@ export function getSources(config) {
 export function getEffectiveRegistries(config) {
     return config.registries ?? DEFAULT_CONFIG.registries ?? [];
 }
-/**
- * Resolve the name of the default LLM profile.
- *
- * Resolution order:
- *   1. `defaults.llm` — explicit pointer set by the user.
- *   2. A profile literally named `default` under `profiles.llm` — implicit
- *      fallback. The convention "name your default profile `default`" is
- *      what `akm setup` produces, so an unset `defaults.llm` next to a
- *      `profiles.llm.default` block is overwhelmingly a config-rewrite
- *      casualty (see [[project_akm_config_clobber_trap]]) rather than
- *      intent. Treating that shape as configured avoids the silent
- *      `getDefaultLlmConfig → undefined → pass-returns-zero` failure mode
- *      that produced 18h of no-op memory-inference runs on 2026-05-23.
- *
- * Returns `undefined` when neither path resolves to a profile name.
- */
-function resolveDefaultLlmProfileName(config) {
-    const explicit = config.defaults?.llm;
-    if (explicit)
-        return explicit;
-    if (config.profiles?.llm?.default)
-        return "default";
-    return undefined;
-}
-/**
- * Resolve the default LLM connection from `profiles.llm[defaults.llm]`.
- *
- * Throws {@link ConfigError} when no default profile can be resolved (neither
- * `defaults.llm` nor an implicit `profiles.llm.default`) or when the named
- * profile does not exist under `profiles.llm`. Use this in code paths that
- * must have an LLM configured (per-pass index calls, distill, consolidate,
- * etc).
- */
+/** Resolve and materialize the configured default LLM engine at dispatch time. */
 export function requireLlmConfig(config) {
-    const defaultName = resolveDefaultLlmProfileName(config);
-    if (!defaultName) {
-        throw new ConfigError("LLM is not configured. Run `akm setup` or set `defaults.llm` to a profile defined in `profiles.llm`.", "LLM_NOT_CONFIGURED");
-    }
-    const profile = config.profiles?.llm?.[defaultName];
-    if (!profile) {
-        throw new ConfigError(`LLM default profile "${defaultName}" not found in profiles.llm.`, "LLM_NOT_CONFIGURED", `Available profiles: ${Object.keys(config.profiles?.llm ?? {}).join(", ") || "none"}. Run \`akm setup\` to configure.`);
-    }
-    return profile;
+    return materializeLlmConnection(resolveLlmEngineUse(config, []));
 }
 /**
  * Like {@link requireLlmConfig} but returns `undefined` instead of throwing
  * when no LLM is configured. Use in code paths where the LLM is optional.
  */
 export function getDefaultLlmConfig(config) {
-    const defaultName = resolveDefaultLlmProfileName(config);
-    if (!defaultName)
-        return undefined;
-    return config.profiles?.llm?.[defaultName];
+    const resolved = resolveLlmEngineUse(config, [], { optional: true });
+    return resolved ? materializeLlmConnection(resolved) : undefined;
 }
 /**
- * Resolve the per-process config section for an improve process,
- * centralizing the deeply-nested lookup
- * `profile?.processes?.<name>` that was previously copy-pasted across the
- * improve command family (20+ call sites).
- *
- * When an `activeProfile` is supplied (the profile resolved for the current
- * `akm improve --profile <name>` run), its per-process override wins; otherwise
- * — and as a fallback when the active profile does not define the section — the
- * lookup falls back to the `"default"` improve profile from the on-disk config.
- * Callers that have not yet threaded the active profile pass only `config` and
- * get the historical default-profile behavior unchanged.
+ * Transitional internal accessor. It deliberately never consults a configured
+ * default strategy; callers must pass their already selected strategy.
  */
-export function getImproveProcessConfig(config, processName, activeProfile) {
-    const fromActiveProfile = activeProfile?.processes?.[processName];
-    if (fromActiveProfile !== undefined)
-        return fromActiveProfile;
-    return config.profiles?.improve?.default?.processes?.[processName];
-}
-/**
- * Run `migrateConfigShape` on the raw text and — unless `AKM_NO_AUTO_MIGRATE=1`
- * is set — persist the migrated result. Returns the (possibly migrated) text
- * for the caller to feed into `parseAndValidate`.
- *
- * If the on-disk config is newer than this binary's known version, the bytes
- * are left untouched (we won't silently strip fields on downgrade).
- */
-function maybeAutoMigrateConfigFile(configPath, text) {
-    let obj;
-    try {
-        obj = parseConfigText(text);
-    }
-    catch {
-        return text; // Malformed JSON — let parseAndValidate surface the error.
-    }
-    // Downgrade protection. Skip migration when the on-disk config is NEWER than
-    // this binary (=== 1), OR when it carries a configVersion we cannot order
-    // against ours (compareConfigVersion returns undefined for an unparseable
-    // value — e.g. one written by a newer/foreign akm). Migrating such a config
-    // could strip fields a newer binary added, a cross-version data-loss path.
-    //
-    // A MISSING configVersion (absent → undefined) is a legacy pre-versioning
-    // config that MUST still migrate, so the unparseable-skip is gated on the
-    // field being PRESENT (`onDiskVersion !== undefined`).
-    const onDiskVersion = obj.configVersion;
-    const versionOrder = compareConfigVersion(onDiskVersion, CURRENT_CONFIG_VERSION);
-    if (versionOrder === 1 || (onDiskVersion !== undefined && versionOrder === undefined)) {
-        return text;
-    }
-    const { changed, result } = migrateConfigShape(obj);
-    if (!changed)
-        return text;
-    const migratedText = `${JSON.stringify(result, null, 2)}\n`;
-    if (process.env.AKM_NO_AUTO_MIGRATE === "1")
-        return migratedText;
-    try {
-        withConfigLock(() => {
-            backupExistingConfig(configPath);
-            writeConfigAtomic(configPath, result);
-        });
-        const newVersion = typeof result.configVersion === "string" ? result.configVersion : "0.8.0";
-        const backupDir = `${getCacheDir()}/config-backups`;
-        // WS-2: emit a loud banner to BOTH stderr and stdout so pipelines and
-        // interactive terminals both see it. Include the backup path (resolved,
-        // not ~/...), opt-out env var, and preview diff command.
-        const banner = [
-            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
-            `  akm: auto-migrated config → ${newVersion} format`,
-            `  file:   ${configPath}`,
-            `  backup: ${backupDir}/config-<timestamp>.json`,
-            "  to opt out of future auto-migration: AKM_NO_AUTO_MIGRATE=1",
-            "  to preview a dry-run diff:            akm config migrate --dry-run --print-diff",
-            "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
-        ].join("\n");
-        process.stderr?.write?.(`${banner}\n`);
-        process.stdout?.write?.(`${banner}\n`);
-    }
-    catch (err) {
-        // #461: never return migrated bytes when disk write fails — that triggers
-        // an infinite re-migrate loop on every load. Hard-error so the user
-        // notices and either fixes the disk issue or sets AKM_NO_AUTO_MIGRATE=1.
-        throw new ConfigError(`Failed to write migrated config to ${configPath}: ${err instanceof Error ? err.message : String(err)}`, "INVALID_CONFIG_FILE", "Check filesystem permissions, free space, and disk health. To skip auto-migration, set AKM_NO_AUTO_MIGRATE=1.");
-    }
-    return migratedText;
+export function getImproveProcessConfig(_config, processName, selected) {
+    return selected?.processes?.[processName];
 }
 export function loadConfig() {
     // Single-layer load: only the user-level config file is read. Project-level
@@ -292,39 +182,90 @@ export function _setSaveConfigForTests(fake) {
     saveConfigOverride = fake;
 }
 export function saveConfig(config) {
+    // Every lifecycle write produces the only config version this binary can load.
+    const currentConfig = { ...config, configVersion: CURRENT_CONFIG_VERSION };
     if (saveConfigOverride) {
-        saveConfigOverride(config);
+        saveConfigOverride(currentConfig);
         return;
     }
-    saveConfigReal(config);
+    saveConfigReal(currentConfig);
 }
 function saveConfigReal(config) {
     cachedConfig = undefined;
     const configPath = getConfigPath();
     const dir = path.dirname(configPath);
     fs.mkdirSync(dir, { recursive: true });
-    const sanitized = sanitizeConfigForWrite(config);
-    // Final validation gate before bytes hit disk. Runs the FULL schema —
-    // including the cross-field superRefine guards (removed `feedbackDistillation`
-    // process key, `defaultWriteTarget` resolution, writable npm/website sources)
-    // and all type/enum/range checks — so an `akm config set` (leaf OR object
-    // form) cannot persist a guard-violating or mistyped value. NOTE: unknown
-    // keys are intentionally NOT rejected here — object schemas are `.passthrough()`
-    // so cross-version skew round-trips (see config-schema.ts header); the lenient
-    // tolerance is by design, not an oversight.
-    const parseResult = AkmConfigSchema.safeParse(sanitized);
-    if (!parseResult.success) {
-        const lines = parseResult.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
-        throw new ConfigError(`Refusing to save invalid config:\n${lines}`, "INVALID_CONFIG_FILE", "Fix the listed fields, or undo the offending `akm config set`. " +
-            "If this looks like an akm bug, re-run with --debug to attach the traceback.");
-    }
-    // WS-3: acquire the config write lock so concurrent `akm config set`
-    // invocations do not interleave their backup+atomic-write cycles.
     withConfigLock(() => {
+        const validated = validateCompleteConfig(config);
+        ensureMigrationBackupWithConfigLockHeld();
         backupExistingConfig(configPath);
-        writeConfigAtomic(configPath, sanitized);
+        writeConfigAtomic(configPath, sanitizeConfigForWrite(validated));
     });
 }
+export function validateCompleteConfig(config) {
+    const parseResult = AkmConfigSchema.safeParse(config);
+    if (parseResult.success)
+        return parseResult.data;
+    const lines = parseResult.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+    throw new ConfigError(`Refusing to save invalid config:\n${lines}`, "INVALID_CONFIG_FILE", "Fix the listed fields, or undo the offending `akm config set`. " +
+        "If this looks like an akm bug, re-run with --debug to attach the traceback.");
+}
+/**
+ * Mutate config under one fail-closed lock spanning read, merge, validation,
+ * migration backup, ordinary backup, and atomic write.
+ */
+export function mutateConfig(mutate, options) {
+    cachedConfig = undefined;
+    const configPath = getConfigPath();
+    return withConfigLock(() => {
+        const text = readConfigText(configPath);
+        if (text === undefined && options?.absentNoop) {
+            return { config: { ...DEFAULT_CONFIG }, written: false };
+        }
+        const current = text === undefined ? { ...DEFAULT_CONFIG } : parseAndValidateConfigText(text, configPath);
+        const mutated = mutate(current);
+        if (mutated === current)
+            return { config: current, written: false };
+        const next = validateCompleteConfig({ ...mutated, configVersion: CURRENT_CONFIG_VERSION });
+        ensureMigrationBackupWithConfigLockHeld();
+        if (text !== undefined)
+            backupExistingConfig(configPath);
+        fs.mkdirSync(path.dirname(configPath), { recursive: true });
+        writeConfigAtomic(configPath, sanitizeConfigForWrite(next));
+        return { config: next, written: true };
+    });
+}
+/**
+ * Mutate config while holding the write lock across one validated pre-commit
+ * side effect. Setup uses this to reject a three-way conflict before creating
+ * its stash, while preventing another config writer from racing the final save.
+ */
+export async function mutateConfigWithPrecommit(mutate, precommit) {
+    cachedConfig = undefined;
+    const configPath = getConfigPath();
+    const release = acquireConfigLock();
+    try {
+        const text = readConfigText(configPath);
+        const current = text === undefined ? { ...DEFAULT_CONFIG } : parseAndValidateConfigText(text, configPath);
+        const mutated = mutate(current);
+        const next = validateCompleteConfig({ ...mutated, configVersion: CURRENT_CONFIG_VERSION });
+        // Setup's pre-commit may initialize the stash. Prove the rebase and final
+        // config are valid, then require the recovery snapshots before that first
+        // external side effect.
+        ensureMigrationBackupWithConfigLockHeld();
+        if (text !== undefined)
+            backupExistingConfig(configPath);
+        const precommitResult = await precommit(next);
+        if (mutated === current)
+            return { config: current, written: false, precommit: precommitResult };
+        fs.mkdirSync(path.dirname(configPath), { recursive: true });
+        writeConfigAtomic(configPath, sanitizeConfigForWrite(next));
+        return { config: next, written: true, precommit: precommitResult };
+    }
+    finally {
+        release();
+    }
+}
 /**
  * Strip literal apiKey fields before writing config to disk.
  * API keys are expected to come from environment variables
@@ -359,50 +300,36 @@ function sanitizeConfigForWrite(config) {
     else if (config.embedding) {
         sanitized.embedding = { ...config.embedding };
     }
-    if (config.profiles?.llm) {
-        const llmProfiles = {};
-        for (const [name, profile] of Object.entries(config.profiles.llm)) {
-            if (profile.apiKey !== undefined) {
-                if (isEnvReference(profile.apiKey)) {
-                    llmProfiles[name] = { ...profile };
-                }
-                else {
-                    const { apiKey: _drop, ...rest } = profile;
-                    llmProfiles[name] = rest;
-                    if (profile.apiKey) {
-                        const envVar = `AKM_PROFILE_${name.toUpperCase().replace(/-/g, "_")}_API_KEY`;
-                        stripped.push(`profiles.llm.${name}.apiKey (set ${envVar} to provide at runtime)`);
-                    }
-                }
-            }
-            else {
-                llmProfiles[name] = { ...profile };
+    if (config.engines) {
+        const engines = {};
+        for (const [name, engine] of Object.entries(config.engines)) {
+            if (engine.kind !== "llm" || engine.apiKey === undefined || isEnvReference(engine.apiKey)) {
+                engines[name] = { ...engine };
+                continue;
             }
+            const { apiKey: _drop, ...rest } = engine;
+            engines[name] = rest;
+            if (engine.apiKey)
+                stripped.push(`engines.${name}.apiKey`);
         }
-        sanitized.profiles = {
-            ...(sanitized.profiles ?? {}),
-            llm: llmProfiles,
-        };
+        sanitized.engines = engines;
     }
     if (stripped.length > 0) {
         warn(`Config sanitizer dropped API key(s) before writing to disk:\n  - ${stripped.join("\n  - ")}\n\nakm does not persist API keys to config.json. Set the listed environment variables to provide them at runtime, or use \`\${VAR}\` references in your config to defer lookup. See docs/data-and-telemetry.md.`);
     }
     return sanitized;
 }
-/** Matches `${VAR}`, `${VAR:-default}`, or `$VAR`. */
+/** Matches the only 0.9 symbolic secret forms: `${VAR}` or `$VAR`. */
 function isEnvReference(value) {
-    return /^\$\{[^}]+\}$|^\$[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+    return /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$|^\$[A-Za-z_][A-Za-z0-9_]*$/.test(value);
 }
 export function updateConfig(partial) {
-    const current = loadUserConfig();
-    const merged = mergeLoadedConfig(current, partial);
-    saveConfig(merged);
-    return merged;
+    return mutateConfig((current) => deepMergeConfig(current, partial)).config;
 }
 // ── Helpers ─────────────────────────────────────────────────────────────────
 /**
- * Resolve a single secret value by expanding `${VAR}` / `$VAR` /
- * `${VAR:-default}` references against `process.env`. Use this at apiKey /
+ * Resolve a single secret value by expanding `${VAR}` / `$VAR` references
+ * against `process.env`. Use this at apiKey /
  * authorization-header consumption sites (LLM client, embedder, agent SDK
  * runner) — NOT on the load path. Non-string inputs pass through unchanged.
  *
@@ -420,13 +347,8 @@ export function resolveSecret(value) {
         return value;
     if (!value.includes("$"))
         return value;
-    return value.replace(/\$\{([^}]+)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (_match, braced, bare) => {
-        if (braced) {
-            const [name, ...rest] = braced.split(":-");
-            const fallback = rest.join(":-");
-            return process.env[name] ?? fallback ?? "";
-        }
-        return process.env[bare] ?? "";
+    return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (_match, braced, bare) => {
+        return process.env[(braced ?? bare)] ?? "";
     });
 }
 /**
@@ -437,9 +359,10 @@ export function resolveSecret(value) {
 /**
  * Reserved well-known keys on IndexConfig that are NOT per-pass entries.
  * `stalenessDetection` is retired (10-Q3) but stays reserved so a leftover
- * config section is never misread as a pass entry.
+ * config section is never misread as a pass entry. `indexBodyOpening`
+ * (stash-conventions SPEC-8) is a boolean feature flag, not a pass section.
  */
-const INDEX_RESERVED_KEYS = new Set(["metadataEnhance", "stalenessDetection"]);
+const INDEX_RESERVED_KEYS = new Set(["metadataEnhance", "stalenessDetection", "indexBodyOpening"]);
 export function getIndexPassConfig(config, passName) {
     if (!config)
         return undefined;
@@ -458,63 +381,6 @@ export { parseSourceSpec, resolveConfiguredSources } from "./config-sources.js";
  * (current config + partial patch). Sub-objects with named records (profiles,
  * defaults, etc.) shallow-merge; arrays override wholesale.
  */
-function mergeLoadedConfig(base, override) {
-    if (!override)
-        return { ...base };
-    const merged = { ...base, ...override };
-    // Shallow-merge sub-objects so a partial update to e.g. `output.format`
-    // doesn't drop the existing `output.detail`.
-    for (const key of ["output", "embedding", "index", "defaults"]) {
-        if (base[key] && override[key]) {
-            // biome-ignore lint/suspicious/noExplicitAny: heterogeneous structural merge
-            merged[key] = { ...base[key], ...override[key] };
-        }
-    }
-    if (base.profiles && override.profiles) {
-        const next = { ...base.profiles };
-        for (const k of ["llm", "agent", "improve"]) {
-            const ovr = override.profiles[k];
-            if (ovr)
-                next[k] = { ...(next[k] ?? {}), ...ovr };
-        }
-        merged.profiles = next;
-    }
-    return merged;
-}
-function applyRuntimeEnvApiKeys(config) {
-    const next = { ...config };
-    if (next.embedding && !next.embedding.apiKey) {
-        const envKey = process.env.AKM_EMBED_API_KEY?.trim();
-        if (envKey)
-            next.embedding = { ...next.embedding, apiKey: envKey };
-    }
-    // LLM profile keys: AKM_LLM_API_KEY for the default profile, then
-    // AKM_PROFILE_<UPPER>_API_KEY for any profile (per-profile wins).
-    // Resolve the default profile the SAME way the rest of the config layer does
-    // (resolveDefaultLlmProfileName), so the implicit `profiles.llm.default`
-    // fallback is honored. Keying off the raw `defaults.llm` field alone silently
-    // dropped AKM_LLM_API_KEY for configs that rely on the implicit default —
-    // the same no-op-run class as the 2026-05-23 incident.
-    const defaultProfile = resolveDefaultLlmProfileName(next);
-    if (next.profiles?.llm) {
-        const updated = { ...next.profiles.llm };
-        let changed = false;
-        for (const [name, profile] of Object.entries(updated)) {
-            if (profile.apiKey)
-                continue;
-            const perProfile = process.env[`AKM_PROFILE_${name.toUpperCase().replace(/-/g, "_")}_API_KEY`]?.trim();
-            const fallback = name === defaultProfile ? process.env.AKM_LLM_API_KEY?.trim() : undefined;
-            const envKey = perProfile || fallback;
-            if (envKey) {
-                updated[name] = { ...profile, apiKey: envKey };
-                changed = true;
-            }
-        }
-        if (changed)
-            next.profiles = { ...next.profiles, llm: updated };
-    }
-    return next;
-}
 /**
  * Walk cwd-ancestors looking for `.akm/config.json`. If one is found, emit a
  * one-time deprecation warning per path. The file's contents are NOT read —

package/dist/core/config/deep-merge.js

@@ -0,0 +1,41 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+export function isPlainObject(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function copyConfigValue(value) {
+    if (Array.isArray(value))
+        return value.map(copyConfigValue);
+    if (!isPlainObject(value))
+        return value;
+    const copy = {};
+    for (const key of Object.keys(value)) {
+        if (UNSAFE_KEYS.has(key))
+            throw new TypeError(`Unsafe configuration key: ${key}`);
+        copy[key] = copyConfigValue(value[key]);
+    }
+    return copy;
+}
+/**
+ * Merge configuration values without mutating either input. Plain objects merge
+ * recursively; arrays and scalar values replace the less-specific value.
+ */
+export function deepMergeConfig(base, override) {
+    const result = copyConfigValue(base);
+    for (const key of Object.keys(override)) {
+        if (UNSAFE_KEYS.has(key))
+            throw new TypeError(`Unsafe configuration key: ${key}`);
+        const next = override[key];
+        if (next === undefined)
+            continue;
+        const current = result[key];
+        result[key] =
+            isPlainObject(current) && isPlainObject(next) ? deepMergeConfig(current, next) : copyConfigValue(next);
+    }
+    return result;
+}

package/dist/core/config/engine-semantics.js

@@ -0,0 +1,32 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+export const ENGINE_NAME_PATTERN_SOURCE = "^(?!akm-)[a-z][a-z0-9]*(?:-[a-z0-9]+)*$";
+export const BUILTIN_IMPROVE_STRATEGY_NAMES = [
+    "default",
+    "quick",
+    "thorough",
+    "memory-focus",
+    "graph-refresh",
+    "frequent",
+    "consolidate",
+    "catchup",
+    "synthesize",
+    "reflect-distill",
+    "proactive-maintenance",
+    "recombine-only",
+];
+/** Engine capability required by each configured improve process. `null` means engine-free. */
+export const IMPROVE_PROCESS_ENGINE_CAPABILITIES = {
+    reflect: "llm",
+    distill: "llm",
+    consolidate: "llm",
+    memoryInference: "llm",
+    graphExtraction: "llm",
+    extract: "llm",
+    validation: "llm",
+    triage: "runner",
+    proactiveMaintenance: null,
+    recombine: "llm",
+    procedural: "llm",
+};

package/dist/core/errors.js

@@ -10,11 +10,11 @@ const CONFIG_HINTS = {
     STASH_DIR_NOT_A_DIRECTORY: "The configured stashDir exists but isn't a directory. Update stashDir to point at a folder.",
     STASH_DIR_UNREADABLE: "Check the path exists and your user has read permission, or update stashDir.",
     EMBEDDING_NOT_CONFIGURED: 'Run `akm config set embedding \'{"endpoint":"...","model":"..."}\'` to enable embeddings.',
-    LLM_NOT_CONFIGURED: 'Run `akm setup` or `akm config set profiles.llm.default \'{"endpoint":"...","model":"..."}\' to configure an LLM profile.',
+    LLM_NOT_CONFIGURED: 'Run `akm setup` or configure an `engines` entry with `kind: "llm"`, then select it with `defaults.llmEngine`.',
     TEST_ISOLATION_MISSING: "Under bun test, when AKM_STASH_DIR is set you MUST also set XDG_DATA_HOME (or AKM_DATA_DIR) and XDG_STATE_HOME (or AKM_STATE_DIR) to temp directories so the test does not touch the developer's real ~/.local/share/akm or ~/.local/state/akm.",
     SETUP_TMP_STASH_REFUSED: "Use a persistent directory, or set AKM_FORCE_SETUP_TMP_STASH=1 to opt in to a sandboxed setup (setup also pre-sets AKM_STASH_DIR so config and cache writes auto-isolate into $stashDir/.akm/ — host config is preserved).",
     UNSAFE_STASH_DIR: "Choose a path inside your home directory (e.g. ~/akm) or another empty workspace. The stash directory cannot be the filesystem root, your home directory itself, or a sensitive system path like /etc, /var, ~/.config, or ~/.ssh.",
-    UNKNOWN_IMPROVE_PROFILE: "Pass one of the listed profile names to `--profile`, or define it under `profiles.improve` in your config. Names are case-sensitive.",
+    UNKNOWN_IMPROVE_STRATEGY: "Pass one of the listed strategy names to `--strategy`, or define it under `improve.strategies`. Names are case-sensitive.",
 };
 /** Default hint for each UsageError code. */
 const USAGE_HINTS = {