@phuetz/code-buddy 1.6.1 → 2.1.0

package/dist/index.js

@@ -10,8 +10,19 @@ 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 { addLazyCommandGroup, getNonInteractiveUnknownCommand, removeCommands, } from './cli/command-routing.js';
+import { attachUnknownOptionHint } from './cli/unknown-option-hint.js';
+import { parseListenPort } from './cli/listen-port.js';
+import { hoistPermissionModeOption, installPermissionModeActionHook, parseCliPermissionMode, } from './cli/permission-mode-option.js';
+import { getRequestedProfile } from './cli/requested-profile.js';
+import { findUnexecutedProseToolCall, formatEmptyHeadlessResponseError, isHeadlessFinalResponseEmpty, resolveHeadlessOutputFormat, resolveHeadlessTurnExitCode, } from './cli/headless-options.js';
+import { validateOutputText } from './utils/output-schema-validator.js';
 import { resolveCliModelList } from './cli/model-listing.js';
+import { registerBackupCommand } from './commands/cli/backup-command.js';
+import { registerSensoryCommand } from './commands/cli/sensory-command.js';
+import { NO_PROVIDER_GUIDANCE, recoverFirstRunWithChatGpt, } from './cli/first-run.js';
+import { getConfigManager } from './config/toml-config.js';
+import { getHiddenCliCommands } from './config/feature-surface.js';
 // Read version from package.json
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -22,6 +33,7 @@ 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 { writeFileAtomic } from './utils/atomic-write.js';
 // Import graceful shutdown for clean application termination
 import { initializeGracefulShutdown, getShutdownManager, } from "./utils/graceful-shutdown.js";
 import { sweepStaleCodebuddyTemp } from "./utils/disk-guard.js";
@@ -290,7 +302,7 @@ function _detectProviderFromEnvLegacy() {
                         provider: 'chatgpt',
                         apiKey: 'oauth-chatgpt', // sentinel consumed by CodeBuddyClient
                         baseURL: 'https://chatgpt.com/backend-api/codex',
-                        defaultModel: process.env.CHATGPT_MODEL || 'gpt-5.5',
+                        defaultModel: process.env.CHATGPT_MODEL || 'gpt-5.6-sol',
                     };
                 }
             }
@@ -441,7 +453,7 @@ async function detectOnboardedLocalProvider() {
             source: 'environment',
         };
     }
-    catch {
+    catch (_error) {
         return null;
     }
 }
@@ -508,23 +520,9 @@ async function saveCommandLineSettings(apiKey, baseURL) {
         cli.warn(`⚠️ Could not save settings to file: ${error instanceof Error ? error.message : "Unknown error"}`);
     }
 }
