pi-workflow-engine 0.10.3 → 0.11.0

package/.pi/extensions/pi-workflow-engine/src/agent-skills.ts

@@ -1,6 +1,9 @@
 import { DefaultResourceLoader, getAgentDir, type ResourceDiagnostic, type Skill } from "@earendil-works/pi-coding-agent";
+import { dirname, resolve } from "node:path";
+import { logicalWorkspacePath, type ReplayWorkspaceRoots } from "./replay-path-identity.ts";
+import { captureTreeFingerprint } from "./tree-fingerprint.ts";
+import type { ResolvedSkillIdentity } from "./resume-context.ts";
 
-export type AgentSkillOption = readonly string[] | undefined;
 export type AgentSkillRequestSource = "explicit" | "prompt";
 
 export interface AgentSkillRequest {
@@ -21,6 +24,18 @@ export interface AgentSkillResourceSetup {
   readonly diagnostics: readonly ResourceDiagnostic[];
 }
 
+export type AgentSkillIdentityCapture =
+  | { readonly kind: "verified"; readonly skills: readonly ResolvedSkillIdentity[] }
+  | { readonly kind: "unverifiable"; readonly reason: string };
+
+export interface AgentSkillIdentityOptions extends ReplayWorkspaceRoots {
+  readonly signal?: AbortSignal;
+}
+
+const SKILL_FINGERPRINT_EXCLUSIONS = new Set([".git", "node_modules"]);
+const SKILL_FINGERPRINT_MAX_BYTES = 8 << 20;
+const SKILL_FINGERPRINT_MAX_FILES = 1024;
+
 const SLASH_SKILL_PATTERN = /\/skill:([a-z0-9][a-z0-9-]{0,63})/gi;
 const SKILLS_FIELD_PATTERN = /(?<!\/)\bskills?\s*[:=]\s*([^\n.;]+)/gi;
 const VERB_SKILL_LIST_PATTERN = /\b(?:include|use|enable|load|provide|allow|grant|with)\s+(?:the\s+|this\s+|these\s+)?skills?\s+([^\n.;]+)/gi;
@@ -131,6 +146,33 @@ export function appendSkillReminder(prompt: string, skills: readonly Pick<Skill,
   return `${prompt}\n\nWorkflow subagent skills enabled: ${skillList}. If you rely on an enabled skill, first read its SKILL.md with the read tool and follow its instructions. No other skills are available in this subagent.`;
 }
 
+/** Capture the exact selected skill directories before journal lookup. */
+export async function captureAgentSkillIdentities(
+  skills: readonly Skill[],
+  options: AgentSkillIdentityOptions,
+): Promise<AgentSkillIdentityCapture> {
+  const identities: ResolvedSkillIdentity[] = [];
+  for (const skill of skills) {
+    const root = resolve(dirname(skill.filePath));
+    const capture = await captureTreeFingerprint({
+      root,
+      excludedRelativePaths: SKILL_FINGERPRINT_EXCLUSIONS,
+      maxBytes: SKILL_FINGERPRINT_MAX_BYTES,
+      maxFiles: SKILL_FINGERPRINT_MAX_FILES,
+      signal: options.signal,
+    });
+    if (capture.kind === "unverifiable") {
+      return { kind: "unverifiable", reason: `skill ${skill.name} could not be fingerprinted: ${capture.reason}` };
+    }
+    identities.push({
+      name: skill.name,
+      path: logicalWorkspacePath(root, options) ?? `external:${skill.name}`,
+      fingerprint: capture.fingerprint,
+    });
+  }
+  return { kind: "verified", skills: identities };
+}
+
 function collectPatternMatches(text: string, pattern: RegExp, selectors: string[], captureIndex: number): void {
   pattern.lastIndex = 0;
   for (let match = pattern.exec(text); match !== null; match = pattern.exec(text)) {

package/.pi/extensions/pi-workflow-engine/src/agent-workspace.ts

@@ -0,0 +1,81 @@
+import type { AgentExecutionOptions, RunContext } from "./agent-runner-types.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+
+interface AgentWorkspaceBase {
+  readonly cwd: string;
+  wrapResult(result: unknown): Promise<unknown>;
+  dispose(): Promise<void>;
+}
+
+export interface SharedAgentWorkspace extends AgentWorkspaceBase {
+  readonly kind: "shared";
+}
+
+export interface IsolatedAgentWorkspace extends AgentWorkspaceBase {
+  readonly kind: "isolated";
+  readonly baselineOid: string;
+}
+
+export type AgentWorkspace = SharedAgentWorkspace | IsolatedAgentWorkspace;
+
+export async function createAgentWorkspace(
+  rc: RunContext,
+  opts: AgentExecutionOptions,
+  label: string,
+): Promise<AgentWorkspace> {
+  if (opts.isolation !== "worktree") {
+    return {
+      kind: "shared",
+      cwd: rc.cwd,
+      async wrapResult(result) {
+        return result;
+      },
+      async dispose() {},
+    };
+  }
+
+  const probe = await rc.worktrees.probe(rc.signal);
+  if (!probe.ok) {
+    throw new Error(`Failed to check git worktree availability for isolated agent: ${probe.error ?? "unknown git error"}`);
+  }
+  if (!probe.inside) {
+    throw new Error("Agent requested worktree isolation, but the workflow cwd is not inside a git work tree.");
+  }
+
+  const added = await rc.worktrees.add(rc.signal, opts.worktreeBaseline);
+  if ("error" in added) throw new Error(`Failed to create isolated worktree: ${added.error}`);
+  const worktreePath = added.path;
+  rc.progress.log(`${label}: using isolated worktree ${worktreePath}`);
+
+  return {
+    kind: "isolated",
+    cwd: worktreePath,
+    baselineOid: added.baselineOid,
+    async wrapResult(result) {
+      const patch = await rc.worktrees.capturePatch(worktreePath, added.baselineOid, rc.signal);
+      if ("error" in patch) throw new Error(`Failed to capture isolated worktree patch: ${patch.error}`);
+      return { result, patch: patch.patch, changed: patch.changed };
+    },
+    async dispose() {
+      const removed = await rc.worktrees.remove(worktreePath);
+      if (!removed.ok) {
+        rc.progress.log(
+          `${label}: failed to remove isolated worktree (${removed.error ?? (removed.stderr.trim() || "unknown error")})`,
+        );
+      }
+    },
+  };
+}
+
+export async function disposeAgentWorkspace(
+  rc: RunContext,
+  label: string,
+  workspace: AgentWorkspace | undefined,
+): Promise<void> {
+  if (!workspace) return;
+  try {
+    await workspace.dispose();
+  } catch (error) {
+    rc.progress.log(`${label}: failed to dispose isolated workspace (${unknownErrorMessage(error)})`);
+  }
+}

package/.pi/extensions/pi-workflow-engine/src/budget.ts

@@ -32,6 +32,13 @@ export interface WorkflowBudget {
   remaining(): number;
 }
 
+/** Refuse a new model turn after the run has consumed its output-token budget. */
+export function assertWorkflowBudgetAvailable(budget: WorkflowBudget): void {
+  if (budget.total !== null && budget.remaining() <= 0) {
+    throw new WorkflowBudgetExceededError(budget.total, budget.spent());
+  }
+}
+
 /**
  * Build a budget backed by the run's usage sink. `spent()` reads
  * `usage.snapshot().totals.output` — the same output-token sum surfaced in the

package/.pi/extensions/pi-workflow-engine/src/cancellation.ts

@@ -7,7 +7,7 @@ export class WorkflowAbortError extends Error {
 
 export function abortReason(signal: AbortSignal | undefined): Error {
   const reason = signal?.reason;
-  if (reason instanceof Error) return reason;
+  if (safeInstanceOf(reason, Error)) return reason;
   if (typeof reason === "string" && reason.length > 0) return new WorkflowAbortError(reason);
   return new WorkflowAbortError();
 }
@@ -18,8 +18,14 @@ export function throwIfAborted(signal: AbortSignal | undefined): void {
 
 export function isFatalWorkflowError(error: unknown, signal: AbortSignal | undefined): boolean {
   if (signal?.aborted) return true;
-  if (error instanceof WorkflowAbortError) return true;
-  if (typeof DOMException !== "undefined" && error instanceof DOMException && error.name === "AbortError") return true;
+  if (safeInstanceOf(error, WorkflowAbortError)) return true;
+  if (typeof DOMException !== "undefined" && safeInstanceOf(error, DOMException)) {
+    try {
+      return error.name === "AbortError";
+    } catch {
+      return false;
+    }
+  }
   return false;
 }
 
@@ -33,3 +39,11 @@ export function linkAbortSignal(parent: AbortSignal | undefined, controller: Abo
   parent.addEventListener("abort", onAbort, { once: true });
   return () => parent.removeEventListener("abort", onAbort);
 }
+
+function safeInstanceOf<T>(value: unknown, constructor: abstract new (...args: never[]) => T): value is T {
+  try {
+    return value instanceof constructor;
+  } catch {
+    return false;
+  }
+}

package/.pi/extensions/pi-workflow-engine/src/concurrency.ts

@@ -1,5 +1,6 @@
 import { performance } from "node:perf_hooks";
 import { abortReason, isFatalWorkflowError, throwIfAborted } from "./cancellation.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
 
 /**
  * A counting semaphore: bounds how many async tasks run at once.
@@ -66,82 +67,191 @@ export interface ParallelOptions {
   readonly signal?: AbortSignal;
   readonly abortController?: AbortController;
   readonly limit?: number;
+  /** Maximum time to drain already-started tasks after a fatal failure. */
+  readonly drainTimeoutMs?: number;
+}
+
+export interface ParallelSettledOptions {
+  readonly settled: true;
+}
+
+export interface ParallelSettledError {
+  readonly name?: string;
+  readonly message: string;
+}
+
+export type ParallelSettledResult<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: ParallelSettledError };
+
+export interface WorkflowParallel {
+  <T>(thunks: Array<() => Promise<T>>): Promise<Array<T | null>>;
+  <T>(thunks: Array<() => Promise<T>>, options: ParallelSettledOptions): Promise<Array<ParallelSettledResult<T>>>;
 }
 
 export interface PipelineOptions {
   readonly signal?: AbortSignal;
   readonly abortController?: AbortController;
+  /** Maximum time to drain already-started item chains after a fatal failure. */
+  readonly drainTimeoutMs?: number;
 }
 
+const DEFAULT_FATAL_DRAIN_TIMEOUT_MS = 1_000;
+
 export function compactResults<T>(values: ReadonlyArray<T | null | undefined>): T[] {
   return values.filter((value): value is T => value != null);
 }
 
-/** Run every thunk concurrently and wait for all results; recoverable failures become null slots. */
-export async function parallel<T>(thunks: Array<() => Promise<T>>, options: ParallelOptions = {}): Promise<Array<T | null>> {
+/** Run every thunk concurrently and wait for all results; recoverable failures become null slots by default. */
+export function parallel<T>(
+  thunks: Array<() => Promise<T>>,
+  options: ParallelOptions & ParallelSettledOptions,
+): Promise<Array<ParallelSettledResult<T>>>;
+export function parallel<T>(thunks: Array<() => Promise<T>>, options?: ParallelOptions): Promise<Array<T | null>>;
+export async function parallel<T>(
+  thunks: Array<() => Promise<T>>,
+  options: ParallelOptions & Partial<ParallelSettledOptions> = {},
+): Promise<Array<T | null> | Array<ParallelSettledResult<T>>> {
+  if (options.settled) {
+    return await runParallel(
+      thunks,
+      options,
+      (value): ParallelSettledResult<T> => ({ ok: true, value }),
+      (error): ParallelSettledResult<T> => ({ ok: false, error: serializeParallelError(error) }),
+    );
+  }
+
+  return await runParallel(
+    thunks,
+    options,
+    (value): T | null => value,
+    (): T | null => null,
+  );
+}
+
+export function bindParallel(options: ParallelOptions): WorkflowParallel {
+  const executionOptions: ParallelOptions = {
+    signal: options.signal,
+    abortController: options.abortController,
+    limit: options.limit,
+    drainTimeoutMs: options.drainTimeoutMs,
+  };
+
+  function boundParallel<T>(thunks: Array<() => Promise<T>>): Promise<Array<T | null>>;
+  function boundParallel<T>(
+    thunks: Array<() => Promise<T>>,
+    workflowOptions: ParallelSettledOptions,
+  ): Promise<Array<ParallelSettledResult<T>>>;
+  async function boundParallel<T>(
+    thunks: Array<() => Promise<T>>,
+    workflowOptions?: ParallelSettledOptions,
+  ): Promise<Array<T | null> | Array<ParallelSettledResult<T>>> {
+    if (workflowOptions?.settled) {
+      return await parallel(thunks, { ...executionOptions, settled: true });
+    }
+    return await parallel(thunks, executionOptions);
+  }
+
+  return boundParallel;
+}
+
+async function runParallel<T, Result>(
+  thunks: Array<() => Promise<T>>,
+  options: ParallelOptions,
+  onSuccess: (value: T) => Result,
+  onFailure: (error: unknown) => Result,
+): Promise<Result[]> {
   throwIfAborted(options.signal);
-  const results = new Array<T | null>(thunks.length);
-  let remaining = thunks.length;
-  if (remaining === 0) return results;
+  const results = new Array<Result>(thunks.length);
+  if (thunks.length === 0) return results;
 
   const limit = normalizeLimit(options.limit, thunks.length);
-  return await new Promise<Array<T | null>>((resolve, reject) => {
-    let rejected = false;
-    let active = 0;
-    let next = 0;
-    const cleanup = () => options.signal?.removeEventListener("abort", onAbort);
-    const rejectOnce = (error: unknown) => {
-      if (rejected) return;
-      rejected = true;
-      options.abortController?.abort(error);
+  return await new Promise<Result[]>((resolve, reject) => {
+    let terminal = false;
+    let nextIndex = 0;
+    let workersRemaining = limit;
+    let fatalFailure: { readonly error: unknown } | undefined;
+    let drainTimer: ReturnType<typeof setTimeout> | undefined;
+    const cleanup = () => {
+      options.signal?.removeEventListener("abort", onAbort);
+      if (drainTimer) clearTimeout(drainTimer);
+    };
+    const settle = (force = false) => {
+      if (terminal || (!force && workersRemaining > 0)) return;
+      terminal = true;
       cleanup();
-      reject(error);
+      if (fatalFailure) reject(fatalFailure.error);
+      else resolve(results);
     };
-    const settleSlot = (index: number, value: T | null) => {
-      if (rejected) return;
-      active--;
-      results[index] = value;
-      remaining--;
-      if (remaining === 0) {
-        cleanup();
-        resolve(results);
-        return;
-      }
-      launchMore();
+    const recordFatalFailure = (error: unknown) => {
+      if (fatalFailure) return;
+      fatalFailure = { error };
+      options.abortController?.abort(error);
+      const timeoutMs = normalizeDrainTimeout(options.drainTimeoutMs);
+      drainTimer = setTimeout(() => settle(true), timeoutMs);
+    };
+    const completeWorker = () => {
+      workersRemaining--;
+      settle();
     };
-    const onAbort = () => rejectOnce(abortReason(options.signal));
-    const launchMore = () => {
-      while (!rejected && active < limit && next < thunks.length) {
-        const index = next++;
-        active++;
-        void Promise.resolve()
-          .then(() => {
-            throwIfAborted(options.signal);
-            return thunks[index]();
-          })
-          .then(
-            (value) => settleSlot(index, value),
-            (error: unknown) => {
-              if (isFatalWorkflowError(error, options.signal)) {
-                rejectOnce(error);
-                return;
-              }
-              settleSlot(index, null);
-            },
-          );
+    const onAbort = () => recordFatalFailure(abortReason(options.signal));
+    const runWorker = async () => {
+      while (!fatalFailure) {
+        throwIfAborted(options.signal);
+        const index = nextIndex++;
+        if (index >= thunks.length) return;
+        try {
+          const value = await thunks[index]();
+          if (fatalFailure) return;
+          results[index] = onSuccess(value);
+        } catch (error) {
+          if (fatalFailure) return;
+          if (isFatalWorkflowError(error, options.signal)) {
+            recordFatalFailure(error);
+            return;
+          }
+          results[index] = onFailure(error);
+        }
       }
     };
 
     options.signal?.addEventListener("abort", onAbort, { once: true });
-    launchMore();
+    if (options.signal?.aborted) onAbort();
+    for (let worker = 0; worker < limit; worker++) {
+      void runWorker().then(completeWorker, (error) => {
+        recordFatalFailure(error);
+        completeWorker();
+      });
+    }
   });
 }
 
+function serializeParallelError(error: unknown): ParallelSettledError {
+  const message = readStringProperty(error, "message") ?? unknownErrorMessage(error);
+  const name = readStringProperty(error, "name");
+  return name && name.length > 0 ? { name, message } : { message };
+}
+
+function readStringProperty(value: unknown, property: "message" | "name"): string | undefined {
+  if ((typeof value !== "object" && typeof value !== "function") || value === null) return undefined;
+  try {
+    const candidate = Reflect.get(value, property);
+    return typeof candidate === "string" ? candidate : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function normalizeLimit(limit: number | undefined, itemCount: number): number {
   if (limit === undefined || !Number.isFinite(limit)) return Math.max(1, itemCount);
   return Math.max(1, Math.min(itemCount, Math.trunc(limit)));
 }
 
+function normalizeDrainTimeout(timeoutMs: number | undefined): number {
+  if (timeoutMs === undefined || !Number.isFinite(timeoutMs)) return DEFAULT_FATAL_DRAIN_TIMEOUT_MS;
+  return Math.max(0, Math.trunc(timeoutMs));
+}
+
 /**
  * Run each item through all stages independently. There is NO barrier between
  * stages: item A can be in stage 3 while item B is still in stage 1. Actual agent
@@ -207,24 +317,17 @@ export async function pipelineWithOptions(
   options: PipelineOptions = {},
 ): Promise<Array<unknown | null>> {
   throwIfAborted(options.signal);
-  return Promise.all(
-    items.map(async (item, index) => {
+  return await parallel(
+    items.map((item, index) => async () => {
       throwIfAborted(options.signal);
       let acc: unknown = item;
-      try {
-        for (const stage of stages) {
-          throwIfAborted(options.signal);
-          acc = await stage(acc, item, index);
-        }
-        return acc;
-      } catch (error) {
-        if (isFatalWorkflowError(error, options.signal)) {
-          options.abortController?.abort(error);
-          throw error;
-        }
-        return null;
+      for (const stage of stages) {
+        throwIfAborted(options.signal);
+        acc = await stage(acc, item, index);
       }
+      return acc;
     }),
+    options,
   );
 }
 

package/.pi/extensions/pi-workflow-engine/src/diff-capture.ts

@@ -1,19 +1,43 @@
+import { Type, type Static } from "typebox";
+import { Value } from "typebox/value";
 import type { PerfSink } from "./perf.ts";
-import { runBoundedProcess } from "./process-runner.ts";
+import { runBoundedProcess, type BoundedProcessFailure } from "./process-runner.ts";
 
-export interface AllowedDiffCommand {
-  readonly file: "git" | "gh";
-  readonly args: readonly string[];
-}
+export type GitDiffBaselineTarget =
+  | { readonly kind: "working-tree" }
+  | { readonly kind: "index" }
+  | { readonly kind: "range"; readonly ref: string };
+
+export const GitReviewDiffTargetSchema = Type.Object({
+  kind: Type.Literal("git"),
+  args: Type.Array(Type.String()),
+});
+
+export const PullRequestReviewDiffTargetSchema = Type.Object({
+  kind: Type.Literal("pull-request"),
+  number: Type.Integer({ minimum: 1 }),
+});
+
+export const ReviewDiffTargetSchema = Type.Union([GitReviewDiffTargetSchema, PullRequestReviewDiffTargetSchema]);
 
-export interface DiffCaptureResult {
-  readonly ok: boolean;
+export type GitReviewDiffTarget = Static<typeof GitReviewDiffTargetSchema>;
+export type PullRequestReviewDiffTarget = Static<typeof PullRequestReviewDiffTargetSchema>;
+
+/** Serializable semantic identity of the diff being reviewed. */
+export type ReviewDiffTarget = Static<typeof ReviewDiffTargetSchema>;
+
+interface DiffCaptureResultBase {
   readonly stdout: string;
   readonly durationMs: number;
   readonly bytes: number;
-  readonly error?: string;
 }
 
+export type DiffCaptureResult =
+  | (DiffCaptureResultBase & { readonly ok: true; readonly error?: undefined; readonly failure?: undefined })
+  | (DiffCaptureResultBase & { readonly ok: false; readonly error: string; readonly failure: DiffCaptureFailure });
+
+export type DiffCaptureFailure = BoundedProcessFailure | { readonly kind: "invalid-target"; readonly message: string };
+
 export interface DiffCaptureOptions {
   readonly cwd: string;
   readonly signal?: AbortSignal;
@@ -25,25 +49,35 @@ export interface DiffCaptureOptions {
 }
 
 const SAFE_REF_OR_PATH = /^[A-Za-z0-9_./:@~+=,\-]+$/;
-const SAFE_GH_FLAG = /^--[A-Za-z0-9-]+(=[A-Za-z0-9_./:@~+=,\-]+)?$/;
-const SAFE_GIT_DIFF_FLAGS = new Set(["--cached", "--staged", "--no-color", "--color=never", "--no-ext-diff"]);
+const SAFE_GH_DIFF_FLAGS = new Set(["--color=never"]);
+const SAFE_GIT_DIFF_FLAGS = new Set(["--binary", "--cached", "--staged", "--no-color", "--color=never", "--no-ext-diff"]);
 
-export function parseAllowedDiffCommand(command: string): AllowedDiffCommand | { error: string } {
+export function parseAllowedDiffCommand(command: string): ReviewDiffTarget | { error: string } {
   const tokens = command.trim().split(/\s+/).filter(Boolean);
   if (tokens.length < 2) return { error: "empty or incomplete diff command" };
-  if (tokens[0] === "git" && tokens[1] === "diff") return parseGitDiff(tokens);
+  if (tokens[0] === "git" && tokens[1] === "diff") {
+    const parsed = parseGitDiff(tokens);
+    return "error" in parsed ? parsed : parsed.target;
+  }
   if (tokens[0] === "gh" && tokens[1] === "pr" && tokens[2] === "diff" && /^\d+$/.test(tokens[3] ?? "")) {
+    const number = Number(tokens[3]);
+    if (!Number.isSafeInteger(number) || number <= 0) return { error: "pull-request number must be a positive safe integer" };
     const flags = tokens.slice(4);
-    const unsafe = flags.find((token) => !SAFE_GH_FLAG.test(token));
-    if (unsafe) return { error: `unsupported gh pr diff token: ${unsafe}` };
-    return { file: "gh", args: ["pr", "diff", tokens[3], ...flags] };
+    if (flags.includes("--patch")) return { error: "gh pr diff --patch is not supported because reviews require the cumulative pull-request diff" };
+    const unsupported = flags.find((token) => !SAFE_GH_DIFF_FLAGS.has(token));
+    if (unsupported) return { error: `unsupported gh pr diff option: ${unsupported}` };
+    return { kind: "pull-request", number };
   }
   return { error: "diff command is not in the git/gh allowlist" };
 }
 
-function parseGitDiff(tokens: readonly string[]): AllowedDiffCommand | { error: string } {
+function parseGitDiff(
+  tokens: readonly string[],
+): { readonly target: GitReviewDiffTarget; readonly baseline: GitDiffBaselineTarget } | { readonly error: string } {
   const args = tokens.slice(2);
   const safeArgs = ["diff", "--no-ext-diff"];
+  const operands: string[] = [];
+  let staged = false;
   let pathMode = false;
 
   for (const token of args) {
@@ -55,13 +89,31 @@ function parseGitDiff(tokens: readonly string[]): AllowedDiffCommand | { error:
     }
     if (!pathMode && token.startsWith("-")) {
       if (!isAllowedGitDiffFlag(token)) return { error: `unsupported git diff option: ${token}` };
+      staged ||= token === "--cached" || token === "--staged";
       if (token !== "--no-ext-diff") safeArgs.push(token);
       continue;
     }
+    if (!pathMode) operands.push(token);
     safeArgs.push(token);
   }
 
-  return { file: "git", args: safeArgs };
+  const baseline = classifyGitDiffBaseline(staged, operands);
+  return "error" in baseline ? baseline : { target: { kind: "git", args: safeArgs }, baseline };
+}
+
+function classifyGitDiffBaseline(staged: boolean, operands: readonly string[]): GitDiffBaselineTarget | { readonly error: string } {
+  if (operands.length > 1) {
+    return { error: "ambiguous git diff operands; use A..B or A...B for revisions, or -- before multiple paths" };
+  }
+  if (staged) return { kind: "index" };
+
+  const range = operands.find((operand) => operand.includes(".."));
+  if (range) {
+    const separator = range.includes("...") ? "..." : "..";
+    return { kind: "range", ref: range.slice(range.indexOf(separator) + separator.length) || "HEAD" };
+  }
+
+  return { kind: "working-tree" };
 }
 
 function isAllowedGitDiffFlag(token: string): boolean {
@@ -71,12 +123,24 @@ function isAllowedGitDiffFlag(token: string): boolean {
 export async function captureDiff(command: string, options: DiffCaptureOptions): Promise<DiffCaptureResult> {
   const parsed = parseAllowedDiffCommand(command);
   if ("error" in parsed) {
-    return { ok: false, stdout: "", durationMs: 0, bytes: 0, error: parsed.error };
+    return {
+      ok: false,
+      stdout: "",
+      durationMs: 0,
+      bytes: 0,
+      error: parsed.error,
+      failure: { kind: "invalid-target", message: parsed.error },
+    };
   }
 
+  return await captureDiffTarget(parsed, options);
+}
+
+export async function captureDiffTarget(target: ReviewDiffTarget, options: DiffCaptureOptions): Promise<DiffCaptureResult> {
+  const command = reviewDiffCommand(target);
   const result = await runBoundedProcess({
-    file: parsed.file,
-    args: parsed.args,
+    file: command.file,
+    args: command.args,
     cwd: options.cwd,
     env: diffCaptureEnv(options.env),
     signal: options.signal,
@@ -93,6 +157,39 @@ export async function captureDiff(command: string, options: DiffCaptureOptions):
   return result;
 }
 
+export function reviewDiffCommand(target: ReviewDiffTarget): { readonly file: "git" | "gh"; readonly args: readonly string[] } {
+  return target.kind === "pull-request"
+    ? { file: "gh", args: ["pr", "diff", String(target.number), "--color=never"] }
+    : { file: "git", args: target.args };
+}
+
+/** Canonical display form. Never execute this string directly; use reviewDiffCommand(). */
+export function formatReviewDiffTarget(target: ReviewDiffTarget): string {
+  const command = reviewDiffCommand(target);
+  return [command.file, ...command.args].join(" ");
+}
+
+/** Derive reconstruction semantics from the canonical git command instead of persisting duplicate state. */
+export function reviewGitDiffBaseline(target: GitReviewDiffTarget): GitDiffBaselineTarget {
+  const parsed = parseGitDiff(["git", ...target.args]);
+  if ("error" in parsed) throw new Error(`Invalid persisted git review target: ${parsed.error}`);
+  return parsed.baseline;
+}
+
+/** Validate persisted targets by round-tripping through the single command allowlist parser. */
+export function isReviewDiffTarget(value: unknown): value is ReviewDiffTarget {
+  if (!Value.Check(ReviewDiffTargetSchema, value)) return false;
+  const parsed = parseAllowedDiffCommand(formatReviewDiffTarget(value));
+  return !("error" in parsed) && sameReviewDiffTarget(parsed, value);
+}
+
+function sameReviewDiffTarget(left: ReviewDiffTarget, right: ReviewDiffTarget): boolean {
+  if (left.kind !== right.kind) return false;
+  if (left.kind === "pull-request") return right.kind === "pull-request" && left.number === right.number;
+  if (right.kind !== "git" || left.args.length !== right.args.length) return false;
+  return left.args.every((arg, index) => arg === right.args[index]);
+}
+
 function diffCaptureEnv(env: NodeJS.ProcessEnv | undefined): NodeJS.ProcessEnv {
   return { ...(env ?? process.env), GIT_EXTERNAL_DIFF: "", GIT_DIFF_OPTS: "" };
 }