@kal-elsam/kairo-runtime 0.5.1 → 0.7.0

package/src/global/runtime/review/review-cli.js

@@ -0,0 +1,150 @@
+import { resolveHomeDir } from "../../paths.js";
+import { printJson } from "../../json-output.js";
+import { commandHeader } from "../../brand/index.js";
+import { formatCliCommand } from "../../brand/cli.js";
+import {
+  isInteractiveTerminal, promptApplyConfirmation
+} from "../../apply-confirmation.js";
+import {
+  REVIEW_EXIT_CODES, REVIEW_SEVERITIES,
+  assertReceiptSecretFree, assertSafeReviewId,
+  listReviewReceipts, loadReviewReceipt
+} from "./index.js";
+import { runReview } from "./review-runner.js";
+
+const FAIL_ON = new Set(Object.values(REVIEW_SEVERITIES));
+
+function parseFailOn(value) {
+  if (value == null || value === "") return null;
+  const normalized = String(value).trim().toLowerCase();
+  if (!FAIL_ON.has(normalized)) {
+    throw new Error(`Invalid --fail-on "${value}". Use high, medium, or low.`);
+  }
+  return normalized;
+}
+
+async function resolvePrivateConfirmed(options, { prompt = promptApplyConfirmation } = {}) {
+  if (!options.includePrivate) return { privateConfirmed: false, cancelled: false };
+  if (options.yes || options.confirm) return { privateConfirmed: true, cancelled: false };
+  if (!isInteractiveTerminal(options.interactive)) {
+    throw new Error(
+      "Including private paths requires --include-private with --yes/--confirm, or a TTY confirmation."
+    );
+  }
+  const ok = await prompt({
+    command: "review",
+    question: "Include private paths in this review? [Y/n]: "
+  });
+  return { privateConfirmed: Boolean(ok), cancelled: !ok };
+}
+
+function publicReceipt(receipt) {
+  return assertReceiptSecretFree(receipt);
+}
+
+function printReviewHuman(receipt, exitCode) {
+  const counts = { high: 0, medium: 0, low: 0 };
+  for (const f of receipt.findings ?? []) {
+    if (counts[f.severity] != null) counts[f.severity] += 1;
+  }
+  console.log(commandHeader(`review ${receipt.reviewId}`));
+  console.log(`Agent: ${receipt.agentId} · state: ${receipt.state} · exit: ${exitCode}`);
+  console.log(
+    `Findings: ${(receipt.findings ?? []).length}`
+    + ` (high ${counts.high}, medium ${counts.medium}, low ${counts.low})`
+  );
+  console.log(
+    `Snapshot: ${receipt.snapshot.mode} · files ${receipt.snapshot.totals.fileCount}`
+    + ` · ${receipt.snapshot.fingerprint.slice(0, 12)}`
+  );
+  if ((receipt.warnings ?? []).length) console.log(`Warnings: ${receipt.warnings.length}`);
+}
+
+export async function runGlobalReview(options, packageManifest, deps = {}) {
+  const homeDir = deps.homeDir ?? resolveHomeDir();
+  try {
+    if (!options.agent) {
+      throw new Error(`Missing --agent. Use: ${formatCliCommand("review --agent codex|pi")}`);
+    }
+    const failOn = parseFailOn(options.failOn);
+    const consent = await resolvePrivateConfirmed(options, { prompt: deps.prompt });
+    if (consent.cancelled) {
+      if (options.json) {
+        printJson({
+          ok: false, cancelled: true, exitCode: REVIEW_EXIT_CODES.ERROR,
+          error: "Private path inclusion cancelled."
+        });
+      } else {
+        console.log("Review cancelled: private paths not included.");
+      }
+      process.exitCode = REVIEW_EXIT_CODES.ERROR;
+      return { cancelled: true, exitCode: REVIEW_EXIT_CODES.ERROR };
+    }
+
+    const result = await (deps.runReview ?? runReview)({
+      cwd: options.cwd, agent: options.agent, base: options.base ?? null,
+      commit: options.commit ?? null, model: options.model ?? null,
+      includePrivate: Boolean(options.includePrivate),
+      privateConfirmed: consent.privateConfirmed, failOn,
+      homeDir, cliVersion: packageManifest?.version ?? null
+    });
+    const receipt = publicReceipt(result.receipt);
+    if (options.json) printJson({ ok: result.exitCode === 0, exitCode: result.exitCode, receipt });
+    else printReviewHuman(receipt, result.exitCode);
+    process.exitCode = result.exitCode;
+    return { receipt, exitCode: result.exitCode };
+  } catch (error) {
+    const exitCode = REVIEW_EXIT_CODES.ERROR;
+    const message = String(error?.message ?? error);
+    if (options.json) printJson({ ok: false, exitCode, error: message, code: error?.code ?? null });
+    else console.error(message);
+    process.exitCode = exitCode;
+    return { exitCode, error };
+  }
+}
+
+export async function runGlobalReviews(options, _packageManifest, deps = {}) {
+  const homeDir = deps.homeDir ?? resolveHomeDir();
+  try {
+    const action = options.reviewsAction ?? "list";
+    if (action === "list") {
+      const receipts = (await listReviewReceipts({ homeDir, limit: options.limit }))
+        .map((r) => publicReceipt(r));
+      if (options.json) printJson({ receipts });
+      else {
+        console.log(commandHeader("reviews"));
+        if (receipts.length === 0) console.log("  (no reviews yet)");
+        for (const r of receipts) {
+          console.log(
+            `  ${r.reviewId}  ${String(r.state).padEnd(10)}  ${String(r.agentId).padEnd(6)}  ${r.createdAt}`
+          );
+        }
+      }
+      return { receipts };
+    }
+    if (action === "show") {
+      if (!options.reviewId) {
+        throw new Error(`Missing review id. Use: ${formatCliCommand("reviews show <reviewId>")}`);
+      }
+      try { assertSafeReviewId(options.reviewId); }
+      catch { throw new Error(`Invalid review id "${options.reviewId}".`); }
+      let receipt;
+      try {
+        receipt = publicReceipt(await loadReviewReceipt(options.reviewId, { homeDir }));
+      } catch {
+        throw new Error(`Review receipt not found: ${options.reviewId}`);
+      }
+      if (options.json) printJson({ receipt });
+      else printReviewHuman(receipt, REVIEW_EXIT_CODES.OK);
+      return { receipt };
+    }
+    throw new Error(`Unknown reviews action "${action}". Use list or show.`);
+  } catch (error) {
+    const exitCode = REVIEW_EXIT_CODES.ERROR;
+    const message = String(error?.message ?? error);
+    if (options.json) printJson({ ok: false, exitCode, error: message, code: error?.code ?? null });
+    else console.error(message);
+    process.exitCode = exitCode;
+    return { exitCode, error };
+  }
+}

