akm-cli 0.9.10 → 0.9.12

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/integration/bundling-akm.md

@@ -259,7 +259,7 @@ rather than rely on `$HOME`-derived defaults (names verified against
 | `AKM_CONFIG_DIR` | `config.json`'s directory. |
 | `AKM_DATA_DIR` | Durable, non-regenerable data: **`index.db` and `state.db` live here.** This is the directory a migration snapshot's safety copy sits beside. |
 | `AKM_CACHE_DIR` | Regenerable cache: registry downloads, config backups, task logs. Safe to discard between image builds (not between boots of the same running install). |
-| `AKM_STATE_DIR` | **Not** where `state.db` lives, despite the name — this is the XDG "state" directory used for scheduled-task invocation context and companion-plugin hook state (Claude Code / OpenCode hook logs). Set it anyway if you schedule akm tasks inside the image, so that context is captured consistently rather than falling back to `$HOME/.local/state/akm`. |
+| `AKM_STATE_DIR` | **Not** where `state.db` lives, despite the name — this is the XDG "state" directory. Holds scheduled-task invocation context, companion-plugin hook state (Claude Code / OpenCode hook logs), and, per stash, `akm improve`'s machine-local writers (`improve/distill-rejected/`, `improve/eval-cases/`, `improve/measurement/verdicts/`) and whole-run lock (`locks/`) — see [Storage locations](https://github.com/itlackey/akm/blob/main/docs/architecture/internals/storage-locations.md). Set it anyway if you schedule akm tasks inside the image, so that context is captured consistently rather than falling back to `$HOME/.local/state/akm`. |
 
 Set all five to paths that persist across container restarts (a mounted
 volume), or `akm migrate apply` will see an empty `state.db` on every boot

package/docs/migration/v0.8-to-v0.9.md

@@ -112,6 +112,38 @@ IR and freeze the durable plan v4 family's executable `irVersion: 5` format.
 That is the only executable stored plan. Do not copy an old workflow database
 expecting old runs to resume; start new runs from current authored sources.
 
+## Storage relocations within the 0.9.x line
+
+0.9.11 (itlackey/akm#890) moves five machine-local `akm improve` writers out
+of `$STASH/.akm` — where they never belonged, per the "must travel with the
+content" rule in [Storage locations](https://github.com/itlackey/akm/blob/main/docs/architecture/internals/storage-locations.md)
+— into `$STATE`/`$CACHE`, namespaced per stash so two stashes on one machine
+never collide:
+
+| Old path | New path |
+|---|---|
+| `$STASH/.akm/distill-rejected/` | `$STATE/improve/distill-rejected/<stash>/` |
+| `$STASH/.akm/eval-cases/` | `$STATE/improve/eval-cases/<stash>/` |
+| `$STASH/.akm/measurement/verdicts/` | `$STATE/improve/measurement/verdicts/<stash>/` |
+| `$STASH/.akm/unresolved-sources/` | `$CACHE/index/unresolved-sources/<stash>/` |
+| `$STASH/.akm/improve.lock` (+ `.improve.lock.operations.sensitive`) | `$STATE/locks/<stash>/improve.lock` (+ `.improve.lock.operations.sensitive`) |
+
+Any script that reads the old paths directly — `scripts/akm-eval/src/proactive-verdict.ts`
+(verdicts), `scripts/akm-eval/README.md`'s eval-cases note, or a custom
+snapshot/backup tool — must read the new ones instead; the pilot treatment
+file at `$STASH/.akm/measurement/` (sibling to `verdicts/`) is unaffected, it
+was never a writer output. `akm migrate status`/`apply [--dry-run]` covers
+every configured LOCAL bundle (the default stash first, then every other
+filesystem-backed bundle — a `git`/`website`/`npm` bundle is cache-backed,
+never touched), and reports and relocates any files still sitting at the old
+paths (same-filesystem rename, or copy-then-delete across filesystems). A
+lock file is only ever deleted once the same staleness check `akm improve`
+itself uses says its holder is dead; a lock a live run still holds (or one
+this process cannot read) is left in place and reported instead. The whole
+step is idempotent — a second run reports nothing pending.
+`$STASH/.akm/memory-cleanup/` did not move; it is the one confirmed exception
+to the rule (see Storage locations, above).
+
 ## Recovery
 
 If the new setup is wrong, stop AKM, move the new current directories aside,

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

@@ -113,6 +113,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 +280,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 +312,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 +592,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 +611,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 +667,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 +710,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 +756,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 +1560,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 +2297,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
@@ -2457,10 +2514,10 @@ shell commands. It manages on-disk task definitions under
 (cron / launchd / schtasks). Task source v4 YAML (`version: 4`) is the only
 executable source contract this release accepts; `akm task add` writes v4 —
 see the canonical [Tasks reference](tasks.md). The
-group is `add | run | explain | sync | doctor | history | prune` — there is
-no `list` or `remove`; use `akm search --type task` / `akm show tasks/<id>`
-to inspect, and edit the file + `akm task sync` to change or remove a
-schedule.
+group is `add | run | explain | validate | sync | doctor | history | prune`
+— there is no `list` or `remove`; use `akm search --type task` /
+`akm show tasks/<id>` to inspect, and edit the file + `akm task sync` to
+change or remove a schedule.
 
 ```sh
 akm search --type task                      # List tasks (cross-bundle)
@@ -2472,6 +2529,7 @@ akm task add nightly --schedule "@daily" --command "akm improve" --disabled  # r
 akm task add nightly --schedule "@daily" --command "akm improve" --force    # overwrite an existing task id
 akm task run <id>                           # Execute now (what the scheduler calls)
 akm task explain <ref>                      # Read-only: declared inputs, target, schedule — spawns nothing
+akm task validate <path>                    # Read-only: parse one task file by path, report sync's diagnostic
 akm task history [<id>] [--id <id>] [--limit <n>]  # Recent runs from state.db (positional id == --id)
 akm task sync                               # Reconcile on-disk YAML with scheduler
 akm task sync --dry-run                     # Preview the reconcile — zero scheduler writes
@@ -2494,6 +2552,30 @@ it never spawns anything, writes history, or touches the scheduler. A
 secret-shaped value prints as `<redacted>`. See
 [`akm task explain`](tasks.md#akm-task-explain).
 
+`akm task validate <path>` parses ONE task file by filesystem path — not a
+concept ref or id, and the file need not live in any configured bundle —
+and reports the same diagnostic `akm task sync` would produce for it,
+INCLUDING sync's own cron-dialect check and its per-schedule-entry
+input-contract check (so a file `sync` would reject can never be reported
+`valid`/`converts` here): `{ok, path, sourceVersion, outcome, reason?,
+resolved?}` where `outcome` is `valid` (parses as task source v4 directly
+and passes both sync checks), `converts` (task v2/v3 that the deterministic
+migrator converts in memory and which then also passes both sync checks),
+`blocked` (task v2/v3 the migrator itself cannot convert — needs a human
+decision), `invalid` (the YAML doesn't parse, or the document fails schema
+validation, or it parsed but fails one of the two sync checks), or
+`not-a-task` (the YAML parses but never declares a `version:` field — not
+shaped like a task source). `resolved` is the compiled task shape
+`akm task sync` itself would build a scheduler binding from — id, the
+compiled schema version, resolved `uses`/`run` target, declared `inputs`
+contract, and `schedule` bindings — present only on `valid`/`converts`.
+Unlike `akm task explain`, it never runs execution lowering: a command-kind
+task validates the same whether or not the local config has an engine
+configured. Exits 0 for `valid`/`converts`, 1 for
+`blocked`/`invalid`/`not-a-task`, 2 for a missing or unreadable path.
+**Read-only**: it never touches the scheduler and never requires the file to
+be indexed or wired into a bundle.
+
 `akm task run` is what cron / launchd / schtasks invoke at the scheduled
 time. Each run is recorded as a row in the durable `task_history` table
 (`state.db`), surfaced by `akm task history` — **not** by `akm log`; there is
@@ -2539,7 +2621,8 @@ the AKM storage path or installed runtime path therefore requires an explicit
 operates on the primary/default bundle. `add`, `history`, `sync`, `run`, and
 `explain` all accept `--bundle <bundle>` to schedule, reconcile, or inspect
 tasks that live in another configured bundle (`doctor` reports scheduler-wide
-state and takes no `--bundle`):
+state and takes no `--bundle`; `validate` takes a bare filesystem path
+instead of a ref, so it has no bundle to target either):
 
 ```sh
 akm task add nightly --schedule "@daily" --command "akm improve" --bundle team-bundle

package/docs/reference/configuration.md

@@ -217,7 +217,8 @@ and is never rescued by that fallback.
 Index passes select engines through `index.defaults.engine` or
 `index.<pass>.engine`. Per-pass `model`, `timeoutMs`, and `llm` fields are
 invocation overrides; `enabled: false` disables that pass. Connection fields
-such as `endpoint`, `provider`, and `apiKey` belong only on named engines.
+such as `endpoint`, `provider`, `apiKey`, and `apiKeyFile` belong only on
+named engines.
 
 `workflow.maxConcurrency` is the native workflow engine ceiling. An explicit
 value is clamped to `1..64`. When absent, AKM derives the cap once from the CPU
@@ -494,7 +495,7 @@ generic walker.
 | `AKM_BUNDLE_DIR` | Override the bundle directory |
 | `AKM_DATA_DIR` | Override the data directory — `index.db`, durable `state.db`, and `akm.lock` (or set `XDG_DATA_HOME`) |
 | `AKM_CACHE_DIR` | Override the cache directory — regenerable caches (or set `XDG_CACHE_HOME`) |
-| `AKM_STATE_DIR` | Override the state directory — task-scheduler invocation state (or set `XDG_STATE_HOME`) |
+| `AKM_STATE_DIR` | Override the state directory — task-scheduler invocation state, and (per stash) `akm improve`'s machine-local writers and whole-run lock (or set `XDG_STATE_HOME`) |
 | `AKM_SQLITE_JOURNAL_MODE` | SQLite journal mode: `WAL` (default), `DELETE`, or `TRUNCATE` |
 | `AKM_VERBOSE` | Truthy value enables the same diagnostics as `--verbose` |
 | `AKM_DEBUG` | `1` prints a stack trace on unexpected internal errors |
@@ -503,6 +504,15 @@ For an engine named `fast`, its fallback variable is
 `AKM_ENGINE_FAST_API_KEY`. An explicit `apiKey` symbolic reference is
 authoritative and does not fall through to another variable.
 
+`engines.<name>.apiKeyFile` is a file-backed alternative to `apiKey`, for a
+host that refuses to put secrets in the process environment (a container
+runtime's mounted secret, for example). It is a plain filesystem path — `~`
+expands to the home directory — read at dispatch time and trimmed of one
+trailing newline; the raw path is safe to keep in `config.json` since it is
+not itself a secret. Setting both `apiKey` and `apiKeyFile` on the same
+engine is rejected. A missing, unreadable, or empty file fails the call
+closed, naming the engine and path but never the file's content.
+
 Use `AKM_SQLITE_JOURNAL_MODE=DELETE` or `TRUNCATE` when WAL is unavailable,
 such as on some NFS/SMB mounts. With the default `WAL` setting, AKM detects a
 network filesystem for the data directory and falls back to `DELETE`.

package/docs/reference/data-and-telemetry.md

@@ -16,7 +16,7 @@ AKM adds no network destinations of its own. The requests it *does* make all go
 2. **Registry metadata and bundle packages** from sources you explicitly configure (GitHub, npm, git remotes, websites) — those hosts receive the fetch/clone/crawl requests, and website sources receive requests for the pages you crawl.
 3. **`akm upgrade`** — fetches the latest release from GitHub releases (GitHub sees the request).
 4. **`akm setup`** — a single DNS lookup for `github.com` to decide whether to skip network-dependent steps (Ollama detection, remote embedding probes) when offline. No HTTP request is made by this probe; if it succeeds, akm proceeds with the network-dependent steps you already configured.
-5. **`akm improve` dead-link checks** — a full-scope improve run (the default for a bare `akm improve`) sends best-effort `HEAD` requests (following redirects, with a short timeout and a hard cap on URL count) to URLs found in the bodies of the knowledge assets it is improving, to flag dead links. The hosts of those URLs see a `HEAD` request; no asset content is sent. Keep URLs you don't want probed out of knowledge-asset bodies, or run improve with an explicit narrower scope.
+5. **`akm improve` dead-link checks** — a full-scope improve run (the default for a bare `akm improve`) sends best-effort `HEAD` requests (following redirects, with a short per-request timeout, checked at a bounded concurrency rather than all at once) to every URL found in the bodies of the knowledge assets it is improving, to flag dead links. The hosts of those URLs see a `HEAD` request; no asset content is sent. Keep URLs you don't want probed out of knowledge-asset bodies, or run improve with an explicit narrower scope.
 
 In every case the receiving endpoint is one you configured or invoked; the data leaving your machine is the data you directed AKM to send there.
 

package/docs/reference/tasks.md

@@ -385,6 +385,14 @@ for full before/after examples and recovery guidance.
 - `akm task explain <ref>` prints a task's declared inputs, resolved target,
   effective execution settings, and schedule bindings without running
   anything — see [`akm task explain`](#akm-task-explain) above.
+- `akm task validate <path>` parses one task file by filesystem path (the
+  file need not live in a configured bundle) and reports the same
+  `valid`/`converts`/`blocked`/`invalid`/`not-a-task` diagnostic
+  `akm task sync` would produce for it — including sync's own cron-dialect
+  check and its per-schedule-entry input-contract check — without touching
+  the scheduler and without requiring a configured engine, even for a
+  command-kind task. The envelope's own `sourceVersion` field names the
+  file's originally declared schema version (2, 3, or 4).
 - `akm task add` writes a task source v4 document and installs it after
   validation. `--params` renders typed `inputs:` declarations instead of a
   `with:` bag; `--schedule` is required on every invocation, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.10",
+  "version": "0.9.12",
   "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": [