codex.ts

import { Provider, ProviderExecutionPolicy } from './base';
import { Finding, ReviewResult } from '../types';
import { logger } from '../utils/logger';
import { spawn, spawnSync } from 'child_process';
import * as fs from 'fs/promises';
import * as fsSync from 'fs';
import * as os from 'os';
import * as path from 'path';
import * as crypto from 'crypto';
import { estimateTokensSimple } from '../utils/token-estimation';
import { buildCliSafeEnv } from './cli-env';
import { prepareCodexCliBeforeAuthRead } from '../codex-oauth/codex-cli';
import {
  buildReviewFindingsSchema,
  type ParsedReviewOutput,
  parseReviewOutputStrict,
  parseReviewFindingsStrict,
} from './review-output';

export interface CodexProviderOptions {
  agenticContext?: boolean;
  eventAudit?: boolean;
  modelProvider?: 'openai' | 'openrouter';
  providerNamePrefix?: 'codex' | 'codex-openrouter' | 'openrouter';
  providerNameModel?: string;
}

type CodexRunOptions = {
  healthCheck: boolean;
  outputSchema?: unknown;
  eventAudit?: boolean;
  jsonEvents?: boolean;
  cwd?: string;
  includeWorkspaceEnv?: boolean;
  disableTools?: boolean;
  skipGitRepoCheck?: boolean;
  acceptReviewOutputOnNonZero?: boolean;
};

type CodexRunResult = {
  stdout: string;
  stderr: string;
  lastMessage: string;
  audit?: CodexAgenticAudit;
};

type CodexAgenticAuditMode = 'off' | 'rerun' | 'strict';

const MAX_OPTIONAL_AGENTIC_RETRY_PROMPT_TOKENS = 24_000;

type CodexAgenticAudit = {
  commandExecutions: number;
  readOnlyExplorationCommands: number;
  commands: string[];
};

class CodexCliExitError extends Error {
  constructor(
    readonly code: number | null,
    readonly stdout: string,
    readonly stderr: string,
    message: string
  ) {
    super(message);
    this.name = 'CodexCliExitError';
  }
}

export class CodexProvider extends Provider {
  private static preparedBinaryPath: string | undefined;

  constructor(
    private readonly model: string,
    private readonly options: CodexProviderOptions = {}
  ) {
    super(
      `${options.providerNamePrefix || 'codex'}/${options.providerNameModel || model}`
    );
  }

  // Verify the CLI is available. Model/auth failures are surfaced by the real
  // review call; a model-exec health check costs an extra Codex subscription
  // request and can exhaust limited OAuth usage before review starts.
  async healthCheck(_timeoutMs: number = 5000): Promise<boolean> {
    const timeoutMs = Math.max(500, _timeoutMs ?? 5000);
    const mode = (process.env.CODEX_HEALTHCHECK_MODE || 'binary').toLowerCase();

    if (mode === 'none' || mode === 'binary') {
      return true;
    }

    let timeoutId: NodeJS.Timeout;
    let isTimedOut = false;

    const timeoutPromise = new Promise<never>((_, reject) => {
      timeoutId = setTimeout(() => {
        isTimedOut = true;
        reject(new Error(`Codex health check timed out after ${timeoutMs}ms`));
      }, timeoutMs);
    });

    try {
      const binary = await Promise.race([
        this.resolveBinary().then((resolved) => {
          if (isTimedOut) {
            logger.debug(`Codex binary resolved after timeout (${this.name})`);
          }
          return resolved;
        }),
        timeoutPromise,
      ]);
      clearTimeout(timeoutId!);

      const result = await this.runCliWithStdin(
        binary,
        'Respond with exactly: codex-health-ok',
        timeoutMs,
        { healthCheck: true }
      );
      const output = result.lastMessage || result.stdout;

      if (!output.includes('codex-health-ok')) {
        logger.warn(
          `Codex health check returned unexpected output for ${this.name}`
        );
        return false;
      }

      return true;
    } catch (error) {
      if (timeoutId!) {
        clearTimeout(timeoutId);
      }
      logger.warn(
        `Codex health check failed for ${this.name}: ${(error as Error).message}`
      );
      return false;
    }
  }

  async review(
    prompt: string,
    timeoutMs: number,
    executionPolicy?: ProviderExecutionPolicy
  ): Promise<ReviewResult> {
    const started = Date.now();

    const binary = await this.resolveBinary();

    const agenticContext = this.shouldUseAgenticContext();
    const promptForCodex = agenticContext
      ? await this.wrapAgenticReviewPrompt(prompt)
      : this.wrapPromptOnlyReviewPrompt(prompt);
    const auditMode = agenticContext ? this.agenticAuditMode() : 'off';
    const eventAudit = this.shouldUseEventAudit();

    logger.info(
      `Running Codex CLI safely: codex exec --model ${this.model} --sandbox read-only --ephemeral ...`
    );

    try {
      const initialTimeoutMs =
        executionPolicy?.clampTimeoutMs(timeoutMs) ?? timeoutMs;
      if (initialTimeoutMs <= 0) {
        const deadlineError = new Error(
          'Review execution deadline reached before Codex invocation'
        );
        deadlineError.name = 'TimeoutError';
        throw deadlineError;
      }
      let runResult = await this.runCliWithStdin(
        binary,
        promptForCodex,
        initialTimeoutMs,
        {
          healthCheck: false,
          outputSchema: this.buildFindingsSchema(),
          eventAudit,
          jsonEvents: auditMode !== 'off',
          acceptReviewOutputOnNonZero: true,
        }
      );
      let content = this.sanitizeReviewContent(
        (runResult.lastMessage || runResult.stdout).trim()
      );
      if (runResult.audit) {
        this.logAgenticAudit(runResult.audit, false);
      }
      let parsed = this.parseNonEmptyReviewContent(content, runResult.stderr);

      if (
        this.shouldRetryForMissingAgenticExploration(
          parsed,
          runResult.audit,
          prompt,
          auditMode
        ) &&
        (executionPolicy?.canStartOptionalRetry() ?? true)
      ) {
        logger.warn(
          `Codex agentic review completed without read-only exploration; retrying once for ${this.name}`
        );
        const firstContent = content;
        const firstParsed = parsed;
        const firstRunResult = runResult;
        try {
          const retryTimeoutMs =
            executionPolicy?.clampTimeoutMs(timeoutMs) ?? timeoutMs;
          if (retryTimeoutMs <= 0) {
            throw new Error(
              'Review execution deadline reached before Codex agentic retry'
            );
          }
          runResult = await this.runCliWithStdin(
            binary,
            this.buildAgenticRetryPrompt(promptForCodex, runResult.audit),
            retryTimeoutMs,
            {
              healthCheck: false,
              outputSchema: this.buildFindingsSchema(),
              eventAudit,
              jsonEvents: true,
              acceptReviewOutputOnNonZero: true,
            }
          );
          content = this.sanitizeReviewContent(
            (runResult.lastMessage || runResult.stdout).trim()
          );
          if (runResult.audit) {
            this.logAgenticAudit(runResult.audit, true);
          }
          parsed = this.parseNonEmptyReviewContent(content, runResult.stderr);
        } catch (retryError) {
          if (auditMode === 'strict') {
            throw retryError;
          }
          const normalizedRetryError = this.normalizeCodexError(retryError);
          logger.warn(
            `Codex agentic retry failed for ${this.name}; preserving first-pass findings. ${normalizedRetryError.message}`
          );
          content = firstContent;
          parsed = firstParsed;
          runResult = firstRunResult;
        }
        if (
          runResult !== firstRunResult &&
          this.isMissingAgenticExploration(parsed, runResult.audit, prompt) &&
          firstParsed.findings.length >= parsed.findings.length
        ) {
          logger.warn(
            `Codex agentic retry still lacked read-only exploration and did not add findings; preserving first-pass findings for ${this.name}`
          );
          content = firstContent;
          parsed = firstParsed;
          runResult = firstRunResult;
        }
      }

      if (
        auditMode === 'strict' &&
        this.isMissingAgenticExploration(parsed, runResult.audit, prompt)
      ) {
        throw new Error(
          'Codex agentic review completed without recorded read-only repository exploration'
        );
      }

      const durationSeconds = (Date.now() - started) / 1000;
      logger.info(
        `Codex CLI output for ${this.name}: final=${content.length} bytes, stdout=${runResult.stdout.length} bytes, stderr=${runResult.stderr.length} bytes, duration=${durationSeconds.toFixed(1)}s`
      );

      return {
        content,
        durationSeconds,
        usage: this.estimateUsage(prompt, content),
        findings: parsed.findings,
        revalidations: parsed.revalidations,
      };
    } catch (error) {
      const normalized = this.normalizeCodexError(error);
      logger.error(`Codex provider failed: ${this.name}`, normalized);
      throw normalized;
    }
  }

