gnosys 5.11.4 → 5.12.2

package/dist/lib/setup.js

@@ -14,12 +14,16 @@ import fsSync from "fs";
 import path from "path";
 import os from "os";
 import { execSync } from "child_process";
-import { loadConfig, updateConfig, getProviderModel, } from "./config.js";
-import { validateModel } from "./modelValidation.js";
+import { loadConfig, updateConfig, resolveTaskModel, getProviderModel, } from "./config.js";
+import { isApiKeyValidationError, validateModel } from "./modelValidation.js";
+import { buildOpenRouterTiers, OPENROUTER_STATIC_TIERS, } from "./openrouterTiers.js";
+import { apiKeyServiceName, buildApiKeyRequirementsFromConfig, ensureApiKeys, getApiKeyForProviderFromConfig, providerNeedsApiKey, readFirstInChain, readStoredSecret, storeApiKeySecret, } from "./apiKeyVault.js";
 import { resolveActiveStorePath, ensureActiveStorePath } from "./setup/storePath.js";
 import { safeQuestion } from "./setup/ui/safePrompt.js";
+export { printStatus } from "./setup/ui/status.js";
 import { getClaudeDesktopConfigPath, getApiKeySkipHints } from "./platform.js";
 import { gnosysStdioMcpEntry, installStdioMcpJson, normalizeIdeKey, resolveGnosysMcpCommand, cursorMcpPaths, runCli, removeTomlSection, } from "./ideMcpInstall.js";
+import { runKeysSetup } from "./setupKeys.js";
 // ─── ANSI Colors ────────────────────────────────────────────────────────────
 const BOLD = "\x1b[1m";
 const DIM = "\x1b[2m";
@@ -76,6 +80,7 @@ export const PROVIDER_TIERS = {
     lmstudio: [
         { name: "Default", model: "default", input: 0, output: 0, recommended: true },
     ],
+    openrouter: OPENROUTER_STATIC_TIERS,
     custom: [],
 };
 // ─── Dynamic Model Fetching (OpenRouter) ─────────────────────────────────────
