muonroi-cli 1.8.4 → 1.9.0

package/dist/src/cli/keys.js

@@ -1,26 +1,19 @@
 /**
  * `muonroi-cli keys` subcommand group.
  *
- * Manages provider API keys via the OS keychain (Windows Credential Manager,
- * macOS Keychain, libsecret on Linux via keytar). Keys are read by the CLI through the
- * keychain → env → settings.json priority chain in providers/keychain.ts.
- *
- * On Linux without libsecret + an active secret service (gnome-keyring etc.),
- * or in headless sessions, keychain writes return false and callers fall back
- * to advising environment variables (which are still honored at runtime).
+ * Manages provider API keys via the env-store. Keys are read by the CLI through
+ * the env-store → env → settings.json priority chain in providers/keychain.ts.
  *
  * Subcommands:
- *   keys set <provider>           — interactive prompt, stores in keychain
+ *   keys set <provider>           — interactive prompt, stores the key
  *   keys list                     — show masked keys currently stored
  *   keys delete <provider>        — remove a stored key
- *   keys import-bw [providers]    — pull from Bitwarden vault, store in keychain
- *   keys cleanup-settings         — strip plaintext keys from user-settings.json
- *   keys login <provider>         — OAuth login (openai, google/agy)
- *   keys logout <provider>        — OAuth logout (openai, google/agy)
+ *   keys export <file>            — export keys to an encrypted portable bundle
+ *   keys import <file>            — import an encrypted bundle
+ *   keys login <provider>         — OAuth login (openai, xai)
+ *   keys logout <provider>        — OAuth logout (openai, xai)
  */
-import { spawnSync } from "node:child_process";
 import { promises as fs } from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
 import { getChatSecret, listChatSecrets, setChatSecret } from "../chat/chat-keychain.js";
 import { setMcpKey } from "../mcp/mcp-keychain.js";
@@ -39,11 +32,6 @@ const MCP_KEY_IDS = ["tavily"];
 function isMcpKeyId(value) {
     return MCP_KEY_IDS.includes(value);
 }
-const CHAT_SECRET_IDS = ["discord-token", "discord-guild-id", "slack-token", "slack-team-id"];
-function isChatSecretId(value) {
-    return CHAT_SECRET_IDS.includes(value);
-}
-const SETTINGS_PATH = path.join(os.homedir(), ".muonroi-cli", "user-settings.json");
 function maskKey(key) {
     if (key.length <= 10)
         return "***";
@@ -51,8 +39,6 @@ function maskKey(key) {
 }
 function normalizeProvider(p) {
     const lower = p.toLowerCase();
-    if (lower === "agy")
-        return "google"; // agy is alias for google (OAuth + key)
     if (KEYCHAIN_PROVIDER_IDS.includes(lower)) {
         return lower;
     }
@@ -112,10 +98,10 @@ async function promptHidden(question) {
         process.stdin.on("data", onData);
     });
 }
