akm-cli 0.9.14 → 0.9.15-beta.1

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

@@ -89,6 +89,20 @@ export const DefaultsSchema = z
  */
 export const AkmConfigShape = {
     configVersion: z.literal(CURRENT_CONFIG_VERSION),
+    // #945 — fleet inheritance. A filesystem path (relative to the directory of
+    // the config file that declares it; `~` expands) or a `bundle//<path>` ref
+    // naming an already-synced local file to deep-merge underneath this config
+    // (local keys win) — the part after `//` is a plain file path relative to
+    // that bundle's content root, not an asset conceptId; it needs no asset
+    // type and is never indexed. No URL form: config load is synchronous and
+    // runs on every invocation, and akm deliberately does not fetch network
+    // resources at load time (see `registries`, never fetched until a
+    // registry-touching command runs) — a URL-backed shared config should be
+    // synced via `akm bundle add` (git/website) and referenced as
+    // `extends: bundle//<path>` once materialized locally. Resolved in
+    // `resolveExtendsChain` (./config.ts), not validated here (a bad ref
+    // surfaces as a `ConfigError` at load, naming the ref).
+    extends: nonEmptyString.optional(),
     engines: EnginesSchema.optional(),
     defaults: DefaultsSchema.optional(),
     semanticSearchMode: z.enum(["off", "auto"]).default("off"),

package/dist/core/config/config.js

@@ -2,15 +2,19 @@
 // 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/.
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { isBundleSlug } from "../asset/asset-ref.js";
+import { isRecord } from "../common.js";
 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 { bundleComponentConfig, bundleContentRoot, bundlesToSourceEntries } from "./config-sources.js";
 import { upgradeConfigVersion } from "./config-version-shim.js";
-import { deepMergeConfig } from "./deep-merge.js";
+import { deepMergeConfig, isPlainObject } 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";
@@ -139,25 +143,31 @@ export function acquireConfigReadFence() {
     }
 }
 /**
- * Parse raw config text and validate via Zod.
- * ({@link AkmConfigSchema}). Returns the merged-with-defaults AkmConfig.
- *
- * The schema accepts only the current config version. A known older version
- * is auto-upgraded in memory first (see `./config-version-shim`); anything
- * else — including anything newer — is rejected before the canonical shape
- * is validated.
+ * Run the per-file config pipeline every raw config object goes through
+ * before it is either validated (the local/top-level file) or merged in as
+ * an `extends` base: JSONC parse already done by the caller, then version
+ * shim, then legacy `stashDir`/`sources[]`/`installed[]` shim, then the
+ * legacy `extraParams` lift (#852). Shared by {@link parseAndValidateConfigText}
+ * (the local file) and {@link resolveExtendsChain} (each base in the chain) so
+ * a fleet-shared base config can carry its own old `configVersion` / legacy
+ * shape independently of the file that extends it.
  */
