rippletide-package 0.1.0

package/reviewer/src/integrations/cli/rippletide.js

@@ -0,0 +1,1595 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import {
+  DEFAULT_EVIDENCE_BUDGET,
+  collectAgentContext,
+  redactSecrets,
+} from "../../connect/evidence.js";
+
+const DEFAULT_MODEL = "gpt-5.5";
+const REVIEWER_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+const COLOR_ENABLED = !process.env.NO_COLOR
+  && process.env.TERM !== "dumb"
+  && Boolean(process.stdout.isTTY || process.stderr.isTTY);
+
+function color(code, value) {
+  return COLOR_ENABLED ? `\x1b[${code}m${value}\x1b[0m` : value;
+}
+
+const style = {
+  bold: (value) => color(1, value),
+  dim: (value) => color(2, value),
+  gray: (value) => color(90, value),
+  green: (value) => color(32, value),
+  magenta: (value) => color(35, value),
+  red: (value) => color(31, value),
+  yellow: (value) => color(33, value),
+  cyan: (value) => color(36, value),
+};
+
+const STATUS_WORDS = [
+  "Rippling",
+  "Tide-mapping",
+  "Evidence-sifting",
+  "Trace-reading",
+  "Signal-finding",
+  "Flow-checking",
+  "Context-packing",
+  "Boundary-checking",
+  "Proof-matching",
+  "Drift-spotting",
+  "Finding-shaping",
+  "Edit-tuning",
+  "Action-routing",
+  "Ship-checking",
+  "Tidewalking",
+  "Rippletiding",
+];
+
+const INSPECTOR_INSTRUCTIONS = `You are Rippletide's agent systems inspector.
+
+Your job is to read a local evidence pack for an AI agent and produce a precise, neutral Agent Dossier.
+
+Important:
+- The code that collected the evidence did not decide what the agent is. You must infer the agent from the evidence.
+- Work for any type of agent: coding agent, research agent, business-system agent, support agent, browser agent, workflow agent, MCP server, prompt-only agent, Python/TypeScript/Go/Rust/etc.
+- Inspection is extraction, not review. Do not judge whether the agent is good, safe, risky, shippable, or well-designed.
+- Do not produce findings, recommendations, fixes, tests to add, or "why this matters" commentary.
+- Do not use review language such as "risk", "risky", "dangerous", "high-impact", "should", "would not ship", "missing guardrail", "not safe", or "smallest proof needed" unless those exact words appear in the evidence. If they appear in evidence, make clear they are declared by the source.
+- Prefer "Not shown in local evidence" over guessing.
+- Use neutral labels: "Observed", "Declared", "Inferred from local evidence", and "Not shown in local evidence".
+- Cite concrete claims with file:line references from the evidence pack.
+- List actual tools, actions, entrypoints, env vars, data sources, tests, evals, runtime paths, policies, and gates when shown.
+- If a capability is delegated to another service or runtime, say what is visible locally and what remains opaque from local evidence.
+- Use natural builder language, but keep it factual and precise.
+- Do not add generic security or AI safety advice.
+- Do not repeat the same fact across sections unless it is needed for that section.
+
+Accuracy rules:
+- A prompt, README, or manifest declaration is not runtime proof. Label it as "Declared".
+- Code paths, routes, tool definitions, tests, and fixtures are local evidence. Label them as "Observed".
+- If a test/eval exists, say only what it directly exercises. Do not infer wider coverage.
+- If a line number is uncertain, cite the nearest file/line shown in the evidence pack and keep the claim narrow.
+- If the evidence pack omits a file because of budget, do not claim the repo lacks that behavior. Say "Not shown in the included local evidence."
+
+Return exactly this markdown shape:
+
+Agent Dossier
+
+1. Identity
+- Agent:
+- Repo/folder:
+- Type:
+- Interface:
+- Runtime/framework:
+- External systems:
+- Main files:
+- Scan scope:
+
+2. Intended Job
+- Declared job:
+- Inferred job from local evidence:
+- Users/requesters served:
+- Success signal or final output:
+- Expected actions:
+- Declared limits or non-goals:
+- Unknowns:
+
+3. Instructions
+- Instruction sources:
+- System/developer prompt summary:
+- Rules as written:
+- Output requirements:
+- Tool-use instructions:
+- Escalation/refusal/approval instructions:
+- Ambiguous or conflicting instructions shown:
+
+4. Capabilities
+- Tool surface:
+- Tools/actions:
+- Read capability families:
+- Write capability families:
+- Delete/send/deploy/external-mutation actions:
+- External services called:
+- Opaque delegated capabilities:
+- Unknowns:
+
+5. Permissions And Credentials
+- Required env vars:
+- Credential-backed systems:
+- User/channel identity:
+- Production vs sandbox hints:
+- Scope/role hints:
+- Permission checks shown:
+- Permission checks not shown:
+
+6. Runtime Behavior
+- Entry path:
+- Normal execution path:
+- Tool execution path:
+- Fallback/error path:
+- Retry/timeout behavior:
+- Success/failure states:
+- How tool calls are recorded:
+- How final output is produced:
+
+7. Memory And Context
+- Input context:
+- Files/data sources it reads:
+- Retrieval/search behavior:
+- User/session memory:
+- Cached or stored state:
+- Sensitive data surfaces:
+- Context handling not shown:
+
+8. Policies And Gates
+- Policy sources:
+- Approval/human review instructions:
+- Identity/auth checks shown:
+- Deny/refusal instructions:
+- Redaction/privacy handling shown:
+- Rate/abuse limits shown:
+- Gate enforcement code shown:
+- Gate enforcement not shown:
+
+9. Pre-Ship Proof
+- Tests:
+- Evals:
+- Fixtures/mock traces:
+- Assertions:
+- Runtime traces/log examples:
+- Behavior directly exercised by local proof:
+- Behavior declared but not exercised locally:
+- Unknowns:
+
+10. Business/System Footprint
+- Primary output:
+- External systems touched:
+- Data or records touched:
+- User-facing surfaces:
+- Downstream dependencies:
+- Observable side effects:
+- Open factual questions:
+
+Reviewer note:
+This is neutral extraction only. It reads the local agent system and builds a dossier from included evidence; it does not judge the agent or claim live runtime proof unless traces/logs are present in the evidence pack.`;
+
+const REVIEWER_INSTRUCTIONS = `You are Rippletide's agent reviewer.
+
+You receive two inputs:
+1. An internal neutral Agent Dossier produced by inspection.
+2. The local evidence pack with file:line excerpts.
+
+Your job is to reread the evidence pack with the dossier as context and produce the user-facing review.
+The builder should see useful findings, not the dossier.
+
+What makes a good finding:
+- It is specific to this agent, not generic AI/security advice.
+- It connects the agent's intended job to an expected action.
+- It identifies a concrete mismatch, missing proof, unclear gate, or behavior boundary that a builder would care about before shipping.
+- It is backed by exact file:line evidence.
+- It includes the smallest next proof or fix.
+- It sounds like a senior teammate saying: "your agent says X, but the code can do Y."
+
+Hard rules:
+- Verify the dossier against the evidence pack. If they disagree, trust the evidence pack.
+- Do not repeat obvious facts like "this agent uses Slack" unless that fact is part of a finding.
+- Do not create a finding just because something is "not shown"; tie it to an expected action that the agent actually performs or declares.
+- Do not invent runtime proof. Local code, README, manifest, fixtures, and tests are not live traces unless the evidence explicitly shows traces.
+- Do not include generic items such as "add tests", "add logging", "validate inputs", or "secure credentials" unless they are grounded in this agent's actual behavior.
+- Use natural builder language. No compliance phrasing, no "shipping risks", no "mutation boundaries", no audit-report tone.
+- Return at most 3 findings. A fourth finding is noise unless it is clearly more important than one of the first three.
+- Keep the output short. Review summary: one sentence. Each finding: at most 100 words.
+- Evidence must be compact: at most 4 file:line references per finding, inline on one line.
+- If there are no strong findings, say "No strong findings from local evidence" and explain the missing evidence in 2 bullets.
+
+Return exactly this markdown shape:
+
+Rippletide Review
+
+Agent:
+Found: <N> things worth checking before ship.
+
+Finding 1: <plain-language title>
+- What your agent says:
+- What the code can do:
+- Explanation:
+- Evidence:
+- Suggested action:
+
+Finding 2: <plain-language title>
+- What your agent says:
+- What the code can do:
+- Explanation:
+- Evidence:
+- Suggested action:
+
+Only include as many findings as are actually useful.`;
+
+const ACTION_INSTRUCTIONS = `You are Rippletide's action planner for agent builders.
+
+You receive:
+1. The user-facing Rippletide finding.
+2. The full user-facing review.
+3. The internal neutral Agent Dossier.
+4. The local evidence pack.
+5. Raw source excerpts for the files most relevant to the finding.
+6. Optional builder comments from a previous proposal.
+
+Your job is to propose the smallest useful action for this one finding.
+
+The builder is in a coding-agent style loop. They want to accept, refuse, or comment on a proposed fix. Your response must make that easy.
+
+Hard rules:
+- Do not silently broaden scope beyond the finding.
+- Do not rewrite architecture.
+- Do not make cosmetic/doc-only changes unless the finding itself is documentation mismatch.
+- Do not patch generated files, lock files, vendored code, or dependency snapshots.
+- If the finding needs a product decision, external account, live runtime proof, credentials, or a test environment you cannot infer locally, return NO_PATCH and give the smallest manual check instead.
+- If the evidence is weak or the finding is only a suspicion, return NO_PATCH and say what to inspect before changing code.
+- If a small patch is appropriate, return a unified diff that can be applied from the scanned agent repo root with git apply.
+- Patch paths must be relative to the scanned agent repo root.
+- In patch hunks, use the raw source excerpts. Do not include line numbers from the evidence pack.
+- Make patch hunks small and make hunk line counts correct.
+- The patch should change as few files and lines as possible.
+- Do not invent APIs, dependencies, tests, or files that are not supported by the local evidence.
+- If the fix can be proven locally without network, credentials, or side effects, include the exact safe command in "Proof command". Otherwise use NO_COMMAND.
+- "Proof type" must be behavior when the command exercises the changed agent behavior through a test/eval/demo assertion. Syntax/type/lint commands are code checks, not behavior proof.
+
+Return exactly this markdown shape:
+
+Rippletide Action
+
+Finding: <same finding title>
+Confidence: high|medium|low
+
+Action:
+- Proof:
+- Proof type: behavior|code|manual
+- Proof command: <npm test | bun test | bun test file.test.ts | python3 -m pytest | python3 -m unittest discover | node --test | npm run check | node --check file.js | python3 -m py_compile file.py | NO_COMMAND>
+- Pass:
+- Fail:
+- Smallest fix:
+- Files:
+
+Patch:
+\`\`\`diff
+<unified diff, or NO_PATCH>
+\`\`\`
+
+Notes:
+- <one or two short notes, or "None">
+`;
+
+function usage() {
+  return `Rippletide Reviewer
+
+Usage:
+  rippletide review [path] [--evidence-budget 140000] [--fix]
+  rippletide inspect [path] [--evidence-budget 140000]
+  npm run inspect -- [path]
+  npm run review -- [path]
+
+Example:
+  npx rippletide review
+  npx rippletide review ../my-agent
+  rippletide review ../my-agent
+  rippletide review ../my-agent --fix
+  rippletide inspect ../my-agent
+
+Interactive fix mode:
+  --fix shows a short findings menu first, then proposes an action for the finding you choose.
+  Diffs are hidden until you ask to view them.
+  Accepted edits are applied locally and followed by a local proof attempt.
+  All proposals and proof reports are saved under .rippletide/actions/.
+
+Environment:
+  Current local reviewer mode requires OPENAI_API_KEY.
+  Hosted reviewer mode will remove local model key setup.
+`;
+}
+
+function getOptionValue(args, name) {
+  const equalsPrefix = `${name}=`;
+  const inline = args.find((arg) => arg.startsWith(equalsPrefix));
+  if (inline) return inline.slice(equalsPrefix.length);
+
+  const index = args.indexOf(name);
+  if (index >= 0 && args[index + 1] && !args[index + 1].startsWith("-")) {
+    return args[index + 1];
+  }
+
+  return null;
+}
+
+function hasFlag(args, name) {
+  return args.includes(name);
+}
+
+function displayPath(filePath) {
+  const relative = path.relative(process.cwd(), filePath);
+  if (relative && !relative.startsWith("..") && !path.isAbsolute(relative)) {
+    return relative;
+  }
+  return filePath;
+}
+
+function statusEnabled() {
+  return Boolean(process.stderr.isTTY) && process.env.CI !== "true";
+}
+
+function elapsedLabel(startedAt) {
+  const seconds = Math.max(0, Math.round((Date.now() - startedAt) / 1000));
+  return `${seconds}s`;
+}
+
+async function withStatus(label, task, options = {}) {
+  const words = options.words ?? STATUS_WORDS;
+  const startedAt = Date.now();
+  const frames = ["-", "\\", "|", "/"];
+  let frameIndex = 0;
+  let interval = null;
+
+  const doneLabel = (result) => {
+    if (typeof options.done === "function") return options.done(result);
+    return options.done ?? label;
+  };
+
+  if (!statusEnabled()) {
+    console.error(`${style.bold(style.cyan("Rippletide"))} ${style.cyan(`${words[0]}...`)}`);
+    try {
+      const result = await task();
+      console.error(`${style.green("[ok]")} Rippletide ${doneLabel(result)}`);
+      return result;
+    } catch (error) {
+      console.error(`${style.red("[error]")} Rippletide ${label}`);
+      throw error;
+    }
+  }
+
+  const render = () => {
+    const frame = frames[frameIndex % frames.length];
+    const word = words[Math.floor((Date.now() - startedAt) / 1800) % words.length];
+    frameIndex += 1;
+    process.stderr.write(`\r\x1b[K${style.cyan(frame)} ${style.bold(style.cyan("Rippletide"))} ${style.bold(`${word}...`)} ${style.dim(elapsedLabel(startedAt))}`);
+  };
+
+  render();
+  interval = setInterval(render, 140);
+
+  try {
+    const result = await task();
+    clearInterval(interval);
+    process.stderr.write(`\r\x1b[K${style.green("[ok]")} Rippletide ${doneLabel(result)} ${style.dim(elapsedLabel(startedAt))}\n`);
+    return result;
+  } catch (error) {
+    clearInterval(interval);
+    process.stderr.write(`\r\x1b[K${style.red("[error]")} Rippletide ${label} ${style.dim(elapsedLabel(startedAt))}\n`);
+    throw error;
+  }
+}
+
+function terminalWidth() {
+  return Math.min(Math.max(process.stdout.columns || 100, 72), 120);
+}
+
+function wrapWords(value, width) {
+  const words = String(value).replace(/\s+/g, " ").trim().split(" ").filter(Boolean);
+  if (!words.length) return [""];
+
+  const lines = [];
+  let line = "";
+
+  for (const word of words) {
+    if (!line) {
+      line = word;
+      continue;
+    }
+
+    if (line.length + word.length + 1 <= width) {
+      line += ` ${word}`;
+    } else {
+      lines.push(line);
+      line = word;
+    }
+  }
+
+  if (line) lines.push(line);
+  return lines;
+}
+
+function printField(label, value, options = {}) {
+  if (!value) return;
+
+  const indent = options.indent ?? "";
+  const prefixText = `${indent}${label}: `;
+  const labelStyle = options.labelStyle ?? style.gray;
+  const firstPrefix = `${indent}${labelStyle(`${label}:`)} `;
+  const nextPrefix = " ".repeat(prefixText.length);
+  const available = Math.max(32, terminalWidth() - prefixText.length);
+  const lines = wrapWords(value, available);
+
+  console.log(`${firstPrefix}${lines[0]}`);
+  for (const line of lines.slice(1)) {
+    console.log(`${nextPrefix}${line}`);
+  }
+}
+
+function shortTitle(value, max = 96) {
+  if (!value || value.length <= max) return value;
+  return `${value.slice(0, max - 3).trimEnd()}...`;
+}
+
+function confidenceBadge(confidence) {
+  const normalized = confidence?.toLowerCase();
+  if (normalized === "high") return style.green("high");
+  if (normalized === "medium") return style.yellow("medium");
+  if (normalized === "low") return style.red("low");
+  return confidence ?? "unknown";
+}
+
+function patchBadge(patchCheck) {
+  return patchCheck.ok ? style.green("ready") : style.yellow("needs work");
+}
+
+function choice(key, label) {
+  return `${style.cyan(`[${key}]`)} ${label}`;
+}
+
+function printSaved(filePath) {
+  printField("Saved", displayPath(filePath), { labelStyle: style.gray });
+}
+
+function printStep(number, total, title) {
+  console.log(`\n${style.bold(style.cyan(`Step ${number}/${total}`))} ${style.bold(title)}`);
+}
+
+function getTargetPath(args) {
+  const optionValues = new Set();
+  for (const name of ["--model", "--evidence-budget"]) {
+    const value = getOptionValue(args, name);
+    if (value) optionValues.add(value);
+  }
+
+  return args.find((arg) => !arg.startsWith("-") && !optionValues.has(arg)) ?? ".";
+}
+
+async function loadLocalEnv() {
+  const envPath = path.join(REVIEWER_ROOT, ".env");
+  const source = await readFile(envPath, "utf8").catch(() => "");
+  if (!source) return;
+
+  for (const line of source.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+
+    const separatorIndex = trimmed.indexOf("=");
+    if (separatorIndex < 1) continue;
+
+    const name = trimmed.slice(0, separatorIndex).trim().replace(/^export\s+/, "");
+    const rawValue = trimmed.slice(separatorIndex + 1).trim();
+    const value = rawValue.replace(/^["']|["']$/g, "");
+
+    if (name && process.env[name] === undefined) {
+      process.env[name] = value;
+    }
+  }
+}
+
+function createRunId() {
+  return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+function slugify(value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 64) || "finding";
+}
+
+function parseFindings(reviewText) {
+  const matches = [...reviewText.matchAll(/^Finding\s+(\d+):\s+(.+)$/gm)];
+  return matches.map((match, index) => {
+    const start = match.index ?? 0;
+    const end = matches[index + 1]?.index ?? reviewText.length;
+    return {
+      number: Number(match[1]),
+      title: match[2].trim(),
+      text: reviewText.slice(start, end).trim(),
+    };
+  });
+}
+
+function extractBulletValue(text, label) {
+  const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = text.match(new RegExp(`^- ${escaped}:\\s*(.+)$`, "m"));
+  return match?.[1]?.trim() ?? "";
+}
+
+function extractReviewAgent(reviewText, root) {
+  const match = reviewText.match(/^Agent:\s*(.*)$/m);
+  const declared = match?.[1]?.trim();
+  if (declared) return declared;
+  return path.basename(root);
+}
+
+function summarizePatch(patchText) {
+  if (!patchText) return "No patch proposed";
+  const files = listPatchFiles(patchText);
+  let added = 0;
+  let removed = 0;
+
+  for (const line of patchText.split("\n")) {
+    if (line.startsWith("+") && !line.startsWith("+++")) added += 1;
+    if (line.startsWith("-") && !line.startsWith("---")) removed += 1;
+  }
+
+  const fileLabel = files.size === 1 ? "1 file" : `${files.size || "unknown"} files`;
+  return `${fileLabel}, +${added}/-${removed}`;
+}
+
+function patchFileList(patchText) {
+  const files = [...listPatchFiles(patchText)];
+  return files.length ? files.join(", ") : "unknown";
+}
+
+function listPatchFiles(patchText) {
+  const files = new Set();
+
+  for (const line of patchText.split("\n")) {
+    const fileMatch = line.match(/^diff --git a\/(.+?) b\/(.+)$/);
+    if (fileMatch) files.add(fileMatch[2]);
+  }
+
+  return files;
+}
+
+function printReviewMenu({ reviewText, findings, root, runDir, reviewPath }) {
+  const agentName = extractReviewAgent(reviewText, root);
+  const displayAgent = agentName.length > 72 ? path.basename(root) : agentName;
+  printStep(1, 5, "Review");
+  printField("Agent", displayAgent, { labelStyle: style.cyan });
+  printField("Findings", `${findings.length} ${findings.length === 1 ? "finding" : "findings"} worth your attention`, { labelStyle: style.yellow });
+  printField("Artifact", displayPath(reviewPath ?? path.join(runDir, "review.md")), { labelStyle: style.gray });
+
+  for (const finding of findings) {
+    const explanation = extractBulletValue(finding.text, "Explanation")
+      || extractBulletValue(finding.text, "Why this can surprise you");
+    const suggestedAction = extractBulletValue(finding.text, "Suggested action")
+      || extractBulletValue(finding.text, "Smallest check");
+    console.log(`\n${style.yellow(`#${finding.number}`)} ${style.bold(shortTitle(finding.title))}`);
+    printField("Why", explanation, { indent: "  ", labelStyle: style.magenta });
+    printField("Suggested fix", suggestedAction, { indent: "  ", labelStyle: style.cyan });
+  }
+}
+
+async function promptForFindingSelection(rl, findings) {
+  const validNumbers = new Set(findings.map((finding) => String(finding.number)));
+  while (true) {
+    printStep(2, 5, "Choose Findings");
+    const answer = (await rl.question(`${choice("1", "one")}  ${choice("1,2", "several")}  ${choice("a", "all")}  ${choice("q", "quit")}\n> `)).trim().toLowerCase();
+    if (answer === "q" || answer === "quit") return [];
+    if (answer === "a" || answer === "all") return findings;
+    const numbers = answer.split(",").map((part) => part.trim()).filter(Boolean);
+    if (numbers.length && numbers.every((number) => validNumbers.has(number))) {
+      const selected = findings.filter((finding) => numbers.includes(String(finding.number)));
+      console.log(`${style.dim("Selected:")} ${selected.map((finding) => `#${finding.number}`).join(", ")}`);
+      return selected;
+    }
+    console.log(style.yellow("Choose one or more finding numbers, all, or quit."));
+  }
+}
+
+function printActionSummary({ actionText, patchText, patchCheck, actionPath }) {
+  const finding = actionText.match(/^Finding:\s*(.+)$/m)?.[1]?.trim();
+  const confidence = actionText.match(/^Confidence:\s*(.+)$/m)?.[1]?.trim();
+  const proof = extractBulletValue(actionText, "Proof");
+  const proofCommand = extractBulletValue(actionText, "Proof command");
+  const fix = extractBulletValue(actionText, "Smallest fix");
+  const files = extractBulletValue(actionText, "Files");
+
+  printStep(3, 5, "Proposed Fix");
+  if (finding) console.log(style.bold(shortTitle(finding.replace(/^Finding\s+\d+:\s*/, ""))));
+  if (confidence) console.log(`${style.dim("Confidence:")} ${confidenceBadge(confidence)}`);
+  printField("Change", fix, { labelStyle: style.cyan });
+  printField("Proof", proofCommand || proof, { labelStyle: style.green });
+  printField("Files", files, { labelStyle: style.yellow });
+
+  if (!patchText) {
+    printField("Patch", "none proposed", { labelStyle: style.yellow });
+    printField("Next", `${choice("c", "comment")} ask for a different action  ${choice("r", "refuse")}`, { labelStyle: style.gray });
+    if (actionPath) printField("Artifact", displayPath(actionPath), { labelStyle: style.gray });
+    return;
+  }
+
+  printField("Patch", `${patchBadge(patchCheck)} (${summarizePatch(patchText)})`, { labelStyle: style.gray });
+  if (!patchCheck.ok) {
+    printField("Next", `${choice("c", "comment")} ask for a smaller edit  ${choice("r", "refuse")}`, { labelStyle: style.gray });
+  } else {
+    printField("Next", `${choice("a", "apply")}  ${choice("v", "view diff")}  ${choice("c", "comment")}`, { labelStyle: style.gray });
+  }
+  if (actionPath) printField("Artifact", displayPath(actionPath), { labelStyle: style.gray });
+}
+
+function extractReferencedFiles(text) {
+  const files = new Set();
+  const pattern = /`?([A-Za-z0-9_./@-]+\.(?:c|cc|cfg|cjs|cpp|cs|css|go|html|ini|java|js|json|jsx|kt|lua|md|mjs|php|prompt|properties|py|rb|rs|sh|sql|toml|ts|tsx|txt|xml|ya?ml)):\d+(?:-\d+)?`?/g;
+  let match;
+  while ((match = pattern.exec(text)) !== null) {
+    files.add(match[1]);
+  }
+  return files;
+}
+
+function buildRawSourcePack(sources, referencedFiles, budget = 90_000) {
+  const prioritized = [];
+  const rest = [];
+
+  for (const item of sources) {
+    if (referencedFiles.has(item.file)) {
+      prioritized.push(item);
+    } else {
+      rest.push(item);
+    }
+  }
+
+  const selected = prioritized.length ? prioritized : rest.slice(0, 20);
+  const sections = [
+    "# Raw Source For Patch Generation",
+    "",
+    "These excerpts are raw source, not line-numbered evidence. Use them when generating unified diffs.",
+  ];
+
+  let remaining = budget;
+  for (const item of selected) {
+    if (remaining < 1_500) break;
+    const language = path.extname(item.file).replace(".", "") || "text";
+    const source = redactSecrets(item.source);
+    const body = source.length > remaining ? `${source.slice(0, remaining - 200)}\n... truncated ...` : source;
+    const block = [
+      "",
+      `## ${item.file}`,
+      `\`\`\`${language}`,
+      body,
+      "```",
+    ].join("\n");
+    if (block.length > remaining + 200) break;
+    sections.push(block);
+    remaining -= block.length;
+  }
+
+  return sections.join("\n");
+}
+
+function extractPatch(actionText) {
+  const fenced = actionText.match(/```(?:diff|patch)?\s*\n([\s\S]*?)\n```/i);
+  const candidate = (fenced ? fenced[1] : actionText).trim();
+
+  if (!candidate || /\bNO_PATCH\b/i.test(candidate)) {
+    return null;
+  }
+
+  const diffIndex = candidate.indexOf("diff --git ");
+  if (diffIndex >= 0) {
+    return candidate.slice(diffIndex).trimEnd() + "\n";
+  }
+
+  if (/^---\s+/m.test(candidate) && /^\+\+\+\s+/m.test(candidate) && /^@@\s+/m.test(candidate)) {
+    return candidate.trimEnd() + "\n";
+  }
+
+  return null;
+}
+
+function runCommand(command, args, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: {
+        ...process.env,
+        ...(options.env ?? {}),
+      },
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let timeout = null;
+
+    if (options.timeoutMs) {
+      timeout = setTimeout(() => {
+        timedOut = true;
+        child.kill("SIGTERM");
+      }, options.timeoutMs);
+    }
+
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", (error) => {
+      if (timeout) clearTimeout(timeout);
+      resolve({ ok: false, code: 1, stdout, stderr: error.message });
+    });
+    child.on("close", (code) => {
+      if (timeout) clearTimeout(timeout);
+      resolve({ ok: code === 0 && !timedOut, code, stdout, stderr, timedOut });
+    });
+
+    if (options.stdinText) {
+      child.stdin.write(options.stdinText);
+    }
+    child.stdin.end();
+  });
+}
+
+async function checkPatch(root, patchText) {
+  const result = await runCommand("git", ["apply", "--verbose", "--check", "--recount", "--whitespace=nowarn"], {
+    cwd: root,
+    env: { GIT_CEILING_DIRECTORIES: path.dirname(root) },
+    stdinText: patchText,
+  });
+  const output = `${result.stdout}\n${result.stderr}`;
+  if (/\bSkipped patch\b/i.test(output)) {
+    return { ...result, ok: false, stderr: output.trim() || "Patch was skipped by git apply." };
+  }
+  return result;
+}
+
+async function applyPatch(root, patchText) {
+  return runCommand("git", ["apply", "--recount", "--whitespace=nowarn"], {
+    cwd: root,
+    env: { GIT_CEILING_DIRECTORIES: path.dirname(root) },
+    stdinText: patchText,
+  });
+}
+
+function truncateOutput(value, max = 6_000) {
+  const clean = redactSecrets(String(value ?? ""));
+  if (clean.length <= max) return clean;
+  return `${clean.slice(0, max)}\n... truncated ...`;
+}
+
+function isSafeRelativeFile(file) {
+  return file
+    && !path.isAbsolute(file)
+    && !file.split(/[\\/]+/).includes("..");
+}
+
+function patchFiles(patchText) {
+  return [...listPatchFiles(patchText)].filter(isSafeRelativeFile).sort();
+}
+
+function splitProofCommand(commandText) {
+  const value = String(commandText ?? "").trim();
+  if (!value || /^NO_COMMAND$/i.test(value)) return null;
+  if (/[;&|<>`$\\]/.test(value)) return { error: "Proof command contains shell syntax and was not run." };
+  const parts = value.split(/\s+/).filter(Boolean);
+  return parts.length ? { parts } : null;
+}
+
+function safeProofCommandFromText(commandText) {
+  const parsed = splitProofCommand(commandText);
+  if (!parsed || parsed.error) return parsed;
+
+  const [command, ...args] = parsed.parts;
+  const files = args.filter((arg) => /\.[A-Za-z0-9]+$/.test(arg));
+  if (files.some((file) => !isSafeRelativeFile(file))) {
+    return { error: "Proof command contains an unsafe file path and was not run." };
+  }
+
+  if (command === "node" && args[0] === "--check" && args.length > 1 && files.every((file) => /\.(?:cjs|js|mjs)$/.test(file))) {
+    return { command, args, label: parsed.parts.join(" ") };
+  }
+
+  if (command === "python3" && args[0] === "-m" && args[1] === "py_compile" && args.length > 2 && files.every((file) => file.endsWith(".py"))) {
+    return { command, args, label: parsed.parts.join(" ") };
+  }
+
+  if (command === "python3" && args[0] === "-m" && args[1] === "pytest" && args.length === 2) {
+    return { command, args, label: parsed.parts.join(" ") };
+  }
+
+  if (command === "python3" && args[0] === "-m" && args[1] === "unittest" && args[2] === "discover" && args.length === 3) {
+    return { command, args, label: parsed.parts.join(" ") };
+  }
+
+  if (command === "node" && args[0] === "--test" && files.every((file) => /\.(?:cjs|js|mjs)$/.test(file))) {
+    return { command, args, label: parsed.parts.join(" ") };
+  }
+
+  if (command === "bun" && args[0] === "test" && files.every((file) => /\.(?:cjs|js|mjs|ts|tsx)$/.test(file))) {
+    return { command, args, label: parsed.parts.join(" ") };
+  }
+
+  if (command === "npm" && args.length === 2 && args[0] === "run" && args[1] === "check") {
+    return { command, args, label: parsed.parts.join(" ") };
+  }
+
+  if (command === "npm" && args.length === 1 && args[0] === "test") {
+    return { command, args, label: parsed.parts.join(" ") };
+  }
+
+  return { error: "Proof command is not in Rippletide's local allowlist." };
+}
+
+function commandProofType(proofCommand) {
+  if (!proofCommand) return "manual";
+  if (proofCommand.command === "node" && proofCommand.args[0] === "--check") return "code";
+  if (proofCommand.command === "python3" && proofCommand.args[0] === "-m" && proofCommand.args[1] === "py_compile") return "code";
+  return "behavior";
+}
+
+function proofType(actionText, proofCommand) {
+  const declared = extractBulletValue(actionText, "Proof type").toLowerCase();
+  if (["behavior", "code", "manual"].includes(declared)) return declared;
+  return commandProofType(proofCommand);
+}
+
+async function packageScripts(root) {
+  const source = await readFile(path.join(root, "package.json"), "utf8").catch(() => "");
+  if (!source) return {};
+  try {
+    return JSON.parse(source).scripts ?? {};
+  } catch {
+    return {};
+  }
+}
+
+async function inferredProofCommand(root, files) {
+  const scripts = await packageScripts(root);
+  if (scripts.check) return { command: "npm", args: ["run", "check"], label: "npm run check" };
+  if (scripts.test) return { command: "npm", args: ["test"], label: "npm test" };
+
+  const pythonFiles = files.filter((file) => file.endsWith(".py"));
+  if (pythonFiles.length) {
+    return { command: "python3", args: ["-m", "py_compile", ...pythonFiles], label: `python3 -m py_compile ${pythonFiles.join(" ")}` };
+  }
+
+  const nodeFiles = files.filter((file) => /\.(?:cjs|js|mjs)$/.test(file));
+  if (nodeFiles.length) {
+    return { command: "node", args: ["--check", ...nodeFiles], label: `node --check ${nodeFiles.join(" ")}` };
+  }
+
+  const pyproject = await readFile(path.join(root, "pyproject.toml"), "utf8").catch(() => "");
+  if (/\bpytest\b/.test(pyproject)) {
+    return { command: "python3", args: ["-m", "pytest"], label: "python3 -m pytest" };
+  }
+
+  return null;
+}
+
+export async function runProof(root, patchText, actionText = "") {
+  const files = patchFiles(patchText);
+  const requested = extractBulletValue(actionText, "Proof command");
+  const method = extractBulletValue(actionText, "Proof");
+  const passCondition = extractBulletValue(actionText, "Pass");
+  const failCondition = extractBulletValue(actionText, "Fail");
+  const safeRequested = safeProofCommandFromText(requested);
+  if (safeRequested?.error) {
+    return {
+      command: requested,
+      failCondition,
+      files,
+      method,
+      passCondition,
+      proofType: "manual",
+      reason: safeRequested.error,
+      status: "not proven",
+      stderr: "",
+      stdout: "",
+    };
+  }
+
+  const proofCommand = safeRequested ?? await inferredProofCommand(root, files);
+  if (!proofCommand) {
+    return {
+      command: "NO_COMMAND",
+      failCondition,
+      files,
+      method,
+      passCondition,
+      proofType: "manual",
+      reason: "No safe local proof command was available.",
+      status: "not proven",
+      stderr: "",
+      stdout: "",
+    };
+  }
+
+  const result = await runCommand(proofCommand.command, proofCommand.args, {
+    cwd: root,
+    env: { GIT_CEILING_DIRECTORIES: path.dirname(root) },
+    timeoutMs: 120_000,
+  });
+
+  return {
+    code: result.code,
+    command: proofCommand.label,
+    failCondition,
+    files,
+    method,
+    passCondition,
+    proofType: proofType(actionText, proofCommand),
+    reason: result.timedOut ? "Proof command timed out." : "",
+    status: result.ok ? "passed" : "failed",
+    stderr: truncateOutput(result.stderr),
+    stdout: truncateOutput(result.stdout),
+  };
+}
+
+function renderProofReport(proof) {
+  return [
+    "# Rippletide Proof",
+    "",
+    `Status: ${proof.status}`,
+    `Proof type: ${proof.proofType}`,
+    `What was checked: ${proof.method || "Safe local command completed."}`,
+    proof.passCondition ? `Pass condition: ${proof.passCondition}` : "",
+    proof.failCondition ? `Fail condition: ${proof.failCondition}` : "",
+    `Command: ${proof.command}`,
+    `Files: ${proof.files.length ? proof.files.join(", ") : "none"}`,
+    proof.reason ? `Reason: ${proof.reason}` : "",
+    proof.code === undefined ? "" : `Exit code: ${proof.code}`,
+    proof.status === "passed" && proof.proofType === "behavior" ? "Evidence: the behavior check exited 0 and satisfied the pass condition above." : "",
+    proof.status === "passed" && proof.proofType === "code" ? "Evidence: the code check exited 0. Behavior still needs a behavior test/eval." : "",
+    proof.proofType === "behavior"
+      ? "Limit: this proves the local behavior check above, not external services or live production behavior."
+      : "Limit: this is not behavior proof. It only proves the local code check above.",
+    "",
+    "## stdout",
+    "```text",
+    proof.stdout || "",
+    "```",
+    "",
+    "## stderr",
+    "```text",
+    proof.stderr || "",
+    "```",
+    "",
+  ].filter((line) => line !== "").join("\n");
+}
+
+export async function writeProofFile(filePath, proof) {
+  await writeActionFile(filePath, renderProofReport(proof));
+}
+
+function proofOutcome(proof) {
+  if (proof.status === "passed" && proof.proofType === "behavior") return "Fix applied and behavior proof passed";
+  if (proof.status === "passed") return "Fix applied, code check passed";
+  if (proof.status === "failed") return "Fix applied, local proof failed";
+  return "Fix applied, no local proof";
+}
+
+function printProofSummary(proof, proofPath, patchText) {
+  printStep(5, 5, "Proof");
+  printField("Result", proofOutcome(proof), { labelStyle: proof.status === "passed" ? style.green : style.yellow });
+  printField("Proof type", proof.proofType, { labelStyle: proof.proofType === "behavior" ? style.green : style.yellow });
+  printField("Checked", proof.method, { labelStyle: style.magenta });
+  printField("Changed", `${patchFileList(patchText)} (${summarizePatch(patchText)})`, { labelStyle: style.cyan });
+  printField("Command", proof.command, { labelStyle: style.cyan });
+  printField("Pass condition", proof.passCondition, { labelStyle: style.green });
+  const evidence = proof.status === "passed" && proof.proofType === "behavior"
+    ? "behavior check exited 0"
+    : proof.status === "passed"
+      ? "code check exited 0; behavior not proven"
+      : proof.reason || "command did not satisfy the pass condition";
+  printField("Evidence", evidence, { labelStyle: proof.status === "passed" && proof.proofType === "behavior" ? style.green : style.yellow });
+  printField("Artifact", displayPath(proofPath), { labelStyle: style.gray });
+}
+
+async function writeActionFile(filePath, content) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, content, "utf8");
+}
+
+async function appendDecision(filePath, content) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await appendFile(filePath, `${content.trimEnd()}\n`, "utf8");
+}
+
+let fakeModelResponses = null;
+
+function fakeModelPath() {
+  return process.env.RIPPLETIDE_TEST_MODEL_RESPONSES || "";
+}
+
+async function nextFakeModelResponse() {
+  if (!fakeModelResponses) {
+    const source = await readFile(fakeModelPath(), "utf8");
+    fakeModelResponses = JSON.parse(source);
+  }
+  if (!Array.isArray(fakeModelResponses) || !fakeModelResponses.length) {
+    throw new Error("RIPPLETIDE_TEST_MODEL_RESPONSES did not contain enough fake responses.");
+  }
+  return String(fakeModelResponses.shift());
+}
+
+function extractResponseText(payload) {
+  if (typeof payload.output_text === "string" && payload.output_text.trim()) {
+    return payload.output_text.trim();
+  }
+
+  const parts = [];
+  for (const item of payload.output ?? []) {
+    for (const content of item.content ?? []) {
+      if (typeof content.text === "string") {
+        parts.push(content.text);
+      }
+    }
+  }
+
+  return parts.join("\n").trim();
+}
+
+async function callOpenAI({ apiKey, model, instructions, input, maxOutputTokens = 10_000 }) {
+  if (fakeModelPath()) return nextFakeModelResponse();
+
+  const response = await fetch("https://api.openai.com/v1/responses", {
+    method: "POST",
+    headers: {
+      "Authorization": `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      model,
+      max_output_tokens: maxOutputTokens,
+      input: [
+        {
+          role: "developer",
+          content: [
+            {
+              type: "input_text",
+              text: instructions,
+            },
+          ],
+        },
+        {
+          role: "user",
+          content: [
+            {
+              type: "input_text",
+              text: input,
+            },
+          ],
+        },
+      ],
+    }),
+  });
+
+  const raw = await response.text();
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    throw new Error(`OpenAI returned a non-JSON response with status ${response.status}.`);
+  }
+
+  if (!response.ok) {
+    const message = payload.error?.message ?? raw.slice(0, 500);
+    throw new Error(`OpenAI request failed (${response.status}): ${message}`);
+  }
+
+  const text = extractResponseText(payload);
+  if (!text) {
+    throw new Error("OpenAI response did not contain text output.");
+  }
+
+  return text;
+}
+
+function getApiKey() {
+  if (fakeModelPath()) return "test-api-key";
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey) {
+    throw new Error("OPENAI_API_KEY is required. Rippletide is LLM-based and has no deterministic fallback.");
+  }
+  return apiKey;
+}
+
+async function inspect(targetPath, options = {}) {
+  const root = path.resolve(targetPath ?? ".");
+  const model = options.model ?? process.env.RIPPLETIDE_MODEL ?? process.env.OPENAI_MODEL ?? DEFAULT_MODEL;
+  const { evidencePack } = await withStatus(
+    `Reading ${displayPath(root)}`,
+    () => collectAgentContext(targetPath, options),
+    {
+      done: (context) => `Read ${context.files.length} files and ${context.sources.length} excerpts`,
+    },
+  );
+
+  return withStatus(
+    "Building the internal agent dossier",
+    () => callOpenAI({
+      apiKey: getApiKey(),
+      model,
+      instructions: INSPECTOR_INSTRUCTIONS,
+      input: evidencePack,
+      maxOutputTokens: 10_000,
+    }),
+    {
+      done: "Inspection ready",
+    },
+  );
+}
+
+async function buildReviewArtifacts(targetPath, options = {}) {
+  const root = path.resolve(targetPath ?? ".");
+  const model = options.model ?? process.env.RIPPLETIDE_MODEL ?? process.env.OPENAI_MODEL ?? DEFAULT_MODEL;
+  const context = await withStatus(
+    `Reading ${displayPath(root)}`,
+    () => collectAgentContext(targetPath, options),
+    {
+      done: (result) => `Read ${result.files.length} files and ${result.sources.length} excerpts`,
+    },
+  );
+  const { evidencePack } = context;
+  const apiKey = getApiKey();
+  const dossier = await withStatus(
+    "Understanding this agent",
+    () => callOpenAI({
+      apiKey,
+      model,
+      instructions: INSPECTOR_INSTRUCTIONS,
+      input: evidencePack,
+      maxOutputTokens: 10_000,
+    }),
+    {
+      done: "Agent understood",
+    },
+  );
+
+  const reviewText = await withStatus(
+    "Looking for useful findings",
+    () => callOpenAI({
+      apiKey,
+      model,
+      instructions: REVIEWER_INSTRUCTIONS,
+      input: [
+        "# Internal Agent Dossier",
+        dossier,
+        "",
+        "# Evidence Pack",
+        evidencePack,
+      ].join("\n"),
+      maxOutputTokens: 3_500,
+    }),
+    {
+      done: "Review ready",
+    },
+  );
+
+  return {
+    ...context,
+    apiKey,
+    dossier,
+    model,
+    reviewText,
+  };
+}
+
+async function review(targetPath, options = {}) {
+  const artifacts = await buildReviewArtifacts(targetPath, options);
+  return artifacts.reviewText;
+}
+
+async function generateActionProposal({ apiKey, model, dossier, evidencePack, reviewText, sources, finding, comment }) {
+  const referencedFiles = extractReferencedFiles(finding.text);
+  const rawSourcePack = buildRawSourcePack(sources, referencedFiles);
+
+  return callOpenAI({
+    apiKey,
+    model,
+    instructions: ACTION_INSTRUCTIONS,
+    input: [
+      "# Finding To Act On",
+      finding.text,
+      "",
+      "# Builder Comment",
+      comment?.trim() ? comment.trim() : "None",
+      "",
+      "# Full User-Facing Review",
+      reviewText,
+      "",
+      "# Internal Agent Dossier",
+      dossier,
+      "",
+      "# Evidence Pack",
+      evidencePack,
+      "",
+      rawSourcePack,
+    ].join("\n"),
+    maxOutputTokens: 7_000,
+  });
+}
+
+async function promptForDecision(rl, { hasPatch, patchApplies, patchText }) {
+  const choices = hasPatch && patchApplies
+    ? `${choice("a", "apply")}  ${choice("v", "view diff")}  ${choice("c", "comment")}  ${choice("r", "refuse")}  ${choice("s", "skip")}  ${choice("q", "quit")}`
+    : hasPatch
+      ? `${choice("v", "view diff")}  ${choice("c", "comment")}  ${choice("r", "refuse")}  ${choice("s", "skip")}  ${choice("q", "quit")}`
+      : `${choice("c", "comment")}  ${choice("r", "refuse")}  ${choice("s", "skip")}  ${choice("q", "quit")}`;
+
+  while (true) {
+    const answer = (await rl.question(`\n${style.bold("Apply this fix?")}  ${choices}\n> `)).trim().toLowerCase();
+    if (["v", "view", "diff"].includes(answer) && hasPatch) {
+      console.log(`\n${patchText}\n`);
+      continue;
+    }
+    if (["a", "accept"].includes(answer) && hasPatch && patchApplies) return "accept";
+    if (["r", "refuse"].includes(answer)) return "refuse";
+    if (["c", "comment"].includes(answer)) return "comment";
+    if (["s", "skip"].includes(answer)) return "skip";
+    if (["q", "quit"].includes(answer)) return "quit";
+    console.log(style.yellow("Please choose one of the shown options."));
+  }
+}
+
+async function promptAfterApply(rl, { hasMoreSelected }) {
+  const continueLabel = hasMoreSelected ? "continue" : "done";
+  while (true) {
+    const answer = (await rl.question(`\n${style.bold("Next")}  ${choice("r", "re-check findings")}  ${choice("c", continueLabel)}  ${choice("q", "quit")}\n> `)).trim().toLowerCase();
+    if (answer === "r" || answer === "recheck" || answer === "re-check") return "recheck";
+    if (answer === "c" || answer === "continue" || answer === "d" || answer === "done") return "continue";
+    if (answer === "q" || answer === "quit") return "quit";
+    console.log(style.yellow("Please choose re-check, continue, or quit."));
+  }
+}
+
+async function promptAfterProofFailure(rl) {
+  while (true) {
+    const answer = (await rl.question(`\n${style.bold("Proof failed")}  ${choice("r", "regenerate")}  ${choice("c", "comment")}  ${choice("s", "skip")}  ${choice("q", "quit")}\n> `)).trim().toLowerCase();
+    if (answer === "r" || answer === "regenerate") return "regenerate";
+    if (answer === "c" || answer === "comment") return "comment";
+    if (answer === "s" || answer === "skip") return "skip";
+    if (answer === "q" || answer === "quit") return "quit";
+    console.log(style.yellow("Please choose regenerate, comment, skip, or quit."));
+  }
+}
+
+function proofFailureComment(proof) {
+  return [
+    "System proof request: the previous accepted patch was applied, but local proof failed.",
+    `Proof command: ${proof.command}`,
+    proof.reason ? `Reason: ${proof.reason}` : "",
+    proof.stdout ? `stdout:\n${proof.stdout}` : "",
+    proof.stderr ? `stderr:\n${proof.stderr}` : "",
+    "Regenerate a smaller correction for the same finding. If a clean local proof is not possible, return NO_PATCH with the manual check.",
+  ].filter(Boolean).join("\n\n");
+}
+
+async function reviewWithFix(targetPath, options = {}) {
+  let artifacts = await buildReviewArtifacts(targetPath, options);
+  let findings = parseFindings(artifacts.reviewText);
+  const runDir = path.join(artifacts.root, ".rippletide", "actions", createRunId());
+
+  await mkdir(runDir, { recursive: true });
+  await writeActionFile(path.join(runDir, "review.md"), artifacts.reviewText);
+  await writeActionFile(path.join(runDir, "dossier.md"), artifacts.dossier);
+
+  if (!findings.length) {
+    console.log(artifacts.reviewText);
+    console.log(`\nNo findings to fix. Saved review: ${path.join(runDir, "review.md")}`);
+    return artifacts.reviewText;
+  }
+
+  printReviewMenu({
+    reviewText: artifacts.reviewText,
+    findings,
+    root: artifacts.root,
+    runDir,
+  });
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    let selectedFindings = await promptForFindingSelection(rl, findings);
+    if (!selectedFindings.length) {
+      console.log("Stopped fix mode.");
+      return artifacts.reviewText;
+    }
+
+    printField("Run artifacts", displayPath(runDir), { labelStyle: style.gray });
+
+    for (let selectedIndex = 0; selectedIndex < selectedFindings.length; selectedIndex += 1) {
+      const finding = selectedFindings[selectedIndex];
+      const findingDir = path.join(
+        runDir,
+        `finding-${finding.number}-${slugify(finding.title)}`,
+      );
+      await mkdir(findingDir, { recursive: true });
+      await writeActionFile(path.join(findingDir, "finding.md"), finding.text);
+
+      let comment = "";
+
+      while (true) {
+        console.log(`\n${style.dim("Working on")} ${style.bold(`#${finding.number}`)} ${shortTitle(finding.title)}`);
+
+        let actionText = await withStatus(
+          `Planning an edit for Finding ${finding.number}`,
+          () => generateActionProposal({
+            ...artifacts,
+            finding,
+            comment,
+          }),
+          {
+            done: "Action ready",
+          },
+        );
+        let patchText = extractPatch(actionText);
+        let patchCheck = patchText
+          ? await checkPatch(artifacts.root, patchText)
+          : { ok: false, stderr: "No patch was proposed." };
+
+        if (patchText && !patchCheck.ok) {
+          const invalidSuffix = `invalid-${Date.now()}`;
+          await writeActionFile(path.join(findingDir, `${invalidSuffix}.md`), actionText);
+          await writeActionFile(path.join(findingDir, `${invalidSuffix}.patch`), patchText);
+
+          const details = (patchCheck.stderr || patchCheck.stdout).trim();
+          console.log(style.yellow("Initial edit did not apply cleanly. Repairing once..."));
+
+          actionText = await withStatus(
+            "Repairing the proposed edit",
+            () => generateActionProposal({
+              ...artifacts,
+              finding,
+              comment: [
+                comment,
+                "System repair request: the previous unified diff failed `git apply --check`.",
+                details ? `git apply output:\n${details}` : "",
+                "Regenerate the same action with a smaller, valid unified diff. If a clean patch is uncertain, return NO_PATCH.",
+              ].filter(Boolean).join("\n\n"),
+            }),
+            {
+              done: "Repaired action ready",
+            },
+          );
+          patchText = extractPatch(actionText);
+          patchCheck = patchText
+            ? await checkPatch(artifacts.root, patchText)
+            : { ok: false, stderr: "No patch was proposed." };
+        }
+
+        const proposalSuffix = comment ? `regenerated-${Date.now()}` : "proposal";
+        const proposalPath = path.join(findingDir, `${proposalSuffix}.md`);
+
+        await writeActionFile(proposalPath, actionText);
+        if (patchText) {
+          await writeActionFile(path.join(findingDir, `${proposalSuffix}.patch`), patchText);
+        }
+
+        printActionSummary({
+          actionPath: proposalPath,
+          actionText,
+          patchCheck,
+          patchText,
+        });
+
+        const decision = await promptForDecision(rl, {
+          hasPatch: Boolean(patchText),
+          patchApplies: patchCheck.ok,
+          patchText,
+        });
+
+        if (decision === "accept") {
+          await appendDecision(
+            path.join(findingDir, "decisions.log"),
+            `${new Date().toISOString()} decision=accept${comment ? ` comment=${JSON.stringify(comment)}` : ""}`,
+          );
+          const applyResult = await applyPatch(artifacts.root, patchText);
+          if (!applyResult.ok) {
+            console.log(style.yellow("Apply failed. No edit was applied."));
+            const details = (applyResult.stderr || applyResult.stdout).trim();
+            if (details) console.log(details);
+            continue;
+          }
+
+          const stillApplies = await checkPatch(artifacts.root, patchText);
+          if (stillApplies.ok) {
+            console.log(style.yellow("Apply command finished, but the edit still appears unapplied. No reliable file change was confirmed."));
+            continue;
+          }
+
+          printStep(4, 5, "Apply");
+          printField("Patch", "applied", { labelStyle: style.green });
+          printField("Changed", `${patchFileList(patchText)} (${summarizePatch(patchText)})`, { labelStyle: style.cyan });
+
+          const proof = await withStatus(
+            `Running local proof for Finding ${finding.number}`,
+            () => runProof(artifacts.root, patchText, actionText),
+            {
+              done: (result) => `Proof ${result.status}`,
+            },
+          );
+          const proofPath = path.join(findingDir, "proof.md");
+          await writeProofFile(proofPath, proof);
+          printProofSummary(proof, proofPath, patchText);
+
+          if (proof.status === "failed") {
+            const proofDecision = await promptAfterProofFailure(rl);
+            if (proofDecision === "regenerate") {
+              comment = [comment, proofFailureComment(proof)].filter(Boolean).join("\n\n");
+              continue;
+            }
+            if (proofDecision === "comment") {
+              const builderComment = await rl.question("Tell Rippletide what to change about the proposed fix:\n> ");
+              comment = [comment, proofFailureComment(proof), builderComment].filter(Boolean).join("\n\n");
+              await appendDecision(path.join(findingDir, "comments.log"), `${new Date().toISOString()} ${builderComment}`);
+              continue;
+            }
+            if (proofDecision === "quit") {
+              console.log(style.dim("Stopped fix mode."));
+              return artifacts.reviewText;
+            }
+            break;
+          }
+
+          const nextStep = await promptAfterApply(rl, {
+            hasMoreSelected: selectedIndex < selectedFindings.length - 1,
+          });
+
+          if (nextStep === "recheck") {
+            artifacts = await buildReviewArtifacts(artifacts.root, options);
+            findings = parseFindings(artifacts.reviewText);
+
+            const refreshSuffix = `after-finding-${finding.number}-${Date.now()}`;
+            const refreshedReviewPath = path.join(runDir, `${refreshSuffix}.review.md`);
+            const refreshedDossierPath = path.join(runDir, `${refreshSuffix}.dossier.md`);
+            await writeActionFile(refreshedReviewPath, artifacts.reviewText);
+            await writeActionFile(refreshedDossierPath, artifacts.dossier);
+
+            if (!findings.length) {
+              console.log(`\n${style.green("No findings remain after the edit.")}`);
+              console.log(`${style.dim("Saved refreshed review:")} ${displayPath(refreshedReviewPath)}`);
+              return artifacts.reviewText;
+            }
+
+            console.log(`\n${style.green("Findings updated after your edit.")}`);
+            printReviewMenu({
+              reviewText: artifacts.reviewText,
+              findings,
+              root: artifacts.root,
+              runDir,
+              reviewPath: refreshedReviewPath,
+            });
+
+            selectedFindings = await promptForFindingSelection(rl, findings);
+            if (!selectedFindings.length) {
+              console.log(style.dim("Stopped fix mode."));
+              return artifacts.reviewText;
+            }
+
+            selectedIndex = -1;
+          }
+
+          if (nextStep === "quit") {
+            console.log(style.dim("Stopped fix mode."));
+            return artifacts.reviewText;
+          }
+
+          break;
+        }
+
+        if (decision === "comment") {
+          await appendDecision(
+            path.join(findingDir, "decisions.log"),
+            `${new Date().toISOString()} decision=${decision}${comment ? ` comment=${JSON.stringify(comment)}` : ""}`,
+          );
+          comment = await rl.question("Tell Rippletide what to change about the proposed fix:\n> ");
+          await appendDecision(path.join(findingDir, "comments.log"), `${new Date().toISOString()} ${comment}`);
+          continue;
+        }
+
+        if (decision === "quit") {
+          await appendDecision(
+            path.join(findingDir, "decisions.log"),
+            `${new Date().toISOString()} decision=${decision}${comment ? ` comment=${JSON.stringify(comment)}` : ""}`,
+          );
+          console.log(style.dim("Stopped fix mode."));
+          return artifacts.reviewText;
+        }
+
+        await appendDecision(
+          path.join(findingDir, "decisions.log"),
+          `${new Date().toISOString()} decision=${decision}${comment ? ` comment=${JSON.stringify(comment)}` : ""}`,
+        );
+        console.log(style.dim(decision === "refuse" ? "Refused finding." : "Skipped finding."));
+        break;
+      }
+    }
+  } finally {
+    rl.close();
+  }
+
+  console.log(`\n${style.green("Fix mode complete.")} ${style.dim(`Saved in ${displayPath(runDir)}`)}`);
+  return artifacts.reviewText;
+}
+
+export async function main(argv = process.argv) {
+  const [, , command, ...args] = argv;
+  await loadLocalEnv();
+
+  if (!command || command === "--help" || command === "-h") {
+    console.log(usage());
+    return;
+  }
+
+  if (hasFlag(args, "--help") || hasFlag(args, "-h")) {
+    console.log(usage());
+    return;
+  }
+
+  if (command !== "inspect" && command !== "review") {
+    console.error(`Unknown command: ${command}\n`);
+    console.error(usage());
+    process.exit(1);
+  }
+
+  const model = getOptionValue(args, "--model") ?? process.env.RIPPLETIDE_MODEL ?? process.env.OPENAI_MODEL ?? DEFAULT_MODEL;
+  const evidenceBudgetValue = getOptionValue(args, "--evidence-budget");
+  const evidenceBudget = evidenceBudgetValue ? Number(evidenceBudgetValue) : DEFAULT_EVIDENCE_BUDGET;
+
+  if (!Number.isFinite(evidenceBudget) || evidenceBudget < 10_000) {
+    throw new Error("--evidence-budget must be a number greater than or equal to 10000.");
+  }
+
+  if (command === "inspect") {
+    console.log(await inspect(getTargetPath(args), { model, evidenceBudget }));
+    return;
+  }
+
+  if (hasFlag(args, "--fix")) {
+    await reviewWithFix(getTargetPath(args), { model, evidenceBudget });
+    return;
+  }
+
+  console.log(await review(getTargetPath(args), { model, evidenceBudget }));
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}
+
+export {
+  applyPatch,
+  checkPatch,
+  extractPatch,
+  parseFindings,
+  safeProofCommandFromText,
+};