@mono-agent/agent-app 0.8.0 → 0.9.0

package/dist/cli.js

@@ -13,7 +13,9 @@ import { startMonoAgentApp } from "./app.js";
 import { describeSensitiveDataExportWarning, isAppCoreConfigError, loadAppCoreConfig, phoenixAppBaseUrl, } from "./app-config.js";
 import { runAuditRuns } from "./audit-runs.js";
 import { runBackfill } from "./backfill.js";
-import { defaultBackgroundDeps, resolveInstanceTarget, restartBackground, startBackground, statusBackground, stopBackground, tailLogs, } from "./background.js";
+import { acquireBackgroundWorkerLease, canonicalBackgroundConfigPath, defaultBackgroundDeps, ensureBackgroundReady, forceRestartBackground, managedBackgroundEnvironment, resolveInstanceTarget, restartBackground, startBackground, statusBackground, stopBackground, tailLogs, } from "./background.js";
+import { MANAGED_BACKGROUND_WORKER_ENV, sanitizeManagedBackgroundWorkerEnvironment, } from "./background-runtime.js";
+import { captureBackgroundSnapshot, decodeBackgroundSnapshot, captureDurableBackgroundInputs, loadDurableBackgroundEnvironment, materializeBackgroundRuntimeInputs, } from "./background-snapshot.js";
 import { collectChannelConfigViews } from "./channel-config-view.js";
 import { formatChannelFactValue } from "./channel-fact-format.js";
 import { resolveChannelDrivers } from "./channels.js";
@@ -22,6 +24,7 @@ import { validateMonoAgentFolder } from "./doctor.js";
 import { effectiveFirstRunEnvironment, evaluateFirstRunConfigurationReadiness, evaluateFirstRunReadiness, hasSensitivePersistedEnvironmentValue, piAuthPathBackgroundConflict, readCliConfigSnapshot, readCliDotenvFile, readCliDotenvSnapshot, resolveEffectivePiAuthPath, selectedSecretEnvironmentConflicts, selectedSecretValues, unexpectedPersistedMonoAgentOverrides, validateWizardPlanInStaging, withExactProcessEnvironment, } from "./first-run-readiness.js";
 import { initMonoAgentFolder, SecretEnvConcurrentModificationError, verifySecretEnvPersistenceGuard, } from "./init.js";
 import { installComposerSkill } from "./install-skill.js";
+import { deriveLaunchdLabel, launchdPathsFor } from "./launchd.js";
 import { checkManagedProjectSkills, updateManagedProjectSkills } from "./project-skills.js";
 import { runMetrics } from "./metrics.js";
 import { buildRunsHealthDisplay, RUNS_HEALTH_MAX_RUNS } from "./runs-health.js";
@@ -41,7 +44,7 @@ const DEFAULT_LOG_LINES = 200;
 // busy-waiting; larger values silently overflow to a 1ms delay.
 const KEEP_ALIVE_INTERVAL_MS = 2_147_483_647;
 const BACKGROUND_COMMANDS = ["start", "restart", "stop", "status", "logs"];
