overmind-mcp 2.5.0 → 2.6.0

package/dist/services/ClaudeRunner.js

@@ -1,108 +1,202 @@
 import fs from 'fs';
-import os from 'os';
 import path from 'path';
-import { spawn } from 'child_process';
-import { CONFIG, resolveConfigPath } from '../lib/config.js';
+import { fileURLToPath } from 'url';
+import { spawn, exec, execSync } from 'child_process';
+import { CONFIG, resolveConfigPath, getWorkspaceDir } from '../lib/config.js';
 import { getLastSessionId, saveSessionId } from '../lib/sessions.js';
-import { registerProcess, appendOutput, updateProcessStatus, linkSessionToPid } from '../lib/processRegistry.js';
+import { interpolateEnvVars } from '../lib/envUtils.js';
+import { resolveModel } from '../lib/modelMapping.js';
+import { withSpan } from '../lib/telemetry.js';
+import { loadEnvQuietly } from '../lib/loadEnv.js';
+import { registerProcess, linkSessionToPid, appendOutput, updateProcessStatus, } from '../lib/processRegistry.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Sur Windows, `child.kill()` ne tue que cmd.exe (le wrapper) — claude.exe
+// devient orphelin et garde la session bound au token initial côté provider.
+// On utilise `taskkill /F /T /PID` pour propager le kill au sous-arbre,
+// puis on attend l'event 'exit' avant de respawn.
 /**
- * Interpole les variables d'environnement dans les valeurs de type $VAR
- * Ex: "$ANTHROPIC_MODEL_Z" → process.env.ANTHROPIC_MODEL_Z
+ * On Windows, `claude` on PATH is a `.cmd` shim. cmd.exe-based shims don't
+ * reliably forward inherited file FDs to their child `.exe` when the whole
+ * thing is spawned `detached`, which leaves the log file empty. To dodge that,
+ * the detached path needs to invoke `claude.exe` directly.
+ *
+ * Returns null if we cannot locate the .exe — caller falls back to cmd.exe.
  */
