@kal-elsam/kairo-runtime 0.6.0 → 0.8.0

package/src/global/runtime/orchestration/orch-receipts.js

@@ -0,0 +1,234 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { runPaths } from "../../paths.js";
+import { writeAtomicJson } from "../write-atomic-json.js";
+import {
+  DAG_NODE_STATES, ORCH_ERROR_CODES, OrchContractError, RUN_STRATEGIES,
+  createBudgetUsage, createDagNode, createMinionResult, createOrchLineage,
+  digestAllowlisted, isTerminalDagState, normalizeRunStrategy
+} from "./orch-types.js";
+import { assertOrchReceiptSecretFree, walkForbiddenKeys } from "./orch-validate.js";
+
+export function orchPaths(homeDir, rootRunId) {
+  if (typeof rootRunId !== "string" || !rootRunId) {
+    throw new OrchContractError("rootRunId is required for orchestration paths.", {
+      code: ORCH_ERROR_CODES.INVALID_LINEAGE
+    });
+  }
+  const { runDir } = runPaths(homeDir, rootRunId);
+  const orchDir = join(runDir, "orchestration");
+  return {
+    runDir, orchDir,
+    receiptPath: join(orchDir, "receipt.json"),
+    statePath: join(orchDir, "state.json")
+  };
+}
+
+function normalizeNodes(nodes = []) {
+  return nodes.map((node) => {
+    const { objective, ...rest } = node;
+    return createDagNode({
+      ...rest,
+      budget: createBudgetUsage(rest.budget ?? {}),
+      objectiveDigest: rest.objectiveDigest
+        ?? (objective ? digestAllowlisted({ objective }) : null)
+    });
+  });
+}
+
+export function buildOrchReceipt({
+  rootRunId, strategy = RUN_STRATEGIES.ORCHESTRATED, lineage = null,
+  nodes = [], results = [], cliVersion = null, createdAt = null, recovered = false
+} = {}) {
+  const normalizedStrategy = normalizeRunStrategy(strategy);
+  const normalizedLineage = createOrchLineage(lineage ?? { rootRunId, parentRunId: null, depth: 0 });
+  if (normalizedLineage.rootRunId !== rootRunId) {
+    throw new OrchContractError("lineage.rootRunId must match receipt rootRunId.", {
+      code: ORCH_ERROR_CODES.INVALID_LINEAGE
+    });
+  }
+  return assertOrchReceiptSecretFree({
+    version: 1, strategy: normalizedStrategy, rootRunId, lineage: normalizedLineage,
+    nodes: normalizeNodes(nodes),
+    results: results.map((entry) => createMinionResult(entry)),
+    createdAt: createdAt ?? new Date().toISOString(),
+    cliVersion,
+    recovered: Boolean(recovered)
+  });
+}
+
+export async function saveOrchReceipt(receipt, { homeDir } = {}) {
+  const sanitized = assertOrchReceiptSecretFree(receipt);
+  const { orchDir, receiptPath } = orchPaths(homeDir, sanitized.rootRunId);
+  await mkdir(orchDir, { recursive: true });
+  try {
+    await writeAtomicJson(receiptPath, sanitized, { createExclusive: true });
+  } catch (error) {
+    if (error?.code === "EEXIST") {
+      throw new OrchContractError(`Orchestration receipt already exists: ${sanitized.rootRunId}`, {
+        code: ORCH_ERROR_CODES.RECEIPT_EXISTS,
+        details: { rootRunId: sanitized.rootRunId, path: receiptPath }
+      });
+    }
+    throw error;
+  }
+  return { path: receiptPath, receipt: sanitized };
+}
+
+export async function loadOrchReceipt(rootRunId, { homeDir } = {}) {
+  const { receiptPath } = orchPaths(homeDir, rootRunId);
+  if (!existsSync(receiptPath)) {
+    throw new OrchContractError(`Orchestration receipt not found: ${rootRunId}`, {
+      code: ORCH_ERROR_CODES.INVALID_LINEAGE, details: { rootRunId }
+    });
+  }
+  return assertOrchReceiptSecretFree(JSON.parse(await readFile(receiptPath, "utf8")));
+}
+
+export function createOrchState({
+  rootRunId, strategy = RUN_STRATEGIES.ORCHESTRATED, lineage = null,
+  nodes = [], results = [], cliVersion = null, updatedAt = null
+} = {}) {
+  const normalizedStrategy = normalizeRunStrategy(strategy);
+  if (normalizedStrategy !== RUN_STRATEGIES.ORCHESTRATED) {
+    throw new OrchContractError("Orchestration state requires strategy orchestrated.", {
+      code: ORCH_ERROR_CODES.INVALID_STRATEGY
+    });
+  }
+  const normalizedLineage = createOrchLineage(lineage ?? { rootRunId, parentRunId: null, depth: 0 });
+  if (normalizedLineage.rootRunId !== rootRunId) {
+    throw new OrchContractError("lineage.rootRunId must match state rootRunId.", {
+      code: ORCH_ERROR_CODES.INVALID_LINEAGE
+    });
+  }
+  const state = {
+    version: 1, strategy: normalizedStrategy, rootRunId, lineage: normalizedLineage,
+    nodes: normalizeNodes(nodes),
+    results: (results ?? []).map((entry) => createMinionResult(entry)),
+    cliVersion: cliVersion ?? null,
+    updatedAt: updatedAt ?? new Date().toISOString()
+  };
+  walkForbiddenKeys(state);
+  return state;
+}
+
+export async function saveOrchState(state, { homeDir } = {}) {
+  const sanitized = createOrchState(state);
+  const { orchDir, statePath } = orchPaths(homeDir, sanitized.rootRunId);
+  await mkdir(orchDir, { recursive: true });
+  await writeAtomicJson(statePath, sanitized);
+  return { path: statePath, state: sanitized };
+}
+
+export async function loadOrchState(rootRunId, { homeDir } = {}) {
+  const { statePath } = orchPaths(homeDir, rootRunId);
+  if (!existsSync(statePath)) {
+    throw new OrchContractError(`Orchestration state not found: ${rootRunId}`, {
+      code: ORCH_ERROR_CODES.INVALID_NODE, details: { rootRunId }
+    });
+  }
+  try {
+    return createOrchState(JSON.parse(await readFile(statePath, "utf8")));
+  } catch {
+    throw new OrchContractError(`Corrupt orchestration state: ${rootRunId}`, {
+      code: ORCH_ERROR_CODES.INVALID_NODE, details: { rootRunId }
+    });
+  }
+}
+
+export function terminalizeOrchNodes(nodes, { recovered = false } = {}) {
+  return (nodes ?? []).map((node) => {
+    if (isTerminalDagState(node.state)) return createDagNode(node);
+    return createDagNode({
+      ...node,
+      state: recovered ? DAG_NODE_STATES.CANCELLED : DAG_NODE_STATES.COMPLETED,
+      error: recovered ? (node.error ?? { code: "interrupted" }) : node.error
+    });
+  });
+}
+
+const orchWriteLocks = new Map();
+
+function withOrchWriteLock(rootRunId, work) {
+  const previous = orchWriteLocks.get(rootRunId) ?? Promise.resolve();
+  const next = previous.then(work);
+  orchWriteLocks.set(rootRunId, next.catch(() => {}));
+  return next;
+}
+
+/** Serialized load → mutate → save for concurrent minion DAG updates. */
+export async function updateOrchState(rootRunId, mutator, { homeDir } = {}) {
+  return withOrchWriteLock(rootRunId, async () => {
+    const current = await loadOrchState(rootRunId, { homeDir });
+    return saveOrchState(await mutator(current), { homeDir });
+  });
+}
+
+/** Upsert one depth-1 node by taskId; append/replace MinionResult on completed. */
+export async function applyMinionDagUpdate(rootRunId, {
+  homeDir, taskId, parentTaskId, attempt = 0, state,
+  objectiveDigest = null, result = null, error = null
+} = {}) {
+  return updateOrchState(rootRunId, (current) => {
+    const rootTaskId = current.lineage?.taskId;
+    if (!rootTaskId || taskId === rootTaskId || parentTaskId !== rootTaskId) {
+      throw new OrchContractError("Minion taskId/parentTaskId must honor supervisor rootTaskId.", {
+        code: ORCH_ERROR_CODES.INVALID_NODE, details: { taskId, parentTaskId, rootTaskId }
+      });
+    }
+    const node = createDagNode({
+      taskId, parentTaskId, depth: 1, state, attempt,
+      objectiveDigest: objectiveDigest ?? null, error: error ?? null
+    });
+    const nodes = [...current.nodes];
+    const idx = nodes.findIndex((entry) => entry.taskId === taskId);
+    if (idx >= 0) {
+      nodes[idx] = createDagNode({
+        ...nodes[idx], ...node,
+        objectiveDigest: node.objectiveDigest ?? nodes[idx].objectiveDigest
+      });
+    } else {
+      nodes.push(node);
+    }
+    let results = current.results;
+    if (state === DAG_NODE_STATES.COMPLETED && result) {
+      const sealed = createMinionResult(result);
+      results = [...results.filter((entry) => entry.taskId !== taskId), sealed];
+    }
+    return { ...current, nodes, results, updatedAt: new Date().toISOString() };
+  }, { homeDir });
+}
+
+export async function finalizeOrchState(rootRunId, { homeDir, recovered = false } = {}) {
+  return withOrchWriteLock(rootRunId, async () => {
+    const { receiptPath } = orchPaths(homeDir, rootRunId);
+    if (existsSync(receiptPath)) {
+      return { path: receiptPath, receipt: await loadOrchReceipt(rootRunId, { homeDir }), idempotent: true };
+    }
+    const state = await loadOrchState(rootRunId, { homeDir });
+    const nodes = terminalizeOrchNodes(state.nodes, { recovered });
+    await saveOrchState({ ...state, nodes, updatedAt: new Date().toISOString() }, { homeDir });
+    try {
+      const saved = await saveOrchReceipt(buildOrchReceipt({
+        rootRunId: state.rootRunId, strategy: state.strategy, lineage: state.lineage,
+        nodes, results: state.results, cliVersion: state.cliVersion, recovered
+      }), { homeDir });
+      return { ...saved, idempotent: false };
+    } catch (error) {
+      if (error?.code === ORCH_ERROR_CODES.RECEIPT_EXISTS) {
+        return { path: receiptPath, receipt: await loadOrchReceipt(rootRunId, { homeDir }), idempotent: true };
+      }
+      throw error;
+    }
+  });
+}
+
+export async function reconcileOrchState(rootRunId, { homeDir } = {}) {
+  const { statePath, receiptPath } = orchPaths(homeDir, rootRunId);
+  if (existsSync(receiptPath)) {
+    return { rootRunId, path: receiptPath, receipt: await loadOrchReceipt(rootRunId, { homeDir }), idempotent: true };
+  }
+  if (!existsSync(statePath)) return null;
+  return finalizeOrchState(rootRunId, { homeDir, recovered: true });
+}

