akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/core/config/config.js

@@ -4,11 +4,20 @@
 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 { assertNoPendingMigrationOperation } from "../migration-operation.js";
+import { acquireConfigLock, backupExistingConfig, parseConfigText, readConfigText, withConfigLock, writeConfigAtomic, } from "./config-io.js";
+import { AkmConfigSchema, CURRENT_CONFIG_VERSION } from "./config-schema.js";
+import { bundlesToSourceEntries } from "./config-sources.js";
+import { deepMergeConfig } from "./deep-merge.js";
 export { stripJsonComments } from "./config-io.js";
-import { getCacheDir, getConfigPath } from "../paths.js";
+// requireLlmConfig / getDefaultLlmConfig moved to
+// integrations/agent/engine-resolution.ts (WI-9.8 KILL 3, D.3 edge A) — they
+// called that module's materializeLlmConnection/resolveLlmEngineUse, and that
+// module imported LlmConnectionConfig back from this file, closing a 2-file
+// cycle that also fused config.ts into the harness/agent-runtime SCC. This
+// file can no longer re-export them (a re-export is still a graph edge to
+// engine-resolution.ts) — import them from there directly.
+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,7 +57,8 @@ export function resolveBatchSize(configured, contextLength) {
 }
 // ── Defaults ────────────────────────────────────────────────────────────────
 export const DEFAULT_CONFIG = {
-    semanticSearchMode: "auto",
+    configVersion: "0.9.0",
+    semanticSearchMode: "off",
     registries: [
         { url: "https://raw.githubusercontent.com/itlackey/akm-registry/main/index.json", name: "akm-registry" },
         { url: "https://skills.sh", name: "skills.sh", provider: "skills-sh", enabled: false },
@@ -59,20 +69,23 @@ export const DEFAULT_CONFIG = {
     },
 };
 // ── Load / Save / Update ────────────────────────────────────────────────────
-const PROJECT_CONFIG_RELATIVE_PATH = path.join(".akm", "config.json");
 let cachedConfig;
 export function resetConfigCache() {
     cachedConfig = undefined;
 }
 export function loadUserConfig() {
+    assertNoPendingMigrationOperation();
     const configPath = getConfigPath();
     let stat;
     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 —
@@ -85,17 +98,16 @@ export function loadUserConfig() {
     }
     let text;
     try {
-        text = fs.readFileSync(configPath, "utf8");
+        text = readConfigText(configPath);
     }
-    catch {
+    catch (err) {
+        throw new ConfigError(`Unable to read config at ${configPath}: ${err instanceof Error ? err.message : String(err)}`, "INVALID_CONFIG_FILE");
+    }
+    if (text === undefined) {
         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,222 +125,141 @@ 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.
+ * The schema accepts only the current config version and validates the
+ * canonical shape before defaults are merged.
  */
-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);
-}
-export function getSources(config) {
-    return config.sources ?? [];
-}
-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).
- */
-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.`);
+    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 profile;
+    return finalResult.data;
 }
 /**
- * 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];
-}
-/**
- * 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).
+ * The configured stash sources as an ordered {@link SourceConfigEntry} list.
  *
- * 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.
+ * 0.9.0 (spec §10.1): the retired `stashDir`/`sources[]`/`installed[]` trio is
+ * gone — every source is a `bundles.<slug>` entry. This derives the unified
+ * source list from `bundles` (defaultBundle first, then map order), so callers
+ * that iterated `sources[]` keep working over the new shape. Returns `[]` when
+ * no bundles are configured.
  */
-export function getImproveProcessConfig(config, processName, activeProfile) {
-    const fromActiveProfile = activeProfile?.processes?.[processName];
-    if (fromActiveProfile !== undefined)
-        return fromActiveProfile;
-    return config.profiles?.improve?.default?.processes?.[processName];
+export function getSources(config) {
+    return bundlesToSourceEntries(config) ?? [];
+}
+export function getEffectiveRegistries(config) {
+    return config.registries ?? DEFAULT_CONFIG.registries ?? [];
 }
 /**
- * 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).
+ * Transitional internal accessor. It deliberately never consults a configured
+ * default strategy; callers must pass their already selected strategy.
  */
-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(processName, selected) {
+    return selected?.processes?.[processName];
 }
 export function loadConfig() {
-    // Single-layer load: only the user-level config file is read. Project-level
-    // .akm/config.json files discovered under cwd-ancestors emit a one-time
-    // deprecation warning (#457) but are NOT merged.
-    warnIfProjectConfigPresent(process.cwd());
     return loadUserConfig();
 }
-let saveConfigOverride;
-/** TEST-ONLY. Swap the implementation of `saveConfig`; pass undefined to restore. */
-export function _setSaveConfigForTests(fake) {
-    saveConfigOverride = fake;
-}
 export function saveConfig(config) {
-    if (saveConfigOverride) {
-        saveConfigOverride(config);
-        return;
-    }
-    saveConfigReal(config);
+    // Every lifecycle write produces the only config version this binary can load.
+    const currentConfig = { ...config, configVersion: CURRENT_CONFIG_VERSION };
+    saveConfigReal(currentConfig);
 }
 function saveConfigReal(config) {
+    assertNoPendingMigrationOperation();
     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(() => {
+        assertNoPendingMigrationOperation();
+        const validated = validateCompleteConfig(config);
         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,
+ * ordinary backup, and atomic write.
+ */
+export function mutateConfig(mutate, options) {
+    assertNoPendingMigrationOperation();
+    cachedConfig = undefined;
+    const configPath = getConfigPath();
+    return withConfigLock(() => {
+        assertNoPendingMigrationOperation();
+        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 });
+        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) {
+    assertNoPendingMigrationOperation();
+    cachedConfig = undefined;
+    const configPath = getConfigPath();
+    const release = acquireConfigLock();
+    try {
+        assertNoPendingMigrationOperation();
+        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 });
+        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
- * (AKM_EMBED_API_KEY, AKM_LLM_API_KEY, AKM_PROFILE_<NAME>_API_KEY).
+ * (AKM_EMBED_API_KEY, AKM_LLM_API_KEY, AKM_ENGINE_<NAME>_API_KEY).
  *
  * `${VAR}` / `$VAR` references are preserved — they are not secrets, they
  * are deferred lookups resolved at consumption by `resolveSecret`. Dropping
@@ -340,7 +271,7 @@ function saveConfigReal(config) {
  * --yes` with an `apiKey` field expected persistence and got a wiped config
  * with no feedback.
  */
-function sanitizeConfigForWrite(config) {
+export function sanitizeConfigForWrite(config) {
     const sanitized = { ...config };
     const stripped = [];
     if (config.embedding?.apiKey !== undefined) {
@@ -359,50 +290,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.`);
+        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/reference/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,26 +337,21 @@ 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)] ?? "";
     });
 }
 /**
  * Read a per-pass {@link IndexPassConfig} entry from {@link IndexConfig},
  * filtering out the reserved feature-section keys so callers don't mistake
- * `metadataEnhance` / `stalenessDetection` for a pass.
+ * `metadataEnhance` for a pass.
  */
 /**
  * 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.
+ * `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", "indexBodyOpening"]);
 export function getIndexPassConfig(config, passName) {
     if (!config)
         return undefined;
@@ -451,99 +363,10 @@ export function getIndexPassConfig(config, passName) {
     return entry;
 }
 // Re-export source runtime helpers — implementation lives in config-sources.ts.
-export { parseSourceSpec, resolveConfiguredSources } from "./config-sources.js";
+export { bundleComponentConfig, bundleEntryToSourceEntry, bundlesToSourceEntries, installedSourceDescriptor, parseSourceSpec, primaryBundlePath, resolveConfiguredSources, } from "./config-sources.js";
 /**
  * Merge a partial user-config override onto a base config. Used by
  * {@link loadUserConfig} (DEFAULT_CONFIG + on-disk) and {@link updateConfig}
  * (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 —
- * multi-layer project config was removed in this release; the warning stays
- * for one cycle so users notice they have a now-dead file on disk and can
- * migrate its settings to the user-level config.
- */
-const PROJECT_CONFIG_DEPRECATION_WARNED = new Set();
-function warnIfProjectConfigPresent(startDir) {
-    let currentDir = path.resolve(startDir);
-    while (true) {
-        const configPath = path.join(currentDir, PROJECT_CONFIG_RELATIVE_PATH);
-        if (isFile(configPath) && !PROJECT_CONFIG_DEPRECATION_WARNED.has(configPath)) {
-            PROJECT_CONFIG_DEPRECATION_WARNED.add(configPath);
-            warn(`[akm] DEPRECATED: project-level config file found at ${configPath}. ` +
-                "Project-level config files are no longer merged (removed after 0.8.x deprecation). " +
-                "Move any needed settings to ~/.config/akm/config.json; this file is ignored.");
-        }
-        const parentDir = path.dirname(currentDir);
-        if (parentDir === currentDir)
-            break;
-        currentDir = parentDir;
-    }
-}
-function isFile(filePath) {
-    try {
-        return fs.statSync(filePath).isFile();
-    }
-    catch {
-        return false;
-    }
-}

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