-/**
- * A saved/default model is only usable if it matches the detected provider's
- * backend: a `grok-*` slug 404s on the ChatGPT/Codex backend, and a `gpt-5.*`
- * slug 404s on xAI. We only enforce this for the two providers with a known
- * hard incompatibility (grok ↔ chatgpt); other providers are left untouched so
- * local/OpenAI/Anthropic model names pass through as before.
- */
-function isModelCompatibleWithProvider(model, provider) {
-    if (!provider)
-        return true;
-    const looksGrok = /grok/i.test(model);
-    if (provider === 'grok')
-        return looksGrok;
-    if (provider === 'chatgpt')
-        return /^(gpt-|o[1-9]|codex)/i.test(model) && !looksGrok;
-    return true;
-}
+/** Providers served by a local OpenAI-compatible runtime (no cloud model catalog). */
+import { isModelCompatibleWithProvider } from './providers/model-provider-compat.js';
+export { isModelCompatibleWithProvider };
 // Load model from detected provider or user settings
 async function loadModel() {
     await ensureEnvLoaded();
@@ -532,41 +530,84 @@ async function loadModel() {
     if (process.env.GROK_MODEL)
         return process.env.GROK_MODEL;
     const detected = await getDetectedProvider();
-    // 2. Project/user settings override auto-detection — UNLESS the saved model is
-    //    incompatible with the detected provider. A `gpt-5.5` left in settings.json
-    //    would 404 against xAI after `buddy login xai`; symmetrically, a stale
-    //    `grok-code-fast-1` default 404s against the ChatGPT/Codex backend (which
-    //    then falls back to another unsupported slug and crashes). In either
-    //    mismatch, prefer the detected provider's own default model.
+    // Read the saved model once (reused by both the settings path and the
+    // local-runtime path below).
+    let settingsModel;
     try {
         const getSettingsManager = await lazyImport.settingsManager();
-        const settingsModel = getSettingsManager().getCurrentModel();
-        if (settingsModel && isModelCompatibleWithProvider(settingsModel, detected?.provider)) {
-            return settingsModel;
-        }
+        settingsModel = getSettingsManager().getCurrentModel() || undefined;
     }
     catch (_err) {
         logger.debug('Failed to load model from settings manager', { error: _err });
     }
-    // 3. Fallback to auto-detected provider's default model
+    // 2. Local runtime (Ollama): resolve to a model that is ACTUALLY installed,
+    //    never a stale cloud slug. Detection sets `defaultModel` to the advertised
+    //    onboarding tag (e.g. `qwen2.5-coder:7b`), but a fresh box rarely has that
+    //    exact tag pulled — sending it (or a leftover `grok-code-fast-1` from
+    //    settings) yields a cryptic `404 model not found`. Probe the server's tags
+    //    and pick a real one; if none is installed / the server is down, fail with
+    //    a clear `ollama pull …` hint. This is the "$0 local" onboarding path, so
+    //    it must never dead-end on a Grok 404. Only triggers for local runtimes,
+    //    so cloud/no-provider behavior stays byte-identical.
+    if (detected && detected.provider === 'ollama') {
+        const { resolveInstalledOllamaModel, buildOllamaPullHint } = await import('./providers/local-model-resolver.js');
+        const requested = process.env.OLLAMA_MODEL ||
+            (settingsModel && isModelCompatibleWithProvider(settingsModel, 'ollama')
+                ? settingsModel
+                : undefined) ||
+            detected.defaultModel;
+        const resolution = await resolveInstalledOllamaModel({
+            baseURL: detected.baseURL,
+            requested,
+        });
+        if (resolution.model)
+            return resolution.model;
+        const hint = buildOllamaPullHint({
+            baseURL: detected.baseURL,
+            reachable: resolution.reachable,
+            requested,
+        });
+        const { shouldBypassUnreachableLocalPreflight } = await import('./providers/provider-failover-policy.js');
+        if (shouldBypassUnreachableLocalPreflight()) {
+            cli.warn(`${hint}\nDeclared provider failover is enabled; continuing so chat() can try the backup chain.`);
+            return requested || detected.defaultModel;
+        }
+        cli.error(hint);
+        process.exit(1);
+    }
+    // 3. Project/user settings override auto-detection — UNLESS the saved model is
+    //    incompatible with the detected provider. A `gpt-5.5` left in settings.json
+    //    would 404 against xAI after `buddy login xai`; symmetrically, a stale
+    //    `grok-code-fast-1` default 404s against the ChatGPT/Codex backend (which
+    //    then falls back to another unsupported slug and crashes). In either
+    //    mismatch, prefer the detected provider's own default model.
+    if (settingsModel && isModelCompatibleWithProvider(settingsModel, detected?.provider)) {
+        return settingsModel;
+    }
+    // 4. Fallback to auto-detected provider's default model
     if (detected)
         return detected.defaultModel;
     return undefined;
 }
 /**
- * Active-LLM auto-failover. When `[llm] enabled` (or CODEBUDDY_LLM_FAILOVER=1),
- * build the registry of the user's live logins and inject it into the agent's
- * client fallback list — so a failing primary transparently fails over to the
- * next active LLM (resilience order by default: capable/subscription first,
- * local last). OFF by default → single-provider behavior is unchanged.
+ * Active-LLM auto-failover. `CODEBUDDY_LLM_FAILOVER` is a deprecated alias of
+ * `CODEBUDDY_PROVIDER_FALLBACK` — both take the declared client path. When no
+ * `CODEBUDDY_FALLBACK_CHAIN` is set, the authenticated registry is injected as
+ * the candidate list (resilience order by default).
  */
 async function applyActiveLlmFailover(agent) {
     try {
         const { getConfigManager } = await import('./config/toml-config.js');
+        const { isDeclaredProviderFallbackEnabled, warnLegacyLlmFailoverAlias } = await import('./providers/provider-failover-policy.js');
         const llmCfg = getConfigManager().getConfig().llm;
-        const enabled = Boolean(llmCfg?.enabled) || process.env.CODEBUDDY_LLM_FAILOVER === '1';
+        warnLegacyLlmFailoverAlias();
+        const enabled = isDeclaredProviderFallbackEnabled() || Boolean(llmCfg?.enabled);
         if (!enabled)
             return;
+        if (process.env.CODEBUDDY_FALLBACK_CHAIN) {
+            logger.info('Active-LLM failover: CODEBUDDY_FALLBACK_CHAIN wins over the registry list');
+            return;
+        }
         const primary = await getDetectedProvider();
         const { buildActiveLlmRegistry } = await import('./providers/active-llm-registry.js');
         const orderEnv = process.env.CODEBUDDY_LLM_ORDER;
@@ -636,7 +677,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.`;
         cli.info("🤖 Generating commit message...");
-        const commitMessageEntries = await agent.processUserMessage(commitPrompt);
+        const commitMessageEntries = await agent.processUserMessage(commitPrompt, { surface: 'cli' });
         let commitMessage = "";
         // Extract the commit message from the AI response
         for (const entry of commitMessageEntries) {
@@ -839,9 +880,15 @@ async function applyCustomAgentToolFilter(agentConfig) {
     setToolFilter(buildCustomAgentToolFilter(agentConfig, getToolFilter(), getBuiltinToolNames()));
 }
 // Headless mode processing function
-async function processPromptHeadless(prompt, apiKey, baseURL, model, maxToolRounds, selfHealEnabled = true, outputFormat = 'json', outputSchemaPath, agentName) {
+async function processPromptHeadless(prompt, apiKey, baseURL, model, maxToolRounds, selfHealEnabled = true, outputFormat = 'json', outputLastMessagePath, outputSchemaPath, agentName) {
     const previousDisableMCP = process.env.CODEBUDDY_DISABLE_MCP;
     const previousHeadless = process.env.CODEBUDDY_HEADLESS;
+    const startedAt = Date.now();
+    let agent;
+    let interactionLogger = null;
+    let runStore;
+    let runId;
+    let runStatus = 'failed';
     // Headless defaults MCP OFF (startup cost / determinism), but respect an
     // explicit opt-in so `CODEBUDDY_DISABLE_MCP=false buddy -p …` can use MCP
     // servers (e.g. the Code Explorer / code-explorer bridge, or the benchmark's
@@ -852,8 +899,50 @@ async function processPromptHeadless(prompt, apiKey, baseURL, model, maxToolRoun
         const customAgentConfig = await loadCustomAgentForCli(agentName, false);
         const modelToUse = customAgentConfig?.model ?? model;
         const CodeBuddyAgent = await lazyImport.CodeBuddyAgent();
-        const agent = new CodeBuddyAgent(apiKey, baseURL, modelToUse, maxToolRounds);
+        // Evolved execution strategy (opt-in CODEBUDDY_SELF_IMPROVE_STRATEGIES): fills only what
+        // the user left unset — an explicit --max-tool-rounds always wins. Off ⇒ empty overlay.
+        const { resolveStrategyOverlay, applyStrategyCostCap } = await import('./agent/self-improvement/strategy-runtime.js');
+        const strategy = resolveStrategyOverlay('headless', { maxToolRounds });
+        if (strategy.strategyId && strategy.strategyId !== 'baseline') {
+            const cost = applyStrategyCostCap(strategy);
+            logger.info(`Execution strategy ${strategy.strategyId} in force (rounds ${strategy.maxToolRounds ?? maxToolRounds ?? 'explicit'}, cost cap ${cost.maxCostUsd !== undefined ? `$${cost.maxCostUsd}` : 'explicit'}, ${strategy.systemPromptAppend ? 'with' : 'no'} directives)`);
+        }
+        agent = new CodeBuddyAgent(apiKey, baseURL, modelToUse, maxToolRounds ?? strategy.maxToolRounds, true, undefined, undefined, strategy.systemPromptAppend);
         await applyActiveLlmFailover(agent);
+        // A headless prompt is a real session unless --ephemeral was selected.
+        // The timeline hook is installed by the agent constructor and resolves the
+        // current session lazily at turn completion, so the session must exist
+        // before the first message is processed.
+        const sessionStore = agent.getSessionStore();
+        if (!sessionStore.isEphemeral()) {
+            // GK29: --resume/--continue hydrate the persisted session in headless mode; GK28: the run
+            // record keeps the session's working directory for `buddy run show`.
+            const existingId = sessionStore.getCurrentSessionId();
+            const existing = existingId ? await sessionStore.loadSession(existingId) : null;
+            if (existing) {
+                agent.hydratePersistedSession(existing);
+            }
+            else {
+                const sessionName = prompt.replace(/\s+/gu, ' ').trim().slice(0, 80) || 'Headless session';
+                await sessionStore.createSession(sessionName, modelToUse);
+            }
+            const sessionId = sessionStore.getCurrentSessionId();
+            if (sessionId) {
+                const current = existing ?? (await sessionStore.loadSession(sessionId));
+                const { RunStore: RunStoreClass } = await import('./observability/run-store.js');
+                runStore = RunStoreClass.getInstance();
+                const { auditLogger } = await import('./security/audit-logger.js');
+                const auditDir = process.env.CODEBUDDY_AUDIT_DIR || nodePath.join(nodeOs.homedir(), '.codebuddy');
+                auditLogger.init({ logDir: auditDir, sessionId });
+                runId = runStore.startRun('headless prompt', {
+                    channel: 'terminal',
+                    sessionId,
+                    ...(current?.workingDirectory ? { cwd: current.workingDirectory } : {}),
+                    tags: ['headless', modelToUse || 'unknown'],
+                });
+                agent.setRunId(runId);
+            }
+        }
         await agent.systemPromptReady;
         // When MCP is opted in for this headless run, wait for the servers to finish
         // connecting so their tools (e.g. the Code Explorer / code-explorer bridge) are
@@ -882,7 +971,6 @@ async function processPromptHeadless(prompt, apiKey, baseURL, model, maxToolRoun
         const confirmationService = ConfirmationService.getInstance();
         confirmationService.setSessionFlag("allOperations", true);
         // Initialize interaction logger for headless session tracking
-        let interactionLogger = null;
         try {
             const { getInteractionLogger } = await import('./logging/interaction-logger.js');
             const il = getInteractionLogger();
@@ -897,8 +985,47 @@ async function processPromptHeadless(prompt, apiKey, baseURL, model, maxToolRoun
         catch (e) {
             logger.debug('Failed to initialize headless interaction logger', { error: String(e) });
         }
+        // Slash commands must not be sent to the LLM as a user message.
+        if (prompt.trim().startsWith('/')) {
+            const { dispatchSlashPrompt } = await import('./commands/headless-slash.js');
+            const handler = (await import('./commands/enhanced-command-handler.js')).getEnhancedCommandHandler();
+            handler.setCodeBuddyClient(agent.getClient());
+            const slash = await dispatchSlashPrompt(prompt.trim(), { client: agent.getClient() });
+            if (slash?.handled) {
+                const resultText = slash.output ?? slash.reason ?? '(slash command produced no output)';
+                const format = outputFormat.toLowerCase();
+                if (format === 'text' || format === 'markdown') {
+                    cli.stdout(resultText);
+                }
+                else {
+                    const slashEffectiveModel = modelToUse || process.env.GROK_MODEL || 'unknown';
+                    const slashCostExtended = agent.getSessionCostExtended?.() ?? { total: agent.getSessionCost(), estimated: true, pricing: 'unknown', billing: 'pay-per-use', inputTokens: 0, outputTokens: 0 };
+                    const slashOutputData = {
+                        result: resultText,
+                        cost: {
+                            total: slashCostExtended.total,
+                            estimated: slashCostExtended.estimated,
+                            pricing: slashCostExtended.pricing,
+                            billing: slashCostExtended.billing,
+                        },
+                        model: slashEffectiveModel,
+                        messages: [{ role: 'assistant', content: resultText }],
+                    };
+                    // For slash commands, we don't have effective vs requested model tracking
+                    // since the agent hasn't processed a user message yet
+                    cli.stdout(JSON.stringify(slashOutputData));
+                }
+                return slash.denied ? 1 : 0;
+            }
+            if (slash?.passToAI && slash.prompt) {
+                prompt = slash.prompt;
+            }
+        }
         // Process the user message
-        const chatEntries = await agent.processUserMessage(prompt);
+        const chatEntries = await agent.processUserMessage(prompt, { surface: 'cli' });
+        if (!sessionStore.isEphemeral()) {
+            await agent.saveCurrentSession();
+        }
         // WS3-T1 — session-end flush (handoff + lesson candidates). Awaited with
         // a hard cap so headless runs keep their continuity write without ever
         // hanging the exit; trivial sessions no-op inside the module.
@@ -964,26 +1091,70 @@ async function processPromptHeadless(prompt, apiKey, baseURL, model, maxToolRoun
                     break;
             }
         }
-        // Validate output against JSON Schema if --output-schema was provided
+        // Extract the final assistant response directly from chatEntries. This is
+        // the text used by every headless output mode and by the file flags.
+        const lastAssistantEntry = [...chatEntries]
+            .reverse()
+            .find((entry) => entry.type === 'assistant');
+        const resultText = lastAssistantEntry?.content ?? '';
+        const client = agent.getClient();
+        const effectiveModel = client.getLastEffectiveModel() ?? modelToUse ?? process.env.GROK_MODEL ?? 'unknown';
+        if (isHeadlessFinalResponseEmpty(resultText)) {
+            const providerLabel = process.env.CODEBUDDY_PROVIDER?.trim()
+                || detectProviderFromEnv()?.provider
+                || 'inconnu';
+            process.stderr.write(`${formatEmptyHeadlessResponseError({
+                provider: providerLabel,
+                model: effectiveModel,
+                durationMs: Date.now() - startedAt,
+            })}\n`);
+            runStatus = 'failed';
+            return 1;
+        }
+        // Validate before writing or emitting any successful output. The schema
+        // applies to the JSON value represented by the final assistant text, not
+        // to the internal/OpenAI-compatible message history.
         if (outputSchemaPath) {
-            const { validateOutputSchema } = await import("./utils/output-schema-validator.js");
-            const validation = validateOutputSchema(messages, outputSchemaPath);
+            const validation = validateOutputText(resultText, outputSchemaPath);
             if (!validation.valid) {
                 cli.error('Output schema validation failed:');
                 for (const error of validation.errors) {
                     cli.error(`  - ${error}`);
                 }
-                return 2;
+                return 1;
             }
         }
-        // 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);
+        if (outputLastMessagePath) {
+            await writeFileAtomic(outputLastMessagePath, resultText);
+        }
+        const { getBuiltinToolNames } = await import('./codebuddy/tools.js');
+        const knownToolNames = getBuiltinToolNames();
+        const executedToolNames = chatEntries
+            .filter((entry) => entry.type === 'tool_result' && entry.toolCall)
+            .map((entry) => entry.toolCall?.function.name)
+            .filter((toolName) => Boolean(toolName));
+        const proseToolCall = findUnexecutedProseToolCall(resultText, knownToolNames, executedToolNames);
+        if (proseToolCall) {
+            logger.warn('le modèle a décrit un appel d’outil sans l’exécuter', {
+                toolName: proseToolCall.toolName,
+                line: proseToolCall.line,
+            });
+        }
+        const exitCode = resolveHeadlessTurnExitCode(resultText, knownToolNames, executedToolNames);
+        runStatus = exitCode === 0 ? 'completed' : 'failed';
         // Gather cost and model info from the agent
-        const sessionCost = agent.getSessionCost();
-        const usedModel = modelToUse || process.env.GROK_MODEL || 'unknown';
+        const sessionCostExtended = agent.getSessionCostExtended?.() ?? { total: agent.getSessionCost(), estimated: true, pricing: 'unknown', billing: 'pay-per-use', inputTokens: 0, outputTokens: 0 };
+        const sessionCost = sessionCostExtended.total;
+        const requestedModel = client.getLastRequestedModel();
+        // MODELLABEL1: Warn on stderr when requested model differs from effective model in headless mode
+        if (requestedModel && requestedModel !== effectiveModel) {
+            const fallbackWarning = `⚠️  Modèle "${requestedModel}" non disponible, repli sur "${effectiveModel}"`;
+            // Only warn once per process in headless mode
+            if (!process.env.CODEBUDDY_MODEL_FALLBACK_WARNED) {
+                process.env.CODEBUDDY_MODEL_FALLBACK_WARNED = 'true';
+                process.stderr.write(fallbackWarning + '\n');
+            }
+        }
         // Output in the requested format
         const format = outputFormat.toLowerCase();
         if (format === 'text' || format === 'markdown') {
@@ -999,23 +1170,51 @@ async function processPromptHeadless(prompt, apiKey, baseURL, model, maxToolRoun
                 process.stdout.write(JSON.stringify(message) + '\n');
             }
             // Emit a final summary event
-            process.stdout.write(JSON.stringify({
+            const summaryData = {
                 type: 'summary',
                 result: resultText,
-                cost: { total: sessionCost },
-                model: usedModel,
-            }) + '\n');
+                cost: {
+                    total: sessionCost,
+                    estimated: sessionCostExtended.estimated,
+                    pricing: sessionCostExtended.pricing,
+                    billing: sessionCostExtended.billing,
+                },
+                model: effectiveModel,
+            };
+            if (requestedModel && requestedModel !== effectiveModel) {
+                summaryData.requestedModel = requestedModel;
+            }
+            process.stdout.write(JSON.stringify(summaryData) + '\n');
         }
         else {
             // Default: json — structured output goes to stdout (pipeable).
-            cli.stdout(JSON.stringify({
+            const { autoWidget } = await import('./widgets/auto-widget.js');
+            const widgetPayloads = chatEntries
+                .filter((entry) => entry.type === 'tool_result')
+                .map((entry) => entry.toolResult ?? { output: entry.content });
+            const widget = await autoWidget(resultText, widgetPayloads);
+            const { detectWidgetable } = await import('./widgets/widget-matcher.js');
+            // `data` is a public structured-output field even when automatic HTML
+            // rendering is disabled. The matcher is pure and does not open the
+            // registry; typed payloads also bypass the table length gate.
+            const candidate = widget.candidate ?? detectWidgetable(resultText, widgetPayloads);
+            const outputData = {
                 result: resultText,
                 cost: {
                     total: sessionCost,
+                    estimated: sessionCostExtended.estimated,
+                    pricing: sessionCostExtended.pricing,
+                    billing: sessionCostExtended.billing,
                 },
-                model: usedModel,
+                model: effectiveModel,
                 messages,
-            }));
+                ...(candidate ? { data: candidate.data } : {}),
+                ...(widget.widgetHtml ? { widgetHtml: widget.widgetHtml } : {}),
+            };
+            if (requestedModel && requestedModel !== effectiveModel) {
+                outputData.requestedModel = requestedModel;
+            }
+            cli.stdout(JSON.stringify(outputData));
         }
         return exitCode;
     }
@@ -1038,6 +1237,49 @@ async function processPromptHeadless(prompt, apiKey, baseURL, model, maxToolRoun
         return 1;
     }
     finally {
+        if (runStore && runId) {
+            try {
+                if (agent) {
+                    const ext = agent.getSessionCostExtended?.();
+                    if (ext) {
+                        runStore.updateMetrics(runId, {
+                            promptTokens: ext.inputTokens,
+                            completionTokens: ext.outputTokens,
+                            totalTokens: ext.inputTokens + ext.outputTokens,
+                            totalCost: ext.total,
+                        });
+                    }
+                }
+                runStore.endRun(runId, runStatus);
+                runStore.dispose();
+            }
+            catch (e) {
+                logger.debug('Headless run cleanup skipped', { error: String(e) });
+            }
+        }
+        if (interactionLogger) {
+            try {
+                interactionLogger.endSession();
+            }
+            catch (e) {
+                logger.debug('Failed to end headless interaction logger session', { error: String(e) });
+            }
+        }
+        if (agent) {
+            try {
+                agent.dispose({ skipSessionLearning: true });
+            }
+            catch (e) {
+                logger.debug('Headless agent cleanup skipped', { error: String(e) });
+            }
+        }
+        try {
+            const { resetMCPClient } = await import('./mcp/mcp-client.js');
+            await resetMCPClient();
+        }
+        catch (e) {
+            logger.debug('Headless MCP cleanup skipped', { error: String(e) });
+        }
         if (previousDisableMCP === undefined) {
             delete process.env.CODEBUDDY_DISABLE_MCP;
         }
@@ -1054,6 +1296,11 @@ async function processPromptHeadless(prompt, apiKey, baseURL, model, maxToolRoun
 }
 program
     .name("buddy")
+    // Git-style option scoping: ROOT options must come before the subcommand.
+    // Without this, root flags are consumed from anywhere in argv and shadow
+    // same-named subcommand options — e.g. `buddy lessons add -c RULE
+    // --context ci` silently lost both to the root `-c, --context <patterns>`.
+    .enablePositionalOptions()
     .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")
@@ -1064,9 +1311,10 @@ program
     .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("--max-tool-rounds <rounds>", "maximum number of tool execution rounds (default: 50) (400 in YOLO mode)")
     .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")
+    .option("--output-format <format>", "output format for headless mode: json, stream-json, text, markdown")
+    .option("-o, --output-last-message <file>", "write the agent's final text response directly and atomically to a file")
     .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)")
@@ -1080,7 +1328,7 @@ program
     .option("--no-emoji", "disable emoji in output")
     .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("--resume [sessionId]", "resume a specific session by ID (supports partial matching); without an ID, pick a recent session")
     .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("--auto-approve", "automatically approve all tool executions (like mistral-vibe)")
@@ -1092,13 +1340,13 @@ 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("--permission-mode <mode>", "permission mode: default, plan, acceptEdits, dontAsk, bypassPermissions", parseCliPermissionMode)
     .option("--dangerously-skip-permissions", "bypass all permission checks (use in trusted containers without network access)")
     .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")
+    .option("--output-schema <file>", "path to a JSON Schema file to validate the final response shape against")
     .option("--add-dir <paths...>", "grant additional writable directories (repeatable)")
     .option("--no-alt-screen", "disable alternate screen buffer for Ink UI")
     .option("--ephemeral", "skip session persistence (do not save session to disk)")
@@ -1107,17 +1355,30 @@ program
     .option("--append-system-prompt <text>", "append text to the default system prompt")
     .option("--append-system-prompt-file <path>", "append file contents to the default system prompt")
     .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("--profile <name>", "apply a built-in or configured profile (core, all, or [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)")
+    .option("--channel <name>", "Start with a messaging channel (telegram, discord, slack, …)")
     .action(async (message, options) => {
+    const unknownCommand = getNonInteractiveUnknownCommand({
+        positionalArgs: Array.isArray(message) ? message : undefined,
+        hasExplicitPrompt: Boolean(options.prompt || options.print),
+        stdinIsTTY: process.stdin.isTTY,
+        stdoutIsTTY: process.stdout.isTTY,
+    });
+    if (unknownCommand) {
+        process.stderr.write(`Commande inconnue « ${unknownCommand} ». Voir buddy --help\n`);
+        process.exitCode = 1;
+        return;
+    }
     // Apply --quiet / --verbose flags
     if (options.quiet) {
         process.env.LOG_LEVEL = 'error';
+        process.env.CODEBUDDY_QUIET = 'true';
         logger.setLevel('error');
     }
     if (options.verbose) {
@@ -1125,6 +1386,11 @@ program
         process.env.DEBUG = 'true';
         logger.setLevel('debug');
     }
+    if (options.channel) {
+        const { handleChannels } = await import('./commands/handlers/channel-handlers.js');
+        await handleChannels('start', { type: String(options.channel) });
+        return;
+    }
     // Apply --speak / --tts-provider flags
     if (options.speak || options.ttsProvider) {
         const { getTTSManager } = await import('./input/text-to-speech.js');
@@ -1143,18 +1409,6 @@ program
             }
         }
     }
-    // Apply named configuration profile (--profile <name>) before anything else
-    if (options.profile) {
-        try {
-            const { getConfigManager } = await import('./config/toml-config.js');
-            getConfigManager().load();
-            getConfigManager().applyProfile(options.profile);
-        }
-        catch (err) {
-            startupLogger.error(`Profile error: ${err instanceof Error ? err.message : err}`);
-            process.exit(1);
-        }
-    }
     // Handle --setup flag (interactive setup wizard)
     if (options.setup) {
         const { runSetup } = await import("./utils/interactive-setup.js");
@@ -1265,6 +1519,14 @@ program
         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 === true) {
+        // P6: `--resume` without an ID opens the recent-session picker.
+        const { pickRecentSession } = await import("./cli/session-commands.js");
+        const picked = await pickRecentSession(20);
+        if (!picked)
+            process.exit(process.exitCode ?? 1);
+        options.resume = picked;
+    }
     if (options.resume) {
         const { getSessionStore } = await import("./persistence/session-store.js");
         const sessionStore = getSessionStore();
@@ -1280,7 +1542,9 @@ program
         }
         await sessionStore.resumeSession(session.id);
         cli.info(`📂 Resuming session: ${session.name} (${session.id.slice(0, 8)})`);
-        cli.info(`   ${session.messages.length} messages, last accessed: ${session.lastAccessedAt.toLocaleString()}\n`);
+        cli.info(`   ${session.messages.length} messages, last accessed: ${session.lastAccessedAt.toLocaleString()}`);
+        const { buildSessionRecap, formatSessionRecap } = await import("./cli/session-picker.js");
+        cli.info(`${formatSessionRecap(buildSessionRecap(session)).join("\n")}\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.
@@ -1290,7 +1554,8 @@ program
             process.chdir(options.directory);
         }
         catch (error) {
-            logger.error(`Error changing directory to ${options.directory}:`, error);
+            const detail = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`error: cannot change directory to ${options.directory}: ${detail}\n`);
             process.exit(1);
         }
     }
@@ -1314,54 +1579,68 @@ program
     }
     try {
         // Get API key from options, environment, or user settings
+        // The OAuth-aware variant, NOT the sync one: naming a model on the command
+        // line must not throw away a subscription login. The sync resolver is blind
+        // to `buddy login xai`, so `--model grok-4.3` used to fall back to an
+        // ambient XAI_API_KEY — dead, in the case measured on 2026-09-02.
         const explicitProvider = options.model && !options.apiKey && !options.baseUrl
-            ? (await import('./commands/llm-provider-resolution.js')).resolveCommandProvider({
-                explicitModel: options.model,
-            })
+            ? await (await import('./commands/llm-provider-resolution.js')).resolveCommandProviderWithOAuth({ explicitModel: options.model })
             : null;
         let apiKey = options.apiKey || explicitProvider?.apiKey || await loadApiKey();
         let baseURL = options.baseUrl || explicitProvider?.baseURL || await loadBaseURL();
         let model = options.model || explicitProvider?.model || await loadModel(); // let: can be overridden by --agent
-        const maxToolRounds = parseInt(options.maxToolRounds) || 400;
+        const maxToolRounds = options.maxToolRounds
+            ? parseInt(options.maxToolRounds, 10) || undefined
+            : undefined;
         if (!apiKey) {
-            // In an interactive terminal, offer the guided setup wizard right here
-            // (like Hermes) instead of dead-ending on an error — then continue the
-            // session with the credentials it captured.
+            // The shortest first-run path is a direct ChatGPT OAuth login. Keep the
+            // full wizard available, but do not make a new user navigate provider,
+            // model, and TTS choices before seeing the coding agent work.
             const interactive = Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY) &&
                 !options.prompt && !options.print &&
                 process.env.CI !== 'true' && process.env.GITHUB_ACTIONS !== 'true';
-            let recovered = false;
-            if (interactive) {
-                const readline = await import('readline');
-                const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-                const answer = await new Promise((resolve) => rl.question('\n❔ No AI provider configured. Run guided setup now? [Y/n] ', resolve));
-                rl.close();
-                const yes = answer.trim() === '' || /^y(es)?$/i.test(answer.trim());
-                if (yes) {
+            const recoveredProvider = await recoverFirstRunWithChatGpt({
+                interactive,
+                ask: async (question) => {
+                    const readline = await import('readline');
+                    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
                     try {
-                        const { runOnboarding } = await import('./wizard/onboarding.js');
-                        const result = await runOnboarding();
-                        // Bust the cached provider detection so the just-saved creds resolve.
-                        cachedProvider = undefined;
-                        apiKey = options.apiKey || await loadApiKey();
-                        baseURL = options.baseUrl || await loadBaseURL();
-                        model = options.model || result.model || await loadModel();
-                        recovered = Boolean(apiKey);
+                        return await new Promise((resolve) => rl.question(question, resolve));
                     }
-                    catch (err) {
-                        logger.error('Guided setup did not complete', err instanceof Error ? err : { error: String(err) });
+                    finally {
+                        rl.close();
                     }
-                }
+                },
+                login: async () => {
+                    const { loginInteractive } = await import('./providers/codex-oauth.js');
+                    cli.stdout('\n🔐 ChatGPT login — opening your browser…');
+                    const auth = await loginInteractive();
+                    cli.stdout(`✅ Authenticated${auth.email ? ` as ${auth.email}` : ''}. Starting Code Buddy…`);
+                },
+                reloadProvider: async () => {
+                    // Bust provider detection so the OAuth file written moments ago is
+                    // immediately visible to this same process.
+                    cachedProvider = undefined;
+                    const nextApiKey = options.apiKey || await loadApiKey();
+                    if (!nextApiKey)
+                        return null;
+                    return {
+                        apiKey: nextApiKey,
+                        baseURL: options.baseUrl || await loadBaseURL(),
+                        model: options.model || await loadModel(),
+                    };
+                },
+                onLoginError: (err) => {
+                    logger.error('ChatGPT login did not complete', err instanceof Error ? err : { error: String(err) });
+                },
+            });
+            if (recoveredProvider) {
+                apiKey = recoveredProvider.apiKey;
+                baseURL = recoveredProvider.baseURL;
+                model = recoveredProvider.model;
             }
-            if (!recovered) {
-                logger.error([
-                    "❌ No AI provider configured. Pick one to get started:",
-                    "   • Guided setup (recommended) — interactive wizard:     buddy onboard",
-                    "   • Free, no API key — sign in with your ChatGPT plan:    buddy login",
-                    "   • Local & free — run a model with Ollama, then:         export OLLAMA_HOST=http://localhost:11434",
-                    "   • API key — set GROK_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY / GOOGLE_API_KEY (or pass --api-key)",
-                    "   Run  buddy doctor  to check your setup.",
-                ].join("\n"));
+            if (!recoveredProvider) {
+                logger.error(NO_PROVIDER_GUIDANCE);
                 process.exit(1);
             }
         }
@@ -1381,21 +1660,6 @@ program
             confirmationService.setSessionFlag("allOperations", true);
             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 (natively)
         if (options.dangerouslySkipPermissions) {
             const { ConfirmationService } = await import("./utils/confirmation-service.js");
@@ -1505,7 +1769,7 @@ program
         ].filter(Boolean).join('\n\n');
         // Headless mode: process prompt and exit (if prompt, message, or piped input provided)
         if (combinedPrompt && (promptArg || pipedInput)) {
-            const headlessExitCode = await processPromptHeadless(combinedPrompt, apiKey, baseURL, model, maxToolRounds, options.selfHeal !== false, resolveHeadlessOutputFormat(options), options.outputSchema, options.agent);
+            const headlessExitCode = await processPromptHeadless(combinedPrompt, apiKey, baseURL, model, maxToolRounds, options.selfHeal !== false, resolveHeadlessOutputFormat(options), options.outputLastMessage, options.outputSchema, options.agent);
             await finalizeHeadlessRun(headlessExitCode);
             return;
         }
@@ -1646,6 +1910,7 @@ program
         await ensureUserSettingsDirectory();
         recordStartupPhase('user-settings-done');
         // ── Crash recovery: detect unclean shutdown and offer session resume ──
+        let crashResumed = false;
         if (!options.resume && !options.continue) {
             try {
                 const { checkCrashRecovery, clearRecoveryFiles } = await import('./errors/crash-recovery.js');
@@ -1667,6 +1932,7 @@ program
                             const session = await sessionStore.getSessionByPartialId(recovery.sessionId);
                             if (session) {
                                 await sessionStore.resumeSession(session.id);
+                                crashResumed = true;
                                 cli.info(`   Resuming session: ${session.name} (${session.messages.length} messages)`);
                             }
                             else {
@@ -1724,7 +1990,24 @@ program
         // 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);
+        // Memory fact reconciliation (remember tool and /remember) must use the
+        // provider this session runs on, never a provider auto-detected from env.
+        const { setFactsMemorySessionClient } = await import('./memory/facts-memory.js');
+        setFactsMemorySessionClient(agent.getClient());
+        // A resumed session (--resume, --continue, crash recovery) must reach both the model
+        // history and the chat view; resumeSession() alone only selects the store's current session.
+        let initialHistory;
+        if (options.resume || options.continue || crashResumed) {
+            const { getSessionStore } = await import('./persistence/session-store.js');
+            const resumedStore = getSessionStore();
+            const resumedId = resumedStore.getCurrentSessionId();
+            const resumed = resumedId ? await resumedStore.loadSession(resumedId) : null;
+            if (resumed) {
+                agent.hydratePersistedSession(resumed);
+                initialHistory = agent.getChatHistory();
+            }
+        }
+        render(React.createElement(ChatInterface, { agent, initialMessage, initialHistory }), inkOptions);
         // Initialize plugin system in background (non-blocking)
         setImmediate(async () => {
             try {
@@ -1790,6 +2073,9 @@ program
             try {
                 const { RunStore } = await import('./observability/run-store.js');
                 const runStore = RunStore.getInstance();
+                const { auditLogger } = await import('./security/audit-logger.js');
+                const auditDir = process.env.CODEBUDDY_AUDIT_DIR || nodePath.join(nodeOs.homedir(), '.codebuddy');
+                auditLogger.init({ logDir: auditDir });
                 const runId = runStore.startRun('interactive session', {
                     channel: 'terminal',
                     tags: ['interactive', model || 'unknown'],
@@ -1797,6 +2083,17 @@ program
                 agent.setRunId(runId);
                 const cleanupRun = () => {
                     try {
+                        if (agent) {
+                            const ext = agent.getSessionCostExtended?.();
+                            if (ext) {
+                                runStore.updateMetrics(runId, {
+                                    promptTokens: ext.inputTokens,
+                                    completionTokens: ext.outputTokens,
+                                    totalTokens: ext.inputTokens + ext.outputTokens,
+                                    totalCost: ext.total,
+                                });
+                            }
+                        }
                         runStore.endRun(runId, 'completed');
                     }
                     catch (_err) { /* ignore */ }
@@ -1855,7 +2152,7 @@ gitCommand
     .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("--max-tool-rounds <rounds>", "maximum number of tool execution rounds (default: 400)", "400")
+    .option("--max-tool-rounds <rounds>", "maximum number of tool execution rounds (default: 50)")
     .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.
@@ -1865,7 +2162,8 @@ gitCommand
             process.chdir(options.directory);
         }
         catch (error) {
-            logger.error(`Error changing directory to ${options.directory}:`, error);
+            const detail = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`error: cannot change directory to ${options.directory}: ${detail}\n`);
             process.exit(1);
         }
     }
@@ -1874,16 +2172,11 @@ gitCommand
         const apiKey = options.apiKey || await loadApiKey();
         const baseURL = options.baseUrl || await loadBaseURL();
         const model = options.model || await loadModel();
-        const maxToolRounds = parseInt(options.maxToolRounds) || 400;
+        const maxToolRounds = options.maxToolRounds
+            ? parseInt(options.maxToolRounds, 10) || undefined
+            : undefined;
         if (!apiKey) {
-            logger.error([
-                "❌ No AI provider configured. Pick one to get started:",
-                "   • Guided setup (recommended) — interactive wizard:     buddy onboard",
-                "   • Free, no API key — sign in with your ChatGPT plan:    buddy login",
-                "   • Local & free — run a model with Ollama, then:         export OLLAMA_HOST=http://localhost:11434",
-                "   • API key — set GROK_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY / GOOGLE_API_KEY (or pass --api-key)",
-                "   Run  buddy doctor  to check your setup.",
-            ].join("\n"));
+            logger.error(NO_PROVIDER_GUIDANCE);
             process.exit(1);
         }
         // Save API key and base URL to user settings if provided via command line
@@ -1901,20 +2194,6 @@ gitCommand
 // Lazy command registration: create lightweight Commander stubs that defer
 // importing heavy modules until the command is actually invoked.
 // This avoids loading MCP, provider, pipeline, etc. at startup.
-/**
- * Remove commands from a Commander program by name(s).
- * Uses splice to mutate the readonly commands array in-place.
- */
-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--) {
-        const cmd = cmds[i];
-        if (cmd !== undefined && nameSet.has(cmd.name())) {
-            cmds.splice(i, 1);
-        }
-    }
-}
 /**
  * Register a lazy subcommand tree. When any subcommand action fires, the
  * real module is imported and re-parsed to handle the invocation.
@@ -1944,19 +2223,52 @@ function addLazyCommand(parent, name, description, loader, prevalidateArgv) {
         const realCommand = await loader();
         // Replace the stub with the real command and re-parse
         removeCommands(parent, name);
+        attachUnknownOptionHint(realCommand, parent);
         parent.addCommand(realCommand);
         // Re-parse argv so the real command handles subcommands & options
         await parent.parseAsync(process.argv);
     });
 }
+addLazyCommand(program, 'try', 'Run an isolated 60-second coding-agent demo (ChatGPT OAuth or local Ollama)', async () => {
+    const { createTryCommand } = await import('./commands/try.js');
+    return createTryCommand();
+});
+addLazyCommand(program, 'import', 'Import project rules and MCP servers from Cursor, Cline, Copilot, or Claude Code', async () => {
+    const { createImportCommand } = await import('./commands/import.js');
+    return createImportCommand();
+});
+addLazyCommand(program, 'explain', 'Explain an unfamiliar repository in one Markdown or self-contained HTML artifact', async () => {
+    const { createExplainCommand } = await import('./commands/explain.js');
+    return createExplainCommand();
+});
+addLazyCommand(program, 'changelog', 'Generate grouped release notes from Conventional Commits', async () => {
+    const { createChangelogCommand } = await import('./commands/changelog.js');
+    return createChangelogCommand();
+});
+addLazyCommand(program, 'ws', 'Manage and search the opt-in multi-repository workspace', async () => {
+    const { createWsCommand } = await import('./commands/ws.js');
+    return createWsCommand();
+});
 addLazyCommand(program, 'provider', 'Manage AI providers (Claude, ChatGPT, Grok, Gemini)', async () => {
     const { createProviderCommand } = await import('./commands/provider.js');
     return createProviderCommand();
 });
-addLazyCommand(program, 'mcp', 'Manage MCP (Model Context Protocol) servers', async () => {
+addLazyCommand(program, 'mcp', 'Manage MCP servers or expose Code Buddy with `buddy mcp serve`', async () => {
     const { createMCPCommand } = await import('./commands/mcp.js');
     return createMCPCommand();
 });
+addLazyCommand(program, 'campaign', 'Native editorial, book-promotion and PubCommander campaign workspace', async () => {
+    const { createCampaignCommand } = await import('./commands/campaign.js');
+    return createCampaignCommand();
+});
+addLazyCommand(program, 'influencer', 'Influencer & book-trailer media pipeline (scripts/influencer)', async () => {
+    const { createInfluencerCommand } = await import('./commands/influencer.js');
+    return createInfluencerCommand();
+});
+addLazyCommand(program, 'maison', 'Household rhythm, holidays, quiet modes and private meal safety', async () => {
+    const { createMaisonCommand } = await import('./commands/maison.js');
+    return createMaisonCommand();
+});
 addLazyCommand(program, 'pipeline', 'Manage and run pipeline workflows', async () => {
     const { createPipelineCommand } = await import('./commands/pipeline.js');
     return createPipelineCommand();
@@ -1965,8 +2277,9 @@ addLazyCommand(program, 'pipeline', 'Manage and run pipeline workflows', async (
 program
     .command("channels")
     .description("Manage channel connections (Telegram, Discord, Slack, etc.)")
-    .argument("[action]", "start|stop|status|list", "list")
+    .argument("[action]", "start|stop|status|list|pairing", "list")
     .option("--type <type>", "Channel type (telegram|discord|slack|whatsapp|signal|google-chat|teams|matrix|webchat)")
+    .option("--instance <name>", "Named channel instance, or default for an unnamed entry")
     .option("--config <path>", "Channel config file path")
     .option("--json", "Output JSON for status")
     .action(async (action, options) => {
@@ -1979,12 +2292,21 @@ program
     .description("Start the Code Buddy HTTP/WebSocket API server")
     .option("--port <port>", "server port", "3000")
     .option("--host <host>", "server host", "0.0.0.0")
-    .option("--no-auth", "disable JWT authentication")
+    .option("--no-auth", "disable JWT authentication (loopback development only)")
     .action(async (options) => {
+    let port;
+    try {
+        port = parseListenPort(String(options.port));
+    }
+    catch (error) {
+        process.stderr.write(`error: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(1);
+        return;
+    }
     const { startServer } = await import("./server/index.js");
     try {
         await startServer({
-            port: parseInt(options.port),
+            port,
             host: options.host,
             authEnabled: options.auth !== false,
         });
@@ -1994,6 +2316,258 @@ program
         process.exit(1);
     }
 });
