akm-cli 0.9.11 → 0.9.13

package/dist/workflows/source-files.js

@@ -15,6 +15,7 @@ import path from "node:path";
 import { compareCodePoints, toPosix } from "../core/common.js";
 import { UsageError } from "../core/errors.js";
 import { canonicalizeWorkflowName, WORKFLOW_EXTENSIONS } from "../core/recognition-util.js";
+import { warnOnce } from "../core/warn.js";
 export class WorkflowSourceRejectionError extends UsageError {
     sourcePaths;
     constructor(message, code, sourcePaths) {
@@ -34,23 +35,6 @@ export class WorkflowSourceCollisionError extends WorkflowSourceRejectionError {
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
-export class WorkflowSourceDomainError extends WorkflowSourceRejectionError {
-    canonicalName;
-    constructor(canonicalName, sourcePaths, issues, collidingSourcePaths) {
-        const sortedPaths = [...sourcePaths].sort(compareCodePoints);
-        const sortedCollisions = [...collidingSourcePaths].sort(compareCodePoints);
-        const code = issues.some((issue) => issue.code === "PATH_ESCAPE_VIOLATION")
-            ? "PATH_ESCAPE_VIOLATION"
-            : "WORKFLOW_SOURCE_INVALID";
-        const collisionDetail = sortedCollisions.length > 1 ? ` Valid owners also collide: ${sortedCollisions.join(", ")}.` : "";
-        super(`Workflow "${canonicalName}" has an invalid source ownership domain across candidates: ${sortedPaths.join(", ")}. ` +
-            `Problems: ${issues.map((issue) => issue.message).join(" ")}${collisionDetail} ` +
-            "Every candidate in the canonical domain is rejected until all invalid or duplicate sources are removed.", code, sortedPaths);
-        this.name = "WorkflowSourceDomainError";
-        this.canonicalName = canonicalName;
-        Object.setPrototypeOf(this, new.target.prototype);
-    }
-}
 export class WorkflowSourceIdentityError extends UsageError {
     constructor(ref, indexedPath, authoritativePath) {
         super(`Indexed workflow source identity for "${ref}" points to ${indexedPath}, but the authoritative source is ${authoritativePath}. ` +
@@ -171,11 +155,7 @@ export function listWorkflowSourceFiles(sourceRoot, adapterId, name) {
         });
     }
     candidates.sort((left, right) => compareCodePoints(left.relativePath, right.relativePath));
-    const { sources, issues } = inspectWorkflowSourceDomain(candidates, canonicalName, realRoot);
-    if (issues.length > 0) {
-        throw workflowSourceDomainError(adapterId, canonicalName, candidates, sources, issues);
-    }
-    return sources;
+    return inspectWorkflowSourceDomain(candidates, canonicalName, realRoot);
 }
 /**
  * Resolve a pre-enumerated set of authored workflow candidates in one batch.
@@ -233,47 +213,44 @@ export function resolveWorkflowSourceDomains(sourceRoot, adapterId, sourcePaths)
     for (const canonicalName of [...candidatesByName.keys()].sort(compareCodePoints)) {
         const candidates = candidatesByName.get(canonicalName) ?? [];
         candidates.sort((left, right) => compareCodePoints(left.relativePath, right.relativePath));
-        const { sources, issues } = inspectWorkflowSourceDomain(candidates, canonicalName, realRoot);
+        const sources = inspectWorkflowSourceDomain(candidates, canonicalName, realRoot);
         const sourcePaths = candidates.map((candidate) => candidate.relativePath);
-        if (issues.length > 0) {
-            resolutions.push({
-                canonicalName,
-                sourcePaths,
-                rejection: workflowSourceDomainError(adapterId, canonicalName, candidates, sources, issues),
-            });
-            continue;
-        }
-        if (sources.length > 1) {
-            resolutions.push({
-                canonicalName,
-                sourcePaths,
-                rejection: new WorkflowSourceCollisionError(adapterId === "akm" ? `workflows/${canonicalName}` : canonicalName, sources.map((source) => source.relativePath)),
-            });
-            continue;
-        }
-        resolutions.push({ canonicalName, sourcePaths, source: sources[0] });
+        resolutions.push({
+            canonicalName,
+            sourcePaths,
+            source: pickWorkflowSource(adapterId, canonicalName, sources),
+        });
     }
     return resolutions;
 }
 function inspectWorkflowSourceDomain(candidates, canonicalName, realRoot) {
     const sources = [];
-    const issues = [];
     for (const candidate of candidates) {
         const inspection = inspectWorkflowSourceCandidate(candidate, canonicalName, realRoot);
-        if (inspection.source)
+        if (inspection.source) {
             sources.push(inspection.source);
-        issues.push(...inspection.issues);
+            continue;
+        }
+        for (const issue of inspection.issues) {
+            warnOnce(`workflow-source-invalid:${issue.sourcePaths.join(",")}`, issue.message);
+        }
     }
-    return { sources, issues };
+    return sources;
 }
-function workflowSourceDomainError(adapterId, canonicalName, candidates, sources, issues) {
-    return new WorkflowSourceDomainError(adapterId === "akm" ? `workflows/${canonicalName}` : canonicalName, candidates.map((candidate) => candidate.relativePath), issues, sources.map((source) => source.relativePath));
+function pickWorkflowSource(adapterId, canonicalName, sources) {
+    if (sources.length <= 1)
+        return sources[0];
+    const winner = [...sources].sort((left, right) => left.format === right.format ? 0 : left.format === "markdown" ? -1 : 1)[0];
+    const shadowed = sources.filter((source) => source !== winner);
+    const displayName = adapterId === "akm" ? `workflows/${canonicalName}` : canonicalName;
+    warnOnce(`workflow-source-collision:${displayName}`, `Workflow "${displayName}" has both a .md and .yml source (${shadowed
+        .map((source) => source.relativePath)
+        .join(", ")} shadowed by ${winner?.relativePath}); using the .md source. Remove the shadowed sibling to ` +
+        "silence this warning.");
+    return winner;
 }
 function inspectWorkflowSourceCandidate(candidate, canonicalName, realRoot) {
     const issues = [];
-    const nestedSuffix = WORKFLOW_EXTENSIONS.find((suffix) => candidate.extensionlessStem.toLowerCase().endsWith(suffix));
-    if (nestedSuffix)
-        issues.push(new WorkflowSourceNameError(candidate.relativePath, nestedSuffix));
     let authoredStat;
     try {
         authoredStat = fs.lstatSync(candidate.path);
@@ -327,11 +304,8 @@ function inspectWorkflowSourceCandidate(candidate, canonicalName, realRoot) {
 /** Return the sole owner, throw on a collision, or return undefined when absent. */
 export function resolveUniqueWorkflowSource(sourceRoot, adapterId, name) {
     const sources = listWorkflowSourceFiles(sourceRoot, adapterId, name);
-    if (sources.length > 1) {
-        const canonicalName = sources[0]?.canonicalName ?? canonicalizeWorkflowName(normalizeName(name));
-        throw new WorkflowSourceCollisionError(adapterId === "akm" ? `workflows/${canonicalName}` : canonicalName, sources.map((source) => source.relativePath));
-    }
-    return sources[0];
+    const canonicalName = sources[0]?.canonicalName ?? canonicalizeWorkflowName(normalizeName(name));
+    return pickWorkflowSource(adapterId, canonicalName, sources);
 }
 /** Compare an indexed path with the single authoritative on-disk source. */
 export function assertIndexedWorkflowSourceIdentity(ref, indexedPath, authoritative) {

package/dist/workflows/source-ir/program.js

@@ -2,7 +2,7 @@
 // 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 { parseBuiltinCommandAction } from "../../commands/command/builtin-action.js";
-import { applyPortableCommandArguments } from "../../commands/command/portable-template.js";
+import { PORTABLE_ARGUMENTS_PLACEHOLDER } from "../../commands/command/portable-template.js";
 /** Lower one adapter-neutral source-IR step into the shared execution unit. */
 export function sourceStepProgramUnit(source) {
     const unit = {
@@ -32,7 +32,7 @@ export function sourceStepInstructions(source) {
         }
         if (source.commandMode === "literal")
             return action.content;
-        return applyPortableCommandArguments(action.content, action.arguments, "inline workflow command").content;
+        return action.content.split(PORTABLE_ARGUMENTS_PLACEHOLDER).join(action.arguments ?? "");
     }
     if (source.uses !== undefined)
         return `Invoke local target ${source.uses}.`;

package/dist/workflows/source-ir/semantics.js

@@ -5,10 +5,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { parseBuiltinCommandAction } from "../../commands/command/builtin-action.js";
-import { validatePortableCommandTemplate } from "../../commands/command/portable-template.js";
 import { parseSchedule } from "../../tasks/schedule.js";
 import { classifyWorkflowSourceUses } from "./uses.js";
-const TOKEN_SAFE_RUN = /^[A-Za-z0-9_./:@+=,-]+(?: [A-Za-z0-9_./:@+=,-]+)*$/;
 export class WorkflowSourceSemanticError extends Error {
     code;
     constructor(code, message) {
@@ -34,17 +32,10 @@ export function canonicalizeWorkflowRun(value) {
     if (value.includes("${{")) {
         throw new WorkflowSourceSemanticError("unsupported-github-expression", "GitHub expressions and contexts are not supported.");
     }
-    if (value.includes("\n") || value.includes("\r")) {
-        throw new WorkflowSourceSemanticError("unsafe-run-syntax", "Local run accepts only whitespace-separated safe tokens; shell expansion and operators are unsupported.");
+    if (value.includes("\0")) {
+        throw new WorkflowSourceSemanticError("invalid-exec-argv", "Local run may not contain NUL bytes.");
     }
-    const canonical = value
-        .trim()
-        .split(/[ \t]+/)
-        .join(" ");
-    if (!TOKEN_SAFE_RUN.test(canonical)) {
-        throw new WorkflowSourceSemanticError("unsafe-run-syntax", "Local run accepts only whitespace-separated safe tokens; shell expansion and operators are unsupported.");
-    }
-    return canonical;
+    return value;
 }
 export function canonicalizeWorkflowWorkingDirectory(value, workspaceRoot) {
     if (hasControlCharacter(value)) {
@@ -125,17 +116,8 @@ export function validateWorkflowBuiltinCommand(value, mode) {
     if (effectiveMode === "stored-ref") {
         throw new WorkflowSourceSemanticError("builtin-command-inputs", "Inline akm/command content cannot use commandMode stored-ref.");
     }
-    if (effectiveMode === "literal") {
-        if (action.arguments !== undefined) {
-            throw new WorkflowSourceSemanticError("builtin-command-inputs", "Literal akm/command content cannot declare arguments because no substitution occurs.");
-        }
-        return action;
-    }
-    try {
-        validatePortableCommandTemplate(action.content, "inline workflow command");
-    }
-    catch (cause) {
-        throw new WorkflowSourceSemanticError("builtin-command-inputs", cause instanceof Error ? cause.message : "Invalid portable command template.");
+    if (effectiveMode === "literal" && action.arguments !== undefined) {
+        throw new WorkflowSourceSemanticError("builtin-command-inputs", "Literal akm/command content cannot declare arguments because no substitution occurs.");
     }
     return action;
 }

package/docs/migration/v0.9.1-to-v0.9.2.md

@@ -303,6 +303,26 @@ one akm version reading a given `state.db` at a time; do not alternate
 versions against the same state directory, and do not downgrade below
 0.9.2 once a 0.9.2-or-later akm has recorded task history there.
 
+## Harness id rename: `claude-code` -> `claude`
+
+0.9.2 also renamed the Claude Code harness id from `claude-code` to
+`claude` — the id used for both agent dispatch and the per-session
+extraction ledger (`state.db`'s `extract_sessions_seen.harness` and
+`workflow_runs.agent_harness`). The 0.9.2 release did not carry a state
+migration for this rename, so any row a pre-0.9.2 akm wrote stayed
+keyed under `claude-code`, invisible to anything querying by the new
+name — a script or dashboard filtering `extract_sessions_seen` or
+`workflow_runs` on `harness = 'claude-code'` (or
+`agent_harness = 'claude-code'`) sees those rows disappear from that
+query, not deleted, once you're on a release carrying the 0.9.12 fix.
+0.9.12 adds state migration
+`027-extract-sessions-seen-harness-rename`, which runs automatically
+on the next managed `state.db` open (no separate command needed) and
+renames every such row to `claude` in place — conflict-tolerant
+against a session already recorded under `claude`, which is kept as
+the authoritative row. After upgrading to 0.9.12 or later, re-point
+any external query at `harness = 'claude'` / `agent_harness = 'claude'`.
+
 ## Workflow cutover
 
 Markdown `.md` and GitHub-shaped `.yml` are peer workflow source formats in

package/docs/reference/cli.md

@@ -79,6 +79,24 @@ For local materialized assets, `editHint` is added only when `editable` is
 or use `action` (or curate `followUp`). Registry-only results have no local
 `path`, `editable`, or `editHint`.
 
+### The `results` collection alias
+
+Every list-returning command names its collection field differently —
+`search` returns `hits`, `curate` returns `items`, `proposal list` returns
+`proposals`, `bundle list` returns `sources`, `env list` returns `envs`,
+`secret list` returns `secrets`, `registry list` returns `registries`,
+`registry search` returns `hits`, `workflow list` returns `runs`,
+`task history` returns `rows`, `log list` returns `events`. A caller that does
+not already know each command's key cannot write one accessor across all of
+them.
+
+Every one of these commands also carries a `results` field — the identical
+array, not a copy — alongside its semantic key, in every `--format`/`--detail`
+combination and both `--shape human` (the default) and `--shape agent`. Code
+written against a single command should keep using its semantic key for
+clarity; code that needs to handle several list commands uniformly can read
+`results` and never maintain a per-command lookup table.
+
 ### `--shape summary`
 
 Valid **only on `akm show`**. Every other command rejects `--shape summary`
@@ -113,6 +131,14 @@ The `hint` field is present only when actionable remediation is available
 `ok === false` on the parsed stderr envelope or a non-zero exit code to
 detect failure. Scripts can rely on the exit code alone.
 
+Every success envelope produced by the passthrough stamp — `config`, `clone`,
+`models`, `task-*`, `workflow-*`, `registry-*`, and the rest of that shared
+handler — also carries `ok: true` (0.9.12+), so a caller branching on `.ok`
+sees the same field on both sides — success and failure — instead of
+`undefined` on success. A command that already computes its own `ok` from a
+graded outcome (e.g. `task run`'s exit-code mapping, `akm lint`, `akm proposal
+extract`) keeps that value, `false` included.
+
 `env run`, `secret run`, and `migrate` preserve the spawned process's exact
 status and raw streams instead of replacing them with an akm failure envelope.
 `task run` maps completed, active, and disabled status to 0; blocked and failed
@@ -272,17 +298,21 @@ akm health --report --window-compare 7d --format html
 | `--window-compare` | Compare the current window against the prior window of the same duration (e.g. `24h`, `7d`). With `--report`, overrides the default trend window. |
 | `--group-by` | Group rows by `run` (one row per `improve_runs` entry). Omit for the default summary. |
 | `--windows` | Explicit comparison window(s) as `name=...,since=ISO,until=ISO` (repeatable, up to 4). Mutually exclusive with `--window-compare`. |
+| `--no-probe` | Skip the `default-llm-engine` / `configured-engines` reachability probes (for an offline or air-gapped host). |
 
 The command reads `state.db`, verifies that the required tables exist, performs a
 write-read probe against the events stream, inspects `task_history`, checks the
-default agent engine, and summarizes recent `improve_*` events.
+default agent engine, and summarizes recent `improve_*` events. Unless
+`--no-probe` is given, it also sends a bounded (3s timeout) reachability probe
+to the `default-llm-engine` and every `configured-engines` LLM connection (and
+an SDK engine's LLM fallback), one probe per distinct endpoint.
 
 Primary result fields:
 
 | Field | Description |
 | --- | --- |
 | `status` | Overall health verdict: `pass`, `warn`, or `fail` |
-| `hardChecks` | Deterministic checks such as `state-db-schema`, `state-db-round-trip`, `state-db-migrations`, `task-log-backing`, `active-runs`, `default-engine`, and `model-map-files` |
+| `hardChecks` | Deterministic checks such as `state-db-schema`, `state-db-round-trip`, `state-db-migrations`, `task-log-backing`, `active-runs`, `default-engine`, `model-map-files`, `default-llm-engine`, `configured-engines`, and `active-improve-strategy` |
 | `advisories` | Non-fatal warnings including `semantic-search-runtime` and `session-extraction` (akmExtract pipeline health) |
 | `metrics` | Aggregate task/runtime metrics: `taskFailRate`, `agentFailureRate`, `stuckActiveRuns`, `logBackingRate`, `probeRoundTripMs` |
 | `improve` | Recent improve-loop counts derived from `improve_invoked`, `improve_skipped`, and `improve_completed` events |
@@ -300,9 +330,21 @@ holds a pending historical-destructive migration and something other than
 `akm upgrade` / `akm migrate apply` opens it directly. Read this check's
 `status` instead of grepping akm's error text for that case.
 
-The `session-extraction` advisory reflects the health of the `akmExtract` pipeline
-(Phase 0.4 of `akm improve`). It warns on harness errors or when no proposals are
-generated across five or more scanned sessions.
+`default-llm-engine` and `configured-engines` probe reachability (not just
+configuration) for a `kind: "llm"` engine — an unreachable endpoint is a hard
+`fail` for `default-llm-engine` and a `warn` for any other engine. `--no-probe`
+skips this. `active-improve-strategy` names the resolved engine per process
+in its evidence and message, so a strategy-level `engine` pin that shadows
+`defaults.llmEngine` is visible without config archaeology.
+
+The `session-extraction` advisory is derived from the `extract_sessions_seen`
+ledger for the last 7 days — not `improve_runs`, which the hook-driven `akm
+proposal extract --session-id ...` invocation never writes. It reports
+`unknown` when nothing was recorded in the window (cannot tell "off on
+purpose" from "broken"), `warn` when every session in the window was skipped
+for an infrastructure reason (`llm_unavailable`, `read_failed`, `exception`,
+`locked_concurrent`) — naming the reason and, when recorded, the engine — and
+`pass` otherwise, with per-outcome counts.
 
 The indexed entity graph (entities/relations extracted from bundle assets) has
 no dedicated inspection command; its summary counts surface as an info-level
@@ -568,8 +610,10 @@ akm workflow create ship-release
 akm workflow create ship-release --from ./ship-release.md
 akm workflow run workflows/ship-release --version 1.2.3
 akm workflow run <run-id>                  # continue an active partial run
+akm workflow run workflows/ship-release --new  # start a fresh run even if one is already active
 akm workflow status <run-id>
 akm workflow status workflows/ship-release
+akm workflow status 7c115132               # 8+ char run-id prefix also works
 akm workflow resume <run-id>
 akm workflow abandon <run-id>
 akm workflow list --active
@@ -585,13 +629,21 @@ Subcommands:
 | Subcommand | Description |
 | --- | --- |
 | `create <name>` | Validate and write a Markdown workflow under `workflows/`. `--path <dir>` places it in a subdirectory; `--from <file>` imports content; `--force` (requires `--from` or `--reset`) overwrites; `--print` prints the template that would be written instead of writing it |
-| `run <run-id\|ref>` | Stable canonical start/resume/execute command. A ref starts a run or continues the active run in the current scope; a run id continues that exact active run. Executes until completion, failure, verification rejection, interruption, or an explicit limit |
+| `run <run-id\|ref>` | Stable canonical start/resume/execute command. A ref starts a run or resumes the active run in the current scope (announced as `resumed: true`, see below); a run id continues that exact active run. `--new` starts a fresh run even when one is already active. Executes until completion, failure, verification rejection, interruption, or an explicit limit |
 | `status <run-id\|ref>` | Show the full run state, including all step statuses. `--units` also lists per-unit rows from the run journal (diagnostics only). Renders a `children:` tree when the run composes child workflows |
 | `list` | List workflow runs (optionally filtered by `--ref`; `--active` shows only `status=active` runs, excluding `blocked`/`failed`/`completed`). Child workflow runs are excluded unless `--children` is passed |
 | `resume <run-id>` | Flip a `blocked` or `failed` run back to `active`. Completed runs cannot be resumed |
 | `abandon <run-id>` | Mark a run failed so it stops counting as active (`resume` can reopen it) |
 | `plan <ref>` | **Evolving.** Compile and freeze a workflow WITHOUT publishing a run: the canonical step graph, per-step frozen target kinds, task/child expansion, input bindings, source read set, and lowering notices — zero durable writes. Returns the full JSON envelope by default, like every other command; pass `--format text` for a human-readable summary |
 
+Everywhere a run id is accepted (`run`, `status`, `resume`, `abandon`), a
+unique run-id **prefix** of 8 or more characters works too — the same
+convention `akm proposal accept`/`reject` use for proposal UUIDs. A prefix
+matching more than one run is a usage error listing every candidate; a
+prefix matching none is a not-found error. Only strings shaped like a run id
+(hex digits and hyphens, 8+ characters) are ever treated as a prefix, so a
+workflow ref is never mistaken for one.
+
 The public `workflow start`, `next`, and `complete` lifecycle was removed in
 0.9, along with the experimental `brief`/`report` external-driver protocol.
 Use `workflow run` for execution and `workflow status` for inspection. The
@@ -633,6 +685,14 @@ The old `--params <json>` bag is removed.
 | `--max-steps <n>` | Stop once this many steps have finished, leaving a partial run active. Must be at least 1. |
 | `--max-retries <n>` | When a step fails, reopen the same run and retry the failed step up to this many additional times. Range: 0 through 100; default 0. Gate rejection and interruption are not retried. |
 | `--timeout <duration>` | Abort the whole invocation after `N`, `Nms`, `Ns`, or `Nm`; bare `N` is milliseconds. The active step remains resumable. |
+| `--new` | Start a fresh run even when one is already active for this ref, instead of resuming it. The existing active run is left untouched — it is never abandoned automatically. A workflow ref only: passing a run id with `--new` is a usage error (exit 2). Parameter flags are allowed together with `--new`, since it is starting a new run. |
+
+**Resuming an active run is announced, not silent.** Passing a ref that
+already has an active run in the current scope resumes that run rather than
+starting a new one (unchanged since #485) — but the envelope now carries
+`resumed: true` alongside the resumed run's `run.id`, and the default text
+output leads with `resuming existing run <id> for <ref>; pass --new to start
+a fresh run`. Pass `--new` to start a second, independent run instead.
 
 The result includes the current `run`, an `executed` step report list, a
 `stepsProcessed` count of the steps that finished, and optional `done`,
@@ -668,7 +728,7 @@ repos or directories. akm resolves that context from the nearest `.akm/config.js
 ancestor when present, otherwise the nearest git root, otherwise the bundle root
 when the cwd is inside it, otherwise the cwd itself. In practice this means:
 
-- `workflow run workflows/<name>` continues the active run for the current project/worktree/directory, or starts one when none is active.
+- `workflow run workflows/<name>` resumes the active run for the current project/worktree/directory (announced with `resumed: true`), or starts one when none is active. `--new` always starts a fresh run.
 - `workflow status workflows/<name>` resolves the most-recently-updated run in the current scope only.
 - `workflow list` shows runs for the current scope only.
 - Direct run-id commands like `workflow status <run-id>` still work even if the run was started from another directory.
@@ -714,11 +774,12 @@ akm workflow status workflows/ship-release
 akm workflow status <run-id> --units    # also list per-unit rows from the run journal
 ```
 
-Accepts either a run-id or a workflow ref. When given a workflow ref, resolves
-to the most-recently-updated run for that ref in the current working scope.
-`--units` adds per-unit rows (unit id, status, failure reason, and any
-result/error diagnostic text) from the run journal — diagnostics only; step
-evidence stays deterministic and is unaffected.
+Accepts a run id, a unique 8+ character run-id prefix, or a workflow ref.
+When given a workflow ref, resolves to the most-recently-updated run for that
+ref in the current working scope. `--units` adds per-unit rows (unit id,
+status, failure reason, and any result/error diagnostic text) from the run
+journal — diagnostics only; step evidence stays deterministic and is
+unaffected.
 
 #### workflow plan
 
@@ -1517,13 +1578,14 @@ Subcommands:
 | --- | --- |
 | `get <key>` | Read one config key |
 | `list` | List current configuration |
-| `set <key> <value>` | Set one config key |
-| `unset <key>` | Unset an optional key, or a whole `embedding`/engine section |
+| `set <key> <value>` | Set one config key; prints the resulting config with `ok: true` |
+| `unset <key>` | Unset an optional key, or a whole `embedding`/engine section; prints the resulting config with `ok: true` |
 | `path` | Show paths to config, bundle, cache, and index. `--all` prints every path; without it, just the config path. Load-bearing: `config path` is the one subcommand the CLI still allows to run when the on-disk config itself fails to load, so you always have a way to locate a broken config. |
 
-`set` and `unset` accept `--silent` to suppress the post-write config dump on
-stdout (the write still happens and errors still print) — use it from hooks
-and CI scripts.
+`set` and `unset` accept `--silent` to suppress the post-write config dump
+entirely — nothing is printed on stdout, and the exit code is the status (the
+write still happens and errors still print) — use it from hooks and CI
+scripts.
 
 > **Removed in 0.9.0:** `akm config enable`/`akm config disable`. Use
 > `akm registry add|remove` to toggle a registry, the general mechanism.
@@ -2253,6 +2315,19 @@ schedule) is the answer.
 Requires an LLM engine: pass `--engine`, select a `--strategy` whose
 `processes.extract.engine` is set, or configure `defaults.llmEngine`.
 
+**Output.** `ok` means the command ran to completion — it is `true` even when
+every session was skipped (an unreachable LLM engine included); it does not
+mean anything was harvested. Consumers that need "did this run actually
+harvest" branch on `skipReasons`, `warnings`, or `sessionsProcessed` /
+`sessionsSkipped` instead. The envelope also reports:
+
+| Field | Description |
+| --- | --- |
+| `engine` | Resolved LLM engine name for this run. Absent only when extract is disabled by the selected improve strategy (the run returns before an engine is resolved). |
+| `engineKind` | `"llm"`, `"sdk"`, or `"agent"` — the kind of runner `engine` resolved to. Same absence condition as `engine`. |
+| `skipReasons` | Per-`skipReason` count across `sessions[]` (e.g. `{ "llm_unavailable": 25 }`). Present only when `sessionsSkipped > 0`. |
+| `warnings` | Includes one aggregate line per infrastructure skip reason that fired (`llm_unavailable`, `read_failed`, `exception`, `locked_concurrent`) — e.g. `25 of 25 sessions skipped: llm_unavailable (engine "default")` — so an engine outage is visible without inspecting `sessions[]`. Session-content skips (`already_extracted`, `too_short`, `triaged_out`) are counted in `skipReasons` but never produce a warning line. |
+
 #### proposal new
 
 Generate a brand-new asset proposal from a description. Output is always a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.11",
+  "version": "0.9.13",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [

package/schemas/akm-config.json

@@ -31,8 +31,7 @@
                 "minLength": 1
               },
               "apiKey": {
-                "type": "string",
-                "pattern": "^\\$[A-Za-z_][A-Za-z0-9_]*$|^\\$\\{[A-Za-z_][A-Za-z0-9_]*\\}$"
+                "type": "string"
               },
               "apiKeyFile": {
                 "type": "string",
@@ -197,8 +196,7 @@
           "type": "string"
         },
         "apiKey": {
-          "type": "string",
-          "pattern": "^\\$[A-Za-z_][A-Za-z0-9_]*$|^\\$\\{[A-Za-z_][A-Za-z0-9_]*\\}$"
+          "type": "string"
         },
         "dimension": {
           "type": "integer",
@@ -1720,8 +1718,7 @@
                     "minLength": 1
                   },
                   "apiKey": {
-                    "type": "string",
-                    "pattern": "^\\$[A-Za-z_][A-Za-z0-9_]*$|^\\$\\{[A-Za-z_][A-Za-z0-9_]*\\}$"
+                    "type": "string"
                   },
                   "apiKeyFile": {
                     "type": "string",
@@ -1886,8 +1883,7 @@
               "type": "string"
             },
             "apiKey": {
-              "type": "string",
-              "pattern": "^\\$[A-Za-z_][A-Za-z0-9_]*$|^\\$\\{[A-Za-z_][A-Za-z0-9_]*\\}$"
+              "type": "string"
             },
             "dimension": {
               "type": "integer",
@@ -3456,8 +3452,7 @@
           "type": "string"
         },
         "apiKey": {
-          "type": "string",
-          "pattern": "^\\$[A-Za-z_][A-Za-z0-9_]*$|^\\$\\{[A-Za-z_][A-Za-z0-9_]*\\}$"
+          "type": "string"
         },
         "dimension": {
           "type": "integer",