akm-cli 0.9.14 → 0.9.15-beta.2

package/dist/commands/workflow-cli.js

@@ -11,7 +11,8 @@ import { getStringArg } from "../cli/parse-args.js";
 import { defineGroupCommand, defineJsonCommand, EXIT_CODES, output, outputWithExitCode } from "../cli/shared.js";
 import { armAbortDeadline } from "../core/abort-deadline.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../core/asset/asset-create.js";
-import { NotFoundError, UsageError } from "../core/errors.js";
+import { NotFoundError, TransientError, UsageError } from "../core/errors.js";
+import { warn } from "../core/warn.js";
 import { akmIndex } from "../indexer/indexer.js";
 import { assertWorkflowMarkdownName, createWorkflowAsset, getWorkflowTemplate } from "../workflows/authoring/authoring.js";
 import { WORKFLOW_MAX_TIMEOUT_MS } from "../workflows/ir/schema.js";
@@ -30,10 +31,16 @@ const workflowStatusCommand = defineJsonCommand({
                 "diagnostic text). Diagnostics only — step evidence stays deterministic and is unaffected.",
             default: false,
         },
+        "all-scopes": {
+            type: "boolean",
+            description: "When resolving a workflow ref (not a run id), search every scope instead of only the current one (#942).",
+            default: false,
+        },
     },
     async run({ args }) {
         const target = args.target;
         const includeUnits = args.units === true;
+        const allScopes = args["all-scopes"] === true;
         const resolvedRunId = await resolveWorkflowRunTarget(target);
         if (resolvedRunId !== undefined) {
             const result = await getWorkflowStatus(resolvedRunId, { includeUnits });
@@ -41,8 +48,9 @@ const workflowStatusCommand = defineJsonCommand({
             return;
         }
         let runs;
+        let scopeKey;
         try {
-            ({ runs } = await listWorkflowRuns({ workflowRef: target }));
+            ({ runs, scopeKey } = await listWorkflowRuns({ workflowRef: target, allScopes }));
         }
         catch (error) {
             if (!target.includes(":") && !target.includes("/")) {
@@ -51,8 +59,17 @@ const workflowStatusCommand = defineJsonCommand({
             throw error;
         }
         const mostRecent = runs[0];
-        if (!mostRecent)
+        if (!mostRecent) {
+            // #942: name the scope actually searched and point at `--all-scopes`
+            // rather than a bare "not found" — the ref-fallthrough lookup is
+            // scope-local by default, so "no runs" here means "none in THIS
+            // scope", not "none anywhere". Already searching every scope (or no
+            // real scope was filtered on) has nothing more specific to suggest.
+            if (!allScopes && scopeKey !== null) {
+                throw new NotFoundError(`No workflow runs found for ${target} in scope ${scopeKey}.`, "WORKFLOW_NOT_FOUND", `Run 'akm workflow status ${target} --all-scopes' to search every scope.`);
+            }
             throw new NotFoundError(`No workflow runs found for ${target}`, "WORKFLOW_NOT_FOUND");
+        }
         const result = await getWorkflowStatus(mostRecent.id, { includeUnits });
         output("workflow-status", result);
     },
@@ -70,12 +87,20 @@ const workflowListCommand = defineJsonCommand({
             description: "Also include child workflow runs (hidden by default, P3b)",
             default: false,
         },
+        "all-scopes": {
+            type: "boolean",
+            description: "Search every scope instead of only the current one (#942). The envelope's top-level `scopeKey` is " +
+                "`null` with this flag, otherwise the scope that was searched — so an empty `runs: []` is never " +
+                'indistinguishable from "nothing anywhere".',
+            default: false,
+        },
     },
     async run({ args }) {
         const result = await listWorkflowRuns({
             workflowRef: args.ref,
             activeOnly: args.active,
             includeChildren: args.children,
+            allScopes: args["all-scopes"],
         });
         output("workflow-list", result);
     },
@@ -145,6 +170,20 @@ const workflowCreateCommand = defineJsonCommand({
         output("workflow-create", { ok: true, ...result });
     },
 });
+/**
+ * `--skip-if-locked` (#948) eligibility: only these two named, retryable
+ * `TransientError` codes (#948 addendum — moved off UsageError, exit 75) turn
+ * a `workflow run` failure into a graceful skip — `RUN_LEASE_HELD` (another
+ * engine invocation is driving THIS run, `workflow-runs-repository.ts`'s
+ * single-driver lease) and `STATE_DB_CONTENDED` (an unrelated akm process is
+ * writing state.db right now, `core/state-db.ts`'s BEGIN IMMEDIATE retry
+ * exhaustion). Every other error — a bad flag, an unresolvable target —
+ * still fails loudly.
+ */
+const WORKFLOW_RUN_SKIP_REASONS = {
+    RUN_LEASE_HELD: "lock-held",
+    STATE_DB_CONTENDED: "state-db-contended",
+};
 const workflowRunCommand = defineJsonCommand({
     meta: {
         name: "run",
@@ -161,6 +200,13 @@ const workflowRunCommand = defineJsonCommand({
                 "(never abandons it). A workflow ref only — passing a run id with --new is a usage error.",
             default: false,
         },
+        "skip-if-locked": {
+            type: "boolean",
+            description: "If another akm process already holds this run's engine lease, or state.db is busy with another " +
+                "writer, skip gracefully (exit 0) instead of failing (exit 75). Use for high-frequency scheduled runs " +
+                "so they don't pile up failures while a longer-running invocation is in progress.",
+            default: false,
+        },
     },
     async run({ args, rawArgs }) {
         const { runWorkflowSteps } = await import("../workflows/exec/run-workflow.js");
@@ -168,6 +214,7 @@ const workflowRunCommand = defineJsonCommand({
         const maxSteps = parseIntegerFlag(getStringArg(args, "max-steps"), "--max-steps", 1);
         const maxRetries = parseIntegerFlag(getStringArg(args, "max-retries"), "--max-retries", 0);
         const timeoutMs = parseWorkflowTimeout(getStringArg(args, "timeout"));
+        const skipIfLocked = args["skip-if-locked"];
         const controller = new AbortController();
         let signalExitCode;
         const interrupt = (signal) => {
@@ -185,14 +232,31 @@ const workflowRunCommand = defineJsonCommand({
             reason: `Workflow run timed out after ${timeoutMs}ms.`,
         });
         try {
-            const result = await runWorkflowSteps({
-                target: args.target,
-                parameterFlags,
-                ...(maxSteps !== undefined ? { maxSteps } : {}),
-                ...(maxRetries !== undefined ? { maxRetries } : {}),
-                newRun: args.new,
-                signal: controller.signal,
-            });
+            let result;
+            try {
+                result = await runWorkflowSteps({
+                    target: args.target,
+                    parameterFlags,
+                    ...(maxSteps !== undefined ? { maxSteps } : {}),
+                    ...(maxRetries !== undefined ? { maxRetries } : {}),
+                    newRun: args.new,
+                    signal: controller.signal,
+                });
+            }
+            catch (err) {
+                // #948: `--skip-if-locked` extends improve's "another run already
+                // holds this" skip semantics to `workflow run`. Only these two named,
+                // retryable TransientError codes are eligible (#948 addendum — moved
+                // off UsageError) — a bad flag or malformed input still fails loudly
+                // even with the flag set.
+                if (skipIfLocked && err instanceof TransientError && WORKFLOW_RUN_SKIP_REASONS[err.code]) {
+                    const reason = WORKFLOW_RUN_SKIP_REASONS[err.code];
+                    warn(`[workflow] ${err.message} skipping (--skip-if-locked)`);
+                    output("workflow-run", { ok: true, target: args.target, skipped: { reason, message: err.message } });
+                    return;
+                }
+                throw err;
+            }
             // The abort is observed between steps, so a deadline landing in the run's
             // final bookkeeping fires on a run that then finishes. Reporting that as
             // timed out would send an operator to resume a run with nothing left to
@@ -222,7 +286,17 @@ const WORKFLOW_RUN_VALUE_FLAGS = new Set([
     "shape",
     "output",
 ]);
-const WORKFLOW_RUN_BOOLEAN_FLAGS = new Set(["quiet", "verbose", "help", "no-quiet", "no-verbose", "new", "no-new"]);
+const WORKFLOW_RUN_BOOLEAN_FLAGS = new Set([
+    "quiet",
+    "verbose",
+    "help",
+    "no-quiet",
+    "no-verbose",
+    "new",
+    "no-new",
+    "skip-if-locked",
+    "no-skip-if-locked",
+]);
 export function parseWorkflowParameterFlags(rawArgs, target) {
     const flags = [];
     let targetSeen = false;

package/dist/core/asset/markdown-fragments.js

@@ -12,6 +12,8 @@ import { createHash } from "node:crypto";
 import { markdownHeadingSlug, parseMarkdownToc } from "./markdown.js";
 export const MARKDOWN_FRAGMENT_MAX_CHARS = 1600;
 export const MARKDOWN_FRAGMENT_PREFIX = "akm-fragment-";
+export const MARKDOWN_FRAGMENT_CONTEXT_DEFAULT_MAX_CHARS = 3200;
+export const MARKDOWN_FRAGMENT_SELECTED_LABEL = "[Selected matching fragment]";
 function hash(text) {
     return createHash("sha256").update(text).digest("hex");
 }
@@ -144,3 +146,36 @@ export function splitMarkdownFragments(body, maxChars = MARKDOWN_FRAGMENT_MAX_CH
 export function fragmentForSelector(body, selector) {
     return splitMarkdownFragments(body).find((fragment) => fragment.fragmentId === selector || fragment.headingSlug === selector);
 }
+/**
+ * Assemble the document lead and selected fragment under one hard character
+ * budget. The selected match is always labelled and last. When both pieces do
+ * not fit, lead bytes are discarded before any selected-fragment bytes so the
+ * evidence that caused retrieval remains intact whenever the caller's budget
+ * can hold it.
+ */
+export function buildMarkdownLeadContext(fragments, selectedOrdinal, maxChars = MARKDOWN_FRAGMENT_CONTEXT_DEFAULT_MAX_CHARS) {
+    if (!Number.isSafeInteger(maxChars) || maxChars <= 0) {
+        throw new RangeError("Markdown fragment context maxChars must be a positive safe integer");
+    }
+    const selected = fragments[selectedOrdinal];
+    if (!selected)
+        throw new RangeError(`Markdown fragment ordinal ${selectedOrdinal} is out of range`);
+    const selectedBlock = `${MARKDOWN_FRAGMENT_SELECTED_LABEL}\n${selected.text}`;
+    if (selectedBlock.length > maxChars) {
+        return { content: selectedBlock.slice(0, maxChars), truncated: true };
+    }
+    const lead = fragments[0];
+    if (!lead || lead.ordinal === selected.ordinal)
+        return { content: selectedBlock, truncated: false };
+    const separator = "\n\n";
+    const availableLeadChars = maxChars - selectedBlock.length - separator.length;
+    if (availableLeadChars <= 0)
+        return { content: selectedBlock, truncated: true };
+    const leadText = lead.text.slice(0, availableLeadChars).trimEnd();
+    if (!leadText)
+        return { content: selectedBlock, truncated: true };
+    return {
+        content: `${leadText}${separator}${selectedBlock}`,
+        truncated: leadText.length < lead.text.length,
+    };
+}

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 ?? "";
     });
 }
 /**