@mono-agent/agent-app 0.12.0 → 0.14.0

package/dist/background.js

@@ -7,12 +7,15 @@ 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, buildLaunchdMaintenancePlistXml, buildPlistXml, defaultPathEnv, deriveLaunchdLabel, deriveLaunchdMaintenanceLabel, isLoaded, launchdServiceInfo, launchdPathsFor, MANAGED_LAUNCHD_LOG_MAINTENANCE_ENV, makeLaunchctlRunner, } from "./launchd.js";
+import { formatHumanChannelSections } from "./channel-status-display.js";
+import { hasCompletedManagedStartup } from "./managed-startup.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";
@@ -65,6 +68,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) }),
@@ -107,6 +111,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,
@@ -140,12 +145,18 @@ export function defaultBackgroundDeps() {
             }
         },
         ensureManagedRuntime: (input) => ensureManagedBackgroundRuntime(input),
+        inspectManagedRuntimeSourceIdentity,
+        verifyManagedRuntimeLaunch,
         resolveManagedRuntimePackages: (target) => resolveConfiguredManagedRuntimePackages({
             cwd: target.cwd,
             configPath: target.configPath,
             env: target.configurationEnvironment,
         }),
         acquireLifecycleLock: acquireFilesystemLifecycleLock,
+        acquireRuntimePublicationBarrier: (target) => acquireManagedRuntimePublicationBarrier({
+            label: target.label,
+            managedRoot: dirname(target.paths.logDir),
+        }),
         probeTui: probeTuiEndpoint,
         stdout: (text) => void process.stdout.write(text),
         stderr: (text) => void process.stderr.write(text),
@@ -156,20 +167,133 @@ export function defaultBackgroundDeps() {
         }),
     };
 }
