akm-cli 0.9.17-alpha.3 → 0.9.17-alpha.5

package/dist/tasks/backends/launchd.js

@@ -11,12 +11,13 @@
  *
  * Platform notes:
  *   • The `bootstrap` / `bootout` / `enable` / `disable` subcommands require
- *     macOS 10.10 (Yosemite) or newer. On older systems the equivalents
- *     are `launchctl load -w` / `unload -w`. We only target modern macOS.
+ *     macOS 10.10 (Yosemite) or newer. We only target modern macOS.
  *   • `gui/<uid>` is the per-user GUI launchd domain — agents in this
- *     domain only run while the user is logged in (no background runs at
- *     the loginwindow). Tasks that need to run when the user is logged
- *     out should be installed as system Daemons, which is out of scope.
+ *     domain only run while the user is logged in. Tasks that need to run
+ *     when the user is logged out should be installed as system Daemons,
+ *     which is out of scope.
+ *   • launchd strips the environment; the syncing shell's PATH goes into the
+ *     plist's `EnvironmentVariables` so task bodies find the same binaries.
  *
  * Tests inject a fake exec + filesystem so the backend can be unit-tested
  * without touching the host launchctl.
@@ -31,14 +32,11 @@ import { getTaskLogDir } from "../../core/paths.js";
 import { warn } from "../../core/warn.js";
 import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToLaunchd } from "../schedule.js";
-import { assertSchedulerExecutionEvidenceDigest, assertSchedulerExpectationIdentity, assertSchedulerMutationArtifact, assertSchedulerNativeArtifactCardinality, assertSchedulerNativeArtifactOwner, assertSchedulerRemovalArtifact, assertSchedulerRollbackArtifactCardinality, schedulerBindingNativeId, schedulerLogicalBindingId, schedulerLogicalBindingOwner, schedulerNativeArtifactKey, } from "../scheduler-binding.js";
+import { schedulerBindingNativeId, schedulerLogicalBindingId } from "../scheduler-binding.js";
 import { buildScheduledBindingInvocation, parseScheduledBindingArgv, resolveScheduledTaskContext, schedulerContextDescriptor, schedulerContextPath, } from "../scheduler-invocation.js";
 import { escapeXml, nodeExec, nodeFs, runOrThrow } from "./exec-utils.js";
 export const LAUNCHD_LABEL_PREFIX = "com.akm.task.";
-const MAX_LAUNCHD_DOMAIN_OUTPUT_BYTES = 4 * 1024 * 1024;
-const MAX_LAUNCHD_AKM_NAMESPACE_ENTRIES = 4096;
 const LAUNCHD_AKM_LABEL_RE = /^com\.akm\.task\.[A-Za-z0-9._-]{1,1024}$/u;