package/src/global/runtime/orchestration/orch-types.js

@@ -0,0 +1,173 @@
+import { createHash, randomBytes } from "node:crypto";
+export const RUN_STRATEGIES = Object.freeze({ DIRECT: "direct", ORCHESTRATED: "orchestrated" });
+export const DAG_NODE_STATES = Object.freeze({
+  PENDING: "pending", READY: "ready", RUNNING: "running", COMPACTING: "compacting",
+  COMPLETED: "completed", FAILED: "failed", CANCELLED: "cancelled", BLOCKED: "blocked"
+});
+export const DAG_TERMINAL_STATES = new Set([
+  DAG_NODE_STATES.COMPLETED, DAG_NODE_STATES.FAILED, DAG_NODE_STATES.CANCELLED
+]);
+export const ORCH_LIMITS = Object.freeze({
+  MAX_DEPTH: 1, DEFAULT_CONCURRENCY: 2, MAX_ATTEMPTS: 2, COMPACT_RATIO: 0.7, STOP_RATIO: 0.9
+});
+export const ORCH_ERROR_CODES = Object.freeze({
+  INVALID_STRATEGY: "invalid_strategy", INVALID_DEPTH: "invalid_depth",
+  INVALID_LINEAGE: "invalid_lineage", INVALID_HANDOFF: "invalid_handoff",
+  INVALID_NODE: "invalid_node", LIMIT_EXCEEDED: "limit_exceeded",
+  FORBIDDEN_FIELD: "forbidden_field", RECEIPT_EXISTS: "receipt_exists"
+});
+export class OrchContractError extends Error {
+  constructor(message, { code, details = null } = {}) {
+    super(message);
+    this.name = "OrchContractError";
+    this.code = code;
+    this.details = details;
+  }
+}
+export function createTaskId() {
+  return `task_${randomBytes(8).toString("hex")}`;
+}
+export function isTerminalDagState(state) {
+  return DAG_TERMINAL_STATES.has(state);
+}
+
+function assertDepth(depth) {
+  const d = Number(depth);
+  if (!Number.isInteger(d) || d < 0) {
+    throw new OrchContractError(`Invalid depth "${depth}".`, {
+      code: ORCH_ERROR_CODES.INVALID_DEPTH, details: { depth }
+    });
+  }
+  if (d > ORCH_LIMITS.MAX_DEPTH) {
+    throw new OrchContractError(`Orchestration depth ${d} exceeds max ${ORCH_LIMITS.MAX_DEPTH}.`, {
+      code: ORCH_ERROR_CODES.INVALID_DEPTH, details: { depth: d }
+    });
+  }
+  return d;
+}
+
+function assertParentForDepth(depth, parentId, { rootMsg, minionMsg, code }) {
+  if (depth === 0 && parentId != null) {
+    throw new OrchContractError(rootMsg, { code });
+  }
+  if (depth > 0 && !parentId) {
+    throw new OrchContractError(minionMsg, { code });
+  }
+}
+
+export function normalizeRunStrategy(value = RUN_STRATEGIES.DIRECT) {
+  const strategy = String(value ?? RUN_STRATEGIES.DIRECT).trim().toLowerCase();
+  if (!Object.values(RUN_STRATEGIES).includes(strategy)) {
+    throw new OrchContractError(`Invalid run strategy "${value}". Use direct or orchestrated.`, {
+      code: ORCH_ERROR_CODES.INVALID_STRATEGY, details: { value }
+    });
+  }
+  return strategy;
+}
+
+/** Lineage: max depth 1 (root=0, minion=1). */
+export function createOrchLineage({ rootRunId, parentRunId = null, taskId = null, depth = 0 } = {}) {
+  if (typeof rootRunId !== "string" || !rootRunId) {
+    throw new OrchContractError("rootRunId is required.", { code: ORCH_ERROR_CODES.INVALID_LINEAGE });
+  }
+  const d = assertDepth(depth);
+  assertParentForDepth(d, parentRunId, {
+    rootMsg: "Root nodes must not set parentRunId.",
+    minionMsg: "Minion nodes require parentRunId.",
+    code: ORCH_ERROR_CODES.INVALID_LINEAGE
+  });
+  return { rootRunId, parentRunId: parentRunId ?? null, taskId: taskId ?? createTaskId(), depth: d };
+}
+
+export function createBudgetUsage({
+  contextTokens = 0, contextLimit = 0,
+  compactRatio = ORCH_LIMITS.COMPACT_RATIO, stopRatio = ORCH_LIMITS.STOP_RATIO
+} = {}) {
+  const tokens = Math.max(0, Number(contextTokens) || 0);
+  const limit = Math.max(0, Number(contextLimit) || 0);
+  const ratio = limit > 0 ? tokens / limit : 0;
+  return {
+    contextTokens: tokens, contextLimit: limit, ratio,
+    shouldCompact: limit > 0 && ratio >= compactRatio && ratio < stopRatio,
+    shouldStop: limit > 0 && ratio >= stopRatio
+  };
+}
+
+export function createDagNode({
+  taskId = null, runId = null, parentTaskId = null, depth = 0,
+  state = DAG_NODE_STATES.PENDING, dependsOn = [], attempt = 0,
+  objectiveDigest = null, budget = null, resultDigest = null, error = null
+} = {}) {
+  if (!Object.values(DAG_NODE_STATES).includes(state)) {
+    throw new OrchContractError(`Invalid DAG node state "${state}".`, {
+      code: ORCH_ERROR_CODES.INVALID_NODE, details: { state }
+    });
+  }
+  const d = assertDepth(depth);
+  assertParentForDepth(d, parentTaskId, {
+    rootMsg: "Root nodes must not set parentTaskId.",
+    minionMsg: "Minion nodes require parentTaskId.",
+    code: ORCH_ERROR_CODES.INVALID_NODE
+  });
+  const attempts = Number(attempt) || 0;
+  if (attempts < 0 || attempts > ORCH_LIMITS.MAX_ATTEMPTS) {
+    throw new OrchContractError(`Attempt ${attempts} outside 0..${ORCH_LIMITS.MAX_ATTEMPTS}.`, {
+      code: ORCH_ERROR_CODES.LIMIT_EXCEEDED, details: { attempt: attempts }
+    });
+  }
+  const deps = [...new Set((dependsOn ?? []).map((id) => {
+    if (typeof id !== "string" || !id) {
+      throw new OrchContractError("Dependency taskId is required.", { code: ORCH_ERROR_CODES.INVALID_NODE });
+    }
+    return id;
+  }))];
+  return {
+    taskId: taskId ?? createTaskId(), runId: runId ?? null, parentTaskId: parentTaskId ?? null,
+    depth: d, state, dependsOn: deps, attempt: attempts,
+    objectiveDigest, budget: budget ?? null, resultDigest, error: error ?? null
+  };
+}
+
+export function createMinionBrief({
+  objective, constraints = [], admittedPaths = [], exitCriteria = [],
+  parentTaskId = null, taskId = null
+} = {}) {
+  if (typeof objective !== "string" || !objective.trim()) {
+    throw new OrchContractError("Minion brief requires a non-empty objective.", {
+      code: ORCH_ERROR_CODES.INVALID_HANDOFF
+    });
+  }
+  return {
+    taskId: taskId ?? createTaskId(), parentTaskId: parentTaskId ?? null,
+    objective: objective.trim(), constraints: (constraints ?? []).map(String),
+    admittedPaths: (admittedPaths ?? []).map(String), exitCriteria: (exitCriteria ?? []).map(String)
+  };
+}
+
+export function createMinionResult({
+  taskId = null, summary, decisions = [], files = [], risks = [],
+  evidence = [], usage = null, compact = false
+} = {}) {
+  if (typeof taskId !== "string" || !taskId) {
+    throw new OrchContractError("Minion result requires taskId.", { code: ORCH_ERROR_CODES.INVALID_HANDOFF });
+  }
+  if (typeof summary !== "string" || !summary.trim()) {
+    throw new OrchContractError("Minion result requires a non-empty summary.", {
+      code: ORCH_ERROR_CODES.INVALID_HANDOFF
+    });
+  }
+  return {
+    taskId, summary: summary.trim(),
+    decisions: (decisions ?? []).map(String), files: (files ?? []).map(String),
+    risks: (risks ?? []).map(String), evidence: (evidence ?? []).map(String),
+    usage: {
+      inputTokens: usage?.inputTokens ?? null, outputTokens: usage?.outputTokens ?? null,
+      totalTokens: usage?.totalTokens ?? null, cost: usage?.cost ?? null
+    },
+    compact: Boolean(compact)
+  };
+}
+
+export function digestAllowlisted(value) {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex").slice(0, 16);
+}