  async runStructuredPrompt(
    prompt: string,
    outputSchema: unknown,
    timeoutMs: number,
    options: {
      cwd?: string;
      eventAudit?: boolean;
      includeWorkspaceEnv?: boolean;
      skipGitRepoCheck?: boolean;
    } = {}
  ): Promise<string> {
    const binary = await this.resolveBinary();
    const { stdout, stderr, lastMessage } = await this.runCliWithStdin(
      binary,
      prompt,
      timeoutMs,
      {
        healthCheck: false,
        outputSchema,
        eventAudit: options.eventAudit,
        cwd: options.cwd,
        includeWorkspaceEnv: options.includeWorkspaceEnv,
        disableTools: true,
        skipGitRepoCheck: options.skipGitRepoCheck,
      }
    );
    const content = this.sanitizeReviewContent((lastMessage || stdout).trim());
    if (!content) {
      throw new Error(
        `Codex CLI returned no output${stderr ? `; stderr: ${stderr.slice(0, 200)}` : ''}`
      );
    }
    return content;
  }

  private estimateUsage(prompt: string, content: string) {
    const promptTokens = estimateTokensSimple(prompt).tokens;
    const completionTokens = estimateTokensSimple(content).tokens;

    return {
      promptTokens,
      completionTokens,
      totalTokens: promptTokens + completionTokens,
    };
  }

  private buildExecArgs(options: {
    healthCheck: boolean;
    outputLastMessageFile: string;
    outputSchemaFile?: string;
    eventAudit?: boolean;
    jsonEvents?: boolean;
    disableTools?: boolean;
    skipGitRepoCheck?: boolean;
  }): string[] {
    // The top-level `codex` command starts the interactive TUI and fails in CI.
    const args = [
      'exec',
      '--model',
      this.model,
      '--sandbox',
      'read-only',
      '--ephemeral',
      '--ignore-rules',
      '-c',
      'approval_policy=never',
      '--output-last-message',
      options.outputLastMessageFile,
    ];

    if (!this.shouldUseForkSandboxCodexHomeConfig()) {
      args.splice(args.indexOf('--ignore-rules'), 0, '--ignore-user-config');
    }

    if (options.skipGitRepoCheck) {
      args.splice(1, 0, '--skip-git-repo-check');
    }

    if (options.disableTools) {
      args.push(
        '--disable',
        'shell_tool',
        '--disable',
        'unified_exec',
        '--disable',
        'browser_use',
        '--disable',
        'computer_use',
        '--disable',
        'js_repl',
        '--disable',
        'tool_search',
        '--disable',
        'web_search_request',
        '--disable',
        'plugins'
      );
    }

    if (options.outputSchemaFile) {
      args.push('--output-schema', options.outputSchemaFile);
    }

    if (options.eventAudit || options.jsonEvents) {
      args.push('--json');
    }

    const effort = options.healthCheck
      ? process.env.CODEX_HEALTHCHECK_REASONING_EFFORT || 'low'
      : process.env.CODEX_REASONING_EFFORT;

    if (effort) {
      const normalized = effort.trim().toLowerCase();
      if (/^[a-z]+$/.test(normalized)) {
        args.push('-c', `model_reasoning_effort="${normalized}"`);
      }
    }

    if (this.options.modelProvider === 'openrouter') {
      args.push(
        '-c',
        'model_provider="openrouter"',
        '-c',
        'model_providers.openrouter.name="openrouter"',
        '-c',
        'model_providers.openrouter.base_url="https://openrouter.ai/api/v1"',
        '-c',
        'model_providers.openrouter.env_key="OPENROUTER_API_KEY"'
      );
    }

    args.push('-');
    return args;
  }

  private async runCliWithStdin(
    bin: string,
    stdin: string,
    timeoutMs: number,
    options: CodexRunOptions
  ): Promise<CodexRunResult> {
    // Write prompt to temporary file to avoid TTY check issues
    // Use restrictive permissions (0600) since prompt may contain sensitive PR diffs
    const runId = crypto.randomBytes(8).toString('hex');
    const tmpFile = path.join(os.tmpdir(), `codex-prompt-${runId}.txt`);
    const outputFile = path.join(os.tmpdir(), `codex-output-${runId}.txt`);
    const schemaFile = options.outputSchema
      ? path.join(os.tmpdir(), `codex-schema-${runId}.json`)
      : undefined;
    let fd: fs.FileHandle | undefined;
    try {
      await fs.writeFile(tmpFile, stdin, { encoding: 'utf8', mode: 0o600 });
      await fs.writeFile(outputFile, '', { encoding: 'utf8', mode: 0o600 });
      if (schemaFile) {
        await fs.writeFile(schemaFile, JSON.stringify(options.outputSchema), {
          encoding: 'utf8',
          mode: 0o600,
        });
      }

      const args = this.buildExecArgs({
        healthCheck: options.healthCheck,
        outputLastMessageFile: outputFile,
        outputSchemaFile: schemaFile,
        eventAudit: options.eventAudit && !options.healthCheck,
        jsonEvents: options.jsonEvents && !options.healthCheck,
        disableTools: options.disableTools,
        skipGitRepoCheck: options.skipGitRepoCheck,
      });

      // Use stdin redirection via file descriptor instead of shell
      // This avoids both "stdin is not a terminal" error and shell injection
      fd = await fs.open(tmpFile, 'r');
      const fdNum = fd.fd;

      const { stdout, stderr } = await new Promise<{
        stdout: string;
        stderr: string;
      }>((resolve, reject) => {
        const proc = spawn(bin, args, {
          stdio: [fdNum, 'pipe', 'pipe'],
          detached: true,
          cwd: options.cwd || process.cwd(),
          env: this.buildSafeEnv(options.includeWorkspaceEnv !== false),
        });

        let stdout = '';
        let stderr = '';
        let timedOut = false;

        const timer = setTimeout(() => {
          timedOut = true;
          logger.warn(
            `Codex CLI timeout (${timeoutMs}ms), killing process and all children`
          );

          try {
            if (proc.pid) {
              process.kill(-proc.pid, 'SIGKILL');
            }
          } catch {
            proc.kill('SIGKILL');
          }

          reject(new Error(`Codex CLI timed out after ${timeoutMs}ms`));
        }, timeoutMs);

        proc.stdout?.on('data', (chunk) => {
          stdout += chunk.toString();
        });
        proc.stderr?.on('data', (chunk) => {
          stderr += chunk.toString();
        });
        proc.on('error', (err) => {
          if (!timedOut) {
            clearTimeout(timer);
            reject(err);
          }
        });
        proc.on('close', (code) => {
          if (!timedOut) {
            clearTimeout(timer);
            if (code !== 0) {
              const message = `Codex CLI failed with exit code ${code}: ${this.formatCliError(stderr, stdout)}`;
              reject(new CodexCliExitError(code, stdout, stderr, message));
            } else {
              resolve({ stdout, stderr });
            }
          }
        });
      }).catch(async (error) => {
        const lastMessage = await this.readOptionalFile(outputFile);
        if (
          options.acceptReviewOutputOnNonZero &&
          this.isUsableReviewOutput(lastMessage)
        ) {
          const exitError =
            error instanceof CodexCliExitError ? error : undefined;
          logger.warn(
            `Codex CLI exited non-zero for ${this.name} but produced valid review JSON; using --output-last-message`
          );
          return {
            stdout: exitError?.stdout || '',
            stderr: exitError?.stderr || '',
          };
        }

        throw error;
      });

      const lastMessage = await this.readOptionalFile(outputFile);
      if (options.eventAudit && !options.healthCheck) {
        this.logEventAudit(stdout);
      }

      return {
        stdout,
        stderr,
        lastMessage,
        audit:
          !options.healthCheck && (options.jsonEvents || options.eventAudit)
            ? this.buildAgenticAudit(stdout)
            : undefined,
      };
    } finally {
      // Clean up temp file and file descriptor
      try {
        if (fd) {
          await fd.close();
        }
        await fs.unlink(tmpFile);
        await fs.unlink(outputFile);
        if (schemaFile) {
          await fs.unlink(schemaFile);
        }
      } catch {
        // Ignore cleanup errors
      }
    }
  }