-export function parseAndValidateConfigText(text, sourcePath) {
+function runConfigFilePipeline(text, 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
-    // to happen silently, in memory, on every load; that ran forever and never
-    // converged. The lift itself is now `akm migrate apply`'s job (see
-    // scripts/akm-migrate/migrate/config-extra-params.ts) and persists to disk, so a
-    // config that has not been migrated yet fails closed here instead of
-    // silently drifting from what's on disk.
+    return liftExtraParamsOrThrow(parsedRaw, 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
+ * to happen silently, in memory, on every load; that ran forever and never
+ * converged. The lift itself is now `akm migrate apply`'s job (see
+ * scripts/akm-migrate/migrate/config-extra-params.ts) and persists to disk, so a
+ * config that has not been migrated yet fails closed here instead of
+ * silently drifting from what's on disk.
+ */
+function liftExtraParamsOrThrow(parsedRaw, sourcePath) {
     const where = sourcePath ? ` at ${sourcePath}` : "";
     const { config: liftedConfig, lifted, conflicts } = liftLegacyEngineExtraParams(parsedRaw);
     if (conflicts.length > 0) {
@@ -169,7 +179,22 @@ export function parseAndValidateConfigText(text, sourcePath) {
     if (lifted.length > 0) {
         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(liftedConfig);
+    return liftedConfig;
+}
+/**
+ * Resolve a local file's `extends` chain and validate the merged result
+ * (deep-merged under `DEFAULT_CONFIG`) via Zod ({@link AkmConfigSchema}).
+ * `liftedLocalRaw` must already be through {@link runConfigFilePipeline}.
+ *
+ * Split out of {@link parseAndValidateConfigText} so `mutateConfig` (#945
+ * finding: baking extends-inherited fields into the local file on every
+ * write) can build the same effective config from a `localRaw` it also
+ * keeps around, instead of only getting the final merged `AkmConfig` back.
+ */
+function buildEffectiveConfig(liftedLocalRaw, sourcePath) {
+    const withExtends = resolveExtendsChain(liftedLocalRaw, sourcePath);
+    const where = sourcePath ? ` at ${sourcePath}` : "";
+    const parsed = AkmConfigSchema.safeParse(withExtends);
     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");
@@ -182,6 +207,199 @@ export function parseAndValidateConfigText(text, sourcePath) {
     }
     return finalResult.data;
 }
+/**
+ * Parse raw config text and validate via Zod.
+ * ({@link AkmConfigSchema}). Returns the merged-with-defaults AkmConfig.
+ *
+ * The schema accepts only the current config version. A known older version
+ * is auto-upgraded in memory first (see `./config-version-shim`); anything
+ * else — including anything newer — is rejected before the canonical shape
+ * is validated. When the config sets `extends` (#945), its resolved chain is
+ * deep-merged underneath before validation — see {@link resolveExtendsChain}.
+ */
+export function parseAndValidateConfigText(text, sourcePath) {
+    const liftedConfig = runConfigFilePipeline(text, sourcePath);
+    return buildEffectiveConfig(liftedConfig, sourcePath);
+}
+/**
+ * Walk an `extends` chain starting at `localRaw` (already through
+ * {@link runConfigFilePipeline}), returning every layer from the local file
+ * outward to the chain's root, local first. A chain is allowed (a base may
+ * itself set `extends`); a cycle (a resolved source repeating) throws
+ * {@link ConfigError} instead of recursing forever.
+ */
+function collectExtendsLayers(localRaw, configPath) {
+    const layers = [{ ref: undefined, raw: localRaw }];
+    const visited = new Set(configPath ? [path.resolve(configPath)] : []);
+    let current = localRaw;
+    let currentPath = configPath;
+    while (true) {
+        const ref = current.extends;
+        if (ref === undefined)
+            return layers;
+        if (typeof ref !== "string" || !ref.trim()) {
+            throw new ConfigError(`Invalid "extends"${currentPath ? ` at ${currentPath}` : ""}: expected a non-empty string (a file path or bundle//path ref), got ${JSON.stringify(ref)}.`, "INVALID_CONFIG_FILE");
+        }
+        const { text, resolvedPath } = resolveConfigRefSource(ref, current, currentPath);
+        if (visited.has(resolvedPath)) {
+            throw new ConfigError(`Config "extends" cycle detected: "${ref}"${currentPath ? ` (from ${currentPath})` : ""} resolves back to an already-visited config at ${resolvedPath}.`, "INVALID_CONFIG_FILE");
+        }
+        visited.add(resolvedPath);
+        const baseRaw = runConfigFilePipeline(text, resolvedPath);
+        layers.push({ ref, raw: baseRaw });
+        current = baseRaw;
+        currentPath = resolvedPath;
+    }
+}
+/**
+ * Deep-merge an `extends` chain into its effective raw shape: each layer's
+ * own fields win over its base's (`deepMergeConfig` "local wins" semantics),
+ * reduced root-to-local so the local file's fields win overall. `DEFAULT_CONFIG`
+ * is NOT applied here — the caller still layers it outermost, unchanged.
+ *
+ * The merged result's `extends` field, if any, is always the LOCAL file's own
+ * literal value (never a base's) — `deepMergeConfig`'s local-wins semantics
+ * already guarantee this at every level, since a layer only has `extends` set
+ * when it itself declares one. Keeping it (rather than stripping it) lets
+ * `akm config set`/`unset` round-trip the directive: `mutateConfig` reads the
+ * effective config as `current` for the mutation, but writes back only the
+ * fields `pruneUnchangedInheritedFields` finds changed-or-already-local (#945
+ * finding — the effective object used to be baked into the local file
+ * verbatim, duplicating every inherited field into it). That pruning keys off
+ * which fields are present in `current`/`next`, so `extends` has to still be
+ * one of them or it would silently vanish from disk on the very next
+ * `config set`.
+ */
+function resolveExtendsChain(localRaw, configPath) {
+    const layers = collectExtendsLayers(localRaw, configPath);
+    let merged = {};
+    for (let i = layers.length - 1; i >= 0; i--) {
+        merged = deepMergeConfig(merged, layers[i].raw);
+    }
+    return merged;
+}
+/** `~` expands to the home directory, mirroring `apiKeyFile`'s resolution (engine-resolution.ts). */
+function expandExtendsHomePath(p) {
+    return p.startsWith("~") ? path.join(os.homedir(), p.slice(1)) : p;
+}
+/** True when `ref`'s segment before the first `//` is a legal bundle slug — the `bundle//<path>` shape, not a plain filesystem path. */
+function looksLikeBundleAssetRef(ref) {
+    const boundary = ref.indexOf("//");
+    return boundary > 0 && isBundleSlug(ref.slice(0, boundary));
+}
+/**
+ * Resolve an `extends` value (or a `config diff <ref>` CLI argument — same
+ * grammar) to its config text and the absolute path it was read from. Either
+ * a filesystem path (relative to the directory of `fromConfigPath`; `~`
+ * expands) or a `bundle//<path>` ref, where the part after `//` is a plain
+ * file path *relative to that bundle's content root* — NOT an asset
+ * conceptId. It needs no asset type (`scripts/`, `knowledge/`, …) and is
+ * never indexed; a shared config file just lives wherever the bundle puts
+ * it. No URL form and no fetch/sync — the source must already exist locally;
+ * a missing file/bundle throws {@link ConfigError} naming the ref, as does an
+ * empty, absolute, or content-root-escaping path after `//`.
+ */
+function resolveConfigRefSource(ref, context, fromConfigPath) {
+    return looksLikeBundleAssetRef(ref)
+        ? resolveConfigBundleRefSource(ref, context)
+        : resolveConfigFileRefSource(ref, fromConfigPath);
+}
+function resolveConfigFileRefSource(ref, fromConfigPath) {
+    const expanded = expandExtendsHomePath(ref);
+    let resolvedPath;
+    if (path.isAbsolute(expanded)) {
+        resolvedPath = expanded;
+    }
+    else if (fromConfigPath) {
+        resolvedPath = path.resolve(path.dirname(fromConfigPath), expanded);
+    }
+    else {
+        throw new ConfigError(`extends "${ref}" is a relative path, but the current config has no known file location to resolve it against.`, "INVALID_CONFIG_FILE");
+    }
+    const text = readConfigText(resolvedPath);
+    if (text === undefined) {
+        throw new ConfigError(`extends "${ref}" resolves to ${resolvedPath}, which does not exist. Create the file first, or point "extends" at an existing config.`, "INVALID_CONFIG_FILE");
+    }
+    return { text, resolvedPath };
+}
+function resolveConfigBundleRefSource(ref, context) {
+    // Split by hand rather than through `parseBundleRef`: the part after `//`
+    // is a plain file path here, not an asset conceptId, so it must not be run
+    // through conceptId validation (which, for instance, rejects every `..`
+    // segment outright — stricter than the "must not escape the content root"
+    // rule this function enforces itself below via `path.resolve`).
+    // `looksLikeBundleAssetRef` already confirmed `ref` has this `bundle//`
+    // shape with a legal bundle slug before routing here.
+    const boundary = ref.indexOf("//");
+    const bundleId = ref.slice(0, boundary);
+    const relativePath = ref.slice(boundary + 2);
+    if (!relativePath) {
+        throw new ConfigError(`extends "${ref}" is missing a path after "${bundleId}//".`, "INVALID_CONFIG_FILE");
+    }
+    if (path.isAbsolute(relativePath)) {
+        throw new ConfigError(`extends "${ref}" must be a path relative to bundle "${bundleId}"'s content root, not absolute.`, "INVALID_CONFIG_FILE");
+    }
+    const bundles = isRecord(context.bundles) ? context.bundles : undefined;
+    const bundleEntry = bundles?.[bundleId];
+    const bundlePath = isRecord(bundleEntry) && typeof bundleEntry.path === "string" && bundleEntry.path.length > 0
+        ? bundleEntry.path
+        : undefined;
+    if (!bundlePath || !isRecord(bundleEntry)) {
+        throw new ConfigError(`extends "${ref}" names bundle "${bundleId}", which is not a configured filesystem bundle (bundles.${bundleId}.path). Only a filesystem bundle can host an "extends" source.`, "INVALID_CONFIG_FILE");
+    }
+    let componentRoot;
+    try {
+        componentRoot = bundleComponentConfig(bundleEntry)?.root;
+    }
+    catch (err) {
+        throw new ConfigError(`extends "${ref}" names bundle "${bundleId}": ${err instanceof Error ? err.message : String(err)}`, "INVALID_CONFIG_FILE");
+    }
+    const bundleRoot = bundleContentRoot(bundlePath, componentRoot);
+    const resolvedPath = path.resolve(bundleRoot, relativePath);
+    const relativeToRoot = path.relative(bundleRoot, resolvedPath);
+    if (relativeToRoot === ".." || relativeToRoot.startsWith(`..${path.sep}`) || path.isAbsolute(relativeToRoot)) {
+        throw new ConfigError(`extends "${ref}" escapes bundle "${bundleId}"'s content root.`, "INVALID_CONFIG_FILE");
+    }
+    const text = readConfigText(resolvedPath);
+    if (text === undefined) {
+        throw new ConfigError(`extends "${ref}" resolves to ${resolvedPath}, which does not exist locally. Sync the bundle first, or point "extends" at an existing file.`, "INVALID_CONFIG_FILE");
+    }
+    return { text, resolvedPath };
+}
+/**
+ * `akm config get --show-source` (#945): which raw layer the dotted path's
+ * value comes from — `"local"` when the local file's own raw JSON sets it,
+ * `"extends:<ref>"` for the nearest chain member that sets it (the ref by
+ * which that member is reached), or `"default"` when no layer sets it
+ * (`DEFAULT_CONFIG` or schema default supplies it). Computed lazily by
+ * re-walking the raw layers on each call — no merge-time bookkeeping.
+ */
+export function getConfigValueSource(dotted) {
+    const configPath = getConfigPath();
+    const text = readConfigText(configPath);
+    if (text === undefined)
+        return "default";
+    const liftedConfig = runConfigFilePipeline(text, configPath);
+    const segments = dotted.split(".").filter((s) => s.length > 0);
+    for (const layer of collectExtendsLayers(liftedConfig, configPath)) {
+        if (hasRawPath(layer.raw, segments)) {
+            return layer.ref === undefined ? "local" : `extends:${layer.ref}`;
+        }
+    }
+    return "default";
+}
+function hasRawPath(raw, segments) {
+    let cursor = raw;
+    for (const segment of segments) {
+        if (!isRecord(cursor) || !(segment in cursor))
+            return false;
+        cursor = cursor[segment];
+    }
+    return true;
+}
+// Exposed for `akm config diff` (config-cli.ts): the `<path|bundle//ref>`
+// argument shares the exact same resolution grammar as `extends`.
+export { resolveConfigRefSource };
 /**
  * The configured stash sources as an ordered {@link SourceConfigEntry} list.
  *
@@ -229,6 +447,56 @@ export function validateCompleteConfig(config) {
     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.");
 }
+/**
+ * #945 review finding: `mutateConfig` used to write the entire extends-merged
+ * *effective* config (`next`) back to the local file on every `config
+ * set`/`unset`, duplicating every inherited `engines`/`improve.strategies`
+ * field into the local file on the very first ordinary write after adopting
+ * `extends` — defeating the feature (shared config, ≤20-line local files)
+ * and silently freezing the local copy against future upstream changes.
+ *
+ * Reduces `after` (the mutated effective config) down to only what the
+ * mutation actually changed relative to `before` (the effective config
+ * *before* the mutation), plus whatever `localRaw` — the local file's own
+ * raw content, pre-`extends`-merge — already had explicitly. Everything
+ * else that only came along for the ride from `extends`/`DEFAULT_CONFIG` is
+ * left out, so it keeps being read from the base on the next load instead
+ * of being frozen as a local literal.
+ */
+function pruneUnchangedInheritedFields(before, after, localRaw) {
+    if (!isPlainObject(after) || !isPlainObject(before))
+        return after;
+    const localRecord = isPlainObject(localRaw) ? localRaw : undefined;
+    const result = {};
+    for (const key of Object.keys(after)) {
+        const afterValue = after[key];
+        const beforeValue = before[key];
+        const localHasKey = localRecord ? Object.hasOwn(localRecord, key) : false;
+        if (isPlainObject(afterValue) && isPlainObject(beforeValue)) {
+            const pruned = pruneUnchangedInheritedFields(beforeValue, afterValue, localHasKey ? localRecord?.[key] : undefined);
+            const prunedHasContent = isPlainObject(pruned) ? Object.keys(pruned).length > 0 : pruned !== undefined;
+            if (prunedHasContent || localHasKey)
+                result[key] = pruned;
+            continue;
+        }
+        if (localHasKey || !isDeepStrictEqual(afterValue, beforeValue)) {
+            result[key] = afterValue;
+        }
+    }
+    return result;
+}
+/**
+ * What to persist for a `mutateConfig`/`mutateConfigWithPrecommit` write:
+ * the full effective `next` when the local file has no `extends` (unchanged
+ * pre-#945 behavior), otherwise only the changed-or-already-local fields
+ * (#945 finding above).
+ */
+function configWriteBody(localRaw, current, next) {
+    const usesExtends = typeof localRaw?.extends === "string" && localRaw.extends.trim().length > 0;
+    if (!usesExtends)
+        return next;
+    return pruneUnchangedInheritedFields(current, next, localRaw);
+}
 /**
  * Mutate config under one fail-closed lock spanning read, merge, validation,
  * ordinary backup, and atomic write.
@@ -241,7 +509,8 @@ export function mutateConfig(mutate, options) {
         if (text === undefined && options?.absentNoop) {
             return { config: { ...DEFAULT_CONFIG }, written: false };
         }
-        const current = text === undefined ? { ...DEFAULT_CONFIG } : parseAndValidateConfigText(text, configPath);
+        const localRaw = text === undefined ? undefined : runConfigFilePipeline(text, configPath);
+        const current = localRaw === undefined ? { ...DEFAULT_CONFIG } : buildEffectiveConfig(localRaw, configPath);
         const mutated = mutate(current);
         if (mutated === current)
             return { config: current, written: false };
@@ -249,7 +518,7 @@ export function mutateConfig(mutate, options) {
         if (text !== undefined)
             backupExistingConfig(configPath);
         fs.mkdirSync(path.dirname(configPath), { recursive: true });
-        writeConfigAtomic(configPath, sanitizeConfigForWrite(next));
+        writeConfigAtomic(configPath, sanitizeConfigForWrite(configWriteBody(localRaw, current, next)));
         return { config: next, written: true };
     });
 }
@@ -264,7 +533,8 @@ export async function mutateConfigWithPrecommit(mutate, precommit) {
     const release = acquireConfigLock();
     try {
         const text = readConfigText(configPath);
-        const current = text === undefined ? { ...DEFAULT_CONFIG } : parseAndValidateConfigText(text, configPath);
+        const localRaw = text === undefined ? undefined : runConfigFilePipeline(text, configPath);
+        const current = localRaw === undefined ? { ...DEFAULT_CONFIG } : buildEffectiveConfig(localRaw, configPath);
         const mutated = mutate(current);
         const next = validateCompleteConfig({ ...mutated, configVersion: CURRENT_CONFIG_VERSION });
         if (text !== undefined)
@@ -273,7 +543,7 @@ export async function mutateConfigWithPrecommit(mutate, precommit) {
         if (mutated === current)
             return { config: current, written: false, precommit: precommitResult };
         fs.mkdirSync(path.dirname(configPath), { recursive: true });
-        writeConfigAtomic(configPath, sanitizeConfigForWrite(next));
+        writeConfigAtomic(configPath, sanitizeConfigForWrite(configWriteBody(localRaw, current, next)));
         return { config: next, written: true, precommit: precommitResult };
     }
     finally {
@@ -383,7 +653,15 @@ export function resolveSecret(value, resolveFromStore) {
     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) => {
-        return process.env[(braced ?? bare)] ?? "";
+        const name = (braced ?? bare);
+        const resolved = process.env[name];
+        if (!resolved) {
+            // #953: an unset/empty $VAR used to substitute silently, so a gateway
+            // that enforces auth on inference (e.g. Bifrost) failed every call with
+            // an opaque 401 instead of a diagnosable warning naming the variable.
+            warnOnce(`config:empty-env-var:${name}`, `Environment variable ${name} referenced by a $VAR apiKey is unset or empty; the request will be sent without a valid credential.`);
+        }
+        return resolved ?? "";
     });
 }
 /**

package/dist/core/env-secret-ref.js

@@ -16,13 +16,60 @@ import path from "node:path";
 import { resolveSourceEntries } from "../indexer/search/search-source.js";
 import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "./asset/asset-create.js";
-import { assetPathForName } from "./asset/asset-placement.js";
+import { assetPathForName, deriveCanonicalAssetName } from "./asset/asset-placement.js";
 import { displayRef, isFullRefInput, parseRefInput } from "./asset/resolve-ref.js";
 import { isWithin } from "./common.js";
 import { loadConfig } from "./config/config.js";
 import { NotFoundError, UsageError } from "./errors.js";
 import { resolveMutationTarget } from "./mutation-target.js";
+import { sensitiveMarkerPath } from "./sensitive-marker-path.js";
 import { formatRefForMessage, withWriteTargetMutation } from "./write-source.js";
+export { sensitiveMarkerPath } from "./sensitive-marker-path.js";
+/**
+ * Walk each stash's env files and return one entry per `.env` file, using the
+ * env asset spec's canonical-name logic (e.g. `env/team/prod.env` →
+ * `env/team/prod`, `env/team/.env` → `env/team/default`). Moved here from
+ * `commands/env/env-cli.ts` (#950) so `commands/health` can reuse it to name
+ * which env asset supplies a credential's variable — pure move, `akm env
+ * list`'s behaviour is unchanged. `listKeysFn` stays injected (rather than a
+ * static import of `commands/env/env.ts`) so this core module never depends
+ * upward on the commands layer. `config` defaults to the real `loadConfig()`
+ * (unchanged default for `akm env list`); `commands/health` passes its own
+ * injected/resolved config so a test-supplied `loadConfig` seam is honoured
+ * instead of this always re-reading the real config/sources.
+ */
+export function listEnvsRecursive(listKeysFn, config = loadConfig()) {
+    const result = [];
+    for (const source of resolveSourceEntries(undefined, config)) {
+        const root = path.join(source.path, "env");
+        if (!fs.existsSync(root))
+            continue;
+        const walk = (dir) => {
+            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                const full = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    walk(full);
+                    continue;
+                }
+                if (!entry.isFile())
+                    continue;
+                if (entry.name !== ".env" && !entry.name.endsWith(".env"))
+                    continue;
+                const canonical = deriveCanonicalAssetName("env", root, full);
+                if (!canonical)
+                    continue;
+                // Skip sensitive envs: a sibling .sensitive marker file suppresses listing.
+                const markerPath = sensitiveMarkerPath(full, "env");
+                if (fs.existsSync(markerPath))
+                    continue;
+                const { keys } = listKeysFn(full);
+                result.push({ ref: makeEnvRef(canonical, source, config), path: full, keys });
+            }
+        };
+        walk(root);
+    }
+    return result;
+}
 /**
  * The `vault` asset type was removed in 0.9.0. The env/secret input path no
  * longer routes through the legacy stored-ref parser (which carries the removal
@@ -91,10 +138,17 @@ export function findEnvSource(origin, type, name) {
     }
     return named;
 }
-export function makeEnvRef(name, source) {
+/**
+ * `config` defaults to the real `loadConfig()`, same as {@link displayDefaultBundle}.
+ * `listEnvsRecursive` threads its own (possibly injected) config through here so a
+ * caller-supplied config governs ref display the same way it governs which stashes
+ * get walked — otherwise this would silently fall back to reading the real config a
+ * second time even when the walk itself honoured an injected one.
+ */
+export function makeEnvRef(name, source, config = loadConfig()) {
     // F4b output-spelling flip: `env/name` in the primary stash, `bundle//env/name`
     // for a slug-clean named source.
-    return displayRef({ type: "env", name, bundleId: source?.registryId }, displayDefaultBundle(source));
+    return displayRef({ type: "env", name, bundleId: source?.registryId }, displayDefaultBundle(source, config));
 }
 /**
  * Resolve an env ref to an absolute `.env` path. Accepts the `env/<name>`
@@ -132,8 +186,7 @@ export function makeSecretRef(name, source) {
     // `bundle//secrets/name` for a slug-clean named source.
     return displayRef({ type: "secret", name, bundleId: source?.registryId }, displayDefaultBundle(source));
 }
-function displayDefaultBundle(source) {
-    const config = loadConfig();
+function displayDefaultBundle(source, config = loadConfig()) {
     if (config.defaultBundle || !source)
         return config.defaultBundle;
     const primary = resolveSourceEntries(undefined, config)[0];

package/dist/core/errors.js

@@ -77,7 +77,11 @@ const USAGE_HINTS = {
     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.",
+};
+/** Default hint for each TransientErrorCode. */
+const TRANSIENT_HINTS = {
     RUN_LEASE_HELD: "Wait for the named engine invocation to finish or for the lease to expire, then retry. `akm workflow status <id>` shows the current lease.",
+    STATE_DB_CONTENDED: "Another akm process is writing state.db right now. Wait a few seconds and retry; commands that support --skip-if-locked can skip instead of failing.",
 };
 /** Default hint for each NotFoundError code. */
 const NOT_FOUND_HINTS = {
@@ -89,6 +93,7 @@ const NOT_FOUND_HINTS = {
     // for a mistyped id, which points at the wrong thing entirely.
     PROPOSAL_NOT_FOUND: "Run `akm proposal list` to see pending proposals and their ids.",
     FILE_NOT_FOUND: "Check the path exists and is readable.",
+    IMPROVE_RUN_NOT_FOUND: "Run `akm improve` first, or `akm improve report --since 30d` to see recent run ids in `runIds`.",
 };
 /**
  * Base class for all akm-thrown, classified errors. Carries the `kind`
@@ -131,6 +136,31 @@ export class UsageError extends AkmError {
         return this._hint ?? USAGE_HINTS[this.code];
     }
 }
+/**
+ * Raised when a condition is ordinary, retryable contention rather than a
+ * bad command line or a genuine failure — another akm process holds a lock
+ * or is writing state.db right now. Distinct from `UsageError` (#948
+ * addendum, dev-team field review 2026-09-09): schedulers classify exit 2 as
+ * "fix the command line", so contention needs its own exit code (75,
+ * sysexits EX_TEMPFAIL) a cron wrapper can branch on to retry instead of
+ * alerting.
+ */
+export class TransientError extends AkmError {
+    kind = "transient";
+    code;
+    _hint;
+    constructor(msg, code, hint) {
+        super(msg);
+        this.name = "TransientError";
+        this.code = code;
+        this._hint = hint;
+        // Fixes `instanceof` checks under ES5 transpilation targets.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    hint() {
+        return this._hint ?? TRANSIENT_HINTS[this.code];
+    }
+}
 /** Raised when a requested resource (asset, entry, file) is not found. */
 export class NotFoundError extends AkmError {
     kind = "not-found";