@phuetz/code-buddy 0.3.0 → 1.0.0-rc.8

package/dist/index.js

@@ -1,15 +1,56 @@
 #!/usr/bin/env node
 // Record startup time as early as possible
 const STARTUP_TIME = Date.now();
-import { program } from "commander";
-import { createRequire } from "module";
+import { Option, program } from "commander";
+import { readFileSync } from "fs";
+import * as nodeFs from "fs";
+import * as nodeOs from "os";
+import * as nodePath from "path";
+import { join, dirname } from "path";
+import { globalAgent as httpGlobalAgent } from 'node:http';
+import { globalAgent as httpsGlobalAgent } from 'node:https';
+import { fileURLToPath } from 'url';
+import { resolveHeadlessOutputFormat, resolveHeadlessResultExitCode } from './cli/headless-options.js';
+import { resolveCliModelList } from './cli/model-listing.js';
 // Read version from package.json
-const require = createRequire(import.meta.url);
-const packageJson = require("../package.json");
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageJson = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+const launchCwd = process.cwd();
+// Mark this process as running inside the Code Buddy CLI
+process.env.CODEBUDDY_CLI = '1';
+process.env.CODEBUDDY_CLI_VERSION = packageJson.version;
 // Import logger statically since it's used throughout the file synchronously
 import { logger } from "./utils/logger.js";
 // Import graceful shutdown for clean application termination
 import { initializeGracefulShutdown, getShutdownManager, } from "./utils/graceful-shutdown.js";
+/**
+ * CLI output helper.
+ *
+ * Prior to the F4 cleanup this file used `console.*` ~97 times, which
+ * violated the CLAUDE.md rule that production code must go through the
+ * `logger` (tests spy on `logger.warn` for assertions). Wrapping behind
+ * `cli.*` gives us:
+ *   - `cli.info` / `cli.warn` / `cli.error` → delegated to `logger` so log
+ *     level, LOG_FILE, and test spies all work uniformly.
+ *   - `cli.stdout` → raw `process.stdout.write` for pipeable output
+ *     (`buddy list-models`, `--output json`, tool results). These MUST
+ *     stay on stdout because users pipe them into other tools; routing
+ *     them through the logger would send them to stderr.
+ */
+const cli = {
+    info: (msg) => logger.info(msg),
+    warn: (msg) => logger.warn(msg),
+    error: (msg, err) => {
+        if (err !== undefined) {
+            logger.error(msg, { error: err instanceof Error ? err.message : String(err) });
+        }
+        else {
+            logger.error(msg);
+        }
+    },
+    stdout: (msg) => process.stdout.write(msg + '\n'),
+};
 // CLI command modules are loaded lazily below (see registerLazyCommands)
 // to avoid importing heavy transitive dependencies at startup.
 // Startup timing (enabled via PERF_TIMING=true or DEBUG=true)