  private shouldUseAgenticContext(): boolean {
    if (this.options.agenticContext !== undefined) {
      return this.options.agenticContext;
    }
    return this.parseBooleanEnv(process.env.CODEX_AGENTIC_CONTEXT, true);
  }

  private shouldUseEventAudit(): boolean {
    if (this.options.eventAudit !== undefined) {
      return this.options.eventAudit;
    }
    return this.parseBooleanEnv(process.env.CODEX_EVENT_AUDIT, false);
  }

  private agenticAuditMode(): CodexAgenticAuditMode {
    const raw = process.env.CODEX_AGENTIC_AUDIT?.trim().toLowerCase();
    if (!raw) {
      return 'rerun';
    }
    if (['0', 'false', 'no', 'off'].includes(raw)) {
      return 'off';
    }
    if (raw === '1' || raw === 'true' || raw === 'yes' || raw === 'on') {
      return 'rerun';
    }
    if (raw === 'rerun' || raw === 'strict') {
      return raw;
    }
    logger.warn(
      `Unknown CODEX_AGENTIC_AUDIT value "${raw}", falling back to rerun`
    );
    return 'rerun';
  }

  private parseNonEmptyReviewContent(
    content: string,
    stderr: string
  ): ParsedReviewOutput {
    if (!content) {
      throw new Error(
        `Codex CLI returned no output${stderr ? `; stderr: ${stderr.slice(0, 200)}` : ''}`
      );
    }
    return parseReviewOutputStrict(content, 'Codex CLI');
  }

  private shouldRetryForMissingAgenticExploration(
    parsed: ParsedReviewOutput,
    audit: CodexAgenticAudit | undefined,
    prompt: string,
    mode: CodexAgenticAuditMode
  ): boolean {
    if (
      (mode !== 'rerun' && mode !== 'strict') ||
      !this.isMissingAgenticExploration(parsed, audit, prompt)
    ) {
      return false;
    }
    if (mode === 'strict') return true;

    const promptTokens = estimateTokensSimple(prompt).tokens;
    if (promptTokens > MAX_OPTIONAL_AGENTIC_RETRY_PROMPT_TOKENS) {
      logger.info(
        `Skipping optional Codex agentic retry for ${this.name}: prompt is approximately ${promptTokens} tokens (limit ${MAX_OPTIONAL_AGENTIC_RETRY_PROMPT_TOKENS})`
      );
      return false;
    }
    return true;
  }

  private isMissingAgenticExploration(
    parsed: ParsedReviewOutput,
    audit: CodexAgenticAudit | undefined,
    prompt: string
  ): boolean {
    if (!this.looksLikePullRequestReviewPrompt(prompt)) return false;
    return !audit || audit.readOnlyExplorationCommands === 0;
  }

  private looksLikePullRequestReviewPrompt(prompt: string): boolean {
    return (
      prompt.includes('Files changed:') ||
      prompt.includes('Diff:') ||
      /^diff --git a\//m.test(prompt)
    );
  }

  private buildAgenticRetryPrompt(
    prompt: string,
    audit?: CodexAgenticAudit
  ): string {
    const commands =
      audit && audit.commands.length > 0
        ? audit.commands.slice(0, 5).join(' | ')
        : 'none recorded';

    return [
      'Your previous Codex review pass completed without enough recorded read-only repository exploration.',
      `Recorded commands: ${commands}`,
      '',
      'Rerun the review from scratch.',
      'Before final JSON, inspect changed hunks and at least one related caller, test, schema, config, or helper file when available using read-only commands such as git diff, git show, rg, git grep, sed, cat, ls, find, pwd, nl, head, or tail.',
      'Changed helper/API contract regressions are reportable bugs when callers will behave incorrectly, even if the broken behavior is indirect.',
      'Specifically check for inverted boolean/filter/ignore semantics, dropped structured fields, broken draft/recovery/delete flows, stale cache/list summaries, workflow routing regressions, auth/config mistakes, and persistence side effects.',
      'If exploration proves there is no concrete bug, return exactly {"findings":[],"revalidations":[]}.',
      '',
      prompt,
    ].join('\n');
  }

  private parseBooleanEnv(
    value: string | undefined,
    defaultValue: boolean
  ): boolean {
    if (value === undefined || value === '') return defaultValue;
    return !['0', 'false', 'no', 'off'].includes(value.trim().toLowerCase());
  }