-const KNOWN_COMMANDS = ["init", "setup", "validate", "doctor", "auth", "sandbox", "config", "recipes", "presets", "start", "restart", "stop", "status", "logs", "tui", "web", "install-skill", "backfill", "audit-runs", "metrics", "memory"];
+const KNOWN_COMMANDS = ["init", "setup", "validate", "doctor", "auth", "sandbox", "config", "recipes", "presets", "start", "restart", "stop", "status", "logs", "tui", "web", "install-skill", "backfill", "audit-runs", "metrics", "memory", "continuations"];
 export function parseCliArgs(argv) {
     const [command, ...rest] = argv;
     if (command === undefined || command === "help" || command === "--help" || command === "-h") {
@@ -83,6 +86,7 @@ export function parseCliArgs(argv) {
     let codexAuthMode;
     const positionals = [];
     let envFile;
+    let expectedBackgroundSnapshot;
     let target;
     let force = false;
     let foreground = false;
@@ -108,6 +112,7 @@ export function parseCliArgs(argv) {
     let json = false;
     let strict = false;
     let limit;
+    let cursor;
     let host;
     let port;
     let open;
@@ -196,12 +201,18 @@ export function parseCliArgs(argv) {
             case "--limit": {
                 const raw = requireValue(rest, ++i, flag);
                 const parsed = Number(raw);
-                if (!Number.isInteger(parsed) || parsed < 1 || parsed > 100) {
-                    throw new Error("--limit must be an integer between 1 and 100.");
+                const maximum = cmd === "continuations" ? 500 : 100;
+                if (!Number.isInteger(parsed) || parsed < 1 || parsed > maximum) {
+                    throw new Error(`--limit must be an integer between 1 and ${String(maximum)}.`);
                 }
                 limit = parsed;
                 break;
             }
+            case "--cursor":
+                cursor = requireValue(rest, ++i, flag).trim();
+                if (cursor.length === 0 || cursor.length > 512)
+                    throw new Error("--cursor must be 1-512 characters.");
+                break;
             case "--host":
                 host = requireValue(rest, ++i, flag);
                 break;
@@ -335,6 +346,9 @@ export function parseCliArgs(argv) {
             case "--env-file":
                 envFile = requireValue(rest, ++i, flag);
                 break;
+            case "--expected-background-snapshot":
+                expectedBackgroundSnapshot = requireValue(rest, ++i, flag);
+                break;
             case "--target": {
                 const raw = requireValue(rest, ++i, flag);
                 if (raw !== "claude" && raw !== "codex" && raw !== "both") {
@@ -388,8 +402,8 @@ export function parseCliArgs(argv) {
     if ((local || configure) && cmd !== "tui") {
         throw new Error("--local and --configure are only supported for `mono-agent tui`.");
     }
-    if (configure && !local) {
-        throw new Error("--configure requires `mono-agent tui --local`.");
+    if (configure && local) {
+        throw new Error("--configure attaches to the authoritative background agent; omit --local.");
     }
     if ((project || check || update) && cmd !== "install-skill") {
         throw new Error("--project, --check, and --update are only supported for `mono-agent install-skill`.");
@@ -412,8 +426,14 @@ export function parseCliArgs(argv) {
     if (includeMemory && cmd !== "audit-runs" && cmd !== "metrics" && cmd !== "backfill" && cmd !== "web") {
         throw new Error("--include-memory is only supported for `mono-agent audit-runs`, `mono-agent metrics`, `mono-agent backfill`, and `mono-agent web`.");
     }
-    if (limit !== undefined && cmd !== "memory") {
-        throw new Error("--limit is only supported for `mono-agent memory`.");
+    if (limit !== undefined && cmd !== "memory" && cmd !== "continuations") {
+        throw new Error("--limit is only supported for `mono-agent memory` and `mono-agent continuations list`.");
+    }
+    if ((limit !== undefined || cursor !== undefined) && cmd === "continuations" && (positionals[0] ?? "list") !== "list") {
+        throw new Error("--limit and --cursor are only supported for `mono-agent continuations list`.");
+    }
+    if (cursor !== undefined && cmd !== "continuations") {
+        throw new Error("--cursor is only supported for `mono-agent continuations list`.");
     }
     if (strict && (cmd !== "memory" || (positionals[0] ?? "stats") !== "audit")) {
         throw new Error("--strict is only supported for `mono-agent memory audit`.");
@@ -460,6 +480,7 @@ export function parseCliArgs(argv) {
         ...(codexAuthMode === undefined ? {} : { codexAuthMode }),
         positionals,
         ...(envFile === undefined ? {} : { envFile }),
+        ...(expectedBackgroundSnapshot === undefined ? {} : { expectedBackgroundSnapshot }),
         ...(target === undefined ? {} : { target }),
         force,
         foreground,
@@ -478,6 +499,7 @@ export function parseCliArgs(argv) {
         ...(json ? { json } : {}),
         ...(strict ? { strict } : {}),
         ...(limit === undefined ? {} : { limit }),
+        ...(cursor === undefined ? {} : { cursor }),
         ...(agent === undefined ? {} : { agent }),
         ...(conversation === undefined ? {} : { conversation }),
         ...(local ? { local } : {}),
@@ -617,14 +639,14 @@ const HELP_COMMANDS = [
     },
     {
         signature: "mono-agent tui [--agent <label|sourceId>] [--conversation <id>]\n" +
-            "               [--local [--configure]]",
+            "               [--configure | --local]",
         lines: [
             "Open the operator console from any directory: live chat with full",
             "thinking/tool/telemetry insight, recorded-run replay, and config view.",
             "Discovers running agents via the trace-source registry; one running",
             "agent connects directly, several open a picker.",
-            "--local builds the current folder's responder in-process without a",
-            "daemon; --configure starts the recorded local configuration invitation.",
+            "--configure opens the guided configuration chat on the authoritative",
+            "background agent; --local is an ordinary in-process chat only.",
         ],
     },
     {
@@ -694,6 +716,14 @@ const HELP_COMMANDS = [
             "operation. It returns metadata only and requires rebuild before restart.",
         ],
     },
+    {
+        signature: "mono-agent continuations [list [--limit <n>] [--cursor <opaque>]|health|retry <id>|cancel <id>|resolve <id> delivered|not-delivered|dead-lettered [delivery-id]] [--json]",
+        lines: [
+            "Inspect and operate the authenticated durable-continuation service.",
+            "Ambiguous delivery cannot be retried until it is explicitly resolved;",
+            "no command accepts or changes a channel destination.",
+        ],
+    },
 ];
 const HELP_NOTES = `Background mode runs the agent under launchd, keeping it alive across logins
 (auto-restarting only on crash) until you run stop. Secrets are read from the
@@ -776,6 +806,21 @@ export async function runCli(argv) {
         process.stdout.write(`\n${renderHelp()}`);
         return 2;
     }
+    // Only the internal launchd foreground shape may honor the managed-worker
+    // marker. A hostile/global launchctl environment must not sanitize unrelated
+    // commands such as `mono-agent validate` or `mono-agent status`.
+    const managedBackgroundWorker = args.command === "start" && args.foreground && process.env[MANAGED_BACKGROUND_WORKER_ENV] === "1";
+    if (args.expectedBackgroundSnapshot !== undefined && !managedBackgroundWorker) {
+        process.stderr.write(ui.errorLine("--expected-background-snapshot is reserved for the managed LaunchAgent worker."));
+        return 2;
+    }
+    if (managedBackgroundWorker && args.expectedBackgroundSnapshot === undefined) {
+        process.stderr.write(ui.errorLine("Managed LaunchAgent worker is missing its approved background snapshot."));
+        return 0;
+    }
+    if (managedBackgroundWorker) {
+        sanitizeManagedBackgroundWorkerEnvironment(process.env);
+    }
     if (args.command === "memory"
         && args.positionals[0] === "adopt-replay"
         && hasUnsupportedReplayAdoptionFlag(argv)) {
@@ -822,7 +867,7 @@ export async function runCli(argv) {
         case "presets":
             return runPresets(args);
         case "start":
-            return await runStart(args);
+            return await runStart(args, undefined, managedBackgroundWorker);
         case "restart":
         case "stop":
         case "status":
@@ -835,6 +880,7 @@ export async function runCli(argv) {
                 configPath: resolve(process.cwd(), args.configPath ?? "mono-agent.config.json"),
                 cwd: process.cwd(),
                 env: process.env,
+                ...(args.envFile === undefined ? {} : { envFile: args.envFile }),
                 ...(args.agent === undefined ? {} : { agent: args.agent }),
                 ...(args.conversation === undefined ? {} : { conversationId: args.conversation }),
                 ...(args.local === true ? { local: true } : {}),
@@ -859,6 +905,18 @@ export async function runCli(argv) {
         }
         case "install-skill":
             return await runInstallSkill(args);
+        case "continuations": {
+            const { runContinuationCommand } = await import("./continuation-command.js");
+            return await runContinuationCommand({
+                cwd: process.cwd(),
+                configPath: resolve(process.cwd(), args.configPath ?? "mono-agent.config.json"),
+                env: process.env,
+                positionals: args.positionals,
+                ...(args.json === true ? { json: true } : {}),
+                ...(args.limit === undefined ? {} : { limit: args.limit }),
+                ...(args.cursor === undefined ? {} : { cursor: args.cursor }),
+            });
+        }
         case "backfill":
             return await runBackfill({
                 ...(args.configPath === undefined ? {} : { configPath: args.configPath }),
@@ -1346,6 +1404,14 @@ async function runInit(args, environment) {
                         printIncompleteSetup(["The committed .env could not be read back safely; no readiness claim is safe."], result.configPath);
                         return 1;
                     }
+                    // A missing default .env is a valid, durable empty environment. Keep
+                    // proving its absence in the approved snapshot, but do not turn that
+                    // default into an explicit --env-file argument: the managed worker
+                    // treats an explicitly named missing file as an operator error.
+                    const backgroundEnvFile = args.envFile === undefined
+                        && committedDotenvSnapshot.fingerprint === "missing"
+                        ? undefined
+                        : environment.dotenvPath;
                     const postWriteConflicts = selectedSecretEnvironmentConflicts(result.plan, environment.shellEnv, committedDotenvSnapshot.env, moduleSecrets);
                     const postWriteOverrides = unexpectedPersistedMonoAgentOverrides(result.plan, committedDotenvSnapshot.env);
                     const postWritePiAuthConflict = piAuthPathBackgroundConflict({
@@ -1369,6 +1435,28 @@ async function runInit(args, environment) {
                         printIncompleteSetup(["The durable environment changed after the primary-model check. Retry setup before claiming readiness."], result.configPath);
                         return 1;
                     }
+                    let committedBackgroundSnapshot;
+                    let committedBackgroundEnvironment;
+                    let committedBackgroundConfigSourceFingerprint;
+                    try {
+                        const durableInputs = await captureDurableBackgroundInputs({
+                            cwd,
+                            configPath: result.configPath,
+                            envFile: environment.dotenvPath,
+                            operationalEnvironment: managedBackgroundEnvironment(postWriteEnv),
+                        });
+                        committedBackgroundSnapshot = durableInputs.snapshot;
+                        committedBackgroundEnvironment = durableInputs.environment;
+                        committedBackgroundConfigSourceFingerprint = durableInputs.configSourceFingerprint;
+                    }
+                    catch {
+                        printIncompleteSetup(["The complete committed config, dotenv, Identity, Soul, and MCP snapshot could not be proven safely."], result.configPath);
+                        return 1;
+                    }
+                    if (committedBackgroundConfigSourceFingerprint !== committedConfigSnapshot.fingerprint) {
+                        printIncompleteSetup(["The committed config or durable environment changed before the background snapshot was captured."], result.configPath);
+                        return 1;
+                    }
                     printInitResult(result);
                     let report;
                     try {
@@ -1416,7 +1504,7 @@ async function runInit(args, environment) {
                         return 1;
                     }
                     process.stdout.write(ui.badge("ok") + ui.style.green("All runtime route checks passed — every selected model produced a real no-tool response.\n") +
-                        ui.badge("ok") + ui.style.green("Agent ready — every selected capability passed full validation.\n"));
+                        ui.badge("ok") + ui.style.green("Agent configuration validated — every selected capability passed full validation.\n"));
                     const preTuiConfigDrift = await firstRunConfigDrift(result.configPath, committedConfigSnapshot);
                     if (preTuiConfigDrift !== undefined) {
                         printIncompleteSetup([preTuiConfigDrift.message], result.configPath);
@@ -1432,13 +1520,46 @@ async function runInit(args, environment) {
                         printIncompleteSetup([preTuiSecretGuard.message], result.configPath);
                         return 1;
                     }
-                    process.stdout.write(ui.badge("ok") + ui.style.green("Opening the ready agent in the local configuration TUI.\n"));
+                    if (process.platform !== "darwin") {
+                        printUnsupportedGuidedInitHandoff(result.configPath, backgroundEnvFile);
+                        return 0;
+                    }
+                    process.stdout.write(ui.hint("Starting the authoritative background agent before configuration chat…"));
+                    let background;
+                    try {
+                        const resolvedBackgroundTarget = await resolveInstanceTarget({
+                            args: {
+                                configPath: result.configPath,
+                                ...(backgroundEnvFile === undefined ? {} : { envFile: backgroundEnvFile }),
+                            },
+                            env: { ...committedBackgroundEnvironment },
+                            cwd,
+                            cliPath: fileURLToPath(import.meta.url),
+                            requireTui: true,
+                        });
+                        const backgroundTarget = {
+                            ...resolvedBackgroundTarget,
+                            expectedSnapshot: committedBackgroundSnapshot,
+                        };
+                        background = await ensureBackgroundReady(backgroundTarget, defaultBackgroundDeps());
+                    }
+                    catch (error) {
+                        printUnexpectedGuidedBackgroundFailure(result.configPath, backgroundEnvFile, error);
+                        return 1;
+                    }
+                    if (!background.ok) {
+                        process.stderr.write(ui.hint("The validated agent files were preserved, but configuration chat was not opened because the background agent is not ready."));
+                        return 1;
+                    }
+                    process.stdout.write(ui.badge("ok") + ui.style.green("Agent ready — the background process reported startup complete.\n") +
+                        ui.badge("ok") + ui.style.green("Opening configuration chat on the authoritative background agent.\n"));
                     const { runTui } = await import("./tui-command.js");
-                    return await withExactProcessEnvironment(postWriteEnv, () => runTui({
+                    return await withExactProcessEnvironment(committedBackgroundEnvironment, () => runTui({
                         configPath: result.configPath,
                         cwd,
-                        env: postWriteEnv,
-                        local: true,
+                        env: committedBackgroundEnvironment,
+                        ...(backgroundEnvFile === undefined ? {} : { envFile: backgroundEnvFile }),
+                        agent: background.source.sourceId,
                         configure: true,
                     }));
                 }
@@ -2521,7 +2642,7 @@ async function runAuth(args) {
         return 2;
     }
     const cwd = process.cwd();
-    const configPath = resolve(cwd, args.configPath ?? "mono-agent.config.json");
+    const configPath = await canonicalBackgroundConfigPath(cwd, args.configPath);
     const directCodex = provider === "codex";
     if (directCodex && args.piAuthPath !== undefined) {
         process.stderr.write(ui.errorLine("--pi-auth-path does not apply to direct Codex login."));
@@ -2728,6 +2849,19 @@ export function initChangeDisplayRows(result) {
         unchanged: change.kind === "unchanged",
     }));
 }
+/** Human-readable, value-free proof of where the wizard Role did (or did not) land. */
+export function identityRoleDisplayLine(identityRole) {
+    switch (identityRole.status) {
+        case "created":
+            return `Role saved to ${identityRole.path} → ${identityRole.section}. ` +
+                `Edit ${identityRole.path} → ${identityRole.section} later to change it.`;
+        case "preserved":
+            return `${identityRole.path} already existed and was preserved; the entered Role was not written. ` +
+                `Add or edit ${identityRole.path} → ${identityRole.section} to set it.`;
+        case "planned-create":
+            return `Dry run: Role would be saved to ${identityRole.path} → ${identityRole.section}.`;
+    }
+}
 export function secretChecklistDisplayRows(secrets, configured) {
     return secrets.map((secret) => ({
         envVar: secret.envVar,
@@ -2749,6 +2883,7 @@ function printInitResult(result) {
         // included in this result or printed here.
         process.stdout.write(`${prefix}${rendered}  ${row.path}\n`);
     }
+    process.stdout.write(`\n${identityRoleDisplayLine(result.identityRole)}\n`);
     if (result.knowledgeFiles.length > 0) {
         process.stdout.write(`\nIdentity references existing knowledge: ${ui.style.cyan(result.knowledgeFiles.join(", "))}\n`);
     }
@@ -2792,12 +2927,45 @@ function printSecretsChecklist(secrets, configured = new Set()) {
     }
 }
 function printNextSteps(configPath) {
+    const startCommand = process.platform === "darwin" ? "mono-agent start" : "mono-agent start --foreground";
+    const tuiCommand = process.platform === "darwin"
+        ? `mono-agent tui --configure ${ui.style.dim("(after the agent reports ready)")}`
+        : `mono-agent tui ${ui.style.dim("(ordinary chat after foreground startup; edit config files manually)")}`;
     process.stdout.write("\n" +
         ui.heading("Next steps") +
         `  ${ui.style.bold("1.")} Edit ${configPath} ${ui.style.dim("(model, channels, skills, memory, sandbox)")}\n` +
         `  ${ui.style.bold("2.")} mono-agent validate\n` +
-        `  ${ui.style.bold("3.")} mono-agent tui --local --configure\n` +
-        `  ${ui.style.bold("4.")} ${process.platform === "darwin" ? "mono-agent start" : "mono-agent start --foreground"} ${ui.style.dim("(optional background/long-running service)")}\n`);
+        `  ${ui.style.bold("3.")} ${startCommand}\n` +
+        `  ${ui.style.bold("4.")} ${tuiCommand}\n`);
+}
+function printUnsupportedGuidedInitHandoff(configPath, envFile) {
+    const flags = guidedHandoffFlags(configPath, envFile);
+    process.stdout.write("\n" +
+        ui.heading("Manual start required") +
+        ui.style.yellow("Automatic background start and configuration chat require macOS launchd.\n") +
+        ui.style.dim("The validated agent files were preserved, but no agent process was started and readiness is not claimed.\n") +
+        `  ${ui.style.bold("Configure manually:")} edit ${configPath} and IDENTITY.md, then run mono-agent validate${flags}\n` +
+        `  ${ui.style.bold("Terminal 1:")} mono-agent start --foreground${flags}\n` +
+        `  ${ui.style.bold("Terminal 2:")} mono-agent tui${flags} ${ui.style.dim("(ordinary chat after startup completes)")}\n` +
+        ui.style.dim("Conversational configuration requires the managed macOS background lifecycle.\n"));
+}
+function printUnexpectedGuidedBackgroundFailure(configPath, envFile, error) {
+    const flags = guidedHandoffFlags(configPath, envFile);
+    const paths = launchdPathsFor(deriveLaunchdLabel(configPath));
+    process.stderr.write(ui.errorLine(`The background lifecycle failed unexpectedly: ${error instanceof Error ? error.message : String(error)}`));
+    process.stderr.write(ui.style.dim("The validated agent files were preserved, but configuration chat was not opened. Retry or inspect with:\n"));
+    process.stderr.write(`  ${ui.style.gray("logs:  ")} ${paths.stderrPath}\n` +
+        `          ${paths.stdoutPath}\n` +
+        `  ${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 guidedHandoffFlags(configPath, envFile) {
+    return ` --config ${shellCommandArgument(configPath)}`
+        + (envFile === undefined ? "" : ` --env-file ${shellCommandArgument(envFile)}`);
+}
+function shellCommandArgument(value) {
+    return /^[a-zA-Z0-9_./:@%+=,-]+$/u.test(value) ? value : `'${value.replaceAll("'", `'"'"'`)}'`;
 }
 async function runInstallSkill(args) {
     if (args.project === true) {
@@ -3150,13 +3318,19 @@ function colorDetail(status, detail) {
  * refuse on any `error` section. `waiting` (e.g. Ollama/Phoenix not up yet) is
  * runtime-soft and never blocks.
  */
-export async function ensureStartable(args, env = process.env) {
-    const cwd = process.cwd();
-    const configPath = resolve(cwd, args.configPath ?? "mono-agent.config.json");
+export async function ensureStartable(args, env = process.env, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const configPath = options.configPath ?? resolve(cwd, args.configPath ?? "mono-agent.config.json");
     if (!(await pathExists(configPath))) {
         return { ok: false, code: 2, kind: "missing-config", configPath };
     }
-    const report = await validateMonoAgentFolder({ env, cwd, configPath, liveness: false });
+    const report = await validateMonoAgentFolder({
+        env,
+        cwd,
+        configPath,
+        liveness: false,
+        ...(options.preferAppPluginInstall === true ? { preferAppPluginInstall: true } : {}),
+    });
     if (!report.ok) {
         return { ok: false, code: 1, kind: "validation", report };
     }
@@ -3185,9 +3359,9 @@ async function pathExists(path) {
         return false;
     }
 }
-async function runStart(args, env) {
+async function runStart(args, env, managedBackgroundWorker = false) {
     if (args.foreground) {
-        return await runForeground(args, env);
+        return await runForeground(args, env, managedBackgroundWorker);
     }
     return await runBackgroundCommand(args, "start", env);
 }
@@ -3196,56 +3370,155 @@ async function runStart(args, env) {
  * plus traceability, and stays alive until a signal. This is what launchd
  * invokes (via `start --foreground`) and what users get with `--foreground`/`-f`.
  */
-async function runForeground(args, env = process.env) {
-    const pre = await ensureStartable(args, env);
-    if (!pre.ok) {
-        printPreflightFailure(pre);
-        return pre.code;
+async function runForeground(args, env = process.env, managedBackgroundWorker = false) {
+    const cwd = process.cwd();
+    const configPath = await canonicalBackgroundConfigPath(cwd, args.configPath);
+    const startupEnvironment = { ...env };
+    let lease;
+    try {
+        lease = await acquireBackgroundWorkerLease(configPath);
+    }
+    catch (error) {
+        process.stderr.write(ui.errorLine(`Could not acquire the worker singleton lease: ${error instanceof Error ? error.message : String(error)}`));
+        return 1;
+    }
+    if (lease === undefined) {
+        process.stderr.write(ui.errorLine(`Another foreground or managed background worker already owns ${configPath}; refusing to start a duplicate.`));
+        return 1;
+    }
+    let runtimeInputs;
+    let app;
+    try {
+        let backgroundSnapshot;
+        if (managedBackgroundWorker) {
+            try {
+                backgroundSnapshot = decodeBackgroundSnapshot(args.expectedBackgroundSnapshot ?? "");
+                const dotenvPath = resolve(cwd, args.envFile ?? ".env");
+                if (backgroundSnapshot.configPath !== configPath || backgroundSnapshot.dotenvPath !== dotenvPath) {
+                    throw new Error("The approved snapshot paths do not match the managed worker arguments.");
+                }
+                runtimeInputs = await materializeBackgroundRuntimeInputs({
+                    snapshot: backgroundSnapshot,
+                    cwd,
+                    env: startupEnvironment,
+                });
+            }
+            catch (error) {
+                process.stderr.write(ui.errorLine(`Managed worker could not freeze its startup snapshot: ${error instanceof Error ? error.message : String(error)}`));
+                // KeepAlive restarts only unsuccessful exits. This refusal cannot heal
+                // without a new approved snapshot, so exit successfully and let the
+                // controller unload/recreate the job instead of retrying forever.
+                return 0;
+            }
+        }
+        const preflightEnvironment = runtimeInputs?.environment ?? startupEnvironment;
+        const pre = await ensureStartable(args, preflightEnvironment, runtimeInputs === undefined
+            ? {}
+            : {
+                cwd,
+                configPath: runtimeInputs.configPath,
+                preferAppPluginInstall: true,
+            });
+        if (!pre.ok) {
+            printPreflightFailure(pre);
+            return managedBackgroundWorker ? 0 : pre.code;
+        }
+        try {
+            await readCliConfigSnapshot(runtimeInputs?.configPath ?? configPath);
+        }
+        catch (error) {
+            process.stderr.write(ui.errorLine(`Cannot establish the foreground config identity: ${error instanceof Error ? error.message : String(error)}`));
+            return managedBackgroundWorker ? 0 : 1;
+        }
+        app = await startMonoAgentApp({
+            cwd,
+            configPath,
+            ...(runtimeInputs === undefined ? {} : { configReadPath: runtimeInputs.configPath }),
+            env: runtimeInputs?.environment ?? startupEnvironment,
+            logger: consoleLogger(),
+            ...(backgroundSnapshot === undefined ? {} : { backgroundSnapshot }),
+        });
+        await printAppStatus(app);
+        // Block until a shutdown signal. Returning here (the old behavior) let the
+        // process exit immediately whenever no channel owned a live handle — e.g. a
+        // traceability-only config, now that the operator console is retired and the
+        // trace heartbeat timer is unref'd.
+        return await waitForShutdownSignal(app);
+    }
+    finally {
+        await app?.stop().catch(() => undefined);
+        await runtimeInputs?.dispose().catch(() => undefined);
+        await lease.release().catch((error) => {
+            process.stderr.write(ui.style.yellow(`⚠ Could not cleanly release worker singleton lease ${lease.path}: ${error instanceof Error ? error.message : String(error)}`) + "\n");
+        });
     }
-    const app = await startMonoAgentApp({
-        cwd: process.cwd(),
-        env,
-        ...(args.configPath === undefined ? {} : { configPath: args.configPath }),
-        logger: consoleLogger(),
-    });
-    await printAppStatus(app);
-    // Block until a shutdown signal. Returning here (the old behavior) let the
-    // process exit immediately whenever no channel owned a live handle — e.g. a
-    // traceability-only config, now that the operator console is retired and the
-    // trace heartbeat timer is unref'd.
-    return await waitForShutdownSignal(app);
 }
 async function runBackgroundCommand(args, command, env = process.env) {
     const guard = requireDarwin(command);
     if (guard !== undefined) {
         return guard;
     }
+    let controllerEnvironment;
+    try {
+        controllerEnvironment = await loadDurableBackgroundEnvironment({
+            cwd: process.cwd(),
+            ...(args.envFile === undefined ? {} : { envFile: args.envFile }),
+            operationalEnvironment: managedBackgroundEnvironment(env),
+        });
+    }
+    catch (error) {
+        if (command === "start" || command === "restart") {
+            process.stderr.write(ui.errorLine(`Cannot reconstruct the managed worker environment: ${error instanceof Error ? error.message : String(error)}`));
+            process.stderr.write(ui.hint("No LaunchAgent changes were made. Fix the dotenv path and retry."));
+            return 1;
+        }
+        controllerEnvironment = { ...env };
+        process.stderr.write(ui.style.yellow(`⚠ Could not reconstruct the managed worker environment; ${command} will use the current shell only: ${error instanceof Error ? error.message : String(error)}`) + "\n");
+    }
     // Refuse to launch (or relaunch) an unconfigured/broken folder BEFORE writing
     // the plist and bootstrapping launchctl — otherwise the worker would crash and
     // launchd's KeepAlive would retry it forever. stop/status/logs stay ungated so
     // a broken instance can still be inspected and torn down.
     if (command === "start" || command === "restart") {
-        const pre = await ensureStartable(args, env);
+        const pre = await ensureStartable(args, controllerEnvironment);
         if (!pre.ok) {
             printPreflightFailure(pre);
             return pre.code;
         }
     }
-    const target = await resolveInstanceTarget({
+    let target = await resolveInstanceTarget({
         args: {
             ...(args.configPath === undefined ? {} : { configPath: args.configPath }),
             ...(args.envFile === undefined ? {} : { envFile: args.envFile }),
         },
-        env,
+        env: controllerEnvironment,
         cwd: process.cwd(),
         cliPath: fileURLToPath(import.meta.url),
     });
+    if (command === "start" || command === "restart") {
+        try {
+            const expectedSnapshot = await captureBackgroundSnapshot({
+                cwd: target.cwd,
+                configPath: target.configPath,
+                ...(target.envFile === undefined ? {} : { envFile: target.envFile }),
+                env: controllerEnvironment,
+            });
+            target = { ...target, expectedSnapshot };
+        }
+        catch (error) {
+            process.stderr.write(ui.errorLine(`Cannot prove the durable background snapshot: ${error instanceof Error ? error.message : String(error)}`));
+            process.stderr.write(ui.hint("No LaunchAgent changes were made. Fix the config/dotenv/Identity/Soul/MCP mismatch and retry."));
+            return 1;
+        }
+    }
     const deps = defaultBackgroundDeps();
     switch (command) {
         case "start":
             return await startBackground(target, deps);
         case "restart":
-            return args.force ? await runForceRestart(target, deps) : await restartBackground(target, deps);
+            return args.force
+                ? await runForceRestart(target, deps, controllerEnvironment)
+                : await restartBackground(target, deps);
         case "stop":
             return await stopBackground(target, deps);
         case "status":
@@ -3260,20 +3533,17 @@ async function runBackgroundCommand(args, command, env = process.env) {
  * they are deleted; the runtime recreates the store on the next session, and the
  * agent's durable memory lives elsewhere, so only resumable transcripts are dropped.
  */
-async function runForceRestart(target, deps) {
-    const stopCode = await stopBackground(target, deps);
-    if (stopCode !== 0) {
-        return stopCode;
-    }
-    const result = await purgeSessions({ env: process.env, cwd: target.cwd, configPath: target.configPath });
-    if (result.removed) {
-        const count = result.files === 0 ? "" : ` (${result.files} session file${result.files === 1 ? "" : "s"})`;
-        process.stdout.write(`${ui.badge("ok")}${ui.style.bold("Cleared persisted sessions")}${count}.\n`);
-    }
-    else {
-        process.stdout.write(ui.style.dim("No persisted sessions to clear (in-memory or none on disk).") + "\n");
-    }
-    return await startBackground(target, deps);
+async function runForceRestart(target, deps, environment) {
+    return await forceRestartBackground(target, deps, async () => {
+        const result = await purgeSessions({ env: environment, cwd: target.cwd, configPath: target.configPath });
+        if (result.removed) {
+            const count = result.files === 0 ? "" : ` (${result.files} session file${result.files === 1 ? "" : "s"})`;
+            process.stdout.write(`${ui.badge("ok")}${ui.style.bold("Cleared persisted sessions")}${count}.\n`);
+        }
+        else {
+            process.stdout.write(ui.style.dim("No persisted sessions to clear (in-memory or none on disk).") + "\n");
+        }
+    });
 }
 /**
  * Background service mode is launchd-specific. On other platforms point the
@@ -3419,8 +3689,16 @@ export function waitForShutdownSignal(app) {
             clearInterval(keepAlive);
             void (async () => {
                 process.stdout.write("\n" + ui.hint(`Received ${signal}; stopping mono agent app…`));
-                await app.stop();
-                resolve(0);
+                try {
+                    await app.stop();
+                    resolve(0);
+                }
+                catch (error) {
+                    process.stderr.write(ui.errorLine(`Foreground shutdown failed: ${error instanceof Error ? error.message : String(error)}`));
+                    // Resolve so runForeground's finally block can retry idempotent app
+                    // cleanup and release the process-lifetime singleton lease.
+                    resolve(1);
+                }
             })();
         };
         process.on("SIGINT", onSignal);