@mono-agent/agent-app 0.6.1 → 0.8.0

package/dist/wizard/run.js

@@ -1,15 +1,113 @@
 import { stat } from "node:fs/promises";
 import { basename, join } from "node:path";
+import { emitKeypressEvents } from "node:readline";
 import * as p from "@clack/prompts";
+import { parseMonoRuntimeModelReference } from "@mono-agent/runtime-adapter";
 import { findModule } from "../modules/catalog.js";
-import { ALLOW_ALL_TOOLS, BUILTIN_TOOL_NAMES, isAllowAllTools } from "../modules/known-tools.js";
-import { planProviderSetup, providerSetupActionCommandLine } from "../provider-setup.js";
-import { alwaysOnTools, composeWizardPlan, defaultAnswers, recommendedToolSelection, } from "./answers.js";
+import { hasSensitivePersistedEnvironmentValue } from "../first-run-readiness.js";
+import { DEFAULT_MODEL } from "../modules/base.js";
+import { ALLOW_ALL_TOOLS, APP_TOOL_NAMES, BUILTIN_TOOL_NAMES, isAllowAllTools } from "../modules/known-tools.js";
+import { hasDurableProviderEnvironmentCredential, isProviderSetupPiApiKeyAction, planProviderSetup, providerSetupActionCommandLine, } from "../provider-setup.js";
+import { isSupermemoryPluginInstalled } from "../supermemory-plugin.js";
+import { alwaysOnTools, composeWizardPlan, defaultAnswers, effectiveFallbacks, humanizeAgentName, recommendedToolSelection, referencedSetupModelRefs, } from "./answers.js";
 import { findPreset, presetAnswers } from "./presets.js";
-import { channelSelectOptions, effortSelectOptions, guard, memorySelectOptions, modelSelectOptions, presetSelectOptions, toolMultiselectOptions, WizardCancelled, } from "./prompts.js";
-import { discoverWizardModelCandidates, formatModelDiscoveryStatus } from "./model-discovery.js";
-const LOCAL_PROVIDER_MODEL = /^pi:(?:ollama|lmstudio):/u;
+import { assertConcreteWizardModelRef, channelSelectOptions, creationReviewOptions, CUSTOM_PI_MODEL_OPTION, effortSelectOptions, fallbackModelSelectOptions, formatRouteSafetyMatrix, isMixedRouteChain, memorySelectOptions, MODEL_AUTOCOMPLETE_MAX_ITEMS, modelSelectOptions, piModelSelectOptions, presetSelectOptions, ROUTE_SAFETY_OPTIONS, toolMultiselectOptions, validateWizardAgentName, validateWizardAgentPurpose, wizardCancelIntentForKey, WizardBack, WizardCancelled, WizardExitRequested, } from "./prompts.js";
+import { discoverWizardModelCandidates, formatModelDiscoveryStatus, guidedPiProviderProblem, } from "./model-discovery.js";
 const SANDBOXABLE_TOOLS = new Set(["Bash", "Write", "Edit"]);
