@mono-agent/agent-app 0.6.2 → 0.9.0

package/dist/cli.js

@@ -1,32 +1,42 @@
 #!/usr/bin/env node
+import { createHash } from "node:crypto";
 import { stat } from "node:fs/promises";
 import { createRequire } from "node:module";
-import { basename, resolve } from "node:path";
+import { basename, dirname, resolve } from "node:path";
 import process from "node:process";
+import { emitKeypressEvents } from "node:readline";
 import { fileURLToPath } from "node:url";
-import { buildMonoAgentConfigView, EFFORT_LEVELS, findJsonSecretConfigWarnings, findRemovedConfigWarnings, readMonoAgentConfigJson, redactMonoAgentConfig, } from "@mono-agent/config";
+import { buildMonoAgentConfigView, EFFORT_LEVELS, findJsonSecretConfigWarnings, findRemovedConfigWarnings, MAX_AGENT_NAME_LENGTH, readMonoAgentConfigJson, redactMonoAgentConfig, } from "@mono-agent/config";
 import { listRecordedRuns } from "@mono-agent/observability";
-import { describeSandboxEffectiveState, sandboxEffectiveStateWarning, } from "@mono-agent/runtime-adapter";
+import { describeSandboxEffectiveState, parseMonoRuntimeModelReference, sandboxEffectiveStateWarning, } from "@mono-agent/runtime-adapter";
 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";
 import { findUnknownAppConfigWarnings } from "./config-reference.js";
 import { validateMonoAgentFolder } from "./doctor.js";
-import { initMonoAgentFolder } from "./init.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";
 import { purgeSessions } from "./sessions.js";
-import { composeWizardPlan } from "./wizard/answers.js";
+import { composeWizardPlan, referencedSetupModelRefs } from "./wizard/answers.js";
 import { answersFromCli, isWithChannel } from "./wizard/from-flags.js";
 import { findPreset, PRESET_CATALOG, presetAnswers, presetIds, RECIPE_TO_PRESET } from "./wizard/presets.js";
-import { runInitWizard } from "./wizard/run.js";
-import { executeProviderSetupPlan, planProviderSetup, providerSetupActionCommandLine } from "./provider-setup.js";
+import { runInitWizard, runSetupRepairWizard } from "./wizard/run.js";
+import { detectProviderCredentialStates, executeProviderSetupPlan, isProviderSetupPiApiKeyAction, planProviderSetup, providerSetupActionCommandLine, } from "./provider-setup.js";
+import { readinessProbeTimeoutMs, runAllRouteReadinessProbe } from "./readiness-probe.js";
+import { checkSandboxRuntime, sandboxRuntimeStatus, setupManagedSrt, } from "./sandbox-manager.js";
+import * as p from "@clack/prompts";
 import * as ui from "./ui.js";
 const DEFAULT_LOG_LINES = 200;
 // Node's maximum setInterval/setTimeout delay (2^31 - 1 ms, ~24.8 days). A
@@ -34,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", "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") {
@@ -58,8 +68,12 @@ export function parseCliArgs(argv) {
                 : command);
     const isLogs = cmd === "logs";
     let configPath;
+    let name;
     let model;
     let fallbackModels;
+    const fallbacks = [];
+    let canAssignFallbackEffort = false;
+    let routeSafety;
     let effort;
     let memory;
     let preset;
