akm-cli 0.9.12 → 0.9.13

package/dist/storage/repositories/workflow-runs-repository.js

@@ -5,6 +5,7 @@ import { randomUUID } from "node:crypto";
 import { NotFoundError, UsageError } from "../../core/errors.js";
 import { openStateDatabase, withImmediateTransaction } from "../../core/state-db.js";
 import { borrowScopedStateDb, withStateDbScope } from "../../core/state-db-scope.js";
+import { sleepSync } from "../../runtime.js";
 import { escapeLikePattern } from "../like-pattern.js";
 import { resolveStorageLocations } from "../locations.js";
 import { insertEventOnce, insertEventStrict } from "./events-repository.js";
@@ -21,6 +22,51 @@ function assertAttemptReservationLease(input, run) {
         throw new UsageError(`Workflow run ${input.runId} engine lease expired before durable dispatch reservation.`, "RESOURCE_ALREADY_EXISTS");
     }
 }
+/**
+ * Whether `error` is one of the specific SQLite conditions a run-lease
+ * statement can throw under real cross-process contention on the same row:
+ * `SQLITE_BUSY`/`SQLITE_LOCKED` (both drivers), or the message text a
+ * transient contention blip has been observed producing, "database is
+ * locked", "disk I/O error", or "database disk image is malformed".
+ * Matching on this set alone is never sufficient to call something lease
+ * contention — see {@link WorkflowRunsRepository.acquireEngineLease}, which
+ * additionally requires a fresh read confirming a live lease before
+ * substituting the lease-held message for the original error.
+ */
+function isLeaseContentionSqliteError(error) {
+    const code = error?.code;
+    if (code === "SQLITE_BUSY" || code === "SQLITE_LOCKED")
+        return true;
+    const message = error instanceof Error ? error.message : String(error);
+    return (message.includes("database is locked") ||
+        message.includes("disk I/O error") ||
+        message.includes("database disk image is malformed"));
+}
+const LEASE_RETRY_ATTEMPTS = 4;
+const LEASE_RETRY_BASE_DELAY_MS = 15;
+/**
+ * Retry a single lease statement across a short, bounded set of attempts when
+ * it throws one of {@link isLeaseContentionSqliteError}'s conditions —
+ * absorbing a blip that a fresh attempt on the same connection clears on its
+ * own. Any other error, or the same error surviving every attempt, propagates
+ * unchanged; this never converts a persistent failure into a false success.
+ */
+function runLeaseStatementWithRetry(fn) {
+    let lastError;
+    for (let attempt = 0; attempt < LEASE_RETRY_ATTEMPTS; attempt += 1) {
+        try {
+            return fn();
+        }
+        catch (error) {
+            if (!isLeaseContentionSqliteError(error))
+                throw error;
+            lastError = error;
+            if (attempt < LEASE_RETRY_ATTEMPTS - 1)
+                sleepSync(LEASE_RETRY_BASE_DELAY_MS * 2 ** attempt);
+        }
+    }
+    throw lastError;
+}
 /**
  * Repository owning every raw SQL statement against `workflow_runs` and
  * `workflow_run_steps`. It is DB-location-agnostic: the lifecycle helper
@@ -365,25 +411,57 @@ export class WorkflowRunsRepository {
      * A live lease held by anyone (including a stale copy of the same holder)
      * is NOT reclaimable through this method; the single UPDATE is the whole
      * claim, so two racing invocations cannot both win.
+     *
+     * The UPDATE can throw instead of cleanly returning `changes: 0` under real
+     * cross-process contention on this row: a `SQLITE_BUSY`/`SQLITE_LOCKED`
+     * from two engines racing the same statement, occasionally surfacing as
+     * "database is locked" or even "database disk image is malformed" text that
+     * reads as corruption but is not. `runLeaseStatementWithRetry` absorbs a
+     * blip that a fresh attempt clears on its own. If it is still failing after
+     * every retry, the row is read fresh (a plain SELECT, far less likely to
+     * trip whatever the write hit) to get independent evidence of what is
+     * actually going on: a live lease there means this really was contention,
+     * so the caller gets the same lease-held message `akm workflow run` already
+     * shows for the clean (non-throwing) case, now with `RUN_LEASE_HELD`. No
+     * live lease — or the verifying read itself fails — means the error was
+     * never actually about the lease, so it is rethrown exactly as raised.
+     * Nothing here invents a diagnosis from error text alone or suppresses a
+     * genuine SQLite failure.
      */
     acquireEngineLease(runId, holder, until, now) {
-        const result = this.db
-            .prepare(`UPDATE workflow_runs
-           SET engine_lease_holder = ?, engine_lease_until = ?
-           WHERE id = ? AND status = 'active'
-             AND (engine_lease_holder IS NULL OR engine_lease_until IS NULL OR engine_lease_until < ?)`)
-            .run(holder, until, runId, now);
-        return Number(result.changes) > 0;
+        try {
+            const result = runLeaseStatementWithRetry(() => this.db
+                .prepare(`UPDATE workflow_runs
+               SET engine_lease_holder = ?, engine_lease_until = ?
+               WHERE id = ? AND status = 'active'
+                 AND (engine_lease_holder IS NULL OR engine_lease_until IS NULL OR engine_lease_until < ?)`)
+                .run(holder, until, runId, now));
+            return Number(result.changes) > 0;
+        }
+        catch (error) {
+            if (!isLeaseContentionSqliteError(error))
+                throw error;
+            const row = this.tryReadLeaseColumns(runId);
+            if (row?.engine_lease_holder && row.engine_lease_until && row.engine_lease_until >= now) {
+                throw new UsageError(`Workflow run ${runId} is already being driven by engine ${row.engine_lease_holder} ` +
+                    `(run lease expires ${row.engine_lease_until}). A second \`akm workflow run\` would race it — ` +
+                    `wait for that invocation to finish or for the lease to expire.`, "RUN_LEASE_HELD");
+            }
+            throw error;
+        }
     }
     /**
      * Extend the lease expiry — only while `holder` still owns it. Returns
      * false when the lease was lost (expired and claimed by another engine),
-     * so the caller can stop driving instead of racing the new owner.
+     * so the caller can stop driving instead of racing the new owner. Wrapped
+     * in the same transient-error retry as {@link acquireEngineLease}; a
+     * renewal that still fails after retries is rethrown as-is (no confirmed
+     * "lost lease" diagnosis to substitute, unlike the acquire case above).
      */
     renewEngineLease(runId, holder, until) {
-        const result = this.db
+        const result = runLeaseStatementWithRetry(() => this.db
             .prepare("UPDATE workflow_runs SET engine_lease_until = ? WHERE id = ? AND engine_lease_holder = ? AND status = 'active'")
-            .run(until, runId, holder);
+            .run(until, runId, holder));
         return Number(result.changes) > 0;
     }
     /**
@@ -396,6 +474,36 @@ export class WorkflowRunsRepository {
             .prepare("UPDATE workflow_runs SET engine_lease_holder = NULL, engine_lease_until = NULL WHERE id = ? AND engine_lease_holder = ? AND status <> 'failed'")
             .run(runId, holder);
     }
+    /**
+     * Self-heal an engine lease its holder crashed without releasing: once
+     * `engine_lease_until` has passed, clear it so a read (`workflow status`,
+     * `workflow list`) stops reporting a run as engine-driven when the engine is
+     * long gone — mirroring the maintenance barrier's self-reclaim of a wedged
+     * sentinel (`tryAcquireMaintenanceBarrier`) rather than a bespoke mechanism.
+     * The WHERE clause repeats the exact (holder, until) snapshot the caller
+     * read, so a lease renewed or re-acquired in between never gets clobbered —
+     * same compare-and-swap shape as the claim above. Never touches a lease
+     * that is still live.
+     */
+    reclaimExpiredEngineLease(runId, holder, until, now) {
+        if (until >= now)
+            return false;
+        const result = this.db
+            .prepare(`UPDATE workflow_runs
+           SET engine_lease_holder = NULL, engine_lease_until = NULL
+           WHERE id = ? AND engine_lease_holder = ? AND engine_lease_until = ? AND engine_lease_until < ?`)
+            .run(runId, holder, until, now);
+        return Number(result.changes) > 0;
+    }
+    /** Best-effort lease-column read used only to confirm genuine contention after {@link acquireEngineLease} exhausts its retries. `undefined` on any failure — never a diagnosis, just "couldn't confirm". */
+    tryReadLeaseColumns(runId) {
+        try {
+            return (this.db.prepare("SELECT engine_lease_holder, engine_lease_until FROM workflow_runs WHERE id = ?").get(runId) ?? undefined);
+        }
+        catch {
+            return undefined;
+        }
+    }
     // ── durable v4 append-only dispatch attempts (migration 022) ─────────────
     getUnitAttempts(runId, unitId) {
         return this.db

package/dist/workflows/exec/run-workflow.js

@@ -194,7 +194,7 @@ async function acquireRunLease(runId, holder) {
         const row = repo.getRunById(runId);
         throw new UsageError(`Workflow run ${runId} is already being driven by engine ${row?.engine_lease_holder ?? "(unknown)"} ` +
             `(run lease expires ${row?.engine_lease_until ?? "(unknown)"}). A second \`akm workflow run\` would race it — ` +
-            `wait for that invocation to finish or for the lease to expire.`);
+            `wait for that invocation to finish or for the lease to expire.`, "RUN_LEASE_HELD");
     }));
 }
 /**

package/dist/workflows/exec/step-work.js

@@ -18,6 +18,7 @@ import { createHash, randomUUID } from "node:crypto";
 import unitPreambleTemplate from "../../assets/prompts/workflow-unit-preamble.md" with { type: "text" };
 import { UsageError } from "../../core/errors.js";
 import { validateJsonSchemaSubset } from "../../core/json-schema.js";
+import { parseEmbeddedJsonResponse } from "../../core/parse.js";
 import { canonicalInputJson, validateInputs } from "../../execution/input-contract.js";
 import { withWorkflowRunsRepo, } from "../../storage/repositories/workflow-runs-repository.js";
 import { canonicalJson } from "../ir/plan-hash.js";
@@ -599,6 +600,41 @@ export function validateStepArtifact(plan, evidence) {
     return (`Step "${plan.stepId}" artifact failed validation against the step's declared output schema: ` +
         `${errors.join("; ")}.`);
 }
+/**
+ * Warn-only check of each successful unit's own promoted value against its
+ * template's declared `schema` (`unit.output`) — the one field a harness that
+ * cannot request structured output drops during lowering (`untranslated-field`,
+ * field `outputSchema`), after which nothing else ever compares the returned
+ * text to it. Unlike {@link validateStepArtifact} this never fails the step:
+ * a harness that DID honor the schema already returned a compliant `result`
+ * (this re-check then finds nothing), and one that could not is exactly the
+ * case this exists to surface — the run continues either way.
+ */
+export function unitSchemaWarning(plan, units) {
+    const schema = stepTemplate(plan)?.schema;
+    if (!schema)
+        return undefined;
+    const mismatches = [];
+    for (const unit of units) {
+        if (!unit.ok)
+            continue;
+        const candidate = unit.result !== undefined
+            ? unit.result
+            : unit.text !== undefined
+                ? parseEmbeddedJsonResponse(unit.text)
+                : undefined;
+        if (candidate === undefined) {
+            mismatches.push(`unit "${unit.unitId}" produced no structured output to check`);
+            continue;
+        }
+        const errors = validateJsonSchemaSubset(candidate, schema);
+        if (errors.length > 0)
+            mismatches.push(`unit "${unit.unitId}": ${errors.join("; ")}`);
+    }
+    if (mismatches.length === 0)
+        return undefined;
+    return `Output does not match the unit's declared schema (advisory; the run continued): ${mismatches.join("; ")}.`;
+}
 /**
  * Build the summary the completion-criteria gate judges for a step (addendum
  * R2, "typed artifacts, honest gates"): a one-line unit count followed by the
@@ -743,6 +779,11 @@ export function reduceStepOutcomes(plan, reducer, isFanOut, onError, units) {
             artifactSchemaFailure = true;
         }
     }
+    if (!artifactSchemaFailure) {
+        const schemaWarning = unitSchemaWarning(plan, units);
+        if (schemaWarning !== undefined)
+            summary += ` ${schemaWarning}`;
+    }
     // P3b §3.4: a composed child workflow that blocked is carried on the
     // failed unit's LIVE-ONLY `childRun` field (child-workflow.ts's
     // driveChildWorkflowUnit). Surfaced here, unconditionally on the unit

package/dist/workflows/parser.js

@@ -249,7 +249,7 @@ function bindStepSections(headings, lines, bodyStartLine, totalLines, path, decl
         if (!declaredIds.has(h.text)) {
             errors.push({
                 line: h.line,
-                message: `Unexpected level-2 heading "## ${h.text}" on line ${h.line} — no step "${h.text}" is declared in frontmatter "steps:". Level-2 headings must exactly match a declared step id.`,
+                message: `Unexpected level-2 heading "## ${h.text}" on line ${h.line} — no step "${h.text}" is declared in frontmatter "steps:". Level-2 headings must exactly match a declared step id. To document something that is not a step, use a level-3 heading.`,
             });
             continue;
         }

package/dist/workflows/runtime/runs.js

@@ -637,14 +637,33 @@ function readWorkflowRunOrPrefix(repo, specifier) {
     const run = findRunByIdOrPrefix(repo, specifier);
     if (!run)
         throw new NotFoundError(`Workflow run "${specifier}" not found.`, "WORKFLOW_NOT_FOUND");
-    return run;
+    return reclaimOrphanedEngineLease(repo, run);
 }
 function readWorkflowRun(repo, runId) {
     const run = repo.getRunById(runId);
     if (!run) {
         throw new NotFoundError(`Workflow run "${runId}" not found.`, "WORKFLOW_NOT_FOUND");
     }
-    return run;
+    return reclaimOrphanedEngineLease(repo, run);
+}
+/**
+ * Self-heal a run's engine lease once it has expired — the orphaned-lease
+ * case where an engine crashed without releasing it — mirroring the
+ * maintenance barrier's self-reclaim of a wedged sentinel, applied at the
+ * points a caller actually asks "what is this run's state". Never touches a
+ * live lease: {@link WorkflowRunsRepository.reclaimExpiredEngineLease} is a
+ * compare-and-swap on the exact (holder, until) this call observed, so a
+ * lease renewed or re-acquired between the read and this write is left alone.
+ */
+function reclaimOrphanedEngineLease(repo, run) {
+    const { engine_lease_holder: holder, engine_lease_until: until } = run;
+    if (!holder || !until)
+        return run;
+    const now = new Date().toISOString();
+    if (until >= now)
+        return run;
+    repo.reclaimExpiredEngineLease(run.id, holder, until, now);
+    return { ...run, engine_lease_holder: null, engine_lease_until: null };
 }
 function readWorkflowRunSteps(repo, runId) {
     return repo.getStepsForRun(runId);
@@ -758,8 +777,13 @@ function toWorkflowRunSummary(run) {
         executionSupport: plan.support,
         // Surface the engine lease (holder id + expiry — never workflow-authored
         // content) so `workflow run`/`status` show which native execution
-        // invocation currently holds the run lease.
-        ...(run.engine_lease_holder && run.engine_lease_until
+        // invocation currently holds the run lease. Gated on `until` still being
+        // in the future: a crashed engine's lease self-expires, and a run
+        // whose holder is provably gone must stop reading as engine-driven the
+        // instant that happens, not just once something next attempts to acquire
+        // it (`readWorkflowRun`/`readWorkflowRunOrPrefix` also reclaim the DB
+        // columns outright on the same condition).
+        ...(run.engine_lease_holder && run.engine_lease_until && run.engine_lease_until >= new Date().toISOString()
             ? { engineLease: { holder: run.engine_lease_holder, until: run.engine_lease_until } }
             : {}),
         // P3b (spec §4.5): all three optional and conditionally spread, so every
@@ -786,7 +810,7 @@ function assertLeaseAllowsSpineAdvance(run, leaseHolder) {
         return; // expired ⇒ claimable, not live
     throw new UsageError(`Workflow run ${run.id} is being driven by engine ${run.engine_lease_holder} ` +
         `(run lease expires ${run.engine_lease_until}). The engine owns the step spine while it runs — ` +
-        `wait for it to finish or for the lease to expire before advancing steps manually.`);
+        `wait for it to finish or for the lease to expire before advancing steps manually.`, "RUN_LEASE_HELD");
 }
 function toWorkflowRunStepState(step) {
     return {

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`

package/package.json

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