package/src/global/runtime/orchestration/orch-validate.js

@@ -0,0 +1,63 @@
+import {
+  ORCH_ERROR_CODES, OrchContractError, createBudgetUsage, createDagNode,
+  createMinionResult, createOrchLineage, normalizeRunStrategy
+} from "./orch-types.js";
+export const FORBIDDEN_KEYS = new Set([
+  "prompt", "diff", "transcript", "raw", "rawOutput", "stdout", "stderr", "output",
+  "message", "messages", "content", "secret", "secrets", "token", "apiKey",
+  "conversation", "history", "toolArgs", "arguments", "objective"
+]);
+export function walkForbiddenKeys(value, path = "") {
+  if (!value || typeof value !== "object") return;
+  if (Array.isArray(value)) {
+    value.forEach((item, i) => walkForbiddenKeys(item, `${path}[${i}]`));
+    return;
+  }
+  for (const [key, child] of Object.entries(value)) {
+    if (FORBIDDEN_KEYS.has(key)) {
+      throw new OrchContractError(`Forbidden field "${path}${key}" in orchestration receipt.`, {
+        code: ORCH_ERROR_CODES.FORBIDDEN_FIELD, details: { key, path }
+      });
+    }
+    walkForbiddenKeys(child, `${path}${key}.`);
+  }
+}
+export function assertOrchReceiptSecretFree(receipt) {
+  if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)) {
+    throw new OrchContractError("Invalid orchestration receipt: expected object.", {
+      code: ORCH_ERROR_CODES.FORBIDDEN_FIELD
+    });
+  }
+  walkForbiddenKeys(receipt);
+  if (receipt.version !== 1) {
+    throw new OrchContractError("Orchestration receipt version must be 1.", {
+      code: ORCH_ERROR_CODES.FORBIDDEN_FIELD
+    });
+  }
+  normalizeRunStrategy(receipt.strategy);
+  if (typeof receipt.rootRunId !== "string" || !receipt.rootRunId) {
+    throw new OrchContractError("rootRunId is required on receipt.", {
+      code: ORCH_ERROR_CODES.INVALID_LINEAGE
+    });
+  }
+  createOrchLineage(receipt.lineage);
+  if (receipt.lineage.rootRunId !== receipt.rootRunId) {
+    throw new OrchContractError("lineage.rootRunId must match receipt.rootRunId.", {
+      code: ORCH_ERROR_CODES.INVALID_LINEAGE
+    });
+  }
+  if (!Array.isArray(receipt.nodes) || !Array.isArray(receipt.results)) {
+    throw new OrchContractError("Receipt requires nodes[] and results[].", {
+      code: ORCH_ERROR_CODES.INVALID_NODE
+    });
+  }
+  for (const node of receipt.nodes) {
+    createDagNode(node);
+    if (node.budget) createBudgetUsage(node.budget);
+  }
+  for (const result of receipt.results) createMinionResult(result);
+  if (typeof receipt.createdAt !== "string" || !receipt.createdAt) {
+    throw new OrchContractError("createdAt is required.", { code: ORCH_ERROR_CODES.FORBIDDEN_FIELD });
+  }
+  return receipt;
+}

