akm-cli 0.9.11 → 0.9.13

package/dist/core/adapter/execution-source.js

@@ -6,6 +6,8 @@ import { isMap, isScalar, parseDocument, visit } from "yaml";
 import { cloneExecutionJson, cloneExecutionJsonObject, } from "../../execution/json.js";
 import { assertSnapshotKeys, snapshotStrictRecord } from "../../execution/record.js";
 import { cloneToolSelection, createAdapterRenderedExecutionSource, } from "../../execution/source.js";
+import { UsageError } from "../errors.js";
+import { warnOnce } from "../warn.js";
 function nextLine(text, start) {
     const lf = text.indexOf("\n", start);
     if (lf < 0)
@@ -13,16 +15,39 @@ function nextLine(text, start) {
     const end = lf > start && text[lf - 1] === "\r" ? lf - 1 : lf;
     return { line: text.slice(start, end), next: lf + 1 };
 }
-/** Strict execution-only frontmatter parser; indexing's tolerant parser is deliberately not reused. */
-export function parseExecutionMarkdown(raw) {
+/**
+ * Strict execution-only frontmatter parser; indexing's tolerant parser is
+ * deliberately not reused.
+ *
+ * `filePath`, when given, names the offending asset in a thrown error so an
+ * operator (or CI) sees which file to fix instead of a bare message.
+ *
+ * A third party's markdown that genuinely cannot be parsed into a mapping
+ * (unterminated frontmatter, broken YAML syntax, a non-mapping document)
+ * throws {@link UsageError} \u2014 exit 2, an actionable usage problem, not exit
+ * 70 (`TypeError`'s "unclassified internal error" code, which is what a
+ * `throw new TypeError(...)` here used to surface as). Anchors, explicit
+ * tags, and non-string mapping keys are recognized-but-unsupported
+ * constructs rather than parse failures on their own \u2014 an anchor nobody
+ * aliases, or a tag `toJS` converts to a plain value, is harmless \u2014 so they
+ * warn once (naming the file) and fall through to conversion instead of
+ * being pre-emptively rejected by a second, stricter gate in front of it.
+ * `toJS({ maxAliasCount: 0 })` is the real, UNCHANGED safety bound against
+ * alias-expansion abuse \u2014 it disables alias RESOLUTION outright, so a value
+ * that actually references an anchor via `*name` still fails, now as a
+ * {@link UsageError} from this same conversion step rather than the removed
+ * duplicate pre-check.
+ */
+export function parseExecutionMarkdown(raw, filePath) {
     if (typeof raw !== "string")
         throw new TypeError("execution source raw content must be a string");
+    const where = filePath ? ` (${filePath})` : "";
     const withoutBom = raw.startsWith("\uFEFF") ? raw.slice(1) : raw;
     const opening = nextLine(withoutBom, 0);
     if (opening.line !== "---")
         return { content: withoutBom, data: Object.freeze({}) };
     if (opening.next === withoutBom.length) {
-        throw new TypeError("execution source has unterminated frontmatter");
+        throw new UsageError(`execution source${where} has unterminated frontmatter`);
     }
     let cursor = opening.next;
     let frontmatterEnd = -1;
@@ -40,18 +65,18 @@ export function parseExecutionMarkdown(raw) {
         cursor = current.next;
     }
     if (frontmatterEnd < 0 || bodyStart < 0) {
-        throw new TypeError("execution source has unterminated frontmatter");
+        throw new UsageError(`execution source${where} has unterminated frontmatter`);
     }
     const yaml = withoutBom.slice(opening.next, frontmatterEnd);
     const document = parseDocument(yaml, { uniqueKeys: true });
     if (document.errors.length > 0) {
-        throw new TypeError(`execution source has invalid YAML frontmatter: ${document.errors[0]?.message ?? "parse error"}`);
+        throw new UsageError(`execution source${where} has invalid YAML frontmatter: ${document.errors[0]?.message ?? "parse error"}`);
     }
     if (document.warnings.length > 0) {
-        throw new TypeError(`execution source YAML frontmatter uses an unsupported tag or construct: ${document.warnings[0]?.message}`);
+        warnOnce(`execution-source:yaml-warning:${filePath ?? "<inline>"}`, `execution source${where} YAML frontmatter uses an unsupported tag or construct: ${document.warnings[0]?.message}. Using it as parsed.`);
     }
     if (!isMap(document.contents)) {
-        throw new TypeError("execution source YAML frontmatter must be a mapping");
+        throw new UsageError(`execution source${where} YAML frontmatter must be a mapping`);
     }
     let unsupported;
     visit(document, {
@@ -69,14 +94,16 @@ export function parseExecutionMarkdown(raw) {
                 unsupported ??= "non-string mapping keys";
         },
     });
-    if (unsupported)
-        throw new TypeError(`execution source YAML frontmatter does not support ${unsupported}`);
+    if (unsupported) {
+        warnOnce(`execution-source:unsupported:${filePath ?? "<inline>"}`, `execution source${where} YAML frontmatter uses ${unsupported}, which akm does not fully support; using the bounded conversion's result as-is.`);
+    }
     let root;
     try {
         root = document.toJS({ maxAliasCount: 0 });
     }
     catch (cause) {
-        throw new TypeError("execution source YAML frontmatter could not be converted safely", { cause });
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        throw new UsageError(`execution source${where} YAML frontmatter could not be converted safely: ${detail}`);
     }
     const data = cloneExecutionJsonObject(root, "execution source YAML frontmatter");
     return { content: withoutBom.slice(bodyStart), data: Object.freeze(data) };
@@ -279,7 +306,8 @@ export function renderMarkdownExecutionSource(input) {
     const kind = snapshots.input.kind;
     if (kind !== "command" && kind !== "persona")
         throw new TypeError("adapter execution source.kind is invalid");
-    const parsed = parseExecutionMarkdown(raw);
+    const identityFile = snapshots.identity.file;
+    const parsed = parseExecutionMarkdown(raw, typeof identityFile === "string" ? identityFile : undefined);
     const hasDefaults = Object.hasOwn(snapshots.input, "defaults");
     const defaultsProjection = snapshots.input.defaults;
     const defaults = typeof defaultsProjection === "function" ? defaultsProjection(parsed.data) : defaultsProjection;

package/dist/core/asset/stash-meta.js

@@ -18,6 +18,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { isWithin } from "../common.js";
 import { UsageError } from "../errors.js";
 /** Root-relative directory holding a stash's meta docs. */
 export const META_DIR = ".meta";
@@ -113,7 +114,7 @@ export function readMetaFile(sourceRoot, name) {
         return null;
     let fd;
     try {
-        fd = fs.openSync(filePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        fd = fs.openSync(filePath, fs.constants.O_RDONLY);
         const opened = fs.fstatSync(fd);
         if (!opened.isFile())
             throw metaPathEscape();
@@ -141,60 +142,25 @@ export function readMetaFile(sourceRoot, name) {
     }
 }
 function isSafeRegularMetaFile(sourceRoot, metaRoot, filePath) {
-    const sourceRootReal = realPathOrNull(sourceRoot);
-    if (!sourceRootReal)
-        return false;
-    const metaStat = lstatOrNull(metaRoot);
-    if (!metaStat)
-        return false;
-    if (metaStat.isSymbolicLink())
-        throw metaPathEscape();
-    if (!metaStat.isDirectory())
-        return false;
     const relative = path.relative(metaRoot, filePath);
     if (relative === "" || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
         throw metaPathEscape();
     }
-    let current = metaRoot;
-    for (const segment of relative.split(path.sep)) {
-        current = path.join(current, segment);
-        const stat = lstatOrNull(current);
-        if (!stat)
-            return false;
-        if (stat.isSymbolicLink())
-            throw metaPathEscape();
-    }
-    const finalStat = lstatOrNull(filePath);
+    const finalStat = statOrNull(filePath);
     if (!finalStat?.isFile())
         return false;
-    const metaRootReal = realPathOrNull(metaRoot);
-    const fileReal = realPathOrNull(filePath);
-    if (!metaRootReal || !fileReal)
-        return false;
-    if (!isWithin(sourceRootReal, metaRootReal) || !isWithin(metaRootReal, fileReal))
+    if (!isWithin(filePath, sourceRoot))
         throw metaPathEscape();
     return true;
 }
-function lstatOrNull(filePath) {
+function statOrNull(filePath) {
     try {
-        return fs.lstatSync(filePath);
+        return fs.statSync(filePath);
     }
     catch {
         return null;
     }
 }
-function realPathOrNull(filePath) {
-    try {
-        return fs.realpathSync(filePath);
-    }
-    catch {
-        return null;
-    }
-}
-function isWithin(root, candidate) {
-    const relative = path.relative(root, candidate);
-    return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
-}
 function metaPathEscape() {
-    return new UsageError("Meta doc must be a regular file inside the stash .meta directory; symlinks are refused.", "PATH_ESCAPE_VIOLATION");
+    return new UsageError("Meta doc must resolve to a regular file inside the stash .meta directory, not one that escapes it.", "PATH_ESCAPE_VIOLATION");
 }

package/dist/core/common.js

@@ -4,6 +4,7 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { migrateLegacySourceShape } from "./config/legacy-source-shape-shim.js";
 import { ConfigError } from "./errors.js";
 import { getConfigPath, getDefaultStashDir, getRegistryCacheDir, getRegistryIndexCacheDir } from "./paths.js";
 // ── Constants ───────────────────────────────────────────────────────────────
@@ -302,23 +303,20 @@ function readStashDirFromConfig() {
         // in use. Parsing it raw here threw, the catch swallowed it, and every
         // caller silently fell back — operating on the wrong bundle or failing with
         // STASH_DIR_NOT_FOUND despite a perfectly good config.
-        const raw = JSON.parse(stripJsonComments(text));
-        if (typeof raw !== "object" || raw === null)
+        const parsed = JSON.parse(stripJsonComments(text));
+        if (typeof parsed !== "object" || parsed === null)
             return undefined;
+        const raw = migrateLegacySourceShape(parsed, configPath);
         // 0.9.0 config-shape cutover (spec §10.1): the primary stash is the
         // `defaultBundle`'s filesystem `path`. Read it directly (no config module
         // import) so the primary-stash location survives the stashDir → bundles
         // migration without a runtime rewire.
         const bundles = raw.bundles;
         const defaultBundle = raw.defaultBundle;
-        if (bundles &&
-            typeof bundles === "object" &&
-            typeof defaultBundle === "string" &&
-            bundles[defaultBundle] &&
-            typeof bundles[defaultBundle] === "object" &&
-            typeof bundles[defaultBundle].path === "string" &&
-            bundles[defaultBundle].path.trim()) {
-            const bundle = bundles[defaultBundle];
+        const selectedBundle = typeof defaultBundle === "string" ? bundles?.[defaultBundle] : undefined;
+        const selectedBundlePath = typeof selectedBundle?.path === "string" ? selectedBundle.path : undefined;
+        if (bundles && typeof bundles === "object" && typeof defaultBundle === "string" && selectedBundlePath?.trim()) {
+            const bundle = selectedBundle;
             const bundlePath = bundle.path.trim();
             if (bundle.components !== undefined) {
                 if (typeof bundle.components !== "object" || bundle.components === null) {
@@ -343,13 +341,6 @@ function readStashDirFromConfig() {
             }
             return bundlePath;
         }
-        // Retired pre-cutover shapes are not runtime inputs. Refuse them instead
-        // of silently resolving old keys.
-        for (const key of ["stashDir", "sources", "installed"]) {
-            if (key in raw && raw[key] !== undefined) {
-                throw new ConfigError(`${key} is not supported; configure the current bundles shape`, "INVALID_CONFIG_FILE");
-            }
-        }
     }
     catch (err) {
         // An unsupported-shape refusal must reach the caller; genuine missing/invalid

package/dist/core/config/config-schema.js

@@ -41,6 +41,7 @@
  *   enforced at save time via `superRefine` on the top-level schema.
  */
 import { z } from "zod";
+import { warnOnce } from "../warn.js";
 import { BUILTIN_IMPROVE_STRATEGY_NAMES, IMPROVE_PROCESS_ENGINE_CAPABILITIES } from "./engine-semantics.js";
 import { EmbeddingConnectionConfigSchema } from "./schema/embedding.js";
 import { EnginesSchema } from "./schema/engines.js";
@@ -121,25 +122,11 @@ const RETIRED_SOURCE_SHAPE_KEY_MESSAGES = {
 };
 export const AkmConfigSchema = AkmConfigBaseSchema.superRefine((config, ctx) => {
     const raw = config;
-    for (const key of ["profiles", "llm", "agent", "features", "stashes", "modelAliases"]) {
+    for (const key of ["profiles", "llm", "agent", "features", "stashes", "modelAliases", "bindings", "writable"]) {
         if (key in raw) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                path: [key],
-                message: `${key} is retired in 0.9; configure engines and improve.strategies instead`,
-            });
+            warnOnce(`config:retired-key:${key}`, `Config key "${key}" is retired in 0.9 and is ignored; configure engines/improve.strategies/bundles.<id> instead.`);
         }
     }
-    // `bindings` (spec §10.1) is Tier B — never emitted, never accepted. The
-    // top-level schema is `.passthrough()`, so without this it would round-trip
-    // silently; reject it loudly so a stray/hand-written bindings block is caught.
-    if ("bindings" in raw) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ["bindings"],
-            message: "bindings is not supported in 0.9.0 (Tier B); it is neither emitted nor accepted",
-        });
-    }
     // Only the current source shape enters the runtime. There is no config
     // compatibility path; `bundles` + `defaultBundle` fully supersede these keys.
     for (const key of ["stashDir", "sources", "installed"]) {
@@ -151,13 +138,6 @@ export const AkmConfigSchema = AkmConfigBaseSchema.superRefine((config, ctx) =>
             });
         }
     }
-    if ("writable" in raw) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ["writable"],
-            message: "top-level writable is not supported; configure bundles.<id>.writable instead",
-        });
-    }
     // `defaultBundle`, when present, must name a configured bundle.
     if (config.defaultBundle !== undefined) {
         if (config.bundles === undefined) {

package/dist/core/config/config-walker.js

@@ -23,8 +23,11 @@
 import { z } from "zod";
 import { isRecord } from "../common.js";
 import { UsageError } from "../errors.js";
+import { hasRegistryUrlCredentials, REGISTRY_CREDENTIALS_UNSUPPORTED } from "../registry-url.js";
+import { warnOnce } from "../warn.js";
 import { AkmConfigBaseSchema, EngineConfigSchema, listTopLevelConfigKeys } from "./config-schema.js";
 import { deepMergeConfig } from "./deep-merge.js";
+import { isApiKeyReference } from "./schema/primitives.js";
 /**
  * Parse a dotted path into segments. Empty segments are rejected. Bracket
  * notation (e.g. `sources[0]`) is NOT supported — arrays are set as JSON.
@@ -175,11 +178,13 @@ export function configSet(config, dotted, raw) {
     }
     // #454: apiKey paths are not persistable. Throw at set time.
     rejectApiKeyPath(path, dotted);
+    rejectLiteralApiKeyInWholeObjectSet(path, raw, dotted);
     const schema = resolveSchemaAt(path, config, raw);
     const symbolicApiKey = (path[0] === "engines" && path[2] === "apiKey") ||
         (path[0] === "embedding" && path.length === 2 && path[1] === "apiKey");
-    if (!schema && !symbolicApiKey) {
-        throw new UsageError(`Unknown config key: ${dotted}`, "INVALID_FLAG_VALUE", unknownKeyHint(dotted));
+    const isUnknownKey = !schema && !symbolicApiKey;
+    if (isUnknownKey) {
+        warnOnce(`config-set:unknown-key:${dotted}`, `"${dotted}" is not a known config key; storing it anyway. Run \`akm config get ${dotted}\` to confirm it round-trips as expected.`);
     }
     const judgmentObjectPath = isTriageJudgmentPath(path);
     const value = judgmentObjectPath && raw === "null"
@@ -188,7 +193,11 @@ export function configSet(config, dotted, raw) {
             ? parseObjectPatch(raw, dotted)
             : symbolicApiKey
                 ? raw
-                : coerceForSchema(schema, raw, dotted);
+                : isUnknownKey
+                    ? bestEffortJsonValue(raw)
+                    : coerceForSchema(schema, raw, dotted);
+    if (path[0] === "registries")
+        rejectRegistryCredentialValue(value, dotted);
     const existing = path.reduce((value, key) => {
         if (value && typeof value === "object")
             return value[key];
@@ -206,10 +215,15 @@ export function configSet(config, dotted, raw) {
     const parsed = path[0] === "engines" && path.length === 2
         ? EngineConfigSchema.safeParse(value)
         : symbolicApiKey
-            ? /^\$[A-Za-z_][A-Za-z0-9_]*$|^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(raw)
+            ? isApiKeyReference(raw)
+                ? { success: true, data: value }
+                : {
+                    success: false,
+                    error: { issues: [{ path: [], message: "apiKey must be $VAR, ${VAR}, or secret://<name>" }] },
+                }
+            : isUnknownKey
                 ? { success: true, data: value }
-                : { success: false, error: { issues: [{ path: [], message: `apiKey must be $VAR or \${VAR}` }] } }
-            : schema.safeParse(candidate);
+                : schema.safeParse(candidate);
     if (!parsed.success) {
         const lines = parsed.error.issues
             .map((i) => {
@@ -273,6 +287,42 @@ function rejectApiKeyPath(path, dotted) {
     throw new UsageError(`apiKey cannot be persisted in config; export ${recipe} instead. (key: ${dotted})`, "INVALID_FLAG_VALUE", "Storing API keys in config.json leaks them through backups, logs, and version control. " +
         "Use the corresponding environment variable. AKM reads it at request time.");
 }
+function rejectLiteralApiKeyInWholeObjectSet(path, raw, dotted) {
+    const isWholeEngineSet = path[0] === "engines" && path.length === 2;
+    const isWholeEmbeddingSet = path.length === 1 && path[0] === "embedding";
+    if (!isWholeEngineSet && !isWholeEmbeddingSet)
+        return;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return; // Malformed JSON — the caller's own parse/coercion reports this.
+    }
+    if (!isRecord(parsed) || typeof parsed.apiKey !== "string")
+        return;
+    if (isApiKeyReference(parsed.apiKey))
+        return;
+    throw new UsageError(`apiKey cannot be persisted in config; export ${recipeForApiKey([...path, "apiKey"], `${dotted}.apiKey`)} instead. (key: ${dotted}.apiKey)`, "INVALID_FLAG_VALUE", "Storing API keys in config.json leaks them through backups, logs, and version control. " +
+        "Use the corresponding environment variable. AKM reads it at request time.");
+}
+function rejectRegistryCredentialValue(value, dotted) {
+    const entries = Array.isArray(value) ? value : [value];
+    for (const entry of entries) {
+        const url = isRecord(entry) && typeof entry.url === "string" ? entry.url : undefined;
+        if (url && hasRegistryUrlCredentials(url)) {
+            throw new UsageError(`${REGISTRY_CREDENTIALS_UNSUPPORTED} (key: ${dotted})`, "INVALID_FLAG_VALUE", REGISTRY_CREDENTIALS_UNSUPPORTED);
+        }
+    }
+}
+function bestEffortJsonValue(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return raw;
+    }
+}
 function parseObjectPatch(raw, key) {
     try {
         const value = JSON.parse(raw);

package/dist/core/config/config.js

@@ -5,14 +5,17 @@ import fs from "node:fs";
 import path from "node:path";
 import { ConfigError } from "../errors.js";
 import { liftLegacyEngineExtraParams } from "../extra-params.js";
+import { formatRegistryLabel, hasRegistryUrlCredentials } from "../registry-url.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 { upgradeConfigVersion } from "./config-version-shim.js";
 import { deepMergeConfig } from "./deep-merge.js";
+import { migrateLegacySourceShape } from "./legacy-source-shape-shim.js";
+import { isApiKeyReference, SECRET_STORE_REFERENCE_PATTERN } from "./schema/primitives.js";
 export { stripJsonComments } from "./config-io.js";
 import { getConfigPath } from "../paths.js";
-import { warn } from "../warn.js";
+import { warn, warnOnce } from "../warn.js";
 // Canonical harness-id source of truth (#565) — runtime value re-export.
 export { VALID_HARNESS_IDS } from "./config-types.js";
 // ── Feedback failure-mode constants (F-3 / #384) ────────────────────────────
@@ -145,7 +148,8 @@ export function acquireConfigReadFence() {
  * is validated.
  */
 export function parseAndValidateConfigText(text, sourcePath) {
-    const parsedRaw = upgradeConfigVersion(parseConfigText(text, sourcePath), sourcePath);
+    const versioned = upgradeConfigVersion(parseConfigText(text, sourcePath), sourcePath);
+    const parsedRaw = migrateLegacySourceShape(versioned, sourcePath);
     // #852 (following #815): a config still using legacy `extraParams` keys —
     // e.g. `reasoning_effort`, a documented 0.9.1 workaround — needs to be
     // rewritten onto the first-class engine field they now shadow. This used
@@ -155,7 +159,7 @@ export function parseAndValidateConfigText(text, sourcePath) {
     // config that has not been migrated yet fails closed here instead of
     // silently drifting from what's on disk.
     const where = sourcePath ? ` at ${sourcePath}` : "";
-    const { lifted, conflicts } = liftLegacyEngineExtraParams(parsedRaw);
+    const { config: liftedConfig, lifted, conflicts } = liftLegacyEngineExtraParams(parsedRaw);
     if (conflicts.length > 0) {
         const lines = conflicts
             .map((c) => `  - engines.${c.engine}.extraParams.${c.key} (${JSON.stringify(c.extraParamsValue)}) conflicts with engines.${c.engine}.${c.field} (${JSON.stringify(c.fieldValue)})`)
@@ -163,9 +167,9 @@ export function parseAndValidateConfigText(text, sourcePath) {
         throw new ConfigError(`Invalid config${where}: extraParams and the first-class field disagree:\n${lines}\n\nEach extraParams key above has a first-class equivalent and akm will not guess which value you meant — remove the extraParams entry once the field carries the value you want.`, "INVALID_CONFIG_FILE");
     }
     if (lifted.length > 0) {
-        throw new ConfigError(`Config${where} uses deprecated extraParams keys with first-class equivalents:\n  - ${lifted.join("\n  - ")}\n\nRun \`akm migrate apply\` to rewrite the config file, or move the values onto the first-class fields yourself.`, "INVALID_CONFIG_FILE");
+        warnOnce(`config:extra-params-lift${sourcePath ? `:${sourcePath}` : ""}`, `Config${where} uses deprecated extraParams keys with first-class equivalents — auto-lifted in memory:\n  - ${lifted.join("\n  - ")}\n\nRun \`akm migrate apply\` to rewrite the config file and silence this warning.`);
     }
-    const parsed = AkmConfigSchema.safeParse(parsedRaw);
+    const parsed = AkmConfigSchema.safeParse(liftedConfig);
     if (!parsed.success) {
         const lines = parsed.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
         throw new ConfigError(`Invalid config${where}:\n${lines}`, "INVALID_CONFIG_FILE");
@@ -296,7 +300,7 @@ export function sanitizeConfigForWrite(config) {
     const stripped = [];
     if (config.embedding?.apiKey !== undefined) {
         const apiKey = config.embedding.apiKey;
-        if (isEnvReference(apiKey)) {
+        if (isApiKeyReference(apiKey)) {
             // Preserve reference verbatim — not a secret.
             sanitized.embedding = { ...config.embedding };
         }
@@ -313,7 +317,7 @@ export function sanitizeConfigForWrite(config) {
     if (config.engines) {
         const engines = {};
         for (const [name, engine] of Object.entries(config.engines)) {
-            if (engine.kind !== "llm" || engine.apiKey === undefined || isEnvReference(engine.apiKey)) {
+            if (engine.kind !== "llm" || engine.apiKey === undefined || isApiKeyReference(engine.apiKey)) {
                 engines[name] = { ...engine };
                 continue;
             }
@@ -327,21 +331,30 @@ export function sanitizeConfigForWrite(config) {
     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/reference/data-and-telemetry.md.`);
     }
+    if (config.registries) {
+        const droppedRegistries = [];
+        const registries = config.registries.filter((entry) => {
+            if (!hasRegistryUrlCredentials(entry.url))
+                return true;
+            droppedRegistries.push(formatRegistryLabel(entry));
+            return false;
+        });
+        if (droppedRegistries.length > 0) {
+            sanitized.registries = registries;
+            warn(`Config sanitizer dropped registry entr${droppedRegistries.length === 1 ? "y" : "ies"} with URL credentials before writing to disk:\n  - ${droppedRegistries.join("\n  - ")}\n\nRegistry URLs must be credential-free; configure a credential-free HTTPS endpoint.`);
+        }
+    }
     return sanitized;
 }
-/** Matches the only 0.9 symbolic secret forms: `${VAR}` or `$VAR`. */
-function isEnvReference(value) {
-    return /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$|^\$[A-Za-z_][A-Za-z0-9_]*$/.test(value);
-}
 export function updateConfig(partial) {
     return mutateConfig((current) => deepMergeConfig(current, partial)).config;
 }
-// ── Helpers ─────────────────────────────────────────────────────────────────
 /**
- * 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.
+ * Resolve a single secret value: expand `${VAR}` / `$VAR` against
+ * `process.env`, or look up `secret://<name>` via `resolveFromStore`. 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.
  *
  * Returns the input unchanged when no substitution markers are present, so
  * literal API key strings (already-resolved secrets) are zero-cost.
@@ -349,12 +362,24 @@ export function updateConfig(partial) {
  * Other config string values (URLs, endpoints, model names, prompts) are
  * preserved verbatim on read — only fields explicitly routed through this
  * helper are expanded.
+ *
+ * A `secret://<name>` value that fails to resolve throws `ConfigError`
+ * (naming the ref, never the secret) rather than silently sending an unusable
+ * credential.
  */
-export function resolveSecret(value) {
+export function resolveSecret(value, resolveFromStore) {
     if (value === undefined)
         return undefined;
     if (typeof value !== "string")
         return value;
+    const storeRef = SECRET_STORE_REFERENCE_PATTERN.exec(value)?.[1];
+    if (storeRef !== undefined) {
+        const resolved = resolveFromStore?.(storeRef) ?? null;
+        if (resolved === null) {
+            throw new ConfigError(`Secret store reference "${value}" did not resolve to a stored value.`, "SECRET_REFERENCE_UNRESOLVED");
+        }
+        return resolved;
+    }
     if (!value.includes("$"))
         return value;
     return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (_match, braced, bare) => {

package/dist/core/config/legacy-source-shape-shim.js

@@ -0,0 +1,79 @@
+import { isBundleSlug } from "../asset/asset-ref.js";
+import { warnOnce } from "../warn.js";
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const DEFAULT_WRITABLE_BY_TYPE = {
+    filesystem: true,
+    git: false,
+    website: false,
+    npm: false,
+};
+function bundleFromLegacySource(entry, index) {
+    if (!isPlainRecord(entry))
+        return undefined;
+    const type = typeof entry.type === "string" ? entry.type : undefined;
+    const bundle = {};
+    switch (type) {
+        case "filesystem":
+            if (typeof entry.path !== "string" || !entry.path)
+                return undefined;
+            bundle.path = entry.path;
+            break;
+        case "git":
+            if (typeof entry.url !== "string" || !entry.url)
+                return undefined;
+            bundle.git = entry.url;
+            break;
+        case "website":
+            if (typeof entry.url !== "string" || !entry.url)
+                return undefined;
+            bundle.website = { url: entry.url };
+            break;
+        case "npm": {
+            const spec = typeof entry.url === "string" && entry.url ? entry.url : entry.path;
+            if (typeof spec !== "string" || !spec)
+                return undefined;
+            bundle.npm = spec;
+            break;
+        }
+        default:
+            return undefined;
+    }
+    const writable = typeof entry.writable === "boolean" ? entry.writable : DEFAULT_WRITABLE_BY_TYPE[type ?? ""];
+    if (writable !== undefined)
+        bundle.writable = writable;
+    if (typeof entry.enabled === "boolean")
+        bundle.enabled = entry.enabled;
+    const name = typeof entry.name === "string" ? entry.name : undefined;
+    const key = name && isBundleSlug(name) ? name : `source-${index + 1}`;
+    return [key, bundle];
+}
+export function migrateLegacySourceShape(raw, sourcePath) {
+    const hasStashDir = typeof raw.stashDir === "string" && raw.stashDir.trim().length > 0;
+    const hasSources = Array.isArray(raw.sources) && raw.sources.length > 0;
+    const hasInstalled = "installed" in raw && raw.installed !== undefined;
+    if (!hasStashDir && !hasSources && !hasInstalled)
+        return raw;
+    const { stashDir: _stashDir, sources: _sources, installed: _installed, ...rest } = raw;
+    const bundles = isPlainRecord(rest.bundles) ? { ...rest.bundles } : {};
+    let defaultBundle = typeof rest.defaultBundle === "string" ? rest.defaultBundle : undefined;
+    if (hasStashDir) {
+        bundles.stash = { path: raw.stashDir, writable: true };
+        defaultBundle ??= "stash";
+    }
+    if (hasSources) {
+        raw.sources.forEach((entry, index) => {
+            const converted = bundleFromLegacySource(entry, index);
+            if (!converted)
+                return;
+            const [key, bundle] = converted;
+            bundles[key] = bundle;
+            defaultBundle ??= key;
+        });
+    }
+    const droppedKeys = [hasStashDir && "stashDir", hasSources && "sources", hasInstalled && "installed"].filter(Boolean);
+    const where = sourcePath ? ` at ${sourcePath}` : "";
+    warnOnce(`legacy-source-shape${sourcePath ? `:${sourcePath}` : ""}`, `Config${where} uses the retired ${droppedKeys.join("/")} shape — auto-migrated in memory to \`bundles\`/\`defaultBundle\`. Run \`akm migrate apply\` to rewrite the config file and silence this warning.`);
+    return { ...rest, bundles, ...(defaultBundle !== undefined ? { defaultBundle } : {}) };
+}

package/dist/core/config/schema/embedding.js

@@ -6,7 +6,7 @@
  * `config-schema.ts` monolith — no behavior change.
  */
 import { z } from "zod";
-import { ENV_REFERENCE_PATTERN, positiveInt } from "./primitives.js";
+import { positiveInt, symbolicOrWarnApiKey } from "./primitives.js";
 const EmbeddingOllamaOptionsSchema = z
     .object({
     num_ctx: positiveInt.optional(),
@@ -26,7 +26,7 @@ export const EmbeddingConnectionConfigSchema = z
     provider: z.string().optional(),
     endpoint: z.string().optional(),
     model: z.string().optional(),
-    apiKey: z.string().regex(ENV_REFERENCE_PATTERN, `apiKey must be $VAR or \${VAR}`).optional(),
+    apiKey: symbolicOrWarnApiKey("embedding.apiKey").optional(),
     // Bounded to the index schema's own vec-table guard (1–4096,
     // storage/repositories/index-schema.ts) so an out-of-range dimension
     // fails at config validation with a clear message instead of crashing

package/dist/core/config/schema/engines.js

@@ -15,7 +15,7 @@ import { z } from "zod";
 // a config-schema ↔ config-types type cycle that collapses inference.
 import { HARNESS_AGENT_DISPATCH_IDS, VALID_HARNESS_IDS } from "../../../integrations/harnesses/ids.js";
 import { WORKFLOW_MAX_TIMEOUT_MS } from "../../../workflows/resource-limits.js";
-import { chatCompletionsEndpoint, ENV_REFERENCE_PATTERN, ExtraParamsSchema, engineName, nonEmptyString, positiveInt, } from "./primitives.js";
+import { chatCompletionsEndpoint, ExtraParamsSchema, engineName, nonEmptyString, positiveInt, symbolicOrWarnApiKey, } from "./primitives.js";
 /**
  * Engine-config timeouts share the workflow ceiling.
  *
@@ -67,7 +67,7 @@ const LlmEngineSchema = z
     provider: z.string().optional(),
     endpoint: chatCompletionsEndpoint,
     model: nonEmptyString,
-    apiKey: z.string().regex(ENV_REFERENCE_PATTERN, `apiKey must be $VAR or \${VAR}`).optional(),
+    apiKey: symbolicOrWarnApiKey("engines.<name>.apiKey").optional(),
     // #905: file-backed alternative to `apiKey` for hosts that refuse
     // secrets in the process environment. A plain filesystem path (`~`
     // expanded, read at dispatch) — see resolveLlmEngineUse/