@kal-elsam/kairo-runtime 0.6.0 → 0.7.0

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

@@ -0,0 +1,122 @@
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+import { join } from "node:path";
+import { REVIEW_SCOPE_MODES } from "./review-types.js";
+import { ReviewExecError } from "./review-exec.js";
+import { readReviewRegularFile } from "./review-fs.js";
+
+export const REVIEW_PATCH_ERROR_CODES = Object.freeze({
+  INVALID_CWD: "invalid_cwd", GIT_FAILED: "git_failed"
+});
+
+const defaultExecFile = promisify(execFileCb);
+
+async function gitDiff(cwd, args, execFileImpl) {
+  try {
+    const { stdout } = await execFileImpl("git", args, {
+      cwd, encoding: "utf8", maxBuffer: 8 * 1024 * 1024
+    });
+    return stdout ?? "";
+  } catch (error) {
+    if ((error?.code === 1 || error?.status === 1) && typeof error.stdout === "string") {
+      return error.stdout;
+    }
+    throw new ReviewExecError(String(error?.stderr ?? error?.message ?? error).trim() || "git failed", {
+      code: REVIEW_PATCH_ERROR_CODES.GIT_FAILED, details: { args }
+    });
+  }
+}
+
+function unquoteGitPath(path) {
+  if (path.startsWith("\"") && path.endsWith("\"")) {
+    try { return JSON.parse(path); } catch { return path.slice(1, -1); }
+  }
+  return path;
+}
+
+function pathsFromGitDiffHeader(line) {
+  const match = /^diff --git a\/(.+) b\/(.+)$/.exec(line);
+  if (!match) return [];
+  return [unquoteGitPath(match[1]), unquoteGitPath(match[2])];
+}
+
+/** Keep only unified-diff sections whose every a/b endpoint is admitted. */
+export function filterDiffToAdmittedPaths(diffText, admittedPaths) {
+  const admitted = new Set(admittedPaths);
+  if (admitted.size === 0) return "";
+  const out = [];
+  let keep = false;
+  for (const line of String(diffText ?? "").split(/\r?\n/)) {
+    if (line.startsWith("diff --git ")) {
+      const paths = pathsFromGitDiffHeader(line);
+      keep = paths.length > 0 && paths.every((path) => admitted.has(path));
+    }
+    if (keep) out.push(line);
+  }
+  while (out.length && out.at(-1) === "") out.pop();
+  return out.length ? `${out.join("\n")}\n` : "";
+}
+
+function synthesizeNewFileDiff(path, content) {
+  const raw = String(content);
+  const body = raw.endsWith("\n") ? raw.slice(0, -1).split("\n") : raw.split("\n");
+  const hunk = body.length === 0
+    ? ["@@ -0,0 +0,0 @@"]
+    : [`@@ -0,0 +1,${body.length} @@`, ...body.map((line) => `+${line}`)];
+  return [
+    `diff --git a/${path} b/${path}`, "new file mode 100644", "--- /dev/null", `+++ b/${path}`,
+    ...hunk, ""
+  ].join("\n");
+}
+
+function admittedPaths(files) {
+  const paths = [];
+  for (const file of files) {
+    if (file.path) paths.push(file.path);
+    if (file.sourcePath) paths.push(file.sourcePath);
+  }
+  return paths;
+}
+
+/**
+ * Host-generated unified diff limited to snapshot.files paths.
+ * Covers WT (unstaged/staged/untracked/deleted), base, and commit scopes.
+ * Never includes excluded/private paths from snapshot.excluded.
+ */
+export async function buildScopedReviewPatch(snapshot, { execFileImpl = defaultExecFile } = {}) {
+  const cwd = snapshot?.cwd;
+  if (typeof cwd !== "string" || !cwd) {
+    throw new ReviewExecError("Scoped review patch requires snapshot.cwd.", {
+      code: REVIEW_PATCH_ERROR_CODES.INVALID_CWD
+    });
+  }
+  const files = Array.isArray(snapshot.files) ? snapshot.files : [];
+  const admitted = admittedPaths(files);
+  if (admitted.length === 0) return "";
+
+  let raw = "";
+  if (snapshot.mode === REVIEW_SCOPE_MODES.BASE) {
+    raw = await gitDiff(cwd, ["diff", `${snapshot.base}...HEAD`, "--", ...admitted], execFileImpl);
+  } else if (snapshot.mode === REVIEW_SCOPE_MODES.COMMIT) {
+    raw = await gitDiff(
+      cwd, ["show", "--format=", "--patch", snapshot.commit, "--", ...admitted], execFileImpl
+    );
+  } else {
+    raw = [
+      await gitDiff(cwd, ["diff", "--", ...admitted], execFileImpl),
+      await gitDiff(cwd, ["diff", "--cached", "--", ...admitted], execFileImpl)
+    ].join("");
+    for (const file of files) {
+      if (file.status !== "??") continue;
+      try {
+        const buffer = await readReviewRegularFile(join(cwd, file.path));
+        raw += synthesizeNewFileDiff(file.path, buffer.toString("utf8"));
+      } catch (error) {
+        if (error?.code === "REVIEW_SYMLINK" || error?.code === "REVIEW_NON_REGULAR"
+          || error?.code === "REVIEW_IDENTITY_CHANGED") continue;
+        throw error;
+      }
+    }
+  }
+  return filterDiffToAdmittedPaths(raw, admitted);
+}

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

