akm-cli 0.9.4 → 0.9.5

package/dist/tasks/scheduler-sync.js

@@ -17,7 +17,7 @@ import { WorkflowSourceCollisionError, WorkflowSourceNameError, WorkflowSourceRe
 import { compileWorkflowSource } from "../workflows/source-ir/compile.js";
 import { prepareTaskV3Execution } from "./prepare/prepare.js";
 import { parseSchedule } from "./schedule.js";
-import { assertSchedulerNativeArtifactCardinality, compileTaskSchedulerBindings, compileWorkflowSchedulerBindings, schedulerBindingNativeId, schedulerBindingOrdinal, schedulerNativeArtifactKey, schedulerNativeBindingId, } from "./scheduler-binding.js";
+import { assertSchedulerNativeArtifactCardinality, compileTaskSchedulerBindings, compileWorkflowSchedulerBindings, schedulerBindingNativeId, schedulerBindingOrdinal, schedulerNativeArtifactKey, schedulerNativeArtifactOwner, schedulerNativeBindingId, } from "./scheduler-binding.js";
 import { parseTaskSource } from "./source/parse-task-source.js";
 import { projectTaskSourceV4 } from "./source/project-v4.js";
 import { taskSourceErrorDetail } from "./source-v3.js";
@@ -47,6 +47,7 @@ export async function prepareSchedulerSyncSourceSet(input) {
         desired: compiled.desired,
         sourceSnapshot,
         executableWorkflows: compiled.executableWorkflows,
+        failures: compiled.failures,
     });
 }
 export function finalizeSchedulerSyncPlan(input, prepared) {
@@ -108,35 +109,7 @@ export function finalizeSchedulerSyncPlan(input, prepared) {
         .sort(compareCodePoints);
     for (const id of removed) {
         const current = present.get(id);
-        if (!current?.invocation) {
-            throw nativeArtifactCollision({ nativeId: current?.nativeId ?? schedulerNativeBindingId(id), bindingId: id }, { nativeId: current?.nativeId ?? schedulerNativeBindingId(id) });
-        }
-        const nativeId = exactInstalledNativeId(id, current, inspection.artifacts);
-        const artifact = inspection.artifacts.find((candidate) => candidate.nativeId === nativeId && candidate.bindingId === id);
-        const priorFingerprint = current.signature ?? artifact?.fingerprint;
-        if (!artifact || priorFingerprint === undefined) {
-            throw new UsageError(`Installed scheduler binding ${JSON.stringify(id)} has no exact native fingerprint; refusing removal.`, "RESOURCE_ALREADY_EXISTS");
-        }
-        const logicalSource = installedLogicalSource(current.invocation, coherentInput);
-        const ordinal = schedulerBindingOrdinal(id, logicalSource, current.invocation);
-        if (ordinal === undefined) {
-            throw new UsageError(`Installed scheduler binding ${JSON.stringify(id)} cannot be attributed to an exact schedule ordinal; refusing removal.`, "RESOURCE_ALREADY_EXISTS");
-        }
-        operations.push(Object.freeze({
-            kind: "remove",
-            id,
-            nativeId,
-            expected: freezeRemovalExpectation({
-                state: "present",
-                bindingId: id,
-                nativeId,
-                logicalSource,
-                ordinal,
-                invocation: current.invocation,
-                fingerprint: priorFingerprint,
-            }),
-            ...(current.ownerBundlePath !== undefined ? { ownerBundlePath: current.ownerBundlePath } : {}),
-        }));
+        operations.push(buildSchedulerRemoveOperation(id, current, inspection.artifacts, coherentInput));
     }
     return Object.freeze({
         desired,
@@ -146,6 +119,49 @@ export function finalizeSchedulerSyncPlan(input, prepared) {
         unchanged: Object.freeze(unchanged),
         operations: Object.freeze(operations),
         sourceSnapshot: prepared.sourceSnapshot,
+        failures: prepared.failures,
+    });
+}
+/**
+ * Build the exact removal operation for one installed binding: same
+ * exact-native-fingerprint / ordinal-attribution safety checks
+ * `finalizeSchedulerSyncPlan`'s remove loop always applied, factored out so
+ * `akm task prune` (#851) can build removal operations for entries
+ * `belongsToBundle` structurally can't see (unresolvable ownership) without
+ * re-deriving — or weakening — this logic. Throws the same `UsageError`s a
+ * sync removal would on an inexact match; callers computing prune candidates
+ * should only pass entries they've already independently confirmed are safe
+ * to remove.
+ */
+export function buildSchedulerRemoveOperation(id, current, artifacts, input) {
+    if (!current?.invocation) {
+        throw nativeArtifactCollision({ nativeId: current?.nativeId ?? schedulerNativeBindingId(id), bindingId: id }, { nativeId: current?.nativeId ?? schedulerNativeBindingId(id) });
+    }
+    const nativeId = exactInstalledNativeId(id, current, artifacts);
+    const artifact = artifacts.find((candidate) => candidate.nativeId === nativeId && candidate.bindingId === id);
+    const priorFingerprint = current.signature ?? artifact?.fingerprint;
+    if (!artifact || priorFingerprint === undefined) {
+        throw new UsageError(`Installed scheduler binding ${JSON.stringify(id)} has no exact native fingerprint; refusing removal.`, "RESOURCE_ALREADY_EXISTS");
+    }
+    const logicalSource = installedLogicalSource(current.invocation, input);
+    const ordinal = schedulerBindingOrdinal(id, logicalSource, current.invocation);
+    if (ordinal === undefined) {
+        throw new UsageError(`Installed scheduler binding ${JSON.stringify(id)} cannot be attributed to an exact schedule ordinal; refusing removal.`, "RESOURCE_ALREADY_EXISTS");
+    }
+    return Object.freeze({
+        kind: "remove",
+        id,
+        nativeId,
+        expected: freezeRemovalExpectation({
+            state: "present",
+            bindingId: id,
+            nativeId,
+            logicalSource,
+            ordinal,
+            invocation: current.invocation,
+            fingerprint: priorFingerprint,
+        }),
+        ...(current.ownerBundlePath !== undefined ? { ownerBundlePath: current.ownerBundlePath } : {}),
     });
 }
 function exactInstalledNativeId(logicalId, current, artifacts) {
@@ -190,10 +206,17 @@ export function assertSchedulerNativeArtifactOwnership(desired, installed) {
         const wanted = desiredByKey.get(key);
         if (!wanted)
             continue;
-        if (artifact.nativeId !== schedulerBindingNativeId(wanted) ||
-            artifact.bindingId !== wanted.id ||
-            artifact.invocation === undefined ||
-            !sameInvocation(artifact.invocation, wanted.invocation)) {
+        // Re-derive ownership from the artifact's own invocation content (not the
+        // caller-supplied `bindingId` label) so a proven owner whose invocation
+        // no longer matches the desired shape is an UPDATE, not a refusal — that
+        // reconciliation happens below in finalizeSchedulerSyncPlan. An artifact
+        // whose invocation content does not actually prove it belongs to
+        // `wanted` (unproven, malformed, or a different logical owner) is still
+        // a genuine collision.
+        const provenBindingId = artifact.invocation !== undefined
+            ? schedulerNativeArtifactOwner(artifact.nativeId, artifact.invocation)?.logicalId
+            : undefined;
+        if (artifact.nativeId !== schedulerBindingNativeId(wanted) || provenBindingId !== wanted.id) {
             throw nativeArtifactCollision(desiredArtifact(wanted), artifact);
         }
     }
@@ -252,12 +275,17 @@ async function compileDesiredSourceSet(input, collector) {
     const failures = [];
     await compileTaskSources(input, collector, bindings, failures);
     await compileWorkflowSources(input, collector, bindings, executableWorkflows, failures);
-    if (failures.length > 0) {
-        throw new UsageError(`Scheduler sync rejected the desired source set before mutation:\n${failures.map((failure) => `- ${failure}`).join("\n")}`, "TASK_SOURCE_INVALID");
-    }
+    // Degrade, don't reject (#867): one source that fails to parse/prepare no
+    // longer poisons the whole desired set — it is dropped from `desired` and
+    // reported here instead, so every OTHER task/workflow still reconciles.
+    // Genuinely cross-cutting integrity violations (duplicate ids, native
+    // artifact ownership conflicts, an incoherent backend inspection) are
+    // asserted separately in `finalizeSchedulerSyncPlan` and still hard-fail
+    // the whole sync — this only relaxes the per-source parse/prepare gate.
     return Object.freeze({
         desired: Object.freeze(bindings),
         executableWorkflows: Object.freeze(executableWorkflows.sort((left, right) => compareCodePoints(left.ref, right.ref))),
+        failures: Object.freeze(failures.sort((left, right) => compareCodePoints(left.path, right.path))),
     });
 }
 async function compileTaskSources(input, collector, out, failures) {
@@ -269,6 +297,7 @@ async function compileTaskSources(input, collector, out, failures) {
         const relative = guarded.relativePath;
         const conceptId = relative.slice(0, -4);
         const id = input.adapterId === "akm-task" ? conceptId : path.basename(sourcePath, ".yml");
+        const qualifiedRefForFailure = makeBundleRef(input.bundleName, conceptId);
         try {
             const physicalIdentity = guarded.physicalIdentity;
             const priorOwner = physicalOwners.get(physicalIdentity);
@@ -356,7 +385,7 @@ async function compileTaskSources(input, collector, out, failures) {
             }
         }
         catch (cause) {
-            failures.push(taskFailure(sourcePath, cause));
+            failures.push(taskFailure(sourcePath, qualifiedRefForFailure, cause));
         }
     }
 }
@@ -365,6 +394,8 @@ async function compileWorkflowSources(input, collector, out, evidence, failures)
         return;
     const lookups = enumerateWorkflowLookups(input, collector, failures);
     for (const [canonicalName, sources] of lookups) {
+        const failurePath = sources[0]?.sourcePath ?? canonicalName;
+        const failureRef = makeBundleRef(input.bundleName, input.adapterId === "akm" ? `workflows/${canonicalName}` : canonicalName);
         try {
             if (sources.length > 1) {
                 throw new WorkflowSourceCollisionError(input.adapterId === "akm" ? `workflows/${canonicalName}` : canonicalName, sources.map((source) => source.relativePath));
@@ -427,7 +458,7 @@ async function compileWorkflowSources(input, collector, out, evidence, failures)
             }
         }
         catch (cause) {
-            failures.push(errorMessage(cause));
+            failures.push(workflowFailure(failurePath, failureRef, cause));
         }
     }
 }
@@ -456,7 +487,7 @@ function enumerateWorkflowLookups(input, collector, failures) {
         const stem = authoredName.slice(0, -extension.length).toLowerCase();
         const nestedSuffix = WORKFLOW_EXTENSIONS.find((suffix) => stem.endsWith(suffix));
         if (nestedSuffix) {
-            failures.push(errorMessage(new WorkflowSourceNameError(guarded.relativePath, nestedSuffix)));
+            failures.push(workflowFailure(sourcePath, undefined, new WorkflowSourceNameError(guarded.relativePath, nestedSuffix)));
             continue;
         }
         const canonicalName = canonicalizeWorkflowName(authoredName);
@@ -529,9 +560,13 @@ function assertUniqueInstalledIds(installed) {
         seen.add(binding.id);
     }
 }
-function taskFailure(file, cause) {
+function taskFailure(file, ref, cause) {
     const detail = taskSourceErrorDetail(cause);
-    return detail === errorMessage(cause) ? `${file}: ${detail}` : detail;
+    const reason = detail === errorMessage(cause) ? `${file}: ${detail}` : detail;
+    return Object.freeze({ path: file, ref, reason });
+}
+function workflowFailure(file, ref, cause) {
+    return Object.freeze({ path: file, ...(ref ? { ref } : {}), reason: errorMessage(cause) });
 }
 function errorMessage(cause) {
     return cause instanceof Error ? cause.message : String(cause);

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

@@ -61,6 +61,27 @@ const SHELL_ASSIGNMENT_WORD = /^[A-Za-z_][A-Za-z0-9_]*=/;
 function shellStableV2Executable(executable) {
     return executable === "akm" || executable.includes("/");
 }
+/**
+ * `env NAME=value... cmd args...` is env(1) itself resolving and exec'ing
+ * `cmd` via its own PATH search — that lookup happens inside env's execvp()
+ * regardless of whether env was launched by direct execve (v2) or by a host
+ * shell (v3 `run:`). The shell-vs-argv divergence `shellStableV2Executable`
+ * guards against (bare names shadowed by shell aliases/builtins/functions)
+ * therefore does not apply to whatever env ultimately invokes, so skip past
+ * a leading `env` and its `NAME=value` assignments to find the real target.
+ * Returns the original tokens, unchanged, when there is no such target
+ * (e.g. `env` with nothing after its assignments).
+ */
+function skipEnvAssignmentPrefix(tokens) {
+    if (tokens[0] !== "env")
+        return { tokens, envWrapped: false };
+    let index = 1;
+    while (index < tokens.length && SHELL_ASSIGNMENT_WORD.test(tokens[index]))
+        index += 1;
+    if (index >= tokens.length)
+        return { tokens, envWrapped: false };
+    return { tokens: tokens.slice(index), envWrapped: true };
+}
 const KNOWN_PROMPT_REF_FAMILIES = new Set([
     "agents",
     "commands",
@@ -81,15 +102,6 @@ function hash(bytes) {
     return crypto.createHash("sha256").update(bytes).digest("hex");
 }
 function base(input) {
-    const inspectionIdentity = input.inspectionIdentity
-        ? Object.freeze({
-            file: Object.freeze({ ...input.inspectionIdentity.file }),
-            root: Object.freeze({ ...input.inspectionIdentity.root }),
-            ...(input.inspectionIdentity.bundleRoot
-                ? { bundleRoot: Object.freeze({ ...input.inspectionIdentity.bundleRoot }) }
-                : {}),
-        })
-        : undefined;
     return {
         filePath: input.filePath,
         before: Buffer.from(input.bytes),
@@ -98,7 +110,6 @@ function base(input) {
         writable: input.writable,
         ...(input.onDiskWritable !== undefined ? { onDiskWritable: input.onDiskWritable } : {}),
         ...(input.containmentRoot ? { containmentRoot: input.containmentRoot } : {}),
-        ...(inspectionIdentity ? { inspectionIdentity } : {}),
     };
 }
 function blocked(input, reason, detail) {
@@ -348,8 +359,9 @@ function migratedObject(data) {
         if (tokens.length === 0 || tokens.some((token) => !SAFE_V2_COMMAND_TOKEN.test(token))) {
             return "shell-operators-change-v2-literal-argv-semantics";
         }
-        const executable = tokens[0];
-        if (SHELL_ASSIGNMENT_WORD.test(executable) || !shellStableV2Executable(executable)) {
+        const { tokens: targetTokens, envWrapped } = skipEnvAssignmentPrefix(tokens);
+        const executable = targetTokens[0];
+        if (SHELL_ASSIGNMENT_WORD.test(executable) || (!envWrapped && !shellStableV2Executable(executable))) {
             return "shell-command-resolution-changes-v2-literal-argv-semantics";
         }
         output.run = tokens.join(" ");

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

@@ -76,15 +76,6 @@ function causeMessage(cause) {
     return cause instanceof Error ? cause.message : String(cause);
 }
 function base(input) {
-    const inspectionIdentity = input.inspectionIdentity
-        ? Object.freeze({
-            file: Object.freeze({ ...input.inspectionIdentity.file }),
-            root: Object.freeze({ ...input.inspectionIdentity.root }),
-            ...(input.inspectionIdentity.bundleRoot
-                ? { bundleRoot: Object.freeze({ ...input.inspectionIdentity.bundleRoot }) }
-                : {}),
-        })
-        : undefined;
     return {
         filePath: input.filePath,
         before: Buffer.from(input.bytes),
@@ -93,7 +84,6 @@ function base(input) {
         writable: input.writable,
         ...(input.onDiskWritable !== undefined ? { onDiskWritable: input.onDiskWritable } : {}),
         ...(input.containmentRoot ? { containmentRoot: input.containmentRoot } : {}),
-        ...(inspectionIdentity ? { inspectionIdentity } : {}),
     };
 }
 function blocked(input, reason, detail) {

package/docs/reference/cli.md

@@ -2423,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)
@@ -2439,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
@@ -2466,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.4",
+  "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": [