akm-cli 0.9.10 → 0.9.12

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,6 +23,8 @@
 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";
 /**
@@ -175,11 +177,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 +192,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];
@@ -209,7 +217,9 @@ export function configSet(config, dotted, raw) {
             ? /^\$[A-Za-z_][A-Za-z0-9_]*$|^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(raw)
                 ? { success: true, data: value }
                 : { success: false, error: { issues: [{ path: [], message: `apiKey must be $VAR or \${VAR}` }] } }
-            : schema.safeParse(candidate);
+            : isUnknownKey
+                ? { success: true, data: value }
+                : schema.safeParse(candidate);
     if (!parsed.success) {
         const lines = parsed.error.issues
             .map((i) => {
@@ -273,6 +283,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 (/^\$[A-Za-z_][A-Za-z0-9_]*$|^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(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,16 @@ 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";
 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 +147,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 +158,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 +166,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");
@@ -327,6 +330,19 @@ 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`. */

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,12 @@ 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/
+    // materializeLlmConnectionWithCredential in integrations/agent/engine-resolution.ts.
+    apiKeyFile: nonEmptyString.optional(),
     temperature: z.number().finite().optional(),
     maxTokens: positiveInt.optional(),
     timeoutMs: timeoutMsField,
@@ -83,6 +88,17 @@ const LlmEngineSchema = z
         if (key in value)
             ctx.addIssue({ code: z.ZodIssueCode.custom, path: [key], message: `${key} is not valid on an LLM engine` });
     }
+    // #905: apiKey and apiKeyFile are two alternative ways to supply the same
+    // credential; a third (the implicit AKM_ENGINE_<NAME>_API_KEY env var) is
+    // still available when neither is set, so only the both-set case is
+    // rejected here.
+    if (value.apiKey !== undefined && value.apiKeyFile !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["apiKeyFile"],
+            message: "apiKey and apiKeyFile cannot both be set",
+        });
+    }
 });
 const AgentEngineSchema = z
     .object({
@@ -103,6 +119,7 @@ const AgentEngineSchema = z
         "provider",
         "endpoint",
         "apiKey",
+        "apiKeyFile",
         "temperature",
         "maxTokens",
         "concurrency",

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

@@ -7,6 +7,7 @@
  * change.
  */
 import { z } from "zod";
+import { warnOnce } from "../../warn.js";
 import { engineName, LlmInvocationOverridesSchema, nonEmptyString, positiveInt } from "./primitives.js";
 // ── Index / per-pass ────────────────────────────────────────────────────────
 //
@@ -53,26 +54,23 @@ export const IndexPassConfigSchema = z.preprocess((raw, ctx) => {
         return raw; // let z.object below produce the type error
     }
     const obj = raw;
+    let cleaned;
     for (const key of Object.keys(obj)) {
+        const dotted = [...(ctx.path ?? []), key].join(".");
         if (INDEX_PASS_RETIRED_KEYS.has(key)) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                message: `Retired or misplaced engine setting: \`${[...(ctx.path ?? []), key].join(".")}\` is not allowed. ` +
-                    "Select a named engine and use typed invocation fields instead.",
-            });
-            return raw;
+            warnOnce(`index-pass:retired:${dotted}`, `\`${dotted}\` is a retired engine setting and is ignored; select a named engine and use typed invocation fields instead.`);
+            cleaned ??= { ...obj };
+            delete cleaned[key];
         }
-        if (!INDEX_PASS_KNOWN_KEYS.has(key)) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                message: `Unknown key \`${[...(ctx.path ?? []), key].join(".")}\`. Per-pass entries support ` +
-                    "`engine`, `model`, `timeoutMs`, `enabled`, `llm`, `graphExtractionBatchSize`, " +
-                    "`graphExtractionIncludeTypes`, and `lazyGraphExtraction`.",
-            });
-            return raw;
+        else if (!INDEX_PASS_KNOWN_KEYS.has(key)) {
+            warnOnce(`index-pass:unknown:${dotted}`, `Unknown key \`${dotted}\` ignored. Per-pass entries support ` +
+                "`engine`, `model`, `timeoutMs`, `enabled`, `llm`, `graphExtractionBatchSize`, " +
+                "`graphExtractionIncludeTypes`, and `lazyGraphExtraction`.");
+            cleaned ??= { ...obj };
+            delete cleaned[key];
         }
     }