+/**
+ * Clack intentionally coalesces Escape and Ctrl-C into one cancel sentinel. The
+ * wizard owns a scoped keypress observer so the state machine can interpret
+ * Escape as Back and Ctrl-C as Exit without changing Clack globally.
+ */
+async function runPrompt(invoke) {
+    let intent;
+    const input = process.stdin;
+    const listener = (_text, key) => {
+        intent = wizardCancelIntentForKey(key) ?? intent;
+    };
+    if (input.isTTY) {
+        emitKeypressEvents(input);
+        input.on("keypress", listener);
+    }
+    try {
+        const value = await invoke();
+        if (!p.isCancel(value))
+            return value;
+        if (intent === "back")
+            throw new WizardBack();
+        throw new WizardExitRequested();
+    }
+    finally {
+        if (input.isTTY)
+            input.off("keypress", listener);
+    }
+}
+async function discoverModelsInterruptibly(options) {
+    const controller = new AbortController();
+    let intent;
+    const input = process.stdin;
+    const wasRaw = input.isRaw === true;
+    const wasFlowing = input.readableFlowing;
+    const interrupt = (nextIntent) => {
+        intent ??= nextIntent;
+        controller.abort();
+    };
+    const onKeypress = (_text, key) => {
+        const nextIntent = wizardCancelIntentForKey(key);
+        if (nextIntent !== undefined)
+            interrupt(nextIntent);
+    };
+    const onSigint = () => interrupt("exit");
+    if (input.isTTY) {
+        emitKeypressEvents(input);
+        input.setRawMode?.(true);
+        input.resume();
+        input.on("keypress", onKeypress);
+    }
+    process.on("SIGINT", onSigint);
+    try {
+        const result = await discoverWizardModelCandidates({
+            ...options,
+            abortSignal: controller.signal,
+        });
+        if (!controller.signal.aborted)
+            return result;
+    }
+    catch (error) {
+        if (!controller.signal.aborted)
+            throw error;
+    }
+    finally {
+        process.off("SIGINT", onSigint);
+        if (input.isTTY) {
+            input.off("keypress", onKeypress);
+            input.setRawMode?.(wasRaw);
+            if (wasFlowing !== true)
+                input.pause();
+        }
+    }
+    if (intent === "back")
+        throw new WizardBack();
+    throw new WizardExitRequested();
+}
+async function select(options) {
+    return runPrompt(() => p.select(options));
+}
+async function autocomplete(options) {
+    return runPrompt(() => p.autocomplete(options));
+}
+async function confirm(options) {
+    return runPrompt(() => p.confirm(options));
+}
+async function multiselect(options) {
+    return runPrompt(() => p.multiselect(options));
+}
+async function textPrompt(options) {
+    return runPrompt(() => p.text(options));
+}
+async function passwordPrompt(options) {
+    return runPrompt(() => p.password(options));
+}
 /**
  * The interactive `init` wizard: a colourful, step-by-step flow that COLLECTS a
  * {@link WizardAnswers} and hands it back — it never writes anything. The caller
@@ -20,7 +118,16 @@ const SANDBOXABLE_TOOLS = new Set(["Bash", "Write", "Edit"]);
 export async function runInitWizard(ctx) {
     try {
         const result = await collectAnswers(ctx);
-        return { status: "answers", answers: result.answers, runProviderSetup: result.runProviderSetup };
+        return {
+            status: "answers",
+            answers: result.answers,
+            runProviderSetup: result.runProviderSetup,
+            providerSetupSecrets: result.providerSetupSecrets,
+            providerEnvironmentSecrets: result.providerEnvironmentSecrets,
+            piApiKeyPersistenceByProvider: result.piApiKeyPersistenceByProvider,
+            credentialStates: result.credentialStates,
+            moduleSecrets: result.moduleSecrets,
+        };
     }
     catch (error) {
         if (error instanceof WizardCancelled) {
@@ -30,95 +137,287 @@ export async function runInitWizard(ctx) {
         throw error;
     }
 }
+/**
+ * Re-open an already reviewed setup at the Creation review. The caller keeps
+ * ownership of the original state: Escape returns `cancelled`, and no mutable
+ * credential or answer state is exposed unless the operator confirms a repair.
+ */
+export async function runSetupRepairWizard(ctx) {
+    try {
+        p.log.step("Repair setup choices");
+        const initialStep = ctx.initialStep ?? 8;
+        const result = await collectInteractiveFromSeed(ctx, ctx.answers, {
+            initialStep,
+            ...(initialStep === 8 ? {} : { initialReturnToReviewStep: initialStep }),
+            returnToCallerOnReviewBack: true,
+            repairState: ctx,
+        });
+        return {
+            status: "answers",
+            answers: result.answers,
+            runProviderSetup: result.runProviderSetup,
+            providerSetupSecrets: result.providerSetupSecrets,
+            providerEnvironmentSecrets: result.providerEnvironmentSecrets,
+            piApiKeyPersistenceByProvider: result.piApiKeyPersistenceByProvider,
+            credentialStates: result.credentialStates,
+            moduleSecrets: result.moduleSecrets,
+        };
+    }
+    catch (error) {
+        if (error instanceof WizardBack || error instanceof WizardCancelled) {
+            p.log.info("Returning to the preflight recovery menu; previous setup choices were kept.");
+            return { status: "cancelled" };
+        }
+        throw error;
+    }
+}
+/**
+ * Re-select only primary/fallback models and effort after a failed model check.
+ * Capabilities, module inputs, and observability are copied from `ctx.answers`,
+ * and no module secret is requested again. Tool/sandbox choices are re-confirmed
+ * when the runtime family crosses the direct-Codex boundary or changes whether
+ * a provider-owned Claude/direct-OpenCode tool loop is present.
+ */
+export async function runModelRepairWizard(ctx) {
+    try {
+        p.log.step("Repair model configuration");
+        for (;;) {
+            const draft = draftFrom(ctx.answers);
+            try {
+                const previousFamilies = selectedRuntimeModels(draft).map(runtimeFamily).join(",");
+                await promptModelSettings(draft, ctx);
+                const nextFamilies = selectedRuntimeModels(draft).map(runtimeFamily).join(",");
+                if (previousFamilies !== nextFamilies
+                    || !hasExactAllowAllTools(draft)
+                    || hasInvalidUniformManagedSrtChain(draft)) {
+                    p.log.info("The runtime route changed, so tool and sandbox safety choices must be confirmed again.");
+                    await promptTools(draft);
+                    await promptSafetyPolicy(draft);
+                }
+                const answers = toWizardAnswers(draft);
+                const plan = await composePlanForCwd(answers, ctx.cwd);
+                const providerSetup = await promptProviderSetup(plan, ctx, draft.credentialStates);
+                if (!await confirm({ message: "Use this model configuration?", initialValue: true })) {
+                    return { status: "cancelled" };
+                }
+                return { status: "answers", answers, ...providerSetup, credentialStates: { ...draft.credentialStates } };
+            }
+            catch (error) {
+                if (error instanceof WizardBack) {
+                    p.log.info("Returning to the preflight recovery menu; previous model choices were kept.");
+                    return { status: "cancelled" };
+                }
+                if (error instanceof WizardExitRequested) {
+                    if (await confirmExitSetup())
+                        throw new WizardCancelled();
+                    continue;
+                }
+                throw error;
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof WizardCancelled) {
+            p.cancel("Model repair cancelled — previous choices were kept.");
+            return { status: "cancelled" };
+        }
+        throw error;
+    }
+}
 /** Walk the flow (preset or custom), returning the fully collected answers. */
 async function collectAnswers(ctx) {
     p.intro("mono-agent init — let's build your agent");
-    const choice = guard(await p.select({
-        message: "Start from…",
-        options: presetSelectOptions(),
-        initialValue: "__custom__",
-    }));
-    return choice === "__custom__"
-        ? await collectCustom(ctx)
-        : await collectFromPreset(ctx, choice);
+    for (;;) {
+        let choice;
+        try {
+            choice = await select({
+                message: "Start from…",
+                options: presetSelectOptions(),
+                initialValue: "__custom__",
+            });
+        }
+        catch (error) {
+            if (error instanceof WizardBack || error instanceof WizardExitRequested) {
+                if (await confirmExitSetup())
+                    throw new WizardCancelled();
+                continue;
+            }
+            throw error;
+        }
+        try {
+            return choice === "__custom__"
+                ? await collectCustom(ctx)
+                : await collectFromPreset(ctx, choice);
+        }
+        catch (error) {
+            // Escape from the first detail step returns to the preset chooser. Ctrl-C
+            // is handled inside the detail state machine and should not normally leak.
+            if (error instanceof WizardBack)
+                continue;
+            if (error instanceof WizardExitRequested) {
+                if (await confirmExitSetup())
+                    throw new WizardCancelled();
+                continue;
+            }
+            throw error;
+        }
+    }
 }
 /**
  * The full custom flow: model → effort → channels → memory → per-module inputs
  * → tools → sandbox (only if code tools were chosen) → observability → summary.
  */
 async function collectCustom(ctx) {
-    const draft = draftFrom(defaultAnswers());
-    // 1. Model.
-    const discovery = await discoverWizardModelCandidates();
-    p.note(formatModelDiscoveryStatus(discovery.statuses), "Model discovery");
-    const model = guard(await p.select({
-        message: "Which model?",
-        options: modelSelectOptions(discovery.candidates),
-        initialValue: "claude:claude-sonnet-4-6",
+    return await collectInteractiveFromSeed(ctx, defaultAnswers({
+        name: humanizeAgentName(basename(ctx.cwd)),
     }));
-    draft.model = model === "__other__"
-        ? guard(await p.text({
-            message: "Model reference",
+}
+async function resolveModelSelection(model, opts) {
+    if (model === "__pi_other__") {
+        return await promptPiModelSelection(opts);
+    }
+    if (model === "__other__") {
+        const resolved = (await textPrompt({
+            message: opts.context === "primary" ? "Model reference" : "Fallback model reference",
             placeholder: "pi:ollama:llama3.1:8b",
-            validate: (v) => (v ?? "").trim().length === 0
-                ? "Enter a provider:model reference (e.g. pi:ollama:llama3.1:8b)"
-                : undefined,
-        }))
-        : model;
-    // Optional fallback chain.
-    if (guard(await p.confirm({ message: "Add fallback models?", initialValue: false }))) {
-        const raw = guard(await p.text({
-            message: "Fallback models (comma-separated)",
-            placeholder: "codex:gpt-5.5, pi:ollama:llama3.1:8b",
-        }));
-        draft.fallbackModels = splitCsv(raw);
-    }
-    const effort = guard(await p.select({
-        message: "Reasoning effort?",
-        options: effortSelectOptions(),
-        initialValue: "",
-    }));
-    draft.effort = effort.length === 0 ? undefined : effort;
-    // 2. Channels.
-    const channels = guard(await p.multiselect({
-        message: "How will you talk to this agent?",
-        options: channelSelectOptions(),
-        initialValues: ["channel:webhook"],
-        required: false,
-    }));
-    draft.channels = [...channels];
-    // 3. Memory (before per-module inputs so a memory module's inputs are prompted).
-    const memory = guard(await p.select({
-        message: "Should the agent remember across conversations?",
-        options: memorySelectOptions(),
-        initialValue: "",
-    }));
-    draft.memory = memory === "" ? undefined : memory;
-    // 4. Per-module (non-secret) inputs for the chosen channels + memory.
-    await promptModuleInputs(draft);
-    // 5. Tools.
-    await promptTools(draft);
-    // 6. Sandbox — only meaningful once shell/file tools are in play. Allow-all
-    // includes Bash/Write/Edit, so the sandbox question must still appear under it.
-    if (isAllowAllTools(draft.allowedTools) || draft.allowedTools.some((tool) => SANDBOXABLE_TOOLS.has(tool))) {
-        draft.sandbox = guard(await p.confirm({
-            message: "Sandbox shell/file tools? (native srt, localhost-only network, fails closed if srt is missing)",
-            initialValue: true,
-        }));
+            validate: validateFullModelReference,
+        })).trim();
+        assertConcreteWizardModelRef(resolved);
+        assertGuidedModelRef(resolved);
+        return resolved;
+    }
+    assertConcreteWizardModelRef(model);
+    assertGuidedModelRef(model);
+    return model;
+}
+async function promptPiModelSelection(opts) {
+    const options = piModelSelectOptions(opts.candidates, opts.excludedModels ?? []);
+    const choice = await autocomplete({
+        message: opts.context === "primary" ? "Other Pi model" : "Other Pi fallback model",
+        options,
+        initialValue: options[0]?.value ?? CUSTOM_PI_MODEL_OPTION,
+        placeholder: "Type to search Pi providers and models…",
+        maxItems: MODEL_AUTOCOMPLETE_MAX_ITEMS,
+    });
+    if (choice !== CUSTOM_PI_MODEL_OPTION) {
+        assertConcreteWizardModelRef(choice);
+        return choice;
+    }
+    return await promptManualPiModelRef();
+}
+async function promptManualPiModelRef() {
+    const provider = (await textPrompt({
+        message: "Pi provider id",
+        placeholder: "openai-codex",
+        validate: (v) => {
+            const value = (v ?? "").trim();
+            if (value.length === 0) {
+                return "Enter a supported Pi provider id (anthropic, github-copilot, openai-codex, opencode-go, ollama, or lmstudio)";
+            }
+            if (value.includes(":"))
+                return "Provider id cannot contain ':'.";
+            return guidedPiProviderProblem(value);
+        },
+    })).trim();
+    const modelId = (await textPrompt({
+        message: "Pi model id",
+        placeholder: provider === "openai-codex" ? "gpt-5.6-terra" : "llama3.1:8b",
+        validate: (v) => (v ?? "").trim().length === 0
+            ? "Enter the provider-specific model id (e.g. gpt-5.6-terra, gpt-5.6-sol, kimi-k2.6, llama3.1:8b)"
+            : undefined,
+    })).trim();
+    return `pi:${provider}:${modelId}`;
+}
+function validateFullModelReference(value) {
+    const trimmed = (value ?? "").trim();
+    if (trimmed.length === 0) {
+        return "Enter a provider:model reference (e.g. pi:ollama:llama3.1:8b)";
+    }
+    if (trimmed.includes(",")) {
+        return "Enter one model reference. Add more fallbacks one at a time.";
+    }
+    try {
+        assertConcreteWizardModelRef(trimmed);
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : "Enter a concrete model reference.";
+    }
+    return guidedModelRefProblem(trimmed);
+}
+function assertGuidedModelRef(model) {
+    const problem = guidedModelRefProblem(model);
+    if (problem !== undefined) {
+        throw new Error(problem);
+    }
+}
+export function guidedModelRefProblem(model) {
+    let parsed;
+    try {
+        parsed = parseMonoRuntimeModelReference(model);
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : "Enter a concrete model reference.";
+    }
+    if (parsed.sdk === "opencode") {
+        return "Direct OpenCode is scaffold/config-only. Choose pi:opencode-go:* for guided readiness.";
+    }
+    if (parsed.sdk === "pi" && parsed.provider !== undefined) {
+        return guidedPiProviderProblem(parsed.provider);
+    }
+    return parsed.sdk === "claude" || parsed.sdk === "codex"
+        ? undefined
+        : "Guided init supports Claude, Codex, supported Pi providers, and local Pi routes.";
+}
+/**
+ * Build an ordered fallback chain one model at a time. Each step reuses the same
+ * discovered model labels as the primary picker while hiding the selected primary
+ * and any fallback already chosen. `Other…` is the explicit path for custom refs.
+ */
+async function promptFallbackModels(draft, candidates) {
+    const byValue = new Map(candidates.map((candidate) => [candidate.value, candidate]));
+    for (;;) {
+        const selectedModels = draft.fallbacks.map((fallback) => fallback.model);
+        let choice;
+        try {
+            choice = await autocomplete({
+                message: `Fallback model #${draft.fallbacks.length + 1}`,
+                options: fallbackModelSelectOptions(candidates, draft.model, selectedModels),
+                initialValue: "__done__",
+                placeholder: "Type to search all supported models…",
+                maxItems: MODEL_AUTOCOMPLETE_MAX_ITEMS,
+            });
+        }
+        catch (error) {
+            if (!(error instanceof WizardBack) || draft.fallbacks.length === 0)
+                throw error;
+            draft.fallbacks.pop();
+            continue;
+        }
+        if (choice === "__done__") {
+            return;
+        }
+        const resolved = await resolveModelSelection(choice, {
+            candidates,
+            excludedModels: [draft.model, ...selectedModels],
+            context: "fallback",
+        });
+        if (resolved !== draft.model && !selectedModels.includes(resolved)) {
+            let effort;
+            try {
+                effort = await promptEffortForModel(resolved, byValue.get(resolved));
+            }
+            catch (error) {
+                if (error instanceof WizardBack)
+                    continue;
+                throw error;
+            }
+            draft.fallbacks.push({ model: resolved, ...(effort === undefined ? {} : { effort }) });
+        }
     }
-    // 7. Observability.
-    draft.observability = guard(await p.confirm({
-        message: "Export traces to Phoenix (best-effort OTLP, sensitive data excluded)?",
-        initialValue: false,
-    }));
-    // 8. Summary + final confirm.
-    const runProviderSetup = await confirmSummary(draft, ctx);
-    return { answers: toWizardAnswers(draft), runProviderSetup };
 }
 /**
- * The preset flow: the preset fixes model/channels/memory/sandbox/observability,
- * so we only prompt its per-module inputs, let the operator adjust tools, and
- * confirm the summary.
+ * Presets seed every choice, but do not silently freeze them. A first run must
+ * still choose its model, channels, tool policy, and sandbox safety posture.
  */
 async function collectFromPreset(ctx, presetId) {
     const preset = findPreset(presetId);
@@ -127,19 +426,428 @@ async function collectFromPreset(ctx, presetId) {
         throw new WizardCancelled();
     }
     p.log.step(`Preset: ${preset.title}`);
-    const draft = draftFrom(presetAnswers(preset));
-    await promptModuleInputs(draft);
-    await promptTools(draft);
-    const runProviderSetup = await confirmSummary(draft, ctx);
-    return { answers: toWizardAnswers(draft), runProviderSetup };
+    return await collectInteractiveFromSeed(ctx, defaultAnswers({
+        ...presetAnswers(preset),
+        name: humanizeAgentName(basename(ctx.cwd)),
+    }));
+}
+/**
+ * Whether a logical wizard step will actually ask the operator anything for
+ * the current draft. Some runtime families make Tools and Safety informative
+ * only; treating those as back-navigation destinations traps Escape in a
+ * silent forward loop.
+ */
+function wizardStepHasInteractivePrompt(step, draft) {
+    switch (step) {
+        case 0:
+        case 1:
+        case 2:
+        case 3:
+        case 7:
+        case 8:
+            return true;
+        case 4:
+            return [...draft.channels, ...(draft.memory === undefined ? [] : [draft.memory])]
+                .some((id) => findModule(id)?.inputs.some((input) => input.secret !== true) === true);
+        case 5:
+            return !selectedRuntimeModels(draft).every(hasFixedAllowAllToolPolicyRef);
+        case 6:
+            return safetyPolicyHasInteractivePrompt(draft);
+        default:
+            return false;
+    }
+}
+function safetyPolicyHasInteractivePrompt(draft) {
+    const models = selectedRuntimeModels(draft);
+    const mixed = isMixedRouteChain(models);
+    if (mixed)
+        return true;
+    const hasSandboxableTools = isAllowAllTools(draft.allowedTools)
+        || draft.allowedTools.some((tool) => SANDBOXABLE_TOOLS.has(tool));
+    const hasPiRoute = models.some((model) => model.startsWith("pi:"));
+    const providerNative = models.some((model) => !model.startsWith("pi:"));
+    if (hasSandboxableTools && hasPiRoute)
+        return true;
+    if (draft.routeSafety === "per-route-native" && providerNative)
+        return true;
+    return hasSandboxableTools
+        && providerNative
+        && !models.every(isDirectCodexRef)
+        && isAllowAllTools(draft.allowedTools);
+}
+function previousInteractiveWizardStep(step, draft) {
+    for (let candidate = step - 1; candidate >= 0; candidate -= 1) {
+        if (wizardStepHasInteractivePrompt(candidate, draft))
+            return candidate;
+    }
+    return undefined;
+}
+/** Shared custom/preset first-run chooser; seed answers only set sensible defaults. */
+async function collectInteractiveFromSeed(ctx, seed, options = {}) {
+    const draft = draftFrom(seed);
+    if (options.repairState !== undefined) {
+        draft.credentialStates = { ...options.repairState.credentialStates };
+    }
+    const modelDiscoveryCache = {};
+    let step = options.initialStep ?? 0;
+    let returnToReviewAfterStep = options.initialReturnToReviewStep;
+    const finalStep = 8;
+    const advanceAfter = (completedStep) => {
+        if (returnToReviewAfterStep === completedStep) {
+            returnToReviewAfterStep = undefined;
+            step = finalStep;
+        }
+        else {
+            step = completedStep + 1;
+        }
+    };
+    for (;;) {
+        const snapshot = cloneDraft(draft);
+        let finalizing = false;
+        try {
+            switch (step) {
+                case 0:
+                    draft.name = (await textPrompt({
+                        message: "What should this agent be called?",
+                        // Keep the current answer visible and editable when Escape returns
+                        // here from model selection. `defaultValue` only substitutes an
+                        // empty submission, so Clack would otherwise render the folder-name
+                        // placeholder and make a preserved custom name look lost.
+                        initialValue: draft.name,
+                        placeholder: humanizeAgentName(basename(ctx.cwd)),
+                        validate: validateWizardAgentName,
+                    })).trim();
+                    draft.purpose = (await textPrompt({
+                        message: "What should this agent help with?",
+                        initialValue: draft.purpose,
+                        placeholder: "Help with work in this folder",
+                        validate: validateWizardAgentPurpose,
+                    })).trim();
+                    advanceAfter(0);
+                    break;
+                case 1: {
+                    const previousFamilies = selectedRuntimeModels(draft).map(runtimeFamily).join(",");
+                    await promptModelSettings(draft, ctx, modelDiscoveryCache);
+                    const nextFamilies = selectedRuntimeModels(draft).map(runtimeFamily).join(",");
+                    if (returnToReviewAfterStep === 1
+                        && (previousFamilies !== nextFamilies
+                            || !hasExactAllowAllTools(draft)
+                            || hasInvalidUniformManagedSrtChain(draft))) {
+                        p.log.info("The runtime route changed, so tool and sandbox safety choices must be confirmed again.");
+                        await promptTools(draft);
+                        await promptSafetyPolicy(draft);
+                    }
+                    advanceAfter(1);
+                    break;
+                }
+                case 2: {
+                    const previousChannels = new Set(draft.channels);
+                    draft.channels = [...await multiselect({
+                            message: "How will you talk to this agent?",
+                            options: channelSelectOptions({ readyOnly: true }),
+                            initialValues: draft.channels,
+                            required: false,
+                        })];
+                    if (returnToReviewAfterStep === 2) {
+                        await promptModuleInputs(draft, draft.channels.filter((channel) => !previousChannels.has(channel)));
+                        await promptTools(draft);
+                        await promptSafetyPolicy(draft);
+                    }
+                    advanceAfter(2);
+                    break;
+                }
+                case 3: {
+                    const previousMemory = draft.memory;
+                    const memory = await select({
+                        message: "Should the agent remember across conversations?",
+                        options: memorySelectOptions({
+                            includeOptionalPlugins: draft.memory === "memory:supermemory"
+                                || isSupermemoryPluginInstalled({ cwd: ctx.cwd }),
+                        }),
+                        initialValue: draft.memory ?? "",
+                    });
+                    draft.memory = memory === "" ? undefined : memory;
+                    if (returnToReviewAfterStep === 3
+                        && draft.memory !== undefined
+                        && draft.memory !== previousMemory) {
+                        await promptModuleInputs(draft, [draft.memory]);
+                    }
+                    advanceAfter(3);
+                    break;
+                }
+                case 4:
+                    await promptModuleInputs(draft);
+                    advanceAfter(4);
+                    break;
+                case 5:
+                    await promptTools(draft);
+                    if (returnToReviewAfterStep === 5) {
+                        await promptSafetyPolicy(draft);
+                    }
+                    advanceAfter(5);
+                    break;
+                case 6:
+                    await promptSafetyPolicy(draft);
+                    advanceAfter(6);
+                    break;
+                case 7:
+                    draft.observability = await confirm({
+                        message: "Export traces to Phoenix (best-effort OTLP, sensitive data excluded)?",
+                        initialValue: draft.observability,
+                    });
+                    advanceAfter(7);
+                    break;
+                case 8: {
+                    const reviewed = await confirmSummary(draft, ctx, options.repairState === undefined
+                        ? undefined
+                        : {
+                            existing: options.repairState,
+                        });
+                    if (reviewed.status === "edit") {
+                        step = reviewed.step;
+                        returnToReviewAfterStep = reviewed.step === finalStep ? undefined : reviewed.step;
+                        break;
+                    }
+                    finalizing = true;
+                    const answers = toWizardAnswers(draft);
+                    const moduleSecrets = await promptRequiredModuleSecrets(answers, ctx.persistedEnv, options.repairState?.moduleSecrets);
+                    return {
+                        answers,
+                        ...reviewed.providerSetup,
+                        moduleSecrets,
+                        credentialStates: { ...draft.credentialStates },
+                    };
+                }
+                default:
+                    throw new Error(`Unknown wizard step ${step}.`);
+            }
+        }
+        catch (error) {
+            restoreDraft(draft, snapshot);
+            if (error instanceof WizardBack) {
+                if (options.returnToCallerOnReviewBack === true)
+                    throw error;
+                if (returnToReviewAfterStep === step) {
+                    returnToReviewAfterStep = undefined;
+                    step = finalStep;
+                    continue;
+                }
+                const previous = previousInteractiveWizardStep(step, draft);
+                if (previous === undefined)
+                    throw error;
+                // Secret/auth collection happens after the review choice. Escape there
+                // returns to the review rather than discarding unrelated answers.
+                step = step === finalStep && finalizing ? finalStep : previous;
+                continue;
+            }
+            if (error instanceof WizardExitRequested) {
+                if (await confirmExitSetup())
+                    throw new WizardCancelled();
+                continue;
+            }
+            throw error;
+        }
+    }
+}
+async function promptSafetyPolicy(draft) {
+    const models = selectedRuntimeModels(draft);
+    const mixed = isMixedRouteChain(models);
+    if (mixed) {
+        draft.routeSafety = await select({
+            message: "How should safety apply across this mixed fallback chain?",
+            options: [...ROUTE_SAFETY_OPTIONS],
+            initialValue: draft.routeSafety,
+        });
+    }
+    else {
+        draft.routeSafety = "uniform";
+    }
+    const hasSandboxableTools = isAllowAllTools(draft.allowedTools)
+        || draft.allowedTools.some((tool) => SANDBOXABLE_TOOLS.has(tool));
+    const hasPiRoute = models.some((model) => model.startsWith("pi:"));
+    const providerNative = models.some((model) => !model.startsWith("pi:"));
+    const mixedPiProviderNativeChain = mixed && hasPiRoute && providerNative;
+    if (hasSandboxableTools && hasPiRoute) {
+        draft.sandbox = await confirm({
+            message: "Install and use managed SRT for Pi shell/file tools? (localhost-only network; setup verifies fail-closed enforcement)",
+            initialValue: true,
+        });
+    }
+    else {
+        draft.sandbox = false;
+    }
+    if (mixedPiProviderNativeChain && draft.routeSafety === "uniform" && draft.sandbox) {
+        p.note("Managed SRT applies to Pi routes only. A mixed Pi/provider-native chain therefore cannot promise one uniform managed-SRT contract.", "Safety choice required");
+        const resolution = await select({
+            message: "How should this mixed chain resolve the managed-SRT mismatch?",
+            options: [
+                {
+                    value: "per-route-native",
+                    label: "Use per-route native safety",
+                    hint: "keep managed SRT for Pi and show every provider's native contract",
+                },
+                {
+                    value: "disable-managed-srt",
+                    label: "Disable managed SRT",
+                    hint: "keep the uniform contract without claiming SRT on provider-native routes",
+                },
+            ],
+            initialValue: "per-route-native",
+        });
+        if (resolution === "per-route-native")
+            draft.routeSafety = "per-route-native";
+        else
+            draft.sandbox = false;
+    }
+    if (draft.routeSafety === "per-route-native" && (mixed || providerNative)) {
+        p.note(formatRouteSafetyMatrix({ model: draft.model, ...(draft.effort === undefined ? {} : { effort: draft.effort }) }, draft.fallbacks, draft.sandbox), "Per-route safety contract");
+        const accepted = await confirm({
+            message: "Use these per-route safety contracts? Provider-native routes cannot enforce every mono-agent capability.",
+            initialValue: false,
+        });
+        if (!accepted) {
+            draft.routeSafety = "uniform";
+            if (mixedPiProviderNativeChain && draft.sandbox) {
+                draft.sandbox = false;
+                p.log.info("Managed SRT disabled because this mixed chain kept the uniform compatibility contract.");
+            }
+            p.log.info("Per-route native safety was not accepted; restored the uniform compatibility contract.");
+        }
+        else {
+            return;
+        }
+    }
+    if (hasSandboxableTools && hasPiRoute && isAllowAllTools(draft.allowedTools) && !draft.sandbox) {
+        const accepted = await confirmHighRiskUnsandboxedAccess();
+        if (!accepted) {
+            draft.sandbox = true;
+            if (mixedPiProviderNativeChain && draft.routeSafety === "uniform") {
+                draft.routeSafety = "per-route-native";
+                p.note(formatRouteSafetyMatrix({ model: draft.model, ...(draft.effort === undefined ? {} : { effort: draft.effort }) }, draft.fallbacks, draft.sandbox), "Per-route safety contract");
+                if (!await confirm({
+                    message: "Use these per-route safety contracts? Provider-native routes cannot enforce every mono-agent capability.",
+                    initialValue: false,
+                })) {
+                    throw new WizardBack();
+                }
+            }
+            else {
+                p.log.info("Managed SRT enabled because unsandboxed Pi allow-all access was not confirmed.");
+            }
+        }
+    }
+    else if (hasSandboxableTools
+        && providerNative
+        && !models.every(isDirectCodexRef)
+        && isAllowAllTools(draft.allowedTools)
+        && !await confirmHighRiskUnsandboxedAccess()) {
+        throw new WizardBack();
+    }
+}
+async function confirmHighRiskUnsandboxedAccess() {
+    return confirm({
+        message: "Proceed with high-risk unsandboxed access? The model may run shell commands, change files, access the web, and send through enabled channels.",
+        initialValue: false,
+    });
+}
+/** Select primary, fallbacks, and effort without touching any other answer. */
+async function promptModelSettings(draft, ctx, cache = {}) {
+    if (cache.result === undefined)
+        p.log.step("Discovering supported model catalogs…");
+    const discovery = cache.result ??= await discoverModelsInterruptibly({
+        ...(ctx.piAuthPath === undefined ? {} : { piAuthPath: ctx.piAuthPath }),
+        ...(ctx.persistedEnv === undefined ? {} : { persistedEnv: ctx.persistedEnv }),
+    });
+    const discoveredByValue = new Map(discovery.candidates.map((candidate) => [candidate.value, candidate]));
+    p.note(formatModelDiscoveryStatus(discovery.statuses), "Model discovery");
+    const previousModel = draft.model;
+    const previousEffort = draft.effort;
+    const providerDefault = discovery.candidates.find((candidate) => candidate.providerDefault === true);
+    const initialModel = draft.model === DEFAULT_MODEL ? providerDefault?.value ?? draft.model : draft.model;
+    let substep = 0;
+    for (;;) {
+        try {
+            if (substep === 0) {
+                const model = await autocomplete({
+                    message: "Which model?",
+                    options: modelSelectOptions(discovery.candidates, draft.model),
+                    initialValue: draft.model === DEFAULT_MODEL ? initialModel : draft.model,
+                    placeholder: "Type to search Pi, Codex, Claude, and local models…",
+                    maxItems: MODEL_AUTOCOMPLETE_MAX_ITEMS,
+                });
+                draft.model = await resolveModelSelection(model, { candidates: discovery.candidates, context: "primary" });
+                substep = 1;
+                continue;
+            }
+            if (substep === 1) {
+                draft.effort = await promptEffortForModel(draft.model, discoveredByValue.get(draft.model), draft.model === previousModel ? previousEffort : undefined);
+                substep = 2;
+                continue;
+            }
+            if (substep === 2) {
+                draft.fallbacks = [];
+                if (!await confirm({ message: "Add fallback models?", initialValue: false }))
+                    break;
+                substep = 3;
+                continue;
+            }
+            await promptFallbackModels(draft, discovery.candidates);
+            break;
+        }
+        catch (error) {
+            if (!(error instanceof WizardBack) || substep === 0)
+                throw error;
+            substep -= 1;
+        }
+    }
+    draft.credentialStates = selectedCredentialStates(draft, discoveredByValue, ctx.persistedEnv);
+}
+function selectedCredentialStates(draft, candidates, persistedEnv = {}) {
+    const states = {};
+    for (const model of selectedRuntimeModels(draft)) {
+        const key = providerCredentialKey(model);
+        if (key === undefined)
+            continue;
+        const authState = candidates.get(model)?.authState;
+        states[key] = authState === "verified"
+            ? "verified"
+            : hasDurableProviderEnvironmentCredential(model, persistedEnv)
+                ? "credential_detected"
+                : authState === "credential_detected"
+                    ? "credential_detected"
+                    : "auth_required";
+    }
+    return states;
+}
+function providerCredentialKey(model) {
+    if (model.startsWith("codex:"))
+        return "codex";
+    if (model.startsWith("claude:"))
+        return "claude";
+    if (!model.startsWith("pi:"))
+        return undefined;
+    const provider = model.split(":")[1];
+    return provider === undefined || provider === "ollama" || provider === "lmstudio" ? undefined : `pi:${provider}`;
+}
+async function promptEffortForModel(model, candidate, initial) {
+    const supported = candidate?.supportedEfforts ?? [];
+    const options = effortSelectOptions(supported, candidate?.defaultEffort);
+    const initialValue = initial !== undefined && supported.includes(initial) ? initial : "";
+    const effort = await select({
+        message: `Reasoning effort for ${model}`,
+        options,
+        initialValue,
+    });
+    return effort === "" ? undefined : effort;
 }
 /**
  * Prompt every non-secret input of the selected channel + memory modules and store
- * the answers into `draft.moduleInputs`. Secret inputs are never prompted — they
- * only ever surface as `.env.example` placeholders.
+ * the answers into `draft.moduleInputs`. Required secrets are collected only after
+ * the write confirmation so they can never appear in the plan summary.
  */
-async function promptModuleInputs(draft) {
-    const moduleIds = [...draft.channels, ...(draft.memory === undefined ? [] : [draft.memory])];
+async function promptModuleInputs(draft, requestedModuleIds) {
+    const moduleIds = requestedModuleIds
+        ?? [...draft.channels, ...(draft.memory === undefined ? [] : [draft.memory])];
     for (const id of moduleIds) {
         const module = findModule(id);
         if (module === undefined) {
@@ -149,21 +857,50 @@ async function promptModuleInputs(draft) {
             if (input.secret === true) {
                 continue;
             }
-            const answer = guard(await p.text({
+            const currentValue = draft.moduleInputs[module.id]?.[input.id];
+            const answer = await textPrompt({
                 message: `${module.title}: ${input.label}`,
                 placeholder: input.description,
                 ...(input.default === undefined ? {} : { defaultValue: input.default }),
-            }));
+                ...(currentValue === undefined ? {} : { initialValue: currentValue }),
+                ...(input.validate === undefined ? {} : { validate: input.validate }),
+            });
             const trimmed = answer.trim();
             if (trimmed.length > 0) {
                 (draft.moduleInputs[module.id] ??= {})[input.id] = trimmed;
             }
+            else {
+                delete draft.moduleInputs[module.id]?.[input.id];
+            }
         }
     }
 }
+/** Collect only typed required secrets, masked and retained solely for this run. */
+async function promptRequiredModuleSecrets(answers, persistedEnv = {}, existing = {}) {
+    const plan = composeWizardPlan(answers, { dirBasename: "agent", skillsRootExists: false });
+    const secrets = {};
+    for (const secret of plan.secrets) {
+        if (!secret.required || hasNonEmptyValue(persistedEnv[secret.envVar]))
+            continue;
+        if (hasNonEmptyValue(existing[secret.envVar])) {
+            secrets[secret.envVar] = existing[secret.envVar];
+            continue;
+        }
+        secrets[secret.envVar] = await passwordPrompt({
+            message: `${secret.label} (${secret.envVar})`,
+            validate: (value) => (value ?? "").trim().length === 0 ? "This secret is required for the selected capability." : undefined,
+            clearOnError: true,
+        });
+    }
+    return secrets;
+}
+function hasNonEmptyValue(value) {
+    return value !== undefined && value.trim().length > 0;
+}
 /** Short reasons annotating each always-on tool in the framing note. */
 const ALWAYS_ON_TOOL_REASONS = {
     MemoryRecall: "memory recall is on",
+    ReadSkill: "configuration skills load on demand",
 };
 /** The always-on tool names annotated with their reason, e.g. `MemoryRecall (memory recall is on)`. */
 function alwaysOnDisplay(alwaysOn) {
@@ -179,7 +916,7 @@ function alwaysOnDisplay(alwaysOn) {
  */
 function channelSendTools(channels) {
     return toolMultiselectOptions(channels)
-        .slice(BUILTIN_TOOL_NAMES.length)
+        .slice(BUILTIN_TOOL_NAMES.length + APP_TOOL_NAMES.length)
         .map((option) => option.value)
         .filter((value) => value !== "AskUser");
 }
@@ -188,7 +925,8 @@ function channelSendTools(channels) {
  * knows what "Allow all" turns on and what is unaffected by the choice:
  *   1. Always on — auto-provisioned, NOT gated by this choice (e.g. MemoryRecall).
  *   2. Built-ins — file/shell/web tools.
- *   3. Channel tools — the send/ask tools that came with the channels you enabled,
+ *   3. App tools — safe host capabilities such as bounded run inspection.
+ *   4. Channel tools — the send/ask tools that came with the channels you enabled,
  *      plus AskUser (ask the human, any channel).
  */
 function toolSituationFraming(draft, alwaysOn) {
@@ -201,8 +939,9 @@ function toolSituationFraming(draft, alwaysOn) {
             ? `Always on (auto-provisioned, not affected by this choice): ${alwaysOnDisplay(alwaysOn).join(", ")}.`
             : "Always on (auto-provisioned): none for this setup.",
         "Built-ins: files (Read/Write/Edit/Glob/Grep), shell (Bash), web (WebFetch/WebSearch).",
+        "App tools: RunHistory (read-only evidence from completed prior runs in this conversation).",
         channelLine,
-        '"Allow all" turns on every built-in and channel tool; you can turn specific tools off later via tools.disallowedTools.',
+        '"Allow all" lets the model run shell commands, read/change files, access the web, and send through enabled channels. These actions can modify data or contact people; you can turn specific tools off later via tools.disallowedTools.',
     ].join("\n");
 }
 /**
@@ -214,10 +953,15 @@ function toolSituationFraming(draft, alwaysOn) {
 async function promptTools(draft) {
     const alwaysOn = alwaysOnTools(toWizardAnswers(draft));
     p.note(toolSituationFraming(draft, alwaysOn), "Tools");
-    const allowAll = guard(await p.confirm({
-        message: "Allow all tools? (recommended — the model can use every built-in and your channels' tools)",
+    if (selectedRuntimeModels(draft).every(hasFixedAllowAllToolPolicyRef)) {
+        draft.allowedTools = [ALLOW_ALL_TOOLS];
+        p.log.info("Direct Codex uses its native app-server tool set and cannot enforce mono-agent per-tool allowlists. Tool policy is fixed to allow-all; use Pi or Claude for a restrictive tool list.");
+        return;
+    }
+    const allowAll = await confirm({
+        message: "Allow all tools? (shell commands, file changes, web access, and enabled-channel sends)",
         initialValue: true,
-    }));
+    });
     if (allowAll) {
         draft.allowedTools = [ALLOW_ALL_TOOLS];
         return;
@@ -235,17 +979,17 @@ async function pickSpecificTools(draft) {
     const optionOrder = new Map(options.map((option, index) => [option.value, index]));
     const recommended = recommendedToolSelection(toWizardAnswers(draft));
     for (;;) {
-        const tools = guard(await p.multiselect({
+        const tools = await multiselect({
             message: "Which tools may the model call?",
             options,
             initialValues: [...recommended],
             required: false,
-        }));
+        });
         if (tools.length === 0) {
-            const proceed = guard(await p.confirm({
+            const proceed = await confirm({
                 message: "⚠ Zero tools selected — the agent will be chat-only (cannot read files, run commands, or send proactively). Continue?",
                 initialValue: false,
-            }));
+            });
             if (!proceed) {
                 continue;
             }
@@ -254,66 +998,315 @@ async function pickSpecificTools(draft) {
         return;
     }
 }
-/**
- * Render the compact plan summary and ask for the single write-time confirmation.
- * Provider modules are implementation detail (auto-added for local models), so
- * they are excluded from the user-facing capabilities line. A "no" cancels.
- */
-async function confirmSummary(draft, ctx) {
-    if ([draft.model, ...draft.fallbackModels].some((model) => LOCAL_PROVIDER_MODEL.test(model))) {
-        p.note("A matching local provider block is added automatically.\nThe first turn may be slow while the model loads.", "Local model");
-    }
+async function confirmSummary(draft, ctx, options) {
     const answers = toWizardAnswers(draft);
-    const plan = composeWizardPlan(answers, {
-        dirBasename: basename(ctx.cwd),
-        skillsRootExists: await pathExists(join(ctx.cwd, "skills")),
-    });
+    const plan = await composePlanForCwd(answers, ctx.cwd);
+    const setupModelRefs = referencedSetupModelRefs(plan);
+    const existingSetupModelRefs = options === undefined
+        ? undefined
+        : referencedSetupModelRefs(await composePlanForCwd(options.existing.answers, ctx.cwd));
+    const preserveProviderSetup = options !== undefined
+        && existingSetupModelRefs !== undefined
+        && sameOrderedValues(setupModelRefs, existingSetupModelRefs);
+    const preliminarySetupPlan = providerSetupPlan(plan, ctx, draft.credentialStates);
+    // Resolve destinations before the final review; collect masked values only
+    // after the operator chooses Create.
+    const piApiKeyPersistenceByProvider = preserveProviderSetup
+        ? { ...options.existing.piApiKeyPersistenceByProvider }
+        : await selectPiApiKeyPersistence(preliminarySetupPlan, options?.existing.piApiKeyPersistenceByProvider);
+    const setupPlan = providerSetupPlan(plan, ctx, draft.credentialStates, piApiKeyPersistenceByProvider);
+    if (setupModelRefs.some((model) => /^pi:(?:ollama|lmstudio):/u.test(model))) {
+        p.note("Local runtime or memory services are checked before readiness. The first load may take longer while models start.", "Local dependencies");
+    }
     const capabilities = plan.selectedModules
         .filter((module) => module.kind !== "provider")
         .map((module) => module.title);
-    const writes = ["mono-agent.config.json", "IDENTITY.md"];
+    const creates = ["mono-agent.config.json", "IDENTITY.md", ".mono-agent/artifacts/", ".mono-agent/workspace/"];
     if (plan.envExample !== undefined) {
-        writes.push(".env.example");
+        creates.push(".env.example (placeholders only)");
     }
     for (const file of plan.files) {
-        writes.push(file.path);
+        creates.push(file.path);
+    }
+    const providerEnvironmentNames = setupPlan.actions
+        .filter(isProviderSetupPiApiKeyAction)
+        .filter((action) => action.persistence === "environment")
+        .map((action) => action.envVar);
+    const moduleSecretsToCollect = plan.secrets
+        .filter((secret) => secret.required && !hasNonEmptyValue(ctx.persistedEnv?.[secret.envVar]))
+        .map((secret) => secret.envVar);
+    const secrets = [...new Set([
+            ...moduleSecretsToCollect,
+            ...providerEnvironmentNames,
+        ])];
+    const hardenExistingDotenv = hasSensitivePersistedEnvironmentValue(ctx.persistedEnv ?? {});
+    const mutableSecretFiles = [];
+    if (secrets.length > 0 || hardenExistingDotenv) {
+        mutableSecretFiles.push(secrets.length > 0 ? ".env (owner-only secret merge)" : ".env (owner-only permission hardening)", ".gitignore (ensure /.env is ignored)");
     }
-    const secrets = plan.secrets.map((secret) => secret.envVar);
     const toolsLine = isAllowAllTools(draft.allowedTools)
         ? "all tools"
         : draft.allowedTools.length > 0
             ? draft.allowedTools.join(", ")
             : "none (chat-only)";
     const alwaysOn = alwaysOnTools(answers);
+    const runtimeRoutes = [
+        { model: draft.model, effort: draft.effort },
+        ...draft.fallbacks,
+    ];
+    const potentiallyBilledCalls = runtimeRoutes.filter((route) => modelRefMayBill(route.model)).length;
+    const providerActions = [
+        ...setupPlan.detectedModelRefs.map((modelRef) => `${modelRef}: credential/sign-in detected; skip initial auth and verify with the live readiness call`),
+        ...setupPlan.actions.map((action) => {
+            if (isProviderSetupPiApiKeyAction(action)) {
+                return action.persistence === "environment"
+                    ? `${action.label}: read ${action.envVar} from owner-only .env; do not write Pi auth.json`
+                    : `${action.label}: save credential to owner-only ${action.piAuthPath}; do not copy it to .env`;
+            }
+            return `${action.label}: check the current credential/service state first; if needed run ${providerSetupActionCommandLine(action)} (cwd: ${action.cwd})`;
+        }),
+        ...(draft.sandbox
+            ? ["Managed SRT: install the pinned tool in the private user cache and run the functional fail-closed preflight"]
+            : []),
+    ];
     const lines = [
-        `Model:        ${draft.model}${draft.fallbackModels.length > 0 ? `  (fallbacks: ${draft.fallbackModels.join(", ")})` : ""}`,
-        `Effort:       ${draft.effort ?? "default"}`,
+        `Agent:        ${draft.name}`,
+        `Purpose:      ${draft.purpose}`,
+        "Routes:",
+        ...runtimeRoutes.map((route, index) => `  ${index === 0 ? "Primary" : `Fallback ${index}`}: ${route.model} [${route.effort ?? "provider default"}]`),
         `Capabilities: ${capabilities.length > 0 ? capabilities.join(", ") : "none"}`,
         `Tools:        ${toolsLine}`,
+        `Route safety: ${draft.routeSafety}`,
+        ...(draft.routeSafety === "per-route-native" || !isMixedRouteChain(runtimeRoutes.map((route) => route.model))
+            ? [formatRouteSafetyMatrix({ model: draft.model, ...(draft.effort === undefined ? {} : { effort: draft.effort }) }, draft.fallbacks, draft.sandbox)]
+            : [
+                "Uniform contract: every route must satisfy the same mono-agent tool/sandbox capabilities; an incompatible route is rejected or skipped, never silently weakened.",
+            ]),
         ...(alwaysOn.length > 0 ? [`Always on:    ${alwaysOnDisplay(alwaysOn).join(", ")}`] : []),
-        `Writes:       ${writes.join(", ")}`,
-        `Secrets:      ${secrets.length > 0 ? `${secrets.join(", ")} → .env.example` : "none"}`,
+        `Readiness:    ${runtimeRoutes.length} real model call(s), one per selected route; ${potentiallyBilledCalls} potentially billed`,
+        `Verify refs:  ${setupModelRefs.join(", ")}`,
+        `Provider actions: ${providerActions.length > 0 ? providerActions.join("\n  ") : "none"}`,
+        `Creates if missing (preserves existing scaffold paths): ${creates.join(", ")}`,
+        ...(mutableSecretFiles.length > 0
+            ? [`May create or update: ${mutableSecretFiles.join(", ")}`]
+            : []),
+        `Secret persistence: ${secrets.length > 0
+            ? `${secrets.join(", ")} -> owner-only .env merge (values hidden)`
+            : hardenExistingDotenv
+                ? "existing sensitive .env -> owner-only permission/ignore hardening (values unchanged)"
+                : "none"}`,
+        ...(Object.values(piApiKeyPersistenceByProvider).some((value) => value === "secure-store")
+            ? ["Pi credential persistence: selected keys -> owner-only Pi auth.json (values hidden; not copied to .env)"]
+            : []),
+        ...(secrets.length > 0 || hardenExistingDotenv
+            ? [`Secret files: .env (${secrets.length > 0 ? "owner-only merge" : "owner-only hardening"}), .gitignore (ensure /.env is ignored)`]
+            : []),
     ];
-    p.note(lines.join("\n"), "Review");
-    const setupPlan = planProviderSetup({
-        modelRefs: [answers.model, ...answers.fallbackModels],
+    p.note(lines.join("\n"), "Creation review");
+    const choice = await select({
+        message: `Create “${draft.name}”?`,
+        options: creationReviewOptions({
+            setupRequired: (preserveProviderSetup
+                ? options.existing.runProviderSetup
+                : setupPlan.actions.length > 0) || draft.sandbox,
+        }),
+        initialValue: "create",
+    });
+    if (choice === "cancel") {
+        throw new WizardCancelled();
+    }
+    if (choice === "edit") {
+        try {
+            const step = await select({
+                message: "What would you like to edit?",
+                options: [
+                    { value: "0", label: "Agent name and purpose" },
+                    { value: "1", label: "Models and efforts" },
+                    { value: "2", label: "Channels" },
+                    { value: "3", label: "Memory" },
+                    { value: "4", label: "Capability details" },
+                    { value: "5", label: "Tools" },
+                    { value: "6", label: "Route safety and sandbox" },
+                    { value: "7", label: "Observability" },
+                    { value: "8", label: "Return to review" },
+                ],
+                initialValue: "1",
+            });
+            return { status: "edit", step: Number(step) };
+        }
+        catch (error) {
+            if (error instanceof WizardBack) {
+                if (options !== undefined)
+                    throw error;
+                return { status: "edit", step: 8 };
+            }
+            throw error;
+        }
+    }
+    if (preserveProviderSetup) {
+        return {
+            status: "create",
+            providerSetup: {
+                runProviderSetup: options.existing.runProviderSetup,
+                providerSetupSecrets: { ...options.existing.providerSetupSecrets },
+                providerEnvironmentSecrets: { ...options.existing.providerEnvironmentSecrets },
+                piApiKeyPersistenceByProvider: { ...options.existing.piApiKeyPersistenceByProvider },
+            },
+        };
+    }
+    let providerSetup;
+    try {
+        providerSetup = await collectProviderSetup(setupPlan, setupPlan.actions.length > 0, piApiKeyPersistenceByProvider, options?.existing.providerSetupSecrets, options?.existing.providerEnvironmentSecrets);
+    }
+    catch (error) {
+        if (error instanceof WizardBack) {
+            if (options !== undefined)
+                throw error;
+            return { status: "edit", step: 8 };
+        }
+        throw error;
+    }
+    return {
+        status: "create",
+        providerSetup,
+    };
+}
+function selectedRuntimeModels(draft) {
+    return [draft.model, ...draft.fallbacks.map((fallback) => fallback.model)];
+}
+function sameOrderedValues(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function hasFixedAllowAllToolPolicyRef(model) {
+    return isDirectCodexRef(model) || isDirectOpenCodeRef(model);
+}
+function hasExactAllowAllTools(draft) {
+    return draft.allowedTools.length === 1 && draft.allowedTools[0] === ALLOW_ALL_TOOLS;
+}
+function hasInvalidUniformManagedSrtChain(draft) {
+    if (draft.routeSafety !== "uniform" || !draft.sandbox)
+        return false;
+    const models = selectedRuntimeModels(draft);
+    return isMixedRouteChain(models)
+        && models.some((model) => model.startsWith("pi:"))
+        && models.some((model) => !model.startsWith("pi:"));
+}
+function isDirectCodexRef(model) {
+    return model.startsWith("codex:");
+}
+function isDirectOpenCodeRef(model) {
+    return model.startsWith("opencode:");
+}
+function runtimeFamily(model) {
+    return model.split(":", 1)[0] ?? model;
+}
+function modelRefMayBill(model) {
+    return !/^pi:(?:ollama|lmstudio):/u.test(model);
+}
+/** Build a plan using the destination-derived context for honest review/setup. */
+async function composePlanForCwd(answers, cwd) {
+    return composeWizardPlan(answers, {
+        dirBasename: basename(cwd),
+        skillsRootExists: await pathExists(join(cwd, "skills")),
+    });
+}
+/** Offer auth/preflight for every runtime and hidden memory model dependency. */
+async function promptProviderSetup(plan, ctx, credentialStates = {}) {
+    const modelRefs = referencedSetupModelRefs(plan);
+    p.note(modelRefs.join("\n"), "Models and services to verify");
+    const preliminarySetupPlan = providerSetupPlan(plan, ctx, credentialStates);
+    if (preliminarySetupPlan.actions.length === 0) {
+        return { runProviderSetup: false, providerSetupSecrets: {}, providerEnvironmentSecrets: {}, piApiKeyPersistenceByProvider: {} };
+    }
+    const piApiKeyPersistenceByProvider = await selectPiApiKeyPersistence(preliminarySetupPlan);
+    const setupPlan = providerSetupPlan(plan, ctx, credentialStates, piApiKeyPersistenceByProvider);
+    p.note(setupPlan.actions
+        .map(providerSetupActionReviewLine)
+        .join("\n"), "Provider setup");
+    const runProviderSetup = await confirm({
+        message: setupPlan.actions.some((action) => action.id.startsWith("pi-login:"))
+            ? "Run provider auth/preflight now? (detected credentials are reused and verified by live readiness; Pi OAuth may update the auth store)"
+            : "Run provider auth/preflight now? (detected credentials are reused and verified by live readiness)",
+        initialValue: false,
+    });
+    return collectProviderSetup(setupPlan, runProviderSetup, piApiKeyPersistenceByProvider);
+}
+function providerSetupPlan(plan, ctx, credentialStates = {}, piApiKeyPersistenceByProvider = {}) {
+    const modelRefs = referencedSetupModelRefs(plan);
+    const configuredPiAuthPath = typeof plan.configJson.providers?.piAuthPath === "string"
+        ? plan.configJson.providers.piAuthPath
+        : undefined;
+    const piAuthPath = ctx.piAuthPath ?? configuredPiAuthPath;
+    return planProviderSetup({
+        modelRefs,
         cwd: ctx.cwd,
-        ...(typeof plan.configJson.providers?.piAuthPath === "string" ? { piAuthPath: plan.configJson.providers.piAuthPath } : {}),
+        credentialStates,
+        piApiKeyPersistenceByProvider,
+        ...(piAuthPath === undefined ? {} : { piAuthPath }),
     });
-    let runProviderSetup = false;
-    if (setupPlan.actions.length > 0) {
-        p.note(setupPlan.actions
-            .map((action) => `${action.label}: ${providerSetupActionCommandLine(action)} (cwd: ${action.cwd})`)
-            .join("\n"), "Provider setup");
-        runProviderSetup = guard(await p.confirm({
-            message: "Run provider auth/preflight before writing files?",
-            initialValue: false,
-        }));
+}
+async function collectProviderSetup(setupPlan, runProviderSetup, selectedPersistence, existingSetupSecrets = {}, existingEnvironmentSecrets = {}) {
+    const providerSetupSecrets = {};
+    const providerEnvironmentSecrets = {};
+    if (!runProviderSetup) {
+        return {
+            runProviderSetup: false,
+            providerSetupSecrets,
+            providerEnvironmentSecrets,
+            piApiKeyPersistenceByProvider: { ...(selectedPersistence ?? {}) },
+        };
     }
-    if (!guard(await p.confirm({ message: "Write these files?", initialValue: true }))) {
-        throw new WizardCancelled();
+    const piApiKeyPersistenceByProvider = { ...(selectedPersistence ?? {}) };
+    for (const action of setupPlan.actions) {
+        if (!isProviderSetupPiApiKeyAction(action))
+            continue;
+        if (action.persistence === "environment") {
+            if (hasNonEmptyValue(existingEnvironmentSecrets[action.envVar])) {
+                providerEnvironmentSecrets[action.envVar] = existingEnvironmentSecrets[action.envVar];
+                continue;
+            }
+            providerEnvironmentSecrets[action.envVar] = await passwordPrompt({
+                message: `${action.label} (${action.envVar}, saved to owner-only .env)`,
+                validate: (value) => (value ?? "").trim().length === 0 ? "API key is required." : undefined,
+                clearOnError: true,
+            });
+            continue;
+        }
+        if (hasNonEmptyValue(existingSetupSecrets[action.id])) {
+            providerSetupSecrets[action.id] = existingSetupSecrets[action.id];
+            continue;
+        }
+        providerSetupSecrets[action.id] = await passwordPrompt({
+            message: `${action.label} (${action.envVar})`,
+            validate: (value) => (value ?? "").trim().length === 0 ? "API key is required." : undefined,
+            clearOnError: true,
+        });
+    }
+    return { runProviderSetup, providerSetupSecrets, providerEnvironmentSecrets, piApiKeyPersistenceByProvider };
+}
+async function selectPiApiKeyPersistence(setupPlan, existing = {}) {
+    const selected = {};
+    for (const action of setupPlan.actions) {
+        if (!isProviderSetupPiApiKeyAction(action))
+            continue;
+        const label = action.label.replace(/ \((?:secure store|environment)\)$/u, "");
+        const existingSelection = existing[action.provider];
+        selected[action.provider] = existingSelection ?? await select({
+            message: `Where should ${label} store ${action.envVar}?`,
+            options: [
+                { value: "secure-store", label: "Store securely in Pi auth.json", hint: "owner-only Pi credential store" },
+                { value: "environment", label: "Use environment variable", hint: `owner-only .env (${action.envVar})` },
+            ],
+            initialValue: "secure-store",
+        });
+    }
+    return selected;
+}
+function providerSetupActionReviewLine(action) {
+    if (isProviderSetupPiApiKeyAction(action) && action.persistence === "environment") {
+        return `${action.label}: read ${action.envVar} from the durable agent environment; Pi auth.json remains unchanged (cwd: ${action.cwd})`;
     }
-    return runProviderSetup;
+    return `${action.label}: ${providerSetupActionCommandLine(action)} (cwd: ${action.cwd})`;
 }
 /** Seed a mutable draft from immutable answers (defaults or a preset). */
 function draftFrom(answers) {
@@ -328,9 +1321,13 @@ function draftFrom(answers) {
         moduleInputs[moduleId] = bag;
     }
     return {
+        name: answers.name?.trim() || "Mono Agent",
+        purpose: answers.purpose?.trim() || "Help the operator work effectively in this folder.",
         model: answers.model,
-        fallbackModels: [...answers.fallbackModels],
+        fallbacks: effectiveFallbacks(answers).map((fallback) => ({ ...fallback })),
         effort: answers.effort,
+        routeSafety: answers.routeSafety,
+        credentialStates: {},
         channels: [...answers.channels],
         memory: answers.memory,
         sandbox: answers.sandbox,
@@ -345,10 +1342,16 @@ function draftFrom(answers) {
  * `undefined`).
  */
 function toWizardAnswers(draft) {
+    for (const modelRef of selectedRuntimeModels(draft)) {
+        assertConcreteWizardModelRef(modelRef);
+    }
     return {
+        name: draft.name,
+        purpose: draft.purpose,
         model: draft.model,
-        fallbackModels: [...draft.fallbackModels],
+        fallbacks: draft.fallbacks.map((fallback) => ({ ...fallback })),
         ...(draft.effort === undefined ? {} : { effort: draft.effort }),
+        routeSafety: draft.routeSafety,
         channels: [...draft.channels],
         ...(draft.memory === undefined ? {} : { memory: draft.memory }),
         sandbox: draft.sandbox,
@@ -357,9 +1360,22 @@ function toWizardAnswers(draft) {
         moduleInputs: draft.moduleInputs,
     };
 }
-/** Split a comma-separated string into trimmed, non-empty entries. */
-function splitCsv(value) {
-    return value.split(",").map((entry) => entry.trim()).filter(Boolean);
+function cloneDraft(draft) {
+    return {
+        ...draft,
+        fallbacks: draft.fallbacks.map((fallback) => ({ ...fallback })),
+        channels: [...draft.channels],
+        allowedTools: [...draft.allowedTools],
+        moduleInputs: Object.fromEntries(Object.entries(draft.moduleInputs).map(([id, values]) => [id, { ...values }])),
+    };
+}
+function restoreDraft(target, source) {
+    Object.assign(target, cloneDraft(source));
+}
+/** A second Esc/Ctrl-C while this default-No prompt is open exits cleanly. */
+async function confirmExitSetup() {
+    const answer = await p.confirm({ message: "Exit setup?", initialValue: false });
+    return p.isCancel(answer) ? true : answer;
 }
 /** True when `path` exists (a local mirror of the CLI's private helper). */
 async function pathExists(path) {