reviewflow 3.12.0 → 3.13.0

package/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.13.0](https://github.com/DGouron/review-flow/compare/reviewflow-v3.12.0...reviewflow-v3.13.0) (2026-05-22)
+
+
+### Added
+
+* **claude-invocation:** implement spec-169 migrate claude -p to --bg mode ([#170](https://github.com/DGouron/review-flow/issues/170)) ([f3e408a](https://github.com/DGouron/review-flow/commit/f3e408af03056bb23017b29b62d811a25e62fb67))
+
 ## [3.12.0](https://github.com/DGouron/review-flow/compare/reviewflow-v3.11.0...reviewflow-v3.12.0) (2026-05-20)
 
 

package/dist/frameworks/claude/claudeInvoker.d.ts

@@ -11,6 +11,25 @@ import { ProjectConfigRoutingPolicyGateway } from '../../modules/review-executio
 import { TrackTokenUsageUseCase } from '../../modules/token-accounting/usecases/trackTokenUsage/trackTokenUsage.usecase.js';
 import { GetBudgetStatusUseCase } from '../../modules/token-accounting/usecases/getBudgetStatus/getBudgetStatus.usecase.js';
 import { BudgetStatusPresenter, type BudgetStatusViewModel } from '../../modules/token-accounting/interface-adapters/presenters/budgetStatus.presenter.js';
+import type { ClaudeSessionGateway } from '../../modules/claude-invocation/entities/claudeSession/claudeSession.gateway.js';
+import type { McpCompletionBridge } from '../../modules/claude-invocation/entities/sessionCompletion/mcpCompletion.gateway.js';
+import type { ReviewReportGateway } from '../../modules/claude-invocation/entities/sessionCompletion/reviewReport.gateway.js';
+import type { BillingStateGateway } from '../../modules/claude-invocation/entities/billingState/billingState.gateway.js';
+import type { EnvironmentGateway } from '../../modules/claude-invocation/entities/billingState/environment.gateway.js';
+/**
+ * Bundle of gateways needed by runClaudeReviewJob. Built in the composition
+ * root so the Fastify process, the supervisor/billing timers, and the MCP
+ * completion bridge can share the same instances.
+ */
+export interface ClaudeInvocationDeps {
+    sessionGateway: ClaudeSessionGateway;
+    completionBridge: McpCompletionBridge;
+    reportGateway: ReviewReportGateway;
+    billingState: BillingStateGateway;
+    environment: EnvironmentGateway;
+    timeoutMs: number;
+    pollIntervalMs: number;
+}
 /**
  * Gateways and use cases required by invokeClaudeReview. Extracted from the
  * function body so production wiring stays in the composition root and tests
@@ -26,6 +45,7 @@ export interface ClaudeInvokerDependencies {
     budgetStatusPresenter: BudgetStatusPresenter;
     broadcastBudgetStatus: (viewModel: BudgetStatusViewModel) => void;
     getEnabledLocalPaths?: () => string[];
+    invocation: ClaudeInvocationDeps;
 }
 /**
  * Default wiring used when invokeClaudeReview is called without explicit deps.
@@ -36,6 +56,15 @@ export interface ClaudeInvokerDependencies {
  * 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 declare function buildSpawnEnv(processEnv: NodeJS.ProcessEnv, override?: Record<string, string>): NodeJS.ProcessEnv;
+export declare function createDefaultClaudeInvocationDeps(): ClaudeInvocationDeps;
 export declare function createDefaultClaudeInvokerDependencies(): ClaudeInvokerDependencies;
 export declare function resolveMcpServerPath(): string;
 export declare function writeMcpContext(job: ReviewJob): void;

package/dist/frameworks/claude/claudeInvoker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claudeInvoker.d.ts","sourceRoot":"","sources":["../../../src/frameworks/claude/claudeInvoker.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"claudeInvoker.d.ts","sourceRoot":"","sources":["../../../src/frameworks/claude/claudeInvoker.ts"],"names":[],"mappings":"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"}

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,12 @@ 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';
 /**
  * Default wiring used when invokeClaudeReview is called without explicit deps.
  *
@@ -34,6 +37,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 +107,7 @@ export function createDefaultClaudeInvokerDependencies() {
         getBudgetStatus: new GetBudgetStatusUseCase({ budgetGateway, tokenUsageGateway }),
         budgetStatusPresenter: new BudgetStatusPresenter(),
         broadcastBudgetStatus: () => { },
+        invocation: createDefaultClaudeInvocationDeps(),
     };
 }
 const currentDir = dirname(fileURLToPath(import.meta.url));
@@ -116,10 +176,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);
@@ -281,13 +337,11 @@ 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',
         '--append-system-prompt', mcpSystemPrompt,
@@ -295,7 +349,7 @@ export async function invokeClaudeReview(job, logger, onProgress, signal, deps =
         '--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 +373,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 +382,151 @@ 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'],
+    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');
-            }
-            else if (success) {
-                progressParser.markAllCompleted();
+                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 {
-                progressParser.markFailed(`Exit code: ${code}`);
+            catch (statsError) {
+                logger.warn({ error: statsError }, 'Erreur lors de l\'enregistrement des stats');
             }
-            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