akm-cli 0.9.0-rc.9 → 0.9.1-beta.1

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
@@ -15,18 +15,20 @@ 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 { resolveAssetPath } from "../../sources/resolve.js";
+import { commitWriteTargetBoundary, deleteAssetFromSource, prepareWriteTargetForMutation, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
+import { withEngineFallback } from "../../integrations/agent/engine-fallback.js";
 import { backendNameForPlatform, selectBackend } from "../../tasks/backends/index.js";
-import { findBareAkmExecutableIndex } from "../../tasks/command-executable.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 { parseSchedule, SCHEDULE_SUPPORTED_SUBSET_HINT, translateToCron } from "../../tasks/schedule.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 { 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);
@@ -38,8 +40,12 @@ export async function akmTasksAdd(input, deps = {}) {
     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");
+    // `--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");
@@ -49,15 +55,22 @@ export async function akmTasksAdd(input, deps = {}) {
     // 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");
     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");
+    // 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) {
+        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,
@@ -77,9 +90,6 @@ export async function akmTasksAdd(input, deps = {}) {
     });
     const task = parseTaskDocument({ yaml, filePath: assetPath, id });
     await validateTaskDocument(task, { backend, stashDir });
-    const obsoleteReason = obsoleteBackupTaskReason(task);
-    if (obsoleteReason)
-        throw new UsageError(obsoleteReason, "INVALID_FLAG_VALUE");
     const ref = taskAssetRef(id);
     const previousYaml = fs.existsSync(assetPath) ? fs.readFileSync(assetPath, "utf8") : undefined;
     let previousTask;
@@ -96,15 +106,19 @@ export async function akmTasksAdd(input, deps = {}) {
     const writeAsset = deps.writeAsset ?? writeAssetToSource;
     const deleteAsset = deps.deleteAsset ?? deleteAssetFromSource;
     const commitBoundary = deps.commitBoundary ?? commitWriteTargetBoundary;
-    const wasInstalled = previousYaml !== undefined && (await sched.list()).some((entry) => entry.id === id);
+    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;
-        await writeAsset(target.source, target.config, ref, yaml);
-        await sched.install(task);
+        await writeAsset(writeTarget.source, writeTarget.config, ref, yaml);
+        await sched.install(task, runtimeOpts);
         installSucceeded = true;
-        commitBoundary(target, `Update tasks/${id}`);
+        commitBoundary(writeTarget, `Update tasks/${id}`);
     }
     catch (err) {
         const rollbackErrors = [];
@@ -113,12 +127,12 @@ export async function akmTasksAdd(input, deps = {}) {
             try {
                 if (previousYaml === undefined) {
                     if (fs.existsSync(assetPath)) {
-                        await deleteAsset(target.source, target.config, ref);
+                        await deleteAsset(writeTarget.source, writeTarget.config, ref);
                         sourceRestored = true;
                     }
                 }
                 else {
-                    await restoreTaskSourceBytes(writeAsset, target.source, target.config, ref, assetPath, previousYaml);
+                    await restoreTaskSourceBytes(writeAsset, writeTarget.source, writeTarget.config, ref, assetPath, previousYaml);
                     sourceRestored = true;
                 }
             }
@@ -136,7 +150,7 @@ export async function akmTasksAdd(input, deps = {}) {
         }
         else if (installSucceeded && previousTask) {
             try {
-                await sched.install(previousTask);
+                await sched.install(previousTask, runtimeOpts);
             }
             catch (rollbackError) {
                 rollbackErrors.push(rollbackError);
@@ -162,7 +176,7 @@ export async function akmTasksAdd(input, deps = {}) {
         }
         if (sourceRestored) {
             try {
-                commitBoundary(target, `Restore tasks/${id}`);
+                commitBoundary(writeTarget, `Restore tasks/${id}`);
             }
             catch (rollbackError) {
                 rollbackErrors.push(rollbackError);
@@ -178,252 +192,13 @@ export async function akmTasksAdd(input, deps = {}) {
         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;
-    try {
-        mdFiles = fs.readdirSync(typeRoot).filter((f) => f.endsWith(".md"));
-    }
-    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: [], stale: [] };
-    const entries = fs.readdirSync(typeRoot);
-    warnLegacyMdTaskFiles(typeRoot);
-    const files = entries.filter((f) => f.endsWith(".yml"));
-    const tasks = [];
-    const stale = [];
-    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 (err) {
-            if (isStaleTaskError(err))
-                stale.push(id);
-            continue; // skip malformed files; `akm tasks show <id>` will surface the error
-        }
-        tasks.push({
-            id: task.id,
-            ref: conceptIdFromTypeName("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,
-        });
-    }
-    if (stale.length > 0)
-        warnStaleTaskFiles(stale);
-    return { tasks, stale };
-}
-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: conceptIdFromTypeName("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, deps = {}) {
-    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 ref = taskAssetRef(normalised);
-    const sched = deps.backend ?? selectBackend();
-    const writeAsset = deps.writeAsset ?? writeAssetToSource;
-    const deleteAsset = deps.deleteAsset ?? deleteAssetFromSource;
-    const commitBoundary = deps.commitBoundary ?? commitWriteTargetBoundary;
-    const wasInstalled = (await sched.list()).some((entry) => entry.id === normalised);
-    const previousTask = wasInstalled ? parseTaskDocument({ yaml, filePath, id: normalised }) : undefined;
-    let uninstallAttempted = false;
-    let deleteAttempted = false;
-    try {
-        uninstallAttempted = true;
-        await sched.uninstall(normalised);
-        deleteAttempted = true;
-        await deleteAsset(target.source, target.config, ref);
-        commitBoundary(target, `Remove tasks/${normalised}`);
-    }
-    catch (err) {
-        const rollbackErrors = [];
-        let sourceRestored = false;
-        if (deleteAttempted) {
-            try {
-                await restoreTaskSourceBytes(writeAsset, target.source, target.config, ref, filePath, yaml);
-                sourceRestored = true;
-            }
-            catch (rollbackError) {
-                rollbackErrors.push(rollbackError);
-            }
-        }
-        if (uninstallAttempted && previousTask) {
-            try {
-                await sched.install(previousTask);
-            }
-            catch (rollbackError) {
-                rollbackErrors.push(rollbackError);
-            }
-        }
-        if (sourceRestored) {
-            try {
-                commitBoundary(target, `Restore tasks/${normalised}`);
-            }
-            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 "${normalised}" was incomplete.`);
-        }
-        throw err;
-    }
-    return { id: normalised, removed: true, backend: sched.name };
-}
-export async function akmTasksSetEnabled(id, enabled, deps = {}) {
-    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");
-    // Parse before writing so unsupported tasks are diagnosed without changing
-    // the source file or its installed scheduler entry.
-    const previousTask = parseTaskDocument({ yaml, filePath, id: normalised });
-    const updated = setEnabledInYaml(yaml, enabled);
-    const task = parseTaskDocument({ yaml: updated, filePath, id: normalised });
-    const obsoleteReason = obsoleteBackupTaskReason(task);
-    if (obsoleteReason)
-        throw new UsageError(obsoleteReason, "INVALID_FLAG_VALUE");
-    const ref = taskAssetRef(normalised);
-    const sched = deps.backend ?? selectBackend();
-    const writeAsset = deps.writeAsset ?? writeAssetToSource;
-    const commitBoundary = deps.commitBoundary ?? commitWriteTargetBoundary;
-    const wasInstalled = (await sched.list()).some((entry) => entry.id === normalised);
-    let sourceRestoreArmed = false;
-    let installSucceeded = false;
-    try {
-        sourceRestoreArmed = true;
-        await writeAsset(target.source, target.config, ref, updated);
-        // 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.
-        await sched.install(task);
-        installSucceeded = true;
-        commitBoundary(target, `Update tasks/${normalised}`);
-    }
-    catch (err) {
-        const rollbackErrors = [];
-        let sourceRestored = false;
-        if (sourceRestoreArmed) {
-            try {
-                await restoreTaskSourceBytes(writeAsset, target.source, target.config, ref, filePath, yaml);
-                sourceRestored = true;
-            }
-            catch (rollbackError) {
-                rollbackErrors.push(rollbackError);
-            }
-        }
-        if (installSucceeded) {
-            try {
-                if (wasInstalled)
-                    await sched.install(previousTask);
-                else
-                    await sched.uninstall(normalised);
-            }
-            catch (rollbackError) {
-                rollbackErrors.push(rollbackError);
-            }
-        }
-        if (sourceRestored) {
-            try {
-                commitBoundary(target, `Restore tasks/${normalised}`);
-            }
-            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 "${normalised}" was incomplete.`);
-        }
-        throw err;
-    }
-    return { id: normalised, enabled, backend: sched.name };
-}
 export async function akmTasksRun(id, options = {}) {
     const startedAt = new Date();
     let normalised;
@@ -441,7 +216,13 @@ export async function akmTasksRun(id, options = {}) {
     }
     let stashDir;
     try {
-        stashDir = resolveStashDir();
+        // 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({
@@ -452,9 +233,6 @@ export async function akmTasksRun(id, options = {}) {
         });
         throw failure;
     }
-    const typeRoot = path.join(stashDir, "tasks");
-    if (fs.existsSync(typeRoot))
-        warnLegacyMdTaskFiles(typeRoot);
     const result = await runTask(normalised, { stashDir, scheduled: options.scheduled === true });
     const exitCode = result.status === "failed" && result.target.kind === "command" && result.detail?.exitCode === 78
         ? 78
@@ -468,26 +246,32 @@ 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 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)
@@ -496,22 +280,30 @@ export async function akmTasksSync(deps = {}) {
         : [];
     const sched = deps.backend ?? selectBackend();
     const backend = sched.name;
-    // 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 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 });
             await validateTaskDocument(task, { backend, stashDir });
-            const obsoleteReason = obsoleteBackupTaskReason(task);
-            if (obsoleteReason)
-                throw new UsageError(obsoleteReason, "INVALID_FLAG_VALUE");
+            // 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) });
@@ -531,8 +323,14 @@ export async function akmTasksSync(deps = {}) {
             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
@@ -540,13 +338,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);
         }
     }
@@ -557,48 +357,69 @@ export async function akmTasksSync(deps = {}) {
             removed.push(installedId);
         }
     }
-    return { installed, updated, removed, unchanged, skipped, backend: sched.name };
-}
-function obsoleteBackupTaskReason(task) {
-    if (!task.enabled || task.target.kind !== "command")
-        return undefined;
-    const executableIndex = findBareAkmExecutableIndex(task.target.cmd);
-    if (executableIndex === undefined)
-        return undefined;
-    const args = task.target.cmd.slice(executableIndex + 1);
-    if (args.length !== 2 || args[0] !== "db" || args[1] !== "backups")
-        return undefined;
-    return (`Task "${task.id}" invokes obsolete \`akm db backups\`, which only listed legacy backups and is not a 0.9 backup command. ` +
-        "AKM will not install or enable it; sync will keep any existing scheduler entry disabled, and the task file is unchanged. " +
-        "Use `akm backup create --for 0.9.0` for an explicit migration recovery snapshot.");
+    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 config = loadConfig();
+    const bindings = groupInstalledBindings(installed, invocation);
+    // Report the EFFECTIVE engine view — the same one the runner resolves —
+    // so doctor never says "no engine" on an install where tasks actually run.
+    const { config } = withEngineFallback(loadConfig());
     const defaultEngine = config.defaults?.engine;
     const engines = Object.keys(config.engines ?? {});
     // §6.1: surface the effective triage settings for the default improve
     // strategy. The struct is a fixed shape, so this is a deliberate addition.
     const improveStrategyName = typeof config.defaults?.improveStrategy === "string" ? config.defaults.improveStrategy : "default";
-    const triage = resolveImproveStrategy(config.defaults?.improveStrategy, config).config.processes?.triage;
+    // 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 })),
+    };
+    const triage = effectiveStrategy.processes?.triage;
     const improveTriage = triage
         ? {
             defaultStrategy: improveStrategyName,
@@ -610,17 +431,111 @@ 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(),
         engine: { defaultEngine, available: engines },
-        stale: collectStaleTaskIds(),
-        staleGeneratedCommands: collectStaleGeneratedCommands(),
         scheduleSubset: SCHEDULE_SUPPORTED_SUBSET_HINT,
         warnings,
+        improveAutonomy,
         ...(improveTriage ? { improveTriage } : {}),
     };
 }
 // ── helpers ─────────────────────────────────────────────────────────────────
+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 };
 }