  private async wrapAgenticReviewPrompt(prompt: string): Promise<string> {
    const contextSeed = await this.buildRepositoryContextSeed(prompt);

    return [
      'You are running as review-router inside GitHub Actions.',
      '',
      'Use the deterministic PR context below as the source of truth for review scope.',
      contextSeed,
      contextSeed ? '' : '',
      'You may inspect related repository files before producing findings, but only with read-only shell commands such as rg, sed, cat, git diff, git show, git grep, ls, find, and pwd.',
      'Before deciding whether findings is empty or non-empty, run read-only exploration commands: inspect changed source files with git diff/sed, then use rg/git grep on imported or changed symbols to find related files.',
      'Inspect at least one directly related file when available, such as imports, called modules, schema/config files, tests, or callers.',
      '',
      'Universal context discovery checklist:',
      '- First identify the project ecosystems from changed file extensions plus nearby manifests, lockfiles, workspace files, and build config such as package.json, pnpm-workspace.yaml, tsconfig.json, pubspec.yaml, pubspec.lock, go.mod, Cargo.toml, pyproject.toml, requirements.txt, pom.xml, build.gradle, composer.json, Gemfile, Dockerfile, Makefile, and CI workflow files.',
      '- For every changed symbol or behavior, trace the nearest imports/includes/exports, dependency injection registrations, routes/controllers, schema files, generated protocol files, database migrations, ORM models, event names, feature flags, cache keys, permissions, and public API contracts before reporting a finding.',
      '- Prefer repo-local evidence: sibling implementations, previous patterns, tests, mocks, fixtures, generated clients, migration history, and direct callers/callees found with rg/git grep.',
      '- For dependencies, inspect committed lockfiles and already available read-only package source/cache directories when present. If dependency source is unavailable and repo-local evidence is not enough, treat the issue as insufficiently proven instead of guessing.',
      '- For large PRs, prioritize changed files with security, auth, persistence, migrations, concurrency, realtime/eventing, billing, external API, public contract, or data-loss impact before low-risk formatting or generated files.',
      '',
      'For CRUD, realtime, cache, or repository-state changes, explicitly compare create/update/delete side effects, broadcasts, invalidation, and listener update paths.',
      'For destructive operations such as delete/remove/archive/revoke/cancel, distinguish direct caller response handling from global side effects. A local API response that updates only the caller does not prove other open clients, subscribers, caches, workers, or projections are invalidated. If create/update paths broadcast, invalidate, enqueue, or publish but the new destructive path does not, report it when the changed line is the destructive config/call and no framework evidence proves equivalent global propagation.',
      'When a changed file uses framework APIs from a dependency, you may inspect read-only language package caches referenced by lockfiles, such as ~/.pub-cache/git, but never inspect secrets or credentials.',
      'Do not produce the final JSON until this context exploration is complete.',
      'When a finding depends on related context, cite the concrete related file evidence in the message.',
      'Use repository-relative paths only. Do not include absolute local filesystem paths in findings.',
      'Do not read environment variables, secret files, ~/.codex, git credentials, or GitHub token files.',
      'Do not run package installation, tests, builds, formatters, network commands, or commands that write files.',
      'Do not return empty findings until you inspected the changed hunks and at least one related caller, test, schema, config, or helper file when available.',
      'Only report real bugs on changed lines from the diff: crashes, data loss, security vulnerabilities, clear user-visible functional regressions such as permanent loading, stale UI state, dead-end navigation, hidden required content, or wrong access control state, or changed helper/API contract regressions that will break callers, tests, workflows, persistence, auth, configuration, MCP tools, or public/internal APIs.',
      'Changed helper contracts and semantic inversions are reportable even when the failure is indirect, if callers will behave incorrectly.',
      'Specifically check for inverted boolean/filter/ignore semantics, dropped non-string structured fields, broken draft/recovery/delete flows, stale cache/list summaries, workflow routing regressions, auth/config mistakes, and persistence side effects.',
      'A repeated local repository pattern, adjacent implementation, generated protocol/schema file, or direct dependency source counts as concrete evidence. If there is still no concrete evidence after exploration, return no finding rather than guessing.',
      '',
      '<deterministic_review_prompt>',
      prompt,
      '</deterministic_review_prompt>',
      '',
      'FINAL OUTPUT CONTRACT:',
      'Return exactly one JSON object matching this shape: {"findings":[{"file":"path","startLine":null,"line":1,"endLine":null,"severity":"major","title":"short","message":"specific evidence","suggestion":null}],"revalidations":[{"targetId":"rrt_example","fingerprint":"abc","verdict":"resolved","confidence":0.9,"evidence":[{"path":"src/file.ts","startLine":1,"endLine":2,"reason":"why current code fixes it"}],"rationale":"short reason"}]}',
      'Return ONLY one valid JSON object.',
      'No markdown, no prose, no code fences, comments, trailing commas, or text before/after the JSON.',
      'If no findings, return exactly {"findings":[],"revalidations":[]}.',
      'The "findings" array may be empty. "severity" must be one of "critical", "major", or "minor".',
      'The "revalidations" array may be empty. Include entries only for targetId values listed in the deterministic prompt.',
      'When the issue covers a changed block, set "startLine" to the first affected RIGHT-side line and "endLine" to the last affected RIGHT-side line; keep "line" equal to "endLine". For single-line findings, set "startLine" and "endLine" to null.',
      'The "suggestion" field is required by schema; use null unless there is an exact safe replacement.',
      'Do not return markdown, prose, or a bare JSON array.',
    ]
      .filter((line) => line !== undefined)
      .join('\n');
  }

  private wrapPromptOnlyReviewPrompt(prompt: string): string {
    return [
      'Use the deterministic PR context below. Do not assume access to extra context.',
      '',
      '<deterministic_review_prompt>',
      prompt,
      '</deterministic_review_prompt>',
      '',
      'FINAL OUTPUT CONTRACT:',
      'Return exactly one JSON object matching this shape: {"findings":[{"file":"path","startLine":null,"line":1,"endLine":null,"severity":"major","title":"short","message":"specific evidence","suggestion":null}],"revalidations":[{"targetId":"rrt_example","fingerprint":"abc","verdict":"resolved","confidence":0.9,"evidence":[{"path":"src/file.ts","startLine":1,"endLine":2,"reason":"why current code fixes it"}],"rationale":"short reason"}]}',
      'Return ONLY one valid JSON object.',
      'No markdown, no prose, no code fences, comments, trailing commas, or text before/after the JSON.',
      'If no findings, return exactly {"findings":[],"revalidations":[]}.',
      'The "findings" array may be empty. The "suggestion" field is required and may be null.',
      'The "revalidations" array may be empty. Include entries only for targetId values listed in the deterministic prompt.',
      'When the issue covers a changed block, set "startLine" to the first affected RIGHT-side line and "endLine" to the last affected RIGHT-side line; keep "line" equal to "endLine". For single-line findings, set "startLine" and "endLine" to null.',
      'Do not return markdown, prose, or a bare JSON array.',
    ].join('\n');
  }

  private buildFindingsSchema(): unknown {
    return buildReviewFindingsSchema();
  }

  private buildSafeEnv(includeWorkspaceEnv = true): NodeJS.ProcessEnv {
    return buildCliSafeEnv({
      includeWorkspaceEnv:
        includeWorkspaceEnv && !this.shouldUseForkSandboxCodexHomeConfig(),
      extraAllowedKeys: [
        'CODEX_HOME',
        'OPENAI_API_KEY',
        ...(this.options.modelProvider === 'openrouter'
          ? ['OPENROUTER_API_KEY']
          : []),
      ],
    });
  }

  private shouldUseForkSandboxCodexHomeConfig(): boolean {
    return this.parseBooleanEnv(
      process.env.REVIEWROUTER_FORK_AGENTIC_SANDBOX,
      false
    );
  }