@@ -0,0 +1,168 @@
+import { REVIEW_AGENTS, REVIEW_SCOPE_MODES } from "./review-types.js";
+import { ReviewExecError, assertBoundedProcessOk, runBoundedProcess } from "./review-exec.js";
+import { buildScopedReviewPatch } from "./review-patch.js";
+import { validateReviewOutput } from "./review-validate.js";
+
+export const REVIEW_PI_ERROR_CODES = Object.freeze({
+  INVALID_JSONL: "invalid_jsonl", MISSING_AGENT_MESSAGE: "missing_agent_message",
+  STREAM_ERROR: "stream_error", INVALID_CWD: "invalid_cwd"
+});
+
+const EXECUTABLE = "pi";
+const READ_ONLY_TOOLS = "read,grep,find,ls";
+const CLI_ENV_KEYS = Object.freeze([
+  "PATH", "HOME", "USER", "LOGNAME", "SHELL", "LANG", "LC_ALL", "LC_CTYPE", "TMPDIR", "TERM",
+  "ANTHROPIC_API_KEY", "OPENAI_API_KEY", "OPENAI_BASE_URL", "GOOGLE_API_KEY", "GEMINI_API_KEY",
+  "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("Pi review requires snapshot.cwd.", {
+      code: REVIEW_PI_ERROR_CODES.INVALID_CWD
+    });
+  }
+  return cwd;
+}
+
+/** JSON mode, ephemeral, read-only tools, ambient resources + project trust off. Prompt via stdin. */
+export function buildPiReviewArgs(snapshot, { model = null } = {}) {
+  requireSnapshotCwd(snapshot);
+  const args = [
+    "--mode", "json", "--no-session",
+    "--tools", READ_ONLY_TOOLS,
+    "--no-extensions", "--no-skills", "--no-prompt-templates", "--no-context-files",
+    "--no-approve"
+  ];
+  if (model) args.push("--model", String(model));
+  return args;
+}
+
+/** Preserve only env needed to start/authenticate the CLI. */
+export function buildPiCliEnv(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 header: mode + scope ref + admitted paths (patch follows on stdin). */
+export function buildPiReviewPrompt(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");
+}
+
+/** Stdin payload for Pi JSON mode: prompt + host-scoped patch. Never persisted. */
+export function buildPiReviewStdin(snapshot, patch) {
+  const body = typeof patch === "string" && patch.trim() !== "" ? patch.trimEnd() : "(empty patch)";
+  return `${buildPiReviewPrompt(snapshot)}\n\nScoped patch (host-generated; review this diff only; do not run git):\n${body}\n`;
+}
+
+function assistantText(message) {
+  if (!Array.isArray(message?.content)) return null;
+  const text = message.content
+    .filter((block) => block?.type === "text" && typeof block.text === "string")
+    .map((block) => block.text)
+    .join("");
+  return text.trim() === "" ? null : text;
+}
+
+function normalizeUsage(usage) {
+  if (!usage || typeof usage !== "object") return null;
+  const input = Number.isFinite(usage.input) ? usage.input
+    : Number.isFinite(usage.inputTokens) ? usage.inputTokens
+      : Number.isFinite(usage.input_tokens) ? usage.input_tokens : null;
+  const output = Number.isFinite(usage.output) ? usage.output
+    : Number.isFinite(usage.outputTokens) ? usage.outputTokens
+      : Number.isFinite(usage.output_tokens) ? usage.output_tokens : null;
+  const total = Number.isFinite(usage.totalTokens) ? usage.totalTokens
+    : Number.isFinite(usage.total) ? usage.total
+      : Number.isFinite(usage.total_tokens) ? usage.total_tokens
+        : input != null && output != null ? input + output : null;
+  const cost = typeof usage.cost === "number" ? usage.cost
+    : typeof usage.cost?.total === "number" ? usage.cost.total : null;
+  return { inputTokens: input, outputTokens: output, totalTokens: total, cost };
+}
+
+/** Parse Pi JSONL: last assistant message_end + turn_end usage. Trailing partial ignored. */
+export function parsePiReviewJsonl(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 Pi JSONL: ${error.message}`, {
+        code: REVIEW_PI_ERROR_CODES.INVALID_JSONL
+      });
+    }
+    if (!event || typeof event !== "object") {
+      throw new ReviewExecError("Malformed Pi JSONL event.", {
+        code: REVIEW_PI_ERROR_CODES.INVALID_JSONL
+      });
+    }
+    if (event.type === "error") {
+      streamError = String(event.message ?? event.errorMessage ?? "Pi stream error.");
+    } else if (event.type === "message_end" && event.message?.role === "assistant") {
+      const stop = event.message.stopReason;
+      if (stop === "error" || stop === "aborted") {
+        streamError = String(event.message.errorMessage ?? `Pi stopReason ${stop}.`);
+      } else {
+        const text = assistantText(event.message);
+        if (text != null) agentText = text;
+      }
+    } else if (event.type === "turn_end") {
+      const next = normalizeUsage(event.message?.usage);
+      if (next) usage = next;
+    }
+  }
+  if (streamError) throw new ReviewExecError(streamError, { code: REVIEW_PI_ERROR_CODES.STREAM_ERROR });
+  if (typeof agentText !== "string" || agentText.trim() === "") {
+    throw new ReviewExecError("Pi JSONL missing final assistant message_end.", {
+      code: REVIEW_PI_ERROR_CODES.MISSING_AGENT_MESSAGE
+    });
+  }
+  return { agentText, usage };
+}
+
+/** Run Pi read-only review bound to snapshot.cwd. No receipts/drift/raw streams/patch. */
+export async function runPiReview({
+  snapshot, model = null, env = process.env, spawnImpl,
+  timeoutMs, terminationGraceMs, killGraceMs,
+  buildPatch = buildScopedReviewPatch, runProcess = runBoundedProcess
+} = {}) {
+  const cwd = requireSnapshotCwd(snapshot);
+  const requestedModel = model == null || model === "" ? null : String(model);
+  const patch = await buildPatch(snapshot);
+  const result = await runProcess({
+    command: EXECUTABLE, args: buildPiReviewArgs(snapshot, { model: requestedModel }), cwd,
+    env: buildPiCliEnv(env), stdin: buildPiReviewStdin(snapshot, patch),
+    spawnImpl, timeoutMs, terminationGraceMs, killGraceMs
+  });
+  assertBoundedProcessOk(result);
+  const parsed = parsePiReviewJsonl(result.stdout);
+  const validated = validateReviewOutput(parsed.agentText, snapshot);
+  return {
+    agentId: REVIEW_AGENTS.PI, model: requestedModel,
+    findings: validated.findings, warnings: validated.warnings, usage: parsed.usage
+  };
+}

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

@@ -0,0 +1,128 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { harnessHomePaths } from "../../paths.js";
+import { writeAtomicJson } from "../write-atomic-json.js";
+import { REVIEW_STATES } from "./review-types.js";
+import {
+  REVIEW_VALIDATION_ERROR_CODES,
+  ReviewValidationError,
+  assertReceiptSecretFree
+} from "./review-validate.js";
+
+export function assertSafeReviewId(reviewId) {
+  if (typeof reviewId !== "string" || !/^rev-[a-f0-9]{16,32}$/.test(reviewId)) {
+    throw new Error(`Invalid review id "${reviewId}".`);
+  }
+}
+
+export function createReviewId() {
+  return `rev-${randomBytes(12).toString("hex")}`;
+}
+
+export function reviewPaths(homeDir, reviewId) {
+  assertSafeReviewId(reviewId);
+  const reviewDir = join(harnessHomePaths(homeDir).reviewsDir, reviewId);
+  return { reviewDir, receiptPath: join(reviewDir, "receipt.json") };
+}
+
+function snapshotProvenance(snapshot) {
+  return {
+    mode: snapshot.mode,
+    headSha: snapshot.headSha,
+    base: snapshot.base ?? null,
+    commit: snapshot.commit ?? null,
+    fingerprint: snapshot.fingerprint,
+    totals: snapshot.totals,
+    files: (snapshot.files ?? []).map((f) => ({
+      path: f.path,
+      sourcePath: f.sourcePath ?? null,
+      status: f.status, hash: f.hash, changedLines: f.changedLines
+    })),
+    excluded: (snapshot.excluded ?? []).map((e) => ({ path: e.path, reason: e.reason }))
+  };
+}
+
+/** Build a v1 receipt: findings + provenance only (no prompt/diff/transcript/raw). */
+export function buildReviewReceipt({
+  reviewId,
+  agentId,
+  model = null,
+  snapshot,
+  state = REVIEW_STATES.COMPLETED,
+  findings = [],
+  warnings = [],
+  usage = null,
+  timings = null,
+  cliVersion = null,
+  createdAt = null
+} = {}) {
+  assertSafeReviewId(reviewId);
+  const receipt = {
+    version: 1,
+    reviewId,
+    agentId,
+    model,
+    state,
+    snapshot: snapshotProvenance(snapshot),
+    findings,
+    warnings,
+    usage,
+    timings: timings && typeof timings === "object"
+      ? {
+        startedAt: timings.startedAt ?? null,
+        finishedAt: timings.finishedAt ?? null,
+        durationMs: Number.isFinite(timings.durationMs) ? timings.durationMs : null
+      }
+      : null,
+    cliVersion,
+    createdAt: createdAt ?? new Date().toISOString()
+  };
+  return assertReceiptSecretFree(receipt);
+}
+
+/** Write-once create-if-absent via exclusive link; EEXIST → RECEIPT_EXISTS. */
+export async function saveReviewReceipt(receipt, { homeDir } = {}) {
+  const sanitized = assertReceiptSecretFree(receipt);
+  assertSafeReviewId(sanitized.reviewId);
+  const { reviewDir, receiptPath } = reviewPaths(homeDir, sanitized.reviewId);
+  await mkdir(reviewDir, { recursive: true });
+  try {
+    await writeAtomicJson(receiptPath, sanitized, { createExclusive: true });
+  } catch (error) {
+    if (error?.code === "EEXIST") {
+      throw new ReviewValidationError(`Review receipt already exists: ${sanitized.reviewId}`, {
+        code: REVIEW_VALIDATION_ERROR_CODES.RECEIPT_EXISTS,
+        details: { reviewId: sanitized.reviewId, path: receiptPath }
+      });
+    }
+    throw error;
+  }
+  return { path: receiptPath, receipt: sanitized };
+}
+
+export async function loadReviewReceipt(reviewId, { homeDir } = {}) {
+  const { receiptPath } = reviewPaths(homeDir, reviewId);
+  if (!existsSync(receiptPath)) throw new Error(`Review receipt not found: ${reviewId}`);
+  return assertReceiptSecretFree(JSON.parse(await readFile(receiptPath, "utf8")));
+}
+
+/** Load → sort by createdAt desc, reviewId asc → apply limit. */
+export async function listReviewReceipts({ homeDir, limit = null } = {}) {
+  const dir = harnessHomePaths(homeDir).reviewsDir;
+  if (!existsSync(dir)) return [];
+  const ids = (await readdir(dir)).filter((name) => /^rev-[a-f0-9]{16,32}$/.test(name));
+  const receipts = [];
+  for (const reviewId of ids) {
+    try {
+      receipts.push(await loadReviewReceipt(reviewId, { homeDir }));
+    } catch {
+      // Skip corrupt/partial directories fail-closed for list readers.
+    }
+  }
+  receipts.sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt))
+    || String(a.reviewId).localeCompare(String(b.reviewId)));
+  if (limit == null) return receipts;
+  return receipts.slice(0, Math.max(0, Number(limit) || 0));
+}

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

@@ -0,0 +1,119 @@
+import {
+  REVIEW_AGENTS, REVIEW_EXIT_CODES, REVIEW_SEVERITIES, REVIEW_STATES
+} from "./review-types.js";
+import {
+  resolveReviewSnapshot, detectReviewSnapshotDrift
+} from "./review-git.js";
+import {
+  buildReviewReceipt, createReviewId, saveReviewReceipt
+} from "./review-receipts.js";
+import { ReviewValidationError } from "./review-validate.js";
+import { runCodexReview } from "./review-codex.js";
+import { runPiReview } from "./review-pi.js";
+
+export const REVIEW_RUNNER_ERROR_CODES = Object.freeze({
+  UNKNOWN_AGENT: "unknown_agent",
+  CANCELLED: "cancelled"
+});
+
+const SEVERITY_RANK = Object.freeze({
+  [REVIEW_SEVERITIES.HIGH]: 3,
+  [REVIEW_SEVERITIES.MEDIUM]: 2,
+  [REVIEW_SEVERITIES.LOW]: 1
+});
+
+export class ReviewRunnerError extends Error {
+  constructor(message, { code, details = null } = {}) {
+    super(message);
+    this.name = "ReviewRunnerError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+/** Reject unknown agents before any Git snapshot work. */
+export function resolveReviewAgent(agent) {
+  const id = String(agent ?? "").trim().toLowerCase();
+  if (id === REVIEW_AGENTS.CODEX || id === REVIEW_AGENTS.PI) return id;
+  throw new ReviewRunnerError(
+    `Unknown review agent "${agent ?? ""}". Use --agent codex|pi.`,
+    { code: REVIEW_RUNNER_ERROR_CODES.UNKNOWN_AGENT, details: { agent } }
+  );
+}
+
+export function resolveReviewExitCode({ state, findings = [], failOn = null } = {}) {
+  if (state !== REVIEW_STATES.COMPLETED) return REVIEW_EXIT_CODES.ERROR;
+  if (!failOn) return REVIEW_EXIT_CODES.OK;
+  const threshold = SEVERITY_RANK[failOn] ?? 0;
+  if (threshold === 0) return REVIEW_EXIT_CODES.OK;
+  const hit = findings.some((f) => (SEVERITY_RANK[f.severity] ?? 0) >= threshold);
+  return hit ? REVIEW_EXIT_CODES.THRESHOLD : REVIEW_EXIT_CODES.OK;
+}
+
+function classifyAgentError(error) {
+  if (error instanceof ReviewValidationError) return REVIEW_STATES.INVALID;
+  return REVIEW_STATES.FAILED;
+}
+
+/**
+ * Snapshot → Codex|Pi → drift revalidation → write-once receipt.
+ * Never returns/persists prompt, patch, JSONL, or transcript.
+ */
+export async function runReview({
+  cwd, agent, base = null, commit = null, model = null,
+  includePrivate = false, privateConfirmed = false, failOn = null,
+  homeDir, cliVersion = null,
+  resolveSnapshot = resolveReviewSnapshot,
+  detectDrift = detectReviewSnapshotDrift,
+  runCodex = runCodexReview, runPi = runPiReview,
+  saveReceipt = saveReviewReceipt, createId = createReviewId,
+  now = () => new Date().toISOString()
+} = {}) {
+  const agentId = resolveReviewAgent(agent);
+  const reviewId = createId();
+  const startedAt = now();
+  const snapshot = await resolveSnapshot({
+    cwd, base, commit, includePrivate, privateConfirmed
+  });
+
+  let state = REVIEW_STATES.COMPLETED;
+  let findings = [];
+  let warnings = [];
+  let usage = null;
+  let resolvedModel = model == null || model === "" ? null : String(model);
+
+  try {
+    const result = agentId === REVIEW_AGENTS.CODEX
+      ? await runCodex({ snapshot, model: resolvedModel })
+      : await runPi({ snapshot, model: resolvedModel });
+    findings = Array.isArray(result.findings) ? result.findings : [];
+    warnings = Array.isArray(result.warnings) ? result.warnings : [];
+    usage = result.usage ?? null;
+    resolvedModel = result.model ?? resolvedModel;
+  } catch (error) {
+    state = classifyAgentError(error);
+    warnings = [String(error?.message ?? error)];
+  }
+
+  const drift = await detectDrift(snapshot, { includePrivate, privateConfirmed });
+  if (drift.stale) state = REVIEW_STATES.STALE;
+
+  const finishedAt = now();
+  const durationMs = Date.parse(finishedAt) - Date.parse(startedAt);
+  const receipt = buildReviewReceipt({
+    reviewId, agentId, model: resolvedModel, snapshot, state,
+    findings, warnings, usage,
+    timings: {
+      startedAt, finishedAt,
+      durationMs: Number.isFinite(durationMs) ? durationMs : null
+    },
+    cliVersion
+  });
+  await saveReceipt(receipt, { homeDir });
+
+  return {
+    receipt,
+    exitCode: resolveReviewExitCode({ state, findings, failOn }),
+    stale: Boolean(drift.stale)
+  };
+}

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

@@ -0,0 +1,108 @@
+import { createHash } from "node:crypto";
+
+export const REVIEW_SCOPE_MODES = Object.freeze({
+  WORKING_TREE: "working-tree", BASE: "base", COMMIT: "commit"
+});
+export const REVIEW_SEVERITIES = Object.freeze({ HIGH: "high", MEDIUM: "medium", LOW: "low" });
+export const REVIEW_STATES = Object.freeze({
+  COMPLETED: "completed", FAILED: "failed", STALE: "stale", INVALID: "invalid"
+});
+export const REVIEW_EXIT_CODES = Object.freeze({ OK: 0, THRESHOLD: 1, ERROR: 2 });
+export const REVIEW_AGENTS = Object.freeze({ CODEX: "codex", PI: "pi" });
+export const REVIEW_LIMITS = Object.freeze({
+  MAX_FILES: 100, MAX_CHANGED_LINES: 400, MAX_DIFF_BYTES: 256 * 1024
+});
+export const REVIEW_SNAPSHOT_ERROR_CODES = Object.freeze({
+  NOT_A_GIT_REPO: "not_a_git_repo",
+  INVALID_REF: "invalid_ref",
+  INVALID_SCOPE: "invalid_scope",
+  INVALID_PATH: "invalid_path",
+  LIMIT_EXCEEDED: "limit_exceeded",
+  PRIVATE_CONSENT_REQUIRED: "private_consent_required"
+});
+
+export class ReviewSnapshotError extends Error {
+  constructor(message, { code, details = null } = {}) {
+    super(message);
+    this.name = "ReviewSnapshotError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export function resolveReviewScopeMode({ base = null, commit = null } = {}) {
+  if (base && commit) {
+    throw new ReviewSnapshotError("--base and --commit are mutually exclusive.", {
+      code: REVIEW_SNAPSHOT_ERROR_CODES.INVALID_SCOPE
+    });
+  }
+  if (base) return REVIEW_SCOPE_MODES.BASE;
+  if (commit) return REVIEW_SCOPE_MODES.COMMIT;
+  return REVIEW_SCOPE_MODES.WORKING_TREE;
+}
+
+export function createFindingId({ severity, title, path, line = null, problem }) {
+  return createHash("sha256")
+    .update([severity, title, path, line ?? "", problem].map(String).join("\0"))
+    .digest("hex")
+    .slice(0, 16);
+}
+
+export function canonicalFingerprint(parts) {
+  return createHash("sha256").update(JSON.stringify(parts)).digest("hex");
+}
+
+const PRIVATE_PATH_PATTERNS = [
+  /^\.env(\.|$)/i, /(^|\/)\.env(\.|$)/i, /(^|\/)secrets?\//i, /(^|\/)credentials?\./i,
+  /\.pem$/i, /\.key$/i, /(^|\/)id_rsa/i, /(^|\/)\.npmrc$/i, /(^|\/)\.netrc$/i
+];
+
+export function isReviewPrivatePath(relativePath) {
+  return PRIVATE_PATH_PATTERNS.some((p) => p.test(String(relativePath ?? "").replace(/\\/g, "/")));
+}
+
+export function isBinaryContent(buffer) {
+  return Buffer.isBuffer(buffer) && buffer.subarray(0, Math.min(buffer.length, 8192)).includes(0);
+}
+
+export function assertReviewPathSafe(relativePath) {
+  const raw = String(relativePath ?? "");
+  const normalized = raw.replace(/\\/g, "/");
+  if (
+    !normalized || normalized.startsWith("/") || normalized.includes("\0")
+    || normalized.split("/").some((part) => part === ".." || part === "")
+  ) {
+    throw new ReviewSnapshotError(`Unsafe review path "${raw}".`, {
+      code: REVIEW_SNAPSHOT_ERROR_CODES.INVALID_PATH, details: { path: raw }
+    });
+  }
+  return normalized;
+}
+
+export function assertWithinReviewLimits({
+  fileCount, changedLines, diffBytes, limits = REVIEW_LIMITS
+} = {}) {
+  const reasons = [];
+  if (fileCount > limits.MAX_FILES) reasons.push(`files ${fileCount} > ${limits.MAX_FILES}`);
+  if (changedLines > limits.MAX_CHANGED_LINES) {
+    reasons.push(`changed lines ${changedLines} > ${limits.MAX_CHANGED_LINES}`);
+  }
+  if (diffBytes > limits.MAX_DIFF_BYTES) {
+    reasons.push(`diff bytes ${diffBytes} > ${limits.MAX_DIFF_BYTES}`);
+  }
+  if (reasons.length === 0) return;
+  throw new ReviewSnapshotError(`Review scope exceeds fail-closed limits (${reasons.join("; ")}).`, {
+    code: REVIEW_SNAPSHOT_ERROR_CODES.LIMIT_EXCEEDED,
+    details: { fileCount, changedLines, diffBytes, limits, reasons }
+  });
+}
+
+export function requirePrivateConsent({
+  includePrivate = false, privateConfirmed = false, privatePaths = []
+} = {}) {
+  if (!includePrivate || privatePaths.length === 0 || privateConfirmed) return;
+  throw new ReviewSnapshotError(
+    "Including private paths requires explicit consent (--include-private with --yes/--confirm, or interactive confirmation).",
+    { code: REVIEW_SNAPSHOT_ERROR_CODES.PRIVATE_CONSENT_REQUIRED, details: { privatePaths } }
+  );
+}