package/src/global/runtime/review/index.js

@@ -0,0 +1,37 @@
+export {
+  REVIEW_SCOPE_MODES, REVIEW_SEVERITIES, REVIEW_STATES, REVIEW_EXIT_CODES, REVIEW_AGENTS,
+  REVIEW_LIMITS, REVIEW_SNAPSHOT_ERROR_CODES, ReviewSnapshotError, resolveReviewScopeMode,
+  createFindingId, canonicalFingerprint, isReviewPrivatePath, isBinaryContent,
+  assertReviewPathSafe, assertWithinReviewLimits, requirePrivateConsent
+} from "./review-types.js";
+export {
+  resolveReviewSnapshot, fingerprintReviewSnapshot, detectReviewSnapshotDrift,
+  readReviewRegularFile
+} from "./review-git.js";
+export {
+  REVIEW_PATCH_ERROR_CODES, filterDiffToAdmittedPaths, buildScopedReviewPatch
+} from "./review-patch.js";
+export {
+  REVIEW_VALIDATION_ERROR_CODES, ReviewValidationError,
+  validateReviewOutput, assertReceiptSecretFree
+} from "./review-validate.js";
+export {
+  assertSafeReviewId, createReviewId, reviewPaths,
+  buildReviewReceipt, saveReviewReceipt, loadReviewReceipt, listReviewReceipts
+} from "./review-receipts.js";
+export {
+  REVIEW_EXEC_ERROR_CODES, REVIEW_EXEC_LIMITS, ReviewExecError,
+  runBoundedProcess, assertBoundedProcessOk
+} from "./review-exec.js";
+export {
+  REVIEW_CODEX_ERROR_CODES, buildCodexReviewArgs, buildCodexCliEnv,
+  buildCodexReviewPrompt, parseCodexReviewJsonl, runCodexReview
+} from "./review-codex.js";
+export {
+  REVIEW_PI_ERROR_CODES, buildPiReviewArgs, buildPiCliEnv,
+  buildPiReviewPrompt, buildPiReviewStdin, parsePiReviewJsonl, runPiReview
+} from "./review-pi.js";
+export {
+  REVIEW_RUNNER_ERROR_CODES, ReviewRunnerError,
+  resolveReviewAgent, resolveReviewExitCode, runReview
+} from "./review-runner.js";

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 };
+  }
+}