package/src/global/runtime/review/review-codex.js

@@ -0,0 +1,132 @@
+import { REVIEW_AGENTS, REVIEW_SCOPE_MODES } from "./review-types.js";
+import { ReviewExecError, assertBoundedProcessOk, runBoundedProcess } from "./review-exec.js";
+import { validateReviewOutput } from "./review-validate.js";
+
+export const REVIEW_CODEX_ERROR_CODES = Object.freeze({
+  INVALID_JSONL: "invalid_jsonl", MISSING_AGENT_MESSAGE: "missing_agent_message",
+  STREAM_ERROR: "stream_error", INVALID_CWD: "invalid_cwd"
+});
+
+const EXECUTABLE = "codex";
+const ENV_INHERIT_NONE = "shell_environment_policy.inherit=none";
+const CLI_ENV_KEYS = Object.freeze([
+  "PATH", "HOME", "USER", "LOGNAME", "SHELL", "LANG", "LC_ALL", "LC_CTYPE", "TMPDIR", "TERM",
+  "CODEX_HOME", "OPENAI_API_KEY", "OPENAI_BASE_URL", "OPENAI_API_BASE",
+  "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "http_proxy", "https_proxy", "no_proxy"
+]);
+
+function requireSnapshotCwd(snapshot) {
+  const cwd = snapshot?.cwd;
+  if (typeof cwd !== "string" || !cwd) {
+    throw new ReviewExecError("Codex review requires snapshot.cwd.", {
+      code: REVIEW_CODEX_ERROR_CODES.INVALID_CWD
+    });
+  }
+  return cwd;
+}
+
+/** Global approval before `exec`; read-only/ephemeral after; prompt via `-`. */
+export function buildCodexReviewArgs(snapshot, { model = null } = {}) {
+  const cwd = requireSnapshotCwd(snapshot);
+  const args = [
+    "--ask-for-approval", "never",
+    "exec", "--json", "--ephemeral", "--ignore-user-config",
+    "--sandbox", "read-only", "-C", cwd, "-c", ENV_INHERIT_NONE
+  ];
+  if (model) args.push("-m", String(model));
+  args.push("-");
+  return args;
+}
+
+/** Preserve only env needed to start/authenticate the CLI. */
+export function buildCodexCliEnv(sourceEnv = process.env) {
+  const env = Object.create(null);
+  for (const key of CLI_ENV_KEYS) {
+    if (sourceEnv[key] != null && sourceEnv[key] !== "") env[key] = sourceEnv[key];
+  }
+  return env;
+}
+
+function scopeRefLine(snapshot) {
+  if (snapshot?.mode === REVIEW_SCOPE_MODES.BASE) return `base=${snapshot.base ?? ""}`;
+  if (snapshot?.mode === REVIEW_SCOPE_MODES.COMMIT) return `commit=${snapshot.commit ?? ""}`;
+  return "ref=working-tree";
+}
+
+/** Prompt is mode + exact scope ref + snapshot paths — no diffs/transcripts. */
+export function buildCodexReviewPrompt(snapshot) {
+  const files = Array.isArray(snapshot?.files) ? snapshot.files : [];
+  return [
+    `Bounded review mode=${snapshot?.mode ?? "working-tree"} ${scopeRefLine(snapshot)}.`,
+    "Respond JSON only: {\"findings\":[{\"severity\":\"high|medium|low\",\"title\":\"...\",\"path\":\"...\",\"line\":null,\"problem\":\"...\",\"recommendation\":\"...\"}],\"warnings\":[]}.",
+    "Cite only snapshot paths:",
+    ...(files.length ? files.map((f) => `- ${f.path} (${f.status})`) : ["(none)"])
+  ].join("\n");
+}
+
+/** Parse Codex JSONL: last agent_message + usage. Trailing partial line ignored. */
+export function parseCodexReviewJsonl(stdout) {
+  let agentText = null;
+  let usage = null;
+  let streamError = null;
+  const raw = String(stdout ?? "");
+  const parts = raw.split(/\r?\n/);
+  const complete = raw.endsWith("\n") || raw.endsWith("\r\n") ? parts : parts.slice(0, -1);
+  for (const line of complete) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let event;
+    try { event = JSON.parse(trimmed); }
+    catch (error) {
+      throw new ReviewExecError(`Malformed Codex JSONL: ${error.message}`, {
+        code: REVIEW_CODEX_ERROR_CODES.INVALID_JSONL
+      });
+    }
+    if (!event || typeof event !== "object") {
+      throw new ReviewExecError("Malformed Codex JSONL event.", {
+        code: REVIEW_CODEX_ERROR_CODES.INVALID_JSONL
+      });
+    }
+    if (event.type === "error") streamError = String(event.message ?? "Codex stream error.");
+    else if (event.type === "turn.failed") streamError = String(event.error?.message ?? "Codex turn failed.");
+    else if (event.type === "turn.completed" && event.usage && typeof event.usage === "object") {
+      const input = Number.isFinite(event.usage.input_tokens) ? event.usage.input_tokens : null;
+      const output = Number.isFinite(event.usage.output_tokens) ? event.usage.output_tokens : null;
+      usage = {
+        inputTokens: input, outputTokens: output,
+        totalTokens: input != null && output != null ? input + output : null, cost: null
+      };
+    } else if (event.type === "item.completed" && event.item?.type === "agent_message"
+      && typeof event.item.text === "string") {
+      agentText = event.item.text;
+    }
+  }
+  if (streamError) throw new ReviewExecError(streamError, { code: REVIEW_CODEX_ERROR_CODES.STREAM_ERROR });
+  if (typeof agentText !== "string" || agentText.trim() === "") {
+    throw new ReviewExecError("Codex JSONL missing final agent_message.", {
+      code: REVIEW_CODEX_ERROR_CODES.MISSING_AGENT_MESSAGE
+    });
+  }
+  return { agentText, usage };
+}
+
+/** Run Codex read-only review bound to snapshot.cwd. No receipts/drift/raw streams. */
+export async function runCodexReview({
+  snapshot, model = null, env = process.env, spawnImpl,
+  timeoutMs, terminationGraceMs, killGraceMs, runProcess = runBoundedProcess
+} = {}) {
+  const cwd = requireSnapshotCwd(snapshot);
+  const requestedModel = model == null || model === "" ? null : String(model);
+  const result = await runProcess({
+    command: EXECUTABLE, args: buildCodexReviewArgs(snapshot, { model: requestedModel }), cwd,
+    env: buildCodexCliEnv(env), stdin: buildCodexReviewPrompt(snapshot), spawnImpl,
+    timeoutMs, terminationGraceMs, killGraceMs
+  });
+  assertBoundedProcessOk(result);
+  const parsed = parseCodexReviewJsonl(result.stdout);
+  const validated = validateReviewOutput(parsed.agentText, snapshot);
+  return {
+    agentId: REVIEW_AGENTS.CODEX, model: requestedModel,
+    findings: validated.findings, warnings: validated.warnings, usage: parsed.usage
+  };
+}