+program
+    .command("voice")
+    .description("Push-to-talk voice commands — speak an instruction, the agent acts, the reply is spoken")
+    .option("--mode <mode>", "voice ACT posture: default (guarded workspace, default) | plan (read-only) | acceptEdits | dontAsk | bypassPermissions", "default")
+    .action(async (options) => {
+    const allowed = ["default", "plan", "acceptEdits", "dontAsk", "bypassPermissions"];
+    if (!allowed.includes(options.mode)) {
+        cli.stdout(`error: unknown --mode '${options.mode}'. Values: ${allowed.join(", ")}`);
+        process.exit(1);
+    }
+    const mode = options.mode;
+    if (mode === "dontAsk" || mode === "bypassPermissions") {
+        cli.stdout(`⚠️  Posture '${mode}': voice can EDIT FILES / RUN COMMANDS from a possibly-misheard transcript. Ctrl-C to abort.`);
+    }
+    try {
+        const { runVoiceCommand } = await import("./cli/voice-command.js");
+        await runVoiceCommand({
+            permissionMode: mode,
+        });
+    }
+    catch (error) {
+        logger.error("Voice command session failed", error instanceof Error ? error : new Error(String(error)));
+        process.exit(1);
+    }
+});
+program
+    .command("remind [action] [args...]")
+    .description("Reminders — the robot reminds you (meds…) and you flag them done (add|list|agenda|done|rm)")
+    .option("--at <time>", "time of day HH:MM (for `add`)")
+    .option("--date <date>", "one-shot date YYYY-MM-DD — fires once then retires (not recurring)")
+    .option("--days <csv>", "days of week 0=Sun..6=Sat, e.g. 1,3,5 (default: every day)")
+    .option("--ahead <n>", "agenda: how many days ahead to list (default 7)")
+    .option("--daily", "every day (default when --days omitted)")
+    .option("--message <text>", "custom spoken/sent text")
+    .action(async (action, args = [], options) => {
+    const r = await import("./companion/reminders.js");
+    const act = (action || "list").toLowerCase();
+    try {
+        if (act === "add") {
+            const label = args.join(" ").trim();
+            if (!label || !options.at) {
+                cli.stdout('Usage: buddy remind add "<label>" --at HH:MM [--date YYYY-MM-DD] [--days 1,3,5]');
+                process.exitCode = 1;
+                return;
+            }
+            const days = options.days
+                ? String(options.days)
+                    .split(",")
+                    .map((s) => parseInt(s.trim(), 10))
+                    .filter((n) => Number.isInteger(n) && n >= 0 && n <= 6)
+                : undefined;
+            const rem = await r.addReminder({
+                label,
+                time: options.at,
+                ...(options.date ? { date: String(options.date) } : days && days.length ? { days } : {}),
+                ...(options.message ? { message: options.message } : {}),
+            });
+            cli.stdout(`✅ Added ${rem.id}: "${rem.label}" at ${rem.time} ${rem.date ? `on ${rem.date} (one-shot)` : rem.days?.length ? `on ${rem.days.join(",")}` : "daily"}`);
+        }
+        else if (act === "list") {
+            const list = await r.listReminders();
+            if (!list.length) {
+                cli.stdout('No reminders yet. Add one: buddy remind add "médicaments" --at 09:00');
+                return;
+            }
+            for (const x of list) {
+                const cadence = x.date ? `${x.date} (once)` : x.days?.length ? `[${x.days.join(",")}]` : "daily";
+                cli.stdout(`${x.enabled ? "•" : "◦"} ${x.id}  ${x.time}  ${cadence}  ${x.label}` +
+                    `${x.lastDoneAt ? `  (last done ${x.lastDoneAt.slice(0, 16).replace("T", " ")})` : ""}`);
+            }
+        }
+        else if (act === "agenda") {
+            const ahead = Number(options.ahead ?? 7);
+            const agenda = r.agendaFor(await r.listReminders(), Date.now(), Number.isFinite(ahead) ? ahead : 7);
+            if (!agenda.length) {
+                cli.stdout("Rien de prévu dans cette période.");
+                return;
+            }
+            for (const e of agenda) {
+                const when = new Date(e.at).toLocaleDateString("fr-FR", { weekday: "short", day: "2-digit", month: "2-digit" });
+                cli.stdout(`${when}  ${e.time}  ${e.label}  ${e.recurring ? "[récurrent]" : "[ponctuel]"}`);
+            }
+        }
+        else if (act === "done") {
+            const id = args[0];
+            if (!id) {
+                cli.stdout("Usage: buddy remind done <id>");
+                process.exitCode = 1;
+                return;
+            }
+            const done = await r.markDone(id, "cli");
+            cli.stdout(done ? `✅ Marked done: ${done.label}` : `Reminder not found: ${id}`);
+            if (!done)
+                process.exitCode = 1;
+        }
+        else if (act === "rm" || act === "remove") {
+            const id = args[0];
+            if (!id) {
+                cli.stdout("Usage: buddy remind rm <id>");
+                process.exitCode = 1;
+                return;
+            }
+            const removed = await r.removeReminder(id);
+            cli.stdout(removed ? `🗑️  Removed ${id}` : `Reminder not found: ${id}`);
+            if (!removed)
+                process.exitCode = 1;
+        }
+        else {
+            cli.stdout("Usage: buddy remind add|list|agenda|done|rm");
+            process.exitCode = 1;
+        }
+    }
+    catch (e) {
+        cli.stdout(`❌ ${e instanceof Error ? e.message : String(e)}`);
+        process.exitCode = 1;
+    }
+});
+program
+    .command("rules [action] [args...]")
+    .description("Administer sensory rules (event→action) — list|templates|enable|disable|rm|runs|validate|add")
+    .option("--json <rule>", "rule JSON (for `add`)")
+    .option("--from-file <path>", "read rule JSON from a file (for `add`)")
+    .option("--template <name>", "install a bundled rule template (for `add`)")
+    .option("--limit <n>", "max rows (for `runs`)", "20")
+    .action(async (action, args = [], options) => {
+    const r = await import("./sensory/sensory-rules-engine.js");
+    const act = (action || "list").toLowerCase();
+    try {
+        if (act === "list") {
+            const rules = await r.listSensoryRules();
+            if (!rules.length) {
+                cli.stdout("No sensory rules. Edit ~/.codebuddy/sensory-rules.json or: buddy rules add --json '…'");
+                return;
+            }
+            for (const x of rules) {
+                cli.stdout(`${x.enabled === false ? "◦" : "•"} ${x.id}  on:${x.match.kind}  → ${x.action.type}` +
+                    `${x.cooldownMs ? `  cd:${Math.round(x.cooldownMs / 1000)}s` : ""}${x.name ? `  (${x.name})` : ""}`);
+            }
+        }
+        else if (act === "enable" || act === "disable") {
+            const id = args[0];
+            if (!id) {
+                cli.stdout(`Usage: buddy rules ${act} <id>`);
+                process.exitCode = 1;
+                return;
+            }
+            const ok = await r.toggleSensoryRule(id, act === "enable");
+            cli.stdout(ok
+                ? `${act === "enable" ? "✅ enabled" : "⏸️  disabled"} ${id} (live within ~2s on a running server — no restart)`
+                : `Rule not found: ${id}`);
+            if (!ok)
+                process.exitCode = 1;
+        }
+        else if (act === "rm" || act === "remove") {
+            const id = args[0];
+            if (!id) {
+                cli.stdout("Usage: buddy rules rm <id>");
+                process.exitCode = 1;
+                return;
+            }
+            const removed = await r.removeSensoryRule(id);
+            cli.stdout(removed ? `🗑️  Removed ${id}` : `Rule not found: ${id}`);
+            if (!removed)
+                process.exitCode = 1;
+        }
+        else if (act === "runs") {
+            const runs = await r.readRuleRuns(parseInt(options.limit, 10) || 20);
+            if (!runs.length) {
+                cli.stdout("No rule fires logged yet.");
+                return;
+            }
+            for (const run of runs) {
+                cli.stdout(`${new Date(run.ts).toISOString().slice(0, 19).replace("T", " ")}  ${run.ok ? "ok  " : "FAIL"}  ` +
+                    `${run.rule}  ${run.action}${run.detail ? `  ${String(run.detail).slice(0, 60)}` : ""}`);
+            }
+        }
+        else if (act === "validate") {
+            const rules = await r.listSensoryRules();
+            let bad = 0;
+            for (const x of rules) {
+                const v = r.validateRule(x);
+                if (!v.ok) {
+                    bad++;
+                    cli.stdout(`❌ ${x.id}: ${v.errors.join("; ")}`);
+                }
+            }
+            cli.stdout(bad ? `${bad} invalid rule(s).` : `✅ ${rules.length} rule(s) valid.`);
+        }
+        else if (act === "templates") {
+            const { listRuleTemplates } = await import("./sensory/rule-templates.js");
+            const templates = listRuleTemplates();
+            cli.stdout("Available rule templates (install with: buddy rules add --template <name>):");
+            for (const t of templates) {
+                cli.stdout(`• ${t.name}  — ${t.description}`);
+            }
+        }
+        else if (act === "add" && options.template) {
+            const { getRuleTemplate } = await import("./sensory/rule-templates.js");
+            const tpl = getRuleTemplate(String(options.template));
+            if (!tpl) {
+                cli.stdout(`❌ unknown template '${options.template}'. See: buddy rules templates`);
+                process.exitCode = 1;
+                return;
+            }
+            const rule = tpl.build();
+            const validation = r.validateRule(rule);
+            if (!validation.ok) {
+                cli.stdout(`❌ template '${tpl.name}' failed validation:\n  - ${validation.errors.join("\n  - ")}`);
+                process.exitCode = 1;
+                return;
+            }
+            const res = await r.upsertSensoryRule(rule);
+            cli.stdout(res.ok
+                ? `✅ Installed template '${tpl.name}' as rule ${rule.id} (disabled? ${rule.enabled === false ? "yes" : "no"})`
+                : `❌ rejected:\n  - ${res.errors.join("\n  - ")}`);
+            if (!res.ok)
+                process.exitCode = 1;
+        }
+        else if (act === "add") {
+            let raw = options.json;
+            if (!raw && options.fromFile) {
+                raw = await (await import("node:fs/promises")).readFile(options.fromFile, "utf8");
+            }
+            if (!raw) {
+                cli.stdout('Usage: buddy rules add --json \'{"id":"x","match":{"kind":"person_entered"},"action":{"type":"alert","message":"hi"}}\'');
+                process.exitCode = 1;
+                return;
+            }
+            let rule;
+            try {
+                rule = JSON.parse(raw);
+            }
+            catch (e) {
+                cli.stdout(`❌ invalid JSON: ${e instanceof Error ? e.message : String(e)}`);
+                process.exitCode = 1;
+                return;
+            }
+            const res = await r.upsertSensoryRule(rule);
+            cli.stdout(res.ok ? `✅ Saved rule ${rule.id}` : `❌ rejected:\n  - ${res.errors.join("\n  - ")}`);
+            if (!res.ok)
+                process.exitCode = 1;
+        }
+        else {
+            cli.stdout("Usage: buddy rules list|templates|enable|disable|rm|runs|validate|add [--template <name>]");
+            process.exitCode = 1;
+        }
+    }
+    catch (e) {
+        cli.stdout(`❌ ${e instanceof Error ? e.message : String(e)}`);
+        process.exitCode = 1;
+    }
+});
 // Cowork (the Electron desktop GUI) needs Node >= 22; the terminal CLI runs on
 // Node >= 18. Without this guard a Node 18/20 user gets a cryptic Electron/Vite
 // crash mid-launch instead of a clear message — a classic first-run star-killer.
