akm-cli 0.9.3 → 0.9.5

package/dist/tasks/source/task-to-v4.js

@@ -0,0 +1,457 @@
+// 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/.
+/**
+ * Pure, byte-producing task-v3 to task-source-v4 migration planner (spec
+ * docs/plans/specs/p2b-input-bindings.md §1.3, §1.7 C-N1, §5). Mirrors
+ * `task-to-v3.ts`'s fail-closed ladder exactly: the INPUT side is read as a
+ * raw record by a vendored bounded-YAML reader (never the typed
+ * `parseTaskV3Yaml`, which would normalize away exactly the value bytes this
+ * migrator must preserve — a duration string like "5m", or a bare numeric
+ * `timeout`, would be converted to milliseconds by the real parser). The
+ * OUTPUT side is validated through the REAL `parseTaskSourceV4` before a
+ * "changed" outcome is ever handed back (C-N1, B-71).
+ *
+ * `inputs:` is never invented — the migrator translates structure, not
+ * intent (spec §5.3).
+ */
+import crypto from "node:crypto";
+import path from "node:path";
+import { LineCounter, parseDocument, stringify as stringifyYaml } from "yaml";
+import { assertBoundedTaskYamlDocument, TASK_V3_MAX_SOURCE_BYTES } from "./bounded-document.js";
+import { classifyTaskV3Uses } from "./task-source-v3-frozen.js";
+import { parseTaskSourceV4 } from "./task-source-v4.js";
+/** The closed v3 top-level key set (`src/tasks/source-v3.ts`'s own, vendored — not exported there). */
+const V3_TOP_LEVEL_KEYS = new Set([
+    "version",
+    "name",
+    "uses",
+    "run",
+    "with",
+    "env",
+    "shell",
+    "working-directory",
+    "akm",
+    "on",
+]);
+/** The closed v3 `akm.*` key set, vendored from `src/tasks/source-v3.ts`. */
+const V3_AKM_KEYS = new Set([
+    "schedule",
+    "enabled",
+    "description",
+    "when_to_use",
+    "tags",
+    "agent",
+    "engine",
+    "model",
+    "inference",
+    "outputSchema",
+    "tools",
+    "timeout",
+    "redact",
+    "maxSteps",
+    "maxRetries",
+]);
+/** The closed v3 `on.*` key set, vendored from `src/tasks/source-v3.ts`. */
+const V3_ON_KEYS = new Set(["schedule", "workflow_dispatch"]);
+/** `akm.*` keys hoisted verbatim to the identical top-level v4 key (schedule/enabled handled separately). */
+const AKM_HOIST_KEYS = [
+    "description",
+    "when_to_use",
+    "tags",
+    "agent",
+    "engine",
+    "model",
+    "inference",
+    "tools",
+    "timeout",
+    "redact",
+    "maxSteps",
+    "maxRetries",
+];
+function hash(bytes) {
+    return crypto.createHash("sha256").update(bytes).digest("hex");
+}
+function causeMessage(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+function base(input) {
+    return {
+        filePath: input.filePath,
+        before: Buffer.from(input.bytes),
+        beforeHash: hash(input.bytes),
+        mode: input.mode,
+        writable: input.writable,
+        ...(input.onDiskWritable !== undefined ? { onDiskWritable: input.onDiskWritable } : {}),
+        ...(input.containmentRoot ? { containmentRoot: input.containmentRoot } : {}),
+    };
+}
+function blocked(input, reason, detail) {
+    return Object.freeze({ status: "blocked", ...base(input), reason, ...(detail ? { detail } : {}) });
+}
+function plainRecord(value, label) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be a mapping`);
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new Error(`${label} must use a plain or null prototype`);
+    }
+    return value;
+}
+function exactString(value, label, nonempty = false) {
+    if (typeof value !== "string" || (nonempty && value.trim().length === 0)) {
+        throw new Error(`${label} must be ${nonempty ? "a non-empty " : "a "}string`);
+    }
+    return value;
+}
+/**
+ * Vendored raw-record reader (mirrors `task-to-v3.ts`'s `parseLegacyTaskYaml`
+ * exactly). Reading the RAW decoded record — rather than the typed
+ * `parseTaskV3Yaml` — keeps every field's original value bytes (a duration
+ * string, a bare millisecond integer, an env value's exact type) intact for
+ * verbatim re-emission; a typed v3 parse would normalize several of these
+ * away (C-N1).
+ */
+function parseV3RawYaml(input) {
+    if (input.bytes.byteLength > TASK_V3_MAX_SOURCE_BYTES) {
+        throw new Error(`task YAML exceeds the 1 MiB (${TASK_V3_MAX_SOURCE_BYTES}-byte) source resource limit`);
+    }
+    let source;
+    try {
+        source = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(input.bytes);
+    }
+    catch {
+        throw new Error("task YAML contains invalid UTF-8 bytes");
+    }
+    const lineCounter = new LineCounter();
+    let document;
+    try {
+        document = parseDocument(source, { lineCounter, uniqueKeys: true });
+    }
+    catch (cause) {
+        throw new Error(`invalid YAML: ${causeMessage(cause)}`);
+    }
+    const [parseError] = document.errors;
+    if (parseError)
+        throw new Error(`invalid YAML: ${parseError.message.split("\n")[0]}`);
+    const [parseWarning] = document.warnings;
+    if (parseWarning)
+        throw new Error(`unsupported YAML construct: ${parseWarning.message}`);
+    assertBoundedTaskYamlDocument(document, {
+        filePath: input.filePath,
+        sourceLabel: "task v3 migration source",
+        lineCounter,
+    });
+    return { data: plainRecord(document.toJS({ maxAliasCount: 0 }), "task YAML"), source };
+}
+/** Convert one already-validated v3 raw record to final task source v4 bytes. */
+function planV3DataToV4(input, data) {
+    const unknownTop = Object.keys(data).filter((key) => !V3_TOP_LEVEL_KEYS.has(key));
+    if (unknownTop.length > 0) {
+        return blocked(input, "invalid-v3-task", `unknown v3 field(s): ${unknownTop.join(", ")}`);
+    }
+    const hasUses = Object.hasOwn(data, "uses");
+    const hasRun = Object.hasOwn(data, "run");
+    if (hasUses === hasRun) {
+        return blocked(input, "invalid-v3-task", "requires exactly one executable selector: uses or run");
+    }
+    let akm;
+    if (Object.hasOwn(data, "akm")) {
+        try {
+            akm = plainRecord(data.akm, "akm");
+        }
+        catch (cause) {
+            return blocked(input, "invalid-v3-task", causeMessage(cause));
+        }
+        const unknownAkm = Object.keys(akm).filter((key) => !V3_AKM_KEYS.has(key));
+        if (unknownAkm.length > 0) {
+            return blocked(input, "unrecognized-akm-member", `akm has unknown field(s): ${unknownAkm.join(", ")}`);
+        }
+        if (Object.hasOwn(akm, "enabled") && typeof akm.enabled !== "boolean") {
+            return blocked(input, "invalid-v3-task", "akm.enabled must be a boolean");
+        }
+        if (Object.hasOwn(akm, "schedule") && typeof akm.schedule !== "string") {
+            return blocked(input, "invalid-v3-task", "akm.schedule must be a string");
+        }
+    }
+    const hasOn = Object.hasOwn(data, "on");
+    let onRecord;
+    if (hasOn) {
+        try {
+            onRecord = plainRecord(data.on, "on");
+        }
+        catch (cause) {
+            return blocked(input, "invalid-v3-task", causeMessage(cause));
+        }
+        // Mirrors the frozen v3 reader's own `parseOn` gates exactly
+        // (task-source-v3-frozen.ts:395-427): an empty `on: {}` declares no
+        // trigger at all, and `on.workflow_dispatch` accepts only null or an
+        // empty mapping (inputs are unsupported in v3). The frozen parser
+        // rejects both shapes outright, so this migrator must too — translating
+        // a document the v3 oracle would refuse to parse into runnable v4 bytes
+        // would launder invalid input into a valid, schedule-less task.
+        if (Object.keys(onRecord).length === 0) {
+            return blocked(input, "invalid-v3-task", "on must declare schedule and/or workflow_dispatch.");
+        }
+        const unknownOn = Object.keys(onRecord).filter((key) => !V3_ON_KEYS.has(key));
+        if (unknownOn.length > 0) {
+            return blocked(input, "invalid-v3-task", `on has unknown field(s): ${unknownOn.join(", ")}`);
+        }
+        if (Object.hasOwn(onRecord, "workflow_dispatch") && onRecord.workflow_dispatch !== null) {
+            let dispatchMapping;
+            try {
+                dispatchMapping = plainRecord(onRecord.workflow_dispatch, "on.workflow_dispatch");
+            }
+            catch (cause) {
+                return blocked(input, "invalid-v3-task", causeMessage(cause));
+            }
+            if (Object.keys(dispatchMapping).length > 0) {
+                return blocked(input, "invalid-v3-task", "on.workflow_dispatch must be null or an empty mapping; inputs are unsupported.");
+            }
+        }
+    }
+    const hasAkmSchedule = akm !== undefined && Object.hasOwn(akm, "schedule");
+    if (hasAkmSchedule && hasOn) {
+        return blocked(input, "ambiguous-scheduling-source", "declares both akm.schedule and on:; task v3 requires exactly one scheduling source and the migrator will not guess which one wins.");
+    }
+    if (!hasAkmSchedule && !hasOn) {
+        return blocked(input, "invalid-v3-task", "requires exactly one scheduling source: akm.schedule or on.");
+    }
+    const hasWith = Object.hasOwn(data, "with");
+    let usesTarget;
+    if (hasUses) {
+        let usesValue;
+        try {
+            usesValue = exactString(data.uses, "uses", true);
+        }
+        catch (cause) {
+            return blocked(input, "invalid-v3-task", causeMessage(cause));
+        }
+        try {
+            usesTarget = classifyTaskV3Uses(usesValue);
+        }
+        catch (cause) {
+            return blocked(input, "invalid-v3-task", causeMessage(cause));
+        }
+        if (usesTarget.kind === "github-action") {
+            return blocked(input, "github-action-target-removed", `"${usesValue}" is a github-action target; the github-action uses: variant was removed in task source v4. Use commands/, scripts/, workflows/, or akm/command instead.`);
+        }
+        if (hasWith && usesTarget.kind !== "builtin-command") {
+            return blocked(input, "with-on-non-command-target", `a with: block on "${usesValue}" (a non-akm/command target) has no task source v4 equivalent; task-call inputs are declared and bound separately.`);
+        }
+    }
+    else if (hasWith) {
+        return blocked(input, "invalid-v3-task", "with is legal only with uses");
+    }
+    if (!input.writable || input.onDiskWritable === false) {
+        return blocked(input, "read-only-source", !input.writable ? "the owning source is not writable" : "the source file or publication directory is read-only");
+    }
+    const enabledFalse = akm !== undefined && akm.enabled === false;
+    let scheduleField;
+    // Several independent translation facts can need reporting on the SAME
+    // file (a manual-only trigger AND a dropped output schema, say), so
+    // notices accumulate and are joined into the single `notice` string the
+    // outcome carries.
+    const notices = [];
+    if (hasAkmSchedule) {
+        const cron = akm.schedule;
+        scheduleField = enabledFalse ? [{ cron, enabled: false }] : cron;
+    }
+    else {
+        const rawSchedule = onRecord !== undefined && Object.hasOwn(onRecord, "schedule") ? onRecord.schedule : undefined;
+        if (rawSchedule !== undefined) {
+            if (!Array.isArray(rawSchedule) || rawSchedule.length === 0) {
+                return blocked(input, "invalid-v3-task", "on.schedule must be a non-empty list of {cron} records");
+            }
+            const crons = [];
+            for (const entry of rawSchedule) {
+                let record;
+                try {
+                    record = plainRecord(entry, "on.schedule[]");
+                }
+                catch (cause) {
+                    return blocked(input, "invalid-v3-task", causeMessage(cause));
+                }
+                const keys = Object.keys(record);
+                if (keys.length !== 1 || keys[0] !== "cron" || typeof record.cron !== "string" || record.cron.length === 0) {
+                    return blocked(input, "invalid-v3-task", "each on.schedule entry must be exactly {cron: <non-empty string>}");
+                }
+                crons.push(record.cron);
+            }
+            scheduleField = crons.map((cron) => (enabledFalse ? { cron, enabled: false } : { cron }));
+        }
+        else if (enabledFalse) {
+            return blocked(input, "enabled-false-has-no-schedule-entry", "akm.enabled: false has no schedule entry to attach to (the only trigger is on.workflow_dispatch); task source v4 has no top-level enabled flag.");
+        }
+        else {
+            notices.push("schedule: is absent from the migrated document — the source's only trigger was on.workflow_dispatch (manual dispatch); task source v4 tasks are always runnable manually via `akm task run`, so no schedule: entry was emitted.");
+        }
+    }
+    const out = { version: 4 };
+    if (Object.hasOwn(data, "name"))
+        out.name = data.name;
+    if (hasUses)
+        out.uses = data.uses;
+    else
+        out.run = data.run;
+    if (Object.hasOwn(data, "shell"))
+        out.shell = data.shell;
+    if (hasWith)
+        out.with = data.with;
+    if (Object.hasOwn(data, "env"))
+        out.env = data.env;
+    if (Object.hasOwn(data, "working-directory"))
+        out["working-directory"] = data["working-directory"];
+    if (scheduleField !== undefined)
+        out.schedule = scheduleField;
+    if (akm) {
+        for (const key of AKM_HOIST_KEYS) {
+            if (Object.hasOwn(akm, key))
+                out[key] = akm[key];
+        }
+        // v3's `akm.outputSchema: null` means "no schema" (accepted verbatim by
+        // the frozen v3 reader, task-source-v3-frozen.ts:256-258); v4's
+        // `output:` has no null form (parseOutputSchema always requires a
+        // mapping). Omitting the key is the faithful v4 equivalent of an
+        // explicit v3 null — emitting `output: null` would fail the real
+        // parseTaskSourceV4 validation below and block the whole file.
+        if (Object.hasOwn(akm, "outputSchema") && akm.outputSchema !== null) {
+            // v4 accepts `output:` ONLY on a command target — `uses: commands/<ref>`
+            // or `uses: akm/command` (src/tasks/source/task-source-v4.ts's
+            // `targetConsumesOutputSchema`). v3 enforced no such rule: the frozen v3
+            // reader accepts `akm.outputSchema` on ANY target kind
+            // (task-source-v3-frozen.ts:256-263), and on `run:`/`uses: scripts/`/
+            // `uses: workflows/` it was equally inert there — nothing ever consumed
+            // it. Hoisting it unconditionally would therefore emit bytes the real
+            // parseTaskSourceV4 below rejects, blocking a valid, previously-runnable
+            // v3 file — and one blocked file aborts the whole plan
+            // (`applyTaskToV4MigrationPlan`, ./task-files-to-v4.ts). Dropping an
+            // already-inert field and SAYING SO is the faithful translation, and
+            // keeps spec row B-66 / §5.3's `changed` guarantee intact.
+            if (usesTarget !== undefined && (usesTarget.kind === "command" || usesTarget.kind === "builtin-command")) {
+                out.output = akm.outputSchema;
+            }
+            else {
+                const targetLabel = usesTarget === undefined ? "a run: target" : `the "${usesTarget.ref}" target`;
+                notices.push(`akm.outputSchema was dropped rather than hoisted to output: — task source v4 accepts output: only with a command target (uses: commands/<ref> or uses: akm/command), and ${targetLabel} never consumed the schema in v3 either, so nothing enforceable was lost.`);
+            }
+        }
+    }
+    const afterYaml = stringifyYaml(out);
+    const after = Buffer.from(afterYaml, "utf8");
+    try {
+        parseTaskSourceV4({
+            yaml: afterYaml,
+            filePath: input.filePath,
+            ...(input.containmentRoot ? { workspaceRoot: input.containmentRoot } : {}),
+        });
+    }
+    catch (cause) {
+        return blocked(input, "generated-v4-validation-failed", causeMessage(cause));
+    }
+    const notice = notices.join(" ");
+    return Object.freeze({
+        status: "changed",
+        ...base(input),
+        reason: "task-converted",
+        after,
+        afterHash: hash(after),
+        ...(notice ? { notice } : {}),
+    });
+}
+/** Plan exactly one source file without touching disk. */
+export function planTaskToV4File(input) {
+    let data;
+    let source;
+    try {
+        ({ data, source } = parseV3RawYaml(input));
+    }
+    catch (cause) {
+        return blocked(input, "invalid-task-yaml", causeMessage(cause));
+    }
+    if (data.version === 4) {
+        try {
+            parseTaskSourceV4({
+                yaml: source,
+                filePath: input.filePath,
+                ...(input.containmentRoot ? { workspaceRoot: input.containmentRoot } : {}),
+            });
+            return Object.freeze({ status: "skipped", ...base(input), reason: "already-v4" });
+        }
+        catch (cause) {
+            return blocked(input, "invalid-v4-task", causeMessage(cause));
+        }
+    }
+    // Not this generation's document to validate — v2 grammar is entirely
+    // generation 1's domain (task-to-v3.ts). Reported skipped, not blocked
+    // (see TaskToV4Skipped's own header).
+    if (data.version === 2) {
+        return Object.freeze({
+            status: "skipped",
+            ...base(input),
+            reason: "pending-v2-to-v3-migration",
+        });
+    }
+    if (data.version !== 3) {
+        return blocked(input, "unsupported-task-version", `expected version 2, 3, or 4, got ${String(data.version)}`);
+    }
+    return planV3DataToV4(input, data);
+}
+function generationFor(files) {
+    const digest = crypto.createHash("sha256");
+    digest.update("akm-task-to-v4-plan-v1\0");
+    for (const file of files) {
+        digest.update(file.filePath);
+        digest.update("\0");
+        digest.update(file.status);
+        digest.update("\0");
+        digest.update(file.reason);
+        digest.update("\0");
+        digest.update(String(file.mode));
+        digest.update("\0");
+        digest.update(file.writable ? "writable" : "read-only");
+        digest.update("\0");
+        digest.update(file.onDiskWritable === false ? "disk-read-only" : "disk-writable-or-unspecified");
+        digest.update("\0");
+        if (file.containmentRoot)
+            digest.update(file.containmentRoot);
+        digest.update("\0");
+        digest.update(file.beforeHash);
+        digest.update("\0");
+        if (file.status === "changed")
+            digest.update(file.afterHash);
+        digest.update("\0");
+        if (file.detail)
+            digest.update(file.detail);
+        digest.update("\0");
+        if (file.status === "changed" && file.notice)
+            digest.update(file.notice);
+        digest.update("\0");
+    }
+    return digest.digest("hex");
+}
+/** Build/fingerprint a plan from already-derived immutable outcomes. */
+export function taskToV4PlanFromOutcomes(outcomes) {
+    const files = [...outcomes].sort((left, right) => left.filePath < right.filePath ? -1 : left.filePath > right.filePath ? 1 : 0);
+    for (let index = 1; index < files.length; index += 1) {
+        const previous = files[index - 1];
+        const current = files[index];
+        if (previous && current && path.resolve(previous.filePath) === path.resolve(current.filePath)) {
+            throw new Error(`duplicate task migration file path: ${current.filePath}`);
+        }
+    }
+    return Object.freeze({ schemaVersion: 1, generation: generationFor(files), files: Object.freeze(files) });
+}
+/** Plan a complete, stable file set. Input order cannot change the result. */
+export function planTaskToV4Migration(inputs) {
+    const sorted = [...inputs].sort((left, right) => left.filePath < right.filePath ? -1 : left.filePath > right.filePath ? 1 : 0);
+    let previous;
+    for (const current of sorted) {
+        if (previous && path.resolve(previous.filePath) === path.resolve(current.filePath)) {
+            throw new Error(`duplicate task migration file path: ${current.filePath}`);
+        }
+        previous = current;
+    }
+    return taskToV4PlanFromOutcomes(sorted.map(planTaskToV4File));
+}

package/docs/reference/cli.md

@@ -393,6 +393,11 @@ availability:
 - **`origin`** -- The source bundle (e.g. `npm:@scope/pkg`), present only for
   managed source assets; surfaced at `full` only
 - **`id`** -- Registry-level identifier (registry hits only)
+- **`matchStage`** -- Which stage of the progressive AND->OR lexical search
+  ladder produced the hit: `exact` (strict AND), `prefix` (prefix AND), or
+  `relaxed` (OR/prefix-OR recovery). Omitted for hits with no FTS component
+  (e.g. a pure-semantic hybrid match) and for registry hits; surfaced at
+  `normal`, `full`, and `--shape agent`
 
 The default brief shape is intentionally small. The exact field set per
 detail level (and per `--shape`) is authoritative in
@@ -402,9 +407,9 @@ assembled into the shape registry by the `src/output/shapes.ts` barrel:
 | Level | Local bundle hits | Registry hits |
 | --- | --- | --- |
 | `brief` (default) | `type`, `name`, `ref`, `action`, `estimatedTokens` | `name`, `installRef`, `score` |
-| `normal` | `type`, `name`, `description`, `action`, `score`, `estimatedTokens`, optional `warnings`/`quality`/`keys` | `name`, `description`, `action`, `installRef`, `score`, optional `warnings` |
-| `full` | full hit object (includes `ref`, `origin`, `tags`, `whyMatched`, optional `warnings`, optional `quality`, timings, bundle metadata) | full hit object |
-| `--shape agent` | `name`, `ref`, `type`, `path`, `editable`, conditional `editHint`, `description`, `action`, `score`, optional `estimatedTokens`/`keys` | no local access fields |
+| `normal` | `type`, `name`, `description`, `action`, `score`, `estimatedTokens`, optional `warnings`/`quality`/`keys`/`matchStage` | `name`, `description`, `action`, `installRef`, `score`, optional `warnings` |
+| `full` | full hit object (includes `ref`, `origin`, `tags`, `whyMatched`, optional `warnings`, optional `quality`, optional `matchStage`, timings, bundle metadata) | full hit object |
+| `--shape agent` | `name`, `ref`, `type`, `path`, `editable`, conditional `editHint`, `description`, `action`, `score`, optional `estimatedTokens`/`keys`/`matchStage` | no local access fields |
 
 `--shape summary` is **not valid on `search`** — see
 [`--shape summary`](#--shape-summary) above; it is a usage error (exit 2)
@@ -2418,9 +2423,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` — 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 | 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)
@@ -2434,8 +2440,12 @@ akm task run <id>                           # Execute now (what the scheduler ca
 akm task explain <ref>                      # Read-only: declared inputs, target, schedule — spawns nothing
 akm task history [--id <id>] [--limit <n>]  # Recent runs from state.db
 akm task sync                               # Reconcile on-disk YAML with scheduler
