akm-cli 0.9.11 → 0.9.13

package/dist/indexer/passes/metadata.js

@@ -6,7 +6,7 @@ import path from "node:path";
 import { parseBundleRef } from "../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { asNonEmptyString } from "../../core/common.js";
-import { isVerbose, warn, warnVerbose } from "../../core/warn.js";
+import { isVerbose, warn } from "../../core/warn.js";
 export const SCOPE_KEYS = ["user", "agent", "run", "channel"];
 // ── Quality semantics (v1 spec §4.2) ────────────────────────────────────────
 /**
@@ -835,10 +835,17 @@ export function isEnrichmentComplete(entry) {
 // ── Native Markdown search projection ──────────────────────────────────────
 /**
  * Maximum native Markdown prose carried by the low-weight `content` field.
- * Structured fields remain separate and higher-weighted; this bound prevents
- * large documents from dominating index size or embedding inputs.
+ *
+ * Raised far past any real authored document:
+ * this used to sit at 16_384 chars, tight enough that ordinary long-form
+ * skills/knowledge docs lost their tail from both FTS and the embedding
+ * input with no visible signal (the cut was reported via `warnVerbose`,
+ * silent unless `AKM_VERBOSE` was set). The remaining bound exists only to
+ * stop a truly pathological single file (a committed data dump, a decompressed
+ * log) from ballooning index size — not to shave real content — so a caller
+ * that hits it is always told, unconditionally.
  */
-export const MARKDOWN_CONTENT_MAX_CHARS = 16_384;
+export const MARKDOWN_CONTENT_MAX_CHARS = 1_000_000;
 /**
  * Locate a leading nested frontmatter block in a body: up to three blank
  * lines, then a `---` line, closed by a later `---` line. Mirrors the
@@ -1220,7 +1227,11 @@ export function applyPreContributorFields(entry, file, ctx, pkgMeta) {
                 entry.content = contentProjection;
                 if (truncationInfo.truncated) {
                     entry.contentTruncated = true;
-                    warnVerbose(`${file}: indexed content truncated to ${MARKDOWN_CONTENT_MAX_CHARS} chars`);
+                    // Unconditional, not warnVerbose: this bound now sits far past any
+                    // real document, so tripping it means
+                    // something unusual is in the bundle and the operator should see
+                    // it without having to pass --verbose.
+                    warn(`${file}: indexed content truncated to ${MARKDOWN_CONTENT_MAX_CHARS} chars`);
                 }
             }
         }

package/dist/indexer/search/search-fields.js

@@ -1,18 +1,6 @@
 // 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/.
-/**
- * Per-field search text extraction for FTS5 indexing.
- *
- * Extracted from indexer.ts to break the circular dependency:
- *   db.ts -> indexer.ts -> db.ts
- *
- * This module imports only from metadata.ts (for the IndexDocument type),
- * so it can be safely imported by both db.ts and indexer.ts.
- */
-import { warnVerbose } from "../../core/warn.js";
-/** Structured metadata plus bounded body text supplied to embedding providers. */
-export const SEARCH_TEXT_MAX_CHARS = 8_192;
 /**
  * Return per-field search text for multi-column FTS5 indexing.
  *
@@ -90,25 +78,8 @@ export function buildSearchText(entry) {
     const structured = [fields.name, fields.description, fields.tags, fields.hints]
         .filter((field) => field.length > 0)
         .join(" ");
-    if (structured.length >= SEARCH_TEXT_MAX_CHARS) {
-        warnVerbose(`${entry.ref ?? entry.name}: search text truncated to ${SEARCH_TEXT_MAX_CHARS} chars (content dropped entirely)`);
-        return truncateUnicodeSafe(structured, SEARCH_TEXT_MAX_CHARS);
-    }
     if (!fields.content)
         return structured;
     const separator = structured ? " " : "";
-    const remaining = SEARCH_TEXT_MAX_CHARS - structured.length - separator.length;
-    if (fields.content.length > remaining) {
-        warnVerbose(`${entry.ref ?? entry.name}: search text truncated to ${SEARCH_TEXT_MAX_CHARS} chars`);
-    }
-    return `${structured}${separator}${truncateUnicodeSafe(fields.content, remaining)}`;
-}
-function truncateUnicodeSafe(text, maxChars) {
-    if (text.length <= maxChars)
-        return text;
-    let cut = text.slice(0, maxChars);
-    const lastCode = cut.charCodeAt(cut.length - 1);
-    if (lastCode >= 0xd800 && lastCode <= 0xdbff)
-        cut = cut.slice(0, -1);
-    return cut.trimEnd();
+    return `${structured}${separator}${fields.content}`;
 }

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

@@ -8,6 +8,7 @@ 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";
@@ -205,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) {

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/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

@@ -9,11 +9,12 @@
  */
 import { fetchWithTimeout, readBodyWithByteCap } from "../core/common.js";
 import { resolveSecret } from "../core/config/config.js";
