@mrclrchtr/supi-review 2.7.0 → 3.0.0

package/README.md

@@ -1,14 +1,6 @@
-<div align="center">
-  <a href="https://github.com/mrclrchtr/supi/tree/main/packages/supi-review">
-    <picture>
-      <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-review/assets/logo.png" alt="SuPi" width="50%">
-    </picture>
-  </a>
-</div>
-
 # @mrclrchtr/supi-review
 
-Adds human-driven and agent-driven Session-Aware Review workflows to the [pi coding agent](https://github.com/earendil-works/pi).
+Runs caller-defined, read-only code review tasks in managed Pi child sessions.
 
 ## Install
 
@@ -16,177 +8,97 @@ Adds human-driven and agent-driven Session-Aware Review workflows to the [pi cod
 pi install npm:@mrclrchtr/supi-review
 ```
 
-This is a **beta** package. Install individually.
-
-For local development:
-
-```bash
-pi install ./packages/supi-review
+This is a beta package with intentionally unstable interfaces.
+
+## Surfaces
+
+- `/supi-review` — interactive Direct or Planner-assisted review
+- `supi_review_prepare` — optional one-shot preparation with `planning: "none" | "suggest"`
+- `supi_review_run` — universal Direct or Prepared Review execution
+
+Preparation is optional. Skills and agents that already know how to review should use Direct Review.
+
+## Direct Review
+
+```json
+{
+  "mode": "direct",
+  "target": {
+    "kind": "comparison",
+    "baseCommit": "<full commit object id>"
+  },
+  "review": {
+    "sharedContext": "The change implements issue #123.",
+    "tasks": [
+      {
+        "id": "standards",
+        "instructions": "Review against the repository standards."
+      },
+      {
+        "id": "spec",
+        "instructions": "Review against issue #123 and cite unmet requirements."
+      }
+    ]
+  }
+}
 ```
 
-## What you get
-
-After install, pi gets one human-driven command and two agent-facing tools:
-
-- `/supi-review` — launch a guided review flow over a concrete git snapshot
-- `supi_review_prepare` — synthesize a versioned brief and return a session-scoped `planId`
-- `supi_review_run` — accept the main agent's structured brief critique, freshness-check the plan, and run focused reviewers concurrently
-
-The run tool is initially inactive and is dynamically enabled after `supi_review_prepare` returns a plan. This keeps the initial agent-facing prompt surface small.
-
-The reviewer runs in managed child agent sessions:
-
-- a **brief synthesizer** creates a structured review brief from the active session branch
-- a **read-only reviewer** inspects the selected snapshot (without receiving bulk inline diffs) and submits structured review items
-
-![Review target selection](https://raw.githubusercontent.com/mrclrchtr/supi/main/screenshots/supi-review-1.png)
-
-![Review brief preview](https://raw.githubusercontent.com/mrclrchtr/supi/main/screenshots/supi-review-2.png)
-
-![Review result](https://raw.githubusercontent.com/mrclrchtr/supi/main/screenshots/supi-review-3.png)
-
-![Review progress](https://raw.githubusercontent.com/mrclrchtr/supi/main/screenshots/supi-review-4.png)
-
-## Review flow
-
-`/supi-review` walks you through:
-
-1. choose a review target
-2. choose the reviewer model
-3. optionally add a short note
-4. resolve the snapshot
-5. synthesize a review brief from the current session history
-6. preview the synthesized brief + compact prompt preview, then press `v` for an in-app inspector (Overview first, Raw Prompt via `tab`, export via `e`)
-7. the reviewer fetches per-file diffs on demand via snapshot-aware tools; live progress widget shows activity
-8. normalize the submitted review items into a host-derived verdict + structured result
-9. if review items exist, hand off to the main agent so it can ask what to do next with fixed options (`Fix all`, `Fix selected`, `Verify findings`, `Skip`)
+All tasks use one reviewer model and run concurrently. A run accepts one to four tasks. Direct and Prepared adapters use the same canonical packet compiler; every task result includes the SHA-256 of the exact packet bytes.
 
-## Agent-driven review flow
+## Prepared Review
 
-The agent-facing path deliberately separates preparation from execution:
-
-1. `supi_review_prepare` resolves the target, serializes the active session context, and synthesizes a generated brief.
-2. The main agent compares that brief with the user request, session evidence, and snapshot.
-3. The main agent calls `supi_review_run` with:
-   - the prepared `planId`
-   - an `accept` or `revise` critique
-   - evidence-backed critique findings
-   - at least one evidence-backed finding and a full `revisedBrief` when revision is required
-   - one to four independent reviewer assignments
-4. The host atomically consumes the plan, checks snapshot freshness, and runs reviewer child sessions concurrently.
-5. The tool returns each normalized review result plus a retained brief evaluation artifact.
-
-The evaluation artifact keeps the generated brief, main-agent critique, effective brief, synthesis prompt version, model id, and snapshot fingerprint separate. This makes brief-synthesis prompt regressions inspectable instead of hiding main-agent repairs. The full artifact is stored in tool-result `details`; a summary is also recorded as a `supi-review/brief-critique` SuPi Debug event when debug capture is enabled.
-
-Prepared plans are session-scoped. File or git changes before or during review invalidate the run, so `supi_review_run` should not share a tool batch with mutating tools.
-
-## Review targets
-
-Current targets:
-
-- working tree
-- branch diff vs a selected local base branch (`merge-base..HEAD`, excluding dirty worktree changes)
-- one commit (recent-commit picker in the command; hexadecimal object id in the agent tool)
-
-Agent-provided branch targets must name an existing local branch. Commit targets must be unique 7–64 character hexadecimal commit-object ids: object-only disambiguation rejects ambiguous prefixes, non-commit objects, and hexadecimal branch/tag fallback. Git revision arguments are option-hardened before execution.
-
-## Session-aware brief synthesis
-
-The generated review prompt is **not** just a static diff wrapper.
-
-Before the actual review starts, the package:
-
-- resolves the **active session branch into the current LLM-visible context**
-- **serializes** that resolved context into a compaction-style transcript
-- feeds the serialized transcript (plus snapshot + optional note) to a dedicated brief synthesizer
-- synthesizes a structured brief with:
-  - summary
-  - intended outcome
-  - constraints to preserve
-  - focus areas
-  - risky files
-  - unresolved questions
-  - `reviewInstructionBlockIds` selected from a fixed host-owned catalog
-
-The synthesizer also receives a bounded diff excerpt from the snapshot so it can reason about actual code changes, not just filenames.
-
-That synthesized brief is then combined with the git snapshot into a compact reviewer prompt. The host owns a fixed catalog of review instruction blocks, and the brief selects zero or more block IDs from that catalog when extra review guidance is warranted. The resulting prompt contains the brief, file manifest, per-file overview, and any brief-selected **mandatory review instructions**, but no large inline diffs. Instead, the reviewer session gets snapshot-aware tools (`read_snapshot_diff`, `read_snapshot_file`) to fetch exact per-file diffs and before/after file contents on demand.
-
-The session-transcript approach mirrors how Pi summarizes context for compaction: the entire resolved conversation is rendered in a readable label format and sent to the model as a whole, rather than relying on heuristic excerpt ranking.
+```json
+{
+  "target": { "kind": "working-tree" },
+  "planning": "suggest"
+}
+```
 
-## Review-plan inspector
+Preparation returns a session-scoped, one-shot `planId` and optional Planner Draft. Execute it with an explicit decision:
 
-Before the reviewer runs, the plan preview stays inside Pi:
+```json
+{
+  "mode": "prepared",
+  "planId": "review-plan-...",
+  "decision": { "kind": "accept-draft" }
+}
+```
 
-- `v` opens an in-app inspector instead of spawning an external pager
-- the inspector opens in **Overview** mode first
-- `tab` toggles between **Overview** and **Raw Prompt**
-- `↑↓` or `j` / `k` scroll long content in the inspector
-- `q` or `esc` returns to the summary preview without canceling the review
-- `e` exports the raw prompt to a temp file as a debugging fallback
+Use `use-review` with a complete replacement review when the draft needs editing.
 
-The Overview mode uses the same structured packet data that feeds the reviewer prompt: mandatory review instructions, file overview rows, and truncated snapshot notes all come from shared packet derivation rather than re-parsing the raw prompt text.
+## Targets
 
-## Model selection
+- `working-tree` — net `HEAD` to current filesystem, plus non-ignored untracked files, computed through a temporary HEAD-seeded index rather than the caller's real index
+- `comparison` — merge base of a full `baseCommit` and captured `HEAD` to captured `HEAD`
+- `commit` — first parent (or empty tree) to a full commit object id
 
-Every `/supi-review` command run asks you to choose the reviewer model.
+Agent-facing commit values must be full hexadecimal object ids. The repository must remain stable from preparation or Direct invocation until reviewers finish; drift is not detected.
 
-- the picker only shows **scoped models** from Pi's `enabledModels` configuration
-- the current session model is preselected only when it is inside that scoped set
-- the selected model is used for both brief synthesis and the final review
-- no review model is persisted in settings
+## Reviewer protocol
 
-Agent-driven tool runs use the current session model for preparation and all focused reviewers. The selected model is retained in the prepared plan so a model change between tool calls cannot silently alter the run.
+Callers own task methodology. The Review Engine owns:
 
-## Result shape
+- target resolution
+- target-aware read-only tools
+- minimal finding-quality instructions
+- structured submission
+- child lifecycle handling
+- per-task verdict derivation
 
-A successful review includes:
+Reviewers receive no shell, arbitrary extension tools, Pi context files, skills, or prompt templates. Discovered `SYSTEM.md` and `APPEND_SYSTEM.md` files are explicitly suppressed; only the package-owned reviewer protocol is appended to Pi's base system prompt. In-memory child settings disable compaction and retries so provider limits apply to the original packet. Inspection-tool and parent-visible outputs are paged/bounded; canonical packet bytes are never truncated.
 
-- a host-derived binary verdict:
-  - `PATCH IS CORRECT`
-  - `PATCH HAS ISSUES`
-- overall explanation
-- overall confidence score
-- normalized action/category summary counts
-- structured review items with:
-  - title
-  - body
-  - category
-  - impact
-  - effort
-  - recommended action
-  - confidence score
-  - suggested fix
-  - verification hint
-  - optional code location
-- the synthesized brief that drove the review
+## Result
 
-The renderer also handles failed, canceled, and timed-out reviews.
+Each successful task returns a summary and ordered findings. Findings contain:
 
-The reviewer model does **not** decide the final binary verdict directly. It submits review items plus overall explanation/confidence, then the host derives the verdict from the normalized items (`must-fix` items => `PATCH HAS ISSUES`).
+- `blocksAcceptance`
+- `impact`: `low | medium | high`
+- `effort`: `small | medium | large`
+- `confidence`: `0..1`
+- optional target-relative location
 
-When a successful review contains review items, `supi-review` also injects an agent-visible hidden follow-up message that asks the main agent to decide the next step with the user. If `ask_user` is available, the main agent is instructed to use it and offer:
-
-- Fix all
-- Fix selected
-- Verify findings
-- Skip
+The Review Engine derives `pass` or `issues` per task and never aggregates or reranks tasks. Batch details also record `mode`, caller/planner provenance, and each task's packet hash.
 
-## Source
+## Models
 
-- `src/review.ts` — command orchestration and interactive flow
-- `src/model.ts` — explicit model selection helpers
-- `src/git.ts` — git snapshot resolution
-- `src/history/collect.ts` — compaction-style session-context serialization
-- `src/history/synthesize.ts` — brief synthesis orchestration
-- `src/review-result.ts` — review-item normalization, verdict derivation, and summary counts
-- `src/target/review-instruction-blocks.ts` — fixed catalog of host-owned review instruction blocks
-- `src/target/packet.ts` — final reviewer packet builder + shared preview-data derivation for the inspector
-- `src/session/review-plan-store.ts` — session-scoped, one-shot prepared review plans
-- `src/tool/agent-review-tools.ts` — prepare/run tool registration, dynamic activation, progress, and debug artifact recording
-- `src/tool/agent-review-workflow.ts` — preparation, critique validation, freshness checks, and concurrent reviewer fan-out
-- `src/tool/brief-runner.ts` — brief synthesis child session
-- `src/tool/review-runner.ts` — read-only reviewer child session with snapshot-aware tools
-- `src/tool/snapshot-tools.ts` — per-file diff and before/after content tools scoped to the selected snapshot
-- `src/ui/review-plan-inspector.ts` — in-app summary/inspector preview with Overview + Raw Prompt modes and export fallback
-- `src/ui/renderer.ts` — structured result rendering
+`/supi-review` asks for the reviewer model. Agent-triggered runs use `review.agentModel`. Optional planning uses the separately configured `review.plannerModel` at low thinking effort. Both settings default to the current session model for availability; configure `review.plannerModel` to a lightweight model when using Planner suggestions.

package/node_modules/@mrclrchtr/supi-core/README.md

@@ -43,7 +43,7 @@ Config file locations:
 - `registerSettingsCommand(pi)` — register `/supi-settings` (used by `@mrclrchtr/supi-settings`)
 - `openSettingsOverlay(pi, ctx)` — open the shared settings UI directly
 - `createInputSubmenu()` — helper for simple text-entry submenus
-- `createModelPickerSubmenu()` — helper for scoped model selection submenus
+- `createModelPickerSubmenu()` — helper for scoped model selection submenus, with optional host-owned choices and `disabled` control
 
 The built-in settings UI supports:
 

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "2.7.0",
+  "version": "3.0.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -55,6 +55,7 @@
     "./config": "./src/config.ts",
     "./context": "./src/context.ts",
     "./debug": "./src/debug-registry.ts",
+    "./evidence-badge": "./src/evidence-badge.ts",
     "./footer-registry": "./src/footer-registry.ts",
     "./llm": "./src/llm.ts",
     "./model-selection": "./src/model-selection.ts",

package/node_modules/@mrclrchtr/supi-core/src/api.ts

@@ -15,6 +15,8 @@ export * from "./context.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./debug-registry.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./evidence-badge.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./footer-registry.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./llm.ts";

package/node_modules/@mrclrchtr/supi-core/src/evidence-badge.ts

@@ -0,0 +1,40 @@
+/**
+ * TUI-facing evidence badge string formatter.
+ *
+ * Pure string formatting — no pi-tui dependency. Consumes evidence
+ * completeness metadata and produces compact human-readable badges.
+ */
+
+/** Metadata describing how many evidence atoms were shown vs exist. */
+export interface EvidenceBadgeInput {
+  shownCount: number;
+  totalCount: number | null;
+  omittedCount: number | null;
+  partialReason: string | null;
+  /** Human-readable label for the badge, e.g. "references", "symbols". */
+  label: string;
+}
+
+/**
+ * Format a compact evidence completeness badge.
+ *
+ * | Input                                                | Output                                |
+ * |------------------------------------------------------|---------------------------------------|
+ * | shown=12, total=12, omitted=0, label="references"   | `12 references`                       |
+ * | shown=8,  total=20, omitted=12, label="symbols"     | `8 of 20 symbols (12 omitted)`        |
+ * | shown=5,  total=null, reason="timeout", label="matches" | `5 matches — timeout`              |
+ */
+export function formatEvidenceBadge(input: EvidenceBadgeInput): string {
+  const { shownCount, totalCount, omittedCount, partialReason, label } = input;
+
+  if (totalCount === null) {
+    const reasonSuffix = partialReason ? ` — ${partialReason}` : "";
+    return `${shownCount} ${label}${reasonSuffix}`;
+  }
+
+  if (omittedCount !== null && omittedCount > 0) {
+    return `${shownCount} of ${totalCount} ${label} (${omittedCount} omitted)`;
+  }
+
+  return `${shownCount} ${label}`;
+}

package/node_modules/@mrclrchtr/supi-core/src/settings/scoped-settings-list.ts

@@ -324,6 +324,7 @@ export class ScopedSettingsList {
             this.tui.requestRender();
           },
           this.ctx,
+          row.field.field,
         ),
         onDone: () => {
           this.submenu = null;

package/node_modules/@mrclrchtr/supi-core/src/settings/settings-schema.ts

@@ -91,9 +91,23 @@ export interface StringListField extends BaseField {
   kind: "stringList";
 }
 
+/** One non-model choice shown before the scoped models in a model picker. */
+export interface ModelPickerStaticOption {
+  /** Persisted value for the choice. */
+  value: string;
+  /** Human-readable picker label. */
+  label: string;
+  /** Optional explanation shown alongside the label. */
+  description?: string;
+}
+
 /** Model picker backed by the scoped model set. */
 export interface ModelPickerField extends BaseField {
   kind: "modelPicker";
+  /** Additional host-owned choices shown before scoped models. */
+  staticOptions?: ModelPickerStaticOption[];
+  /** Whether to include the built-in `disabled` choice. Defaults to true. */
+  includeDisabled?: boolean;
 }
 
 /**

package/node_modules/@mrclrchtr/supi-core/src/settings/settings-submenus.ts

@@ -14,6 +14,7 @@ import {
   Text,
 } from "@earendil-works/pi-tui";
 import { getSelectableModels } from "../model-selection.ts";
+import type { ModelPickerField } from "./settings-schema.ts";
 
 /**
  * Creates a pi-tui Input-backed submenu component with enter-to-confirm
@@ -57,25 +58,26 @@ export function createInputSubmenu(
 }
 
 /**
- * Creates a model picker submenu for settings with "disabled" as the first option.
+ * Creates a model picker submenu backed by the scoped model set.
+ *
+ * The built-in `disabled` choice remains enabled by default. Callers can add
+ * host-owned static choices or omit `disabled` through the field options.
  */
 export function createModelPickerSubmenu(
   currentValue: string,
   done: (selectedValue?: string) => void,
   ctx?: ExtensionContext,
+  options: Pick<ModelPickerField, "includeDisabled" | "staticOptions"> = {},
 ): {
   render: (width: number) => string[];
   invalidate: () => void;
   handleInput: (data: string) => boolean;
 } {
-  const items = buildModelItems(ctx);
-  const initialIndex =
-    currentValue === "disabled"
-      ? 0
-      : Math.max(
-          0,
-          items.findIndex((item) => item.value === currentValue),
-        );
+  const items = buildModelItems(ctx, options);
+  const initialIndex = Math.max(
+    0,
+    items.findIndex((item) => item.value === currentValue),
+  );
 
   const container = new Container();
   container.addChild(new Text("  Select model", 1, 0));
@@ -105,20 +107,35 @@ export function createModelPickerSubmenu(
   };
 }
 
-/** Build selectable model items with "disabled" as the first option. */
-function buildModelItems(ctx?: ExtensionContext): SelectItem[] {
-  const items: SelectItem[] = [
-    { value: "disabled", label: "disabled", description: "No model selected" },
-  ];
+/** Build static choices followed by the selectable scoped models. */
+function buildModelItems(
+  ctx: ExtensionContext | undefined,
+  options: Pick<ModelPickerField, "includeDisabled" | "staticOptions">,
+): SelectItem[] {
+  const items: SelectItem[] = [];
+  const seen = new Set<string>();
+  for (const option of options.staticOptions ?? []) {
+    if (seen.has(option.value)) continue;
+    items.push({ ...option });
+    seen.add(option.value);
+  }
+
+  if (options.includeDisabled !== false && !seen.has("disabled")) {
+    items.push({ value: "disabled", label: "disabled", description: "No model selected" });
+    seen.add("disabled");
+  }
+
   if (!ctx) return items;
   const models = getSelectableModels(ctx);
   for (const model of models) {
+    if (seen.has(model.canonicalId)) continue;
     const suffix = model.isCurrent ? "  [current]" : "";
     items.push({
       value: model.canonicalId,
       label: `${model.canonicalId}${suffix}`,
       description: model.label !== model.canonicalId ? model.label : undefined,
     });
+    seen.add(model.canonicalId);
   }
   return items;
 }

package/node_modules/@mrclrchtr/supi-core/src/settings.ts

@@ -20,6 +20,7 @@ export type {
   DeclarativeSettingsOptions,
   EnumField,
   ModelPickerField,
+  ModelPickerStaticOption,
   NumberField,
   ScopedFieldValue,
   SettingsField,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mrclrchtr/supi-review",
-  "version": "2.7.0",
-  "description": "SuPi Review extension — session-aware review command and agent tools",
+  "version": "3.0.0",
+  "description": "SuPi Review extension — caller-defined read-only review tasks for users and agents",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -31,7 +31,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "2.7.0"
+    "@mrclrchtr/supi-core": "3.0.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/config.ts

@@ -0,0 +1,64 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadSupiConfig } from "@mrclrchtr/supi-core/config";
+import { registerDeclarativeSettings } from "@mrclrchtr/supi-core/settings";
+import { CURRENT_SESSION_REVIEW_MODEL } from "./model.ts";
+
+/** Persisted model choices for agent-triggered reviews and optional planning. */
+export interface ReviewConfig extends Record<string, unknown> {
+  /** Canonical reviewer model id, or `current` for the active session model. */
+  agentModel: string;
+  /** Canonical Planner model id, or `current` for the active session model. */
+  plannerModel: string;
+}
+
+/** Shared SuPi configuration section owned by this package. */
+export const REVIEW_CONFIG_SECTION = "review";
+/** Availability-safe defaults; users can configure a separate lightweight Planner model. */
+export const REVIEW_DEFAULTS: ReviewConfig = {
+  agentModel: CURRENT_SESSION_REVIEW_MODEL,
+  plannerModel: CURRENT_SESSION_REVIEW_MODEL,
+};
+
+/** Load merged and normalized review configuration. */
+export function loadReviewConfig(cwd: string, homeDir?: string): ReviewConfig {
+  const raw = loadSupiConfig(REVIEW_CONFIG_SECTION, cwd, REVIEW_DEFAULTS, { homeDir });
+  const readModel = (value: unknown, fallback: string) =>
+    typeof value === "string" && value.trim() ? value.trim() : fallback;
+  return {
+    agentModel: readModel(raw.agentModel, REVIEW_DEFAULTS.agentModel),
+    plannerModel: readModel(raw.plannerModel, REVIEW_DEFAULTS.plannerModel),
+  };
+}
+
+/** Contribute reviewer and Planner model pickers to `/supi-settings`. */
+export function registerReviewSettings(pi: ExtensionAPI, homeDir?: string): void {
+  const currentOption = {
+    value: CURRENT_SESSION_REVIEW_MODEL,
+    label: "current session model",
+  };
+  registerDeclarativeSettings(pi, {
+    id: REVIEW_CONFIG_SECTION,
+    label: "Review",
+    section: REVIEW_CONFIG_SECTION,
+    defaults: REVIEW_DEFAULTS,
+    fields: [
+      {
+        kind: "modelPicker",
+        key: "agentModel",
+        label: "Reviewer model",
+        description: "Model shared by all tasks in an agent-triggered review run.",
+        includeDisabled: false,
+        staticOptions: [currentOption],
+      },
+      {
+        kind: "modelPicker",
+        key: "plannerModel",
+        label: "Planner model",
+        description: "Lightweight model used only when planning is set to suggest.",
+        includeDisabled: false,
+        staticOptions: [currentOption],
+      },
+    ],
+    ...(homeDir ? { homeDir } : {}),
+  });
+}

package/src/git-command.ts

@@ -0,0 +1,78 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const GIT_TIMEOUT_MS = 30_000;
+
+function gitOptions(cwd: string, indexFile?: string) {
+  const env = { ...process.env };
+  for (const key of Object.keys(env)) if (key.startsWith("GIT_")) delete env[key];
+  if (indexFile) env.GIT_INDEX_FILE = indexFile;
+  return { cwd, env, timeout: GIT_TIMEOUT_MS, maxBuffer: 50 * 1024 * 1024 };
+}
+
+/** Run Git with bounded resources and a sanitized environment. */
+export async function runGit(cwd: string, args: string[], indexFile?: string): Promise<string> {
+  return (await execFileAsync("git", args, gitOptions(cwd, indexFile))).stdout;
+}
+
+export function expectedGitExitOutput(error: unknown, allowedCodes: number[]): string | undefined {
+  if (!error || typeof error !== "object") return undefined;
+  const failure = error as {
+    code?: unknown;
+    killed?: unknown;
+    signal?: unknown;
+    stdout?: unknown;
+  };
+  if (
+    typeof failure.code !== "number" ||
+    !allowedCodes.includes(failure.code) ||
+    failure.killed === true ||
+    failure.signal
+  ) {
+    return undefined;
+  }
+  if (typeof failure.stdout === "string") return failure.stdout;
+  if (Buffer.isBuffer(failure.stdout)) return failure.stdout.toString("utf8");
+  return "";
+}
+
+/** Allow only documented non-zero Git outcomes while preserving operational failures. */
+export async function runGitAllowExit(
+  cwd: string,
+  args: string[],
+  allowedCodes: number[],
+  indexFile?: string,
+): Promise<string> {
+  try {
+    return await runGit(cwd, args, indexFile);
+  } catch (error) {
+    const stdout = expectedGitExitOutput(error, allowedCodes);
+    if (stdout !== undefined) return stdout;
+    throw error;
+  }
+}
+
+/** Execute an operation against a temporary index seeded only from HEAD. */
+export async function withHeadIndex<T>(
+  cwd: string,
+  head: string,
+  operation: (indexFile: string) => Promise<T>,
+): Promise<T> {
+  const directory = await mkdtemp(join(tmpdir(), "supi-review-index-"));
+  const indexFile = join(directory, "index");
+  try {
+    await runGit(cwd, ["read-tree", head], indexFile);
+    return await operation(indexFile);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+
+/** Disable Git pathspec magic for a path-taking command. */
+export function literalPathspec(args: string[]): string[] {
+  return ["--literal-pathspecs", ...args];
+}