reviewflow 3.12.0 → 3.14.0

package/dist/frameworks/claude/claudeInvoker.js

@@ -2,7 +2,6 @@ import { spawn } from 'node:child_process';
 import { writeFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { ProgressParser } from '../../frameworks/claude/progressParser.js';
 import { logInfo, logWarn, logError } from '../../frameworks/logging/logBuffer.js';
 import { getModel } from '../../frameworks/settings/runtimeSettings.js';
 import { getProjectAgents, getFollowupAgents, loadProjectConfig } from '../../config/projectConfig.js';
@@ -23,8 +22,14 @@ import { FilesystemTokenUsageGateway } from '../../modules/token-accounting/inte
 import { GetBudgetStatusUseCase } from '../../modules/token-accounting/usecases/getBudgetStatus/getBudgetStatus.usecase.js';
 import { FilesystemBudgetGateway } from '../../modules/token-accounting/interface-adapters/gateways/budget/budget.filesystem.gateway.js';
 import { BudgetStatusPresenter } from '../../modules/token-accounting/interface-adapters/presenters/budgetStatus.presenter.js';
-import { broadcastBudgetAfterUsage } from '../../frameworks/claude/broadcastBudgetAfterUsage.js';
-import { StreamJsonParser } from '../../frameworks/claude/streamJsonParser.js';
+import { ClaudeSessionCliGateway, } from '../../modules/claude-invocation/interface-adapters/gateways/claudeSession.cli.gateway.js';
+import { FileSystemMcpCompletionBridge } from '../../modules/claude-invocation/interface-adapters/gateways/mcpCompletion.fileSystem.gateway.js';
+import { ReviewReportFileSystemGateway } from '../../modules/claude-invocation/interface-adapters/gateways/reviewReport.fileSystem.gateway.js';
+import { InMemoryBillingStateGateway } from '../../modules/claude-invocation/interface-adapters/gateways/billingState.memory.gateway.js';
+import { ProcessEnvironmentGateway } from '../../modules/claude-invocation/interface-adapters/gateways/environment.process.gateway.js';
+import { runClaudeReviewJob } from '../../modules/claude-invocation/usecases/runClaudeReviewJob.usecase.js';
+import { WorktreeFileSystemGateway } from '../../modules/worktree-management/interface-adapters/gateways/worktree.fileSystem.gateway.js';
+import { GitCommandCliGateway } from '../../modules/worktree-management/interface-adapters/gateways/gitCommand.cli.gateway.js';
 /**
  * Default wiring used when invokeClaudeReview is called without explicit deps.
  *
@@ -34,6 +39,62 @@ import { StreamJsonParser } from '../../frameworks/claude/streamJsonParser.js';
  * The no-op `broadcastBudgetStatus` here is intentional for tests and CLI
  * one-shots where there is no WebSocket fanout to perform.
  */
+/**
+ * Build the environment for spawning a Claude child process.
+ *
+ * Strips CLAUDECODE so a Claude-launched ReviewFlow does not leak its parent
+ * session marker into the child, and forces TERM=dumb + CI=true to keep the
+ * child in non-interactive mode.
+ */
+export function buildSpawnEnv(processEnv, override) {
+    const { CLAUDECODE: _claudeCode, ...rest } = processEnv;
+    return {
+        ...rest,
+        TERM: 'dumb',
+        CI: 'true',
+        ...(override ?? {}),
+    };
+}
+/**
+ * Default process runner used by createDefaultClaudeInvocationDeps when the
+ * composition root does not provide one. Wraps node:child_process.spawn so
+ * tests can inject a fake runner instead.
+ */
+function defaultProcessRunner() {
+    return async ({ args, cwd, env }) => new Promise((resolve, reject) => {
+        const child = spawn(resolveClaudePath(), args, {
+            cwd,
+            env: buildSpawnEnv(process.env, env),
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.on('data', chunk => {
+            stdout += chunk.toString();
+        });
+        child.stderr?.on('data', chunk => {
+            stderr += chunk.toString();
+        });
+        child.on('error', reject);
+        child.on('close', code => {
+            resolve({ stdout, stderr, exitCode: code ?? -1 });
+        });
+    });
+}
+export function createDefaultClaudeInvocationDeps() {
+    return {
+        sessionGateway: new ClaudeSessionCliGateway(defaultProcessRunner()),
+        // FileSystem-backed because the MCP server runs in a sub-process spawned
+        // by `claude --bg`, so an in-memory bridge cannot reach the Fastify host.
+        // See FileSystemMcpCompletionBridge for the wire format.
+        completionBridge: new FileSystemMcpCompletionBridge(),
+        reportGateway: new ReviewReportFileSystemGateway(),
+        billingState: new InMemoryBillingStateGateway(),
+        environment: new ProcessEnvironmentGateway(),
+        timeoutMs: 15 * 60 * 1000,
+        pollIntervalMs: 30 * 1000,
+    };
+}
 export function createDefaultClaudeInvokerDependencies() {
     const tokenUsageGateway = new FilesystemTokenUsageGateway();
     const budgetGateway = new FilesystemBudgetGateway();
@@ -48,6 +109,8 @@ export function createDefaultClaudeInvokerDependencies() {
         getBudgetStatus: new GetBudgetStatusUseCase({ budgetGateway, tokenUsageGateway }),
         budgetStatusPresenter: new BudgetStatusPresenter(),
         broadcastBudgetStatus: () => { },
+        invocation: createDefaultClaudeInvocationDeps(),
+        worktreeGateway: new WorktreeFileSystemGateway({ executor: new GitCommandCliGateway() }),
     };
 }
 const currentDir = dirname(fileURLToPath(import.meta.url));
@@ -116,10 +179,6 @@ export function cleanupMcpContext(jobId) {
         // Ignore cleanup errors
     }
 }
-// Memory guard configuration
-const MEMORY_LIMIT_GB = 4; // Kill process if RSS exceeds 4GB
-const MEMORY_CHECK_INTERVAL_MS = 5000; // Check every 5 seconds
-const MEMORY_LIMIT_BYTES = MEMORY_LIMIT_GB * 1024 * 1024 * 1024;
 function fetchDiffStatsSafely(job, deps, logger) {
     try {
         const gateway = deps.diffStatsFetchFactory(job.platform);
@@ -155,9 +214,6 @@ async function resolveModel(job, diffStats, deps, logger) {
  * This instruction is AUTHORITATIVE and forces Claude to use MCP tools
  */
 export function buildMcpSystemPrompt(job) {
-    const isGitHub = job.platform === 'github';
-    const diffSourceCommand = isGitHub ? `gh pr diff ${job.mrNumber}` : `glab mr diff ${job.mrNumber}`;
-    const metadataSourceCommand = isGitHub ? `gh pr view ${job.mrNumber}` : `glab mr view ${job.mrNumber}`;
     return `
 # AUTOMATED REVIEW MODE - EXECUTE IMMEDIATELY
 
@@ -189,22 +245,9 @@ These rules are about WRITING production code. You are in **READ-ONLY review mod
 - **Source Branch**: ${job.sourceBranch || 'unknown'}
 - **Target Branch**: ${job.targetBranch || 'unknown'}
 
-## ⛔ CRITICAL: Data Source Rules
-
-The local repository at \`${job.localPath}\` may be checked out on a DIFFERENT branch than MR !${job.mrNumber}.
-Multiple reviews can run concurrently on the same repo. The local state is UNRELIABLE.
-
-**SOURCE OF TRUTH for the MR diff**: \`${diffSourceCommand}\` — use this, NEVER \`git diff\`.
-**SOURCE OF TRUTH for MR metadata**: \`${metadataSourceCommand}\` — use this for branch names, title, description.
-**SOURCE OF TRUTH for threads**: \`get_threads({ jobId: "${job.id}" })\` — MCP tool.
-
-**FORBIDDEN — these reflect LOCAL state, not the MR:**
-- \`git diff\`, \`git log\`, \`git branch\`, \`git status\`
-- Reading local files as source of truth for what the MR changes
-- Assuming the local branch matches the MR being reviewed
-
-**ALLOWED — local repo for conflict detection only:**
-- Reading local files to check if they conflict with MR changes (advisory only)
+The current working directory is the dedicated worktree for this MR. The branch is already
+checked out and up to date — \`git diff\`, \`git log\`, and local file reads reflect MR state.
+For thread metadata always use the MCP tool: \`get_threads({ jobId: "${job.id}" })\`.
 
 ## MANDATORY MCP Tools Usage
 
@@ -281,21 +324,19 @@ export async function invokeClaudeReview(job, logger, onProgress, signal, deps =
     // Build MCP config: isolated from project .mcp.json to avoid
     // third-party MCP servers (e.g. gitnexus) causing initialization timeouts
     const mcpConfigJson = buildMcpConfigJson();
-    // Build arguments
-    // --permission-mode bypassPermissions: automated review, no user to approve
-    // --allowedTools / --disallowedTools: belt-and-suspenders to restrict tool scope
-    // --mcp-config + --strict-mcp-config: use ONLY review-progress MCP server
+    // Build arguments for the --bg (background subscription billing) invocation.
+    // The session id is captured from stdout; completion is observed through MCP
+    // (set_phase) or `claude agents --json` polling. No -p, no --print, no stream-json.
     const args = [
-        '--output-format', 'stream-json',
-        '--verbose',
+        '--bg',
         '--model', model,
-        '--permission-mode', 'bypassPermissions',
+        '--permission-mode', 'auto',
         '--append-system-prompt', mcpSystemPrompt,
         '--mcp-config', mcpConfigJson,
         '--strict-mcp-config',
         '--allowedTools', 'Read,Glob,Grep,Bash,Edit,Task,Skill,Write,LSP,mcp__review-progress__*',
         '--disallowedTools', 'EnterPlanMode,AskUserQuestion',
-        '-p', prompt,
+        prompt,
     ];
     // Setup MCP job context file (used by MCP server to identify the review)
     writeMcpContext(job);
@@ -319,13 +360,6 @@ export async function invokeClaudeReview(job, logger, onProgress, signal, deps =
         jobType: job.jobType || 'review',
         customAgents: projectAgents?.length ?? 'default',
     });
-    // Initialize progress parser with project agents (or defaults)
-    const progressParser = new ProgressParser(job.id, (event, progress) => {
-        logger.debug({ event, progress: progress.overallProgress }, 'Progress update');
-        onProgress?.(progress, event);
-    }, projectAgents);
-    // Emit initial progress
-    onProgress?.(progressParser.getProgress());
     // Check if already cancelled
     if (signal?.aborted) {
         logWarn('Review annulée avant démarrage', { jobId: job.id });
@@ -335,265 +369,186 @@ export async function invokeClaudeReview(job, logger, onProgress, signal, deps =
             stdout: '',
             stderr: 'Review cancelled before start',
             durationMs: Date.now() - startTime,
-            finalProgress: progressParser.getProgress(),
             cancelled: true,
         };
     }
-    return new Promise((resolve) => {
-        let stdout = '';
-        let stderr = '';
-        let cancelled = false;
-        const streamParser = new StreamJsonParser();
-        const childEnv = { ...process.env };
-        // Remove CLAUDECODE to allow spawning Claude from within a Claude session
-        childEnv.CLAUDECODE = undefined;
-        const child = spawn(resolveClaudePath(), args, {
-            cwd: job.localPath,
-            env: {
-                ...childEnv,
-                // Ensure non-interactive mode
-                TERM: 'dumb',
-                CI: 'true',
-                // Note: MCP env vars are now passed via --mcp-config
-            },
-            stdio: ['ignore', 'pipe', 'pipe'],
-        });
-        // Memory guard: monitor RSS and kill if exceeds limit
-        let memoryExceeded = false;
-        const memoryCheckInterval = setInterval(() => {
-            const memUsage = process.memoryUsage();
-            const rssMB = Math.round(memUsage.rss / 1024 / 1024);
-            if (memUsage.rss > MEMORY_LIMIT_BYTES) {
-                memoryExceeded = true;
-                const errorMessage = `
-╔═══════════════════════════════════════════════════════════════════╗
-║  🚨 MEMORY LIMIT EXCEEDED - REVIEW KILLED                        ║
-╠═══════════════════════════════════════════════════════════════════╣
-║                                                                   ║
-║  Current RSS: ${rssMB} MB (limit: ${MEMORY_LIMIT_GB * 1024} MB)            ║
-║  Job: ${job.id.substring(0, 50).padEnd(50)}    ║
-║                                                                   ║
-║  The review process consumed too much memory.                     ║
-║  This usually happens when running too many sub-agents            ║
-║  in parallel. Consider using sequential execution.                ║
-║                                                                   ║
-╚═══════════════════════════════════════════════════════════════════╝
-`;
-                logger.error({ rssMB, limitMB: MEMORY_LIMIT_GB * 1024, jobId: job.id }, 'Memory limit exceeded, killing process');
-                logError('Memory limit exceeded', {
-                    jobId: job.id,
-                    rssMB,
-                    limitMB: MEMORY_LIMIT_GB * 1024,
-                    message: 'Review killed due to excessive memory consumption',
-                });
-                // Output error to stderr for visibility
-                stderr += errorMessage;
-                // Kill the child process
-                child.kill('SIGKILL');
-                clearInterval(memoryCheckInterval);
-            }
-            else if (rssMB > (MEMORY_LIMIT_GB * 1024 * 0.8)) {
-                // Warn when approaching limit (80%)
-                logger.warn({ rssMB, limitMB: MEMORY_LIMIT_GB * 1024 }, 'Memory usage high, approaching limit');
-            }
-        }, MEMORY_CHECK_INTERVAL_MS);
-        // Handle cancellation via AbortSignal
-        const abortHandler = () => {
-            if (!cancelled) {
-                cancelled = true;
-                logger.info({ jobId: job.id }, 'Review annulée par utilisateur');
-                logWarn('Review annulée', { jobId: job.id });
-                child.kill('SIGTERM');
-                // Give it time to cleanup, then force kill
-                setTimeout(() => {
-                    if (!child.killed) {
-                        child.kill('SIGKILL');
-                    }
-                }, 5000);
-            }
+    return invokeViaBackgroundSession({
+        job,
+        prompt,
+        model,
+        mcpSystemPrompt,
+        mcpConfigJson,
+        diffStats,
+        startTime,
+        signal,
+    }, logger, onProgress, deps);
+}
+function deriveMrSourceFromJob(job) {
+    if (job.sourceForkCloneUrl) {
+        return { kind: 'fork', cloneUrl: job.sourceForkCloneUrl };
+    }
+    return { kind: 'origin' };
+}
+async function invokeViaBackgroundSession(context, logger, onProgress, deps) {
+    const { job, prompt, model, mcpSystemPrompt, mcpConfigJson, diffStats, startTime, signal } = context;
+    const invocation = deps.invocation;
+    const mergeRequestId = `${job.platform}-${job.projectPath}-${job.mrNumber}`;
+    const jobType = job.jobType === 'followup' ? 'followup' : 'review';
+    const ensureStart = Date.now();
+    const ensureResult = await deps.worktreeGateway.ensure({
+        identity: {
+            platform: job.platform,
+            projectPath: job.projectPath,
+            mrNumber: job.mrNumber,
+        },
+        sourceBranch: job.sourceBranch,
+        source: deriveMrSourceFromJob(job),
+        sourceCheckoutPath: job.localPath,
+    });
+    const ensureDurationMs = Date.now() - ensureStart;
+    logger.info({ jobId: job.id, ensureDurationMs, status: ensureResult.status }, 'ensureWorktree completed');
+    if (ensureResult.status === 'failed') {
+        cleanupMcpContext(job.id);
+        logError('Préparation worktree échouée', { jobId: job.id, reason: ensureResult.reason });
+        return {
+            success: false,
+            exitCode: null,
+            stdout: '',
+            stderr: `ensureWorktree failed: ${ensureResult.reason}`,
+            durationMs: Date.now() - startTime,
+            selectedModel: model,
         };
-        if (signal) {
-            signal.addEventListener('abort', abortHandler, { once: true });
-        }
-        child.stdout.on('data', (data) => {
-            const chunk = data.toString();
-            stdout += chunk;
-            streamParser.feed(chunk);
-            // Progress markers may still appear in assistant text within stream-json events;
-            // feeding the raw chunk keeps any legacy markers detected without coupling to JSON shape.
-            progressParser.parseChunk(chunk);
-            const preview = chunk.length > 200 ? chunk.substring(0, 200) + '...' : chunk;
-            logger.debug({ preview }, 'Claude stdout');
-        });
-        child.stderr.on('data', (data) => {
-            const chunk = data.toString();
-            stderr += chunk;
-            logger.warn({ chunk }, 'Claude stderr');
-            logWarn('Claude stderr', { jobId: job.id, message: chunk.substring(0, 500) });
+    }
+    if (ensureResult.status === 'created' && ensureResult.settingsWarning !== null) {
+        logger.warn({ jobId: job.id, warning: ensureResult.settingsWarning }, 'Worktree created but settings write produced a warning (FR-4 bgIsolation may not be applied)');
+    }
+    const worktreePath = ensureResult.path;
+    // attempt counter is reserved for the queue layer to re-enqueue with backoff
+    // when status === 'retry' is returned. Until that wiring exists, every
+    // invocation is treated as attempt 0 and a single retry signal surfaces back
+    // to the controller as a soft failure.
+    const attempt = 0;
+    const flags = {
+        model,
+        mcpConfigJson,
+        systemPrompt: mcpSystemPrompt,
+        allowedTools: 'Read,Glob,Grep,Bash,Edit,Task,Skill,Write,LSP,mcp__review-progress__*',
+        disallowedTools: 'EnterPlanMode,AskUserQuestion',
+        permissionMode: 'auto',
+    };
+    let result;
+    try {
+        result = await runClaudeReviewJob({
+            jobId: job.id,
+            jobType,
+            prompt,
+            flags,
+            localPath: worktreePath,
+            mergeRequestId,
+            mergeRequestNumber: job.mrNumber,
+            attempt,
+            signal,
+        }, {
+            sessionGateway: invocation.sessionGateway,
+            completionBridge: invocation.completionBridge,
+            reportGateway: invocation.reportGateway,
+            billingState: invocation.billingState,
+            environment: invocation.environment,
+            now: () => new Date(),
+            timeoutMs: invocation.timeoutMs,
+            pollIntervalMs: invocation.pollIntervalMs,
         });
-        child.on('error', (error) => {
-            logger.error({ error }, 'Erreur lors du spawn de Claude');
-            logError('Erreur spawn Claude', { jobId: job.id, error: error.message });
-            progressParser.markFailed(error.message);
-            resolve({
-                success: false,
-                exitCode: null,
-                stdout,
-                stderr: stderr + `\nSpawn error: ${error.message}`,
-                durationMs: Date.now() - startTime,
-                finalProgress: progressParser.getProgress(),
-            });
+    }
+    catch (error) {
+        cleanupMcpContext(job.id);
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error({ error: message, jobId: job.id }, 'runClaudeReviewJob threw');
+        logError('Review en erreur', { jobId: job.id, message });
+        return {
+            success: false,
+            exitCode: null,
+            stdout: '',
+            stderr: message,
+            durationMs: Date.now() - startTime,
+            selectedModel: model,
+        };
+    }
+    cleanupMcpContext(job.id);
+    const durationMs = Date.now() - startTime;
+    const durationMin = Math.round(durationMs / 60000);
+    if (result.status === 'completed') {
+        logInfo('Review terminée', {
+            jobId: job.id,
+            mrNumber: job.mrNumber,
+            duration: `${durationMin} min`,
+            outputLength: result.content.length,
+            model,
         });
-        child.on('close', async (code) => {
-            // Cleanup interval, abort listener, and MCP context
-            clearInterval(memoryCheckInterval);
-            cleanupMcpContext(job.id);
-            if (signal) {
-                signal.removeEventListener('abort', abortHandler);
-            }
-            const durationMs = Date.now() - startTime;
-            const success = code === 0 && !cancelled && !memoryExceeded;
-            const assistantText = streamParser.getAssistantText();
-            const tokenUsage = streamParser.getUsage();
-            // Save logs: raw stream-json + reconstructed human text for readability
+        // Save review statistics (followups are not counted as reviews)
+        if (job.jobType !== 'followup') {
             try {
-                const logsDir = join(job.localPath, '.claude', 'reviews', 'logs');
-                if (!existsSync(logsDir)) {
-                    mkdirSync(logsDir, { recursive: true });
-                }
-                const sanitizedJobId = job.id.replace(/[:/\\]/g, '-');
-                const logPath = join(logsDir, `${sanitizedJobId}-stdout.log`);
-                writeFileSync(logPath, `=== Claude Review Output ===\nJob: ${job.id}\nMR: ${job.mrNumber}\nSkill: ${job.skill}\nModel: ${model}\nExit code: ${code}\nDuration: ${Math.round(durationMs / 1000)}s\nTimestamp: ${new Date().toISOString()}\n\n--- ASSISTANT TEXT ---\n${assistantText}\n\n--- STDERR ---\n${stderr}\n\n--- RAW STREAM-JSON ---\n${stdout}\n`);
-                logger.info({ logPath }, 'Review stdout saved to log file');
+                const mrId = `${job.platform}-${job.projectPath}-${job.mrNumber}`;
+                const mrDetails = deps.trackingGateway.getById(job.localPath, mrId);
+                const assignedBy = mrDetails?.assignment?.username;
+                const reviewStats = addReviewStats(job.localPath, job.mrNumber, durationMs, result.content, assignedBy, diffStats);
+                logger.info({ reviewStats }, 'Stats de review enregistrées');
             }
-            catch {
-                // Non-critical
+            catch (statsError) {
+                logger.warn({ error: statsError }, 'Erreur lors de l\'enregistrement des stats');
             }
-            // Finalize progress
-            if (memoryExceeded) {
-                progressParser.markFailed('Memory limit exceeded - review killed');
-            }
-            else if (cancelled) {
-                progressParser.markFailed('Annulée par utilisateur');
-            }
-            else if (success) {
-                progressParser.markAllCompleted();
-            }
-            else {
-                progressParser.markFailed(`Exit code: ${code}`);
-            }
-            const finalProgress = progressParser.getProgress();
-            onProgress?.(finalProgress);
-            logger.info({
-                exitCode: code,
-                durationMs,
-                stdoutLength: stdout.length,
-                stderrLength: stderr.length,
-                finalProgress: finalProgress.overallProgress,
-                cancelled,
-                memoryExceeded,
-            }, memoryExceeded
-                ? 'Claude killed - memory limit exceeded'
-                : cancelled
-                    ? 'Claude annulé'
-                    : success
-                        ? 'Claude terminé avec succès'
-                        : 'Claude terminé avec erreur');
-            // Log to dashboard with summary
-            const durationMin = Math.round(durationMs / 60000);
-            if (memoryExceeded) {
-                logError('Review killed - Memory limit exceeded', {
-                    jobId: job.id,
-                    mrNumber: job.mrNumber,
-                    duration: `${durationMin} min`,
-                    limitGB: MEMORY_LIMIT_GB,
-                });
-            }
-            else if (cancelled) {
-                logWarn('Review annulée', {
-                    jobId: job.id,
-                    mrNumber: job.mrNumber,
-                    duration: `${durationMin} min`,
-                });
-            }
-            else if (success) {
-                logInfo('Review terminée', {
-                    jobId: job.id,
-                    mrNumber: job.mrNumber,
-                    duration: `${durationMin} min`,
-                    outputLength: assistantText.length,
-                    model,
-                });
-                // Save review statistics (followups are not counted as reviews)
-                if (job.jobType !== 'followup') {
-                    try {
-                        const mrId = `${job.platform}-${job.projectPath}-${job.mrNumber}`;
-                        const mrDetails = deps.trackingGateway.getById(job.localPath, mrId);
-                        const assignedBy = mrDetails?.assignment?.username;
-                        const reviewStats = addReviewStats(job.localPath, job.mrNumber, durationMs, assistantText, assignedBy, diffStats);
-                        logger.info({ reviewStats }, 'Stats de review enregistrées');
-                    }
-                    catch (statsError) {
-                        logger.warn({ error: statsError }, 'Erreur lors de l\'enregistrement des stats');
-                    }
-                }
-                // Persist token usage for cost tracking (non-critical, never blocks the review result)
-                if (tokenUsage) {
-                    try {
-                        await deps.trackTokenUsage.execute({
-                            jobId: job.id,
-                            mrNumber: job.mrNumber,
-                            platform: job.platform,
-                            projectPath: job.projectPath,
-                            localPath: job.localPath,
-                            model,
-                            recordedAt: new Date().toISOString(),
-                            usage: tokenUsage,
-                        });
-                        logger.info({ jobId: job.id, model, usage: tokenUsage }, 'Token usage recorded');
-                        const broadcastLocalPaths = deps.getEnabledLocalPaths?.() ?? [job.localPath];
-                        await broadcastBudgetAfterUsage({
-                            getBudgetStatus: deps.getBudgetStatus,
-                            broadcastBudgetStatus: deps.broadcastBudgetStatus,
-                            presenter: deps.budgetStatusPresenter,
-                        }, { localPaths: broadcastLocalPaths }, logger);
-                    }
-                    catch (trackError) {
-                        logger.warn({ jobId: job.id, error: trackError }, 'Failed to persist token usage');
-                    }
-                }
-                // Log assistant text preview for debugging
-                if (assistantText.length > 0) {
-                    logInfo('Claude output preview', {
-                        jobId: job.id,
-                        preview: assistantText.substring(0, 1000),
-                        fullLength: assistantText.length,
-                    });
-                }
-            }
-            else {
-                logError('Review échouée', {
-                    jobId: job.id,
-                    mrNumber: job.mrNumber,
-                    exitCode: code,
-                    duration: `${durationMin} min`,
-                    stderr: stderr.substring(0, 500),
-                    stdoutPreview: (assistantText || stdout).substring(0, 300),
-                });
-            }
-            resolve({
-                success,
-                exitCode: memoryExceeded ? null : code,
-                stdout: assistantText,
-                stderr,
-                durationMs,
-                finalProgress,
-                cancelled: cancelled || memoryExceeded,
-                usage: tokenUsage,
-                selectedModel: model,
+        }
+        // Token usage tracking is disabled in --bg mode: the legacy stream-json
+        // path is gone and `claude --bg` does not emit usage to stdout. Re-enabling
+        // requires parsing `claude logs <sessionId>` — tracked in SPEC-171
+        // (docs/specs/171-bg-token-usage-tracking.md). Until SPEC-171 ships, the
+        // budget dashboard reports zero spending for --bg reviews.
+        if (onProgress) {
+            onProgress({
+                currentPhase: 'completed',
+                overallProgress: 100,
+                lastUpdate: new Date(),
+                agents: [],
             });
+        }
+        return {
+            success: true,
+            exitCode: 0,
+            stdout: result.content,
+            stderr: '',
+            durationMs,
+            usage: null,
+            selectedModel: model,
+        };
+    }
+    if (result.status === 'retry') {
+        logWarn('Rate-limited — backoff demandé', {
+            jobId: job.id,
+            delayMs: result.delayMs,
+            nextAttempt: result.attempt,
         });
+        return {
+            success: false,
+            exitCode: 1,
+            stdout: '',
+            stderr: `rate-limited; retry in ${result.delayMs}ms (attempt ${result.attempt})`,
+            durationMs,
+            selectedModel: model,
+        };
+    }
+    logError('Review échouée', {
+        jobId: job.id,
+        mrNumber: job.mrNumber,
+        duration: `${durationMin} min`,
+        reason: result.reason,
     });
+    return {
+        success: false,
+        exitCode: 1,
+        stdout: '',
+        stderr: result.reason,
+        durationMs,
+        selectedModel: model,
+    };
 }
 /**
  * Send desktop notification