-export async function runKeysSet(provider, options = {}) {
+export async function runKeysSet(provider, _options = {}) {
     const norm = normalizeProvider(provider);
     if (!norm) {
-        console.error(`Unknown provider '${provider}'. Valid: ${KEYCHAIN_PROVIDER_IDS.join(", ")} (agy is alias for google)`);
+        console.error(`Unknown provider '${provider}'. Valid: ${KEYCHAIN_PROVIDER_IDS.join(", ")}`);
         process.exit(1);
     }
     const key = (await promptHidden(`Paste ${provider} API key (hidden): `)).trim();
@@ -123,16 +109,6 @@ export async function runKeysSet(provider, options = {}) {
         console.error("Aborted (empty key).");
         process.exit(1);
     }
-    if (options.bw) {
-        const { writeBwSecureNote } = await import("./bw-vault.js");
-        const itemName = `${options.itemPrefix ?? "muonroi-cli/"}${provider}`;
-        const res = await writeBwSecureNote(itemName, key);
-        if (!res.ok) {
-            console.error(`Bitwarden write failed: ${res.error}`);
-            process.exit(2);
-        }
-        console.log(`Bitwarden vault: ${res.action} '${itemName}'.`);
-    }
     try {
         const ok = await setKeyForProvider(norm, key);
         if (!ok) {
@@ -152,7 +128,7 @@ export async function runKeysSet(provider, options = {}) {
         process.exit(1);
     }
 }
-export async function runMcpKeysSet(id, options = {}) {
+export async function runMcpKeysSet(id, _options = {}) {
     if (!isMcpKeyId(id)) {
         console.error(`Unknown MCP key '${id}'. Valid: ${MCP_KEY_IDS.join(", ")}`);
         process.exit(1);
@@ -162,16 +138,6 @@ export async function runMcpKeysSet(id, options = {}) {
         console.error("Aborted (empty key).");
         process.exit(1);
     }
-    if (options.bw) {
-        const { writeBwSecureNote } = await import("./bw-vault.js");
-        const itemName = `${options.itemPrefix ?? "muonroi-cli/"}${id}`;
-        const res = await writeBwSecureNote(itemName, key);
-        if (!res.ok) {
-            console.error(`Bitwarden write failed: ${res.error}`);
-            process.exit(2);
-        }
-        console.log(`Bitwarden vault: ${res.action} '${itemName}'.`);
-    }
     try {
         const ok = await setMcpKey(id, key);
         if (!ok) {
@@ -199,30 +165,11 @@ export async function runKeysList() {
     const oauthIds = await getOAuthProviderIds();
     for (const p of oauthIds) {
         try {
-            let tokens = await loadTokens(p);
-            if (!tokens && p === "google") {
-                // Import from agy storage only for fresh (non-expired) tokens.
-                // Stale agy tokens should be cleaned by running `keys logout google` + removing old .gemini file.
-                const { loadAgyTokensWithRefresh } = await import("../providers/auth/gemini-oauth.js");
-                const agyTokens = await loadAgyTokensWithRefresh();
-                if (agyTokens && Date.now() < agyTokens.expiresAt) {
-                    tokens = agyTokens;
-                }
-            }
-            if (tokens) {
-                if (Date.now() < tokens.expiresAt) {
-                    const cfg = await getOAuthProviderConfig(p);
-                    const display = cfg?.displayName ?? p;
-                    oauthRows.push({ provider: p, display, email: tokens.email, expiresAt: tokens.expiresAt });
-                }
-                else if (p === "google") {
-                    // auto-clean stale Agy token from our store (imported from old ~/.gemini)
-                    try {
-                        const { deleteTokens } = await import("../providers/auth/token-store.js");
-                        await deleteTokens("google");
-                    }
-                    catch { }
-                }
+            const tokens = await loadTokens(p);
+            if (tokens && Date.now() < tokens.expiresAt) {
+                const cfg = await getOAuthProviderConfig(p);
+                const display = cfg?.displayName ?? p;
+                oauthRows.push({ provider: p, display, email: tokens.email, expiresAt: tokens.expiresAt });
             }
         }
         catch {
@@ -232,9 +179,8 @@ export async function runKeysList() {
     const hasAnything = stored.length > 0 || chatStored.length > 0 || oauthRows.length > 0;
     if (!hasAnything) {
         console.log("No keys stored in OS keychain.");
-        console.log("Run 'muonroi-cli keys set <provider>' or 'muonroi-cli keys import-bw' to add some.");
+        console.log("Run 'muonroi-cli keys set <provider>' to add some.");
         console.log("Run 'muonroi-cli keys login openai' to log in with your OpenAI subscription.");
-        console.log("Run 'muonroi-cli keys login google' or 'keys login agy' to log in with Agy (Google OAuth).");
         console.log("Run 'muonroi-cli keys login xai' to log in with your SuperGrok / X Premium+ subscription.");
         return;
     }
@@ -288,35 +234,11 @@ export async function runKeysList() {
 export async function runKeysDelete(provider) {
     const norm = normalizeProvider(provider);
     if (!norm) {
-        console.error(`Unknown provider '${provider}'. Valid: ${KEYCHAIN_PROVIDER_IDS.join(", ")} (agy is alias for google)`);
+        console.error(`Unknown provider '${provider}'. Valid: ${KEYCHAIN_PROVIDER_IDS.join(", ")}`);
         process.exit(1);
     }
     const ok = await deleteKeyForProvider(norm);
     console.log(ok ? `Deleted ${provider} key from keychain.` : `No ${provider} key was stored.`);
-    // If deleting google/agy, also clean the OAuth token (Agy uses the google slot for its OAuth)
-    if (norm === "google") {
-        try {
-            const { loadTokens, deleteTokens } = await import("../providers/auth/token-store.js");
-            const { getOAuthProviderConfig } = await import("../providers/auth/registry.js");
-            const tokens = await loadTokens("google");
-            if (tokens) {
-                const cfg = await getOAuthProviderConfig("google");
-                if (cfg?.provider) {
-                    try {
-                        await cfg.provider.revoke(tokens);
-                    }
-                    catch {
-                        // best effort
-                    }
-                }
-                await deleteTokens("google");
-                console.log(`Also cleared Agy/Google OAuth token.`);
-            }
-        }
-        catch {
-            // ignore secondary errors
-        }
-    }
 }
 export async function runKeysExport(filePath) {
     const providers = {};
@@ -411,161 +333,6 @@ export async function runKeysImport(filePath) {
     }
     console.log(`\nImported ${imported} key(s); ${skipped} skipped.`);
 }
-export async function runKeysImportBw(opts = {}) {
-    const which = spawnSync("bw", ["--version"], { encoding: "utf8" });
-    if (which.status !== 0) {
-        console.error("Bitwarden CLI ('bw') not found in PATH.");
-        console.error("Install: https://bitwarden.com/help/cli/");
-        process.exit(2);
-    }
-    const session = process.env.BW_SESSION;
-    if (!session) {
-        console.error("BW_SESSION not set. Run:");
-        console.error("  export BW_SESSION=$(bw unlock --raw)");
-        process.exit(2);
-    }
-    const status = spawnSync("bw", ["status", "--session", session], { encoding: "utf8" });
-    if (status.status !== 0) {
-        console.error(`bw status failed: ${status.stderr || status.stdout}`);
-        process.exit(2);
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(status.stdout);
-    }
-    catch {
-        parsed = {};
-    }
-    if (parsed.status !== "unlocked") {
-        console.error(`Bitwarden vault is not unlocked (status: ${parsed.status ?? "unknown"}).`);
-        console.error("Run: export BW_SESSION=$(bw unlock --raw)");
-        process.exit(2);
-    }
-    const requested = opts.providers && opts.providers.length > 0 ? opts.providers : KEYCHAIN_PROVIDER_IDS.slice();
-    const prefix = opts.itemPrefix ?? "muonroi-cli/";
-    let imported = 0;
-    let skipped = 0;
-    for (const provider of requested) {
-        const norm = normalizeProvider(provider);
-        if (!norm) {
-            console.warn(`Skip unknown provider: ${provider}`);
-            skipped++;
-            continue;
-        }
-        const itemName = `${prefix}${provider}`;
-        const got = spawnSync("bw", ["get", "notes", itemName, "--session", session], { encoding: "utf8" });
-        if (got.status !== 0) {
-            // bw prints "Not found." on stderr when the item is missing — treat as skip.
-            skipped++;
-            continue;
-        }
-        const key = got.stdout.trim();
-        if (!key || key.length < 20) {
-            console.warn(`Skip ${provider}: vault item '${itemName}' empty or too short.`);
-            skipped++;
-            continue;
-        }
-        try {
-            const ok = await setKeyForProvider(norm, key);
-            if (!ok) {
-                console.warn(`! ${provider} — OS keychain unavailable (keytar or secret service backend).`);
-                console.warn("  Linux fix: sudo dnf install libsecret   (Fedora)  or  sudo apt-get install libsecret-1-0 (Ubuntu)");
-                console.warn(`  Fallback (works at runtime): export ${provider.toUpperCase()}_API_KEY=...`);
-                skipped++;
-            }
-            else {
-                console.log(`Imported ${provider} → keychain.`);
-                imported++;
-            }
-        }
-        catch (e) {
-            console.warn(`Failed ${provider}: ${e.message}`);
-            skipped++;
-        }
-    }
-    console.log(`\nDone. Imported: ${imported}, skipped: ${skipped}.`);
-    if (imported > 0) {
-        console.log("Run 'muonroi-cli keys cleanup-settings' to strip any plaintext keys from settings.json.");
-    }
-}
-/**
- * Import MCP secrets (e.g. Tavily) from a Bitwarden vault into the OS
- * keychain via mcp-keychain. Vault items are expected at `<prefix><id>` —
- * default prefix `muonroi-cli/`. The key value is read from the item's
- * notes field, mirroring the provider import-bw flow.
- */
-export async function runMcpImportBw(opts = {}) {
-    const which = spawnSync("bw", ["--version"], { encoding: "utf8" });
-    if (which.status !== 0) {
-        console.error("Bitwarden CLI ('bw') not found in PATH.");
-        console.error("Install: https://bitwarden.com/help/cli/");
-        process.exit(2);
-    }
-    const session = process.env.BW_SESSION;
-    if (!session) {
-        console.error("BW_SESSION not set. Run:");
-        console.error("  export BW_SESSION=$(bw unlock --raw)");
-        process.exit(2);
-    }
-    const status = spawnSync("bw", ["status", "--session", session], { encoding: "utf8" });
-    if (status.status !== 0) {
-        console.error(`bw status failed: ${status.stderr || status.stdout}`);
-        process.exit(2);
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(status.stdout);
-    }
-    catch {
-        parsed = {};
-    }
-    if (parsed.status !== "unlocked") {
-        console.error(`Bitwarden vault is not unlocked (status: ${parsed.status ?? "unknown"}).`);
-        console.error("Run: export BW_SESSION=$(bw unlock --raw)");
-        process.exit(2);
-    }
-    const requested = opts.keys && opts.keys.length > 0 ? opts.keys : MCP_KEY_IDS.slice();
-    const prefix = opts.itemPrefix ?? "muonroi-cli/";
-    let imported = 0;
-    let skipped = 0;
-    for (const id of requested) {
-        if (!isMcpKeyId(id)) {
-            console.warn(`Skip unknown MCP key: ${id}`);
-            skipped++;
-            continue;
-        }
-        const itemName = `${prefix}${id}`;
-        const got = spawnSync("bw", ["get", "notes", itemName, "--session", session], { encoding: "utf8" });
-        if (got.status !== 0) {
-            skipped++;
-            continue;
-        }
-        const key = got.stdout.trim();
-        if (!key || key.length < 16) {
-            console.warn(`Skip ${id}: vault item '${itemName}' empty or too short.`);
-            skipped++;
-            continue;
-        }
-        try {
-            const ok = await setMcpKey(id, key);
-            if (!ok) {
-                console.warn(`! ${id} — OS keychain unavailable (keytar or secret service backend).`);
-                console.warn("  Linux fix: sudo dnf install libsecret   (Fedora)  or  sudo apt-get install libsecret-1-0 (Ubuntu)");
-                console.warn(`  Fallback (works at runtime): export ${id.toUpperCase()}_API_KEY=...`);
-                skipped++;
-            }
-            else {
-                console.log(`Imported MCP key '${id}' → keychain.`);
-                imported++;
-            }
-        }
-        catch (e) {
-            console.warn(`Failed ${id}: ${e.message}`);
-            skipped++;
-        }
-    }
-    console.log(`\nDone. Imported: ${imported}, skipped: ${skipped}.`);
-}
 export async function runChatKeySet(id, value) {
     if (!value || value.length < 8) {
         console.error(`Value for chat secret '${id}' is too short (< 8 chars).`);
@@ -586,85 +353,6 @@ export async function runChatKeySet(id, value) {
         process.exit(1);
     }
 }
-/**
- * Import chat secrets (discord-token, discord-guild-id, slack-token, slack-team-id)
- * from a Bitwarden vault into the OS keychain. Vault items are expected at
- * `<prefix><id>` — default prefix `muonroi-cli/chat-`. The value is read from
- * the item's notes field, mirroring the provider/MCP import-bw flow.
- */
-export async function runChatImportBw(opts = {}) {
-    const which = spawnSync("bw", ["--version"], { encoding: "utf8" });
-    if (which.status !== 0) {
-        console.error("Bitwarden CLI ('bw') not found in PATH.");
-        console.error("Install: https://bitwarden.com/help/cli/");
-        process.exit(2);
-    }
-    const session = process.env.BW_SESSION;
-    if (!session) {
-        console.error("BW_SESSION not set. Run:");
-        console.error("  export BW_SESSION=$(bw unlock --raw)");
-        process.exit(2);
-    }
-    const status = spawnSync("bw", ["status", "--session", session], { encoding: "utf8" });
-    if (status.status !== 0) {
-        console.error(`bw status failed: ${status.stderr || status.stdout}`);
-        process.exit(2);
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(status.stdout);
-    }
-    catch {
-        parsed = {};
-    }
-    if (parsed.status !== "unlocked") {
-        console.error(`Bitwarden vault is not unlocked (status: ${parsed.status ?? "unknown"}).`);
-        console.error("Run: export BW_SESSION=$(bw unlock --raw)");
-        process.exit(2);
-    }
-    const requested = opts.ids && opts.ids.length > 0 ? opts.ids : CHAT_SECRET_IDS.slice();
-    const prefix = opts.itemPrefix ?? "muonroi-cli/chat-";
-    let imported = 0;
-    let skipped = 0;
-    for (const id of requested) {
-        if (!isChatSecretId(id)) {
-            console.warn(`Skip unknown chat secret: ${id}`);
-            skipped++;
-            continue;
-        }
-        const itemName = `${prefix}${id}`;
-        const got = spawnSync("bw", ["get", "notes", itemName, "--session", session], { encoding: "utf8" });
-        if (got.status !== 0) {
-            // bw prints "Not found." on stderr when the item is missing — treat as skip.
-            skipped++;
-            continue;
-        }
-        const value = got.stdout.trim();
-        if (!value || value.length < 8) {
-            console.warn(`Skip ${id}: vault item '${itemName}' empty or too short.`);
-            skipped++;
-            continue;
-        }
-        try {
-            const ok = await setChatSecret(id, value);
-            if (!ok) {
-                console.warn(`! ${id} — OS keychain unavailable (keytar or secret service backend).`);
-                console.warn("  Linux fix: sudo dnf install libsecret   (Fedora)  or  sudo apt-get install libsecret-1-0 (Ubuntu)");
-                console.warn(`  Fallback (works at runtime): export ${id.includes("token") ? "MUONROI_" : "MUONROI_"}${id.replace("-", "_").toUpperCase()}=...`);
-                skipped++;
-            }
-            else {
-                console.log(`Imported chat secret '${id}' → keychain.`);
-                imported++;
-            }
-        }
-        catch (e) {
-            console.warn(`Failed ${id}: ${e.message}`);
-            skipped++;
-        }
-    }
-    console.log(`\nDone. Imported: ${imported}, skipped: ${skipped}.`);
-}
 // ---------------------------------------------------------------------------
 // OAuth login / logout
 // ---------------------------------------------------------------------------
@@ -679,9 +367,9 @@ export async function runChatImportBw(opts = {}) {
  */
 export async function runKeysLogin(provider) {
     const oauthIds = await getOAuthProviderIds();
-    const norm = provider.toLowerCase() === "agy" ? "google" : provider;
+    const norm = provider;
     if (!oauthIds.includes(norm)) {
-        const supported = oauthIds.map((id) => (id === "google" ? "google (or agy)" : id)).join(", ");
+        const supported = oauthIds.join(", ");
         console.error(`OAuth login not supported for '${provider}'. Supported: ${supported}`);
         process.exit(1);
     }
@@ -693,22 +381,6 @@ export async function runKeysLogin(provider) {
         process.exit(1);
     }
     const name = cfg.displayName;
-    // Special handling for google: prefer importing/reusing token from agy local config
-    // (~/.gemini/oauth_creds.json) so existing agy login "just works" without browser.
-    if (provider === "google") {
-        const { loadAgyTokensWithRefresh } = await import("../providers/auth/gemini-oauth.js");
-        const existing = await loadAgyTokensWithRefresh();
-        if (existing?.accessToken) {
-            console.log(`Found existing agy token for ${existing.email || "(no email)"}.`);
-            console.log("Reusing it (refreshed if near expiry). No browser needed.");
-            const expiry = new Date(existing.expiresAt).toLocaleString();
-            const isExpired = Date.now() > existing.expiresAt;
-            console.log(`Token expires: ${expiry}${isExpired ? " (was expired, refresh attempted)" : ""}`);
-            console.log("Run 'muonroi-cli keys list' to verify.");
-            return;
-        }
-        // No existing agy token — fall through to normal browser flow (using agy client)
-    }
     console.log(`Logging in to ${name} via OAuth...`);
     console.log("A browser window will open. Complete the sign-in to continue.");
     const tokens = await cfg.provider.login({
@@ -729,6 +401,16 @@ export async function runKeysLogin(provider) {
         },
     });
     await saveTokens(norm, tokens);
+    // One auth mode per provider (OAuth XOR API key): logging in via OAuth clears
+    // any stored API key for this provider so a stale key can never shadow OAuth.
+    try {
+        const { clearEnvVar } = await import("../providers/env-store.js");
+        const { ENV_BY_PROVIDER } = await import("../providers/keychain.js");
+        clearEnvVar(ENV_BY_PROVIDER[norm]);
+    }
+    catch (err) {
+        console.error(`[keys] failed to clear API key after OAuth login for ${norm}: ${err instanceof Error ? err.message : String(err)}`);
+    }
     const emailDisplay = tokens.email ? ` (${tokens.email})` : "";
     const expiry = new Date(tokens.expiresAt).toLocaleString();
     console.log(`\nLogged in to ${name}${emailDisplay}. Token expires: ${expiry}`);
@@ -742,9 +424,9 @@ export async function runKeysLogin(provider) {
  */
 export async function runKeysLogout(provider) {
     const oauthIds = await getOAuthProviderIds();
-    const norm = provider.toLowerCase() === "agy" ? "google" : provider;
+    const norm = provider;
     if (!oauthIds.includes(norm)) {
-        const supported = oauthIds.map((id) => (id === "google" ? "google (or agy)" : id)).join(", ");
+        const supported = oauthIds.join(", ");
         console.error(`OAuth logout not supported for '${provider}'. Supported: ${supported}`);
         process.exit(1);
     }
@@ -763,54 +445,4 @@ export async function runKeysLogout(provider) {
     const name = cfg?.displayName ?? provider;
     console.log(`Logged out of ${name}. OAuth tokens revoked and deleted.`);
 }
-export async function runKeysCleanupSettings() {
-    let raw;
-    try {
-        raw = await fs.readFile(SETTINGS_PATH, "utf8");
-    }
-    catch (e) {
-        if (e.code === "ENOENT") {
-            console.log("No user-settings.json found — nothing to clean.");
-            return;
-        }
-        throw e;
-    }
-    let json;
-    try {
-        json = JSON.parse(raw);
-    }
-    catch {
-        console.error(`Settings file is not valid JSON: ${SETTINGS_PATH}`);
-        process.exit(1);
-    }
-    const ts = new Date().toISOString().replace(/[:.]/g, "-");
-    const backup = `${SETTINGS_PATH}.bak.${ts}`;
-    await fs.writeFile(backup, raw, "utf8");
-    let removed = 0;
-    if ("apiKey" in json) {
-        delete json.apiKey;
-        removed++;
-    }
-    if (json.providers && typeof json.providers === "object") {
-        const providers = json.providers;
-        for (const [name, block] of Object.entries(providers)) {
-            if (block && "apiKey" in block) {
-                delete block.apiKey;
-                removed++;
-                if (Object.keys(block).length === 0) {
-                    delete providers[name];
-                }
-            }
-        }
-        if (Object.keys(providers).length === 0) {
-            delete json.providers;
-        }
-    }
-    await fs.writeFile(SETTINGS_PATH, `${JSON.stringify(json, null, 2)}\n`, "utf8");
-    console.log(`Backed up to: ${backup}`);
-    console.log(`Removed ${removed} plaintext key field(s) from: ${SETTINGS_PATH}`);
-    if (removed === 0) {
-        console.log("(File was already clean.)");
-    }
-}
 //# sourceMappingURL=keys.js.map

package/dist/src/council/clarifier.d.ts

@@ -46,6 +46,7 @@ export declare function judgeReadiness(spec: ClarifiedSpec, topic: string, qa: A
     confidence: number;
     gaps: string[];
 }>;
+export declare function resolveInterviewLanguage(topic: string): string;
 export interface ClarifyOptionsResult {
     options: CouncilQuestionOption[];
     /**
@@ -68,7 +69,28 @@ export interface ClarifyOptionsResult {
  * returned `defaultIndex` points to it. Otherwise `defaultIndex` is omitted
  * so the UI knows to suppress the "(Recommended)" tag.
  */
-export declare function buildClarifyOptions(suggestions: string[] | undefined, recommended?: string): ClarifyOptionsResult;
+export declare function buildClarifyOptions(suggestions: string[] | undefined, recommended?: string, lang?: string): ClarifyOptionsResult;
+/**
+ * Model-designed option object: a choice the user picks between, carrying its
+ * own explanation. `recommended:true` marks the pre-selected default. This is
+ * the richer shape the clarifier prompt now asks for so every choice shows a
+ * per-option "why" (not just the question-level `why`).
+ */
+export interface ClarifyOptionSpec {
+    label: string;
+    description?: string;
+    recommended?: boolean;
+}
+/**
+ * Build council options from the model's richer `{label, description,
+ * recommended}` objects, preserving each choice's explanation as `description`
+ * and pointing `defaultIndex` at the option the model flagged `recommended`
+ * (falling back to the first when none is flagged). The same "Type something" /
+ * "Chat about this" escape-hatches are appended as in `buildClarifyOptions`.
+ * Pure + exported for unit testing.
+ */
+export declare function buildClarifyOptionsRich(specs: ClarifyOptionSpec[] | undefined, lang?: string): ClarifyOptionsResult;
+export declare function researchScopeForClarification(topic: string, conversationContext: string, leaderModelId: string, llm: CouncilLLM, signal: AbortSignal | undefined, reachableModels: string[]): AsyncGenerator<StreamChunk, string, unknown>;
 export declare function runClarification(topic: string, leaderModelId: string, conversationContext: string, respondToQuestion: QuestionResponder, llm: CouncilLLM, signal?: AbortSignal, seedQuestions?: GrayAreaQuestion[], maxRounds?: number, 
 /**
  * Optional pre-filled answers keyed by seed-question id. When the loop's
@@ -83,5 +105,11 @@ prefillAnswers?: Map<string, string>,
  * a cheaper tier model on the same provider as the leader. Falls back to
  * the leader model if no cheaper model is cataloged. Default false.
  */
-costAware?: boolean): AsyncGenerator<StreamChunk, ClarifiedSpec, unknown>;
-export declare function buildSpecFromTopic(topic: string, _conversationContext: string): ClarifiedSpec;
+costAware?: boolean, 
+/**
+ * Healthy panel models to fall back to when the leader's cost-tier spec-synth
+ * model is on a failing proxy — keeps the spec's ≥3 observable criteria (and
+ * thus a meaningful leader eval) instead of degrading to one generic criterion.
+ */
+fallbackModels?: string[]): AsyncGenerator<StreamChunk, ClarifiedSpec, unknown>;
+export declare function buildSpecFromTopic(topic: string, conversationContext: string): ClarifiedSpec;