reviewflow 3.10.0 → 3.13.0

package/dist/frameworks/claude/claudeInvoker.js

@@ -2,25 +2,114 @@ 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';
-import { addReviewStats } from '../../services/statsService.js';
-import { FileSystemReviewRequestTrackingGateway } from '../../interface-adapters/gateways/fileSystem/reviewRequestTracking.fileSystem.js';
-import { ProjectStatsCalculator } from '../../interface-adapters/presenters/projectStats.calculator.js';
-import { GitLabDiffStatsFetchGateway } from '../../interface-adapters/gateways/diffStatsFetch.gitlab.gateway.js';
-import { GitHubDiffStatsFetchGateway } from '../../interface-adapters/gateways/diffStatsFetch.github.gateway.js';
-import { defaultGitLabExecutor } from '../../interface-adapters/gateways/threadFetch.gitlab.gateway.js';
-import { defaultGitHubExecutor } from '../../interface-adapters/gateways/threadFetch.github.gateway.js';
+import { addReviewStats } from '../../modules/statistics-insights/services/statsService.js';
+import { FileSystemReviewRequestTrackingGateway } from '../../modules/tracking/interface-adapters/gateways/fileSystem/reviewRequestTracking.fileSystem.js';
+import { ProjectStatsCalculator } from '../../modules/statistics-insights/interface-adapters/presenters/projectStats.calculator.js';
+import { GitLabDiffStatsFetchGateway } from '../../modules/statistics-insights/interface-adapters/gateways/diffStatsFetch.gitlab.gateway.js';
+import { GitHubDiffStatsFetchGateway } from '../../modules/statistics-insights/interface-adapters/gateways/diffStatsFetch.github.gateway.js';
+import { defaultGitLabExecutor } from '../../modules/platform-integration/interface-adapters/gateways/threadFetch.gitlab.gateway.js';
+import { defaultGitHubExecutor } from '../../modules/platform-integration/interface-adapters/gateways/threadFetch.github.gateway.js';
 import { resolveClaudePath } from '../../shared/services/claudePathResolver.js';
 import { getJobContextFilePath } from '../../shared/services/mcpJobContext.js';
 import { buildLanguageDirective } from '../../frameworks/claude/languageDirective.js';
