akm-cli 0.9.17-alpha.6 → 0.9.17-alpha.7

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

@@ -5,59 +5,32 @@
  * The task source version router.
  *
  * Runs the bounded YAML front end ONCE (`readBoundedTaskSourceYaml`), reads
- * `root.version`, and either dispatches into `parseTaskSourceV4Document` or
- * routes through the in-memory read shim below — no second parse of the v4
- * grammar itself, no re-serialization back to disk, no synthetic document
- * (the shim adds a pure bytes-in/bytes-out detour, never a disk write).
- *
- * The terminal routing table:
+ * `root.version`, and dispatches into `parseTaskSourceV4Document`. The
+ * runtime reads only task source v4 (#987):
  *
  *   | root `version`        | outcome                                                        |
  *   |------------------------|-----------------------------------------------------------------|
- *   | `4`, no retired `schedule[].enabled` | `parseTaskSourceV4Document` — the current grammar |
- *   | `4`, some `schedule[]` entry carries `enabled` | in-memory read shim (below): the SAME `planTaskToV4File` call `akm migrate apply` uses for this exact case (`./task-to-v4.ts`'s `version === 4` branch, which strips every `schedule[].enabled` and reports `source-enablement-removed`) runs on the bytes already in hand; the result is parsed and returned with a one-line stderr deprecation warning (once per file per process). The value is never read either way — `enabled: false` cannot suppress a granted task and `enabled: true` cannot schedule an ungranted one, since activation is host-local `scheduler.enabled`. Version 4 is supported, so if the planner cannot produce a valid document it is an ordinary grammar defect: falls back to `TASK_SOURCE_INVALID` with the v4 parser's own error, not the unmigratable-version decision |
- *   | `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 (once per file per process). 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 — the shim removes friction for the deterministic case, it never hides a real problem |
+ *   | `4`                    | `parseTaskSourceV4Document` — the current grammar               |
+ *   | `4`, some `schedule[]` entry carries `enabled` (0.9.15's grammar) | `TASK_SOURCE_INVALID` naming `akm migrate apply`, which removes the key |
+ *   | `2` or `3`             | `TASK_SCHEMA_VERSION_UNSUPPORTED` naming `akm migrate apply`, which converts the file |
  *   | any other number       | `TASK_SCHEMA_VERSION_UNSUPPORTED`, naming the migrator          |
  *   | absent / not a number  | `parseTaskSourceV4Document` — its own `TASK_SOURCE_INVALID` "version is required and must be 4" / "must be exactly 4" wording |
  *
+ * `akm migrate apply` (`scripts/akm-migrate/`) is the one place a v2/v3
+ * document, or a v4 document carrying the retired `schedule[].enabled`, is
+ * converted: it rewrites the file once, under a backup. Nothing here converts
+ * in memory. Every caller reports the refusal for that one file — `akm task
+ * sync` keeps reconciling every other task (#867).
+ *
  * A missing or non-numeric `version:` is a MALFORMED v4 document, not a
  * legacy one — it routes into the v4 parser so the field error names the
- * one grammar `src` still accepts, rather than a generic "unsupported"
- * message that would send the user to the migrator for a document that was
- * never task v2 or v3 in the first place.
- *
- * task v2 and task v3 sources are no longer read as their own standing
- * grammar anywhere else in `src` — the only readers of that grammar are the
- * pure, byte-producing planners (`./task-to-v3.ts`, `./task-to-v4.ts`, and
- * the frozen v3 reader `./task-source-v3-frozen.ts`), reached either through
- * this shim (bytes in, bytes out, never touches disk) or through
- * `akm migrate apply` / `akm-migrate` (`scripts/akm-migrate`, which
- * additionally rewrites the file on disk once the user asks for that).
- * Policy: a deterministic byte transform is the tool's job, not the user's —
- * upgrading past a schema bump must not silently break a scheduled task, so
- * v2/v3 files keep reading successfully at the cost of a one-line
- * deprecation warning, and `akm migrate apply` remains available to rewrite
- * the file and silence it. Activation itself is host-local (scheduler
- * config, `src/core/activation-policy.ts`) and this shim never touches it:
- * the v3->v4 planner never hoists the retired `akm.enabled` field to v4's
- * top level and never carries a schedule entry's `enabled` key, so the
- * document this shim hands back carries no enablement at all — the same
- * shape a native v4 document has. A declared `version: 4` document that
- * still carries a `schedule[].enabled` key (0.9.15's v4 grammar accepted
- * it; this release's does not) gets the identical treatment: routed
- * through `planTaskToV4File`'s own `version === 4` branch, which strips
- * every `schedule[].enabled` key without reading its value and reports
- * `source-enablement-removed`, then re-parsed and returned with the same
- * one-line deprecation warning. The front end's own pre-version failures
+ * one grammar `src` accepts. The front end's own pre-version failures
  * (source not a string, source too large, YAML parse/warning/expansion)
  * render with the label `task source`.
  */
 import { UsageError } from "../../core/errors.js";
-import { warnOnce } from "../../core/warn.js";
 import { readBoundedTaskSourceYaml } from "./bounded-document.js";
-import { parseTaskSourceV4, parseTaskSourceV4Document, TASK_SOURCE_V4_VERSION, } from "./task-source-v4.js";
-import { planTaskToV3File } from "./task-to-v3.js";
-import { planTaskToV4File } from "./task-to-v4.js";
+import { parseTaskSourceV4Document, TASK_SOURCE_V4_VERSION } from "./task-source-v4.js";
 /** Read the root `version` field without over-accepting non-number values (e.g. the string `"4"`). */
 export function peekTaskSourceVersion(root) {
     if (root === null || typeof root !== "object" || Array.isArray(root))
@@ -66,71 +39,19 @@ 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.");
+/** A v2/v3 document: `akm migrate apply` converts it; this release reads only v4. */
+function legacyVersionError(filePath, version) {
+    return new UsageError(`TASK_SCHEMA_VERSION_UNSUPPORTED: Task at ${filePath} uses task schema version ${version}; this release reads only version 4. Run \`akm migrate apply\` to convert it.`, "TASK_SCHEMA_VERSION_UNSUPPORTED", TASK_MIGRATE_HINT);
 }
 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);
 }
