aiden-runtime 4.0.1 → 4.1.0

package/dist/cli/v4/setupWizard.js

@@ -42,41 +42,91 @@ const keyValidator_1 = require("./keyValidator");
 const providerAuth_1 = require("../../core/v4/auth/providerAuth");
 const loadProvider_1 = require("./auth/loadProvider");
 const box_1 = require("./box");
+// Phase 30.2.1 — provider order optimised for new-user time-to-first-chat.
+// Free providers first (Groq → Gemini → OpenRouter → NVIDIA → Ollama),
+// paid providers next (Anthropic, OpenAI, Together), subscription
+// sign-ins last. The legacy entries (deepseek, mistral, zai, kimi,
+// minimax, huggingface, vercel, nous, custom) trail the top 10 — still
+// pickable for power users, never the default.
+//
+// Plain-English descriptions per spec — "TPM cap" replaced with
+// "limited messages per minute", "tier 1 paid" with "best for complex
+// tasks", etc. Subsequent prompts use `shortLabel` (e.g. just "Groq")
+// to avoid restating the description.
 exports.PROVIDERS = [
-    { id: 'claude-pro', label: 'Use my Claude Pro/Max subscription', kind: 'pro' },
-    { id: 'chatgpt-plus', label: 'Use my ChatGPT Plus subscription', kind: 'pro' },
+    // ── Free tier / no-cost ──
     {
-        id: 'nous',
-        label: 'Nous Portal (subscription, zero-config)',
-        kind: 'subscription',
-        defaultModel: 'hermes-3-llama-3.1-405b',
+        id: 'groq',
+        shortLabel: 'Groq',
+        label: 'Groq — free, fast, limited messages per minute',
+        kind: 'key',
+        envVar: 'GROQ_API_KEY',
+        keyUrl: 'https://console.groq.com/keys',
+        defaultModel: 'llama-3.3-70b-versatile',
+        models: ['llama-3.3-70b-versatile', 'llama-3.1-8b-instant', 'mixtral-8x7b-32768'],
+    },
+    {
+        id: 'gemini',
+        shortLabel: 'Google Gemini',
+        label: 'Google Gemini — free, generous limits',
+        kind: 'key',
+        envVar: 'GEMINI_API_KEY',
+        keyUrl: 'https://aistudio.google.com/apikey',
+        defaultModel: 'gemini-2.0-flash',
+    },
+    {
+        id: 'openrouter',
+        shortLabel: 'OpenRouter',
+        label: 'OpenRouter — free credits, then paid',
+        kind: 'key',
+        envVar: 'OPENROUTER_API_KEY',
+        keyUrl: 'https://openrouter.ai/keys',
+        defaultModel: 'anthropic/claude-opus-4',
+    },
+    {
+        id: 'nvidia',
+        shortLabel: 'NVIDIA NIM',
+        label: 'NVIDIA NIM — free, but rate-limited',
+        kind: 'key',
+        envVar: 'NVIDIA_API_KEY',
+        keyUrl: 'https://build.nvidia.com',
+        defaultModel: 'meta/llama-3.3-70b-instruct',
     },
+    {
+        id: 'ollama',
+        shortLabel: 'Ollama',
+        label: 'Ollama — fully offline, no key needed (requires Ollama install)',
+        kind: 'local',
+        defaultModel: 'llama3.1:8b',
+    },
+    // ── Paid (best quality) ──
     {
         id: 'anthropic',
-        label: 'Anthropic API key',
+        shortLabel: 'Anthropic',
+        label: 'Anthropic — paid, best for complex tasks',
         kind: 'key',
         envVar: 'ANTHROPIC_API_KEY',
+        keyUrl: 'https://console.anthropic.com/settings/keys',
         defaultModel: 'claude-opus-4-7',
         models: ['claude-opus-4-7', 'claude-sonnet-4-5', 'claude-haiku-4-5'],
     },
     {
         id: 'openai',
-        label: 'OpenAI API key',
+        shortLabel: 'OpenAI',
+        label: 'OpenAI — paid, GPT models',
         kind: 'key',
         envVar: 'OPENAI_API_KEY',
+        keyUrl: 'https://platform.openai.com/api-keys',
         defaultModel: 'gpt-5',
         models: ['gpt-5', 'gpt-4o', 'gpt-4o-mini'],
     },
     {
         id: 'together',
-        // Phase 16f: Together + Qwen3 is the recommended primary — strong tool
-        // calling, $0.20/M throughput tier, 131k context. Free $5-10 credit on
-        // signup covers a few hundred turns. Replaces Groq free tier as the
-        // first recommendation after the user's Groq slots kept hammering
-        // simultaneous 429s within 2 turns of normal use.
-        label: 'Together AI (recommended — Qwen3-235B, paid throughput tier)',
+        shortLabel: 'Together AI',
+        label: 'Together AI — paid, fast & reliable',
         kind: 'key',
         envVar: 'TOGETHER_API_KEY',
+        keyUrl: 'https://api.together.xyz/settings/api-keys',
         defaultModel: 'Qwen/Qwen3-235B-A22B-Instruct-2507-tput',
         models: [
             'Qwen/Qwen3-235B-A22B-Instruct-2507-tput',
@@ -84,74 +134,91 @@ exports.PROVIDERS = [
             'deepseek-ai/DeepSeek-V3',
         ],
     },
+    // ── Subscription sign-ins ──
     {
-        id: 'groq',
-        label: 'Groq (free tier — fast but tight TPM cap)',
-        kind: 'key',
-        envVar: 'GROQ_API_KEY',
-        defaultModel: 'llama-3.3-70b-versatile',
-        models: ['llama-3.3-70b-versatile', 'llama-3.1-8b-instant', 'mixtral-8x7b-32768'],
+        id: 'claude-pro',
+        shortLabel: 'Claude Pro',
+        label: 'Claude Pro — use your existing Claude subscription',
+        kind: 'pro',
     },
     {
-        id: 'openrouter',
-        label: 'OpenRouter (200+ models)',
-        kind: 'key',
-        envVar: 'OPENROUTER_API_KEY',
-        defaultModel: 'anthropic/claude-opus-4',
-    },
-    {
-        id: 'gemini',
-        label: 'Google Gemini (free tier)',
-        kind: 'key',
-        envVar: 'GEMINI_API_KEY',
-        defaultModel: 'gemini-2.0-flash',
+        id: 'chatgpt-plus',
+        shortLabel: 'ChatGPT Plus',
+        label: 'ChatGPT Plus — use your existing ChatGPT subscription',
+        kind: 'pro',
     },
+    // ── Legacy / power-user entries (kept to preserve env-var detection
+    // for users who already configured these out-of-band) ──
     {
         id: 'deepseek',
-        label: 'DeepSeek',
+        shortLabel: 'DeepSeek',
+        label: 'DeepSeek — paid',
         kind: 'key',
         envVar: 'DEEPSEEK_API_KEY',
         defaultModel: 'deepseek-chat',
     },
     {
         id: 'mistral',
-        label: 'Mistral',
+        shortLabel: 'Mistral',
+        label: 'Mistral — paid',
         kind: 'key',
         envVar: 'MISTRAL_API_KEY',
         defaultModel: 'mistral-large-latest',
     },
-    { id: 'zai', label: 'Z.AI / GLM', kind: 'key', envVar: 'ZAI_API_KEY', defaultModel: 'glm-4-plus' },
+    {
+        id: 'zai',
+        shortLabel: 'Z.AI',
+        label: 'Z.AI / GLM — paid',
+        kind: 'key',
+        envVar: 'ZAI_API_KEY',
+        defaultModel: 'glm-4-plus',
+    },
     {
         id: 'kimi',
-        label: 'Kimi / Moonshot',
+        shortLabel: 'Kimi',
+        label: 'Kimi / Moonshot — paid',
         kind: 'key',
         envVar: 'MOONSHOT_API_KEY',
         defaultModel: 'moonshot-v1-128k',
     },
-    { id: 'minimax', label: 'MiniMax', kind: 'key', envVar: 'MINIMAX_API_KEY', defaultModel: 'abab6.5s-chat' },
     {
-        id: 'nvidia',
-        label: 'NVIDIA NIM (free tier)',
+        id: 'minimax',
+        shortLabel: 'MiniMax',
+        label: 'MiniMax — paid',
         kind: 'key',
-        envVar: 'NVIDIA_API_KEY',
-        defaultModel: 'meta/llama-3.3-70b-instruct',
+        envVar: 'MINIMAX_API_KEY',
+        defaultModel: 'abab6.5s-chat',
     },
     {
         id: 'huggingface',
-        label: 'Hugging Face (free tier)',
+        shortLabel: 'Hugging Face',
+        label: 'Hugging Face — free tier',
         kind: 'key',
         envVar: 'HF_API_KEY',
         defaultModel: 'meta-llama/Llama-3.3-70B-Instruct',
     },
     {
         id: 'vercel',
-        label: 'Vercel AI Gateway',
+        shortLabel: 'Vercel AI Gateway',
+        label: 'Vercel AI Gateway — paid',
         kind: 'key',
         envVar: 'VERCEL_AI_GATEWAY_KEY',
         defaultModel: 'anthropic/claude-opus-4',
     },
-    { id: 'custom', label: 'Custom OpenAI-compatible endpoint', kind: 'custom', envVar: 'CUSTOM_API_KEY' },
-    { id: 'ollama', label: 'Local (Ollama, no internet)', kind: 'local', defaultModel: 'llama3.1:8b' },
+    {
+        id: 'nous',
+        shortLabel: 'Nous Portal',
+        label: 'Nous Portal — subscription',
+        kind: 'subscription',
+        defaultModel: 'hermes-3-llama-3.1-405b',
+    },
+    {
+        id: 'custom',
+        shortLabel: 'custom endpoint',
+        label: 'Custom OpenAI-compatible endpoint',
+        kind: 'custom',
+        envVar: 'CUSTOM_API_KEY',
+    },
 ];
 /** Lazy-load @inquirer/prompts so unit tests don't need a TTY. */
 async function defaultPrompts() {
@@ -345,6 +412,66 @@ async function probeOllama(opts) {
         clearTimeout(timer);
     }
 }
+/**
+ * Phase 30.2.1 — open `url` in the user's default browser. Used by the
+ * recovery menu's "Get a key from <provider URL>" branch. Best-effort
+ * — failure is non-fatal (we still print the URL so the user can copy
+ * it manually).
+ */
+async function openUrlInBrowser(url, display) {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { exec } = require('node:child_process');
+    const platform = process.platform;
+    let cmd;
+    if (platform === 'win32') {
+        // `start ""` swallows the URL into the title arg; double-empty-arg
+        // form keeps cmd.exe happy and leaves the URL as the actual target.
+        cmd = `cmd /c start "" "${url}"`;
+    }
+    else if (platform === 'darwin') {
+        cmd = `open "${url}"`;
+    }
+    else {
+        cmd = `xdg-open "${url}"`;
+    }
+    await new Promise((resolve) => {
+        exec(cmd, (err) => {
+            if (err) {
+                display.write(`${kleur_1.default.dim(`(could not auto-open browser — visit ${url} manually)`)}\n`);
+            }
+            resolve();
+        });
+    });
+}
+async function runRecoveryMenu(provider, prompts, display) {
+    const choices = [
+        'Try a different provider',
+        provider.keyUrl
+            ? `Get a key from ${provider.keyUrl}`
+            : 'Get a key from the provider website (URL printed when picked)',
+        'Save without validation (writes config; key untested)',
+        'Skip — explore Aiden first (no chat, but / commands work)',
+        'Exit (try again later)',
+    ];
+    const idx = await prompts.choose('What would you like to do?', choices, 
+    /* default= */ 1);
+    switch (idx) {
+        case 1: return { kind: 'try-different' };
+        case 2: {
+            // Provider may not carry a keyUrl (legacy entries). Fall through
+            // to "try-different" so the user isn't stuck staring at nothing.
+            if (!provider.keyUrl) {
+                display.write(`${kleur_1.default.dim(`(no key URL on file for ${provider.shortLabel}; pick a different provider.)`)}\n`);
+                return { kind: 'try-different' };
+            }
+            return { kind: 'get-key', url: provider.keyUrl };
+        }
+        case 3: return { kind: 'save-anyway' };
+        case 4: return { kind: 'skip' };
+        case 5: return { kind: 'exit' };
+        default: return { kind: 'exit' };
+    }
+}
 /**
  * Append (or overwrite) an entry in `.env`. Existing entries with the same
  * key are replaced. New entries are appended to the bottom. Keys are
@@ -381,59 +508,283 @@ async function runSetupWizard(opts = {}) {
     const prompts = opts.prompts ?? (await defaultPrompts());
     const fetchImpl = opts.fetchImpl ?? fetch;
     if (!opts.force && !(await isFreshInstall(paths))) {
-        return { ran: false, skipReason: 'config.yaml already exists; pass force=true to re-run' };
+        // Existing config — wizard wasn't needed. Treat as already-configured
+        // so the boot path proceeds to resolver (which will surface real
+        // credential issues with its own error contract).
+        return {
+            status: 'configured',
+            ran: false,
+            skipReason: 'config.yaml already exists; pass force=true to re-run',
+        };
     }
     await (0, paths_1.ensureAidenDirsExist)(paths);
     display.printBanner();
     display.write('\nWelcome — let\'s pick a provider.\n');
-    display.write(`${kleur_1.default.dim('(Press Enter to accept the recommended Together AI option — fastest path to a working REPL.)')}\n\n`);
-    // Step 1: provider selection. Phase 22 Task 1: pre-select Together as
-    // the recommended default. Together's signup is fast, the free credit
-    // covers a few hundred turns, and Qwen3-235B has strong tool calling —
-    // optimises for time-to-first-tool-call.
-    const togetherDefaultIdx = exports.PROVIDERS.findIndex((p) => p.id === 'together') + 1;
-    const providerIndex = await prompts.choose('Which provider would you like to use?', exports.PROVIDERS.map((p) => p.label), togetherDefaultIdx > 0 ? togetherDefaultIdx : undefined);
-    const provider = exports.PROVIDERS[providerIndex - 1];
-    if (!provider)
-        throw new Error(`invalid provider selection: ${providerIndex}`);
-    // Phase 18: real OAuth flow for kind: 'pro' providers (claude-pro,
-    // chatgpt-plus). The flow is the same one /auth login uses (Task 5);
-    // single entry point.
-    if (provider.kind === 'pro') {
-        // 1-line explainer up-front so the user knows what they're agreeing to.
-        const explainer = PRO_EXPLAINERS[provider.id] ??
-            'This connects your subscription via OAuth. No API key needed.';
-        display.write(`\n${explainer}\n`);
-        // Phase 18.1: honest beta framing per diagnostic 292c7cd. Some
-        // upstream errors are account-state-specific and have no client-side
-        // fix. We show this every time so a user who hits a wall has clear
-        // remediation: rerun setup with an API-key provider.
-        display.write('Note: OAuth flows are beta in v4.0. If signin fails, rerun `aiden setup` and pick an API-key provider instead.\n\n');
-        const proceed = await prompts.confirm(`Continue with ${provider.label}?`, true);
-        if (!proceed) {
-            display.write('\nSkipped. Run `aiden setup` again to retry, or pick a different provider.\n');
-            return { ran: false, skipReason: 'oauth-skipped' };
-        }
-        let oauthProvider;
+    display.write(`${kleur_1.default.dim('(Press Enter to accept Groq — free + fastest setup.)')}\n\n`);
+    // Phase 30.2.1 — Groq is the new recommended default for first-time
+    // users: free tier, fastest signup, and avoids the surprise charge
+    // path of paid providers. Together AI moved to position [8] paid.
+    const groqDefaultIdx = exports.PROVIDERS.findIndex((p) => p.id === 'groq') + 1;
+    // outer: provider-pick loop. Recovery option [1] "Try a different
+    // provider" jumps back to this prompt without losing progress on
+    // global state (display, paths, ensureAidenDirsExist already ran).
+    // Try/catch wraps inquirer to convert Ctrl+C ("User force closed
+    // the prompt") into the same "skipped" exit state as recovery [4]
+    // — the user clearly didn't want to finish, but we still want them
+    // to land in REPL "explore mode" rather than crash.
+    // eslint-disable-next-line no-constant-condition
+    outer: while (true) {
+        let providerIndex;
         try {
-            oauthProvider = await (0, loadProvider_1.loadOAuthProvider)(provider.id);
+            providerIndex = await prompts.choose('Which provider would you like to use?', exports.PROVIDERS.map((p) => p.label), groqDefaultIdx > 0 ? groqDefaultIdx : undefined);
         }
         catch (err) {
-            display.write(display.error(`Could not load OAuth plugin for ${provider.label}: ${err.message}`));
-            return { ran: false, skipReason: 'oauth-plugin-missing' };
+            const msg = err?.message ?? '';
+            if (/force closed|cancel/i.test(msg)) {
+                display.write('\nWizard cancelled — entering explore mode.\n');
+                return {
+                    status: 'skipped',
+                    ran: false,
+                    skipReason: 'cancelled-at-provider-pick',
+                };
+            }
+            throw err;
         }
-        const ua = wizardUserAgent(prompts, display);
-        const runtime = new providerAuth_1.OAuthProviderRuntime(oauthProvider, paths);
-        let tokens;
-        try {
-            tokens = await runtime.login(ua);
+        const provider = exports.PROVIDERS[providerIndex - 1];
+        if (!provider)
+            throw new Error(`invalid provider selection: ${providerIndex}`);
+        // Phase 18: real OAuth flow for kind: 'pro' providers (claude-pro,
+        // chatgpt-plus). The flow is the same one /auth login uses (Task 5);
+        // single entry point.
+        if (provider.kind === 'pro') {
+            // 1-line explainer up-front so the user knows what they're agreeing to.
+            const explainer = PRO_EXPLAINERS[provider.id] ??
+                'This connects your subscription via OAuth. No API key needed.';
+            display.write(`\n${explainer}\n`);
+            // Phase 18.1: honest beta framing per diagnostic 292c7cd. Some
+            // upstream errors are account-state-specific and have no client-side
+            // fix. We show this every time so a user who hits a wall has clear
+            // remediation: rerun setup with an API-key provider.
+            display.write('Note: OAuth flows are beta in v4.0. If signin fails, rerun `aiden setup` and pick an API-key provider instead.\n\n');
+            const proceed = await prompts.confirm(`Continue with ${provider.shortLabel}?`, true);
+            if (!proceed) {
+                // Phase 30.2.1: don't dead-end. Loop back to provider pick so
+                // the user can choose another option without re-launching aiden.
+                display.write('\nNo problem — pick another provider.\n');
+                continue outer;
+            }
+            let oauthProvider;
+            try {
+                oauthProvider = await (0, loadProvider_1.loadOAuthProvider)(provider.id);
+            }
+            catch (err) {
+                display.write(display.error(`Could not load OAuth plugin for ${provider.shortLabel}: ${err.message}`));
+                // Plugin missing — let the user pick another provider.
+                continue outer;
+            }
+            const ua = wizardUserAgent(prompts, display);
+            const runtime = new providerAuth_1.OAuthProviderRuntime(oauthProvider, paths);
+            let tokens;
+            try {
+                tokens = await runtime.login(ua);
+            }
+            catch (err) {
+                display.write(display.error(`${provider.shortLabel} sign-in failed: ${err.message}`));
+                // OAuth failures are recoverable — loop back so the user can
+                // pick an API-key provider as a fallback.
+                continue outer;
+            }
+            // Pick a default model from the registry's known list; user can /model later.
+            const modelId = oauthProvider.defaultModels?.[0] ?? '';
+            const config = {
+                ...config_1.DEFAULT_CONFIG,
+                model: { provider: provider.id, modelId },
+                agent: { ...config_1.DEFAULT_CONFIG.agent, max_turns: config_1.DEFAULT_CONFIG.agent.max_turns },
+                display: { ...config_1.DEFAULT_CONFIG.display, skin: 'default' },
+                memory: { ...config_1.DEFAULT_CONFIG.memory },
+                providers: {
+                    ...(config_1.DEFAULT_CONFIG.providers ?? {}),
+                    // Marker for /providers + future tooling. The actual bearer
+                    // lives in tokenStore — config.yaml does NOT carry the secret.
+                    [provider.id]: { auth: 'oauth' },
+                },
+                terminal: { backend: 'auto' },
+            };
+            if (opts.smokeTest) {
+                display.write('\n✓ Smoke test complete — would have saved this config:\n');
+                display.write(`${JSON.stringify(config, null, 2)}\n`);
+                display.write(`(would have saved tokens to ${node_path_1.default.join(paths.root, 'auth', `${provider.id}.json`)})\n`);
+                return {
+                    status: 'configured',
+                    ran: false,
+                    skipReason: 'smoke-test',
+                    config,
+                    envFile: paths.envFile,
+                };
+            }
+            const cm = new config_1.ConfigManager(paths);
+            await cm.save(config);
+            // Confirmation surface — what's wired now.
+            const expIso = new Date(tokens.expiresAtMs).toISOString();
+            display.write(`\n✓ ${provider.shortLabel} authed.\n`);
+            if (tokens.account)
+                display.write(`  Account: ${tokens.account}\n`);
+            if (oauthProvider.defaultModels?.length) {
+                display.write(`  Models: ${oauthProvider.defaultModels.join(', ')}\n`);
+            }
+            display.write(`  Tokens stored at: ${node_path_1.default.join(paths.root, 'auth', `${provider.id}.json`)}\n`);
+            display.write(`  Expires: ${expIso}\n`);
+            display.write(`\nTokens encrypted with a machine-derived key. Protects against casual ` +
+                `file inspection but NOT against code execution on this machine. ` +
+                `Real OS keychain integration in v4.1.\n`);
+            printPostWizardTutorial(display, AIDEN_VERSION);
+            return { status: 'configured', ran: true, config, envFile: paths.envFile };
         }
-        catch (err) {
-            display.write(display.error(`${provider.label} sign-in failed: ${err.message}`));
-            return { ran: false, skipReason: 'oauth-failed' };
+        // Step 2: model selection. Phase 30.2.1: subsequent prompts use
+        // `shortLabel` instead of the full picker `label` to drop the
+        // parenthetical description from the wall of text.
+        let modelId = provider.defaultModel ?? '';
+        if (provider.models && provider.models.length > 1) {
+            const modelIndex = await prompts.choose(`Pick a model for ${provider.shortLabel}`, provider.models);
+            modelId = provider.models[modelIndex - 1];
+        }
+        else if (provider.kind === 'local') {
+            modelId = await prompts.input('Ollama model id', { default: provider.defaultModel ?? 'llama3.1:8b' });
+        }
+        else if (!modelId) {
+            modelId = await prompts.input('Model id', { default: '' });
+        }
+        // Step 3: credentials
+        let apiKey;
+        let baseUrl;
+        if (provider.kind === 'local') {
+            const reachable = await probeOllama({ fetchImpl });
+            if (!reachable) {
+                display.write(display.error('Ollama not reachable on http://localhost:11434', 'install from https://ollama.com, run `ollama serve`, then re-run `aiden setup`.'));
+                // Phase 30.2.1: Ollama unreachable is recoverable — loop back
+                // so the user can pick a different provider without restart.
+                continue outer;
+            }
+        }
+        else if (provider.kind === 'custom') {
+            baseUrl = await prompts.input('Base URL (e.g. https://api.example.com/v1)');
+            apiKey = await prompts.input('API key', { mask: true });
+        }
+        else if (provider.kind === 'key' || provider.kind === 'subscription') {
+            if (provider.envVar) {
+                apiKey = await prompts.input(`API key for ${provider.shortLabel}`, { mask: true });
+            }
+        }
+        // Step 3.5: validate the API key against the provider endpoint.
+        // Bypassed when smokeTest or skipValidation is set, or when there's no key
+        // to validate (Ollama, or a subscription provider without an env var).
+        const shouldValidate = !opts.smokeTest &&
+            !opts.skipValidation &&
+            typeof apiKey === 'string' &&
+            apiKey.length > 0;
+        if (shouldValidate) {
+            const validate = opts.validator ?? keyValidator_1.validateProviderKey;
+            const maxAttempts = 3;
+            let attempt = 1;
+            let validated = false;
+            let skipValidationForSave = false;
+            // Validation loop: at most 3 attempts before falling through to
+            // the recovery menu. First attempt uses the already-collected key;
+            // subsequent attempts re-prompt for a fresh key (and baseUrl, for
+            // custom). This loop labelled `validation` so the recovery flow
+            // can `continue validation` to retry with fresh attempts after
+            // option [2] "Get a key" opens the browser.
+            validation: while (attempt <= maxAttempts) {
+                const spinner = display.startSpinner(`Validating ${provider.shortLabel} API key…`);
+                let result;
+                try {
+                    result = await validate(provider.id, apiKey, baseUrl, fetchImpl);
+                }
+                finally {
+                    spinner.stop();
+                }
+                if (result.valid) {
+                    if (result.skipped) {
+                        display.write(`${kleur_1.default.dim(`Skipped validation: ${result.skipReason ?? 'no validation endpoint'}. The key will be tested on first call.`)}\n`);
+                    }
+                    else {
+                        display.write(`${kleur_1.default.green(`✓ ${provider.shortLabel} API key validated`)}\n`);
+                    }
+                    validated = true;
+                    break;
+                }
+                // Invalid — show error, re-prompt if we have attempts left.
+                display.write(display.error(`Validation failed: ${result.reason ?? 'unknown error'}`, attempt < maxAttempts
+                    ? 'Re-enter the key, or press Ctrl+C to exit.'
+                    : 'Three attempts used.'));
+                if (attempt >= maxAttempts) {
+                    // Phase 30.2.1 — recovery menu replaces the prior dead-end
+                    // `throw new Error(...)`. Five paths for the user to pick from:
+                    //   [1] try-different    → loop back to provider picker
+                    //   [2] get-key (URL)    → open browser, fresh 3 attempts
+                    //   [3] save-anyway      → write config without validation
+                    //   [4] skip             → boot REPL in explore mode
+                    //   [5] exit             → clean exit
+                    const choice = await runRecoveryMenu(provider, prompts, display);
+                    if (choice.kind === 'try-different') {
+                        continue outer;
+                    }
+                    if (choice.kind === 'get-key') {
+                        display.write(`\nOpening ${choice.url} in your browser…\n`);
+                        await openUrlInBrowser(choice.url, display);
+                        display.write(`${kleur_1.default.dim('Paste the new key when prompted. You have 3 fresh attempts.')}\n`);
+                        // Reset the attempt counter and re-prompt for a fresh key.
+                        attempt = 1;
+                        if (provider.kind === 'custom') {
+                            baseUrl = await prompts.input('Base URL (e.g. https://api.example.com/v1)', { default: baseUrl });
+                            apiKey = await prompts.input('API key', { mask: true });
+                        }
+                        else {
+                            apiKey = await prompts.input(`API key for ${provider.shortLabel}`, { mask: true });
+                        }
+                        continue validation;
+                    }
+                    if (choice.kind === 'save-anyway') {
+                        display.write(`${kleur_1.default.yellow('Saving without validation. The key will be tested on your first chat.')}\n`);
+                        skipValidationForSave = true;
+                        break validation;
+                    }
+                    if (choice.kind === 'skip') {
+                        display.write('\nEntering explore mode — chat is disabled but slash commands work.\n');
+                        return {
+                            status: 'skipped',
+                            ran: false,
+                            skipReason: 'recovery-explore-mode',
+                        };
+                    }
+                    // choice.kind === 'exit'
+                    display.write('\nExited. Run `aiden setup` to try again.\n');
+                    return { status: 'exited', ran: false, skipReason: 'recovery-exited' };
+                }
+                // Re-prompt for credentials (only reached when attempt < maxAttempts).
+                if (provider.kind === 'custom') {
+                    baseUrl = await prompts.input('Base URL (e.g. https://api.example.com/v1)', {
+                        default: baseUrl,
+                    });
+                    apiKey = await prompts.input('API key', { mask: true });
+                }
+                else {
+                    apiKey = await prompts.input(`API key for ${provider.shortLabel}`, { mask: true });
+                }
+                attempt += 1;
+            }
+            // Tag the outer scope so the post-validation save path knows
+            // whether to print the "untested" warning. (validated is read
+            // by the smoke-test branch below; skipValidationForSave is
+            // currently unused outside this block but documented for
+            // post-save UX hooks.)
+            void validated;
+            void skipValidationForSave;
         }
-        // Pick a default model from the registry's known list; user can /model later.
-        const modelId = oauthProvider.defaultModels?.[0] ?? '';
+        // Step 4: terminal backend (basic — keeps wizard in scope for 14a).
+        // Default to "auto" — full picker lands in 14b.
+        const terminalBackend = 'auto';
+        // Step 5: save
         const config = {
             ...config_1.DEFAULT_CONFIG,
             model: { provider: provider.id, modelId },
@@ -442,17 +793,25 @@ async function runSetupWizard(opts = {}) {
             memory: { ...config_1.DEFAULT_CONFIG.memory },
             providers: {
                 ...(config_1.DEFAULT_CONFIG.providers ?? {}),
-                // Marker for /providers + future tooling. The actual bearer
-                // lives in tokenStore — config.yaml does NOT carry the secret.
-                [provider.id]: { auth: 'oauth' },
+                [provider.id]: {
+                    ...(baseUrl ? { baseUrl } : {}),
+                    ...(provider.envVar ? { apiKey: `\${${provider.envVar}}` } : {}),
+                },
             },
-            terminal: { backend: 'auto' },
+            terminal: { backend: terminalBackend },
         };
         if (opts.smokeTest) {
             display.write('\n✓ Smoke test complete — would have saved this config:\n');
             display.write(`${JSON.stringify(config, null, 2)}\n`);
-            display.write(`(would have saved tokens to ${node_path_1.default.join(paths.root, 'auth', `${provider.id}.json`)})\n`);
+            if (apiKey && provider.envVar) {
+                display.write(`(would have written ${provider.envVar}=*** to ${paths.envFile})\n`);
+            }
+            if (baseUrl && provider.kind === 'custom') {
+                display.write(`(would have written CUSTOM_BASE_URL=${baseUrl} to ${paths.envFile})\n`);
+            }
+            display.write('(no files written because --smoke-test was passed)\n');
             return {
+                status: 'configured',
                 ran: false,
                 skipReason: 'smoke-test',
                 config,
@@ -461,145 +820,19 @@ async function runSetupWizard(opts = {}) {
         }
         const cm = new config_1.ConfigManager(paths);
         await cm.save(config);
-        // Confirmation surface — what's wired now.
-        const expIso = new Date(tokens.expiresAtMs).toISOString();
-        display.write(`\n✓ ${provider.label} authed.\n`);
-        if (tokens.account)
-            display.write(`  Account: ${tokens.account}\n`);
-        if (oauthProvider.defaultModels?.length) {
-            display.write(`  Models: ${oauthProvider.defaultModels.join(', ')}\n`);
-        }
-        display.write(`  Tokens stored at: ${node_path_1.default.join(paths.root, 'auth', `${provider.id}.json`)}\n`);
-        display.write(`  Expires: ${expIso}\n`);
-        display.write(`\nTokens encrypted with a machine-derived key. Protects against casual ` +
-            `file inspection but NOT against code execution on this machine. ` +
-            `Real OS keychain integration in v4.1.\n`);
-        printPostWizardTutorial(display, AIDEN_VERSION);
-        return { ran: true, config, envFile: paths.envFile };
-    }
-    // Step 2: model selection
-    let modelId = provider.defaultModel ?? '';
-    if (provider.models && provider.models.length > 1) {
-        const modelIndex = await prompts.choose(`Pick a model for ${provider.label}`, provider.models);
-        modelId = provider.models[modelIndex - 1];
-    }
-    else if (provider.kind === 'local') {
-        modelId = await prompts.input('Ollama model id', { default: provider.defaultModel ?? 'llama3.1:8b' });
-    }
-    else if (!modelId) {
-        modelId = await prompts.input('Model id', { default: '' });
-    }
-    // Step 3: credentials
-    let apiKey;
-    let baseUrl;
-    if (provider.kind === 'local') {
-        const reachable = await probeOllama({ fetchImpl });
-        if (!reachable) {
-            display.write(display.error('Ollama not reachable on http://localhost:11434', 'install from https://ollama.com, run `ollama serve`, then re-run `aiden setup`.'));
-            return { ran: false, skipReason: 'ollama-not-reachable' };
-        }
-    }
-    else if (provider.kind === 'custom') {
-        baseUrl = await prompts.input('Base URL (e.g. https://api.example.com/v1)');
-        apiKey = await prompts.input('API key', { mask: true });
-    }
-    else if (provider.kind === 'key' || provider.kind === 'subscription') {
-        if (provider.envVar) {
-            apiKey = await prompts.input(`API key for ${provider.label}`, { mask: true });
-        }
-    }
-    // Step 3.5: validate the API key against the provider endpoint.
-    // Bypassed when smokeTest or skipValidation is set, or when there's no key
-    // to validate (Ollama, or a subscription provider without an env var).
-    const shouldValidate = !opts.smokeTest &&
-        !opts.skipValidation &&
-        typeof apiKey === 'string' &&
-        apiKey.length > 0;
-    if (shouldValidate) {
-        const validate = opts.validator ?? keyValidator_1.validateProviderKey;
-        const maxAttempts = 3;
-        let attempt = 1;
-        // First attempt uses the key already collected. Subsequent attempts
-        // re-prompt for a fresh key (and baseUrl, for custom).
-        while (attempt <= maxAttempts) {
-            const spinner = display.startSpinner(`Validating ${provider.label} API key…`);
-            let result;
-            try {
-                result = await validate(provider.id, apiKey, baseUrl, fetchImpl);
-            }
-            finally {
-                spinner.stop();
-            }
-            if (result.valid) {
-                if (result.skipped) {
-                    display.write(`${kleur_1.default.dim(`Skipped validation: ${result.skipReason ?? 'no validation endpoint'}. The key will be tested on first call.`)}\n`);
-                }
-                else {
-                    display.write(`${kleur_1.default.green(`✓ ${provider.label} API key validated`)}\n`);
-                }
-                break;
-            }
-            // Invalid — show error, re-prompt if we have attempts left.
-            display.write(display.error(`Validation failed: ${result.reason ?? 'unknown error'}`, 'Re-enter the key, or press Ctrl+C to exit.'));
-            if (attempt >= maxAttempts) {
-                throw new Error('Could not validate key after 3 attempts. Run `aiden setup --skip-validation` to bypass.');
-            }
-            // Re-prompt for credentials.
-            if (provider.kind === 'custom') {
-                baseUrl = await prompts.input('Base URL (e.g. https://api.example.com/v1)', {
-                    default: baseUrl,
-                });
-                apiKey = await prompts.input('API key', { mask: true });
-            }
-            else {
-                apiKey = await prompts.input(`API key for ${provider.label}`, { mask: true });
-            }
-            attempt += 1;
-        }
-    }
-    // Step 4: terminal backend (basic — keeps wizard in scope for 14a).
-    // Default to "auto" — full picker lands in 14b.
-    const terminalBackend = 'auto';
-    // Step 5: save
-    const config = {
-        ...config_1.DEFAULT_CONFIG,
-        model: { provider: provider.id, modelId },
-        agent: { ...config_1.DEFAULT_CONFIG.agent, max_turns: config_1.DEFAULT_CONFIG.agent.max_turns },
-        display: { ...config_1.DEFAULT_CONFIG.display, skin: 'default' },
-        memory: { ...config_1.DEFAULT_CONFIG.memory },
-        providers: {
-            ...(config_1.DEFAULT_CONFIG.providers ?? {}),
-            [provider.id]: {
-                ...(baseUrl ? { baseUrl } : {}),
-                ...(provider.envVar ? { apiKey: `\${${provider.envVar}}` } : {}),
-            },
-        },
-        terminal: { backend: terminalBackend },
-    };
-    if (opts.smokeTest) {
-        display.write('\n✓ Smoke test complete — would have saved this config:\n');
-        display.write(`${JSON.stringify(config, null, 2)}\n`);
         if (apiKey && provider.envVar) {
-            display.write(`(would have written ${provider.envVar}=*** to ${paths.envFile})\n`);
+            await upsertEnvVar(paths.envFile, provider.envVar, apiKey);
         }
         if (baseUrl && provider.kind === 'custom') {
-            display.write(`(would have written CUSTOM_BASE_URL=${baseUrl} to ${paths.envFile})\n`);
+            await upsertEnvVar(paths.envFile, 'CUSTOM_BASE_URL', baseUrl);
         }
-        display.write('(no files written because --smoke-test was passed)\n');
-        return { ran: false, skipReason: 'smoke-test', config, envFile: paths.envFile };
-    }
-    const cm = new config_1.ConfigManager(paths);
-    await cm.save(config);
-    if (apiKey && provider.envVar) {
-        await upsertEnvVar(paths.envFile, provider.envVar, apiKey);
-    }
-    if (baseUrl && provider.kind === 'custom') {
-        await upsertEnvVar(paths.envFile, 'CUSTOM_BASE_URL', baseUrl);
-    }
-    // Step 6: tutorial
-    display.write(`\n${kleur_1.default.green(`✓ ${provider.label}`)} configured with model ${kleur_1.default.cyan(modelId)}.\n`);
-    printPostWizardTutorial(display, AIDEN_VERSION);
-    return { ran: true, config, envFile: paths.envFile };
+        // Step 6: tutorial
+        display.write(`\n${kleur_1.default.green(`✓ ${provider.shortLabel}`)} configured with model ${kleur_1.default.cyan(modelId)}.\n`);
+        printPostWizardTutorial(display, AIDEN_VERSION);
+        return { status: 'configured', ran: true, config, envFile: paths.envFile };
+    } // end of outer: while (true) — every path inside either continues,
+    // returns, or breaks. Reaching this `}` is impossible (guarded by
+    // the no-constant-condition eslint comment above the outer label).
 }
 // ---------------------------------------------------------------------------
 // Direct invocation: `npx tsx cli/v4/setupWizard.ts [--smoke-test] [--force]`
@@ -611,10 +844,11 @@ if (require.main === module) {
     const skipValidation = argv.includes('--skip-validation');
     runSetupWizard({ smokeTest, force, skipValidation })
         .then((result) => {
-        if (!result.ran && result.skipReason && result.skipReason !== 'smoke-test') {
-            // Skipped for a reason that's already been displayed; non-zero so callers can detect.
-            process.exit(0);
-        }
+        // Phase 30.2.1: status is the new authoritative signal. Direct
+        // CLI invocation always exits 0 — the wizard already printed
+        // its own outcome lines, and a non-zero exit confuses shell
+        // wrappers that pipe the wizard's output into other tools.
+        void result.status;
         process.exit(0);
     })
         .catch((err) => {