akm-cli 0.9.6 → 0.9.8-beta.1

package/dist/storage/repositories/index-vec-repository.js

@@ -229,9 +229,14 @@ export function searchVec(db, queryEmbedding, k) {
                 .all(buf, k);
         }
         catch (err) {
-            // Log the failure so it's visible in diagnostics
-            warn("[db] searchVec (sqlite-vec path) failed:", err instanceof Error ? err.message : String(err));
-            return [];
+            // A dimension mismatch (e.g. the embedding provider/model changed since
+            // the fast-path table was built) is a real, expected reason this query
+            // specifically cannot use the vec table — the complete BLOB table below
+            // is unaffected, so fall back to it rather than either silently
+            // returning [] (masking a genuinely corrupt index) or failing the whole
+            // search over one degraded index.
+            warn("[db] searchVec (sqlite-vec path) failed, falling back to JS-cosine scan:", err instanceof Error ? err.message : String(err));
+            return searchBlobVec(db, queryEmbedding, k);
         }
     }
     // Fallback: JS-based cosine similarity over BLOB table
@@ -281,32 +286,25 @@ function bufferToFloat32(buf, expectedDim) {
     return Array.from(f32);
 }
 function searchBlobVec(db, queryEmbedding, k) {
-    try {
-        const rows = db.prepare("SELECT id, embedding FROM embeddings").all();
-        if (rows.length === 0)
-            return [];
-        const expectedDim = queryEmbedding.length;
-        const scored = [];
-        for (const row of rows) {
-            const embedding = bufferToFloat32(row.embedding, expectedDim);
-            if (embedding === null)
-                continue;
-            const similarity = cosineSimilarity(queryEmbedding, embedding);
-            scored.push({ id: row.id, similarity });
-        }
-        scored.sort((a, b) => b.similarity - a.similarity);
-        // Convert cosine similarity to L2 distance for compatibility with sqlite-vec interface
-        // For normalized vectors: L2² = 2(1 - cos_sim)
-        return scored.slice(0, k).map(({ id, similarity }) => ({
-            id,
-            distance: Math.sqrt(2 * Math.max(0, 1 - similarity)),
-        }));
-    }
-    catch (err) {
-        // MD-5: Log the failure so it's visible in diagnostics
-        warn("[db] searchBlobVec (JS fallback) failed:", err instanceof Error ? err.message : String(err));
+    const rows = db.prepare("SELECT id, embedding FROM embeddings").all();
+    if (rows.length === 0)
         return [];
+    const expectedDim = queryEmbedding.length;
+    const scored = [];
+    for (const row of rows) {
+        const embedding = bufferToFloat32(row.embedding, expectedDim);
+        if (embedding === null)
+            continue;
+        const similarity = cosineSimilarity(queryEmbedding, embedding);
+        scored.push({ id: row.id, similarity });
     }
+    scored.sort((a, b) => b.similarity - a.similarity);
+    // Convert cosine similarity to L2 distance for compatibility with sqlite-vec interface
+    // For normalized vectors: L2² = 2(1 - cos_sim)
+    return scored.slice(0, k).map(({ id, similarity }) => ({
+        id,
+        distance: Math.sqrt(2 * Math.max(0, 1 - similarity)),
+    }));
 }
 /**
  * Return all entries that do not yet have an embedding row.

package/dist/storage/repositories/task-history-repository.js

@@ -1,12 +1,18 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // 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/.
+/**
+ * Repository for the state.db `task_history` table (per-task run ledger,
+ * replaces the old per-task JSONL files). Extracted verbatim from
+ * core/state-db.ts — queries unchanged, only relocated behind the repository
+ * boundary. Re-exported by core/state-db.ts so existing importers resolve.
+ *
+ * @module task-history-repository
+ */
+import { isRecord } from "../../core/common.js";
 function metadataError(message) {
     throw new Error(`invalid task_history metadata_json: ${message}`);
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function validateDetail(value) {
     if (value === undefined || value === null)
         return;

package/dist/tasks/backends/cron.js

@@ -31,7 +31,7 @@ import { getTaskLogDir } from "../../core/paths.js";
 import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToCron } from "../schedule.js";
 import { assertSchedulerExecutionEvidenceDigest, assertSchedulerExpectationIdentity, assertSchedulerMutationArtifact, assertSchedulerNativeArtifactCardinality, assertSchedulerNativeArtifactOwner, assertSchedulerRemovalArtifact, assertSchedulerRollbackArtifactCardinality, schedulerBindingNativeId, schedulerLogicalBindingId, schedulerLogicalBindingOwner, schedulerNativeArtifactKey, } from "../scheduler-binding.js";
-import { buildScheduledBindingInvocation, parseScheduledBindingArgv, resolveScheduledTaskContext, schedulerContextDescriptor, schedulerContextPath, } from "../scheduler-invocation.js";
+import { buildScheduledBindingInvocation, parsePublicSchedulerInvocation, parseScheduledBindingArgv, resolveScheduledTaskContext, SCHEDULER_CONTEXT_ARG, schedulerContextDescriptor, schedulerContextPath, } from "../scheduler-invocation.js";
 import { nodeFs, throwIfNotOk } from "./exec-utils.js";
 const BEGIN = (id) => `# akm:task ${assertCronValue(id)} BEGIN`;
 const END = (id) => `# akm:task ${assertCronValue(id)} END`;
@@ -105,7 +105,7 @@ export function CRON_BACKEND(options = {}) {
             replaceCrontab(exec, existing, next);
         },
         list() {
-            return [...inspectCronState(readCrontab(exec)).installed];
+            return [...inspectCronState(readCrontab(exec), defaultContextPath).installed];
         },
         listForRebind() {
             const existing = readCrontab(exec);
@@ -123,14 +123,14 @@ export function CRON_BACKEND(options = {}) {
             });
         },
         listNativeArtifacts() {
-            return [...inspectCronState(readCrontab(exec)).artifacts];
+            return [...inspectCronState(readCrontab(exec), defaultContextPath).artifacts];
         },
         inspectBindings() {
-            return inspectCronState(readCrontab(exec));
+            return inspectCronState(readCrontab(exec), defaultContextPath);
         },
         snapshotBindings(ids) {
             const crontab = readCrontab(exec);
-            const inspection = inspectCronState(crontab);
+            const inspection = inspectCronState(crontab, defaultContextPath);
             const keys = new Set(ids.map(schedulerNativeArtifactKey));
             return Object.freeze({
                 kind: CRON_SNAPSHOT,
@@ -144,7 +144,7 @@ export function CRON_BACKEND(options = {}) {
                 throw new ConfigError("Invalid cron scheduler snapshot.", "INVALID_CONFIG_FILE");
             }
             const existing = readCrontab(exec);
-            const current = inspectCronState(existing);
+            const current = inspectCronState(existing, defaultContextPath);
             const safeNativeIds = [];
             const errors = [];
             if (expectedCurrent) {
@@ -192,7 +192,7 @@ export function CRON_BACKEND(options = {}) {
         },
     };
 }
-function inspectCronState(crontab) {
+function inspectCronState(crontab, fallbackContextPath) {
     const installed = [];
     const artifacts = [];
     for (const { id, body } of listBlocks(crontab)) {
@@ -207,7 +207,14 @@ function inspectCronState(crontab) {
             signature: fingerprint,
             ...(parsed.target !== undefined ? { target: parsed.target } : {}),
             binding: parsed.binding,
-            contextPath: parsed.contextPath,
+            // A legacy (pre-`--scheduler-context`) row has no real descriptor
+            // path to report — `extractLegacyCronInvocation` leaves it "". Fall
+            // back to the current default so downstream consumers (context
+            // validation in `akm task prune`/`explain`, `sync`'s reuse of an
+            // existing binding's contextPath) see a real, resolvable descriptor
+            // rather than an empty path, since the row is about to be reconciled
+            // to a current one anyway (#881).
+            contextPath: parsed.contextPath || fallbackContextPath,
         };
         Object.defineProperty(ref, "nativeId", { value: id });
         Object.defineProperty(ref, "invocation", { value: Object.freeze([...parsed.invocation]) });
@@ -323,7 +330,40 @@ export function extractCronInvocation(body) {
     const redirectIndex = fields.indexOf(">>", commandStart);
     if (redirectIndex === -1)
         return undefined;
-    return parseScheduledBindingArgv(fields.slice(commandStart, redirectIndex));
+    const tail = fields.slice(commandStart, redirectIndex);
+    const parsed = parseScheduledBindingArgv(tail);
+    if (parsed)
+        return parsed;
+    // Rows written by akm < 0.9.2 (before `--scheduler-context` existed) have
+    // no context argument at all — just the akm argv immediately followed by
+    // the public `task run …` / `workflow run …` tail. `extractCronInvocation`
+    // only ever runs on a body already isolated between this backend's own
+    // `# akm:task … BEGIN/END` sentinels (see `parseBlocks`), so recognizing
+    // this older shape here doesn't extend trust to any unmarked crontab
+    // line — it only lets sync see and reconcile a row akm already owns
+    // instead of treating it as absent and colliding with the still-present
+    // artifact (#881). Guarded on the marker's absence so a row that DOES
+    // carry `--scheduler-context` but fails to parse for some other reason
+    // is never silently reinterpreted as legacy.
+    if (tail.includes(SCHEDULER_CONTEXT_ARG))
+        return undefined;
+    return extractLegacyCronInvocation(tail);
+}
+function extractLegacyCronInvocation(tail) {
+    for (let index = 0; index < tail.length - 1; index += 1) {
+        if ((tail[index] === "task" || tail[index] === "workflow") && tail[index + 1] === "run") {
+            const publicInvocation = parsePublicSchedulerInvocation(tail.slice(index));
+            if (!publicInvocation)
+                return undefined;
+            return {
+                binding: tail.slice(0, index),
+                contextPath: "",
+                invocation: publicInvocation.invocation,
+                ...(publicInvocation.target !== undefined ? { target: publicInvocation.target } : {}),
+            };
+        }
+    }
+    return undefined;
 }
 /** Reverse {@link quoteForCron} for a single whitespace-free token. */
 function splitCronShellWords(value) {

package/dist/tasks/backends/launchd.js

@@ -25,6 +25,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import launchdTemplate from "../../assets/backends/launchd-template.xml" with { type: "text" };
+import { hasErrnoCode } from "../../core/common.js";
 import { ConfigError } from "../../core/errors.js";
 import { getTaskLogDir } from "../../core/paths.js";
 import { resolveAkmInvocation } from "../resolve-akm-bin.js";
@@ -851,22 +852,6 @@ export function parseLaunchdLoadedLabels(output) {
     }
     return labels;
 }
-function countCharacter(value, needle) {
-    let count = 0;
-    for (const character of value)
-        if (character === needle)
-            count += 1;
-    return count;
-}
-function hasUnsafeLaunchdControlCharacter(output) {
-    for (let index = 0; index < output.length; index += 1) {
-        const code = output.charCodeAt(index);
-        if (code <= 8 || code === 11 || code === 12 || (code >= 14 && code <= 31) || (code >= 127 && code <= 159)) {
-            return true;
-        }
-    }
-    return false;
-}
 function readDisabledLabels(exec) {
     try {
         const result = exec.run(["launchctl", "print-disabled", `gui/${exec.uid()}`]);
@@ -933,8 +918,13 @@ function defaultLaunchdFs() {
             try {
                 return fs.readdirSync(dir);
             }
-            catch {
-                return [];
+            catch (error) {
+                // Genuinely absent is an empty listing; anything else (e.g. EACCES) is
+                // not "no plists" — surfacing it as such could make inspectBindings
+                // think there is nothing to reconcile.
+                if (hasErrnoCode(error, "ENOENT"))
+                    return [];
+                throw new ConfigError(`Unable to read LaunchAgents directory at "${dir}".`, "INVALID_CONFIG_FILE");
             }
         },
         exists(file) {

package/dist/tasks/resolve-akm-bin.js

@@ -10,7 +10,11 @@
  * Resolution order:
  *
  *   1. `process.execPath` alone for a Bun standalone executable.
- *   2. Absolute Node plus the public `dist/akm` package launcher.
+ *   2. Absolute Node plus the public `dist/akm` package launcher — eligible
+ *      when it is the active npm global install, or when this process
+ *      cannot write to the directory containing it (a read-only mount, e.g.
+ *      an image-baked install, gives the same "won't change out from under
+ *      the scheduler" guarantee npm-global ownership does).
  *   3. Absolute runtime plus the source/build CLI entry, classified as a
  *      checkout that requires explicit `--rebind` for scheduler writes.
  *
@@ -51,12 +55,13 @@ export function resolveAkmInvocation(options = {}) {
             }
         }
         const npmGlobal = !checkout && packageBelongsToNpmGlobalRoot(launcherPath, npmGlobalRoot);
+        const readOnlyInstall = !checkout && !npmGlobal && !(options.isPathWritable ?? isPathWritable)(path.dirname(launcherPath));
         const kind = checkout ? "checkout" : npmGlobal ? "npm" : "package-local";
         return {
             argv: [absoluteInvocationPath(nodePath), absoluteInvocationPath(launcherPath)],
             via: kind,
             kind,
-            eligible: npmGlobal,
+            eligible: npmGlobal || readOnlyInstall,
         };
     }
     const checkoutEntry = resolveCheckoutEntry(options.cliEntryUrl ?? import.meta.url, runtime, mainPath);
@@ -117,6 +122,16 @@ function isCheckoutLauncher(file) {
     const packageRoot = path.dirname(path.dirname(launcher));
     return fs.existsSync(path.join(packageRoot, ".git"));
 }
+/** Whether this process can write to `dir` — false also covers a read-only mount. */
+function isPathWritable(dir) {
+    try {
+        fs.accessSync(dir, fs.constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function packageBelongsToNpmGlobalRoot(launcherPath, npmGlobalRoot) {
     if (!npmGlobalRoot)
         return false;

package/dist/tasks/run/task-history.js

@@ -14,20 +14,15 @@
  *
  * D8 result-vocabulary re-code (why, and the WRITE side's exact shape): see
  * docs/architecture/decisions/0005-task-result-vocabulary-and-legacy-read-mapping.md.
- * The READ side's mapping rule is a PERMANENT invariant kept here, not moved
- * — a maintainer touching `taskHistoryRowToResult` needs it right here, and
- * row B-51 (docs/plans/specs/p4-deletions-closeout.md) makes deleting it a
- * review-blocking violation: it reads rows written by every previous
- * release, forever.
- *
- *   A legacy row (no `targetVocab` marker — written before D8) maps:
- *   `"prompt"` -> `{kind:"command", engine}`, `"command"` -> `{kind:"shell"}`,
- *   `"workflow"` unchanged, anything else (including the new vocabulary's own
- *   "shell"/"script"/"prompt" written WITHOUT a marker, which no production
- *   writer ever does) -> `"unknown"`. The P0-pinned null fallbacks survive:
- *   workflow `ref` falls back to `""`, the command/prompt arm's `engine`
- *   falls back to `null`. A row carrying `targetVocab: 2` reads `target_kind`
- *   directly in the current vocabulary — no mapping needed.
+ * The READ side used to carry a permanent legacy-vocabulary mapping here
+ * (row B-51 of docs/plans/specs/p4-deletions-closeout.md called deleting it
+ * "review-blocking") — SUPERSEDED: `task_history` is DB-owned data, so the
+ * remap is now a one-time schema migration
+ * (`025-task-history-vocabulary-backfill` in src/core/state/migrations.ts)
+ * instead of a read-side shim run forever. Every row this function sees now
+ * carries the current vocabulary's `target_kind` strings; the P0-pinned null
+ * fallbacks still apply (workflow `ref` falls back to `""`, the command
+ * arm's `engine` falls back to `null`).
  *
  * A DAG leaf with respect to the rest of src/tasks/run/**: this module
  * imports TaskRunResult/TaskRunStatus's TYPE from ./task-result but no VALUE
@@ -37,6 +32,7 @@
  */
 import { rethrowIfTestIsolationError } from "../../core/errors.js";
 import { withStateDb } from "../../core/state-db.js";
+import { warn } from "../../core/warn.js";
 import { decodeTaskHistoryMetadata, finalizeTaskHistoryAttempt, getTaskHistory, getTaskHistoryRuns, queryTaskHistory, upsertTaskHistory, } from "../../storage/repositories/task-history-repository.js";
 /** Append (or finalize a reserved attempt into) one task_history row. */
 export function appendHistory(result, historyReserved = false) {
@@ -67,7 +63,11 @@ export function appendHistory(result, historyReserved = false) {
     }
     catch (error) {
         rethrowIfTestIsolationError(error);
-        // History recording is fully best-effort and must not alter CLI output.
+        // History recording must not alter the task's own result/exit status —
+        // the task already ran and its outcome is independent of whether we can
+        // persist a history row. But silence would make a failed write
+        // indistinguishable from the task never having run, so warn.
+        warn(`task history: failed to record history for task ${result.id}: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
 export function readTaskHistory(options = {}) {
@@ -111,32 +111,22 @@ function decodeTaskHistoryRows(rows) {
  * Convert a `TaskHistoryRow` from state.db back to a `TaskRunResult` shape
  * that callers of `readTaskHistory()` expect.
  *
- * D8 read boundary (spec §5.3): branches on the decoded metadata's
- * `targetVocab` marker — see the module header's table.
+ * Reads `target_kind` directly in the current (post-D8) vocabulary — the
+ * `025-task-history-vocabulary-backfill` state migration rewrites every
+ * legacy-vocabulary row before this ever runs against it.
  */
 function taskHistoryRowToResult(row) {
     const meta = decodeTaskHistoryMetadata(row.metadata_json);
-    const marked = meta.targetVocab === 2;
     const target = (() => {
         switch (row.target_kind) {
             case "workflow":
-                // PRESERVED for both vintages (incl. the null-ref fallback).
                 return { kind: "workflow", ref: row.target_ref ?? "" };
             case "command":
-                // NEW vocabulary: a prepared command (agent/LLM) result.
-                // LEGACY vocabulary: the native shell/script arm's shared string.
-                return marked ? { kind: "command", engine: meta.engine ?? null } : { kind: "shell" };
+                return { kind: "command", engine: meta.engine ?? null };
             case "shell":
-                // Only the NEW vocabulary ever writes this string; an unmarked
-                // "shell" row is unreachable from any production writer.
-                return marked ? { kind: "shell" } : { kind: "unknown" };
+                return { kind: "shell" };
             case "script":
-                // Only the NEW vocabulary ever writes this string; an unmarked
-                // "script" row is unreachable from any production writer.
-                return marked ? { kind: "script" } : { kind: "unknown" };
-            case "prompt":
-                // Only LEGACY rows (pre-P1b) ever wrote this string.
-                return marked ? { kind: "unknown" } : { kind: "command", engine: meta.engine ?? null };
+                return { kind: "script" };
             default:
                 return { kind: "unknown" };
         }

package/dist/tasks/scheduler-invocation.js

@@ -189,7 +189,14 @@ export function parseScheduledBindingArgv(argv) {
         ...(publicInvocation.target !== undefined ? { target: publicInvocation.target } : {}),
     };
 }
-function parsePublicSchedulerInvocation(invocation) {
+/**
+ * Parse just the public `task run …` / `workflow run …` tail, with no
+ * `--scheduler-context` wrapper. Exported so a backend can recognize a
+ * pre-`--scheduler-context` invocation still sitting inside akm's own
+ * ownership-marked block (see `extractCronInvocation` in
+ * `src/tasks/backends/cron.ts`) without re-implementing this grammar.
+ */
+export function parsePublicSchedulerInvocation(invocation) {
     if (invocation[0] === "task" && invocation[1] === "run" && invocation[2]) {
         try {
             if (normaliseTaskConceptId(invocation[2]) !== invocation[2])

package/dist/tasks/scheduler-sync.js

@@ -6,6 +6,7 @@ import { createHash } from "node:crypto";
 import path from "node:path";
 import { loadAdapterExecutionSource } from "../commands/command/execution-source-loader.js";
 import { makeBundleRef } from "../core/asset/asset-ref.js";
+import { compareCodePoints, toPosix } from "../core/common.js";
 import { UsageError } from "../core/errors.js";
 import { canonicalizeWorkflowName, WORKFLOW_EXTENSIONS } from "../core/recognition-util.js";
 import { captureGuardedDirectoryManifest, captureGuardedExecutionSource, GuardedExecutionSourceCollector, } from "../execution/guarded-source.js";
@@ -742,12 +743,6 @@ function freezeOperation(operation) {
 function sameInvocation(left, right) {
     return left.length === right.length && left.every((value, index) => value === right[index]);
 }
-function compareCodePoints(left, right) {
-    return left < right ? -1 : left > right ? 1 : 0;
-}
-function toPosix(value) {
-    return value.replaceAll("\\", "/");
-}
 // Retain the concrete error in this module's public dependency graph so callers
 // can continue to identify ownership failures without importing an adapter.
 export { WorkflowSourceRejectionError };

package/dist/tasks/source/bounded-document.js

@@ -47,6 +47,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { types as utilTypes } from "node:util";
 import { isAlias, isMap, isScalar, isSeq, LineCounter, parseDocument } from "yaml";
+import { wellFormedUnicode } from "../../core/common.js";
 import { UsageError } from "../../core/errors.js";
 import { DURATION_UNITS, parseDuration } from "../../core/time.js";
 import { EXECUTION_MAX_TIMEOUT_MS } from "../../execution/limits.js";
@@ -67,20 +68,6 @@ export function own(value, key) {
 export function utf8Bytes(value) {
     return new TextEncoder().encode(value).byteLength;
 }
-export function wellFormedUnicode(value) {
-    for (let index = 0; index < value.length; index += 1) {
-        const code = value.charCodeAt(index);
-        if (code >= 0xd800 && code <= 0xdbff) {
-            const next = value.charCodeAt(index + 1);
-            if (!(next >= 0xdc00 && next <= 0xdfff))
-                return false;
-            index += 1;
-        }
-        else if (code >= 0xdc00 && code <= 0xdfff)
-            return false;
-    }
-    return true;
-}
 /** The one per-field error funnel both grammars render through, distinguished only by `ctx.sourceLabel` (D2-N4). */
 export function sourceError(ctx, fieldPath, detail) {
     const dotted = fieldPath.length === 0

package/dist/tasks/source/parse-task-source.js

@@ -17,7 +17,7 @@
  *   | root `version`        | outcome                                                        |
  *   |------------------------|-----------------------------------------------------------------|
  *   | `4`                    | `parseTaskSourceV4Document` — the new grammar (row B-13)        |
- *   | `2` or `3`             | in-memory read shim (below): the SAME pure planners `akm migrate apply` uses (`./task-to-v3.ts`, `./task-to-v4.ts`) convert the bytes already in hand to v4 in memory; the result is parsed and returned with a one-line stderr deprecation warning. If the deterministic conversion itself fails (an unmigratable shape), falls back to `TASK_SCHEMA_VERSION_UNSUPPORTED`, naming the migrator (B-14/B-15) — the shim removes friction for the deterministic case, it never hides a real problem |
+ *   | `2` or `3`             | in-memory read shim (below): the SAME pure planners `akm migrate apply` uses (`./task-to-v3.ts`, `./task-to-v4.ts`) convert the bytes already in hand to v4 in memory; the result is parsed and returned with a one-line stderr deprecation warning. If the deterministic conversion itself fails (an unmigratable shape — the file needs a human decision, not a re-run), falls back to `TASK_SCHEMA_VERSION_UNSUPPORTED` naming the specific blocked reason (issue #869) — the shim removes friction for the deterministic case, it never hides a real problem |
  *   | any other number       | `TASK_SCHEMA_VERSION_UNSUPPORTED`, naming the migrator (B-14/B-15) |
  *   | absent / not a number  | `parseTaskSourceV4Document` — its own `TASK_SOURCE_INVALID` "version is required and must be 4" / "must be exactly 4" wording (row B-16) |
  *
@@ -57,6 +57,18 @@ export function peekTaskSourceVersion(root) {
     return typeof value === "number" ? value : undefined;
 }
 const TASK_MIGRATE_HINT = "Run `akm migrate apply --dry-run` to preview the task-v3 to task-source-v4 conversion, then run `akm migrate apply`.";
+/**
+ * Thrown only when the deterministic conversion itself could not produce a
+ * task source v4 document — a case where a person must decide the intended
+ * behavior (e.g. an ambiguous shell command), not one the migrator can just
+ * be re-run to fix. `reason`/`detail` are the SAME blocked outcome
+ * `akm migrate status`/`apply` reports for this file, so the message names
+ * the actual decision instead of pointing at a command that will report the
+ * identical block.
+ */
+function unmigratableVersionError(filePath, version, reason, detail) {
+    return new UsageError(`TASK_SCHEMA_VERSION_UNSUPPORTED: Task at ${filePath} uses task schema version ${version} and needs a human decision before it can run — the deterministic migrator cannot convert it automatically (${reason}${detail ? `: ${detail}` : ""}).`, "TASK_SCHEMA_VERSION_UNSUPPORTED", "Review the file and resolve the ambiguity by hand, then it will convert normally; `akm migrate status` reports the same reason.");
+}
 function unsupportedVersionError(filePath, version) {
     return new UsageError(`TASK_SCHEMA_VERSION_UNSUPPORTED: Task at ${filePath} uses task schema version ${version}, which this release does not accept.`, "TASK_SCHEMA_VERSION_UNSUPPORTED", TASK_MIGRATE_HINT);
 }
@@ -64,9 +76,10 @@ function unsupportedVersionError(filePath, version) {
  * Plan the SAME bytes already in hand through the pure v3->v4 (and, for v2,
  * chained v2->v3->v4) migration planner(s) — never touches disk, never
  * writes the file, never re-reads it from disk. Returns the produced v4
- * YAML text, or `undefined` when the deterministic conversion cannot
- * proceed (an unmigratable v2/v3 shape) — the caller falls back to the same
- * hard error this gate threw before the shim existed.
+ * YAML text, or the blocked reason/detail when the deterministic conversion
+ * cannot proceed (an unmigratable v2/v3 shape) — the caller falls back to
+ * the same hard error this gate threw before the shim existed, now naming
+ * that reason.
  */
 function planInMemoryV4Bytes(version, yaml, filePath, workspaceRoot) {
     const bytes = Buffer.from(yaml, "utf8");
@@ -89,12 +102,12 @@ function planInMemoryV4Bytes(version, yaml, filePath, workspaceRoot) {
     else {
         const v3Outcome = planTaskToV3File(baseInput);
         if (v3Outcome.status !== "changed")
-            return undefined;
+            return { reason: v3Outcome.reason, detail: v3Outcome.detail };
         v3Bytes = v3Outcome.after;
     }
     const v4Outcome = planTaskToV4File({ ...baseInput, bytes: v3Bytes });
     if (v4Outcome.status !== "changed")
-        return undefined;
+        return { reason: v4Outcome.reason, detail: v4Outcome.detail };
     return v4Outcome.after.toString("utf8");
 }
 /** Parse task source YAML, routing per the terminal table above. */
@@ -103,16 +116,17 @@ export function parseTaskSource(input) {
     const version = peekTaskSourceVersion(root);
     if (version !== undefined && version !== TASK_SOURCE_V4_VERSION) {
         if (version === 2 || version === 3) {
-            const v4Yaml = planInMemoryV4Bytes(version, input.yaml, input.filePath, input.workspaceRoot);
-            if (v4Yaml !== undefined) {
+            const shimmed = planInMemoryV4Bytes(version, input.yaml, input.filePath, input.workspaceRoot);
+            if (typeof shimmed === "string") {
                 const v4 = parseTaskSourceV4({
-                    yaml: v4Yaml,
+                    yaml: shimmed,
                     filePath: input.filePath,
                     ...(input.workspaceRoot ? { workspaceRoot: input.workspaceRoot } : {}),
                 });
                 warn(`akm: task ${input.filePath} uses schema v${version} — auto-read as v4; run \`akm migrate apply\` to rewrite it and silence this`);
                 return Object.freeze({ version: 4, v4 });
             }
+            throw unmigratableVersionError(input.filePath, version, shimmed.reason, shimmed.detail);
         }
         throw unsupportedVersionError(input.filePath, version);
     }

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

@@ -284,7 +284,7 @@ async function driveChildRun(input, childRow) {
  * before step 6 (publication) produces `child_workflow_publish_failed`.
  */
 export async function driveChildWorkflowUnit(input) {
-    const { request, target, ctx } = input;
+    const { request, ctx } = input;
     const precheck = precheckAndDeriveInvocationKey(input);
     if (!precheck.ok) {
         return precheck.outcome;

package/dist/workflows/exec/native-executor.js

@@ -708,7 +708,7 @@ async function prepareAttemptWorktree(input) {
     }
     return { ok: true, request: { ...input.request, cwd: created.path }, worktreePath: created.path };
 }
-async function reserveJournaledDispatch(input, request, worktreePath, startedAt) {
+async function reserveJournaledDispatch(input, worktreePath, startedAt) {
     const { plan, workUnit, ctx, attemptId, inputHash } = input;
     let durableAttempt;
     await enqueueUnitWrite(async () => {
@@ -799,7 +799,7 @@ async function dispatchJournaledAttempt(input) {
     const startedAt = new Date().toISOString();
     let durableAttempt;
     try {
-        durableAttempt = await reserveJournaledDispatch(input, request, worktreePath, startedAt);
+        durableAttempt = await reserveJournaledDispatch(input, worktreePath, startedAt);
     }
     catch (err) {
         // A failed dispatch-row insert means NOTHING dispatched (the row is the

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

@@ -20,7 +20,7 @@ import { UsageError } from "../../core/errors.js";
 import { validateJsonSchemaSubset } from "../../core/json-schema.js";
 import { canonicalInputJson, validateInputs } from "../../execution/input-contract.js";
 import { withWorkflowRunsRepo, } from "../../storage/repositories/workflow-runs-repository.js";
-import { canonicalJson as canonicalJsonString } from "../ir/plan-hash.js";
+import { canonicalJson } from "../ir/plan-hash.js";
 import { parseReference, resolveReferenceString, } from "../program/expressions.js";
 import { clip, WORKFLOW_UNIT_DIAGNOSTIC_CLIP } from "../resource-limits.js";
 import { completeWorkflowStep, isTruncatedEvidence, } from "../runtime/runs.js";
@@ -463,7 +463,7 @@ function buildExecContextEnv(args) {
 function computeUnitInputHash(ctx, item) {
     return createHash("sha256")
         .update("akm.workflow.unit\0v7\0")
-        .update(canonicalJsonString({
+        .update(canonicalJson({
         hashVersion: 7,
         role: "unit",
         stepId: ctx.plan.stepId,
@@ -855,20 +855,8 @@ export function unitOutcomeFromRow(unitId, row, hasSchema) {
         ...(row.tokens !== null ? { tokens: row.tokens } : {}),
     };
 }
-/** Stable stringify (sorted object keys, recursively) so equal values vote together. */
-export function canonicalJson(value) {
-    return JSON.stringify(sortKeys(value));
-}
-function sortKeys(value) {
-    if (Array.isArray(value))
-        return value.map(sortKeys);
-    if (value && typeof value === "object") {
-        return Object.fromEntries(Object.entries(value)
-            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
-            .map(([k, v]) => [k, sortKeys(v)]));
-    }
-    return value;
-}
+/** Re-exported so existing importers (`tests/workflows/fuzz/*`) keep resolving; canonical impl lives in `../ir/plan-hash`. */
+export { canonicalJson };
 // ── Gate-feedback recovery (PURE) ────────────────────────────────────────────
 //
 // A gate rejection is journaled as `<stepId>.gate:l<loop>` with result_json
@@ -1431,7 +1419,7 @@ export async function finalizeExecutedStep(input) {
                     // fields are unchanged).
                     inputHash: createHash("sha256")
                         .update("akm.workflow.gate\0v7\0")
-                        .update(canonicalJsonString({
+                        .update(canonicalJson({
                         hashVersion: 7,
                         dispatch: gateTarget,
                         invocation: null,