akm-cli 0.9.12 → 0.9.14-beta.1

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/migration/release-notes/0.9.14.md

@@ -0,0 +1,26 @@
+Migration notes for akm v0.9.14
+
+The derived `index.db` generation changes from v22 to v23 to support lexical
+Markdown fragments. On the first normal read after upgrade, akm detects that
+the v22 cache cannot serve queries and performs one inline v23 rebuild from
+currently materialized sources before serving the request. An explicit
+`akm index` performs the same writable rebuild. No hand-written database
+migration or manual deletion is needed, but the first rebuild may take longer
+than a normal read. Do not run an older akm against an index this release has
+already rebuilt: upgrade that binary instead. If v23 schema creation is
+interrupted, the partial cache is not admitted as current; the next writable
+open rebuilds it, while an existing/read-only opener reports that `akm index`
+is required.
+
+Search may now return an addressable `#akm-fragment-…` suffix for the matching
+part of a long Markdown asset. Pass that returned ref to `akm show` to display
+the exact indexed fragment.
+
+If you use collapse-detector canaries, their baseline predates the new index
+generation. After the `akm index` rebuild/reindex completes, explicitly mint a
+new set from the repository checkout:
+
+    bun scripts/refresh-canary-set.ts --refresh
+
+The refresh is deliberate and is never automatic, so historical canary cycles
+remain interpretable against their original baseline.

package/docs/migration/release-notes/README.md

@@ -7,6 +7,8 @@ live one level up in `docs/migration/`.
 
 ## Available notes
 
+- [0.9.14](0.9.14.md) — index v22-to-v23 derived-cache rebuild, lexical
+  fragments, and collapse-detector canary re-minting
 - [0.9.2](0.9.2.md) — task source v4 migration, workflow source IR v1 and
   durable-v4-family `irVersion: 5`, command diagnostics, and strategy judgment
   migration

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.14-beta.1",
   "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": [