@brutalist/mcp 1.8.1 → 1.9.0

package/dist/cli-agents.js

@@ -3,7 +3,28 @@ import { promises as fs, realpathSync } from 'fs';
 import { promisify } from 'util';
 import { logger } from './logger.js';
 import { ModelResolver } from './model-resolver.js';
-import { resolveServers, writeClaudeMCPConfig, cleanupTempConfig, buildCodexMCPOverride, ensureGeminiMCPServers, ensurePlaywrightBrowsers, } from './mcp-registry.js';
+import { cleanupTempConfig, } from './mcp-registry.js';
+import { getProvider, parseNDJSON } from './cli-adapters/index.js';
+import { GEMINI_FRONTIER_CHAIN } from './cli-adapters/gemini-adapter.js';
+import { safeMetric } from './metrics/index.js';
+/**
+ * Detect Gemini-specific saturation errors — "No capacity available",
+ * status 429, overloaded, quota exhaustion. Used by the frontier-chain
+ * rotation logic in `executeSingleCLI` to decide whether to rotate to the
+ * next model tier or fail immediately (non-saturation errors don't
+ * benefit from a different model).
+ *
+ * Model-not-found (/ModelNotFoundError/) is NOT saturation — it means
+ * the model alias is wrong. Treat as non-saturation so rotation aborts
+ * and the caller sees the error rather than silently rotating past it.
+ */
+function isGeminiSaturationError(error) {
+    if (!error)
+        return false;
+    if (/ModelNotFoundError/i.test(error))
+        return false;
+    return /no capacity available|\b429\b|overloaded|rateLimitExceeded|rate limit|quota|too many requests/i.test(error);
+}
 // Configurable timeouts and limits
 const DEFAULT_TIMEOUT = parseInt(process.env.BRUTALIST_TIMEOUT || '1800000', 10); // 30 minutes default
 const CLI_CHECK_TIMEOUT = parseInt(process.env.BRUTALIST_CLI_CHECK_TIMEOUT || '5000', 10); // 5 seconds for CLI checks
@@ -239,6 +260,19 @@ async function spawnAsync(command, args, options = {}) {
             spawnCommand = command;
             spawnArgs = args;
         }
+        // Fires only after all pre-spawn validators (command, args, cwd)
+        // pass. Callers gate their `spawned` flag on this callback so
+        // invalid-command / invalid-args / invalid-cwd rejects do NOT count
+        // as spawn outcomes in `brutalist_cli_spawn_total`
+        // (Cycle 3 Task CLI-C'). Wrapped in try/catch because a throw from
+        // the user-supplied callback must not abort the spawn itself.
+        try {
+            options.onBeforeSpawn?.();
+        }
+        catch {
+            // Swallow — this hook is diagnostic only; failures here must not
+            // prevent the spawn from proceeding.
+        }
         const child = spawn(spawnCommand, spawnArgs, {
             cwd: cwd,
             stdio: ['pipe', 'pipe', 'pipe'],
@@ -399,58 +433,6 @@ async function spawnAsync(command, args, options = {}) {
         }
     });
 }
