akm-cli 0.9.0-rc.1 → 0.9.0-rc.13

package/dist/commands/tasks/tasks.js

@@ -2,7 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
- * `akm tasks` — register, inspect, run, and remove scheduled task assets.
+ * `akm task` — register, inspect, run, and remove scheduled task assets.
  *
  * Each handler exported here is a pure function that performs the real work;
  * `src/cli.ts` wraps these in citty `defineCommand`s and shapes their return
@@ -11,22 +11,26 @@
 import fs from "node:fs";
 import path from "node:path";
 import { stringify as yamlStringify } from "yaml";
-import { resolveAssetPathFromName } from "../../core/asset/asset-spec.js";
+import { assetPathForName } from "../../core/asset/asset-placement.js";
+import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
 import { isWithin, resolveStashDir } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.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, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
-import { listAgentProfileNames } from "../../integrations/agent/index.js";
-import { resolveAssetPath } from "../../sources/resolve.js";
+import { commitWriteTargetBoundary, deleteAssetFromSource, prepareWriteTargetForMutation, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.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, readTaskHistory, runTask } from "../../tasks/runner.js";
-import { parseSchedule, SCHEDULE_SUPPORTED_SUBSET_HINT, translateToCron } from "../../tasks/schedule.js";
+import { exitCodeForStatus, INVALID_TASK_ATTEMPT_ID, readTaskHistory, recordTaskAttemptFailure, runTask, } from "../../tasks/runner.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 { resolveImproveProfile } from "../improve/improve-profiles.js";
-export async function akmTasksAdd(input) {
+import { isWorkflowEngineEnabled, WORKFLOW_ENGINE_CONFIG_KEY } from "../../workflows/exec/workflow-engine-gate.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 &&
@@ -36,19 +40,28 @@ export async function akmTasksAdd(input) {
     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");
     }
+    if (input.workflow && (input.engine !== undefined || input.model !== undefined || input.timeoutMs !== undefined)) {
+        throw new UsageError("Workflow tasks accept only --params; engine, model, and timeout 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");
+    }
     // Validate the schedule for the active backend before writing anything.
-    const backend = backendNameForPlatform();
+    // WI-9.10e: the injected backend (tests) carries its own name, so derive it
+    // from `deps.backend` when present — retiring the `_setBackendsForTests` seam.
+    const backend = deps.backend?.name ?? backendNameForPlatform();
     parseSchedule(input.schedule, backend);
-    const target = resolveTaskWriteTarget();
-    const stashDir = target.source.path;
+    const bundle = resolveTaskBundle(input.target, { requireWritable: true });
+    const writeTarget = bundle.resolved;
+    const stashDir = bundle.stashDir;
+    const installOpts = bundle.installTarget !== undefined ? { target: bundle.installTarget } : undefined;
     const typeRoot = path.join(stashDir, "tasks");
-    fs.mkdirSync(typeRoot, { recursive: true });
-    const assetPath = resolveAssetPathFromName("task", typeRoot, id);
+    const assetPath = assetPathForName("task", typeRoot, id);
     if (!isWithin(assetPath, typeRoot)) {
         throw new UsageError(`Resolved task path escapes the stash: "${id}".`, "PATH_ESCAPE_VIOLATION");
     }
     if (fs.existsSync(assetPath) && !input.force) {
-        throw new UsageError(`Task "${id}" already exists. Pass --force to overwrite, or use \`akm tasks remove ${id}\` first.`, "RESOURCE_ALREADY_EXISTS");
+        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 yaml = renderTaskYaml({
         id,
@@ -56,7 +69,9 @@ export async function akmTasksAdd(input) {
         workflow: input.workflow,
         prompt: input.prompt,
         command: input.command,
-        profile: input.profile,
+        engine: input.engine,
+        model: input.model,
+        timeoutMs: input.timeoutMs,
         params: input.params,
         name: input.name,
         description: input.description,
@@ -67,231 +82,187 @@ export async function akmTasksAdd(input) {
     const task = parseTaskDocument({ yaml, filePath: assetPath, id });
     await validateTaskDocument(task, { backend, stashDir });
     const ref = taskAssetRef(id);
-    await writeAssetToSource(target.source, target.config, ref, yaml);
-    // Install in the OS scheduler. If install fails after the file was written,
-    // delete the file so the on-disk state never claims a task is registered
-    // when it isn't.
+    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 {
-        const sched = selectBackend();
-        await sched.install(task);
+        sourceRestoreArmed = true;
+        await writeAsset(writeTarget.source, writeTarget.config, ref, yaml);
+        await sched.install(task, runtimeOpts);
+        installSucceeded = true;
+        commitBoundary(writeTarget, `Update tasks/${id}`);
     }
     catch (err) {
-        try {
-            await deleteAssetFromSource(target.source, target.config, ref);
+        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;
+                }
+            }
+            catch (rollbackError) {
+                rollbackErrors.push(rollbackError);
+            }
         }
-        catch {
-            /* ignore */
+        if (installSucceeded && !wasInstalled) {
+            try {
+                await sched.uninstall(id);
+            }
+            catch (rollbackError) {
+                rollbackErrors.push(rollbackError);
+            }
+        }
+        else if (installSucceeded && previousTask) {
+            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);
+                }
+                catch (disableError) {
+                    rollbackErrors.push(disableError);
+                    try {
+                        await sched.uninstall(id);
+                    }
+                    catch (uninstallError) {
+                        rollbackErrors.push(uninstallError);
+                    }
+                }
+            }
+        }
+        else if (installSucceeded && wasInstalled) {
+            rollbackErrors.push(previousTaskError ?? new Error(`Prior task "${id}" could not be restored.`));
+        }
+        if (sourceRestored) {
+            try {
+                commitBoundary(writeTarget, `Restore tasks/${id}`);
+            }
+            catch (rollbackError) {
+                rollbackErrors.push(rollbackError);
+            }
+        }
+        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;
     }
-    commitWriteTargetBoundary(target, `Update task:${id}`);
     return {
         id,
-        ref: `task:${id}`,
+        ref: conceptIdFromTypeName("task", id),
         path: assetPath,
-        stashDir,
+        bundleDir: stashDir,
         schedule: task.schedule,
         enabled: task.enabled,
         backend,
         target: task.target,
     };
 }
-/**
- * Emit a single grouped stderr warning for legacy `.md` task files in the
- * tasks directory. 0.8.0 requires task definitions to be pure `.yml`; any
- * leftover `.md` files from 0.7.x would otherwise be silently skipped, which
- * makes scheduled tasks vanish without operator notice. We do NOT auto-migrate
- * — that is a separate workstream — but operators must see the affected files.
- *
- * `seen` is module-level so the warning is emitted at most once per process,
- * even when both `akm tasks list` and `akm tasks sync` are invoked in the same
- * akm run.
- */
-const warnedLegacyMdDirs = new Set();
-function warnLegacyMdTaskFiles(typeRoot) {
-    if (warnedLegacyMdDirs.has(typeRoot))
-        return;
-    let mdFiles;
+export async function akmTasksRun(id, options = {}) {
+    const startedAt = new Date();
+    let normalised;
     try {
-        mdFiles = fs.readdirSync(typeRoot).filter((f) => f.endsWith(".md"));
+        normalised = parseTaskRef(id).id;
     }
-    catch {
-        return;
-    }
-    if (mdFiles.length === 0)
-        return;
-    warnedLegacyMdDirs.add(typeRoot);
-    const affected = mdFiles.map((f) => `tasks/${f}`).join(", ");
-    process.stderr.write(`WARNING: ${mdFiles.length} task file(s) use the legacy .md format and were ignored.\n` +
-        `         AKM 0.8.0 requires tasks as pure .yml. See docs/migration/v0.7-to-v0.8.md#task-definition-files-mdfrontmatter--yml.\n` +
-        `         Affected: ${affected}\n`);
-}
-/**
- * Reset the legacy `.md` task warning de-duplication state. Test-only escape
- * hatch — production code should never call this.
- */
-export function _resetLegacyMdTaskWarningStateForTests() {
-    warnedLegacyMdDirs.clear();
-}
-export async function akmTasksList() {
-    const stashDir = resolveStashDir();
-    const typeRoot = path.join(stashDir, "tasks");
-    if (!fs.existsSync(typeRoot))
-        return { tasks: [] };
-    const entries = fs.readdirSync(typeRoot);
-    warnLegacyMdTaskFiles(typeRoot);
-    const files = entries.filter((f) => f.endsWith(".yml"));
-    const tasks = [];
-    for (const file of files) {
-        const id = file.slice(0, -4);
-        const filePath = path.join(typeRoot, file);
-        let task;
-        try {
-            task = parseTaskDocument({ yaml: fs.readFileSync(filePath, "utf8"), filePath, id });
-        }
-        catch {
-            continue; // skip malformed files; `akm tasks show <id>` will surface the error
-        }
-        tasks.push({
-            id: task.id,
-            ref: `task:${task.id}`,
-            path: filePath,
-            schedule: task.schedule,
-            enabled: task.enabled,
-            target: task.target,
-            name: task.name,
-            description: task.description,
-            when_to_use: task.when_to_use,
-            tags: task.tags,
+    catch (failure) {
+        recordTaskAttemptFailure({
+            taskId: INVALID_TASK_ATTEMPT_ID,
+            reason: "invalid_task_id",
+            failure,
+            startedAt,
         });
+        throw failure;
     }
-    return { tasks };
-}
-export async function akmTasksShow(id) {
-    const normalised = normaliseTaskId(id);
-    const stashDir = resolveStashDir();
-    const typeRoot = path.join(stashDir, "tasks");
-    if (fs.existsSync(typeRoot))
-        warnLegacyMdTaskFiles(typeRoot);
-    const filePath = await resolveAssetPath(stashDir, "task", normalised);
-    const task = parseTaskDocument({
-        yaml: fs.readFileSync(filePath, "utf8"),
-        filePath,
-        id: normalised,
-    });
-    const spec = parseSchedule(task.schedule, backendNameForPlatform());
-    return {
-        id: task.id,
-        ref: `task:${task.id}`,
-        path: filePath,
-        schedule: task.schedule,
-        cron: translateToCron(spec),
-        enabled: task.enabled,
-        target: task.target,
-        name: task.name,
-        description: task.description,
-        when_to_use: task.when_to_use,
-        tags: task.tags,
-    };
-}
-export async function akmTasksRemove(id) {
-    const normalised = normaliseTaskId(id);
-    const target = resolveTaskWriteTarget();
-    const stashDir = target.source.path;
-    const typeRoot = path.join(stashDir, "tasks");
-    if (fs.existsSync(typeRoot))
-        warnLegacyMdTaskFiles(typeRoot);
-    await resolveAssetPath(stashDir, "task", normalised);
-    const ref = taskAssetRef(normalised);
-    const sched = selectBackend();
-    let uninstallError;
-    let deleteError;
-    try {
-        await sched.uninstall(normalised);
-    }
-    catch (err) {
-        uninstallError = err;
-    }
+    let stashDir;
     try {
-        await deleteAssetFromSource(target.source, target.config, ref);
+        // 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 (err) {
-        deleteError = err;
-    }
-    if (uninstallError !== undefined)
-        throw uninstallError;
-    if (deleteError !== undefined)
-        throw deleteError;
-    commitWriteTargetBoundary(target, `Remove task:${normalised}`);
-    return { id: normalised, removed: true, backend: sched.name };
-}
-export async function akmTasksSetEnabled(id, enabled) {
-    const normalised = normaliseTaskId(id);
-    const target = resolveTaskWriteTarget();
-    const stashDir = target.source.path;
-    const typeRoot = path.join(stashDir, "tasks");
-    if (fs.existsSync(typeRoot))
-        warnLegacyMdTaskFiles(typeRoot);
-    const filePath = await resolveAssetPath(stashDir, "task", normalised);
-    const yaml = fs.readFileSync(filePath, "utf8");
-    const updated = setEnabledInYaml(yaml, enabled);
-    const ref = taskAssetRef(normalised);
-    await writeAssetToSource(target.source, target.config, ref, updated);
-    const sched = selectBackend();
-    try {
-        // Reinstall from the (just-updated) definition rather than only toggling
-        // the comment. A plain toggle leaves a stale schedule in place if the
-        // .yml's `schedule:` changed while the task was disabled — re-enabling
-        // would silently keep the old cron line. install() renders the block with
-        // both the current schedule and the new enabled state, and is idempotent.
-        const task = parseTaskDocument({ yaml: updated, filePath, id: normalised });
-        await sched.install(task);
-    }
-    catch (err) {
-        // Roll the file back so the YAML source-of-truth and the OS
-        // scheduler don't diverge silently when the backend call fails.
-        await writeAssetToSource(target.source, target.config, ref, yaml);
-        throw err;
+    catch (failure) {
+        recordTaskAttemptFailure({
+            taskId: normalised,
+            reason: "task_load_failed",
+            failure,
+            startedAt,
+        });
+        throw failure;
     }
-    commitWriteTargetBoundary(target, `Update task:${normalised}`);
-    return { id: normalised, enabled, backend: sched.name };
-}
-export async function akmTasksRun(id) {
-    const normalised = normaliseTaskId(id);
-    const stashDir = resolveStashDir();
-    const typeRoot = path.join(stashDir, "tasks");
-    if (fs.existsSync(typeRoot))
-        warnLegacyMdTaskFiles(typeRoot);
-    const result = await runTask(normalised);
+    const result = await runTask(normalised, { stashDir, scheduled: options.scheduled === true });
+    const exitCode = result.status === "failed" && result.target.kind === "command" && result.detail?.exitCode === 78
+        ? 78
+        : exitCodeForStatus(result.status);
     return {
         ok: result.status === "completed" || result.status === "disabled",
         result,
-        exitCode: exitCodeForStatus(result.status),
+        exitCode,
     };
 }
 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 stashDir = resolveStashDir();
-    const typeRoot = path.join(stashDir, "tasks");
-    if (fs.existsSync(typeRoot))
-        warnLegacyMdTaskFiles(typeRoot);
+    // History rows are keyed by task id in state.db, not per bundle.
     return { rows: readTaskHistory({ id, limit }) };
 }
 /**
- * Reconcile the on-disk task files with the OS scheduler.
+ * 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)
  *   • 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)
  *   • remove orphan scheduler entries that no longer have a backing file
+ *
+ * `--bundle <bundle>` scopes the reconciliation to that bundle: the file set is
+ * the bundle's `tasks/*.yml` and — crucially — the scheduler entries considered
+ * are ONLY those attributed to the same bundle (parsed from the installed
+ * `--bundle` token; absent ⇒ primary). This is the security boundary that keeps
+ * "registering a bundle never activates code": a plain (primary) sync never
+ * installs from, updates, or removes another bundle's entries, and sync never
+ * scans all bundles. Activation happens only through explicit `add --bundle`
+ * (or `sync --bundle` on a bundle whose task files are already present).
  */
-export async function akmTasksSync(deps = {}) {
-    const stashDir = resolveStashDir();
+export async function akmTasksSync(deps = {}, bundleTarget, options = {}) {
+    const stashDir = resolveTaskInspectDir(bundleTarget);
+    // Primary-bundle scheduler entries omit --bundle; other bundles carry it.
+    const syncTarget = bundleTarget !== undefined && !isPrimaryStashPath(stashDir) ? bundleTarget : undefined;
     const typeRoot = path.join(stashDir, "tasks");
-    if (fs.existsSync(typeRoot))
-        warnLegacyMdTaskFiles(typeRoot);
     const fileIds = fs.existsSync(typeRoot)
         ? fs
             .readdirSync(typeRoot)
@@ -299,34 +270,58 @@ export async function akmTasksSync(deps = {}) {
             .map((f) => f.slice(0, -4))
         : [];
     const sched = deps.backend ?? selectBackend();
-    const backend = backendNameForPlatform();
-    // Map id → installed signature so sync can detect schedule/enabled drift on
-    // tasks that already exist in the scheduler, not just presence/absence.
-    const present = new Map((await sched.list()).map((t) => [t.id, t.signature]));
+    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 = [];
+    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 });
-        }
-        catch (err) {
-            skipped.push({ id, reason: err instanceof Error ? err.message : String(err) });
-            continue;
-        }
-        try {
             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)) {
-            await sched.install(task);
-            installed.push(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) });
+            }
             continue;
         }
         // Already installed — reconcile against the current definition. Compare the
@@ -334,13 +329,15 @@ export async function akmTasksSync(deps = {}) {
         // 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 installedSig = present.get(id);
-        const expectedSig = sched.expectedSignature?.(task);
+        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);
+            await sched.install(task, runtimeOpts);
             updated.push(id);
         }
     }