-import { ENV_REFERENCE_PATTERN } from "../core/config/schema/primitives.js";
+import { isApiKeyReference } from "../core/config/schema/primitives.js";
 import { formatExtraParamsIssue, validateExtraParams } from "../core/extra-params.js";
 import { redactErrorBody, redactSensitiveText } from "../core/redaction.js";
 import { warn, warnVerbose } from "../core/warn.js";
 import { DEFAULT_LLM_TIMEOUT_MS } from "../integrations/agent/config.js";
+import { resolveSecretFromStore } from "../sources/snapshot-fetchers/secret-seam.js";
 import { emitLlmUsage, extractUsageTokens, } from "./usage-telemetry.js";
 /** Maximum length of an upstream response excerpt included in thrown errors. */
 const ERROR_BODY_MAX_LEN = 200;
@@ -264,13 +265,16 @@ async function chatCompletionAttemptOnce(config, messages, options, timeoutMs, i
             throw new Error(formatExtraParamsIssue("LLM extraParams", issue));
     }
     const headers = { "Content-Type": "application/json" };
-    // Resolve ONLY a whole-string env reference. The execution boundary normally
-    // hands us a materialized credential after resolving `$VAR` upstream, so
-    // re-running the substitution over a literal key mangled any credential
-    // containing `$` — `sk-live$ecret` lost everything from the `$` onward, and
-    // the request failed with an opaque 401. The narrow check keeps the symbolic
-    // form working for any direct caller that still passes one.
-    const resolvedKey = ENV_REFERENCE_PATTERN.test(config.apiKey ?? "") ? resolveSecret(config.apiKey) : config.apiKey;
+    // Resolve ONLY a whole-string reference ($VAR/${VAR} or secret://<name>).
+    // The execution boundary normally hands us a materialized credential after
+    // resolving the reference upstream, so re-running the substitution over a
+    // literal key mangled any credential containing `$` — `sk-live$ecret` lost
+    // everything from the `$` onward, and the request failed with an opaque
+    // 401. The narrow check keeps the symbolic form working for any direct
+    // caller that still passes one.
+    const resolvedKey = isApiKeyReference(config.apiKey ?? "")
+        ? resolveSecret(config.apiKey, resolveSecretFromStore)
+        : config.apiKey;
     if (resolvedKey) {
         headers.Authorization = `Bearer ${resolvedKey}`;
     }
@@ -447,3 +451,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/embedders/remote.js

@@ -11,6 +11,7 @@ import { fetchWithTimeout, isHttpUrl, readBodyWithByteCap } from "../../core/com
 import { resolveSecret } from "../../core/config/config.js";
 import { redactErrorBody, redactSensitiveText } from "../../core/redaction.js";
 import { warnVerbose } from "../../core/warn.js";
