akm-cli 0.9.1 → 0.9.2-alpha.2

package/dist/commands/tasks/tasks.js

@@ -8,48 +8,38 @@
  * `src/cli.ts` wraps these in citty `defineCommand`s and shapes their return
  * values via `output()`.
  */
+import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { stringify as yamlStringify } from "yaml";
+import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
 import { assetPathForName } from "../../core/asset/asset-placement.js";
-import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
+import { makeBundleRef, parseBundleRef } from "../../core/asset/asset-ref.js";
+import { conceptIdFromTypeName, isFullRefInput } from "../../core/asset/resolve-ref.js";
 import { isWithin, resolveStashDir } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
+import { resolveConfiguredSources } from "../../core/config/config-sources.js";
 import { IMPROVE_AUTONOMY_CONFIG_KEY, isImproveAutonomyEnabled } from "../../core/config/experimental.js";
 import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
 import { getTaskHistoryDir, getTaskLogDir } from "../../core/paths.js";
-import { commitWriteTargetBoundary, deleteAssetFromSource, prepareWriteTargetForMutation, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
+import { commitWriteTargetBoundary, deleteAssetFromSource, prepareWriteTargetForMutation, resolveWorkingStashTarget, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
 import { withEngineFallback } from "../../integrations/agent/engine-fallback.js";
+import { resolveAssetPath } from "../../sources/resolve.js";
 import { backendNameForPlatform, selectBackend } from "../../tasks/backends/index.js";
-import { parseTaskDocument } from "../../tasks/parser.js";
 import { resolveAkmInvocation } from "../../tasks/resolve-akm-bin.js";
-import { exitCodeForStatus, INVALID_TASK_ATTEMPT_ID, readTaskHistory, recordTaskAttemptFailure, runTask, } from "../../tasks/runner.js";
+import { exitCodeForStatus, readTaskHistory, runTask } from "../../tasks/runner.js";
+import { prepareTaskV3Execution } from "../../tasks/runtime-v3.js";
 import { parseSchedule, SCHEDULE_SUPPORTED_SUBSET_HINT } from "../../tasks/schedule.js";
-import { schedulerContextDescriptor, validateSchedulerContextDescriptor, writeSchedulerContextDescriptor, } from "../../tasks/scheduler-invocation.js";
-import { normaliseTaskId } from "../../tasks/task-id.js";
-import { validateTaskDocument } from "../../tasks/validator.js";
+import { assertSchedulerMutationArtifact, assertSchedulerNativeArtifactCardinality, compileTaskSchedulerBindings, schedulerBindingNativeId, schedulerBindingOrdinal, schedulerNativeArtifactKey, schedulerNativeBindingId, } from "../../tasks/scheduler-binding.js";
+import { schedulerContextDescriptor, schedulerContextPath, validateSchedulerContextDescriptor, writeSchedulerContextDescriptor, } from "../../tasks/scheduler-invocation.js";
+import { assertSchedulerNativeArtifactOwnership, assertSchedulerSourceSnapshot, finalizeSchedulerSyncPlan, prepareSchedulerSyncSourceSet, } from "../../tasks/scheduler-sync.js";
+import { parseTaskV3Yaml, TASK_V3_MAX_SOURCE_BYTES } from "../../tasks/source-v3.js";
+import { normaliseTaskConceptId, normaliseTaskId } from "../../tasks/task-id.js";
 import { applyAutonomyGate, configuredDirectAutonomyLanes, describeGatedLanes } from "../improve/autonomy-gate.js";
 import { resolveImproveStrategy } from "../improve/improve-strategies.js";
 export async function akmTasksAdd(input, deps = {}) {
     const id = normaliseTaskId(input.id);
-    const hasCommand = input.command !== undefined &&
-        input.command !== null &&
-        !(typeof input.command === "string" && input.command.trim() === "") &&
-        !(Array.isArray(input.command) && input.command.length === 0);
-    const targetCount = [Boolean(input.workflow), Boolean(input.prompt), hasCommand].filter(Boolean).length;
-    if (targetCount !== 1) {
-        throw new UsageError("Pass exactly one of --workflow <ref>, --prompt <asset-ref|./file.md|text>, or --command <shell-command>.", "INVALID_FLAG_VALUE");
-    }
-    // `--timeout-ms` IS valid on a workflow task: it is the whole-run bound the
-    // task runner turns into an abort signal (issue 11), the same one
-    // `akm workflow run --timeout` applies interactively. Engine and model stay
-    // prompt-only — a workflow's engines come from its frozen plan.
-    if (input.workflow && (input.engine !== undefined || input.model !== undefined)) {
-        throw new UsageError("Workflow tasks accept --params and --timeout-ms; engine and model are prompt-task fields.", "INVALID_FLAG_VALUE");
-    }
-    if (hasCommand && (input.engine !== undefined || input.model !== undefined)) {
-        throw new UsageError("Command tasks accept --timeout-ms but not --engine or --model.", "INVALID_FLAG_VALUE");
-    }
+    assertTaskAddTargetShape(input);
     // Validate the schedule for the active backend before writing anything.
     // WI-9.10e: the injected backend (tests) carries its own name, so derive it
     // from `deps.backend` when present — retiring the `_setBackendsForTests` seam.
@@ -64,14 +54,13 @@ export async function akmTasksAdd(input, deps = {}) {
     if (!isWithin(assetPath, typeRoot)) {
         throw new UsageError(`Resolved task path escapes the stash: "${id}".`, "PATH_ESCAPE_VIOLATION");
     }
-    // Pre-0.8.0 tasks were markdown; the 0.8.0 cutover moved them to pure YAML
-    // (see the tasks dir rule in src/indexer/walk/matchers.ts). A leftover
-    // `<id>.md` still names the same task, so creating `<id>.yml` beside it
-    // must collide loudly rather than silently minting a duplicate.
-    const legacyAssetPath = path.join(typeRoot, `${id}.md`);
-    if ((fs.existsSync(assetPath) || fs.existsSync(legacyAssetPath)) && !input.force) {
+    if (fs.existsSync(assetPath) && !input.force) {
         throw new UsageError(`Task "${id}" already exists. Pass --force to overwrite, or delete its file and run \`akm task sync\` first.`, "RESOURCE_ALREADY_EXISTS");
     }
+    const sourceExpectation = captureTaskSourceExpectation(assetPath, stashDir);
+    if (sourceExpectation.state === "present" && !input.force) {
+        throw new UsageError(`Task "${id}" appeared while add was preparing. Pass --force only after reviewing the current owner.`, "RESOURCE_ALREADY_EXISTS");
+    }
     const yaml = renderTaskYaml({
         id,
         schedule: input.schedule,
@@ -88,152 +77,165 @@ export async function akmTasksAdd(input, deps = {}) {
         tags: input.tags,
         enabled: input.disabled !== true,
     });
-    const task = parseTaskDocument({ yaml, filePath: assetPath, id });
-    await validateTaskDocument(task, { backend, stashDir });
+    const task = parseTaskV3Yaml({ yaml, filePath: assetPath, workspaceRoot: stashDir });
+    const qualifiedRef = makeBundleRef(bundle.bundleName, `tasks/${id}`);
+    await prepareTaskV3Execution(task, {
+        taskId: id,
+        taskRef: qualifiedRef,
+        bundleName: bundle.bundleName,
+        bundleRoot: stashDir,
+        config: bundle.config,
+        resolveAsset: taskProjectionAssetResolver(bundle.config, bundle.bundleName, stashDir),
+    });
+    const taskBindings = compileTaskSchedulerBindings({
+        id,
+        qualifiedRef,
+        ...(bundle.installTarget ? { bundleTarget: bundle.installTarget } : {}),
+        enabled: task.akm?.enabled !== false,
+        schedules: task.triggers.schedules,
+    });
+    const taskBinding = taskBindings[0];
+    if (!taskBinding)
+        throw new UsageError(`Task "${id}" has no schedulable trigger.`, "INVALID_FLAG_VALUE");
     const ref = taskAssetRef(id);
-    const previousYaml = fs.existsSync(assetPath) ? fs.readFileSync(assetPath, "utf8") : undefined;
-    let previousTask;
-    let previousTaskError;
-    if (previousYaml !== undefined) {
-        try {
-            previousTask = parseTaskDocument({ yaml: previousYaml, filePath: assetPath, id });
-        }
-        catch (err) {
-            previousTaskError = err;
-        }
-    }
     const sched = deps.backend ?? selectBackend();
     const writeAsset = deps.writeAsset ?? writeAssetToSource;
     const deleteAsset = deps.deleteAsset ?? deleteAssetFromSource;
     const commitBoundary = deps.commitBoundary ?? commitWriteTargetBoundary;
-    const installedEntries = await sched.list();
-    assertNoForeignSchedule(installedEntries, id, bundle.installTarget);
-    const wasInstalled = previousYaml !== undefined && installedEntries.some((entry) => entry.id === id);
-    const installedEntry = installedEntries.find((entry) => entry.id === id);
-    const runtimeOpts = schedulerInstallOptions(installOpts, installedEntry, deps, installedEntry ? false : input.rebind === true, `create scheduler entry for task "${id}"`);
-    let sourceRestoreArmed = false;
-    let installSucceeded = false;
-    try {
-        sourceRestoreArmed = true;
+    const transaction = await prepareTaskAddSchedulerTransaction({
+        id,
+        installTarget: bundle.installTarget,
+        ownerTarget: bundle.bundleName,
+        installOpts,
+        taskBindings,
+        sched,
+        deps,
+        rebind: input.rebind === true,
+    });
+    let sourceMutationReceipt;
+    let sourcePublished = false;
+    let sourcePublicationAttempted = false;
+    const publishSource = async () => {
+        assertTaskSourceExpectation(sourceExpectation);
+        sourcePublicationAttempted = true;
         await writeAsset(writeTarget.source, writeTarget.config, ref, yaml);
-        await sched.install(task, runtimeOpts);
-        installSucceeded = true;
-        commitBoundary(writeTarget, `Update tasks/${id}`);
-    }
-    catch (err) {
-        const rollbackErrors = [];
-        let sourceRestored = false;
-        if (sourceRestoreArmed) {
-            try {
-                if (previousYaml === undefined) {
-                    if (fs.existsSync(assetPath)) {
-                        await deleteAsset(writeTarget.source, writeTarget.config, ref);
-                        sourceRestored = true;
-                    }
-                }
-                else {
-                    await restoreTaskSourceBytes(writeAsset, writeTarget.source, writeTarget.config, ref, assetPath, previousYaml);
-                    sourceRestored = true;
+        const publishedSource = captureTaskSourceExpectation(assetPath, stashDir);
+        if (publishedSource.state !== "present" || publishedSource.sha256 !== hashTaskSource(yaml)) {
+            throw new UsageError(`Task source ${JSON.stringify(assetPath)} changed during publication.`, "RESOURCE_ALREADY_EXISTS");
+        }
+        sourceMutationReceipt = publishedSource;
+        sourcePublished = true;
+        transaction.publishRuntime?.();
+    };
+    await applySchedulerTransaction(sched, transaction.operations, {
+        initialExpectations: transaction.initialExpectations,
+        assertReadSet: () => {
+            if (sourcePublished) {
+                if (!sourceMutationReceipt) {
+                    throw new ConfigError("Published task source lost its transaction receipt.", "INVALID_CONFIG_FILE");
                 }
+                assertTaskSourceExpectation(sourceMutationReceipt);
             }
-            catch (rollbackError) {
-                rollbackErrors.push(rollbackError);
-            }
-        }
-        if (installSucceeded && !wasInstalled) {
-            try {
-                await sched.uninstall(id);
+            else {
+                assertTaskSourceExpectation(sourceExpectation);
             }
-            catch (rollbackError) {
-                rollbackErrors.push(rollbackError);
+        },
+        beforeOperation: async (_operation, index) => {
+            if (index === transaction.publishOperationIndex && !sourcePublished)
+                await publishSource();
+        },
+        afterOperations: () => commitBoundary(writeTarget, `Update tasks/${id}`),
+        rollbackExternal: async () => {
+            if (!sourcePublicationAttempted)
+                return;
+            if (!sourceMutationReceipt) {
+                const current = captureTaskSourceExpectation(assetPath, stashDir);
+                if (sameTaskSourceExpectation(current, sourceExpectation))
+                    return;
+                if (current.state !== "present" || current.sha256 !== hashTaskSource(yaml)) {
+                    throw new UsageError(`Task source ${JSON.stringify(assetPath)} has an unowned publication state; refusing rollback over a possible concurrent owner.`, "RESOURCE_ALREADY_EXISTS");
+                }
+                sourceMutationReceipt = current;
             }
-        }
-        else if (installSucceeded && previousTask) {
+            assertTaskSourceExpectation(sourceMutationReceipt);
             try {
-                await sched.install(previousTask, runtimeOpts);
-            }
-            catch (rollbackError) {
-                rollbackErrors.push(rollbackError);
-                try {
-                    if (typeof sched.setEnabled !== "function") {
-                        throw new Error(`Scheduler backend "${sched.name}" cannot disable task "${id}".`);
-                    }
-                    await sched.setEnabled(id, false);
+                if (sourceExpectation.state === "absent") {
+                    await deleteAsset(writeTarget.source, writeTarget.config, ref);
                 }
-                catch (disableError) {
-                    rollbackErrors.push(disableError);
-                    try {
-                        await sched.uninstall(id);
-                    }
-                    catch (uninstallError) {
-                        rollbackErrors.push(uninstallError);
+                else {
+                    await writeAsset(writeTarget.source, writeTarget.config, ref, sourceExpectation.content);
+                    const providerRestored = captureTaskSourceExpectation(assetPath, stashDir);
+                    if (providerRestored.state !== "present" || providerRestored.sha256 !== sourceExpectation.sha256) {
+                        // Provider writers conventionally normalize a trailing newline.
+                        // Rollback is byte-exact, so finish the already-owned restore with
+                        // the frozen bytes before checking the physical source state.
+                        fs.writeFileSync(assetPath, Buffer.from(sourceExpectation.bytesBase64, "base64"));
                     }
                 }
-            }
-        }
-        else if (installSucceeded && wasInstalled) {
-            rollbackErrors.push(previousTaskError ?? new Error(`Prior task "${id}" could not be restored.`));
-        }
-        if (sourceRestored) {
-            try {
+                assertTaskSourceRestored(sourceExpectation);
                 commitBoundary(writeTarget, `Restore tasks/${id}`);
             }
-            catch (rollbackError) {
-                rollbackErrors.push(rollbackError);
+            catch (cause) {
+                // A write/commit seam may report failure after it has already restored
+                // the exact source bytes. Prove that state before allowing native
+                // rollback; otherwise preserve the possible concurrent source owner.
+                try {
+                    assertTaskSourceRestored(sourceExpectation);
+                }
+                catch {
+                    throw cause;
+                }
+                throw new TaskSourceRestoredBoundaryError(cause);
             }
-        }
-        if (rollbackErrors.length > 0) {
-            const message = err instanceof Error ? err.message : String(err);
-            throw new AggregateError([err, ...rollbackErrors], `${message}; rollback for task "${id}" was incomplete.`);
-        }
-        throw err;
-    }
+        },
+        suppressNativeRollbackWhenExternalFails: true,
+        allowNativeRollbackAfterExternalFailure: (error) => error instanceof TaskSourceRestoredBoundaryError,
+    });
     return {
         id,
         ref: conceptIdFromTypeName("task", id),
         path: assetPath,
         bundleDir: stashDir,
-        schedule: task.schedule,
-        enabled: task.enabled,
+        schedule: taskBinding.cron,
+        enabled: taskBinding.enabled,
         backend,
         target: task.target,
     };
 }
-export async function akmTasksRun(id, options = {}) {
-    const startedAt = new Date();
-    let normalised;
-    try {
-        normalised = parseTaskRef(id).id;
-    }
-    catch (failure) {
-        recordTaskAttemptFailure({
-            taskId: INVALID_TASK_ATTEMPT_ID,
-            reason: "invalid_task_id",
-            failure,
-            startedAt,
-        });
-        throw failure;
+function assertTaskAddTargetShape(input) {
+    const hasCommand = input.command !== undefined &&
+        input.command !== null &&
+        !(typeof input.command === "string" && input.command.trim() === "") &&
+        !(Array.isArray(input.command) && input.command.length === 0);
+    const targetCount = [Boolean(input.workflow), Boolean(input.prompt), hasCommand].filter(Boolean).length;
+    if (targetCount !== 1) {
+        throw new UsageError("Pass exactly one of --workflow <ref>, --prompt <inline-text>, or --command <shell-command>.", "INVALID_FLAG_VALUE");
     }
-    let stashDir;
-    try {
-        // No --bundle uses the primary stash. With --bundle, resolve (read-only)
-        // the named bundle so the task file and
-        // its relative asset refs load from that bundle's path.
-        stashDir =
-            options.target !== undefined
-                ? resolveWriteTarget(loadConfig(), options.target, { requireWritable: false }).source.path
-                : resolveStashDir();
-    }
-    catch (failure) {
-        recordTaskAttemptFailure({
-            taskId: normalised,
-            reason: "task_load_failed",
-            failure,
-            startedAt,
-        });
-        throw failure;
+    // `--timeout-ms` is the workflow's whole-run bound. Engine and model stay
+    // prompt-only because workflow engines come from the frozen plan.
+    if (input.workflow && (input.engine !== undefined || input.model !== undefined)) {
+        throw new UsageError("Workflow tasks accept --params and --timeout-ms; engine and model are prompt-task fields.", "INVALID_FLAG_VALUE");
+    }
+    if (hasCommand && (input.engine !== undefined || input.model !== undefined)) {
+        throw new UsageError("Command tasks accept --timeout-ms but not --engine or --model.", "INVALID_FLAG_VALUE");
     }
-    const result = await runTask(normalised, { stashDir, scheduled: options.scheduled === true });
+    if (input.prompt !== undefined)
+        assertInlineTaskPrompt(input.prompt);
+}
+export async function akmTasksRun(id, options = {}) {
+    const parsed = parseTaskRef(id);
+    const bundle = resolveTaskReadBundle(parsed.bundle, options.target);
+    const adapterId = bundle.source.adapterId ?? detectAdapterId(bundle.source.path);
+    const resolvedId = taskIdForAdapter(parsed.id, adapterId);
+    const runOptions = {
+        stashDir: bundle.source.path,
+        bundleName: bundle.source.name,
+        adapterId,
+        scheduled: options.scheduled === true,
+    };
+    // The runner owns the prepare-before-reserve boundary. Invalid source,
+    // projectability, and resolver failures therefore create no history row.
+    const result = await runTask(resolvedId, runOptions);
     const exitCode = result.status === "failed" && result.target.kind === "command" && result.detail?.exitCode === 78
         ? 78
         : exitCodeForStatus(result.status);
@@ -245,14 +247,18 @@ export async function akmTasksRun(id, options = {}) {
 }
 export async function akmTasksHistory(input) {
     const limit = input.limit !== undefined && input.limit > 0 ? input.limit : 50;
-    const id = input.id ? normaliseTaskId(input.id) : undefined;
+    const parsed = input.id ? parseTaskRef(input.id) : undefined;
+    const bundle = resolveTaskReadBundle(parsed?.bundle, input.target);
+    const adapterId = bundle.source.adapterId ?? detectAdapterId(bundle.source.path);
+    const id = parsed ? taskIdForAdapter(parsed.id, adapterId) : undefined;
     // History rows are keyed by task id in state.db, not per bundle.
     return { rows: readTaskHistory({ id, limit }) };
 }
 /**
  * Reconcile the on-disk task files of ONE bundle with the OS scheduler.
- *   • install missing tasks (after validating them — invalid files are
- *     skipped with a per-task reason rather than aborting the whole sync)
+ *   • compile and runtime-project the complete desired task/workflow set;
+ *     one invalid source rejects the sync before descriptor/backend mutation
+ *   • install missing bindings only after that whole-set preflight succeeds
  *   • reinstall tasks whose schedule or enabled state changed in the .yml
  *     (drift detected by comparing the backend's installed signature against
  *     the signature the current definition would produce)
@@ -268,101 +274,65 @@ export async function akmTasksHistory(input) {
  * (or `sync --bundle` on a bundle whose task files are already present).
  */
 export async function akmTasksSync(deps = {}, bundleTarget, options = {}) {
-    const stashDir = resolveTaskInspectDir(bundleTarget);
-    // Primary-bundle scheduler entries omit --bundle; other bundles carry it.
+    const resolved = resolveTaskReadBundle(undefined, bundleTarget);
+    const config = loadConfig();
+    const stashDir = resolved.source.path;
     const syncTarget = bundleTarget !== undefined && !isPrimaryStashPath(stashDir) ? bundleTarget : undefined;
-    const typeRoot = path.join(stashDir, "tasks");
-    const fileIds = fs.existsSync(typeRoot)
-        ? fs
-            .readdirSync(typeRoot)
-            .filter((f) => f.endsWith(".yml"))
-            .map((f) => f.slice(0, -4))
-        : [];
     const sched = deps.backend ?? selectBackend();
-    const backend = sched.name;
-    const installOpts = syncTarget !== undefined ? { target: syncTarget } : undefined;
-    const allEntries = options.rebind && sched.listForRebind ? await sched.listForRebind() : await sched.list();
-    // Attribution filter: only entries installed from THIS bundle are reconciled
-    // here. Entries carrying a `--bundle` for a different bundle are invisible to
-    // this sync — never removed, never touched.
-    const present = new Map(allEntries.filter((t) => sameBundle(t.target, syncTarget)).map((t) => [t.id, t]));
-    const installed = [];
-    const updated = [];
-    const unchanged = [];
-    const skipped = [];
+    if (!sched.inspectBindings) {
+        throw new ConfigError(`Scheduler backend "${sched.name}" cannot provide one coherent inspection for transactional sync.`, "INVALID_CONFIG_FILE");
+    }
+    const inspection = await sched.inspectBindings({ rebind: options.rebind === true });
+    const rawEntries = [...inspection.installed];
+    const allEntries = rawEntries.map((entry) => ({
+        ...entry,
+        ...(entry.nativeId !== undefined ? { nativeId: entry.nativeId } : {}),
+        ...(entry.invocation !== undefined ? { invocation: Object.freeze([...entry.invocation]) } : {}),
+        binding: "binding" in entry ? [...entry.binding] : [],
+        contextPath: "contextPath" in entry ? entry.contextPath : "",
+    }));
+    const nativeArtifacts = inspection.artifacts;
+    const common = {
+        sourceRoot: stashDir,
+        adapterId: resolved.source.adapterId ?? detectAdapterId(stashDir),
+        bundleName: resolved.source.name,
+        ...(syncTarget ? { bundleTarget: syncTarget } : {}),
+        backend: sched.name,
+        installed: allEntries,
+        nativeArtifacts,
+        inspection: Object.freeze({ installed: allEntries, artifacts: nativeArtifacts }),
+        rebind: options.rebind === true,
+        config,
+        resolveAsset: taskProjectionAssetResolver(config, resolved.source.name, stashDir),
+    };
+    // Pass one validates every desired source, ownership domain, schedule, and
+    // installed-id collision before runtime descriptor preparation is possible.
+    const preparedSources = await prepareSchedulerSyncSourceSet(common);
+    const preflight = finalizeSchedulerSyncPlan(common, preparedSources);
     const warnings = [];
-    for (const id of fileIds) {
-        const filePath = path.join(typeRoot, `${id}.yml`);
-        let task;
-        try {
-            task = parseTaskDocument({ yaml: fs.readFileSync(filePath, "utf8"), filePath, id });
-            await validateTaskDocument(task, { backend, stashDir });
-            // A bare id can only be scheduled from ONE bundle at a time (scheduler ids
-            // are never namespaced). If this id is already scheduled from a different
-            // bundle, refuse rather than clobber it — surface it as a per-task skip so
-            // the rest of the sync still proceeds.
-            const foreign = allEntries.find((e) => e.id === id && !sameBundle(e.target, syncTarget));
-            if (foreign)
-                throw new UsageError(foreignScheduleMessage(id, foreign.target), "RESOURCE_ALREADY_EXISTS");
-        }
-        catch (err) {
-            skipped.push({ id, reason: err instanceof Error ? err.message : String(err) });
-            if (present.has(id)) {
-                try {
-                    await sched.setEnabled(id, false);
-                }
-                catch (disableError) {
-                    try {
-                        await sched.uninstall(id);
-                    }
-                    catch (uninstallError) {
-                        throw new AggregateError([err, disableError, uninstallError], `Task "${id}" is invalid and its installed scheduler entry could not be disabled or removed.`);
-                    }
-                }
-            }
-            continue;
-        }
-        if (!present.has(id)) {
-            try {
-                const runtimeOpts = schedulerInstallOptions(installOpts, undefined, deps, options.rebind === true, `create scheduler entry for task "${id}"`, warnings);
-                await sched.install(task, runtimeOpts);
-                installed.push(id);
-            }
-            catch (error) {
-                skipped.push({ id, reason: error instanceof Error ? error.message : String(error) });
+    const expectedSignature = sched.expectedSignature?.bind(sched);
+    const needsRuntime = preflight.operations.some((operation) => operation.kind !== "remove" && operation.options?.binding === undefined);
+    const prepared = needsRuntime
+        ? prepareSchedulerSyncRuntime(syncTarget ? { target: syncTarget } : undefined, deps, options.rebind === true, "reconcile native scheduler bindings", warnings)
+        : undefined;
+    const plan = finalizeSchedulerSyncPlan({
+        ...common,
+        ...(prepared?.options ? { installOptions: prepared.options } : {}),
+        ...(expectedSignature
+            ? {
+                expectedSignature: (binding, install) => expectedSignature(binding, install),
             }
-            continue;
-        }
-        // Already installed — reconcile against the current definition. Compare the
-        // installed signature to what this task would render to; reinstall on drift.
-        // When the backend can't produce a signature (no expectedSignature, or it
-        // didn't record one), reinstall unconditionally — install() is idempotent,
-        // so the cost is one crontab write and correctness is guaranteed.
-        const installedEntry = present.get(id);
-        const runtimeOpts = schedulerInstallOptions(installOpts, options.rebind ? undefined : installedEntry, deps, options.rebind === true, `rebind scheduler entry for task "${id}"`, warnings);
-        const installedSig = installedEntry.signature;
-        const expectedSig = sched.expectedSignature?.(task, runtimeOpts);
-        if (installedSig !== undefined && expectedSig !== undefined && installedSig === expectedSig) {
-            unchanged.push(id);
-        }
-        else {
-            await sched.install(task, runtimeOpts);
-            updated.push(id);
-        }
-    }
-    const removed = [];
-    for (const installedId of present.keys()) {
-        if (!fileIds.includes(installedId)) {
-            await sched.uninstall(installedId);
-            removed.push(installedId);
-        }
-    }
+            : {}),
+    }, preparedSources);
+    await applySchedulerSyncPlan(sched, plan, prepared?.publish && plan.operations.some((operation) => operation.kind !== "remove")
+        ? prepared.publish
+        : undefined);
     return {
-        installed,
-        updated,
-        removed,
-        unchanged,
-        skipped,
+        installed: [...plan.installed],
+        updated: [...plan.updated],
+        removed: [...plan.removed],
+        unchanged: [...plan.unchanged],
+        skipped: [],
         backend: sched.name,
         ...(warnings.length > 0 ? { warnings } : {}),
     };
@@ -446,24 +416,281 @@ export async function akmTasksDoctor(deps = {}) {
     };
 }
 // ── helpers ─────────────────────────────────────────────────────────────────
-function schedulerInstallOptions(base, installed, deps, explicitRebind, operation, warnings = []) {
-    if (installed && !explicitRebind) {
-        return {
-            ...base,
-            binding: installed.binding,
-            contextPath: installed.contextPath,
-        };
+async function applySchedulerSyncPlan(backend, plan, publish) {
+    await applySchedulerTransaction(backend, plan.operations, {
+        initialExpectations: plan.operations.map((operation) => operation.expected),
+        assertReadSet: () => assertSchedulerSourceSnapshot(plan.sourceSnapshot),
+        beforeOperation: (_operation, index) => {
+            if (index === 0)
+                publish?.();
+        },
+    });
+}
+async function applySchedulerTransaction(backend, operations, hooks) {
+    if (operations.length === 0) {
+        hooks.assertReadSet?.();
+        await hooks.afterOperations?.();
+        hooks.assertReadSet?.();
+        return;
+    }
+    hooks.assertReadSet?.();
+    if (!backend.snapshotBindings || !backend.restoreBindings) {
+        throw new ConfigError(`Scheduler backend "${backend.name}" cannot snapshot and restore a whole-set transaction.`, "INVALID_CONFIG_FILE");
     }
-    // Injected backends can own their default runtime unless a resolver is supplied.
+    const nativeIds = [
+        ...new Set(operations.map((operation) => operation.kind === "remove" ? operation.nativeId : schedulerBindingNativeId(operation.binding))),
+    ];
+    const snapshot = await backend.snapshotBindings(nativeIds);
+    assertSchedulerTransactionSnapshot(snapshot, nativeIds, hooks.initialExpectations);
+    const rollbackExpected = schedulerRollbackExpectations(snapshot, operations);
+    hooks.assertReadSet?.();
+    try {
+        for (const [index, operation] of operations.entries()) {
+            hooks.assertReadSet?.();
+            await hooks.beforeOperation?.(operation, index);
+            hooks.assertReadSet?.();
+            if (operation.kind === "remove")
+                await backend.uninstall(operation.nativeId, operation.expected);
+            else
+                await backend.install(operation.binding, operation.options, operation.expected);
+            hooks.assertReadSet?.();
+        }
+        hooks.assertReadSet?.();
+        await hooks.afterOperations?.();
+        hooks.assertReadSet?.();
+    }
+    catch (primaryError) {
+        let externalRollbackError;
+        try {
+            await hooks.rollbackExternal?.();
+        }
+        catch (error) {
+            externalRollbackError = error;
+        }
+        let nativeRollbackError;
+        const externalStateAllowsNativeRollback = externalRollbackError !== undefined &&
+            hooks.allowNativeRollbackAfterExternalFailure?.(externalRollbackError) === true;
+        if (!(externalRollbackError && hooks.suppressNativeRollbackWhenExternalFails && !externalStateAllowsNativeRollback)) {
+            try {
+                await backend.restoreBindings(snapshot, rollbackExpected);
+            }
+            catch (error) {
+                nativeRollbackError = error;
+            }
+        }
+        const rollbackErrors = [externalRollbackError, nativeRollbackError].filter((error) => error !== undefined);
+        if (rollbackErrors.length > 0) {
+            throw new AggregateError([primaryError, ...rollbackErrors], `Scheduler transaction failed and rollback was incomplete: ${errorMessage(primaryError)}`);
+        }
+        throw primaryError;
+    }
+}
+function schedulerRollbackExpectations(snapshot, operations) {
+    return Object.freeze(snapshot.nativeIds.map((nativeId) => {
+        const prior = snapshot.artifacts.find((artifact) => schedulerNativeArtifactKey(artifact.nativeId) === schedulerNativeArtifactKey(nativeId));
+        const allowed = [];
+        if (prior) {
+            if (prior.fingerprint === undefined) {
+                throw new ConfigError(`Scheduler backend snapshot for ${JSON.stringify(nativeId)} has no exact fingerprint.`, "INVALID_CONFIG_FILE");
+            }
+            allowed.push(Object.freeze({
+                state: "present",
+                ...(prior.bindingId !== undefined ? { bindingId: prior.bindingId } : {}),
+                ...(prior.invocation !== undefined ? { invocation: Object.freeze([...prior.invocation]) } : {}),
+                fingerprint: prior.fingerprint,
+            }));
+        }
+        else {
+            allowed.push(Object.freeze({ state: "absent" }));
+        }
+        const matchingOperations = operations.filter((candidate) => {
+            const operationNativeId = candidate.kind === "remove" ? candidate.nativeId : schedulerBindingNativeId(candidate.binding);
+            return schedulerNativeArtifactKey(operationNativeId) === schedulerNativeArtifactKey(nativeId);
+        });
+        for (const operation of matchingOperations) {
+            if (operation.kind === "remove") {
+                if (!allowed.some((state) => state.state === "absent")) {
+                    allowed.push(Object.freeze({ state: "absent" }));
+                }
+                continue;
+            }
+            if (operation.resultFingerprint === undefined) {
+                throw new ConfigError(`Scheduler backend cannot freeze the post-mutation fingerprint for ${JSON.stringify(nativeId)}.`, "INVALID_CONFIG_FILE");
+            }
+            allowed.push(Object.freeze({
+                state: "present",
+                bindingId: operation.binding.id,
+                invocation: Object.freeze([...operation.binding.invocation]),
+                fingerprint: operation.resultFingerprint,
+            }));
+        }
+        return Object.freeze({ nativeId, allowed: Object.freeze(allowed) });
+    }));
+}
+function assertSchedulerTransactionSnapshot(snapshot, nativeIds, initialExpectations) {
+    if (!snapshot ||
+        !Array.isArray(snapshot.nativeIds) ||
+        !Array.isArray(snapshot.artifacts) ||
+        nativeIds.some((nativeId) => !snapshot.nativeIds.includes(nativeId))) {
+        throw new ConfigError("Scheduler backend returned an incomplete transaction snapshot.", "INVALID_CONFIG_FILE");
+    }
+    const snapshotKeys = snapshot.nativeIds.map(schedulerNativeArtifactKey);
+    const requestedKeys = nativeIds.map(schedulerNativeArtifactKey);
+    if (snapshotKeys.length !== requestedKeys.length ||
+        new Set(snapshotKeys).size !== snapshotKeys.length ||
+        snapshotKeys.some((key) => !requestedKeys.includes(key))) {
+        throw new ConfigError("Scheduler backend returned an inexact normalized transaction snapshot set.", "INVALID_CONFIG_FILE");
+    }
+    for (const expected of initialExpectations) {
+        const artifact = assertSchedulerNativeArtifactCardinality(snapshot.artifacts, expected.nativeId, expected.state === "absent" ? 0 : 1);
+        assertSchedulerMutationArtifact(artifact, expected);
+    }
+}
+async function prepareTaskAddSchedulerTransaction(input) {
+    if (!input.sched.inspectBindings) {
+        throw new ConfigError(`Scheduler backend "${input.sched.name}" cannot provide one coherent inspection for transactional add.`, "INVALID_CONFIG_FILE");
+    }
+    if (!input.sched.snapshotBindings || !input.sched.restoreBindings || !input.sched.expectedSignature) {
+        throw new ConfigError(`Scheduler backend "${input.sched.name}" cannot provide exact snapshot, restore, and signature contracts for transactional add.`, "INVALID_CONFIG_FILE");
+    }
+    const inspection = await input.sched.inspectBindings({ rebind: input.rebind });
+    const installedEntries = [...inspection.installed];
+    const nativeArtifacts = [...inspection.artifacts];
+    const seenNativeKeys = new Set();
+    for (const artifact of nativeArtifacts) {
+        const key = schedulerNativeArtifactKey(artifact.nativeId);
+        if (seenNativeKeys.has(key)) {
+            throw new UsageError(`Scheduler inspection has duplicate normalized native artifact ${JSON.stringify(artifact.nativeId)}.`, "RESOURCE_ALREADY_EXISTS");
+        }
+        seenNativeKeys.add(key);
+    }
+    for (const binding of input.taskBindings) {
+        assertNoForeignSchedule(installedEntries, binding.id, input.ownerTarget);
+    }
+    const taskEntries = installedEntries.filter((entry) => installedEntryRunsTask(entry, input.id));
+    const foreignTaskEntry = taskEntries.find((entry) => !sameBundle(entry.target, input.ownerTarget));
+    if (foreignTaskEntry) {
+        throw new UsageError(foreignScheduleMessage(input.id, foreignTaskEntry.target), "RESOURCE_ALREADY_EXISTS");
+    }
+    assertSchedulerNativeArtifactOwnership(input.taskBindings, nativeArtifacts);
+    const primary = input.taskBindings[0];
+    if (!primary)
+        throw new Error("invariant: scheduler transaction has no desired binding");
+    const installedEntry = installedEntries.find((entry) => entry.id === primary.id) ?? taskEntries[0];
+    const preparedRuntime = installedEntry && !input.rebind
+        ? {
+            options: {
+                ...input.installOpts,
+                binding: Object.freeze([...installedEntry.binding]),
+                contextPath: installedEntry.contextPath,
+            },
+        }
+        : prepareSchedulerSyncRuntime(input.installOpts, input.deps, input.rebind, `create scheduler entry for task "${input.id}"`, []);
+    const runtimeOpts = preparedRuntime.options;
+    const removals = taskEntries.map((entry) => {
+        const invocation = entry.invocation;
+        if (!invocation) {
+            throw new UsageError(`Installed scheduler binding ${JSON.stringify(entry.id)} has no exact parsed owner; refusing replacement.`, "RESOURCE_ALREADY_EXISTS");
+        }
+        const nativeId = entry.nativeId ?? schedulerNativeBindingId(entry.id);
+        const artifact = assertSchedulerNativeArtifactCardinality(nativeArtifacts, nativeId, 1);
+        if (!artifact?.fingerprint || artifact.bindingId !== entry.id) {
+            throw new UsageError(`Installed scheduler binding ${JSON.stringify(entry.id)} has no exact coherent fingerprint.`, "RESOURCE_ALREADY_EXISTS");
+        }
+        const logicalSource = primary.logicalSource;
+        const ordinal = schedulerBindingOrdinal(entry.id, logicalSource, invocation);
+        if (ordinal === undefined) {
+            throw new UsageError(`Installed scheduler binding ${JSON.stringify(entry.id)} has no exact schedule ordinal; refusing replacement.`, "RESOURCE_ALREADY_EXISTS");
+        }
+        return Object.freeze({
+            kind: "remove",
+            id: entry.id,
+            nativeId,
+            expected: Object.freeze({
+                bindingId: entry.id,
+                nativeId,
+                logicalSource,
+                ordinal,
+                invocation: Object.freeze([...invocation]),
+                fingerprint: artifact.fingerprint,
+            }),
+        });
+    });
+    const installs = input.taskBindings.map((binding) => {
+        const nativeId = schedulerBindingNativeId(binding);
+        const resultFingerprint = input.sched.expectedSignature(binding, runtimeOpts);
+        if (!resultFingerprint) {
+            throw new ConfigError(`Scheduler backend "${input.sched.name}" cannot freeze the post-install fingerprint for ${JSON.stringify(binding.id)}.`, "INVALID_CONFIG_FILE");
+        }
+        return Object.freeze({
+            kind: "install",
+            binding,
+            expected: Object.freeze({
+                state: "absent",
+                bindingId: binding.id,
+                nativeId,
+                logicalSource: binding.logicalSource,
+                ordinal: binding.ordinal,
+                invocation: binding.invocation,
+            }),
+            resultFingerprint,
+            ...(runtimeOpts ? { options: runtimeOpts } : {}),
+        });
+    });
+    const initialByKey = new Map();
+    for (const removal of removals) {
+        if (removal.kind !== "remove")
+            continue;
+        initialByKey.set(schedulerNativeArtifactKey(removal.nativeId), Object.freeze({ ...removal.expected, state: "present" }));
+    }
+    for (const install of installs) {
+        if (install.kind === "remove")
+            continue;
+        const key = schedulerNativeArtifactKey(schedulerBindingNativeId(install.binding));
+        if (!initialByKey.has(key))
+            initialByKey.set(key, install.expected);
+    }
+    return Object.freeze({
+        runtimeOpts,
+        ...(preparedRuntime.publish ? { publishRuntime: preparedRuntime.publish } : {}),
+        operations: Object.freeze([...removals, ...installs]),
+        initialExpectations: Object.freeze([...initialByKey.values()]),
+        publishOperationIndex: removals.length,
+    });
+}
+function prepareSchedulerSyncRuntime(base, deps, explicitRebind, operation, warnings) {
     if (deps.backend && !deps.schedulerRuntime)
-        return base;
-    const runtime = deps.schedulerRuntime?.() ?? prepareSchedulerRuntime(explicitRebind, operation);
-    // --rebind bypasses the eligibility refusal in prepareSchedulerRuntime; warn once
-    // per sync run rather than silently writing a mutable/unproven binary into cron.
-    if (explicitRebind && runtime.eligible === false && warnings.length === 0) {
-        warnings.push(`--rebind bound scheduled tasks to an ineligible ${runtime.kind ?? "unknown"} invocation (${runtime.binding.join(" ")}); scheduled runs will invoke a mutable, unproven binary. Install akm via \`npm install --global akm-cli\` or a standalone release, then re-run \`akm task sync --rebind\`.`);
+        return base ? { options: base } : {};
+    if (deps.schedulerRuntime) {
+        const runtime = deps.schedulerRuntime();
+        warnIneligibleRebind(runtime, explicitRebind, warnings);
+        return { options: { ...base, binding: runtime.binding, contextPath: runtime.contextPath } };
     }
-    return { ...base, binding: runtime.binding, contextPath: runtime.contextPath };
+    const invocation = resolveAndValidateSchedulerInvocation(explicitRebind, operation);
+    warnIneligibleRebind(invocation, explicitRebind, warnings);
+    const descriptor = schedulerContextDescriptor();
+    const contextPath = schedulerContextPath(descriptor);
+    return {
+        options: { ...base, binding: invocation.binding, contextPath },
+        publish: () => {
+            const written = writeSchedulerContextDescriptor(descriptor);
+            if (written !== contextPath) {
+                throw new ConfigError("Scheduler context descriptor path changed after preflight.", "INVALID_CONFIG_FILE");
+            }
+        },
+    };
+}
+function resolveAndValidateSchedulerInvocation(explicitRebind, operation) {
+    const invocation = resolveAkmInvocation();
+    if (!invocation.eligible && !explicitRebind) {
+        throw new UsageError(`Refusing to ${operation} from an ineligible ${invocation.kind ?? "unknown"} invocation (${invocation.argv.join(" ")}).`, "INVALID_FLAG_VALUE", "npm-global ownership could not be verified. Run `npm install --global akm-cli` and use that launcher, use a standalone installation, or explicitly repeat the operation with --rebind.");
+    }
+    return { binding: invocation.argv, contextPath: "", eligible: invocation.eligible, kind: invocation.kind };
+}
+function warnIneligibleRebind(runtime, explicitRebind, warnings) {
+    if (!explicitRebind || runtime.eligible !== false || warnings.length > 0)
+        return;
+    warnings.push(`--rebind bound scheduled tasks to an ineligible ${runtime.kind ?? "unknown"} invocation (${runtime.binding.join(" ")}); scheduled runs will invoke a mutable, unproven binary. Install akm via \`npm install --global akm-cli\` or a standalone release, then re-run \`akm task sync --rebind\`.`);
 }
 export function prepareSchedulerRuntime(explicitRebind, operation, deps = {}) {
     const invocation = (deps.resolveInvocation ?? resolveAkmInvocation)();
@@ -476,7 +703,7 @@ export function prepareSchedulerRuntime(explicitRebind, operation, deps = {}) {
 function groupInstalledBindings(entries, invocation) {
     const groups = new Map();
     for (const entry of entries) {
-        const argv = entry.binding;
+        const argv = [...entry.binding];
         const status = inspectInstalledBinding(entry, invocation);
         const key = JSON.stringify([argv, entry.contextPath, status]);
         const existing = groups.get(key);
@@ -539,10 +766,119 @@ function hasGitAncestor(file) {
 function taskAssetRef(id) {
     return { type: "task", name: id };
 }
-async function restoreTaskSourceBytes(writeAsset, source, config, ref, filePath, yaml) {
-    await writeAsset(source, config, ref, yaml);
-    // The normal write path adds a trailing newline; rollback restores the raw snapshot exactly.
-    fs.writeFileSync(filePath, yaml, "utf8");
+function captureTaskSourceExpectation(filePathInput, rootInput) {
+    const filePath = path.resolve(filePathInput);
+    const root = path.resolve(rootInput);
+    const lexicalRelative = path.relative(root, filePath);
+    if (lexicalRelative === "" || lexicalRelative.startsWith("..") || path.isAbsolute(lexicalRelative)) {
+        throw new UsageError(`${filePathInput} resolves outside the task source root.`, "PATH_ESCAPE_VIOLATION");
+    }
+    const rootRealPath = fs.realpathSync(root);
+    const rootStat = fs.statSync(rootRealPath, { bigint: true });
+    if (!rootStat.isDirectory()) {
+        throw new UsageError(`${root} is not a task source directory.`, "INVALID_FLAG_VALUE");
+    }
+    const common = {
+        filePath,
+        rootRealPath,
+        rootPhysicalIdentity: rootStat.ino === 0n ? `path:${rootRealPath}` : `inode:${rootStat.dev}:${rootStat.ino}`,
+        rootMtimeNs: String(rootStat.mtimeNs),
+        rootCtimeNs: String(rootStat.ctimeNs),
+    };
+    let descriptor;
+    try {
+        const noFollow = "O_NOFOLLOW" in fs.constants ? fs.constants.O_NOFOLLOW : 0;
+        descriptor = fs.openSync(filePath, fs.constants.O_RDONLY | noFollow);
+        const before = fs.fstatSync(descriptor, { bigint: true });
+        if (!before.isFile()) {
+            throw new UsageError(`${filePath} is not a regular task source.`, "INVALID_FLAG_VALUE");
+        }
+        if (before.size > BigInt(TASK_V3_MAX_SOURCE_BYTES)) {
+            throw new UsageError(`${filePath} exceeds the 1 MiB (${TASK_V3_MAX_SOURCE_BYTES}-byte) task source limit.`, "INVALID_FLAG_VALUE");
+        }
+        const bytes = fs.readFileSync(descriptor);
+        const after = fs.fstatSync(descriptor, { bigint: true });
+        if (!sameTaskSourceStat(before, after) || BigInt(bytes.byteLength) !== before.size) {
+            throw new UsageError(`${filePath} changed while its guarded bytes were read.`, "RESOURCE_ALREADY_EXISTS");
+        }
+        const realPath = fs.realpathSync(filePath);
+        const physicalRelative = path.relative(rootRealPath, realPath);
+        if (physicalRelative === "" || physicalRelative.startsWith("..") || path.isAbsolute(physicalRelative)) {
+            throw new UsageError(`${filePath} resolves outside the task source root.`, "PATH_ESCAPE_VIOLATION");
+        }
+        let content;
+        try {
+            content = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+        }
+        catch {
+            throw new UsageError(`${filePath} contains invalid UTF-8 bytes.`, "INVALID_FLAG_VALUE");
+        }
+        return Object.freeze({
+            state: "present",
+            ...common,
+            realPath,
+            physicalIdentity: before.ino === 0n ? `path:${realPath}` : `inode:${before.dev}:${before.ino}`,
+            size: bytes.byteLength,
+            mtimeNs: String(before.mtimeNs),
+            ctimeNs: String(before.ctimeNs),
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+            bytesBase64: bytes.toString("base64"),
+            content,
+        });
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT") {
+            return Object.freeze({ state: "absent", ...common });
+        }
+        if (cause instanceof UsageError)
+            throw cause;
+        if (cause.code === "ELOOP") {
+            throw new UsageError(`${filePath} must not be a symbolic task source.`, "RESOURCE_ALREADY_EXISTS");
+        }
+        throw new UsageError(`${filePath} could not be guarded as a contained regular task source: ${errorMessage(cause)}`, "PATH_ESCAPE_VIOLATION");
+    }
+    finally {
+        if (descriptor !== undefined)
+            fs.closeSync(descriptor);
+    }
+}
+function assertTaskSourceExpectation(expected) {
+    const actual = captureTaskSourceExpectation(expected.filePath, expected.rootRealPath);
+    if (!sameTaskSourceExpectation(actual, expected)) {
+        throw new UsageError(`Task source ${JSON.stringify(expected.filePath)} changed after transaction planning.`, "RESOURCE_ALREADY_EXISTS");
+    }
+}
+function sameTaskSourceExpectation(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function assertTaskSourceRestored(expected) {
+    const actual = captureTaskSourceExpectation(expected.filePath, expected.rootRealPath);
+    const restored = actual.state === expected.state &&
+        actual.rootPhysicalIdentity === expected.rootPhysicalIdentity &&
+        (actual.state === "absent" ||
+            (expected.state === "present" && actual.sha256 === expected.sha256 && actual.content === expected.content));
+    if (!restored) {
+        throw new UsageError(`Task source ${JSON.stringify(expected.filePath)} could not be restored without replacing a concurrent owner.`, "RESOURCE_ALREADY_EXISTS");
+    }
+}
+class TaskSourceRestoredBoundaryError extends Error {
+    cause;
+    constructor(cause) {
+        super(errorMessage(cause));
+        this.name = "TaskSourceRestoredBoundaryError";
+        this.cause = cause;
+    }
+}
+function sameTaskSourceStat(left, right) {
+    return (left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.mode === right.mode &&
+        left.size === right.size &&
+        left.mtimeNs === right.mtimeNs &&
+        left.ctimeNs === right.ctimeNs);
+}
+function hashTaskSource(source) {
+    return createHash("sha256").update(Buffer.from(source, "utf8")).digest("hex");
 }
 /**
  * Resolve the bundle a mutating/run task command targets. Returns the resolved
@@ -550,20 +886,66 @@ async function restoreTaskSourceBytes(writeAsset, source, config, ref, filePath,
  * in scheduled invocations. The primary bundle uses the target-less form.
  */
 function resolveTaskBundle(target, opts) {
-    const selected = resolveWriteTarget(loadConfig(), target, { requireWritable: opts.requireWritable });
+    const config = loadConfig();
+    const selected = resolveWriteTarget(config, target, { requireWritable: opts.requireWritable });
     const resolved = opts.requireWritable ? prepareWriteTargetForMutation(selected) : selected;
     const stashDir = resolved.source.path;
     const installTarget = isPrimaryStashPath(stashDir) ? undefined : (resolved.selector ?? resolved.source.name);
-    return { resolved, stashDir, installTarget };
+    return { resolved, config, stashDir, bundleName: resolved.source.name, installTarget };
+}
+function taskProjectionAssetResolver(config, bundleName, bundleRoot) {
+    return async ({ bundle, type, name }) => {
+        if (bundle === bundleName) {
+            return { file: await resolveAssetPath(bundleRoot, type, name), bundleRoot };
+        }
+        const target = resolveWriteTarget(config, bundle, { requireWritable: false });
+        return {
+            file: await resolveAssetPath(target.source.path, type, name),
+            bundleRoot: target.source.path,
+        };
+    };
+}
+function resolveTaskReadBundle(refBundle, flagBundle) {
+    if (refBundle && flagBundle && refBundle !== flagBundle) {
+        throw new UsageError(`Task ref selects bundle ${JSON.stringify(refBundle)}, but --bundle selects ${JSON.stringify(flagBundle)}.`, "INVALID_FLAG_VALUE");
+    }
+    const selector = flagBundle ?? refBundle;
+    const config = loadConfig();
+    let resolved;
+    if (!selector) {
+        resolved = resolveWorkingStashTarget(config, { requireWritable: false });
+    }
+    else {
+        const configured = resolveConfiguredSources(config).some((source) => source.name === selector);
+        const implicit = configured ? undefined : resolveImplicitScheduledBundleTarget(config, selector);
+        resolved = implicit ?? resolveWriteTarget(config, selector, { requireWritable: false });
+    }
+    if (refBundle && resolved.source.name !== refBundle) {
+        throw new UsageError(`Task ref bundle ${JSON.stringify(refBundle)} does not match the resolved source.`, "INVALID_FLAG_VALUE");
+    }
+    return resolved;
 }
 /**
- * Resolve the tasks/ directory a read/inspect command operates on. No
- * `--bundle` uses the primary stash; `--bundle X` resolves bundle X read-only.
+ * New scheduler bindings always carry a canonical `--bundle <owner>` token,
+ * including an env-selected working stash. That stash need not be persisted in
+ * config (CI, one-shot tools, and fresh installs commonly use only
+ * AKM_BUNDLE_DIR), so its scheduled child must accept precisely its derived
+ * owner name after the scheduler context restores the environment.
+ *
+ * This is intentionally narrower than an unknown-bundle fallback: a configured
+ * source always wins, and an unconfigured selector is accepted only when it is
+ * exactly the current env-selected working stash identity.
  */
-function resolveTaskInspectDir(target) {
-    if (target === undefined)
-        return resolveStashDir();
-    return resolveWriteTarget(loadConfig(), target, { requireWritable: false }).source.path;
+function resolveImplicitScheduledBundleTarget(config, selector) {
+    if (!process.env.AKM_BUNDLE_DIR?.trim())
+        return undefined;
+    try {
+        const working = resolveWorkingStashTarget(config, { requireWritable: false });
+        return working.source.name === selector ? working : undefined;
+    }
+    catch {
+        return undefined;
+    }
 }
 /** True when `candidate` resolves to the same directory as the primary stash. */
 function isPrimaryStashPath(candidate) {
@@ -580,10 +962,17 @@ function isPrimaryStashPath(candidate) {
 function sameBundle(a, b) {
     return (a ?? undefined) === (b ?? undefined);
 }
+function installedEntryRunsTask(entry, id) {
+    const invocation = entry.invocation;
+    return invocation?.[0] === "task" && invocation[1] === "run" && invocation[2] === id;
+}
 function foreignScheduleMessage(id, existingTarget) {
     const where = existingTarget === undefined ? "the default bundle" : `bundle "${existingTarget}"`;
     return `Task id "${id}" is already scheduled from ${where}; rename the task or disable the existing one first.`;
 }
+function errorMessage(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
 /**
  * Refuse to schedule an id already installed from a DIFFERENT bundle. Scheduler
  * ids are the bare task id (never namespaced), so a single id can be active from
@@ -595,42 +984,44 @@ function assertNoForeignSchedule(entries, id, installTarget) {
         throw new UsageError(foreignScheduleMessage(id, foreign.target), "RESOURCE_ALREADY_EXISTS");
 }
 function renderTaskYaml(input) {
-    const obj = { version: 2, schedule: input.schedule, enabled: input.enabled };
+    const obj = { version: 3 };
     if (input.workflow) {
-        obj.workflow = input.workflow;
-        if (input.params) {
-            obj.params = parseJsonObjectArg(input.params);
-        }
-        if (input.timeoutMs !== undefined)
-            obj.timeoutMs = input.timeoutMs;
+        obj.uses = input.workflow;
+        if (input.params)
+            obj.with = parseJsonObjectArg(input.params);
     }
     else if (input.prompt) {
-        obj.prompt = input.prompt;
-        if (input.engine)
-            obj.engine = input.engine;
-        if (input.model)
-            obj.model = input.model;
-        if (input.timeoutMs !== undefined)
-            obj.timeoutMs = input.timeoutMs;
+        obj.uses = "akm/command";
+        obj.with = { content: input.prompt };
     }
     else if (input.command !== undefined) {
-        // Emit a string when given a string, an array when given an array. The
-        // parser accepts both forms; preserving the caller's shape keeps the YAML
-        // ergonomic for humans editing the file later.
-        obj.command = input.command;
-        if (input.timeoutMs !== undefined)
-            obj.timeoutMs = input.timeoutMs;
+        if (Array.isArray(input.command)) {
+            throw new UsageError("Task v3 --command accepts one shell string; argv arrays require manual migration.", "INVALID_FLAG_VALUE");
+        }
+        obj.run = input.command;
     }
     if (input.name)
         obj.name = input.name;
-    if (input.description)
-        obj.description = input.description;
-    if (input.when_to_use)
-        obj.when_to_use = input.when_to_use;
-    if (input.tags && input.tags.length > 0)
-        obj.tags = input.tags;
+    obj.akm = {
+        schedule: input.schedule,
+        enabled: input.enabled,
+        ...(input.description !== undefined ? { description: input.description } : {}),
+        ...(input.when_to_use !== undefined ? { when_to_use: input.when_to_use } : {}),
+        ...(input.tags && input.tags.length > 0 ? { tags: input.tags } : {}),
+        ...(input.engine !== undefined ? { engine: input.engine } : {}),
+        ...(input.model !== undefined ? { model: input.model } : {}),
+        ...(input.timeoutMs !== undefined ? { timeout: input.timeoutMs } : {}),
+    };
     return yamlStringify(obj);
 }
+function assertInlineTaskPrompt(input) {
+    const value = input.trim();
+    const pathShaped = /^(?:\.{1,2}[\\/]|~[\\/]|[\\/]|[A-Za-z]:[\\/])/.test(value) ||
+        (!/\s/.test(value) && /[\\/]/.test(value) && path.extname(value) !== "");
+    if (!isFullRefInput(value) && !pathShaped)
+        return;
+    throw new UsageError("--prompt accepts inline text only; asset refs and file paths are not prompt content. Use --workflow or an authored command ref where appropriate.", "INVALID_FLAG_VALUE");
+}
 function parseJsonObjectArg(raw) {
     let parsed;
     try {
@@ -645,7 +1036,7 @@ function parseJsonObjectArg(raw) {
     return parsed;
 }
 /**
- * Toggle the `enabled:` value in a task YAML file in-place without a full
+ * Toggle the v3 `akm.enabled:` value in a task YAML file without a full
  * parse/render round-trip (which would reformat the file). Appends the key
  * if absent.
  *
@@ -653,40 +1044,68 @@ function parseJsonObjectArg(raw) {
  * case-sensitive matching (YAML keys are case-sensitive).
  */
 export function setEnabledInYaml(yaml, enabled) {
-    // Match: key prefix (group 1), value (group 2), optional trailing comment (group 3)
-    const pattern = /^(enabled:\s*)([^\s#\r\n][^\r\n]*?)(\s*(?:#[^\r\n]*))?$/m;
-    if (pattern.test(yaml)) {
-        return yaml.replace(pattern, `$1${enabled}$3`);
-    }
-    // Handle the case where enabled: has no value yet (bare key)
-    const simplePattern = /^(enabled:)\s*$/m;
-    if (simplePattern.test(yaml)) {
-        return yaml.replace(simplePattern, `$1 ${enabled}`);
+    const lines = yaml.replace(/\r\n/g, "\n").split("\n");
+    const akmLine = lines.findIndex((line) => /^akm:\s*(?:#.*)?$/.test(line));
+    if (akmLine < 0)
+        return `${yaml.trimEnd()}\nakm:\n  enabled: ${enabled}\n`;
+    let insertAt = akmLine + 1;
+    for (let index = akmLine + 1; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (line === undefined)
+            break;
+        if (line !== "" && !/^[ \t]/.test(line))
+            break;
+        insertAt = index + 1;
+        const match = line.match(/^([ \t]+enabled:\s*)([^\s#\r\n][^\r\n]*?)(\s*(?:#[^\r\n]*))?$/);
+        if (match) {
+            lines[index] = `${match[1]}${enabled}${match[3] ?? ""}`;
+            return `${lines.join("\n").trimEnd()}\n`;
+        }
+        const bare = line.match(/^([ \t]+enabled:)\s*$/);
+        if (bare) {
+            lines[index] = `${bare[1]} ${enabled}`;
+            return `${lines.join("\n").trimEnd()}\n`;
+        }
     }
-    return `${yaml.trimEnd()}\nenabled: ${enabled}\n`;
+    lines.splice(insertAt, 0, `  enabled: ${enabled}`);
+    return `${lines.join("\n").trimEnd()}\n`;
 }
 // Re-exported so tests can verify the validator path directly.
 // Re-export error classes consumed by callers that want to instanceof-check.
 // Re-export this so the CLI can decide what process exit code to use after
 // `akm task run` completes.
-export { ConfigError, exitCodeForStatus, NotFoundError, parseTaskDocument, UsageError };
-// Accept a bare task id or the canonical `[bundle//]tasks/<id>` ref.
+export { ConfigError, exitCodeForStatus, NotFoundError, UsageError };
+// Parse only the bundle/ref syntax here. Whether a concept is a task is an
+// adapter-specific decision made after resolving the selected bundle.
 export function parseTaskRef(input) {
     const trimmed = input.trim();
-    // Canonical conceptId form: `[bundle//]tasks/<id>`. A `/` unambiguously marks
-    // it — a bare task id can never contain `/` (`validateTaskId` forbids it) — so
-    // route it through the shared parser, which strips any bundle prefix and maps
-    // the `tasks/` stash-subdir back to the `task` type in one place.
     if (trimmed.includes("/")) {
         try {
-            const parsed = parseRefInput(trimmed);
-            if (parsed.type === "task")
-                return { id: normaliseTaskId(parsed.name) };
+            const parsed = parseBundleRef(trimmed);
+            if (parsed.fragment !== undefined)
+                throw new Error("task refs do not accept fragments");
+            return {
+                id: normaliseTaskConceptId(parsed.conceptId),
+                ...(parsed.bundle ? { bundle: parsed.bundle } : {}),
+            };
         }
         catch {
             // fall through to the shared error below
         }
-        throw new UsageError(`Expected a task id or tasks/<id> ref, got "${input}".`, "INVALID_FLAG_VALUE");
+        throw new UsageError(`Expected a syntactically valid task concept id, got "${input}".`, "INVALID_FLAG_VALUE");
     }
     return { id: normaliseTaskId(trimmed) };
 }
+function taskIdForAdapter(parsedId, adapterId) {
+    if (adapterId === "akm-task")
+        return normaliseTaskConceptId(parsedId);
+    if (adapterId === "akm") {
+        if (!parsedId.includes("/"))
+            return normaliseTaskId(parsedId);
+        if (parsedId.startsWith("tasks/") && !parsedId.slice("tasks/".length).includes("/")) {
+            return normaliseTaskId(parsedId.slice("tasks/".length));
+        }
+        throw new UsageError(`The native akm adapter accepts only a bare task id or tasks/<id>, got "${parsedId}".`, "INVALID_FLAG_VALUE");
+    }
+    throw new UsageError(`Bundle adapter "${adapterId}" does not define task runtime identity.`, "INVALID_FLAG_VALUE");
+}