@@ -351,39 +348,76 @@ export async function akmTasksSync(deps = {}) {
             removed.push(installedId);
         }
     }
-    return { installed, updated, removed, unchanged, skipped, backend: sched.name };
+    return {
+        installed,
+        updated,
+        removed,
+        unchanged,
+        skipped,
+        backend: sched.name,
+        ...(warnings.length > 0 ? { warnings } : {}),
+    };
 }
-export async function akmTasksDoctor() {
+export async function akmTasksDoctor(deps = {}) {
     const warnings = [];
-    let invocation = { argv: [], via: "unresolved" };
+    let invocation = {
+        argv: [],
+        via: "unresolved",
+    };
     try {
-        const r = resolveAkmInvocation();
-        invocation = { argv: r.argv, via: r.via };
+        const r = (deps.resolveInvocation ?? resolveAkmInvocation)();
+        invocation = { argv: r.argv, via: r.via, kind: r.kind, eligible: r.eligible };
     }
     catch (err) {
         warnings.push(err instanceof Error ? err.message : String(err));
     }
-    try {
-        const stashDir = resolveStashDir();
-        const typeRoot = path.join(stashDir, "tasks");
-        if (fs.existsSync(typeRoot))
-            warnLegacyMdTaskFiles(typeRoot);
+    const skipNativeInspection = process.env.BUN_TEST === "1" && !deps.backend;
+    const sched = deps.backend ?? (skipNativeInspection ? undefined : selectBackend());
+    const backend = sched?.name ?? backendNameForPlatform();
+    let installed = [];
+    if (skipNativeInspection) {
+        warnings.push("Native scheduler inspection is skipped inside the bun test harness.");
     }
-    catch {
-        // doctor must never fail on stash-resolution; the warning is best-effort
+    else {
+        try {
+            installed = await sched.list();
+        }
+        catch (error) {
+            warnings.push(`Unable to inspect installed ${backend} definitions: ${error instanceof Error ? error.message : String(error)}`);
+        }
     }
-    const backend = backendNameForPlatform();
+    const bindings = groupInstalledBindings(installed, invocation);
     const config = loadConfig();
-    // v2: prefer profiles.agent / defaults.agent; fall back to legacy agent.default
-    const defaultProfile = config.defaults?.agent;
-    const profiles = config.profiles?.agent ? Object.keys(config.profiles.agent) : listAgentProfileNames(config);
+    const defaultEngine = config.defaults?.engine;
+    const engines = Object.keys(config.engines ?? {});
     // §6.1: surface the effective triage settings for the default improve
-    // profile. The struct is a fixed shape, so this is a deliberate addition.
-    const improveProfileName = typeof config.defaults?.improve === "string" ? config.defaults.improve : "default";
-    const triage = resolveImproveProfile(config.defaults?.improve, config).processes?.triage;
+    // strategy. The struct is a fixed shape, so this is a deliberate addition.
+    const improveStrategyName = typeof config.defaults?.improveStrategy === "string" ? config.defaults.improveStrategy : "default";
+    // D8 — report the EFFECTIVE strategy, not the raw one. Resolving the raw
+    // strategy here would report `applyMode: "promote"` for a promote strategy
+    // under a review-first config, while the run actually uses "queue" — a doctor
+    // command lying about the thing it exists to diagnose.
+    const rawStrategy = resolveImproveStrategy(config.defaults?.improveStrategy, config).config;
+    const { config: effectiveStrategy, gated } = applyAutonomyGate(rawStrategy, config);
+    const autonomyEnabled = isImproveAutonomyEnabled(config);
+    // Memory cleanup has no strategy flag to downgrade, so add that direct lane
+    // to the strategy-derived gate report.
+    const allGated = autonomyEnabled ? [] : [...gated, ...describeGatedLanes(configuredDirectAutonomyLanes())];
+    const improveAutonomy = {
+        enabled: autonomyEnabled,
+        configKey: IMPROVE_AUTONOMY_CONFIG_KEY,
+        gatedLanes: allGated.map((entry) => ({ lane: entry.lane, reason: entry.reason })),
+    };
+    // Q-05 — report the workflow engine gate's state alongside the autonomy
+    // gate: both are `experimental.*` opt-ins doctor exists to surface.
+    const workflowEngine = {
+        enabled: isWorkflowEngineEnabled(config),
+        configKey: WORKFLOW_ENGINE_CONFIG_KEY,
+    };
+    const triage = effectiveStrategy.processes?.triage;
     const improveTriage = triage
         ? {
-            defaultProfile: improveProfileName,
+            defaultStrategy: improveStrategyName,
             enabled: triage.enabled === true,
             applyMode: triage.applyMode ?? "queue",
             policy: triage.policy ?? "personal-stash",
@@ -392,36 +426,172 @@ export async function akmTasksDoctor() {
     return {
         backend,
         akm: invocation,
+        caller: invocation,
+        bindings,
+        ...(bindings.some((binding) => !binding.status.includes("ok"))
+            ? { remediation: "akm task sync --rebind" }
+            : {}),
         logDir: getTaskLogDir(),
         historyDir: getTaskHistoryDir(),
-        agent: { defaultProfile, available: profiles },
+        engine: { defaultEngine, available: engines },
         scheduleSubset: SCHEDULE_SUPPORTED_SUBSET_HINT,
         warnings,
+        improveAutonomy,
+        workflowEngine,
         ...(improveTriage ? { improveTriage } : {}),
     };
 }
 // ── helpers ─────────────────────────────────────────────────────────────────
-const VALID_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-function normaliseTaskId(raw) {
-    // Accept both .yml and .md suffixes from users so muscle memory from the
-    // pre-0.8.0 markdown task format doesn't produce a confusing "task not found".
-    const id = raw.trim().replace(/\.(yml|md)$/, "");
-    if (!id) {
-        throw new UsageError("Task id must be non-empty.", "MISSING_REQUIRED_ARGUMENT");
-    }
-    if (!VALID_ID_RE.test(id)) {
-        throw new UsageError(`Task id "${id}" is invalid. Use letters, digits, dots, underscores, and dashes only.`, "INVALID_FLAG_VALUE");
-    }
-    return id;
+function schedulerInstallOptions(base, installed, deps, explicitRebind, operation, warnings = []) {
+    if (installed && !explicitRebind) {
+        return {
+            ...base,
+            binding: installed.binding,
+            contextPath: installed.contextPath,
+        };
+    }
+    // Injected backends can own their default runtime unless a resolver is supplied.
+    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, binding: runtime.binding, contextPath: runtime.contextPath };
+}
+export function prepareSchedulerRuntime(explicitRebind, operation, deps = {}) {
+    const invocation = (deps.resolveInvocation ?? 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.");
+    }
+    const contextPath = (deps.writeDescriptor ?? writeSchedulerContextDescriptor)(schedulerContextDescriptor());
+    return { binding: invocation.argv, contextPath, eligible: invocation.eligible, kind: invocation.kind };
+}
+function groupInstalledBindings(entries, invocation) {
+    const groups = new Map();
+    for (const entry of entries) {
+        const argv = entry.binding;
+        const status = inspectInstalledBinding(entry, invocation);
+        const key = JSON.stringify([argv, entry.contextPath, status]);
+        const existing = groups.get(key);
+        if (existing) {
+            existing.taskIds.push(entry.id);
+            continue;
+        }
+        groups.set(key, {
+            argv,
+            contextPath: entry.contextPath,
+            taskIds: [entry.id],
+            status,
+        });
+    }
+    return [...groups.values()].map((group) => ({ ...group, taskIds: group.taskIds.sort() }));
+}
+function inspectInstalledBinding(entry, invocation) {
+    const status = [];
+    const binding = entry.binding;
+    if (!(invocation.eligible === true && sameArgv(binding, invocation.argv)) &&
+        binding.some((part) => /(?:^|[\\/])src[\\/]cli\.ts$|(?:^|[\\/])dist[\\/](?:cli\.js|cli-node\.mjs)$/i.test(part) ||
+            (path.isAbsolute(part) && hasGitAncestor(part)))) {
+        status.push("checkout");
+    }
+    if (binding.some((part) => part === "akm" || part === "bun" || part === "node"))
+        status.push("path-selected");
+    try {
+        validateSchedulerContextDescriptor(entry.contextPath);
+    }
+    catch {
+        status.push("invalid-context");
+    }
+    const absolutePaths = [...binding.filter((part) => path.isAbsolute(part)), entry.contextPath];
+    if (absolutePaths.some((part) => !fs.existsSync(part)))
+        status.push("missing-path");
+    if (status.length === 0)
+        status.push("ok");
+    return status;
+}
+function sameArgv(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function hasGitAncestor(file) {
+    let current;
+    try {
+        current = path.dirname(fs.realpathSync(file));
+    }
+    catch {
+        return false;
+    }
+    for (;;) {
+        if (fs.existsSync(path.join(current, ".git")))
+            return true;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return false;
+        current = parent;
+    }
 }
 function taskAssetRef(id) {
     return { type: "task", name: id };
 }
-function resolveTaskWriteTarget() {
-    return resolveWriteTarget(loadConfig());
+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");
+}
+/**
+ * Resolve the bundle a mutating/run task command targets. Returns the resolved
+ * write/read target, its stash path, and the `--bundle <bundle>` token to embed
+ * in scheduled invocations. The primary bundle uses the target-less form.
+ */
+function resolveTaskBundle(target, opts) {
+    const selected = resolveWriteTarget(loadConfig(), 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 };
+}
+/**
+ * Resolve the tasks/ directory a read/inspect command operates on. No
+ * `--bundle` uses the primary stash; `--bundle X` resolves bundle X read-only.
+ */
+function resolveTaskInspectDir(target) {
+    if (target === undefined)
+        return resolveStashDir();
+    return resolveWriteTarget(loadConfig(), target, { requireWritable: false }).source.path;
+}
+/** True when `candidate` resolves to the same directory as the primary stash. */
+function isPrimaryStashPath(candidate) {
+    let primary;
+    try {
+        primary = path.resolve(resolveStashDir());
+    }
+    catch {
+        return false;
+    }
+    return path.resolve(candidate) === primary;
+}
+/** Two bundle attributions match when both are the primary (undefined) or equal names. */
+function sameBundle(a, b) {
+    return (a ?? undefined) === (b ?? undefined);
+}
+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.`;
+}
+/**
+ * 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
+ * only one bundle at a time — a collision is a hard error, not an auto-rename.
+ */
+function assertNoForeignSchedule(entries, id, installTarget) {
+    const foreign = entries.find((entry) => entry.id === id && !sameBundle(entry.target, installTarget));
+    if (foreign)
+        throw new UsageError(foreignScheduleMessage(id, foreign.target), "RESOURCE_ALREADY_EXISTS");
 }
 function renderTaskYaml(input) {
-    const obj = { schedule: input.schedule };
+    const obj = { version: 2, schedule: input.schedule, enabled: input.enabled };
     if (input.workflow) {
         obj.workflow = input.workflow;
         if (input.params) {
@@ -430,16 +600,21 @@ function renderTaskYaml(input) {
     }
     else if (input.prompt) {
         obj.prompt = input.prompt;
-        if (input.profile)
-            obj.profile = input.profile;
+        if (input.engine)
+            obj.engine = input.engine;
+        if (input.model)
+            obj.model = input.model;
+        if (input.timeoutMs !== undefined)
+            obj.timeoutMs = input.timeoutMs;
     }
     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;
     }
-    obj.enabled = input.enabled;
     if (input.name)
         obj.name = input.name;
     if (input.description)
@@ -487,17 +662,25 @@ export function setEnabledInYaml(yaml, enabled) {
 // 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 tasks run` completes.
+// `akm task run` completes.
 export { ConfigError, exitCodeForStatus, NotFoundError, parseTaskDocument, UsageError };
-// Helper: ensure the asset-spec resolver agrees with our id rules. If the
-// user passes a ref, we accept the bare name part too.
+// Accept a bare task id or the canonical `[bundle//]tasks/<id>` ref.
 export function parseTaskRef(input) {
-    if (input.includes(":")) {
-        const [typePart, ...rest] = input.split(":");
-        if (typePart !== "task" || rest.length === 0) {
-            throw new UsageError(`Expected a task id or task:<id> ref, got "${input}".`, "INVALID_FLAG_VALUE");
+    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) };
+        }
+        catch {
+            // fall through to the shared error below
         }
-        return { id: normaliseTaskId(rest.join(":")) };
+        throw new UsageError(`Expected a task id or tasks/<id> ref, got "${input}".`, "INVALID_FLAG_VALUE");
     }
-    return { id: normaliseTaskId(input) };
+    return { id: normaliseTaskId(trimmed) };
 }