-    return raw;
+    return cleaned ?? raw;
 }, z
     .object({
     engine: engineName.optional(),
@@ -120,13 +118,13 @@ const IndexConfigRuntimeSchema = z.preprocess((raw, ctx) => {
     }
     if (typeof raw !== "object")
         return raw;
+    let cleaned;
     for (const [passName, value] of Object.entries(raw)) {
         if (passName === "stalenessDetection") {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                message: "Invalid `index.stalenessDetection`: the removed pass is not supported.",
-            });
-            return raw;
+            warnOnce("index:stalenessDetection", "`index.stalenessDetection` is a retired pass and is ignored.");
+            cleaned ??= { ...raw };
+            delete cleaned.stalenessDetection;
+            continue;
         }
         if (typeof value !== "object" || value === null || Array.isArray(value)) {
             ctx.addIssue({
@@ -136,7 +134,7 @@ const IndexConfigRuntimeSchema = z.preprocess((raw, ctx) => {
             return raw;
         }
     }
-    return raw;
+    return cleaned ?? raw;
 }, z
     .object({
     defaults: IndexDefaultsSchema.optional(),

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

@@ -8,6 +8,7 @@
  */
 import { z } from "zod";
 import { validateExtraParams } from "../../extra-params.js";
+import { warnOnce } from "../../warn.js";
 import { ENGINE_NAME_PATTERN_SOURCE } from "../engine-semantics.js";
 /** Persisted config schema version. Package prerelease/patch versions do not change this value. */
 export const CURRENT_CONFIG_VERSION = "0.9.0";
@@ -31,21 +32,31 @@ export const engineName = z
     .string()
     .max(63)
     .regex(ENGINE_NAME_PATTERN, "names must be lowercase kebab-case and must not begin with reserved akm-");
+export function symbolicOrWarnApiKey(label) {
+    return z.string().superRefine((value) => {
+        if (ENV_REFERENCE_PATTERN.test(value))
+            return;
+        warnOnce(`config:literal-api-key:${label}`, `A ${label} in config.json is a literal API key, not a $VAR/\${VAR} reference; using it as configured. Prefer \`akm config set ...apiKey '$VAR'\` (with the corresponding env var set) — see docs/reference/data-and-telemetry.md.`);
+    });
+}
 export const chatCompletionsEndpoint = z.string().superRefine((value, ctx) => {
+    let url;
     try {
-        const url = new URL(value);
-        if (url.protocol !== "http:" && url.protocol !== "https:") {
-            ctx.addIssue({ code: z.ZodIssueCode.custom, message: "endpoint must use http:// or https://" });
-        }
-        if (url.username || url.password || url.search || url.hash || !url.pathname.endsWith("/chat/completions")) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                message: "endpoint must be a credential-free OpenAI chat-completions URL without query or fragment",
-            });
-        }
+        url = new URL(value);
     }
     catch {
         ctx.addIssue({ code: z.ZodIssueCode.custom, message: "endpoint must be a complete URL" });
+        return;
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "endpoint must use http:// or https://" });
+        return;
+    }
+    if (url.username || url.password) {
+        warnOnce(`chatCompletionsEndpoint:userinfo:${value}`, `Config endpoint "${value}" embeds a username/password; consider moving the credential to the engine's apiKey field instead.`);
+    }
+    if (!url.pathname.endsWith("/chat/completions")) {
+        warnOnce(`chatCompletionsEndpoint:path:${value}`, `Config endpoint "${value}" does not end in /chat/completions; using it as configured.`);
     }
 });
 export const ExtraParamsSchema = z.record(z.unknown()).superRefine((value, ctx) => {

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

@@ -13,7 +13,6 @@ import { z } from "zod";
 // and, transitively, the indexer modules they delegate to).
 import { VALID_ADAPTER_IDS } from "../../adapter/adapter-ids.js";
 import { isBundleSlug } from "../../asset/asset-ref.js";
-import { hasRegistryUrlCredentials, REGISTRY_CREDENTIALS_UNSUPPORTED } from "../../registry-url.js";
 import { httpUrl, nonEmptyString, positiveInt } from "./primitives.js";
 const VALID_ADAPTER_IDS_SET = new Set(VALID_ADAPTER_IDS);
 // ── Sources / registries / installed ────────────────────────────────────────
@@ -56,11 +55,7 @@ export const SourceConfigEntrySchema = z
 });
 export const RegistryConfigEntrySchema = z
     .object({
-    url: httpUrl.superRefine((value, ctx) => {
-        if (hasRegistryUrlCredentials(value)) {
-            ctx.addIssue({ code: z.ZodIssueCode.custom, message: REGISTRY_CREDENTIALS_UNSUPPORTED });
-        }
-    }),
+    url: httpUrl,
     name: z.string().min(1).optional(),
     enabled: z.boolean().optional(),
     provider: z.string().min(1).optional(),

package/dist/core/errors.js

@@ -14,7 +14,6 @@ const CONFIG_HINTS = {
     EMBEDDING_NOT_CONFIGURED: 'Run `akm config set embedding \'{"endpoint":"...","model":"..."}\'` to enable embeddings.',
     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_BUNDLE_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_BUNDLE_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 bundle directory cannot be the filesystem root, your home directory itself, or a sensitive system path like /etc, /var, ~/.config, or ~/.ssh.",
     UNKNOWN_IMPROVE_STRATEGY: "Pass one of the listed strategy names to `--strategy`, or define it under `improve.strategies`. Names are case-sensitive.",
     EXECUTION_NOT_AUTHORIZED: "Change the selected tools or update the machine/user execution policy, then retry.",
@@ -39,7 +38,7 @@ const USAGE_HINTS = {
     INVALID_SOURCE_VALUE: "Pick one of: local, registry, all, or a configured source name.",
     INVALID_FORMAT_VALUE: "Pick one of: json, jsonl, yaml, text, md, html.",
     INVALID_DETAIL_VALUE: "Pick one of: brief, normal, full. For agent/summary projections use --shape.",
-    INVALID_SHAPE_VALUE: "Pick one of: human, agent, summary (summary is only valid on `akm show`).",
+    INVALID_SHAPE_VALUE: "Pick one of: human, agent, summary (summary falls back to agent, with a warning, on commands with no summary projection).",
     INVALID_JSON_CONFIG_VALUE: 'Quote JSON values in your shell, for example: akm config set embedding \'{"endpoint":"http://localhost:11434/v1/embeddings","model":"nomic-embed-text"}\'.',
     MISSING_OR_AMBIGUOUS_TARGET: "Use `akm bundle update --all` or pass a target like `akm bundle update npm:@scope/pkg` (not both).",
     TARGET_NOT_UPDATABLE: "Run `akm bundle list` to view your sources, then retry with one of those values.",
@@ -74,7 +73,7 @@ const USAGE_HINTS = {
     TASK_TARGET_UNSUPPORTED: "Task definitions support command, script, workflow, and shell (run:) targets; akm/command is layered by callers.",
     // P3a (docs/plans/specs/p3a-plan-v5-child-freeze.md §3.2, A-N2): the
     // complete-or-abandon policy for a stored pre-irVersion-5 run.
-    WORKFLOW_IR_VERSION_UNSUPPORTED: "Abandon the run with `akm workflow abandon <id>`, then start it again from the workflow source — pre-0.9.2 frozen plans are not re-executable.",
+    WORKFLOW_IR_VERSION_UNSUPPORTED: "Abandon the run with `akm workflow abandon <id>`, then start it again from the workflow source — a frozen plan this akm cannot execute is not re-executable in place.",
     // P3b (docs/plans/specs/p3b-child-executor.md §4.3).
     WORKFLOW_OUTPUT_INVALID: "Check each `outputs:` entry's `from:` against the step artifact it names, and its `schema:` against the value that step actually promotes.",
 };

package/dist/core/improve-result.js

@@ -27,6 +27,7 @@ const COMMON_FIELDS = [
     "coverageGaps",
     "evalCasesWritten",
     "deadUrls",
+    "deadUrlCoverage",
     "reflectsWithErrorContext",
     "memoryInference",
     "graphExtraction",
@@ -440,6 +441,7 @@ function validateCommon(value) {
         "sync",
         "terminated",
         "plan",
+        "deadUrlCoverage",
     ]) {
         if (value[field] !== undefined && !isRecord(value[field]))
             fail(`${field} must be an object`);
@@ -453,6 +455,12 @@ function validateCommon(value) {
             fail("terminated.errorMessage must be a string when present");
         }
     }
+    if (isRecord(value.deadUrlCoverage)) {
+        requireExactFields(value.deadUrlCoverage, new Set(["checked", "total", "skipped"]));
+        for (const field of ["checked", "total", "skipped"]) {
+            requireCount(value.deadUrlCoverage, field, "deadUrlCoverage");
+        }
+    }
 }
 /**
  * Per-`schemaVersion` decoders for the persisted `improve_runs.result_json`

package/dist/core/improve-types.js

@@ -49,6 +49,23 @@ export function classifyImproveAction(mode) {
             return assertNever(mode);
     }
 }
+/**
+ * #912 — skip reasons that mean infrastructure failed to run the extraction,
+ * not that a session was legitimately uninteresting. `already_extracted`,
+ * `too_short`, and `triaged_out` are the ledger and pre-filter doing their
+ * job and are deliberately excluded; `malformed_model_output` already gets
+ * its own per-session forwarding into the envelope's `warnings[]` and is
+ * excluded here to avoid double-reporting the same failure two ways.
+ *
+ * Typed against `ExtractedSessionResult["skipReason"]` so a future reason
+ * cannot be added to one union without a compiler error surfacing here.
+ */
+export const EXTRACT_INFRASTRUCTURE_SKIP_REASONS = [
+    "llm_unavailable",
+    "read_failed",
+    "exception",
+    "locked_concurrent",
+];
 /** Upper bound on retained sample refs PER reason in {@link DistillSkippedAggregate}. */
 export const DISTILL_SKIPPED_SAMPLE_CAP_PER_REASON = 3;
 /**