akm-cli 0.9.12 → 0.9.13

package/CHANGELOG.md

@@ -4,6 +4,67 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.9.13] - 2026-09-04
+
+### Added
+
+- **A stable `results` alias on every list-returning command (#922).** `search`,
+  `curate`, `proposal list`, `bundle list`, `env list`, `secret list`,
+  `registry search`, `registry list`, `workflow list`, `task history` and
+  `log list` each keep their existing semantic key (`hits`, `items`,
+  `proposals`, …) and now also expose the same array as `results`, in every
+  shape including `--shape agent`. It is the same array, not a copy. A caller
+  reading `hits` from a `curate` response previously got nothing back and could
+  reasonably read that as "no results" — there was no error and the `summary`
+  alongside it still reported that results were selected. Commands carrying
+  several heterogeneous collections (`health`, `task doctor`) are deliberately
+  excluded.
+- **Engine and embedding credentials can resolve from the secret store
+  (#917).** `apiKey` accepts `secret://<name>` alongside `$VAR` / `${VAR}`,
+  resolved through the existing store-backed resolver. A detached SessionEnd
+  hook or a cron job — the two contexts least able to supply an environment
+  variable and most likely to need extraction — no longer requires editing the
+  login environment for a value akm already stores. Literal keys in
+  `config.json` are still refused, and an unresolvable reference fails loudly,
+  naming the reference and never the secret.
+- **`akm proposal drain` reports what failed (#921).** The envelope carries a
+  `failed[]` naming each proposal and why it was refused (stale target,
+  validation), instead of reporting `failed: 0` while the same run printed five
+  failures to stderr. `--dry-run` now applies the same stale-target check the
+  real run does, so its prediction stops disagreeing with the outcome. The
+  refusals themselves are correct and unchanged: declining to overwrite a target
+  modified since the proposal was created is the desired behaviour. `akm
+  improve`'s triage pre-pass reports the same count.
+- **Workflow step output is checked against its declared schema (#923).** A step
+  whose returned object does not match its `outputSchema` now says so, naming
+  the step and the specific problem (a missing required field, say). This is a
+  warning: the run continues and its status is unchanged, because a workflow is
+  a guide rather than a contract. Previously an author got neither enforcement
+  nor feedback — the only signal was a notice saying akm was not checking, which
+  is a different fact from whether the output matched.
+
+### Changed
+
+- **A held run lease no longer reports as database corruption (#924).** `akm
+  workflow run` surfaced raw SQLite text — `database is locked`, `database disk
+  image is malformed`, `disk I/O error` — for what was simply another
+  invocation holding the lease. `disk image is malformed` in particular reads as
+  data loss and sent one reporter through integrity checks and a WAL review
+  before finding the real cause. The lease message now appears at default
+  verbosity and carries a dedicated `RUN_LEASE_HELD` code, so a wrapper can tell
+  "retry shortly" from "you passed bad input". Genuine SQLite errors still
+  report as themselves.
+- **`akm lint` stops flagging templated output paths (#927).** A documented
+  run-time filename such as `reports/review-<timestamp>.md` is no longer
+  reported as a `stale-path` broken reference. Angle-bracket and brace
+  placeholders, `${VAR}`, date-format runs like `YYYYMMDD`, and glob characters
+  are all recognised as parameterised rather than missing. Genuinely broken
+  literal paths are still reported.
+- **The workflow level-2 heading rule is discoverable before you trip it
+  (#926).** The `workflow create` template states that `##` headings are step
+  ids and points at `###` for cross-cutting notes, and the compiler's rejection
+  now carries the remedy rather than only the diagnosis.
+
 ## [0.9.12] - 2026-09-03
 
 ### Added

package/dist/assets/workflows/workflow-template.md

@@ -16,6 +16,10 @@ steps:
 Free preamble prose describing what this workflow does. It is indexed for
 search and shown in `akm show`, but it is never dispatched to a step.
 
+Level-2 (`##`) headings below are step ids and must exactly match one
+declared in `steps:` above — for cross-cutting notes that aren't a step
+(shared context, prerequisites), use a level-3 (`###`) heading instead.
+
 ## first-step
 
 Describe what to do in this step. Refer to run parameters in plain

package/dist/commands/improve/improve.js

@@ -1380,6 +1380,7 @@ function finalizeImproveResult(args) {
                     promoted: triageDrain.promoted.length,
                     rejected: triageDrain.rejected.length,
                     deferred: triageDrain.deferred.length,
+                    failed: triageDrain.failed.length,
                     skippedByCap: triageDrain.skippedByCap.length,
                 },
             }

package/dist/commands/lint/base-linter.js

@@ -132,6 +132,14 @@ function fixMissingUpdated(raw, mtime) {
     return spliceFrontmatterLine(raw, `updated: ${localDateStamp(mtime)}`) ?? raw;
 }
 // ── stale-path helpers ────────────────────────────────────────────────────────
+/**
+ * A path segment shaped like a run-time filename template rather than a
+ * literal reference: `<timestamp>`-style angle brackets, `{stamp}`/`${VAR}`
+ * braces, a `YYYYMMDD`/`HHMMSS`-style run of date-format letters, or a glob
+ * character. Such a path never exists under its literal spelling, so
+ * `stale-path` skips it instead of flagging it.
+ */
+const PATH_PLACEHOLDER_PATTERN = /[<{]|[*?]|[YMDHS]{4,}/;
 function checkStalePath(body) {
     const pathRe = /(?:\/home\/|\/tmp\/|\/var\/|\/root\/|\/opt\/)[^\s"'`)\]>,\n]+/g;
     let match;
@@ -139,6 +147,8 @@ function checkStalePath(body) {
     // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex loop
     while ((match = pathRe.exec(body)) !== null) {
         const candidate = match[0];
+        if (PATH_PLACEHOLDER_PATTERN.test(candidate))
+            continue;
         if (!fs.existsSync(candidate)) {
             stale.push(candidate);
         }

package/dist/commands/proposal/drain.js

@@ -123,6 +123,42 @@ export function classifyProposal(proposal, policy, maxDiffLines) {
 function deferReasonForSource(source) {
     return source === "distill" ? "possible-dup" : "mid-band";
 }
+/**
+ * Map a thrown error's message to one of `DrainResult.failed`'s stable reason
+ * codes, falling back to `fallback` for anything not specifically recognized.
+ * Recognizes the write-time guards a proposal can trip during promotion
+ * (see repository.ts's `promoteProposalWithLease` / `preflightProposalPromotion`).
+ */
+function categorizeDrainFailure(message, fallback) {
+    if (/target (?:changed after|was created after) proposal/.test(message))
+        return "stale-target";
+    if (/failed validation:/.test(message))
+        return "validation";
+    return fallback;
+}
+function pushDrainFailure(result, id, err, fallbackReason) {
+    const message = err instanceof Error ? err.message : String(err);
+    result.failed.push({ id, reason: categorizeDrainFailure(message, fallbackReason), detail: message });
+    return message;
+}
+/**
+ * Mirror repository.ts's `promoteProposalWithLease` stale-target guard so a
+ * dry-run preflight predicts the same refusal a real promote would hit,
+ * without writing anything. `assetPath` is the path `preflightProposalPromotion`
+ * already resolved for this proposal.
+ */
+function assertProposalTargetFresh(proposal, assetPath) {
+    const backup = fs.existsSync(assetPath) ? fs.readFileSync(assetPath) : undefined;
+    const currentHash = backup ? createHash("sha256").update(backup).digest("hex") : undefined;
+    if (proposal.beforeHash !== undefined && (!backup || currentHash !== proposal.beforeHash)) {
+        throw new Error(`Proposal target changed after proposal ${proposal.id} was created; refusing to overwrite newer content.`);
+    }
+    if (proposal.beforeHash === undefined &&
+        backup !== undefined &&
+        proposal.changes.some((change) => change.op === "create")) {
+        throw new Error(`Proposal target was created after proposal ${proposal.id} was created; refusing to overwrite newer content.`);
+    }
+}
 // ---------------------------------------------------------------------------
 // Judgment tier (Phase 3)
 // ---------------------------------------------------------------------------
@@ -493,6 +529,7 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
         deferred: classification.deferred,
         skippedByCap: [],
         staged: [],
+        failed: [],
     };
     // A configured judgment runner makes every deferred item dispatch-eligible.
     // Validate its symbolic credentials before applying any deterministic gate,
@@ -518,7 +555,8 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
                 result.rejected.push(target.id);
             }
             catch (err) {
-                warn(`[triage] reject failed for ${target.id}: ${err instanceof Error ? err.message : String(err)}`);
+                const message = pushDrainFailure(result, target.id, err, "reject-error");
+                warn(`[triage] reject failed for ${target.id}: ${message}`);
             }
         }
         // --- Accept ceiling: enforced BEFORE the promote loop ---
@@ -550,13 +588,15 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
                     deterministicPromoted += 1;
                 }
                 catch (err) {
-                    warn(`[triage] promote failed for ${id}: ${err instanceof Error ? err.message : String(err)}`);
+                    const message = pushDrainFailure(result, id, err, "promote-error");
+                    warn(`[triage] promote failed for ${id}: ${message}`);
                 }
             }
         }
         else if (opts.applyMode === "promote" && opts.dryRun) {
-            // Exercise the same stamped candidate and lint boundary as real promotion.
-            // Tests that omit config retain the classification-only seam.
+            // Exercise the same stamped candidate, lint, and stale-target boundary as
+            // real promotion so a dry-run's predicted promotions match what a real
+            // run would do. Tests that omit config retain the classification-only seam.
             const byId = new Map(pending.map((proposal) => [proposal.id, proposal]));
             for (const id of withinCap) {
                 try {
@@ -564,7 +604,7 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
                         const proposal = byId.get(id);
                         if (!proposal)
                             throw new Error(`Proposal ${id} disappeared during drain preflight.`);
-                        preflightProposalPromotion(opts.config, proposal, {
+                        const preflight = preflightProposalPromotion(opts.config, proposal, {
                             ...(opts.target ? { target: opts.target } : {}),
                             gateDecision: {
                                 outcome: "auto-accepted",
@@ -572,12 +612,14 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
                                 gate: gateLabel,
                             },
                         });
+                        assertProposalTargetFresh(proposal, preflight.assetPath);
                     }
                     result.promoted.push(id);
                     deterministicPromoted += 1;
                 }
                 catch (err) {
-                    warn(`[triage] preflight failed for ${id}: ${err instanceof Error ? err.message : String(err)}`);
+                    const message = pushDrainFailure(result, id, err, "promote-error");
+                    warn(`[triage] preflight failed for ${id}: ${message}`);
                 }
             }
         }

package/dist/commands/proposal/proposal-cli.js

@@ -473,6 +473,7 @@ const proposalDrainCommand = defineJsonCommand({
             deferred: result.deferred,
             skippedByCap: result.skippedByCap,
             staged: result.staged,
+            failed: result.failed,
         });
     },
 });

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

@@ -27,6 +27,7 @@ import { hasRegistryUrlCredentials, REGISTRY_CREDENTIALS_UNSUPPORTED } from "../
 import { warnOnce } from "../warn.js";
 import { AkmConfigBaseSchema, EngineConfigSchema, listTopLevelConfigKeys } from "./config-schema.js";
 import { deepMergeConfig } from "./deep-merge.js";
+import { isApiKeyReference } from "./schema/primitives.js";
 /**
  * Parse a dotted path into segments. Empty segments are rejected. Bracket
  * notation (e.g. `sources[0]`) is NOT supported — arrays are set as JSON.
@@ -214,9 +215,12 @@ export function configSet(config, dotted, raw) {
     const parsed = path[0] === "engines" && path.length === 2
         ? EngineConfigSchema.safeParse(value)
         : symbolicApiKey
-            ? /^\$[A-Za-z_][A-Za-z0-9_]*$|^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(raw)
+            ? isApiKeyReference(raw)
                 ? { success: true, data: value }
-                : { success: false, error: { issues: [{ path: [], message: `apiKey must be $VAR or \${VAR}` }] } }
+                : {
+                    success: false,
+                    error: { issues: [{ path: [], message: "apiKey must be $VAR, ${VAR}, or secret://<name>" }] },
+                }
             : isUnknownKey
                 ? { success: true, data: value }
                 : schema.safeParse(candidate);
@@ -297,7 +301,7 @@ function rejectLiteralApiKeyInWholeObjectSet(path, raw, dotted) {
     }
     if (!isRecord(parsed) || typeof parsed.apiKey !== "string")
         return;
-    if (/^\$[A-Za-z_][A-Za-z0-9_]*$|^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(parsed.apiKey))
+    if (isApiKeyReference(parsed.apiKey))
         return;
     throw new UsageError(`apiKey cannot be persisted in config; export ${recipeForApiKey([...path, "apiKey"], `${dotted}.apiKey`)} instead. (key: ${dotted}.apiKey)`, "INVALID_FLAG_VALUE", "Storing API keys in config.json leaks them through backups, logs, and version control. " +
         "Use the corresponding environment variable. AKM reads it at request time.");

package/dist/core/config/config.js

@@ -12,6 +12,7 @@ import { bundlesToSourceEntries } from "./config-sources.js";
 import { upgradeConfigVersion } from "./config-version-shim.js";
 import { deepMergeConfig } from "./deep-merge.js";
 import { migrateLegacySourceShape } from "./legacy-source-shape-shim.js";
+import { isApiKeyReference, SECRET_STORE_REFERENCE_PATTERN } from "./schema/primitives.js";
 export { stripJsonComments } from "./config-io.js";
 import { getConfigPath } from "../paths.js";
 import { warn, warnOnce } from "../warn.js";
@@ -299,7 +300,7 @@ export function sanitizeConfigForWrite(config) {
     const stripped = [];
     if (config.embedding?.apiKey !== undefined) {
         const apiKey = config.embedding.apiKey;
-        if (isEnvReference(apiKey)) {
+        if (isApiKeyReference(apiKey)) {
             // Preserve reference verbatim — not a secret.
             sanitized.embedding = { ...config.embedding };
         }
@@ -316,7 +317,7 @@ export function sanitizeConfigForWrite(config) {
     if (config.engines) {
         const engines = {};
         for (const [name, engine] of Object.entries(config.engines)) {
-            if (engine.kind !== "llm" || engine.apiKey === undefined || isEnvReference(engine.apiKey)) {
+            if (engine.kind !== "llm" || engine.apiKey === undefined || isApiKeyReference(engine.apiKey)) {
                 engines[name] = { ...engine };
                 continue;
             }
@@ -345,19 +346,15 @@ export function sanitizeConfigForWrite(config) {
     }
     return sanitized;
 }
-/** Matches the only 0.9 symbolic secret forms: `${VAR}` or `$VAR`. */
-function isEnvReference(value) {
-    return /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$|^\$[A-Za-z_][A-Za-z0-9_]*$/.test(value);
-}
 export function updateConfig(partial) {
     return mutateConfig((current) => deepMergeConfig(current, partial)).config;
 }
-// ── Helpers ─────────────────────────────────────────────────────────────────
 /**
- * Resolve a single secret value by expanding `${VAR}` / `$VAR` references
- * against `process.env`. Use this at apiKey /
- * authorization-header consumption sites (LLM client, embedder, agent SDK
- * runner) — NOT on the load path. Non-string inputs pass through unchanged.
+ * Resolve a single secret value: expand `${VAR}` / `$VAR` against
+ * `process.env`, or look up `secret://<name>` via `resolveFromStore`. Use this
+ * at apiKey / authorization-header consumption sites (LLM client, embedder,
+ * agent SDK runner) — NOT on the load path. Non-string inputs pass through
+ * unchanged.
  *
  * Returns the input unchanged when no substitution markers are present, so
  * literal API key strings (already-resolved secrets) are zero-cost.
@@ -365,12 +362,24 @@ export function updateConfig(partial) {
  * Other config string values (URLs, endpoints, model names, prompts) are
  * preserved verbatim on read — only fields explicitly routed through this
  * helper are expanded.
+ *
+ * A `secret://<name>` value that fails to resolve throws `ConfigError`
+ * (naming the ref, never the secret) rather than silently sending an unusable
+ * credential.
  */
-export function resolveSecret(value) {
+export function resolveSecret(value, resolveFromStore) {
     if (value === undefined)
         return undefined;
     if (typeof value !== "string")
         return value;
+    const storeRef = SECRET_STORE_REFERENCE_PATTERN.exec(value)?.[1];
+    if (storeRef !== undefined) {
+        const resolved = resolveFromStore?.(storeRef) ?? null;
+        if (resolved === null) {
+            throw new ConfigError(`Secret store reference "${value}" did not resolve to a stored value.`, "SECRET_REFERENCE_UNRESOLVED");
+        }
+        return resolved;
+    }
     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) => {

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

@@ -28,15 +28,21 @@ export const httpUrl = z.string().refine((v) => v.startsWith("http://") || v.sta
 });
 const ENGINE_NAME_PATTERN = new RegExp(ENGINE_NAME_PATTERN_SOURCE);
 export const ENV_REFERENCE_PATTERN = /^\$[A-Za-z_][A-Za-z0-9_]*$|^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/;
+/** `secret://<name>` — an apiKey reference into the akm secret store, resolved via `resolveSecretFromStore`. */
+export const SECRET_STORE_REFERENCE_PATTERN = /^secret:\/\/(.+)$/;
 export const engineName = z
     .string()
     .max(63)
     .regex(ENGINE_NAME_PATTERN, "names must be lowercase kebab-case and must not begin with reserved akm-");
+/** The two symbolic apiKey forms akm accepts: an env-var reference or a secret-store reference. Never matches a literal key. */
+export function isApiKeyReference(value) {
+    return ENV_REFERENCE_PATTERN.test(value) || SECRET_STORE_REFERENCE_PATTERN.test(value);
+}
 export function symbolicOrWarnApiKey(label) {
     return z.string().superRefine((value) => {
-        if (ENV_REFERENCE_PATTERN.test(value))
+        if (isApiKeyReference(value))
             return;
-        warnOnce(`config:literal-api-key:${label}`, `A ${label} in config.json is a literal API key, not a $VAR/\${VAR} reference; using it as configured. Prefer \`akm config set ...apiKey '$VAR'\` (with the corresponding env var set) — see docs/reference/data-and-telemetry.md.`);
+        warnOnce(`config:literal-api-key:${label}`, `A ${label} in config.json is a literal API key, not a $VAR/\${VAR}/secret:// reference; using it as configured. Prefer \`akm config set ...apiKey '$VAR'\` (with the corresponding env var set) or \`secret://<name>\` (with \`akm secret set <name> ...\`) — see docs/reference/data-and-telemetry.md.`);
     });
 }
 export const chatCompletionsEndpoint = z.string().superRefine((value, ctx) => {

package/dist/core/errors.js

@@ -17,6 +17,7 @@ const CONFIG_HINTS = {
     UNSAFE_STASH_DIR: "Choose a path inside your home directory (e.g. ~/akm) or another empty workspace. The bundle directory cannot be the filesystem root, your home directory itself, or a sensitive system path like /etc, /var, ~/.config, or ~/.ssh.",
     UNKNOWN_IMPROVE_STRATEGY: "Pass one of the listed strategy names to `--strategy`, or define it under `improve.strategies`. Names are case-sensitive.",
     EXECUTION_NOT_AUTHORIZED: "Change the selected tools or update the machine/user execution policy, then retry.",
+    SECRET_REFERENCE_UNRESOLVED: "Check the secret exists (`akm secret list`) and the name after `secret://` matches, or run `akm secret set <name> <value>` to store it.",
 };
 // Code-review finding: COMPOSITION_INVALID covers several unrelated causes
 // (a rejected with:, a multi-job source, a composition cycle/depth/size
@@ -76,6 +77,7 @@ const USAGE_HINTS = {
     WORKFLOW_IR_VERSION_UNSUPPORTED: "Abandon the run with `akm workflow abandon <id>`, then start it again from the workflow source — a frozen plan this akm cannot execute is not re-executable in place.",
     // P3b (docs/plans/specs/p3b-child-executor.md §4.3).
     WORKFLOW_OUTPUT_INVALID: "Check each `outputs:` entry's `from:` against the step artifact it names, and its `schema:` against the value that step actually promotes.",
+    RUN_LEASE_HELD: "Wait for the named engine invocation to finish or for the lease to expire, then retry. `akm workflow status <id>` shows the current lease.",
 };
 /** Default hint for each NotFoundError code. */
 const NOT_FOUND_HINTS = {

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}`;
     }

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/output/shapes.js

@@ -66,6 +66,51 @@ 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)) {
@@ -74,7 +119,7 @@ export function shapeForCommand(command, result, detail, shape = "human") {
     }
     const handler = getOutputShapeHandler(command);
     if (handler) {
-        return handler(result, detail, effectiveShape);
+        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();
 }