-function interpolateEnvVars(obj) {
-    const result = {};
-    console.error(`[ClaudeRunner] 🔧 Interpolating ${Object.keys(obj).length} env variables...`);
-    for (const [key, value] of Object.entries(obj)) {
-        if (typeof value === 'string' && value.startsWith('$')) {
-            const varName = value.substring(1); // Enlever le $
-            const envValue = process.env[varName];
-            if (envValue !== undefined) {
-                result[key] = envValue;
-                console.error(`[ClaudeRunner] ✅ ${key} = $${varName} → "${envValue}"`);
-            }
-            else {
-                console.error(`[ClaudeRunner] ⚠️  Variable $${varName} non trouvée, garde la valeur littérale: ${value}`);
-                result[key] = value;
-            }
+let cachedClaudeExe;
+function resolveClaudeExePath() {
+    if (cachedClaudeExe !== undefined)
+        return cachedClaudeExe;
+    try {
+        const out = execSync('where claude.exe', {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const found = out.split(/\r?\n/).map((l) => l.trim()).find((l) => l.toLowerCase().endsWith('.exe'));
+        if (found && fs.existsSync(found)) {
+            cachedClaudeExe = found;
+            return found;
         }
-        else {
-            result[key] = value;
-            console.error(`[ClaudeRunner] 📋 ${key} = "${value}" (pas d'interpolation nécessaire)`);
+    }
+    catch {
+        // `where` may not be on PATH (extremely unusual) — fall through.
+    }
+    try {
+        // Fallback: derive from `claude.cmd` location → npm prefix → node_modules path.
+        const cmdOut = execSync('where claude', {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const cmdPath = cmdOut.split(/\r?\n/).map((l) => l.trim()).find((l) => l.toLowerCase().endsWith('.cmd'));
+        if (cmdPath) {
+            const npmPrefix = path.dirname(cmdPath);
+            const exePath = path.join(npmPrefix, 'node_modules', '@anthropic-ai', 'claude-code', 'bin', 'claude.exe');
+            if (fs.existsSync(exePath)) {
+                cachedClaudeExe = exePath;
+                return exePath;
+            }
         }
     }
-    return result;
+    catch {
+        // ignored
+    }
+    cachedClaudeExe = null;
+    return null;
 }
+const killProcessTree = (child) => {
+    return new Promise((resolve) => {
+        if (!child || child.exitCode !== null || child.killed) {
+            resolve();
+            return;
+        }
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve();
+        };
+        child.once('exit', finish);
+        if (process.platform === 'win32' && child.pid) {
+            exec(`taskkill /F /T /PID ${child.pid}`, () => {
+                // taskkill peut échouer si le process est déjà mort — on s'appuie sur 'exit'
+            });
+        }
+        else {
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+                // Ignored
+            }
+            setTimeout(() => {
+                if (child.exitCode === null && !child.killed) {
+                    try {
+                        child.kill('SIGKILL');
+                    }
+                    catch {
+                        // Ignored
+                    }
+                }
+            }, 2000);
+        }
+        // Filet de sécurité : si 'exit' ne se déclenche pas (process zombie),
+        // on débloque le respawn après 5s plutôt que de bloquer indéfiniment.
+        setTimeout(finish, 5000);
+    });
+};
 export class ClaudeRunner {
     config;
     timeoutMs;
     constructor() {
         this.config = CONFIG.CLAUDE;
-        this.timeoutMs = CONFIG.TIMEOUT_MS || 120000;
+        this.timeoutMs = CONFIG.TIMEOUT_MS || 900000;
     }
     async runAgent(options) {
         const { prompt, agentName, autoResume } = options;
         let { sessionId } = options;
         const { CORE, PERMISSIONS, PATHS } = this.config;
         const agentCustomEnv = {};
+        // Load environment variables FIRST before any processing
+        const workspaceEnvPath = path.resolve(options.configPath || getWorkspaceDir(), '.env');
+        loadEnvQuietly(workspaceEnvPath);
+        // Also load from Workflow directory as fallback
+        const workflowEnvPath = path.resolve(__dirname, '../../.env');
+        loadEnvQuietly(workflowEnvPath);
+        // Debug: check if variables are loaded
+        if (!options.silent) {
+            console.error(`[ClaudeRunner] Env check - ANTHROPIC_MODEL_Z present: ${!!process.env.ANTHROPIC_MODEL_Z}`);
+            console.error(`[ClaudeRunner] Auth tokens present: ${!!process.env.ANTHROPIC_AUTH_TOKEN_Y || !!process.env.ANTHROPIC_AUTH_TOKEN_E}`);
+            console.error(`[ClaudeRunner] workspaceEnvPath: ${workspaceEnvPath}`);
+            console.error(`[ClaudeRunner] workflowEnvPath: ${workflowEnvPath}`);
+        }
+        if (agentName) {
+            agentCustomEnv.OVERMIND_AGENT_NAME = agentName;
+        }
         // --- Auto Resume ---
         if (autoResume && agentName && !sessionId) {
-            const lastId = await getLastSessionId(agentName);
+            const lastId = await getLastSessionId(agentName, options.configPath, 'claude');
             if (lastId) {
                 sessionId = lastId;
+                if (!options.silent) {
+                    console.log(`[ClaudeRunner] Auto-resume session: ${sessionId}`);
+                }
             }
         }
-        let settingsPath = resolveConfigPath(PATHS.SETTINGS);
+        let settingsPath = resolveConfigPath(PATHS.SETTINGS, options.configPath);
         if (agentName) {
             const settingsDir = path.dirname(PATHS.SETTINGS);
-            const specificSettingsPath = resolveConfigPath(path.join(settingsDir, `settings_${agentName}.json`));
+            const specificSettingsPath = resolveConfigPath(path.join(settingsDir, `settings_${agentName}.json`), options.configPath);
             if (!fs.existsSync(specificSettingsPath)) {
                 return {
                     result: '',
-                    error: `INVALID_AGENT`,
+                    error: `INVALID_AGENT: Agent "${agentName}" non trouvé.`,
                 };
             }
             settingsPath = specificSettingsPath;
         }
-        const cwd = process.cwd();
-        const relativeSettings = path.relative(cwd, settingsPath);
-        if (!relativeSettings.startsWith('..') && !path.isAbsolute(relativeSettings)) {
-            settingsPath = relativeSettings.startsWith('./') ? relativeSettings : `./${relativeSettings}`;
-        }
-        let mcpPath = resolveConfigPath(PATHS.MCP);
+        let mcpPath = resolveConfigPath(PATHS.MCP, options.configPath);
         let tmpMcpPathToDelete = null;
+        let tmpSettingsPathToDelete = null;
         let customTimeoutMs = this.timeoutMs;
-        // --- Isolation ---
         if (agentName) {
             try {
-                const agentSettingsPath = resolveConfigPath(path.join(path.dirname(PATHS.SETTINGS), `settings_${agentName}.json`));
+                const agentSettingsPath = resolveConfigPath(path.join(path.dirname(PATHS.SETTINGS), `settings_${agentName}.json`), options.configPath);
                 if (fs.existsSync(agentSettingsPath)) {
-                    const settings = JSON.parse(fs.readFileSync(agentSettingsPath, 'utf8'));
+                    let settings = JSON.parse(fs.readFileSync(agentSettingsPath, 'utf8'));
+                    // Debug: log environment variables
+                    if (!options.silent) {
+                        console.error(`[ClaudeRunner] ANTHROPIC_MODEL_Z present: ${!!process.env.ANTHROPIC_MODEL_Z}`);
+                        console.error(`[ClaudeRunner] Auth tokens present: ${!!process.env.ANTHROPIC_AUTH_TOKEN_Y || !!process.env.ANTHROPIC_AUTH_TOKEN_E}`);
+                        console.error(`[ClaudeRunner] ANTHROPIC_BASE_URL_Z present: ${!!process.env.ANTHROPIC_BASE_URL_Z}`);
+                    }
+                    // --- New interpolation logic ---
+                    settings = interpolateEnvVars(settings);
+                    // Debug: log interpolated values
+                    if (!options.silent) {
+                        console.error(`[ClaudeRunner] Interpolated ANTHROPIC_MODEL = ${settings.env?.ANTHROPIC_MODEL}`);
+                        console.error(`[ClaudeRunner] Interpolated ANTHROPIC_BASE_URL = ${settings.env?.ANTHROPIC_BASE_URL}`);
+                    }
+                    // 1. Create a temporary settings file with interpolated values
+                    const tmpSettingsPath = path.join(path.dirname(agentSettingsPath), `settings_${agentName}_tmp.json`);
+                    fs.writeFileSync(tmpSettingsPath, JSON.stringify(settings, null, 2));
+                    settingsPath = tmpSettingsPath;
+                    tmpSettingsPathToDelete = tmpSettingsPath;
                     if (settings.env) {
-                        // Mémoriser l'env configuré pour l'injection
-                        const interpolatedEnv = interpolateEnvVars(settings.env);
-                        Object.assign(agentCustomEnv, interpolatedEnv);
-                        // --- SMART NICKNAME FALLBACK ---
-                        const currentModel = settings.env.ANTHROPIC_MODEL;
-                        const isTechnicalModelId = currentModel && (currentModel.includes('claude') ||
-                            currentModel.includes('gpt') ||
-                            currentModel.includes('glm') ||
-                            currentModel.includes('minimax') ||
-                            currentModel.includes('deepseek') ||
-                            currentModel.includes('moonshot'));
-                        if (currentModel && !isTechnicalModelId) {
-                            // Si le modèle est un surnom, on l'utilise pour l'affichage mais on remet un vrai ID de modèle pour l'API
-                            agentCustomEnv.AGENT_NICKNAME = currentModel;
-                            // On utilise le modèle Sonnet par défaut ou la valeur configurée si elle semble valide
-                            agentCustomEnv.ANTHROPIC_MODEL = (settings.env.ANTHROPIC_DEFAULT_SONNET_MODEL && settings.env.ANTHROPIC_DEFAULT_SONNET_MODEL.includes('claude'))
-                                ? settings.env.ANTHROPIC_DEFAULT_SONNET_MODEL
-                                : 'claude-3-5-sonnet-20241022';
-                        }
+                        Object.assign(agentCustomEnv, settings.env);
                         if (settings.env.AGENT_TIMEOUT_MS || settings.env.API_TIMEOUT_MS) {
                             const timeoutValue = settings.env.AGENT_TIMEOUT_MS || settings.env.API_TIMEOUT_MS;
                             customTimeoutMs = parseInt(timeoutValue, 10) || customTimeoutMs;
                         }
+                        if (!options.model && settings.env.MODEL) {
+                            agentCustomEnv.ANTHROPIC_MODEL = settings.env.MODEL;
+                        }
+                    }
+                    const agentMcpPath = resolveConfigPath(path.join(path.dirname(PATHS.SETTINGS), `.mcp.${agentName}.json`));
+                    if (fs.existsSync(agentMcpPath)) {
+                        mcpPath = agentMcpPath;
                     }
-                    if (settings.enableAllProjectMcpServers === false &&
+                    else if (settings.enableAllProjectMcpServers === false &&
                         Array.isArray(settings.enabledMcpjsonServers)) {
                         if (fs.existsSync(mcpPath)) {
                             const fullMcp = JSON.parse(fs.readFileSync(mcpPath, 'utf8'));
@@ -120,40 +214,8 @@ export class ClaudeRunner {
                     }
                 }
             }
-            catch (_e) {
-                // Warning
-            }
-        }
-        const relativeMcp = path.relative(cwd, mcpPath);
-        if (!relativeMcp.startsWith('..') && !path.isAbsolute(relativeMcp)) {
-            mcpPath = relativeMcp.startsWith('./') ? relativeMcp : `./${relativeMcp}`;
-        }
-        let tmpSettingsPathToDelete = null;
-        let finalSettingsPath = settingsPath;
-        if (agentCustomEnv.AGENT_NICKNAME) {
-            try {
-                // On crée un fichier settings temporaire pour substituer le surnom par un vrai modèle
-                // car le CLI Claude ne valide pas les surnoms dynamiques en interne
-                const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
-                const tempSettings = JSON.parse(JSON.stringify(settings));
-                // IMPORTANT: Mettre à jour toutes les variables env avec les valeurs interpolées
-                // pour éviter que le CLI Claude ne reçoive les valeurs $VAR littérales
-                if (tempSettings.env) {
-                    for (const [key, value] of Object.entries(agentCustomEnv)) {
-                        if (key !== 'AGENT_NICKNAME' && key !== 'AGENT_TIMEOUT_MS' && key !== 'API_TIMEOUT_MS') {
-                            tempSettings.env[key] = value;
-                        }
-                    }
-                }
-                tempSettings.env.ANTHROPIC_MODEL = agentCustomEnv.ANTHROPIC_MODEL;
-                const tmpSettingsPath = path.join(os.tmpdir(), `settings-${agentName || 'agent'}-${Date.now()}.json`);
-                fs.writeFileSync(tmpSettingsPath, JSON.stringify(tempSettings, null, 2));
-                finalSettingsPath = tmpSettingsPath;
-                tmpSettingsPathToDelete = tmpSettingsPath;
-                console.error(`[ClaudeRunner] 📝 Settings temporaire créé avec variables interpolées`);
-            }
             catch (e) {
-                console.error(`[ClaudeRunner] ⚠️ Erreur lors de la création du settings temporaire: ${e}`);
+                console.error(`[ClaudeRunner] [WARN] Error processing agent settings: ${e}`);
             }
         }
         const argsSpawn = [];
@@ -161,215 +223,507 @@ export class ClaudeRunner {
             argsSpawn.push(...CORE.split(' ').filter(Boolean));
         if (PERMISSIONS)
             argsSpawn.push(...PERMISSIONS.split(' ').filter(Boolean));
-        // DÉCISION IMPORTANTE: On n'ajoute pas de guillemets manuels ici, spawn s'en occupe
-        argsSpawn.push('--settings', finalSettingsPath);
+        argsSpawn.push('--settings', settingsPath);
         argsSpawn.push('--mcp-config', mcpPath);
-        if (sessionId) {
-            argsSpawn.push('--resume', sessionId);
+        argsSpawn.push('--output-format', 'json');
+        let modelUsed = options.model;
+        if (!modelUsed && agentCustomEnv.ANTHROPIC_MODEL) {
+            modelUsed = agentCustomEnv.ANTHROPIC_MODEL;
         }
-        // --- MODEL & NICKNAME FLAGS ---
-        const modelToUse = agentCustomEnv.ANTHROPIC_MODEL || 'claude-3-5-sonnet-20241022';
-        console.error(`[ClaudeRunner] 🛠️  Model override: ${modelToUse}`);
-        argsSpawn.push('--model', modelToUse);
-        if (agentCustomEnv.AGENT_NICKNAME) {
-            console.error(`[ClaudeRunner] 👤 Nickname: ${agentCustomEnv.AGENT_NICKNAME}`);
-            argsSpawn.push('--name', agentCustomEnv.AGENT_NICKNAME);
+        // Remember original value (nickname or raw model) for display
+        const originalModel = modelUsed ?? '';
+        // Resolve nickname → real model ID before calling the API
+        if (modelUsed) {
+            modelUsed = resolveModel(modelUsed);
         }
-        else if (agentName) {
+        if (sessionId)
+            argsSpawn.push('--resume', sessionId);
+        if (modelUsed)
+            argsSpawn.push('--model', modelUsed);
+        if (agentName)
             argsSpawn.push('--name', agentName);
-        }
-        return new Promise((resolve) => {
-            const cleanupTmpFiles = () => {
-                if (tmpMcpPathToDelete && fs.existsSync(tmpMcpPathToDelete)) {
-                    try {
-                        fs.unlinkSync(tmpMcpPathToDelete);
-                    }
-                    catch (_e) { /* intentionally empty */ }
-                }
-                if (tmpSettingsPathToDelete && fs.existsSync(tmpSettingsPathToDelete)) {
-                    try {
-                        fs.unlinkSync(tmpSettingsPathToDelete);
-                    }
-                    catch (_e) { /* intentionally empty */ }
-                }
-            };
-            const isWin = process.platform === 'win32';
-            let command = 'claude';
-            let spawnArgs;
-            // Prepend persona if defined
-            let finalPrompt = prompt;
-            if (agentName) {
-                let agentPromptPath = resolveConfigPath(path.join(path.dirname(PATHS.SETTINGS), 'agents', `${agentName}.md`));
-                if (!fs.existsSync(agentPromptPath)) {
-                    // Fallback: Check agents/ folder at the root level of settingsDir
-                    agentPromptPath = resolveConfigPath(path.join(path.dirname(path.dirname(PATHS.SETTINGS)), 'agents', `${agentName}.md`));
-                }
-                if (fs.existsSync(agentPromptPath)) {
-                    const systemPrompt = fs.readFileSync(agentPromptPath, 'utf8');
-                    finalPrompt = `${systemPrompt}\n\n[USER QUERY]:\n${prompt}`;
+        // ───────────────────────────────────────────────────────────────────────────
+        // 🔄 FALLBACK TOKEN RETRY LOGIC
+        //
+        // Overmind lit les tokens fallback depuis agentCustomEnv (résolus depuis $VAR).
+        // Si une erreur 401 (auth) survient, on tente chaque fallback séquentiellement :
+        //   AUTH_FALLBACK_1 → AUTH_FALLBACK_2 → AUTH_FALLBACK_3
+        //
+        // Settings exemple :
+        //   { "env": { "ANTHROPIC_AUTH_TOKEN": "$ANTHROPIC_AUTH_FALLBACK_1" } }
+        // ───────────────────────────────────────────────────────────────────────────
+        const FALLBACK_KEYS = ['AUTH_FALLBACK_1', 'AUTH_FALLBACK_2', 'AUTH_FALLBACK_3'];
+        const TOKEN_KEYS = ['ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_AUTH_TOKEN_E'];
+        /**
+         * Vérifie si une erreur est retryable (fallback recommended).
+         * 401 = auth error (token invalide/expiré)
+         * 429 = rate limit / quota exhausted
+         * 500/502/503 = server error
+         */
+        const isRetryableError = (stderr, jsonEnv) => {
+            const lower = stderr.toLowerCase();
+            const status = jsonEnv?.api_error_status;
+            if (status === 401)
+                return true;
+            if (status === 429)
+                return true;
+            if (status === 500 || status === 502 || status === 503)
+                return true;
+            return (lower.includes('401') ||
+                lower.includes('unauthorized') ||
+                lower.includes('invalid api key') ||
+                lower.includes('api key invalid') ||
+                lower.includes('authentication failed') ||
+                lower.includes('auth error') ||
+                lower.includes('invalid authentication') ||
+                lower.includes('429') ||
+                lower.includes('rate limit') ||
+                lower.includes('quota exhausted') ||
+                lower.includes('limit exhausted') ||
+                lower.includes('503') ||
+                lower.includes('service unavailable') ||
+                lower.includes('500') ||
+                lower.includes('internal server error'));
+        };
+        /**
+         * Extrait les tokens fallback disponibles depuis agentCustomEnv.
+         * Retourne un tableau de { key, value } pour chaque fallback non vide.
+         */
+        const getAvailableFallbacks = () => {
+            const fallbacks = [];
+            for (const key of FALLBACK_KEYS) {
+                const val = agentCustomEnv[key];
+                if (val && typeof val === 'string' && val.length > 0) {
+                    fallbacks.push({ key, value: val });
                 }
             }
-            if (isWin) {
-                // Spawn claude.exe directly to bypass PowerShell/cmd argument
-                // re-tokenization that mangles multi-line prompts containing patterns
-                // like "0-100" into a stray "-100" flag.
-                const claudeExe = 'C:\\Users\\Deamon\\AppData\\Roaming\\npm\\node_modules\\@anthropic-ai\\claude-code\\bin\\claude.exe';
-                if (fs.existsSync(claudeExe)) {
-                    command = claudeExe;
-                    spawnArgs = [...argsSpawn, '-p', finalPrompt];
-                }
-                else {
-                    // Fallback: powershell wrapper (may mishandle multi-line prompts).
-                    const claudePath = 'C:\\Users\\Deamon\\AppData\\Roaming\\npm\\claude.ps1';
-                    if (fs.existsSync(claudePath)) {
-                        command = 'powershell.exe';
-                        spawnArgs = [
-                            '-NoProfile',
-                            '-ExecutionPolicy',
-                            'Bypass',
-                            '-File',
-                            claudePath,
-                            ...argsSpawn,
-                            '-p',
-                            finalPrompt,
-                        ];
-                    }
-                    else {
-                        command = 'cmd.exe';
-                        spawnArgs = ['/c', 'claude', ...argsSpawn, '-p', finalPrompt];
+            return fallbacks;
+        };
+        /**
+         * Détermine quel token utiliser selon l'index de retry.
+         * - index 0 = tentative initiale → use primary token (ANTHROPIC_AUTH_TOKEN)
+         * - index 1+ = retry → skip primary, use fallbacks directly
+         */
+        const getTokenForIndex = (index) => {
+            if (index === 0) {
+                // Tentative initiale : utiliser le primary token
+                // NOTE: si la valeur est un $VAR non résolu (interpolateEnvVars n'a pas trouvé
+                // la variable dans process.env à ce moment), on le passe quand même à spawnWithToken
+                // qui fera la résolution finale via process.env.
+                for (const tk of TOKEN_KEYS) {
+                    const val = agentCustomEnv[tk];
+                    if (val && typeof val === 'string' && val.length > 0) {
+                        return { tokenEnvKey: tk, tokenValue: val };
                     }
                 }
+                // Aucun primary token trouvé — retourner null plutôt que de tomber dans les fallbacks
+                return null;
             }
-            else {
-                spawnArgs = [...argsSpawn, '-p', finalPrompt];
+            // Retry (index >= 1) : skip primary, use fallbacks directly
+            const fallbacks = getAvailableFallbacks();
+            const fallbackIndex = index - 1; // index 1 → fallback[0] (AUTH_FALLBACK_1)
+            if (fallbackIndex < fallbacks.length) {
+                return { tokenEnvKey: fallbacks[fallbackIndex].key, tokenValue: fallbacks[fallbackIndex].value };
             }
-            if (agentName) {
-                const id = agentCustomEnv.AGENT_NICKNAME || agentName;
-                console.error(`[ClaudeRunner] 🚀 Démarrage de l'agent ${id}...`);
-                // Debug: Log the prompt size
-                console.error(`[ClaudeRunner] 📏 Prompt Size: ${finalPrompt.length} chars`);
+            return null;
+        };
+        // ─── AbortSignal support ─────────────────────────────────────────────────────
+        let currentChildRef = null;
+        if (options.signal?.aborted) {
+            return Promise.reject(new Error('ABORTED'));
+        }
+        options.signal?.addEventListener('abort', () => {
+            if (currentChildRef)
+                void killProcessTree(currentChildRef);
+        });
+        // ─── DETACHED FAST-PATH ─────────────────────────────────────────────────────
+        // Fire-and-forget: parent returns immediately after spawn. Monitoring is done
+        // via the process registry + agent_control. No token retry, no in-process
+        // output capture — stdio is redirected to a log file the child writes to
+        // directly, so output keeps flowing even if our MCP server exits.
+        if (options.detached) {
+            const tokenInfo = getTokenForIndex(0);
+            const spawnEnv = {
+                ...process.env,
+                ...agentCustomEnv,
+            };
+            if (tokenInfo) {
+                for (const tk of TOKEN_KEYS)
+                    delete spawnEnv[tk];
+                let resolvedToken = tokenInfo.tokenValue;
+                if (resolvedToken.startsWith('$')) {
+                    resolvedToken = process.env[resolvedToken.slice(1)] || resolvedToken;
+                }
+                spawnEnv['ANTHROPIC_AUTH_TOKEN'] = resolvedToken;
             }
-            const child = spawn(command, spawnArgs, {
-                stdio: ['ignore', 'pipe', 'pipe'],
-                cwd: process.cwd(),
-                // shell: false explicitly (handled by command selection)
+            const logDir = path.resolve(options.configPath || getWorkspaceDir(), '.claude/agent_logs');
+            fs.mkdirSync(logDir, { recursive: true });
+            const stamp = `${Date.now()}`;
+            const logFile = path.join(logDir, `${agentName || 'agent'}_${stamp}.log`);
+            const promptFile = path.join(logDir, `${agentName || 'agent'}_${stamp}.prompt`);
+            fs.writeFileSync(promptFile, prompt, 'utf-8');
+            // On Windows the `claude` shim is a .cmd file. Inherited file FDs survive
+            // a direct .exe spawn fine, but cmd.exe (in detached mode) silently drops
+            // them before they reach claude.cmd → log file ends up empty. We resolve
+            // `claude.exe` directly to skip the shim entirely. On Unix we just call
+            // `claude` (a real executable on PATH).
+            const promptFd = fs.openSync(promptFile, 'r');
+            const logFd = fs.openSync(logFile, 'a');
+            const claudeExe = process.platform === 'win32' ? resolveClaudeExePath() : null;
+            const detachedCommand = claudeExe ?? 'claude';
+            const detachedArgs = [...argsSpawn, '-p'];
+            const child = spawn(detachedCommand, detachedArgs, {
+                cwd: options.cwd || process.cwd(),
                 windowsHide: true,
-                env: {
-                    ...process.env,
-                    ...agentCustomEnv,
-                    // Compatibilité Anthropic/Z.ai pour Claude Code standard
-                    ...(agentCustomEnv.ANTHROPIC_AUTH_TOKEN && !agentCustomEnv.ANTHROPIC_API_KEY
-                        ? { ANTHROPIC_API_KEY: agentCustomEnv.ANTHROPIC_AUTH_TOKEN }
-                        : {}),
-                    ...(agentName ? { OVERMIND_AGENT_NAME: agentName } : {}),
-                },
+                env: spawnEnv,
+                shell: false,
+                detached: true,
+                stdio: [promptFd, logFd, logFd],
             });
-            // Register this process in the registry for agent_control visibility
-            if (child.pid) {
-                registerProcess(child.pid, {
-                    agentName: agentName || 'unknown',
-                    runner: 'claude',
-                }).catch(() => { });
+            try {
+                fs.closeSync(promptFd);
             }
-            let stdout = '';
-            let stderr = '';
-            if (child.stdout) {
-                child.stdout.on('data', (d) => {
-                    const chunk = d.toString();
-                    stdout += chunk;
-                    if (agentName) {
-                        const id = agentCustomEnv.AGENT_NICKNAME || agentName;
-                        process.stderr.write(`[ClaudeRunner:${id}] ${chunk}`);
-                    }
-                    // Append to registry for stream tracking
-                    if (child.pid) {
-                        appendOutput(child.pid, chunk).catch(() => { });
-                    }
-                });
+            catch { /* ignored */ }
+            try {
+                fs.closeSync(logFd);
             }
-            if (child.stderr) {
-                child.stderr.on('data', (d) => {
-                    const chunk = d.toString();
-                    stderr += chunk;
-                    if (agentName) {
-                        const id = agentCustomEnv.AGENT_NICKNAME || agentName;
-                        process.stderr.write(`[ClaudeRunner:${id}:ERR] ${chunk}`);
-                    }
+            catch { /* ignored */ }
+            if (child.pid) {
+                await registerProcess(child.pid, {
+                    agentName: agentName || '',
+                    runner: 'claude',
+                    configPath: options.configPath,
+                    logFile,
+                    detached: true,
                 });
             }
-            const timeout = setTimeout(() => {
-                child.kill();
-                if (child.pid) {
-                    updateProcessStatus(child.pid, 'failed', null).catch(() => { });
-                }
-                cleanupTmpFiles();
-                resolve({ result: '', error: `TIMEOUT`, rawOutput: stdout });
-            }, customTimeoutMs);
-            child.on('close', async (code) => {
-                clearTimeout(timeout);
-                cleanupTmpFiles();
-                // Update process registry status
-                if (child.pid) {
-                    const status = code === 0 ? 'done' : 'failed';
-                    updateProcessStatus(child.pid, status, code).catch(() => { });
+            // Best-effort cleanup of the prompt file once the child is done reading it.
+            // 30s is generous: claude reads stdin within the first second normally.
+            setTimeout(() => {
+                try {
+                    fs.unlinkSync(promptFile);
                 }
-                const detectError = (text) => {
-                    const lower = text.toLowerCase();
-                    if (lower.includes('api key') || lower.includes('auth') || lower.includes('401')) {
-                        return '🔑 Erreur Auth/API Key (Clé invalide ou manquante)';
+                catch { /* ignored */ }
+            }, 30000).unref();
+            child.unref();
+            return {
+                result: `DETACHED: pid=${child.pid ?? 'unknown'}, agentName=${agentName || ''}\n` +
+                    `logFile=${logFile}\n` +
+                    `Use agent_control({action:"status"|"stream"|"wait"|"kill", agentName, runner:"claude"}) to monitor.`,
+                sessionId: undefined,
+            };
+        }
+        const runImpl = async (span) => {
+            span.setAttribute('agentName', agentName || '');
+            span.setAttribute('model', modelUsed || '');
+            span.setAttribute('runner', 'claude');
+            return new Promise((resolve) => {
+                let resolved = false;
+                let retryCount = 0;
+                const maxRetries = getAvailableFallbacks().length + 1; // primary + fallbacks
+                currentChildRef = null;
+                let currentStderr = '';
+                let currentStdout = '';
+                const MAX_BUF = 10 * 1024 * 1024;
+                let currentSessionId = sessionId;
+                let earlyExitTriggered = false; // Prevent double-exit on early retry
+                const safeResolve = (value) => {
+                    if (!resolved) {
+                        resolved = true;
+                        resolve(value);
                     }
-                    if (lower.includes('quota') || lower.includes('exceeded') || lower.includes('429')) {
-                        return '📊 Quota dépassé (API Key épuisée)';
+                };
+                const triggerRetry = async (targetRetryCount) => {
+                    if (earlyExitTriggered)
+                        return;
+                    earlyExitTriggered = true;
+                    if (hardTimeoutTimer)
+                        clearTimeout(hardTimeoutTimer);
+                    if (killTimer)
+                        clearTimeout(killTimer);
+                    // Attendre la mort effective de l'arbre (cmd.exe + claude.exe sur Win)
+                    // avant de respawn, sinon le nouveau process tape sur la même session
+                    // encore "vivante" côté provider → 429 fantôme.
+                    if (currentChildRef) {
+                        await killProcessTree(currentChildRef);
+                    }
+                    retryCount = targetRetryCount;
+                    const tokenInfo = getTokenForIndex(retryCount);
+                    if (!options.silent) {
+                        process.stderr.write(`\n\x1b[41m\x1b[37m[ClaudeRunner] 🔄 Retry ${retryCount}/${maxRetries} avec ${tokenInfo?.tokenEnvKey || 'UNKNOWN'}...\x1b[0m\n`);
                     }
-                    if (lower.includes('rate limit')) {
-                        return '⏳ Rate limit atteint';
+                    setImmediate(() => spawnWithToken(tokenInfo));
+                };
+                const cleanupTmpFiles = () => {
+                    if (tmpMcpPathToDelete && fs.existsSync(tmpMcpPathToDelete)) {
+                        try {
+                            fs.unlinkSync(tmpMcpPathToDelete);
+                        }
+                        catch {
+                            // Ignored
+                        }
                     }
-                    if (lower.includes('model') && lower.includes('404')) {
-                        return '🤖 Modèle introuvable';
+                    if (tmpSettingsPathToDelete && fs.existsSync(tmpSettingsPathToDelete)) {
+                        try {
+                            fs.unlinkSync(tmpSettingsPathToDelete);
+                        }
+                        catch {
+                            // Ignored
+                        }
                     }
-                    return null;
                 };
-                if (code !== 0 && !stdout) {
-                    const specificError = detectError(stderr);
-                    return resolve({
-                        result: '',
-                        error: specificError || `EXIT_CODE_${code}`,
-                        rawOutput: stderr,
-                    });
-                }
-                try {
-                    let jsonStr = stdout.trim();
-                    const jsonStartIndex = jsonStr.indexOf('{');
-                    const jsonLastIndex = jsonStr.lastIndexOf('}');
-                    if (jsonStartIndex >= 0 && jsonLastIndex > jsonStartIndex) {
-                        jsonStr = jsonStr.substring(jsonStartIndex, jsonLastIndex + 1);
+                let killTimer = null;
+                let hardTimeoutTimer = null;
+                /**
+                 * Fonction centrale qui spawn le processus Claude avec le bon token.
+                 * Appelé initialement et après chaque retry.
+                 */
+                const spawnWithToken = (tokenInfo) => {
+                    // Nettoyer les listeners/timers de la tentative précédente
+                    if (hardTimeoutTimer) {
+                        clearTimeout(hardTimeoutTimer);
+                        hardTimeoutTimer = null;
+                    }
+                    if (killTimer) {
+                        clearTimeout(killTimer);
+                        killTimer = null;
                     }
-                    const response = JSON.parse(jsonStr || '{}');
-                    if (agentName && response.session_id) {
-                        await saveSessionId(agentName, response.session_id);
-                        if (child.pid) {
-                            linkSessionToPid(response.session_id, child.pid).catch(() => { });
+                    // Construire l'env avec le bon token
+                    // NOTE: Overmind gère la substitution des variables $VAR dans les settings.
+                    // Les fallback tokens (AUTH_FALLBACK_1/2/3) sont résolus ici pour le retry 401.
+                    const spawnEnv = {
+                        ...process.env,
+                        ...agentCustomEnv,
+                    };
+                    if (tokenInfo) {
+                        // Remplacer le token actif par celui du fallback
+                        // NOTE: Les tokens peuvent encore contenir des $VAR non résolus
+                        // (interpolateEnvVars n'a pas trouvé ces vars dans process.env au moment du load).
+                        // On résout ici via process.env (qui a été peuplé par loadEnvQuietly).
+                        for (const tk of TOKEN_KEYS) {
+                            delete spawnEnv[tk];
                         }
+                        let resolvedToken = tokenInfo.tokenValue;
+                        if (resolvedToken.startsWith('$')) {
+                            const envKey = resolvedToken.slice(1);
+                            resolvedToken = process.env[envKey] || resolvedToken;
+                        }
+                        // Le Claude CLI lit ANTHROPIC_AUTH_TOKEN — on injecte toujours sous ce nom,
+                        // peu importe que tokenInfo vienne du primary ou d'un AUTH_FALLBACK_n.
+                        spawnEnv['ANTHROPIC_AUTH_TOKEN'] = resolvedToken;
+                    }
+                    currentStderr = '';
+                    currentStdout = '';
+                    const command = process.platform === 'win32' ? 'cmd.exe' : 'claude';
+                    const spawnArgs = process.platform === 'win32'
+                        ? ['/c', 'claude', ...argsSpawn, '-p']
+                        : ['claude', ...argsSpawn, '-p'];
+                    if (!options.silent) {
+                        const tokenLabel = tokenInfo ? ` (token: ${tokenInfo.tokenEnvKey})` : '';
+                        process.stderr.write(`\n\x1b[33m[ClaudeRunner]${tokenLabel} Spawning Claude CLI...\x1b[0m\n`);
                     }
-                    resolve({
-                        result: response.result || JSON.stringify(response),
-                        sessionId: response.session_id,
-                        rawOutput: stdout,
+                    currentChildRef = spawn(command, spawnArgs, {
+                        cwd: options.cwd || process.cwd(),
+                        windowsHide: true,
+                        env: spawnEnv,
+                        shell: false,
+                        signal: options.signal,
                     });
-                }
-                catch (_error) {
-                    const specificError = detectError(stdout) || detectError(stderr);
-                    resolve({
-                        result: '',
-                        error: specificError || 'JSON_PARSE_ERROR',
-                        rawOutput: stdout,
+                    // Register process immediately after spawn
+                    if (currentChildRef.pid) {
+                        void registerProcess(currentChildRef.pid, {
+                            agentName: agentName || '',
+                            runner: 'claude',
+                            configPath: options.configPath,
+                        });
+                    }
+                    if (currentChildRef.stdout) {
+                        currentChildRef.stdout.on('data', (d) => {
+                            const chunk = d.toString();
+                            if (currentChildRef && currentChildRef.pid && chunk) {
+                                void appendOutput(currentChildRef.pid, chunk, options.configPath);
+                            }
+                            if (currentStdout.length + chunk.length > MAX_BUF)
+                                currentStdout = currentStdout.slice(-MAX_BUF);
+                            else
+                                currentStdout += chunk;
+                            if (agentName && !options.silent) {
+                                process.stderr.write(`[ClaudeRunner:${agentName}] ${chunk}`);
+                            }
+                        });
+                    }
+                    if (currentChildRef.stderr) {
+                        currentChildRef.stderr.on('data', (d) => {
+                            const chunk = d.toString();
+                            if (currentChildRef && currentChildRef.pid && chunk) {
+                                void appendOutput(currentChildRef.pid, chunk, options.configPath);
+                            }
+                            if (currentStderr.length + chunk.length > MAX_BUF)
+                                currentStderr = currentStderr.slice(-MAX_BUF);
+                            else
+                                currentStderr += chunk;
+                            if (agentName && !options.silent) {
+                                process.stderr.write(`[ClaudeRunner:${agentName}:ERR] ${chunk}`);
+                            }
+                        });
+                    }
+                    if (currentChildRef.stdin) {
+                        currentChildRef.stdin.write(prompt);
+                        currentChildRef.stdin.end();
+                    }
+                    const timeout = setTimeout(() => {
+                        if (currentChildRef && currentChildRef.stdin && !currentChildRef.stdin.destroyed) {
+                            try {
+                                currentChildRef.stdin.write('\n');
+                                if (!options.silent) {
+                                    process.stderr.write(`\n\x1b[33m[ClaudeRunner] [WARN] Agent stagnant (${customTimeoutMs}ms). Envoi d'un keep-alive (\\n)...\x1b[0m\n`);
+                                }
+                            }
+                            catch (_e) {
+                                // Ignore
+                            }
+                        }
+                        const hardTimeoutDelay = CONFIG.HARD_TIMEOUT_MS || 60000;
+                        hardTimeoutTimer = setTimeout(() => {
+                            if (currentChildRef)
+                                void killProcessTree(currentChildRef);
+                            cleanupTmpFiles();
+                            safeResolve({
+                                result: '',
+                                error: 'HARD_TIMEOUT',
+                                rawOutput: currentStdout + currentStderr,
+                            });
+                        }, hardTimeoutDelay);
+                    }, customTimeoutMs);
+                    currentChildRef.on('error', (err) => {
+                        clearTimeout(timeout);
+                        if (hardTimeoutTimer)
+                            clearTimeout(hardTimeoutTimer);
+                        cleanupTmpFiles();
+                        safeResolve({ result: '', error: `SPAWN_ERROR: ${err.message}`, rawOutput: '' });
                     });
-                }
-            });
-            child.on('error', (err) => {
-                cleanupTmpFiles();
-                resolve({ result: '', error: err.message, rawOutput: '' });
+                    currentChildRef.on('close', async (code) => {
+                        clearTimeout(timeout);
+                        if (hardTimeoutTimer)
+                            clearTimeout(hardTimeoutTimer);
+                        const fullRaw = currentStdout + (currentStderr ? `\n\n--- STDERR ---\n${currentStderr}` : '');
+                        // ─── Parser le JSON en premier (pour extraire api_error_status) ───
+                        let jsonEnvelope = null;
+                        const trimmedStdout = currentStdout.trim();
+                        try {
+                            jsonEnvelope = JSON.parse(trimmedStdout);
+                        }
+                        catch {
+                            const lastBrace = trimmedStdout.lastIndexOf('}');
+                            const firstBrace = trimmedStdout.lastIndexOf('{', lastBrace);
+                            if (firstBrace !== -1 && lastBrace !== -1) {
+                                try {
+                                    jsonEnvelope = JSON.parse(trimmedStdout.substring(firstBrace, lastBrace + 1));
+                                }
+                                catch {
+                                    // Ignored
+                                }
+                            }
+                        }
+                        // ─── Fallback retry ─────────────────────────────────────────────────
+                        // Sur 401/429/5xx, on tue l'arbre du process courant via killProcessTree
+                        // (taskkill /F /T sur Windows pour ne pas laisser claude.exe orphelin),
+                        // puis on respawn un nouveau noeud avec --resume + le token fallback
+                        // suivant (AUTH_FALLBACK_1 → 2 → 3).
+                        // ───────────────────────────────────────────────────────────────────
+                        const FALLBACK_RETRY_ENABLED = true;
+                        const isRetryable = isRetryableError(currentStderr, jsonEnvelope);
+                        const hasRetryableStatus = jsonEnvelope !== null &&
+                            (jsonEnvelope.api_error_status === 401 ||
+                                jsonEnvelope.api_error_status === 429 ||
+                                jsonEnvelope.api_error_status === 500 ||
+                                jsonEnvelope.api_error_status === 502 ||
+                                jsonEnvelope.api_error_status === 503);
+                        const isFailure = FALLBACK_RETRY_ENABLED && ((code !== 0 && isRetryable) || hasRetryableStatus);
+                        if (isFailure) {
+                            if (retryCount < maxRetries) {
+                                triggerRetry(retryCount + 1);
+                                return;
+                            }
+                            else {
+                                if (!options.silent) {
+                                    process.stderr.write(`\n\x1b[41m\x1b[37m[ClaudeRunner] ❌ Tous les tokens fallback épuisés. Error retryable finale.\x1b[0m\n`);
+                                }
+                                if (currentChildRef?.pid) {
+                                    void updateProcessStatus(currentChildRef.pid, 'failed', code, options.configPath);
+                                }
+                                cleanupTmpFiles();
+                                safeResolve({
+                                    result: '',
+                                    error: 'RETRYABLE_ERROR_ALL_FALLBACKS_EXHAUSTED',
+                                    rawOutput: fullRaw,
+                                });
+                                return;
+                            }
+                        }
+                        cleanupTmpFiles();
+                        try {
+                            if (jsonEnvelope) {
+                                let foundSessionId = currentSessionId;
+                                if (jsonEnvelope.session_id && agentName) {
+                                    foundSessionId = jsonEnvelope.session_id;
+                                    currentSessionId = foundSessionId;
+                                    await saveSessionId(agentName, jsonEnvelope.session_id, options.configPath, 'claude');
+                                    if (currentChildRef?.pid) {
+                                        void linkSessionToPid(jsonEnvelope.session_id, currentChildRef.pid, options.configPath);
+                                    }
+                                }
+                                if (currentChildRef?.pid) {
+                                    void updateProcessStatus(currentChildRef.pid, code === 0 ? 'done' : 'failed', code ?? null, options.configPath);
+                                }
+                                return safeResolve({
+                                    result: jsonEnvelope.reply ||
+                                        jsonEnvelope.result ||
+                                        currentStdout.trim(),
+                                    sessionId: foundSessionId,
+                                    rawOutput: currentStdout,
+                                    model: modelUsed ?? undefined,
+                                    nickname: originalModel !== modelUsed ? originalModel : undefined,
+                                });
+                            }
+                            if (code === 0) {
+                                if (currentChildRef?.pid) {
+                                    void updateProcessStatus(currentChildRef.pid, 'done', code, options.configPath);
+                                }
+                                return safeResolve({
+                                    result: currentStdout.trim(),
+                                    sessionId: currentSessionId,
+                                    rawOutput: currentStdout,
+                                    model: modelUsed ?? undefined,
+                                    nickname: originalModel !== modelUsed ? originalModel : undefined,
+                                });
+                            }
+                            if (currentChildRef?.pid) {
+                                void updateProcessStatus(currentChildRef.pid, 'failed', code, options.configPath);
+                            }
+                            safeResolve({
+                                result: '',
+                                error: code !== 0 ? `EXIT_CODE_${code}` : 'JSON_PARSE_ERROR',
+                                rawOutput: fullRaw,
+                            });
+                        }
+                        catch (error) {
+                            safeResolve({
+                                result: '',
+                                error: `INTERNAL_ERROR: ${error instanceof Error ? error.message : String(error)}`,
+                                rawOutput: fullRaw,
+                            });
+                        }
+                    });
+                };
+                // ─── Démarrage initial avec le primary token ───
+                spawnWithToken(getTokenForIndex(0));
             });
+        };
+        return withSpan('claude.runAgent', runImpl, {
+            agentName: agentName || '',
+            model: modelUsed || '',
+            runner: 'claude',
         });
     }
 }