akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/storage/repositories/task-history-repository.js

@@ -24,7 +24,7 @@ function validateDetail(value) {
         metadataError("detail.exitCode must be a number or null");
     }
 }
-/** Decode historical v1 and current v2 metadata without cross-version aliases. */
+/** Decode supported historical and current task-history metadata. */
 export function decodeTaskHistoryMetadata(input) {
     let parsed = input;
     if (typeof input === "string") {
@@ -37,27 +37,26 @@ export function decodeTaskHistoryMetadata(input) {
     }
     if (!isRecord(parsed))
         metadataError("root must be an object");
-    const version = parsed.metadataVersion ?? 1;
-    if (version === 1) {
+    if (parsed.metadataVersion === undefined || parsed.metadataVersion === 1) {
         const allowed = new Set(["metadataVersion", "durationMs", "detail", "profile"]);
         const unknown = Object.keys(parsed).filter((key) => !allowed.has(key));
         if (unknown.length > 0)
             metadataError(`unknown v1 fields: ${unknown.sort().join(", ")}`);
-        if (parsed.metadataVersion !== undefined && parsed.metadataVersion !== 1)
-            metadataError("invalid v1 metadataVersion");
-        if (parsed.durationMs !== undefined && typeof parsed.durationMs !== "number")
+        if (parsed.durationMs !== undefined && typeof parsed.durationMs !== "number") {
             metadataError("durationMs must be a number");
-        if (parsed.profile !== undefined && typeof parsed.profile !== "string")
+        }
+        if (parsed.profile !== undefined && typeof parsed.profile !== "string") {
             metadataError("profile must be a string");
+        }
         validateDetail(parsed.detail);
         return {
             metadataVersion: 1,
-            ...(typeof parsed.durationMs === "number" ? { durationMs: parsed.durationMs } : {}),
-            ...(parsed.detail !== undefined && parsed.detail !== null ? { detail: parsed.detail } : {}),
-            ...(typeof parsed.profile === "string" ? { legacyProfile: parsed.profile } : {}),
+            durationMs: parsed.durationMs ?? 0,
+            detail: parsed.detail ?? null,
+            ...(parsed.profile !== undefined ? { legacyProfile: parsed.profile } : {}),
         };
     }
-    if (version === 2) {
+    if (parsed.metadataVersion === 2) {
         const allowed = new Set(["metadataVersion", "durationMs", "detail", "engine"]);
         const unknown = Object.keys(parsed).filter((key) => !allowed.has(key));
         if (unknown.length > 0)
@@ -77,7 +76,7 @@ export function decodeTaskHistoryMetadata(input) {
             ...(parsed.engine !== undefined ? { engine: parsed.engine } : {}),
         };
     }
-    metadataError(`unsupported metadataVersion: ${String(version)}`);
+    metadataError(`unsupported metadataVersion: ${String(parsed.metadataVersion)}`);
 }
 /**
  * Atomically reserve one task-attempt identity.
@@ -169,10 +168,13 @@ export function queryTaskHistory(db, options = {}) {
         params.push(options.targetRef);
     }
     const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    const limit = options.limit !== undefined ? "LIMIT ?" : "";
+    if (options.limit !== undefined)
+        params.push(options.limit);
     return db
         .prepare(`SELECT task_id, status, started_at, completed_at, failed_at, log_path,
               target_kind, target_ref, metadata_json
-       FROM task_history ${where} ORDER BY started_at DESC, id DESC`)
+       FROM task_history ${where} ORDER BY started_at DESC, id DESC ${limit}`)
         .all(...params);
 }
 /**

package/dist/storage/repositories/workflow-runs-repository.js

@@ -1,7 +1,7 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // 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/.
-import { openStateDatabase } from "../../core/state-db.js";
+import { openStateDatabase, withImmediateTransaction } from "../../core/state-db.js";
 import { resolveStorageLocations } from "../locations.js";
 /**
  * Repository owning every raw SQL statement against `workflow_runs` and
@@ -30,19 +30,28 @@ export class WorkflowRunsRepository {
     transaction(fn) {
         return this.db.transaction(fn)();
     }
+    immediateTransaction(fn) {
+        return withImmediateTransaction(this.db, () => fn(this.db));
+    }
     // ── reads (fully materialised) ─────────────────────────────────────────────
-    findActiveRunForScope(workflowRef, scopeKey) {
+    findActiveRunForScope(workflowRefs, scopeKey) {
+        const refs = typeof workflowRefs === "string" ? [workflowRefs] : [...workflowRefs];
+        if (refs.length === 0)
+            return undefined;
         return this.db
-            .prepare("SELECT id, current_step_id FROM workflow_runs WHERE workflow_ref = ? AND scope_key = ? AND status = 'active' ORDER BY updated_at DESC LIMIT 1")
-            .get(workflowRef, scopeKey);
+            .prepare(`SELECT id, current_step_id FROM workflow_runs WHERE workflow_ref IN (${refs.map(() => "?").join(", ")}) AND scope_key = ? AND status = 'active' ORDER BY updated_at DESC, created_at DESC LIMIT 1`)
+            .get(...refs, scopeKey);
     }
     getRunById(runId) {
         return this.db.prepare("SELECT * FROM workflow_runs WHERE id = ?").get(runId);
     }
-    getActiveRunRowForScope(workflowRef, scopeKey) {
+    getActiveRunRowForScope(workflowRefs, scopeKey) {
+        const refs = typeof workflowRefs === "string" ? [workflowRefs] : [...workflowRefs];
+        if (refs.length === 0)
+            return undefined;
         return this.db
-            .prepare("SELECT * FROM workflow_runs WHERE workflow_ref = ? AND scope_key = ? AND status = 'active' ORDER BY updated_at DESC LIMIT 1")
-            .get(workflowRef, scopeKey);
+            .prepare(`SELECT * FROM workflow_runs WHERE workflow_ref IN (${refs.map(() => "?").join(", ")}) AND scope_key = ? AND status = 'active' ORDER BY updated_at DESC, created_at DESC LIMIT 1`)
+            .get(...refs, scopeKey);
     }
     hasRun(runId) {
         const row = this.db.prepare("SELECT 1 FROM workflow_runs WHERE id = ? LIMIT 1").get(runId);
@@ -57,6 +66,10 @@ export class WorkflowRunsRepository {
             filters.push("workflow_ref = ?");
             params.push(filter.workflowRef);
         }
+        else if (filter.workflowRefs && filter.workflowRefs.length > 0) {
+            filters.push(`workflow_ref IN (${filter.workflowRefs.map(() => "?").join(", ")})`);
+            params.push(...filter.workflowRefs);
+        }
         if (filter.activeOnly) {
             // `activeOnly` means EXACTLY status='active' — a run currently
             // executable. A `blocked` run is NOT active (it is parked awaiting a
@@ -113,7 +126,9 @@ export class WorkflowRunsRepository {
             .run(runId, currentStepId);
     }
     markRunActive(runId, updatedAt) {
-        this.db.prepare("UPDATE workflow_runs SET status = 'active', updated_at = ? WHERE id = ?").run(updatedAt, runId);
+        this.db
+            .prepare("UPDATE workflow_runs SET status = 'active', updated_at = ?, engine_lease_holder = NULL, engine_lease_until = NULL WHERE id = ?")
+            .run(updatedAt, runId);
     }
     updateStepCompletion(input) {
         this.db
@@ -129,6 +144,14 @@ export class WorkflowRunsRepository {
            WHERE id = ?`)
             .run(input.status, input.currentStepId, input.updatedAt, input.completedAt, input.checkinArmedAt, input.runId);
     }
+    markRunAbandoned(runId, updatedAt) {
+        const result = this.db
+            .prepare(`UPDATE workflow_runs
+           SET status = 'failed', updated_at = ?, completed_at = ?, checkin_armed_at = ?
+           WHERE id = ? AND status IN ('active', 'blocked')`)
+            .run(updatedAt, updatedAt, updatedAt, runId);
+        return Number(result.changes) === 1;
+    }
     rearmCheckin(runId, checkinArmedAt) {
         this.db.prepare("UPDATE workflow_runs SET checkin_armed_at = ? WHERE id = ?").run(checkinArmedAt, runId);
     }
@@ -161,7 +184,8 @@ export class WorkflowRunsRepository {
         const result = this.db
             .prepare(`UPDATE workflow_runs
            SET engine_lease_holder = ?, engine_lease_until = ?
-           WHERE id = ? AND (engine_lease_holder IS NULL OR engine_lease_until IS NULL OR engine_lease_until < ?)`)
+           WHERE id = ? AND status = 'active'
+             AND (engine_lease_holder IS NULL OR engine_lease_until IS NULL OR engine_lease_until < ?)`)
             .run(holder, until, runId, now);
         return Number(result.changes) > 0;
     }
@@ -172,18 +196,18 @@ export class WorkflowRunsRepository {
      */
     renewEngineLease(runId, holder, until) {
         const result = this.db
-            .prepare("UPDATE workflow_runs SET engine_lease_until = ? WHERE id = ? AND engine_lease_holder = ?")
+            .prepare("UPDATE workflow_runs SET engine_lease_until = ? WHERE id = ? AND engine_lease_holder = ? AND status = 'active'")
             .run(until, runId, holder);
         return Number(result.changes) > 0;
     }
     /**
-     * Clear the lease — only while `holder` still owns it, so a crashed-then-
-     * recovered invocation can never release a lease another engine has since
-     * claimed. Releasing an already-lost lease is a harmless no-op.
+     * Clear the lease only while `holder` still owns a non-failed run. Failed
+     * runs retain the final holder/expiry for forensics until explicit resume.
+     * Releasing an already-lost lease is a harmless no-op.
      */
     releaseEngineLease(runId, holder) {
         this.db
-            .prepare("UPDATE workflow_runs SET engine_lease_holder = NULL, engine_lease_until = NULL WHERE id = ? AND engine_lease_holder = ?")
+            .prepare("UPDATE workflow_runs SET engine_lease_holder = NULL, engine_lease_until = NULL WHERE id = ? AND engine_lease_holder = ? AND status <> 'failed'")
             .run(runId, holder);
     }
     // ── unit rows (migration 004) ──────────────────────────────────────────────
@@ -202,25 +226,11 @@ export class WorkflowRunsRepository {
             .prepare("SELECT * FROM workflow_run_units WHERE run_id = ? AND step_id = ? ORDER BY started_at ASC, unit_id ASC")
             .all(runId, stepId);
     }
-    /** One unit row by primary key, or undefined. Used by the R3 report path's
-     * guarded read-then-write (idempotency / replay-divergence / claim checks). */
+    /** One unit row by primary key, or undefined. Used for guarded read-then-write
+     * (idempotency / replay-divergence / claim checks). */
     getUnit(runId, unitId) {
         return this.db.prepare("SELECT * FROM workflow_run_units WHERE run_id = ? AND unit_id = ?").get(runId, unitId);
     }
-    /**
-     * Stamp a unit-level check-in heartbeat (migration 007, R3 driver protocol):
-     * a driver executing a unit calls `report --status running` to claim (first
-     * call) or heartbeat (subsequent) it. Sets `status = 'running'` and
-     * `last_checkin_at`; NEVER touches `started_at` (the first-claim marker set by
-     * {@link insertUnit}) so the heartbeat window advances without resetting the
-     * claim time. The caller guards against re-claiming a terminal unit inside its
-     * transaction.
-     */
-    updateUnitCheckin(runId, unitId, lastCheckinAt) {
-        this.db
-            .prepare("UPDATE workflow_run_units SET status = 'running', last_checkin_at = ? WHERE run_id = ? AND unit_id = ?")
-            .run(lastCheckinAt, runId, unitId);
-    }
     /**
      * Insert a unit row in `running` state (a dispatch is starting now).
      *
@@ -267,20 +277,22 @@ export class WorkflowRunsRepository {
             .run(input.runId, input.unitId, input.stepId, input.nodeId, input.parentUnitId, input.phase, input.runner, input.engine ?? null, input.model, input.inputHash, input.worktreePath ?? null, input.startedAt, input.claimHolder ?? null, input.claimExpiresAt ?? null);
     }
     /**
-     * Stamp a `--status running` claim + heartbeat on a unit row (migration 009,
-     * PR #714 review round 2). Sets `status = 'running'`, refreshes the heartbeat
-     * (`last_checkin_at`), and (re)writes the claim owner + expiry. Called inside
-     * the report path's running-claim transaction AFTER it has validated that the
-     * claim is free / expired / already held by this holder, so the write is the
-     * final step of a checked reclaim. Never touches `started_at` (the first-claim
-     * marker set by {@link insertUnit}).
+     * Stamp a `running` claim + heartbeat on a unit row (migration 009, PR #714
+     * review round 2). Sets `status = 'running'`, refreshes the heartbeat
+     * (`last_checkin_at`), and (re)writes the claim owner + expiry. Must be called
+     * inside a transaction that has ALREADY validated the claim is free / expired
+     * / already held by this holder, so the write is the final step of a checked
+     * reclaim. Never touches `started_at` (the first-claim marker set by
+     * {@link insertUnit}).
      */
     updateUnitClaim(runId, unitId, holder, expiresAt, lastCheckinAt) {
-        this.db
+        const result = this.db
             .prepare(`UPDATE workflow_run_units
            SET status = 'running', last_checkin_at = ?, claim_holder = ?, claim_expires_at = ?
-           WHERE run_id = ? AND unit_id = ?`)
-            .run(lastCheckinAt, holder, expiresAt, runId, unitId);
+           WHERE run_id = ? AND unit_id = ?
+             AND EXISTS (SELECT 1 FROM workflow_runs WHERE id = ? AND status = 'active')`)
+            .run(lastCheckinAt, holder, expiresAt, runId, unitId, runId);
+        return Number(result.changes) === 1;
     }
     /**
      * Record a unit's terminal state (completed / failed / skipped).

package/dist/tasks/backends/cron.js

@@ -1,13 +1,13 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // 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/.
-// crontab backend for `akm tasks` (Linux default).
+// crontab backend for `akm task` (Linux default).
 //
 // Each akm-owned entry is wrapped in markers so a hand-edited crontab keeps
 // its other lines untouched:
 //
 //     # akm:task <id> BEGIN
-//     [SCHED] /abs/akm tasks run <id> >> /home/.../tasks/logs/<id>.log 2>&1
+//     [SCHED] /abs/akm task run <id> >> /home/.../tasks/logs/<id>.log 2>&1
 //     # akm:task <id> END
 //
 // The backend reads/writes the user's crontab via `crontab -l` and
@@ -30,13 +30,14 @@ import { ConfigError } from "../../core/errors.js";
 import { getTaskLogDir } from "../../core/paths.js";
 import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToCron } from "../schedule.js";
-import { buildScheduledTaskInvocation, resolveScheduledTaskContext, } from "../scheduler-invocation.js";
+import { buildScheduledTaskInvocation, parseScheduledTaskArgv, resolveScheduledTaskContext, schedulerContextDescriptor, schedulerContextPath, } from "../scheduler-invocation.js";
 import { nodeFs, throwIfNotOk } from "./exec-utils.js";
 const BEGIN = (id) => `# akm:task ${assertCronValue(id)} BEGIN`;
 const END = (id) => `# akm:task ${assertCronValue(id)} END`;
 const DISABLED_PREFIX = "# akm:disabled ";
 const BLOCK_RE = /^# akm:task ([\w.@:_-]+) BEGIN$/;
 const BLOCK_END_RE = /^# akm:task ([\w.@:_-]+) END$/;
+export const PORTABLE_CRON_LINE_LIMIT = 1000;
 export function CRON_BACKEND(options = {}) {
     const exec = options.exec ?? defaultCronExec();
     const fsLike = options.fs ?? nodeFs();
@@ -44,14 +45,16 @@ export function CRON_BACKEND(options = {}) {
     const akmArgv = options.akmArgv ?? resolveAkmInvocation().argv;
     const envPath = options.envPath === false ? undefined : (options.envPath ?? process.env.PATH);
     const scheduledContext = options.scheduledContext ?? resolveScheduledTaskContext();
+    const defaultContextPath = schedulerContextPath(schedulerContextDescriptor(scheduledContext, envPath ?? ""));
     return {
         name: "cron",
-        install(task) {
+        install(task, opts) {
             // Create the log directory before writing the crontab line — cron
             // appends with `>>` and the surrounding shell will fail the entire
             // entry if the parent directory doesn't exist.
+            const cronLine = buildCronLine(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.contextPath ?? defaultContextPath, opts?.target);
+            assertPortableCronLine(cronLine);
             fsLike.ensureDir(logDir);
-            const cronLine = buildCronLine(task, akmArgv, logDir, envPath, scheduledContext);
             const existing = readCrontab(exec);
             const block = renderBlock(task.id, cronLine, task.enabled);
             const next = upsertBlock(existing, task.id, block);
@@ -69,26 +72,54 @@ export function CRON_BACKEND(options = {}) {
         },
         list() {
             const existing = readCrontab(exec);
-            return listBlocks(existing).map(({ id, body }) => ({ id, signature: normalizeSignature(body) }));
+            const refs = [];
+            for (const { id, body } of listBlocks(existing)) {
+                const installed = extractCronInvocation(body);
+                // An invocation that no longer parses (e.g. a pre-0.9 `tasks run`
+                // entry surviving the scheduler-ABI respelling, or any other
+                // foreign/malformed line between our markers) is an orphan of its
+                // marker id, not a hard failure: omit it here so `akmTasksSync`
+                // treats the id as "not present" and reinstalls it from the current
+                // task file — going through the normal eligibility/`--rebind` gate
+                // exactly like a fresh install.
+                if (!installed)
+                    continue;
+                refs.push({
+                    id,
+                    signature: normalizeSignature(body),
+                    ...(installed.target !== undefined ? { target: installed.target } : {}),
+                    binding: installed.binding,
+                    contextPath: installed.contextPath,
+                });
+            }
+            return refs;
+        },
+        listForRebind() {
+            const existing = readCrontab(exec);
+            return listBlocks(existing).map(({ id, body }) => {
+                const installed = extractCronInvocation(body);
+                return {
+                    id,
+                    signature: normalizeSignature(body),
+                    ...(installed?.target !== undefined ? { target: installed.target } : {}),
+                };
+            });
         },
-        expectedSignature(task) {
-            const cronLine = buildCronLine(task, akmArgv, logDir, envPath, scheduledContext);
+        expectedSignature(task, opts) {
+            const cronLine = buildCronLine(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.contextPath ?? defaultContextPath, opts?.target);
+            assertPortableCronLine(cronLine);
             return normalizeSignature(cronBlockBody(cronLine, task.enabled));
         },
     };
 }
 // ── helpers (exported for tests) ────────────────────────────────────────────
-export function buildCronLine(task, akmArgv, logDir, envPath, scheduledContext) {
+export function buildCronLine(task, akmArgv, logDir, contextPath, target) {
     const spec = parseSchedule(task.schedule, "cron");
     const cronExpr = translateToCron(spec);
     const logPath = path.join(logDir, `${task.id}.log`);
-    const invocation = buildScheduledTaskInvocation(akmArgv, task.id, scheduledContext);
+    const invocation = buildScheduledTaskInvocation(akmArgv, task.id, contextPath, target);
     const cmd = invocation.argv.map((part) => quoteForCron(part)).join(" ");
-    const contextPrefix = Object.entries(invocation.environment)
-        .map(([key, value]) => `${key}=${quoteForCron(value)}`)
-        .join(" ");
-    const pathPrefix = envPath === undefined ? "" : `PATH=${quoteForCron(envPath)} `;
-    return `${cronExpr} ${contextPrefix} ${pathPrefix}${cmd} >> ${quoteForCron(logPath)} 2>&1`;
+    return `${cronExpr} ${cmd} >> ${quoteForCron(logPath)} 2>&1`;
 }
 /** The crontab line as it appears inside a block — commented when disabled. */
 export function cronBlockBody(cronLine, enabled) {
@@ -141,6 +172,59 @@ function parseBlocks(existing) {
 function malformedBlockError(id) {
     return new ConfigError(`Crontab contains a malformed akm task block for "${id}"; refusing to modify it.`, "INVALID_CONFIG_FILE");
 }
+/**
+ * Recover the bundle name from an installed cron block body by reading the
+ * `--bundle <bundle>` token embedded in the scheduled `akm task run …`
+ * invocation. Returns undefined for the byte-identical primary/default form
+ * (no `--bundle`). Bundle slugs never contain whitespace (config-schema
+ * `isBundleSlug`), so the quoted token is a single whitespace-delimited field
+ * even when cron-quoted — a plain field split recovers it, and
+ * the shell-word parser below reverses the quoting.
+ */
+export function extractInstalledTarget(body) {
+    return extractCronInvocation(body)?.target;
+}
+export function extractCronInvocation(body) {
+    const line = body.startsWith(DISABLED_PREFIX) ? body.slice(DISABLED_PREFIX.length) : body;
+    const fields = splitCronShellWords(line);
+    if (fields.length < 6)
+        return undefined;
+    let commandStart = 5;
+    while (commandStart < fields.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(fields[commandStart]))
+        commandStart += 1;
+    const redirectIndex = fields.indexOf(">>", commandStart);
+    if (redirectIndex === -1)
+        return undefined;
+    return parseScheduledTaskArgv(fields.slice(commandStart, redirectIndex));
+}
+/** Reverse {@link quoteForCron} for a single whitespace-free token. */
+function splitCronShellWords(value) {
+    const words = [];
+    let current = "";
+    let quoted = false;
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value[index];
+        if (char === "'") {
+            quoted = !quoted;
+            continue;
+        }
+        if (char === "\\" && index + 1 < value.length) {
+            current += value[index + 1];
+            index += 1;
+            continue;
+        }
+        if (!quoted && /\s/.test(char)) {
+            if (current)
+                words.push(current);
+            current = "";
+            continue;
+        }
+        current += char;
+    }
+    if (current)
+        words.push(current);
+    return words;
+}
 /** Collapse incidental whitespace so signature comparison ignores it. */
 function normalizeSignature(body) {
     return body
@@ -218,6 +302,12 @@ function assertCronValue(value) {
     }
     return value;
 }
+function assertPortableCronLine(line) {
+    const bytes = Buffer.byteLength(line, "utf8");
+    if (bytes > PORTABLE_CRON_LINE_LIMIT) {
+        throw new ConfigError(`Generated cron definition is ${bytes} bytes; portable cron command lines are limited to ${PORTABLE_CRON_LINE_LIMIT} bytes.`, "INVALID_CONFIG_FILE");
+    }
+}
 function readCrontab(exec) {
     const result = exec.read();
     if (result.status === 0)

package/dist/tasks/backends/index.js

@@ -6,7 +6,7 @@ import { LAUNCHD_BACKEND } from "./launchd.js";
 import { SCHTASKS_BACKEND } from "./schtasks.js";
 // WI-9.10e: the former `_setBackendsForTests` module-mutation seam was retired.
 // Tests inject a fake `TaskBackend` directly via the `deps.backend` parameter
-// the `akm tasks` mutation entries already accept (the backend carries its own
+// the `akm task` mutation entries already accept (the backend carries its own
 // `name`), so no module-level override binding is needed. `selectBackend`'s
 // `options.platform` covers the platform-steering the seam's second override
 // used to provide.

package/dist/tasks/backends/launchd.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/.
 /**
- * launchd backend for `akm tasks` (macOS default).
+ * launchd backend for `akm task` (macOS default).
  *
  * Each task is written as a per-user LaunchAgent plist at
  * `~/Library/LaunchAgents/com.akm.task.<id>.plist` and registered via
@@ -29,7 +29,7 @@ import { ConfigError } from "../../core/errors.js";
 import { getTaskLogDir } from "../../core/paths.js";
 import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToLaunchd } from "../schedule.js";
-import { buildScheduledTaskInvocation, resolveScheduledTaskContext, } from "../scheduler-invocation.js";
+import { buildScheduledTaskInvocation, parseScheduledTaskArgv, resolveScheduledTaskContext, schedulerContextDescriptor, schedulerContextPath, } from "../scheduler-invocation.js";
 import { escapeXml, nodeExec, nodeFs, runOrThrow } from "./exec-utils.js";
 export const LAUNCHD_LABEL_PREFIX = "com.akm.task.";
 export function LAUNCHD_BACKEND(options = {}) {
@@ -49,6 +49,7 @@ export function LAUNCHD_BACKEND(options = {}) {
             return options.envPath;
         return process.env.PATH ?? "";
     };
+    const defaultContextPath = schedulerContextPath(schedulerContextDescriptor(scheduledContext, pathEnv() ?? ""));
     const setEnableState = (id, enabled) => {
         const verb = enabled ? "enable" : "disable";
         runOrThrow(exec, ["launchctl", verb, target(id)], {
@@ -57,10 +58,10 @@ export function LAUNCHD_BACKEND(options = {}) {
     };
     return {
         name: "launchd",
-        install(task) {
+        install(task, opts) {
             // Capture PATH at install time so launchd (which strips the environment
             // aggressively) can find the same binaries the user sees interactively.
-            const xml = buildPlistXml(task, akmArgv, logDir, pathEnv(), scheduledContext);
+            const xml = buildPlistXml(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.contextPath ?? defaultContextPath, opts?.target);
             const file = plistPath(task.id);
             const previousPlist = fsLike.exists(file) ? fsLike.readFile(file) : undefined;
             let previousEnabled = true;
@@ -201,55 +202,101 @@ export function LAUNCHD_BACKEND(options = {}) {
             if (ids.length === 0)
                 return [];
             const disabledLabels = readDisabledLabels(exec);
-            return ids.map((id) => {
-                if (!disabledLabels)
-                    return { id };
-                try {
-                    const loaded = exec.run(["launchctl", "print", target(id)]);
-                    if (loaded.status !== 0)
-                        return { id };
-                }
-                catch {
-                    return { id };
-                }
-                try {
-                    const xml = fsLike
-                        .readFile(plistPath(id))
-                        .replace(/<!-- akm-enabled:(?:true|false) -->/, `<!-- akm-enabled:${!disabledLabels.has(label(id))} -->`);
-                    return { id, signature: normalizeSignature(xml) };
-                }
-                catch {
-                    return { id };
-                }
-            });
+            return ids
+                .map((id) => inspectInstalledLaunchdTask(id, fsLike.readFile(plistPath(id)), disabledLabels, exec))
+                .filter((ref) => ref !== undefined);
+        },
+        listForRebind() {
+            if (!fsLike.exists(agentsDir))
+                return [];
+            const refs = [];
+            for (const file of fsLike.list(agentsDir)) {
+                if (!file.startsWith(LAUNCHD_LABEL_PREFIX) || !file.endsWith(".plist"))
+                    continue;
+                const id = file.slice(LAUNCHD_LABEL_PREFIX.length, -".plist".length);
+                const installed = extractPlistInvocation(fsLike.readFile(plistPath(id)));
+                refs.push({ id, ...(installed?.target !== undefined ? { target: installed.target } : {}) });
+            }
+            return refs;
         },
-        expectedSignature(task) {
-            return normalizeSignature(buildPlistXml(task, akmArgv, logDir, pathEnv(), scheduledContext));
+        expectedSignature(task, opts) {
+            return normalizeSignature(buildPlistXml(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.contextPath ?? defaultContextPath, opts?.target));
         },
     };
 }
+function inspectInstalledLaunchdTask(id, raw, disabledLabels, exec) {
+    const installed = extractPlistInvocation(raw);
+    // An invocation that no longer parses (e.g. a pre-0.9 `tasks run` entry
+    // surviving the scheduler-ABI respelling) is an orphan of its marker id,
+    // not a hard failure: `list()` omits it so `akmTasksSync` treats the id as
+    // "not present" and reinstalls it from the current task file.
+    if (!installed)
+        return undefined;
+    const metadata = {
+        ...(installed.target !== undefined ? { target: installed.target } : {}),
+        binding: installed.binding,
+        contextPath: installed.contextPath,
+    };
+    if (!disabledLabels)
+        return { id, ...metadata };
+    const jobLabel = `${LAUNCHD_LABEL_PREFIX}${id}`;
+    try {
+        const loaded = exec.run(["launchctl", "print", `gui/${exec.uid()}/${jobLabel}`]);
+        if (loaded.status !== 0)
+            return { id, ...metadata };
+    }
+    catch {
+        return { id, ...metadata };
+    }
+    try {
+        const xml = raw.replace(/<!-- akm-enabled:(?:true|false) -->/, `<!-- akm-enabled:${!disabledLabels.has(jobLabel)} -->`);
+        return {
+            id,
+            signature: normalizeSignature(xml),
+            ...metadata,
+        };
+    }
+    catch {
+        return { id, ...metadata };
+    }
+}
+/**
+ * Recover the bundle name embedded as a `--bundle <bundle>` pair in a plist's
+ * `<ProgramArguments>`. Returns undefined for the primary/default form.
+ */
+export function extractPlistTarget(xml) {
+    return extractPlistInvocation(xml)?.target;
+}
+export function extractPlistInvocation(xml) {
+    const block = xml.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/);
+    if (!block)
+        return undefined;
+    const args = [...block[1].matchAll(/<string>([\s\S]*?)<\/string>/g)].map((m) => decodeXmlEntities(m[1]));
+    return parseScheduledTaskArgv(args);
+}
+function decodeXmlEntities(value) {
+    return value
+        .replaceAll("&lt;", "<")
+        .replaceAll("&gt;", ">")
+        .replaceAll("&quot;", '"')
+        .replaceAll("&apos;", "'")
+        .replaceAll("&amp;", "&");
+}
 // ── XML builder (exported for tests) ────────────────────────────────────────
-export function buildPlistXml(task, akmArgv, logDir, pathEnv, scheduledContext) {
+export function buildPlistXml(task, akmArgv, logDir, contextPath, target) {
     const spec = parseSchedule(task.schedule, "launchd");
     const trigger = translateToLaunchd(spec);
-    const invocation = buildScheduledTaskInvocation(akmArgv, task.id, scheduledContext);
+    const invocation = buildScheduledTaskInvocation(akmArgv, task.id, contextPath, target);
     const argv = invocation.argv;
     const programArgs = argv.map((a) => `      <string>${escapeXml(a)}</string>`).join("\n");
     const logPath = path.join(logDir, `${task.id}.log`);
     const triggerXml = renderLaunchdTrigger(trigger);
-    const environment = { ...invocation.environment };
-    if (pathEnv !== undefined)
-        environment.PATH = pathEnv;
-    const envEntries = Object.entries(environment)
-        .map(([key, value]) => `    <key>${key}</key>\n    <string>${escapeXml(value)}</string>`)
-        .join("\n");
-    const envVarsXml = `  <key>EnvironmentVariables</key>\n  <dict>\n${envEntries}\n  </dict>\n`;
     const xml = launchdTemplate
         .replace("<dict>\n", `<dict>\n  <!-- akm-enabled:${task.enabled} -->\n`)
         .replace("{{LABEL}}", LAUNCHD_LABEL_PREFIX + escapeXml(task.id))
         .replace("{{PROGRAM_ARGS}}", programArgs)
         .replaceAll("{{LOG_PATH}}", escapeXml(logPath))
-        .replace("{{ENV_VARS}}", envVarsXml)
+        .replace("{{ENV_VARS}}", "")
         .replace("{{TRIGGER_XML}}", triggerXml);
     for (const char of xml) {
         const code = char.codePointAt(0) ?? 0;
@@ -330,7 +377,7 @@ function defaultAgentsDir() {
     // relative path that would write somewhere unexpected.
     const home = os.homedir();
     if (!home) {
-        throw new ConfigError("Cannot determine user home directory; launchd backend requires HOME to locate ~/Library/LaunchAgents.", "INVALID_CONFIG_FILE", "Set $HOME (POSIX) or the equivalent before running `akm tasks` on macOS.");
+        throw new ConfigError("Cannot determine user home directory; launchd backend requires HOME to locate ~/Library/LaunchAgents.", "INVALID_CONFIG_FILE", "Set $HOME (POSIX) or the equivalent before running `akm task` on macOS.");
     }
     return path.join(home, "Library", "LaunchAgents");
 }