  private sanitizeReviewContent(content: string): string {
    const cwd = process.cwd().replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
    return content
      .replace(new RegExp(`${cwd}/?`, 'g'), '')
      .replace(/\/home\/runner\/work\/[^/\s")]+\/[^/\s")]+\//g, '')
      .replace(/\/private\/tmp\/[^/\s")]+\//g, '');
  }

  private async buildRepositoryContextSeed(prompt: string): Promise<string> {
    const changedFiles = this.extractChangedFiles(prompt)
      .filter((file) => this.isContextReadableFile(file))
      .slice(0, 5);

    if (changedFiles.length === 0) {
      return '';
    }

    const snippets: string[] = [];
    const relatedFiles = new Set<string>();

    for (const file of changedFiles) {
      const content = await this.readRepoFileSnippet(file);
      if (!content) continue;

      snippets.push(this.formatContextSnippet(file, 'changed', content));
      for (const related of this.extractRelatedImportFiles(file, content)) {
        if (this.isContextReadableFile(related)) {
          relatedFiles.add(related);
        }
      }
    }

    for (const related of this.findIdentifierRelatedFiles(changedFiles)) {
      if (this.isContextReadableFile(related)) {
        relatedFiles.add(related);
      }
    }

    for (const file of [...relatedFiles]
      .filter((file) => !changedFiles.includes(file))
      .slice(0, 8)) {
      const content = await this.readRepoFileSnippet(file);
      if (content) {
        snippets.push(this.formatContextSnippet(file, 'related', content));
      }
    }

    if (snippets.length === 0) {
      return '';
    }

    return [
      'DETERMINISTIC REPOSITORY CONTEXT SEED:',
      'These snippets were read before Codex agentic exploration. Use them as evidence, but only comment on changed lines.',
      ...snippets,
      'END DETERMINISTIC REPOSITORY CONTEXT SEED',
    ].join('\n');
  }

  private extractChangedFiles(prompt: string): string[] {
    const files = new Set<string>();
    const fileListPattern =
      /^- ([^\s]+) \((?:added|modified|removed|renamed|changed)/gm;
    let match;

    while ((match = fileListPattern.exec(prompt)) !== null) {
      files.add(match[1]);
    }

    const diffPattern = /^diff --git a\/(.+?) b\/(.+?)$/gm;
    while ((match = diffPattern.exec(prompt)) !== null) {
      files.add(match[2]);
    }

    return [...files];
  }

  private isContextReadableFile(file: string): boolean {
    const normalized = this.normalizeRepoPath(file);
    if (!normalized) return false;
    const lower = normalized.toLowerCase();

    if (
      lower.includes('/.git/') ||
      lower.includes('/.codex/') ||
      lower.includes('.env') ||
      lower.includes('secret') ||
      lower.includes('credential') ||
      lower.endsWith('.pem') ||
      lower.endsWith('.key') ||
      lower.endsWith('auth.json')
    ) {
      return false;
    }

    return /\.(?:[cm]?js|jsx|tsx?|py|go|rs|java|kt|kts|dart|rb|php|cs|cpp|c|h|hpp|swift|scala|json|ya?ml|toml|sql|graphql|proto)$/i.test(
      normalized
    );
  }

  private normalizeRepoPath(file: string): string | null {
    if (!file || file.includes('\0') || path.isAbsolute(file)) {
      return null;
    }

    const normalized = path.normalize(file).replace(/\\/g, '/');
    if (
      normalized === '.' ||
      normalized.startsWith('../') ||
      normalized === '..'
    ) {
      return null;
    }

    return normalized;
  }

  private async readRepoFileSnippet(file: string): Promise<string> {
    const normalized = this.normalizeRepoPath(file);
    if (!normalized) return '';

    const repoRoot = process.cwd();
    const fullPath = path.resolve(repoRoot, normalized);
    if (!fullPath.startsWith(repoRoot + path.sep)) {
      return '';
    }

    try {
      const stat = await fs.stat(fullPath);
      if (!stat.isFile() || stat.size > 200_000) {
        return '';
      }

      const content = await fs.readFile(fullPath, 'utf8');
      return content.split(/\r?\n/).slice(0, 220).join('\n').slice(0, 16_000);
    } catch {
      return '';
    }
  }

  private extractRelatedImportFiles(
    fromFile: string,
    content: string
  ): string[] {
    const imports = new Set<string>();
    const importPattern =
      /(?:import\s+(?:[^'"]+\s+from\s+)?|export\s+[^'"]+\s+from\s+|require\(|import\s+|export\s+)\s*['"]([^'"]+)['"]/g;
    let match;

    while ((match = importPattern.exec(content)) !== null) {
      const specifier = match[1];
      const resolved = specifier.startsWith('.')
        ? this.resolveRelativeImport(fromFile, specifier)
        : this.resolvePackageImport(specifier);
      if (resolved) imports.add(resolved);
    }

    return [...imports];
  }

  private resolveRelativeImport(
    fromFile: string,
    specifier: string
  ): string | null {
    const base = path.dirname(fromFile);
    const raw = this.normalizeRepoPath(path.join(base, specifier));
    if (!raw) return null;

    const candidates = [
      raw,
      ...['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.json'].map(
        (ext) => `${raw}${ext}`
      ),
      ...['.ts', '.tsx', '.js', '.jsx', '.json'].map((ext) =>
        path.posix.join(raw, `index${ext}`)
      ),
    ];

    for (const candidate of candidates) {
      const normalized = this.normalizeRepoPath(candidate);
      if (!normalized || !this.isContextReadableFile(normalized)) continue;
      try {
        const fullPath = path.resolve(process.cwd(), normalized);
        if (fullPath.startsWith(process.cwd() + path.sep)) {
          const stat = fsSync.statSync(fullPath);
          if (stat.isFile()) return normalized;
        }
      } catch {
        // Try next candidate.
      }
    }

    return null;
  }

  private resolvePackageImport(specifier: string): string | null {
    const match = /^package:([^/]+)\/(.+)$/.exec(specifier);
    if (!match) return null;

    const [, packageName, packagePath] = match;
    const roots = this.getWorkspacePackageRoots();
    const root =
      roots.get(packageName) || this.getDependencyPackageRoot(packageName);
    if (!root) return null;

    return this.resolveImportCandidate(path.posix.join(root, packagePath));
  }

  private getDependencyPackageRoot(packageName: string): string | null {
    if (!this.parseBooleanEnv(process.env.CODEX_DEPENDENCY_CONTEXT, true)) {
      return null;
    }

    const dependency = this.findGitDependency(packageName);
    if (!dependency) return null;

    const safePackage = packageName.replace(/[^a-zA-Z0-9_.-]/g, '_');
    const cacheKey = crypto
      .createHash('sha1')
      .update(`${dependency.url}:${dependency.ref}:${dependency.path}`)
      .digest('hex')
      .slice(0, 10);
    const checkoutDir = path.join(
      process.cwd(),
      '.review-router-deps',
      `${safePackage}-${cacheKey}`
    );
    const root = path.posix.join(
      '.review-router-deps',
      `${safePackage}-${cacheKey}`,
      dependency.path
    );

    if (fsSync.existsSync(path.join(checkoutDir, dependency.path))) {
      return root;
    }

    if (!this.isSafeDependencyGitUrl(dependency.url)) {
      logger.debug(
        `Skipping dependency context for ${packageName}: unsupported git URL`
      );
      return null;
    }

    try {
      fsSync.mkdirSync(path.dirname(checkoutDir), { recursive: true });
      fsSync.rmSync(checkoutDir, { recursive: true, force: true });
      fsSync.mkdirSync(checkoutDir, { recursive: true });

      this.runGitForDependency(['init', '--quiet'], checkoutDir);
      this.runGitForDependency(
        ['remote', 'add', 'origin', dependency.url],
        checkoutDir
      );
      this.runGitForDependency(
        ['fetch', '--quiet', '--depth', '1', 'origin', dependency.ref],
        checkoutDir
      );
      this.runGitForDependency(
        ['checkout', '--quiet', 'FETCH_HEAD'],
        checkoutDir
      );

      if (fsSync.existsSync(path.join(checkoutDir, dependency.path))) {
        logger.info(
          `Loaded dependency context for ${packageName} from ${dependency.url}@${dependency.ref}`
        );
        return root;
      }
    } catch (error) {
      logger.debug(
        `Failed to load dependency context for ${packageName}: ${(error as Error).message}`
      );
      fsSync.rmSync(checkoutDir, { recursive: true, force: true });
    }

    return null;
  }

  private findGitDependency(packageName: string): {
    url: string;
    ref: string;
    path: string;
  } | null {
    for (const lockfile of this.findPubspecLockFiles(process.cwd(), 3)) {
      const dependency = this.parseGitDependencyFromLockfile(
        lockfile,
        packageName
      );
      if (dependency) return dependency;
    }
    return null;
  }

  private findPubspecLockFiles(root: string, maxDepth: number): string[] {
    const found: string[] = [];

    const walk = (dir: string, depth: number) => {
      if (depth > maxDepth || found.length >= 50) return;

      let entries: fsSync.Dirent[];
      try {
        entries = fsSync.readdirSync(dir, { withFileTypes: true });
      } catch {
        return;
      }

      if (
        entries.some((entry) => entry.isFile() && entry.name === 'pubspec.lock')
      ) {
        found.push(path.join(dir, 'pubspec.lock'));
      }

      for (const entry of entries) {
        if (!entry.isDirectory()) continue;
        if (this.shouldSkipContextDirectory(entry.name)) continue;
        walk(path.join(dir, entry.name), depth + 1);
      }
    };

    walk(root, 0);
    return found;
  }

  private parseGitDependencyFromLockfile(
    lockfile: string,
    packageName: string
  ): { url: string; ref: string; path: string } | null {
    let content = '';
    try {
      content = fsSync.readFileSync(lockfile, 'utf8');
    } catch {
      return null;
    }

    const escapedName = packageName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
    const blockMatch = new RegExp(
      `^  ${escapedName}:\\n([\\s\\S]*?)(?=^  [^\\s].*:\\n|(?![\\s\\S]))`,
      'm'
    ).exec(content);
    const block = blockMatch?.[1];
    if (!block || !/^\s{4}source:\s+git\s*$/m.test(block)) {
      return null;
    }

    const url = this.extractYamlScalar(block, 'url');
    const dependencyPath = this.extractYamlScalar(block, 'path');
    const ref =
      this.extractYamlScalar(block, 'resolved-ref') ||
      this.extractYamlScalar(block, 'ref');

    if (!url || !dependencyPath || !ref) return null;

    return {
      url,
      ref,
      path: dependencyPath.replace(/^\/+/, ''),
    };
  }

  private extractYamlScalar(block: string, key: string): string | null {
    const match = new RegExp(`^\\s+${key}:\\s+(.+?)\\s*$`, 'm').exec(block);
    if (!match) return null;
    return match[1].replace(/^['"]|['"]$/g, '');
  }

  private isSafeDependencyGitUrl(url: string): boolean {
    return /^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+(?:\.git)?$/.test(
      url
    );
  }

  private runGitForDependency(args: string[], cwd: string): void {
    const result = spawnSync('git', args, {
      cwd,
      encoding: 'utf8',
      timeout: 20_000,
      env: {
        PATH: process.env.PATH || '',
        LANG: process.env.LANG || 'C',
        LC_ALL: process.env.LC_ALL || 'C',
        HOME: path.join(os.tmpdir(), 'review-router-git-home'),
        GIT_TERMINAL_PROMPT: '0',
        GIT_CONFIG_NOSYSTEM: '1',
      },
    });

    if (result.status !== 0) {
      throw new Error(
        `git ${args[0]} failed: ${(result.stderr || result.stdout || '').slice(0, 200)}`
      );
    }
  }

  private getWorkspacePackageRoots(): Map<string, string> {
    const roots = new Map<string, string>();

    for (const pubspec of this.findPubspecFiles(process.cwd(), 3)) {
      try {
        const content = fsSync.readFileSync(pubspec, 'utf8');
        const name = /^name:\s*['"]?([^'"\s#]+)['"]?/m.exec(content)?.[1];
        if (!name) continue;

        const packageDir = path
          .relative(process.cwd(), path.dirname(pubspec))
          .replace(/\\/g, '/');
        const libDir =
          packageDir === '' ? 'lib' : path.posix.join(packageDir, 'lib');
        roots.set(name, libDir);
      } catch {
        // Ignore malformed or unreadable pubspec files.
      }
    }

    return roots;
  }

  private findPubspecFiles(root: string, maxDepth: number): string[] {
    const found: string[] = [];

    const walk = (dir: string, depth: number) => {
      if (depth > maxDepth || found.length >= 50) return;

      let entries: fsSync.Dirent[];
      try {
        entries = fsSync.readdirSync(dir, { withFileTypes: true });
      } catch {
        return;
      }

      if (
        entries.some((entry) => entry.isFile() && entry.name === 'pubspec.yaml')
      ) {
        found.push(path.join(dir, 'pubspec.yaml'));
      }

      for (const entry of entries) {
        if (!entry.isDirectory()) continue;
        if (this.shouldSkipContextDirectory(entry.name)) continue;
        walk(path.join(dir, entry.name), depth + 1);
      }
    };

    walk(root, 0);
    return found;
  }

  private findIdentifierRelatedFiles(changedFiles: string[]): string[] {
    const changedContents = changedFiles
      .map((file) => this.readRepoFileSync(file))
      .filter(Boolean)
      .join('\n');
    if (!changedContents) return [];

    const identifiers = this.extractContextIdentifiers(changedContents);
    if (identifiers.length === 0) return [];

    const candidates = this.findContextCandidateFiles(process.cwd(), 5);
    const changed = new Set(changedFiles);
    const scored: Array<{ file: string; score: number }> = [];

    for (const file of candidates) {
      if (changed.has(file)) continue;

      const content = this.readRepoFileSync(file);
      if (!content) continue;

      let score = 0;
      for (const identifier of identifiers) {
        if (content.includes(identifier))
          score += this.contextIdentifierWeight(identifier);
      }

      if (score > 0) {
        scored.push({ file, score });
      }
    }

    return scored
      .sort((a, b) => b.score - a.score || a.file.localeCompare(b.file))
      .slice(0, 8)
      .map((item) => item.file);
  }

  private extractContextIdentifiers(content: string): string[] {
    const identifiers = new Set<string>();
    const importantPatterns = [
      /\b[A-Z][A-Za-z0-9_]*(?:Config|Provider|Repository|Endpoint|Widget|Dialog|Service)\b/g,
      /\bDw[A-Za-z0-9_]+\b/g,
      /\bUpdateChannels\.[A-Za-z0-9_]+\b/g,
      /\b[a-z][A-Za-z0-9_]*(?:Config|Provider|Repository|Endpoint|Channel|Model|Wrapper)\b/g,
    ];

    for (const pattern of importantPatterns) {
      let match;
      while ((match = pattern.exec(content)) !== null) {
        identifiers.add(match[0]);
      }
    }

    return [...identifiers]
      .filter((identifier) => identifier.length >= 5)
      .filter((identifier) => !this.isNoisyContextIdentifier(identifier))
      .slice(0, 40);
  }

  private contextIdentifierWeight(identifier: string): number {
    if (identifier.startsWith('Dw')) return 4;
    if (identifier.startsWith('UpdateChannels.')) return 4;
    if (/(Config|Repository|Endpoint|Wrapper)$/.test(identifier)) return 3;
    return 1;
  }

  private isNoisyContextIdentifier(identifier: string): boolean {
    return [
      'BuildContext',
      'ConsumerWidget',
      'ConsumerState',
      'ConsumerStatefulWidget',
      'TextEditingController',
      'StatefulWidget',
      'StatelessWidget',
      'Widget',
    ].includes(identifier);
  }

  private findContextCandidateFiles(root: string, maxDepth: number): string[] {
    const files: string[] = [];

    const walk = (dir: string, depth: number) => {
      if (depth > maxDepth || files.length >= 2000) return;

      let entries: fsSync.Dirent[];
      try {
        entries = fsSync.readdirSync(dir, { withFileTypes: true });
      } catch {
        return;
      }

      for (const entry of entries) {
        const fullPath = path.join(dir, entry.name);
        if (entry.isDirectory()) {
          if (!this.shouldSkipContextDirectory(entry.name)) {
            walk(fullPath, depth + 1);
          }
          continue;
        }

        if (!entry.isFile()) continue;

        const relative = path.relative(root, fullPath).replace(/\\/g, '/');
        if (!this.isContextReadableFile(relative)) continue;

        try {
          const stat = fsSync.statSync(fullPath);
          if (stat.size <= 200_000) files.push(relative);
        } catch {
          // Ignore files that disappear during traversal.
        }
      }
    };

    walk(root, 0);
    return files;
  }

  private shouldSkipContextDirectory(name: string): boolean {
    return [
      '.git',
      '.codex',
      '.dart_tool',
      'node_modules',
      'build',
      'dist',
      'coverage',
      '.next',
      '.turbo',
    ].includes(name);
  }

  private readRepoFileSync(file: string): string {
    const normalized = this.normalizeRepoPath(file);
    if (!normalized) return '';

    const repoRoot = process.cwd();
    const fullPath = path.resolve(repoRoot, normalized);
    if (!fullPath.startsWith(repoRoot + path.sep)) return '';

    try {
      const stat = fsSync.statSync(fullPath);
      if (!stat.isFile() || stat.size > 200_000) return '';
      return fsSync.readFileSync(fullPath, 'utf8');
    } catch {
      return '';
    }
  }

  private resolveImportCandidate(raw: string): string | null {
    const candidates = [
      raw,
      ...['.dart', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.json'].map(
        (ext) => `${raw}${ext}`
      ),
      ...['.dart', '.ts', '.tsx', '.js', '.jsx', '.json'].map((ext) =>
        path.posix.join(raw, `index${ext}`)
      ),
    ];

    for (const candidate of candidates) {
      const normalized = this.normalizeRepoPath(candidate);
      if (!normalized || !this.isContextReadableFile(normalized)) continue;
      try {
        const fullPath = path.resolve(process.cwd(), normalized);
        if (fullPath.startsWith(process.cwd() + path.sep)) {
          const stat = fsSync.statSync(fullPath);
          if (stat.isFile()) return normalized;
        }
      } catch {
        // Try next candidate.
      }
    }

    return null;
  }

  private isUsableReviewOutput(content: string): boolean {
    const trimmed = content.trim();
    if (!trimmed) return false;

    try {
      const parsed = parseReviewOutputStrict(
        this.sanitizeReviewContent(trimmed),
        'Codex CLI'
      );
      return !parsed.findings.some((finding) =>
        this.isPlaceholderFinding(finding)
      );
    } catch {
      return false;
    }
  }

  private isPlaceholderFinding(finding: Finding): boolean {
    return (
      finding.file === 'path' ||
      finding.title === 'short' ||
      finding.message.trim().toLowerCase() === 'specific evidence'
    );
  }

  private formatContextSnippet(
    file: string,
    role: 'changed' | 'related',
    content: string
  ): string {
    return [
      `<context-file path="${file}" role="${role}">`,
      content,
      '</context-file>',
    ].join('\n');
  }

  private async readOptionalFile(file: string): Promise<string> {
    try {
      return await fs.readFile(file, 'utf8');
    } catch {
      return '';
    }
  }

  private logEventAudit(stdout: string): void {
    const audit = this.extractEventAudit(stdout);
    if (audit.commandCount === 0) {
      logger.info('Codex event audit: no shell commands recorded');
      return;
    }

    const commands =
      audit.commandNames.length > 0 ? audit.commandNames.join(', ') : 'unknown';
    const files = audit.fileCount > 0 ? `, files=${audit.fileCount}` : '';
    logger.info(
      `Codex event audit: commands=${audit.commandCount}, commandNames=${commands}${files}`
    );
  }

  private logAgenticAudit(audit: CodexAgenticAudit, retry: boolean): void {
    const suffix = retry ? ' after retry' : '';
    const preview =
      audit.commands.length > 0
        ? `, commands=${audit.commands.slice(0, 3).join(', ')}`
        : '';
    logger.info(
      `Codex agentic audit${suffix}: commandExecutions=${audit.commandExecutions}, readOnlyExplorationCommands=${audit.readOnlyExplorationCommands}${preview}`
    );
  }

  private buildAgenticAudit(stdout: string): CodexAgenticAudit {
    const commands: string[] = [];
    let commandExecutions = 0;
    let readOnlyExplorationCommands = 0;

    for (const line of stdout.split(/\r?\n/)) {
      if (!line.trim()) continue;

      try {
        const event = JSON.parse(line);
        const command = this.extractCommandFromCodexEvent(event);
        if (!command) continue;

        commandExecutions += 1;
        if (commands.length < 20) {
          commands.push(command);
        }
        if (this.isReadOnlyExplorationCommand(command)) {
          readOnlyExplorationCommands += 1;
        }
      } catch {
        // Ignore non-JSON progress lines.
      }
    }

    return {
      commandExecutions,
      readOnlyExplorationCommands,
      commands,
    };
  }

  private extractCommandFromCodexEvent(value: unknown): string | null {
    return this.extractCommandFromCodexEventInner(value, 0);
  }

  private extractCommandFromCodexEventInner(
    value: unknown,
    depth: number
  ): string | null {
    if (!value || typeof value !== 'object' || depth > 4) {
      return null;
    }

    const event = value as Record<string, unknown>;
    const command =
      typeof event.command === 'string'
        ? event.command
        : typeof event.cmd === 'string'
          ? event.cmd
          : undefined;
    const type = String(event.type || event.event || event.kind || '');
    if (
      command &&
      /(command|shell|exec|unified).*?(execution|call|tool)|tool.*?(command|shell|exec)/i.test(
        type
      )
    ) {
      return command;
    }

    for (const key of [
      'item',
      'message',
      'payload',
      'data',
      'event',
      'tool_call',
      'call',
      'arguments',
    ]) {
      const nested = this.extractCommandFromCodexEventInner(
        event[key],
        depth + 1
      );
      if (nested) return nested;
    }

    return null;
  }

  private isReadOnlyExplorationCommand(command: string): boolean {
    const commandName = this.extractCommandName(command);
    if (!commandName) return false;

    const base = path.basename(commandName).toLowerCase();
    if (
      [
        'rg',
        'grep',
        'git',
        'sed',
        'cat',
        'ls',
        'find',
        'pwd',
        'nl',
        'head',
        'tail',
        'wc',
        'awk',
        'jq',
        'sort',
        'uniq',
      ].includes(base)
    ) {
      if (base === 'git') {
        return this.isReadOnlyGitCommand(command);
      }
      return !this.commandContainsWriteRedirection(command);
    }

    return false;
  }

  private isReadOnlyGitCommand(command: string): boolean {
    const normalized = command.replace(/\s+/g, ' ').trim();
    return /(?:^|\s)git\s+(?:diff|show|grep|log|status|ls-files|ls-tree|cat-file|rev-parse|merge-base|branch|describe|name-rev)\b/.test(
      normalized
    );
  }

  private commandContainsWriteRedirection(command: string): boolean {
    return /(^|[^<])>{1,2}|\b(?:tee|xargs|rm|mv|cp|touch|mkdir|chmod|chown|npm|pnpm|yarn|bun|pip|go|cargo|flutter|dart|make)\b/.test(
      command
    );
  }

  private extractEventAudit(stdout: string): {
    commandCount: number;
    commandNames: string[];
    fileCount: number;
  } {
    const commandNames = new Set<string>();
    const files = new Set<string>();
    let commandCount = 0;

    for (const line of stdout.split(/\r?\n/)) {
      if (!line.trim()) continue;

      try {
        const event = JSON.parse(line);
        const item = event?.item;
        if (
          item?.type !== 'command_execution' ||
          typeof item.command !== 'string'
        ) {
          continue;
        }

        commandCount += 1;
        const commandName = this.extractCommandName(item.command);
        if (commandName) commandNames.add(commandName);
        for (const file of this.extractLikelyFilePaths(item.command)) {
          files.add(file);
        }
      } catch {
        // Ignore non-JSON progress lines.
      }
    }

    return {
      commandCount,
      commandNames: [...commandNames].sort(),
      fileCount: files.size,
    };
  }

  private extractCommandName(command: string): string | null {
    const shellMatch = command.match(
      /(?:^|\s)(?:\/[^\s]+\/)?(?:bash|zsh|sh)\s+-lc\s+["']?([^"']+)/
    );
    const normalized = shellMatch?.[1] || command;
    const match = normalized.trim().match(/^([A-Za-z0-9_.-]+)/);
    return match?.[1] || null;
  }

  private extractLikelyFilePaths(command: string): string[] {
    const matches = command.matchAll(
      /(?:^|[\s"'`])((?:\.{0,2}\/)?[A-Za-z0-9_@./:+-]+\.(?:[cm]?js|tsx?|jsx|py|go|rs|java|kt|kts|dart|rb|php|cs|cpp|c|h|hpp|swift|scala|json|ya?ml|toml|md|sh|sql|graphql|proto))(?:$|[\s"'`])/g
    );
    return [...matches].map((match) => match[1]).filter(Boolean);
  }

  private formatCliError(stderr: string, stdout: string): string {
    const raw = (stderr || stdout || 'no output')
      .replace(new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g'), '')
      .replace(
        /www_authenticate_header:\s*"[^"]+"/gi,
        'www_authenticate_header: "[redacted]"'
      )
      .replace(/authorization_uri="[^"]+"/gi, 'authorization_uri="[redacted]"')
      .replace(
        /authorization_uri=\\?"[^"\\]*(?:\\.[^"\\]*)*\\?"/gi,
        'authorization_uri="[redacted]"'
      )
      .replace(/https?:\/\/[^\s",)]+/gi, '[redacted-url]')
      .replace(/sk-[A-Za-z0-9_-]{20,}/g, '[redacted-openai-key]')
      .replace(/gh[pousr]_[A-Za-z0-9_]{20,}/g, '[redacted-github-token]')
      .replace(/github_pat_[A-Za-z0-9_]+/g, '[redacted-github-token]')
      .replace(/"access_token"\s*:\s*"[^"]+"/gi, '"access_token":"[redacted]"')
      .replace(
        /"refresh_token"\s*:\s*"[^"]+"/gi,
        '"refresh_token":"[redacted]"'
      )
      .replace(/session id:\s*[a-f0-9-]+/gi, 'session id: [redacted]')
      .replace(/thread\s+[a-f0-9-]{8,}/gi, 'thread [redacted]');

    const lines = raw
      .split(/\r?\n/)
      .map((line) => line.trim())
      .filter(Boolean)
      .filter(
        (line) =>
          !line.startsWith('user') && !line.includes('Respond with exactly:')
      );

    const jsonMessages = Array.from(raw.matchAll(/"message"\s*:\s*"([^"]+)"/gi))
      .map((match) => match[1])
      .filter(Boolean);
    if (jsonMessages.length > 0) {
      return this.truncateCliError([...new Set(jsonMessages)].join(' '));
    }

    const important = lines.filter((line) =>
      /not supported|invalid_request_error|auth|error|failed|timed out|timeout/i.test(
        line
      )
    );
    const summary = (important.length > 0 ? important : lines).join(' ');

    return this.truncateCliError(summary);
  }

  private truncateCliError(message: string): string {
    return message.length > 800 ? `${message.slice(0, 800)}...` : message;
  }

  private normalizeCodexError(error: unknown): Error {
    const err = error instanceof Error ? error : new Error(String(error));
    const rawMessage = this.truncateCliError(
      this.sanitizeReviewContent(this.formatCliError(err.message, ''))
    );
    const message = this.withActionableAuthHint(rawMessage);
    const normalized = new Error(message || 'Codex CLI failed');
    normalized.name = err.name || 'CodexProviderError';
    normalized.stack = err.stack;
    return normalized;
  }

  private withActionableAuthHint(message: string): string {
    if (!message) return message;
    if (
      !/(401|unauthorized|access token|refresh token|auth|login)/i.test(message)
    ) {
      return message;
    }

    const hint =
      'Codex authentication failed. If using ChatGPT subscription OAuth, reseed auth.json by running `codex login` on a trusted machine and updating CODEX_AUTH_JSON. If using API-key mode, verify OPENAI_API_KEY.';

    return message.includes('reseed auth.json')
      ? message
      : this.truncateCliError(`${message} ${hint}`);
  }

  private async resolveBinary(): Promise<string> {
    if (
      CodexProvider.preparedBinaryPath &&
      (await this.canRun(CodexProvider.preparedBinaryPath, ['--version']))
    ) {
      return CodexProvider.preparedBinaryPath;
    }
    const explicitBinary = process.env.REVIEWROUTER_CODEX_BINARY?.trim();
    if (explicitBinary) {
      if (await this.canRun(explicitBinary, ['--version'])) {
        return explicitBinary;
      }
      throw new Error(
        'Codex CLI is not available at REVIEWROUTER_CODEX_BINARY'
      );
    }
    // Try codex command directly
    if (await this.canRun('codex', ['--version'])) {
      return 'codex';
    }
    // Try codex-cli
    if (await this.canRun('codex-cli', ['--version'])) {
      return 'codex-cli';
    }
    const preparedBinary = await this.findPreparedRotatingCodexBinary();
    if (preparedBinary && (await this.canRun(preparedBinary, ['--version']))) {
      CodexProvider.preparedBinaryPath = preparedBinary;
      return preparedBinary;
    }
    const installedBinary = await this.installPinnedCodexCli();
    CodexProvider.preparedBinaryPath = installedBinary;
    return installedBinary;
  }

  private async findPreparedRotatingCodexBinary(): Promise<string | undefined> {
    try {
      const entries = await fs.readdir(os.tmpdir(), { withFileTypes: true });
      const candidates: Array<{ path: string; mtimeMs: number }> = [];
      for (const entry of entries) {
        if (
          !entry.isDirectory() ||
          !entry.name.startsWith('reviewrouter-codex-cli-')
        ) {
          continue;
        }
        const candidate = path.join(
          os.tmpdir(),
          entry.name,
          'node_modules',
          '.bin',
          'codex'
        );
        try {
          const stat = await fs.stat(candidate);
          if (stat.isFile() || stat.isSymbolicLink()) {
            candidates.push({ path: candidate, mtimeMs: stat.mtimeMs });
          }
        } catch {
          // Ignore incomplete or already-cleaned install roots.
        }
      }
      candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
      return candidates[0]?.path;
    } catch {
      return undefined;
    }
  }

  private async canRun(cmd: string, args: string[]): Promise<boolean> {
    return new Promise((resolve) => {
      const proc = spawn(cmd, args, {
        cwd: os.tmpdir(),
        env: {
          PATH: process.env.PATH || '',
          HOME: process.env.HOME || os.tmpdir(),
          GIT_CONFIG_NOSYSTEM: '1',
          GIT_CONFIG_GLOBAL: '/dev/null',
        },
        stdio: 'ignore',
      });
      proc.on('error', () => resolve(false));
      proc.on('close', (code) => resolve(code === 0));
    });
  }

  private async installPinnedCodexCli(): Promise<string> {
    const prepared = await prepareCodexCliBeforeAuthRead({
      logger: {
        info: (message) => logger.info(message),
        warn: (message) => logger.warn(message),
      },
    });
    return prepared.binaryPath;
  }

  private extractFindings(content: string): Finding[] {
    try {
      return this.parseFindingsStrict(content);
    } catch (error) {
      logger.debug(
        'Failed to parse findings from Codex response',
        error as Error
      );
    }
    return [];
  }

  private parseFindingsStrict(content: string): Finding[] {
    return parseReviewFindingsStrict(content, 'Codex CLI');
  }
}