akm-cli 0.9.1 → 0.9.2-alpha.2

package/dist/tasks/backends/launchd.js

@@ -29,9 +29,14 @@ 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, parseScheduledTaskArgv, resolveScheduledTaskContext, schedulerContextDescriptor, schedulerContextPath, } from "../scheduler-invocation.js";
+import { assertSchedulerExecutionEvidenceDigest, assertSchedulerExpectationIdentity, assertSchedulerMutationArtifact, assertSchedulerNativeArtifactCardinality, assertSchedulerNativeArtifactOwner, assertSchedulerRemovalArtifact, assertSchedulerRollbackArtifactCardinality, schedulerBindingNativeId, schedulerLogicalBindingId, schedulerLogicalBindingOwner, schedulerNativeArtifactKey, } 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();
@@ -39,240 +44,708 @@ export function LAUNCHD_BACKEND(options = {}) {
     const logDir = options.logDir ?? getTaskLogDir();
     const akmArgv = options.akmArgv ?? resolveAkmInvocation().argv;
     const scheduledContext = options.scheduledContext ?? resolveScheduledTaskContext();
-    const plistPath = (id) => path.join(agentsDir, `${LAUNCHD_LABEL_PREFIX}${id}.plist`);
-    const label = (id) => `${LAUNCHD_LABEL_PREFIX}${id}`;
-    const target = (id) => `gui/${exec.uid()}/${label(id)}`;
-    const pathEnv = () => {
-        if (options.envPath === false)
-            return undefined;
-        if (typeof options.envPath === "string")
-            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)], {
-            message: (r) => `launchctl ${verb} failed: ${r.stderr || r.stdout || "no output"}.`,
-        });
-    };
+    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);
     return {
         name: "launchd",
-        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, [...(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;
-            if (previousPlist !== undefined) {
-                const disabledLabels = readDisabledLabels(exec);
-                if (disabledLabels === undefined) {
-                    throw new ConfigError(`launchctl print-disabled failed; cannot safely replace existing task "${task.id}".`, "INVALID_CONFIG_FILE");
+        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");
                 }
-                previousEnabled = !disabledLabels.has(label(task.id));
+                assertSchedulerRemovalArtifact(initialArtifact.nativeId, expected, initialArtifact.invocation, initialArtifact.fingerprint);
             }
-            fsLike.ensureDir(agentsDir);
-            // launchd refuses to start a job when StandardOutPath/StandardErrorPath
-            // points at a non-existent directory; create it before bootstrap.
-            fsLike.ensureDir(logDir);
-            const tempFile = path.join(agentsDir, `.${task.id}.${Date.now()}.tmp`);
-            fsLike.writeFile(tempFile, xml);
-            let bootoutCompleted = false;
-            let previousWasLoaded = false;
-            let fileReplaced = false;
-            let enableStateTouched = false;
+            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;
             try {
-                const bootout = runOrThrow(exec, ["launchctl", "bootout", target(task.id)], {
+                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"}.`,
                 });
-                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(task.id, 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(task.id, false);
-                }
+                // launchctl disable overrides persist after the plist is removed.
+                setEnableState(resolvedNativeId, true);
+                if (fsLike.exists(file))
+                    fsLike.removeFile(file);
             }
-            catch (err) {
-                if (!bootoutCompleted)
-                    throw err;
-                const rollbackErrors = [];
-                let priorFileRestored = !fileReplaced;
-                if (fileReplaced) {
-                    let replacementUnloaded = false;
-                    try {
-                        const rollbackBootout = exec.run(["launchctl", "bootout", target(task.id)]);
-                        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);
-                        }
-                    }
-                }
-                if (previousPlist !== undefined && previousWasLoaded && priorFileRestored) {
-                    try {
-                        setEnableState(task.id, 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(task.id, false);
-                        }
-                        catch (rollbackError) {
-                            rollbackErrors.push(rollbackError);
-                        }
-                    }
-                }
-                else if (enableStateTouched) {
-                    try {
-                        setEnableState(task.id, previousPlist === undefined || previousEnabled);
-                    }
-                    catch (rollbackError) {
-                        rollbackErrors.push(rollbackError);
-                    }
+            catch (primaryError) {
+                try {
+                    const rollbackExpected = [
+                        launchdRollbackExpectationForCurrent(resolvedNativeId, inspectionContext, initialArtifact),
+                    ];
+                    restoreLaunchdBindings(snapshot, { exec, fsLike, agentsDir, plistPath, target, label, setEnableState }, rollbackExpected);
                 }
-                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.`);
+                catch (rollbackError) {
+                    throw new AggregateError([primaryError, rollbackError], `${errorMessage(primaryError)}; rollback for launchd removal ${JSON.stringify(nativeId)} was incomplete.`);
                 }
-                throw err;
+                throw primaryError;
             }
-            finally {
-                if (fsLike.exists(tempFile))
-                    fsLike.removeFile(tempFile);
-            }
-        },
-        uninstall(id) {
-            runOrThrow(exec, ["launchctl", "bootout", target(id)], {
-                isOk: (r) => r.status === 0 || isServiceNotFoundResult(r),
-                message: (r) => `launchctl bootout failed (exit ${r.status}): ${r.stderr || r.stdout || "no output"}.`,
-            });
-            // launchctl disable overrides persist after the plist is removed.
-            setEnableState(id, true);
-            const file = plistPath(id);
-            if (fsLike.exists(file))
-                fsLike.removeFile(file);
         },
-        setEnabled(id, enabled) {
-            setEnableState(id, enabled);
+        setEnabled(nativeId, enabled) {
+            setEnableState(nativeId, enabled);
         },
         list() {
-            if (!fsLike.exists(agentsDir))
-                return [];
-            const ids = [];
-            for (const file of fsLike.list(agentsDir)) {
-                if (file.startsWith(LAUNCHD_LABEL_PREFIX) && file.endsWith(".plist")) {
-                    ids.push(file.slice(LAUNCHD_LABEL_PREFIX.length, -".plist".length));
-                }
-            }
-            if (ids.length === 0)
-                return [];
-            const disabledLabels = readDisabledLabels(exec);
-            return ids
-                .map((id) => inspectInstalledLaunchdTask(id, fsLike.readFile(plistPath(id)), disabledLabels, exec))
-                .filter((ref) => ref !== undefined);
+            return [
+                ...inspectLaunchdState({ exec, fsLike, agentsDir, plistPath, target, label }).installed,
+            ];
         },
         listForRebind() {
-            if (!fsLike.exists(agentsDir))
-                return [];
+            const namespace = inspectStableLaunchdNamespace([], { exec, fsLike, agentsDir, plistPath, target, label });
             const refs = [];
-            for (const file of fsLike.list(agentsDir)) {
-                if (!file.startsWith(LAUNCHD_LABEL_PREFIX) || !file.endsWith(".plist"))
+            for (const entry of namespace.entries) {
+                if (entry.plist === undefined)
                     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 } : {}) });
+                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);
             }
             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);
+        },
         expectedSignature(task, opts) {
-            return normalizeSignature(buildPlistXml(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.contextPath ?? defaultContextPath, opts?.target));
+            return launchdFingerprint(buildPlistXml(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.contextPath ?? defaultContextPath, opts?.target), task.enabled, true);
         },
     };
 }
-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}`;
+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 {
-        const loaded = exec.run(["launchctl", "print", `gui/${exec.uid()}/${jobLabel}`]);
-        if (loaded.status !== 0)
-            return { id, ...metadata };
+        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 {
-        return { id, ...metadata };
+    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 {
-        const xml = raw.replace(/<!-- akm-enabled:(?:true|false) -->/, `<!-- akm-enabled:${!disabledLabels.has(jobLabel)} -->`);
-        return {
-            id,
-            signature: normalizeSignature(xml),
-            ...metadata,
-        };
+        rollbackInventory = inspectStableLaunchdNamespace(snapshot.nativeIds, context).inspection;
     }
-    catch {
-        return { id, ...metadata };
+    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).`);
     }
 }
-/**
- * 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;
+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");
+    }
+}
+function inspectStableLaunchdNamespace(seedIds, context) {
+    const first = captureLaunchdNamespacePass(seedIds, context);
+    const second = captureLaunchdNamespacePass(seedIds, context);
+    if (first.stabilityKey !== second.stabilityKey) {
+        throw new ConfigError("The launchd AKM service namespace changed while scheduler state was being stabilized.", "INVALID_CONFIG_FILE");
+    }
+    return second.namespace;
+}
+function captureLaunchdNamespacePass(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);
+    if (loadedLabels === undefined) {
+        throw new ConfigError("launchctl returned an unsafe, unsupported, or oversized loaded-service inventory during scheduler state inspection.", "INVALID_CONFIG_FILE");
+    }
+    const disabledLabels = readDisabledLabels(context.exec);
+    if (disabledLabels === undefined) {
+        throw new ConfigError("launchctl print-disabled failed during scheduler state inspection.", "INVALID_CONFIG_FILE");
+    }
+    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));
+    if (ids.size > MAX_LAUNCHD_AKM_NAMESPACE_ENTRIES) {
+        throw new ConfigError(`launchd AKM scheduler inventory exceeds ${MAX_LAUNCHD_AKM_NAMESPACE_ENTRIES} namespace entries.`, "INVALID_CONFIG_FILE");
+    }
+    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),
+            ...(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({
+        namespace: Object.freeze({
+            inspection: Object.freeze({ installed: Object.freeze(installed), artifacts: Object.freeze(artifacts) }),
+            entries: Object.freeze(entries),
+        }),
+        stabilityKey: JSON.stringify({
+            loadedLabels: [...loadedLabels].sort(),
+            disabledLabels: akmDisabledLabels,
+            plistEntries,
+        }),
+    });
+}
+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"}.`,
+    });
 }
 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);
+    return parseScheduledBindingArgv(args);
 }
 function decodeXmlEntities(value) {
     return value
@@ -283,17 +756,21 @@ function decodeXmlEntities(value) {
         .replaceAll("&amp;", "&");
 }
 // ── XML builder (exported for tests) ────────────────────────────────────────
-export function buildPlistXml(task, akmArgv, logDir, contextPath, target) {
-    const spec = parseSchedule(task.schedule, "launchd");
+export function buildPlistXml(task, akmArgv, logDir, contextPath, _target) {
+    const spec = parseSchedule(task.cron, "launchd");
     const trigger = translateToLaunchd(spec);
-    const invocation = buildScheduledTaskInvocation(akmArgv, task.id, contextPath, target);
+    const invocation = buildScheduledBindingInvocation(akmArgv, contextPath, task.invocation);
     const argv = invocation.argv;
     const programArgs = argv.map((a) => `      <string>${escapeXml(a)}</string>`).join("\n");
-    const logPath = path.join(logDir, `${task.id}.log`);
+    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`)
-        .replace("{{LABEL}}", LAUNCHD_LABEL_PREFIX + escapeXml(task.id))
+        .replace("<dict>\n", `<dict>\n  <!-- akm-enabled:${task.enabled} -->\n${executionEvidence}`)
+        .replace("{{LABEL}}", LAUNCHD_LABEL_PREFIX + escapeXml(nativeId))
         .replace("{{PROGRAM_ARGS}}", programArgs)
         .replaceAll("{{LOG_PATH}}", escapeXml(logPath))
         .replace("{{ENV_VARS}}", "")
@@ -340,6 +817,114 @@ function renderCalendar(calendar, indent) {
 function normalizeSignature(xml) {
     return xml.replace(/\r\n/g, "\n").trim();
 }
+/** Parse only proven loaded-service labels from bounded launchctl domain/list output. */
+export function parseLaunchdLoadedLabels(output) {
+    if (Buffer.byteLength(output, "utf8") > MAX_LAUNCHD_DOMAIN_OUTPUT_BYTES || hasUnsafeLaunchdControlCharacter(output)) {
+        return undefined;
+    }
+    const lines = output.replace(/\r\n?/gu, "\n").split("\n");
+    const labels = new Set();
+    let akmEntryCount = 0;
+    const add = (label) => {
+        if (!LAUNCHD_AKM_LABEL_RE.test(label))
+            return false;
+        akmEntryCount += 1;
+        if (akmEntryCount > MAX_LAUNCHD_AKM_NAMESPACE_ENTRIES || labels.has(label))
+            return false;
+        labels.add(label);
+        return true;
+    };
+    const firstContent = lines.findIndex((line) => line.trim() !== "");
+    if (firstContent >= 0 && /^PID\s+Status\s+Label$/iu.test(lines[firstContent].trim())) {
+        for (const line of lines.slice(firstContent + 1)) {
+            if (!line.trim())
+                continue;
+            const row = /^\s*(?:-|\d+)\s+-?\d+\s+(\S+)\s*$/u.exec(line);
+            if (!row?.[1])
+                return undefined;
+            if (row[1].startsWith(LAUNCHD_LABEL_PREFIX) && !add(row[1]))
+                return undefined;
+        }
+        return labels;
+    }
+    const firstLine = firstContent < 0 ? undefined : lines[firstContent];
+    if (firstLine === undefined || !/^\s*(?:gui|user)\/\d+\s*=\s*\{\s*$/u.test(firstLine))
+        return undefined;
+    let lastContent = lines.length - 1;
+    while (lastContent >= 0 && !lines[lastContent]?.trim())
+        lastContent -= 1;
+    const lastLine = lines[lastContent];
+    if (lastContent <= firstContent || lastLine === undefined || !/^\s*\}\s*$/u.test(lastLine))
+        return undefined;
+    let depth = 1;
+    let servicesSeen = false;
+    let insideServices = false;
+    for (let index = firstContent + 1; index <= lastContent; index += 1) {
+        const line = lines[index];
+        if (index === lastContent) {
+            if (insideServices || depth !== 1)
+                return undefined;
+            depth = 0;
+            continue;
+        }
+        const servicesBlock = /^\s*services\s*=\s*\{\s*$/u.test(line);
+        const emptyServicesBlock = /^\s*services\s*=\s*\{\s*\}\s*$/u.test(line);
+        if (servicesBlock || emptyServicesBlock) {
+            if (servicesSeen || insideServices || depth !== 1)
+                return undefined;
+            servicesSeen = true;
+            if (servicesBlock) {
+                insideServices = true;
+                depth += 1;
+            }
+            continue;
+        }
+        if (/^\s*services\s*=/u.test(line))
+            return undefined;
+        if (insideServices && depth === 2) {
+            if (!line.trim())
+                continue;
+            if (/^\s*\}\s*$/u.test(line)) {
+                insideServices = false;
+                depth -= 1;
+                continue;
+            }
+            const assignment = /^\s*-?\d+\s*=\s*"?([^"\s{}=]+)"?\s*$/u.exec(line);
+            const domainTable = /^\s*(?:-|\d+)\s+(?:-|-?\d+)\s+(\S+)\s*$/u.exec(line);
+            const dictionary = /^\s*"?([^"\s{}=]+)"?\s*=\s*\{\s*$/u.exec(line);
+            const candidate = assignment?.[1] ?? domainTable?.[1] ?? dictionary?.[1];
+            if (!candidate)
+                return undefined;
+            if (candidate.startsWith(LAUNCHD_LABEL_PREFIX) && !add(candidate))
+                return undefined;
+            if (dictionary)
+                depth += 1;
+            continue;
+        }
+        if (line.includes(LAUNCHD_LABEL_PREFIX))
+            return undefined;
+        depth += countCharacter(line, "{") - countCharacter(line, "}");
+        if (depth < 1 || (insideServices && depth < 2))
+            return undefined;
+    }
+    return servicesSeen && depth === 0 ? labels : undefined;
+}
+function countCharacter(value, needle) {
+    let count = 0;
+    for (const character of value)
+        if (character === needle)
+            count += 1;
+    return count;
+}
+function hasUnsafeLaunchdControlCharacter(output) {
+    for (let index = 0; index < output.length; index += 1) {
+        const code = output.charCodeAt(index);
+        if (code <= 8 || code === 11 || code === 12 || (code >= 14 && code <= 31) || (code >= 127 && code <= 159)) {
+            return true;
+        }
+    }
+    return false;
+}
 function readDisabledLabels(exec) {
     try {
         const result = exec.run(["launchctl", "print-disabled", `gui/${exec.uid()}`]);