@@ -67,8 +81,12 @@ export function parseCliArgs(argv) {
     let withChannels;
     let yes = false;
     let auth = false;
+    let piAuthPath;
+    let apiKeyStdin = false;
+    let codexAuthMode;
     const positionals = [];
     let envFile;
+    let expectedBackgroundSnapshot;
     let target;
     let force = false;
     let foreground = false;
@@ -85,16 +103,26 @@ export function parseCliArgs(argv) {
     let consumerPath;
     let agent;
     let conversation;
+    let local = false;
+    let configure = false;
+    let project = false;
+    let check = false;
+    let update = false;
     let staleAfterMs;
     let json = false;
+    let strict = false;
     let limit;
+    let cursor;
     let host;
     let port;
     let open;
     let allowNonLoopback;
+    let showAuthUrl;
     let maxRunsPerInstance;
     for (let i = 0; i < rest.length; i += 1) {
         const flag = rest[i];
+        if (flag !== "--fallback-effort")
+            canAssignFallbackEffort = false;
         switch (flag) {
             case "--config":
                 configPath = requireValue(rest, ++i, flag);
@@ -140,6 +168,21 @@ export function parseCliArgs(argv) {
             case "--conversation":
                 conversation = requireValue(rest, ++i, flag);
                 break;
+            case "--local":
+                local = true;
+                break;
+            case "--configure":
+                configure = true;
+                break;
+            case "--project":
+                project = true;
+                break;
+            case "--check":
+                check = true;
+                break;
+            case "--update":
+                update = true;
+                break;
             case "--stale-after-ms": {
                 const raw = requireValue(rest, ++i, flag);
                 const parsed = Number(raw);
@@ -152,15 +195,24 @@ export function parseCliArgs(argv) {
             case "--json":
                 json = true;
                 break;
+            case "--strict":
+                strict = true;
+                break;
             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;
@@ -179,6 +231,9 @@ export function parseCliArgs(argv) {
             case "--allow-non-loopback":
                 allowNonLoopback = true;
                 break;
+            case "--show-auth-url":
+                showAuthUrl = true;
+                break;
             case "--max-runs": {
                 const raw = requireValue(rest, ++i, flag);
                 const parsed = Number(raw);
@@ -191,12 +246,55 @@ export function parseCliArgs(argv) {
             case "--model":
                 model = requireValue(rest, ++i, flag);
                 break;
+            case "--name":
+                name = requireValue(rest, ++i, flag).trim();
+                if (Array.from(name).length === 0
+                    || Array.from(name).length > MAX_AGENT_NAME_LENGTH
+                    || /[\u0000-\u001f\u007f]/u.test(name)) {
+                    throw new Error(`--name must be 1-${MAX_AGENT_NAME_LENGTH} characters on one line.`);
+                }
+                break;
             case "--fallback-models":
                 fallbackModels = requireValue(rest, ++i, flag)
                     .split(",")
                     .map((entry) => entry.trim())
                     .filter((entry) => entry.length > 0);
                 break;
+            case "--fallback": {
+                const fallbackModel = requireValue(rest, ++i, flag).trim();
+                if (fallbacks.some((entry) => entry.model === fallbackModel)) {
+                    throw new Error(`Duplicate --fallback model \`${fallbackModel}\`.`);
+                }
+                fallbacks.push({ model: fallbackModel });
+                canAssignFallbackEffort = true;
+                break;
+            }
+            case "--fallback-effort": {
+                if (!canAssignFallbackEffort || fallbacks.length === 0) {
+                    throw new Error("--fallback-effort must immediately follow the --fallback it configures.");
+                }
+                const raw = requireValue(rest, ++i, flag);
+                if (raw !== "provider-default" && !EFFORT_LEVELS.includes(raw)) {
+                    throw new Error(`--fallback-effort must be provider-default or ${EFFORT_LEVELS.join(", ")}.`);
+                }
+                if (raw !== "provider-default") {
+                    const current = fallbacks[fallbacks.length - 1];
+                    fallbacks[fallbacks.length - 1] = {
+                        ...current,
+                        effort: raw,
+                    };
+                }
+                canAssignFallbackEffort = false;
+                break;
+            }
+            case "--route-safety": {
+                const raw = requireValue(rest, ++i, flag);
+                if (raw !== "uniform" && raw !== "per-route-native") {
+                    throw new Error("--route-safety must be uniform or per-route-native.");
+                }
+                routeSafety = raw;
+                break;
+            }
             case "--effort": {
                 const raw = requireValue(rest, ++i, flag);
                 if (!EFFORT_LEVELS.includes(raw)) {
@@ -225,6 +323,20 @@ export function parseCliArgs(argv) {
             case "--auth":
                 auth = true;
                 break;
+            case "--pi-auth-path":
+                piAuthPath = requireValue(rest, ++i, flag);
+                break;
+            case "--api-key-stdin":
+                apiKeyStdin = true;
+                break;
+            case "--codex-auth": {
+                const raw = requireValue(rest, ++i, flag);
+                if (raw !== "browser" && raw !== "device") {
+                    throw new Error("--codex-auth must be browser or device.");
+                }
+                codexAuthMode = raw;
+                break;
+            }
             case "--with":
                 withChannels = requireValue(rest, ++i, flag)
                     .split(",")
@@ -234,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") {
@@ -284,24 +399,75 @@ export function parseCliArgs(argv) {
     if (consumerPath !== undefined && cmd !== "validate" && cmd !== "audit-runs") {
         throw new Error("--consumer is only supported for `mono-agent validate` and `mono-agent audit-runs`.");
     }
-    if ((host !== undefined || port !== undefined || open !== undefined || allowNonLoopback !== undefined || maxRunsPerInstance !== undefined) &&
+    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 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`.");
+    }
+    if ((check || update) && !project) {
+        throw new Error("--check and --update require `mono-agent install-skill --project`.");
+    }
+    if (check && update) {
+        throw new Error("Choose either --check or --update for project skills.");
+    }
+    if ((host !== undefined
+        || port !== undefined
+        || open !== undefined
+        || allowNonLoopback !== undefined
+        || showAuthUrl !== undefined
+        || maxRunsPerInstance !== undefined) &&
         cmd !== "web") {
-        throw new Error("--host, --port, --no-open, --allow-non-loopback, and --max-runs are only supported for `mono-agent web`.");
+        throw new Error("--host, --port, --no-open, --allow-non-loopback, --show-auth-url, and --max-runs are only supported for `mono-agent web`.");
     }
     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`.");
     }
     if (auth && cmd !== "init") {
         throw new Error("--auth is only supported for `mono-agent init`.");
     }
+    if (piAuthPath !== undefined && cmd !== "auth") {
+        throw new Error("--pi-auth-path is only supported for `mono-agent auth`.");
+    }
+    if (apiKeyStdin && cmd !== "auth") {
+        throw new Error("--api-key-stdin is only supported for `mono-agent auth login <provider>`.");
+    }
+    if (codexAuthMode !== undefined && cmd !== "init" && cmd !== "auth") {
+        throw new Error("--codex-auth is only supported for `mono-agent init` and `mono-agent auth login codex`.");
+    }
+    if (fallbackModels !== undefined && fallbacks.length > 0) {
+        throw new Error("Use either legacy --fallback-models or repeated --fallback flags, not both.");
+    }
+    if (fallbackModels !== undefined && new Set(fallbackModels).size !== fallbackModels.length) {
+        throw new Error("--fallback-models contains a duplicate model reference.");
+    }
+    const selectedFallbackModels = fallbackModels ?? fallbacks.map((fallback) => fallback.model);
+    if (model !== undefined && selectedFallbackModels.includes(model)) {
+        throw new Error(`Primary --model \`${model}\` cannot also be a fallback.`);
+    }
     return {
         command: cmd,
         ...(configPath === undefined ? {} : { configPath }),
+        ...(name === undefined ? {} : { name }),
         ...(model === undefined ? {} : { model }),
         ...(fallbackModels === undefined ? {} : { fallbackModels }),
+        ...(fallbacks.length === 0 ? {} : { fallbacks }),
+        ...(routeSafety === undefined ? {} : { routeSafety }),
         ...(effort === undefined ? {} : { effort }),
         ...(memory === undefined ? {} : { memory }),
         ...(preset === undefined ? {} : { preset }),
@@ -309,8 +475,12 @@ export function parseCliArgs(argv) {
         ...(withChannels === undefined ? {} : { withChannels }),
         ...(yes ? { yes } : {}),
         ...(auth ? { auth } : {}),
+        ...(piAuthPath === undefined ? {} : { piAuthPath }),
+        ...(apiKeyStdin ? { apiKeyStdin } : {}),
+        ...(codexAuthMode === undefined ? {} : { codexAuthMode }),
         positionals,
         ...(envFile === undefined ? {} : { envFile }),
+        ...(expectedBackgroundSnapshot === undefined ? {} : { expectedBackgroundSnapshot }),
         ...(target === undefined ? {} : { target }),
         force,
         foreground,
@@ -327,13 +497,21 @@ export function parseCliArgs(argv) {
         ...(consumerPath === undefined ? {} : { consumerPath }),
         ...(staleAfterMs === undefined ? {} : { staleAfterMs }),
         ...(json ? { json } : {}),
+        ...(strict ? { strict } : {}),
         ...(limit === undefined ? {} : { limit }),
+        ...(cursor === undefined ? {} : { cursor }),
         ...(agent === undefined ? {} : { agent }),
         ...(conversation === undefined ? {} : { conversation }),
+        ...(local ? { local } : {}),
+        ...(configure ? { configure } : {}),
+        ...(project ? { project } : {}),
+        ...(check ? { check } : {}),
+        ...(update ? { update } : {}),
         ...(host === undefined ? {} : { host }),
         ...(port === undefined ? {} : { port }),
         ...(open === undefined ? {} : { open }),
         ...(allowNonLoopback === undefined ? {} : { allowNonLoopback }),
+        ...(showAuthUrl === undefined ? {} : { showAuthUrl }),
         ...(maxRunsPerInstance === undefined ? {} : { maxRunsPerInstance }),
     };
 }
@@ -370,14 +548,18 @@ function requireValue(args, index, flag) {
 const HELP_COMMANDS = [
     {
         signature: "mono-agent init [--preset <id>] [--with <csv>] [--yes] [--auth] [--dry-run]\n" +
-            "                [--model <ref>] [--fallback-models <csv>] [--effort <level>]\n" +
-            "                [--memory lite|journal|bujo]",
+            "                [--name <display-name>] [--model <ref>] [--effort <level>]\n" +
+            "                [--fallback <ref> [--fallback-effort <provider-default|level>]]...\n" +
+            "                [--fallback-models <csv>] [--route-safety uniform|per-route-native]\n" +
+            "                [--codex-auth browser|device] [--memory lite|journal|bujo]",
         lines: [
             "Scaffold a mono-agent in the current folder. On a TTY with no flags, launches",
             "the step-by-step wizard; with --yes or any flag, writes the default/preset",
             "scaffold non-interactively. --preset seeds a blueprint, --with adds channels,",
-            "--effort writes runtime.effort, --auth runs supported provider auth/preflight",
-            "commands before writing, and --dry-run previews only. Existing files are never overwritten.",
+            `Effort levels: ${EFFORT_LEVELS.join(", ")}; an omitted fallback effort uses that provider's default.`,
+            "--auth runs supported provider auth/preflight before writing; --codex-auth device supports headless hosts.",
+            "--dry-run previews only. Existing scaffold/config files are not overwritten;",
+            "guided secret setup may securely update .env and .gitignore after explicit review.",
         ],
     },
     {
@@ -392,7 +574,7 @@ const HELP_COMMANDS = [
         ],
     },
     {
-        signature: "mono-agent validate [--preset <id>] [--consumer <path>] [--config <path>] [--env-file <path>]",
+        signature: "mono-agent validate [--preset <id>] [--consumer <path>] [--config <path>] [--env-file <path>] [--json]",
         lines: [
             "Load every config section and report what would run, wait, or fail.",
             "--consumer validates another agent folder read-only, including its .env.",
@@ -400,6 +582,25 @@ const HELP_COMMANDS = [
             "`mono-agent doctor` is an alias for this command.",
         ],
     },
+    {
+        signature: "mono-agent auth login <provider|codex> [--pi-auth-path <path>] [--api-key-stdin]\n" +
+            "                       [--codex-auth browser|device] [--config <path>]",
+        lines: [
+            "Run a supported bundled Pi provider login, or direct Codex browser/device login.",
+            "Pi credentials are promoted with owner-only no-clobber checks.",
+            "API-key providers prompt securely on a TTY; --api-key-stdin explicitly reads a redirected secret.",
+            "Path precedence: --pi-auth-path, MONO_AGENT_PI_AUTH_PATH, providers.piAuthPath, then Pi's default.",
+            "Supported Pi targets: anthropic, github-copilot, openai-codex, and opencode-go.",
+        ],
+    },
+    {
+        signature: "mono-agent sandbox status | setup | check",
+        lines: [
+            "Inspect, install, or functionally prove the pinned SRT sandbox runtime.",
+            "Managed setup is macOS-only and installs into the user's cache; it never changes PATH,",
+            "global npm packages, system packages, or another user's files.",
+        ],
+    },
     {
         signature: "mono-agent config [--config <path>] [--env-file <path>]",
         lines: [
@@ -437,16 +638,19 @@ const HELP_COMMANDS = [
         lines: ["Print (and optionally follow) the background instance's log files."],
     },
     {
-        signature: "mono-agent tui [--agent <label|sourceId>] [--conversation <id>]",
+        signature: "mono-agent tui [--agent <label|sourceId>] [--conversation <id>]\n" +
+            "               [--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.",
+            "--configure opens the guided configuration chat on the authoritative",
+            "background agent; --local is an ordinary in-process chat only.",
         ],
     },
     {
-        signature: "mono-agent web [--host <addr>] [--port <n>] [--no-open] [--allow-non-loopback] [--include-memory] [--max-runs <n>]",
+        signature: "mono-agent web [--host <addr>] [--port <n>] [--no-open] [--allow-non-loopback] [--show-auth-url] [--include-memory] [--max-runs <n>]",
         lines: [
             "Serve the read-only Session Recorder web PWA from any directory: a live",
             "flight-recorder over every agent's runs (prompt, reasoning, tools, cost).",
@@ -455,13 +659,20 @@ const HELP_COMMANDS = [
             "--include-memory also shows memory-maintenance runs. --max-runs (default",
             "200) bounds the in-memory working set; the UI still pages the full",
             "on-disk history via \"Load older\".",
+            "Non-loopback service use requires MONO_AGENT_WEB_AUTH_TOKEN; an",
+            "interactive run may generate one. --show-auth-url reveals a configured",
+            "token only to an interactive terminal. Authenticated URLs are not",
+            "auto-opened through process arguments.",
         ],
     },
     {
-        signature: "mono-agent install-skill [--target claude|codex|both] [--force]",
+        signature: "mono-agent install-skill [--target claude|codex|both] [--force]\n" +
+            "                         --project (--check|--update)",
         lines: [
             "Copy the bundled mono-agent-composer skill into ~/.claude/skills and",
             "~/.agents/skills (default: both). Refuses to overwrite without --force.",
+            "Project mode checks or safely updates the two managed skills generated",
+            "by init; modified copies are never overwritten and updates retain backups.",
         ],
     },
     {
@@ -494,12 +705,23 @@ const HELP_COMMANDS = [
         ],
     },
     {
-        signature: "mono-agent memory [stats|today|show <date>|search <query>|top]\n" +
-            "                  [--limit <n>] [--json] [--config <path>] [--env-file <path>]",
+        signature: "mono-agent memory [stats|today|show <date>|search <query>|top|audit|inspect [id]|retry [id]|resolve <id> <reason>|rebuild|rollback|adopt-replay]\n" +
+            "                  [--limit <n>] [--strict] [--json] [--config <path>] [--env-file <path>]",
         lines: [
             "Preview the configured memory store from an agent folder. Reads the",
             "memory block from mono-agent.config.json, not the standalone memory-bujo",
-            "env workflow. Human-first output by default; --json is for scripts.",
+            "env workflow. Human-first output by default; audit --strict --json is a",
+            "metadata-only health gate. Intake inspect/retry/resolve never print payload content.",
+            "adopt-replay is an explicit stopped-agent, SSH-safe BuJo trust-on-first-use",
+            "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.",
         ],
     },
 ];
@@ -509,11 +731,28 @@ const HELP_NOTES = `Background mode runs the agent under launchd, keeping it ali
 commands require macOS; elsewhere use start --foreground.
 
 Init model references look like pi:<provider>:<model>, claude:claude-sonnet-4-6,
-codex:gpt-5.5, or opencode:<provider>:<model>. The init wizard defaults to
-pi:openai-codex:gpt-5.5, keeps it selectable when Pi auth setup is needed, and
-can save OPENCODE_API_KEY for pi:opencode-go:* refs. Direct codex:gpt-5.5 and
-Claude remain selectable; direct opencode:<provider>:<model> refs are for
-hand-authored runtime backend config.
+codex:gpt-5.6-terra, codex:gpt-5.6-sol, or opencode:<provider>:<model>. The init wizard
+selects the live provider-declared default when available and falls back offline to
+codex:gpt-5.6-terra. Direct and Pi OpenAI-Codex Sol choices remain selectable.
+Direct GPT-5.6 routes require Codex CLI 0.144.0 or newer. Guided Pi authentication
+covers Anthropic, GitHub Copilot, OpenAI Codex, and OpenCode-Go. Claude remains selectable;
+direct opencode:<provider>:<model> refs are for
+hand-authored runtime backend config and are rejected by guided selection/readiness.
+
+Mixed fallback chains are allowed. runtime.routeSafety=uniform (the default)
+requires one compatibility-preserving contract across every route;
+per-route-native makes each route's exact safety boundary explicit (Pi SRT,
+Claude provider-owned permissions, Codex native sandbox, or OpenCode native).
+
+Native mono-agent srt policy is enforced by Pi-owned tools. In uniform mode,
+Claude, direct Codex, and direct OpenCode cannot silently weaken that policy.
+In per-route-native mode, validate reports each provider-owned safety contract
+and rejects capabilities that the selected route cannot represent.
+Direct OpenCode's bridge cannot enforce an explicit runtime.effort; omit effort and
+configure runtime.permissionMode deliberately for hand-authored direct routes.
+It is per-run/non-resumable and rejects MCP (including auto-provisioned memory
+or send tools), positive maxTurns, index skill disclosure, structured output,
+live input, fast mode, and native subagents instead of silently dropping them.
 
 A .env file in the current folder is loaded automatically when present;
 already-exported shell variables take precedence.
@@ -558,14 +797,56 @@ export async function runCli(argv) {
         args = parseCliArgs(argv);
     }
     catch (error) {
+        if (argv[0] === "memory" && argv.includes("adopt-replay")) {
+            const { writeReplayAdoptionCliFailure } = await import("./memory-command.js");
+            writeReplayAdoptionCliFailure(argv.includes("--json"), "replay_adoption_usage");
+            return 2;
+        }
         process.stderr.write(ui.errorLine(error instanceof Error ? error.message : String(error)));
         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)) {
+        const { writeReplayAdoptionCliFailure } = await import("./memory-command.js");
+        writeReplayAdoptionCliFailure(args.json === true, "replay_adoption_usage");
+        return 2;
+    }
     const invocationCwd = process.cwd();
-    loadCliEnvFile(args.command === "validate"
+    // Capture the exported shell before dotenv loading. Guided init retains only
+    // worker-operational values and reports shell/background credential drift;
+    // normal CLI commands still get the established shell-over-dotenv precedence.
+    const shellEnv = { ...process.env };
+    const envFilePath = args.command === "validate"
         ? resolveValidateContext(args, invocationCwd).envFilePath
-        : resolve(invocationCwd, args.envFile ?? ".env"));
+        : resolve(invocationCwd, args.envFile ?? ".env");
+    let dotenvEnv = {};
+    if (args.command === "init") {
+        try {
+            dotenvEnv = await readCliDotenvFile(envFilePath);
+        }
+        catch (error) {
+            process.stderr.write(ui.errorLine(`Cannot read ${envFilePath}: ${error instanceof Error ? error.message : String(error)}`));
+            return 1;
+        }
+    }
+    loadCliEnvFile(envFilePath);
     switch (args.command) {
         case "help":
             process.stdout.write(renderHelp());
@@ -574,15 +855,19 @@ export async function runCli(argv) {
             process.stdout.write(`mono-agent ${monoAgentVersion()}\n`);
             return 0;
         case "init":
-            return await runInit(args);
+            return await runInit(args, { shellEnv, dotenvEnv, dotenvPath: envFilePath });
         case "validate":
             return await runValidate(args);
+        case "auth":
+            return await runAuth(args);
+        case "sandbox":
+            return await runSandboxCommand(args);
         case "config":
             return await runConfig(args);
         case "presets":
             return runPresets(args);
         case "start":
-            return await runStart(args);
+            return await runStart(args, undefined, managedBackgroundWorker);
         case "restart":
         case "stop":
         case "status":
@@ -595,8 +880,11 @@ 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 } : {}),
+                ...(args.configure === true ? { configure: true } : {}),
             });
         }
         case "web": {
@@ -610,12 +898,25 @@ export async function runCli(argv) {
                 ...(args.port === undefined ? {} : { port: args.port }),
                 ...(args.open === undefined ? {} : { open: args.open }),
                 ...(args.allowNonLoopback === undefined ? {} : { allowNonLoopback: args.allowNonLoopback }),
+                ...(args.showAuthUrl === undefined ? {} : { showAuthUrl: args.showAuthUrl }),
                 includeMemory: args.includeMemory,
                 ...(args.maxRunsPerInstance === undefined ? {} : { maxRunsPerInstance: args.maxRunsPerInstance }),
             });
         }
         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 }),
@@ -654,56 +955,872 @@ export async function runCli(argv) {
                 ...(args.configPath === undefined ? {} : { configPath: args.configPath }),
                 positionals: args.positionals,
                 json: args.json === true,
+                strict: args.strict === true,
                 ...(args.limit === undefined ? {} : { limit: args.limit }),
             });
         }
     }
 }
-async function runInit(args) {
+/**
+ * `adopt-replay` is a stopped-store trust boundary, so command-global flags
+ * must never be silently ignored. In particular, `--dry-run` cannot be parsed
+ * successfully and then execute the mutation. Validate the raw invocation so
+ * future parser flags also fail closed unless they are explicitly admitted.
+ */
+function hasUnsupportedReplayAdoptionFlag(argv) {
+    for (let index = 1; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === "--config" || token === "--env-file") {
+            index += 1;
+            continue;
+        }
+        if (token === "--json")
+            continue;
+        if (token?.startsWith("-") === true)
+            return true;
+    }
+    return false;
+}
+const DEFAULT_SANDBOX_COMMAND_DEPENDENCIES = {
+    status: sandboxRuntimeStatus,
+    setup: setupManagedSrt,
+    check: checkSandboxRuntime,
+};
+/** App-owned sandbox lifecycle surface; safe to inject in focused CLI tests. */
+export async function runSandboxCommand(args, dependencies = DEFAULT_SANDBOX_COMMAND_DEPENDENCIES) {
+    const [subcommand, ...extra] = args.positionals;
+    if ((subcommand !== "status" && subcommand !== "setup" && subcommand !== "check") || extra.length > 0) {
+        process.stderr.write(ui.errorLine("[sandbox_usage] Usage: mono-agent sandbox status | setup | check."));
+        return 2;
+    }
+    if (subcommand === "status") {
+        try {
+            printSandboxRuntimeStatus(await dependencies.status());
+            return 0;
+        }
+        catch (error) {
+            process.stderr.write(ui.errorLine(`[sandbox_status_failed] ${reasonOf(error)}`));
+            return 1;
+        }
+    }
+    return await withScopedSandboxCancellation(async (signal) => {
+        try {
+            if (subcommand === "setup") {
+                process.stdout.write(ui.heading("Sandbox setup"));
+                process.stdout.write(ui.style.dim("Installing the pinned SRT copy in the user cache; no PATH, global npm, or system-package changes will be made.\n"));
+                const result = await dependencies.setup({ signal, verify: true });
+                printSandboxSetupResult(result);
+                return 0;
+            }
+            process.stdout.write(ui.heading("Sandbox check"));
+            const result = await dependencies.check({ signal });
+            printSandboxCheckResult(result);
+            return 0;
+        }
+        catch (error) {
+            if (signal.aborted || isAbortLike(error)) {
+                process.stderr.write(ui.errorLine("[sandbox_interrupted] Sandbox operation was interrupted; no partial success was claimed."));
+                process.stderr.write(ui.hint(`Retry safely with \`mono-agent sandbox ${subcommand}\`.\n`));
+                return 130;
+            }
+            const code = subcommand === "setup" ? "sandbox_setup_failed" : "sandbox_check_failed";
+            process.stderr.write(ui.errorLine(`[${code}] ${reasonOf(error)}`));
+            process.stderr.write(ui.hint(`Retry with \`mono-agent sandbox ${subcommand}\` after resolving the error.\n`));
+            return 1;
+        }
+    });
+}
+function printSandboxRuntimeStatus(status) {
+    process.stdout.write(ui.heading("Sandbox status"));
+    process.stdout.write(`  State: ${status.state}\n`);
+    process.stdout.write(`  Source: ${status.source}\n`);
+    process.stdout.write(`  Cache: ${status.installRoot}\n`);
+    process.stdout.write(`  Detail: ${status.message}\n`);
+}
+function printSandboxCheckResult(result) {
+    printSandboxRuntimeStatus(result.status);
+    process.stdout.write(ui.heading("Functional enforcement"));
+    for (const check of result.checks) {
+        process.stdout.write(`${check.ok ? ui.badge("ok") : ui.badge("error")}${check.id}: ${check.detail}\n`);
+    }
+}
+function printSandboxSetupResult(result) {
+    printSandboxRuntimeStatus(result.status);
+    const action = result.repaired ? "repaired" : result.installed ? "installed" : "already installed";
+    process.stdout.write(`${ui.badge("ok")}Managed SRT ${action}; integrity verification passed.\n`);
+    if (result.check !== undefined)
+        printSandboxCheckResult(result.check);
+}
+async function withScopedSandboxCancellation(task) {
+    const controller = new AbortController();
+    let interrupts = 0;
+    const interrupt = () => {
+        interrupts += 1;
+        controller.abort();
+    };
+    const onKeypress = (_value, key) => {
+        if (key?.name === "escape")
+            interrupt();
+    };
+    process.on("SIGINT", interrupt);
+    const restoreKeypress = attachScopedKeypress(onKeypress);
+    try {
+        const result = await task(controller.signal);
+        return interrupts > 1 ? 130 : result;
+    }
+    finally {
+        process.off("SIGINT", interrupt);
+        restoreKeypress();
+    }
+}
+function isAbortLike(error) {
+    return error instanceof Error && (error.name === "AbortError" || /abort|cancel/iu.test(error.message));
+}
+function attachScopedKeypress(listener) {
+    if (!process.stdin.isTTY)
+        return () => undefined;
+    emitKeypressEvents(process.stdin);
+    const input = process.stdin;
+    const wasRaw = input.isRaw === true;
+    const wasFlowing = input.readableFlowing;
+    input.setRawMode?.(true);
+    input.resume();
+    input.on("keypress", listener);
+    return () => {
+        input.off("keypress", listener);
+        input.setRawMode?.(wasRaw);
+        if (wasFlowing !== true)
+            input.pause();
+    };
+}
+async function runInit(args, environment) {
+    const cwd = process.cwd();
     // On an interactive TTY with no overriding flags, walk the step-by-step wizard;
     // any flag (or a piped/non-TTY invocation) takes the silent default/preset path.
-    const wantsWizard = process.stdin.isTTY === true && process.stdout.isTTY === true
-        && args.yes !== true && args.preset === undefined && args.recipe === undefined
-        && args.model === undefined && args.fallbackModels === undefined
-        && args.effort === undefined && args.memory === undefined && args.withChannels === undefined && args.dryRun !== true;
+    const wantsWizard = shouldRunInitWizard(args, process.stdin.isTTY === true, process.stdout.isTTY === true);
     if (wantsWizard) {
         // Existing-config pre-check — don't walk the wizard into a guaranteed no-op.
-        if (await pathExists(resolve(process.cwd(), "mono-agent.config.json"))) {
+        if (await pathExists(resolve(cwd, "mono-agent.config.json"))) {
             process.stdout.write(ui.hint("Found an existing mono-agent.config.json — `mono-agent init` never overwrites. Run `mono-agent validate`, or start in an empty folder.\n"));
             return 0;
         }
-        const outcome = await runInitWizard({ cwd: process.cwd() });
-        if (outcome.status === "cancelled") {
+        let resolvedPiAuthPath = resolveEffectivePiAuthPath({
+            cwd,
+            ...(nonEmptyEnv(environment.dotenvEnv.MONO_AGENT_PI_AUTH_PATH)
+                ? { envPath: environment.dotenvEnv.MONO_AGENT_PI_AUTH_PATH }
+                : {}),
+        });
+        const initial = await runInitWizard({
+            cwd,
+            piAuthPath: resolvedPiAuthPath,
+            persistedEnv: environment.dotenvEnv,
+        });
+        if (initial.status === "cancelled")
             return 1;
-        }
-        if (outcome.runProviderSetup) {
-            const previewPlan = composeWizardPlan(outcome.answers, {
-                dirBasename: basename(process.cwd()),
-                skillsRootExists: await pathExists(resolve(process.cwd(), "skills")),
+        let answers = initial.answers;
+        let moduleSecrets = { ...initial.moduleSecrets };
+        let providerEnvironmentSecrets = { ...initial.providerEnvironmentSecrets };
+        let providerSetupSecrets = { ...initial.providerSetupSecrets };
+        let piApiKeyPersistenceByProvider = { ...initial.piApiKeyPersistenceByProvider };
+        let credentialStates = { ...initial.credentialStates };
+        let pendingProviderSetup = initial.runProviderSetup;
+        let selectedCodexAuthMode = "browser";
+        let readinessProgress;
+        let sandboxMutationCompleted = false;
+        let deferredFailure;
+        firstRun: for (;;) {
+            let dotenvSnapshot = { env: {}, fingerprint: "unreadable" };
+            let failure = deferredFailure;
+            let configurationRecoveryStep;
+            let invalidPlanStage;
+            deferredFailure = undefined;
+            try {
+                dotenvSnapshot = await readCliDotenvSnapshot(environment.dotenvPath);
+            }
+            catch {
+                failure ??= dotenvReadinessFailure("The persisted .env could not be read safely. Fix it before retrying setup.");
+            }
+            const plan = composeWizardPlan(answers, {
+                dirBasename: basename(cwd),
+                skillsRootExists: await pathExists(resolve(cwd, "skills")),
             });
-            const setup = await runProviderSetupBeforeInit({
-                modelRefs: [outcome.answers.model, ...outcome.answers.fallbackModels],
-                cwd: process.cwd(),
-                auth: true,
-                dryRun: false,
-                ...(typeof previewPlan.configJson.providers?.piAuthPath === "string" ? { piAuthPath: previewPlan.configJson.providers.piAuthPath } : {}),
-                apiKeys: outcome.providerSetupSecrets,
+            resolvedPiAuthPath = resolveEffectivePiAuthPath({
+                cwd,
+                ...(nonEmptyEnv(dotenvSnapshot.env.MONO_AGENT_PI_AUTH_PATH)
+                    ? { envPath: dotenvSnapshot.env.MONO_AGENT_PI_AUTH_PATH }
+                    : {}),
+                ...(nonEmptyEnv(plan.configJson.providers?.piAuthPath)
+                    ? { configPath: plan.configJson.providers.piAuthPath }
+                    : {}),
             });
-            if (setup === "failed") {
-                return 1;
+            const effectiveEnv = effectiveFirstRunEnvironment({
+                shellEnv: environment.shellEnv,
+                dotenvEnv: dotenvSnapshot.env,
+                enteredSecrets: { ...moduleSecrets, ...providerEnvironmentSecrets },
+                resolvedPiAuthPath,
+            });
+            // Re-submit every selected durable value, not only values typed during this
+            // wizard session. That lets the secure merge tighten an existing .env to
+            // 0600 while preserving its non-empty operator-owned values verbatim.
+            const selectedSecrets = {
+                ...selectedSecretValues(plan, effectiveEnv),
+                ...providerEnvironmentSecrets,
+            };
+            const secureExistingDotenv = hasSensitivePersistedEnvironmentValue(dotenvSnapshot.env);
+            const conflicts = selectedSecretEnvironmentConflicts(plan, environment.shellEnv, dotenvSnapshot.env, moduleSecrets);
+            const persistedOverrides = unexpectedPersistedMonoAgentOverrides(plan, dotenvSnapshot.env);
+            if (failure === undefined && persistedOverrides.length > 0) {
+                failure = {
+                    ok: false,
+                    kind: "invalid_plan",
+                    message: `Persisted .env contains mono-agent config override${persistedOverrides.length === 1 ? "" : "s"}: ` +
+                        `${persistedOverrides.join(", ")}. Remove ${persistedOverrides.length === 1 ? "it" : "them"} so the ` +
+                        "generated config is the exact config validated and started.",
+                };
+            }
+            if (failure === undefined && conflicts.length > 0) {
+                failure = {
+                    ok: false,
+                    kind: "invalid_plan",
+                    message: `Selected secret${conflicts.length === 1 ? "" : "s"} ${conflicts.join(", ")} ` +
+                        "differ between the exported shell, persisted .env, or newly entered value. " +
+                        "Unset the shell value or make every source match, then retry.",
+                };
+            }
+            if (failure === undefined && piAuthPathBackgroundConflict({
+                cwd,
+                shellPath: environment.shellEnv.MONO_AGENT_PI_AUTH_PATH,
+                dotenvPath: dotenvSnapshot.env.MONO_AGENT_PI_AUTH_PATH,
+                ...(nonEmptyEnv(plan.configJson.providers?.piAuthPath)
+                    ? { configPath: plan.configJson.providers.piAuthPath }
+                    : {}),
+            })) {
+                failure = {
+                    ok: false,
+                    kind: "invalid_plan",
+                    message: "The exported MONO_AGENT_PI_AUTH_PATH selects a different credential store than a background start. " +
+                        "Persist the same path in .env or providers.piAuthPath, or unset the shell override, then retry.",
+                };
+            }
+            if (failure === undefined && pendingProviderSetup) {
+                pendingProviderSetup = false;
+                const modelRefs = referencedSetupModelRefs(plan);
+                const credentialObservation = await withScopedPreflightCancellation(async (abortSignal) => ({
+                    states: await detectProviderCredentialStates({
+                        modelRefs,
+                        cwd,
+                        piAuthPath: resolvedPiAuthPath,
+                        persistedEnv: dotenvSnapshot.env,
+                        abortSignal,
+                    }),
+                    interrupted: abortSignal.aborted,
+                }));
+                if (credentialObservation.interrupted) {
+                    pendingProviderSetup = true;
+                    deferredFailure = {
+                        ok: false,
+                        kind: "cancelled",
+                        message: "Provider status detection was interrupted. No agent files were written.",
+                        interrupted: true,
+                    };
+                    continue firstRun;
+                }
+                credentialStates = credentialObservation.states;
+                const plannedSetup = planProviderSetup({
+                    modelRefs,
+                    cwd,
+                    piAuthPath: resolvedPiAuthPath,
+                    credentialStates,
+                    piApiKeyPersistenceByProvider,
+                });
+                if (plannedSetup.actions.some((action) => action.id === "codex-login")) {
+                    const selected = await selectCodexAuthMode(selectedCodexAuthMode);
+                    if (selected === undefined)
+                        return 1;
+                    selectedCodexAuthMode = selected;
+                }
+                const environmentApiKeys = environmentProviderApiKeys(plannedSetup, effectiveEnv);
+                const missingEnvironmentKeys = plannedSetup.actions
+                    .filter(isProviderSetupPiApiKeyAction)
+                    .filter((action) => action.persistence === "environment" && environmentApiKeys[action.id] === undefined)
+                    .map((action) => action.envVar);
+                if (missingEnvironmentKeys.length > 0) {
+                    for (const envVar of missingEnvironmentKeys) {
+                        const answer = await p.password({
+                            message: `Enter ${envVar} for the agent's owner-only .env`,
+                            validate: (value) => (value ?? "").trim().length === 0 ? "API key is required." : undefined,
+                            clearOnError: true,
+                        });
+                        if (p.isCancel(answer))
+                            return 1;
+                        providerEnvironmentSecrets[envVar] = answer;
+                    }
+                    pendingProviderSetup = true;
+                    continue firstRun;
+                }
+                const setup = await withScopedPreflightCancellation((abortSignal) => withExactProcessEnvironment(effectiveEnv, () => runProviderSetupBeforeInit({
+                    modelRefs,
+                    cwd,
+                    auth: true,
+                    dryRun: false,
+                    piAuthPath: resolvedPiAuthPath,
+                    apiKeys: { ...providerSetupSecrets, ...environmentApiKeys },
+                    codexAuthMode: selectedCodexAuthMode,
+                    credentialStates,
+                    persistedEnv: dotenvSnapshot.env,
+                    piApiKeyPersistenceByProvider,
+                    abortSignal,
+                })), { keypress: false });
+                if (setup === "fatal")
+                    return 130;
+                if (setup === "interrupted") {
+                    pendingProviderSetup = true;
+                    failure = {
+                        ok: false,
+                        kind: "cancelled",
+                        message: "Provider setup was interrupted. No agent files were written.",
+                        interrupted: true,
+                    };
+                }
+                else if (setup === "failed") {
+                    // A plain retry must revisit provider setup rather than falling
+                    // through to a guaranteed-failing model turn.
+                    pendingProviderSetup = true;
+                    failure = {
+                        ok: false,
+                        kind: "provider_failed",
+                        message: "Provider setup did not complete. No agent files were written.",
+                    };
+                }
+            }
+            if (failure === undefined) {
+                if (answers.sandbox) {
+                    const sandboxPreflight = await runGuidedSandboxPreflight(sandboxMutationCompleted);
+                    sandboxMutationCompleted = sandboxMutationCompleted || sandboxPreflight.ok;
+                    if (!sandboxPreflight.ok)
+                        failure = sandboxPreflight;
+                }
+            }
+            if (failure === undefined) {
+                const configurationGate = await runConfigurationPreflightWithSpinner({
+                    cwd,
+                    answers,
+                    plan,
+                    env: effectiveEnv,
+                    secretValues: selectedSecrets,
+                    secureExistingDotenv,
+                });
+                if (configurationGate.interrupted === true) {
+                    failure = {
+                        ok: false,
+                        kind: "cancelled",
+                        message: "Configuration preflight was interrupted. No agent files were written.",
+                        interrupted: true,
+                    };
+                }
+                else if (!configurationGate.ready) {
+                    configurationRecoveryStep = focusedConfigurationRepairStep(configurationGate.failedSectionIds);
+                    invalidPlanStage = "configuration";
+                    failure = {
+                        ok: false,
+                        kind: "invalid_plan",
+                        message: `Configuration preflight did not pass: ${configurationGate.reasons.join(" ")}`,
+                    };
+                }
+            }
+            if (failure === undefined) {
+                const readiness = await runReadinessProbeWithSpinner({
+                    plan,
+                    effectiveEnv,
+                    resolvedPiAuthPath,
+                    ...(readinessProgress === undefined ? {} : {
+                        resume: {
+                            planFingerprint: readinessProgress.planFingerprint,
+                            successfulRouteKeys: readinessProgress.successfulRouteKeys,
+                        },
+                    }),
+                });
+                readinessProgress = mergeReadinessProgress(readinessProgress, readiness, plan);
+                failure = readiness;
+            }
+            readyAttempt: if (failure.ok) {
+                const stagedGate = await runFinalReadinessValidationWithSpinner({
+                    cwd,
+                    answers,
+                    plan,
+                    env: effectiveEnv,
+                    secretValues: selectedSecrets,
+                    secureExistingDotenv,
+                    verifiedCredentialModelRefs: readinessProgress?.verifiedModelRefs ?? [],
+                });
+                if (stagedGate.interrupted === true) {
+                    failure = {
+                        ok: false,
+                        kind: "cancelled",
+                        message: "Final readiness validation was interrupted. No agent files were written.",
+                        interrupted: true,
+                    };
+                    break readyAttempt;
+                }
+                if (stagedGate.ready) {
+                    const drift = await firstRunDotenvDrift(environment.dotenvPath, dotenvSnapshot);
+                    if (drift !== undefined) {
+                        failure = drift;
+                        break readyAttempt;
+                    }
+                    let result;
+                    try {
+                        result = await initMonoAgentFolder({
+                            dir: cwd,
+                            answers,
+                            env: effectiveEnv,
+                            secretValues: selectedSecrets,
+                            secureExistingDotenv,
+                            requireConfigCreation: true,
+                        });
+                    }
+                    catch (error) {
+                        const recovery = secretPersistenceRecoveryMessage(error);
+                        process.stderr.write(ui.errorLine(`The validated scaffold could not be committed safely. The agent was not started; inspect the destination before retrying.${recovery}`));
+                        return 1;
+                    }
+                    let committedConfigSnapshot;
+                    try {
+                        committedConfigSnapshot = await readCliConfigSnapshot(result.configPath);
+                    }
+                    catch {
+                        printIncompleteSetup(["The committed config could not be read back as the regular file setup created."], result.configPath);
+                        return 1;
+                    }
+                    if (committedConfigSnapshot.contents !== `${JSON.stringify(result.plan.configJson, null, 2)}\n`) {
+                        printIncompleteSetup(["The committed config does not match the exact plan setup validated."], result.configPath);
+                        return 1;
+                    }
+                    let committedDotenvSnapshot;
+                    try {
+                        committedDotenvSnapshot = await readCliDotenvSnapshot(environment.dotenvPath);
+                    }
+                    catch {
+                        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({
+                        cwd,
+                        shellPath: environment.shellEnv.MONO_AGENT_PI_AUTH_PATH,
+                        dotenvPath: committedDotenvSnapshot.env.MONO_AGENT_PI_AUTH_PATH,
+                        ...(nonEmptyEnv(result.plan.configJson.providers?.piAuthPath)
+                            ? { configPath: result.plan.configJson.providers.piAuthPath }
+                            : {}),
+                    });
+                    if (postWriteConflicts.length > 0 || postWriteOverrides.length > 0 || postWritePiAuthConflict) {
+                        printIncompleteSetup(["The committed .env no longer matches the values and generated config that setup approved."], result.configPath);
+                        return 1;
+                    }
+                    const postWriteEnv = effectiveFirstRunEnvironment({
+                        shellEnv: environment.shellEnv,
+                        dotenvEnv: committedDotenvSnapshot.env,
+                        resolvedPiAuthPath,
+                    });
+                    if (!sameConcreteEnvironment(effectiveEnv, postWriteEnv)) {
+                        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 {
+                        report = await validateMonoAgentFolder({
+                            env: postWriteEnv,
+                            cwd,
+                            configPath: result.configPath,
+                            liveness: true,
+                            verifiedCredentialModelRefs: readinessProgress?.verifiedModelRefs ?? [],
+                        });
+                    }
+                    catch {
+                        printIncompleteSetup(["Post-write validation could not complete; no readiness claim is safe."], result.configPath);
+                        return 1;
+                    }
+                    process.stdout.write("\n" + ui.heading("Validation"));
+                    for (const section of report.sections)
+                        process.stdout.write(formatSection(section));
+                    process.stdout.write(renderPlanCompleteness(result.plan.validateExpectations, "Selected capabilities", report));
+                    const configuredSecrets = configuredSecretNames(result, postWriteEnv);
+                    printSecretsChecklist(result.plan.secrets, configuredSecrets);
+                    const finalGate = evaluateFirstRunReadiness({
+                        plan: result.plan,
+                        report,
+                        secretPersistence: result.secretPersistence,
+                        verifiedCredentialModelRefs: readinessProgress?.verifiedModelRefs ?? [],
+                    });
+                    if (!finalGate.ready) {
+                        printIncompleteSetup(finalGate.reasons, result.configPath);
+                        return 1;
+                    }
+                    const postValidationConfigDrift = await firstRunConfigDrift(result.configPath, committedConfigSnapshot);
+                    if (postValidationConfigDrift !== undefined) {
+                        printIncompleteSetup([postValidationConfigDrift.message], result.configPath);
+                        return 1;
+                    }
+                    const postValidationDrift = await firstRunDotenvDrift(environment.dotenvPath, committedDotenvSnapshot);
+                    if (postValidationDrift !== undefined) {
+                        printIncompleteSetup([postValidationDrift.message], result.configPath);
+                        return 1;
+                    }
+                    const postValidationSecretGuard = await firstRunSecretEnvGuardFailure(environment.dotenvPath, result.secretPersistence.status === "persisted");
+                    if (postValidationSecretGuard !== undefined) {
+                        printIncompleteSetup([postValidationSecretGuard.message], result.configPath);
+                        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 configuration validated — every selected capability passed full validation.\n"));
+                    const preTuiConfigDrift = await firstRunConfigDrift(result.configPath, committedConfigSnapshot);
+                    if (preTuiConfigDrift !== undefined) {
+                        printIncompleteSetup([preTuiConfigDrift.message], result.configPath);
+                        return 1;
+                    }
+                    const preTuiDotenvDrift = await firstRunDotenvDrift(environment.dotenvPath, committedDotenvSnapshot);
+                    if (preTuiDotenvDrift !== undefined) {
+                        printIncompleteSetup([preTuiDotenvDrift.message], result.configPath);
+                        return 1;
+                    }
+                    const preTuiSecretGuard = await firstRunSecretEnvGuardFailure(environment.dotenvPath, result.secretPersistence.status === "persisted");
+                    if (preTuiSecretGuard !== undefined) {
+                        printIncompleteSetup([preTuiSecretGuard.message], result.configPath);
+                        return 1;
+                    }
+                    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(committedBackgroundEnvironment, () => runTui({
+                        configPath: result.configPath,
+                        cwd,
+                        env: committedBackgroundEnvironment,
+                        ...(backgroundEnvFile === undefined ? {} : { envFile: backgroundEnvFile }),
+                        agent: background.source.sourceId,
+                        configure: true,
+                    }));
+                }
+                configurationRecoveryStep = focusedConfigurationRepairStep(stagedGate.failedSectionIds);
+                invalidPlanStage = "final_readiness";
+                failure = {
+                    ok: false,
+                    kind: "invalid_plan",
+                    message: `Runtime route checks passed, but the complete agent is not ready: ${stagedGate.reasons.join(" ")}`,
+                };
+            }
+            if (failure.ok)
+                throw new Error("First-run recovery reached without a failure.");
+            if (failure.interrupted === true || failure.kind === "cancelled") {
+                interruptedRecoveryMenu: for (;;) {
+                    const interruptedRecovery = await selectInterruptedFirstRunRecovery();
+                    if (interruptedRecovery === "cancel")
+                        return 1;
+                    if (interruptedRecovery === "restart") {
+                        readinessProgress = undefined;
+                        break interruptedRecoveryMenu;
+                    }
+                    if (interruptedRecovery === "edit") {
+                        const repaired = await runSetupRepairWizard({
+                            cwd,
+                            answers,
+                            piAuthPath: resolvedPiAuthPath,
+                            persistedEnv: dotenvSnapshot.env,
+                            moduleSecrets,
+                            providerSetupSecrets,
+                            providerEnvironmentSecrets,
+                            piApiKeyPersistenceByProvider,
+                            credentialStates,
+                            runProviderSetup: pendingProviderSetup,
+                        });
+                        if (repaired.status === "cancelled")
+                            continue interruptedRecoveryMenu;
+                        answers = repaired.answers;
+                        moduleSecrets = { ...repaired.moduleSecrets };
+                        providerSetupSecrets = { ...repaired.providerSetupSecrets };
+                        providerEnvironmentSecrets = { ...repaired.providerEnvironmentSecrets };
+                        piApiKeyPersistenceByProvider = { ...repaired.piApiKeyPersistenceByProvider };
+                        credentialStates = { ...repaired.credentialStates };
+                        pendingProviderSetup = repaired.runProviderSetup;
+                        if (pendingProviderSetup)
+                            readinessProgress = undefined;
+                    }
+                    break interruptedRecoveryMenu;
+                }
+                continue firstRun;
+            }
+            if (failure.message.startsWith("[sandbox_preflight_failed]")) {
+                sandboxRecoveryMenu: for (;;) {
+                    const recovery = await selectSandboxPreflightRecovery();
+                    if (recovery === "cancel")
+                        return 1;
+                    if (recovery === "edit") {
+                        const edited = await runSetupRepairWizard({
+                            cwd,
+                            answers,
+                            piAuthPath: resolvedPiAuthPath,
+                            persistedEnv: dotenvSnapshot.env,
+                            moduleSecrets,
+                            providerSetupSecrets,
+                            providerEnvironmentSecrets,
+                            piApiKeyPersistenceByProvider,
+                            credentialStates,
+                            runProviderSetup: pendingProviderSetup,
+                        });
+                        if (edited.status === "cancelled")
+                            continue sandboxRecoveryMenu;
+                        answers = edited.answers;
+                        moduleSecrets = { ...edited.moduleSecrets };
+                        providerSetupSecrets = { ...edited.providerSetupSecrets };
+                        providerEnvironmentSecrets = { ...edited.providerEnvironmentSecrets };
+                        piApiKeyPersistenceByProvider = { ...edited.piApiKeyPersistenceByProvider };
+                        credentialStates = { ...edited.credentialStates };
+                        pendingProviderSetup = edited.runProviderSetup;
+                        if (pendingProviderSetup)
+                            readinessProgress = undefined;
+                    }
+                    break sandboxRecoveryMenu;
+                }
+                continue firstRun;
+            }
+            let recoveryFailure = failure;
+            recoveryMenu: for (;;) {
+                p.log.error(`[${recoveryFailure.kind}] ${recoveryFailure.message}`);
+                const recovery = await selectFirstRunRecovery(recoveryFailure, configurationRecoveryStep, invalidPlanStage);
+                if (recovery === "cancel")
+                    return 1;
+                if (recovery === "save") {
+                    let saved;
+                    try {
+                        saved = await initMonoAgentFolder({
+                            dir: cwd,
+                            answers,
+                            env: effectiveEnv,
+                            secretValues: selectedSecrets,
+                            secureExistingDotenv,
+                            requireConfigCreation: true,
+                        });
+                    }
+                    catch (error) {
+                        const recovery = secretPersistenceRecoveryMessage(error);
+                        process.stderr.write(ui.errorLine(`The incomplete scaffold could not be committed safely; inspect the destination and retry.${recovery}`));
+                        return 1;
+                    }
+                    printInitResult(saved);
+                    let durableSavedEnv = {};
+                    if (saved.secretPersistence.status === "persisted") {
+                        try {
+                            durableSavedEnv = (await readCliDotenvSnapshot(environment.dotenvPath)).env;
+                        }
+                        catch {
+                            durableSavedEnv = {};
+                        }
+                    }
+                    printSecretsChecklist(saved.plan.secrets, configuredSecretNames(saved, durableSavedEnv));
+                    printIncompleteSetup([recoveryFailure.message], saved.configPath);
+                    return 1;
+                }
+                if (recovery === "edit") {
+                    const repaired = await runSetupRepairWizard({
+                        cwd,
+                        answers,
+                        piAuthPath: resolvedPiAuthPath,
+                        persistedEnv: dotenvSnapshot.env,
+                        ...(configurationRecoveryStep === undefined ? {} : { initialStep: configurationRecoveryStep }),
+                        moduleSecrets,
+                        providerSetupSecrets,
+                        providerEnvironmentSecrets,
+                        piApiKeyPersistenceByProvider,
+                        credentialStates,
+                        runProviderSetup: pendingProviderSetup,
+                    });
+                    if (repaired.status === "cancelled")
+                        continue recoveryMenu;
+                    answers = repaired.answers;
+                    moduleSecrets = { ...repaired.moduleSecrets };
+                    providerSetupSecrets = { ...repaired.providerSetupSecrets };
+                    providerEnvironmentSecrets = { ...repaired.providerEnvironmentSecrets };
+                    piApiKeyPersistenceByProvider = { ...repaired.piApiKeyPersistenceByProvider };
+                    credentialStates = { ...repaired.credentialStates };
+                    pendingProviderSetup = repaired.runProviderSetup;
+                    if (pendingProviderSetup)
+                        readinessProgress = undefined;
+                    continue firstRun;
+                }
+                if (recovery === "model") {
+                    const repaired = await runSetupRepairWizard({
+                        cwd,
+                        answers,
+                        piAuthPath: resolvedPiAuthPath,
+                        persistedEnv: dotenvSnapshot.env,
+                        initialStep: 1,
+                        moduleSecrets,
+                        providerSetupSecrets,
+                        providerEnvironmentSecrets,
+                        piApiKeyPersistenceByProvider,
+                        credentialStates,
+                        runProviderSetup: pendingProviderSetup,
+                    });
+                    if (repaired.status === "cancelled")
+                        continue recoveryMenu;
+                    answers = repaired.answers;
+                    moduleSecrets = { ...repaired.moduleSecrets };
+                    providerSetupSecrets = { ...repaired.providerSetupSecrets };
+                    providerEnvironmentSecrets = { ...repaired.providerEnvironmentSecrets };
+                    piApiKeyPersistenceByProvider = { ...repaired.piApiKeyPersistenceByProvider };
+                    credentialStates = { ...repaired.credentialStates };
+                    pendingProviderSetup = repaired.runProviderSetup;
+                    if (pendingProviderSetup)
+                        readinessProgress = undefined;
+                    continue firstRun;
+                }
+                if (recovery === "auth") {
+                    // Authentication can replace credential bytes without changing the
+                    // route/config fingerprint. Every route must be proven again.
+                    readinessProgress = undefined;
+                    if (referencedSetupModelRefs(plan).some((ref) => ref.startsWith("codex:"))) {
+                        const selected = await selectCodexAuthMode(selectedCodexAuthMode);
+                        if (selected === undefined)
+                            return 1;
+                        selectedCodexAuthMode = selected;
+                    }
+                    const setupPlan = planProviderSetup({
+                        modelRefs: referencedSetupModelRefs(plan),
+                        cwd,
+                        piAuthPath: resolvedPiAuthPath,
+                        codexAuthMode: selectedCodexAuthMode,
+                        forceAuthentication: true,
+                    });
+                    const prompted = await promptProviderSetupSecrets(setupPlan, providerSetupSecrets, piApiKeyPersistenceByProvider, providerEnvironmentSecrets);
+                    if (prompted === undefined)
+                        return 1;
+                    providerSetupSecrets = prompted.apiKeys;
+                    piApiKeyPersistenceByProvider = prompted.persistenceByProvider;
+                    providerEnvironmentSecrets = prompted.environmentSecrets;
+                    readinessProgress = undefined;
+                    const selectedSetupPlan = planProviderSetup({
+                        modelRefs: referencedSetupModelRefs(plan),
+                        cwd,
+                        piAuthPath: resolvedPiAuthPath,
+                        codexAuthMode: selectedCodexAuthMode,
+                        forceAuthentication: true,
+                        piApiKeyPersistenceByProvider,
+                    });
+                    const environmentApiKeys = environmentProviderApiKeys(selectedSetupPlan, { ...effectiveEnv, ...providerEnvironmentSecrets });
+                    const missingEnvironmentKeys = selectedSetupPlan.actions
+                        .filter(isProviderSetupPiApiKeyAction)
+                        .filter((action) => action.persistence === "environment" && environmentApiKeys[action.id] === undefined)
+                        .map((action) => action.envVar);
+                    if (missingEnvironmentKeys.length > 0) {
+                        recoveryFailure = {
+                            ok: false,
+                            kind: "provider_failed",
+                            message: `Add ${missingEnvironmentKeys.join(", ")} to the durable owner-only .env, then retry authentication. No agent files were written.`,
+                        };
+                        continue recoveryMenu;
+                    }
+                    const setup = await withScopedPreflightCancellation((abortSignal) => withExactProcessEnvironment(effectiveEnv, () => runProviderSetupBeforeInit({
+                        modelRefs: referencedSetupModelRefs(plan),
+                        cwd,
+                        auth: true,
+                        dryRun: false,
+                        piAuthPath: resolvedPiAuthPath,
+                        apiKeys: { ...providerSetupSecrets, ...environmentApiKeys },
+                        codexAuthMode: selectedCodexAuthMode,
+                        forceAuthentication: true,
+                        piApiKeyPersistenceByProvider,
+                        abortSignal,
+                    })), { keypress: false });
+                    if (setup === "fatal")
+                        return 130;
+                    if (setup === "interrupted") {
+                        pendingProviderSetup = true;
+                        deferredFailure = {
+                            ok: false,
+                            kind: "cancelled",
+                            message: "Provider setup was interrupted. No agent files were written.",
+                            interrupted: true,
+                        };
+                        continue firstRun;
+                    }
+                    if (setup === "failed") {
+                        pendingProviderSetup = true;
+                        recoveryFailure = {
+                            ok: false,
+                            kind: "provider_failed",
+                            message: "Provider setup still needs attention. No agent files were written.",
+                        };
+                        continue recoveryMenu;
+                    }
+                    pendingProviderSetup = false;
+                }
+                // "retry" deliberately reruns only the live checks. Provider setup is a
+                // separate explicit recovery action and is never repeated automatically.
+                continue firstRun;
             }
         }
-        const result = await initMonoAgentFolder({ dir: process.cwd(), answers: outcome.answers });
-        printInitResult(result);
-        const report = await validateMonoAgentFolder({ env: process.env, cwd: process.cwd(), configPath: result.configPath });
-        process.stdout.write("\n" + ui.heading("Validation"));
-        for (const section of report.sections) {
-            process.stdout.write(formatSection(section));
-        }
-        process.stdout.write(renderPlanCompleteness(result.plan.validateExpectations, "Selected capabilities", report));
-        printSecretsChecklist(result.plan.secrets);
-        printNextSteps(result.configPath);
-        return report.ok ? 0 : 1;
     }
     const presetId = resolveInitPresetId(args);
     if (presetId === "unknown") {
@@ -715,7 +1832,10 @@ async function runInit(args) {
     }
     const answers = answersFromCli({
         ...(args.model === undefined ? {} : { model: args.model }),
+        ...(args.name === undefined ? {} : { name: args.name }),
         ...(args.fallbackModels === undefined ? {} : { fallbackModels: args.fallbackModels }),
+        ...(args.fallbacks === undefined ? {} : { fallbacks: args.fallbacks }),
+        ...(args.routeSafety === undefined ? {} : { routeSafety: args.routeSafety }),
         ...(args.effort === undefined ? {} : { effort: args.effort }),
         ...(args.memory === undefined ? {} : { memory: args.memory }),
         ...(withChannels === undefined ? {} : { withChannels }),
@@ -725,24 +1845,750 @@ async function runInit(args) {
         dirBasename: basename(process.cwd()),
         skillsRootExists: await pathExists(resolve(process.cwd(), "skills")),
     });
-    const setup = await runProviderSetupBeforeInit({
-        modelRefs: [answers.model, ...answers.fallbackModels],
-        cwd: process.cwd(),
+    const nonInteractivePiAuthPath = resolveEffectivePiAuthPath({
+        cwd,
+        ...(nonEmptyEnv(environment.shellEnv.MONO_AGENT_PI_AUTH_PATH)
+            ? { envPath: environment.shellEnv.MONO_AGENT_PI_AUTH_PATH }
+            : nonEmptyEnv(environment.dotenvEnv.MONO_AGENT_PI_AUTH_PATH)
+                ? { envPath: environment.dotenvEnv.MONO_AGENT_PI_AUTH_PATH }
+                : {}),
+        ...(nonEmptyEnv(previewPlan.configJson.providers?.piAuthPath)
+            ? { configPath: previewPlan.configJson.providers.piAuthPath }
+            : {}),
+    });
+    const nonInteractiveEnvironment = effectiveFirstRunEnvironment({
+        shellEnv: environment.shellEnv,
+        dotenvEnv: environment.dotenvEnv,
+        resolvedPiAuthPath: nonInteractivePiAuthPath,
+    });
+    const setup = await withScopedPreflightCancellation((abortSignal) => withExactProcessEnvironment(nonInteractiveEnvironment, () => runProviderSetupBeforeInit({
+        modelRefs: referencedSetupModelRefs(previewPlan),
+        cwd,
         auth: args.auth === true,
         dryRun: args.dryRun,
-        ...(typeof previewPlan.configJson.providers?.piAuthPath === "string" ? { piAuthPath: previewPlan.configJson.providers.piAuthPath } : {}),
-    });
+        persistedEnv: environment.dotenvEnv,
+        piAuthPath: nonInteractivePiAuthPath,
+        ...(args.codexAuthMode === undefined ? {} : { codexAuthMode: args.codexAuthMode }),
+        abortSignal,
+    })), { keypress: false });
+    if (setup === "interrupted" || setup === "fatal") {
+        return 130;
+    }
     if (setup === "failed") {
         return 1;
     }
-    const result = await initMonoAgentFolder({ dir: process.cwd(), answers, dryRun: args.dryRun });
+    const result = await initMonoAgentFolder({
+        dir: cwd,
+        answers,
+        dryRun: args.dryRun,
+        // Scaffold-only init has no immediate launchd-minimal worker proof. Reject
+        // both shell and persisted memory-identity overrides instead of creating a
+        // generation at a different path/tier than a follow-up validate would use.
+        env: { ...environment.shellEnv, ...environment.dotenvEnv },
+    });
     printInitResult(result);
-    printSecretsChecklist(result.plan.secrets);
+    printSecretsChecklist(result.plan.secrets, new Set());
     printNextSteps(result.configPath);
     return 0;
 }
+const FIRST_RUN_STAGING_FAILURE_MAX_LENGTH = 500;
+const FIRST_RUN_SENSITIVE_ENV_NAME = /(api.?key|credential|password|secret|token)/iu;
+function throwIfFirstRunPreflightAborted(signal) {
+    if (signal?.aborted !== true)
+        return;
+    const error = new Error("Preflight was interrupted.");
+    error.name = "AbortError";
+    throw error;
+}
+function firstRunStagingFailureDetail(error, sensitiveValues = []) {
+    let message = reasonOf(error);
+    for (const value of [...new Set(sensitiveValues)].filter((candidate) => candidate.length >= 4).sort((left, right) => right.length - left.length)) {
+        message = message.replaceAll(value, "[secret-redacted]");
+    }
+    const normalized = message
+        .replace(/\bBearer\s+[^\s,;]+/giu, "Bearer [secret-redacted]")
+        .replace(/\b(api[ _-]?key|access[ _-]?token|auth[ _-]?token|password|secret)(\s*[=:]\s*)([^\s,;]+)/giu, (_match, label, separator) => `${label}${separator}[secret-redacted]`)
+        .replace(/\s+/gu, " ")
+        .trim();
+    if (normalized.length === 0)
+        return "Unknown staging failure.";
+    return normalized.length <= FIRST_RUN_STAGING_FAILURE_MAX_LENGTH
+        ? normalized
+        : `${normalized.slice(0, FIRST_RUN_STAGING_FAILURE_MAX_LENGTH - 1).trimEnd()}…`;
+}
+function firstRunStagingSensitiveValues(env, explicit) {
+    return [
+        ...Object.entries(env)
+            .filter((entry) => FIRST_RUN_SENSITIVE_ENV_NAME.test(entry[0])
+            && typeof entry[1] === "string"
+            && entry[1].length > 0)
+            .map(([, value]) => value),
+        ...Object.values(explicit),
+    ];
+}
+async function runConfigurationPreflightWithSpinner(options) {
+    process.stdout.write("\n" + ui.heading("Configuration preflight"));
+    const spinner = p.spinner();
+    try {
+        return await withScopedPreflightCancellation(async (abortSignal) => {
+            spinner.start("Validating generated files and selected capabilities before runtime calls");
+            const gate = await assessPrewriteFirstRunConfigurationReadiness({ ...options, abortSignal });
+            if (abortSignal.aborted || spinner.isCancelled) {
+                spinner.cancel("Configuration preflight interrupted");
+                return interruptedConfigurationAssessment();
+            }
+            if (gate.ready) {
+                spinner.stop("Selected capabilities are ready for runtime checks");
+            }
+            else {
+                spinner.error("Configuration preflight needs attention");
+            }
+            return gate;
+        });
+    }
+    catch (error) {
+        if (!isAbortLike(error))
+            throw error;
+        spinner.cancel("Configuration preflight interrupted");
+        return interruptedConfigurationAssessment();
+    }
+}
+function interruptedConfigurationAssessment() {
+    return {
+        ready: false,
+        reasons: ["Configuration preflight was interrupted."],
+        failedSectionIds: [],
+        interrupted: true,
+    };
+}
+async function runFinalReadinessValidationWithSpinner(options) {
+    process.stdout.write("\n" + ui.heading("Final readiness validation"));
+    const spinner = p.spinner();
+    try {
+        return await withScopedPreflightCancellation(async (abortSignal) => {
+            spinner.start("Revalidating the effective files after runtime route checks");
+            const gate = await assessPrewriteFirstRunReadiness({ ...options, abortSignal });
+            if (abortSignal.aborted || spinner.isCancelled) {
+                spinner.cancel("Final readiness validation interrupted");
+                return interruptedFinalReadinessAssessment();
+            }
+            if (gate.ready)
+                spinner.stop("Effective files and runtime routes are ready");
+            else
+                spinner.error("Final readiness validation needs attention");
+            return gate;
+        });
+    }
+    catch (error) {
+        if (!isAbortLike(error))
+            throw error;
+        spinner.cancel("Final readiness validation interrupted");
+        return interruptedFinalReadinessAssessment();
+    }
+}
+function interruptedFinalReadinessAssessment() {
+    return {
+        ready: false,
+        reasons: ["Final readiness validation was interrupted."],
+        failedSectionIds: [],
+        interrupted: true,
+    };
+}
+async function assessPrewriteFirstRunConfigurationReadiness(options) {
+    try {
+        throwIfFirstRunPreflightAborted(options.abortSignal);
+        const preview = await initMonoAgentFolder({
+            dir: options.cwd,
+            answers: options.answers,
+            env: options.env,
+            secretValues: options.secretValues,
+            secureExistingDotenv: options.secureExistingDotenv,
+            dryRun: true,
+        });
+        throwIfFirstRunPreflightAborted(options.abortSignal);
+        const report = await validateWizardPlanInStaging({
+            plan: options.plan,
+            sourceCwd: options.cwd,
+            env: options.env,
+            verifiedCredentialModelRefs: [],
+            ...(options.abortSignal === undefined ? {} : { abortSignal: options.abortSignal }),
+        });
+        const gate = evaluateFirstRunConfigurationReadiness({
+            plan: options.plan,
+            report,
+            secretPersistence: preview.secretPersistence,
+        });
+        return {
+            ...gate,
+            failedSectionIds: configurationFailureSectionIds(options.plan, report, true),
+        };
+    }
+    catch (error) {
+        throwIfFirstRunPreflightAborted(options.abortSignal);
+        if (error instanceof Error && error.name === "AbortError")
+            throw error;
+        return {
+            ready: false,
+            reasons: [
+                `The complete generated configuration could not be validated safely in staging: ${firstRunStagingFailureDetail(error, firstRunStagingSensitiveValues(options.env, options.secretValues))}`,
+            ],
+            failedSectionIds: [],
+        };
+    }
+}
+async function assessPrewriteFirstRunReadiness(options) {
+    try {
+        throwIfFirstRunPreflightAborted(options.abortSignal);
+        const preview = await initMonoAgentFolder({
+            dir: options.cwd,
+            answers: options.answers,
+            env: options.env,
+            secretValues: options.secretValues,
+            secureExistingDotenv: options.secureExistingDotenv,
+            dryRun: true,
+        });
+        throwIfFirstRunPreflightAborted(options.abortSignal);
+        const report = await validateWizardPlanInStaging({
+            plan: options.plan,
+            sourceCwd: options.cwd,
+            env: options.env,
+            verifiedCredentialModelRefs: options.verifiedCredentialModelRefs,
+            ...(options.abortSignal === undefined ? {} : { abortSignal: options.abortSignal }),
+        });
+        const gate = evaluateFirstRunReadiness({
+            plan: options.plan,
+            report,
+            secretPersistence: preview.secretPersistence,
+            verifiedCredentialModelRefs: options.verifiedCredentialModelRefs,
+        });
+        return {
+            ...gate,
+            failedSectionIds: configurationFailureSectionIds(options.plan, report, false),
+        };
+    }
+    catch (error) {
+        throwIfFirstRunPreflightAborted(options.abortSignal);
+        if (error instanceof Error && error.name === "AbortError")
+            throw error;
+        return {
+            ready: false,
+            reasons: [
+                `The complete generated plan could not be validated safely in staging: ${firstRunStagingFailureDetail(error, firstRunStagingSensitiveValues(options.env, options.secretValues))}`,
+            ],
+            failedSectionIds: [],
+        };
+    }
+}
+function configurationFailureSectionIds(plan, report, deferWaitingCredentials) {
+    const byId = new Map(report.sections.map((section) => [section.id, section]));
+    const ids = new Set();
+    for (const expectation of plan.validateExpectations) {
+        const actual = byId.get(expectation.sectionId)?.status;
+        if (actual === expectation.mustBe
+            || (deferWaitingCredentials && expectation.sectionId === "credentials" && actual === "waiting"))
+            continue;
+        ids.add(expectation.sectionId);
+    }
+    if (!report.ok) {
+        for (const section of report.sections) {
+            if (section.status === "error")
+                ids.add(section.id);
+        }
+    }
+    return [...ids];
+}
+function nonEmptyEnv(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function sameConcreteEnvironment(left, right) {
+    const concreteEntries = (env) => Object.entries(env)
+        .filter((entry) => typeof entry[1] === "string")
+        .sort(([leftName], [rightName]) => leftName.localeCompare(rightName));
+    const leftEntries = concreteEntries(left);
+    const rightEntries = concreteEntries(right);
+    return leftEntries.length === rightEntries.length && leftEntries.every(([name, value], index) => rightEntries[index]?.[0] === name && rightEntries[index]?.[1] === value);
+}
+function dotenvReadinessFailure(message) {
+    return { ok: false, kind: "invalid_plan", message };
+}
+async function firstRunDotenvDrift(path, expected) {
+    let current;
+    try {
+        current = await readCliDotenvSnapshot(path);
+    }
+    catch {
+        return dotenvReadinessFailure("The persisted .env became unreadable during setup. Readiness cannot be claimed.");
+    }
+    if (current.fingerprint === expected.fingerprint)
+        return undefined;
+    return dotenvReadinessFailure("The persisted .env changed while setup was validating the agent. Review the change, then retry so the exact durable values can be checked.");
+}
+async function firstRunConfigDrift(path, expected) {
+    let current;
+    try {
+        current = await readCliConfigSnapshot(path);
+    }
+    catch {
+        return dotenvReadinessFailure("The committed config became unreadable or unsafe during setup. Readiness cannot be claimed.");
+    }
+    if (current.fingerprint === expected.fingerprint)
+        return undefined;
+    return dotenvReadinessFailure("The committed config changed while setup was validating the agent. Review the change, then retry so the exact plan can be checked.");
+}
+async function firstRunSecretEnvGuardFailure(path, required) {
+    if (!required)
+        return undefined;
+    try {
+        if (await verifySecretEnvPersistenceGuard(path))
+            return undefined;
+    }
+    catch {
+        // Fall through to one stable, non-secret-bearing operator message.
+    }
+    return dotenvReadinessFailure("The committed .env is no longer owner-only, safely ignored, and untracked. Readiness cannot be claimed.");
+}
+function secretPersistenceRecoveryMessage(error) {
+    if (!(error instanceof SecretEnvConcurrentModificationError)) {
+        return "";
+    }
+    return ` ${error.message}`;
+}
+function readinessPlanIdentity(plan) {
+    const displayed = readinessRoutesForDisplay(plan);
+    const immutable = displayed.map((route, index) => ({
+        index,
+        model: route.model,
+        effort: route.effort ?? null,
+    }));
+    return {
+        fingerprint: createHash("sha256")
+            .update(JSON.stringify({ version: 1, routes: immutable }))
+            .digest("hex"),
+        routes: displayed.map((route, index) => ({
+            index,
+            ...route,
+            key: createHash("sha256")
+                .update(JSON.stringify({ version: 1, index, model: route.model, effort: route.effort ?? null }))
+                .digest("hex"),
+        })),
+    };
+}
+function mergeReadinessProgress(previous, result, plan) {
+    const identity = readinessPlanIdentity(plan);
+    const fingerprint = result.planFingerprint ?? identity.fingerprint;
+    const successfulKeys = new Set(previous?.planFingerprint === fingerprint ? previous.successfulRouteKeys : []);
+    const verifiedRefs = new Set(previous?.planFingerprint === fingerprint ? previous.verifiedModelRefs : []);
+    const reported = result.routes ?? (result.ok
+        ? identity.routes.map((route) => ({ ...route, status: "verified" }))
+        : []);
+    for (const route of reported) {
+        if (route.status === "verified" || route.status === "skipped_verified") {
+            successfulKeys.add(route.key);
+            verifiedRefs.add(route.model);
+        }
+    }
+    const currentRefs = new Set(identity.routes.map((route) => route.model));
+    return {
+        planFingerprint: fingerprint,
+        successfulRouteKeys: [...successfulKeys],
+        verifiedModelRefs: [...verifiedRefs].filter((ref) => currentRefs.has(ref)),
+    };
+}
+async function runGuidedSandboxPreflight(installedEarlier) {
+    process.stdout.write("\n" + ui.heading("Sandbox preflight"));
+    return await withScopedPreflightCancellation(async (signal) => {
+        try {
+            process.stdout.write(ui.style.dim(installedEarlier
+                ? "Rechecking the pinned managed SRT copy and its functional enforcement postcondition.\n"
+                : "Installing the pinned managed SRT copy in the private user cache, then running the functional enforcement check.\n"));
+            const setup = await setupManagedSrt({ signal, verify: true });
+            if (setup.status.source !== "managed" || setup.status.state !== "ready" || setup.check === undefined) {
+                throw new Error("Managed SRT setup did not return a ready managed functional-check result.");
+            }
+            process.stdout.write(`${ui.badge("ok")}Managed SRT ${setup.repaired ? "repaired" : setup.installed ? "installed" : "verified"}; functional postcondition passed.\n`);
+            return { ok: true };
+        }
+        catch (error) {
+            if (signal.aborted || isAbortLike(error)) {
+                process.stderr.write(ui.errorLine("Preflight was interrupted."));
+                return {
+                    ok: false,
+                    kind: "cancelled",
+                    message: "Sandbox preflight was interrupted. No agent files were written.",
+                    interrupted: true,
+                };
+            }
+            return {
+                ok: false,
+                kind: "provider_failed",
+                message: `[sandbox_preflight_failed] ${reasonOf(error)} No agent files were written; retry setup or edit the sandbox choice.`,
+            };
+        }
+    });
+}
+async function runReadinessProbeWithSpinner(options) {
+    const routes = readinessRoutesForDisplay(options.plan);
+    process.stdout.write("\n" + ui.heading("Runtime readiness"));
+    routes.forEach((route, index) => {
+        const timeoutMs = readinessProbeTimeoutMs(parseMonoRuntimeModelReference(route.model));
+        process.stdout.write(`  Route ${index + 1}/${routes.length}: ${route.model} ` +
+            ui.style.dim(`(effort: ${route.effort ?? "provider-default"}; up to ${Math.ceil(timeoutMs / 1_000)}s)`) +
+            "\n");
+    });
+    process.stdout.write(ui.style.dim("Running real no-tool checks sequentially. Press Esc or Ctrl-C once to interrupt safely.\n"));
+    return await withScopedPreflightCancellation(async (signal) => {
+        try {
+            const result = await runAllRouteReadinessProbe({
+                plan: options.plan,
+                hostEnv: options.effectiveEnv,
+                secretValues: selectedSecretValues(options.plan, options.effectiveEnv),
+                resolvedPiAuthPath: options.resolvedPiAuthPath,
+                abortSignal: signal,
+                ...(options.resume === undefined ? {} : { resume: options.resume }),
+                onRouteStart: (route) => {
+                    process.stdout.write(`  Checking route ${route.index + 1}/${route.total}: ${route.model} ` +
+                        ui.style.dim(`(effort: ${route.effort ?? "provider-default"})`) +
+                        "\n");
+                },
+                onRouteComplete: (route) => {
+                    const ok = route.status === "verified" || route.status === "skipped_verified";
+                    process.stdout.write(`${ok ? ui.badge("ok") : route.status === "interrupted" ? ui.badge("waiting") : ui.badge("error")}` +
+                        `Route ${route.index + 1}/${routes.length} ${route.status.replaceAll("_", " ")}\n`);
+                },
+            });
+            process.stdout.write(ui.heading("Readiness summary"));
+            printReadinessRouteSummary(result, routes);
+            return result;
+        }
+        catch (error) {
+            if (signal.aborted || isAbortLike(error)) {
+                process.stderr.write(ui.errorLine("Preflight was interrupted."));
+                return {
+                    ok: false,
+                    kind: "cancelled",
+                    message: "Preflight was interrupted before the current route completed.",
+                    interrupted: true,
+                };
+            }
+            process.stderr.write(ui.errorLine("[readiness_probe_failed] Runtime readiness could not run."));
+            return {
+                ok: false,
+                kind: "probe_failed",
+                message: "Runtime readiness could not run. Review provider authentication and retry.",
+            };
+        }
+    });
+}
+function readinessRoutesForDisplay(plan) {
+    const runtime = (plan.configJson.runtime ?? {});
+    const primaryEffort = typeof runtime.effort === "string" ? runtime.effort : undefined;
+    const routes = [];
+    if (typeof runtime.model === "string") {
+        routes.push({ model: runtime.model, ...(primaryEffort === undefined ? {} : { effort: primaryEffort }) });
+    }
+    if (Array.isArray(runtime.fallbacks) && runtime.fallbacks.length > 0) {
+        for (const raw of runtime.fallbacks) {
+            if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+                continue;
+            const entry = raw;
+            if (typeof entry.model !== "string")
+                continue;
+            routes.push({
+                model: entry.model,
+                ...(typeof entry.effort === "string" ? { effort: entry.effort } : {}),
+            });
+        }
+    }
+    else if (Array.isArray(runtime.fallbackModels)) {
+        for (const model of runtime.fallbackModels) {
+            if (typeof model === "string") {
+                routes.push({ model, ...(primaryEffort === undefined ? {} : { effort: primaryEffort }) });
+            }
+        }
+    }
+    return routes;
+}
+function printReadinessRouteSummary(result, planned) {
+    const reported = result.routes ?? planned.map((route, index) => ({
+        key: `${index}:${route.model}`,
+        index,
+        ...route,
+        status: result.ok ? "verified" : result.kind === "cancelled" ? "interrupted" : "failed",
+        ...(!result.ok ? { kind: result.kind, message: result.message } : {}),
+    }));
+    for (const route of reported) {
+        const badge = route.status === "verified" || route.status === "skipped_verified"
+            ? ui.badge("ok")
+            : route.status === "interrupted"
+                ? ui.badge("waiting")
+                : ui.badge("error");
+        const state = route.status === "skipped_verified" ? "verified earlier" : route.status.replaceAll("_", " ");
+        process.stdout.write(`${badge}Route ${route.index + 1}/${planned.length}: ${route.model} ` +
+            ui.style.dim(`(effort: ${route.effort ?? "provider-default"})`) +
+            ` — ${state}${route.message === undefined ? "" : `: ${route.message}`}\n`);
+    }
+    if (!result.ok && result.interrupted === true) {
+        process.stderr.write(ui.errorLine("Preflight was interrupted."));
+    }
+}
+async function withScopedPreflightCancellation(task, options = {}) {
+    const controller = new AbortController();
+    let interruptCount = 0;
+    const interrupt = () => {
+        interruptCount += 1;
+        controller.abort();
+        if (interruptCount > 1)
+            process.exitCode = 130;
+    };
+    const onKeypress = (_value, key) => {
+        if (key?.name === "escape" || (key?.ctrl === true && key.name === "c"))
+            interrupt();
+    };
+    process.on("SIGINT", interrupt);
+    const restoreKeypress = options.keypress === false
+        ? () => undefined
+        : attachScopedKeypress(onKeypress);
+    try {
+        return await task(controller.signal);
+    }
+    finally {
+        process.off("SIGINT", interrupt);
+        restoreKeypress();
+    }
+}
+function focusedConfigurationRepairStep(sectionIds) {
+    const mapped = new Set();
+    for (const id of sectionIds) {
+        if (id === "agent")
+            mapped.add(0);
+        else if (id === "runtime" || id === "credentials")
+            mapped.add(1);
+        else if (id === "memory" || id.startsWith("memory:"))
+            mapped.add(3);
+        else if (id === "context" || id.startsWith("channel:"))
+            mapped.add(4);
+        else if (id === "tools")
+            mapped.add(5);
+        else if (id === "sandbox")
+            mapped.add(6);
+        else if (id === "observability")
+            mapped.add(7);
+    }
+    return mapped.size === 1 ? [...mapped][0] : undefined;
+}
+function configurationRecoveryEditLabel(step) {
+    switch (step) {
+        case 0: return "Edit agent name";
+        case 1: return "Edit model routes";
+        case 3: return "Edit memory";
+        case 4: return "Edit capability details";
+        case 5: return "Edit tools";
+        case 6: return "Edit route safety and sandbox";
+        case 7: return "Edit observability";
+        default: return "Edit setup choices";
+    }
+}
+async function selectSandboxPreflightRecovery() {
+    const recovery = await p.select({
+        message: "Sandbox preflight did not pass. How would you like to recover?",
+        initialValue: "retry",
+        options: [
+            { value: "retry", label: "Retry sandbox setup and check" },
+            { value: "edit", label: "Change safety or other choices" },
+            { value: "cancel", label: "Cancel without writing" },
+        ],
+    });
+    return p.isCancel(recovery) ? "cancel" : recovery;
+}
+async function selectInterruptedFirstRunRecovery() {
+    const recovery = await p.select({
+        message: "Preflight was interrupted. What would you like to do?",
+        initialValue: "resume",
+        options: [
+            { value: "resume", label: "Resume preflight", hint: "keeps successful auth, SRT setup, and route checks" },
+            { value: "restart", label: "Restart all checks", hint: "keeps successful auth and SRT installation" },
+            { value: "edit", label: "Edit setup choices" },
+            { value: "cancel", label: "Cancel without writing" },
+        ],
+    });
+    return p.isCancel(recovery) ? "cancel" : recovery;
+}
+async function selectFirstRunRecovery(failure, configurationRepairStep, invalidPlanStage) {
+    const sharedTail = [
+        { value: "save", label: "Save incomplete", hint: "does not call the agent ready or start it" },
+        { value: "cancel", label: "Cancel without writing" },
+    ];
+    const providerSetupFailed = failure.kind === "provider_failed"
+        && /^Provider setup (?:did not complete|still needs attention)\./u.test(failure.message);
+    const message = failure.kind === "invalid_plan"
+        ? invalidPlanStage === "final_readiness"
+            ? "Final readiness validation did not pass. What would you like to do?"
+            : "Configuration preflight did not pass. What would you like to do?"
+        : providerSetupFailed
+            ? "Provider setup did not pass. What would you like to do?"
+            : "Runtime readiness did not pass. What would you like to do?";
+    const options = failure.kind === "invalid_plan"
+        ? [
+            { value: "edit", label: configurationRecoveryEditLabel(configurationRepairStep) },
+            {
+                value: "retry",
+                label: invalidPlanStage === "final_readiness"
+                    ? "Retry final readiness validation"
+                    : "Retry configuration preflight",
+            },
+            ...sharedTail,
+        ]
+        : providerSetupFailed
+            ? [
+                { value: "auth", label: "Repair authentication" },
+                { value: "retry", label: "Retry provider setup" },
+                { value: "model", label: "Edit model routes" },
+                ...sharedTail,
+            ]
+            : failure.kind === "provider_failed"
+                ? [
+                    { value: "retry", label: "Retry failed route" },
+                    { value: "auth", label: "Repair authentication" },
+                    { value: "model", label: "Edit model routes" },
+                    ...sharedTail,
+                ]
+                : failure.kind === "unsupported_guided_probe"
+                    ? [
+                        { value: "model", label: "Edit model routes" },
+                        ...sharedTail,
+                    ]
+                    : [
+                        { value: "retry", label: "Retry runtime checks" },
+                        { value: "model", label: "Edit model routes" },
+                        ...sharedTail,
+                    ];
+    const recovery = await p.select({
+        message,
+        initialValue: options[0]?.value ?? "cancel",
+        options: [...options],
+    });
+    return p.isCancel(recovery) ? "cancel" : recovery;
+}
+async function promptProviderSetupSecrets(plan, existing, existingPersistence = {}, existingEnvironmentSecrets = {}) {
+    const values = { ...existing };
+    const persistenceByProvider = { ...existingPersistence };
+    const environmentSecrets = { ...existingEnvironmentSecrets };
+    for (const action of plan.actions) {
+        if (!isProviderSetupPiApiKeyAction(action))
+            continue;
+        const reviewedPersistence = existingPersistence[action.provider];
+        const persistence = reviewedPersistence ?? await p.select({
+            message: `How should ${action.label} receive ${action.envVar}?`,
+            initialValue: "secure-store",
+            options: [
+                { value: "secure-store", label: "Store securely in Pi auth.json", hint: "owner-only credential store" },
+                { value: "environment", label: `Use environment variable ${action.envVar}`, hint: "save it to the agent's owner-only .env" },
+            ],
+        });
+        if (p.isCancel(persistence))
+            return undefined;
+        if (persistence === "environment") {
+            delete values[action.id];
+            persistenceByProvider[action.provider] = "environment";
+            const answer = await p.password({
+                message: `Enter ${action.envVar} for the agent's owner-only .env`,
+                validate: (value) => (value ?? "").trim().length === 0 ? "API key is required." : undefined,
+                clearOnError: true,
+            });
+            if (p.isCancel(answer))
+                return undefined;
+            environmentSecrets[action.envVar] = answer;
+            continue;
+        }
+        persistenceByProvider[action.provider] = "secure-store";
+        delete environmentSecrets[action.envVar];
+        const answer = await p.password({
+            message: `Enter ${action.label} (${action.envVar})`,
+            validate: (value) => (value ?? "").trim().length === 0 ? "API key is required." : undefined,
+            clearOnError: true,
+        });
+        if (p.isCancel(answer))
+            return undefined;
+        values[action.id] = answer;
+    }
+    return { apiKeys: values, persistenceByProvider, environmentSecrets };
+}
+function environmentProviderApiKeys(plan, env) {
+    const values = {};
+    for (const action of plan.actions) {
+        if (!isProviderSetupPiApiKeyAction(action) || action.persistence !== "environment")
+            continue;
+        const value = env[action.envVar];
+        if (nonEmptyEnv(value))
+            values[action.id] = value;
+    }
+    return values;
+}
+async function selectCodexAuthMode(initialValue) {
+    const selected = await p.select({
+        message: "How should Codex authenticate on this machine?",
+        initialValue,
+        options: [
+            { value: "browser", label: "Browser login", hint: "opens a localhost callback server" },
+            { value: "device", label: "Device-code login", hint: "recommended for remote or headless machines" },
+        ],
+    });
+    return p.isCancel(selected) ? undefined : selected;
+}
+function configuredSecretNames(result, effectiveEnv) {
+    const names = new Set();
+    for (const secret of result.plan.secrets) {
+        if (nonEmptyEnv(effectiveEnv[secret.envVar]))
+            names.add(secret.envVar);
+    }
+    return names;
+}
+function printIncompleteSetup(reasons, configPath) {
+    process.stderr.write(ui.hint("INCOMPLETE SETUP: no readiness claim was made and the agent was not started.\n"));
+    for (const reason of reasons)
+        process.stderr.write(ui.style.yellow(`  - ${reason}\n`));
+    process.stderr.write(ui.hint(`Review ${configPath}, run \`mono-agent validate\`, then retry the first turn.\n`));
+}
+export function shouldRunInitWizard(args, stdinIsTty, stdoutIsTty) {
+    if (!stdinIsTty || !stdoutIsTty || args.command !== "init" || args.positionals.length > 0) {
+        return false;
+    }
+    if (args.force || args.foreground || args.follow || args.all || args.dryRun || args.includeMemory) {
+        return false;
+    }
+    // A bare parsed init has only these required/default keys. Treat every
+    // optional key—current or future—as an overriding flag so the documented
+    // "any flag is scaffold-only" contract cannot silently drift again.
+    const bareKeys = new Set([
+        "command",
+        "positionals",
+        "force",
+        "foreground",
+        "follow",
+        "all",
+        "dryRun",
+        "includeMemory",
+    ]);
+    return Object.keys(args).every((key) => bareKeys.has(key));
+}
 export async function runProviderSetupBeforeInit(options) {
-    const plan = planProviderSetup(options);
+    const credentialStates = options.credentialStates !== undefined
+        ? options.credentialStates
+        : options.forceAuthentication === true || !options.auth || options.dryRun
+            ? undefined
+            : await detectProviderCredentialStates({
+                modelRefs: options.modelRefs,
+                cwd: options.cwd,
+                ...(options.piAuthPath === undefined ? {} : { piAuthPath: options.piAuthPath }),
+                ...(options.persistedEnv === undefined ? {} : { persistedEnv: options.persistedEnv }),
+                ...(options.abortSignal === undefined ? {} : { abortSignal: options.abortSignal }),
+            });
+    const plan = planProviderSetup({
+        ...options,
+        ...(credentialStates === undefined ? {} : { credentialStates }),
+        ...(options.codexAuthMode === undefined ? {} : { codexAuthMode: options.codexAuthMode }),
+        ...(options.forceAuthentication === undefined ? {} : { forceAuthentication: options.forceAuthentication }),
+    });
     if (plan.actions.length === 0) {
         return "skipped";
     }
@@ -757,23 +2603,191 @@ export async function runProviderSetupBeforeInit(options) {
     }
     process.stdout.write("\n" + ui.heading("Provider setup"));
     printProviderSetupPlan(plan);
+    if (options.abortSignal !== undefined) {
+        process.stdout.write(ui.style.dim("Press Ctrl-C once to interrupt authentication safely.\n"));
+    }
     const results = await (options.execute ?? ((setupPlan) => executeProviderSetupPlan(setupPlan, {
         ...(options.apiKeys === undefined ? {} : { apiKeys: options.apiKeys }),
+        ...(options.abortSignal === undefined ? {} : { abortSignal: options.abortSignal }),
     })))(plan);
+    const interrupted = options.abortSignal?.aborted === true;
     for (const result of results) {
-        const badge = result.status === "ok"
-            ? ui.badge("ok")
-            : result.status === "skipped"
-                ? ui.style.dim("- ")
-                : ui.badge("error");
+        const badge = interrupted && result.status === "failed"
+            ? ui.badge("waiting")
+            : result.status === "ok"
+                ? ui.badge("ok")
+                : result.status === "skipped"
+                    ? ui.style.dim("- ")
+                    : ui.badge("error");
         process.stdout.write(`${badge}${result.action.label}: ${result.detail}\n`);
     }
+    if (results.some((result) => result.failureKind !== undefined)) {
+        process.stderr.write(ui.errorLine("Provider setup ended in an unconfirmed process or credential-cleanup state. Follow the reported manual cleanup guidance before retrying; automatic recovery is disabled."));
+        return "fatal";
+    }
+    if (interrupted) {
+        process.stderr.write(ui.errorLine("Provider setup was interrupted."));
+        return "interrupted";
+    }
     if (results.some((result) => result.status === "failed")) {
         process.stderr.write(ui.errorLine("Provider setup failed; init stopped before writing files."));
         return "failed";
     }
     return "ok";
 }
+async function runAuth(args) {
+    const [subcommand, provider, ...extra] = args.positionals;
+    if (subcommand !== "login" || provider === undefined || extra.length > 0) {
+        process.stderr.write(ui.errorLine("Usage: mono-agent auth login <provider|codex> [--pi-auth-path <path>] [--api-key-stdin] [--codex-auth browser|device] [--config <path>]."));
+        return 2;
+    }
+    const cwd = process.cwd();
+    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."));
+        return 2;
+    }
+    let configuredPiAuthPath;
+    try {
+        configuredPiAuthPath = directCodex ? resolve(cwd, ".pi", "auth.json") : await resolvePiAuthPathForLogin({
+            configPath,
+            cwd,
+            ...(process.env.MONO_AGENT_PI_AUTH_PATH === undefined
+                ? {}
+                : { envPath: process.env.MONO_AGENT_PI_AUTH_PATH }),
+            ...(args.piAuthPath === undefined ? {} : { piAuthPath: args.piAuthPath }),
+        });
+    }
+    catch (error) {
+        process.stderr.write(ui.errorLine(`Cannot resolve the Pi auth path from ${configPath}: ${error instanceof Error ? error.message : String(error)}`));
+        return 1;
+    }
+    const plan = planProviderSetup({
+        modelRefs: [directCodex ? "codex:gpt-5.6-terra" : `pi:${provider}:credential-setup`],
+        cwd,
+        piAuthPath: configuredPiAuthPath,
+        forceAuthentication: true,
+        ...(args.codexAuthMode === undefined ? {} : { codexAuthMode: args.codexAuthMode }),
+    });
+    if (plan.actions.length === 0) {
+        process.stderr.write(ui.errorLine(`Provider \`${provider}\` has no interactive auth method in the bundled ${directCodex ? "Codex" : "Pi"} provider catalog.`));
+        return 2;
+    }
+    const apiKeyActions = plan.actions.filter(isProviderSetupPiApiKeyAction);
+    if (args.apiKeyStdin === true && apiKeyActions.length !== 1) {
+        process.stderr.write(ui.errorLine("--api-key-stdin is only supported when the selected provider has one bundled API-key login action."));
+        return 2;
+    }
+    process.stdout.write("\n" + ui.heading(directCodex ? "Codex authentication" : "Pi authentication"));
+    printProviderSetupPlan(plan);
+    let apiKeys;
+    const apiKeyAction = apiKeyActions[0];
+    if (apiKeyAction !== undefined) {
+        let apiKey;
+        if (args.apiKeyStdin === true) {
+            if (process.stdin.isTTY === true) {
+                process.stderr.write(ui.errorLine("--api-key-stdin requires redirected standard input. Omit the flag to enter the key in a masked prompt."));
+                return 2;
+            }
+            try {
+                apiKey = await readApiKeyFromStdin(process.stdin);
+            }
+            catch {
+                process.stderr.write(ui.errorLine(`Could not read a valid ${apiKeyAction.envVar} value from standard input; no credentials were written.`));
+                return 1;
+            }
+        }
+        else {
+            if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
+                process.stderr.write(ui.errorLine(`Cannot securely prompt for ${apiKeyAction.envVar} without an interactive TTY. ` +
+                    `Run this command in a terminal, or pipe the value explicitly with --api-key-stdin; no credentials were written.`));
+                return 1;
+            }
+            const answer = await p.password({
+                message: `Enter ${apiKeyAction.label} (${apiKeyAction.envVar})`,
+                validate: (value) => apiKeyInputProblem(value ?? ""),
+                clearOnError: true,
+            });
+            if (p.isCancel(answer)) {
+                process.stderr.write(ui.errorLine("Authentication was cancelled; no credentials were written."));
+                return 130;
+            }
+            apiKey = answer.trim();
+        }
+        apiKeys = { [apiKeyAction.id]: apiKey };
+    }
+    process.stdout.write(ui.style.dim("Press Ctrl-C once to interrupt authentication safely.\n"));
+    const execution = await withScopedPreflightCancellation(async (abortSignal) => ({
+        results: await executeProviderSetupPlan(plan, {
+            ...(apiKeys === undefined ? {} : { apiKeys }),
+            abortSignal,
+        }),
+        interrupted: abortSignal.aborted,
+    }), { keypress: false });
+    const { results } = execution;
+    for (const result of results) {
+        const badge = execution.interrupted && result.status === "failed"
+            ? ui.badge("waiting")
+            : result.status === "ok"
+                ? ui.badge("ok")
+                : ui.badge("error");
+        process.stdout.write(`${badge}${result.action.label}: ${result.detail}\n`);
+    }
+    if (results.some((result) => result.failureKind !== undefined)) {
+        process.stderr.write(ui.errorLine("Provider setup ended in an unconfirmed process or credential-cleanup state. Follow the reported manual cleanup guidance before retrying; automatic recovery is disabled."));
+        return 130;
+    }
+    if (execution.interrupted) {
+        process.stderr.write(ui.errorLine("Authentication was interrupted; temporary credentials were cleaned up."));
+        return 130;
+    }
+    return results.every((result) => result.status === "ok") ? 0 : 1;
+}
+const MAX_STANDALONE_API_KEY_BYTES = 65_536;
+function apiKeyInputProblem(value) {
+    const normalized = value.trim();
+    if (normalized.length === 0)
+        return "API key is required.";
+    if (normalized.includes("\0") || /[\r\n]/u.test(normalized))
+        return "API key must be a single non-empty line.";
+    if (Buffer.byteLength(normalized, "utf8") > MAX_STANDALONE_API_KEY_BYTES)
+        return "API key is too large.";
+    return undefined;
+}
+/**
+ * Read one explicitly redirected API key without consulting ambient provider
+ * environment variables. A single trailing line ending from `echo` is accepted;
+ * embedded newlines, NUL bytes, empty input, and unbounded input fail closed.
+ */
+export async function readApiKeyFromStdin(input) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of input) {
+        const bytes = typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk);
+        size += bytes.byteLength;
+        if (size > MAX_STANDALONE_API_KEY_BYTES + 2)
+            throw new Error("API key input is too large.");
+        chunks.push(bytes);
+    }
+    const value = Buffer.concat(chunks).toString("utf8").replace(/\r?\n$/u, "");
+    const problem = apiKeyInputProblem(value);
+    if (problem !== undefined)
+        throw new Error(problem);
+    return value.trim();
+}
+export async function resolvePiAuthPathForLogin(options) {
+    // A missing config is represented by readMonoAgentConfigJson as `missing`; a
+    // malformed or unreadable config throws and must remain visible to operators.
+    const result = await readMonoAgentConfigJson(options.configPath);
+    const configured = result.missing ? undefined : result.json.providers?.piAuthPath;
+    return resolveEffectivePiAuthPath({
+        cwd: options.cwd ?? dirname(resolve(options.configPath)),
+        ...(nonEmptyEnv(options.piAuthPath) ? { explicitPath: options.piAuthPath } : {}),
+        ...(nonEmptyEnv(options.envPath) ? { envPath: options.envPath } : {}),
+        ...(nonEmptyEnv(configured) ? { configPath: configured } : {}),
+    });
+}
 function printProviderSetupPlan(plan) {
     for (const action of plan.actions) {
         process.stdout.write(`  ${action.label}: ${providerSetupActionCommandLine(action)} ${ui.style.dim(`(cwd: ${action.cwd})`)}\n`);
@@ -820,17 +2834,56 @@ function resolveWithChannels(args) {
     }
     return args.withChannels.filter(isWithChannel);
 }
+/** Safe reporting rows: paths and outcomes only, never secret contents. */
+export function initChangeDisplayRows(result) {
+    const labels = {
+        created: "created",
+        updated: "updated",
+        unchanged: "kept",
+        "planned-create": "would create",
+        "planned-update": "would update",
+    };
+    return result.changes.map((change) => ({
+        label: labels[change.kind],
+        path: change.path,
+        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,
+        label: secret.label,
+        description: secret.description,
+        status: configured.has(secret.envVar) ? "configured" : secret.required ? "missing" : "optional",
+    }));
+}
 function printInitResult(result) {
     if (result.dryRun) {
         process.stdout.write(ui.style.dim("Dry run — nothing was written.\n"));
     }
-    const verb = result.dryRun ? "would create" : "created";
-    for (const path of result.created) {
-        process.stdout.write(`${ui.badge("ok")}${ui.style.green(verb.padEnd(12))}  ${path}\n`);
-    }
-    for (const path of result.skipped) {
-        process.stdout.write(ui.style.dim(`  kept          ${path}`) + "\n");
+    for (const row of initChangeDisplayRows(result)) {
+        const prefix = row.unchanged ? "  " : ui.badge("ok");
+        const rendered = row.unchanged
+            ? ui.style.dim(row.label.padEnd(12))
+            : ui.style.green(row.label.padEnd(12));
+        // Sensitive files are safe to identify by path; their contents are never
+        // 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`);
     }
@@ -843,29 +2896,107 @@ function printInitResult(result) {
             process.stdout.write(`  ${ui.style.cyan(module.title)} ${ui.style.dim(`(risk: ${riskColor(module.riskLevel)})`)}\n`);
         }
     }
-    if (result.plan.envExample !== undefined) {
-        process.stdout.write("\n" + ui.style.dim("Fill the secret placeholders in .env.example, then copy it to .env.\n"));
+    if (result.secretPersistence.status === "persisted") {
+        process.stdout.write("\n" + ui.style.dim(result.secretPersistence.changed
+            ? "Required secrets were securely merged into .env (mode 0600).\n"
+            : "Required secrets were already securely configured in .env.\n"));
+    }
+    else if (result.secretPersistence.status === "planned") {
+        process.stdout.write("\n" + ui.style.dim("Dry run: required secrets would be securely merged into .env.\n"));
+    }
+    else if (result.secretPersistence.status === "refused") {
+        process.stderr.write(ui.hint(`Automatic secret persistence was refused${result.secretPersistence.reason === undefined ? "" : ` (${result.secretPersistence.reason})`}. No secret value was written.\n` +
+            (result.secretPersistence.detail === undefined ? "" : `${result.secretPersistence.detail}\n`)));
+    }
+    else if (result.plan.envExample !== undefined) {
+        process.stdout.write("\n" + ui.style.dim("Use .env.example as a reference and add missing values to .env; do not overwrite an existing .env.\n"));
     }
 }
-function printSecretsChecklist(secrets) {
+function printSecretsChecklist(secrets, configured = new Set()) {
     process.stdout.write("\n" + ui.heading("Secrets checklist"));
     if (secrets.length === 0) {
         process.stdout.write(ui.style.dim("No secrets required by the selected capabilities.\n"));
         return;
     }
-    process.stdout.write(ui.style.dim("Copy .env.example to .env, then fill these variables. Secret values are never written to JSON.\n"));
-    for (const secret of secrets) {
-        process.stdout.write(`  ${ui.style.bold(secret.envVar)} ${ui.style.dim(`- ${secret.label}: ${secret.description}`)}\n`);
+    process.stdout.write(ui.style.dim("Secret values are never written to config JSON and are never printed.\n"));
+    for (const secret of secretChecklistDisplayRows(secrets, configured)) {
+        const status = secret.status === "configured"
+            ? ui.style.green(secret.status)
+            : ui.style.yellow(secret.status);
+        process.stdout.write(`  ${ui.style.bold(secret.envVar)} ${ui.style.dim(`- ${secret.label}: ${secret.description}`)} ${status}\n`);
     }
 }
 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 start\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) {
+        try {
+            if (args.update === true) {
+                const result = await updateManagedProjectSkills(process.cwd());
+                for (const path of result.updated) {
+                    process.stdout.write(`${ui.badge("ok")}${ui.style.green("updated")}  ${path}\n`);
+                }
+                if (result.backupDir !== undefined) {
+                    process.stdout.write(`${ui.badge("ok")}backup    ${result.backupDir}\n`);
+                }
+                if (result.updated.length === 0)
+                    process.stdout.write(`${ui.badge("ok")}project skills are current\n`);
+                return 0;
+            }
+            const result = await checkManagedProjectSkills(process.cwd());
+            for (const status of result.statuses) {
+                const badge = status.status === "ready" ? ui.badge("ok") : ui.badge("error");
+                process.stdout.write(`${badge}${status.name}: ${status.status} (${status.path})\n`);
+            }
+            if (!result.ok && args.check !== true) {
+                process.stderr.write(ui.errorLine("Project skills need attention. Run `mono-agent install-skill --project --update`; modified copies require manual reconciliation."));
+            }
+            return result.ok ? 0 : 1;
+        }
+        catch (error) {
+            process.stderr.write(ui.errorLine(error instanceof Error ? error.message : String(error)));
+            return 1;
+        }
+    }
     let result;
     try {
         result = await installComposerSkill({
@@ -890,22 +3021,58 @@ async function runValidate(args) {
         configPath: context.configPath,
         allowFilesystemWrites: context.allowFilesystemWrites,
     });
-    for (const section of report.sections) {
-        process.stdout.write(formatSection(section));
-    }
     const preset = resolveValidatePreset(args);
     if (preset === "unknown") {
+        if (args.json === true) {
+            process.stdout.write(`${JSON.stringify({ ok: false, sections: report.sections })}\n`);
+        }
         return 1;
     }
+    let presetResult;
     if (preset !== undefined) {
         const plan = composeWizardPlan(presetAnswers(preset), {
             dirBasename: basename(context.cwd),
             skillsRootExists: false,
         });
+        presetResult = {
+            id: preset.id,
+            expectations: plan.validateExpectations.map((expectation) => {
+                const actual = report.sections.find((entry) => entry.id === expectation.sectionId)?.status ?? "missing";
+                return {
+                    sectionId: expectation.sectionId,
+                    expected: expectation.mustBe,
+                    actual,
+                    met: actual === expectation.mustBe,
+                };
+            }),
+        };
+        if (args.json === true) {
+            process.stdout.write(`${JSON.stringify({
+                ok: report.ok,
+                sections: report.sections,
+                preset: presetResult,
+            })}\n`);
+            return report.ok ? 0 : 1;
+        }
+        for (const section of report.sections) {
+            process.stdout.write(formatSection(section));
+        }
         process.stdout.write(renderPlanCompleteness(plan.validateExpectations, `Preset: ${preset.id}`, report));
     }
+    else if (args.json === true) {
+        process.stdout.write(`${JSON.stringify({ ok: report.ok, sections: report.sections })}\n`);
+        return report.ok ? 0 : 1;
+    }
+    else {
+        for (const section of report.sections) {
+            process.stdout.write(formatSection(section));
+        }
+    }
+    const hasWaitingSections = report.sections.some((section) => section.status === "waiting");
     process.stdout.write(report.ok
-        ? `\n${ui.style.green("✓ Config is ready to start.")}\n${ui.style.dim("Run `mono-agent config` for the full field-by-field view.")}\n`
+        ? hasWaitingSections
+            ? `\n${ui.style.yellow("⚠ Config is structurally valid, but needs attention before start.")}\n${ui.style.dim("Review the waiting sections above, then re-run mono-agent validate.")}\n`
+            : `\n${ui.style.green("✓ Config is ready to start.")}\n${ui.style.dim("Run `mono-agent config` for the full field-by-field view.")}\n`
         : `\n${ui.hint("Fix the errors above, then re-run mono-agent validate.")}`);
     process.stdout.write(ui.style.dim("Core sections activate by presence; channels need `enabled: true` — see docs/config (How sections activate).\n"));
     return report.ok ? 0 : 1;
@@ -1151,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) {
-    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: process.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 };
     }
@@ -1186,66 +3359,166 @@ async function pathExists(path) {
         return false;
     }
 }
-async function runStart(args) {
+async function runStart(args, env, managedBackgroundWorker = false) {
     if (args.foreground) {
-        return await runForeground(args);
+        return await runForeground(args, env, managedBackgroundWorker);
     }
-    return await runBackgroundCommand(args, "start");
+    return await runBackgroundCommand(args, "start", env);
 }
 /**
  * The blocking worker: builds the responder, starts every configured channel
  * 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) {
-    const pre = await ensureStartable(args);
-    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);
     }
-    const app = await startMonoAgentApp({
-        cwd: process.cwd(),
-        ...(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) {
+    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");
+        });
+    }
+}
+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);
+        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: process.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":
@@ -1260,20 +3533,17 @@ async function runBackgroundCommand(args, command) {
  * 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
@@ -1419,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);