akm-cli 0.9.10 → 0.9.12

package/dist/integrations/agent/engine-resolution.js

@@ -1,11 +1,14 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { deepMergeConfig } from "../../core/config/deep-merge.js";
 import { ConfigError } from "../../core/errors.js";
 import { formatExtraParamsIssue, validateExtraParams } from "../../core/extra-params.js";
 import { collectSensitiveValues } from "../../core/redaction.js";
+import { warn } from "../../core/warn.js";
 import { getHarness } from "../harnesses/index.js";
 import { DEFAULT_AGENT_TIMEOUT_MS, DEFAULT_LLM_TIMEOUT_MS } from "./config.js";
 import { getBuiltinAgentProfile } from "./profiles.js";
@@ -22,6 +25,51 @@ function envName(reference) {
     const match = /^\$(?:\{)?([A-Za-z_][A-Za-z0-9_]*)(?:\})?$/.exec(reference);
     return match?.[1];
 }
+/** Expand a leading `~` the same way `loadSetupConfigFromFile` does for `--from <file>`. */
+function expandHomePath(filePath) {
+    return filePath.startsWith("~") ? path.join(os.homedir(), filePath.slice(1)) : filePath;
+}
+/** Trim exactly one trailing newline (`\n` or `\r\n`) — never interior whitespace. */
+function trimTrailingNewline(raw) {
+    return raw.replace(/\r?\n$/, "");
+}
+/**
+ * Read a file-backed credential (#905) at the dispatch boundary. Never
+ * includes the file's content in a thrown message — only the engine name and
+ * path, so a misconfigured `apiKeyFile` cannot leak its (partial) contents
+ * into a log or error report.
+ */
+function readApiKeyFile(engineName, filePath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        const code = err instanceof Error ? err.code : undefined;
+        const reason = code === "ENOENT" ? "does not exist" : "could not be read";
+        throw new ConfigError(`Engine "${engineName}" apiKeyFile ${reason}: ${filePath}`, "INVALID_CONFIG_FILE");
+    }
+    const value = trimTrailingNewline(raw);
+    if (value.length === 0) {
+        throw new ConfigError(`Engine "${engineName}" apiKeyFile is empty: ${filePath}`, "INVALID_CONFIG_FILE");
+    }
+    return value;
+}
+/**
+ * Best-effort, non-throwing read of a file-backed credential's current value
+ * (#905), for redaction inventories and health probes that must never fail
+ * just because a value collector ran ahead of the real dispatch — a missing
+ * or empty file is reported by {@link readApiKeyFile} at the actual call.
+ */
+export function lookupApiKeyFileValue(filePath) {
+    try {
+        const value = trimTrailingNewline(fs.readFileSync(filePath, "utf8"));
+        return value.length > 0 ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function selectedEngineName(config, layers, llmOnly) {
     for (let index = layers.length - 1; index >= 0; index--) {
         const layer = layers[index];
@@ -50,6 +98,11 @@ function resolveCredential(name, engine, config) {
             throw new ConfigError(`Engine "${name}" has an invalid symbolic apiKey reference.`, "INVALID_CONFIG_FILE");
         return { names: [explicit], required: true };
     }
+    // #905: an explicit apiKeyFile is its own credential source — resolved
+    // separately onto `ResolvedLlmUse.apiKeyFile` — so it does not also fall
+    // through to the implicit AKM_ENGINE_<NAME>_API_KEY convention below.
+    if (ownValue(engine, "apiKeyFile") !== undefined)
+        return undefined;
     const specific = `AKM_ENGINE_${name.toUpperCase().replaceAll("-", "_")}_API_KEY`;
     const defaults = ownValue(config, "defaults");
     return (defaults ? ownValue(defaults, "llmEngine") : undefined) === name
@@ -81,6 +134,20 @@ export function resolveCredentialFromEnv(credential, envSource = process.env) {
     }
     return undefined;
 }
+/**
+ * The enforcing credential seam for one resolved LLM engine or SDK fallback
+ * (#905): the symbolic env-var descriptor first (throws if a required one is
+ * missing), then the file-backed alternative when no env descriptor applies.
+ * Call this once per operation — lease acquisition, or direct materialize —
+ * so a whole operation observes one stable credential value instead of
+ * re-reading the file on every dispatch within it.
+ */
+export function resolveLlmCredentialValue(engine, credential, apiKeyFile, envSource = process.env) {
+    const envValue = resolveCredentialFromEnv(credential, envSource);
+    if (envValue !== undefined)
+        return envValue;
+    return apiKeyFile !== undefined ? readApiKeyFile(engine, apiKeyFile) : undefined;
+}
 /** Collect materialized engine credentials for output and persistence redaction. */
 export function collectEngineCredentialValues(config, envSource = process.env) {
     const values = new Set();
@@ -92,6 +159,15 @@ export function collectEngineCredentialValues(config, envSource = process.env) {
             if (value)
                 values.add(value);
         }
+        // #905: file-backed credential — best-effort, so a broken apiKeyFile on
+        // one engine never stops redaction from collecting every other engine's
+        // credential too.
+        const apiKeyFile = ownValue(engine, "apiKeyFile");
+        if (apiKeyFile !== undefined) {
+            const value = lookupApiKeyFileValue(expandHomePath(apiKeyFile));
+            if (value)
+                values.add(value);
+        }
     }
     return collectSensitiveValues(values);
 }
@@ -130,7 +206,20 @@ export function resolveLlmEngineUse(config, layers, options = {}) {
     }
     const engine = resolveEngineConfig(name, config);
     if (engine.kind !== "llm") {
-        throw new ConfigError(`Engine "${name}" is not an LLM engine.`, "INVALID_CONFIG_FILE");
+        const defaults = ownValue(config, "defaults");
+        const fallbackName = ownValue(engine, "llmEngine") ?? (defaults ? ownValue(defaults, "llmEngine") : undefined);
+        const fallbackEngine = fallbackName ? resolveEngineConfig(fallbackName, config) : undefined;
+        if (!fallbackEngine || fallbackEngine.kind !== "llm") {
+            if (options.optional)
+                return undefined;
+            throw new ConfigError(fallbackName
+                ? `Engine "${name}" is not an LLM engine, and its llmEngine fallback "${fallbackName}" is not one either.`
+                : `Engine "${name}" is not an LLM engine, and has no llmEngine fallback configured.`, "INVALID_CONFIG_FILE");
+        }
+        warn(`[akm] Engine "${name}" is an agent engine, not an LLM engine; using its llmEngine "${fallbackName}" instead.`);
+        return options.optional
+            ? resolveLlmEngineUse(config, [{ engine: fallbackName }], { optional: true })
+            : resolveLlmEngineUse(config, [{ engine: fallbackName }]);
     }
     let connection = rawLlmConnection(engine);
     for (const layer of layers) {
@@ -145,14 +234,22 @@ export function resolveLlmEngineUse(config, layers, options = {}) {
         if (connection[key] === undefined)
             delete connection[key];
     }
+    const apiKeyFile = ownValue(engine, "apiKeyFile");
     return {
         engine: name,
         connection: sterileRecord(connection),
         credential: resolveCredential(name, engine, config),
+        ...(apiKeyFile !== undefined ? { apiKeyFile: expandHomePath(apiKeyFile) } : {}),
         timeoutMs: effectiveTimeout(engine, layers, DEFAULT_LLM_TIMEOUT_MS),
     };
 }
-/** Read a resolved symbolic credential only at the runtime dispatch boundary. */
+/**
+ * Inject an already-resolved credential value into a connection. Callers
+ * resolve the value themselves via {@link resolveLlmCredentialValue} (or its
+ * lease-cached equivalent) — this function never reads env or disk itself, so
+ * a frozen `ResolvedLlmUse`/`RunnerSpec` plan object can be materialized
+ * repeatedly without re-triggering I/O per call.
+ */
 export function materializeLlmConnectionWithCredential(resolved, credentialValue) {
     const extraParams = ownValue(resolved.connection, "extraParams");
     if (extraParams !== undefined) {
@@ -167,9 +264,13 @@ export function materializeLlmConnectionWithCredential(resolved, credentialValue
         timeoutMs: resolved.timeoutMs,
     });
 }
-/** Read and inject one resolved symbolic credential at the runtime boundary. */
+/**
+ * Read and inject one resolved credential at the runtime boundary: the
+ * symbolic `$VAR` reference, or the file-backed alternative (#905) when the
+ * engine has no env descriptor.
+ */
 export function materializeLlmConnection(resolved, envSource = process.env) {
-    return materializeLlmConnectionWithCredential(resolved, resolveCredentialFromEnv(resolved.credential, envSource));
+    return materializeLlmConnectionWithCredential(resolved, resolveLlmCredentialValue(resolved.engine, resolved.credential, resolved.apiKeyFile, envSource));
 }
 function lowerAgentEngine(name, engine, config) {
     const harness = getHarness(engine.platform);
@@ -217,6 +318,7 @@ function lowerAgentEngine(name, engine, config) {
             ? {
                 fallbackConnection: fallback.connection,
                 ...(fallback.credential ? { fallbackCredential: fallback.credential } : {}),
+                ...(fallback.apiKeyFile ? { fallbackApiKeyFile: fallback.apiKeyFile } : {}),
                 fallbackTimeoutMs: fallback.timeoutMs,
             }
             : {}),
@@ -237,6 +339,7 @@ export function resolveEngine(name, config) {
             engine: name,
             connection: resolved.connection,
             ...(resolved.credential ? { credential: resolved.credential } : {}),
+            ...(resolved.apiKeyFile ? { apiKeyFile: resolved.apiKeyFile } : {}),
             timeoutMs: resolved.timeoutMs,
         };
     }

package/dist/integrations/agent/execution-lowering.js

@@ -210,17 +210,29 @@ function snapshotRunnerSpec(input, options = {}) {
     if (own(cloned, "timeoutMs"))
         validateTimeout(cloned.timeoutMs, "execution runner material.timeoutMs");
     if (kind === "llm") {
-        assertKeys(cloned, ["kind", "engine", "connection", "credential", "timeoutMs"], "execution runner material");
+        assertKeys(cloned, ["kind", "engine", "connection", "credential", "apiKeyFile", "timeoutMs"], "execution runner material");
         validateConnection(cloned.connection, "execution runner material.connection", !options.allowMissingLlmModel);
         if (own(cloned, "credential"))
             validateCredential(cloned.credential, "execution runner material.credential");
+        // #905: a path, not the secret itself — as safe to freeze as `credential`'s
+        // env-var name.
+        validateOptionalString(cloned, "apiKeyFile", "execution runner material");
     }
     else if (kind === "agent") {
         assertKeys(cloned, ["kind", "engine", "profile", "timeoutMs"], "execution runner material");
         validateProfile(cloned.profile, "execution runner material.profile");
     }
     else if (kind === "sdk") {
-        assertKeys(cloned, ["kind", "engine", "profile", "fallbackConnection", "fallbackCredential", "fallbackTimeoutMs", "timeoutMs"], "execution runner material");
+        assertKeys(cloned, [
+            "kind",
+            "engine",
+            "profile",
+            "fallbackConnection",
+            "fallbackCredential",
+            "fallbackApiKeyFile",
+            "fallbackTimeoutMs",
+            "timeoutMs",
+        ], "execution runner material");
         validateProfile(cloned.profile, "execution runner material.profile");
         if (own(cloned, "fallbackConnection")) {
             validateConnection(cloned.fallbackConnection, "execution runner material.fallbackConnection", !options.allowMissingSdkFallbackModel);
@@ -228,6 +240,7 @@ function snapshotRunnerSpec(input, options = {}) {
         if (own(cloned, "fallbackCredential")) {
             validateCredential(cloned.fallbackCredential, "execution runner material.fallbackCredential");
         }
+        validateOptionalString(cloned, "fallbackApiKeyFile", "execution runner material");
         if (own(cloned, "fallbackTimeoutMs")) {
             validateTimeout(cloned.fallbackTimeoutMs, "execution runner material.fallbackTimeoutMs");
         }

package/dist/integrations/agent/model-map.js

@@ -9,6 +9,7 @@ import { writeFileAtomic } from "../../core/common.js";
 import { ENGINE_NAME_PATTERN_SOURCE } from "../../core/config/engine-semantics.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { getConfigDir } from "../../core/paths.js";
+import { warnOnce } from "../../core/warn.js";
 import { cloneExecutionJsonObject } from "../../execution/json.js";
 /**
  * Installed and operator-owned model intent aliases (#802 / WP2).
@@ -218,10 +219,16 @@ export function resolveModelMapAlias(input, engine, map) {
     const profile = ownValue(tier, selectedEngine);
     if (profile !== undefined)
         return selectionFromProfile(input, profile);
-    if (tier !== undefined) {
-        throw new ConfigError(`Known alias ${JSON.stringify(input)} has no model mapping for selected engine ${JSON.stringify(engine)}.`, "INVALID_CONFIG_FILE", `Add $.aliases.${alias}.${engine} to models.json.`);
+    const knownAliasUnmappedForEngine = tier !== undefined;
+    if (knownAliasUnmappedForEngine) {
+        warnOnce(`model-map-alias-no-engine-mapping:${alias}:${selectedEngine}`, `[akm] Model alias ${JSON.stringify(input)} has no mapping for engine ${JSON.stringify(engine)}; using ${JSON.stringify(input)} as the literal model name. Add $.aliases.${alias}.${engine} to models.json to map it.`);
     }
-    return Object.freeze({ input, interpretation: "exact", model: input });
+    return Object.freeze({
+        input,
+        interpretation: "exact",
+        model: input,
+        ...(knownAliasUnmappedForEngine ? { unmappedForEngine: true } : {}),
+    });
 }
 export function userModelMapPath(env = process.env) {
     return path.join(getConfigDir(env), "models.json");
@@ -235,25 +242,24 @@ function modelMapFileError(label, filePath, action) {
  * absence; dangling links and every non-regular type are configuration errors.
  */
 function readModelMapFile(filePath, label, optional) {
-    let linkStat;
+    let targetStat;
     try {
-        linkStat = fs.lstatSync(filePath);
+        targetStat = fs.statSync(filePath);
     }
     catch (error) {
         if (optional && error?.code === "ENOENT")
             return undefined;
         throw modelMapFileError(label, filePath, optional ? "inspected" : "found");
     }
-    if (!linkStat.isFile()) {
-        throw new ConfigError(`Unable to read ${label.toLowerCase()} because it is not a readable regular file: ${filePath}.`, "INVALID_CONFIG_FILE", "Move the symlink or non-regular target aside, or replace it with a readable regular models.json file.");
+    if (!targetStat.isFile()) {
+        throw new ConfigError(`Unable to read ${label.toLowerCase()} because it is not a readable regular file: ${filePath}.`, "INVALID_CONFIG_FILE", "Replace it with a readable regular models.json file, or a symlink to one.");
     }
-    const noFollow = process.platform !== "win32" && typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
     const nonblock = process.platform !== "win32" && typeof fs.constants.O_NONBLOCK === "number" ? fs.constants.O_NONBLOCK : 0;
     let fd;
     try {
-        fd = fs.openSync(filePath, fs.constants.O_RDONLY | noFollow | nonblock);
+        fd = fs.openSync(filePath, fs.constants.O_RDONLY | nonblock);
         const openedStat = fs.fstatSync(fd);
-        if (!sameFileIdentity(linkStat, openedStat)) {
+        if (!sameFileIdentity(targetStat, openedStat)) {
             throw new ConfigError(`${label} changed while it was being opened: ${filePath}.`, "INVALID_CONFIG_FILE", "Retry after ensuring no other process is replacing models.json.");
         }
         const text = fs.readFileSync(fd, "utf8");

package/dist/integrations/agent/prompts.js

@@ -315,9 +315,18 @@ export function buildReflectPrompt(input) {
     // asset content into shorter prose, drops concrete structure, or strips
     // load-bearing frontmatter. Loud and explicit so small models follow.
     //
-    // maxOutputChars is hoisted so the return value can include it for callers
-    // on the LLM path that want to set a hard max_tokens cap on the request.
-    let maxOutputChars;
+    // Guard-audit finding 15: this used to also hand back a maxOutputChars
+    // value so an LLM-path caller could convert it into a hard `max_tokens`
+    // cap on the API request. llm/client.ts's own doc comment (and
+    // commands/improve/reflect.ts's recorded history of responses actually
+    // getting cut off) is explicit that a character-derived max_tokens causes
+    // silent truncation — a real model's output is measured in tokens, not
+    // characters, and the ratio between the two varies enough that any fixed
+    // conversion either truncates legitimate output or provides no real cap at
+    // all. The size policy below is already enforced twice more (the prompt
+    // rules the model reads, and the post-processor's own size check), so nothing
+    // is lost by not adding a THIRD, byte-derived enforcement point that can
+    // only ever cut a response off early, never usefully re-check it.
     if (input.ref && input.assetContent?.trim()) {
         // Strip frontmatter to get source body length — mirrors checkReflectSize which
         // compares body-only lengths. Inline regex avoids importing parseFrontmatter.
@@ -332,8 +341,6 @@ export function buildReflectPrompt(input) {
         const showCharBounds = sourceBodyLen >= 200;
         const minChars = Math.max(Math.round(0.5 * sourceBodyLen), 150);
         const maxChars = Math.min(Math.max(Math.round(2.5 * sourceBodyLen), 2500), 25000);
-        if (showCharBounds)
-            maxOutputChars = maxChars;
         sections.push([
             "## Content preservation rules (MUST follow)",
             "1. PRESERVE ALL concrete content: code blocks, fenced snippets, CLI commands, numbered/bulleted checklists, tables, YAML/JSON examples, file paths, configuration keys, environment variable names, and CSS/HTML selectors. These are load-bearing — do NOT replace them with prose summaries.",
@@ -353,7 +360,7 @@ export function buildReflectPrompt(input) {
         sections.push(`IMPORTANT: The JSON "ref" field is REQUIRED. It MUST be exactly: "${input.ref}"`);
     }
     sections.push(reflectResponseContract(input));
-    return { prompt: sections.join("\n\n"), ...(maxOutputChars !== undefined ? { maxOutputChars } : {}) };
+    return { prompt: sections.join("\n\n") };
 }
 /**
  * Build the prompt for `akm propose <type> <name> --task ...`. Asks the

package/dist/integrations/agent/runner-dispatch.js

@@ -20,7 +20,7 @@ import { assertNever } from "../../core/assert.js";
 import { collectSensitiveValues, isEnvPassthroughValueSafeToExpose, redactSensitiveText, redactSensitiveValue, } from "../../core/redaction.js";
 import { spawnEnvNamesFor } from "../../core/spawn-env.js";
 import { closeServer as disposeOpencodeSdkServers, opencodeSdkServerEnvironmentNames, runOpencodeSdk, } from "../harnesses/opencode-sdk/sdk-runner.js";
-import { lookupCredentialFromEnv, materializeLlmConnection, materializeLlmConnectionWithCredential, resolveCredentialFromEnv, } from "./engine-resolution.js";
+import { lookupApiKeyFileValue, lookupCredentialFromEnv, materializeLlmConnection, materializeLlmConnectionWithCredential, resolveLlmCredentialValue, } from "./engine-resolution.js";
 import { materializeLlmRunnerConnection, materializeLlmRunnerConnectionWithCredential, } from "./runner.js";
 import { runAgent } from "./spawn.js";
 const liveRunnerDispatchLeases = new WeakMap();
@@ -78,6 +78,7 @@ function runnerLeaseBinding(spec) {
                 endpoint: spec.connection.endpoint,
                 provider: spec.connection.provider ?? null,
                 credential: credentialBinding(spec.credential),
+                apiKeyFile: spec.apiKeyFile ?? null,
             });
         case "agent":
             return JSON.stringify({
@@ -99,6 +100,7 @@ function runnerLeaseBinding(spec) {
                 fallbackEndpoint: spec.fallbackConnection?.endpoint ?? null,
                 fallbackProvider: spec.fallbackConnection?.provider ?? null,
                 fallbackCredential: credentialBinding(spec.fallbackCredential),
+                fallbackApiKeyFile: spec.fallbackApiKeyFile ?? null,
             });
         default:
             return assertNever(spec);
@@ -131,8 +133,12 @@ export function acquireRunnerDispatchLease(spec, envSource = process.env) {
             return typeof property === "string" ? environment.read(property) : undefined;
         },
     });
-    const primaryCredential = spec.kind === "llm" ? resolveCredentialFromEnv(spec.credential, credentialSource) : undefined;
-    const fallbackCredential = spec.kind === "sdk" ? resolveCredentialFromEnv(spec.fallbackCredential, credentialSource) : undefined;
+    const primaryCredential = spec.kind === "llm"
+        ? resolveLlmCredentialValue(spec.engine, spec.credential, spec.apiKeyFile, credentialSource)
+        : undefined;
+    const fallbackCredential = spec.kind === "sdk"
+        ? resolveLlmCredentialValue(spec.engine, spec.fallbackCredential, spec.fallbackApiKeyFile, credentialSource)
+        : undefined;
     const handle = Object.create(null);
     Object.defineProperty(handle, "toJSON", {
         configurable: false,
@@ -217,6 +223,12 @@ export function collectDispatchSensitiveValues(spec, opts, envSource = opts.envS
         add(lookupCredentialFromEnv(spec.credential, envSource));
     if (spec.kind === "sdk")
         add(lookupCredentialFromEnv(spec.fallbackCredential, envSource));
+    // #905: a file-backed credential is read at dispatch, so it must be in the
+    // scrub set for the same reason the env-backed one is.
+    if (spec.kind === "llm" && spec.apiKeyFile)
+        add(lookupApiKeyFileValue(spec.apiKeyFile));
+    if (spec.kind === "sdk" && spec.fallbackApiKeyFile)
+        add(lookupApiKeyFileValue(spec.fallbackApiKeyFile));
     if (spec.kind !== "llm") {
         for (const value of Object.values(spec.profile.env ?? {}))
             add(value);
@@ -315,6 +327,7 @@ export async function executeRunner(spec, prompt, opts, seams = {}, lease) {
                     engine: spec.engine ?? "unnamed-sdk-fallback",
                     connection: spec.fallbackConnection,
                     ...(spec.fallbackCredential ? { credential: spec.fallbackCredential } : {}),
+                    ...(spec.fallbackApiKeyFile ? { apiKeyFile: spec.fallbackApiKeyFile } : {}),
                     timeoutMs: spec.fallbackTimeoutMs !== undefined
                         ? spec.fallbackTimeoutMs
                         : Object.hasOwn(spec.fallbackConnection, "timeoutMs")

package/dist/integrations/agent/runner.js

@@ -8,6 +8,7 @@ export function materializeLlmRunnerConnection(runner) {
         engine: runner.engine,
         connection: runner.connection,
         ...(runner.credential ? { credential: runner.credential } : {}),
+        ...(runner.apiKeyFile ? { apiKeyFile: runner.apiKeyFile } : {}),
         timeoutMs: runner.timeoutMs ?? null,
     });
 }
@@ -17,6 +18,7 @@ export function materializeLlmRunnerConnectionWithCredential(runner, credentialV
         engine: runner.engine,
         connection: runner.connection,
         ...(runner.credential ? { credential: runner.credential } : {}),
+        ...(runner.apiKeyFile ? { apiKeyFile: runner.apiKeyFile } : {}),
         timeoutMs: runner.timeoutMs ?? null,
     }, credentialValue);
 }

package/dist/integrations/lockfile.js

@@ -9,14 +9,24 @@ import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquire
 import { acquireMaintenanceBarrier } from "../core/maintenance-barrier.js";
 import { classifyPathAccess, describeInaccessiblePath } from "../core/path-access.js";
 import { getDataDir, getLockfileLockPath, getLockfilePath } from "../core/paths.js";
+import { warn } from "../core/warn.js";
 // ── Lock sentinel ────────────────────────────────────────────────────────────
-const LOCK_MAX_RETRIES = 3;
-const LOCK_RETRY_DELAY_MS = 100;
+const LOCK_ACQUIRE_TIMEOUT_MS = 30_000;
+const LOCK_RETRY_INITIAL_DELAY_MS = 50;
+const LOCK_RETRY_MAX_DELAY_MS = 1_000;
+let lockAcquireTimeoutMsForTests;
+export function _setLockAcquireTimeoutMsForTests(ms) {
+    lockAcquireTimeoutMsForTests = ms;
+}
 async function acquireLockSentinel() {
     const sentinelPath = getLockfileLockPath();
     // Ensure the directory exists before attempting to create the sentinel.
     fs.mkdirSync(path.dirname(sentinelPath), { recursive: true });
-    for (let attempt = 0; attempt < LOCK_MAX_RETRIES; attempt++) {
+    const timeoutMs = lockAcquireTimeoutMsForTests ?? LOCK_ACQUIRE_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+    let delayMs = LOCK_RETRY_INITIAL_DELAY_MS;
+    let announced = false;
+    for (;;) {
         const releaseBarrier = acquireMaintenanceBarrier();
         try {
             const ownership = tryAcquireLockSync(sentinelPath, createLockPayload());
@@ -31,12 +41,17 @@ async function acquireLockSentinel() {
         finally {
             releaseBarrier();
         }
-        // Another process holds the lock — wait briefly before retrying.
-        if (attempt < LOCK_MAX_RETRIES - 1) {
-            await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_DELAY_MS));
+        // Another process holds the lock.
+        if (Date.now() >= deadline) {
+            throw new ConfigError(`Could not acquire lockfile sentinel at ${sentinelPath} after ${(timeoutMs / 1000).toFixed(1)}s; refusing to write without exclusive ownership.`, "INVALID_CONFIG_FILE");
+        }
+        if (!announced) {
+            announced = true;
+            warn("[akm] Waiting for another akm process to release the lockfile...");
         }
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+        delayMs = Math.min(delayMs * 2, LOCK_RETRY_MAX_DELAY_MS);
     }
-    throw new ConfigError(`Could not acquire lockfile sentinel at ${sentinelPath}; refusing to write without exclusive ownership.`, "INVALID_CONFIG_FILE");
 }
 // ── Read / Write ────────────────────────────────────────────────────────────
 export function readLockfile() {

package/dist/llm/client.js

@@ -447,3 +447,19 @@ export async function probeLlmReachable(config) {
         return { reachable: false, error: err instanceof Error ? err.message : String(err) };
     }
 }
+/**
+ * Reachability probe for `akm health` (#914): one GET against the
+ * OpenAI-compatible `/models` route, bounded by `timeoutMs`. Any HTTP
+ * response counts as reachable — the question is whether the endpoint
+ * answers, not whether the route exists or the credential is right — so a
+ * cold local server is never asked to load a model just to be checked.
+ */
+export async function probeLlmEndpoint(config, timeoutMs = 3_000) {
+    try {
+        await fetch(`${config.endpoint.replace(/\/+$/, "")}/models`, { signal: AbortSignal.timeout(timeoutMs) });
+        return { reachable: true };
+    }
+    catch (err) {
+        return { reachable: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}

package/dist/llm/index-passes.js

@@ -1,7 +1,7 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { ConfigError } from "../core/errors.js";
+import { warn } from "../core/warn.js";
 import { cloneExecutionJsonObject } from "../execution/json.js";
 import { lowerResolvedExecutionRequest } from "../integrations/agent/execution-lowering.js";
 import { prepareInlineExecution } from "../integrations/agent/inline-execution.js";
@@ -48,7 +48,8 @@ export function resolveIndexPassExecution(passName, config) {
     });
     const lowered = lowerResolvedExecutionRequest(prepared.request, prepared.config);
     if (lowered.runner.kind !== "llm") {
-        throw new ConfigError(`Index pass ${JSON.stringify(passName)} requires an LLM engine; ${JSON.stringify(selectedEngine)} is not one.`, "INVALID_CONFIG_FILE");
+        warn("[akm] Index pass %s requires an LLM engine; %s is not one. Skipping this pass.", passName, selectedEngine);
+        return Object.freeze({ runner: undefined, notices: NO_LOWERING_NOTICES });
     }
     return Object.freeze({ runner: lowered.runner, notices: lowered.notices });
 }

package/dist/output/shapes/passthrough.js

@@ -3,7 +3,11 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 // #484: stamp schemaVersion + shape discriminator on passthrough envelopes so
 // third-party consumers can pin a schema version and dispatch on shape uniformly.
-// Idempotent — never overwrites an existing schemaVersion or shape field.
+// #918: also stamp `ok: true` so a caller branching on `.ok` sees the same
+// field on every success envelope that it sees on the `{ok:false,...}` error
+// envelope. Never overwrites an existing `shape`, `schemaVersion`, or `ok`;
+// a command whose exit code grades the outcome emits through
+// `outputWithExitCode` (src/cli/shared.ts), which sets `ok` from that code.
 //
 // Builds a shallow copy rather than mutating `result` in place: several
 // command results (e.g. `akm task sync --dry-run`'s `SchedulerPlanPreview`,
@@ -20,9 +24,11 @@ function makeStampHandler(command) {
         if (typeof result !== "object" || Array.isArray(result))
             return result;
         const obj = result;
-        if (obj.shape !== undefined && obj.schemaVersion !== undefined)
-            return obj;
         return {
+            // `ok` first so it heads the printed envelope instead of trailing a
+            // (possibly large) dump — the spread below still wins with `obj`'s own
+            // `ok` value when present, only its position is fixed here.
+            ok: obj.ok ?? true,
             ...obj,
             shape: obj.shape ?? command,
             schemaVersion: obj.schemaVersion ?? 1,
@@ -70,6 +76,7 @@ const PASSTHROUGH_COMMANDS = [
     "task-run",
     "task-sync",
     "task-sync-dry-run",
+    "task-validate",
     "update",
     "upgrade",
     "workflow-abandon",

package/dist/output/shapes.js

@@ -17,7 +17,7 @@
  * and throws for unknown commands (v1 spec §9 — exhaustive registry, no silent
  * fallback).
  */
-import { UsageError } from "../core/errors.js";
+import { warnOnce } from "../core/warn.js";
 import { curateShapes } from "./shapes/curate.js";
 import { envListShapes } from "./shapes/env-list.js";
 import { eventsShapes } from "./shapes/events.js";
@@ -67,12 +67,14 @@ registerOutputShapes(BUILT_IN_OUTPUT_SHAPES);
  */
 const SHAPE_SUMMARY_COMMANDS = new Set(["show"]);
 export function shapeForCommand(command, result, detail, shape = "human") {
+    let effectiveShape = shape;
     if (shape === "summary" && !SHAPE_SUMMARY_COMMANDS.has(command)) {
-        throw new UsageError(`'--shape summary' is not supported for 'akm ${command}'. It is only available on 'akm show'.`, "INVALID_SHAPE_VALUE");
+        warnOnce(`shape-summary-unsupported:${command}`, `[output] '--shape summary' is not supported for 'akm ${command}' (only 'akm show' has a summary projection); falling back to 'agent'.`);
+        effectiveShape = "agent";
     }
     const handler = getOutputShapeHandler(command);
     if (handler) {
-        return handler(result, detail, shape);
+        return handler(result, detail, effectiveShape);
     }
     // v1 spec §9 (output-shape registry exhaustive): no silent JSON.stringify
     // fallback. A missing case here is a registration bug — fail loudly so

package/dist/output/text/workflow-format.js

@@ -172,7 +172,14 @@ export function formatWorkflowRunPlain(result) {
     const run = typeof result.run === "object" && result.run !== null ? result.run : undefined;
     if (!run)
         return null;
-    const lines = [`run: ${String(run.id ?? "unknown")}`, `status: ${String(run.status ?? "unknown")}`];
+    const lines = [];
+    // #919: `workflow run <ref>` silently resuming an existing active run (the
+    // #485 concurrency guard) is now announced up front, with the escape hatch.
+    if (result.resumed === true) {
+        lines.push(`resuming existing run ${String(run.id ?? "unknown")} for ${String(run.workflowRef ?? "this ref")}; ` +
+            `pass --new to start a fresh run`);
+    }
+    lines.push(`run: ${String(run.id ?? "unknown")}`, `status: ${String(run.status ?? "unknown")}`);
     // Creation-time notices (e.g. the implicit engine fallback) must survive the
     // text renderer: JSON/YAML pass them through, and dropping them here would
     // hide the announcement from the DEFAULT output mode — where it matters most.