@@ -2171,6 +2745,7 @@ program
     .command("login [provider]")
     .description("Authenticate with a provider (chatgpt | xai — uses your subscription, no API key)")
     .option("--code <code>", "Complete an xAI login with the code shown in the browser")
+    .option("--no-browser", "Fail immediately instead of waiting for a browser callback")
     .action(async (provider, options) => {
     const target = (provider ?? "chatgpt").toLowerCase();
     if (target === "xai" || target === "grok" || target === "xai-oauth") {
@@ -2182,12 +2757,18 @@ program
         cli.stdout("Other providers (Gemini, Anthropic) authenticate via API key env vars.");
         process.exit(1);
     }
-    const { loginInteractive, getCodexAuthFilePath } = await import("./providers/codex-oauth.js");
+    const { canAttemptInteractiveLogin, LOGIN_NEEDS_BROWSER_MESSAGE } = await import("./commands/login-prerequisites.js");
+    if (options.browser === false || !canAttemptInteractiveLogin()) {
+        cli.error(LOGIN_NEEDS_BROWSER_MESSAGE);
+        process.exit(1);
+    }
+    const { getCodexAuthFilePath } = await import("./providers/codex-oauth.js");
+    const { loginChatGptWithBrowser } = await import('./commands/login-chatgpt.js');
     cli.stdout("🔐 ChatGPT login");
-    cli.stdout("Opening your browser to https://auth.openai.com/oauth/authorize ...");
+    cli.stdout("Opening your browser for ChatGPT sign-in ...");
     cli.stdout("Sign in with your ChatGPT account, then return to this terminal.\n");
     try {
-        const auth = await loginInteractive();
+        const auth = await loginChatGptWithBrowser(cli);
         cli.stdout("✅ Authenticated successfully");
         if (auth.email)
             cli.stdout(`   Account:    ${auth.email}`);
@@ -2195,8 +2776,11 @@ program
             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}`);
+        const { CHATGPT_OAUTH_DEFAULT_MODEL, CHATGPT_OAUTH_SAFE_FALLBACK_MODEL, discoverChatGptModels, selectChatGptOAuthModel, } = await import('./providers/chatgpt-models.js');
+        const catalog = await discoverChatGptModels(auth);
+        cli.stdout(`   Model:      ${selectChatGptOAuthModel(CHATGPT_OAUTH_DEFAULT_MODEL, catalog)}`);
+        if (!catalog)
+            cli.stdout(`   Safe fallback: ${CHATGPT_OAUTH_SAFE_FALLBACK_MODEL}`);
         cli.stdout(`\nTokens stored at: ${getCodexAuthFilePath()}`);
         cli.stdout("Run `buddy --print \"hello\"` to test, or just `buddy` for a chat session.");
     }
