@mono-agent/agent-app 0.11.2 → 0.11.4

package/dist/background.js

@@ -1,21 +1,24 @@
 import { spawn } from "node:child_process";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
-import { lstat, mkdir, open, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { lstat, mkdir, open, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 import process from "node:process";
 import { listRecordedRuns, listTraceSources } from "@mono-agent/observability";
 import { describeSensitiveDataExportWarning, phoenixAppBaseUrl, resolveAppTraceRegistryDir, resolveAppTraceStaleAfterMs, } from "./app-config.js";
 import { formatChannelFactValue } from "./channel-fact-format.js";
-import { bootout, bootstrap, buildPlistXml, defaultPathEnv, deriveLaunchdLabel, isLoaded, launchdServiceInfo, launchdPathsFor, makeLaunchctlRunner, } from "./launchd.js";
+import { bootout, bootstrap, buildLaunchdMaintenancePlistXml, buildPlistXml, defaultPathEnv, deriveLaunchdLabel, deriveLaunchdMaintenanceLabel, isLoaded, launchdServiceInfo, launchdPathsFor, MANAGED_LAUNCHD_LOG_MAINTENANCE_ENV, makeLaunchctlRunner, } from "./launchd.js";
 import { selectBackgroundOperationalEnvironment } from "./background-environment.js";
+import { beginLaunchdLogMaintenanceIntent, clearLaunchdLogMaintenanceIntent, inspectLaunchdLogs, LAUNCHD_LOG_MAINTENANCE_INTERVAL_SECONDS, markLaunchdLogMaintenanceRestoring, markLaunchdLogMaintenanceStopped, markLaunchdLogMaintenanceStopping, readLaunchdLogMaintenanceIntent, rotateStoppedLaunchdLogs, } from "./launchd-logs.js";
 import { ensureManagedBackgroundRuntime, MANAGED_BACKGROUND_WORKER_ENV, } from "./background-runtime.js";
 import { backgroundSnapshotFromMetadata, captureBackgroundSnapshot, encodeBackgroundSnapshot, sameBackgroundSnapshot, } from "./background-snapshot.js";
 import { resolveConfiguredManagedRuntimePackages } from "./managed-runtime-packages.js";
-import { currentProcessIncarnation, isSameProcessIncarnation as matchesProcessIncarnation, processIncarnationFromJson, } from "./process-incarnation.js";
+import { processIncarnationFromJson, } from "./process-incarnation.js";
+import { acquireOwnerPrivateLock, validateOwnerPrivateLockInputs } from "./owner-private-lock.js";
 import { buildRunsHealthDisplay, RUNS_HEALTH_MAX_RUNS } from "./runs-health.js";
 import * as ui from "./ui.js";
 export { acquireBackgroundWorkerLease, backgroundWorkerLeasePath, } from "./background-worker-lease.js";
+export { LAUNCHD_LOG_MAX_BYTES, LAUNCHD_LOG_ROTATION_COUNT, } from "./launchd-logs.js";
 /** Exact non-secret environment materialised into a managed LaunchAgent. */
 export function managedBackgroundEnvironment(env) {
     return {
@@ -26,6 +29,16 @@ export function managedBackgroundEnvironment(env) {
         [MANAGED_BACKGROUND_WORKER_ENV]: "1",
     };
 }
+/** Exact non-secret environment for the scheduled one-shot log maintainer. */
+export function managedLaunchdLogMaintenanceEnvironment(env) {
+    return {
+        ...selectBackgroundOperationalEnvironment(env),
+        // This unattended helper needs only pinned system tools. Do not persist a
+        // caller-controlled PATH that could shadow launchctl on a later run.
+        PATH: "/usr/bin:/bin",
+        [MANAGED_LAUNCHD_LOG_MAINTENANCE_ENV]: "1",
+    };
+}
 /**
  * Resolve everything the control commands need from CLI args. The registry dir
  * and config path are resolved exactly as the worker will resolve them, so the
@@ -101,8 +114,21 @@ export function defaultBackgroundDeps() {
         writeFile: writeOwnerPrivateLaunchdFile,
         mkdir: ensureOwnerPrivateLaunchdDirectory,
         rm: (path) => rm(path, { force: true }),
-        stat: inspectOwnerPrivateLaunchdLog,
-        rename,
+        inspectLaunchdLogs: async (paths) => await inspectLaunchdLogs(paths),
+        rotateStoppedLaunchdLogs: async (paths) => {
+            await rotateStoppedLaunchdLogs(paths);
+        },
+        readLaunchdLogMaintenanceIntent: async (paths) => await readLaunchdLogMaintenanceIntent(paths),
+        beginLaunchdLogMaintenanceIntent: async (paths, intent) => {
+            await beginLaunchdLogMaintenanceIntent(paths, intent);
+        },
+        markLaunchdLogMaintenanceStopped: async (paths, expected) => await markLaunchdLogMaintenanceStopped(paths, expected),
+        markLaunchdLogMaintenanceRestoring: async (paths, expected) => await markLaunchdLogMaintenanceRestoring(paths, expected),
+        markLaunchdLogMaintenanceStopping: async (paths, expected) => await markLaunchdLogMaintenanceStopping(paths, expected),
+        clearLaunchdLogMaintenanceIntent: async (paths, expected) => {
+            await clearLaunchdLogMaintenanceIntent(paths, expected);
+        },
+        verifyLaunchdPlist: inspectOwnerPrivateLaunchdPlist,
         isAlive: (pid) => {
             try {
                 process.kill(pid, 0);
@@ -131,8 +157,6 @@ export function defaultBackgroundDeps() {
     };
 }
 const DEFAULT_POLL = { timeoutMs: 18_000, intervalMs: 400 };
-export const LAUNCHD_LOG_MAX_BYTES = 5 * 1024 * 1024;
-export const LAUNCHD_LOG_ROTATION_COUNT = 3;
 export async function startBackground(target, deps, poll = DEFAULT_POLL) {
     return (await ensureBackgroundReady(target, deps, poll)).ok ? 0 : 1;
 }
@@ -165,6 +189,213 @@ export async function forceRestartBackground(target, deps, whileStopped, poll =
         });
     }
 }
+/**
+ * Private one-shot invoked only by the scheduled maintenance LaunchAgent. It
+ * never creates or rewrites a service definition. It does not resurrect an
+ * intentionally stopped service; the sole exception is recovery authorized by
+ * its own durable lifecycle intent after a prior maintainer died post-bootout.
+ */
+export async function maintainLaunchdLogs(target, deps, poll = DEFAULT_POLL) {
+    const release = await deps.acquireLifecycleLock(target);
+    if (release === undefined) {
+        // Controller start/restart/stop owns the same lock. Skipping this periodic
+        // pass is expected and avoids making launchd record a false maintenance
+        // failure; the next interval retries from a fresh inventory.
+        return 0;
+    }
+    try {
+        const uid = deps.getuid();
+        const service = await launchdServiceInfo(deps.runner, target.label, uid);
+        let inspection;
+        try {
+            inspection = await deps.inspectLaunchdLogs(target.paths);
+        }
+        catch (error) {
+            reportMaintenanceFailure(target, deps, "inspect launchd logs", error);
+            return 1;
+        }
+        let maintenanceIntent;
+        try {
+            maintenanceIntent = await deps.readLaunchdLogMaintenanceIntent(target.paths);
+        }
+        catch (error) {
+            reportMaintenanceFailure(target, deps, "read durable launchd-log maintenance intent", error);
+            return 1;
+        }
+        if (inspection.pendingMaintenance && maintenanceIntent === undefined) {
+            reportMaintenanceFailure(target, deps, "read durable launchd-log maintenance intent", new Error("The maintenance marker disappeared after inventory."));
+            return 1;
+        }
+        if (!service.loaded && maintenanceIntent === undefined)
+            return 0;
+        let originalPlistIdentity;
+        try {
+            originalPlistIdentity = await deps.verifyLaunchdPlist(target.paths.plistPath);
+        }
+        catch (error) {
+            reportMaintenanceFailure(target, deps, "verify the existing main LaunchAgent", error);
+            return 1;
+        }
+        if (maintenanceIntent !== undefined
+            && (maintenanceIntent.label !== target.label
+                || maintenanceIntent.plistFingerprint !== originalPlistIdentity)) {
+            reportMaintenanceFailure(target, deps, "authenticate durable launchd-log maintenance intent", new Error("The pending intent does not match the exact main LaunchAgent definition."));
+            return 1;
+        }
+        if (maintenanceIntent?.phase === "stopping" && !service.loaded) {
+            reportMaintenanceFailure(target, deps, "recover interrupted launchd-log maintenance", new Error("The prior maintainer did not durably prove every old writer PID dead; refusing rotation."));
+            return 1;
+        }
+        if (maintenanceIntent?.phase === "restoring") {
+            const replacement = await launchdServiceInfo(deps.runner, target.label, uid);
+            if (!replacement.loaded || replacement.pid === undefined || !deps.isAlive(replacement.pid)) {
+                reportMaintenanceFailure(target, deps, "recover interrupted launchd-log restoration", new Error("The replacement writer identity was lost before live-worker proof; refusing stale rotation authority."));
+                return 1;
+            }
+            try {
+                await deps.clearLaunchdLogMaintenanceIntent(target.paths, maintenanceIntent);
+            }
+            catch (error) {
+                reportMaintenanceFailure(target, deps, "clear recovered launchd-log restoration intent", error);
+                return 1;
+            }
+            return 0;
+        }
+        if (maintenanceIntent?.phase === "stopped" && service.loaded) {
+            reportMaintenanceFailure(target, deps, "recover interrupted launchd-log maintenance", new Error("launchd reports a writer loaded after durable stopped-writer proof; refusing rotation."));
+            return 1;
+        }
+        if (!inspection.canMaintain) {
+            deps.stderr(ui.errorLine(`Scheduled log maintenance refused unsafe paths for ${target.label}.`));
+            for (const issue of inspection.issues)
+                deps.stderr(ui.style.dim(issue) + "\n");
+            return 1;
+        }
+        if (!inspection.needsMaintenance && maintenanceIntent === undefined)
+            return 0;
+        if (maintenanceIntent === undefined) {
+            maintenanceIntent = {
+                version: 1,
+                phase: "stopping",
+                label: target.label,
+                plistFingerprint: originalPlistIdentity,
+            };
+            try {
+                await deps.beginLaunchdLogMaintenanceIntent(target.paths, maintenanceIntent);
+            }
+            catch (error) {
+                reportMaintenanceFailure(target, deps, "publish durable launchd-log maintenance intent", error);
+                return 1;
+            }
+        }
+        if (maintenanceIntent.phase === "stopping") {
+            const stopped = await unloadLaunchdService(target.label, service, uniquePids([service.pid]), deps, uid, poll);
+            if (!stopped.ok) {
+                reportMaintenanceFailure(target, deps, "prove the launchd log writer stopped", stopped.failure);
+                return 1;
+            }
+            try {
+                maintenanceIntent = await deps.markLaunchdLogMaintenanceStopped(target.paths, maintenanceIntent);
+            }
+            catch (error) {
+                reportMaintenanceFailure(target, deps, "record durable stopped-writer proof", error);
+                return 1;
+            }
+        }
+        else {
+            const current = await launchdServiceInfo(deps.runner, target.label, uid);
+            if (current.loaded || (current.pid !== undefined && deps.isAlive(current.pid))) {
+                reportMaintenanceFailure(target, deps, "recheck durable stopped-writer proof", new Error("launchd exposed a live writer before recovered rotation."));
+                return 1;
+            }
+        }
+        try {
+            await deps.rotateStoppedLaunchdLogs(target.paths);
+            // Close the pathname-replacement race before handing the definition to
+            // launchctl. A changed/symlinked plist leaves the worker stopped.
+            const currentPlistIdentity = await deps.verifyLaunchdPlist(target.paths.plistPath);
+            if (currentPlistIdentity !== originalPlistIdentity) {
+                throw new Error("The main LaunchAgent plist changed during stopped-writer maintenance.");
+            }
+        }
+        catch (error) {
+            reportMaintenanceFailure(target, deps, "commit bounded stopped-writer logs", error);
+            return 1;
+        }
+        try {
+            maintenanceIntent = await deps.markLaunchdLogMaintenanceRestoring(target.paths, maintenanceIntent);
+        }
+        catch (error) {
+            reportMaintenanceFailure(target, deps, "invalidate stopped-writer proof before restoration", error);
+            return 1;
+        }
+        const booted = await bootstrap(deps.runner, target.paths.plistPath, uid);
+        const observedRestorePids = new Set();
+        const running = await pollUntil(deps, poll, async () => {
+            const current = await launchdServiceInfo(deps.runner, target.label, uid);
+            if (current.pid !== undefined)
+                observedRestorePids.add(current.pid);
+            return current.loaded && current.pid !== undefined && deps.isAlive(current.pid);
+        });
+        if (!running) {
+            const current = await launchdServiceInfo(deps.runner, target.label, uid);
+            if (current.pid !== undefined)
+                observedRestorePids.add(current.pid);
+            const cleanedUp = await unloadLaunchdService(target.label, current, [...observedRestorePids], deps, uid, poll);
+            reportMaintenanceFailure(target, deps, "restore the exact main LaunchAgent after rotation", lifecycleFailure(booted, "launchd did not expose a live replacement worker"));
+            if (!cleanedUp.ok) {
+                reportMaintenanceFailure(target, deps, "remove the failed replacement worker", cleanedUp.failure);
+            }
+            return 1;
+        }
+        try {
+            const restoredPlistIdentity = await deps.verifyLaunchdPlist(target.paths.plistPath);
+            if (restoredPlistIdentity !== originalPlistIdentity) {
+                throw new Error("The main LaunchAgent plist changed while launchd restored the worker.");
+            }
+        }
+        catch (error) {
+            const restoredService = await launchdServiceInfo(deps.runner, target.label, uid);
+            const stoppedAgain = await unloadLaunchdService(target.label, restoredService, uniquePids([restoredService.pid, ...observedRestorePids]), deps, uid, poll);
+            reportMaintenanceFailure(target, deps, "prove the restored main LaunchAgent definition", error);
+            if (!stoppedAgain.ok) {
+                reportMaintenanceFailure(target, deps, "stop the worker after its definition changed", stoppedAgain.failure);
+            }
+            return 1;
+        }
+        try {
+            await deps.clearLaunchdLogMaintenanceIntent(target.paths, maintenanceIntent);
+        }
+        catch (error) {
+            reportMaintenanceFailure(target, deps, "clear durable launchd-log maintenance intent", error);
+            return 1;
+        }
+        return 0;
+    }
+    finally {
+        await release().catch((error) => {
+            deps.stderr(ui.errorLine(`Could not release lifecycle lock for ${target.label}: ${error instanceof Error ? error.message : String(error)}`));
+        });
+    }
+}
+function reportMaintenanceFailure(target, deps, action, error) {
+    deps.stderr(ui.errorLine(`Scheduled log maintenance could not ${action} for ${target.label}: ${maintenanceErrorMessage(error)}`));
+}
+function maintenanceErrorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "object" && error !== null) {
+        const result = error;
+        const detail = [result.stderr, result.stdout]
+            .find((value) => typeof value === "string" && value.trim().length > 0)
+            ?.trim();
+        if (detail !== undefined)
+            return detail;
+        if (typeof result.code === "number")
+            return `launchctl exited ${result.code}`;
+    }
+    return String(error);
+}
 /**
  * Ensure the canonical per-config LaunchAgent is running and return the fresh
  * trace source that proved it reached `startup-complete`. This is the shared
@@ -234,24 +465,50 @@ async function ensureBackgroundReadyUnlocked(target, deps, poll) {
         reportLifecycleException(launchTarget, deps, "verify the existing background worker ownership", error);
         return { ok: false, action: "start", reason: "ownership" };
     }
-    let sinceMs;
+    let sinceMs = deps.now();
     try {
         await prepareLaunchdDirectories(launchTarget, deps);
-        await rotateLaunchdLogs(launchTarget.paths, deps);
-        await writePlist(launchTarget, deps);
-        sinceMs = deps.now();
     }
     catch (error) {
-        reportLifecycleException(launchTarget, deps, "prepare the LaunchAgent", error);
+        reportLifecycleException(launchTarget, deps, "prepare the LaunchAgent directories", error);
         return { ok: false, action: "start", reason: "preparation" };
     }
     let outcome;
+    let prepared = false;
     try {
-        outcome = await bootstrapOrRestart(launchTarget, deps, uid, poll);
+        let interruptedMaintenance = await deps.readLaunchdLogMaintenanceIntent(launchTarget.paths);
+        if (interruptedMaintenance?.phase === "stopping" || interruptedMaintenance?.phase === "restoring") {
+            const current = await launchdServiceInfo(deps.runner, launchTarget.label, uid);
+            if (!current.loaded) {
+                throw new Error("Interrupted launchd-log maintenance lost its writer PID before durable stopped-writer proof; refusing restart.");
+            }
+        }
+        outcome = await bootstrapOrRestart(launchTarget, deps, uid, poll, async () => {
+            const stoppedIntent = interruptedMaintenance;
+            if (stoppedIntent?.phase === "stopped") {
+                interruptedMaintenance = await deps.markLaunchdLogMaintenanceStopping(launchTarget.paths, stoppedIntent);
+            }
+        }, async (mainStopProven) => {
+            const stoppingIntent = interruptedMaintenance;
+            if (stoppingIntent?.phase === "stopping" || stoppingIntent?.phase === "restoring") {
+                if (!mainStopProven) {
+                    throw new Error("The controller could not renew stopped-writer proof for interrupted log maintenance.");
+                }
+                interruptedMaintenance = await deps.markLaunchdLogMaintenanceStopped(launchTarget.paths, stoppingIntent);
+            }
+            await deps.rotateStoppedLaunchdLogs(launchTarget.paths);
+            // A controller may be completing a maintainer that died after bootout.
+            // Once journal recovery finishes under the stopped-writer proof, cancel
+            // its old restore authority before replacing either plist.
+            await deps.clearLaunchdLogMaintenanceIntent(launchTarget.paths, interruptedMaintenance);
+            await writePlists(launchTarget, deps);
+            sinceMs = deps.now();
+            prepared = true;
+        });
     }
     catch (error) {
-        reportLifecycleException(launchTarget, deps, "start the LaunchAgent", error);
-        return { ok: false, action: "start", reason: "launchctl" };
+        reportLifecycleException(launchTarget, deps, prepared ? "start the LaunchAgent" : "prepare the stopped LaunchAgent", error);
+        return { ok: false, action: "start", reason: prepared ? "launchctl" : "preparation" };
     }
     const action = outcome.restarted ? "restart" : "start";
     if (!outcome.ok) {
@@ -297,11 +554,12 @@ async function prepareLaunchdDirectories(target, deps) {
     await deps.mkdir(target.paths.logDir);
     await deps.mkdir(target.paths.launchAgentsDir);
 }
-async function writePlist(target, deps) {
+async function writePlists(target, deps) {
     if (target.expectedSnapshot === undefined) {
         throw new Error("A managed LaunchAgent requires an approved background snapshot.");
     }
-    const xml = buildPlistXml({
+    const maintenance = maintenancePathsForTarget(target);
+    const mainXml = buildPlistXml({
         label: target.label,
         nodePath: target.nodePath,
         cliPath: target.cliPath,
@@ -313,38 +571,20 @@ async function writePlist(target, deps) {
         stderrPath: target.paths.stderrPath,
         environment: target.environment,
     });
-    await deps.writeFile(target.paths.plistPath, xml);
-}
-async function rotateLaunchdLogs(paths, deps) {
-    await Promise.all([
-        rotateLaunchdLog(paths.stdoutPath, deps),
-        rotateLaunchdLog(paths.stderrPath, deps),
-    ]);
-}
-async function rotateLaunchdLog(path, deps) {
-    let size;
-    try {
-        size = (await deps.stat(path)).size;
-    }
-    catch (error) {
-        if (isErrno(error, "ENOENT"))
-            return;
-        throw error;
-    }
-    if (size <= LAUNCHD_LOG_MAX_BYTES) {
-        return;
-    }
-    await deps.rm(`${path}.${LAUNCHD_LOG_ROTATION_COUNT}`);
-    for (let index = LAUNCHD_LOG_ROTATION_COUNT; index >= 1; index -= 1) {
-        const source = index === 1 ? path : `${path}.${index - 1}`;
-        const destination = `${path}.${index}`;
-        try {
-            await deps.rename(source, destination);
-        }
-        catch {
-            // Missing or locked rotation segment: leave it for the next launch cycle.
-        }
-    }
+    const maintenanceXml = buildLaunchdMaintenancePlistXml({
+        label: maintenance.label,
+        nodePath: target.nodePath,
+        cliPath: target.cliPath,
+        configPath: target.configPath,
+        // The agent folder may be renamed or removed while its already-running
+        // worker still owns log descriptors. Keep the scheduler's cwd in the
+        // durable account state tree; its config argument is already absolute.
+        cwd: dirname(target.paths.logDir),
+        environment: managedLaunchdLogMaintenanceEnvironment(target.environment),
+        intervalSeconds: LAUNCHD_LOG_MAINTENANCE_INTERVAL_SECONDS,
+    });
+    await deps.writeFile(target.paths.plistPath, mainXml);
+    await deps.writeFile(maintenance.plistPath, maintenanceXml);
 }
 async function ensureOwnerPrivateLaunchdDirectory(path) {
     const parent = dirname(path);
@@ -431,27 +671,54 @@ async function writeOwnerPrivateLaunchdFile(path, data) {
         await rm(temporaryPath, { force: true }).catch(() => undefined);
     }
 }
-async function inspectOwnerPrivateLaunchdLog(path) {
-    const handle = await open(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+async function inspectOwnerPrivateLaunchdPlist(path) {
+    const handle = await open(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK);
     try {
         const before = await handle.stat();
-        assertOwnerRegularFile(before, path, "LaunchAgent log");
-        await handle.chmod(0o600);
-        const secured = await handle.stat();
-        if (!sameFilesystemIdentity(before, secured)) {
-            throw new Error(`LaunchAgent log ${path} changed while it was secured.`);
+        assertOwnerRegularFile(before, path, "LaunchAgent plist");
+        if ((before.mode & 0o777) !== 0o600) {
+            throw new Error(`LaunchAgent plist ${path} must be owner-only.`);
+        }
+        if (!Number.isSafeInteger(before.size) || before.size < 1 || before.size > 1024 * 1024) {
+            throw new Error(`LaunchAgent plist ${path} has an unsafe size.`);
+        }
+        const contents = await readExactFileHandle(handle, before.size, "LaunchAgent plist");
+        const after = await handle.stat();
+        assertOwnerRegularFile(after, path, "LaunchAgent plist");
+        if ((after.mode & 0o777) !== 0o600
+            || !sameFileSnapshot(before, after)
+            || contents.length !== before.size) {
+            throw new Error(`LaunchAgent plist ${path} changed while it was read.`);
         }
-        assertOwnerRegularFile(secured, path, "LaunchAgent log");
         const current = await lstat(path);
-        if (!sameFilesystemIdentity(secured, current)) {
-            throw new Error(`LaunchAgent log ${path} changed while it was secured.`);
+        assertOwnerRegularFile(current, path, "LaunchAgent plist");
+        if ((current.mode & 0o777) !== 0o600 || !sameFileSnapshot(after, current)) {
+            throw new Error(`LaunchAgent plist ${path} changed while it was inspected.`);
         }
-        return secured;
+        return [
+            String(after.dev),
+            String(after.ino),
+            String(after.size),
+            createHash("sha256").update(contents).digest("hex"),
+        ].join(":");
     }
     finally {
         await handle.close();
     }
 }
+async function readExactFileHandle(handle, size, description) {
+    if (!Number.isSafeInteger(size) || size < 0)
+        throw new Error(`${description} has an unsafe size.`);
+    const contents = Buffer.alloc(size);
+    let offset = 0;
+    while (offset < size) {
+        const result = await handle.read(contents, offset, size - offset, offset);
+        if (result.bytesRead === 0)
+            throw new Error(`${description} ended while its bounded contents were read.`);
+        offset += result.bytesRead;
+    }
+    return contents;
+}
 function assertOwnerDirectory(details, path, description) {
     if (!details.isDirectory() || details.isSymbolicLink()) {
         throw new Error(`${description} ${path} must be a real directory.`);
@@ -475,52 +742,139 @@ function assertCurrentUserOwns(details, path, description) {
 function sameFilesystemIdentity(left, right) {
     return left.dev === right.dev && left.ino === right.ino;
 }
+function sameFileSnapshot(left, right) {
+    return sameFilesystemIdentity(left, right)
+        && left.uid === right.uid
+        && left.nlink === right.nlink
+        && left.mode === right.mode
+        && left.size === right.size
+        && left.mtimeMs === right.mtimeMs
+        && left.ctimeMs === right.ctimeMs;
+}
 /**
  * Idempotent: bootstrap when not loaded. A loaded job is always fully removed
  * before bootstrap so launchd cannot retain stale ProgramArguments or env from
  * the previous plist.
  */
-async function bootstrapOrRestart(target, deps, uid, poll) {
-    const service = await launchdServiceInfo(deps.runner, target.label, uid);
-    if (!service.loaded) {
-        const booted = await bootstrap(deps.runner, target.paths.plistPath, uid);
-        if (booted.code === 0 || (await isLoaded(deps.runner, target.label, uid))) {
-            return { ok: true, restarted: false };
-        }
-        return { ok: false, restarted: false, failure: booted };
-    }
-    const oldSources = await findInstances(target, deps);
-    const oldPids = uniquePids([
-        service.pid,
-        // A cleanly stopped manifest can outlive its process long enough for the OS
-        // to reuse that pid for unrelated work. It is historical evidence, not an
-        // ownership claim, so never wait for its recycled pid during restart.
-        ...oldSources
-            .filter((source) => source.health !== "stopped")
-            .map((source) => source.pid),
+async function bootstrapOrRestart(target, deps, uid, poll, beforeMainBootout, whileStopped) {
+    const maintenance = maintenancePathsForTarget(target);
+    const [service, maintenanceService] = await Promise.all([
+        launchdServiceInfo(deps.runner, target.label, uid),
+        launchdServiceInfo(deps.runner, maintenance.label, uid),
     ]);
-    const removed = await bootout(deps.runner, target.label, uid);
-    const unloaded = await pollUntil(deps, poll, async () => !(await launchdServiceInfo(deps.runner, target.label, uid)).loaded);
-    if (!unloaded) {
+    const restarted = service.loaded;
+    // Stop the scheduler first. A helper that is already running either holds
+    // this lifecycle lock (so the controller could not enter) or is waiting to
+    // acquire it; bootout plus PID death prevents a post-stop resurrection.
+    const maintenanceStopped = await unloadLaunchdService(maintenance.label, maintenanceService, uniquePids([maintenanceService.pid]), deps, uid, poll);
+    if (!maintenanceStopped.ok) {
+        return { ok: false, restarted, failure: maintenanceStopped.failure };
+    }
+    let mainStopProven = false;
+    if (service.loaded) {
+        const oldSources = await findInstances(target, deps);
+        const oldPids = uniquePids([
+            service.pid,
+            // A cleanly stopped manifest can outlive its process long enough for the OS
+            // to reuse that pid for unrelated work. It is historical evidence, not an
+            // ownership claim, so never wait for its recycled pid during restart.
+            ...oldSources
+                .filter((source) => source.health !== "stopped")
+                .map((source) => source.pid),
+        ]);
+        const mainStopped = await unloadLaunchdService(target.label, service, oldPids, deps, uid, poll, beforeMainBootout);
+        if (!mainStopped.ok) {
+            const restoreFailure = await restoreMaintenanceDefinition(maintenanceService.loaded, maintenance, deps, uid, poll);
+            return {
+                ok: false,
+                restarted: true,
+                failure: restoreFailure === undefined
+                    ? mainStopped.failure
+                    : lifecycleFailure(mainStopped.failure, `scheduled maintenance restoration failed: ${maintenanceErrorMessage(restoreFailure)}`),
+            };
+        }
+        mainStopProven = true;
+    }
+    await whileStopped(mainStopProven);
+    const maintenanceBooted = await bootstrap(deps.runner, maintenance.plistPath, uid);
+    const maintenanceLoaded = await pollUntil(deps, poll, async () => await isLoaded(deps.runner, maintenance.label, uid));
+    if (!maintenanceLoaded) {
         return {
             ok: false,
-            restarted: true,
-            failure: lifecycleFailure(removed, "launchd still reports the previous service as loaded after bootout"),
+            restarted,
+            failure: lifecycleFailure(maintenanceBooted, "scheduled log maintenance did not report loaded"),
         };
     }
-    const stopped = await pollUntil(deps, poll, async () => oldPids.every((pid) => !deps.isAlive(pid)));
-    if (!stopped) {
+    const booted = await bootstrap(deps.runner, target.paths.plistPath, uid);
+    if (booted.code === 0 || (await isLoaded(deps.runner, target.label, uid))) {
+        return { ok: true, restarted };
+    }
+    const maintenanceServiceAfterFailure = await launchdServiceInfo(deps.runner, maintenance.label, uid);
+    const maintenanceRemoval = await unloadLaunchdService(maintenance.label, maintenanceServiceAfterFailure, uniquePids([maintenanceServiceAfterFailure.pid]), deps, uid, poll);
+    return {
+        ok: false,
+        restarted,
+        failure: lifecycleFailure(booted, maintenanceRemoval.ok
+            ? "main service did not load; scheduled maintenance was unloaded"
+            : `main service did not load; scheduled maintenance cleanup failed: ${maintenanceErrorMessage(maintenanceRemoval.failure)}`),
+    };
+}
+async function unloadLaunchdService(label, service, ownedPids, deps, uid, poll, beforeLoadedBootout) {
+    const observedPids = new Set(uniquePids([service.pid, ...ownedPids]));
+    try {
+        await beforeLoadedBootout?.();
+    }
+    catch (error) {
         return {
             ok: false,
-            restarted: true,
-            failure: lifecycleFailure(removed, `previous worker pid(s) ${oldPids.join(", ")} remained alive after bootout`),
+            failure: { code: 1, stdout: "", stderr: maintenanceErrorMessage(error) },
         };
     }
-    const booted = await bootstrap(deps.runner, target.paths.plistPath, uid);
-    if (booted.code === 0 || (await isLoaded(deps.runner, target.label, uid))) {
-        return { ok: true, restarted: true };
+    // Refresh immediately before bootout. The caller may have spent time on
+    // inventory or plist verification while KeepAlive replaced its entry PID.
+    let current = await launchdServiceInfo(deps.runner, label, uid);
+    if (current.pid !== undefined)
+        observedPids.add(current.pid);
+    let removed;
+    if (current.loaded) {
+        removed = await bootout(deps.runner, label, uid);
+    }
+    else {
+        removed = { code: 0, stdout: "", stderr: "" };
+    }
+    // Keep launchd state and process liveness in one predicate. In particular,
+    // retain every KeepAlive replacement pid exposed while bootout converges;
+    // proving only the entry snapshot dead is not a stopped-writer proof.
+    const stopped = await pollUntil(deps, poll, async () => {
+        current = await launchdServiceInfo(deps.runner, label, uid);
+        if (current.pid !== undefined)
+            observedPids.add(current.pid);
+        return !current.loaded && [...observedPids].every((pid) => !deps.isAlive(pid));
+    });
+    if (!stopped) {
+        const livePids = [...observedPids].filter((pid) => deps.isAlive(pid));
+        const detail = current.loaded
+            ? `launchd still reports ${label} loaded after bootout`
+            : `${label} pid(s) ${livePids.join(", ")} remained alive after bootout`;
+        return {
+            ok: false,
+            failure: lifecycleFailure(removed, detail),
+        };
     }
-    return { ok: false, restarted: true, failure: booted };
+    return { ok: true };
+}
+function maintenancePathsForTarget(target) {
+    const label = deriveLaunchdMaintenanceLabel(target.label);
+    return { label, plistPath: resolve(target.paths.launchAgentsDir, `${label}.plist`) };
+}
+async function restoreMaintenanceDefinition(wasLoaded, maintenance, deps, uid, poll) {
+    if (!wasLoaded)
+        return undefined;
+    const restored = await bootstrap(deps.runner, maintenance.plistPath, uid);
+    const returned = await pollUntil(deps, poll, async () => await isLoaded(deps.runner, maintenance.label, uid));
+    if (returned)
+        return undefined;
+    return lifecycleFailure(restored, "scheduled maintenance did not return after the main stop failed");
 }
 async function findOwnershipConflict(target, deps, uid) {
     const [service, sources] = await Promise.all([
@@ -577,8 +931,26 @@ export async function stopBackground(target, deps, poll = DEFAULT_POLL) {
 }
 async function stopBackgroundUnlocked(target, deps, poll) {
     const uid = deps.getuid();
+    const maintenance = maintenancePathsForTarget(target);
     const existing = await findInstances(target, deps);
-    const service = await launchdServiceInfo(deps.runner, target.label, uid);
+    const [service, maintenanceService] = await Promise.all([
+        launchdServiceInfo(deps.runner, target.label, uid),
+        launchdServiceInfo(deps.runner, maintenance.label, uid),
+    ]);
+    let maintenanceIntent;
+    try {
+        maintenanceIntent = await deps.readLaunchdLogMaintenanceIntent(target.paths);
+    }
+    catch (error) {
+        deps.stderr(ui.errorLine(`Failed to inspect pending launchd-log maintenance for ${target.label}.`));
+        deps.stderr(ui.style.dim(error instanceof Error ? error.message : String(error)) + "\n");
+        return 1;
+    }
+    if ((maintenanceIntent?.phase === "stopping" || maintenanceIntent?.phase === "restoring") && !service.loaded) {
+        deps.stderr(ui.errorLine(`Refusing to erase interrupted launchd-log maintenance for ${target.label} without stopped-writer proof.`));
+        deps.stderr(ui.hint("Confirm the prior worker is gone, then restore or remove the owner-private maintenance marker explicitly."));
+        return 1;
+    }
     const liveTracePids = uniquePids(existing
         .filter((source) => source.health !== "stopped" && source.pid !== undefined && deps.isAlive(source.pid))
         .map((source) => source.pid));
@@ -587,25 +959,53 @@ async function stopBackgroundUnlocked(target, deps, poll) {
         deps.stderr(ui.hint("The LaunchAgent plist was preserved. Stop the unmanaged process explicitly, then retry."));
         return 1;
     }
-    const result = await bootout(deps.runner, target.label, uid);
-    const unloaded = await pollUntil(deps, poll, async () => !(await launchdServiceInfo(deps.runner, target.label, uid)).loaded);
+    const maintenanceStopped = await unloadLaunchdService(maintenance.label, maintenanceService, uniquePids([maintenanceService.pid]), deps, uid, poll);
+    if (!maintenanceStopped.ok) {
+        deps.stderr(ui.errorLine(`Failed to stop scheduled log maintenance for ${target.label}.`));
+        const detail = (maintenanceStopped.failure.stderr || maintenanceStopped.failure.stdout).trim();
+        if (detail.length > 0)
+            deps.stderr(ui.style.dim(detail) + "\n");
+        deps.stderr(ui.hint("Both LaunchAgent plists were preserved. Retry stop after the maintenance helper exits."));
+        return 1;
+    }
     const ownedPids = uniquePids([service.pid, ...liveTracePids]);
-    const stopped = await pollUntil(deps, poll, async () => ownedPids.every((pid) => !deps.isAlive(pid)));
-    if (!unloaded || !stopped) {
-        deps.stderr(ui.errorLine(`Failed to prove ${target.label} stopped${result.code === 0 ? "" : ` (launchctl bootout exited ${result.code})`}.`));
-        const detail = (result.stderr || result.stdout).trim();
+    const mainStopped = await unloadLaunchdService(target.label, service, ownedPids, deps, uid, poll, async () => {
+        const stoppedIntent = maintenanceIntent;
+        if (stoppedIntent?.phase === "stopped") {
+            maintenanceIntent = await deps.markLaunchdLogMaintenanceStopping(target.paths, stoppedIntent);
+        }
+    });
+    if (!mainStopped.ok) {
+        const result = mainStopped.failure;
+        const maintenanceRestoreFailure = await restoreMaintenanceDefinition(maintenanceService.loaded, maintenance, deps, uid, poll);
+        deps.stderr(ui.errorLine(`Failed to prove ${target.label} stopped${result?.code === undefined || result.code === 0 ? "" : ` (launchctl bootout exited ${result.code})`}.`));
+        const detail = (result?.stderr || result?.stdout || "").trim();
         if (detail.length > 0) {
             deps.stderr(ui.style.dim(detail) + "\n");
         }
-        if (!unloaded)
-            deps.stderr(ui.style.dim("launchd still reports the service as loaded.\n"));
-        if (!stopped)
-            deps.stderr(ui.style.dim(`Worker pid(s) ${ownedPids.join(", ")} are still alive.\n`));
-        deps.stderr(ui.hint("The LaunchAgent plist was preserved so the service remains recoverable. Inspect status/logs and retry."));
+        if (maintenanceRestoreFailure !== undefined) {
+            deps.stderr(ui.style.yellow(`Scheduled log maintenance also could not be restored: ${maintenanceErrorMessage(maintenanceRestoreFailure)}`) + "\n");
+        }
+        deps.stderr(ui.hint("Both LaunchAgent plists were preserved so the service remains recoverable. Inspect status/logs and retry."));
+        return 1;
+    }
+    try {
+        // Explicit stop cancels any interrupted maintainer's restore authority
+        // only after both jobs and every observed pid are proven gone.
+        if (maintenanceIntent?.phase === "stopping" || maintenanceIntent?.phase === "restoring") {
+            maintenanceIntent = await deps.markLaunchdLogMaintenanceStopped(target.paths, maintenanceIntent);
+        }
+        await deps.clearLaunchdLogMaintenanceIntent(target.paths, maintenanceIntent);
+    }
+    catch (error) {
+        deps.stderr(ui.errorLine(`Failed to clear pending launchd-log maintenance for ${target.label}.`));
+        deps.stderr(ui.style.dim(error instanceof Error ? error.message : String(error)) + "\n");
+        deps.stderr(ui.hint("Both LaunchAgent plists were preserved; retry stop after the owner-private marker is inspectable."));
         return 1;
     }
-    // Remove the plist only after both launchd ownership and process death are
-    // proven. This prevents a failed stop from destroying its recovery handle.
+    // Remove both definitions only after the helper and worker are unloaded and
+    // every observed PID is dead. The helper can never resurrect a stopped job.
+    await deps.rm(maintenance.plistPath);
     await deps.rm(target.paths.plistPath);
     for (const source of existing)
         await maybeUnlinkDeadManifest(target, deps, source);
@@ -719,9 +1119,6 @@ async function findInstances(target, deps) {
     })));
     return matches.filter((entry) => entry.matches).map((entry) => entry.source);
 }
-async function findInstance(target, deps) {
-    return (await findInstances(target, deps))[0];
-}
 async function maybeUnlinkDeadManifest(target, deps, existing) {
     // Only clean up a manifest whose process is already gone; a worker that is
     // still shutting down will mark its own manifest stopped.
@@ -1036,179 +1433,53 @@ export async function acquireFilesystemLifecycleLock(target, options = {}) {
     const pid = options.pid ?? process.pid;
     const now = options.now ?? (() => Date.now());
     const isProcessAlive = options.isProcessAlive ?? processIsAlive;
-    const incarnation = options.processIncarnation ?? await currentProcessIncarnation();
-    const isSameProcess = options.isSameProcessIncarnation ?? matchesProcessIncarnation;
     const ownerlessGraceMs = options.ownerlessGraceMs ?? 5 * 60_000;
     const randomToken = options.randomToken ?? randomUUID;
-    if (!Number.isSafeInteger(pid) || pid <= 0) {
-        throw new Error(`Lifecycle lock pid must be a positive safe integer; received ${String(pid)}.`);
-    }
-    if (!Number.isFinite(ownerlessGraceMs) || ownerlessGraceMs < 0) {
-        throw new Error("Lifecycle lock ownerless grace must be a non-negative finite duration.");
-    }
+    validateOwnerPrivateLockInputs("Lifecycle lock", pid, ownerlessGraceMs);
     const managedRoot = dirname(target.paths.logDir);
     const locksDir = resolve(managedRoot, "locks");
     for (const path of [managedRoot, locksDir]) {
         await ensureOwnerPrivateLaunchdDirectory(path);
     }
     const lockDir = resolve(locksDir, `${target.label}.lock`);
-    const ownerPath = resolve(lockDir, "owner.json");
-    const token = `${pid}-${now()}-${randomToken()}`;
-    for (let attempt = 0; attempt < 4; attempt += 1) {
-        let createdIdentity;
-        try {
-            await mkdir(lockDir, { mode: 0o700 });
-            const created = await assertLifecycleLockDirectory(lockDir);
-            createdIdentity = lifecycleLockIdentity(created);
-            await writeFile(ownerPath, `${JSON.stringify({
-                pid,
-                token,
-                createdAt: new Date(now()).toISOString(),
-                incarnation,
-            })}\n`, {
-                encoding: "utf8",
-                flag: "wx",
-                mode: 0o600,
-            });
-            if (!(await sameLifecycleLockDirectory(lockDir, createdIdentity))) {
-                throw new Error(`Lifecycle lock ${lockDir} changed while its owner record was written.`);
-            }
-            const ownedIdentity = createdIdentity;
-            return async () => {
-                try {
-                    if (!(await sameLifecycleLockDirectory(lockDir, ownedIdentity))) {
-                        throw new Error(`Lifecycle lock ${lockDir} is no longer owned by this command.`);
-                    }
-                    const current = JSON.parse(await readFile(ownerPath, "utf8"));
-                    if (current.token !== token) {
-                        throw new Error(`Lifecycle lock ${lockDir} is no longer owned by this command.`);
-                    }
-                    const releasedPath = resolve(locksDir, `${target.label}.released-${now()}-${pid}-${randomToken()}`);
-                    if (!(await sameLifecycleLockDirectory(lockDir, ownedIdentity))) {
-                        throw new Error(`Lifecycle lock ${lockDir} changed during release.`);
-                    }
-                    await rename(lockDir, releasedPath);
-                    const moved = await lstat(releasedPath);
-                    if (!sameLifecycleLockIdentity(moved, ownedIdentity)) {
-                        await rename(releasedPath, lockDir).catch(() => undefined);
-                        throw new Error(`Lifecycle lock ${lockDir} changed during release.`);
-                    }
-                    await rm(releasedPath, { recursive: true, force: true });
-                }
-                catch (error) {
-                    if (!isErrno(error, "ENOENT"))
-                        throw error;
-                }
-            };
-        }
-        catch (error) {
-            if (createdIdentity !== undefined) {
-                await removeSameLifecycleLockDirectory(lockDir, createdIdentity).catch(() => undefined);
-            }
-            if (!isErrno(error, "EEXIST"))
-                throw error;
-        }
-        let observed;
-        try {
-            observed = await assertLifecycleLockDirectory(lockDir);
-        }
-        catch (error) {
-            if (isErrno(error, "ENOENT"))
-                continue;
-            return undefined;
-        }
-        const observedIdentity = lifecycleLockIdentity(observed);
-        const owner = await readLifecycleLockOwner(ownerPath);
-        if (!(await sameLifecycleLockDirectory(lockDir, observedIdentity)))
-            continue;
-        if (owner !== undefined) {
-            let sameOwner = true;
-            try {
-                sameOwner = owner.incarnation === undefined
-                    ? isProcessAlive(owner.pid)
-                    : await isSameProcess(owner.pid, owner.incarnation);
-            }
-            catch {
-                // A failed identity probe cannot authorize stealing another command's lock.
-                sameOwner = true;
-            }
-            if (sameOwner)
+    const held = await acquireOwnerPrivateLock({
+        path: lockDir,
+        label: "Lifecycle lock",
+        schemaTag: "mono-agent.filesystem-lifecycle-lock.v1",
+        ownerlessGraceMs,
+        maxAcquireAttempts: 4,
+        pid,
+        now,
+        randomToken,
+        ...(options.processIncarnation === undefined ? {} : { processIncarnation: options.processIncarnation }),
+        ...(options.isSameProcessIncarnation === undefined
+            ? {}
+            : { isSameProcessIncarnation: options.isSameProcessIncarnation }),
+        parseLegacyOwner: (record) => {
+            if (typeof record.pid !== "number" || !Number.isSafeInteger(record.pid) || record.pid <= 0)
                 return undefined;
-        }
-        if (owner === undefined) {
-            const lockAgeMs = now() - observed.mtimeMs;
-            // Another process may be between its atomic mkdir and owner.json write.
-            // Never steal that fresh ownerless lock; only recover abandoned debris.
-            if (lockAgeMs < ownerlessGraceMs)
-                return undefined;
-        }
-        if (!(await sameLifecycleLockDirectory(lockDir, observedIdentity)))
-            continue;
-        await options.beforeStaleLockRename?.();
-        const stalePath = resolve(locksDir, `${target.label}.stale-${now()}-${pid}-${randomToken()}`);
-        try {
-            await rename(lockDir, stalePath);
-        }
-        catch (error) {
-            if (isErrno(error, "ENOENT") || isErrno(error, "EEXIST"))
-                continue;
-            return undefined;
-        }
-        const moved = await lstat(stalePath);
-        if (!sameLifecycleLockIdentity(moved, observedIdentity)) {
-            // A contender replaced the path after our final identity check. Restore
-            // the directory we moved and fail closed; never delete its live lock.
-            await rename(stalePath, lockDir).catch(() => undefined);
-            return undefined;
-        }
-        await rm(stalePath, { recursive: true, force: true });
-    }
-    return undefined;
-}
-async function assertLifecycleLockDirectory(path) {
-    const details = await lstat(path);
-    if (!details.isDirectory() || details.isSymbolicLink()) {
-        throw new Error(`Lifecycle lock ${path} must be a real directory.`);
-    }
-    if (typeof process.getuid === "function" && details.uid !== process.getuid()) {
-        throw new Error(`Lifecycle lock ${path} is not owned by the current user.`);
-    }
-    return details;
-}
-function lifecycleLockIdentity(details) {
-    return { dev: details.dev, ino: details.ino };
-}
-function sameLifecycleLockIdentity(details, identity) {
-    return details.dev === identity.dev && details.ino === identity.ino;
-}
-async function sameLifecycleLockDirectory(path, identity) {
-    try {
-        const details = await assertLifecycleLockDirectory(path);
-        return sameLifecycleLockIdentity(details, identity);
-    }
-    catch {
-        return false;
-    }
-}
-async function removeSameLifecycleLockDirectory(path, identity) {
-    if (await sameLifecycleLockDirectory(path, identity)) {
-        await rm(path, { recursive: true, force: true });
-    }
-}
-async function readLifecycleLockOwner(path) {
-    try {
-        const parsed = JSON.parse(await readFile(path, "utf8"));
-        const incarnation = processIncarnationFromJson(parsed.incarnation);
-        return typeof parsed.pid === "number" && Number.isSafeInteger(parsed.pid) && parsed.pid > 0
-            ? {
-                pid: parsed.pid,
+            const incarnation = processIncarnationFromJson(record.incarnation);
+            return {
+                pid: record.pid,
                 ...(incarnation === undefined ? {} : { incarnation }),
-            }
-            : undefined;
-    }
-    catch {
-        return undefined;
-    }
+            };
+        },
+        // Permanent pre-v0.9.0 compatibility: a skipped-version upgrade can
+        // encounter crash debris without incarnation identity indefinitely.
+        // All owner records written since v0.9.0 use the stronger shared schema.
+        allowCurrentUserLegacyOwnerMode: true,
+        isLegacyProcessAlive: isProcessAlive,
+        invalidOwner: "ownerless",
+        livenessError: () => "assume-live",
+        ...(options.beforeStaleLockRename === undefined
+            ? {}
+            : { beforeStaleRename: options.beforeStaleLockRename }),
+        staleRace: "return",
+        stalePath: ({ now: staleAt, pid: stalePid, token }) => resolve(locksDir, `${target.label}.stale-${staleAt}-${stalePid}-${token}`),
+        releasedPath: ({ now: releasedAt, pid: ownerPid, token }) => resolve(locksDir, `${target.label}.released-${releasedAt}-${ownerPid}-${token}`),
+        abandonedPath: ({ now: abandonedAt, pid: ownerPid, token }) => resolve(locksDir, `${target.label}.abandoned-${abandonedAt}-${ownerPid}-${token}`),
+    });
+    return held === undefined ? undefined : () => held.release();
 }
 function processIsAlive(pid) {
     try {