-const CLI_BUILDER_CONFIGS = {
-    claude: {
-        command: 'claude',
-        defaultArgs: ['--print'],
-        modelArgName: '--model',
-        mpcEnvCleanup: ['CLAUDE_MCP_CONFIG', 'MCP_ENABLED', 'CLAUDECODE', 'CLAUDE_CODE_ENTRYPOINT'],
-        streamingArgs: () => ['--output-format', 'stream-json', '--verbose'],
-        mcpSupport: {
-            configMethod: 'flag-file',
-            configFlag: '--mcp-config',
-            strictFlag: '--strict-mcp-config',
-            writeProtection: {
-                method: 'disallowed-tools',
-                flag: '--disallowedTools',
-                value: 'Edit,Write,NotebookEdit',
-            },
-        },
-    },
-    codex: {
-        command: 'codex',
-        defaultArgs: ['exec', '--sandbox', 'read-only', '--skip-git-repo-check'],
-        modelArgName: '--model',
-        jsonFlag: '--json',
-        mpcEnvCleanup: ['CODEX_MCP_CONFIG', 'MCP_ENABLED'],
-        promptWrapper: (sys, user) => `${sys}\n\n${user}\n\nUse your shell tools to read files (cat, ls, find, grep, head, etc.) and analyze the codebase. You ARE allowed to run read-only commands. Explore the directory structure, read relevant source files, and provide a comprehensive brutal analysis based on what you find.`,
-        mcpSupport: {
-            configMethod: 'config-override',
-            configOverrideKey: 'mcp_servers',
-            writeProtection: {
-                method: 'sandbox',
-                flag: '--sandbox',
-                value: 'read-only', // already in defaultArgs
-            },
-        },
-    },
-    gemini: {
-        command: 'gemini',
-        defaultArgs: ['--output-format', 'json'],
-        modelArgName: '--model',
-        envExtras: { TERM: 'dumb', NO_COLOR: '1', CI: 'true' },
-        mpcEnvCleanup: ['GEMINI_MCP_CONFIG', 'MCP_ENABLED'],
-        mcpSupport: {
-            configMethod: 'server-whitelist',
-            whitelistFlag: '--allowed-mcp-server-names',
-            writeProtection: {
-                method: 'approval-mode',
-                flag: '--approval-mode',
-                value: 'plan',
-            },
-        },
-    },
-};
 export class CLIAgentOrchestrator {
     defaultTimeout = 1800000; // 30 minutes - complex codebases need time
     defaultWorkingDir = process.cwd();
@@ -462,217 +444,94 @@ export class CLIAgentOrchestrator {
     MAX_CONCURRENT_CLIS = MAX_CONCURRENT_CLIS; // Configurable concurrency limit
     // Runtime model discovery
     modelResolver;
+    // Optional observability deps — injected at the composition root in
+    // production; absent (undefined) in test harnesses that construct
+    // `new CLIAgentOrchestrator()` with no args. Instrumentation is a no-op
+    // when these are undefined, via `this.metrics?.*` and `emitLog()` fallback.
+    metrics;
+    log;
     // Streaming throttle properties
     streamingBuffers = new Map();
     STREAMING_FLUSH_INTERVAL = 200; // 200ms
     MAX_CHUNK_SIZE = 2048; // 2KB per event
     HEARTBEAT_INTERVAL = 5000; // 5s between progress heartbeats
     lastHeartbeat = 0;
-    constructor(modelResolver) {
-        this.modelResolver = modelResolver || new ModelResolver();
-        // Log configuration at startup
-        logger.info(`🔧 Brutalist MCP Configuration:`);
-        logger.info(`  - Default timeout: ${DEFAULT_TIMEOUT}ms`);
-        logger.info(`  - CLI check timeout: ${CLI_CHECK_TIMEOUT}ms`);
-        logger.info(`  - Max buffer size: ${MAX_BUFFER_SIZE} bytes`);
-        logger.info(`  - Max concurrent CLIs: ${MAX_CONCURRENT_CLIS}`);
+    /**
+     * Accepts a deps bag OR a bare `ModelResolver` (legacy positional form)
+     * OR nothing (characterization-test harnesses). The `instanceof ModelResolver`
+     * branch preserves the pre-observability signature.
+     */
+    constructor(deps) {
+        const bag = deps instanceof ModelResolver
+            ? { modelResolver: deps }
+            : (deps || {});
+        this.modelResolver = bag.modelResolver || new ModelResolver();
+        this.metrics = bag.metrics;
+        this.log = bag.log;
+        // Log configuration at startup (via emitLog — falls back to root logger
+        // when no scoped log was injected).
+        const bootLog = this.emitLog();
+        bootLog.info(`🔧 Brutalist MCP Configuration:`);
+        bootLog.info(`  - Default timeout: ${DEFAULT_TIMEOUT}ms`);
+        bootLog.info(`  - CLI check timeout: ${CLI_CHECK_TIMEOUT}ms`);
+        bootLog.info(`  - Max buffer size: ${MAX_BUFFER_SIZE} bytes`);
+        bootLog.info(`  - Max concurrent CLIs: ${MAX_CONCURRENT_CLIS}`);
         // Detect CLI context and discover models at startup
         Promise.all([
             this.detectCLIContext(),
             this.modelResolver.initialize(),
         ]).catch(error => {
-            logger.error("Failed startup detection:", error);
+            this.emitLog().error("Failed startup detection:", error);
         });
     }
-    // Parse NDJSON with proper JSON boundary detection
-    // Handles JSON objects that contain embedded newlines without data loss
+    /**
+     * Return the injected scoped logger if present, otherwise the root
+     * logger singleton. Keeps un-injected (test) instances working while
+     * scoping production emissions with `module='cli-orchestrator'`.
+     */
+    emitLog() {
+        return this.log ?? logger;
+    }
+    /**
+     * Heuristic for classifying a spawnAsync error as a timeout.
+     * Centralized so all outcome paths share the same detection logic.
+     *
+     * Matches any of:
+     *   - execError.code === 'ETIMEDOUT' (Node's timeout code on some paths)
+     *   - execError.killed === true (child_process kill after SIGTERM/SIGKILL
+     *     escalation when the timeout timer fired — see spawnAsync timer block)
+     *   - execError.message matching /timed out|timeout/i (spawnAsync rejects
+     *     with "Command timed out after ..." on timer expiry)
+     */
+    isTimeoutError(err) {
+        if (!err || typeof err !== 'object')
+            return false;
+        const e = err;
+        if (e.code === 'ETIMEDOUT')
+            return true;
+        if (e.killed === true)
+            return true;
+        if (typeof e.message === 'string' && /timed out|timeout/i.test(e.message))
+            return true;
+        return false;
+    }
+    // Proxy methods for backward compatibility — characterization tests
+    // access these via (orchestrator as any).methodName().
+    // Implementation lives in src/cli-adapters/.
     parseNDJSON(input) {
-        if (!input || !input.trim()) {
-            return [];
-        }
-        const results = [];
-        let depth = 0;
-        let inString = false;
-        let escape = false;
-        let start = 0;
-        for (let i = 0; i < input.length; i++) {
-            const char = input[i];
-            // Handle escape sequences
-            if (escape) {
-                escape = false;
-                continue;
-            }
-            if (char === '\\') {
-                escape = true;
-                continue;
-            }
-            // Track string boundaries
-            if (char === '"') {
-                inString = !inString;
-                continue;
-            }
-            // Only count braces/brackets outside of strings
-            if (inString)
-                continue;
-            // Track depth
-            if (char === '{' || char === '[') {
-                depth++;
-            }
-            else if (char === '}' || char === ']') {
-                depth--;
-                // When depth returns to 0, we've found a complete JSON object
-                if (depth === 0) {
-                    const jsonStr = input.slice(start, i + 1).trim();
-                    if (jsonStr) {
-                        try {
-                            const parsed = JSON.parse(jsonStr);
-                            results.push(parsed);
-                        }
-                        catch (e) {
-                            // Log unparseable segments (not silent)
-                            logger.warn(`Failed to parse JSON segment at position ${start}-${i + 1}:`, {
-                                preview: jsonStr.substring(0, 100),
-                                error: e instanceof Error ? e.message : String(e)
-                            });
-                        }
-                    }
-                    // Move start pointer past this object and any whitespace
-                    start = i + 1;
-                    while (start < input.length && /\s/.test(input[start])) {
-                        start++;
-                    }
-                    i = start - 1; // Will be incremented by loop
-                }
-            }
-        }
-        // Warn about incomplete JSON at end of input
-        if (start < input.length) {
-            const remaining = input.slice(start).trim();
-            if (remaining) {
-                logger.warn(`Incomplete JSON at end of input:`, {
-                    preview: remaining.substring(0, 100)
-                });
-            }
-        }
-        return results;
+        return parseNDJSON(input);
     }
-    // Decode Claude's stream-json NDJSON output into plain text.
-    // Extracts text content blocks from all 'assistant' events across all turns.
-    // Skips system events, user events (tool results with raw file contents), and
-    // tool_use content blocks within assistant events.
-    // Falls back to 'result' event if no assistant text was captured.
     decodeClaudeStreamJson(ndjsonOutput) {
-        if (!ndjsonOutput || !ndjsonOutput.trim()) {
-            logger.warn('decodeClaudeStreamJson: empty input');
-            return '';
-        }
-        const events = this.parseNDJSON(ndjsonOutput);
-        if (events.length === 0) {
-            logger.warn('decodeClaudeStreamJson: no valid JSON events found in output');
-            return '';
-        }
-        const textParts = [];
-        let resultText = '';
-        let resultError = '';
-        for (const event of events) {
-            if (typeof event !== 'object' || event === null)
-                continue;
-            const typedEvent = event;
-            if (typedEvent.type === 'assistant' && typedEvent.message?.content) {
-                // Extract only text blocks from assistant messages (skip tool_use blocks)
-                const content = typedEvent.message.content;
-                if (Array.isArray(content)) {
-                    for (const item of content) {
-                        if (item.type === 'text' && item.text) {
-                            textParts.push(item.text);
-                        }
-                    }
-                }
-            }
-            else if (typedEvent.type === 'result') {
-                if (typedEvent.subtype === 'error' || typedEvent.is_error) {
-                    resultError = typedEvent.error || typedEvent.result || 'Unknown error';
-                }
-                else if (typedEvent.result) {
-                    resultText = typedEvent.result;
-                }
-            }
-            // Skip: system, user (tool_result with raw file contents), hooks
-        }
-        // Handle error
-        if (resultError) {
-            logger.error('decodeClaudeStreamJson: Claude returned error result', { error: resultError });
-            return `[Claude Error] ${resultError}`;
-        }
-        // Use accumulated assistant text if available, fall back to result event
-        if (textParts.length > 0) {
-            return textParts.join('\n\n');
-        }
-        if (resultText) {
-            return resultText;
-        }
-        logger.warn('decodeClaudeStreamJson: no text content found in stream-json output', {
-            eventCount: events.length,
-            eventTypes: events.map(e => e.type).filter(Boolean)
-        });
-        return '';
+        const provider = getProvider('claude');
+        return provider.decodeOutput(ndjsonOutput, ['--output-format', 'stream-json']);
     }
-    // Extract only the agent messages from Codex JSON output (no thinking, no file reads, no commands)
     extractCodexAgentMessage(jsonOutput) {
-        if (!jsonOutput || !jsonOutput.trim()) {
-            logger.debug('extractCodexAgentMessage: empty input');
-            return '';
-        }
-        const agentMessages = [];
-        const events = this.parseNDJSON(jsonOutput);
-        logger.debug(`extractCodexAgentMessage: processing ${events.length} JSON events`);
-        for (const event of events) {
-            if (typeof event !== 'object' || event === null)
-                continue;
-            const typedEvent = event;
-            logger.debug(`extractCodexAgentMessage: parsed event type=${typedEvent.type}, item.type=${typedEvent.item?.type}`);
-            // Codex --json outputs events with structure: {"type":"item.completed","item":{...}}
-            // Only extract agent_message type - this is the actual response
-            if (typedEvent.type === 'item.completed' && typedEvent.item) {
-                if (typedEvent.item.type === 'agent_message' && typedEvent.item.text) {
-                    // Agent's actual response text
-                    logger.info(`✅ extractCodexAgentMessage: found agent_message with ${typedEvent.item.text.length} chars`);
-                    agentMessages.push(typedEvent.item.text);
-                }
-                // Skip all other types:
-                // - reasoning: internal thinking steps
-                // - command_execution: file reads, bash commands
-                // - error: will be in stderr
-            }
-        }
-        const result = agentMessages.join('\n\n').trim();
-        logger.info(`extractCodexAgentMessage: extracted ${agentMessages.length} messages, total ${result.length} chars`);
-        return result;
+        const provider = getProvider('codex');
+        return provider.decodeOutput(jsonOutput, ['--json']);
     }
-    // Extract response text from Gemini --output-format json output
     extractGeminiResponse(jsonOutput) {
-        if (!jsonOutput || !jsonOutput.trim()) {
-            logger.debug('extractGeminiResponse: empty input');
-            return '';
-        }
-        try {
-            const parsed = JSON.parse(jsonOutput);
-            if (parsed.response && typeof parsed.response === 'string') {
-                logger.info(`✅ extractGeminiResponse: extracted response with ${parsed.response.length} chars`);
-                return parsed.response;
-            }
-            logger.warn('extractGeminiResponse: no response field in JSON output', {
-                keys: Object.keys(parsed)
-            });
-            return '';
-        }
-        catch (e) {
-            logger.warn('extractGeminiResponse: failed to parse JSON, returning raw output', {
-                error: e instanceof Error ? e.message : String(e),
-                preview: jsonOutput.substring(0, 200)
-            });
-            return '';
-        }
+        const provider = getProvider('gemini');
+        return provider.decodeOutput(jsonOutput, ['--output-format', 'json']);
     }
     emitThrottledStreamingEvent(agent, type, content, onStreamingEvent, options) {
         if (!onStreamingEvent)
@@ -719,98 +578,23 @@ export class CLIAgentOrchestrator {
             buffer.lastFlush = now;
         }
     }
+    // Proxy: delegates to per-provider adapter via getProvider()
     async buildCLICommand(cli, userPrompt, systemPrompt, options) {
-        const config = CLI_BUILDER_CONFIGS[cli];
-        const mcpEnabled = options.mcpServers && options.mcpServers.length > 0;
-        // Build args
-        const args = [...config.defaultArgs];
-        const resolvedModel = this.modelResolver.resolveModel(cli, options.models?.[cli]);
-        if (resolvedModel) {
-            args.push(config.modelArgName, resolvedModel);
-        }
-        if (config.jsonFlag && process.env.CODEX_USE_JSON !== 'false') {
-            args.push(config.jsonFlag);
-        }
-        if (config.streamingArgs) {
-            args.push(...config.streamingArgs(options));
-        }
-        // ── MCP configuration ────────────────────────────────────────────────
-        let tempMcpConfigPath;
-        if (mcpEnabled && config.mcpSupport) {
-            const servers = resolveServers(options.mcpServers);
-            const serverNames = Object.keys(servers);
-            // Auto-install Playwright browsers if playwright is requested
-            if (servers.playwright) {
-                await ensurePlaywrightBrowsers();
-            }
-            if (serverNames.length > 0) {
-                const mcp = config.mcpSupport;
-                switch (mcp.configMethod) {
-                    case 'flag-file': {
-                        // Claude: write temp JSON config, pass --mcp-config <path> --strict-mcp-config
-                        const sessionId = options.sessionId || 'default';
-                        tempMcpConfigPath = await writeClaudeMCPConfig(servers, sessionId);
-                        args.push(mcp.configFlag, tempMcpConfigPath);
-                        args.push(mcp.strictFlag);
-                        // Hard deny on write tools
-                        args.push(mcp.writeProtection.flag, mcp.writeProtection.value);
-                        // Non-interactive MCP tool use requires permission bypass
-                        args.push('--permission-mode', 'bypassPermissions');
-                        break;
-                    }
-                    case 'config-override': {
-                        // Codex: -c 'mcp_servers={...}' — replaces all configured servers (excludes brutalist)
-                        const tomlOverride = buildCodexMCPOverride(servers);
-                        args.push('-c', `${mcp.configOverrideKey}=${tomlOverride}`);
-                        // Write protection already in defaultArgs (--sandbox read-only)
-                        break;
-                    }
-                    case 'server-whitelist': {
-                        // Gemini: --allowed-mcp-server-names <names> --approval-mode plan
-                        await ensureGeminiMCPServers(servers);
-                        args.push(mcp.whitelistFlag, ...serverNames);
-                        args.push(mcp.writeProtection.flag, mcp.writeProtection.value);
-                        break;
-                    }
-                }
-                logger.info(`🔌 MCP enabled for ${cli}: [${serverNames.join(', ')}]`);
-            }
-        }
-        // Build prompt — skip CLI-specific wrapper in debate mode (prevents Codex
-        // from exploring the brutalist repo and reading its own control prompts)
-        const combinedPrompt = (config.promptWrapper && !options.debateMode)
-            ? config.promptWrapper(systemPrompt, userPrompt)
-            : `${systemPrompt}\n\n${userPrompt}`;
-        // Build secure env
+        const provider = getProvider(cli);
         const secureEnv = createSecureEnvironment();
-        // Add CLI-specific env extras
-        if (config.envExtras) {
-            Object.assign(secureEnv, config.envExtras);
-        }
-        // Add required API key
-        const apiKeyMap = {
-            claude: ['ANTHROPIC_API_KEY'],
-            codex: ['OPENAI_API_KEY'],
-            gemini: ['GOOGLE_API_KEY', 'GEMINI_API_KEY']
-        };
-        for (const key of apiKeyMap[cli]) {
-            if (process.env[key])
-                secureEnv[key] = process.env[key];
-        }
-        // Clean up MPC env vars that could cause deadlock — SKIP when MCP is enabled
-        // (the per-CLI config above already isolates to only the requested servers)
-        if (!mcpEnabled && config.mpcEnvCleanup) {
-            for (const envVar of config.mpcEnvCleanup) {
-                delete secureEnv[envVar];
-            }
-        }
-        secureEnv.BRUTALIST_SUBPROCESS = '1';
-        return { command: config.command, args, input: combinedPrompt, env: secureEnv, tempMcpConfigPath };
+        // Pattern A: thread the scoped logger into the adapter via CLIAgentOptions.log.
+        // The adapter reads options.log?.forOperation('<cli>_spawn') and falls back to
+        // the root logger import if absent. A caller-supplied options.log wins so a
+        // test or an upstream operation can override the per-orchestrator default.
+        const perCliOp = `${cli}_spawn`;
+        const adapterLog = options.log ?? this.log?.forOperation(perCliOp);
+        const optionsWithLog = adapterLog && options.log === undefined ? { ...options, log: adapterLog } : options;
+        return provider.buildCommand(userPrompt, systemPrompt, optionsWithLog, this.modelResolver, secureEnv);
     }
     async detectCLIContext() {
         // Return cached context if still valid
         if (this.cliContextCached && Date.now() - this.cliContextCacheTime < this.CLI_CACHE_TTL) {
-            logger.debug('Using cached CLI context');
+            this.emitLog().debug('Using cached CLI context');
             return this.cliContext;
         }
         const availableCLIs = [];
@@ -820,14 +604,16 @@ export class CLIAgentOrchestrator {
             { name: 'codex', command: 'codex --version' },
             { name: 'gemini', command: 'gemini --version' }
         ];
+        // NOTE: These `--version` probes are NOT spawn attempts — they must not
+        // increment `cliSpawnTotal`. Only _executeCLI counts spawns.
         const results = await Promise.allSettled(cliChecks.map(async (check) => {
             try {
                 await spawnAsync(check.name, ['--version'], { timeout: CLI_CHECK_TIMEOUT });
-                logger.debug(`CLI available: ${check.name}`);
+                this.emitLog().debug(`CLI available: ${check.name}`);
                 return check.name;
             }
             catch (error) {
-                logger.debug(`CLI not available: ${check.name}`);
+                this.emitLog().debug(`CLI not available: ${check.name}`);
                 return null;
             }
         }));
@@ -843,7 +629,7 @@ export class CLIAgentOrchestrator {
     selectSingleCLI(preferredCLI, analysisType) {
         // 1. Honor explicit preference if available
         if (preferredCLI && this.cliContext.availableCLIs.includes(preferredCLI)) {
-            logger.info(`✅ Using preferred CLI: ${preferredCLI}`);
+            this.emitLog().info(`✅ Using preferred CLI: ${preferredCLI}`);
             return preferredCLI;
         }
         // 2. Smart selection based on analysis type
@@ -863,7 +649,7 @@ export class CLIAgentOrchestrator {
         // 3. Select by priority from available CLIs
         for (const cli of priority) {
             if (this.cliContext.availableCLIs.includes(cli)) {
-                logger.info(`🎯 Auto-selected ${cli} for ${analysisType || 'general'} analysis`);
+                this.emitLog().info(`🎯 Auto-selected ${cli} for ${analysisType || 'general'} analysis`);
                 return cli;
             }
         }
@@ -871,7 +657,7 @@ export class CLIAgentOrchestrator {
         if (this.cliContext.availableCLIs.length === 0) {
             throw new Error('No CLI agents available');
         }
-        logger.warn(`⚠️ Using fallback CLI: ${this.cliContext.availableCLIs[0]}`);
+        this.emitLog().warn(`⚠️ Using fallback CLI: ${this.cliContext.availableCLIs[0]}`);
         return this.cliContext.availableCLIs[0];
     }
     async _executeCLI(cliName, userPrompt, systemPromptSpec, options = {}, commandBuilder) {
@@ -879,9 +665,22 @@ export class CLIAgentOrchestrator {
         const workingDir = options.workingDirectory || this.defaultWorkingDir;
         const timeout = options.timeout || this.defaultTimeout;
         let tempMcpConfigPath;
+        // Provider label for the spawn counter. Derived from cliName so the
+        // label set stays in sync with the 'claude' | 'codex' | 'gemini' union
+        // instead of reading adapter.name.
+        const provider = cliName;
+        // Gate for the catch-branch counter emission. Per compose.py:174,
+        // pre-spawn paths (commandBuilder throwing before spawnAsync is
+        // invoked, or spawnAsync's own pre-spawn validators for
+        // command/args/cwd rejecting) do NOT represent a spawn attempt and
+        // must not increment the counter. Cycle 3 Task CLI-C' tightened
+        // the semantics: `spawned` is now flipped inside spawnAsync via the
+        // `onBeforeSpawn` callback, which fires only after all pre-spawn
+        // validators pass and immediately before `child_process.spawn()`.
+        let spawned = false;
         try {
-            logger.info(`🤖 Executing ${cliName.toUpperCase()} CLI`);
-            logger.debug(`${cliName.toUpperCase()} prompt`, { prompt: userPrompt.substring(0, 100) });
+            this.emitLog().info(`🤖 Executing ${cliName.toUpperCase()} CLI`);
+            this.emitLog().debug(`${cliName.toUpperCase()} prompt`, { promptLength: userPrompt.length });
             // Emit agent start event
             if (options.onStreamingEvent) {
                 options.onStreamingEvent({
@@ -895,33 +694,57 @@ export class CLIAgentOrchestrator {
             const built = await commandBuilder(userPrompt, systemPromptSpec, options);
             const { command, args, env, input } = built;
             tempMcpConfigPath = built.tempMcpConfigPath;
-            logger.info(`📋 Command: ${command} ${args.join(' ')}`);
-            logger.info(`📁 Working directory: ${workingDir}`);
-            logger.info(`⏱️ Timeout: ${timeout}ms`);
+            // Cycle 4 Task T18 (F9 — security): do NOT log raw command +
+            // joined args. The args array can contain caller-controlled
+            // content that crossed the trust boundary (Codex `-c
+            // mcp_servers=<TOML>` override content, Claude `--mcp-config
+            // <temp-path>`, prompt fragments for CLIs that accept inline
+            // prompt). Log only bounded metadata — cliName for provider
+            // identification, argCount for diagnostic shape, and
+            // hasMcpConfig so operators can correlate MCP-enabled spawns
+            // with MCP registry entries.
+            const hasMcpConfig = !!(options.mcpServers && options.mcpServers.length > 0);
+            this.emitLog().info('CLI spawn preparing', {
+                cliName,
+                argCount: args.length,
+                hasMcpConfig,
+            });
+            this.emitLog().info(`📁 Working directory: ${workingDir}`);
+            this.emitLog().info(`⏱️ Timeout: ${timeout}ms`);
             if (input) {
-                logger.info(`📝 Using stdin for prompt (${input.length} characters)`);
+                this.emitLog().info(`📝 Using stdin for prompt (${input.length} characters)`);
             }
+            // `spawned` is flipped by spawnAsync's `onBeforeSpawn` callback
+            // immediately before `child_process.spawn()`. This means
+            // pre-spawn validator rejects inside spawnAsync (invalid command,
+            // invalid args, invalid cwd) leave `spawned === false` so the
+            // catch-branch counter does NOT fire for those paths
+            // (Cycle 3 Task CLI-C').
             const { stdout, stderr } = await spawnAsync(command, args, {
                 cwd: workingDir,
                 timeout: timeout,
                 maxBuffer: MAX_BUFFER_SIZE, // Configurable buffer for model outputs
                 env: env,
                 input: input,
+                onBeforeSpawn: () => { spawned = true; },
                 onProgress: (chunk, type) => {
-                    // Stream output in real-time with agent identification
+                    // Stream output in real-time with agent identification.
+                    // Log payloads are length-only at debug level — raw chunk text is
+                    // NEVER emitted to the logger to avoid leaking prompt / response
+                    // content through log aggregators. Streaming events are Layer 2.
                     if (type === 'stdout' && chunk.trim()) {
-                        logger.info(`🤖 ${cliName.toUpperCase()}: ${chunk.trim()}`);
+                        this.emitLog().debug(`${cliName.toUpperCase()} stdout chunk received`, { bytes: chunk.length });
                         // Emit throttled streaming event for real-time updates
                         this.emitThrottledStreamingEvent(cliName, 'agent_progress', chunk.trim(), options.onStreamingEvent, options);
                     }
                     else if (type === 'stderr' && chunk.trim()) {
-                        logger.warn(`⚠️ ${cliName.toUpperCase()} stderr: ${chunk.trim()}`);
+                        this.emitLog().debug(`${cliName.toUpperCase()} stderr chunk received`, { bytes: chunk.length });
                         // Emit throttled error streaming event
                         this.emitThrottledStreamingEvent(cliName, 'agent_error', chunk.trim(), options.onStreamingEvent, options);
                     }
                 }
             });
-            logger.info(`✅ ${cliName.toUpperCase()} completed (${Date.now() - startTime}ms)`);
+            this.emitLog().info(`✅ ${cliName.toUpperCase()} completed (${Date.now() - startTime}ms)`);
             // Emit completion event
             if (options.onStreamingEvent) {
                 options.onStreamingEvent({
@@ -932,33 +755,20 @@ export class CLIAgentOrchestrator {
                     sessionId: options.sessionId
                 });
             }
-            // Post-process CLI output if needed
+            // Post-process CLI output via provider adapter. Thread the scoped
+            // logger through decodeOutput so adapter warnings/errors carry
+            // module=cli-orchestrator + operation=<provider>_spawn context.
             let finalOutput = stdout;
-            // If Claude was run with stream-json format, decode the NDJSON to extract text
-            if (cliName === 'claude' && args.includes('--output-format') && args.includes('stream-json')) {
-                const decodedText = this.decodeClaudeStreamJson(stdout);
-                if (decodedText) {
-                    finalOutput = decodedText;
-                }
-            }
-            // If Codex was run with --json flag, extract only the agent messages
-            if (cliName === 'codex' && args.includes('--json')) {
-                const decodedText = this.extractCodexAgentMessage(stdout);
-                if (decodedText) {
-                    finalOutput = decodedText;
-                }
-            }
-            // If Gemini was run with --output-format json, extract the response field
-            if (cliName === 'gemini' && args.includes('--output-format') && args.includes('json')) {
-                const decodedText = this.extractGeminiResponse(stdout);
-                if (decodedText) {
-                    finalOutput = decodedText;
-                }
+            const providerAdapter = getProvider(cliName);
+            const decodeLog = this.log?.forOperation(`${cliName}_spawn`);
+            const decodedText = providerAdapter.decodeOutput(stdout, args, decodeLog);
+            if (decodedText) {
+                finalOutput = decodedText;
             }
             // Fallback: If stdout is empty but stderr has content and exit was successful,
             // Claude might have written to stderr (common in non-TTY environments)
             if (!finalOutput.trim() && stderr && stderr.trim()) {
-                logger.info(`📝 Using stderr as output for ${cliName} (stdout was empty)`);
+                this.emitLog().info(`📝 Using stderr as output for ${cliName} (stdout was empty)`);
                 finalOutput = stderr;
             }
             // Detect CLI errors that exit 0 but contain fatal error output
@@ -985,7 +795,7 @@ export class CLIAgentOrchestrator {
                 const resetMatch = combinedOutput.match(/reset(?:s)? (?:in|after) (\d+h\s*\d+m(?:\s*\d+s)?)/i);
                 const resetInfo = resetMatch ? ` (resets in ${resetMatch[1]})` : '';
                 const errorMsg = `${cliName.toUpperCase()} quota exhausted${resetInfo}. The CLI exited 0 but returned a quota error instead of analysis output.`;
-                logger.warn(`⏱️ ${errorMsg}`);
+                this.emitLog().warn(`⏱️ ${errorMsg}`);
                 if (options.onStreamingEvent) {
                     options.onStreamingEvent({
                         type: 'agent_error',
@@ -995,24 +805,64 @@ export class CLIAgentOrchestrator {
                         sessionId: options.sessionId
                     });
                 }
+                // Spawn counter: outcome=refused (quota exhaustion — CLI exited 0
+                // with a quota error in stdout/stderr). Labels annotated against
+                // CLI_SPAWN_LABELS so a future label-set change fails at compile
+                // time. Wrapped in `safeMetric` so a label-validation throw or
+                // other metric-layer exception cannot propagate into the outer
+                // spawn try/catch and be misclassified as a spawn failure
+                // (Cycle 3 Task CLI-B' — parity with debate's safeMetric).
+                const quotaLabels = {
+                    provider,
+                    outcome: 'refused',
+                };
+                safeMetric(this.emitLog(), 'cliSpawnTotal.inc(refused:quota)', () => {
+                    this.metrics?.cliSpawnTotal.inc(quotaLabels, 1);
+                });
                 return {
                     agent: cliName,
                     success: false,
                     output: '',
                     error: errorMsg,
                     executionTime: Date.now() - startTime,
-                    command: `${command} ${args.join(' ')}`,
+                    // Cycle 4 Task T18 (F9): match the failure-path redaction
+                    // parity — `command` is a diagnostic display field; the
+                    // static placeholder preserves the response shape without
+                    // leaking raw command + args (which may include Codex TOML
+                    // MCP overrides, Claude temp config paths, or prompt
+                    // fragments that crossed the trust boundary).
+                    command: `(redacted command for ${cliName})`,
                     workingDirectory: workingDir,
                     exitCode: 0
                 };
             }
+            // Spawn counter: outcome=success (normal completion path). Labels
+            // annotated against CLI_SPAWN_LABELS so a future label-set change
+            // fails at compile time. Wrapped in `safeMetric` so a metric-layer
+            // exception cannot propagate into the outer catch branch and be
+            // misclassified as a spawn failure (Cycle 3 Task CLI-B').
+            const successLabels = {
+                provider,
+                outcome: 'success',
+            };
+            safeMetric(this.emitLog(), 'cliSpawnTotal.inc(success)', () => {
+                this.metrics?.cliSpawnTotal.inc(successLabels, 1);
+            });
             return {
                 agent: cliName,
                 success: true,
                 output: finalOutput,
                 error: stderr || undefined,
                 executionTime: Date.now() - startTime,
-                command: `${command} ${args.join(' ')}`,
+                // Cycle 4 Task T18 (F9): same redaction parity as the
+                // failure path — `command` is a diagnostic display field,
+                // not a machine-readable command reproduction. The raw
+                // command + args can contain caller-controlled payloads
+                // (Codex TOML MCP overrides at codex-adapter.ts:86/:87,
+                // Claude temp config paths at claude-adapter.ts:96, prompt
+                // fragments for CLIs that accept inline prompt) that
+                // crossed the trust boundary.
+                command: `(redacted command for ${cliName})`,
                 workingDirectory: workingDir,
                 exitCode: 0
             };
@@ -1029,20 +879,66 @@ export class CLIAgentOrchestrator {
             ];
             const errorText = `${execError.message || ''} ${execError.stderr || ''}`.toLowerCase();
             const isRateLimit = rateLimitPatterns.some(p => errorText.includes(p.toLowerCase()));
+            // Classify outcome for the spawn counter. Priority: rate-limit > timeout
+            // > generic failure. Timeout check uses the centralized heuristic.
+            // Classification priority is unchanged; the emission is gated on
+            // `spawned` so pre-spawn failures (e.g., commandBuilder throwing)
+            // do NOT increment the counter (compose.py:174).
+            let outcome;
+            if (isRateLimit) {
+                outcome = 'refused';
+            }
+            else if (this.isTimeoutError(execError)) {
+                outcome = 'timeout';
+            }
+            else {
+                outcome = 'failure';
+            }
+            if (spawned) {
+                // Wrapped in `safeMetric` so a metric-layer exception cannot
+                // re-throw from the catch branch (which would short-circuit
+                // the streaming event emission and the final failure-response
+                // construction below). Parity with debate's safeMetric pattern
+                // (Cycle 3 Task CLI-B').
+                const failureLabels = {
+                    provider,
+                    outcome,
+                };
+                safeMetric(this.emitLog(), `cliSpawnTotal.inc(${outcome})`, () => {
+                    this.metrics?.cliSpawnTotal.inc(failureLabels, 1);
+                });
+            }
             if (isRateLimit) {
-                logger.warn(`⏱️ ${cliName.toUpperCase()} CLI hit rate/usage limit (${Date.now() - startTime}ms)`);
+                this.emitLog().warn(`⏱️ ${cliName.toUpperCase()} CLI hit rate/usage limit (${Date.now() - startTime}ms)`);
             }
             else {
-                logger.error(`❌ ${cliName.toUpperCase()} execution failed (${Date.now() - startTime}ms)`, {
+                this.emitLog().error(`❌ ${cliName.toUpperCase()} execution failed (${Date.now() - startTime}ms)`, {
                     error: "Redacted: See internal logs for full error details.",
                     exitCode,
                     stderr: "Redacted: See internal logs for full stderr output."
                 });
             }
+            // Cycle 3 Task D' (security): `errorMsg` is used both as streaming
+            // event content (just below) and as `result.error` in the returned
+            // CLIAgentResponse. Raw `error.message` from spawnAsync /
+            // downstream CLIs can contain CLI stdout/stderr fragments (TOML
+            // MCP override content, prompt echoes, tool-output snippets) that
+            // must not leak via streaming fan-out or the MCP response payload.
+            // We apply the same static-redaction pattern used by the logger
+            // emission at the `❌ ... execution failed` call above: map each
+            // classification path to a short, content-free string. The
+            // timeout branch preserves the millisecond budget (from our own
+            // `timeout` variable, not the underlying error) so downstream
+            // callers can still distinguish timeout from generic failure.
             const errorMsg = isRateLimit
                 ? `${cliName.toUpperCase()} hit rate/usage limit. Try again later or use a different agent.`
-                : (error instanceof Error ? error.message : String(error));
-            // Emit error event
+                : this.isTimeoutError(execError)
+                    ? `${cliName.toUpperCase()} execution timed out after ${timeout}ms. See internal logs for details.`
+                    : `${cliName.toUpperCase()} execution failed. See internal logs for details.`;
+            // Emit error event. The content derives from the redacted
+            // `errorMsg` above, never from `error.message` directly, so
+            // streaming observers (HTTP SSE, MCP notifications) do not
+            // receive raw CLI payload fragments.
             if (options.onStreamingEvent) {
                 options.onStreamingEvent({
                     type: 'agent_error',
@@ -1070,6 +966,8 @@ export class CLIAgentOrchestrator {
             }
         }
     }
+    // Per-provider execution methods — thin wrappers via adapter dispatch.
+    // Retained for backward compatibility (tests may reference these).
     async executeClaudeCode(userPrompt, systemPromptSpec, options = {}) {
         return this._executeCLI('claude', userPrompt, systemPromptSpec, options, (user, sys, opts) => this.buildCLICommand('claude', user, sys, opts));
     }
@@ -1083,28 +981,77 @@ export class CLIAgentOrchestrator {
         // Wait for available slot to prevent resource exhaustion
         await this.waitForAvailableSlot();
         this.runningCLIs++;
-        logger.info(`🎯 Executing ${cli} (${this.runningCLIs}/${this.MAX_CONCURRENT_CLIS} slots used)`);
+        this.emitLog().info(`\u{1F3AF} Executing ${cli} (${this.runningCLIs}/${this.MAX_CONCURRENT_CLIS} slots used)`);
         try {
-            switch (cli) {
-                case 'claude':
-                    return await this.executeClaudeCode(userPrompt, systemPromptSpec, options);
-                case 'codex':
-                    return await this.executeCodex(userPrompt, systemPromptSpec, options);
-                case 'gemini':
-                    return await this.executeGemini(userPrompt, systemPromptSpec, options);
-                default:
-                    throw new Error(`Unknown CLI: ${cli}`);
+            // Gemini frontier rotation: when using the default frontier chain (no
+            // caller-specified model, no env-var override), rotate through the
+            // chain on saturation failures. Rotation is disabled when the caller
+            // or operator has explicitly chosen a model.
+            const geminiRotationActive = cli === 'gemini'
+                && !options.models?.gemini
+                && !process.env.BRUTALIST_GEMINI_MODEL;
+            if (geminiRotationActive) {
+                return await this._executeGeminiWithRotation(userPrompt, systemPromptSpec, options);
             }
+            // Dispatch to adapter via buildCLICommand (which delegates to provider)
+            return await this._executeCLI(cli, userPrompt, systemPromptSpec, options, (user, sys, opts) => this.buildCLICommand(cli, user, sys, opts));
         }
         finally {
             this.runningCLIs--;
-            logger.info(`✅ Released CLI slot (${this.runningCLIs}/${this.MAX_CONCURRENT_CLIS} slots used)`);
+            this.emitLog().info(`\u2705 Released CLI slot (${this.runningCLIs}/${this.MAX_CONCURRENT_CLIS} slots used)`);
+        }
+    }
+    /**
+     * Gemini frontier rotation - iterate through GEMINI_FRONTIER_CHAIN on
+     * saturation failures.
+     *
+     * Only active when neither caller nor operator has chosen a model. Each
+     * attempt injects the model via options.models.gemini. Per-attempt
+     * saturation is detected via the existing quota-pattern detection in
+     * _executeCLI - saturation produces success=false with an error matching
+     * /\b429\b/ or quota-family patterns. On non-saturation failure,
+     * rotation stops immediately (a different model will not fix prompt
+     * errors, subprocess crashes, or auth failures). On chain exhaustion,
+     * the last failing response is returned.
+     */
+    async _executeGeminiWithRotation(userPrompt, systemPromptSpec, options) {
+        const chain = GEMINI_FRONTIER_CHAIN;
+        let lastResponse = null;
+        for (let i = 0; i < chain.length; i++) {
+            const model = chain[i];
+            const attemptOptions = {
+                ...options,
+                models: { ...(options.models || {}), gemini: model },
+            };
+            if (i > 0) {
+                this.emitLog().info(`Gemini rotation: attempting tier ${i + 1}/${chain.length} (${model})`);
+            }
+            const response = await this._executeCLI('gemini', userPrompt, systemPromptSpec, attemptOptions, (user, sys, opts) => this.buildCLICommand('gemini', user, sys, opts));
+            if (response.success) {
+                if (i > 0) {
+                    this.emitLog().warn(`Gemini served by ${model} after ${i} rotation${i === 1 ? '' : 's'} (tier ${i + 1}/${chain.length})`);
+                }
+                else {
+                    this.emitLog().debug(`Gemini served by frontier ${model}`);
+                }
+                return response;
+            }
+            if (!isGeminiSaturationError(response.error)) {
+                this.emitLog().debug(`Gemini ${model} failed non-saturation; rotation aborted`, {
+                    errorPreview: response.error?.slice(0, 120),
+                });
+                return response;
+            }
+            this.emitLog().warn(`Gemini ${model} saturated; rotating to next frontier tier`);
+            lastResponse = response;
         }
+        this.emitLog().error(`Gemini frontier chain exhausted (${chain.length} tiers); all saturated`);
+        return lastResponse;
     }
     async waitForAvailableSlot() {
         let waitTime = 100; // Start with 100ms wait time
         while (this.runningCLIs >= this.MAX_CONCURRENT_CLIS) {
-            logger.info(`⏳ Waiting for available CLI slot (${this.runningCLIs}/${this.MAX_CONCURRENT_CLIS} in use). Next check in ${waitTime}ms...`);
+            this.emitLog().info(`⏳ Waiting for available CLI slot (${this.runningCLIs}/${this.MAX_CONCURRENT_CLIS} in use). Next check in ${waitTime}ms...`);
             await new Promise(resolve => setTimeout(resolve, waitTime));
             waitTime = Math.min(waitTime * 2, 5000); // Exponential backoff, max 5 seconds
         }
@@ -1148,15 +1095,15 @@ export class CLIAgentOrchestrator {
         // Only validate filesystem paths for tools that actually operate on files/directories
         // NOTE: Must match BrutalistPromptType values (camelCase)
         const filesystemTools = ['codebase', 'fileStructure', 'dependencies', 'gitHistory', 'testCoverage'];
-        logger.debug(`Validation check: analysisType="${analysisType}", isFilesystemTool=${filesystemTools.includes(analysisType)}`);
+        this.emitLog().debug(`Validation check: analysisType="${analysisType}", isFilesystemTool=${filesystemTools.includes(analysisType)}`);
         try {
             if (filesystemTools.includes(analysisType) && primaryContent && primaryContent.trim() !== '') {
-                logger.debug(`Validating path: "${primaryContent}"`);
+                this.emitLog().debug(`Validating path: "${primaryContent}"`);
                 await asyncValidatePath(primaryContent, 'targetPath');
             }
         }
         catch (error) {
-            logger.error(`Path validation failed: ${error}`);
+            this.emitLog().error(`Path validation failed: ${error}`);
             throw new Error(`Security validation failed: ${error instanceof Error ? error.message : String(error)}`);
         }
         // Validate workingDirectory if provided
@@ -1180,18 +1127,18 @@ export class CLIAgentOrchestrator {
             }
             // Deduplicate
             clisToUse = [...new Set(options.clis)];
-            logger.info(`🎯 Using user-specified CLIs: ${clisToUse.join(', ')}`);
+            this.emitLog().info(`🎯 Using user-specified CLIs: ${clisToUse.join(', ')}`);
         }
         else {
             // Default: use all available CLIs
             clisToUse = [...this.cliContext.availableCLIs];
-            logger.info(`📋 Using all available CLIs: ${clisToUse.join(', ')}`);
+            this.emitLog().info(`📋 Using all available CLIs: ${clisToUse.join(', ')}`);
         }
         if (clisToUse.length === 0) {
             throw new Error('No CLI agents available for analysis');
         }
         const selectionMethod = options.clis ? 'user-specified' : 'all-available';
-        logger.info(`📊 Executing ${clisToUse.length} CLI(s): ${clisToUse.join(', ')} (${selectionMethod})`);
+        this.emitLog().info(`📊 Executing ${clisToUse.length} CLI(s): ${clisToUse.join(', ')} (${selectionMethod})`);
         // Execute selected CLIs in parallel with allSettled for better error handling
         const promises = clisToUse.map(async (cli) => {
             try {
@@ -1203,7 +1150,7 @@ export class CLIAgentOrchestrator {
                 };
             }
             catch (error) {
-                logger.error(`❌ ${cli} execution failed:`, error);
+                this.emitLog().error(`❌ ${cli} execution failed:`, error);
                 return {
                     agent: cli,
                     success: false,
@@ -1220,7 +1167,7 @@ export class CLIAgentOrchestrator {
         const responses = results
             .filter(result => result.status === 'fulfilled')
             .map(result => result.value);
-        logger.info(`✅ CLI analysis complete: ${responses.filter(r => r.success).length}/${responses.length} successful`);
+        this.emitLog().info(`✅ CLI analysis complete: ${responses.filter(r => r.success).length}/${responses.length} successful`);
         return responses;
     }
     synthesizeBrutalistFeedback(responses, analysisType) {