pi-workflow-engine 0.12.0 → 0.13.0

package/.pi/extensions/pi-workflow-engine/src/advisory-challenge.ts

@@ -0,0 +1,75 @@
+import { Type, type Static } from "typebox";
+import { collectAdvisoryStage, type AdvisoryStageCoverage } from "./advisory-evidence.ts";
+import { DEFAULT_ADVISORY_TOOLS, DEFAULT_ADVISORY_TOOL_HINTS, type AdvisoryVerified } from "./workflow-advisory-utils.ts";
+import type { WorkflowApi } from "./types.ts";
+
+const ChallengeSchema = Type.Object({
+  outcome: Type.Union([Type.Literal("counterexample"), Type.Literal("alternative-explanation"), Type.Literal("supports-original"), Type.Literal("no-counterexample")]),
+  evidence: Type.Array(Type.String()),
+  experiment: Type.String({ description: "Smallest distinguishing experiment, with observed result if actually run." }),
+});
+const AdjudicationSchema = Type.Object({
+  outcome: Type.Union([Type.Literal("upheld"), Type.Literal("refuted"), Type.Literal("unresolved")]),
+  evidence: Type.Array(Type.String()),
+  reason: Type.String(),
+});
+export type ChallengeRecord =
+  | { status: "complete"; challenge: Static<typeof ChallengeSchema>; adjudication: Static<typeof AdjudicationSchema> }
+  | { status: "failed"; challenge?: Static<typeof ChallengeSchema> };
+export interface AdvisoryChallengeOptions {
+  maxChallenges: number;
+  shouldChallenge?: (finding: AdvisoryVerified) => boolean;
+}
+
+/** Opt in with --challenge or --challenge=N (hard bound of 10). */
+export function parseChallengeArgs(args: string): { args: string; options: AdvisoryChallengeOptions } {
+  let maxChallenges = 0;
+  const remaining = args.replace(/(?:^|\s)--challenge(?:=([^\s]*))?(?=\s|$)/g, (_match, limit: string | undefined) => {
+    if (limit !== undefined && !/^\d+$/.test(limit)) {
+      throw new Error(`Invalid --challenge value "${limit}". Use --challenge or --challenge=N with a non-negative integer; zero disables challenges.`);
+    }
+    maxChallenges = Math.min(10, limit === undefined ? 3 : Number(limit));
+    return " ";
+  });
+  return { args: remaining.trim(), options: { maxChallenges } };
+}
+
+export function needsChallenge(finding: AdvisoryVerified): boolean {
+  return finding.verdict === "PLAUSIBLE" || finding.verdict === "NOT_SUBSTANTIATED" || finding.evidence.length === 0 ||
+    /\b(security|concurren\w*|race|persist\w*|cancel\w*|retr(?:y|ies)|data loss|corrupt\w*|high impact)\b/i.test(`${finding.category} ${finding.summary} ${finding.impact}`);
+}
+
+/** A bounded recipe using existing agent/parallel calls, not a new runtime primitive. */
+export async function challengeFindings<T extends AdvisoryVerified>(
+  api: Pick<WorkflowApi, "agent" | "parallel">,
+  findings: T[],
+  context: string,
+  options: AdvisoryChallengeOptions,
+  coverage: AdvisoryStageCoverage[],
+): Promise<T[]> {
+  const limit = Number.isFinite(options.maxChallenges) ? Math.max(0, Math.min(10, Math.trunc(options.maxChallenges))) : 0;
+  if (limit === 0) return findings;
+  const selected = findings.filter((finding) => finding.verdict !== "REFUTED" && (options.shouldChallenge ?? needsChallenge)(finding)).slice(0, limit);
+  const replacements = new Map<string, T>();
+  await collectAdvisoryStage(api, "Challenge", selected.map((finding) => ({ id: finding.candidateId, run: async () => {
+    // Preserve the candidate as unresolved if either independent stage fails.
+    replacements.set(finding.candidateId, { ...finding, verdict: "NOT_SUBSTANTIATED", challenge: { status: "failed" } });
+    const challenge = await api.agent(
+      `Assume this finding is a false positive. Try to DISPROVE it. Find the strongest concrete counterexample or alternative root cause. Inspect callers, invariants, tests and control flow. For a repair, seek an input, race or error path that still fails. State the smallest experiment distinguishing explanations. Do not edit files or claim tests you did not run. No counterexample found is not proof.\n\nExact review context:\n${context}\n\nCandidate and verifier evidence:\n${JSON.stringify(finding)}`,
+      { label: `challenge:${finding.candidateId}`, phase: "Challenge", profile: "medium", tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS, schema: ChallengeSchema },
+    );
+    replacements.set(finding.candidateId, { ...finding, verdict: "NOT_SUBSTANTIATED", challenge: { status: "failed", challenge } });
+    const adjudication = await api.agent(
+      `Adjudicate the original finding, independent verifier evidence and falsification attempt below. Preserve unresolved conflict; do not force consensus. A missing counterexample alone cannot upgrade a plausible claim. Cite concrete evidence and observed test results; never invent experiments.\nContext:\n${context}\nOriginal and verifier:\n${JSON.stringify(finding)}\nChallenger:\n${JSON.stringify(challenge)}`,
+      { label: `adjudicate:${finding.candidateId}`, phase: "Challenge", profile: "medium", tools: [], schema: AdjudicationSchema },
+    );
+    replacements.set(finding.candidateId, {
+      ...finding,
+      verdict: adjudication.outcome === "refuted" ? "REFUTED" : adjudication.outcome === "unresolved" ? "NOT_SUBSTANTIATED" : finding.verdict,
+      evidence: [...finding.evidence, ...challenge.evidence, ...(challenge.experiment ? [challenge.experiment] : []), ...adjudication.evidence, adjudication.reason],
+      challenge: { status: "complete", challenge, adjudication },
+    });
+    return finding.candidateId;
+  } })), coverage);
+  return findings.map((finding) => replacements.get(finding.candidateId) ?? finding);
+}

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

