@mono-agent/agent-app 0.6.2 → 0.9.0

package/dist/background.js

@@ -1,21 +1,42 @@
 import { spawn } from "node:child_process";
-import { mkdir, rename, rm, stat, writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
+import { 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 { 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, kickstartRestart, launchdPathsFor, makeLaunchctlRunner, } from "./launchd.js";
+import { bootout, bootstrap, buildPlistXml, defaultPathEnv, deriveLaunchdLabel, isLoaded, launchdServiceInfo, launchdPathsFor, makeLaunchctlRunner, } from "./launchd.js";
+import { selectBackgroundOperationalEnvironment } from "./background-environment.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 { buildRunsHealthDisplay, RUNS_HEALTH_MAX_RUNS } from "./runs-health.js";
 import * as ui from "./ui.js";
+export { acquireBackgroundWorkerLease, backgroundWorkerLeasePath, } from "./background-worker-lease.js";
+/** Exact non-secret environment materialised into a managed LaunchAgent. */
+export function managedBackgroundEnvironment(env) {
+    return {
+        ...selectBackgroundOperationalEnvironment(env),
+        PATH: defaultPathEnv({ ...env }),
+        // This is a lifecycle marker, not a config override. It tells cli.ts to
+        // discard launchd's ambient environment before loading the chosen dotenv.
+        [MANAGED_BACKGROUND_WORKER_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
  * detached launcher can find the worker's manifest without any IPC.
  */
 export async function resolveInstanceTarget(input) {
-    const cwd = resolve(input.cwd);
-    const configPath = resolve(cwd, input.args.configPath ?? "mono-agent.config.json");
+    const lexicalCwd = resolve(input.cwd);
+    const [cwd, configPath] = await Promise.all([
+        realpath(lexicalCwd),
+        canonicalBackgroundConfigPath(lexicalCwd, input.args.configPath),
+    ]);
     const configInput = { env: input.env, cwd, configPath };
     const [registryDir, staleAfterMs] = await Promise.all([
         resolveAppTraceRegistryDir(configInput),
@@ -34,9 +55,41 @@ export async function resolveInstanceTarget(input) {
         // 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) }),
-        pathEnv: defaultPathEnv(input.env),
+        configurationEnvironment: { ...input.env },
+        environment: managedBackgroundEnvironment(input.env),
+        ...(input.requireTui === true ? { requireTui: true } : {}),
     };
 }
+/**
+ * Collapse symlinked parent aliases without following the config's final path
+ * component. The final component is separately required to be a regular,
+ * non-symlink file before start; keeping it unresolved preserves that check.
+ * Missing parents remain addressable so stop/status/logs can still operate on
+ * a previously installed label after an agent folder is damaged or removed.
+ */
+export async function canonicalBackgroundConfigPath(cwd, configuredPath) {
+    const lexical = resolve(cwd, configuredPath ?? "mono-agent.config.json");
+    try {
+        const candidate = join(await realpath(dirname(lexical)), basename(lexical));
+        try {
+            const details = await lstat(candidate);
+            // Preserve the final-component symlink so the start-time regular-file
+            // check can reject it. For a real file, realpath also canonicalises the
+            // stored filename casing on the default case-insensitive macOS volume.
+            return details.isSymbolicLink() ? candidate : await realpath(candidate);
+        }
+        catch (error) {
+            if (isErrno(error, "ENOENT") || isErrno(error, "ENOTDIR"))
+                return candidate;
+            throw error;
+        }
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT") || isErrno(error, "ENOTDIR"))
+            return lexical;
+        throw error;
+    }
+}
 export function defaultBackgroundDeps() {
     return {
         runner: makeLaunchctlRunner(),
@@ -45,10 +98,10 @@ export function defaultBackgroundDeps() {
         sleep: (ms) => new Promise((resolvePromise) => setTimeout(resolvePromise, ms)),
         listRecordedRuns,
         listTraceSources,
-        writeFile: (path, data) => writeFile(path, data, "utf8"),
-        mkdir: (path) => mkdir(path, { recursive: true }).then(() => undefined),
+        writeFile: writeOwnerPrivateLaunchdFile,
+        mkdir: ensureOwnerPrivateLaunchdDirectory,
         rm: (path) => rm(path, { force: true }),
-        stat,
+        stat: inspectOwnerPrivateLaunchdLog,
         rename,
         isAlive: (pid) => {
             try {
@@ -60,6 +113,14 @@ export function defaultBackgroundDeps() {
                 return isErrno(error, "EPERM");
             }
         },
+        ensureManagedRuntime: (input) => ensureManagedBackgroundRuntime(input),
+        resolveManagedRuntimePackages: (target) => resolveConfiguredManagedRuntimePackages({
+            cwd: target.cwd,
+            configPath: target.configPath,
+            env: target.configurationEnvironment,
+        }),
+        acquireLifecycleLock: acquireFilesystemLifecycleLock,
+        probeTui: probeTuiEndpoint,
         stdout: (text) => void process.stdout.write(text),
         stderr: (text) => void process.stderr.write(text),
         spawnTail: (args) => new Promise((resolvePromise) => {
@@ -70,38 +131,176 @@ export function defaultBackgroundDeps() {
     };
 }
 const DEFAULT_POLL = { timeoutMs: 18_000, intervalMs: 400 };
-const SINCE_SKEW_MS = 2_000;
 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 launchBackground(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) {
-    return await launchBackground(target, deps, poll);
+    return (await ensureBackgroundReady(target, deps, poll)).ok ? 0 : 1;
+}
+/**
+ * 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) {
+    const release = await deps.acquireLifecycleLock(target);
+    if (release === undefined) {
+        deps.stderr(ui.errorLine(`Another lifecycle command is already active for ${target.label}.`));
+        deps.stderr(ui.hint("No LaunchAgent or session changes were made. Wait for that command to finish, then retry."));
+        return 1;
+    }
+    try {
+        const stopCode = await stopBackgroundUnlocked(target, deps, poll);
+        if (stopCode !== 0)
+            return stopCode;
+        await whileStopped();
+        return (await ensureBackgroundReadyUnlocked(target, deps, poll)).ok ? 0 : 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)}`));
+        });
+    }
+}
+/**
+ * Ensure the canonical per-config LaunchAgent is running and return the fresh
+ * trace source that proved it reached `startup-complete`. 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) {
+    const release = await deps.acquireLifecycleLock(target);
+    if (release === undefined) {
+        deps.stderr(ui.errorLine(`Another lifecycle command is already active for ${target.label}.`));
+        deps.stderr(ui.hint("No LaunchAgent changes were made. Wait for that command to finish, then retry."));
+        return { ok: false, action: "start", reason: "ownership" };
+    }
+    try {
+        return await ensureBackgroundReadyUnlocked(target, deps, poll);
+    }
+    finally {
+        await release().catch((error) => {
+            deps.stderr(ui.errorLine(`Could not release lifecycle lock for ${target.label}: ${error instanceof Error ? error.message : String(error)}`));
+        });
+    }
 }
-async function launchBackground(target, deps, poll) {
+async function ensureBackgroundReadyUnlocked(target, deps, poll) {
+    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();
-    await writePlist(target, deps);
-    await rotateLaunchdLogs(target.paths, deps);
-    const sinceMs = deps.now();
-    const outcome = await bootstrapOrRestart(target, deps, uid);
+    if (!(await snapshotStillMatches(target, deps))) {
+        reportSnapshotDrift(target, deps);
+        return { ok: false, action: "start", reason: "snapshot" };
+    }
+    let launchTarget;
+    try {
+        const additionalPackages = await deps.resolveManagedRuntimePackages?.(target) ?? [];
+        const runtime = await deps.ensureManagedRuntime({
+            currentCliPath: target.cliPath,
+            nodePath: target.nodePath,
+            additionalPackages,
+        });
+        launchTarget = {
+            ...target,
+            cliPath: runtime.cliPath,
+            nodePath: runtime.nodePath,
+        };
+    }
+    catch (error) {
+        reportLifecycleException(target, deps, "install and verify the durable managed runtime", error);
+        return { ok: false, action: "start", reason: "runtime" };
+    }
+    // Runtime materialisation can involve npm/native installation. Recheck the
+    // approved files after that unbounded external work and before writing any
+    // LaunchAgent state.
+    if (!(await snapshotStillMatches(launchTarget, deps))) {
+        reportSnapshotDrift(launchTarget, deps);
+        return { ok: false, action: "start", reason: "snapshot" };
+    }
+    try {
+        const conflict = await findOwnershipConflict(launchTarget, deps, uid);
+        if (conflict !== undefined) {
+            reportOwnershipConflict(launchTarget, deps, conflict);
+            return { ok: false, action: "start", reason: "ownership" };
+        }
+    }
+    catch (error) {
+        reportLifecycleException(launchTarget, deps, "verify the existing background worker ownership", error);
+        return { ok: false, action: "start", reason: "ownership" };
+    }
+    let sinceMs;
+    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);
+        return { ok: false, action: "start", reason: "preparation" };
+    }
+    let outcome;
+    try {
+        outcome = await bootstrapOrRestart(launchTarget, deps, uid, poll);
+    }
+    catch (error) {
+        reportLifecycleException(launchTarget, deps, "start the LaunchAgent", error);
+        return { ok: false, action: "start", reason: "launchctl" };
+    }
+    const action = outcome.restarted ? "restart" : "start";
     if (!outcome.ok) {
-        return failLaunch(target, deps, outcome.restarted ? "restart" : "start", outcome.failure);
+        reportLaunchFailure(launchTarget, deps, action, outcome.failure);
+        return { ok: false, action, reason: "launchctl" };
     }
     deps.stdout(ui.hint("Waiting for the worker to report ready…"));
-    const ready = await pollInstanceReady(target, deps, { ...poll, sinceMs });
+    let ready;
+    try {
+        ready = await pollInstanceReady(launchTarget, deps, {
+            ...poll,
+            sinceMs,
+            ...(launchTarget.requireTui === true ? { requireTui: true } : {}),
+        });
+    }
+    catch (error) {
+        reportLifecycleException(launchTarget, deps, "read the worker readiness trace", error);
+        return { ok: false, action, reason: "readiness" };
+    }
     if (ready === undefined) {
-        return reportTimeout(target, deps);
+        if (!(await snapshotStillMatches(launchTarget, deps))) {
+            const stopped = await stopBackgroundUnlocked(launchTarget, deps, poll);
+            reportSnapshotDrift(launchTarget, deps);
+            if (stopped === 0) {
+                deps.stderr(ui.style.dim("The drifted LaunchAgent was stopped before returning control.") + "\n");
+            }
+            else {
+                deps.stderr(ui.style.yellow("The drifted LaunchAgent could not be proven stopped; follow the recovery commands above.") + "\n");
+            }
+            return { ok: false, action, reason: "snapshot" };
+        }
+        reportTimeout(launchTarget, deps);
+        return { ok: false, action, reason: "timeout" };
     }
-    printInstanceInfo(ready, target, deps, outcome.restarted ? "restarted" : "started");
-    return 0;
+    const completedAction = outcome.restarted ? "restarted" : "started";
+    printInstanceInfo(ready, launchTarget, deps, completedAction);
+    return { ok: true, action: completedAction, source: ready };
 }
-async function writePlist(target, deps) {
+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.
+    await deps.mkdir(dirname(target.paths.logDir));
     await deps.mkdir(target.paths.logDir);
     await deps.mkdir(target.paths.launchAgentsDir);
+}
+async function writePlist(target, deps) {
+    if (target.expectedSnapshot === undefined) {
+        throw new Error("A managed LaunchAgent requires an approved background snapshot.");
+    }
     const xml = buildPlistXml({
         label: target.label,
         nodePath: target.nodePath,
@@ -109,9 +308,10 @@ async function writePlist(target, deps) {
         configPath: target.configPath,
         cwd: target.cwd,
         ...(target.envFile === undefined ? {} : { envFile: target.envFile }),
+        expectedBackgroundSnapshot: encodeBackgroundSnapshot(target.expectedSnapshot),
         stdoutPath: target.paths.stdoutPath,
         stderrPath: target.paths.stderrPath,
-        pathEnv: target.pathEnv,
+        environment: target.environment,
     });
     await deps.writeFile(target.paths.plistPath, xml);
 }
@@ -126,8 +326,10 @@ async function rotateLaunchdLog(path, deps) {
     try {
         size = (await deps.stat(path)).size;
     }
-    catch {
-        return;
+    catch (error) {
+        if (isErrno(error, "ENOENT"))
+            return;
+        throw error;
     }
     if (size <= LAUNCHD_LOG_MAX_BYTES) {
         return;
@@ -144,52 +346,270 @@ async function rotateLaunchdLog(path, deps) {
         }
     }
 }
+async function ensureOwnerPrivateLaunchdDirectory(path) {
+    const parent = dirname(path);
+    const parentDetails = await lstat(parent);
+    assertOwnerDirectory(parentDetails, parent, "LaunchAgent parent");
+    try {
+        await mkdir(path, { mode: 0o700 });
+    }
+    catch (error) {
+        if (!isErrno(error, "EEXIST"))
+            throw error;
+    }
+    const parentAfter = await lstat(parent);
+    assertOwnerDirectory(parentAfter, parent, "LaunchAgent parent");
+    if (!sameFilesystemIdentity(parentDetails, parentAfter)) {
+        throw new Error(`LaunchAgent parent ${parent} changed while ${path} was created.`);
+    }
+    const handle = await open(path, fsConstants.O_RDONLY | fsConstants.O_DIRECTORY | fsConstants.O_NOFOLLOW);
+    try {
+        const before = await handle.stat();
+        assertOwnerDirectory(before, path, "LaunchAgent directory");
+        await handle.chmod(0o700);
+        const secured = await handle.stat();
+        if (!sameFilesystemIdentity(before, secured)) {
+            throw new Error(`LaunchAgent directory ${path} changed while it was secured.`);
+        }
+        assertOwnerDirectory(secured, path, "LaunchAgent directory");
+        if ((secured.mode & 0o077) !== 0) {
+            throw new Error(`LaunchAgent directory ${path} must be owner-only.`);
+        }
+        const current = await lstat(path);
+        if (!sameFilesystemIdentity(secured, current)) {
+            throw new Error(`LaunchAgent directory ${path} changed while it was secured.`);
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function writeOwnerPrivateLaunchdFile(path, data) {
+    let existing;
+    try {
+        existing = await lstat(path);
+        assertOwnerRegularFile(existing, path, "LaunchAgent plist");
+    }
+    catch (error) {
+        if (!isErrno(error, "ENOENT"))
+            throw error;
+    }
+    const temporaryPath = join(dirname(path), `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+    let handle = await open(temporaryPath, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_NOFOLLOW, 0o600);
+    try {
+        await handle.writeFile(data, "utf8");
+        await handle.chmod(0o600);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        const temporary = await lstat(temporaryPath);
+        assertOwnerRegularFile(temporary, temporaryPath, "temporary LaunchAgent plist");
+        if ((temporary.mode & 0o777) !== 0o600) {
+            throw new Error(`Temporary LaunchAgent plist ${temporaryPath} must be owner-readable and owner-writable only.`);
+        }
+        let current;
+        try {
+            current = await lstat(path);
+        }
+        catch (error) {
+            if (!isErrno(error, "ENOENT"))
+                throw error;
+        }
+        if ((existing === undefined) !== (current === undefined)
+            || (existing !== undefined && current !== undefined && !sameFilesystemIdentity(existing, current))) {
+            throw new Error(`LaunchAgent plist ${path} changed before the new definition was committed.`);
+        }
+        await rename(temporaryPath, path);
+        const committed = await lstat(path);
+        assertOwnerRegularFile(committed, path, "LaunchAgent plist");
+        if (!sameFilesystemIdentity(temporary, committed)) {
+            throw new Error(`LaunchAgent plist ${path} changed while the new definition was committed.`);
+        }
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+        await rm(temporaryPath, { force: true }).catch(() => undefined);
+    }
+}
+async function inspectOwnerPrivateLaunchdLog(path) {
+    const handle = await open(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    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(secured, path, "LaunchAgent log");
+        const current = await lstat(path);
+        if (!sameFilesystemIdentity(secured, current)) {
+            throw new Error(`LaunchAgent log ${path} changed while it was secured.`);
+        }
+        return secured;
+    }
+    finally {
+        await handle.close();
+    }
+}
+function assertOwnerDirectory(details, path, description) {
+    if (!details.isDirectory() || details.isSymbolicLink()) {
+        throw new Error(`${description} ${path} must be a real directory.`);
+    }
+    assertCurrentUserOwns(details, path, description);
+}
+function assertOwnerRegularFile(details, path, description) {
+    if (!details.isFile() || details.isSymbolicLink()) {
+        throw new Error(`${description} ${path} must be a regular non-symbolic-link file.`);
+    }
+    if (details.nlink !== 1) {
+        throw new Error(`${description} ${path} must have exactly one filesystem link.`);
+    }
+    assertCurrentUserOwns(details, path, description);
+}
+function assertCurrentUserOwns(details, path, description) {
+    if (typeof process.getuid === "function" && details.uid !== process.getuid()) {
+        throw new Error(`${description} ${path} is not owned by the current user.`);
+    }
+}
+function sameFilesystemIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
 /**
- * Idempotent: bootstrap when not loaded, otherwise `kickstart -k` to restart.
- * `bootstrap` reporting "already bootstrapped" (or any non-zero) is tolerated as
- * long as a follow-up `print` confirms the service is loaded.
+ * 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) {
-    if (!(await isLoaded(deps.runner, target.label, uid))) {
+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 restart = await kickstartRestart(deps.runner, target.label, uid);
-    if (restart.code === 0) {
-        return { ok: true, restarted: true };
+    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 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) {
+        return {
+            ok: false,
+            restarted: true,
+            failure: lifecycleFailure(removed, "launchd still reports the previous service as loaded after bootout"),
+        };
+    }
+    const stopped = await pollUntil(deps, poll, async () => oldPids.every((pid) => !deps.isAlive(pid)));
+    if (!stopped) {
+        return {
+            ok: false,
+            restarted: true,
+            failure: lifecycleFailure(removed, `previous worker pid(s) ${oldPids.join(", ")} remained alive after bootout`),
+        };
     }
-    // Fallback: a full unload + reload cycle.
-    await bootout(deps.runner, target.label, uid);
     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 };
     }
     return { ok: false, restarted: true, failure: booted };
 }
-export async function stopBackground(target, deps) {
+async function findOwnershipConflict(target, deps, uid) {
+    const [service, sources] = await Promise.all([
+        launchdServiceInfo(deps.runner, target.label, uid),
+        findInstances(target, deps),
+    ]);
+    const live = sources.filter((source) => source.health !== "stopped" && source.pid !== undefined && deps.isAlive(source.pid));
+    if (live.length === 0)
+        return undefined;
+    if (!service.loaded || service.pid === undefined || !deps.isAlive(service.pid)) {
+        return `live matching trace pid(s) ${live.map((source) => source.pid).join(", ")} are not owned by a live ${target.label} launchd job`;
+    }
+    const foreign = live.filter((source) => source.pid !== service.pid);
+    if (foreign.length > 0) {
+        return `live matching trace pid(s) ${foreign.map((source) => source.pid).join(", ")} differ from launchd pid ${service.pid}`;
+    }
+    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_POLL) {
+    const release = await deps.acquireLifecycleLock(target);
+    if (release === undefined) {
+        deps.stderr(ui.errorLine(`Another lifecycle command is already active for ${target.label}.`));
+        deps.stderr(ui.hint("The LaunchAgent plist was preserved. Wait for that command to finish, then retry."));
+        return 1;
+    }
+    try {
+        return await stopBackgroundUnlocked(target, deps, poll);
+    }
+    finally {
+        await release().catch((error) => {
+            deps.stderr(ui.errorLine(`Could not release lifecycle lock for ${target.label}: ${error instanceof Error ? error.message : String(error)}`));
+        });
+    }
+}
+async function stopBackgroundUnlocked(target, deps, poll) {
     const uid = deps.getuid();
-    const existing = await findInstance(target, deps);
-    const wasLoaded = await isLoaded(deps.runner, target.label, uid);
+    const existing = await findInstances(target, deps);
+    const service = await launchdServiceInfo(deps.runner, target.label, uid);
+    const liveTracePids = uniquePids(existing
+        .filter((source) => source.health !== "stopped" && source.pid !== undefined && deps.isAlive(source.pid))
+        .map((source) => source.pid));
+    if (liveTracePids.some((pid) => pid !== service.pid)) {
+        deps.stderr(ui.errorLine(`Refusing to stop ${target.label}: matching live trace pid(s) ${liveTracePids.join(", ")} are not owned by that launchd job.`));
+        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);
-    // Removing the plist stops it from relaunching at the next login.
-    await deps.rm(target.paths.plistPath);
-    await maybeUnlinkDeadManifest(target, deps, existing);
-    // `bootout` also exits non-zero when the service was never loaded, which is
-    // fine. A non-zero exit is only a real failure if the service is still loaded
-    // afterwards — otherwise we'd silently swallow genuine stop failures.
-    if (result.code !== 0 && (await isLoaded(deps.runner, target.label, uid))) {
-        deps.stderr(ui.errorLine(`Failed to stop ${target.label}: launchctl bootout exited ${result.code}.`));
+    const unloaded = await pollUntil(deps, poll, async () => !(await launchdServiceInfo(deps.runner, target.label, uid)).loaded);
+    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();
         if (detail.length > 0) {
             deps.stderr(ui.style.dim(detail) + "\n");
         }
-        deps.stderr(ui.hint("The plist was removed, but the service is still running."));
+        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."));
         return 1;
     }
-    deps.stdout(wasLoaded
+    // Remove the plist only after both launchd ownership and process death are
+    // proven. This prevents a failed stop from destroying its recovery handle.
+    await deps.rm(target.paths.plistPath);
+    for (const source of existing)
+        await maybeUnlinkDeadManifest(target, deps, source);
+    deps.stdout(service.loaded
         ? `${ui.badge("ok")}${ui.style.bold(`Stopped ${target.label}`)} and removed its LaunchAgent.\n`
         : `${ui.style.dim(`${target.label} was not running; removed its LaunchAgent if present.`)}\n`);
     deps.stdout(ui.keyValue([["config", target.configPath]]));
@@ -197,10 +617,14 @@ export async function stopBackground(target, deps) {
 }
 export async function statusBackground(target, deps) {
     const result = await deps.listTraceSources({ registryDir: target.registryDir, staleAfterMs: target.staleAfterMs });
-    const current = result.sources.find((source) => matchesConfig(source, target.configPath));
+    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;
     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${configFlag(target)}`));
+        deps.stdout(ui.hint(`Start it with: mono-agent start${commandFlags(target)}`));
     }
     else {
         writeInstanceDetail(current, target, deps);
@@ -208,7 +632,9 @@ export async function statusBackground(target, deps) {
     }
     // Only surface other instances that are live or crashed — cleanly stopped
     // manifests linger in the registry and would just be noise.
-    const others = result.sources.filter((source) => !matchesConfig(source, target.configPath) && source.health !== "stopped");
+    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) {
@@ -229,11 +655,19 @@ export async function tailLogs(target, deps, options) {
 }
 export async function pollInstanceReady(target, deps, options) {
     const deadline = deps.now() + options.timeoutMs;
-    const sinceFloor = options.sinceMs - SINCE_SKEW_MS;
     for (;;) {
-        const match = await findInstance(target, deps);
-        if (match !== undefined && isReady(match) && startedAtMs(match) >= sinceFloor) {
-            return match;
+        const service = await launchdServiceInfo(deps.runner, target.label, deps.getuid());
+        if (service.loaded && service.pid !== undefined && deps.isAlive(service.pid)) {
+            const matches = await findInstances(target, deps);
+            const match = matches.find((source) => source.pid === service.pid);
+            if (match !== undefined
+                && isReady(match, options.requireTui === true)
+                && startedAtMs(match) >= options.sinceMs
+                && snapshotMetadataMatches(match, target.expectedSnapshot)
+                && await snapshotStillMatches(target, deps)
+                && (options.requireTui !== true || await deps.probeTui(match))) {
+                return match;
+            }
         }
         if (deps.now() >= deadline) {
             return undefined;
@@ -241,15 +675,52 @@ export async function pollInstanceReady(target, deps, options) {
         await deps.sleep(options.intervalMs);
     }
 }
+async function snapshotStillMatches(target, deps) {
+    if (target.expectedSnapshot === undefined)
+        return true;
+    const capture = deps.captureSnapshot ?? captureTargetSnapshot;
+    try {
+        return sameBackgroundSnapshot(await capture(target), target.expectedSnapshot);
+    }
+    catch {
+        return false;
+    }
+}
+async function captureTargetSnapshot(target) {
+    return await captureBackgroundSnapshot({
+        cwd: target.cwd,
+        configPath: target.configPath,
+        ...(target.envFile === undefined ? {} : { envFile: target.envFile }),
+        env: target.configurationEnvironment,
+    });
+}
+function snapshotMetadataMatches(source, expected) {
+    if (expected === undefined)
+        return true;
+    const actual = backgroundSnapshotFromMetadata(source.metadata);
+    return actual !== undefined && sameBackgroundSnapshot(actual, expected);
+}
+function reportSnapshotDrift(target, deps) {
+    deps.stderr(ui.errorLine("The committed config, dotenv, Identity, Soul, MCP config, or durable environment changed before background readiness."));
+    deps.stderr(ui.style.dim("No readiness claim was made for a different snapshot.") + "\n");
+    reportLaunchRecovery(target, deps);
+}
 export function printInstanceInfo(source, target, deps, verb) {
-    const flag = configFlag(target);
+    const flag = commandFlags(target);
     deps.stdout(`${ui.badge("ok")}${ui.style.bold(`mono-agent ${verb} in the background.`)}\n\n`);
     writeInstanceDetail(source, target, deps);
     deps.stdout("\n" + ui.hint(`Stop with: mono-agent stop${flag}   ·   Logs: mono-agent logs${flag} --follow`));
 }
-async function findInstance(target, deps) {
+async function findInstances(target, deps) {
     const result = await deps.listTraceSources({ registryDir: target.registryDir, staleAfterMs: target.staleAfterMs });
-    return result.sources.find((source) => matchesConfig(source, target.configPath));
+    const matches = await Promise.all(result.sources.map(async (source) => ({
+        source,
+        matches: await matchesConfig(source, target.configPath),
+    })));
+    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
@@ -259,25 +730,38 @@ async function maybeUnlinkDeadManifest(target, deps, existing) {
     }
     await deps.rm(resolve(target.registryDir, `${existing.sourceId}.json`));
 }
-function failLaunch(target, deps, verb, result) {
+function reportLaunchFailure(target, deps, verb, result) {
     deps.stderr(ui.errorLine(`Failed to ${verb} ${target.label} via launchctl${result === undefined ? "" : ` (exit ${result.code})`}.`));
     const detail = (result?.stderr || result?.stdout || "").trim();
     if (detail.length > 0) {
         deps.stderr(ui.style.dim(detail) + "\n");
     }
-    deps.stderr(ui.hint(`Logs: ${target.paths.stderrPath}`));
-    return 1;
+    reportLaunchRecovery(target, deps);
+}
+function reportOwnershipConflict(target, deps, detail) {
+    deps.stderr(ui.errorLine(`Refusing to launch a second worker for ${target.configPath}.`));
+    deps.stderr(ui.style.dim(`${detail}.\n`));
+    deps.stderr(ui.hint("No LaunchAgent changes were made. Stop the unmanaged process or reconcile launchd ownership, then retry."));
+    reportLaunchRecovery(target, deps);
+}
+function reportLifecycleException(target, deps, operation, error) {
+    deps.stderr(ui.errorLine(`Failed to ${operation}: ${error instanceof Error ? error.message : String(error)}`));
+    deps.stderr(ui.style.dim("The committed agent files were preserved.") + "\n");
+    reportLaunchRecovery(target, deps);
 }
 function reportTimeout(target, deps) {
-    const flag = configFlag(target);
     deps.stderr(ui.errorLine("mono-agent did not report ready within the timeout."));
-    deps.stderr(ui.style.dim("It may still be starting, or it may have failed. Inspect:") + "\n");
+    deps.stderr(ui.style.dim("The committed agent files were preserved. It may still be starting, or it may have failed.") + "\n");
+    reportLaunchRecovery(target, deps);
+}
+function reportLaunchRecovery(target, deps) {
+    const flags = commandFlags(target);
+    deps.stderr(ui.style.dim("Retry or inspect with:") + "\n");
     deps.stderr(`  ${ui.style.gray("logs:  ")} ${target.paths.stderrPath}\n` +
         `          ${target.paths.stdoutPath}\n` +
-        `  ${ui.style.gray("follow:")} mono-agent logs${flag} --follow\n` +
-        `  ${ui.style.gray("status:")} mono-agent status${flag}\n` +
-        `  ${ui.style.gray("stop:  ")} mono-agent stop${flag}\n`);
-    return 1;
+        `  ${ui.style.gray("retry: ")} mono-agent start${flags}\n` +
+        `  ${ui.style.gray("status:")} mono-agent status${flags}\n` +
+        `  ${ui.style.gray("follow:")} mono-agent logs${flags} --follow\n`);
 }
 function writeInstanceDetail(source, target, deps) {
     deps.stdout(ui.rule("instance"));
@@ -360,11 +844,32 @@ function formatOtherInstance(source) {
     const config = source.configPath ?? "(unknown config)";
     return `  ${ui.healthBadge(source.health)}${source.health.padEnd(8)} pid ${pid.padEnd(7)} ${source.sourceId}  ${config}`;
 }
-function matchesConfig(source, configPath) {
-    return source.configPath !== undefined && resolve(source.configPath) === configPath;
+async function matchesConfig(source, configPath) {
+    if (source.configPath === undefined)
+        return false;
+    return await canonicalBackgroundConfigPath(process.cwd(), source.configPath) === configPath;
+}
+function isReady(source, requireTui) {
+    if (source.health !== "running" || metadataReason(source) !== "startup-complete")
+        return false;
+    if (source.memoryHealth?.status === "unhealthy")
+        return false;
+    const channels = channelRecords(source);
+    if (channels.some((channel) => channel.kind === "failed"))
+        return false;
+    if (!requireTui)
+        return true;
+    if (channels.some((channel) => typeof channel.kind === "string"
+        && ["failed", "degraded", "waiting_for_config"].includes(channel.kind)))
+        return false;
+    return tuiEndpoint(source) !== undefined;
 }
-function isReady(source) {
-    return source.health === "running" && metadataReason(source) === "startup-complete";
+function channelRecords(source) {
+    const channels = source.metadata?.channels;
+    if (channels === null || typeof channels !== "object")
+        return [];
+    return Object.values(channels)
+        .filter((value) => value !== null && typeof value === "object");
 }
 function metadataReason(source) {
     const reason = source.metadata?.reason;
@@ -519,7 +1024,244 @@ function stringFieldAsList(record, key) {
 /** ` --config <path>` when a non-default config is in play, else empty. */
 function configFlag(target) {
     const defaultPath = resolve(target.cwd, "mono-agent.config.json");
-    return target.configPath === defaultPath ? "" : ` --config ${target.configPath}`;
+    return target.configPath === defaultPath ? "" : ` --config ${shellCommandArgument(target.configPath)}`;
+}
+function commandFlags(target) {
+    return `${configFlag(target)}${target.envFile === undefined ? "" : ` --env-file ${shellCommandArgument(target.envFile)}`}`;
+}
+function shellCommandArgument(value) {
+    return /^[a-zA-Z0-9_./:@%+=,-]+$/u.test(value) ? value : `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+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.");
+    }
+    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)
+                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,
+                ...(incarnation === undefined ? {} : { incarnation }),
+            }
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return isErrno(error, "EPERM");
+    }
+}
+async function probeTuiEndpoint(source) {
+    const baseUrl = tuiEndpoint(source);
+    if (baseUrl === undefined)
+        return false;
+    let url;
+    try {
+        url = new URL(`${baseUrl.replace(/\/+$/u, "")}/v1/info`);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol !== "http:" || !isLoopbackHostname(url.hostname))
+        return false;
+    try {
+        const response = await fetch(url, { signal: AbortSignal.timeout(1_000) });
+        // Authenticated adapters return 401/403 without the secret. That still
+        // proves the advertised loopback listener is reachable; an open endpoint
+        // additionally proves it belongs to the expected worker pid.
+        if (response.status === 401 || response.status === 403)
+            return true;
+        if (!response.ok)
+            return false;
+        const body = await response.json();
+        return typeof source.pid === "number" && body.pid === source.pid;
+    }
+    catch {
+        return false;
+    }
+}
+function isLoopbackHostname(hostname) {
+    return hostname === "127.0.0.1" || hostname === "::1" || hostname === "localhost";
+}
+function tuiEndpoint(source) {
+    const channels = source.metadata?.channels;
+    if (channels === null || typeof channels !== "object")
+        return undefined;
+    const tui = channels.tui;
+    if (tui === null || typeof tui !== "object")
+        return undefined;
+    const record = tui;
+    return record.kind === "running" && typeof record.baseUrl === "string" && record.baseUrl.trim().length > 0
+        ? record.baseUrl
+        : undefined;
 }
 function formatChannels(source) {
     const channels = source.metadata?.channels;