-const DEFAULT_POLL = { timeoutMs: 18_000, intervalMs: 400 };
-export async function startBackground(target, deps, poll = DEFAULT_POLL) {
+const DEFAULT_CONTROL_POLL = { timeoutMs: 18_000, intervalMs: 400 };
+const DEFAULT_READINESS_POLL = { timeoutMs: 60_000, intervalMs: 400 };
+export async function startBackground(target, deps, poll) {
     return (await ensureBackgroundReady(target, deps, poll)).ok ? 0 : 1;
 }
 /** Restart is behaviourally identical: ensure a single fresh running instance. */
-export async function restartBackground(target, deps, poll = DEFAULT_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
  * concurrent start could previously enter while the session store was purged.
  */
-export async function forceRestartBackground(target, deps, whileStopped, poll = DEFAULT_POLL) {
+export async function forceRestartBackground(target, deps, whileStopped, poll) {
     const release = await deps.acquireLifecycleLock(target);
     if (release === undefined) {
         deps.stderr(ui.errorLine(`Another lifecycle command is already active for ${target.label}.`));
@@ -177,11 +301,12 @@ export async function forceRestartBackground(target, deps, whileStopped, poll =
         return 1;
     }
     try {
-        const stopCode = await stopBackgroundUnlocked(target, deps, poll);
+        const controlPoll = poll ?? DEFAULT_CONTROL_POLL;
+        const stopCode = await stopBackgroundUnlocked(target, deps, controlPoll);
         if (stopCode !== 0)
             return stopCode;
         await whileStopped();
-        return (await ensureBackgroundReadyUnlocked(target, deps, poll)).ok ? 0 : 1;
+        return (await ensureBackgroundReadyUnlocked(target, deps, controlPoll, poll ?? DEFAULT_READINESS_POLL)).ok ? 0 : 1;
     }
     finally {
         await release().catch((error) => {
@@ -195,7 +320,7 @@ export async function forceRestartBackground(target, deps, whileStopped, poll =
  * 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) {
+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
@@ -398,11 +523,11 @@ function maintenanceErrorMessage(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
+ * trace source that proved it completed the full startup lifecycle. This is the shared
  * lifecycle boundary for CLI start/restart and remote configuration handoffs;
  * callers must not open a console when the result is not ok.
  */
-export async function ensureBackgroundReady(target, deps, poll = DEFAULT_POLL) {
+export async function ensureBackgroundReady(target, deps, poll) {
     const release = await deps.acquireLifecycleLock(target);
     if (release === undefined) {
         deps.stderr(ui.errorLine(`Another lifecycle command is already active for ${target.label}.`));
@@ -410,7 +535,7 @@ export async function ensureBackgroundReady(target, deps, poll = DEFAULT_POLL) {
         return { ok: false, action: "start", reason: "ownership" };
     }
     try {
-        return await ensureBackgroundReadyUnlocked(target, deps, poll);
+        return await ensureBackgroundReadyUnlocked(target, deps, poll ?? DEFAULT_CONTROL_POLL, poll ?? DEFAULT_READINESS_POLL);
     }
     finally {
         await release().catch((error) => {
@@ -418,18 +543,58 @@ export async function ensureBackgroundReady(target, deps, poll = DEFAULT_POLL) {
         });
     }
 }
-async function ensureBackgroundReadyUnlocked(target, deps, poll) {
+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`."));
         return { ok: false, action: "start", reason: "snapshot" };
     }
-    const uid = deps.getuid();
     if (!(await snapshotStillMatches(target, deps))) {
         reportSnapshotDrift(target, deps);
         return { ok: false, action: "start", reason: "snapshot" };
     }
+    let publicationBarrier;
+    try {
+        publicationBarrier = await (deps.acquireRuntimePublicationBarrier
+            ?? ((input) => acquireManagedRuntimePublicationBarrier({
+                label: input.label,
+                managedRoot: dirname(input.paths.logDir),
+            })))(target);
+    }
+    catch (error) {
+        reportLifecycleException(target, deps, "establish the managed runtime publication barrier", error);
+        return { ok: false, action: "start", reason: "ownership" };
+    }
+    if (publicationBarrier === undefined) {
+        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, options);
+}
+async function ensureBackgroundReadyWithPublicationBarrier(target, deps, controlPoll, readinessPoll, publicationBarrier, options) {
+    let barrierReleased = false;
+    const releaseBarrier = async () => {
+        if (barrierReleased)
+            return;
+        await publicationBarrier.release();
+        barrierReleased = true;
+    };
+    try {
+        return await ensureBackgroundReadyAfterPublicationBarrier(target, deps, controlPoll, readinessPoll, releaseBarrier, options);
+    }
+    finally {
+        if (!barrierReleased) {
+            await releaseBarrier().catch((error) => {
+                deps.stderr(ui.errorLine(`Could not release runtime publication barrier for ${target.label}: ${error instanceof Error ? error.message : String(error)}`));
+            });
+        }
+    }
+}
+async function ensureBackgroundReadyAfterPublicationBarrier(target, deps, controlPoll, readinessPoll, releaseBarrier, options) {
+    const uid = deps.getuid();
     let launchTarget;
+    const runtimeStartedAt = deps.now();
+    deps.stdout(ui.hint("Verifying the durable managed runtime…"));
     try {
         const additionalPackages = await deps.resolveManagedRuntimePackages?.(target) ?? [];
         const runtime = await deps.ensureManagedRuntime({
@@ -441,7 +606,10 @@ async function ensureBackgroundReadyUnlocked(target, deps, poll) {
             ...target,
             cliPath: runtime.cliPath,
             nodePath: runtime.nodePath,
+            managedRuntimeLaunchProof: runtime.launchProof,
         };
+        deps.stdout(ui.hint(`Managed runtime ready (${runtimeVerificationLabel(runtime.verificationMode)}, `
+            + `${formatLifecycleDuration(deps.now() - runtimeStartedAt)}).`));
     }
     catch (error) {
         reportLifecycleException(target, deps, "install and verify the durable managed runtime", error);
@@ -475,6 +643,7 @@ async function ensureBackgroundReadyUnlocked(target, deps, poll) {
     }
     let outcome;
     let prepared = false;
+    deps.stdout(ui.hint("Replacing the managed worker…"));
     try {
         let interruptedMaintenance = await deps.readLaunchdLogMaintenanceIntent(launchTarget.paths);
         if (interruptedMaintenance?.phase === "stopping" || interruptedMaintenance?.phase === "restoring") {
@@ -483,7 +652,7 @@ async function ensureBackgroundReadyUnlocked(target, deps, poll) {
                 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 () => {
+        outcome = await bootstrapOrRestart(launchTarget, deps, uid, controlPoll, async () => {
             const stoppedIntent = interruptedMaintenance;
             if (stoppedIntent?.phase === "stopped") {
                 interruptedMaintenance = await deps.markLaunchdLogMaintenanceStopping(launchTarget.paths, stoppedIntent);
@@ -504,7 +673,10 @@ async function ensureBackgroundReadyUnlocked(target, deps, poll) {
             await writePlists(launchTarget, deps);
             sinceMs = deps.now();
             prepared = true;
-        });
+            // 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);
@@ -519,18 +691,20 @@ async function ensureBackgroundReadyUnlocked(target, deps, poll) {
     let ready;
     try {
         ready = await pollInstanceReady(launchTarget, deps, {
-            ...poll,
+            ...readinessPoll,
             sinceMs,
             ...(launchTarget.requireTui === true ? { requireTui: true } : {}),
         });
     }
     catch (error) {
-        reportLifecycleException(launchTarget, deps, "read the worker readiness trace", error);
+        reportReadinessException(deps, error);
+        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, poll);
+            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");
@@ -540,13 +714,27 @@ async function ensureBackgroundReadyUnlocked(target, deps, poll) {
             }
             return { ok: false, action, reason: "snapshot" };
         }
-        reportTimeout(launchTarget, deps);
+        reportTimeout(deps);
+        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";
     printInstanceInfo(ready, launchTarget, deps, completedAction);
     return { ok: true, action: completedAction, source: ready };
 }
+function runtimeVerificationLabel(mode) {
+    switch (mode) {
+        case "fast-reuse": return "warm reuse";
+        case "full-reuse": return "full verification";
+        case "installed": return "installed";
+        case "repaired": return "repaired";
+    }
+}
+function formatLifecycleDuration(milliseconds) {
+    const safe = Math.max(0, milliseconds);
+    return safe < 1_000 ? `${Math.round(safe)} ms` : `${(safe / 1_000).toFixed(1)} s`;
+}
 async function prepareLaunchdDirectories(target, deps) {
     // launchd will not create the log file's parent directory, so make both dirs
     // before writing the plist that references them.
@@ -558,6 +746,13 @@ async function writePlists(target, deps) {
     if (target.expectedSnapshot === undefined) {
         throw new Error("A managed LaunchAgent requires an approved background snapshot.");
     }
+    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,
@@ -567,6 +762,7 @@ async function writePlists(target, deps) {
         cwd: target.cwd,
         ...(target.envFile === undefined ? {} : { envFile: target.envFile }),
         expectedBackgroundSnapshot: encodeBackgroundSnapshot(target.expectedSnapshot),
+        expectedManagedRuntimeLaunch: target.managedRuntimeLaunchProof,
         stdoutPath: target.paths.stdoutPath,
         stderrPath: target.paths.stderrPath,
         environment: target.environment,
@@ -576,6 +772,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.
@@ -756,7 +956,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),
@@ -766,9 +966,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) {
@@ -784,7 +986,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,
@@ -796,19 +1000,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 {
@@ -913,7 +1126,7 @@ function lifecycleFailure(result, detail) {
 function uniquePids(values) {
     return [...new Set(values.filter((value) => value !== undefined && value > 0))];
 }
-export async function stopBackground(target, deps, poll = DEFAULT_POLL) {
+export async function stopBackground(target, deps, poll = DEFAULT_CONTROL_POLL) {
     const release = await deps.acquireLifecycleLock(target);
     if (release === undefined) {
         deps.stderr(ui.errorLine(`Another lifecycle command is already active for ${target.label}.`));
@@ -1015,13 +1228,39 @@ async function stopBackgroundUnlocked(target, deps, poll) {
     deps.stdout(ui.keyValue([["config", target.configPath]]));
     return 0;
 }
-export async function statusBackground(target, deps) {
-    const result = await deps.listTraceSources({ registryDir: target.registryDir, staleAfterMs: target.staleAfterMs });
+export async function statusBackground(target, deps, options = {}) {
+    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
+        .filter((entry) => !entry.matches && entry.source.health !== "stopped")
+        .map((entry) => entry.source);
+    if (options.json === true) {
+        const instance = current === undefined ? null : await assembleInstanceStatus(current, target, deps);
+        deps.stdout(`${JSON.stringify({
+            ok: active,
+            instance,
+            others: others.map(assembleOtherInstanceStatus),
+        })}\n`);
+        return active ? 0 : 1;
+    }
     if (current === undefined) {
         deps.stdout(ui.style.dim(`No running mono-agent instance for ${target.configPath}.`) + "\n");
         deps.stdout(ui.hint(`Start it with: mono-agent start${commandFlags(target)}`));
@@ -1030,18 +1269,94 @@ export async function statusBackground(target, deps) {
         writeInstanceDetail(current, target, deps);
         await writeRunsHealthDetail(current, deps);
     }
-    // Only surface other instances that are live or crashed — cleanly stopped
-    // manifests linger in the registry and would just be noise.
-    const others = classified
-        .filter((entry) => !entry.matches && entry.source.health !== "stopped")
-        .map((entry) => entry.source);
     if (others.length > 0) {
         deps.stdout("\n" + ui.rule("Other mono-agent instances"));
         for (const source of others) {
             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
+ * fields the human `writeInstanceDetail`/`writeRunsHealthDetail` render, reading
+ * only the already-computed trace-source manifest (content-free, safe to publish)
+ * and the same runs-health probe the human path performs — no extra probes.
+ */
+async function assembleInstanceStatus(source, target, deps) {
+    const metadata = source.metadata ?? {};
+    const observability = metadata.observability;
+    const sandbox = metadata.sandbox;
+    const session = metadata.session;
+    const channels = metadata.channels;
+    return {
+        sourceId: source.sourceId,
+        label: source.label,
+        launchdLabel: target.label,
+        pid: source.pid ?? null,
+        health: source.health,
+        status: source.status,
+        configPath: target.configPath,
+        startedAt: source.startedAt,
+        updatedAt: source.updatedAt,
+        ...(source.artifactDir === undefined ? {} : { artifactDir: source.artifactDir }),
+        ...(source.transports === undefined ? {} : { transports: source.transports }),
+        logs: { stdout: target.paths.stdoutPath, stderr: target.paths.stderrPath },
+        ...(isPlainRecord(observability) ? { observability } : {}),
+        ...(isPlainRecord(sandbox) ? { sandbox } : {}),
+        ...(isPlainRecord(session) ? { session } : {}),
+        ...(isPlainRecord(channels) ? { channels } : {}),
+        ...(source.memoryHealth === undefined ? {} : { memoryHealth: source.memoryHealth }),
+        runsHealth: await assembleRunsHealthStatus(source, deps),
+    };
+}
+async function assembleRunsHealthStatus(source, deps) {
+    if (source.artifactDir === undefined || source.artifactDir.trim().length === 0) {
+        return null;
+    }
+    const { totalRuns, warnings } = await deps.listRecordedRuns({
+        artifactDir: source.artifactDir,
+        maxRuns: RUNS_HEALTH_MAX_RUNS,
+        scope: "agent",
+    });
+    return { totalRuns, warnings };
+}
+function assembleOtherInstanceStatus(source) {
+    return {
+        sourceId: source.sourceId,
+        label: source.label,
+        health: source.health,
+        pid: source.pid ?? null,
+        ...(source.configPath === undefined ? {} : { configPath: source.configPath }),
+    };
+}
+function isPlainRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 export async function tailLogs(target, deps, options) {
     const args = [
@@ -1146,9 +1461,45 @@ function reportLifecycleException(target, deps, operation, error) {
     deps.stderr(ui.style.dim("The committed agent files were preserved.") + "\n");
     reportLaunchRecovery(target, deps);
 }
-function reportTimeout(target, deps) {
+function reportReadinessException(deps, error) {
+    deps.stderr(ui.errorLine(`Failed to read the worker readiness trace: ${error instanceof Error ? error.message : String(error)}`));
+    deps.stderr(ui.style.dim("The committed agent files were preserved.") + "\n");
+}
+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. It may still be starting, or it may have failed.") + "\n");
+    deps.stderr(ui.style.dim("The committed agent files were preserved.") + "\n");
+}
+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) {
+        deps.stderr(ui.errorLine(`Failed while trying to stop the unready LaunchAgent: ${error instanceof Error ? error.message : String(error)}`));
+        return false;
+    }
+}
+function reportReadinessCleanup(target, deps, stopped, options = {}) {
+    deps.stderr(stopped
+        ? 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);
 }
 function reportLaunchRecovery(target, deps) {
@@ -1190,10 +1541,10 @@ function writeInstanceDetail(source, target, deps) {
             deps.stdout(`  ${line}\n`);
         }
     }
-    const channelLines = formatChannels(source);
-    if (channelLines.length > 0) {
-        deps.stdout(ui.rule("channels"));
-        for (const line of channelLines) {
+    const channelSections = formatChannels(source);
+    for (const section of channelSections) {
+        deps.stdout(ui.rule(section.title));
+        for (const line of section.lines) {
             deps.stdout(`${line}\n`);
         }
     }
@@ -1247,7 +1598,7 @@ async function matchesConfig(source, configPath) {
     return await canonicalBackgroundConfigPath(process.cwd(), source.configPath) === configPath;
 }
 function isReady(source, requireTui) {
-    if (source.health !== "running" || metadataReason(source) !== "startup-complete")
+    if (source.health !== "running" || !hasCompletedManagedStartup(source))
         return false;
     if (source.memoryHealth?.status === "unhealthy")
         return false;
@@ -1268,10 +1619,6 @@ function channelRecords(source) {
     return Object.values(channels)
         .filter((value) => value !== null && typeof value === "object");
 }
-function metadataReason(source) {
-    const reason = source.metadata?.reason;
-    return typeof reason === "string" ? reason : undefined;
-}
 function startedAtMs(source) {
     const parsed = Date.parse(source.startedAt);
     return Number.isFinite(parsed) ? parsed : 0;
@@ -1539,10 +1886,10 @@ function formatChannels(source) {
     if (channels === null || typeof channels !== "object") {
         return [];
     }
-    return Object.entries(channels).map(([id, value]) => {
+    return formatHumanChannelSections(Object.entries(channels).map(([id, value]) => {
         const { kind, text } = describeChannel(value);
-        return `  ${ui.channelBadge(kind)}${ui.style.bold(id.padEnd(11))} ${text}`;
-    });
+        return { id, kind, text };
+    }));
 }
 export function describeChannel(value) {
     if (value === null || typeof value !== "object") {