-/**
- * 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. `version === 4` runs the
- * identical bytes straight through `planTaskToV4File`'s own `version === 4`
- * branch instead (the retired `schedule[].enabled` case, `./task-to-v4.ts`),
- * so there is exactly one helper for every version this shim reads, not a
- * second one for the v4-only case. Returns the produced v4 YAML text, or the
- * blocked reason/detail when the deterministic conversion cannot proceed
- * (an unmigratable v2/v3 shape, or a v4 document `planTaskToV4File` cannot
- * revalidate once `schedule[].enabled` is stripped) — 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");
-    // `writable`/`onDiskWritable` gate the DISK apply path's "don't touch a
-    // read-only file" check inside the planners; this shim never writes
-    // anything to disk, so that check does not apply here and must not block
-    // an otherwise-legal read of a task file that happens to be read-only.
-    const baseInput = {
-        filePath,
-        bytes,
-        mode: 0o644,
-        writable: true,
-        onDiskWritable: true,
-        ...(workspaceRoot ? { containmentRoot: workspaceRoot } : {}),
-    };
-    let v3Bytes;
-    if (version === 3 || version === 4) {
-        v3Bytes = bytes;
-    }
-    else {
-        const v3Outcome = planTaskToV3File(baseInput);
-        if (v3Outcome.status !== "changed")
-            return { reason: v3Outcome.reason, detail: v3Outcome.detail };
-        v3Bytes = v3Outcome.after;
-    }
-    const v4Outcome = planTaskToV4File({ ...baseInput, bytes: v3Bytes });
-    if (v4Outcome.status !== "changed")
-        return { reason: v4Outcome.reason, detail: v4Outcome.detail };
-    return v4Outcome.after.toString("utf8");
-}
 /**
  * True when `root`'s `schedule:` is a sequence with at least one mapping
  * entry that carries an `enabled` key, regardless of that key's value or
  * type — the shape 0.9.15's v4 grammar accepted and this release's does
- * not (`schedule[].enabled`). The value is never inspected: activation is
- * host-local `scheduler.enabled`, so this is purely a presence check that
- * decides whether to route through the in-memory shim.
+ * not (`schedule[].enabled`). Activation is host-local `scheduler.enabled`,
+ * so the value is never read; `akm migrate apply` removes the key.
  */
 export function v4ScheduleHasRetiredEnabledKey(root) {
     if (root === null || typeof root !== "object" || Array.isArray(root))
@@ -140,42 +61,17 @@ export function v4ScheduleHasRetiredEnabledKey(root) {
         return false;
     return schedule.some((entry) => entry !== null && typeof entry === "object" && !Array.isArray(entry) && Object.hasOwn(entry, "enabled"));
 }
-/** Parse task source YAML, routing per the terminal table above. */
+/** Parse task source YAML, routing per the table above. */
 export function parseTaskSource(input) {
     const { root, lineAt } = readBoundedTaskSourceYaml(input, { sourceLabel: "task source" });
     const version = peekTaskSourceVersion(root);
     if (version !== undefined && version !== TASK_SOURCE_V4_VERSION) {
-        if (version === 2 || version === 3) {
-            const shimmed = planInMemoryV4Bytes(version, input.yaml, input.filePath, input.workspaceRoot);
-            if (typeof shimmed === "string") {
-                const v4 = parseTaskSourceV4({
-                    yaml: shimmed,
-                    filePath: input.filePath,
-                    ...(input.workspaceRoot ? { workspaceRoot: input.workspaceRoot } : {}),
-                });
-                warnOnce(`task-source:v${version}-shim:${input.filePath}`, `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);
-        }
+        if (version === 2 || version === 3)
+            throw legacyVersionError(input.filePath, version);
         throw unsupportedVersionError(input.filePath, version);
     }
     if (version === TASK_SOURCE_V4_VERSION && v4ScheduleHasRetiredEnabledKey(root)) {
-        const shimmed = planInMemoryV4Bytes(4, input.yaml, input.filePath, input.workspaceRoot);
-        if (typeof shimmed === "string") {
-            const v4 = parseTaskSourceV4({
-                yaml: shimmed,
-                filePath: input.filePath,
-                ...(input.workspaceRoot ? { workspaceRoot: input.workspaceRoot } : {}),
-            });
-            warnOnce(`task-source:v4-schedule-enabled-shim:${input.filePath}`, `akm: task ${input.filePath} uses the retired schedule[].enabled field — auto-read with it ignored; run \`akm migrate apply\` to rewrite it and silence this`);
-            return Object.freeze({ version: 4, v4 });
-        }
-        // Version 4 is supported; a blocked outcome here means the file itself
-        // is malformed (`generated-v4-validation-failed`), not that this
-        // version needs a human decision — throw the v4 grammar error, not
-        // `unmigratableVersionError`.
-        throw new UsageError(shimmed.detail ?? shimmed.reason, "TASK_SOURCE_INVALID");
+        throw new UsageError(`Invalid task source v4 at ${input.filePath}: schedule[].enabled was removed (scheduler activation is host-local config). Run \`akm migrate apply\` to rewrite it.`, "TASK_SOURCE_INVALID", TASK_MIGRATE_HINT);
     }
     const documentOptions = {
         filePath: input.filePath,

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

@@ -374,7 +374,7 @@ function isReason(value) {
     return typeof value === "string";
 }
 /** Convert one already-normalized legacy record directly to final task v3. */
-export function planLegacyTaskDataToV3(input, data) {
+function planLegacyTaskDataToV3(input, data) {
     if (data.version !== 2) {
         return blocked(input, "unsupported-task-version", `expected normalized legacy version 2, got ${String(data.version)}`);
     }
@@ -451,57 +451,3 @@ export function planTaskToV3File(input) {
     }
     return planLegacyTaskDataToV3(input, data);
 }
-function generationFor(files) {
-    const digest = crypto.createHash("sha256");
-    digest.update("akm-task-to-v3-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");
-    }
-    return digest.digest("hex");
-}
-/** Build/fingerprint a plan from already-derived immutable outcomes. */
-export function taskToV3PlanFromOutcomes(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 planTaskToV3Migration(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 taskToV3PlanFromOutcomes(sorted.map(planTaskToV3File));
-}

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

@@ -318,7 +318,7 @@ function planV3DataToV4(input, data) {
             // `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 from both the in-memory read shim and `akm migrate apply`
+            // v3 file from `akm migrate apply`
             // (scripts/akm-migrate/migrate/task-files.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.
@@ -473,15 +473,3 @@ export function taskToV4PlanFromOutcomes(outcomes) {
     }
     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/migration/v0.9.1-to-v0.9.2.md

@@ -57,7 +57,9 @@ pace: an unmigrated v2/v3 task source keeps reading and running through the
 in-memory read shim, with a one-line deprecation warning, until you migrate
 it (nothing silently breaks or half-runs, and only a genuinely unmigratable
 shape fails closed with an actionable hint), and pre-`irVersion`-5 runs stay
-inspectable indefinitely.
+inspectable indefinitely. (0.9.17-alpha.7 removed that shim: a v2/v3 task
+source now fails on its own, naming `akm migrate apply`, which `akm upgrade`
+runs after an install.)
 
 ## Task sources
 
@@ -72,7 +74,9 @@ apply` remains the way to rewrite the file on disk and silence the warning.
 current grammar — extended the same kind of shim to a `version: 4` document
 whose `schedule[]` still carries a per-entry `enabled` key, retired from
 task source v4's own grammar since; the field is stripped without being
-read, never re-added.)
+read, never re-added. 0.9.17-alpha.7 removed both shims: akm now reads only
+task source v4, and each older file fails on its own, naming
+`akm migrate apply`.)
 
 **Before — 0.9.1 task v2:**
 
@@ -679,7 +683,7 @@ phase-specific code:
 | Code | Domain |
 |---|---|
 | `TASK_SOURCE_INVALID` | A task document's field- or semantic-level validation failure, or a malformed/oversized/too-deep YAML front end failure. |
-| `TASK_SCHEMA_VERSION_UNSUPPORTED` | A task document's `version:` is `3` or `2` and the in-memory read shim's deterministic conversion cannot resolve it — a human decision is needed (see [Task sources](#task-sources)); a convertible v2/v3 document reads through the shim instead of failing. |
+| `TASK_SCHEMA_VERSION_UNSUPPORTED` | A task document's `version:` is `3` or `2` and the in-memory read shim's deterministic conversion cannot resolve it — a human decision is needed (see [Task sources](#task-sources)); a convertible v2/v3 document reads through the shim instead of failing. From 0.9.17-alpha.7, every v2/v3 document fails this way, naming `akm migrate apply`. |
 | `TARGET_REF_INVALID` | A value is not a canonical `commands/`, `scripts/`, `tasks/`, or `workflows/` asset ref (malformed shapes, GitHub locators, other asset families). |
 | `WORKFLOW_SOURCE_INVALID` | A workflow-source compile failure other than the one below. |
 | `COMPOSITION_INVALID` | A composition-policy rejection: a rejected `with:`, a multi-job document, a composition cycle/depth/size violation. |

package/docs/reference/cli.md

@@ -2980,9 +2980,10 @@ crontab whose akm markers are malformed is refused unmodified, and another
 akm process holding the scheduler lock makes sync exit 75 (retry shortly).
 
 `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
+clean up on its own: entries that no longer resolve to a live bundle (a row
+whose `AKM_BUNDLE_DIR` names a directory that is gone, or a row written
+before 0.9.17-alpha.7 whose `--scheduler-context` descriptor cannot be
+read). 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

package/docs/reference/tasks.md

@@ -5,27 +5,22 @@ Task assets are strict, local automation sources. They live at
 launchd, or Windows Task Scheduler with `akm task sync`. The task file is
 authored source; scheduler entries are derived OS state.
 
-**Task source v4 (`version: 4`) is the current task source grammar.** A
-document with `version: 3` or `version: 2` still reads and runs: an
-in-memory shim converts it to v4 on the same bytes `akm migrate apply`
-would produce, prints a one-line stderr deprecation warning (once per file
-per process), and never writes anything to disk. Only a v2/v3 document the
-deterministic conversion itself cannot resolve (an ambiguous shell command,
-say) fails to load, with `UsageError` code `TASK_SCHEMA_VERSION_UNSUPPORTED`
-naming the specific blocked reason and the human decision it needs. A
-declared `version: 4` document whose `schedule[]` still carries a
-per-entry `enabled` key — 0.9.15's v4 grammar accepted it, this release's
-does not — reads through the same kind of in-memory shim: the key is
-stripped without ever being read (activation is host-local, below) and the
-same one-line deprecation warning is printed. Task source v4 adds typed
-`inputs:` and a single bounded `output:` schema (command targets only), and
-makes scheduling OPTIONAL rather than mandatory. `akm task add` authors
-task source v4 directly.
+**Task source v4 (`version: 4`) is the only task source grammar akm reads.**
+A document with `version: 3` or `version: 2` fails to load with `UsageError`
+code `TASK_SCHEMA_VERSION_UNSUPPORTED`, naming `akm migrate apply`, which
+converts it. A declared `version: 4` document whose `schedule[]` still
+carries a per-entry `enabled` key — 0.9.15's v4 grammar accepted it, this
+release's does not — fails the same way with `TASK_SOURCE_INVALID`
+(activation is host-local, below). Each such file fails on its own:
+`akm task sync` reports it and keeps reconciling every other task. Task
+source v4 adds typed `inputs:` and a single bounded `output:` schema
+(command targets only), and makes scheduling OPTIONAL rather than
+mandatory. `akm task add` authors task source v4 directly.
 
 If you have `version: 3` or `version: 2` files on disk (from an earlier
 akm release), see [Migrating to task source v4](#migrating-to-task-source-v4)
 below — `akm migrate apply` converts both generations in one pass and
-rewrites the file on disk, silencing the read-time deprecation warning. The
+rewrites the file on disk (`akm upgrade` runs it after an install). The
 retired v3 grammar itself is documented at the bottom of this page
 ([Task v3 (retired): grammar reference for migration](#task-v3-retired-grammar-reference-for-migration))
 purely so you can read an old file while migrating it; it is no longer
@@ -38,10 +33,9 @@ indexed, scheduled, or run. Every task should declare `version: 4`; a
 document with no `version:` key, or a `version:` that is not a number,
 fails with `TASK_SOURCE_INVALID` (`must be exactly 4.` / `is required and
 must be exactly 4.`) — a genuinely malformed v4 document, not a legacy one.
-`version: 3` and `version: 2` read via the in-memory deprecation shim
-described above and, only when the deterministic conversion itself cannot
-resolve the document, fail with `TASK_SCHEMA_VERSION_UNSUPPORTED` instead
-(see [Migrating to task source v4](#migrating-to-task-source-v4)).
+`version: 3` and `version: 2` fail with `TASK_SCHEMA_VERSION_UNSUPPORTED`
+naming `akm migrate apply` (see
+[Migrating to task source v4](#migrating-to-task-source-v4)).
 The published [task schema](../../schemas/akm-task.json) describes the
 hand-authored contract; `src/tasks/source/task-source-v4.ts` is the
 authoritative bounded parser.
@@ -414,17 +408,14 @@ for full before/after examples and recovery guidance.
   anything — see [`akm task explain`](#akm-task-explain) above.
 - `akm task validate <path>` parses one task file by filesystem path (the
   file need not live in a configured bundle) and reports the same
-  `valid`/`converts`/`blocked`/`invalid`/`not-a-task` diagnostic
+  `valid`/`blocked`/`invalid`/`not-a-task` diagnostic
   `akm task sync` would produce for it — including sync's own cron-dialect
   check and its per-schedule-entry input-contract check — without touching
   the scheduler and without requiring a configured engine, even for a
   command-kind task. The envelope's own `sourceVersion` field names the
-  file's declared schema version. A version 2/3 file the in-memory shim
-  converts reports `converts` (exit 0); one the shim's deterministic
-  planner cannot resolve reports `blocked` (exit 1) naming the human
-  decision it needs. A `version: 4` file whose only defect is a retired
-  `schedule[].enabled` also reports `converts` (`sourceVersion` still `4`)
-  — it read through the shim too, not the direct v4 path.
+  file's declared schema version. A version 2/3 file, and a `version: 4`
+  file still carrying a retired `schedule[].enabled`, report `blocked`
+  (exit 1) naming `akm migrate apply`, which converts them.
 - `akm task add` validates a task source v4 document, writes it, adds its ref
   to local scheduler activation, and syncs its bundle. `--params` renders
   typed `inputs:` declarations instead of a `with:` bag; `--schedule` is
@@ -443,8 +434,8 @@ for full before/after examples and recovery guidance.
   A row that fails to install or remove is reported in `failures` and every
   other row still applies. A source that fails to parse is reported the same
   way, and its installed row is left exactly as it is. Rows akm cannot attribute to a bundle this sync covers —
-  another bundle's, another installation's (the row's own descriptor names a
-  different bundle path), or anything outside akm's `# akm:task` markers,
+  another bundle's, another installation's (the row's `AKM_BUNDLE_DIR`
+  names a different working stash), or anything outside akm's `# akm:task` markers,
   `com.akm.task.` labels, or `\akm\` task folder — are never touched. A
   Task Scheduler row is compared by the fingerprint akm writes into its
   `<Source>` plus its enabled state, so an edit made in Task Scheduler that
@@ -457,9 +448,10 @@ for full before/after examples and recovery guidance.
   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.
+  because they no longer resolve to a live bundle: a row whose
+  `AKM_BUNDLE_DIR` names a directory that is gone, or a row written before
+  0.9.17-alpha.7 whose `--scheduler-context` descriptor cannot be read. 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.
@@ -473,13 +465,39 @@ for full before/after examples and recovery guidance.
   section directly above the first akm task block in the crontab (on macOS,
   an `EnvironmentVariables` entry in each plist). It is the PATH of the shell
   that ran the sync, rewritten on every crontab write and removed with the
-  last akm block; cron applies it to every row below it. The
-  `--scheduler-context` descriptor a row references holds directories only:
-  the bundle path, plus any `AKM_CONFIG_DIR`, `AKM_DATA_DIR`, `AKM_CACHE_DIR`
-  or `AKM_STATE_DIR` that shell had set explicitly. Defaults resolve at fire
-  time, so a scheduled run uses the same state, data and cache directories an
-  interactive command does. Run the sync from a shell whose environment you
-  would want scheduled.
+  last akm block; cron applies it to every row below it.
+- A task's row is its command plus its schedule:
+  `<launcher> task run <id> --bundle <bundle> --scheduled`, and it sets its
+  own environment. Every row sets `AKM_BUNDLE_DIR` to the working stash of
+  the shell that ran the sync (its `AKM_BUNDLE_DIR`, or the default bundle),
+  so the scheduled run uses the same working stash, `--bundle` finds a stash
+  no config names, and sync tells rows of other installations sharing the
+  scheduler apart (#846). Rows synced from a shell that set
+  `AKM_CONFIG_DIR`, `AKM_DATA_DIR`, `AKM_CACHE_DIR` or `AKM_STATE_DIR`
+  explicitly set those too. Each backend does it its own way: a
+  `VAR=value` prefix in the crontab, an `EnvironmentVariables` entry in the
+  plist, a `$env:VAR='value';` assignment ahead of the command in Task
+  Scheduler. Other defaults resolve at fire time, so a scheduled run uses
+  the same state, data and cache directories an interactive command does.
+  Run the sync from a shell whose environment you would want scheduled.
+
+  ```text
+  15 2 * * * AKM_BUNDLE_DIR=/home/u/akm /home/u/.bun/bin/bun /home/u/.bun/lib/node_modules/akm-cli/dist/akm task run nightly --bundle work --scheduled > /home/u/.cache/akm/tasks/logs/nightly.log 2>&1
+  ```
+
+  A row whose command is over 1,000 bytes runs a wrapper script under the
+  log directory instead (`sh <log dir>/.akm-cron-wrapper-<id>-<hash>.sh`);
+  sync reads the script to tell which task the row runs.
+
+  Releases 0.9.0 through 0.9.17-alpha.6 wrote a `--scheduler-context
+  <file>` argument into each row instead, naming a descriptor file under
+  `$DATA/tasks/context/` that held the same values. akm still applies that
+  file when such a row fires, and the first `akm task sync` after upgrading
+  rewrites each row in place: it shows as an update, keeps the row's
+  launcher and schedule, and sets the values inline. A row the sync leaves as it is (its task file failed to load, or
+  a `--bundle` sync did not cover it) still names its file; once
+  `akm task doctor` lists no binding with a `contextPath`, the old descriptor
+  files are not read and can be deleted.
 
 Scheduler execution is at least once. Backends provide a stable invocation
 identity and AKM fences stale attempts, but an ambiguous process crash can be

package/package.json

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