package/src/global/runtime/review/review-exec.js

@@ -0,0 +1,136 @@
+import { spawn } from "node:child_process";
+
+export const REVIEW_EXEC_ERROR_CODES = Object.freeze({
+  NONZERO_EXIT: "nonzero_exit", TIMEOUT: "timeout", OUTPUT_OVERFLOW: "output_overflow",
+  TERMINATION_FAILED: "termination_failed", SPAWN_FAILED: "spawn_failed"
+});
+export const REVIEW_EXEC_LIMITS = Object.freeze({
+  STDOUT: 1_048_576, STDERR: 16_384, DEFAULT_TIMEOUT_MS: 180_000,
+  TERMINATION_GRACE_MS: 1_000, KILL_GRACE_MS: 1_000
+});
+
+export class ReviewExecError extends Error {
+  constructor(message, { code, details = null } = {}) {
+    super(message);
+    this.name = "ReviewExecError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+/** Spawn without shell; stdin; capped streams; SIGTERM→SIGKILL. */
+export function runBoundedProcess({
+  command, args = [], cwd, env, stdin = null, spawnImpl = spawn,
+  timeoutMs = REVIEW_EXEC_LIMITS.DEFAULT_TIMEOUT_MS,
+  terminationGraceMs = REVIEW_EXEC_LIMITS.TERMINATION_GRACE_MS,
+  killGraceMs = REVIEW_EXEC_LIMITS.KILL_GRACE_MS,
+  stdoutLimit = REVIEW_EXEC_LIMITS.STDOUT, stderrLimit = REVIEW_EXEC_LIMITS.STDERR
+} = {}) {
+  if (typeof command !== "string" || !command) {
+    return Promise.reject(new ReviewExecError("runBoundedProcess requires command.", {
+      code: REVIEW_EXEC_ERROR_CODES.SPAWN_FAILED
+    }));
+  }
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawnImpl(command, args, { cwd, env, shell: false, stdio: ["pipe", "pipe", "pipe"] });
+    } catch (error) {
+      reject(new ReviewExecError(`Failed to spawn "${command}": ${error.message}`, {
+        code: REVIEW_EXEC_ERROR_CODES.SPAWN_FAILED, details: { command }
+      }));
+      return;
+    }
+    let stdout = "";
+    let stderr = "";
+    let stdoutOverflow = false;
+    let stderrOverflow = false;
+    let settled = false;
+    let timedOut = false;
+    let timers = [];
+    const clearTimers = () => { for (const t of timers) clearTimeout(t); timers = []; };
+    const schedule = (fn, ms) => { timers.push(setTimeout(fn, ms)); };
+    const detachIo = () => {
+      child.stdout?.off?.("data", onStdout);
+      child.stderr?.off?.("data", onStderr);
+      child.off?.("close", onClose);
+    };
+    const settle = (result) => {
+      if (settled) return;
+      settled = true; clearTimers(); detachIo(); resolve(result);
+    };
+    const finish = (extra = {}) => settle({
+      status: null, signal: null, timedOut, terminationFailed: false,
+      stdoutOverflow, stderrOverflow, stdout, stderr, ...extra
+    });
+    const onStdout = (chunk) => {
+      const next = appendLimited(stdout, chunk, stdoutLimit);
+      stdout = next.text; if (next.overflow) stdoutOverflow = true;
+    };
+    const onStderr = (chunk) => {
+      const next = appendLimited(stderr, chunk, stderrLimit);
+      stderr = next.text; if (next.overflow) stderrOverflow = true;
+    };
+    const onError = (error) => {
+      if (settled) return;
+      settled = true; clearTimers(); detachIo();
+      reject(new ReviewExecError(`Spawn error for "${command}": ${error.message}`, {
+        code: REVIEW_EXEC_ERROR_CODES.SPAWN_FAILED, details: { command }
+      }));
+    };
+    const onClose = (status, signal) => finish({ status: status ?? null, signal: signal ?? null });
+    schedule(() => {
+      if (settled) return;
+      timedOut = true; safeKill(child, "SIGTERM");
+      schedule(() => {
+        if (settled) return;
+        safeKill(child, "SIGKILL");
+        schedule(() => {
+          if (settled) return;
+          try { child.unref?.(); } catch { /* ignore */ }
+          finish({ terminationFailed: true });
+        }, killGraceMs);
+      }, terminationGraceMs);
+    }, timeoutMs);
+    child.stdout?.on("data", onStdout);
+    child.stderr?.on("data", onStderr);
+    child.on("error", onError);
+    child.on("close", onClose);
+    child.stdin?.on?.("error", () => {}); // absorb async EPIPE
+    try { child.stdin?.end(stdin == null ? undefined : String(stdin)); }
+    catch { try { child.stdin?.end(); } catch { /* ignore */ } }
+  });
+}
+
+/** Nonzero/overflow/timeout fail even when output exists. */
+export function assertBoundedProcessOk(result) {
+  const fail = (code, message, details = null) => {
+    throw new ReviewExecError(message, { code, details });
+  };
+  if (result.terminationFailed) fail(REVIEW_EXEC_ERROR_CODES.TERMINATION_FAILED, "Process did not terminate after SIGTERM/SIGKILL.");
+  if (result.timedOut) fail(REVIEW_EXEC_ERROR_CODES.TIMEOUT, "Process timed out.", { signal: result.signal });
+  if (result.stdoutOverflow || result.stderrOverflow) {
+    fail(REVIEW_EXEC_ERROR_CODES.OUTPUT_OVERFLOW, "Process output exceeded capture limits.", {
+      stdoutOverflow: result.stdoutOverflow, stderrOverflow: result.stderrOverflow
+    });
+  }
+  if (result.status !== 0) {
+    fail(REVIEW_EXEC_ERROR_CODES.NONZERO_EXIT, `Process exited with status ${result.status}.`, {
+      status: result.status, signal: result.signal
+    });
+  }
+  return result;
+}
+
+function appendLimited(current, chunk, limit) {
+  if (current.length >= limit) return { text: current, overflow: true };
+  const next = current + String(chunk);
+  return next.length <= limit
+    ? { text: next, overflow: false }
+    : { text: next.slice(0, limit), overflow: true };
+}
+
+function safeKill(child, signal) {
+  try { return typeof child.kill === "function" ? child.kill(signal) !== false : false; }
+  catch { return false; }
+}