@@ -95,7 +100,7 @@ const OPENROUTER_PREFIX_MAP = {
  * Fetch models from OpenRouter, cache for 24 hours, fall back to hardcoded.
  * Returns updated PROVIDER_TIERS for cloud providers only.
  */
-async function fetchDynamicModels() {
+export async function fetchDynamicModels() {
     // Check cache first
     try {
         const stat = await fs.stat(CACHE_FILE);
@@ -250,6 +255,7 @@ async function fetchDynamicModels() {
             }
             result[ourProvider] = tiers;
         }
+        result.openrouter = buildOpenRouterTiers(data.data);
         // Cache the result
         try {
             await fs.mkdir(path.dirname(CACHE_FILE), { recursive: true });
@@ -265,16 +271,6 @@ async function fetchDynamicModels() {
         return {};
     }
 }
-/**
- * Get model tiers for a provider — tries dynamic first, falls back to hardcoded.
- */
-async function getModelTiers(provider) {
-    const dynamic = await fetchDynamicModels();
-    if (dynamic[provider] && dynamic[provider].length > 0) {
-        return dynamic[provider];
-    }
-    return PROVIDER_TIERS[provider] ?? [];
-}
 // ─── Provider display names and env var mapping ─────────────────────────────
 const PROVIDER_DISPLAY = {
     anthropic: "Anthropic (Claude)",
@@ -284,6 +280,7 @@ const PROVIDER_DISPLAY = {
     xai: "xAI (Grok)",
     mistral: "Mistral",
     lmstudio: "LM Studio (local, free)",
+    openrouter: "OpenRouter (free + paid models)",
     custom: "Custom (any OpenAI-compatible API)",
 };
 const PROVIDER_ENV_VAR = {
@@ -292,6 +289,7 @@ const PROVIDER_ENV_VAR = {
     groq: "GNOSYS_GROQ_KEY",
     xai: "GNOSYS_XAI_KEY",
     mistral: "GNOSYS_MISTRAL_KEY",
+    openrouter: "GNOSYS_OPENROUTER_KEY",
     custom: "GNOSYS_CUSTOM_KEY",
 };
 // Ordered list for the menu
@@ -303,16 +301,40 @@ const PROVIDER_ORDER = [
     "xai",
     "mistral",
     "lmstudio",
+    "openrouter",
     "custom",
 ];
 // Task descriptions for display
-const TASK_DESCRIPTIONS = {
+export const TASK_DESCRIPTIONS = {
     structuring: "adding memories, tagging",
     synthesis: "Q&A answers",
+    chat: "interactive chat TUI",
     vision: "images, PDFs",
     transcription: "audio files",
     dream: "overnight consolidation",
 };
+/** Tasks routed via taskModels in gnosys.json */
+const ROUTABLE_TASK_LIST = [
+    "structuring",
+    "synthesis",
+    "vision",
+    "transcription",
+    "chat",
+];
+export const ASSIGNABLE_TASK_LIST = [
+    ...ROUTABLE_TASK_LIST,
+    "dream",
+];
+export function getAssignableRouting(cfg, task) {
+    if (task === "dream") {
+        const dreamProvider = (cfg.dream?.provider ?? "ollama");
+        return {
+            provider: dreamProvider,
+            model: cfg.dream?.model ?? getProviderModel(cfg, dreamProvider),
+        };
+    }
+    return resolveTaskModel(cfg, task);
+}
 // ─── Exported Helpers ───────────────────────────────────────────────────────
 /**
  * Returns the cheapest capable model for structuring tasks.
@@ -334,8 +356,10 @@ export function getStructuringModel(provider, chosenModel) {
  * Creates the directory and file if they don't exist.
  * Replaces an existing key line if found, otherwise appends.
  */
-export async function writeApiKey(provider, key) {
-    const envVar = PROVIDER_ENV_VAR[provider];
+export async function writeApiKey(provider, key, opts) {
+    const envVar = opts?.scope === "global"
+        ? apiKeyServiceName(provider, "global")
+        : PROVIDER_ENV_VAR[provider];
     if (!envVar)
         return;
     const configDir = path.join(os.homedir(), ".config", "gnosys");
@@ -418,6 +442,68 @@ function hasSecretTool() {
         return false;
     }
 }
+/**
+ * Prompt for a replacement API key after validation fails, storing it in the
+ * platform secure store when available (Keychain / GNOME Keyring), else .env.
+ */
+async function promptAndStoreProviderApiKey(rl, provider, scope = "provider") {
+    if (provider === "ollama" || provider === "lmstudio" || provider === "skip") {
+        return null;
+    }
+    const service = apiKeyServiceName(provider, scope);
+    console.log();
+    console.log(`  ${WARN} Your API key may be expired or invalid.`);
+    console.log(`  ${DIM}Enter a new key — saved as ${service}${RESET}`);
+    console.log();
+    const key = await askInput(rl, `Enter your ${provider} API key`);
+    if (!key) {
+        return null;
+    }
+    if (storeApiKeySecret(service, key, provider)) {
+        const store = process.platform === "darwin" ? "macOS Keychain" : "GNOME Keyring";
+        console.log(`  ${CHECK} Key saved to ${store} (${maskKey(key)})`);
+        return key;
+    }
+    console.log(`  ${CROSS} Failed to write to secure store. Saving to ~/.config/gnosys/.env instead.`);
+    await writeApiKey(provider, key);
+    console.log(`  ${CHECK} Key saved to ~/.config/gnosys/.env (${maskKey(key)})`);
+    return key;
+}
+/**
+ * Run model validation; on API-key auth failures, offer to rotate the key and
+ * retry once before asking whether to save config anyway.
+ */
+async function validateModelWithKeyRotation(opts) {
+    const { Spinner } = await import("./setup/ui/spinner.js");
+    let apiKey = opts.apiKey;
+    const validateSpin = Spinner(`validating ${opts.provider} / ${opts.model}…`);
+    let result = await validateModel(opts.provider, opts.model, apiKey, {
+        customBaseUrl: opts.customBaseUrl,
+    });
+    if (result.ok) {
+        validateSpin.ok("model validated", `${result.latencyMs} ms · ${opts.provider} / ${opts.model}`);
+        return { proceed: true, apiKey };
+    }
+    validateSpin.fail("model test failed", result.error);
+    if (!opts.isLocalProvider &&
+        isApiKeyValidationError(result.error)) {
+        const newKey = await promptAndStoreProviderApiKey(opts.rl, opts.provider, opts.keyScope ?? "global");
+        if (newKey) {
+            apiKey = newKey;
+            const retrySpin = Spinner(`re-validating ${opts.provider} / ${opts.model}…`);
+            result = await validateModel(opts.provider, opts.model, apiKey, {
+                customBaseUrl: opts.customBaseUrl,
+            });
+            if (result.ok) {
+                retrySpin.ok("model validated", `${result.latencyMs} ms · ${opts.provider} / ${opts.model}`);
+                return { proceed: true, apiKey };
+            }
+            retrySpin.fail("model test failed", result.error);
+        }
+    }
+    const proceed = await askYesNo(opts.rl, opts.saveAnywayPrompt, opts.saveAnywayDefault);
+    return { proceed, apiKey };
+}
 /**
  * Detect where an existing API key is stored.
  * Returns description like "macOS Keychain", "env var", ".env file", or empty string.
@@ -579,7 +665,7 @@ export async function detectIDEs(projectDir) {
  */
 export function upsertGrokMcpBlock(existing, name, entry) {
     // Drop mistaken v5.9.4 `[mcp.<name>]` sections so we don't leave dead config.
-    let content = removeTomlSection(existing, `[mcp.${name}]`);
+    const content = removeTomlSection(existing, `[mcp.${name}]`);
     const sectionHeader = `[mcp_servers.${name}]`;
     const lines = content.split("\n");
     const headerIdx = lines.findIndex((line) => line.trim() === sectionHeader);
@@ -683,7 +769,7 @@ export async function setupIDE(ide, projectDir) {
                 // 1. Strip legacy hand-written sections in ~/.codex/config.toml.
                 const userCodexConfig = path.join(os.homedir(), ".codex", "config.toml");
                 try {
-                    let existing = await fs.readFile(userCodexConfig, "utf-8");
+                    const existing = await fs.readFile(userCodexConfig, "utf-8");
                     const cleaned = removeTomlSection(removeTomlSection(existing, "[mcp.gnosys]"), "[gnosys]");
                     if (cleaned !== existing) {
                         await fs.writeFile(userCodexConfig, cleaned, "utf-8");
@@ -700,7 +786,7 @@ export async function setupIDE(ide, projectDir) {
                 let alreadyCorrect = false;
                 try {
                     const existing = runCli("codex", ["mcp", "get", "gnosys"], { allowFailure: true });
-                    if (existing && existing.includes(gnosysCmd) && !existing.includes(" serve")) {
+                    if (existing?.includes(gnosysCmd) && !existing.includes(" serve")) {
                         alreadyCorrect = true;
                     }
                     else if (existing) {
@@ -817,16 +903,20 @@ async function askChoice(rl, question, options) {
 /**
  * Read a single line of input with an optional default value.
  */
-async function askInput(rl, prompt, opts) {
+export async function askInput(rl, prompt, opts) {
     const suffix = opts?.default ? ` ${DIM}(${opts.default})${RESET}` : "";
     const answer = await safeQuestion(rl, `${prompt}${suffix}: `);
     const trimmed = answer.trim();
     return trimmed || opts?.default || "";
 }
+export function printInfo(text, meta) {
+    const suffix = meta ? ` ${DIM}${meta}${RESET}` : "";
+    console.log(`  ${text}${suffix}`);
+}
 /**
  * Y/n prompt. Returns true for yes.
  */
-async function askYesNo(rl, question, defaultYes = true) {
+export async function askYesNo(rl, question, defaultYes = true) {
     const hint = defaultYes ? "Y/n" : "y/N";
     const answer = await safeQuestion(rl, `${question} [${hint}] `);
     const trimmed = answer.trim().toLowerCase();
@@ -834,6 +924,78 @@ async function askYesNo(rl, question, defaultYes = true) {
         return defaultYes;
     return trimmed === "y" || trimmed === "yes";
 }
+/**
+ * Read a password/API key without echoing it back to the terminal.
+ */
+export async function askPassword(rl, prompt) {
+    if (!stdin.isTTY || typeof stdin.setRawMode !== "function") {
+        return askInput(rl, prompt);
+    }
+    return new Promise((resolve) => {
+        let value = "";
+        stdout.write(`${prompt}: `);
+        stdin.setRawMode(true);
+        stdin.resume();
+        const cleanup = () => {
+            stdin.setRawMode(false);
+            stdin.off("data", onData);
+            stdout.write("\n");
+        };
+        const onData = (chunk) => {
+            const input = chunk.toString("utf-8");
+            for (const char of input) {
+                const code = char.charCodeAt(0);
+                if (code === 3) {
+                    cleanup();
+                    try {
+                        rl.close();
+                    }
+                    catch {
+                        // already closed
+                    }
+                    process.exit(130);
+                }
+                if (code === 13 || code === 10) {
+                    cleanup();
+                    resolve(value.trim());
+                    return;
+                }
+                if (code === 127 || code === 8) {
+                    value = value.slice(0, -1);
+                    continue;
+                }
+                value += char;
+            }
+        };
+        stdin.on("data", onData);
+    });
+}
+/** Parse `1,3,5`, `all`, or `none` into 0-based task indices. */
+export function parseCommaSeparatedTaskSelection(input, count) {
+    const trimmed = input.trim().toLowerCase();
+    if (!trimmed)
+        return null;
+    if (trimmed === "all" || trimmed === "*") {
+        return "all";
+    }
+    if (trimmed === "none" || trimmed === "-") {
+        return "none";
+    }
+    const indices = [];
+    for (const part of trimmed.split(/[,;\s]+/)) {
+        const n = parseInt(part.trim(), 10);
+        if (Number.isNaN(n) || n < 1 || n > count) {
+            return null;
+        }
+        if (!indices.includes(n - 1)) {
+            indices.push(n - 1);
+        }
+    }
+    return indices.length > 0 ? indices : null;
+}
+export function modelForTaskAssignment(task, provider, model) {
+    return task === "structuring" ? getStructuringModel(provider, model) : model;
+}
 /**
  * Format a price for display: "$0.80" or "free".
  */
@@ -926,7 +1088,7 @@ async function loadExistingConfig(projectDir) {
  * Returns the provider name or "skip".
  * If currentProvider is given, shows it as the current value.
  */
-async function pickProvider(rl, dynamicModels, stepLabel, currentProvider) {
+export async function pickProvider(rl, dynamicModels, stepLabel, currentProvider) {
     const currentHint = currentProvider ? ` ${DIM}(current: ${currentProvider})${RESET}` : "";
     const providerOptions = PROVIDER_ORDER.map((key) => {
         const tiers = dynamicModels[key] ?? PROVIDER_TIERS[key];
@@ -947,7 +1109,7 @@ async function pickProvider(rl, dynamicModels, stepLabel, currentProvider) {
  * Returns the model string. Includes a "Custom (enter model name)"
  * option so users can type any model ID not in the curated list.
  */
-async function pickModel(rl, provider, dynamicModels, stepLabel, currentModel) {
+export async function pickModel(rl, provider, dynamicModels, stepLabel, currentModel) {
     const tiers = dynamicModels[provider] ?? PROVIDER_TIERS[provider];
     if (!tiers || tiers.length === 0) {
         // No tiers available — fall back to direct entry
@@ -971,8 +1133,10 @@ async function pickModel(rl, provider, dynamicModels, stepLabel, currentModel) {
     }
     return tiers[tierIndex].model;
 }
-// ─── Main Setup Wizard ──────────────────────────────────────────────────────
 export async function runSetup(opts) {
+    if (opts.section === "keys") {
+        return runKeysSetup();
+    }
     const version = getVersion();
     const projectDir = opts.directory ? path.resolve(opts.directory) : process.cwd();
     // ─── Non-interactive mode ─────────────────────────────────────────────
@@ -1199,6 +1363,7 @@ export async function runSetup(opts) {
             groq: "GROQ_API_KEY",
             xai: "XAI_API_KEY",
             mistral: "MISTRAL_API_KEY",
+            openrouter: "OPENROUTER_API_KEY",
         };
         const legacyEnvVar = legacyEnvVars[provider] ?? "";
         if (needsKey) {
@@ -1264,8 +1429,7 @@ export async function runSetup(opts) {
                 const gnomeIdx = hasSecret ? idx++ : -1;
                 const envIdx = idx++;
                 const dotenvIdx = idx++;
-                const skipIdx = idx++;
-                // skipIdx is unused as a variable but documents the last index
+                idx++; // skip entry consumes the last index (value itself unused)
                 if (keyChoice === keychainIdx) {
                     // macOS Keychain — reuse existing key if available, otherwise ask
                     console.log();
@@ -1373,26 +1537,27 @@ export async function runSetup(opts) {
             console.log();
             console.log(`${DIM}Testing ${provider}/${model}...${RESET}`);
             try {
-                const { validateModel } = await import("./modelValidation.js");
                 const customBaseUrl = provider === "custom"
                     ? process.env.GNOSYS_LLM_BASE_URL
                     : undefined;
-                const result = await validateModel(provider, model, capturedApiKey, { customBaseUrl });
-                if (result.ok) {
-                    console.log(`  ${CHECK} Model validated (${result.latencyMs}ms)`);
-                }
-                else {
-                    console.log(`  ${WARN} Model test failed: ${result.error}`);
-                    const proceed = await askYesNo(rl, "  Continue anyway?", true);
-                    if (!proceed) {
-                        console.log(`  ${DIM}Setup paused. Re-run when ready: gnosys setup${RESET}`);
-                        setupCompleted = true;
-                        rl.close();
-                        return {
-                            provider, model, structuringModel: "",
-                            apiKeyWritten, ides: [], mode: "agent", upgraded,
-                        };
-                    }
+                const { proceed } = await validateModelWithKeyRotation({
+                    rl,
+                    provider,
+                    model,
+                    apiKey: capturedApiKey,
+                    customBaseUrl,
+                    isLocalProvider,
+                    saveAnywayPrompt: "  Continue anyway?",
+                    saveAnywayDefault: true,
+                });
+                if (!proceed) {
+                    console.log(`  ${DIM}Setup paused. Re-run when ready: gnosys setup${RESET}`);
+                    setupCompleted = true;
+                    rl.close();
+                    return {
+                        provider, model, structuringModel: "",
+                        apiKeyWritten, ides: [], mode: "agent", upgraded,
+                    };
                 }
             }
             catch (err) {
@@ -1671,6 +1836,18 @@ export async function runSetup(opts) {
                 await updateConfig(storePath, configUpdates);
                 console.log();
                 console.log(`  ${CHECK} Config written to ${storePath}/gnosys.json`);
+                const savedCfg = await loadConfig(storePath);
+                const keyReqs = buildApiKeyRequirementsFromConfig(savedCfg);
+                if (keyReqs.length > 0) {
+                    await ensureApiKeys(rl, keyReqs, askInput, {
+                        warn: WARN,
+                        check: CHECK,
+                        cross: CROSS,
+                        dim: DIM,
+                        reset: RESET,
+                        maskKey,
+                    });
+                }
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
@@ -1787,58 +1964,163 @@ export async function runSetup(opts) {
     }
 }
 /**
- * Update ONLY `llm.defaultProvider` in gnosys.json. Used by the summary
- * panel row 1 ("provider") so it stops dragging the user into the full
- * model picker — that's row 2's job.
- *
- * v5.9.4 Bug 4 — before this split, both summary rows routed through
- * `runModelsSetup`, leaving no way to swap provider without also choosing
- * a new model. Now row 1 picks a provider, row 2 picks a model.
+ * Build API key requirements from the selected task set only (§3.7).
+ * One global key per distinct cloud provider in the selection.
  */
-export async function runProviderOnlySetup(opts = {}) {
-    const projectDir = opts.directory ? path.resolve(opts.directory) : process.cwd();
-    const ownsRl = !opts.rl;
-    const rl = opts.rl ?? createInterface({ input: stdin, output: stdout });
+export function buildInlineKeyRequirements(selectedTasks, providerForTask) {
+    const providers = [
+        ...new Set(selectedTasks
+            .map((t) => providerForTask(t))
+            .filter((p) => providerNeedsApiKey(p))
+            .map((p) => p)),
+    ];
+    return providers.map((provider) => ({ provider, scope: "global" }));
+}
+/** Write or replace a single `NAME=value` line in ~/.config/gnosys/.env. */
+export async function writeServiceKeyToEnv(service, key) {
+    const configDir = path.join(os.homedir(), ".config", "gnosys");
+    await fs.mkdir(configDir, { recursive: true, mode: 0o700 });
+    await fs.chmod(configDir, 0o700);
+    const envPath = path.join(configDir, ".env");
+    let lines = [];
     try {
-        const { Header } = await import("./setup/ui/header.js");
-        const { Title } = await import("./setup/ui/title.js");
-        const { Spinner } = await import("./setup/ui/spinner.js");
-        const { printStatus } = await import("./setup/ui/status.js");
-        console.log();
-        console.log(Header(["gnosys", "setup", "provider"]));
-        console.log();
-        console.log(Title("Default provider", "pick the LLM provider — model stays as configured"));
-        console.log();
-        const existingConfig = await loadExistingConfig(projectDir);
-        const currentProvider = existingConfig?.llm.defaultProvider;
-        const pricingSpin = Spinner("fetching latest pricing from openrouter…");
-        const fetchStart = Date.now();
-        const dynamicModels = await fetchDynamicModels();
-        const fetchMs = Date.now() - fetchStart;
-        if (Object.keys(dynamicModels).length > 0) {
-            pricingSpin.ok("pricing loaded", `${fetchMs} ms`);
-        }
-        else {
-            pricingSpin.fail("pricing fetch failed", "using bundled tiers");
+        lines = (await fs.readFile(envPath, "utf-8")).split("\n");
+    }
+    catch {
+        // fresh file
+    }
+    const prefix = `${service}=`;
+    let replaced = false;
+    lines = lines.map((line) => {
+        if (line.startsWith(prefix)) {
+            replaced = true;
+            return `${service}=${key}`;
         }
-        console.log();
-        const provider = await pickProvider(rl, dynamicModels, "Choose your LLM provider", currentProvider);
-        if (!provider || provider === currentProvider) {
-            printStatus("warn", "no change · provider unchanged");
-            return;
+        return line;
+    });
+    if (!replaced) {
+        if (lines.length > 0 && lines[lines.length - 1] !== "") {
+            lines.push("");
         }
-        const storePath = ensureActiveStorePath(projectDir);
-        const existingLlm = existingConfig?.llm ?? {};
-        await updateConfig(storePath, {
-            llm: { ...existingLlm, defaultProvider: provider },
+        lines.push(`${service}=${key}`);
+    }
+    await fs.writeFile(envPath, lines.join("\n"), { mode: 0o600 });
+    await fs.chmod(envPath, 0o600);
+}
+/**
+ * Validate a provider/model/key triple without persisting the key (§3.8).
+ * On auth failure, re-prompt for a replacement key in memory only.
+ */
+export async function validateTaskCombo(opts) {
+    const { Spinner } = await import("./setup/ui/spinner.js");
+    const reprompt = opts.repromptKey ??
+        (async (rl, provider) => {
+            console.log();
+            console.log(`  ${WARN} Your API key may be expired or invalid.`);
+            const key = await askInput(rl, `Enter your ${provider} API key`);
+            return key || null;
         });
-        printStatus("ok", `default provider · ${provider}`, `${storePath}/gnosys.json`);
-        printStatus("progress", "model unchanged", "use row 2 to swap the model");
+    let apiKey = opts.apiKey;
+    const validateSpin = Spinner(`validating ${opts.provider} / ${opts.model}…`);
+    let result = await validateModel(opts.provider, opts.model, apiKey, {
+        customBaseUrl: opts.customBaseUrl,
+    });
+    if (result.ok) {
+        validateSpin.ok("model validated", `${result.latencyMs} ms · ${opts.provider} / ${opts.model}`);
+        return { proceed: true, apiKey };
+    }
+    validateSpin.fail("model test failed", result.error);
+    if (!opts.isLocalProvider && isApiKeyValidationError(result.error)) {
+        const newKey = await reprompt(opts.rl, opts.provider);
+        if (newKey) {
+            apiKey = newKey;
+            const retrySpin = Spinner(`re-validating ${opts.provider} / ${opts.model}…`);
+            result = await validateModel(opts.provider, opts.model, apiKey, {
+                customBaseUrl: opts.customBaseUrl,
+            });
+            if (result.ok) {
+                retrySpin.ok("model validated", `${result.latencyMs} ms · ${opts.provider} / ${opts.model}`);
+                return { proceed: true, apiKey };
+            }
+            retrySpin.fail("model test failed", result.error);
+        }
     }
-    finally {
-        if (ownsRl)
-            rl.close();
+    const proceed = await askYesNo(opts.rl, opts.saveAnywayPrompt ?? "Save routing anyway?", opts.saveAnywayDefault ?? false);
+    return { proceed, apiKey };
+}
+const LEGACY_PROVIDER_ENV = {
+    anthropic: "ANTHROPIC_API_KEY",
+    openai: "OPENAI_API_KEY",
+    groq: "GROQ_API_KEY",
+    xai: "XAI_API_KEY",
+    mistral: "MISTRAL_API_KEY",
+    openrouter: "OPENROUTER_API_KEY",
+};
+/** Ask where to store a validated key; persist or print env-var hints (§3.10). */
+export async function promptKeyDestinationAndPersist(opts) {
+    const isMac = process.platform === "darwin";
+    const isLinux = process.platform === "linux";
+    const hasSecret = isLinux && hasSecretTool();
+    const options = [];
+    if (isMac) {
+        options.push("OS secure store (macOS Keychain) — recommended");
+    }
+    else if (hasSecret) {
+        options.push("OS secure store (GNOME Keyring) — recommended");
+    }
+    else {
+        options.push("OS secure store — recommended");
+    }
+    options.push("Config file (~/.config/gnosys/.env)");
+    options.push("Don't store — I'll set it as an environment variable myself");
+    const choice = opts.destinationChoice ??
+        (await askChoice(opts.rl, "Where should I store this key?", options));
+    const secureIdx = 0;
+    const dotenvIdx = 1;
+    if (choice === secureIdx) {
+        if (storeApiKeySecret(opts.service, opts.key, opts.provider)) {
+            const store = process.platform === "darwin" ? "macOS Keychain" : "GNOME Keyring";
+            console.log(`  ${CHECK} Key saved to ${store} (${maskKey(opts.key)})`);
+            return "secure";
+        }
+        console.log(`  ${CROSS} Failed to write to secure store. Saving to ~/.config/gnosys/.env instead.`);
+        await writeServiceKeyToEnv(opts.service, opts.key);
+        console.log(`  ${CHECK} Key saved to ~/.config/gnosys/.env (${maskKey(opts.key)})`);
+        return "dotenv";
+    }
+    if (choice === dotenvIdx) {
+        await writeServiceKeyToEnv(opts.service, opts.key);
+        console.log(`  ${CHECK} Key saved to ~/.config/gnosys/.env (${maskKey(opts.key)})`);
+        return "dotenv";
+    }
+    const legacy = LEGACY_PROVIDER_ENV[opts.provider];
+    const providerSvc = apiKeyServiceName(opts.provider, "provider");
+    console.log();
+    console.log(`  ${DIM}Set one of these environment variables:${RESET}`);
+    console.log(`  ${GREEN}export ${opts.service}=your-key-here${RESET}`);
+    if (opts.service !== providerSvc) {
+        console.log(`  ${DIM}or provider fallback:${RESET} ${GREEN}export ${providerSvc}=…${RESET}`);
+    }
+    if (legacy) {
+        console.log(`  ${DIM}or legacy:${RESET} ${GREEN}export ${legacy}=…${RESET}`);
     }
+    return "none";
+}
+/** Build taskModels patch — only selected routable tasks that changed. */
+export function buildTaskModelsPatchFromAccepted(accepted, currentByTask, selectedSet) {
+    const patch = {};
+    for (const task of ROUTABLE_TASK_LIST) {
+        if (!selectedSet.has(task))
+            continue;
+        const next = accepted[task];
+        if (!next)
+            continue;
+        const cur = currentByTask[task];
+        if (next.provider !== cur.provider || next.model !== cur.model) {
+            patch[task] = next;
+        }
+    }
+    return Object.keys(patch).length > 0 ? patch : undefined;
 }
 /**
  * Models-only configuration — prompts for provider, model, and key (or accepts
@@ -1850,7 +2132,6 @@ export async function runModelsSetup(opts = {}) {
     const ownsRl = !opts.rl;
     const rl = opts.rl ?? createInterface({ input: stdin, output: stdout });
     try {
-        // v5.9.3 Screen 3 — Header + Title at the top.
         const { Header } = await import("./setup/ui/header.js");
         const { Title } = await import("./setup/ui/title.js");
         const { Spinner } = await import("./setup/ui/spinner.js");
@@ -1859,16 +2140,13 @@ export async function runModelsSetup(opts = {}) {
         console.log();
         console.log(Header(["gnosys", "setup", "models"]));
         console.log();
-        console.log(Title("Model configuration", "pick a provider and model — we'll validate it before saving"));
+        console.log(Title("Model configuration", "pick a provider — then default or per-task routing"));
         console.log();
         const existingConfig = await loadExistingConfig(projectDir);
         const currentProvider = existingConfig?.llm.defaultProvider;
         const currentModel = existingConfig
             ? getProviderModel(existingConfig, existingConfig.llm.defaultProvider)
             : undefined;
-        // Step 1: provider (or use --provider flag). v5.9.3: animate the
-        // OpenRouter pricing fetch under a Spinner so the user gets feedback
-        // on what would otherwise feel like a hang.
         const pricingSpin = Spinner("fetching latest pricing from openrouter…");
         const fetchStart = Date.now();
         const dynamicModels = await fetchDynamicModels();
@@ -1878,8 +2156,6 @@ export async function runModelsSetup(opts = {}) {
             pricingSpin.ok(`pricing loaded · ${modelCount} models cached`, `${fetchMs} ms`);
         }
         else {
-            // No-op fallback (cache miss + network fail) — keep the hardcoded
-            // tiers but signal that we're running offline.
             pricingSpin.fail("pricing fetch failed", "using bundled tiers");
         }
         console.log();
@@ -1895,181 +2171,339 @@ export async function runModelsSetup(opts = {}) {
         else {
             provider = await pickProvider(rl, dynamicModels, "Choose your LLM provider", currentProvider);
         }
-        // Step 2: model (or use --model flag)
-        let model;
-        if (opts.model) {
-            model = opts.model;
-            printStatus("ok", "model", model);
-        }
-        else {
-            const tiers = dynamicModels[provider] ?? PROVIDER_TIERS[provider];
-            if (provider === "custom" || !tiers || tiers.length === 0) {
-                model = await askInput(rl, "Model name");
-            }
-            else {
-                const showCurrent = currentProvider === provider ? currentModel : undefined;
-                model = await pickModel(rl, provider, dynamicModels, "Choose model", showCurrent);
-            }
-        }
-        if (!model) {
-            printStatus("fail", "no model selected · aborting");
+        const storePath = ensureActiveStorePath(projectDir);
+        const cfgBefore = existingConfig ?? (await loadConfig(storePath));
+        const nonInteractiveDefault = !!(opts.provider || opts.model);
+        if (nonInteractiveDefault) {
+            await runModelsDefaultOnlySetup({
+                rl,
+                opts,
+                provider,
+                dynamicModels,
+                storePath,
+                existingConfig,
+                currentProvider,
+                currentModel,
+                printDiff,
+                printStatus,
+            });
             return;
         }
-        // Step 3: load API key from existing storage (if available)
-        const envVarName = provider === "custom" ? "GNOSYS_CUSTOM_KEY" :
-            `GNOSYS_${provider.toUpperCase()}_KEY`;
-        const legacyEnvVars = {
-            anthropic: "ANTHROPIC_API_KEY",
-            openai: "OPENAI_API_KEY",
-            groq: "GROQ_API_KEY",
-            xai: "XAI_API_KEY",
-            mistral: "MISTRAL_API_KEY",
-        };
-        const legacyEnvVar = legacyEnvVars[provider] ?? "";
-        let apiKey = process.env[envVarName] || (legacyEnvVar ? process.env[legacyEnvVar] : "") || "";
-        if (!apiKey && process.platform === "darwin") {
-            try {
-                apiKey = execSync(`security find-generic-password -a "$USER" -s "${envVarName}" -w`, { stdio: "pipe", encoding: "utf-8" }).trim();
-            }
-            catch {
-                // No key in keychain
-            }
-        }
-        if (!apiKey && provider !== "ollama" && provider !== "lmstudio") {
-            console.log(`${WARN} No API key found for ${provider}. Run 'gnosys setup' to configure one.`);
-            // Continue anyway — user might just want to update the model in config
-        }
-        // Step 4: validate (default: true) — v5.9.3 Screen 3: animated
-        // Spinner with latency reported on success.
-        const shouldValidate = opts.validate !== false;
-        const isLocalProvider = provider === "ollama" || provider === "lmstudio";
-        if (shouldValidate && (apiKey || isLocalProvider)) {
-            console.log();
-            const validateSpin = Spinner(`validating ${provider} / ${model}…`);
-            const customBaseUrl = provider === "custom"
-                ? process.env.GNOSYS_LLM_BASE_URL
-                : undefined;
-            const result = await validateModel(provider, model, apiKey, { customBaseUrl });
-            if (result.ok) {
-                validateSpin.ok("model validated", `${result.latencyMs} ms · ${provider} / ${model}`);
-            }
-            else {
-                validateSpin.fail("model test failed", result.error);
-                const proceed = await askYesNo(rl, "Save config anyway?", false);
-                if (!proceed) {
-                    printStatus("warn", "cancelled · no changes written");
-                    return;
-                }
-            }
+        console.log();
+        const intentChoice = await askChoice(rl, "What do you want to configure?", [
+            "Default only — set default provider and model",
+            "Assign to specific tasks — route selected tasks only (does not change default)",
+        ]);
+        if (intentChoice === 0) {
+            await runModelsDefaultOnlySetup({
+                rl,
+                opts,
+                provider,
+                dynamicModels,
+                storePath,
+                existingConfig,
+                currentProvider,
+                currentModel,
+                printDiff,
+                printStatus,
+            });
+            return;
         }
-        // Step 5: write config (v5.9.4 Bug 10 — unified store resolution).
-        const storePath = ensureActiveStorePath(projectDir);
-        const existingLlm = existingConfig?.llm;
-        const existingProviderConfig = existingLlm
-            ? existingLlm[provider]
-            : undefined;
-        const providerConfigBase = (typeof existingProviderConfig === "object" && existingProviderConfig !== null)
-            ? existingProviderConfig
-            : {};
-        await updateConfig(storePath, {
-            llm: {
-                ...(existingLlm ?? {}),
-                defaultProvider: provider,
-                [provider]: {
-                    ...providerConfigBase,
-                    model,
-                },
-            },
+        await runModelsTaskRoutingSetup({
+            rl,
+            opts,
+            provider,
+            dynamicModels,
+            storePath,
+            cfgBefore,
+            printStatus,
         });
-        // v5.9.3 Screen 3 — Diff() before the saved confirmation. Shows what
-        // landed in gnosys.json.
-        const { buildModelsDiffRows } = await import("./setup/modelsRender.js");
-        console.log();
-        printDiff(buildModelsDiffRows(currentProvider, currentModel, provider, model));
-        printStatus("ok", `saved · ${storePath}/gnosys.json`);
     }
     finally {
         if (ownsRl)
             rl.close();
     }
 }
-/**
- * Lightweight model-management command. Supports three operations:
- *   --list:    print available models for the current provider
- *   --refresh: clear the OpenRouter cache and re-fetch
- *   --set X:   update the default model in gnosys.json (no prompts)
- */
-async function runModelsCommand(opts = {}) {
-    const projectDir = opts.directory ? path.resolve(opts.directory) : process.cwd();
-    const existingConfig = await loadExistingConfig(projectDir);
-    const currentProvider = existingConfig?.llm.defaultProvider;
-    if (opts.refresh) {
-        const cacheFile = path.join(os.homedir(), ".config", "gnosys", "models-cache.json");
-        try {
-            await fs.unlink(cacheFile);
-            console.log(`${CHECK} Cache cleared.`);
+async function resolveKeyInMemory(opts) {
+    if (!providerNeedsApiKey(opts.provider))
+        return "";
+    const cached = opts.keyCache.get(opts.provider);
+    if (cached)
+        return cached;
+    const stored = readStoredSecret(apiKeyServiceName(opts.provider, "global"));
+    if (stored) {
+        opts.keyCache.set(opts.provider, stored);
+        return stored;
+    }
+    const key = await askInput(opts.rl, `API key for ${opts.provider} (shared across selected tasks)`);
+    opts.keyCache.set(opts.provider, key);
+    return key;
+}
+async function runModelsDefaultOnlySetup(ctx) {
+    const { rl, opts, provider, dynamicModels, storePath, printDiff, printStatus } = ctx;
+    const isLocalProvider = provider === "ollama" || provider === "lmstudio";
+    let model;
+    if (opts.model) {
+        model = opts.model;
+        printStatus("ok", "model", model);
+    }
+    else {
+        const tiers = dynamicModels[provider] ?? PROVIDER_TIERS[provider];
+        if (provider === "custom" || !tiers || tiers.length === 0) {
+            model = await askInput(rl, "Model name");
         }
-        catch {
-            console.log(`${DIM}No cache to clear.${RESET}`);
+        else {
+            const showCurrent = ctx.currentProvider === provider ? ctx.currentModel : undefined;
+            model = await pickModel(rl, provider, dynamicModels, "Choose model", showCurrent);
         }
     }
-    if (opts.list) {
-        if (!currentProvider) {
-            console.log(`${WARN} No provider configured. Run 'gnosys setup' first.`);
-            return;
-        }
+    if (!model) {
+        printStatus("fail", "no model selected · aborting");
+        return;
+    }
+    let apiKey = readFirstInChain(provider) ?? "";
+    let keyEnteredThisRun = false;
+    if (!apiKey && !isLocalProvider) {
         console.log();
-        console.log(`${BOLD}Available models for ${currentProvider}:${RESET}`);
+        apiKey = await askInput(rl, `API key for ${provider}`);
+        keyEnteredThisRun = !!apiKey;
+        if (!apiKey) {
+            console.log(`${WARN} No API key found for ${provider}. Validation may be skipped.`);
+        }
+    }
+    const shouldValidate = opts.validate !== false;
+    if (shouldValidate && (apiKey || isLocalProvider)) {
         console.log();
-        const dynamicModels = await fetchDynamicModels();
-        const tiers = dynamicModels[currentProvider] ?? PROVIDER_TIERS[currentProvider] ?? [];
-        if (tiers.length === 0) {
-            console.log(`  ${DIM}No models in catalog. Try '--refresh' or use a custom model name.${RESET}`);
+        const customBaseUrl = provider === "custom" ? process.env.GNOSYS_LLM_BASE_URL : undefined;
+        const { proceed, apiKey: validatedKey } = await validateModelWithKeyRotation({
+            rl,
+            provider,
+            model,
+            apiKey,
+            customBaseUrl,
+            isLocalProvider,
+            saveAnywayPrompt: "Save config anyway?",
+            saveAnywayDefault: false,
+            keyScope: "provider",
+        });
+        apiKey = validatedKey;
+        if (!proceed) {
+            printStatus("warn", "cancelled · no changes written");
             return;
         }
-        for (const t of tiers) {
-            const rec = t.recommended ? `  ${CYAN}<- recommended${RESET}` : "";
-            const price = t.input === 0 && t.output === 0
-                ? "free"
-                : `$${t.input.toFixed(2)}–$${t.output.toFixed(2)}/M`;
-            console.log(`  ${t.name.padEnd(24)} ${t.model.padEnd(40)} ${DIM}${price}${RESET}${rec}`);
+        if (keyEnteredThisRun && apiKey && !isLocalProvider) {
+            const service = apiKeyServiceName(provider, "provider");
+            await promptKeyDestinationAndPersist({
+                rl,
+                service,
+                provider,
+                key: apiKey,
+                scope: "provider",
+            });
         }
-        return;
     }
-    if (opts.set) {
-        if (!currentProvider) {
-            console.log(`${WARN} No provider configured. Run 'gnosys setup' first.`);
-            return;
-        }
-        // v5.9.4 Bug 10 — unified store resolution.
-        const storePath = ensureActiveStorePath(projectDir);
-        const existingProviderConfig = existingConfig?.llm?.[currentProvider];
-        const providerConfigBase = (typeof existingProviderConfig === "object" && existingProviderConfig !== null)
-            ? existingProviderConfig
-            : {};
-        await updateConfig(storePath, {
-            llm: {
-                ...(existingConfig?.llm ?? {}),
-                defaultProvider: currentProvider,
-                [currentProvider]: { ...providerConfigBase, model: opts.set },
+    const existingLlm = ctx.existingConfig?.llm;
+    const existingProviderConfig = existingLlm
+        ? existingLlm[provider]
+        : undefined;
+    const providerConfigBase = typeof existingProviderConfig === "object" && existingProviderConfig !== null
+        ? existingProviderConfig
+        : {};
+    await updateConfig(storePath, {
+        llm: {
+            ...(existingLlm ?? {}),
+            defaultProvider: provider,
+            [provider]: {
+                ...providerConfigBase,
+                model,
             },
-        });
-        console.log(`${CHECK} Default model set to ${GREEN}${opts.set}${RESET} for ${currentProvider}.`);
-        return;
+        },
+    });
+    const { buildModelsDiffRows } = await import("./setup/modelsRender.js");
+    console.log();
+    printDiff(buildModelsDiffRows(ctx.currentProvider, ctx.currentModel, provider, model));
+    printStatus("ok", `saved · ${storePath}/gnosys.json`);
+}
+async function runModelsTaskRoutingSetup(ctx) {
+    const { rl, opts, provider: initialProvider, dynamicModels, storePath, cfgBefore, printStatus } = ctx;
+    const tasks = ASSIGNABLE_TASK_LIST;
+    const currentByTask = {};
+    for (const task of tasks) {
+        currentByTask[task] = getAssignableRouting(cfgBefore, task);
+    }
+    const dreamEnabledBefore = !!cfgBefore.dream?.enabled;
+    console.log();
+    console.log(`${BOLD}Which tasks should use ${initialProvider}?${RESET}`);
+    console.log(`${DIM}Enter numbers (comma-separated), ${BOLD}all${RESET}${DIM}, or ${BOLD}none${RESET}${DIM}. Unlisted tasks keep their current routing.${RESET}`);
+    console.log();
+    for (let i = 0; i < tasks.length; i++) {
+        const task = tasks[i];
+        const cur = currentByTask[task];
+        const desc = TASK_DESCRIPTIONS[task] ?? "";
+        const off = task === "dream" && !dreamEnabledBefore ? `  ${DIM}[off]${RESET}` : "";
+        console.log(`  ${BOLD}${i + 1}.${RESET} ${task.padEnd(14)} ${DIM}now:${RESET} ${cur.provider} / ${cur.model}  ${DIM}(${desc})${RESET}${off}`);
+    }
+    console.log();
+    let selectedIndices = [];
+    while (true) {
+        const raw = await askInput(rl, `Tasks for ${initialProvider} (e.g. 5,6 or all)`, { default: "all" });
+        const parsed = parseCommaSeparatedTaskSelection(raw, tasks.length);
+        if (parsed === "all") {
+            selectedIndices = tasks.map((_, i) => i);
+            break;
+        }
+        if (parsed === "none") {
+            selectedIndices = [];
+            break;
+        }
+        if (parsed && parsed.length > 0) {
+            selectedIndices = parsed;
+            break;
+        }
+        console.log(`${RED}Enter numbers 1-${tasks.length}, comma-separated, or 'all'.${RESET}`);
     }
-    // No flags: show current config
-    if (!currentProvider) {
-        console.log(`${WARN} No provider configured. Run 'gnosys setup' first.`);
+    const selectedSet = new Set(selectedIndices.map((i) => tasks[i]));
+    if (selectedSet.size === 0) {
+        printStatus("warn", "no tasks selected · no changes written");
         return;
     }
-    const currentModel = existingConfig
-        ? getProviderModel(existingConfig, existingConfig.llm.defaultProvider)
-        : "";
+    const selectedTasks = [...selectedSet];
+    const keyRequirements = buildInlineKeyRequirements(selectedTasks, () => initialProvider);
+    if (keyRequirements.length > 0) {
+        console.log();
+        console.log(`  ${DIM}Keys needed for:${RESET}`);
+        for (const req of keyRequirements) {
+            const svc = apiKeyServiceName(req.provider, req.scope);
+            console.log(`  ${DIM}  all selected → ${req.provider} (${svc})${RESET}`);
+        }
+        console.log();
+    }
+    const keyCache = new Map();
+    const persistedServices = new Set();
+    const accepted = {};
+    for (const task of selectedTasks) {
+        let taskProvider = initialProvider;
+        const cur = currentByTask[task];
+        while (true) {
+            const isLocal = taskProvider === "ollama" || taskProvider === "lmstudio";
+            const showCurrent = cur.provider === taskProvider ? cur.model : undefined;
+            console.log();
+            const model = await pickModel(rl, taskProvider, dynamicModels, `Model for ${task}`, showCurrent);
+            if (!model) {
+                printStatus("fail", `no model for ${task} · skipping`);
+                accepted[task] = cur;
+                break;
+            }
+            const apiKey = await resolveKeyInMemory({
+                rl,
+                provider: taskProvider,
+                keyCache,
+            });
+            const shouldValidate = opts.validate !== false;
+            let proceed = true;
+            let validatedKey = apiKey;
+            if (shouldValidate && (apiKey || isLocal)) {
+                const customBaseUrl = taskProvider === "custom" ? process.env.GNOSYS_LLM_BASE_URL : undefined;
+                const result = await validateTaskCombo({
+                    rl,
+                    provider: taskProvider,
+                    model,
+                    apiKey,
+                    customBaseUrl,
+                    isLocalProvider: isLocal,
+                    saveAnywayPrompt: `Save ${task} routing anyway?`,
+                    saveAnywayDefault: false,
+                });
+                proceed = result.proceed;
+                validatedKey = result.apiKey;
+            }
+            if (proceed) {
+                accepted[task] = {
+                    provider: taskProvider,
+                    model,
+                };
+                if (validatedKey && !isLocal) {
+                    const service = apiKeyServiceName(taskProvider, "global");
+                    if (!persistedServices.has(service)) {
+                        await promptKeyDestinationAndPersist({
+                            rl,
+                            service,
+                            provider: taskProvider,
+                            key: validatedKey,
+                            scope: "global",
+                        });
+                        persistedServices.add(service);
+                    }
+                    keyCache.set(taskProvider, validatedKey);
+                }
+                break;
+            }
+            const retryChoice = await askChoice(rl, "Validation failed. What next?", [
+                "Pick a different provider + model",
+                "Keep provider, pick a new model",
+                "Skip this task (keep current routing)",
+            ]);
+            if (retryChoice === 0) {
+                const picked = await pickProvider(rl, dynamicModels, `Provider for ${task}`, taskProvider);
+                if (picked)
+                    taskProvider = picked;
+                continue;
+            }
+            if (retryChoice === 1) {
+                continue;
+            }
+            accepted[task] = cur;
+            break;
+        }
+    }
+    const planned = { ...currentByTask };
+    for (const task of selectedTasks) {
+        if (accepted[task])
+            planned[task] = accepted[task];
+    }
     console.log();
-    console.log(`Provider: ${GREEN}${currentProvider}${RESET}`);
-    console.log(`Model:    ${GREEN}${currentModel}${RESET}`);
+    console.log(`${BOLD}Planned task routing${RESET}`);
+    console.log(`  ${"Task".padEnd(16)}${"Provider / model".padEnd(42)}${RESET}`);
+    console.log(`  ${"\u2500".repeat(56)}`);
+    for (const task of tasks) {
+        const p = planned[task];
+        const marker = selectedSet.has(task) ? `${CYAN}*${RESET} ` : "  ";
+        const off = task === "dream" && !dreamEnabledBefore
+            ? `  ${DIM}(dream off)${RESET}`
+            : "";
+        console.log(`${marker}${task.padEnd(14)}${p.provider} / ${p.model}${off}`);
+    }
+    console.log(`${DIM}  * = changed in this run${RESET}`);
     console.log();
-    console.log(`${DIM}Use '--list' to see options, '--set <model>' to change, '--refresh' to update catalog.${RESET}`);
+    const confirmed = await askYesNo(rl, "Save this routing?", true);
+    if (!confirmed) {
+        printStatus("warn", "cancelled · no changes written");
+        return;
+    }
+    const taskModelsPatch = buildTaskModelsPatchFromAccepted(accepted, currentByTask, selectedSet);
+    let dreamPatch;
+    if (selectedSet.has("dream") && accepted.dream) {
+        dreamPatch = {
+            ...(cfgBefore.dream ?? {}),
+            provider: accepted.dream.provider,
+            model: accepted.dream.model,
+        };
+        if (!dreamEnabledBefore &&
+            (await askYesNo(rl, "Enable dream mode with this routing?", true))) {
+            dreamPatch.enabled = true;
+        }
+    }
+    const updatePayload = {};
+    if (taskModelsPatch)
+        updatePayload.taskModels = taskModelsPatch;
+    if (dreamPatch)
+        updatePayload.dream = dreamPatch;
+    if (!taskModelsPatch && !dreamPatch) {
+        printStatus("warn", "no routing changes to save");
+        return;
+    }
+    await updateConfig(storePath, updatePayload);
+    printStatus("ok", `saved task routing · ${storePath}/gnosys.json`);
 }
 /**
  * Walks the user through configuring dream mode. Handles:
@@ -2143,8 +2577,12 @@ export async function runDreamSetup(opts = {}) {
                 dream: { ...(existingDream ?? {}), enabled: false },
             });
             clearDreamMachineEverywhere();
+            const { uninstallDreamLaunchAgent } = await import("./dreamLaunchd.js");
+            const launchdPath = uninstallDreamLaunchAgent();
             console.log();
             printStatus("ok", "dream mode disabled · designation cleared");
+            if (launchdPath)
+                printStatus("ok", "launchd agent removed", launchdPath);
             localDb.close();
             remoteDb?.close();
             return;
@@ -2201,26 +2639,27 @@ export async function runDreamSetup(opts = {}) {
         }
         // Validate — animated Spinner with the model latency reported.
         if (dreamProvider !== "skip") {
-            const apiKey = await getApiKeyForProvider(dreamProvider);
+            const apiKey = await getApiKeyForProvider(dreamProvider, { task: "dream" });
             const isLocalProvider = dreamProvider === "ollama" || dreamProvider === "lmstudio";
             if (apiKey || isLocalProvider) {
                 console.log();
-                const validateSpin = Spinner(`validating ${dreamProvider} / ${dreamModel}…`);
                 try {
                     const customBaseUrl = dreamProvider === "custom" ? process.env.GNOSYS_LLM_BASE_URL : undefined;
-                    const result = await validateModel(dreamProvider, dreamModel, apiKey, { customBaseUrl });
-                    if (result.ok) {
-                        validateSpin.ok("model validated", `${result.latencyMs} ms · ${dreamProvider} / ${dreamModel}`);
-                    }
-                    else {
-                        validateSpin.fail("could not reach model", result.error);
-                        const proceed = await askYesNo(rl, "save config anyway?", true);
-                        if (!proceed) {
-                            printStatus("warn", "setup cancelled · no changes written");
-                            localDb.close();
-                            remoteDb?.close();
-                            return;
-                        }
+                    const { proceed } = await validateModelWithKeyRotation({
+                        rl,
+                        provider: dreamProvider,
+                        model: dreamModel,
+                        apiKey,
+                        customBaseUrl,
+                        isLocalProvider,
+                        saveAnywayPrompt: "save config anyway?",
+                        saveAnywayDefault: true,
+                    });
+                    if (!proceed) {
+                        printStatus("warn", "setup cancelled · no changes written");
+                        localDb.close();
+                        remoteDb?.close();
+                        return;
                     }
                 }
                 catch (err) {
@@ -2228,7 +2667,7 @@ export async function runDreamSetup(opts = {}) {
                 }
             }
             else {
-                printStatus("warn", `no API key for ${dreamProvider}`, "set one via `gnosys setup models`");
+                printStatus("warn", `no API key for ${dreamProvider}`, "set one via `gnosys setup providers`");
             }
         }
         // ─── 7.2  Thresholds + sub-tasks ───────────────────────────────────
@@ -2241,6 +2680,12 @@ export async function runDreamSetup(opts = {}) {
         const dIdle = existingDream?.idleMinutes ?? 10;
         const dRuntime = existingDream?.maxRuntimeMinutes ?? 30;
         const dMinMem = existingDream?.minMemories ?? 10;
+        const dScheduleStart = existingDream?.schedule?.startHour ?? 2;
+        const dScheduleEnd = existingDream?.schedule?.endHour ?? 5;
+        const dSystemIdle = existingDream?.systemIdleMinutes ?? 30;
+        const dMinNewMemories = existingDream?.minNewMemoriesToDream ?? 10;
+        const dMinHours = existingDream?.minHoursBetweenRuns ?? 20;
+        const dMaxCalls = existingDream?.maxLLMCallsPerRun ?? 12;
         const dSelfCritique = existingDream?.selfCritique ?? true;
         const dGenSummaries = existingDream?.generateSummaries ?? true;
         const dDiscover = existingDream?.discoverRelationships ?? true;
@@ -2257,16 +2702,34 @@ export async function runDreamSetup(opts = {}) {
         let idleMinutes = dIdle;
         let maxRuntimeMinutes = dRuntime;
         let minMemories = dMinMem;
+        let scheduleStartHour = dScheduleStart;
+        let scheduleEndHour = dScheduleEnd;
+        let systemIdleMinutes = dSystemIdle;
+        let minNewMemoriesToDream = dMinNewMemories;
+        let minHoursBetweenRuns = dMinHours;
+        let maxLLMCallsPerRun = dMaxCalls;
         let selfCritique = dSelfCritique;
         let generateSummaries = dGenSummaries;
         let discoverRelationships = dDiscover;
         if (editChoice === "e") {
             const idleAns = await askInput(rl, "idle minutes before triggering", { default: String(dIdle) });
-            idleMinutes = Math.max(1, parseInt(idleAns) || dIdle);
+            idleMinutes = Math.max(1, parseInt(idleAns, 10) || dIdle);
             const runtimeAns = await askInput(rl, "max runtime minutes", { default: String(dRuntime) });
-            maxRuntimeMinutes = Math.max(1, parseInt(runtimeAns) || dRuntime);
+            maxRuntimeMinutes = Math.max(1, parseInt(runtimeAns, 10) || dRuntime);
             const minMemAns = await askInput(rl, "minimum memories before activating", { default: String(dMinMem) });
-            minMemories = Math.max(1, parseInt(minMemAns) || dMinMem);
+            minMemories = Math.max(1, parseInt(minMemAns, 10) || dMinMem);
+            const scheduleStartAns = await askInput(rl, "night window start hour (0-23)", { default: String(dScheduleStart) });
+            scheduleStartHour = Math.min(23, Math.max(0, parseInt(scheduleStartAns, 10) || dScheduleStart));
+            const scheduleEndAns = await askInput(rl, "night window end hour (0-23)", { default: String(dScheduleEnd) });
+            scheduleEndHour = Math.min(23, Math.max(0, parseInt(scheduleEndAns, 10) || dScheduleEnd));
+            const systemIdleAns = await askInput(rl, "real machine idle minutes required", { default: String(dSystemIdle) });
+            systemIdleMinutes = Math.max(1, parseInt(systemIdleAns, 10) || dSystemIdle);
+            const minNewAns = await askInput(rl, "minimum changed memories before dreaming", { default: String(dMinNewMemories) });
+            minNewMemoriesToDream = Math.max(0, parseInt(minNewAns, 10) || dMinNewMemories);
+            const minHoursAns = await askInput(rl, "minimum hours between successful dreams", { default: String(dMinHours) });
+            minHoursBetweenRuns = Math.max(0, parseInt(minHoursAns, 10) || dMinHours);
+            const maxCallsAns = await askInput(rl, "maximum LLM calls per dream run", { default: String(dMaxCalls) });
+            maxLLMCallsPerRun = Math.max(0, parseInt(maxCallsAns, 10) || dMaxCalls);
             selfCritique = await askYesNo(rl, "self-critique (rule + LLM-based review flagging)", dSelfCritique);
             generateSummaries = await askYesNo(rl, "generate summaries (LLM)", dGenSummaries);
             discoverRelationships = await askYesNo(rl, "discover relationships (LLM)", dDiscover);
@@ -2281,6 +2744,11 @@ export async function runDreamSetup(opts = {}) {
                 minMemories,
                 provider: dreamProvider,
                 model: dreamModel || undefined,
+                schedule: { startHour: scheduleStartHour, endHour: scheduleEndHour },
+                systemIdleMinutes,
+                minNewMemoriesToDream,
+                minHoursBetweenRuns,
+                maxLLMCallsPerRun,
                 selfCritique,
                 generateSummaries,
                 discoverRelationships,
@@ -2289,6 +2757,8 @@ export async function runDreamSetup(opts = {}) {
         // Reset consecutive failure counter on a fresh setup so Layer 4
         // doesn't fire immediately based on stale history.
         localDb.resetDreamConsecutiveFailures();
+        const { installDreamLaunchAgent } = await import("./dreamLaunchd.js");
+        const launchdPath = installDreamLaunchAgent();
         localDb.close();
         remoteDb?.close();
         // Final Diff block per the design — provider/machine + the two
@@ -2316,7 +2786,9 @@ export async function runDreamSetup(opts = {}) {
             discoverRelationships,
         }));
         const dreamerName = designate ? localMachine : (designatedMachine ?? "the designated machine");
-        printStatus("progress", `first cycle runs after ${dreamerName} is idle for ${idleMinutes} min`);
+        printStatus("progress", `scheduled dream checks run nightly (${scheduleStartHour}:00-${scheduleEndHour}:00) on ${dreamerName}`);
+        if (launchdPath)
+            printStatus("ok", "launchd agent installed", launchdPath);
         printStatus("progress", "check status anytime with `gnosys status --system`");
     }
     finally {
@@ -2379,29 +2851,17 @@ async function openRemoteDbIfConfigured(localDb) {
  * Best-effort lookup of the API key for a provider. Used by the dream setup
  * wizard to power the validation step. Mirrors the resolveApiKey precedence.
  */
-export async function getApiKeyForProvider(provider) {
-    if (provider === "ollama" || provider === "lmstudio" || provider === "skip")
+export async function getApiKeyForProvider(provider, opts) {
+    if (provider === "ollama" || provider === "lmstudio" || provider === "skip") {
         return "";
-    const envVarName = provider === "custom" ? "GNOSYS_CUSTOM_KEY" : `GNOSYS_${provider.toUpperCase()}_KEY`;
-    const legacyVars = {
-        anthropic: "ANTHROPIC_API_KEY",
-        openai: "OPENAI_API_KEY",
-        groq: "GROQ_API_KEY",
-        xai: "XAI_API_KEY",
-        mistral: "MISTRAL_API_KEY",
-    };
-    const fromEnv = process.env[envVarName] || (legacyVars[provider] && process.env[legacyVars[provider]]) || "";
-    if (fromEnv)
-        return fromEnv;
-    if (process.platform === "darwin") {
-        try {
-            return execSync(`security find-generic-password -a "$USER" -s "${envVarName}" -w 2>/dev/null`, {
-                stdio: "pipe", encoding: "utf-8", timeout: 2000,
-            }).trim();
-        }
-        catch {
-            // fall through
+    }
+    if (opts?.directory) {
+        const cfg = await loadExistingConfig(opts.directory);
+        if (cfg) {
+            const fromCfg = getApiKeyForProviderFromConfig(cfg, provider);
+            if (fromCfg)
+                return fromCfg;
         }
     }
-    return "";
+    return readFirstInChain(provider) ?? "";
 }