@@ -629,8 +544,55 @@ async function restoreTaskSourceBytes(writeAsset, source, config, ref, filePath,
     // The normal write path adds a trailing newline; rollback restores the raw snapshot exactly.
     fs.writeFileSync(filePath, yaml, "utf8");
 }
-function resolveTaskWriteTarget() {
-    return resolveWriteTarget(loadConfig());
+/**
+ * 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 = { version: 2, schedule: input.schedule, enabled: input.enabled };
@@ -639,6 +601,8 @@ function renderTaskYaml(input) {
         if (input.params) {
             obj.params = parseJsonObjectArg(input.params);
         }
+        if (input.timeoutMs !== undefined)
+            obj.timeoutMs = input.timeoutMs;
     }
     else if (input.prompt) {
         obj.prompt = input.prompt;
@@ -667,101 +631,6 @@ function renderTaskYaml(input) {
         obj.tags = input.tags;
     return yamlStringify(obj);
 }
-function isStaleTaskError(err) {
-    return err instanceof UsageError && err.code === "TASK_SCHEMA_VERSION_UNSUPPORTED";
-}
-function warnStaleTaskFiles(ids) {
-    process.stderr.write(`WARNING: ${ids.length} task file(s) use an unsupported task schema version and were not loaded.\n` +
-        `         Use version: 2. See docs/migration/v0.8-to-v0.9.md#engine-and-task-assets.\n` +
-        `         Affected: ${ids.map((id) => `tasks/${id}.yml`).join(", ")}\n`);
-}
-function collectStaleTaskIds() {
-    const typeRoot = path.join(resolveStashDir(), "tasks");
-    if (!fs.existsSync(typeRoot))
-        return [];
-    const stale = [];
-    for (const file of fs.readdirSync(typeRoot)) {
-        if (!file.endsWith(".yml"))
-            continue;
-        const id = file.slice(0, -4);
-        try {
-            parseTaskDocument({
-                yaml: fs.readFileSync(path.join(typeRoot, file), "utf8"),
-                filePath: path.join(typeRoot, file),
-                id,
-            });
-        }
-        catch (err) {
-            if (isStaleTaskError(err))
-                stale.push(id);
-        }
-    }
-    return stale;
-}
-// Old-spelling match keys for the default-task commands whose retired
-// `--auto-accept safe` flag is dropped in the `replacement`. Each id lists BOTH
-// deprecated spellings that can survive in a v2 task file: the original
-// `--profile X --auto-accept safe` and the intermediate `--strategy X
-// --auto-accept safe` (what the 0.8→0.9 migration writes — parser normalization
-// only rewrites `--profile`→`--strategy` for legacy v1 files, so a stored v2
-// file keeps whichever spelling it was minted with). Without the `--strategy`
-// variant, migrated default tasks match no key and warn on every run until 0.10
-// (chunk-6 ledger residue).
-const STALE_GENERATED_COMMANDS = {
-    "akm-improve-frequent": {
-        commands: [
-            "akm improve --profile frequent --auto-accept safe",
-            "akm improve --strategy frequent --auto-accept safe",
-        ],
-        replacement: "akm improve --strategy frequent",
-    },
-    "akm-improve-consolidate": {
-        commands: [
-            "akm improve --profile consolidate --auto-accept safe",
-            "akm improve --strategy consolidate --auto-accept safe",
-        ],
-        replacement: "akm improve --strategy consolidate",
-    },
-    "akm-improve-nightly": {
-        commands: [
-            "akm improve --profile thorough --auto-accept safe",
-            "akm improve --strategy thorough --auto-accept safe",
-        ],
-        replacement: "akm improve --strategy thorough",
-    },
-    "akm-improve-catchup": {
-        commands: ["akm improve --profile catchup --auto-accept safe", "akm improve --strategy catchup --auto-accept safe"],
-        replacement: "akm improve --strategy catchup",
-    },
-    "akm-graph-refresh-weekly": {
-        commands: [
-            "akm improve --profile graph-refresh --auto-accept safe",
-            "akm improve --strategy graph-refresh --auto-accept safe",
-        ],
-        replacement: "akm improve --strategy graph-refresh",
-    },
-};
-function collectStaleGeneratedCommands() {
-    const typeRoot = path.join(resolveStashDir(), "tasks");
-    if (!fs.existsSync(typeRoot))
-        return [];
-    const stale = [];
-    for (const [id, expected] of Object.entries(STALE_GENERATED_COMMANDS)) {
-        const filePath = path.join(typeRoot, `${id}.yml`);
-        if (!fs.existsSync(filePath))
-            continue;
-        try {
-            const task = parseTaskDocument({ yaml: fs.readFileSync(filePath, "utf8"), filePath, id });
-            if (task.target.kind === "command" && expected.commands.includes(task.target.cmd.join(" "))) {
-                stale.push({ id, replacement: expected.replacement });
-            }
-        }
-        catch {
-            // Stale-schema reporting owns files that cannot be parsed.
-        }
-    }
-    return stale;
-}
 function parseJsonObjectArg(raw) {
     let parsed;
     try {
@@ -799,11 +668,9 @@ 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 };
-// Accept a bare task id or the canonical 0.9.0 `[bundle//]tasks/<id>` ref
-// (ref-grammar decision D-R3). The pre-0.9.0 `task:<id>` colon grammar is
-// retired and rejected loudly — it appears NOWHERE after the flip.
+// Accept a bare task id or the canonical `[bundle//]tasks/<id>` ref.
 export function parseTaskRef(input) {
     const trimmed = input.trim();
     // Canonical conceptId form: `[bundle//]tasks/<id>`. A `/` unambiguously marks
@@ -821,11 +688,5 @@ export function parseTaskRef(input) {
         }
         throw new UsageError(`Expected a task id or tasks/<id> ref, got "${input}".`, "INVALID_FLAG_VALUE");
     }
-    // Legacy `task:<id>` grammar is gone in 0.9.0 (D-R3) — reject it with a typed
-    // error that names the new form so muscle-memory callers get a clear fix.
-    if (trimmed.includes(":")) {
-        const legacyName = trimmed.slice(trimmed.indexOf(":") + 1);
-        throw new UsageError(`The \`task:<id>\` ref grammar was removed in 0.9.0 — use the bare id or \`tasks/${legacyName || "<id>"}\`.`, "INVALID_FLAG_VALUE");
-    }
     return { id: normaliseTaskId(trimmed) };
 }