@phuetz/code-buddy 1.0.0 → 1.2.0

package/dist/index.js

@@ -24,6 +24,7 @@ process.env.CODEBUDDY_CLI_VERSION = packageJson.version;
 import { logger } from "./utils/logger.js";
 // Import graceful shutdown for clean application termination
 import { initializeGracefulShutdown, getShutdownManager, } from "./utils/graceful-shutdown.js";
+import { sweepStaleCodebuddyTemp } from "./utils/disk-guard.js";
 /**
  * CLI output helper.
  *
@@ -165,6 +166,10 @@ const _shutdownManager = initializeGracefulShutdown({
     forceExitOnTimeout: true,
     showProgress: true,
 });
+// Startup janitor: remove our own stale /tmp scratch dirs left by crashed or
+// SIGKILL'd runs (the durable backstop for the disk-leak class that caused the
+// 2026-06-17 ENOSPC — see src/utils/disk-guard.ts). Age-gated; never throws.
+sweepStaleCodebuddyTemp();
 // Note: SIGINT, SIGTERM, SIGHUP are now handled by GracefulShutdownManager
 // The manager will:
 // 1. Wait for pending operations to complete
@@ -352,11 +357,94 @@ async function getDetectedProvider() {
         return cachedProvider;
     await ensureEnvLoaded();
     cachedProvider = detectProviderFromEnv();
+    // xAI subscription login (`buddy login xai`). Token load + refresh is async,
+    // so it can't live in the sync env detector. A valid login takes precedence
+    // over an ambient local/env provider (mirrors ChatGPT-login precedence) — but
+    // ONLY when the token actually resolves, so a stale login never strands a
+    // working provider. Without this, `buddy login xai` stored tokens the runtime
+    // never consumed.
+    {
+        const xaiOverride = process.env.CODEBUDDY_PROVIDER?.toLowerCase();
+        const xaiWanted = xaiOverride === 'xai' ||
+            (!xaiOverride &&
+                cachedProvider?.provider !== 'chatgpt' &&
+                !process.env.GROK_API_KEY &&
+                !process.env.XAI_API_KEY);
+        if (xaiWanted) {
+            try {
+                const { hasXaiCredentials, getValidXaiAccessToken } = await import('./providers/xai-oauth.js');
+                if (hasXaiCredentials()) {
+                    const token = await getValidXaiAccessToken();
+                    if (token) {
+                        cachedProvider = {
+                            provider: 'grok',
+                            apiKey: token,
+                            baseURL: 'https://api.x.ai/v1',
+                            // grok-4-latest is an alias of the current flagship grok-4.3
+                            // (verified accessible on the SuperGrok plan; Hermes defaults here too).
+                            defaultModel: process.env.GROK_MODEL || 'grok-4-latest',
+                        };
+                    }
+                    else {
+                        logger.warn('xAI login found but no valid access token — run `buddy login xai` again.');
+                    }
+                }
+            }
+            catch (err) {
+                logger.debug('xAI login resolution skipped', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    }
+    // Honor an onboarded LOCAL provider (Ollama / LM Studio) persisted to
+    // user-settings.json by `buddy onboard`. Env detection only inspects
+    // OLLAMA_HOST/oauth files, so a user who completed the wizard and picked
+    // Ollama would otherwise dead-end on "No provider configured" on the next
+    // run — local providers legitimately carry no API key, so the guard that
+    // keys off apiKey presence misfires. Cloud/env providers are matched first
+    // above, so this only triggers when nothing else resolved.
+    if (!cachedProvider) {
+        cachedProvider = await detectOnboardedLocalProvider();
+    }
     if (cachedProvider) {
         logger.info(`Auto-detected provider: ${cachedProvider.provider} (model: ${cachedProvider.defaultModel})`);
     }
     return cachedProvider;
 }
+/**
+ * Resolve an onboarded local provider (Ollama / LM Studio) from
+ * user-settings.json. Returns a detection with a placeholder API key (local
+ * OpenAI-compatible servers ignore it) so the downstream "no provider" guard
+ * passes and the persisted baseURL/model are used.
+ */
+async function detectOnboardedLocalProvider() {
+    try {
+        const getSettingsManager = await lazyImport.settingsManager();
+        const settings = getSettingsManager().loadUserSettings();
+        const provider = (settings.provider || '').toLowerCase();
+        if (provider !== 'ollama' && provider !== 'lmstudio')
+            return null;
+        const fallbackBase = provider === 'ollama'
+            ? 'http://localhost:11434/v1'
+            : 'http://localhost:1234/v1';
+        const baseURL = settings.baseURL || fallbackBase;
+        // Mirror the env path so anything else reading OLLAMA_HOST stays consistent.
+        if (provider === 'ollama' && !process.env.OLLAMA_HOST) {
+            process.env.OLLAMA_HOST = baseURL.replace(/\/v1\/?$/, '');
+        }
+        return {
+            provider: provider,
+            apiKey: provider, // placeholder — ignored by local OpenAI-compat servers
+            baseURL,
+            defaultModel: settings.model || (provider === 'ollama' ? 'llama3' : 'default'),
+            source: 'environment',
+        };
+    }
+    catch {
+        return null;
+    }
+}
 // Load API key from environment, secure storage, or legacy settings
 async function loadApiKey() {
     await ensureEnvLoaded();
@@ -426,28 +514,77 @@ async function loadModel() {
     // 1. Explicit env var takes highest priority
     if (process.env.GROK_MODEL)
         return process.env.GROK_MODEL;
-    // 2. Project/user settings override auto-detection
+    const detected = await getDetectedProvider();
+    // 2. Project/user settings override auto-detection — UNLESS the saved model is
+    //    incompatible with the detected provider. A `gpt-5.5` left in settings.json
+    //    would 404 against xAI after `buddy login xai`; prefer the Grok default then.
     try {
         const getSettingsManager = await lazyImport.settingsManager();
-        const manager = getSettingsManager();
-        const settingsModel = manager.getCurrentModel();
-        if (settingsModel)
-            return settingsModel;
+        const settingsModel = getSettingsManager().getCurrentModel();
+        if (settingsModel) {
+            const grokProvider = detected?.provider === 'grok';
+            if (!grokProvider || /grok/i.test(settingsModel)) {
+                return settingsModel;
+            }
+        }
     }
     catch (_err) {
         logger.debug('Failed to load model from settings manager', { error: _err });
     }
     // 3. Fallback to auto-detected provider's default model
-    const detected = await getDetectedProvider();
     if (detected)
         return detected.defaultModel;
     return undefined;
 }
+/**
+ * Active-LLM auto-failover. When `[llm] enabled` (or CODEBUDDY_LLM_FAILOVER=1),
+ * build the registry of the user's live logins and inject it into the agent's
+ * client fallback list — so a failing primary transparently fails over to the
+ * next active LLM (resilience order by default: capable/subscription first,
+ * local last). OFF by default → single-provider behavior is unchanged.
+ */
+async function applyActiveLlmFailover(agent) {
+    try {
+        const { getConfigManager } = await import('./config/toml-config.js');
+        const llmCfg = getConfigManager().getConfig().llm;
+        const enabled = Boolean(llmCfg?.enabled) || process.env.CODEBUDDY_LLM_FAILOVER === '1';
+        if (!enabled)
+            return;
+        const primary = await getDetectedProvider();
+        const { buildActiveLlmRegistry } = await import('./providers/active-llm-registry.js');
+        const orderEnv = process.env.CODEBUDDY_LLM_ORDER;
+        const registry = await buildActiveLlmRegistry({
+            primary: primary
+                ? {
+                    provider: primary.provider,
+                    apiKey: primary.apiKey,
+                    baseURL: primary.baseURL,
+                    model: primary.defaultModel,
+                }
+                : undefined,
+            policy: orderEnv || llmCfg?.order || 'resilience',
+            manualOrder: llmCfg?.manualOrder,
+            localOnly: llmCfg?.local_only,
+        });
+        if (registry.fallbacks.length > 0) {
+            agent.getClient().setRuntimeFallbackProviders(registry.fallbacks);
+            logger.info(`Active-LLM failover: ${primary?.provider ?? '?'} → ${registry.fallbacks
+                .map((f) => f.provider)
+                .join(' → ')}`);
+        }
+    }
+    catch (err) {
+        logger.debug('Active-LLM failover setup skipped', {
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
 // Handle commit-and-push command in headless mode
 async function handleCommitAndPushHeadless(apiKey, baseURL, model, maxToolRounds) {
     try {
         const CodeBuddyAgent = await lazyImport.CodeBuddyAgent();
         const agent = new CodeBuddyAgent(apiKey, baseURL, model, maxToolRounds);
+        await applyActiveLlmFailover(agent);
         // Configure confirmation service for headless mode (auto-approve all operations)
         const { ConfirmationService } = await import("./utils/confirmation-service.js");
         const confirmationService = ConfirmationService.getInstance();
@@ -695,6 +832,7 @@ async function processPromptHeadless(prompt, apiKey, baseURL, model, maxToolRoun
         const modelToUse = customAgentConfig?.model ?? model;
         const CodeBuddyAgent = await lazyImport.CodeBuddyAgent();
         const agent = new CodeBuddyAgent(apiKey, baseURL, modelToUse, maxToolRounds);
+        await applyActiveLlmFailover(agent);
         await agent.systemPromptReady;
         if (customAgentConfig?.systemPrompt) {
             agent.setSystemPrompt(customAgentConfig.systemPrompt);
@@ -728,6 +866,20 @@ async function processPromptHeadless(prompt, apiKey, baseURL, model, maxToolRoun
         }
         // Process the user message
         const chatEntries = await agent.processUserMessage(prompt);
+        // WS3-T1 — session-end flush (handoff + lesson candidates). Awaited with
+        // a hard cap so headless runs keep their continuity write without ever
+        // hanging the exit; trivial sessions no-op inside the module.
+        try {
+            const { runSessionEndFlush } = await import('./agent/session-end-flush.js');
+            const flushTimeoutMs = parseInt(process.env.CODEBUDDY_SESSION_END_FLUSH_TIMEOUT_MS || '15000', 10);
+            await Promise.race([
+                runSessionEndFlush({ chatHistory: chatEntries }),
+                new Promise((resolve) => setTimeout(resolve, flushTimeoutMs).unref()),
+            ]);
+        }
+        catch (e) {
+            logger.debug('Headless session-end flush skipped', { error: String(e) });
+        }
         // Log entries to interaction logger
         if (interactionLogger) {
             for (const entry of chatEntries) {
@@ -928,7 +1080,7 @@ program
     .option("--quiet", "suppress informational logs (only show errors and responses)")
     .option("--verbose", "enable verbose/debug output")
     .option("--speak", "enable automatic speech synthesis of agent responses using Text-to-Speech")
-    .option("--tts-provider <provider>", "TTS provider (edge-tts, espeak, say, piper, audioreader, kokoro)")
+    .option("--tts-provider <provider>", "TTS provider (edge-tts, espeak, say, piper, audioreader)")
     .action(async (message, options) => {
     // Apply --quiet / --verbose flags
     if (options.quiet) {
@@ -949,7 +1101,7 @@ program
             ttsManager.setAutoSpeak(true);
         }
         if (options.ttsProvider) {
-            const validProviders = ['edge-tts', 'espeak', 'say', 'piper', 'audioreader', 'kokoro'];
+            const validProviders = ['edge-tts', 'espeak', 'say', 'piper', 'audioreader'];
             if (validProviders.includes(options.ttsProvider)) {
                 ttsManager.updateConfig({ provider: options.ttsProvider });
             }
@@ -1129,13 +1281,56 @@ program
     }
     try {
         // Get API key from options, environment, or user settings
-        const apiKey = options.apiKey || await loadApiKey();
-        const baseURL = options.baseUrl || await loadBaseURL();
-        let model = options.model || await loadModel(); // let: can be overridden by --agent
+        const explicitProvider = options.model && !options.apiKey && !options.baseUrl
+            ? (await import('./commands/llm-provider-resolution.js')).resolveCommandProvider({
+                explicitModel: options.model,
+            })
+            : null;
+        let apiKey = options.apiKey || explicitProvider?.apiKey || await loadApiKey();
+        let baseURL = options.baseUrl || explicitProvider?.baseURL || await loadBaseURL();
+        let model = options.model || explicitProvider?.model || await loadModel(); // let: can be overridden by --agent
         const maxToolRounds = parseInt(options.maxToolRounds) || 400;
         if (!apiKey) {
-            logger.error("❌ Error: API key required. Set GOOGLE_API_KEY, GROK_API_KEY, or OPENAI_API_KEY environment variable, use --api-key flag, or save to ~/.codebuddy/user-settings.json");
-            process.exit(1);
+            // In an interactive terminal, offer the guided setup wizard right here
+            // (like Hermes) instead of dead-ending on an error — then continue the
+            // session with the credentials it captured.
+            const interactive = Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY) &&
+                !options.prompt && !options.print &&
+                process.env.CI !== 'true' && process.env.GITHUB_ACTIONS !== 'true';
+            let recovered = false;
+            if (interactive) {
+                const readline = await import('readline');
+                const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+                const answer = await new Promise((resolve) => rl.question('\n❔ No AI provider configured. Run guided setup now? [Y/n] ', resolve));
+                rl.close();
+                const yes = answer.trim() === '' || /^y(es)?$/i.test(answer.trim());
+                if (yes) {
+                    try {
+                        const { runOnboarding } = await import('./wizard/onboarding.js');
+                        const result = await runOnboarding();
+                        // Bust the cached provider detection so the just-saved creds resolve.
+                        cachedProvider = undefined;
+                        apiKey = options.apiKey || await loadApiKey();
+                        baseURL = options.baseUrl || await loadBaseURL();
+                        model = options.model || result.model || await loadModel();
+                        recovered = Boolean(apiKey);
+                    }
+                    catch (err) {
+                        logger.error('Guided setup did not complete', err instanceof Error ? err : { error: String(err) });
+                    }
+                }
+            }
+            if (!recovered) {
+                logger.error([
+                    "❌ No AI provider configured. Pick one to get started:",
+                    "   • Guided setup (recommended) — interactive wizard:     buddy onboard",
+                    "   • Free, no API key — sign in with your ChatGPT plan:    buddy login",
+                    "   • Local & free — run a model with Ollama, then:         export OLLAMA_HOST=http://localhost:11434",
+                    "   • API key — set GROK_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY / GOOGLE_API_KEY (or pass --api-key)",
+                    "   Run  buddy doctor  to check your setup.",
+                ].join("\n"));
+                process.exit(1);
+            }
         }
         // Save API key and base URL to user settings if provided via command line
         if (options.apiKey || options.baseUrl) {
@@ -1319,6 +1514,7 @@ program
         recordStartupPhase('agent-create-start');
         const agent = new CodeBuddyAgent(apiKey, baseURL, model, maxToolRounds, true, systemPromptId);
         recordStartupPhase('agent-create-done');
+        await applyActiveLlmFailover(agent);
         // Apply custom agent system prompt if configured
         if (customAgentConfig?.systemPrompt) {
             await agent.systemPromptReady;
@@ -1520,6 +1716,9 @@ program
                     tags: ['interactive'],
                 });
                 agent.__interactionLogger = interactionLogger;
+                // WS3-T1 — pre-load the flush module so the sync `exit` handler
+                // can call it (ESM has no require; dynamic import is async).
+                const sessionEndFlush = await import('./agent/session-end-flush.js');
                 const cleanup = () => {
                     try {
                         interactionLogger.endSession();
@@ -1527,10 +1726,30 @@ program
                     catch (e) {
                         logger.debug('Failed to end interaction logger session', { error: String(e) });
                     }
+                    // `exit` handlers are sync-only: write at least the handoff
+                    // (no LLM) so an interrupted session still leaves a resume
+                    // point. The full async flush runs on SIGINT/SIGTERM below.
+                    try {
+                        sessionEndFlush.writeHandoffSync(agent.getChatHistory());
+                    }
+                    catch (_err) { /* handoff is best-effort on hard exit */ }
+                };
+                const flushThenExit = () => {
+                    cleanup();
+                    void (async () => {
+                        try {
+                            await Promise.race([
+                                sessionEndFlush.runSessionEndFlush({ chatHistory: agent.getChatHistory() }),
+                                new Promise((resolve) => setTimeout(resolve, 8000).unref()),
+                            ]);
+                        }
+                        catch (_err) { /* never block exit on the flush */ }
+                        process.exit(0);
+                    })();
                 };
                 process.on('exit', cleanup);
-                process.on('SIGINT', () => { cleanup(); process.exit(0); });
-                process.on('SIGTERM', () => { cleanup(); process.exit(0); });
+                process.on('SIGINT', flushThenExit);
+                process.on('SIGTERM', flushThenExit);
             }
             catch (err) {
                 logger.warn('Failed to initialize interaction logger', { error: String(err) });
@@ -1624,7 +1843,14 @@ gitCommand
         const model = options.model || await loadModel();
         const maxToolRounds = parseInt(options.maxToolRounds) || 400;
         if (!apiKey) {
-            logger.error("❌ Error: API key required. Set GOOGLE_API_KEY, GROK_API_KEY, or OPENAI_API_KEY environment variable, use --api-key flag, or save to ~/.codebuddy/user-settings.json");
+            logger.error([
+                "❌ No AI provider configured. Pick one to get started:",
+                "   • Guided setup (recommended) — interactive wizard:     buddy onboard",
+                "   • Free, no API key — sign in with your ChatGPT plan:    buddy login",
+                "   • Local & free — run a model with Ollama, then:         export OLLAMA_HOST=http://localhost:11434",
+                "   • API key — set GROK_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY / GOOGLE_API_KEY (or pass --api-key)",
+                "   Run  buddy doctor  to check your setup.",
+            ].join("\n"));
             process.exit(1);
         }
         // Save API key and base URL to user settings if provided via command line
@@ -1664,7 +1890,7 @@ function removeCommands(parent, names) {
  * subcommands, we register a thin wrapper that delegates to the real
  * command tree on first use.
  */
-function addLazyCommand(parent, name, description, loader) {
+function addLazyCommand(parent, name, description, loader, prevalidateArgv) {
     // Create a pass-through command that accepts arbitrary args
     const stub = parent
         .command(name)
@@ -1674,6 +1900,14 @@ function addLazyCommand(parent, name, description, loader) {
         .helpOption(false);
     // Override the parse to delegate to the real command
     stub.action(async () => {
+        try {
+            await prevalidateArgv?.(process.argv);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`error: ${message}\n`);
+            process.exit(1);
+        }
         const realCommand = await loader();
         // Replace the stub with the real command and re-parse
         removeCommands(parent, name);
@@ -1727,6 +1961,19 @@ program
         process.exit(1);
     }
 });
+// Cowork (the Electron desktop GUI) needs Node >= 22; the terminal CLI runs on
+// Node >= 18. Without this guard a Node 18/20 user gets a cryptic Electron/Vite
+// crash mid-launch instead of a clear message — a classic first-run star-killer.
+const COWORK_MIN_NODE_MAJOR = 22;
+function assertNodeForCowork() {
+    const major = Number(process.versions.node.split(".")[0]);
+    if (Number.isFinite(major) && major < COWORK_MIN_NODE_MAJOR) {
+        cli.stdout(`❌ Cowork (the desktop GUI) requires Node.js >= ${COWORK_MIN_NODE_MAJOR} — you're on v${process.versions.node}.`);
+        cli.stdout(`   The terminal CLI works on Node >= 18; only the Electron app needs >= ${COWORK_MIN_NODE_MAJOR}.`);
+        cli.stdout(`   Upgrade Node (e.g. \`nvm install 22 && nvm use 22\`) and retry. Linux build notes: cowork/DEV-LINUX.md`);
+        process.exit(1);
+    }
+}
 // Desktop GUI commands
 program
     .command("gui")
@@ -1734,6 +1981,7 @@ program
     .option("--dev", "start with Vite dev server (hot reload)")
     .option("--detach", "run in background")
     .action(async (options) => {
+    assertNodeForCowork();
     const { launchDesktop } = await import("./desktop/launcher.js");
     const code = await launchDesktop({
         dev: options.dev,
@@ -1747,6 +1995,7 @@ program
     .option("--dev", "start with Vite dev server")
     .option("--detach", "run in background")
     .action(async (options) => {
+    assertNodeForCowork();
     const { launchDesktop } = await import("./desktop/launcher.js");
     const code = await launchDesktop({
         dev: options.dev,
@@ -1758,21 +2007,146 @@ program
     .command("install-gui")
     .description("Install Electron and build the desktop GUI")
     .action(async () => {
+    assertNodeForCowork();
     const { installGUI } = await import("./desktop/installer.js");
     await installGUI();
 });
+/**
+ * After a successful xAI login, probe api.x.ai with one tiny real call so the
+ * user learns immediately whether their subscription includes API inference
+ * (a SuperGrok plan does not always — the OAuth `api:access` scope is
+ * requested, not guaranteed granted).
+ */
+async function probeXaiInference() {
+    const { getValidXaiAccessToken, XAI_OAUTH_BASE_URL } = await import("./providers/xai-oauth.js");
+    cli.stdout("\nVerifying inference access (api.x.ai) ...");
+    const token = await getValidXaiAccessToken();
+    if (!token) {
+        cli.error("❌ Could not load a valid token after login.");
+        return;
+    }
+    const probeModel = process.env.GROK_MODEL || "grok-3";
+    try {
+        const res = await fetch(`${XAI_OAUTH_BASE_URL}/chat/completions`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+            body: JSON.stringify({
+                model: probeModel,
+                max_tokens: 1,
+                messages: [{ role: "user", content: "hi" }],
+            }),
+            signal: AbortSignal.timeout(30_000),
+        });
+        if (res.ok) {
+            cli.stdout("✅ Inference access confirmed — your subscription works in Code Buddy.");
+            cli.stdout(`   Try: buddy --model ${probeModel} -p "hello"   (or just \`buddy\`)`);
+        }
+        else if (res.status === 401 || res.status === 403) {
+            const body = await res.text().catch(() => "");
+            cli.error(`⚠️ Login succeeded, but api.x.ai returned ${res.status} — your subscription may not include API inference.`);
+            if (body)
+                cli.error(`   Detail: ${body.slice(0, 200)}`);
+            cli.error("   You can still use Grok with a metered API key: set XAI_API_KEY.");
+        }
+        else {
+            const body = await res.text().catch(() => "");
+            cli.error(`⚠️ Probe returned ${res.status} (model "${probeModel}"?): ${body.slice(0, 200)}`);
+        }
+    }
+    catch (err) {
+        cli.error(`⚠️ Probe call failed (network?): ${err instanceof Error ? err.message : String(err)}`);
+        cli.stdout('   Tokens are stored; try `buddy -p "hello"`.');
+    }
+}
+/**
+ * xAI / Grok subscription login (`buddy login xai`). Two-step so it works in
+ * backgrounded / non-interactive / remote shells where stdin can't be pasted
+ * into: step 1 opens the browser + persists the PKCE material, step 2
+ * (`--code <code>`) exchanges the code xAI shows in-page. In an interactive
+ * TTY, step 1 also accepts the code inline for a one-shot experience.
+ */
+async function loginXaiCli(codeArg) {
+    const xai = await import("./providers/xai-oauth.js");
+    // Step 2 — complete a pending login with the copied code.
+    if (codeArg) {
+        try {
+            const auth = await xai.completeLogin(codeArg);
+            cli.stdout("✅ Authenticated with xAI");
+            if (auth.email)
+                cli.stdout(`   Account:   ${auth.email}`);
+            if (typeof auth.expires_in_seconds === "number") {
+                cli.stdout(`   Token TTL: ~${Math.round(auth.expires_in_seconds / 60)} min`);
+            }
+            cli.stdout(`   Tokens stored at: ${xai.getXaiAuthFilePath()}`);
+            await probeXaiInference();
+        }
+        catch (err) {
+            cli.error(`❌ Login failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+        return;
+    }
+    // Step 1 — open the browser and persist the pending PKCE material.
+    cli.stdout("🔐 xAI / Grok login");
+    let authorizeUrl;
+    try {
+        ({ authorizeUrl } = await xai.beginLogin());
+    }
+    catch (err) {
+        cli.error(`❌ Could not start login: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+        return;
+    }
+    try {
+        const openModule = await import("open");
+        await openModule.default(authorizeUrl);
+        cli.stdout("Opening your browser to authorize Code Buddy with your xAI / SuperGrok plan ...");
+    }
+    catch (_err) {
+        /* browser open is best-effort — fall back to the printed URL below */
+    }
+    cli.stdout(`\nIf your browser didn't open, visit this URL:\n${authorizeUrl}\n`);
+    cli.stdout("xAI shows an authorization CODE in the page. Copy it, then run:");
+    cli.stdout("   buddy login xai --code <PASTE_THE_CODE>\n");
+    // Interactive convenience: if we have a real TTY, accept the code inline.
+    if (process.stdin.isTTY) {
+        const readline = await import("readline");
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await new Promise((resolve) => rl.question("Paste the code here (or Ctrl-C to finish later): ", resolve));
+        rl.close();
+        if (answer.trim()) {
+            try {
+                const auth = await xai.completeLogin(answer);
+                cli.stdout("✅ Authenticated with xAI");
+                if (auth.email)
+                    cli.stdout(`   Account:   ${auth.email}`);
+                cli.stdout(`   Tokens stored at: ${xai.getXaiAuthFilePath()}`);
+                await probeXaiInference();
+            }
+            catch (err) {
+                cli.error(`❌ Login failed: ${err instanceof Error ? err.message : String(err)}`);
+                process.exit(1);
+            }
+        }
+    }
+}
 // Phase d.23+ — Authentication commands.
 // Run the OAuth flow directly from the CLI so users don't have to enter
 // the interactive TUI just to log in. Mirrors the `/login` slash command
 // that's available inside a session.
 program
     .command("login [provider]")
-    .description("Authenticate with a provider (default: chatgpt — uses your ChatGPT subscription)")
-    .action(async (provider) => {
+    .description("Authenticate with a provider (chatgpt | xai — uses your subscription, no API key)")
+    .option("--code <code>", "Complete an xAI login with the code shown in the browser")
+    .action(async (provider, options) => {
     const target = (provider ?? "chatgpt").toLowerCase();
+    if (target === "xai" || target === "grok" || target === "xai-oauth") {
+        await loginXaiCli(options.code);
+        return;
+    }
     if (target !== "chatgpt" && target !== "codex" && target !== "openai") {
-        cli.stdout(`Unknown provider: "${provider}". Only \`chatgpt\` is supported.`);
-        cli.stdout("Other providers (Gemini, Anthropic, Grok) authenticate via API key env vars.");
+        cli.stdout(`Unknown provider: "${provider}". Supported: \`chatgpt\`, \`xai\`.`);
+        cli.stdout("Other providers (Gemini, Anthropic) authenticate via API key env vars.");
         process.exit(1);
     }
     const { loginInteractive, getCodexAuthFilePath } = await import("./providers/codex-oauth.js");
@@ -1800,11 +2174,21 @@ program
 });
 program
     .command("logout [provider]")
-    .description("Clear stored credentials for a provider (default: chatgpt)")
+    .description("Clear stored credentials for a provider (chatgpt | xai)")
     .action(async (provider) => {
     const target = (provider ?? "chatgpt").toLowerCase();
+    if (target === "xai" || target === "grok" || target === "xai-oauth") {
+        const { hasXaiCredentials, clearXaiCredentials, getXaiAuthFilePath } = await import("./providers/xai-oauth.js");
+        if (!hasXaiCredentials()) {
+            cli.stdout("No xAI credentials on disk — already logged out.");
+            return;
+        }
+        clearXaiCredentials();
+        cli.stdout(`✅ xAI credentials cleared (${getXaiAuthFilePath()})`);
+        return;
+    }
     if (target !== "chatgpt" && target !== "codex" && target !== "openai") {
-        cli.stdout(`Unknown provider: "${provider}". Only \`chatgpt\` is supported.`);
+        cli.stdout(`Unknown provider: "${provider}". Supported: \`chatgpt\`, \`xai\`.`);
         process.exit(1);
     }
     const { hasCodexCredentials, clearCodexCredentials, getCodexAuthFilePath } = await import("./providers/codex-oauth.js");
@@ -1845,6 +2229,89 @@ program
         process.exit(1);
     }
 });
+// Active-LLM registry — list the LLMs you're logged into + the failover order.
+program
+    .command("llm [action] [prompt...]")
+    .description("List active LLMs, or run several together: llm ensemble|consensus|race <prompt>")
+    .option("--order <policy>", "Ordering: resilience | free-first | manual")
+    .action(async (action, promptParts = [], opts) => {
+    const primary = await getDetectedProvider();
+    const { buildActiveLlmRegistry } = await import("./providers/active-llm-registry.js");
+    const registry = await buildActiveLlmRegistry({
+        primary: primary
+            ? {
+                provider: primary.provider,
+                apiKey: primary.apiKey,
+                baseURL: primary.baseURL,
+                model: primary.defaultModel,
+            }
+            : undefined,
+        policy: opts.order,
+    });
+    if (registry.all.length === 0) {
+        cli.stdout("No active LLMs detected. Run `buddy login`, set an API key, or start Ollama.");
+        return;
+    }
+    // "Together" — run several active LLMs at once and aggregate the result.
+    const strategyByAction = {
+        ensemble: "ensemble",
+        consensus: "consensus",
+        race: "fastest",
+        together: "all",
+    };
+    const strategy = action ? strategyByAction[action.toLowerCase()] : undefined;
+    if (strategy) {
+        const promptText = promptParts.join(" ").trim();
+        if (!promptText) {
+            cli.error(`Usage: buddy llm ${action} "<prompt>"`);
+            process.exit(1);
+        }
+        const models = registry.all.map((p) => ({
+            id: p.provider,
+            name: p.provider,
+            provider: "codebuddy",
+            model: p.model,
+            apiKey: p.apiKey,
+            baseURL: p.baseURL,
+            enabled: true,
+            costPerToken: p.costInputUsdPerMtok / 1_000_000,
+        }));
+        cli.stdout(`Running ${action} across ${models.map((m) => m.id).join(", ")} …`);
+        const { createParallelExecutor } = await import("./agent/parallel/parallel-executor.js");
+        const executor = createParallelExecutor({ models, strategy });
+        const result = await executor.execute(promptText);
+        // Show each LLM's own answer — the point of running them together.
+        for (const r of result.responses) {
+            if (r.error) {
+                cli.stdout(`\n── ${r.modelName} ❌ ${r.error.slice(0, 140)}`);
+            }
+            else {
+                cli.stdout(`\n── ${r.modelName}  (${r.latency}ms, ${r.tokensUsed} tok)\n${r.content.trim()}`);
+            }
+        }
+        cli.stdout(`\n${executor.formatResult(result)}`);
+        return;
+    }
+    cli.stdout("Active LLMs (logged in + reachable):");
+    for (const p of registry.all) {
+        const isPrimary = registry.primaryProvider === p.provider ? "  ← primary" : "";
+        const tag = p.isLocal ? "local" : "cloud";
+        const cost = p.costInputUsdPerMtok === 0 ? "$0" : `$${p.costInputUsdPerMtok}/Mtok`;
+        cli.stdout(`  • ${p.provider.padEnd(10)} [${tag}] ${p.model}  (${cost})${isPrimary}`);
+    }
+    if (registry.fallbacks.length > 0) {
+        cli.stdout(`\nFailover order: ${primary?.provider ?? "?"} → ${registry.fallbacks
+            .map((f) => f.provider)
+            .join(" → ")}`);
+    }
+    else {
+        cli.stdout("\nNo additional active LLMs available for failover.");
+    }
+    const { getConfigManager } = await import("./config/toml-config.js");
+    const on = Boolean(getConfigManager().getConfig().llm?.enabled) ||
+        process.env.CODEBUDDY_LLM_FAILOVER === "1";
+    cli.stdout(`Auto-failover: ${on ? "ON" : "OFF  (enable with [llm].enabled = true, or CODEBUDDY_LLM_FAILOVER=1)"}`);
+});
 // MCP Server command - run Code Buddy as an MCP tool provider over stdio
 program
     .command("mcp-server")
@@ -1909,7 +2376,7 @@ addLazyCommandGroup(program, 'speak', 'Synthesize speech using AudioReader TTS',
 // Utility commands (doctor, security-audit, onboard, webhook) are all registered
 // by a single registerUtilityCommands() call, so we must remove all stubs before
 // re-registering to avoid Commander duplicate command errors.
-const utilityCommandNames = ['doctor', 'security-audit', 'onboard', 'webhook'];
+const utilityCommandNames = ['doctor', 'security-audit', 'onboard', 'webhook', 'ollama'];
 const loadUtilityCommands = async () => {
     // Remove all utility stubs at once
     removeCommands(program, utilityCommandNames);
@@ -1921,7 +2388,8 @@ for (const cmdName of utilityCommandNames) {
     const desc = cmdName === 'doctor' ? 'Diagnose Code Buddy environment, dependencies, and configuration'
         : cmdName === 'security-audit' ? 'Run a security audit of your Code Buddy environment'
             : cmdName === 'onboard' ? 'Interactive setup wizard for Code Buddy'
-                : 'Manage webhook triggers';
+                : cmdName === 'ollama' ? 'Inspect or update the local Ollama runtime'
+                    : 'Manage webhook triggers';
     const stub = program
         .command(cmdName)
         .description(desc)
@@ -2045,6 +2513,14 @@ addLazyCommand(program, 'flow', 'Execute a multi-agent planning flow (OpenManus-
     const { createFlowCommand } = await import('./commands/flow.js');
     return createFlowCommand();
 });
+// Goal Ralph loop — headless judge-gated auto-continue (Hermes Agent parity)
+addLazyCommand(program, 'goal', 'Run the agent toward a standing goal until a judge model confirms it is done (Ralph loop)', async () => {
+    const { createGoalCommand } = await import('./commands/goal-cli.js');
+    return createGoalCommand();
+}, async (argv) => {
+    const { validateGoalCommandNumericOptions } = await import('./commands/goal-cli.js');
+    validateGoalCommandNumericOptions(argv);
+});
 // Todo attention bias — Manus AI-inspired persistent task list
 addLazyCommand(program, 'todo', 'Manage persistent task list (todo.md) — injected at end of every agent turn for focus', async () => {
     const { createTodosCommand } = await import('./commands/todos.js');
@@ -2075,6 +2551,11 @@ addLazyCommand(program, 'update', 'Update Code Buddy (switch channels: stable, b
     const { createUpdateCommand } = await import('./commands/update.js');
     return createUpdateCommand();
 });
+// Tunnel — manage ngrok tunnels
+addLazyCommand(program, 'tunnel', 'Manage ngrok tunnels for the Code Buddy remote gateway', async () => {
+    const { createTunnelCommand } = await import('./commands/tunnel.js');
+    return createTunnelCommand();
+});
 // Nodes — companion app node management (macOS, iOS, Android)
 addLazyCommandGroup(program, 'nodes', 'Manage companion app nodes (macOS, iOS, Android)', async () => {
     const { registerNodeCommands } = await import('./commands/cli/node-commands.js');