@@ -23,13 +64,13 @@ function recordStartupPhase(name) {
 function logStartupMetrics() {
     if (!PERF_TIMING || startupPhases.length === 0)
         return;
-    console.log('\n=== Startup Performance ===');
-    console.log(`Total time: ${Date.now() - STARTUP_TIME}ms`);
-    console.log('Phase breakdown:');
+    cli.info('\n=== Startup Performance ===');
+    cli.info(`Total time: ${Date.now() - STARTUP_TIME}ms`);
+    cli.info('Phase breakdown:');
     for (const phase of startupPhases) {
-        console.log(`  ${phase.name}: ${phase.time}ms`);
+        cli.info(`  ${phase.name}: ${phase.time}ms`);
     }
-    console.log('===========================\n');
+    cli.info('===========================\n');
 }
 recordStartupPhase('imports-start');
 recordStartupPhase('imports-done');
@@ -73,6 +114,8 @@ const lazyImport = {
     performance: () => lazyLoad('performance', () => import("./performance/index.js")),
     pluginManager: () => lazyLoad('pluginManager', () => import("./plugins/plugin-manager.js")),
     lazyLoader: () => lazyLoad('lazyLoader', () => import("./performance/lazy-loader.js")),
+    // Settings hierarchy - loaded early for configuration
+    settingsHierarchy: () => lazyLoad('settingsHierarchy', () => import('./config/settings-hierarchy.js').then(m => m.getSettingsHierarchy)),
     // Error handling - deferred until needed
     crashHandler: () => lazyLoad('crashHandler', () => import('./errors/crash-handler.js').then(m => m.getCrashHandler())),
     disposable: () => lazyLoad('disposable', () => import('./utils/disposable.js')),
@@ -87,16 +130,31 @@ let envLoaded = false;
 async function ensureEnvLoaded() {
     if (!envLoaded) {
         const dotenv = await lazyImport.dotenv();
-        dotenv.config();
+        // Always load .env from the launch directory first so `--directory`
+        // does not accidentally drop API keys from the caller workspace.
+        dotenv.config({ path: join(launchCwd, '.env') });
+        // If cwd changed after launch and has its own .env, load it too
+        // (without overriding already-populated environment variables).
+        if (process.cwd() !== launchCwd) {
+            dotenv.config();
+        }
         envLoaded = true;
+        // Configure HTTP proxy from env vars (HTTP_PROXY, HTTPS_PROXY, NO_PROXY)
+        try {
+            const { configureProxy } = await import('./utils/proxy-support.js');
+            configureProxy();
+        }
+        catch (_proxyErr) {
+            // Proxy setup is optional — if the module fails to load, proceed without proxy
+        }
     }
 }
 // Minimal logger for startup errors (no chalk dependency)
 const startupLogger = {
     error: (msg, err) => {
-        console.error(msg, err instanceof Error ? err.message : err);
+        cli.error(msg, err instanceof Error ? err.message : err);
     },
-    warn: (msg) => console.warn(msg),
+    warn: (msg) => cli.warn(msg),
 };
 // ============================================================================
 // Process Signal Handlers - Using Graceful Shutdown Manager
@@ -129,7 +187,7 @@ process.on("uncaughtException", async (error) => {
     startupLogger.error("\nUnexpected error occurred:", error);
     if (crashFile) {
         startupLogger.error(`\nCrash context saved to: ${crashFile}`);
-        startupLogger.error("You can resume your session with: grok --resume");
+        startupLogger.error("You can resume your session with: buddy --resume");
     }
     // Use graceful shutdown with error exit code
     try {
@@ -153,7 +211,7 @@ process.on("unhandledRejection", async (reason, _promise) => {
     startupLogger.error("\nUnhandled promise rejection:", error);
     if (crashFile) {
         startupLogger.error(`\nCrash context saved to: ${crashFile}`);
-        startupLogger.error("You can resume your session with: grok --resume");
+        startupLogger.error("You can resume your session with: buddy --resume");
     }
     // Use graceful shutdown with error exit code
     try {
@@ -167,7 +225,7 @@ process.on("unhandledRejection", async (reason, _promise) => {
 // ============================================================================
 // Settings and Credential Loading - Now async with lazy imports
 // ============================================================================
-// Ensure user settings are initialized
+// Ensure user settings are initialized and hierarchy is loaded
 async function ensureUserSettingsDirectory() {
     try {
         const getSettingsManager = await lazyImport.settingsManager();
@@ -178,24 +236,95 @@ async function ensureUserSettingsDirectory() {
     catch (_err) {
         logger.debug('Failed to initialize user settings directory', { error: _err });
     }
+    // Load the 3-level settings hierarchy:
+    //   ~/.codebuddy/settings.json  <  .codebuddy/settings.json  <  .codebuddy/settings.local.json
+    try {
+        const getSettingsHierarchy = await lazyImport.settingsHierarchy();
+        const hierarchy = getSettingsHierarchy();
+        hierarchy.loadAllLevels();
+        logger.debug('Settings hierarchy loaded successfully');
+    }
+    catch (_err) {
+        logger.debug('Failed to load settings hierarchy', { error: _err });
+    }
 }
-// Detect provider from environment variables
-function detectProviderFromEnv() {
-    // Priority: Gemini > Grok > OpenAI > Anthropic
-    if (process.env.GOOGLE_API_KEY || process.env.GEMINI_API_KEY) {
+// Detected provider configuration — moved to `src/utils/provider-detector.ts`
+// (Phase d.25) so it can be unit-tested in isolation. Re-exported here
+// for the rest of this file's call sites.
+import { detectProviderFromEnv } from './utils/provider-detector.js';
+// Legacy inline implementation kept commented for git-archaeology only.
+function _detectProviderFromEnvLegacy() {
+    // Priority order (mirror of src/fleet/peer-chat-client-factory.ts —
+    // explicit user intent first, then local, then cloud env keys):
+    //   0. CODEBUDDY_PROVIDER override (always wins when set + valid)
+    //   1. ChatGPT OAuth credentials present (~/.codebuddy/codex-auth.json) —
+    //      explicit "I logged in" act, beats ambient OLLAMA_HOST
+    //   2. OLLAMA_HOST    → ollama (local, free, unlimited)
+    //   3. GROK_API_KEY   → grok / OpenAI-compat
+    //   4. GEMINI/GOOGLE  → gemini
+    //   5. OPENAI         → openai
+    //   6. ANTHROPIC      → anthropic
+    const override = process.env.CODEBUDDY_PROVIDER?.toLowerCase();
+    // ChatGPT subscription auth — explicit login wins over ambient
+    // env-detected providers. User who ran `buddy login chatgpt` recently
+    // expects subsequent calls to route through their ChatGPT plan, not
+    // get hijacked by an OLLAMA_HOST set in their shell rc weeks ago.
+    // Inline the file-existence check rather than importing codex-oauth
+    // (this function is sync; the module is async-safe).
+    if (override === 'chatgpt' || !override) {
+        try {
+            const fs = nodeFs;
+            const path = nodePath;
+            const os = nodeOs;
+            const authPath = path.join(os.homedir(), '.codebuddy', 'codex-auth.json');
+            if (fs.existsSync(authPath)) {
+                const raw = fs.readFileSync(authPath, 'utf-8').trim();
+                const parsed = raw ? JSON.parse(raw) : null;
+                if (parsed?.tokens?.access_token) {
+                    return {
+                        provider: 'chatgpt',
+                        apiKey: 'oauth-chatgpt', // sentinel consumed by CodeBuddyClient
+                        baseURL: 'https://chatgpt.com/backend-api/codex',
+                        defaultModel: process.env.CHATGPT_MODEL || 'gpt-5.5',
+                    };
+                }
+            }
+        }
+        catch (err) {
+            logger.debug('Ignoring unreadable ChatGPT OAuth credentials during provider detection', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    if ((override === 'ollama' || (!override && process.env.OLLAMA_HOST))) {
+        let host = process.env.OLLAMA_HOST || 'http://localhost:11434';
+        if (!/^https?:\/\//i.test(host))
+            host = `http://${host}`;
+        if (!host.endsWith('/v1'))
+            host = host.replace(/\/+$/, '') + '/v1';
         return {
-            provider: 'gemini',
-            apiKey: process.env.GOOGLE_API_KEY || process.env.GEMINI_API_KEY || '',
-            baseURL: 'https://generativelanguage.googleapis.com/v1beta',
-            defaultModel: process.env.GEMINI_MODEL || 'gemini-2.5-flash',
+            provider: 'ollama',
+            apiKey: 'ollama', // placeholder — Ollama OpenAI-compat ignores it
+            baseURL: host,
+            defaultModel: process.env.GROK_MODEL || process.env.OLLAMA_MODEL || 'qwen2.5-coder:7b',
         };
     }
-    if (process.env.GROK_API_KEY || process.env.XAI_API_KEY) {
+    if ((override === 'grok' || override === 'xai') ||
+        (!override && (process.env.GROK_API_KEY || process.env.XAI_API_KEY))) {
         return {
             provider: 'grok',
             apiKey: process.env.GROK_API_KEY || process.env.XAI_API_KEY || '',
             baseURL: process.env.GROK_BASE_URL || 'https://api.x.ai/v1',
-            defaultModel: process.env.GROK_MODEL || 'grok-3-fast-latest',
+            defaultModel: process.env.GROK_MODEL || 'grok-3-fast',
+        };
+    }
+    if ((override === 'gemini' || override === 'google') ||
+        (!override && (process.env.GOOGLE_API_KEY || process.env.GEMINI_API_KEY))) {
+        return {
+            provider: 'gemini',
+            apiKey: process.env.GOOGLE_API_KEY || process.env.GEMINI_API_KEY || '',
+            baseURL: 'https://generativelanguage.googleapis.com/v1beta',
+            defaultModel: process.env.GEMINI_MODEL || 'gemini-2.5-flash',
         };
     }
     if (process.env.OPENAI_API_KEY) {
@@ -274,44 +403,45 @@ async function saveCommandLineSettings(apiKey, baseURL) {
             credManager.setApiKey(apiKey);
             const status = credManager.getSecurityStatus();
             if (status.encryptionEnabled) {
-                console.log("✅ API key saved securely (encrypted) to ~/.codebuddy/credentials.enc");
+                cli.info("✅ API key saved securely (encrypted) to ~/.codebuddy/credentials.enc");
             }
             else {
-                console.log("✅ API key saved to ~/.codebuddy/credentials.enc");
-                console.error("⚠️ Consider enabling encryption for better security");
+                cli.info("✅ API key saved to ~/.codebuddy/credentials.enc");
+                cli.error("⚠️ Consider enabling encryption for better security");
             }
         }
         // Save base URL to settings (not sensitive)
         if (baseURL) {
             settingsManager.updateUserSetting("baseURL", baseURL);
-            console.log("✅ Base URL saved to ~/.codebuddy/user-settings.json");
+            cli.info("✅ Base URL saved to ~/.codebuddy/user-settings.json");
         }
     }
     catch (error) {
-        console.warn("⚠️ Could not save settings to file:", error instanceof Error ? error.message : "Unknown error");
+        cli.warn(`⚠️ Could not save settings to file: ${error instanceof Error ? error.message : "Unknown error"}`);
     }
 }
 // Load model from detected provider or user settings
 async function loadModel() {
     await ensureEnvLoaded();
-    // Check environment-detected provider first
+    // 1. Explicit env var takes highest priority
+    if (process.env.GROK_MODEL)
+        return process.env.GROK_MODEL;
+    // 2. Project/user settings override auto-detection
+    try {
+        const getSettingsManager = await lazyImport.settingsManager();
+        const manager = getSettingsManager();
+        const settingsModel = manager.getCurrentModel();
+        if (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;
-    // First check environment variables
-    let model = process.env.GROK_MODEL;
-    if (!model) {
-        // Use the unified model loading from settings manager
-        try {
-            const getSettingsManager = await lazyImport.settingsManager();
-            const manager = getSettingsManager();
-            model = manager.getCurrentModel();
-        }
-        catch (_err) {
-            logger.debug('Failed to load model from settings manager', { error: _err });
-        }
-    }
-    return model;
+    return undefined;
 }
 // Handle commit-and-push command in headless mode
 async function handleCommitAndPushHeadless(apiKey, baseURL, model, maxToolRounds) {
@@ -322,22 +452,22 @@ async function handleCommitAndPushHeadless(apiKey, baseURL, model, maxToolRounds
         const { ConfirmationService } = await import("./utils/confirmation-service.js");
         const confirmationService = ConfirmationService.getInstance();
         confirmationService.setSessionFlag("allOperations", true);
-        console.log("🤖 Processing commit and push...\n");
-        console.log("> /commit-and-push\n");
+        cli.info("🤖 Processing commit and push...\n");
+        cli.info("> /commit-and-push\n");
         // First check if there are any changes at all
         const initialStatusResult = await agent.executeBashCommand("git status --porcelain");
         if (!initialStatusResult.success || !initialStatusResult.output?.trim()) {
-            console.log("❌ No changes to commit. Working directory is clean.");
+            cli.info("❌ No changes to commit. Working directory is clean.");
             process.exit(1);
         }
-        console.log("✅ git status: Changes detected");
+        cli.info("✅ git status: Changes detected");
         // Add all changes
         const addResult = await agent.executeBashCommand("git add .");
         if (!addResult.success) {
-            console.log(`❌ git add: ${addResult.error || "Failed to stage changes"}`);
+            cli.info(`❌ git add: ${addResult.error || "Failed to stage changes"}`);
             process.exit(1);
         }
-        console.log("✅ git add: Changes staged");
+        cli.info("✅ git add: Changes staged");
         // Get staged changes for commit message generation
         const diffResult = await agent.executeBashCommand("git diff --cached");
         // Generate commit message using AI
@@ -351,7 +481,7 @@ ${diffResult.output || "No staged changes shown"}
 
 Follow conventional commit format (feat:, fix:, docs:, etc.) and keep it under 72 characters.
 Respond with ONLY the commit message, no additional text.`;
-        console.log("🤖 Generating commit message...");
+        cli.info("🤖 Generating commit message...");
         const commitMessageEntries = await agent.processUserMessage(commitPrompt);
         let commitMessage = "";
         // Extract the commit message from the AI response
@@ -362,35 +492,35 @@ Respond with ONLY the commit message, no additional text.`;
             }
         }
         if (!commitMessage) {
-            console.log("❌ Failed to generate commit message");
+            cli.info("❌ Failed to generate commit message");
             process.exit(1);
         }
         // Clean the commit message
         const cleanCommitMessage = commitMessage.replace(/^["']|["']$/g, "");
-        console.log(`✅ Generated commit message: "${cleanCommitMessage}"`);
+        cli.info(`✅ Generated commit message: "${cleanCommitMessage}"`);
         // Execute the commit
         const commitCommand = `git commit -m "${cleanCommitMessage}"`;
         const commitResult = await agent.executeBashCommand(commitCommand);
         if (commitResult.success) {
-            console.log(`✅ git commit: ${commitResult.output?.split("\n")[0] || "Commit successful"}`);
+            cli.info(`✅ git commit: ${commitResult.output?.split("\n")[0] || "Commit successful"}`);
             // If commit was successful, push to remote
             // First try regular push, if it fails try with upstream setup
             let pushResult = await agent.executeBashCommand("git push");
             if (!pushResult.success &&
                 pushResult.error?.includes("no upstream branch")) {
-                console.log("🔄 Setting upstream and pushing...");
+                cli.info("🔄 Setting upstream and pushing...");
                 pushResult = await agent.executeBashCommand("git push -u origin HEAD");
             }
             if (pushResult.success) {
-                console.log(`✅ git push: ${pushResult.output?.split("\n")[0] || "Push successful"}`);
+                cli.info(`✅ git push: ${pushResult.output?.split("\n")[0] || "Push successful"}`);
             }
             else {
-                console.log(`❌ git push: ${pushResult.error || "Push failed"}`);
+                cli.info(`❌ git push: ${pushResult.error || "Push failed"}`);
                 process.exit(1);
             }
         }
         else {
-            console.log(`❌ git commit: ${commitResult.error || "Commit failed"}`);
+            cli.info(`❌ git commit: ${commitResult.error || "Commit failed"}`);
             process.exit(1);
         }
     }
@@ -399,11 +529,179 @@ Respond with ONLY the commit message, no additional text.`;
         process.exit(1);
     }
 }
+async function finalizeHeadlessRun(code) {
+    const flushStreamWithTimeout = async (stream, timeoutMs = 250) => {
+        await Promise.race([
+            new Promise((resolve) => {
+                try {
+                    stream.write('', () => resolve());
+                }
+                catch (_error) {
+                    resolve();
+                }
+            }),
+            new Promise((resolve) => {
+                const timer = setTimeout(resolve, timeoutMs);
+                timer.unref();
+            }),
+        ]);
+    };
+    try {
+        const { disposeAll } = await import('./utils/disposable.js');
+        await disposeAll();
+    }
+    catch (error) {
+        logger.debug('Headless cleanup skipped', { error: String(error) });
+    }
+    try {
+        const { getLogger } = await import('./utils/logger.js');
+        getLogger().close();
+    }
+    catch (_error) {
+        // Ignore logger shutdown errors during process exit.
+    }
+    // Explicitly stop singleton file watchers that keep headless runs alive.
+    try {
+        const { resetSkillRegistry } = await import('./skills/registry.js');
+        resetSkillRegistry();
+    }
+    catch (_error) {
+        // Ignore skill registry shutdown errors.
+    }
+    try {
+        const { resetIdentityManager } = await import('./identity/identity-manager.js');
+        resetIdentityManager();
+    }
+    catch (_error) {
+        // Ignore identity manager shutdown errors.
+    }
+    try {
+        const { resetHotReloadManager } = await import('./config/hot-reload/index.js');
+        resetHotReloadManager();
+    }
+    catch (_error) {
+        // Ignore hot reload shutdown errors.
+    }
+    try {
+        const { resetConfigWatcher } = await import('./config/hot-reload/watcher.js');
+        resetConfigWatcher();
+    }
+    catch (_error) {
+        // Ignore config watcher shutdown errors.
+    }
+    try {
+        const { resetSettingsHierarchy } = await import('./config/settings-hierarchy.js');
+        resetSettingsHierarchy();
+    }
+    catch (_error) {
+        // Ignore settings hierarchy shutdown errors.
+    }
+    // Best-effort close of global HTTP agents to reduce socket-close races on Windows.
+    try {
+        httpGlobalAgent.destroy();
+        httpsGlobalAgent.destroy();
+    }
+    catch (_error) {
+        // Ignore HTTP agent shutdown errors.
+    }
+    // Flush stdout/stderr before forcing exit.
+    // In some piped/embedded contexts, write callbacks can stall indefinitely.
+    await flushStreamWithTimeout(process.stdout);
+    await flushStreamWithTimeout(process.stderr);
+    if (!process.stdin.destroyed) {
+        process.stdin.pause();
+    }
+    const handles = (process._getActiveHandles?.() || []);
+    for (const handle of handles) {
+        if (handle === process.stdout || handle === process.stderr || handle === process.stdin) {
+            continue;
+        }
+        try {
+            const h = handle;
+            h.unref?.();
+            if (h.constructor?.name === 'FSWatcher') {
+                h.close?.();
+            }
+        }
+        catch (_error) {
+            // Ignore per-handle unref failures.
+        }
+    }
+    if (process.env.CODEBUDDY_DEBUG_HANDLES === '1') {
+        const activeHandles = (process._getActiveHandles?.() || [])
+            .map((h) => {
+            const handle = h;
+            return {
+                type: handle.constructor?.name || 'Unknown',
+                hasUnref: typeof handle.unref === 'function',
+                hasClose: typeof handle.close === 'function',
+                path: handle._path || handle.path || handle._filename || handle.filename,
+            };
+        });
+        const activeRequests = (process._getActiveRequests?.() || [])
+            .map((r) => r?.constructor?.name || 'Unknown');
+        logger.debug('Active handles before headless return', {
+            count: activeHandles.length,
+            handles: activeHandles,
+            activeRequestsCount: activeRequests.length,
+            activeRequests,
+        });
+    }
+    process.exitCode = code;
+    const fallbackExitTimer = setTimeout(() => {
+        process.exit(code);
+    }, 1500);
+    fallbackExitTimer.unref();
+    return;
+}
+async function loadCustomAgentForCli(agentName, announce) {
+    if (!agentName)
+        return null;
+    const { getCustomAgentLoader } = await import("./agent/custom/custom-agent-loader.js");
+    const loader = getCustomAgentLoader();
+    const agentConfig = loader.getAgent(agentName);
+    if (!agentConfig) {
+        logger.error(`Agent not found: ${agentName}`);
+        const agents = loader.listAgents();
+        if (agents.length > 0) {
+            cli.error('\nAvailable agents:');
+            agents.forEach(a => cli.error(`   - ${a.id}`));
+        }
+        process.exit(1);
+    }
+    if (announce) {
+        cli.info(`Using agent: ${agentConfig.name}`);
+    }
+    const { setActiveCustomAgentRuntime } = await import('./agent/custom/custom-agent-runtime.js');
+    setActiveCustomAgentRuntime(agentConfig);
+    return agentConfig;
+}
+async function applyCustomAgentToolFilter(agentConfig) {
+    const { hasCustomAgentToolFilter, buildCustomAgentToolFilter } = await import('./agent/custom/custom-agent-tool-filter.js');
+    if (!hasCustomAgentToolFilter(agentConfig))
+        return;
+    const { getToolFilter, setToolFilter } = await import('./utils/tool-filter.js');
+    const { getBuiltinToolNames } = await import('./codebuddy/tools.js');
+    setToolFilter(buildCustomAgentToolFilter(agentConfig, getToolFilter(), getBuiltinToolNames()));
+}
 // Headless mode processing function
-async function processPromptHeadless(prompt, apiKey, baseURL, model, maxToolRounds, selfHealEnabled = true, outputFormat = 'json', outputSchemaPath) {
+async function processPromptHeadless(prompt, apiKey, baseURL, model, maxToolRounds, selfHealEnabled = true, outputFormat = 'json', outputSchemaPath, agentName) {
+    const previousDisableMCP = process.env.CODEBUDDY_DISABLE_MCP;
+    const previousHeadless = process.env.CODEBUDDY_HEADLESS;
+    process.env.CODEBUDDY_DISABLE_MCP = 'true';
+    process.env.CODEBUDDY_HEADLESS = 'true';
     try {
+        const customAgentConfig = await loadCustomAgentForCli(agentName, false);
+        const modelToUse = customAgentConfig?.model ?? model;
         const CodeBuddyAgent = await lazyImport.CodeBuddyAgent();
-        const agent = new CodeBuddyAgent(apiKey, baseURL, model, maxToolRounds);
+        const agent = new CodeBuddyAgent(apiKey, baseURL, modelToUse, maxToolRounds);
+        await agent.systemPromptReady;
+        if (customAgentConfig?.systemPrompt) {
+            agent.setSystemPrompt(customAgentConfig.systemPrompt);
+        }
+        if (customAgentConfig) {
+            await applyCustomAgentToolFilter(customAgentConfig);
+        }
         // Configure self-healing
         if (!selfHealEnabled) {
             agent.setSelfHealing(false);
@@ -418,14 +716,16 @@ async function processPromptHeadless(prompt, apiKey, baseURL, model, maxToolRoun
             const { getInteractionLogger } = await import('./logging/interaction-logger.js');
             const il = getInteractionLogger();
             il.startSession({
-                model: model || 'unknown',
+                model: modelToUse || 'unknown',
                 provider: baseURL?.includes('localhost') ? 'local' : 'xai',
                 cwd: process.cwd(),
                 tags: ['headless'],
             });
             interactionLogger = il;
         }
-        catch (_err) { }
+        catch (e) {
+            logger.debug('Failed to initialize headless interaction logger', { error: String(e) });
+        }
         // Process the user message
         const chatEntries = await agent.processUserMessage(prompt);
         // Log entries to interaction logger
@@ -484,21 +784,28 @@ async function processPromptHeadless(prompt, apiKey, baseURL, model, maxToolRoun
             const { validateOutputSchema } = await import("./utils/output-schema-validator.js");
             const validation = validateOutputSchema(messages, outputSchemaPath);
             if (!validation.valid) {
-                console.error('Output schema validation failed:');
+                cli.error('Output schema validation failed:');
                 for (const error of validation.errors) {
-                    console.error(`  - ${error}`);
+                    cli.error(`  - ${error}`);
                 }
-                process.exit(2);
+                return 2;
             }
         }
+        // Extract final assistant response text
+        const assistantMessages = messages.filter(m => m.role === 'assistant' && m.content && !('tool_calls' in m && m.tool_calls));
+        const lastResponse = assistantMessages[assistantMessages.length - 1];
+        const resultText = lastResponse?.content || '';
+        const exitCode = resolveHeadlessResultExitCode(resultText);
+        // Gather cost and model info from the agent
+        const sessionCost = agent.getSessionCost();
+        const usedModel = modelToUse || process.env.GROK_MODEL || 'unknown';
         // Output in the requested format
         const format = outputFormat.toLowerCase();
         if (format === 'text' || format === 'markdown') {
-            // Text/markdown: only output the final assistant response
-            const assistantMessages = messages.filter(m => m.role === 'assistant' && m.content && !('tool_calls' in m && m.tool_calls));
-            const lastResponse = assistantMessages[assistantMessages.length - 1];
-            if (lastResponse?.content) {
-                console.log(lastResponse.content);
+            // Text/markdown: only output the final assistant response.
+            // MUST go to stdout so users can pipe it: `buddy "question" | jq`.
+            if (resultText) {
+                cli.stdout(resultText);
             }
         }
         else if (format === 'stream-json' || format === 'streaming') {
@@ -506,32 +813,62 @@ async function processPromptHeadless(prompt, apiKey, baseURL, model, maxToolRoun
             for (const message of messages) {
                 process.stdout.write(JSON.stringify(message) + '\n');
             }
+            // Emit a final summary event
+            process.stdout.write(JSON.stringify({
+                type: 'summary',
+                result: resultText,
+                cost: { total: sessionCost },
+                model: usedModel,
+            }) + '\n');
         }
         else {
-            // Default: json - each message as a separate JSON object
-            for (const message of messages) {
-                console.log(JSON.stringify(message));
-            }
+            // Default: json — structured output goes to stdout (pipeable).
+            cli.stdout(JSON.stringify({
+                result: resultText,
+                cost: {
+                    total: sessionCost,
+                },
+                model: usedModel,
+                messages,
+            }));
         }
+        return exitCode;
     }
     catch (error) {
         // Output error in appropriate format
         const errorMessage = error instanceof Error ? error.message : String(error);
         const format = outputFormat.toLowerCase();
         if (format === 'text' || format === 'markdown') {
-            console.error(`Error: ${errorMessage}`);
+            cli.error(`Error: ${errorMessage}`);
         }
         else {
-            console.log(JSON.stringify({
-                role: "assistant",
-                content: `Error: ${errorMessage}`,
+            // JSON error envelope also goes to stdout so piping stays consistent.
+            cli.stdout(JSON.stringify({
+                error: errorMessage,
+                result: null,
+                cost: { total: 0 },
+                model: model || process.env.GROK_MODEL || 'unknown',
             }));
         }
-        process.exit(1);
+        return 1;
+    }
+    finally {
+        if (previousDisableMCP === undefined) {
+            delete process.env.CODEBUDDY_DISABLE_MCP;
+        }
+        else {
+            process.env.CODEBUDDY_DISABLE_MCP = previousDisableMCP;
+        }
+        if (previousHeadless === undefined) {
+            delete process.env.CODEBUDDY_HEADLESS;
+        }
+        else {
+            process.env.CODEBUDDY_HEADLESS = previousHeadless;
+        }
     }
 }
 program
-    .name("codebuddy")
+    .name("buddy")
     .description("A conversational AI CLI tool powered by AI with text editor capabilities")
     .version(packageJson.version)
     .argument("[message...]", "Initial message to send to Code Buddy")
@@ -539,11 +876,13 @@ program
     .option("-k, --api-key <key>", "CodeBuddy API key (or set GROK_API_KEY env var)")
     .option("-u, --base-url <url>", "CodeBuddy API base URL (or set GROK_BASE_URL env var)")
     .option("-m, --model <model>", "AI model to use (e.g., grok-code-fast-1, grok-4-latest) (or set GROK_MODEL env var)")
-    .option("-p, --prompt <prompt>", "process a single prompt and exit (headless mode)")
+    .option("-p, --prompt <prompt>", "process a single prompt and exit (headless mode, alias: --print)")
+    .option("--print <prompt>", "alias for --prompt: process a single prompt and exit (headless mode)")
     .option("-b, --browser", "launch browser UI instead of terminal interface")
     .option("--max-tool-rounds <rounds>", "maximum number of tool execution rounds (default: 400)", "400")
     .option("-s, --security-mode <mode>", "security mode: suggest (default), auto-edit, or full-auto")
     .option("-o, --output-format <format>", "output format for headless mode: json, stream-json, text, markdown")
+    .addOption(new Option("--output <format>", "legacy alias for --output-format").hideHelp())
     .option("--init", "initialize .codebuddy directory with templates and exit")
     .option("--dry-run", "preview changes without applying them (simulation mode)")
     .option("-c, --context <patterns>", "load specific files into context using glob patterns (e.g., 'src/**/*.ts,!**/*.test.ts')")
@@ -557,8 +896,8 @@ program
     .option("--list-models", "list available models from the API endpoint and exit")
     .option("--continue", "continue from the most recent saved session (like mistral-vibe)")
     .option("--resume <sessionId>", "resume a specific session by ID (supports partial matching)")
+    .option("--search-sessions <query>", "search saved sessions by content")
     .option("--max-price <dollars>", "maximum cost in dollars before stopping (like mistral-vibe)", "10.0")
-    .option("--output <format>", "output format for headless mode: text, json, streaming (like mistral-vibe)", "json")
     .option("--auto-approve", "automatically approve all tool executions (like mistral-vibe)")
     .option("--system-prompt <id>", "system prompt to use: default, minimal, secure, code-reviewer, architect (or custom from ~/.codebuddy/prompts/)")
     .option("--list-prompts", "list available system prompts and exit")
@@ -568,8 +907,10 @@ program
     .option("--disabled-tools <patterns>", "disable tools matching patterns (comma-separated, supports glob: bash,web_*)")
     .option("--setup", "run interactive setup wizard for API key and configuration")
     .option("--vim", "enable Vim keybindings for input")
+    .option("--permission-mode <mode>", "permission mode: default, plan, acceptEdits, dontAsk, bypassPermissions")
     .option("--dangerously-skip-permissions", "bypass all permission checks (use in trusted containers without network access)")
-    .option("--allowed-tools <patterns>", "only enable tools matching patterns (like Claude Code --allowedTools)")
+    .option("--allowed-tools <patterns>", "only enable tools matching patterns (natively --allowedTools)")
+    .option("--disallowed-tools <patterns>", "block tools matching patterns (natively --disallowedTools)")
     .option("--mcp-debug", "enable MCP debugging output")
     .option("--allow-outside", "allow file operations outside the workspace directory (disables workspace isolation)")
     .option("--output-schema <path>", "validate headless mode JSON output against a JSON Schema file")
@@ -583,7 +924,40 @@ program
     .option("--fallback-model <model>", "auto-fallback model when default is overloaded")
     .option("--profile <name>", "apply a named configuration profile from .codebuddy/config.toml [profiles.<name>]")
     .option("--from-pr <pr>", "link session to a GitHub pull request (number or URL)")
+    .option("--yolo", "enable YOLO mode (full autonomy with guardrails, $100 cost cap)")
+    .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)")
     .action(async (message, options) => {
+    // Apply --quiet / --verbose flags
+    if (options.quiet) {
+        process.env.LOG_LEVEL = 'error';
+        logger.setLevel('error');
+    }
+    if (options.verbose) {
+        process.env.VERBOSE = 'true';
+        process.env.DEBUG = 'true';
+        logger.setLevel('debug');
+    }
+    // Apply --speak / --tts-provider flags
+    if (options.speak || options.ttsProvider) {
+        const { getTTSManager } = await import('./input/text-to-speech.js');
+        const ttsManager = getTTSManager();
+        if (options.speak) {
+            ttsManager.enable();
+            ttsManager.setAutoSpeak(true);
+        }
+        if (options.ttsProvider) {
+            const validProviders = ['edge-tts', 'espeak', 'say', 'piper', 'audioreader', 'kokoro'];
+            if (validProviders.includes(options.ttsProvider)) {
+                ttsManager.updateConfig({ provider: options.ttsProvider });
+            }
+            else {
+                startupLogger.warn(`⚠️ Invalid tts-provider: ${options.ttsProvider}. Valid: ${validProviders.join(', ')}`);
+            }
+        }
+    }
     // Apply named configuration profile (--profile <name>) before anything else
     if (options.profile) {
         try {
@@ -605,28 +979,30 @@ program
     // Handle --init flag
     if (options.init) {
         const { initCodeBuddyProject, formatInitResult } = await lazyImport.initProject();
-        const result = initCodeBuddyProject();
-        console.log(formatInitResult(result));
+        const result = await initCodeBuddyProject();
+        cli.info(formatInitResult(result));
         process.exit(result.success ? 0 : 1);
     }
     // Handle --list-models flag
     if (options.listModels) {
-        const baseURL = options.baseUrl || await loadBaseURL();
+        const detected = options.baseUrl ? null : await getDetectedProvider();
+        const baseURL = options.baseUrl || detected?.baseURL || await loadBaseURL();
         try {
-            const response = await fetch(`${baseURL}/models`);
-            if (!response.ok) {
-                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-            }
-            const data = await response.json();
-            console.log("📋 Available models:\n");
-            if (data.data && data.data.length > 0) {
-                data.data.forEach((model) => {
-                    console.log(`  • ${model.id}`);
+            const { models } = await resolveCliModelList({
+                baseURL,
+                provider: detected?.provider,
+                defaultModel: detected?.defaultModel || process.env.CHATGPT_MODEL,
+            });
+            // Pipeable listing: stdout so `buddy --list-models | grep ...` works.
+            cli.stdout("📋 Available models:\n");
+            if (models.length > 0) {
+                models.forEach((model) => {
+                    cli.stdout(`  • ${model.id}`);
                 });
-                console.log(`\n  Total: ${data.data.length} model(s)`);
+                cli.stdout(`\n  Total: ${models.length} model(s)`);
             }
             else {
-                console.log("  (no models found)");
+                cli.stdout("  (no models found)");
             }
             process.exit(0);
         }
@@ -642,20 +1018,21 @@ program
         const { getPromptManager } = await import("./prompts/prompt-manager.js");
         const promptManager = getPromptManager();
         const prompts = await promptManager.listPrompts();
-        console.log("📋 Available system prompts:\n");
-        console.log("  Built-in:");
+        // Pipeable listing (see --list-models).
+        cli.stdout("📋 Available system prompts:\n");
+        cli.stdout("  Built-in:");
         prompts.filter(p => p.source === 'builtin').forEach(p => {
-            console.log(`    • ${p.id}`);
+            cli.stdout(`    • ${p.id}`);
         });
         const userPrompts = prompts.filter(p => p.source === 'user');
         if (userPrompts.length > 0) {
-            console.log("\n  User (~/.codebuddy/prompts/):");
+            cli.stdout("\n  User (~/.codebuddy/prompts/):");
             userPrompts.forEach(p => {
-                console.log(`    • ${p.id}`);
+                cli.stdout(`    • ${p.id}`);
             });
         }
-        console.log("\n💡 Usage: codebuddy --system-prompt <id>");
-        console.log("   Create custom prompts in ~/.codebuddy/prompts/<name>.md");
+        cli.stdout("\n💡 Usage: codebuddy --system-prompt <id>");
+        cli.stdout("   Create custom prompts in ~/.codebuddy/prompts/<name>.md");
         process.exit(0);
     }
     // Handle --list-agents flag
@@ -663,23 +1040,30 @@ program
         const { getCustomAgentLoader } = await import("./agent/custom/custom-agent-loader.js");
         const loader = getCustomAgentLoader();
         const agents = loader.listAgents();
-        console.log("📋 Available custom agents:\n");
+        // Pipeable listing (see --list-models).
+        cli.stdout("📋 Available agents:\n");
         if (agents.length === 0) {
-            console.log("  (no custom agents found)");
-            console.log("\n💡 Create agents in ~/.codebuddy/agents/");
-            console.log("   Example: ~/.codebuddy/agents/_example.toml");
+            cli.stdout("  (no custom agents found)");
+            cli.stdout("\n💡 Create agents in ~/.codebuddy/agents/");
+            cli.stdout("   Example: ~/.codebuddy/agents/_example.toml");
         }
         else {
             agents.forEach(agent => {
                 const tags = agent.tags?.length ? ` [${agent.tags.join(', ')}]` : '';
-                console.log(`  • ${agent.id}: ${agent.name}${tags}`);
+                cli.stdout(`  • ${agent.id}: ${agent.name}${tags}`);
                 if (agent.description) {
-                    console.log(`      ${agent.description}`);
+                    cli.stdout(`      ${agent.description}`);
                 }
             });
-            console.log(`\n  Total: ${agents.length} agent(s)`);
+            cli.stdout(`\n  Total: ${agents.length} agent(s)`);
         }
-        console.log("\n💡 Usage: codebuddy --agent <id>");
+        cli.info("\n💡 Usage: codebuddy --agent <id>");
+        process.exit(0);
+    }
+    // Handle --search-sessions flag
+    if (options.searchSessions) {
+        const { searchSessions } = await import("./cli/session-commands.js");
+        await searchSessions(options.searchSessions);
         process.exit(0);
     }
     // Handle --continue flag (resume last session, like mistral-vibe)
@@ -692,8 +1076,8 @@ program
             process.exit(1);
         }
         await sessionStore.resumeSession(lastSession.id);
-        console.log(`📂 Resuming session: ${lastSession.name} (${lastSession.id.slice(0, 8)})`);
-        console.log(`   ${lastSession.messages.length} messages, last accessed: ${lastSession.lastAccessedAt.toLocaleString()}\n`);
+        cli.info(`📂 Resuming session: ${lastSession.name} (${lastSession.id.slice(0, 8)})`);
+        cli.info(`   ${lastSession.messages.length} messages, last accessed: ${lastSession.lastAccessedAt.toLocaleString()}\n`);
     }
     // Handle --resume flag (resume specific session by ID, like mistral-vibe)
     if (options.resume) {
@@ -702,17 +1086,20 @@ program
         const session = await sessionStore.getSessionByPartialId(options.resume);
         if (!session) {
             logger.error(`❌ Session not found: ${options.resume}`);
-            console.log("\n📋 Recent sessions:");
+            cli.info("\n📋 Recent sessions:");
             const recent = await sessionStore.getRecentSessions(5);
             recent.forEach(s => {
-                console.log(`   ${s.id.slice(0, 8)} - ${s.name} (${s.messages.length} messages)`);
+                cli.info(`   ${s.id.slice(0, 8)} - ${s.name} (${s.messages.length} messages)`);
             });
             process.exit(1);
         }
         await sessionStore.resumeSession(session.id);
-        console.log(`📂 Resuming session: ${session.name} (${session.id.slice(0, 8)})`);
-        console.log(`   ${session.messages.length} messages, last accessed: ${session.lastAccessedAt.toLocaleString()}\n`);
+        cli.info(`📂 Resuming session: ${session.name} (${session.id.slice(0, 8)})`);
+        cli.info(`   ${session.messages.length} messages, last accessed: ${session.lastAccessedAt.toLocaleString()}\n`);
     }
+    // Load environment before changing cwd so root .env values (API keys) remain available
+    // even when --directory points to a workspace without its own .env file.
+    await ensureEnvLoaded();
     if (options.directory) {
         try {
             process.chdir(options.directory);
@@ -730,7 +1117,15 @@ program
         additionalPaths: options.addDir,
     });
     if (options.allowOutside) {
-        console.error("Warning: Workspace isolation DISABLED - file access is unrestricted");
+        cli.error("Warning: Workspace isolation DISABLED - file access is unrestricted");
+    }
+    // Initialize observability (Sentry/OpenTelemetry)
+    try {
+        const { initObservability } = await import("./observability/index.js");
+        initObservability();
+    }
+    catch (err) {
+        logger.debug('Observability init skipped', { error: String(err) });
     }
     try {
         // Get API key from options, environment, or user settings
@@ -749,16 +1144,31 @@ program
         // Enable force-tools mode for local models
         if (options.forceTools) {
             process.env.GROK_FORCE_TOOLS = 'true';
-            console.error("🔧 Force tools: ENABLED (function calling for local models)");
+            cli.error("🔧 Force tools: ENABLED (function calling for local models)");
         }
         // Handle auto-approve mode (like mistral-vibe)
         if (options.autoApprove) {
             const { ConfirmationService } = await import("./utils/confirmation-service.js");
             const confirmationService = ConfirmationService.getInstance();
             confirmationService.setSessionFlag("allOperations", true);
-            console.error("✅ Auto-approve: ENABLED (all tool executions will be approved)");
+            cli.error("✅ Auto-approve: ENABLED (all tool executions will be approved)");
+        }
+        // CC18: Handle --permission-mode
+        if (options.permissionMode) {
+            const { getPermissionModeManager } = await import("./security/permission-modes.js");
+            const mgr = getPermissionModeManager();
+            const validModes = ['default', 'plan', 'acceptEdits', 'dontAsk', 'bypassPermissions'];
+            if (validModes.includes(options.permissionMode)) {
+                const success = mgr.setMode(options.permissionMode);
+                if (success) {
+                    cli.error(`Permission mode: ${options.permissionMode}`);
+                }
+            }
+            else {
+                cli.error(`Invalid permission mode: ${options.permissionMode}. Valid: ${validModes.join(', ')}`);
+            }
         }
-        // Handle --dangerously-skip-permissions (like Claude Code)
+        // Handle --dangerously-skip-permissions (natively)
         if (options.dangerouslySkipPermissions) {
             const { ConfirmationService } = await import("./utils/confirmation-service.js");
             const confirmationService = ConfirmationService.getInstance();
@@ -766,8 +1176,8 @@ program
             confirmationService.setSessionFlag("fileOperations", true);
             confirmationService.setSessionFlag("bashCommands", true);
             process.env.GROK_SKIP_PERMISSIONS = 'true';
-            console.error("⚠️  DANGEROUS: All permission checks BYPASSED");
-            console.error("   Only use this in trusted containers without network access!");
+            cli.error("⚠️  DANGEROUS: All permission checks BYPASSED");
+            cli.error("   Only use this in trusted containers without network access!");
         }
         // Handle --add-dir: grant additional writable directories to sandbox
         if (options.addDir && options.addDir.length > 0) {
@@ -781,27 +1191,35 @@ program
             catch (_err) {
                 // Sandbox manager may not be initialized; dirs already passed to workspace isolation
             }
-            console.error(`Writable directories added: ${options.addDir.join(', ')}`);
+            cli.error(`Writable directories added: ${options.addDir.join(', ')}`);
         }
         // Handle --ephemeral: skip session persistence
         if (options.ephemeral) {
             const { getSessionStore } = await import("./persistence/session-store.js");
             const sessionStore = getSessionStore();
             sessionStore.setEphemeral(true);
-            console.error("Ephemeral mode: ENABLED (session will not be saved)");
-        }
-        // Handle --allowed-tools (like Claude Code --allowedTools)
-        if (options.allowedTools) {
-            const { setToolFilter, createToolFilter } = await import("./utils/tool-filter.js");
-            setToolFilter(createToolFilter({
-                enabledTools: options.allowedTools,
-            }));
-            console.error(`🔧 Allowed tools: ${options.allowedTools}`);
+            cli.info("Ephemeral mode: ENABLED (session will not be saved)");
+        }
+        // Handle --allowed-tools / --disallowed-tools (natively --allowedTools / --disallowedTools)
+        if (options.allowedTools || options.disallowedTools) {
+            const { setToolFilter, createToolFilter, getToolFilter } = await import("./utils/tool-filter.js");
+            const existing = getToolFilter();
+            const newFilter = createToolFilter({
+                enabledTools: options.allowedTools || (existing.enabledPatterns.length > 0 ? existing.enabledPatterns.join(',') : undefined),
+                disabledTools: options.disallowedTools || (existing.disabledPatterns.length > 0 ? existing.disabledPatterns.join(',') : undefined),
+            });
+            setToolFilter(newFilter);
+            if (options.allowedTools) {
+                cli.info(`Allowed tools: ${options.allowedTools}`);
+            }
+            if (options.disallowedTools) {
+                cli.info(`Disallowed tools: ${options.disallowedTools}`);
+            }
         }
         // Handle --mcp-debug
         if (options.mcpDebug) {
             process.env.MCP_DEBUG = 'true';
-            console.error("🔍 MCP debug: ENABLED");
+            cli.error("🔍 MCP debug: ENABLED");
         }
         // Set max-price for cost limit (like mistral-vibe)
         const maxPrice = parseFloat(options.maxPrice) || 10.0;
@@ -817,16 +1235,33 @@ program
             setToolFilter(filter);
             const allTools = await getAllCodeBuddyTools();
             const result = filterTools(allTools, filter);
-            console.error(formatFilterResult(result));
+            cli.info(formatFilterResult(result));
+        }
+        // Handle --yolo flag (equivalent to /yolo on, skip confirmation in non-interactive)
+        if (options.yolo) {
+            const { getAutonomyManager } = await import("./utils/autonomy-manager.js");
+            const autonomyManager = getAutonomyManager();
+            autonomyManager.enableYOLO(false);
+            autonomyManager.updateYOLOConfig({
+                maxAutoEdits: 50,
+                maxAutoCommands: 100,
+            });
+            process.env.YOLO_MODE = 'true';
+            cli.error("YOLO mode: ENABLED (full autonomy, $100 cost cap)");
         }
         // Handle vim mode
         if (options.vim) {
             process.env.GROK_VIM_MODE = 'true';
-            console.error("Vim mode: ENABLED");
+            cli.error("Vim mode: ENABLED");
         }
+        // Merge --print alias into --prompt
+        const promptArg = options.prompt || options.print;
+        const hasExplicitPrompt = Boolean(promptArg || (Array.isArray(message) && message.length > 0));
         // Check for piped input (like mistral-vibe: cat file.txt | grok)
+        // Avoid blocking on stdin when an explicit prompt is already provided
+        // (common in programmatic exec/spawn usage where stdin stays open).
         let pipedInput = '';
-        if (!process.stdin.isTTY) {
+        if (!process.stdin.isTTY && !hasExplicitPrompt) {
             // Reading from stdin (pipe or redirect)
             const chunks = [];
             for await (const chunk of process.stdin) {
@@ -836,14 +1271,15 @@ program
         }
         // Combine piped input with any CLI prompt or message args
         const combinedPrompt = [
-            options.prompt,
+            promptArg,
             message?.join(' '),
             pipedInput
         ].filter(Boolean).join('\n\n');
         // Headless mode: process prompt and exit (if prompt, message, or piped input provided)
-        if (combinedPrompt && (options.prompt || pipedInput)) {
-            await processPromptHeadless(combinedPrompt, apiKey, baseURL, model, maxToolRounds, options.selfHeal !== false, options.output || options.outputFormat || 'json', options.outputSchema);
-            process.exit(0);
+        if (combinedPrompt && (promptArg || pipedInput)) {
+            const headlessExitCode = await processPromptHeadless(combinedPrompt, apiKey, baseURL, model, maxToolRounds, options.selfHeal !== false, resolveHeadlessOutputFormat(options), options.outputSchema, options.agent);
+            await finalizeHeadlessRun(headlessExitCode);
+            return;
         }
         // Initialize rendering system (lazy load)
         const { initializeRenderers, configureRenderContext } = await lazyImport.renderers();
@@ -866,33 +1302,57 @@ program
                 logger.error(`❌ Agent not found: ${options.agent}`);
                 const agents = loader.listAgents();
                 if (agents.length > 0) {
-                    console.log("\n📋 Available agents:");
-                    agents.forEach(a => console.log(`   • ${a.id}`));
+                    cli.info("\n📋 Available agents:");
+                    agents.forEach(a => cli.info(`   • ${a.id}`));
                 }
                 process.exit(1);
             }
             customAgentConfig = agentConfig;
-            console.log(`🤖 Using agent: ${agentConfig.name}`);
+            cli.info(`🤖 Using agent: ${agentConfig.name}`);
+            const { setActiveCustomAgentRuntime } = await import('./agent/custom/custom-agent-runtime.js');
+            setActiveCustomAgentRuntime(agentConfig);
             // Override model if specified in agent config
             if (agentConfig.model) {
                 model = agentConfig.model;
             }
         }
+        recordStartupPhase('agent-create-start');
         const agent = new CodeBuddyAgent(apiKey, baseURL, model, maxToolRounds, true, systemPromptId);
+        recordStartupPhase('agent-create-done');
         // Apply custom agent system prompt if configured
         if (customAgentConfig?.systemPrompt) {
+            await agent.systemPromptReady;
             agent.setSystemPrompt(customAgentConfig.systemPrompt);
         }
+        // Apply custom-agent tool filters after CLI-level filters have
+        // been parsed. Explicit CLI allowlists win; agent disabledTools
+        // are added as a defensive blacklist.
+        if (customAgentConfig) {
+            const { hasCustomAgentToolFilter, buildCustomAgentToolFilter } = await import('./agent/custom/custom-agent-tool-filter.js');
+            if (hasCustomAgentToolFilter(customAgentConfig)) {
+                const { getToolFilter, setToolFilter } = await import('./utils/tool-filter.js');
+                const { getBuiltinToolNames } = await import('./codebuddy/tools.js');
+                const filter = buildCustomAgentToolFilter(customAgentConfig, getToolFilter(), getBuiltinToolNames());
+                setToolFilter(filter);
+                const disabled = filter.disabledPatterns.length
+                    ? filter.disabledPatterns.join(',')
+                    : 'none';
+                const enabled = filter.enabledPatterns.length
+                    ? filter.enabledPatterns.join(',')
+                    : 'all';
+                cli.info(`Agent tool filter: allowed=${enabled}; disabled=${disabled}`);
+            }
+        }
         // Enable auto-observation for computer-use agents
         if (customAgentConfig?.tags?.includes('computer-use')) {
             agent.enableAutoObservation();
         }
         // Probe for tool support if requested
         if (options.probeTools) {
-            console.log("🔍 Probing model for tool support...");
+            cli.info("🔍 Probing model for tool support...");
             const hasToolSupport = await agent.probeToolSupport();
             if (!hasToolSupport) {
-                console.log("ℹ️ Tool support: NOT DETECTED (switching to chat-only mode)");
+                cli.info("ℹ️ Tool support: NOT DETECTED (switching to chat-only mode)");
                 agent.switchToChatOnlyMode();
             }
         }
@@ -903,10 +1363,10 @@ program
                 const { getSecurityModeManager } = await lazyImport.securityModes();
                 const securityManager = getSecurityModeManager();
                 securityManager.setMode(options.securityMode);
-                console.log(`🛡️ Security mode: ${options.securityMode.toUpperCase()}`);
+                cli.info(`🛡️ Security mode: ${options.securityMode.toUpperCase()}`);
             }
             else {
-                console.warn(`⚠️ Invalid security mode: ${options.securityMode}. Using default (suggest).`);
+                cli.warn(`⚠️ Invalid security mode: ${options.securityMode}. Using default (suggest).`);
             }
         }
         // Configure dry-run mode
@@ -914,7 +1374,7 @@ program
             const { ConfirmationService } = await import("./utils/confirmation-service.js");
             const confirmationService = ConfirmationService.getInstance();
             confirmationService.setDryRunMode(true);
-            console.log("🔍 Dry-run mode: ENABLED (changes will be previewed, not applied)");
+            cli.info("🔍 Dry-run mode: ENABLED (changes will be previewed, not applied)");
         }
         // Load context files if specified and inject into agent
         if (options.context) {
@@ -927,7 +1387,7 @@ program
             });
             const files = await contextLoader.loadFiles();
             if (files.length > 0) {
-                console.log(contextLoader.getSummary(files));
+                cli.info(contextLoader.getSummary(files));
                 // Inject context into agent's message history as a system message
                 const contextContent = contextLoader.formatForPrompt(files);
                 agent.addSystemContext(contextContent);
@@ -936,7 +1396,7 @@ program
         // Configure caching and performance
         recordStartupPhase('perf-init-start');
         if (options.cache === false) {
-            console.log("📦 Response cache: DISABLED");
+            cli.info("📦 Response cache: DISABLED");
             // Disable performance caching when cache is disabled
             const { getPerformanceManager } = await lazyImport.performance();
             getPerformanceManager({ enabled: false });
@@ -950,46 +1410,61 @@ program
         // Configure self-healing
         if (options.selfHeal === false) {
             agent.setSelfHealing(false);
-            console.log("🔧 Self-healing: DISABLED");
+            cli.info("🔧 Self-healing: DISABLED");
         }
-        // Initialize Plugin System
-        try {
-            const { getPluginManager } = await lazyImport.pluginManager();
-            const pluginManager = getPluginManager();
-            await pluginManager.discover();
-        }
-        catch (error) {
-            logger.warn("Failed to initialize plugin system:", { error: String(error) });
-        }
-        console.log("🤖 Starting Code Buddy Conversational Assistant...\n");
-        // Initialize interaction logger for session tracking
-        try {
-            const { getInteractionLogger } = await import('./logging/interaction-logger.js');
-            const interactionLogger = getInteractionLogger();
-            const currentModel = agent.getCurrentModel?.() || model || 'unknown';
-            interactionLogger.startSession({
-                model: currentModel,
-                provider: baseURL?.includes('localhost') ? 'local' : 'xai',
-                cwd: process.cwd(),
-                tags: ['interactive'],
-            });
-            // Store logger on agent for use in message handlers
-            agent.__interactionLogger = interactionLogger;
-            // End session on process exit
-            const cleanup = () => {
-                try {
-                    interactionLogger.endSession();
+        cli.info("🤖 Starting Code Buddy Conversational Assistant...\n");
+        recordStartupPhase('user-settings-start');
+        await ensureUserSettingsDirectory();
+        recordStartupPhase('user-settings-done');
+        // ── Crash recovery: detect unclean shutdown and offer session resume ──
+        if (!options.resume && !options.continue) {
+            try {
+                const { checkCrashRecovery, clearRecoveryFiles } = await import('./errors/crash-recovery.js');
+                const recovery = await checkCrashRecovery(process.cwd());
+                if (recovery) {
+                    const age = Date.now() - new Date(recovery.timestamp).getTime();
+                    const mins = Math.round(age / 60000);
+                    cli.info('== Previous Session Crash Detected ==');
+                    cli.info(`   Time: ${new Date(recovery.timestamp).toLocaleString()} (${mins} min ago)`);
+                    if (recovery.crashReason) {
+                        cli.info(`   Reason: ${recovery.crashReason}`);
+                    }
+                    if (recovery.sessionId && recovery.sessionId !== 'unknown') {
+                        cli.info(`   Session: ${recovery.sessionId}`);
+                        // Attempt to auto-resume the crashed session
+                        try {
+                            const { getSessionStore } = await import('./persistence/session-store.js');
+                            const sessionStore = getSessionStore();
+                            const session = await sessionStore.getSessionByPartialId(recovery.sessionId);
+                            if (session) {
+                                await sessionStore.resumeSession(session.id);
+                                cli.info(`   Resuming session: ${session.name} (${session.messages.length} messages)`);
+                            }
+                            else {
+                                cli.info('   Session no longer available — starting fresh.');
+                            }
+                        }
+                        catch (err) {
+                            logger.debug('Failed to resume crashed session', { error: String(err) });
+                            cli.info('   Could not resume session — starting fresh.');
+                        }
+                    }
+                    if (recovery.lastUserMessage) {
+                        const preview = recovery.lastUserMessage.length > 80
+                            ? recovery.lastUserMessage.substring(0, 80) + '...'
+                            : recovery.lastUserMessage;
+                        cli.info(`   Last message: "${preview}"`);
+                    }
+                    cli.info('');
+                    // Clear the recovery marker so we don't show this again
+                    await clearRecoveryFiles();
                 }
-                catch (_err) { }
-            };
-            process.on('exit', cleanup);
-            process.on('SIGINT', () => { cleanup(); process.exit(0); });
-            process.on('SIGTERM', () => { cleanup(); process.exit(0); });
-        }
-        catch (err) {
-            logger.warn('Failed to initialize interaction logger', { error: String(err) });
+            }
+            catch (err) {
+                // Non-fatal — don't block startup if recovery check fails
+                logger.debug('Crash recovery check failed', { error: String(err) });
+            }
         }
-        await ensureUserSettingsDirectory();
         // Support variadic positional arguments for multi-word initial message
         const initialMessage = Array.isArray(message)
             ? message.join(" ")
@@ -1002,13 +1477,84 @@ program
         // Log startup metrics before UI render
         recordStartupPhase('ui-render');
         logStartupMetrics();
+        const totalStartupMs = Date.now() - STARTUP_TIME;
+        if (totalStartupMs > 5000) {
+            logger.warn(`Slow startup detected: ${totalStartupMs}ms. Run with PERF_TIMING=true for phase breakdown.`);
+        }
+        else {
+            logger.debug(`Startup completed in ${totalStartupMs}ms`);
+        }
         // Configure Ink render options
         const inkOptions = { exitOnCtrlC: true };
         if (options.altScreen === false) {
             // --no-alt-screen disables Ink's alternate screen buffer
             inkOptions.patchConsole = false;
         }
+        // Opt the interactive session into the Hermes-style post-session background
+        // self-learning review (still gated by CODEBUDDY_LEARNING_BACKGROUND_REVIEW).
+        // Only the interactive TUI enables it, so cron/headless/sub-agent runs cannot
+        // trigger a review (recursion + cost safety).
+        agent.enableBackgroundReview();
         render(React.createElement(ChatInterface, { agent, initialMessage }), inkOptions);
+        // Initialize plugin system in background (non-blocking)
+        setImmediate(async () => {
+            try {
+                const { getPluginManager } = await lazyImport.pluginManager();
+                const pluginManager = getPluginManager();
+                await pluginManager.discover();
+            }
+            catch (error) {
+                logger.warn('Failed to initialize plugin system:', { error: String(error) });
+            }
+        });
+        // Initialize interaction logger + RunStore in background (non-blocking)
+        setImmediate(async () => {
+            try {
+                const { getInteractionLogger } = await import('./logging/interaction-logger.js');
+                const interactionLogger = getInteractionLogger();
+                const currentModel = agent.getCurrentModel?.() || model || 'unknown';
+                interactionLogger.startSession({
+                    model: currentModel,
+                    provider: baseURL?.includes('localhost') ? 'local' : 'xai',
+                    cwd: process.cwd(),
+                    tags: ['interactive'],
+                });
+                agent.__interactionLogger = interactionLogger;
+                const cleanup = () => {
+                    try {
+                        interactionLogger.endSession();
+                    }
+                    catch (e) {
+                        logger.debug('Failed to end interaction logger session', { error: String(e) });
+                    }
+                };
+                process.on('exit', cleanup);
+                process.on('SIGINT', () => { cleanup(); process.exit(0); });
+                process.on('SIGTERM', () => { cleanup(); process.exit(0); });
+            }
+            catch (err) {
+                logger.warn('Failed to initialize interaction logger', { error: String(err) });
+            }
+            try {
+                const { RunStore } = await import('./observability/run-store.js');
+                const runStore = RunStore.getInstance();
+                const runId = runStore.startRun('interactive session', {
+                    channel: 'terminal',
+                    tags: ['interactive', model || 'unknown'],
+                });
+                agent.setRunId(runId);
+                const cleanupRun = () => {
+                    try {
+                        runStore.endRun(runId, 'completed');
+                    }
+                    catch (_err) { /* ignore */ }
+                };
+                process.on('exit', cleanupRun);
+            }
+            catch (err) {
+                logger.debug('RunStore init skipped', { error: String(err) });
+            }
+        });
         // Check for updates in background after UI renders
         setImmediate(async () => {
             try {
@@ -1019,6 +1565,16 @@ program
                 // Update check should never break the CLI
             }
         });
+        // Generate .codebuddy/TOOLS.md in the background (non-blocking)
+        setImmediate(async () => {
+            try {
+                const { generateToolsMd } = await import('./tools/tools-md-generator.js');
+                await generateToolsMd();
+            }
+            catch (_err) {
+                logger.debug('TOOLS.md background generation failed', { error: _err });
+            }
+        });
         // Start background preloading of common modules after UI renders
         setImmediate(async () => {
             try {
@@ -1049,6 +1605,9 @@ gitCommand
     .option("-m, --model <model>", "AI model to use (e.g., grok-code-fast-1, grok-4-latest) (or set GROK_MODEL env var)")
     .option("--max-tool-rounds <rounds>", "maximum number of tool execution rounds (default: 400)", "400")
     .action(async (options) => {
+    // Load environment before changing cwd so root .env values (API keys) remain available
+    // even when --directory points to a workspace without its own .env file.
+    await ensureEnvLoaded();
     if (options.directory) {
         try {
             process.chdir(options.directory);
@@ -1091,7 +1650,8 @@ function removeCommands(parent, names) {
     const nameSet = new Set(Array.isArray(names) ? names : [names]);
     const cmds = parent.commands;
     for (let i = cmds.length - 1; i >= 0; i--) {
-        if (nameSet.has(cmds[i].name())) {
+        const cmd = cmds[i];
+        if (cmd !== undefined && nameSet.has(cmd.name())) {
             cmds.splice(i, 1);
         }
     }
@@ -1134,6 +1694,18 @@ addLazyCommand(program, 'pipeline', 'Manage and run pipeline workflows', async (
     const { createPipelineCommand } = await import('./commands/pipeline.js');
     return createPipelineCommand();
 });
+// Channels command - manage channel connections (Telegram, Discord, Slack, etc.)
+program
+    .command("channels")
+    .description("Manage channel connections (Telegram, Discord, Slack, etc.)")
+    .argument("[action]", "start|stop|status|list", "list")
+    .option("--type <type>", "Channel type (telegram|discord|slack|whatsapp|signal|google-chat|teams|matrix|webchat)")
+    .option("--config <path>", "Channel config file path")
+    .option("--json", "Output JSON for status")
+    .action(async (action, options) => {
+    const { handleChannels } = await import("./commands/handlers/channel-handlers.js");
+    await handleChannels(action, options);
+});
 // Server command - start the HTTP/WebSocket API server
 program
     .command("server")
@@ -1155,6 +1727,124 @@ program
         process.exit(1);
     }
 });
+// Desktop GUI commands
+program
+    .command("gui")
+    .description("Launch the Code Buddy desktop GUI (Electron)")
+    .option("--dev", "start with Vite dev server (hot reload)")
+    .option("--detach", "run in background")
+    .action(async (options) => {
+    const { launchDesktop } = await import("./desktop/launcher.js");
+    const code = await launchDesktop({
+        dev: options.dev,
+        detach: options.detach,
+    });
+    process.exit(code);
+});
+program
+    .command("desktop")
+    .description("Alias for 'buddy gui'")
+    .option("--dev", "start with Vite dev server")
+    .option("--detach", "run in background")
+    .action(async (options) => {
+    const { launchDesktop } = await import("./desktop/launcher.js");
+    const code = await launchDesktop({
+        dev: options.dev,
+        detach: options.detach,
+    });
+    process.exit(code);
+});
+program
+    .command("install-gui")
+    .description("Install Electron and build the desktop GUI")
+    .action(async () => {
+    const { installGUI } = await import("./desktop/installer.js");
+    await installGUI();
+});
+// 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) => {
+    const target = (provider ?? "chatgpt").toLowerCase();
+    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.");
+        process.exit(1);
+    }
+    const { loginInteractive, getCodexAuthFilePath } = await import("./providers/codex-oauth.js");
+    cli.stdout("🔐 ChatGPT login");
+    cli.stdout("Opening your browser to https://auth.openai.com/oauth/authorize ...");
+    cli.stdout("Sign in with your ChatGPT account, then return to this terminal.\n");
+    try {
+        const auth = await loginInteractive();
+        cli.stdout("✅ Authenticated successfully");
+        if (auth.email)
+            cli.stdout(`   Account:    ${auth.email}`);
+        if (auth.plan_type)
+            cli.stdout(`   Plan:       ${auth.plan_type}`);
+        if (auth.is_fedramp)
+            cli.stdout(`   FedRAMP:    yes`);
+        if (auth.account_id)
+            cli.stdout(`   Account ID: ${auth.account_id}`);
+        cli.stdout(`\nTokens stored at: ${getCodexAuthFilePath()}`);
+        cli.stdout("Run `buddy --print \"hello\"` to test, or just `buddy` for a chat session.");
+    }
+    catch (err) {
+        cli.error(`❌ Login failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+});
+program
+    .command("logout [provider]")
+    .description("Clear stored credentials for a provider (default: chatgpt)")
+    .action(async (provider) => {
+    const target = (provider ?? "chatgpt").toLowerCase();
+    if (target !== "chatgpt" && target !== "codex" && target !== "openai") {
+        cli.stdout(`Unknown provider: "${provider}". Only \`chatgpt\` is supported.`);
+        process.exit(1);
+    }
+    const { hasCodexCredentials, clearCodexCredentials, getCodexAuthFilePath } = await import("./providers/codex-oauth.js");
+    if (!hasCodexCredentials()) {
+        cli.stdout("No ChatGPT credentials on disk — already logged out.");
+        return;
+    }
+    clearCodexCredentials();
+    cli.stdout(`✅ ChatGPT credentials cleared (${getCodexAuthFilePath()})`);
+});
+program
+    .command("whoami")
+    .description("Show current authentication status (email, plan, account)")
+    .action(async () => {
+    const { hasCodexCredentials, getChatGptAuth } = await import("./providers/codex-oauth.js");
+    if (!hasCodexCredentials()) {
+        cli.stdout("ChatGPT: not connected (run `buddy login` to authenticate)");
+        return;
+    }
+    try {
+        const auth = await getChatGptAuth();
+        if (!auth) {
+            cli.stdout("ChatGPT: token unreadable. Run `buddy logout` then `buddy login`.");
+            return;
+        }
+        cli.stdout("ChatGPT: ✅ connected");
+        if (auth.email)
+            cli.stdout(`  Account:    ${auth.email}`);
+        if (auth.plan_type)
+            cli.stdout(`  Plan:       ${auth.plan_type}`);
+        if (auth.account_id)
+            cli.stdout(`  Account ID: ${auth.account_id}`);
+        if (auth.is_fedramp)
+            cli.stdout(`  FedRAMP:    yes`);
+    }
+    catch (err) {
+        cli.error(`Error reading credentials: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+});
 // MCP Server command - run Code Buddy as an MCP tool provider over stdio
 program
     .command("mcp-server")
@@ -1164,8 +1854,9 @@ program
     if (options.list) {
         const { CodeBuddyMCPServer } = await import("./mcp/mcp-server.js");
         const tools = CodeBuddyMCPServer.getToolDefinitions();
+        // Pipeable listing.
         for (const tool of tools) {
-            console.log(`${tool.name}: ${tool.description}`);
+            cli.stdout(`${tool.name}: ${tool.description}`);
         }
         return;
     }
@@ -1241,31 +1932,75 @@ for (const cmdName of utilityCommandNames) {
         await loadUtilityCommands();
     });
 }
-// OpenClaw-inspired commands
+// Enterprise-grade commands
 addLazyCommandGroup(program, 'heartbeat', 'Manage the heartbeat engine (periodic agent wake)', async () => {
-    const { registerHeartbeatCommands } = await import('./commands/cli/openclaw-commands.js');
+    const { registerHeartbeatCommands } = await import('./commands/cli/native-engine-commands.js');
     registerHeartbeatCommands(program);
 });
 addLazyCommandGroup(program, 'hub', 'Skills marketplace (search, install, publish)', async () => {
-    const { registerHubCommands } = await import('./commands/cli/openclaw-commands.js');
+    const { registerHubCommands } = await import('./commands/cli/native-engine-commands.js');
     registerHubCommands(program);
 });
+addLazyCommandGroup(program, 'gateway-pairing', 'Operator approval for gateway device pairing', async () => {
+    const { registerGatewayPairingCommands } = await import('./commands/cli/native-engine-commands.js');
+    registerGatewayPairingCommands(program);
+});
+addLazyCommandGroup(program, 'screen', 'Capture, record, or watch the screen / a window (real-time machine context)', async () => {
+    const { registerScreenCommands } = await import('./commands/cli/screen-commands.js');
+    registerScreenCommands(program);
+});
+addLazyCommandGroup(program, 'autonomy', 'Autonomous fleet loop (claim + run colab tasks on local-first models)', async () => {
+    const { registerFleetAutonomyCommands } = await import('./commands/cli/native-engine-commands.js');
+    registerFleetAutonomyCommands(program);
+});
 addLazyCommandGroup(program, 'device', 'Manage paired device nodes (SSH, ADB, local)', async () => {
     const { registerDeviceCommands } = await import('./commands/cli/device-commands.js');
     registerDeviceCommands(program);
 });
 addLazyCommandGroup(program, 'identity', 'Manage agent identity files (SOUL.md, USER.md, etc.)', async () => {
-    const { registerIdentityCommands } = await import('./commands/cli/openclaw-commands.js');
+    const { registerIdentityCommands } = await import('./commands/cli/native-engine-commands.js');
     registerIdentityCommands(program);
 });
+addLazyCommandGroup(program, 'companion', 'Configure Buddy as a ChatGPT-backed voice companion', async () => {
+    const { registerCompanionCommands } = await import('./commands/cli/native-engine-commands.js');
+    registerCompanionCommands(program);
+});
 addLazyCommandGroup(program, 'groups', 'Manage group chat security', async () => {
-    const { registerGroupCommands } = await import('./commands/cli/openclaw-commands.js');
+    const { registerGroupCommands } = await import('./commands/cli/native-engine-commands.js');
     registerGroupCommands(program);
 });
 addLazyCommandGroup(program, 'auth-profile', 'Manage authentication profiles (API key rotation)', async () => {
-    const { registerAuthProfileCommands } = await import('./commands/cli/openclaw-commands.js');
+    const { registerAuthProfileCommands } = await import('./commands/cli/native-engine-commands.js');
     registerAuthProfileCommands(program);
 });
+addLazyCommandGroup(program, 'fleet', 'Inspect Fleet routing and dispatch policy decisions', async () => {
+    const { registerFleetCommands } = await import('./commands/cli/fleet-commands.js');
+    registerFleetCommands(program);
+});
+addLazyCommandGroup(program, 'gitnexus', 'Interact with GitNexus for code understanding and session syncing', async () => {
+    const { registerGitNexusCommands } = await import('./commands/cli/gitnexus-commands.js');
+    registerGitNexusCommands(program);
+});
+addLazyCommandGroup(program, 'hermes', 'Inspect the native Hermes-inspired Code Buddy agent profile', async () => {
+    const { registerHermesCommands } = await import('./commands/cli/hermes-commands.js');
+    registerHermesCommands(program);
+});
+addLazyCommandGroup(program, 'acp', 'Run Code Buddy as an ACP (Agent Client Protocol) agent over stdio for editor integration', async () => {
+    const { registerAcpCommand } = await import('./commands/cli/acp-command.js');
+    registerAcpCommand(program);
+});
+addLazyCommandGroup(program, 'tools', 'Inspect tool profiles and effective tool availability', async () => {
+    const { registerToolsCommands } = await import('./commands/cli/tools-commands.js');
+    registerToolsCommands(program);
+});
+addLazyCommandGroup(program, 'autonomous-code', 'Run a guarded Agentic Coding Cell task contract', async () => {
+    const { registerAutonomousCodeCommand } = await import('./commands/cli/autonomous-code-command.js');
+    registerAutonomousCodeCommand(program);
+});
+addLazyCommandGroup(program, 'session', 'Manage saved sessions', async () => {
+    const { registerSessionCommands } = await import('./cli/session-commands.js');
+    registerSessionCommands(program);
+});
 addLazyCommandGroup(program, 'config', 'Show environment variable configuration and validation', async () => {
     const { registerConfigCommand } = await import('./commands/cli/config-command.js');
     registerConfigCommand(program);
@@ -1276,10 +2011,20 @@ addLazyCommandGroup(program, 'dev', 'Golden-path developer workflows (plan, run,
     registerDevCommands(program);
 });
 // Run observability — list, show, tail, replay
-addLazyCommandGroup(program, 'runs', 'Inspect and replay agent runs (observability)', async () => {
+addLazyCommandGroup(program, 'run', 'Inspect and replay agent runs (observability)', async () => {
     const { registerRunCommands } = await import('./commands/run-cli/index.js');
     registerRunCommands(program);
 });
+// Cron — author and manage scheduled jobs (incl. watchdog + pre-check)
+addLazyCommandGroup(program, 'cron', 'Author and manage scheduled cron jobs', async () => {
+    const { registerCronCommands } = await import('./commands/cron-cli/index.js');
+    registerCronCommands(program);
+});
+// Skills — browse, inspect telemetry, enable/disable installed SKILL.md packages
+addLazyCommandGroup(program, 'skills', 'Browse and manage installed skill packages', async () => {
+    const { registerSkillsCommands } = await import('./commands/skills-cli/index.js');
+    registerSkillsCommands(program);
+});
 // DM pairing — approve, revoke, list, pending
 addLazyCommand(program, 'pairing', 'Manage DM pairing security (allowlist for messaging channel senders)', async () => {
     const { createPairingCommand } = await import('./commands/pairing.js');
@@ -1295,6 +2040,11 @@ addLazyCommand(program, 'research', 'Wide Research: spawn parallel agent workers
     const { createResearchCommand } = await import('./commands/research/index.js');
     return createResearchCommand();
 });
+// Planning Flow — OpenManus-compatible multi-agent orchestration
+addLazyCommand(program, 'flow', 'Execute a multi-agent planning flow (OpenManus-compatible): plan → execute → synthesize', async () => {
+    const { createFlowCommand } = await import('./commands/flow.js');
+    return createFlowCommand();
+});
 // 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');
@@ -1310,5 +2060,126 @@ addLazyCommand(program, 'lessons', 'Manage lessons learned — self-improvement
     const { createLessonsCommand } = await import('./commands/lessons.js');
     return createLessonsCommand();
 });
+// Spec — BMAD-inspired spec-driven, review-gated work pipeline
+addLazyCommandGroup(program, 'spec', 'Spec-driven, review-gated work pipeline (durable stories; approve before implementing)', async () => {
+    const { createSpecCommand } = await import('./commands/spec.js');
+    program.addCommand(createSpecCommand());
+});
+// User model — structured model of the user's working preferences (propose/review)
+addLazyCommand(program, 'user-model', 'Manage the local user model — working preferences, propose/review (no silent write)', async () => {
+    const { createUserModelCommand } = await import('./commands/user-model.js');
+    return createUserModelCommand();
+});
+// Update — channel-based update management (stable/beta/dev)
+addLazyCommand(program, 'update', 'Update Code Buddy (switch channels: stable, beta, dev)', async () => {
+    const { createUpdateCommand } = await import('./commands/update.js');
+    return createUpdateCommand();
+});
+// 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');
+    registerNodeCommands(program);
+});
+// Secrets — encrypted vault for API keys and credentials
+addLazyCommandGroup(program, 'secrets', 'Manage API keys and credentials (encrypted vault)', async () => {
+    const { registerSecretsCommands } = await import('./commands/cli/secrets-command.js');
+    registerSecretsCommands(program);
+});
+// Approvals — manage tool/action approval requests
+addLazyCommandGroup(program, 'approvals', 'Manage tool/action approval requests', async () => {
+    const { registerApprovalsCommands } = await import('./commands/cli/approvals-command.js');
+    registerApprovalsCommands(program);
+});
+// Insights — token/cost/activity analytics (Hermes parity: `hermes insights`)
+addLazyCommandGroup(program, 'insights', 'Token, cost, and activity analytics (read-only)', async () => {
+    const { registerInsightsCommands } = await import('./commands/cli/insights-command.js');
+    registerInsightsCommands(program);
+});
+// Bundles — group skills under one named slash-command (Hermes parity: `hermes bundles`)
+addLazyCommandGroup(program, 'bundles', 'Group skills under a single named slash-command bundle', async () => {
+    const { registerBundlesCommands } = await import('./commands/cli/bundles-command.js');
+    registerBundlesCommands(program);
+});
+// Improve — recursive self-improvement engine (empirically-gated, reversible)
+addLazyCommandGroup(program, 'improve', 'Recursive self-improvement: empirically validate and apply reversible learning improvements', async () => {
+    const { registerImproveCommands } = await import('./commands/cli/improve-command.js');
+    registerImproveCommands(program);
+});
+// LSP — Language Server Protocol diagnostics (Hermes parity: `hermes lsp`)
+addLazyCommandGroup(program, 'lsp', 'Language Server Protocol diagnostics', async () => {
+    const { registerLspCommands } = await import('./commands/cli/lsp-command.js');
+    registerLspCommands(program);
+});
+// Proxy — OpenAI-compatible HTTP proxy for third-party clients (Hermes parity: `hermes proxy`)
+addLazyCommandGroup(program, 'proxy', 'Start an OpenAI-compatible HTTP proxy in front of Code Buddy (for third-party clients)', async () => {
+    const { registerProxyCommands } = await import('./commands/cli/proxy-command.js');
+    registerProxyCommands(program);
+});
+// Deploy — generate cloud deployment configurations
+addLazyCommandGroup(program, 'deploy', 'Generate cloud deployment configurations (Fly, Railway, Render, Nix)', async () => {
+    const { registerDeployCommands } = await import('./commands/cli/deploy-command.js');
+    registerDeployCommands(program);
+});
+// Backup — local backup management (Native Engine v2026.3.8 alignment)
+program
+    .command('backup [subcommand] [args...]')
+    .description('Manage .codebuddy/ backups (create, verify, list, restore)')
+    .option('--only-config', 'Only backup configuration files')
+    .option('--no-include-workspace', 'Exclude workspace data')
+    .option('--output <path>', 'Custom output directory')
+    .action(async (subcommand, args, opts) => {
+    const { handleBackup } = await import('./commands/handlers/backup-handlers.js');
+    const flags = [];
+    if (opts.onlyConfig)
+        flags.push('--only-config');
+    if (opts.includeWorkspace === false)
+        flags.push('--no-include-workspace');
+    if (opts.output)
+        flags.push('--output', opts.output);
+    const fullArgs = [subcommand || 'list', ...(args || []), ...flags].join(' ');
+    const result = await handleBackup(fullArgs);
+    // Backup command output is pipeable (scripts often capture it).
+    if (result.response)
+        cli.stdout(result.response);
+});
+// Cloud — background agent tasks (Cursor/Codex parity)
+program
+    .command('cloud [subcommand] [args...]')
+    .description('Manage cloud background agent tasks (submit, status, list, cancel, logs)')
+    .action(async (subcommand, args) => {
+    const { handleCloud } = await import('./commands/handlers/cloud-handlers.js');
+    const fullArgs = [subcommand || 'list', ...(args || [])];
+    const result = await handleCloud(fullArgs);
+    // Cloud command output is pipeable (scripts often capture task IDs).
+    if (result.entry?.content)
+        cli.stdout(result.entry.content);
+});
+// Hidden child entry for per-task subprocess isolation (CODEBUDDY_CLOUD_SUBPROCESS).
+// Runs a single previously-submitted cloud task to completion in its own process.
+program
+    .command('cloud-run-task <taskId>', { hidden: true })
+    .option('--tasks-dir <dir>', 'task store directory')
+    .action(async (taskId, options) => {
+    try {
+        const { CloudAgentRunner } = await import('./cloud/cloud-agent-runner.js');
+        const runner = new CloudAgentRunner(options.tasksDir);
+        const config = runner.loadTaskConfig(taskId);
+        if (!config) {
+            cli.error(`No persisted config for cloud task '${taskId}'`);
+            process.exit(1);
+        }
+        await runner.runTaskInProcess(taskId, config);
+        process.exit(0);
+    }
+    catch (err) {
+        cli.error(`cloud-run-task failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+});
+// Completions — generate or install shell completion scripts
+addLazyCommand(program, 'completions', 'Generate or install shell completion scripts (bash, zsh, fish, powershell)', async () => {
+    const { createCompletionsCommand } = await import('./commands/cli/completions-command.js');
+    return createCompletionsCommand();
+});
 program.parse();
 //# sourceMappingURL=index.js.map