pi-workflow-engine 0.11.0 → 0.13.0

package/.pi/extensions/pi-workflow-engine/src/research-evidence.ts

@@ -0,0 +1,289 @@
+import {
+  MAX_RESEARCH_LANES,
+  MAX_VERIFICATION_CLAIMS,
+  type ResearchClaimCandidate,
+  type ResearchEvidence,
+  type ResearchLane,
+  type ResearchLaneResult,
+  type ResearchPlan,
+  type ResearchReport,
+  type ResearchReportEntry,
+  type ResearchSource,
+  type ResearchVerification,
+} from "./research-contract.ts";
+
+const TRACKING_PARAMETERS = new Set(["fbclid", "gclid", "mc_cid", "mc_eid", "ref_src"]);
+const IMPORTANCE_RANK: Readonly<Record<ResearchEvidence["importance"], number>> = { high: 0, medium: 1, low: 2 };
+
+export function normalizeResearchLanes(plan: ResearchPlan): ResearchLane[] {
+  const seen = new Set<string>();
+  const lanes: ResearchLane[] = [];
+  for (const lane of plan.lanes) {
+    const id = normalizedText(lane.id);
+    const title = normalizedText(lane.title);
+    const objective = normalizedText(lane.objective);
+    const queries = dedupeText(lane.queries).slice(0, 4);
+    if (!id || !title || !objective || queries.length === 0 || seen.has(id.toLowerCase())) continue;
+    seen.add(id.toLowerCase());
+    lanes.push({ id, title, objective, queries });
+    if (lanes.length >= MAX_RESEARCH_LANES) break;
+  }
+  return lanes;
+}
+
+export function sanitizeLaneResults(results: readonly ResearchLaneResult[]): ResearchLaneResult[] {
+  return results.map((result) => ({
+    laneId: normalizedText(result.laneId),
+    gaps: dedupeText(result.gaps),
+    evidence: dedupeEvidence(result.evidence.map(sanitizeEvidence).filter(isDefined)),
+  }));
+}
+
+export function buildClaimCandidates(results: readonly ResearchLaneResult[]): ResearchClaimCandidate[] {
+  const byClaim = new Map<string, { claim: string; importance: ResearchEvidence["importance"]; evidence: ResearchEvidence[] }>();
+  for (const item of results.flatMap((result) => result.evidence)) {
+    const key = normalizedText(item.claim).toLowerCase();
+    if (!key) continue;
+    const current = byClaim.get(key);
+    if (!current) {
+      byClaim.set(key, { claim: normalizedText(item.claim), importance: item.importance, evidence: [item] });
+      continue;
+    }
+    if (IMPORTANCE_RANK[item.importance] < IMPORTANCE_RANK[current.importance]) current.importance = item.importance;
+    current.evidence = dedupeEvidence([...current.evidence, item]);
+  }
+  return [...byClaim.values()]
+    .sort((left, right) => IMPORTANCE_RANK[left.importance] - IMPORTANCE_RANK[right.importance])
+    .slice(0, MAX_VERIFICATION_CLAIMS);
+}
+
+export function sanitizeVerification(
+  verification: ResearchVerification,
+  candidate: ResearchClaimCandidate,
+): ResearchVerification {
+  const sources = dedupeSources(verification.sources);
+  const verdict = (verification.verdict === "SUPPORTED" || verification.verdict === "CONFLICTED") && sources.length === 0
+    ? "UNCERTAIN"
+    : verification.verdict;
+  return {
+    claim: candidate.claim,
+    verdict,
+    explanation: normalizedText(verification.explanation) || "Independent verification returned no explanation.",
+    sources,
+  };
+}
+
+export function unavailableVerification(candidate: ResearchClaimCandidate): ResearchVerification {
+  return {
+    claim: candidate.claim,
+    verdict: "UNCERTAIN",
+    explanation: "Independent verification did not complete; gathered evidence remains unverified.",
+    sources: dedupeSources(candidate.evidence.map((item) => item.source)),
+  };
+}
+
+export function sanitizeResearchReport(
+  report: ResearchReport,
+  verifications: readonly ResearchVerification[],
+): ResearchReport {
+  const sources = dedupeSources(
+    verifications
+      .filter((verification) => verification.verdict !== "REJECTED")
+      .flatMap((verification) => verification.sources),
+  );
+  const uncertainties = sanitizeEntries(
+    report.uncertainties,
+    verificationSources(verifications, "UNCERTAIN"),
+    false,
+  );
+  const supportedClaims = sanitizeEntries(
+    report.supportedClaims,
+    verificationSources(verifications, "SUPPORTED"),
+    true,
+    uncertainties,
+  );
+  const conflictingEvidence = sanitizeEntries(
+    report.conflictingEvidence,
+    verificationSources(verifications, "CONFLICTED"),
+    true,
+    uncertainties,
+  );
+  const inferences = sanitizeEntries(
+    report.inferences,
+    verificationSources(verifications, "INFERENCE"),
+    false,
+  );
+  return {
+    answer: normalizedText(report.answer),
+    supportedClaims,
+    conflictingEvidence,
+    uncertainties,
+    inferences,
+    sources,
+    limitations: dedupeText(report.limitations),
+    nextSteps: dedupeText(report.nextSteps),
+  };
+}
+
+function verificationSources(
+  verifications: readonly ResearchVerification[],
+  verdict: ResearchVerification["verdict"],
+): ReadonlyMap<string, ReadonlyMap<string, ResearchSource>> {
+  const byClaim = new Map<string, Map<string, ResearchSource>>();
+  for (const verification of verifications) {
+    if (verification.verdict !== verdict) continue;
+    const key = normalizedText(verification.claim).toLowerCase();
+    const claimSources = byClaim.get(key) ?? new Map<string, ResearchSource>();
+    dedupeSources(
+      verification.sources,
+    ).forEach((source) => claimSources.set(source.url, source));
+    byClaim.set(key, claimSources);
+  }
+  return byClaim;
+}
+
+export function fallbackResearchReport(
+  verifications: readonly ResearchVerification[],
+  limitation: string,
+): ResearchReport {
+  const entry = (verification: ResearchVerification): ResearchReportEntry => ({
+    claim: verification.claim,
+    explanation: verification.explanation,
+    citations: verification.sources,
+  });
+  return {
+    answer: "The synthesis stage did not complete; independently verified claims are grouped below without additional model interpretation.",
+    supportedClaims: verifications.filter((item) => item.verdict === "SUPPORTED").map(entry),
+    conflictingEvidence: verifications.filter((item) => item.verdict === "CONFLICTED").map(entry),
+    uncertainties: verifications.filter((item) => item.verdict === "UNCERTAIN").map(entry),
+    inferences: verifications.filter((item) => item.verdict === "INFERENCE").map(entry),
+    sources: dedupeSources(verifications.flatMap((verification) => verification.sources)),
+    limitations: [limitation],
+    nextSteps: ["Review the verified claim groups and rerun synthesis if a narrative answer is required."],
+  };
+}
+
+export function unavailableResearchReport(reason: "empty-question" | "missing-capability" | "no-evidence"): ResearchReport {
+  const message = reason === "empty-question"
+    ? "No research question was provided."
+    : reason === "missing-capability"
+      ? "Research could not start because pi exposed no installed external web-search or URL-extraction tool."
+      : "Research completed without enough direct-page evidence to support an answer.";
+  const nextStep = reason === "empty-question"
+    ? "Run `/workflow research <question>` and include any source, date, or geography constraints in the arguments."
+    : reason === "missing-capability"
+      ? "Install or enable a pi tool that can search the web or extract HTTP(S) pages, then rerun the workflow."
+      : "Check the installed external-search tool, narrow the question, or provide preferred source domains.";
+  return {
+    answer: message,
+    supportedClaims: [],
+    conflictingEvidence: [],
+    uncertainties: [],
+    inferences: [],
+    sources: [],
+    limitations: [message],
+    nextSteps: [nextStep],
+  };
+}
+
+export function canonicalSourceUrl(raw: string): string | undefined {
+  try {
+    const url = new URL(raw.trim());
+    if ((url.protocol !== "http:" && url.protocol !== "https:") || url.username || url.password) return undefined;
+    if (isSearchResultsUrl(url)) return undefined;
+    url.hash = "";
+    for (const key of [...url.searchParams.keys()]) {
+      if (key.toLowerCase().startsWith("utm_") || TRACKING_PARAMETERS.has(key.toLowerCase())) url.searchParams.delete(key);
+    }
+    url.searchParams.sort();
+    if (url.pathname.length > 1 && url.pathname.endsWith("/")) url.pathname = url.pathname.slice(0, -1);
+    return url.toString();
+  } catch {
+    return undefined;
+  }
+}
+
+export function dedupeSources(sources: readonly ResearchSource[]): ResearchSource[] {
+  const byUrl = new Map<string, ResearchSource>();
+  for (const source of sources) {
+    const url = canonicalSourceUrl(source.url);
+    const title = normalizedText(source.title);
+    if (!url || !title || byUrl.has(url)) continue;
+    const publishedAt = source.publishedAt === undefined ? undefined : normalizedText(source.publishedAt);
+    byUrl.set(url, { title, url, ...(publishedAt ? { publishedAt } : {}) });
+  }
+  return [...byUrl.values()];
+}
+
+function sanitizeEvidence(item: ResearchEvidence): ResearchEvidence | undefined {
+  const source = dedupeSources([item.source])[0];
+  const claim = normalizedText(item.claim);
+  const evidence = normalizedText(item.evidence);
+  if (!source || !claim || !evidence) return undefined;
+  return { claim, importance: item.importance, stance: item.stance, evidence, source };
+}
+
+function dedupeEvidence(evidence: readonly ResearchEvidence[]): ResearchEvidence[] {
+  const seen = new Set<string>();
+  return evidence.filter((item) => {
+    const key = `${item.claim.toLowerCase()}\0${item.stance}\0${item.source.url}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function sanitizeEntries(
+  entries: readonly ResearchReportEntry[],
+  allowedByClaim: ReadonlyMap<string, ReadonlyMap<string, ResearchSource>>,
+  requireCitation: boolean,
+  demoted: ResearchReportEntry[] = [],
+): ResearchReportEntry[] {
+  const sanitized: ResearchReportEntry[] = [];
+  for (const entry of entries) {
+    const claim = normalizedText(entry.claim);
+    const explanation = normalizedText(entry.explanation);
+    if (!claim || !explanation) continue;
+    const allowed = allowedByClaim.get(claim.toLowerCase()) ?? new Map<string, ResearchSource>();
+    const citations = dedupeSources(entry.citations)
+      .map((source) => allowed.get(source.url))
+      .filter(isDefined);
+    if (requireCitation && citations.length === 0) {
+      demoted.push({ claim, explanation: `${explanation} No verified direct-page citation survived validation.`, citations: [] });
+      continue;
+    }
+    sanitized.push({ claim, explanation, citations });
+  }
+  return sanitized;
+}
+
+function isSearchResultsUrl(url: URL): boolean {
+  const host = url.hostname.toLowerCase().replace(/^www\./, "");
+  const path = url.pathname.replace(/\/+$/, "") || "/";
+  if (/^(?:google\.[a-z.]+|bing\.com|search\.yahoo\.com|search\.brave\.com|yandex\.[a-z.]+)$/.test(host)) {
+    return path === "/search" || path === "/results" || path === "/yandsearch";
+  }
+  if (host === "duckduckgo.com") return (path === "/" || path === "/html" || path === "/lite") && url.searchParams.has("q");
+  return false;
+}
+
+function dedupeText(values: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const value of values) {
+    const normalized = normalizedText(value);
+    const key = normalized.toLowerCase();
+    if (!normalized || seen.has(key)) continue;
+    seen.add(key);
+    result.push(normalized);
+  }
+  return result;
+}
+
+function normalizedText(value: string): string {
+  return value.trim().replace(/\s+/g, " ");
+}
+
+function isDefined<T>(value: T | undefined): value is T {
+  return value !== undefined;
+}

package/.pi/extensions/pi-workflow-engine/src/resume-context.ts

@@ -1,6 +1,8 @@
-import { lstat } from "node:fs/promises";
+import type { Stats } from "node:fs";
+import { lstat, stat } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { throwIfAborted } from "./cancellation.ts";
+import { isMissingPathError } from "./filesystem-error.ts";
 import type {
   EffectiveAgentSessionIdentity,
   EffectiveToolIdentity,
@@ -66,6 +68,10 @@ export interface AgentResumeContext extends VerifiedAgentResumeBaseContext {
   readonly skills: readonly ResolvedSkillIdentity[];
 }
 
+export interface ResumeContextComparisonOptions {
+  readonly allowWorkflowSourceMismatch?: boolean;
+}
+
 type RepositoryRevision =
   | { readonly state: "git"; readonly head: string }
   | { readonly state: "unborn" };
@@ -306,57 +312,85 @@ async function captureGitVisibleStateUnchecked(
   ]);
   throwIfAborted(signal);
 
-  for (const [operation, result] of [
-    ["unstaged diff capture", unstaged],
-    ["unstaged mode capture", unstagedRaw],
-    ["staged diff capture", staged],
-    ["untracked path capture", untrackedPaths],
-    ["index entry capture", indexEntries],
-    ["tracked flag capture", trackedFlags],
-  ] as const) {
-    if (!result.ok) return { kind: "unverifiable", reason: processFailureReason(`git ${operation}`, result) };
-  }
+  const validated = validateGitVisibleOutputs({ unstaged, unstagedRaw, staged, untrackedPaths, indexEntries, trackedFlags });
+  if (!validated.ok) return { kind: "unverifiable", reason: validated.reason };
+
+  const untracked = await captureDeclaredInputFingerprint({
+    root: cwd,
+    inputs: validated.untrackedPaths.filter((path) => !isFingerprintExcludedPath(path)),
+    excludedRelativePaths: FINGERPRINT_EXCLUDED_RELATIVE_PATHS,
+    maxBytes: CONTENT_FINGERPRINT_MAX_BYTES,
+    maxEntries: GIT_UNTRACKED_MAX_ENTRIES,
+    signal,
+  });
+  if (untracked.kind === "unverifiable") return untracked;
+
+  return {
+    kind: "verified",
+    fingerprint: combineFingerprints([
+      ["unstaged", validated.unstaged],
+      ["staged", validated.staged],
+      ["index", validated.indexEntries],
+      ["untracked", untracked.fingerprint],
+    ]),
+  };
+}
+
+interface GitVisibleProcessOutputs {
+  readonly unstaged: BoundedProcessResult;
+  readonly unstagedRaw: BoundedProcessResult;
+  readonly staged: BoundedProcessResult;
+  readonly untrackedPaths: BoundedProcessResult;
+  readonly indexEntries: BoundedProcessResult;
+  readonly trackedFlags: BoundedProcessResult;
+}
+
+type ValidatedGitVisibleOutputs =
+  | {
+      readonly ok: true;
+      readonly unstaged: string;
+      readonly staged: string;
+      readonly indexEntries: string;
+      readonly untrackedPaths: readonly string[];
+    }
+  | { readonly ok: false; readonly reason: string };
+
+function validateGitVisibleOutputs(outputs: GitVisibleProcessOutputs): ValidatedGitVisibleOutputs {
+  const { unstaged, unstagedRaw, staged, untrackedPaths, indexEntries, trackedFlags } = outputs;
+  if (!unstaged.ok) return { ok: false, reason: processFailureReason("git unstaged diff capture", unstaged) };
+  if (!unstagedRaw.ok) return { ok: false, reason: processFailureReason("git unstaged mode capture", unstagedRaw) };
+  if (!staged.ok) return { ok: false, reason: processFailureReason("git staged diff capture", staged) };
+  if (!untrackedPaths.ok) return { ok: false, reason: processFailureReason("git untracked path capture", untrackedPaths) };
+  if (!indexEntries.ok) return { ok: false, reason: processFailureReason("git index entry capture", indexEntries) };
+  if (!trackedFlags.ok) return { ok: false, reason: processFailureReason("git tracked flag capture", trackedFlags) };
 
   const unsafeWorktreeMode = rawWorktreeModeFailure(unstagedRaw.stdout);
-  if (unsafeWorktreeMode) return { kind: "unverifiable", reason: unsafeWorktreeMode };
+  if (unsafeWorktreeMode) return { ok: false, reason: unsafeWorktreeMode };
 
   for (const record of parseNullTerminatedRecords(indexEntries.stdout, "git index entry capture")) {
     const entry = parseIndexEntry(record);
     if (entry.stage !== 0) {
-      return { kind: "unverifiable", reason: "git-visible repository state contains unmerged paths" };
+      return { ok: false, reason: "git-visible repository state contains unmerged paths" };
     }
     const unsafe = unsafeTrackedModeReason(entry.mode, entry.path);
-    if (unsafe) return { kind: "unverifiable", reason: unsafe };
+    if (unsafe) return { ok: false, reason: unsafe };
   }
 
   const unsafeFlag = parseNullTerminatedRecords(trackedFlags.stdout, "git tracked flag capture")
     .find((record) => record[0] !== "H");
   if (unsafeFlag) {
     return {
-      kind: "unverifiable",
+      ok: false,
       reason: `git-visible repository state contains an unsupported tracked-file flag: ${unsafeFlag[0] ?? "unknown"}`,
     };
   }
 
-  const untracked = await captureDeclaredInputFingerprint({
-    root: cwd,
-    inputs: parseNullTerminatedRecords(untrackedPaths.stdout, "git untracked path capture")
-      .filter((path) => !isFingerprintExcludedPath(path)),
-    excludedRelativePaths: FINGERPRINT_EXCLUDED_RELATIVE_PATHS,
-    maxBytes: CONTENT_FINGERPRINT_MAX_BYTES,
-    maxEntries: GIT_UNTRACKED_MAX_ENTRIES,
-    signal,
-  });
-  if (untracked.kind === "unverifiable") return untracked;
-
   return {
-    kind: "verified",
-    fingerprint: combineFingerprints([
-      ["unstaged", unstaged.stdout],
-      ["staged", staged.stdout],
-      ["index", indexEntries.stdout],
-      ["untracked", untracked.fingerprint],
-    ]),
+    ok: true,
+    unstaged: unstaged.stdout,
+    staged: staged.stdout,
+    indexEntries: indexEntries.stdout,
+    untrackedPaths: parseNullTerminatedRecords(untrackedPaths.stdout, "git untracked path capture"),
   };
 }
 
@@ -470,7 +504,11 @@ export function createAgentResumeContext(
   };
 }
 
-export function resumeContextMismatchReason(stored: AgentResumeContext, current: AgentResumeContext): string | undefined {
+export function resumeContextMismatchReason(
+  stored: AgentResumeContext,
+  current: AgentResumeContext,
+  options: ResumeContextComparisonOptions = {},
+): string | undefined {
   if (stored.repository.state !== current.repository.state) return "repository state changed";
   if (
     (stored.repository.state === "git" || stored.repository.state === "isolated") &&
@@ -483,7 +521,10 @@ export function resumeContextMismatchReason(stored: AgentResumeContext, current:
     return "working tree contents changed";
   }
   if (stored.workflow.name !== current.workflow.name) return "workflow name changed";
-  if (stored.workflow.sourceFingerprint !== current.workflow.sourceFingerprint) return "workflow source changed";
+  if (
+    !options.allowWorkflowSourceMismatch
+    && stored.workflow.sourceFingerprint !== current.workflow.sourceFingerprint
+  ) return "workflow source changed";
   if (stored.session.runtimeVersion !== current.session.runtimeVersion) return "coding-agent runtime changed";
   if (stored.session.systemPromptFingerprint !== current.session.systemPromptFingerprint) return "effective system prompt changed";
   if (
@@ -535,6 +576,54 @@ async function runGit(cwd: string, args: readonly string[], signal: AbortSignal
   });
 }
 
+/**
+ * Decide whether a `.git` entry found during the ancestor walk marks a repository
+ * that git may have failed to open, or a stray entry that git's own discovery
+ * also skips.
+ *
+ * The rule mirrors git's discovery loop so that "absent" means git itself would
+ * have walked past every `.git` entry and its "not a repository" answer is
+ * authoritative:
+ *
+ * - A regular file is a gitfile. Git halts on any regular `.git` file, even when
+ *   its content is malformed or its `gitdir:` target is missing, so the entry is
+ *   a marker regardless of content.
+ * - A directory is a repository only when `HEAD`, `objects/`, and `refs/` all
+ *   exist. Git skips a directory that lacks any of them (an empty `.git` is the
+ *   common case), so such a directory is not a marker.
+ * - A symbolic link is resolved first, as git uses `stat`. A dangling link is
+ *   skipped by git and is therefore not a marker.
+ * - Any other entry type (socket, FIFO, device) is skipped by git.
+ *
+ * A missing path (`ENOENT`) is a negative answer, not a failure. Any other
+ * filesystem error propagates so the caller reports the probe as "unknown".
+ */
+async function isRepositoryMarker(entryPath: string, entry: Stats): Promise<boolean> {
+  let target = entry;
+  if (entry.isSymbolicLink()) {
+    const resolved = await statIfPresent(entryPath);
+    if (!resolved) return false;
+    target = resolved;
+  }
+  if (target.isFile()) return true;
+  if (!target.isDirectory()) return false;
+  for (const name of GIT_DIRECTORY_REQUIRED_ENTRIES) {
+    if (!(await statIfPresent(join(entryPath, name)))) return false;
+  }
+  return true;
+}
+
+const GIT_DIRECTORY_REQUIRED_ENTRIES = ["HEAD", "objects", "refs"] as const;
+
+async function statIfPresent(path: string): Promise<Stats | undefined> {
+  try {
+    return await stat(path);
+  } catch (error) {
+    if (isMissingPathError(error)) return undefined;
+    throw error;
+  }
+}
+
 type GitControlPathResult =
   | { readonly kind: "present" | "absent" }
   | { readonly kind: "unknown"; readonly reason: string };
@@ -543,9 +632,10 @@ async function findGitControlPath(cwd: string, signal: AbortSignal | undefined):
   let current = resolve(cwd);
   while (true) {
     throwIfAborted(signal);
+    const entryPath = join(current, ".git");
     try {
-      await lstat(join(current, ".git"));
-      return { kind: "present" };
+      const entry = await lstat(entryPath);
+      if (await isRepositoryMarker(entryPath, entry)) return { kind: "present" };
     } catch (error) {
       if (!isMissingPathError(error)) {
         return { kind: "unknown", reason: `git control-path probe failed: ${unknownErrorMessage(error)}` };
@@ -619,10 +709,6 @@ function isEffectiveToolIdentity(value: unknown): value is EffectiveToolIdentity
   );
 }
 
-function isMissingPathError(error: unknown): boolean {
-  return error instanceof Error && "code" in error && error.code === "ENOENT";
-}
-
 function parseNullTerminatedRecords(output: string, operation: string): string[] {
   if (output.length === 0) return [];
   if (!output.endsWith("\0")) throw new Error(`${operation} returned unterminated data`);

package/.pi/extensions/pi-workflow-engine/src/review/code-review-orchestration.ts

@@ -0,0 +1,24 @@
+const DIFF_EMBED_CAP = 60_000;
+
+export function buildCodeReviewScopeBlock(input: {
+  readonly diffCommand: string;
+  readonly files: readonly string[];
+  readonly summary: string;
+  readonly conventions?: string;
+  readonly diffText: string;
+  readonly target: string;
+}): string {
+  const diffBlock = input.diffText
+    ? `\n## Diff (review is bounded to these changed lines)\n\`\`\`diff\n${
+        input.diffText.length > DIFF_EMBED_CAP
+          ? `${input.diffText.slice(0, DIFF_EMBED_CAP)}\n... (truncated — run \`${input.diffCommand}\` for the full diff)`
+          : input.diffText
+      }\n\`\`\`\n`
+    : "";
+  return (
+    `## Diff command\n${input.diffCommand}\n\n## Changed files\n${input.files.map((file) => `- ${file}`).join("\n")}\n\n` +
+    `## Summary\n${input.summary}\n\n## Conventions\n${input.conventions ?? "(none noted)"}\n` +
+    diffBlock +
+    (input.target ? `\n## User instructions (verbatim)\n${input.target}\n` : "")
+  );
+}

package/.pi/extensions/pi-workflow-engine/src/review/patch-validation.ts

@@ -0,0 +1,120 @@
+import { createHash } from "node:crypto";
+import { Type, type Static } from "typebox";
+import { throwIfAborted } from "../cancellation.ts";
+import { runBoundedProcess, type BoundedProcessResult } from "../process-runner.ts";
+import { WorktreeRegistry, type WorktreeBaseline } from "../worktree.ts";
+import { unknownErrorMessage } from "../unknown-error.ts";
+import { fingerprintReviewWorktreeBaseline } from "./review-snapshot.ts";
+
+export const PatchEvaluationSchema = Type.Object({
+  outcome: Type.Union([Type.Literal("accepted"), Type.Literal("rejected"), Type.Literal("blocked")]),
+  reason: Type.String(),
+  checks: Type.Array(Type.Object({
+    file: Type.String({ description: "Executable for a focused validation command, not a shell command string." }),
+    args: Type.Array(Type.String()),
+    required: Type.Boolean(),
+    regression: Type.Optional(Type.Object({
+      baselinePatch: Type.String({ description: "Test-only patch to apply to the original baseline to reproduce the bug; exclude the repair." }),
+      expectedFailure: Type.String({ description: "Specific failure text proving the intended defect, not a missing dependency or setup error." }),
+    })),
+  }), { maxItems: 6 }),
+});
+export type PatchEvaluation = Static<typeof PatchEvaluationSchema>;
+export type PatchCandidateStatus = "verified" | "rejected" | "blocked" | "no-patch";
+export interface PatchValidation {
+  status: PatchCandidateStatus;
+  baselineFingerprint: string;
+  baselineOid?: string;
+  patchHash: string;
+  checks: { file: string; args: string[]; required: boolean; stage: "candidate" | "baseline"; result: BoundedProcessResult }[];
+  evaluation?: PatchEvaluation;
+  reason: string;
+  cleanupError?: string;
+}
+export function initialPatchValidation(baseline: WorktreeBaseline, baselineOid: string | undefined, patch: string): PatchValidation {
+  return { status: patch.trim() ? "blocked" : "no-patch", baselineFingerprint: fingerprintReviewWorktreeBaseline(baseline), ...(baselineOid ? { baselineOid } : {}),
+    patchHash: createHash("sha256").update(patch).digest("hex"), checks: [], reason: patch.trim() ? "Independent evaluation has not completed." : "The implementer produced no patch; this does not establish that no change is needed." };
+}
+
+interface PatchValidationOptions {
+  cwd: string; baseline: WorktreeBaseline; expectedFingerprint: string; baselineOid: string; patch: string;
+  evaluation: PatchEvaluation; signal?: AbortSignal;
+}
+
+/** Reconstruct the exact reviewed baseline and retain evidence even if cleanup fails. */
+export async function validateCandidatePatch(options: PatchValidationOptions): Promise<PatchValidation> {
+  const validation = initialPatchValidation(options.baseline, options.baselineOid, options.patch);
+  validation.evaluation = options.evaluation;
+  if (validation.baselineFingerprint !== options.expectedFingerprint) return { ...validation, status: "rejected", reason: "Stale reviewed baseline identity." };
+  if (!options.patch.trim()) return validation;
+  const worktrees = new WorktreeRegistry(options.cwd);
+  let result = validation;
+  try {
+    result = await evaluateCandidateInWorktrees(worktrees, options, validation);
+  } catch (error) {
+    throwIfAborted(options.signal);
+    result = { ...validation, status: "blocked", reason: unknownErrorMessage(error) };
+  } finally {
+    try {
+      await worktrees.removeAll();
+    } catch (error) {
+      const cleanupError = unknownErrorMessage(error);
+      result = {
+        ...result,
+        status: result.status === "verified" ? "blocked" : result.status,
+        cleanupError,
+        reason: `${result.reason}\nCleanup failed: ${cleanupError}`,
+      };
+    }
+    throwIfAborted(options.signal);
+  }
+  return result;
+}
+
+async function evaluateCandidateInWorktrees(
+  worktrees: WorktreeRegistry, options: PatchValidationOptions, validation: PatchValidation,
+): Promise<PatchValidation> {
+  const candidate = await worktrees.add(options.signal, options.baseline);
+  if ("error" in candidate) return { ...validation, reason: candidate.error };
+  if (candidate.baselineOid !== options.baselineOid) return { ...validation, status: "rejected", reason: "Candidate was produced from a different baseline." };
+  const applied = await worktrees.applyPatch(candidate.path, options.patch, options.signal);
+  if (!applied.ok) return { ...validation, status: "rejected", reason: applied.error ?? applied.stderr };
+  const rejected = options.evaluation.outcome === "rejected" ? [options.evaluation.reason] : [];
+  const blocked = options.evaluation.outcome === "blocked" ? [options.evaluation.reason] : [];
+  if (!options.evaluation.checks.some((check) => check.required)) blocked.push("No required behavior check was selected.");
+  for (const check of options.evaluation.checks) {
+    const result = await runCheck(check, candidate.path, options.signal);
+    validation.checks.push({ ...check, stage: "candidate", result });
+    throwIfAborted(options.signal);
+    if (!result.ok) {
+      if (result.failure.kind === "exit") rejected.push(`${check.file}: ${result.failure.message}`);
+      else if (check.required) blocked.push(`${check.file}: ${result.failure.message}`);
+    }
+    if (check.regression) {
+      const original = await worktrees.add(options.signal, options.baseline);
+      if ("error" in original) { blocked.push(`Baseline worktree setup failed: ${original.error}`); continue; }
+      const testApplied = await worktrees.applyPatch(original.path, check.regression.baselinePatch, options.signal);
+      if (!testApplied.ok) { blocked.push(`Baseline regression setup failed: ${testApplied.error ?? testApplied.stderr}`); continue; }
+      const baselineResult = await runCheck(check, original.path, options.signal);
+      validation.checks.push({ ...check, stage: "baseline", result: baselineResult });
+      throwIfAborted(options.signal);
+      if (baselineResult.ok || baselineResult.failure.kind !== "exit" || !check.regression.expectedFailure.trim() ||
+        !(baselineResult.stdout + baselineResult.stderr).includes(check.regression.expectedFailure)) {
+        blocked.push(`${check.file}: baseline did not reproduce the expected failure: ${check.regression.expectedFailure}`);
+      }
+    }
+  }
+  // Tests must not silently replace the candidate under evaluation.
+  const after = await worktrees.capturePatch(candidate.path, candidate.baselineOid, options.signal);
+  if ("error" in after) blocked.push(`Candidate capture failed: ${after.error}`);
+  else if (after.patch !== options.patch) blocked.push("Validation checks changed the candidate patch.");
+  if (rejected.length > 0) return { ...validation, status: "rejected", reason: [...rejected, ...blocked].join("\n") };
+  if (blocked.length > 0) return { ...validation, status: "blocked", reason: blocked.join("\n") };
+  return { ...validation, status: "verified", reason: "Independent evaluation and all required checks passed." };
+}
+
+function runCheck(check: PatchEvaluation["checks"][number], cwd: string, signal?: AbortSignal): Promise<BoundedProcessResult> {
+  return runBoundedProcess({ file: check.file, args: check.args, cwd, signal, timeoutMs: 120_000, maxBufferBytes: 1 << 20,
+    abortError: "Validation aborted", timeoutError: "Validation timed out", maxBufferError: "Validation output exceeded its limit",
+    exitError: (stderr, code) => stderr.trim() || `Validation exited with ${code}` });
+}