+akm task sync --dry-run                     # Preview the reconcile — zero scheduler writes
 akm task sync --rebind                      # Also capture the current installed runtime
 akm task doctor                             # Report scheduler backend + paths
+akm task prune                              # Preview orphaned scheduler entries — zero writes
+akm task prune --yes                        # Remove every currently-computed orphan
+akm task prune --id ghost,stale --yes       # Remove only the named orphan ids
 ```
 
 `task add` also accepts `--disabled` (register but leave off in the OS
@@ -2461,6 +2471,23 @@ schedule-binding) and run `akm task sync`. To remove one, delete its file
 (`<bundle>/tasks/<id>.yml`) and run `akm task sync` — sync uninstalls the
 orphaned scheduler entry.
 
+`akm task sync --dry-run` prints the planned adds/updates/removes (removals
+carry their owning bundle) without touching the scheduler — zero writes.
+Exits non-zero when removals are pending, so it can gate a CI/health check
+on "sync would change something."
+
+`akm task prune` reclaims installed scheduler entries that `sync` can never
+clean up on its own: entries whose own `--scheduler-context` descriptor no
+longer resolves to a live bundle (a corrupt/missing descriptor, or the
+bundle directory it pointed at is gone). It never touches an entry that
+still resolves to a live bundle — that's `sync`'s job. Like `sync
+--dry-run`, the default is a dry-run preview (zero scheduler writes) that
+exits non-zero when there are candidates to remove; `--yes` executes the
+printed plan, and `--id <id1,id2,...>` narrows a `--yes` run (or a preview)
+to specific binding ids — naming an id that isn't a current orphan
+candidate (not installed, or it still resolves to a live bundle) is
+refused with a usage error and removes nothing.
+
 Scheduler activation captures the installed akm runtime. Ordinary `task sync`
 reconciles definitions, schedules, and enabled state while preserving that
 runtime binding. Use `task sync --rebind` only after intentionally moving or

package/docs/reference/configuration.md

@@ -7,12 +7,33 @@ directory. Project `.akm/config.json` files are not merged.
 
 ## Version 0.9
 
-A present configuration file must set `configVersion` to exactly `"0.9.0"`.
-Missing, older, newer, numeric, and malformed versions are rejected by ordinary
-commands without rewriting the file. Pre-0.9 config and database layouts are
-not runtime inputs and are not migrated by `akm upgrade`. Configure the current
-schema directly. The standalone migrator exists only for explicit task
-migration: task v2 to task v3, then task v3 to task source v4, in one pass.
+A present configuration file must set `configVersion` to a version this
+binary knows: the current `"0.9.0"`, or a known older version it can
+auto-upgrade in memory (see "Version read shim" below). Missing, newer,
+numeric, and any other unrecognized version are rejected by ordinary
+commands without rewriting the file — an older binary never guesses at a
+newer, unknown shape. Pre-0.9 config and database layouts are not runtime
+inputs and are not migrated by `akm upgrade`. Configure the current schema
+directly. The standalone migrator exists only for explicit task migration:
+task v2 to task v3, then task v3 to task source v4, in one pass.
+
+### Version read shim
+
+Like the task-source v2/v3 auto-shim (`akm migrate apply`'s in-memory
+counterpart, documented under Migration below), a known older `configVersion`
+is converted to the current shape in memory on load — with a one-line stderr
+deprecation warning — rather than hard-failing every command. Nothing is
+written back to disk by the shim itself; the very next config-mutating
+command (`akm config set`, etc.) persists the upgrade for free, since every
+config write already forces `configVersion` to the current value, which
+silences the warning. A `configVersion` this binary does not recognize at
+all — including anything newer than current — still fails closed with
+`UNSUPPORTED_CONFIG_VERSION`.
+
+As of this writing `"0.9.0"` is the only `configVersion` akm has ever
+shipped, so there is no real older shape for the shim to convert yet; the
+mechanism (`src/core/config/config-version-shim.ts`) is established ahead of
+the first bump that will need it, per #863.
 
 ```jsonc
 {

package/docs/reference/tasks.md

@@ -389,6 +389,16 @@ for full before/after examples and recovery guidance.
 - Disable a binding by editing the source and syncing: set that schedule
   entry's own `enabled: false`.
 - Delete the `.yml` source and sync to remove its derived binding(s).
+- `akm task sync --dry-run` previews the reconcile (adds/updates/removes,
+  removals annotated with their owning bundle) without writing to the
+  scheduler; exits non-zero when removals are pending.
+- `akm task prune` removes installed scheduler entries `sync` cannot reach
+  because their own descriptor no longer resolves to a live bundle
+  (corrupt/missing `--scheduler-context`, or the owning bundle directory is
+  gone). It never touches an entry that still resolves to a live bundle.
+  Defaults to a dry-run preview (zero writes); `--yes` executes it; `--id
+  <id1,id2,...>` scopes to specific ids and refuses any id that isn't a
+  current orphan candidate.
 - Use `akm task sync --rebind` only when deliberately changing the captured
   AKM runtime, then verify with `akm task doctor`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "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": [
@@ -36,7 +36,7 @@
   "license": "MPL-2.0",
   "pinNotes": {
     "@opencode-ai/sdk@1.2.20": "Exact pin. The SDK surface we use (createOpencodeClient + session.create/prompt/delete in src/integrations/harnesses/opencode-sdk/sdk-runner.ts) is stable across 1.x, but the SDK has shipped 5+ minor versions of unrelated provider/registry churn. akm-cli is a global CLI install so the pin is isolated from user-project deps. Re-test sdk-runner before bumping. Note this package is an HTTP client only — it declares no dependencies and its own createOpencodeServer spawns `opencode serve` — so it does NOT make the opencode binary available; that install is separate and is what every SDK-path probe checks for.",
-    "better-sqlite3@12.11.1": "Exact pin (#790). This is the SQLite driver akm loads on Node (src/storage/database.ts); Bun never touches it. The pin is about PREBUILT BINARIES, not API surface. better-sqlite3 ships one prebuild per Node ABI as a GitHub release asset and its install script is `prebuild-install || node-gyp rebuild` — so any (version, Node ABI) pair with no prebuild silently COMPILES FROM SOURCE against the headers of whatever Node is on the machine that day. The 11.x line predates Node 24 and declares no `engines` at all: its newest release (11.10.0, 2025-05-08) publishes ABI 108/115/127/131 (Node 18/20/22/23) and nothing for ABI 137 (Node 24). Node 24.19.0 then changed the public `node_object_wrap.h` so `node::ObjectWrap`'s ctor/dtor register and unregister an environment cleanup hook; a from-source 11.x build against those headers aborts at teardown in `Statement::~Statement()` with `RemoveEnvironmentCleanupHook ... Assertion (env) != nullptr`, intermittently, depending on GC timing. 12.11.1 publishes ABI 127/137/141/147 (Node 22/24/25/26) and declares `engines: 20.x || 22.x || 23.x || 24.x || 25.x || 26.x`, so akm's supported Node 24 line installs a prebuilt binary and never compiles. Before bumping: confirm the target version publishes a prebuild for EVERY Node major in `engines` (probe https://github.com/WiseLibs/better-sqlite3/releases/download/vX.Y.Z/better-sqlite3-vX.Y.Z-node-vABI-linux-x64.tar.gz), not just that the version is newer. 13.x is the eventual destination — it moved to node-addon-api/N-API with prebuilds bundled in the npm tarball and no install script, which retires this failure mode entirely — but it is a fresh major rewrite of the binding, so it wants its own soak, not a patch release. The CI node-smoke job installs this exact string by reading it back out of this file (.github/workflows/ci.yml), so the two cannot drift.",
+    "better-sqlite3@12.11.1": "Exact pin (#790). This is the SQLite driver akm loads on Node (src/storage/database.ts); Bun never touches it. The pin is about PREBUILT BINARIES, not API surface. better-sqlite3 ships one prebuild per Node ABI as a GitHub release asset and its install script is `prebuild-install || node-gyp rebuild` — so any (version, Node ABI) pair with no prebuild silently COMPILES FROM SOURCE against the headers of whatever Node is on the machine that day. The 11.x line predates Node 24 and declares no `engines` at all: its newest release (11.10.0, 2025-05-08) publishes ABI 108/115/127/131 (Node 18/20/22/23) and nothing for ABI 137 (Node 24). Node 24.19.0 then changed the public `node_object_wrap.h` so `node::ObjectWrap`'s ctor/dtor register and unregister an environment cleanup hook; a from-source 11.x build against those headers aborts at teardown in `Statement::~Statement()` with `RemoveEnvironmentCleanupHook ... Assertion (env) != nullptr`, intermittently, depending on GC timing. 12.11.1 publishes ABI 127/137/141/147 (Node 22/24/25/26) and declares `engines: 20.x || 22.x || 23.x || 24.x || 25.x || 26.x`, so every Node akm supports installs a prebuilt binary and never compiles. Before bumping: confirm the target version publishes a prebuild for EVERY Node major in `engines` (probe https://github.com/WiseLibs/better-sqlite3/releases/download/vX.Y.Z/better-sqlite3-vX.Y.Z-node-vABI-linux-x64.tar.gz), not just that the version is newer. 13.x is the eventual destination — it moved to node-addon-api/N-API with prebuilds bundled in the npm tarball and no install script, which retires this failure mode entirely — but it is a fresh major rewrite of the binding, so it wants its own soak, not a patch release. The CI node-smoke job installs this exact string by reading it back out of this file (.github/workflows/ci.yml), so the two cannot drift.",
     "@huggingface/transformers@4.2.0": "Exact semantic-search dependency pin. Re-run the real-model semantic gate before changing it."
   },
   "files": [
@@ -66,7 +66,7 @@
     "akm-migrate": "dist/akm-migrate"
   },
   "scripts": {
-    "preinstall": "node -e \"var v=(process.versions.node||'0').split('.').map(function(n){return parseInt(n,10)||0});var ok=v[0]>=24;if(ok){process.exit(0)}console.error('\\n  ERROR: the akm-cli npm package requires Node.js >= 24.\\n  A working Bun >= 1.0 on PATH is optional and preferred for akm and akm-migrate.\\n  Upgrade Node.js (https://nodejs.org), or install the runtime-free standalone binary:\\n    curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\\n');process.exit(1)\"",
+    "preinstall": "node -e \"var v=(process.versions.node||'0').split('.').map(function(n){return parseInt(n,10)||0});var ok=v[0]>=22;if(ok){process.exit(0)}console.error('\\n  ERROR: the akm-cli npm package requires Node.js >= 22.\\n  A working Bun >= 1.0 on PATH is optional and preferred for akm and akm-migrate.\\n  Upgrade Node.js (https://nodejs.org), or install the runtime-free standalone binary:\\n    curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\\n');process.exit(1)\"",
     "build": "rm -rf dist && bun scripts/gen-config-schema.ts &&bun run tsc --project ./tsconfig.build.json && bun scripts/copy-assets.ts && bun scripts/fix-esm-extensions.ts",
     "check": "bun run lint && bunx tsc --noEmit && bun run test:unit && bun run test:integration",
     "check:fast": "bun run lint && bunx tsc --noEmit && bun run test:unit",
@@ -114,7 +114,7 @@
     "sqlite-vec": "^0.1.9"
   },
   "engines": {
-    "node": ">=24"
+    "node": ">=22"
   },
   "dependencies": {
     "@clack/prompts": "^1.3.0",