-const LAUNCHD_SNAPSHOT = Symbol("akm-launchd-binding-snapshot");
 export function LAUNCHD_BACKEND(options = {}) {
     const exec = options.exec ?? defaultLaunchdExec();
     const fsLike = options.fs ?? defaultLaunchdFs();
@@ -46,691 +44,106 @@ export function LAUNCHD_BACKEND(options = {}) {
     const logDir = options.logDir ?? getTaskLogDir();
     const akmArgv = options.akmArgv ?? resolveAkmInvocation().argv;
     const scheduledContext = options.scheduledContext ?? resolveScheduledTaskContext();
+    const envPath = options.envPath === false ? undefined : typeof options.envPath === "string" ? options.envPath : process.env.PATH;
+    const defaultContextPath = schedulerContextPath(schedulerContextDescriptor(scheduledContext));
     const plistPath = (nativeId) => path.join(agentsDir, `${LAUNCHD_LABEL_PREFIX}${nativeId}.plist`);
     const label = (nativeId) => `${LAUNCHD_LABEL_PREFIX}${nativeId}`;
     const target = (nativeId) => `gui/${exec.uid()}/${label(nativeId)}`;
-    const defaultContextPath = launchdDefaultContextPath(options, scheduledContext);
-    const setEnableState = (nativeId, enabled) => setLaunchdEnableState(exec, target(nativeId), enabled);
+    const setEnableState = (nativeId, enabled) => {
+        const verb = enabled ? "enable" : "disable";
+        runOrThrow(exec, ["launchctl", verb, target(nativeId)], {
+            message: (result) => `launchctl ${verb} failed: ${result.stderr || result.stdout || "no output"}.`,
+        });
+    };
+    const bootout = (nativeId) => runOrThrow(exec, ["launchctl", "bootout", target(nativeId)], {
+        isOk: (r) => r.status === 0 || isServiceNotFoundResult(r),
+        message: (r) => `launchctl bootout failed (exit ${r.status}): ${r.stderr || r.stdout || "no output"}.`,
+    });
+    const xmlFor = (task, opts) => buildPlistXml(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.contextPath ?? defaultContextPath, envPath);
     return {
         name: "launchd",
-        install(task, opts, expected) {
-            installLaunchdBinding(task, opts, expected, {
-                exec,
-                fsLike,
-                agentsDir,
-                logDir,
-                akmArgv,
-                defaultContextPath,
-                plistPath,
-                label,
-                target,
-                setEnableState,
-            });
-        },
-        uninstall(nativeId, expected) {
-            const inspectionContext = { exec, fsLike, agentsDir, plistPath, target, label };
-            const initialNamespace = inspectStableLaunchdNamespace([nativeId], inspectionContext);
-            let initialArtifact;
-            if (expected) {
-                assertSchedulerExpectationIdentity({ ...expected, state: "present" });
-                initialArtifact = assertSchedulerNativeArtifactCardinality(initialNamespace.inspection.artifacts, nativeId, 1);
-                if (!initialArtifact) {
-                    throw new ConfigError(`launchd artifact ${JSON.stringify(nativeId)} disappeared during inspection.`, "INVALID_CONFIG_FILE");
-                }
-                assertSchedulerRemovalArtifact(initialArtifact.nativeId, expected, initialArtifact.invocation, initialArtifact.fingerprint);
-            }
-            else {
-                initialArtifact = assertLaunchdDirectRemovalOwner(initialNamespace.inspection.artifacts, nativeId);
-            }
-            let resolvedNativeId = initialArtifact?.nativeId ?? nativeId;
-            const file = plistPath(resolvedNativeId);
-            const snapshot = snapshotLaunchdBindings([resolvedNativeId], {
-                exec,
-                fsLike,
-                agentsDir,
-                plistPath,
-                target,
-                label,
-            });
-            const finalArtifact = expected
-                ? assertSchedulerNativeArtifactCardinality(snapshot.artifacts, nativeId, 1)
-                : assertLaunchdDirectRemovalOwner(snapshot.artifacts, nativeId);
-            if (expected) {
-                if (!finalArtifact) {
-                    throw new ConfigError(`launchd artifact ${JSON.stringify(nativeId)} disappeared during snapshot.`, "INVALID_CONFIG_FILE");
-                }
-                assertSchedulerRemovalArtifact(finalArtifact.nativeId, expected, finalArtifact.invocation, finalArtifact.fingerprint);
-            }
-            if (!finalArtifact)
-                return;
-            resolvedNativeId = finalArtifact.nativeId;
+        install(task, opts) {
+            const xml = xmlFor(task, opts);
+            const nativeId = schedulerBindingNativeId(task);
+            const file = plistPath(nativeId);
+            fsLike.ensureDir(agentsDir);
+            // launchd refuses to start a job whose StandardOutPath directory is
+            // missing; create it before touching launchd state.
+            fsLike.ensureDir(logDir);
+            const tempFile = path.join(agentsDir, `.${nativeId}.${Date.now()}.tmp`);
+            fsLike.writeFile(tempFile, xml);
             try {
-                runOrThrow(exec, ["launchctl", "bootout", target(resolvedNativeId)], {
-                    isOk: (r) => r.status === 0 || isServiceNotFoundResult(r),
-                    message: (r) => `launchctl bootout failed (exit ${r.status}): ${r.stderr || r.stdout || "no output"}.`,
+                bootout(nativeId);
+                fsLike.replaceFile(tempFile, file);
+                // A disable override survives bootout and plist replacement. Clear it
+                // before bootstrap, then apply the desired state after registration.
+                setEnableState(nativeId, true);
+                runOrThrow(exec, ["launchctl", "bootstrap", `gui/${exec.uid()}`, file], {
+                    message: (r) => `launchctl bootstrap failed (exit ${r.status}): ${r.stderr || r.stdout || "no output"}.`,
+                    hint: "Ensure `launchctl` is available; on macOS it is part of the base system.",
                 });
-                // launchctl disable overrides persist after the plist is removed.
-                setEnableState(resolvedNativeId, true);
-                if (fsLike.exists(file))
-                    fsLike.removeFile(file);
+                if (!task.enabled)
+                    setEnableState(nativeId, false);
             }
-            catch (primaryError) {
-                try {
-                    const rollbackExpected = [
-                        launchdRollbackExpectationForCurrent(resolvedNativeId, inspectionContext, initialArtifact),
-                    ];
-                    restoreLaunchdBindings(snapshot, { exec, fsLike, agentsDir, plistPath, target, label, setEnableState }, rollbackExpected);
-                }
-                catch (rollbackError) {
-                    throw new AggregateError([primaryError, rollbackError], `${errorMessage(primaryError)}; rollback for launchd removal ${JSON.stringify(nativeId)} was incomplete.`);
-                }
-                throw primaryError;
+            finally {
+                if (fsLike.exists(tempFile))
+                    fsLike.removeFile(tempFile);
             }
         },
+        uninstall(nativeId) {
+            bootout(nativeId);
+            // launchctl disable overrides persist after the plist is removed.
+            setEnableState(nativeId, true);
+            const file = plistPath(nativeId);
+            if (fsLike.exists(file))
+                fsLike.removeFile(file);
+        },
         setEnabled(nativeId, enabled) {
             setEnableState(nativeId, enabled);
         },
         list() {
-            return [
-                ...inspectLaunchdState({ exec, fsLike, agentsDir, plistPath, target, label }).installed,
-            ];
-        },
-        listForRebind() {
-            const namespace = inspectStableLaunchdNamespace([], { exec, fsLike, agentsDir, plistPath, target, label });
-            const refs = [];
-            for (const entry of namespace.entries) {
-                if (entry.plist === undefined)
+            const domain = exec.run(["launchctl", "print", `gui/${exec.uid()}`]);
+            if (domain.status !== 0) {
+                throw new ConfigError(`launchctl failed to enumerate the loaded user domain: ${domain.stderr || domain.stdout || "no output"}.`, "INVALID_CONFIG_FILE");
+            }
+            const loadedLabels = parseLaunchdLoadedLabels(domain.stdout);
+            const disabledLabels = readDisabledLabels(exec);
+            const rows = [];
+            if (!fsLike.exists(agentsDir))
+                return rows;
+            for (const file of fsLike.list(agentsDir).sort()) {
+                if (!file.startsWith(LAUNCHD_LABEL_PREFIX) || !file.endsWith(".plist"))
+                    continue;
+                const nativeId = file.slice(LAUNCHD_LABEL_PREFIX.length, -".plist".length);
+                const raw = fsLike.readFile(plistPath(nativeId));
+                const parsed = extractPlistInvocation(raw);
+                if (!parsed)
                     continue;
-                const installed = extractPlistInvocation(entry.plist);
-                const id = entry.nativeId;
-                const ref = {
-                    id: installed ? schedulerLogicalBindingId(id, installed.invocation) : id,
-                    ...(installed?.target !== undefined ? { target: installed.target } : {}),
-                };
-                Object.defineProperty(ref, "nativeId", { value: id });
-                if (installed)
-                    Object.defineProperty(ref, "invocation", { value: Object.freeze([...installed.invocation]) });
-                refs.push(ref);
+                const enabled = !disabledLabels.has(label(nativeId));
+                const loaded = loadedLabels.has(label(nativeId));
+                rows.push({
+                    id: schedulerLogicalBindingId(nativeId, parsed.invocation),
+                    nativeId,
+                    enabled: enabled && loaded,
+                    // An unloaded service or a disable override is drift: the signature
+                    // carries both, so sync bootstraps/enables it again.
+                    signature: launchdFingerprint(raw, enabled, loaded),
+                    ...(parsed.target !== undefined ? { target: parsed.target } : {}),
+                    binding: parsed.binding,
+                    contextPath: parsed.contextPath,
+                    invocation: parsed.invocation,
+                });
             }
-            return refs;
-        },
-        listNativeArtifacts() {
-            return [...inspectLaunchdState({ exec, fsLike, agentsDir, plistPath, target, label }).artifacts];
-        },
-        inspectBindings() {
-            return inspectLaunchdState({ exec, fsLike, agentsDir, plistPath, target, label });
-        },
-        snapshotBindings(ids) {
-            return snapshotLaunchdBindings(ids, { exec, fsLike, agentsDir, plistPath, target, label });
-        },
-        restoreBindings(snapshot, expectedCurrent) {
-            restoreLaunchdBindings(snapshot, { exec, fsLike, agentsDir, plistPath, target, label, setEnableState }, expectedCurrent);
+            return rows;
         },
         expectedSignature(task, opts) {
-            return launchdFingerprint(buildPlistXml(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.contextPath ?? defaultContextPath, opts?.target), task.enabled, true);
+            return launchdFingerprint(xmlFor(task, opts), task.enabled, true);
         },
     };
 }
-function installLaunchdBinding(task, opts, expected, context) {
-    const { exec, fsLike, agentsDir, logDir, akmArgv, defaultContextPath, plistPath, label, target, setEnableState } = context;
-    if (expected)
-        assertSchedulerExpectationIdentity(expected, task);
-    // 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, [...(opts?.binding ?? akmArgv)], logDir, opts?.contextPath ?? defaultContextPath, opts?.target);
-    const nativeId = schedulerBindingNativeId(task);
-    const file = plistPath(nativeId);
-    fsLike.ensureDir(agentsDir);
-    // launchd refuses to start a job when StandardOutPath/StandardErrorPath
-    // points at a non-existent directory; create it before reading or mutating
-    // launchd state so a local preparation failure has no scheduler side effect.
-    fsLike.ensureDir(logDir);
-    const inspectionContext = { exec, fsLike, agentsDir, plistPath, target, label };
-    const initialNamespace = inspectStableLaunchdNamespace([nativeId], inspectionContext);
-    const initialArtifact = expected
-        ? assertSchedulerNativeArtifactCardinality(initialNamespace.inspection.artifacts, nativeId, expected.state === "absent" ? 0 : 1)
-        : assertLaunchdDirectMutationOwner(initialNamespace.inspection.artifacts, nativeId, task);
-    if (expected)
-        assertSchedulerMutationArtifact(initialArtifact, expected);
-    const priorEntry = initialArtifact
-        ? initialNamespace.entries.find((entry) => entry.nativeId === initialArtifact.nativeId)
-        : undefined;
-    const previousPlist = priorEntry?.plist;
-    const previousEnabled = priorEntry?.enabled ?? true;
-    const tempFile = path.join(agentsDir, `.${nativeId}.${Date.now()}.tmp`);
-    fsLike.writeFile(tempFile, xml);
-    let bootoutCompleted = false;
-    let previousWasLoaded = false;
-    let fileReplaced = false;
-    let enableStateTouched = false;
-    try {
-        if (expected) {
-            const finalInspection = inspectStableLaunchdNamespace([nativeId], inspectionContext).inspection;
-            const finalArtifact = assertSchedulerNativeArtifactCardinality(finalInspection.artifacts, nativeId, expected.state === "absent" ? 0 : 1);
-            assertSchedulerMutationArtifact(finalArtifact, expected);
-        }
-        else {
-            const finalArtifact = assertLaunchdDirectMutationOwner(inspectStableLaunchdNamespace([nativeId], inspectionContext).inspection.artifacts, nativeId, task);
-            if (finalArtifact?.nativeId !== initialArtifact?.nativeId ||
-                finalArtifact?.fingerprint !== initialArtifact?.fingerprint) {
-                throw new ConfigError(`launchd task ${JSON.stringify(nativeId)} changed while it was being prepared; refusing to replace an unverified owner.`, "INVALID_CONFIG_FILE");
-            }
-        }
-        const bootout = runOrThrow(exec, ["launchctl", "bootout", target(nativeId)], {
-            isOk: (r) => r.status === 0 || isServiceNotFoundResult(r),
-            message: (r) => `launchctl bootout failed (exit ${r.status}): ${r.stderr || r.stdout || "no output"}.`,
-        });
-        bootoutCompleted = true;
-        previousWasLoaded = previousPlist !== undefined && bootout.status === 0;
-        fsLike.replaceFile(tempFile, file);
-        fileReplaced = true;
-        // A disable override survives bootout and plist replacement. Clear it
-        // before bootstrap, then apply the desired state after registration.
-        enableStateTouched = true;
-        setEnableState(nativeId, true);
-        runOrThrow(exec, ["launchctl", "bootstrap", `gui/${exec.uid()}`, file], {
-            message: (r) => `launchctl bootstrap failed (exit ${r.status}): ${r.stderr || r.stdout || "no output"}.`,
-            hint: "Ensure `launchctl` is available; on macOS it is part of the base system.",
-        });
-        if (!task.enabled)
-            setEnableState(nativeId, false);
-    }
-    catch (err) {
-        if (!bootoutCompleted)
-            throw err;
-        const rollbackErrors = [];
-        let priorFileRestored = !fileReplaced;
-        if (fileReplaced) {
-            let replacementUnloaded = false;
-            try {
-                const rollbackBootout = exec.run(["launchctl", "bootout", target(nativeId)]);
-                replacementUnloaded = rollbackBootout.status === 0 || isServiceNotFoundResult(rollbackBootout);
-                if (!replacementUnloaded) {
-                    rollbackErrors.push(new ConfigError(`launchctl bootout during rollback failed: ${rollbackBootout.stderr || rollbackBootout.stdout || "no output"}.`, "INVALID_CONFIG_FILE"));
-                }
-            }
-            catch (rollbackError) {
-                rollbackErrors.push(rollbackError);
-            }
-            if (replacementUnloaded) {
-                try {
-                    if (previousPlist === undefined) {
-                        if (fsLike.exists(file))
-                            fsLike.removeFile(file);
-                    }
-                    else {
-                        fsLike.writeFile(tempFile, previousPlist);
-                        fsLike.replaceFile(tempFile, file);
-                    }
-                    priorFileRestored = true;
-                }
-                catch (rollbackError) {
-                    rollbackErrors.push(rollbackError);
-                }
-            }
-        }
-        restoreLaunchdInstallState({
-            exec,
-            nativeId,
-            file,
-            previousPlist,
-            previousEnabled,
-            previousWasLoaded,
-            priorFileRestored,
-            enableStateTouched,
-            setEnableState,
-            rollbackErrors,
-        });
-        if (rollbackErrors.length > 0) {
-            const message = err instanceof Error ? err.message : String(err);
-            throw new AggregateError([err, ...rollbackErrors], `${message}; rollback for launchd task "${task.id}" was incomplete.`);
-        }
-        throw err;
-    }
-    finally {
-        if (fsLike.exists(tempFile))
-            fsLike.removeFile(tempFile);
-    }
-}
-function restoreLaunchdInstallState(input) {
-    const { exec, nativeId, file, previousPlist, previousEnabled, previousWasLoaded, priorFileRestored, enableStateTouched, setEnableState, rollbackErrors, } = input;
-    if (previousPlist !== undefined && previousWasLoaded && priorFileRestored) {
-        try {
-            setEnableState(nativeId, true);
-            const restore = exec.run(["launchctl", "bootstrap", `gui/${exec.uid()}`, file]);
-            if (restore.status !== 0) {
-                rollbackErrors.push(new ConfigError(`launchctl bootstrap during rollback failed: ${restore.stderr || restore.stdout || "no output"}.`, "INVALID_CONFIG_FILE"));
-            }
-        }
-        catch (rollbackError) {
-            rollbackErrors.push(rollbackError);
-        }
-        if (!previousEnabled) {
-            try {
-                setEnableState(nativeId, false);
-            }
-            catch (rollbackError) {
-                rollbackErrors.push(rollbackError);
-            }
-        }
-    }
-    else if (enableStateTouched) {
-        try {
-            setEnableState(nativeId, previousPlist === undefined || previousEnabled);
-        }
-        catch (rollbackError) {
-            rollbackErrors.push(rollbackError);
-        }
-    }
-}
-function snapshotLaunchdBindings(ids, context) {
-    const requestedKeys = new Set(ids.map(schedulerNativeArtifactKey));
-    const namespace = inspectStableLaunchdNamespace(ids, context);
-    const matchingEntries = namespace.entries.filter((entry) => requestedKeys.has(schedulerNativeArtifactKey(entry.nativeId)));
-    const matchedKeys = new Set(matchingEntries.map((entry) => schedulerNativeArtifactKey(entry.nativeId)));
-    const entries = [
-        ...matchingEntries.map((entry) => Object.freeze({
-            id: entry.nativeId,
-            ...(entry.plist !== undefined ? { plist: entry.plist } : {}),
-            loaded: entry.loaded,
-            enabled: entry.enabled,
-        })),
-        ...ids
-            .filter((id) => !matchedKeys.has(schedulerNativeArtifactKey(id)))
-            .map((id) => Object.freeze({ id, loaded: false, enabled: true })),
-    ];
-    const artifacts = matchingEntries.map((entry) => entry.artifact);
-    return Object.freeze({
-        kind: LAUNCHD_SNAPSHOT,
-        nativeIds: Object.freeze([...ids]),
-        artifacts: Object.freeze(artifacts),
-        entries: Object.freeze(entries),
-    });
-}
-function restoreLaunchdBindings(snapshot, context, expectedCurrent) {
-    if (!isLaunchdBindingSnapshot(snapshot)) {
-        throw new ConfigError("Invalid launchd scheduler snapshot.", "INVALID_CONFIG_FILE");
-    }
-    const preflightErrors = [];
-    const duplicateSnapshotKeys = new Set();
-    const requestedIdsByKey = new Map();
-    for (const nativeId of snapshot.nativeIds) {
-        const key = schedulerNativeArtifactKey(nativeId);
-        const priorId = requestedIdsByKey.get(key);
-        if (priorId !== undefined) {
-            duplicateSnapshotKeys.add(key);
-            preflightErrors.push(new ConfigError(`Launchd scheduler snapshot requests normalized duplicate artifacts ${JSON.stringify(priorId)} and ${JSON.stringify(nativeId)}; refusing restore.`, "INVALID_CONFIG_FILE"));
-            continue;
-        }
-        requestedIdsByKey.set(key, nativeId);
-    }
-    const snapshotEntryIdsByKey = new Map();
-    for (const entry of snapshot.entries) {
-        const key = schedulerNativeArtifactKey(entry.id);
-        const priorId = snapshotEntryIdsByKey.get(key);
-        if (priorId !== undefined) {
-            if (duplicateSnapshotKeys.has(key))
-                continue;
-            duplicateSnapshotKeys.add(key);
-            preflightErrors.push(new ConfigError(`Launchd scheduler snapshot contains normalized duplicate artifacts ${JSON.stringify(priorId)} and ${JSON.stringify(entry.id)}; refusing restore.`, "INVALID_CONFIG_FILE"));
-            continue;
-        }
-        snapshotEntryIdsByKey.set(key, entry.id);
-    }
-    let rollbackInventory;
-    try {
-        rollbackInventory = inspectStableLaunchdNamespace(snapshot.nativeIds, context).inspection;
-    }
-    catch (error) {
-        preflightErrors.push(error);
-    }
-    if (preflightErrors.length > 0) {
-        throw new AggregateError(preflightErrors, `Failed to preflight ${preflightErrors.length} launchd scheduler restore operation(s).`);
-    }
-    const expectationsById = new Map();
-    const expectationIdsByKey = new Map();
-    if (expectedCurrent) {
-        for (const expected of expectedCurrent) {
-            const key = schedulerNativeArtifactKey(expected.nativeId);
-            const priorExact = expectationsById.get(expected.nativeId);
-            const priorKeyId = expectationIdsByKey.get(key);
-            if (priorExact !== undefined || priorKeyId !== undefined) {
-                preflightErrors.push(new ConfigError(`Launchd rollback expectations contain duplicate normalized artifact ${JSON.stringify(expected.nativeId)}.`, "INVALID_CONFIG_FILE"));
-                continue;
-            }
-            expectationsById.set(expected.nativeId, expected);
-            expectationIdsByKey.set(key, expected.nativeId);
-        }
-    }
-    const plannedEntries = [];
-    const coveredExpectationIds = new Set();
-    if (rollbackInventory) {
-        for (const entry of snapshot.entries) {
-            if (duplicateSnapshotKeys.has(schedulerNativeArtifactKey(entry.id)))
-                continue;
-            try {
-                let current;
-                if (expectedCurrent) {
-                    const expected = expectationsById.get(entry.id);
-                    if (!expected) {
-                        throw new ConfigError(`Missing launchd rollback expectation for ${JSON.stringify(entry.id)}.`, "INVALID_CONFIG_FILE");
-                    }
-                    coveredExpectationIds.add(entry.id);
-                    current = assertSchedulerRollbackArtifactCardinality(rollbackInventory.artifacts, expected);
-                }
-                else {
-                    const currentCount = rollbackInventory.artifacts.filter((artifact) => schedulerNativeArtifactKey(artifact.nativeId) === schedulerNativeArtifactKey(entry.id)).length;
-                    current = assertSchedulerNativeArtifactCardinality(rollbackInventory.artifacts, entry.id, currentCount === 0 ? 0 : 1);
-                    if (current !== undefined && current.nativeId !== entry.id) {
-                        throw new ConfigError(`Launchd scheduler artifact ${JSON.stringify(entry.id)} changed to case- or suffix-equivalent spelling ${JSON.stringify(current.nativeId)} before restore.`, "INVALID_CONFIG_FILE");
-                    }
-                }
-                if (entry.loaded && entry.plist === undefined) {
-                    assertUnrestorableLaunchdSnapshotUnchanged(entry, rollbackInventory.artifacts);
-                }
-                plannedEntries.push(Object.freeze({
-                    entry,
-                    immediateExpectation: launchdRollbackExpectationFromArtifact(entry.id, current),
-                    noOp: entry.loaded && entry.plist === undefined,
-                }));
-            }
-            catch (error) {
-                preflightErrors.push(error);
-            }
-        }
-    }
-    if (expectedCurrent) {
-        for (const expected of expectedCurrent) {
-            if (!coveredExpectationIds.has(expected.nativeId)) {
-                preflightErrors.push(new ConfigError(`Unexpected launchd rollback expectation for ${JSON.stringify(expected.nativeId)} is not covered by the snapshot.`, "INVALID_CONFIG_FILE"));
-            }
-        }
-    }
-    if (preflightErrors.length > 0) {
-        throw new AggregateError(preflightErrors, `Failed to preflight ${preflightErrors.length} launchd scheduler restore operation(s).`);
-    }
-    const errors = [];
-    for (const planned of plannedEntries) {
-        if (planned.noOp)
-            continue;
-        try {
-            const immediateInventory = inspectStableLaunchdNamespace(snapshot.nativeIds, context).inspection;
-            assertSchedulerRollbackArtifactCardinality(immediateInventory.artifacts, planned.immediateExpectation);
-        }
-        catch (error) {
-            errors.push(error);
-            continue;
-        }
-        restoreLaunchdBindingEntry(planned.entry, context, errors);
-    }
-    if (errors.length > 0) {
-        throw new AggregateError(errors, `Failed to completely restore ${errors.length} launchd scheduler operation(s).`);
-    }
-}
-function launchdRollbackExpectationFromArtifact(nativeId, current) {
-    if (current === undefined) {
-        return Object.freeze({ nativeId, allowed: Object.freeze([{ state: "absent" }]) });
-    }
-    if (current.nativeId !== nativeId || current.fingerprint === undefined) {
-        throw new ConfigError(`Launchd scheduler artifact ${JSON.stringify(nativeId)} has no exact restorable fingerprint.`, "INVALID_CONFIG_FILE");
-    }
-    return Object.freeze({
-        nativeId,
-        allowed: Object.freeze([
-            Object.freeze({
-                state: "present",
-                ...(current.bindingId !== undefined ? { bindingId: current.bindingId } : {}),
-                ...(current.invocation !== undefined ? { invocation: current.invocation } : {}),
-                fingerprint: current.fingerprint,
-            }),
-        ]),
-    });
-}
-function assertUnrestorableLaunchdSnapshotUnchanged(entry, currentArtifacts) {
-    const current = assertSchedulerNativeArtifactCardinality(currentArtifacts, entry.id, 1);
-    const expectedFingerprint = launchdMissingPlistArtifact(entry.id, entry.enabled, entry.loaded).fingerprint;
-    if (current?.nativeId !== entry.id ||
-        current.invocation !== undefined ||
-        current.bindingId !== undefined ||
-        current.fingerprint !== expectedFingerprint) {
-        throw new ConfigError(`Loaded launchd artifact ${JSON.stringify(entry.id)} has no restorable plist and changed after its snapshot; refusing mutation.`, "INVALID_CONFIG_FILE");
-    }
-}
-/**
- * Enumerate the current launchd AKM service namespace (loaded domain members,
- * print-disabled labels, and on-disk plists) in one pass.
- *
- * This used to run the enumeration twice and fail closed if the two passes
- * disagreed, guarding against launchd state mutating between the two
- * `launchctl` shell-outs (milliseconds apart, in-process). The only actor
- * that could cause that is another concurrent akm process or the user
- * running launchctl by hand at that exact instant; a subsequent `task sync`
- * (idempotent by design) reconciles any such drift on its own, so the
- * two-pass fencing added a TOCTOU-shaped guard around a race with a working
- * self-heal already in place, not a way to avoid one.
- */
-function inspectStableLaunchdNamespace(seedIds, context) {
-    const domain = context.exec.run(["launchctl", "print", `gui/${context.exec.uid()}`]);
-    if (domain.status !== 0) {
-        throw new ConfigError(`launchctl failed to enumerate the loaded user domain during scheduler state inspection: ${domain.stderr || domain.stdout || "no output"}.`, "INVALID_CONFIG_FILE");
-    }
-    const loadedLabels = parseLaunchdLoadedLabels(domain.stdout);
-    const disabledLabels = readDisabledLabels(context.exec);
-    const akmDisabledLabels = [...disabledLabels].filter((label) => label.startsWith(LAUNCHD_LABEL_PREFIX)).sort();
-    const plistEntries = [];
-    if (context.fsLike.exists(context.agentsDir)) {
-        for (const file of context.fsLike.list(context.agentsDir).sort()) {
-            if (!file.startsWith(LAUNCHD_LABEL_PREFIX) || !file.endsWith(".plist"))
-                continue;
-            const nativeId = file.slice(LAUNCHD_LABEL_PREFIX.length, -".plist".length);
-            plistEntries.push(Object.freeze([nativeId, context.fsLike.readFile(context.plistPath(nativeId))]));
-        }
-    }
-    const ids = new Set(seedIds);
-    for (const [nativeId] of plistEntries)
-        ids.add(nativeId);
-    for (const serviceLabel of loadedLabels)
-        ids.add(serviceLabel.slice(LAUNCHD_LABEL_PREFIX.length));
-    for (const serviceLabel of akmDisabledLabels)
-        ids.add(serviceLabel.slice(LAUNCHD_LABEL_PREFIX.length));
-    const plistByNativeId = new Map(plistEntries);
-    const entries = [];
-    for (const nativeId of [...ids].sort()) {
-        const serviceLabel = context.label(nativeId);
-        const plist = plistByNativeId.get(nativeId);
-        const enabled = !disabledLabels.has(serviceLabel);
-        const loaded = loadedLabels.has(serviceLabel);
-        if (plist === undefined && enabled && !loaded)
-            continue;
-        const artifact = plist === undefined
-            ? launchdMissingPlistArtifact(nativeId, enabled, loaded)
-            : launchdArtifact(nativeId, plist, enabled, loaded);
-        entries.push(Object.freeze({ nativeId, ...(plist !== undefined ? { plist } : {}), enabled, loaded, artifact }));
-    }
-    const artifacts = entries.map((entry) => entry.artifact);
-    const installed = [];
-    for (const entry of entries) {
-        if (entry.plist === undefined)
-            continue;
-        const parsed = extractPlistInvocation(entry.plist);
-        if (!parsed)
-            continue;
-        installed.push(withInstalledInvocation({
-            id: schedulerLogicalBindingId(entry.nativeId, parsed.invocation),
-            enabled: entry.enabled && entry.loaded,
-            ...(entry.loaded ? { signature: entry.artifact.fingerprint } : {}),
-            ...(parsed.target !== undefined ? { target: parsed.target } : {}),
-            binding: parsed.binding,
-            contextPath: parsed.contextPath,
-        }, parsed.invocation, entry.nativeId));
-    }
-    return Object.freeze({
-        inspection: Object.freeze({ installed: Object.freeze(installed), artifacts: Object.freeze(artifacts) }),
-        entries: Object.freeze(entries),
-    });
-}
-function restoreLaunchdBindingEntry(entry, context, errors) {
-    try {
-        runOrThrow(context.exec, ["launchctl", "bootout", context.target(entry.id)], {
-            isOk: (result) => result.status === 0 || isServiceNotFoundResult(result),
-            message: (result) => `launchctl bootout failed while restoring task "${entry.id}": ${result.stderr || result.stdout || "no output"}.`,
-        });
-    }
-    catch (error) {
-        errors.push(error);
-        return;
-    }
-    const file = context.plistPath(entry.id);
-    let priorFileRestored = false;
-    try {
-        if (entry.plist === undefined) {
-            if (context.fsLike.exists(file))
-                context.fsLike.removeFile(file);
-        }
-        else {
-            context.fsLike.ensureDir(context.agentsDir);
-            context.fsLike.writeFile(file, entry.plist);
-        }
-        priorFileRestored = true;
-    }
-    catch (error) {
-        errors.push(error);
-    }
-    if (entry.loaded && entry.plist !== undefined && priorFileRestored) {
-        let overrideCleared = false;
-        try {
-            // A disable override survives bootout. Clear it before bootstrap or
-            // launchd can refuse to register the exact prior loaded definition.
-            context.setEnableState(entry.id, true);
-            overrideCleared = true;
-        }
-        catch (error) {
-            errors.push(error);
-        }
-        if (overrideCleared) {
-            try {
-                runOrThrow(context.exec, ["launchctl", "bootstrap", `gui/${context.exec.uid()}`, file], {
-                    message: (result) => `launchctl bootstrap failed while restoring task "${entry.id}": ${result.stderr || result.stdout || "no output"}.`,
-                });
-            }
-            catch (error) {
-                errors.push(error);
-            }
-        }
-    }
-    try {
-        // Apply the prior override last even when an earlier step failed; this is
-        // both the exact state ordering and the best available partial recovery.
-        context.setEnableState(entry.id, entry.enabled);
-    }
-    catch (error) {
-        errors.push(error);
-    }
-}
-function isLaunchdBindingSnapshot(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        value.kind === LAUNCHD_SNAPSHOT &&
-        Array.isArray(value.entries));
-}
-function inspectLaunchdState(context) {
-    return inspectStableLaunchdNamespace([], context).inspection;
-}
-function assertLaunchdDirectMutationOwner(artifacts, nativeId, task) {
-    const key = schedulerNativeArtifactKey(nativeId);
-    const count = artifacts.filter((artifact) => schedulerNativeArtifactKey(artifact.nativeId) === key).length;
-    const artifact = assertSchedulerNativeArtifactCardinality(artifacts, nativeId, count === 0 ? 0 : 1);
-    if (artifact)
-        assertSchedulerNativeArtifactOwner(artifact.nativeId, task, artifact.invocation);
-    return artifact;
-}
-function assertLaunchdDirectRemovalOwner(artifacts, nativeId) {
-    const key = schedulerNativeArtifactKey(nativeId);
-    const count = artifacts.filter((artifact) => schedulerNativeArtifactKey(artifact.nativeId) === key).length;
-    const artifact = assertSchedulerNativeArtifactCardinality(artifacts, nativeId, count === 0 ? 0 : 1);
-    if (!artifact)
-        return undefined;
-    if (artifact.nativeId !== nativeId || artifact.invocation === undefined) {
-        throw new ConfigError(`launchd artifact ${JSON.stringify(artifact.nativeId)} is not the exact proven requested owner ${JSON.stringify(nativeId)}; refusing direct removal.`, "INVALID_CONFIG_FILE");
-    }
-    return artifact;
-}
-function launchdRollbackExpectationForCurrent(nativeId, context, priorArtifact) {
-    const namespace = inspectStableLaunchdNamespace([nativeId], context);
-    const key = schedulerNativeArtifactKey(nativeId);
-    const count = namespace.inspection.artifacts.filter((artifact) => schedulerNativeArtifactKey(artifact.nativeId) === key).length;
-    const artifact = assertSchedulerNativeArtifactCardinality(namespace.inspection.artifacts, nativeId, count === 0 ? 0 : 1);
-    if (!artifact) {
-        return Object.freeze({ nativeId, allowed: Object.freeze([{ state: "absent" }]) });
-    }
-    if (artifact.fingerprint === undefined ||
-        artifact.invocation === undefined ||
-        priorArtifact?.invocation === undefined ||
-        !sameStringArray(artifact.invocation, priorArtifact.invocation)) {
-        throw new ConfigError(`launchd artifact ${JSON.stringify(nativeId)} has no exact transaction-owned rollback fingerprint.`, "INVALID_CONFIG_FILE");
-    }
-    return Object.freeze({
-        nativeId,
-        allowed: Object.freeze([
-            Object.freeze({
-                state: "present",
-                ...(artifact.bindingId !== undefined ? { bindingId: artifact.bindingId } : {}),
-                invocation: Object.freeze([...artifact.invocation]),
-                fingerprint: artifact.fingerprint,
-            }),
-        ]),
-    });
-}
-function sameStringArray(left, right) {
-    return left.length === right.length && left.every((value, index) => value === right[index]);
-}
-function errorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}
-function launchdMissingPlistArtifact(nativeId, enabled, loaded) {
-    const artifact = { nativeId };
-    Object.defineProperty(artifact, "fingerprint", {
-        value: `launchd:missing-plist:enabled=${enabled}:loaded=${loaded}`,
-    });
-    return artifact;
-}
-function launchdArtifact(nativeId, raw, enabled, loaded) {
-    const parsed = extractPlistInvocation(raw);
-    const owner = parsed ? schedulerLogicalBindingOwner(nativeId, parsed.invocation) : undefined;
-    const artifact = parsed
-        ? {
-            nativeId,
-            ...(owner !== undefined ? { bindingId: owner } : {}),
-            invocation: Object.freeze([...parsed.invocation]),
-        }
-        : { nativeId };
-    if (enabled !== undefined && loaded !== undefined) {
-        Object.defineProperty(artifact, "fingerprint", { value: launchdFingerprint(raw, enabled, loaded) });
-    }
-    return artifact;
-}
 function launchdFingerprint(raw, enabled, loaded) {
     const signed = raw.replace(/<!-- akm-enabled:(?:true|false) -->/, `<!-- akm-enabled:${enabled} -->`);
-    return `${normalizeSignature(signed)}:loaded=${loaded}`;
-}
-function withInstalledInvocation(ref, invocation, nativeId) {
-    Object.defineProperty(ref, "nativeId", { value: nativeId });
-    Object.defineProperty(ref, "invocation", { value: Object.freeze([...invocation]) });
-    return ref;
-}
-function launchdDefaultContextPath(options, scheduledContext) {
-    const pathEnv = options.envPath === false
-        ? undefined
-        : typeof options.envPath === "string"
-            ? options.envPath
-            : (process.env.PATH ?? "");
-    return schedulerContextPath(schedulerContextDescriptor(scheduledContext, pathEnv ?? ""));
-}
-function setLaunchdEnableState(exec, nativeTarget, enabled) {
-    const verb = enabled ? "enable" : "disable";
-    runOrThrow(exec, ["launchctl", verb, nativeTarget], {
-        message: (result) => `launchctl ${verb} failed: ${result.stderr || result.stdout || "no output"}.`,
-    });
+    return `${signed.replace(/\r\n/g, "\n").trim()}:loaded=${loaded}`;
 }
 export function extractPlistInvocation(xml) {
     const block = xml.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/);
@@ -748,25 +161,31 @@ function decodeXmlEntities(value) {
         .replaceAll("&amp;", "&");
 }
 // ── XML builder (exported for tests) ────────────────────────────────────────
-export function buildPlistXml(task, akmArgv, logDir, contextPath, _target) {
-    const spec = parseSchedule(task.cron, "launchd");
-    const trigger = translateToLaunchd(spec);
+function renderPlistEnvironment(envPath) {
+    if (!envPath)
+        return "";
+    return [
+        "  <key>EnvironmentVariables</key>",
+        "  <dict>",
+        "    <key>PATH</key>",
+        `    <string>${escapeXml(envPath)}</string>`,
+        "  </dict>",
+        "",
+    ].join("\n");
+}
+export function buildPlistXml(task, akmArgv, logDir, contextPath, envPath) {
+    const trigger = translateToLaunchd(parseSchedule(task.cron, "launchd"));
     const invocation = buildScheduledBindingInvocation(akmArgv, contextPath, task.invocation);
-    const argv = invocation.argv;
-    const programArgs = argv.map((a) => `      <string>${escapeXml(a)}</string>`).join("\n");
+    const programArgs = invocation.argv.map((a) => `      <string>${escapeXml(a)}</string>`).join("\n");
     const nativeId = schedulerBindingNativeId(task);
     const logPath = path.join(logDir, `${nativeId}.log`);
-    const triggerXml = renderLaunchdTrigger(trigger);
-    const executionEvidence = task.executionEvidenceDigest === undefined
-        ? ""
-        : `  <!-- akm-workflow-evidence:${assertSchedulerExecutionEvidenceDigest(task.executionEvidenceDigest)} -->\n`;
     const xml = launchdTemplate
-        .replace("<dict>\n", `<dict>\n  <!-- akm-enabled:${task.enabled} -->\n${executionEvidence}`)
+        .replace("<dict>\n", `<dict>\n  <!-- akm-enabled:${task.enabled} -->\n`)
         .replace("{{LABEL}}", LAUNCHD_LABEL_PREFIX + escapeXml(nativeId))
         .replace("{{PROGRAM_ARGS}}", programArgs)
         .replaceAll("{{LOG_PATH}}", escapeXml(logPath))
-        .replace("{{ENV_VARS}}", "")
-        .replace("{{TRIGGER_XML}}", triggerXml);
+        .replace("{{ENV_VARS}}", renderPlistEnvironment(envPath))
+        .replace("{{TRIGGER_XML}}", renderLaunchdTrigger(trigger));
     for (const char of xml) {
         const code = char.codePointAt(0) ?? 0;
         if (code <= 0x08 || code === 0x0b || code === 0x0c || (code >= 0x0e && code <= 0x1f)) {
@@ -778,22 +197,18 @@ export function buildPlistXml(task, akmArgv, logDir, contextPath, _target) {
 function renderLaunchdTrigger(trigger) {
     if (trigger.calendars !== undefined) {
         const lines = ["  <key>StartCalendarInterval</key>", "  <array>"];
-        for (const calendar of trigger.calendars) {
+        for (const calendar of trigger.calendars)
             lines.push(...renderCalendar(calendar, "    "));
-        }
         lines.push("  </array>");
         return lines.join("\n");
     }
-    const cal = trigger.calendar ?? {};
-    const lines = ["  <key>StartCalendarInterval</key>", ...renderCalendar(cal, "  ")];
-    return lines.join("\n");
+    return ["  <key>StartCalendarInterval</key>", ...renderCalendar(trigger.calendar ?? {}, "  ")].join("\n");
 }
 function renderCalendar(calendar, indent) {
     const valueIndent = `${indent}  `;
     const lines = [`${indent}<dict>`];
-    if (calendar.Minute !== undefined) {
+    if (calendar.Minute !== undefined)
         lines.push(`${valueIndent}<key>Minute</key><integer>${calendar.Minute}</integer>`);
-    }
     if (calendar.Hour !== undefined)
         lines.push(`${valueIndent}<key>Hour</key><integer>${calendar.Hour}</integer>`);
     if (calendar.Day !== undefined)
@@ -806,49 +221,25 @@ function renderCalendar(calendar, indent) {
     lines.push(`${indent}</dict>`);
     return lines;
 }
-function normalizeSignature(xml) {
-    return xml.replace(/\r\n/g, "\n").trim();
-}
 /**
  * Collect the akm-owned service labels present in `launchctl` output.
  *
- * This reads the CURRENT USER'S OWN scheduler inventory — the tasks they asked
- * akm to schedule, on their own machine. It is not an attacker-controlled
- * document, so it is parsed permissively: scan for labels in our own
- * `com.akm.task.` namespace and ignore everything else.
- *
- * It previously enforced a rigid grammar over the whole document and returned
- * `undefined` — surfacing as a hard INVALID_CONFIG_FILE that refused to inspect
- * scheduler state at all — if ANY line failed to match. Real
- * `launchctl print gui/<uid>` output on macOS is far richer than that grammar
- * allowed, so on a real Mac this rejected the user's own inventory and broke
- * every launchd operation. Caught by the gated native-scheduler suite, which
- * had never been dispatched before.
- *
- * The two bounds that remain are real resource bounds, not structural ones: a
- * cap on how much output we will read, and a cap on how many distinct akm
- * labels we will track. Exceeding either still returns `undefined`.
+ * This reads the CURRENT USER'S OWN scheduler inventory, so it is parsed
+ * permissively: scan for labels in our own `com.akm.task.` namespace and
+ * ignore everything else.
  */
 export function parseLaunchdLoadedLabels(output) {
     const labels = new Set();
-    // Our own namespace is the only thing we look for. `[^\s"{}=,()]` stops the
-    // token at whatever punctuation the surrounding launchctl syntax uses, so a
-    // label works whether it appears as a bare table cell, a quoted string, or a
-    // dictionary key.
-    const labelPattern = /com\.akm\.task\.[^\s"{}=,()]+/gu;
-    for (const match of boundLaunchdOutput(output).matchAll(labelPattern)) {
-        const label = match[0];
-        if (!LAUNCHD_AKM_LABEL_RE.test(label))
-            continue;
-        labels.add(label);
-        if (labels.size >= MAX_LAUNCHD_AKM_NAMESPACE_ENTRIES)
-            break;
+    // `[^\s"{}=,()]` stops the token at whatever punctuation the surrounding
+    // launchctl syntax uses, so a label works whether it appears as a bare
+    // table cell, a quoted string, or a dictionary key.
+    for (const match of output.matchAll(/com\.akm\.task\.[^\s"{}=,()]+/gu)) {
+        if (LAUNCHD_AKM_LABEL_RE.test(match[0]))
+            labels.add(match[0]);
     }
     return labels;
 }
-function boundLaunchdOutput(output) {
-    return output.length > MAX_LAUNCHD_DOMAIN_OUTPUT_BYTES ? output.slice(0, MAX_LAUNCHD_DOMAIN_OUTPUT_BYTES) : output;
-}
+/** `print-disabled` failing or looking unfamiliar degrades to "nothing is disabled". */
 function readDisabledLabels(exec) {
     try {
         const result = exec.run(["launchctl", "print-disabled", `gui/${exec.uid()}`]);
@@ -856,35 +247,25 @@ function readDisabledLabels(exec) {
             warn("[akm] launchctl print-disabled exited %d; assuming no akm task is disabled.", result.status);
             return new Set();
         }
-        return parseDisabledLabels(result.stdout);
+        const disabled = new Set();
+        const entryPattern = /"(com\.akm\.task\.[^"\r\n]+)"\s*=>\s*(true|false|enabled|disabled)/gu;
+        for (const match of result.stdout.matchAll(entryPattern)) {
+            const label = match[1];
+            if (LAUNCHD_AKM_LABEL_RE.test(label) && (match[2] === "true" || match[2] === "disabled"))
+                disabled.add(label);
+        }
+        return disabled;
     }
     catch (error) {
         warn("[akm] launchctl print-disabled could not be run; assuming no akm task is disabled: %s", error instanceof Error ? error.message : String(error));
         return new Set();
     }
 }
-function parseDisabledLabels(output) {
-    const disabled = new Set();
-    const entryPattern = /"(com\.akm\.task\.[^"\r\n]+)"\s*=>\s*(true|false|enabled|disabled)/gu;
-    for (const match of boundLaunchdOutput(output).matchAll(entryPattern)) {
-        const label = match[1];
-        if (!LAUNCHD_AKM_LABEL_RE.test(label))
-            continue;
-        if (match[2] === "true" || match[2] === "disabled")
-            disabled.add(label);
-        if (disabled.size >= MAX_LAUNCHD_AKM_NAMESPACE_ENTRIES)
-            break;
-    }
-    return disabled;
-}
 function isServiceNotFoundResult(result) {
     const output = `${result.stderr ?? ""}\n${result.stdout ?? ""}`;
     return /could not find service\b|service\b.*\bnot found\b|\bno such process\b/i.test(output);
 }
 function defaultAgentsDir() {
-    // launchd's per-user LaunchAgents live under the user's home directory.
-    // If we can't determine HOME, refuse rather than silently producing a
-    // 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 task` on macOS.");
@@ -917,9 +298,8 @@ function defaultLaunchdFs() {
                 return fs.readdirSync(dir);
             }
             catch (error) {
-                // Genuinely absent is an empty listing; anything else (e.g. EACCES) is
-                // not "no plists" — surfacing it as such could make inspectBindings
-                // think there is nothing to reconcile.
+                // Genuinely absent is an empty listing; anything else (e.g. EACCES)
+                // is not "no plists".
                 if (hasErrnoCode(error, "ENOENT"))
                     return [];
                 throw new ConfigError(`Unable to read LaunchAgents directory at "${dir}".`, "INVALID_CONFIG_FILE");