package/src/global/runtime/review/review-fs.js

@@ -0,0 +1,52 @@
+import { open, lstat } from "node:fs/promises";
+import { constants } from "node:fs";
+
+/** lstat + open; bind handle to validated inode via fstat (portable vs O_NOFOLLOW). */
+export async function readReviewRegularFile(absPath, {
+  lstatImpl = lstat, openImpl = open
+} = {}) {
+  let st;
+  try { st = await lstatImpl(absPath); }
+  catch (error) {
+    error.code = error.code ?? "ENOENT";
+    throw error;
+  }
+  if (st.isSymbolicLink()) {
+    const error = new Error(`Refusing symlink "${absPath}".`);
+    error.code = "REVIEW_SYMLINK";
+    throw error;
+  }
+  if (!st.isFile()) {
+    const error = new Error(`Refusing non-regular file "${absPath}".`);
+    error.code = "REVIEW_NON_REGULAR";
+    throw error;
+  }
+  const flags = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0);
+  let handle;
+  try {
+    handle = await openImpl(absPath, flags);
+  } catch (error) {
+    if (error?.code === "ELOOP" || error?.code === "EMLINK") {
+      const wrapped = new Error(`Refusing symlink "${absPath}".`);
+      wrapped.code = "REVIEW_SYMLINK";
+      throw wrapped;
+    }
+    throw error;
+  }
+  try {
+    const opened = await handle.stat();
+    if (!opened.isFile() || (typeof opened.isSymbolicLink === "function" && opened.isSymbolicLink())) {
+      const error = new Error(`Refusing non-regular handle "${absPath}".`);
+      error.code = "REVIEW_NON_REGULAR";
+      throw error;
+    }
+    if (opened.dev !== st.dev || opened.ino !== st.ino) {
+      const error = new Error(`Refusing identity change for "${absPath}".`);
+      error.code = "REVIEW_IDENTITY_CHANGED";
+      throw error;
+    }
+    return await handle.readFile();
+  } finally {
+    await handle.close();
+  }
+}

