@mono-agent/agent-app 0.13.0 → 0.15.0

package/dist/background.js

@@ -9,16 +9,18 @@ import { describeSensitiveDataExportWarning, phoenixAppBaseUrl, resolveAppTraceR
 import { formatChannelFactValue } from "./channel-fact-format.js";
 import { formatHumanChannelSections } from "./channel-status-display.js";
 import { hasCompletedManagedStartup } from "./managed-startup.js";
-import { bootout, bootstrap, buildLaunchdMaintenancePlistXml, buildPlistXml, defaultPathEnv, deriveLaunchdLabel, deriveLaunchdMaintenanceLabel, isLoaded, launchdServiceInfo, launchdPathsFor, MANAGED_LAUNCHD_LOG_MAINTENANCE_ENV, makeLaunchctlRunner, } from "./launchd.js";
+import { bootout, bootstrap, buildLaunchdMaintenancePlistXml, buildPlistXml, defaultPathEnv, deriveLaunchdLabel, deriveLaunchdMaintenanceLabel, isLoaded, launchdManagedWorkerInfo, 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 { ensureManagedBackgroundRuntime, inspectManagedRuntimeSourceIdentity, MANAGED_BACKGROUND_WORKER_ENV, verifyManagedRuntimeLaunch, } from "./background-runtime.js";
 import { backgroundSnapshotFromMetadata, captureBackgroundSnapshot, encodeBackgroundSnapshot, sameBackgroundSnapshot, } from "./background-snapshot.js";
 import { resolveConfiguredManagedRuntimePackages } from "./managed-runtime-packages.js";
 import { acquireManagedRuntimePublicationBarrier } from "./managed-runtime-publication.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 { lifecycleFailure, maintenanceErrorMessage, pollUntil, uniquePids, unloadLaunchdService, } from "./background-lifecycle-utils.js";
+import { maintainLaunchdLogsOperation, reportMaintenanceFailure, } from "./background-log-maintenance.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";
@@ -68,6 +70,7 @@ export async function resolveInstanceTarget(input) {
         paths: launchdPathsFor(label),
         nodePath: process.execPath,
         cliPath: input.cliPath,
+        controllerCliPath: input.cliPath,
         // Bake an explicit --env-file (resolved absolute) into the plist so the
         // launchd worker loads the same env file the launcher did.
         ...(input.args.envFile === undefined ? {} : { envFile: resolve(cwd, input.args.envFile) }),
@@ -110,6 +113,7 @@ export function defaultBackgroundDeps() {
     return {
         runner: makeLaunchctlRunner(),
         getuid: () => process.getuid?.() ?? 0,
+        currentPid: () => process.pid,
         now: () => Date.now(),
         sleep: (ms) => new Promise((resolvePromise) => setTimeout(resolvePromise, ms)),
         listRecordedRuns,
@@ -143,6 +147,8 @@ export function defaultBackgroundDeps() {
             }
         },
         ensureManagedRuntime: (input) => ensureManagedBackgroundRuntime(input),
+        inspectManagedRuntimeSourceIdentity,
+        verifyManagedRuntimeLaunch,
         resolveManagedRuntimePackages: (target) => resolveConfiguredManagedRuntimePackages({
             cwd: target.cwd,
             configPath: target.configPath,
@@ -172,6 +178,118 @@ export async function startBackground(target, deps, poll) {
 export async function restartBackground(target, deps, poll) {
     return (await ensureBackgroundReady(target, deps, poll)).ok ? 0 : 1;
 }
+/**
+ * Private one-shot recovery controller invoked by the maintenance LaunchAgent.
+ * It authenticates the exact helper PID launchd owns, compares the inert source
+ * CLI identity with the strictly parsed loaded worker definition, and repairs
+ * only when the worker, snapshot, definition, or available source closure has
+ * drifted. A healthy worker remains serving while a replacement runtime is
+ * materialized.
+ */
+export async function maintainLaunchdController(target, deps, options) {
+    const helper = maintenancePathsForTarget(target);
+    const uid = deps.getuid();
+    const helperService = await launchdServiceInfo(deps.runner, helper.label, uid);
+    const helperPid = deps.currentPid();
+    if (!helperService.loaded || helperService.pid !== helperPid || !deps.isAlive(helperPid)) {
+        reportMaintenanceFailure(target, deps, "authenticate the launchd-owned recovery controller", new Error(`launchd does not own this helper pid ${helperPid}`));
+        return 1;
+    }
+    const release = await deps.acquireLifecycleLock(target);
+    if (release === undefined) {
+        // A manual lifecycle command owns the label. The helper exits cleanly so
+        // that command can boot it out; StartInterval supplies the next retry.
+        return 0;
+    }
+    let maintainLogsOnly = false;
+    let resultCode = 1;
+    try {
+        const [worker, sources, desiredIdentity] = await Promise.all([
+            launchdManagedWorkerInfo(deps.runner, target.label, uid),
+            findInstances(target, deps),
+            deps.inspectManagedRuntimeSourceIdentity(target.cliPath),
+        ]);
+        let loadedIdentity;
+        if (worker.definition !== undefined) {
+            try {
+                loadedIdentity = await deps.verifyManagedRuntimeLaunch({
+                    currentCliPath: worker.definition.cliPath,
+                    launchProof: worker.definition.expectedManagedRuntimeLaunch,
+                });
+            }
+            catch {
+                // A malformed/unverified loaded closure is a recovery condition. Do not
+                // trust any identity or execute its advertised CLI.
+            }
+        }
+        const source = worker.pid === undefined
+            ? undefined
+            : sources.find((candidate) => candidate.pid === worker.pid);
+        const durableSnapshotStillMatches = await snapshotStillMatches(target, deps);
+        const workerHealthy = worker.loaded
+            && worker.pid !== undefined
+            && deps.isAlive(worker.pid)
+            && source !== undefined
+            && isReady(source, false)
+            && snapshotMetadataMatches(source, target.expectedSnapshot)
+            && durableSnapshotStillMatches;
+        const definitionMatches = worker.definition !== undefined
+            && managedWorkerDefinitionMatchesTarget(worker.definition, target);
+        const runtimeMatches = loadedIdentity !== undefined
+            && sameManagedRuntimeIdentity(loadedIdentity, desiredIdentity);
+        const needsRecovery = !workerHealthy
+            || !definitionMatches
+            || loadedIdentity === undefined
+            || (options.sourceAvailable && !runtimeMatches);
+        if (!needsRecovery) {
+            maintainLogsOnly = true;
+            resultCode = 0;
+        }
+        else {
+            if (!options.sourceAvailable) {
+                deps.stderr(ui.style.dim(`The original controller CLI is unavailable; recovering ${target.label} from the helper's private closure without claiming an upgrade.`) + "\n");
+            }
+            const recovered = await ensureBackgroundReadyUnlocked(target, deps, options.controlPoll ?? DEFAULT_CONTROL_POLL, options.readinessPoll ?? DEFAULT_READINESS_POLL, { preserveMaintenanceService: true, preserveDefinitionsOnFailure: true });
+            resultCode = recovered.ok ? 0 : 1;
+        }
+    }
+    catch (error) {
+        reportMaintenanceFailure(target, deps, "reconcile the managed worker", error);
+        resultCode = 1;
+    }
+    finally {
+        await release().catch((error) => {
+            deps.stderr(ui.errorLine(`Could not release lifecycle lock for ${target.label}: ${error instanceof Error ? error.message : String(error)}`));
+        });
+    }
+    return maintainLogsOnly
+        ? await maintainLaunchdLogs(target, deps, options.controlPoll ?? DEFAULT_CONTROL_POLL)
+        : resultCode;
+}
+function managedWorkerDefinitionMatchesTarget(definition, target) {
+    return target.expectedSnapshot !== undefined
+        && definition.plistPath === target.paths.plistPath
+        && definition.nodePath === target.nodePath
+        && definition.configPath === target.configPath
+        && definition.cwd === target.cwd
+        && definition.envFile === target.envFile
+        && definition.stdoutPath === target.paths.stdoutPath
+        && definition.stderrPath === target.paths.stderrPath
+        && definition.expectedBackgroundSnapshot === encodeBackgroundSnapshot(target.expectedSnapshot)
+        && sameStringRecord(definition.environment, target.environment);
+}
+function sameManagedRuntimeIdentity(loaded, desired) {
+    return loaded.packageVersion === desired.packageVersion && loaded.cliSha256 === desired.cliSha256;
+}
+function sameStringRecord(left, right) {
+    const leftEntries = Object.entries(left).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    const rightEntries = Object.entries(right).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    return leftEntries.length === rightEntries.length
+        && leftEntries.every(([name, value], index) => {
+            const other = rightEntries[index];
+            return other?.[0] === name && other[1] === value;
+        });
+}
 /**
  * Stop, perform the caller's stopped-worker mutation, and start again while
  * retaining one lifecycle lock. This closes the force-restart gap in which a
@@ -205,205 +323,7 @@ export async function forceRestartBackground(target, deps, whileStopped, poll) {
  * its own durable lifecycle intent after a prior maintainer died post-bootout.
  */
 export async function maintainLaunchdLogs(target, deps, poll = DEFAULT_CONTROL_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);
+    return await maintainLaunchdLogsOperation(target, deps, poll);
 }
 /**
  * Ensure the canonical per-config LaunchAgent is running and return the fresh
@@ -427,7 +347,7 @@ export async function ensureBackgroundReady(target, deps, poll) {
         });
     }
 }
-async function ensureBackgroundReadyUnlocked(target, deps, controlPoll, readinessPoll) {
+async function ensureBackgroundReadyUnlocked(target, deps, controlPoll, readinessPoll, options = {}) {
     if (target.expectedSnapshot === undefined) {
         deps.stderr(ui.errorLine("Refusing to launch a managed worker without an approved background snapshot."));
         deps.stderr(ui.hint("No LaunchAgent changes were made. Retry from the wizard or `mono-agent start`."));
@@ -453,9 +373,9 @@ async function ensureBackgroundReadyUnlocked(target, deps, controlPoll, readines
         deps.stderr(ui.errorLine(`Another runtime publication is already active for ${target.label}.`));
         return { ok: false, action: "start", reason: "ownership" };
     }
-    return await ensureBackgroundReadyWithPublicationBarrier(target, deps, controlPoll, readinessPoll, publicationBarrier);
+    return await ensureBackgroundReadyWithPublicationBarrier(target, deps, controlPoll, readinessPoll, publicationBarrier, options);
 }
-async function ensureBackgroundReadyWithPublicationBarrier(target, deps, controlPoll, readinessPoll, publicationBarrier) {
+async function ensureBackgroundReadyWithPublicationBarrier(target, deps, controlPoll, readinessPoll, publicationBarrier, options) {
     let barrierReleased = false;
     const releaseBarrier = async () => {
         if (barrierReleased)
@@ -464,7 +384,7 @@ async function ensureBackgroundReadyWithPublicationBarrier(target, deps, control
         barrierReleased = true;
     };
     try {
-        return await ensureBackgroundReadyAfterPublicationBarrier(target, deps, controlPoll, readinessPoll, releaseBarrier);
+        return await ensureBackgroundReadyAfterPublicationBarrier(target, deps, controlPoll, readinessPoll, releaseBarrier, options);
     }
     finally {
         if (!barrierReleased) {
@@ -474,7 +394,7 @@ async function ensureBackgroundReadyWithPublicationBarrier(target, deps, control
         }
     }
 }
-async function ensureBackgroundReadyAfterPublicationBarrier(target, deps, controlPoll, readinessPoll, releaseBarrier) {
+async function ensureBackgroundReadyAfterPublicationBarrier(target, deps, controlPoll, readinessPoll, releaseBarrier, options) {
     const uid = deps.getuid();
     let launchTarget;
     const runtimeStartedAt = deps.now();
@@ -560,7 +480,7 @@ async function ensureBackgroundReadyAfterPublicationBarrier(target, deps, contro
             // The replacement plist now contains the finalized-runtime proof. Let
             // launchd respawn only after the stopped-window commit is complete.
             await releaseBarrier();
-        });
+        }, { preserveMaintenanceService: options.preserveMaintenanceService === true });
     }
     catch (error) {
         reportLifecycleException(launchTarget, deps, prepared ? "start the LaunchAgent" : "prepare the stopped LaunchAgent", error);
@@ -582,13 +502,13 @@ async function ensureBackgroundReadyAfterPublicationBarrier(target, deps, contro
     }
     catch (error) {
         reportReadinessException(deps, error);
-        const stopped = await cleanUpUnreadyBackground(launchTarget, deps, controlPoll);
-        reportReadinessCleanup(launchTarget, deps, stopped);
+        const stopped = await cleanUpUnreadyBackground(launchTarget, deps, controlPoll, options);
+        reportReadinessCleanup(launchTarget, deps, stopped, options);
         return { ok: false, action, reason: "readiness" };
     }
     if (ready === undefined) {
         if (!(await snapshotStillMatches(launchTarget, deps))) {
-            const stopped = await stopBackgroundUnlocked(launchTarget, deps, controlPoll);
+            const stopped = await cleanUpUnreadyBackground(launchTarget, deps, controlPoll, options) ? 0 : 1;
             reportSnapshotDrift(launchTarget, deps);
             if (stopped === 0) {
                 deps.stderr(ui.style.dim("The drifted LaunchAgent was stopped before returning control.") + "\n");
@@ -599,8 +519,8 @@ async function ensureBackgroundReadyAfterPublicationBarrier(target, deps, contro
             return { ok: false, action, reason: "snapshot" };
         }
         reportTimeout(deps);
-        const stopped = await cleanUpUnreadyBackground(launchTarget, deps, controlPoll);
-        reportReadinessCleanup(launchTarget, deps, stopped);
+        const stopped = await cleanUpUnreadyBackground(launchTarget, deps, controlPoll, options);
+        reportReadinessCleanup(launchTarget, deps, stopped, options);
         return { ok: false, action, reason: "timeout" };
     }
     const completedAction = outcome.restarted ? "restarted" : "started";
@@ -633,6 +553,10 @@ async function writePlists(target, deps) {
     if (target.managedRuntimeLaunchProof === undefined) {
         throw new Error("A managed LaunchAgent requires a finalized runtime launch proof.");
     }
+    const agentPath = target.environment.PATH;
+    if (agentPath === undefined || agentPath.length === 0) {
+        throw new Error("A managed LaunchAgent recovery controller requires the durable worker PATH.");
+    }
     const maintenance = maintenancePathsForTarget(target);
     const mainXml = buildPlistXml({
         label: target.label,
@@ -652,6 +576,10 @@ async function writePlists(target, deps) {
         nodePath: target.nodePath,
         cliPath: target.cliPath,
         configPath: target.configPath,
+        controllerCliPath: target.controllerCliPath ?? target.cliPath,
+        agentCwd: target.cwd,
+        agentPath,
+        ...(target.envFile === undefined ? {} : { envFile: target.envFile }),
         // 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.
@@ -832,7 +760,7 @@ function sameFileSnapshot(left, right) {
  * before bootstrap so launchd cannot retain stale ProgramArguments or env from
  * the previous plist.
  */
-async function bootstrapOrRestart(target, deps, uid, poll, beforeMainBootout, whileStopped) {
+async function bootstrapOrRestart(target, deps, uid, poll, beforeMainBootout, whileStopped, options = {}) {
     const maintenance = maintenancePathsForTarget(target);
     const [service, maintenanceService] = await Promise.all([
         launchdServiceInfo(deps.runner, target.label, uid),
@@ -842,9 +770,11 @@ async function bootstrapOrRestart(target, deps, uid, poll, beforeMainBootout, wh
     // 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 };
+    if (options.preserveMaintenanceService !== true) {
+        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) {
@@ -860,7 +790,9 @@ async function bootstrapOrRestart(target, deps, uid, poll, beforeMainBootout, wh
         ]);
         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);
+            const restoreFailure = options.preserveMaintenanceService === true
+                ? undefined
+                : await restoreMaintenanceDefinition(maintenanceService.loaded, maintenance, deps, uid, poll);
             return {
                 ok: false,
                 restarted: true,
@@ -872,19 +804,28 @@ async function bootstrapOrRestart(target, deps, uid, poll, beforeMainBootout, wh
         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,
-            failure: lifecycleFailure(maintenanceBooted, "scheduled log maintenance did not report loaded"),
-        };
+    if (options.preserveMaintenanceService !== true) {
+        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,
+                failure: lifecycleFailure(maintenanceBooted, "scheduled recovery controller did not report 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 };
     }
+    if (options.preserveMaintenanceService === true) {
+        return {
+            ok: false,
+            restarted,
+            failure: lifecycleFailure(booted, "main service did not load; scheduled recovery remains loaded for retry"),
+        };
+    }
     const maintenanceServiceAfterFailure = await launchdServiceInfo(deps.runner, maintenance.label, uid);
     const maintenanceRemoval = await unloadLaunchdService(maintenance.label, maintenanceServiceAfterFailure, uniquePids([maintenanceServiceAfterFailure.pid]), deps, uid, poll);
     return {
@@ -895,50 +836,6 @@ async function bootstrapOrRestart(target, deps, uid, poll, beforeMainBootout, wh
             : `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,
-            failure: { code: 1, stdout: "", stderr: maintenanceErrorMessage(error) },
-        };
-    }
-    // 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: true };
-}
 function maintenancePathsForTarget(target) {
     const label = deriveLaunchdMaintenanceLabel(target.label);
     return { label, plistPath: resolve(target.paths.launchAgentsDir, `${label}.plist`) };
@@ -969,26 +866,6 @@ async function findOwnershipConflict(target, deps, uid) {
     }
     return undefined;
 }
-async function pollUntil(deps, options, condition) {
-    const deadline = deps.now() + options.timeoutMs;
-    for (;;) {
-        if (await condition())
-            return true;
-        if (deps.now() >= deadline)
-            return false;
-        await deps.sleep(options.intervalMs);
-    }
-}
-function lifecycleFailure(result, detail) {
-    return {
-        code: result.code === 0 ? 1 : result.code,
-        stdout: result.stdout,
-        stderr: [result.stderr.trim(), detail].filter((value) => value.length > 0).join("\n"),
-    };
-}
-function uniquePids(values) {
-    return [...new Set(values.filter((value) => value !== undefined && value > 0))];
-}
 export async function stopBackground(target, deps, poll = DEFAULT_CONTROL_POLL) {
     const release = await deps.acquireLifecycleLock(target);
     if (release === undefined) {
@@ -1092,12 +969,24 @@ async function stopBackgroundUnlocked(target, deps, poll) {
     return 0;
 }
 export async function statusBackground(target, deps, options = {}) {
-    const result = await deps.listTraceSources({ registryDir: target.registryDir, staleAfterMs: target.staleAfterMs });
+    const [result, service] = await Promise.all([
+        deps.listTraceSources({ registryDir: target.registryDir, staleAfterMs: target.staleAfterMs }),
+        launchdServiceInfo(deps.runner, target.label, deps.getuid()),
+    ]);
     const classified = await Promise.all(result.sources.map(async (source) => ({
         source,
         matches: await matchesConfig(source, target.configPath),
     })));
-    const current = classified.find((entry) => entry.matches)?.source;
+    const matchingSources = classified.filter((entry) => entry.matches).map((entry) => entry.source);
+    const recorded = service.pid === undefined
+        ? matchingSources[0]
+        : matchingSources.find((source) => source.pid === service.pid) ?? matchingSources[0];
+    const active = service.loaded
+        && service.pid !== undefined
+        && deps.isAlive(service.pid)
+        && recorded?.pid === service.pid
+        && recorded.health === "running";
+    const current = recorded === undefined || active ? recorded : inactiveStatusSource(recorded);
     // Only surface other instances that are live or crashed — cleanly stopped
     // manifests linger in the registry and would just be noise.
     const others = classified
@@ -1106,11 +995,11 @@ export async function statusBackground(target, deps, options = {}) {
     if (options.json === true) {
         const instance = current === undefined ? null : await assembleInstanceStatus(current, target, deps);
         deps.stdout(`${JSON.stringify({
-            ok: current?.health === "running",
+            ok: active,
             instance,
             others: others.map(assembleOtherInstanceStatus),
         })}\n`);
-        return current?.health === "running" ? 0 : 1;
+        return active ? 0 : 1;
     }
     if (current === undefined) {
         deps.stdout(ui.style.dim(`No running mono-agent instance for ${target.configPath}.`) + "\n");
@@ -1126,7 +1015,32 @@ export async function statusBackground(target, deps, options = {}) {
             deps.stdout(`${formatOtherInstance(source)}\n`);
         }
     }
-    return current?.health === "running" ? 0 : 1;
+    return active ? 0 : 1;
+}
+function inactiveStatusSource(source) {
+    const { transports: _staleTransports, pid: _stalePid, ...withoutLiveProcessFacts } = source;
+    const metadata = source.metadata;
+    const channels = metadata?.channels;
+    const stoppedChannels = isPlainRecord(channels)
+        ? Object.fromEntries(Object.entries(channels).map(([id, value]) => {
+            if (!isPlainRecord(value) || value.kind !== "running")
+                return [id, value];
+            return [id, { kind: "stopped", reason: "instance is not running" }];
+        }))
+        : undefined;
+    return {
+        ...withoutLiveProcessFacts,
+        health: "stopped",
+        status: "stopped",
+        ...(metadata === undefined
+            ? {}
+            : {
+                metadata: {
+                    ...metadata,
+                    ...(stoppedChannels === undefined ? {} : { channels: stoppedChannels }),
+                },
+            }),
+    };
 }
 /**
  * The machine-readable instance record for `status --json`. It mirrors the
@@ -1295,8 +1209,24 @@ function reportTimeout(deps) {
     deps.stderr(ui.errorLine("mono-agent did not report ready within the timeout."));
     deps.stderr(ui.style.dim("The committed agent files were preserved.") + "\n");
 }
-async function cleanUpUnreadyBackground(target, deps, poll) {
+async function cleanUpUnreadyBackground(target, deps, poll, options = {}) {
     try {
+        if (options.preserveDefinitionsOnFailure === true) {
+            const uid = deps.getuid();
+            const [service, sources] = await Promise.all([
+                launchdServiceInfo(deps.runner, target.label, uid),
+                findInstances(target, deps),
+            ]);
+            const liveTracePids = uniquePids(sources
+                .filter((source) => source.health !== "stopped"
+                && source.pid !== undefined
+                && deps.isAlive(source.pid))
+                .map((source) => source.pid));
+            if (liveTracePids.some((pid) => pid !== service.pid))
+                return false;
+            const stopped = await unloadLaunchdService(target.label, service, uniquePids([service.pid, ...liveTracePids]), deps, uid, poll);
+            return stopped.ok;
+        }
         return await stopBackgroundUnlocked(target, { ...deps, stdout: () => undefined }, poll) === 0;
     }
     catch (error) {
@@ -1304,9 +1234,11 @@ async function cleanUpUnreadyBackground(target, deps, poll) {
         return false;
     }
 }
-function reportReadinessCleanup(target, deps, stopped) {
+function reportReadinessCleanup(target, deps, stopped, options = {}) {
     deps.stderr(stopped
-        ? ui.style.dim("The unready LaunchAgent and scheduled maintenance were stopped and their definitions removed before returning control.") + "\n"
+        ? options.preserveDefinitionsOnFailure === true
+            ? ui.style.dim("The unready main LaunchAgent was stopped; both definitions and the scheduled recovery controller remain for retry.") + "\n"
+            : ui.style.dim("The unready LaunchAgent and scheduled maintenance were stopped and their definitions removed before returning control.") + "\n"
         : ui.style.yellow("The unready LaunchAgent could not be proven stopped; a worker or maintenance helper may still be running.") + "\n");
     reportLaunchRecovery(target, deps);
 }