-import { SelectModelForReviewUseCase } from '../../usecases/selectModelForReview/selectModelForReview.usecase.js';
-import { ProjectConfigRoutingPolicyGateway } from '../../interface-adapters/gateways/projectConfig/routingPolicy.projectConfig.gateway.js';
-import { TrackTokenUsageUseCase } from '../../usecases/trackTokenUsage/trackTokenUsage.usecase.js';
-import { FilesystemTokenUsageGateway } from '../../interface-adapters/gateways/tokenUsage/tokenUsage.filesystem.gateway.js';
-import { StreamJsonParser } from '../../frameworks/claude/streamJsonParser.js';
+import { SelectModelForReviewUseCase } from '../../modules/review-execution/usecases/selectModelForReview/selectModelForReview.usecase.js';
+import { ProjectConfigRoutingPolicyGateway } from '../../modules/review-execution/interface-adapters/gateways/projectConfig/routingPolicy.projectConfig.gateway.js';
+import { TrackTokenUsageUseCase } from '../../modules/token-accounting/usecases/trackTokenUsage/trackTokenUsage.usecase.js';
+import { FilesystemTokenUsageGateway } from '../../modules/token-accounting/interface-adapters/gateways/tokenUsage/tokenUsage.filesystem.gateway.js';
+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 { 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';
+/**
+ * Default wiring used when invokeClaudeReview is called without explicit deps.
+ *
+ * Production (the HTTP daemon) MUST override `broadcastBudgetStatus` and
+ * `getEnabledLocalPaths` from the composition root in `main/routes.ts`,
+ * otherwise the live budget broadcast and the multi-localPath sum are lost.
+ * 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();
+    return {
+        diffStatsFetchFactory: platform => platform === 'github'
+            ? new GitHubDiffStatsFetchGateway(defaultGitHubExecutor)
+            : new GitLabDiffStatsFetchGateway(defaultGitLabExecutor),
+        routingPolicyGateway: new ProjectConfigRoutingPolicyGateway(),
+        selectModelForReview: new SelectModelForReviewUseCase(),
+        trackingGateway: new FileSystemReviewRequestTrackingGateway(new ProjectStatsCalculator()),
+        trackTokenUsage: new TrackTokenUsageUseCase(tokenUsageGateway),
+        getBudgetStatus: new GetBudgetStatusUseCase({ budgetGateway, tokenUsageGateway }),
+        budgetStatusPresenter: new BudgetStatusPresenter(),
+        broadcastBudgetStatus: () => { },
+        invocation: createDefaultClaudeInvocationDeps(),
+    };
+}
 const currentDir = dirname(fileURLToPath(import.meta.url));
 export function resolveMcpServerPath() {
     // dist/frameworks/claude/claudeInvoker.js → dist/mcpServer.js
@@ -87,15 +176,9 @@ 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, logger) {
+function fetchDiffStatsSafely(job, deps, logger) {
     try {
-        const gateway = job.platform === 'github'
-            ? new GitHubDiffStatsFetchGateway(defaultGitHubExecutor)
-            : new GitLabDiffStatsFetchGateway(defaultGitLabExecutor);
+        const gateway = deps.diffStatsFetchFactory(job.platform);
         return gateway.fetchDiffStats(job.projectPath, job.mrNumber);
     }
     catch (error) {
@@ -103,7 +186,7 @@ function fetchDiffStatsSafely(job, logger) {
         return null;
     }
 }
-async function resolveModel(job, diffStats, logger) {
+async function resolveModel(job, diffStats, deps, logger) {
     if (job.model) {
         return job.model;
     }
@@ -117,19 +200,20 @@ async function resolveModel(job, diffStats, logger) {
     catch (error) {
         logger.warn({ jobId: job.id, error }, 'Failed to load project config, using runtime default');
     }
-    const routingGateway = new ProjectConfigRoutingPolicyGateway();
-    const policy = await routingGateway.load(job.localPath);
+    const policy = await deps.routingPolicyGateway.load(job.localPath);
     if (!policy || !diffStats) {
         return defaultModel;
     }
-    const selector = new SelectModelForReviewUseCase();
-    return selector.execute({ diffStats, policy, defaultModel });
+    return deps.selectModelForReview.execute({ diffStats, policy, defaultModel });
 }
 /**
  * Build MCP system prompt for progress tracking
  * This instruction is AUTHORITATIVE and forces Claude to use MCP tools
  */
-function buildMcpSystemPrompt(job) {
+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
 
@@ -166,8 +250,8 @@ These rules are about WRITING production code. You are in **READ-ONLY review mod
 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**: \`glab mr diff ${job.mrNumber}\` — use this, NEVER \`git diff\`.
-**SOURCE OF TRUTH for MR metadata**: \`glab mr view ${job.mrNumber}\` — use this for branch names, title, description.
+**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:**
@@ -240,26 +324,24 @@ ${buildLanguageDirective(job.language ?? 'en')}
  * @param onProgress - Optional callback for progress updates
  * @param signal - Optional AbortSignal to cancel the review
  */
-export async function invokeClaudeReview(job, logger, onProgress, signal) {
+export async function invokeClaudeReview(job, logger, onProgress, signal, deps = createDefaultClaudeInvokerDependencies()) {
     const startTime = Date.now();
     // Build the prompt
     const prompt = `/${job.skill} ${job.mrNumber}`;
     // Fetch diff stats once: reused for both model routing and end-of-review stats
-    const diffStats = fetchDiffStatsSafely(job, logger);
+    const diffStats = fetchDiffStatsSafely(job, deps, logger);
     // Select model: explicit job override > routing policy + diff stats > project default > runtime default
-    const model = await resolveModel(job, diffStats, logger);
+    const model = await resolveModel(job, diffStats, deps, logger);
     // Build MCP system prompt injection
     const mcpSystemPrompt = buildMcpSystemPrompt(job);
     // 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',
         '--append-system-prompt', mcpSystemPrompt,
@@ -267,7 +349,7 @@ export async function invokeClaudeReview(job, logger, onProgress, signal) {
         '--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);
@@ -291,13 +373,6 @@ export async function invokeClaudeReview(job, logger, onProgress, signal) {
         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 });
@@ -307,261 +382,151 @@ export async function invokeClaudeReview(job, logger, onProgress, signal) {
             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'],
+    return invokeViaBackgroundSession({
+        job,
+        prompt,
+        model,
+        mcpSystemPrompt,
+        mcpConfigJson,
+        diffStats,
+        startTime,
+        signal,
+    }, logger, onProgress, deps);
+}
+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';
+    // 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: 'bypassPermissions',
+    };
+    let result;
+    try {
+        result = await runClaudeReviewJob({
+            jobId: job.id,
+            jobType,
+            prompt,
+            flags,
+            localPath: job.localPath,
+            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,
         });
-        // 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);
-            }
+    }
+    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,
         };
-        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) });
-        });
-        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(),
-            });
+    }
+    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');
-            }
-            catch {
-                // Non-critical
-            }
-            // Finalize progress
-            if (memoryExceeded) {
-                progressParser.markFailed('Memory limit exceeded - review killed');
-            }
-            else if (cancelled) {
-                progressParser.markFailed('Annulée par utilisateur');
+                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');
             }
-            else if (success) {
-                progressParser.markAllCompleted();
+            catch (statsError) {
+                logger.warn({ error: statsError }, 'Erreur lors de l\'enregistrement des stats');
             }
-            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 trackingGateway = new FileSystemReviewRequestTrackingGateway(new ProjectStatsCalculator());
-                        const mrDetails = 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 {
-                        const tracker = new TrackTokenUsageUseCase(new FilesystemTokenUsageGateway());
-                        await tracker.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');
-                    }
-                    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