@@ -2234,28 +2818,67 @@ program
 });
 program
     .command("whoami")
-    .description("Show current authentication status (email, plan, account)")
+    .description("Show current authentication status (email, plan, OAuth model)")
     .action(async () => {
+    const { formatWhoamiStatus } = await import("./commands/whoami-status.js");
     const { hasCodexCredentials, getChatGptAuth } = await import("./providers/codex-oauth.js");
+    let providerHealth = [];
+    try {
+        const { formatProviderHealthLines } = await import("./providers/provider-health.js");
+        providerHealth = formatProviderHealthLines();
+    }
+    catch (error) {
+        logger.debug("Health file optional or unreadable", { error });
+    }
+    let local = null;
+    try {
+        const { getSettingsManager } = await import("./utils/settings-manager.js");
+        const settings = getSettingsManager().readUserSettingsIfPresent();
+        if (settings?.provider) {
+            local = {
+                provider: settings.provider,
+                ...(settings.model || settings.defaultModel
+                    ? { model: settings.model || settings.defaultModel }
+                    : {}),
+                ...(settings.baseURL ? { baseURL: settings.baseURL } : {}),
+            };
+        }
+    }
+    catch (_error) {
+        /* profile unreadable — ChatGPT status still prints */
+    }
     if (!hasCodexCredentials()) {
-        cli.stdout("ChatGPT: not connected (run `buddy login` to authenticate)");
+        for (const line of formatWhoamiStatus({ chatgpt: null, local, providerHealth })) {
+            cli.stdout(line);
+        }
         return;
     }
     try {
         const auth = await getChatGptAuth();
         if (!auth) {
             cli.stdout("ChatGPT: token unreadable. Run `buddy logout` then `buddy login`.");
+            if (local) {
+                for (const line of formatWhoamiStatus({ chatgpt: null, local }).filter((line) => line.startsWith('Local:'))) {
+                    cli.stdout(line);
+                }
+            }
             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`);
+        const { CHATGPT_OAUTH_DEFAULT_MODEL, CHATGPT_OAUTH_SAFE_FALLBACK_MODEL, discoverChatGptModels, selectChatGptOAuthModel, } = await import('./providers/chatgpt-models.js');
+        const catalog = await discoverChatGptModels(auth);
+        for (const line of formatWhoamiStatus({
+            chatgpt: {
+                email: auth.email,
+                plan: auth.plan_type,
+                model: selectChatGptOAuthModel(CHATGPT_OAUTH_DEFAULT_MODEL, catalog),
+                fedramp: auth.is_fedramp,
+                ...(catalog ? {} : { fallback: CHATGPT_OAUTH_SAFE_FALLBACK_MODEL }),
+            },
+            local,
+            providerHealth,
+        })) {
+            cli.stdout(line);
+        }
     }
     catch (err) {
         cli.error(`Error reading credentials: ${err instanceof Error ? err.message : String(err)}`);
@@ -2341,21 +2964,33 @@ program
         cli.stdout("\nNo additional active LLMs available for failover.");
     }
     const { getConfigManager } = await import("./config/toml-config.js");
-    const on = Boolean(getConfigManager().getConfig().llm?.enabled) ||
-        process.env.CODEBUDDY_LLM_FAILOVER === "1";
-    cli.stdout(`Auto-failover: ${on ? "ON" : "OFF  (enable with [llm].enabled = true, or CODEBUDDY_LLM_FAILOVER=1)"}`);
+    const { isDeclaredProviderFallbackEnabled } = await import("./providers/provider-failover-policy.js");
+    const on = isDeclaredProviderFallbackEnabled() ||
+        Boolean(getConfigManager().getConfig().llm?.enabled);
+    cli.stdout(`Auto-failover: ${on ? "ON" : "OFF  (enable with CODEBUDDY_PROVIDER_FALLBACK=true; CODEBUDDY_LLM_FAILOVER is a deprecated alias)"}`);
 });
 // Council — capability-aware multi-LLM router + ensemble (judge + consensus) + learning.
 program
     .command("council [task...]")
-    .description("Ask several capable LLMs the same task, judge + reconcile the answers, and learn which model is best per task type")
+    .description("Ask a capability-routed AI council with conductor roles, judge + reconcile the answers, and learn winners per task type")
     .option("-n, --count <n>", "How many models to consult (default 3)")
     .option("--models <list>", "Restrict to these providers/models (comma list)")
     .option("--judge <model>", "Provider/model to use as the impartial judge")
-    .option("--task-type <tag>", "Override inferred task type (code|reasoning|french|vision|general)")
+    .option("--task-type <tag>", "Override inferred task type (code|reasoning|french|vision|general|literary categories)")
+    .option("--task <tag>", "Task type for `council scoreboard best`")
     .option("--no-consensus", "Skip the consensus/agreement summary")
     .option("--scoreboard", "Print the learned model ranking and exit")
+    .option("--fleet", "Also consult connected fleet peers (other machines' Code Buddy) over the network")
+    .option("--no-conductor", "Disable adaptive council roles and ask every model the exact same prompt")
+    .option("--no-synthesis", "Disable the final collective synthesis pass")
     .action(async (taskParts = [], options) => {
+    if (taskParts[0]?.toLowerCase() === 'scoreboard') {
+        const { runScoreboardCommand } = await import("./commands/council-scoreboard.js");
+        const ok = runScoreboardCommand(taskParts.slice(1), cli.stdout, undefined, { task: options.task });
+        if (!ok)
+            process.exitCode = 1;
+        return;
+    }
     const { runCouncil } = await import("./commands/council.js");
     await runCouncil((taskParts || []).join(" ").trim(), {
         count: options.count ? Number(options.count) : undefined,
@@ -2364,17 +2999,25 @@ program
         taskType: options.taskType,
         consensus: options.consensus,
         scoreboard: options.scoreboard,
+        fleet: options.fleet,
+        conductor: options.conductor,
+        synthesis: options.synthesis,
     }, cli.stdout);
 });
 // MCP Server command - run Code Buddy as an MCP tool provider over stdio
 program
     .command("mcp-server")
-    .description("Start Code Buddy as an MCP server over stdio (for VS Code, Cursor, etc.)")
+    .description("Legacy alias for `buddy mcp serve`")
     .option("--list", "List available MCP tools and exit")
+    .option("--allow-write", "Expose write, shell, and execution tools")
+    .option("--tools <glob>", "Restrict exposed tool names with glob patterns")
     .action(async (options) => {
     if (options.list) {
         const { CodeBuddyMCPServer } = await import("./mcp/mcp-server.js");
-        const tools = CodeBuddyMCPServer.getToolDefinitions();
+        const tools = CodeBuddyMCPServer.getToolDefinitions({
+            ...(options.allowWrite ? { allowWrite: true } : {}),
+            ...(options.tools ? { tools: options.tools } : {}),
+        });
         // Pipeable listing.
         for (const tool of tools) {
             cli.stdout(`${tool.name}: ${tool.description}`);
@@ -2382,9 +3025,11 @@ program
         return;
     }
     try {
-        const { CodeBuddyMCPServer } = await import("./mcp/mcp-server.js");
-        const server = new CodeBuddyMCPServer();
-        await server.start();
+        const { serveMCP } = await import("./commands/mcp.js");
+        await serveMCP({
+            ...(options.allowWrite ? { allowWrite: true } : {}),
+            ...(options.tools ? { tools: options.tools } : {}),
+        });
     }
     catch (error) {
         logger.error("Failed to start MCP server", error instanceof Error ? error : new Error(String(error)));
@@ -2396,25 +3041,6 @@ program
 // and its action handlers already use dynamic imports, but loading the module
 // file itself pulls in transitive dependencies (logger, etc.) at startup.
 // By deferring the import until the command is matched, we avoid that cost.
-/**
- * Register a lazy command group. Creates a stub command whose action
- * loads the real registration module and re-parses argv.
- */
-function addLazyCommandGroup(parent, name, description, loader) {
-    const stub = parent
-        .command(name)
-        .description(description)
-        .allowUnknownOption(true)
-        .allowExcessArguments(true)
-        .helpOption(false);
-    stub.action(async () => {
-        // Remove stub and register the real commands
-        removeCommands(parent, name);
-        await loader();
-        // Re-parse so the real command tree handles the invocation
-        await parent.parseAsync(process.argv);
-    });
-}
 addLazyCommandGroup(program, 'daemon', 'Manage the Code Buddy daemon (background process)', async () => {
     const { registerDaemonCommands } = await import('./commands/cli/daemon-commands.js');
     registerDaemonCommands(program);
@@ -2427,6 +3053,18 @@ addLazyCommandGroup(program, 'speak', 'Synthesize speech using AudioReader TTS',
     const { registerSpeakCommand } = await import('./commands/cli/speak-command.js');
     registerSpeakCommand(program);
 });
+addLazyCommandGroup(program, 'assistant', 'Manage the voice assistant (Lisa): improvement loop, voice', async () => {
+    const { registerAssistantCommand } = await import('./commands/assistant.js');
+    registerAssistantCommand(program);
+});
+addLazyCommandGroup(program, 'self', 'Inspect Code Buddy’s documented self-model and evolution', async () => {
+    const { createSelfCommand } = await import('./commands/self.js');
+    program.addCommand(createSelfCommand());
+});
+addLazyCommandGroup(program, 'widgets', 'Inline conversation widgets: list, preview, generate (authored)', async () => {
+    const { registerWidgetsCommand } = await import('./commands/widgets.js');
+    registerWidgetsCommand(program);
+});
 // Utility commands (doctor, security-audit, onboard, webhook) are all registered
 // by a single registerUtilityCommands() call, so we must remove all stubs before
 // re-registering to avoid Commander duplicate command errors.
@@ -2436,6 +3074,11 @@ const loadUtilityCommands = async () => {
     removeCommands(program, utilityCommandNames);
     const { registerUtilityCommands } = await import('./commands/cli/utility-commands.js');
     registerUtilityCommands(program);
+    for (const name of utilityCommandNames) {
+        const command = program.commands.find((candidate) => candidate.name() === name);
+        if (command)
+            attachUnknownOptionHint(command, program);
+    }
     await program.parseAsync(process.argv);
 };
 for (const cmdName of utilityCommandNames) {
@@ -2463,6 +3106,14 @@ addLazyCommandGroup(program, 'hub', 'Skills marketplace (search, install, publis
     const { registerHubCommands } = await import('./commands/cli/native-engine-commands.js');
     registerHubCommands(program);
 });
+addLazyCommandGroup(program, 'curator', 'Propose-only maintenance report (memory, skills, CKG, lessons, costs)', async () => {
+    const { registerCuratorCommand } = await import('./commands/curator-cli.js');
+    registerCuratorCommand(program);
+});
+addLazyCommandGroup(program, 'triage', 'Write a local redacted support bundle and prompt (no network, launches nothing)', async () => {
+    const { registerTriageCommand } = await import('./commands/cli/triage-command.js');
+    registerTriageCommand(program);
+});
 addLazyCommandGroup(program, 'gateway-pairing', 'Operator approval for gateway device pairing', async () => {
     const { registerGatewayPairingCommands } = await import('./commands/cli/native-engine-commands.js');
     registerGatewayPairingCommands(program);
@@ -2474,7 +3125,7 @@ addLazyCommandGroup(program, 'screen', 'Capture, record, or watch the screen / a
 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);
-});
+}, ['colab']);
 addLazyCommandGroup(program, 'device', 'Manage paired device nodes (SSH, ADB, local)', async () => {
     const { registerDeviceCommands } = await import('./commands/cli/device-commands.js');
     registerDeviceCommands(program);
@@ -2495,6 +3146,18 @@ addLazyCommandGroup(program, 'auth-profile', 'Manage authentication profiles (AP
     const { registerAuthProfileCommands } = await import('./commands/cli/native-engine-commands.js');
     registerAuthProfileCommands(program);
 });
+addLazyCommand(program, 'token', 'Mint a signed JWT for the API and the mobile PWA', async () => {
+    const { createTokenCommand } = await import('./commands/token.js');
+    return createTokenCommand();
+});
+addLazyCommand(program, 'pair', 'Pair an Android authenticator with a local one-time code', async () => {
+    const { createPairCommand } = await import('./commands/device-auth.js');
+    return createPairCommand();
+});
+addLazyCommand(program, 'devices', 'Manage Android authentication devices', async () => {
+    const { createDevicesCommand } = await import('./commands/device-auth.js');
+    return createDevicesCommand();
+});
 addLazyCommandGroup(program, 'fleet', 'Inspect Fleet routing and dispatch policy decisions', async () => {
     const { registerFleetCommands } = await import('./commands/cli/fleet-commands.js');
     registerFleetCommands(program);
@@ -2552,6 +3215,11 @@ addLazyCommand(program, 'pairing', 'Manage DM pairing security (allowlist for me
     const { createPairingCommand } = await import('./commands/pairing.js');
     return createPairingCommand();
 });
+// Speculative shadow-workspace diagnostics
+addLazyCommand(program, 'shadow', 'Inspect or run speculative validation in the persistent shadow worktree', async () => {
+    const { createShadowCommand } = await import('./commands/shadow.js');
+    return createShadowCommand();
+});
 // Knowledge base management — add, list, show, search, remove, context
 addLazyCommand(program, 'knowledge', 'Manage agent knowledge bases (Knowledge.md files injected as context)', async () => {
     const { createKnowledgeCommand } = await import('./commands/knowledge.js');
@@ -2562,11 +3230,51 @@ addLazyCommand(program, 'research', 'Wide Research: spawn parallel agent workers
     const { createResearchCommand } = await import('./commands/research/index.js');
     return createResearchCommand();
 });
+// Meeting intelligence — local transcript/media to grounded Markdown + JSON
+addLazyCommand(program, 'meeting', 'Create grounded meeting notes from a local transcript, audio, or video file', async () => {
+    const { createMeetingCommand } = await import('./commands/meeting.js');
+    return createMeetingCommand();
+});
+// Local Scrapling scraper — fast HTTP, stealth/Cloudflare, or dynamic rendering.
+addLazyCommand(program, 'scrape', 'Scrape a web page locally with Scrapling (with web_fetch fallback)', async () => {
+    const { createScrapeCommand } = await import('./commands/scrape.js');
+    return createScrapeCommand();
+});
+// Paper QA — grounded, cited answers over a local corpus of scientific PDFs
+addLazyCommand(program, 'papers', 'Paper QA: ask a question over a corpus of scientific PDFs and get a grounded, cited answer', async () => {
+    const { createPapersCommand } = await import('./commands/papers/index.js');
+    return createPapersCommand();
+});
+// AI-Scientist-lite (Phases 0-3) — human-gated, sandboxed experiment: single pass or bounded discovery loop (opt-in)
+addLazyCommand(program, 'science', 'AI-Scientist-lite (EXPERIMENTAL, opt-in CODEBUDDY_AI_SCIENTIST=true): human-gated, sandboxed experiment — single pass or bounded best-first discovery loop (--loop)', async () => {
+    const { createScienceCommand } = await import('./commands/science/index.js');
+    return createScienceCommand();
+});
+addLazyCommand(program, 'gpu-worker', 'Run the authenticated PanoWorld/LongCat GPU job worker', async () => {
+    const { createGpuWorkerCommand } = await import('./commands/gpu-worker.js');
+    return createGpuWorkerCommand();
+});
+// Vision-training — synthetic perception curriculum: score robot vision vs
+// self-labeled scenes to find where it's weak (opt-in CODEBUDDY_VISION_TRAIN=true)
+addLazyCommand(program, 'vision-train', 'Synthetic perception-training loop (EXPERIMENTAL, opt-in CODEBUDDY_VISION_TRAIN=true): score the robot vision (YOLO) on labeled generated/real scenes → a weakness benchmark', async () => {
+    const { createVisionTrainCommand } = await import('./commands/vision-train.js');
+    return createVisionTrainCommand();
+});
+// Krea 2 LoRA — character/style LoRA dataset + fal cloud train + local plan + ComfyUI install
+addLazyCommand(program, 'lora', 'Krea 2 LoRA pipeline: init dataset, train cloud (fal, opt-in CODEBUDDY_LORA_TRAIN=true) or local plan, install into ComfyUI', async () => {
+    const { createLoraCommand } = await import('./commands/lora.js');
+    return createLoraCommand();
+});
 // 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();
 });
+// Film producer — chain generated clips into a long-form film with transitions
+addLazyCommand(program, 'film', 'Produce a long-form film from a scene plan: generate a clip per scene → montage with transitions + music → quality gate (resumable). Subcommands: generate|assemble|status', async () => {
+    const { createFilmCommand } = await import('./commands/film.js');
+    return createFilmCommand();
+});
 // Goal Ralph loop — headless judge-gated auto-continue (Hermes Agent parity)
 addLazyCommand(program, 'goal', 'Run the agent toward a standing goal until a judge model confirms it is done (Ralph loop)', async () => {
     const { createGoalCommand } = await import('./commands/goal-cli.js');
@@ -2575,6 +3283,48 @@ addLazyCommand(program, 'goal', 'Run the agent toward a standing goal until a ju
     const { validateGoalCommandNumericOptions } = await import('./commands/goal-cli.js');
     validateGoalCommandNumericOptions(argv);
 });
+// Dev-loop — boucle unifiée plan→exécute→vérifie(Verifier)→juge→décide (façon /loop)
+addLazyCommand(program, 'loop', 'Autonomous development loop (plan → execute → verify → judge → decide) until proven done or budget exhausted', async () => {
+    const { createLoopCommand } = await import('./commands/loop-cli.js');
+    return createLoopCommand();
+}, async (argv) => {
+    const { validateLoopCommandNumericOptions } = await import('./commands/loop-cli.js');
+    validateLoopCommandNumericOptions(argv);
+});
+// Code Buddy 2.0 — durable mission intent + proof-carrying completion
+addLazyCommand(program, 'intent', 'Inspect the current Intent Graph and secret-redacted Proof Ledger', async () => {
+    const { createIntentCommand } = await import('./commands/intent.js');
+    return createIntentCommand();
+});
+// Code Buddy 2.0 — opt-in, repository-local living specifications
+addLazyCommand(program, 'intents', 'Manage replayable intent specifications (EXPERIMENTAL, opt-in CODEBUDDY_INTENTS=true)', async () => {
+    const { createIntentsCommand } = await import('./commands/intents.js');
+    return createIntentsCommand();
+});
+addLazyCommand(program, 'replay', 'Inspect, restore, or fork a time-travel session timeline', async () => {
+    const { createReplayCommand } = await import('./commands/replay.js');
+    return createReplayCommand();
+});
+addLazyCommand(program, 'share', 'Export a saved session as a self-contained, shareable HTML replay', async () => {
+    const { createShareCommand } = await import('./commands/share.js');
+    return createShareCommand();
+});
+addLazyCommand(program, 'cost', 'Aggregate saved-session cost and token usage by model, provider, or day', async () => {
+    const { createCostCommand } = await import('./commands/cost.js');
+    return createCostCommand();
+});
+addLazyCommand(program, 'forge', 'Counterfactual Forge: compare competing strategies against one proof contract', async () => {
+    const { createForgeCommand } = await import('./commands/forge.js');
+    return createForgeCommand();
+});
+addLazyCommand(program, 'exchange', 'Sovereign execution market: constitution, multi-LLM bids, Shadow Twin and proof-gated award', async () => {
+    const { createExchangeCommand } = await import('./commands/exchange.js');
+    return createExchangeCommand();
+});
+addLazyCommand(program, 'capsule', 'Compile proven outcomes into proof-backed, multi-runtime portable workflows', async () => {
+    const { createCapsuleCommand } = await import('./commands/capsule.js');
+    return createCapsuleCommand();
+});
 // 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');
@@ -2590,6 +3340,10 @@ addLazyCommand(program, 'lessons', 'Manage lessons learned — self-improvement
     const { createLessonsCommand } = await import('./commands/lessons.js');
     return createLessonsCommand();
 });
+addLazyCommand(program, 'resources', 'Explicit network resource inventory and read-only health selection', async () => {
+    const { createResourcesCommand } = await import('./commands/resources.js');
+    return createResourcesCommand();
+});
 // 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');
@@ -2640,6 +3394,11 @@ addLazyCommandGroup(program, 'improve', 'Recursive self-improvement: empirically
     const { registerImproveCommands } = await import('./commands/cli/improve-command.js');
     registerImproveCommands(program);
 });
+// Evolve — git-versioned evolutionary self-improvement (evaluate code variants, keep the best, human-gated)
+addLazyCommandGroup(program, 'evolve', 'Git-versioned evolutionary self-improvement: evaluate code variants, keep the best (human-gated)', async () => {
+    const { registerEvolveCommands } = await import('./commands/cli/evolve-command.js');
+    registerEvolveCommands(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');
@@ -2656,27 +3415,8 @@ addLazyCommandGroup(program, 'deploy', 'Generate cloud deployment configurations
     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);
-});
+registerBackupCommand(program, (msg) => cli.stdout(msg));
+registerSensoryCommand(program, (msg) => cli.stdout(msg));
 // Cloud — background agent tasks (Cursor/Codex parity)
 program
     .command('cloud [subcommand] [args...]')
@@ -2716,5 +3456,75 @@ addLazyCommand(program, 'completions', 'Generate or install shell completion scr
     const { createCompletionsCommand } = await import('./commands/cli/completions-command.js');
     return createCompletionsCommand();
 });
-program.parse();
+installPermissionModeActionHook(program, async (mode) => {
+    const { getPermissionModeManager } = await import('./security/permission-modes.js');
+    // setMode announces the posture itself (INFO, escalated WARN for bypass);
+    // a second line here rendered as a false "ERROR Permission mode: <mode>".
+    getPermissionModeManager().setMode(mode);
+});
+// Apply the profile before parsing so it governs root chat, lazy subcommands,
+// slash-command menus, tool selection, and `buddy --help` consistently.
+process.argv = hoistPermissionModeOption(process.argv);
+const requestedProfile = getRequestedProfile(process.argv);
+if (requestedProfile.kind === 'missing') {
+    try {
+        getConfigManager().load();
+    }
+    catch (_error) {
+        // Listing available names is best-effort; the missing-value error still stands.
+    }
+    let available = '(none defined)';
+    try {
+        const names = Object.keys(getConfigManager().getConfig().profiles ?? {});
+        if (names.length)
+            available = names.join(', ');
+    }
+    catch (_error) {
+        available = 'core, all';
+    }
+    process.stderr.write(`error: option '--profile <name>' argument missing. Available profiles: ${available}\n`);
+    process.exitCode = 1;
+}
+else if (requestedProfile.kind === 'value') {
+    try {
+        getConfigManager().load();
+        getConfigManager().applyProfile(requestedProfile.name);
+    }
+    catch (err) {
+        process.stderr.write(`Profile error: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = 1;
+    }
+}
+function isRootHelpRequest(argv) {
+    const args = argv.slice(2);
+    if (!args.some((arg) => arg === '--help' || arg === '-h')) {
+        return false;
+    }
+    const commandNames = new Set(program.commands.map((command) => command.name()));
+    const { operands } = program.parseOptions(args);
+    return !operands.some((operand) => commandNames.has(operand));
+}
+// Commander writes help and immediately calls process.exit(). The root help is
+// larger than a macOS pipe buffer, so a slow reader can lose the queued suffix.
+// It is fully registered here: write it once and let Node drain stdout naturally.
+if (process.exitCode !== 1) {
+    attachUnknownOptionHint(program, program);
+    program.addHelpText('before', `Pour commencer — 6 démos qui montrent le cœur agent de code :
+  1. buddy try
+     Crée FizzBuzz, écrit son test et l’exécute dans un bac à sable.
+  2. /loop "Corrige les tests en échec"              (dans une session buddy)
+  3. buddy research "Cartographie ce dépôt"
+  4. buddy dev pr "Ajoute une petite fonctionnalité"
+  5. /think deep "Propose le refactoring le plus sûr" (dans une session buddy)
+  6. /share create demo                              (dans une session buddy)
+
+`);
+    removeCommands(program, getHiddenCliCommands());
+    if (isRootHelpRequest(process.argv)) {
+        program.outputHelp();
+    }
+    else {
+        program.parse();
+    }
+}
 //# sourceMappingURL=index.js.map