package/src/global/runtime/review/review-git.js

@@ -0,0 +1,212 @@
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import {
+  REVIEW_SCOPE_MODES,
+  REVIEW_SNAPSHOT_ERROR_CODES,
+  ReviewSnapshotError,
+  assertReviewPathSafe,
+  assertWithinReviewLimits,
+  canonicalFingerprint,
+  isBinaryContent,
+  isReviewPrivatePath,
+  requirePrivateConsent,
+  resolveReviewScopeMode
+} from "./review-types.js";
+import { readReviewRegularFile } from "./review-fs.js";
+
+export { readReviewRegularFile } from "./review-fs.js";
+
+const defaultExecFile = promisify(execFileCb);
+
+async function git(cwd, args, execFileImpl) {
+  try {
+    const { stdout } = await execFileImpl("git", args, {
+      cwd, encoding: "utf8", maxBuffer: 8 * 1024 * 1024
+    });
+    return stdout ?? "";
+  } catch (error) {
+    throw new ReviewSnapshotError(String(error?.stderr ?? error?.message ?? error).trim() || "git failed", { code: REVIEW_SNAPSHOT_ERROR_CODES.INVALID_REF, details: { args, status: error?.code ?? null } });
+  }
+}
+
+async function assertGitRepo(cwd, execFileImpl) {
+  try {
+    if ((await git(cwd, ["rev-parse", "--is-inside-work-tree"], execFileImpl)).trim() !== "true") {
+      throw new Error("not git");
+    }
+  } catch (error) {
+    if (error instanceof ReviewSnapshotError && error.code === REVIEW_SNAPSHOT_ERROR_CODES.INVALID_REF) {
+      throw new ReviewSnapshotError("Not a git repository.", {
+        code: REVIEW_SNAPSHOT_ERROR_CODES.NOT_A_GIT_REPO
+      });
+    }
+    throw error;
+  }
+}
+
+function unquotePath(path) {
+  if (path.startsWith("\"") && path.endsWith("\"")) {
+    try { return JSON.parse(path); } catch { return path.slice(1, -1); }
+  }
+  return path;
+}
+
+function parseNumstat(text) {
+  const byPath = new Map();
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    const [addedRaw, deletedRaw, pathRaw] = line.split("\t");
+    if (!pathRaw) continue;
+    const path = pathRaw.includes(" => ") ? pathRaw.split(" => ").at(-1) : pathRaw;
+    const n = (addedRaw === "-" ? 0 : Number(addedRaw)) + (deletedRaw === "-" ? 0 : Number(deletedRaw));
+    byPath.set(path, (byPath.get(path) ?? 0) + n);
+  }
+  return byPath;
+}
+
+function parsePorcelain(text) {
+  return text.split("\n").filter(Boolean).map((line) => {
+    const status = line.slice(0, 2);
+    const rest = line.slice(3);
+    if (rest.includes(" -> ")) {
+      const [from, to] = rest.split(" -> ");
+      return { status, sourcePath: unquotePath(from), path: unquotePath(to) };
+    }
+    return { status, sourcePath: null, path: unquotePath(rest) };
+  });
+}
+
+function parseNameStatus(text) {
+  return text.split("\n").filter((l) => l.trim()).map((line) => {
+    const parts = line.split("\t");
+    if (parts.length >= 3) {
+      return { status: parts[0], sourcePath: unquotePath(parts[1]), path: unquotePath(parts[2]) };
+    }
+    return { status: parts[0], sourcePath: null, path: unquotePath(parts[1]) };
+  });
+}
+
+function fingerprintPayload(s) {
+  return {
+    mode: s.mode, headSha: s.headSha, base: s.base ?? null, commit: s.commit ?? null,
+    files: s.files.map((f) => ({
+      path: f.path, sourcePath: f.sourcePath ?? null, status: f.status, hash: f.hash, changedLines: f.changedLines
+    })),
+    excluded: s.excluded.map((e) => ({ path: e.path, reason: e.reason }))
+  };
+}
+
+/** Bounded Git review snapshot via argv-only git (no shell, no repo writes). */
+export async function resolveReviewSnapshot({
+  cwd, base = null, commit = null, includePrivate = false, privateConfirmed = false,
+  execFileImpl = defaultExecFile
+} = {}) {
+  const mode = resolveReviewScopeMode({ base, commit });
+  await assertGitRepo(cwd, execFileImpl);
+  const headSha = (await git(cwd, ["rev-parse", "HEAD"], execFileImpl)).trim();
+  let rawEntries = [];
+  let numstat = new Map();
+  let diffBytes = 0;
+
+  if (mode === REVIEW_SCOPE_MODES.WORKING_TREE) {
+    rawEntries = parsePorcelain(await git(cwd, ["status", "--porcelain=v1", "-uall"], execFileImpl));
+    numstat = new Map([
+      ...parseNumstat(await git(cwd, ["diff", "--numstat"], execFileImpl)),
+      ...parseNumstat(await git(cwd, ["diff", "--cached", "--numstat"], execFileImpl))
+    ]);
+    diffBytes = Buffer.byteLength(await git(cwd, ["diff"], execFileImpl), "utf8")
+      + Buffer.byteLength(await git(cwd, ["diff", "--cached"], execFileImpl), "utf8");
+  } else if (mode === REVIEW_SCOPE_MODES.BASE) {
+    const range = `${base}...HEAD`;
+    await git(cwd, ["rev-parse", "--verify", base], execFileImpl);
+    rawEntries = parseNameStatus(await git(cwd, ["diff", "--name-status", range], execFileImpl));
+    numstat = parseNumstat(await git(cwd, ["diff", "--numstat", range], execFileImpl));
+    diffBytes = Buffer.byteLength(await git(cwd, ["diff", range], execFileImpl), "utf8");
+  } else {
+    await git(cwd, ["rev-parse", "--verify", `${commit}^{commit}`], execFileImpl);
+    rawEntries = parseNameStatus(
+      await git(cwd, ["diff-tree", "--no-commit-id", "--name-status", "-r", commit], execFileImpl)
+    );
+    numstat = parseNumstat(
+      await git(cwd, ["diff-tree", "--no-commit-id", "--numstat", "-r", commit], execFileImpl)
+    );
+    diffBytes = Buffer.byteLength(await git(cwd, ["show", "--format=", "--patch", commit], execFileImpl), "utf8");
+  }
+
+  const excluded = [];
+  const privateCandidates = [];
+  const files = [];
+
+  for (const entry of rawEntries) {
+    const path = assertReviewPathSafe(entry.path);
+    const sourcePath = entry.sourcePath != null ? assertReviewPathSafe(entry.sourcePath) : null;
+    const privateEnds = [path, sourcePath].filter(Boolean).filter((p) => isReviewPrivatePath(p));
+    if (privateEnds.length > 0) {
+      if (includePrivate) privateCandidates.push(...privateEnds);
+      else { excluded.push({ path, reason: "private" }); continue; }
+    }
+
+    let hash;
+    let changedLines = numstat.get(path) ?? 0;
+    let bytes = 0;
+    const deleted = /D/.test(entry.status);
+
+    if (mode === REVIEW_SCOPE_MODES.WORKING_TREE && !deleted) {
+      let buffer;
+      try { buffer = await readReviewRegularFile(join(cwd, path)); }
+      catch (error) {
+        if (error?.code === "REVIEW_SYMLINK") { excluded.push({ path, reason: "symlink" }); continue; }
+        if (error?.code === "REVIEW_NON_REGULAR" || error?.code === "REVIEW_IDENTITY_CHANGED") {
+          excluded.push({ path, reason: "non-regular" }); continue;
+        }
+        throw error;
+      }
+      if (isBinaryContent(buffer)) { excluded.push({ path, reason: "binary" }); continue; }
+      hash = createHash("sha256").update(buffer).digest("hex");
+      bytes = buffer.length;
+      if (!numstat.has(path)) changedLines = buffer.toString("utf8").split(/\r?\n/).length;
+      if (entry.status === "??") diffBytes += bytes;
+    } else {
+      try { hash = (await git(cwd, ["rev-parse", `HEAD:${path}`], execFileImpl)).trim(); }
+      catch { hash = createHash("sha256").update(`${entry.status}:${path}`).digest("hex"); }
+    }
+
+    files.push({
+      path, sourcePath, status: entry.status.trim(), hash, changedLines, bytes
+    });
+  }
+
+  requirePrivateConsent({ includePrivate, privateConfirmed, privatePaths: privateCandidates });
+  files.sort((a, b) => a.path.localeCompare(b.path));
+  excluded.sort((a, b) => a.path.localeCompare(b.path));
+  const changedLines = files.reduce((sum, f) => sum + f.changedLines, 0);
+  assertWithinReviewLimits({ fileCount: files.length, changedLines, diffBytes });
+
+  const snapshot = {
+    version: 1, mode, cwd, headSha, base: base ?? null, commit: commit ?? null,
+    files, excluded, totals: { fileCount: files.length, changedLines, diffBytes }, fingerprint: null
+  };
+  snapshot.fingerprint = canonicalFingerprint(fingerprintPayload(snapshot));
+  return snapshot;
+}
+
+export function fingerprintReviewSnapshot(snapshot) {
+  return canonicalFingerprint(fingerprintPayload(snapshot));
+}
+
+export async function detectReviewSnapshotDrift(previous, options = {}) {
+  const next = await resolveReviewSnapshot({
+    cwd: previous.cwd, base: previous.base, commit: previous.commit,
+    includePrivate: options.includePrivate ?? false,
+    privateConfirmed: options.privateConfirmed ?? false,
+    execFileImpl: options.execFileImpl
+  });
+  return {
+    stale: next.fingerprint !== previous.fingerprint,
+    previousFingerprint: previous.fingerprint,
+    nextFingerprint: next.fingerprint,
+    next
+  };
+}