@@ -0,0 +1,90 @@
+import { createHash } from "node:crypto";
+import { Type, type Static } from "typebox";
+import { AdvisorySeveritySchema, type IdentifiedAdvisoryCandidate, type AdvisoryCandidate, type AdvisoryReport } from "./advisory-schema.ts";
+import type { WorkflowApi } from "./types.ts";
+
+export interface AdvisoryStageCoverage {
+  stage: string;
+  expected: number;
+  completed: number;
+  failed: number;
+  failures: { branch: string; reason: string; candidate?: AdvisoryCandidate }[];
+}
+
+/** Settled results are required here: a missing branch is not a negative finding. */
+export async function collectAdvisoryStage<T>(
+  api: Pick<WorkflowApi, "parallel">,
+  stage: string,
+  branches: { id: string; candidate?: AdvisoryCandidate; run(): Promise<T> }[],
+  coverage: AdvisoryStageCoverage[],
+): Promise<T[]> {
+  const results = await api.parallel(branches.map((branch) => branch.run), { settled: true });
+  const failures = results.flatMap((result, index) => result.ok ? [] : [{ branch: branches[index]!.id, reason: result.error.message, ...(branches[index]!.candidate ? { candidate: branches[index]!.candidate } : {}) }]);
+  coverage.push({ stage, expected: branches.length, completed: results.length - failures.length, failed: failures.length, failures });
+  return results.flatMap((result) => result.ok ? [result.value] : []);
+}
+
+export function identifyCandidates(candidates: readonly AdvisoryCandidate[], lens: string): IdentifiedAdvisoryCandidate[] {
+  return candidates.map((candidate, index) => {
+    const candidateId = createHash("sha256").update(JSON.stringify([lens, index, candidate])).digest("hex").slice(0, 20);
+    // Identities are assigned by the workflow, never accepted from a finder.
+    return { ...candidate, candidateId, sourceCandidateIds: [candidateId] };
+  });
+}
+
+function normalizedSummary(summary: string): string {
+  return summary.toLowerCase().replace(/\s+/g, " ").trim().replace(/[.!?]+$/, "");
+}
+
+function candidateDedupKey(candidate: AdvisoryCandidate): string {
+  const location = candidate.locations[0];
+  return JSON.stringify([candidate.category, location?.file.replace(/^\.\//, "").replace(/^[ab]\//, ""),
+    location?.symbol ?? location?.line ?? null, normalizedSummary(candidate.summary)]);
+}
+
+/** Collapse only equivalent claims at the same anchor; keep every discovery ID and location. */
+export function dedupeCandidates<T extends IdentifiedAdvisoryCandidate>(candidates: readonly T[]): T[] {
+  const seen = new Map<string, T>();
+  for (const candidate of candidates) {
+    const key = candidateDedupKey(candidate);
+    const previous = seen.get(key);
+    if (!previous) seen.set(key, { ...candidate });
+    else {
+      previous.sourceCandidateIds = [...new Set([...previous.sourceCandidateIds, ...candidate.sourceCandidateIds])];
+      previous.locations = uniqueLocations([...previous.locations, ...candidate.locations]);
+      previous.impact = [...new Set([previous.impact, candidate.impact])].join("\n");
+      previous.discoveryEvidence = [...new Set([...(previous.discoveryEvidence ?? []), ...(candidate.discoveryEvidence ?? [])])];
+    }
+  }
+  return [...seen.values()];
+}
+
+export function uniqueLocations(locations: AdvisoryCandidate["locations"]): AdvisoryCandidate["locations"] {
+  return [...new Map(locations.map((location) => [JSON.stringify(location), location])).values()];
+}
+
+// Synthesis selects evidence records. It has no fields with which to replace their evidence.
+export const AdvisorySynthesisSchema = Type.Object({
+  summary: Type.String(),
+  findings: Type.Array(Type.Object({
+    sourceCandidateIds: Type.Array(Type.String(), { minItems: 1 }),
+    severity: AdvisorySeveritySchema,
+    recommendation: Type.String(),
+  })),
+  nextSteps: Type.Array(Type.String()),
+});
+export type AdvisorySynthesis = Static<typeof AdvisorySynthesisSchema>;
+export const SYNTHESIS_ID_INSTRUCTIONS = "Select or merge findings only by sourceCandidateIds shown below. Return severity and an advisory recommendation per selection. Never select an ID absent from these verified records. ";
+
+export function withAdvisoryCoverage<T extends AdvisoryReport>(report: T, coverage: AdvisoryStageCoverage[]) {
+  const incomplete = coverage.some((stage) => stage.failed > 0);
+  const gaps = coverage.flatMap((stage) => stage.failures.map((failure) => `${stage.stage}/${failure.branch}: ${failure.reason}`));
+  return {
+    ...report,
+    status: incomplete ? "incomplete" as const : "complete" as const,
+    summary: incomplete ? `Incomplete review: ${gaps.length} branch(es) failed. ${report.findings.length} finding(s) available; no clean conclusion is possible.` : report.summary,
+    nextSteps: incomplete ? ["Inspect failed branches and rerun missing work.", ...(report.findings.length > 0 ? report.nextSteps : [])] : report.nextSteps,
+    coverage,
+    gaps,
+  };
+}

package/.pi/extensions/pi-workflow-engine/src/advisory-schema.ts

@@ -9,7 +9,7 @@ export const AdvisoryConfidenceSchema = Type.Union([Type.Literal("low"), Type.Li
   description: "Confidence that the finding is actionable.",
 });
 
-export const AdvisoryVerifierVerdictSchema = Type.Union([Type.Literal("CONFIRMED"), Type.Literal("PLAUSIBLE"), Type.Literal("REFUTED")], {
+export const AdvisoryVerifierVerdictSchema = Type.Union([Type.Literal("CONFIRMED"), Type.Literal("PLAUSIBLE"), Type.Literal("REFUTED"), Type.Literal("NOT_SUBSTANTIATED")], {
   description: "Verifier judgment for a candidate finding.",
 });
 
@@ -20,6 +20,8 @@ export const AdvisoryLocationSchema = Type.Object({
 });
 
 export const AdvisoryCandidateSchema = Type.Object({
+  discoveryEvidence: Type.Optional(Type.Array(Type.String())),
+  reviewAnchor: Type.Optional(AdvisoryLocationSchema),
   summary: Type.String({ description: "One-line candidate finding or hypothesis." }),
   category: Type.String({ description: "Workflow-specific category such as bug, duplication, root-cause, or io." }),
   locations: Type.Array(AdvisoryLocationSchema, { description: "Relevant code or configuration locations." }),
@@ -38,6 +40,9 @@ export const AdvisoryVerdictSchema = Type.Object({
 });
 
 export const AdvisoryFindingSchema = Type.Object({
+  verdict: Type.Optional(AdvisoryVerifierVerdictSchema),
+  sourceCandidateIds: Type.Optional(Type.Array(Type.String())),
+  reviewAnchor: Type.Optional(AdvisoryLocationSchema),
   summary: Type.String({ description: "One-line final finding." }),
   category: Type.String({ description: "Workflow-specific category for grouping and display." }),
   severity: AdvisorySeveritySchema,
@@ -49,6 +54,12 @@ export const AdvisoryFindingSchema = Type.Object({
 });
 
 export const AdvisoryReportSchema = Type.Object({
+  status: Type.Optional(Type.Union([Type.Literal("complete"), Type.Literal("incomplete")])),
+  gaps: Type.Optional(Type.Array(Type.String())),
+  coverage: Type.Optional(Type.Array(Type.Object({
+    stage: Type.String(), expected: Type.Number(), completed: Type.Number(), failed: Type.Number(),
+    failures: Type.Array(Type.Object({ branch: Type.String(), reason: Type.String(), candidate: Type.Optional(AdvisoryCandidateSchema) })),
+  }))),
   summary: Type.String({ description: "Short overall advisory summary." }),
   findings: Type.Array(AdvisoryFindingSchema, { description: "Verified and ranked advisory findings." }),
   nextSteps: Type.Array(Type.String({ description: "Concrete follow-up commands, inspections, or decisions." })),
@@ -61,6 +72,7 @@ export const AdvisoryReportWithStatsSchema = Type.Object({
 
 export type AdvisoryLocation = Static<typeof AdvisoryLocationSchema>;
 export type AdvisoryCandidate = Static<typeof AdvisoryCandidateSchema>;
+export type IdentifiedAdvisoryCandidate = AdvisoryCandidate & { candidateId: string; sourceCandidateIds: string[] };
 export type AdvisoryVerdict = Static<typeof AdvisoryVerdictSchema>;
 export type AdvisoryFinding = Static<typeof AdvisoryFindingSchema>;
 export type AdvisoryReport = Static<typeof AdvisoryReportSchema>;

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

@@ -21,7 +21,7 @@ export type AgentWorkspace = SharedAgentWorkspace | IsolatedAgentWorkspace;
 
 export interface AgentWorkspaceContext {
   readonly cwd: string;
-  readonly worktrees: Pick<WorktreeRegistry, "probe" | "add" | "capturePatch" | "remove">;
+  readonly worktrees: Pick<WorktreeRegistry, "probe" | "add" | "capturePatch" | "applyPatch" | "remove">;
   readonly signal: AbortSignal | undefined;
   readonly progress: Pick<AgentProgress, "log">;
 }
@@ -31,6 +31,7 @@ export async function createAgentWorkspace(
   opts: AgentExecutionOptions,
   label: string,
 ): Promise<AgentWorkspace> {
+  if (opts.candidatePatch && opts.isolation !== "worktree") throw new Error("Candidate evaluation requires worktree isolation");
   if (opts.isolation !== "worktree") {
     return {
       kind: "shared",
@@ -53,6 +54,19 @@ export async function createAgentWorkspace(
   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;
+  if (opts.candidatePatch) {
+    try {
+      if (opts.candidatePatch.baselineOid !== added.baselineOid) throw new Error("Candidate baseline differs from evaluator baseline");
+      if (opts.candidatePatch.patch.trim()) {
+        const applied = await rc.worktrees.applyPatch(worktreePath, opts.candidatePatch.patch, rc.signal);
+        if (!applied.ok) throw new Error(`Candidate patch could not be applied: ${applied.error ?? applied.stderr}`);
+      }
+    } catch (error) {
+      const removed = await rc.worktrees.remove(worktreePath);
+      if (!removed.ok) rc.progress.log(`${label}: evaluator setup cleanup failed: ${removed.error ?? removed.stderr}`);
+      throw error;
+    }
+  }
   rc.progress.log(`${label}: using isolated worktree ${worktreePath}`);
 
   return {
@@ -62,7 +76,7 @@ export async function createAgentWorkspace(
     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 };
+      return { result, patch: patch.patch, changed: patch.changed, baselineOid: added.baselineOid };
     },
     async dispose() {
       const removed = await rc.worktrees.remove(worktreePath);

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

@@ -14,22 +14,28 @@ export class Semaphore {
   private active = 0;
   private readonly waiters: Array<() => void> = [];
 
-  constructor(private readonly max: number) {}
+  constructor(private readonly max: number) {
+    if (!Number.isInteger(max) || max < 1) throw new RangeError("Semaphore capacity must be a positive integer");
+  }
 
   async run<T>(fn: () => Promise<T>, options: { onQueueWaitMs?: (durationMs: number) => void; signal?: AbortSignal } = {}): Promise<T> {
     throwIfAborted(options.signal);
     const queuedAt = performance.now();
     if (this.active >= this.max) {
       await this.waitForSlot(options.signal);
+    } else {
+      this.active++;
     }
-    options.onQueueWaitMs?.(performance.now() - queuedAt);
-    throwIfAborted(options.signal);
-    this.active++;
     try {
+      options.onQueueWaitMs?.(performance.now() - queuedAt);
+      throwIfAborted(options.signal);
       return await fn();
     } finally {
-      this.active--;
-      this.waiters.shift()?.();
+      // Transfer ownership directly. A selected waiter owns this reservation
+      // even before its continuation runs, including if it is then cancelled.
+      const next = this.waiters.shift();
+      if (next) next();
+      else this.active--;
     }
   }
 

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

@@ -115,6 +115,7 @@ function captureAgentCallHash(
         skills: opts.skills,
         schema: opts.schema,
         isolation: opts.isolation,
+        candidatePatch: opts.candidatePatch ? { baselineOid: opts.candidatePatch.baselineOid, hash: createHash("sha256").update(opts.candidatePatch.patch).digest("hex") } : undefined,
         worktreeBaseline: worktreeBaseline
           ? {
               ref: worktreeBaseline.ref,

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

@@ -1,4 +1,5 @@
-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";
@@ -575,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 };
@@ -583,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)}` };

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

@@ -1,6 +1,3 @@
-import type { AdvisoryCandidate } from "../advisory-schema.ts";
-import { normalizePath, primaryLocation } from "../workflow-advisory-utils.ts";
-
 const DIFF_EMBED_CAP = 60_000;
 
 export function buildCodeReviewScopeBlock(input: {
@@ -25,25 +22,3 @@ export function buildCodeReviewScopeBlock(input: {
     (input.target ? `\n## User instructions (verbatim)\n${input.target}\n` : "")
   );
 }
-
-export function dedupeCodeReviewCandidates<Context>(
-  groups: readonly { readonly angle: Context; readonly candidates: readonly AdvisoryCandidate[] }[],
-): Array<{ readonly angle: Context; readonly candidate: AdvisoryCandidate }> {
-  const seen = new Set<string>();
-  return groups.flatMap(({ angle, candidates }) =>
-    candidates
-      .filter((candidate) => {
-        const key = codeReviewDedupKey(candidate);
-        if (seen.has(key)) return false;
-        seen.add(key);
-        return true;
-      })
-      .map((candidate) => ({ angle, candidate })),
-  );
-}
-
-function codeReviewDedupKey(candidate: AdvisoryCandidate): string {
-  const location = primaryLocation(candidate);
-  const lineKey = location.line != null ? Math.round(location.line / 5) * 5 : candidate.summary.slice(0, 40).toLowerCase();
-  return `${normalizePath(location.file)}:${lineKey}`;
-}

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

package/.pi/extensions/pi-workflow-engine/src/review/review-fix-workflow.ts

@@ -1,5 +1,8 @@
+import { initialPatchValidation, PatchEvaluationSchema, validateCandidatePatch, type PatchValidation } from "./patch-validation.ts";
+import { isFatalWorkflowError } from "../cancellation.ts";
+import { unknownErrorMessage } from "../unknown-error.ts";
 import type { ParallelSettledError } from "../concurrency.ts";
-import type { LoadedWorkflow, WorkflowApi, WorkflowModule } from "../types.ts";
+import type { IsolatedAgentResult, LoadedWorkflow, WorkflowApi, WorkflowModule } from "../types.ts";
 import type { WorktreeBaseline } from "../worktree.ts";
 import { loadWorkflow } from "../workflow-module.ts";
 import { serializeReviewIssue, type ReviewIssue } from "./review-issues.ts";
@@ -14,6 +17,7 @@ export interface ReviewFixPreview {
   readonly result: string;
   readonly patch: string;
   readonly changed: boolean;
+  readonly validation: PatchValidation;
 }
 
 export interface ReviewFixFailure {
@@ -28,7 +32,7 @@ export interface ReviewFixWorkflowResult {
   readonly fixes: readonly ReviewFixOutcome[];
 }
 
-export type ReviewFixWorkflowApi = Pick<WorkflowApi, "agent" | "parallel" | "phase">;
+export type ReviewFixWorkflowApi = Pick<WorkflowApi, "agent" | "parallel" | "phase" | "cwd" | "signal">;
 
 /** Build an ephemeral workflow that generates one isolated patch preview per finding. */
 export function createReviewFixWorkflow(
@@ -40,9 +44,9 @@ export function createReviewFixWorkflow(
     meta: {
       name: "code-review-fix-previews",
       description: "Generate isolated patch previews for selected code-review findings.",
-      phases: [{ title: REVIEW_FIX_PHASE }],
+      phases: [{ title: REVIEW_FIX_PHASE }, { title: "Validate patch previews" }],
     },
-    default: (api) => runReviewFixWorkflow(api, issues, context),
+    default: (api) => runReviewFixWorkflow(api, issues, context, baseline),
   };
   return loadWorkflow(
     module,
@@ -76,6 +80,7 @@ export async function runReviewFixWorkflow(
   api: ReviewFixWorkflowApi,
   issues: readonly ReviewIssue[],
   context: ReviewContext | undefined,
+  baseline: WorktreeBaseline,
 ): Promise<ReviewFixWorkflowResult> {
   api.phase(REVIEW_FIX_PHASE);
   const settled = await api.parallel(
@@ -84,16 +89,18 @@ export async function runReviewFixWorkflow(
         isolation: "worktree",
         label: `fix:${issue.id}`,
         phase: REVIEW_FIX_PHASE,
-        thinkingLevel: "medium",
+        profile: "medium",
         cacheKey: `review-fix:${issue.id}`,
         tools: [...REVIEW_FIX_TOOLS],
         toolHints: ["search"],
       });
+      const validation = await evaluateReviewFix(api, { issue, context, baseline, isolated });
       return {
         findingId: issue.id,
         result: isolated.result,
         patch: isolated.patch,
         changed: isolated.changed,
+        validation,
       };
     }),
     { settled: true },
@@ -103,11 +110,11 @@ export async function runReviewFixWorkflow(
     entry.ok ? entry.value : { findingId: issues[index]!.id, error: entry.error },
   );
   const successful = fixes.filter(isReviewFixPreview);
-  const changed = successful.filter((fix) => fix.changed).length;
+  const count = (status: PatchValidation["status"]) => successful.filter((fix) => fix.validation.status === status).length;
   const failed = fixes.length - successful.length;
 
   return {
-    summary: `Generated ${changed} patch preview(s); ${successful.length - changed} finding(s) needed no changes; ${failed} attempt(s) failed.`,
+    summary: `${count("verified")} verified candidate(s); ${count("rejected")} rejected; ${count("blocked")} blocked; ${count("no-patch")} no-patch; ${failed} attempt(s) failed.`,
     fixes,
   };
 }
@@ -115,3 +122,32 @@ export async function runReviewFixWorkflow(
 function isReviewFixPreview(outcome: ReviewFixOutcome): outcome is ReviewFixPreview {
   return "patch" in outcome;
 }
+
+async function evaluateReviewFix(api: ReviewFixWorkflowApi, input: {
+  issue: ReviewIssue; context: ReviewContext | undefined; baseline: WorktreeBaseline; isolated: IsolatedAgentResult<string>;
+}): Promise<PatchValidation> {
+  const { issue, context, baseline, isolated } = input;
+  const validation = initialPatchValidation(baseline, isolated.baselineOid, isolated.patch);
+  if (!isolated.patch.trim()) return validation;
+  if (!isolated.baselineOid) return { ...validation, reason: "Candidate has no recorded baseline identity." };
+  if (!context?.snapshot) return { ...validation, reason: "Reviewed snapshot identity is unavailable." };
+  if (validation.baselineFingerprint !== context.snapshot.baselineFingerprint) {
+    return { ...validation, status: "rejected", reason: "Stale reviewed baseline identity." };
+  }
+  try {
+    const evaluated = await api.agent(
+      `Independently evaluate a candidate repair. Your fresh worktree contains the exact reviewed baseline plus the captured patch. The implementer's report is not validation evidence. Inspect the finding, callers and tests. Reject incorrect repairs; return blocked if required validation is unavailable. Select at most six focused deterministic checks with executable and argument arrays. Require at least one meaningful behavior check. If a regression test is applicable, supply a test-only baselinePatch and specific expectedFailure so the engine can prove it fails before the repair and passes after. Do not edit, install dependencies, commit or change branches. The engine will execute checks independently.\nFinding: ${JSON.stringify(serializeReviewIssue(issue))}\nBaseline: ${isolated.baselineOid}\nPatch SHA-256: ${validation.patchHash}\nPatch:\n${isolated.patch}`,
+      { isolation: "worktree", candidatePatch: { baselineOid: isolated.baselineOid, patch: isolated.patch },
+        label: `evaluate:${issue.id}`, phase: "Validate patch previews", profile: "medium", resume: "off",
+        tools: ["read", "bash", "grep", "find", "ls"], toolHints: ["search"], schema: PatchEvaluationSchema },
+    );
+    if (evaluated.baselineOid !== isolated.baselineOid || evaluated.patch !== isolated.patch) {
+      return { ...validation, status: "rejected", reason: "Evaluator changed the candidate or used a different baseline.", evaluation: evaluated.result };
+    }
+    return await validateCandidatePatch({ cwd: api.cwd, baseline, expectedFingerprint: context.snapshot.baselineFingerprint,
+        baselineOid: isolated.baselineOid, patch: isolated.patch, evaluation: evaluated.result, signal: api.signal });
+  } catch (error) {
+    if (isFatalWorkflowError(error, api.signal)) throw error;
+    return { ...validation, status: "blocked", reason: unknownErrorMessage(error) };
+  }
+}