+import { resolveSecretFromStore } from "../../sources/snapshot-fetchers/secret-seam.js";
 /**
  * Upper bound on the number of documents in one HTTP request, independent of
  * the token budget below. Overridable via `config.batchSize`. Purely a
@@ -215,7 +216,7 @@ export class RemoteEmbedder {
     }
     buildHeaders() {
         const headers = { "Content-Type": "application/json" };
-        const resolvedKey = resolveSecret(this.config.apiKey);
+        const resolvedKey = resolveSecret(this.config.apiKey, resolveSecretFromStore);
         if (resolvedKey) {
             headers.Authorization = `Bearer ${resolvedKey}`;
         }
@@ -231,7 +232,7 @@ export class RemoteEmbedder {
      * far unredacted and uncapped, at readBodyWithByteCap's 10 MB default.
      */
     safeErrorBody(body) {
-        const resolvedKey = resolveSecret(this.config.apiKey);
+        const resolvedKey = resolveSecret(this.config.apiKey, resolveSecretFromStore);
         return redactSensitiveText(redactErrorBody(body), resolvedKey ? [resolvedKey] : []);
     }
 }

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,

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";
@@ -66,13 +66,60 @@ registerOutputShapes(BUILT_IN_OUTPUT_SHAPES);
  * for a soon-frozen contract, not a silent fallback to `human`).
  */
 const SHAPE_SUMMARY_COMMANDS = new Set(["show"]);
+// ── `results` collection alias ──────────────────────────────────────────────
+//
+// Every list-returning command names its collection differently (`hits`,
+// `items`, `proposals`, `sources`, ...) — a caller cannot write one accessor
+// across commands without a per-command lookup table, and the wrong guess
+// (`d.get("hits")` against a `curate` response) reads as "no results" rather
+// than "wrong key", with nothing in the envelope to correct it.
+//
+// This maps each list-returning command to the field already holding its
+// collection, and `withResultsAlias` below adds a `results` key pointing at
+// that SAME array (not a copy) to the shaped output — in every `--shape` /
+// `--detail` combination, `human` included, so `--shape agent` needs no
+// separate handling to "guarantee" it. A new list-returning command MUST add
+// an entry here; there is no way to detect a missed one automatically, so the
+// survey deliberately lives in this one place rather than scattered per
+// handler.
+const LIST_RESULT_COLLECTION_KEYS = {
+    search: "hits",
+    curate: "items",
+    "registry-search": "hits",
+    "proposal-list": "proposals",
+    list: "sources", // `akm bundle list`
+    "env-list": "envs",
+    "secret-list": "secrets",
+    "registry-list": "registries",
+    "workflow-list": "runs",
+    "task-history": "rows",
+    "log-list": "events", // `akm log list`
+};
+function withResultsAlias(command, shaped) {
+    const key = LIST_RESULT_COLLECTION_KEYS[command];
+    if (!key)
+        return shaped;
+    if (shaped === null || typeof shaped !== "object" || Array.isArray(shaped))
+        return shaped;
+    const obj = shaped;
+    if ("results" in obj)
+        return shaped;
+    const collection = obj[key];
+    if (!Array.isArray(collection))
+        return shaped;
+    // Same array reference as `obj[key]`, never a copy, so `results` cannot
+    // silently drift out of sync with the semantic key it aliases.
+    return { ...obj, results: collection };
+}
 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 withResultsAlias(command, 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/proposal-format.js

@@ -191,6 +191,7 @@ export function formatProposalDrainPlain(r) {
     const deferred = Array.isArray(r.deferred) ? r.deferred : [];
     const skippedByCap = Array.isArray(r.skippedByCap) ? r.skippedByCap : [];
     const staged = Array.isArray(r.staged) ? r.staged : [];
+    const failed = Array.isArray(r.failed) ? r.failed : [];
     const prefix = r.dryRun === true ? "[dry-run] " : "";
     const lines = [
         `${prefix}Drained proposal queue (strategy=${String(r.strategy ?? "?")}, policy=${policy}, applyMode=${applyMode})`,
@@ -199,10 +200,14 @@ export function formatProposalDrainPlain(r) {
         `  deferred: ${deferred.length}`,
         `  skippedByCap: ${skippedByCap.length}`,
         `  staged: ${staged.length}`,
+        `  failed: ${failed.length}`,
     ];
     for (const d of deferred) {
         lines.push(`    - ${String(d.id ?? "?")} (${String(d.reason ?? "?")})`);
     }
+    for (const f of failed) {
+        lines.push(`    ! ${String(f.id ?? "?")} (${String(f.reason ?? "?")}): ${String(f.detail ?? "?")}`);
+    }
     appendLoweringNotices(lines, r);
     return lines.join("\n").trimEnd();
 }

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.