pi-workflow-engine 0.13.0 → 1.0.0

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

@@ -1,26 +1,18 @@
 import { randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
+import { existsSync } from "node:fs";
 import { cp, mkdir, mkdtemp, rm } from "node:fs/promises";
-import { isAbsolute, join, relative, resolve, sep } from "node:path";
-import { runBoundedProcess } from "./process-runner.ts";
+import { join, resolve, sep } from "node:path";
+import { isGitObjectId, parseGitTopLevel, runGit, type GitCommandOptions } from "./git.ts";
+import { GIT_DIFF_MACHINE_FORMAT } from "./review-diff-target.ts";
+import { FINGERPRINT_EXCLUDED_RELATIVE_PATHS, isExcludedDeclaredInput, portableRelativePath } from "./tree-fingerprint.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
 
-export interface WorktreeGitCommandOptions {
-  readonly cwd: string;
-  readonly args: readonly string[];
-  readonly env?: NodeJS.ProcessEnv;
-  readonly stdin?: string;
-  readonly signal?: AbortSignal;
-  readonly timeoutMs: number;
-  readonly maxBufferBytes?: number;
-}
+export type WorktreeGitCommandOptions = Omit<GitCommandOptions, "file" | "label">;
 
-export interface WorktreeGitCommandResult {
-  readonly ok: boolean;
-  readonly stdout: string;
-  readonly stderr: string;
-  readonly error?: string;
-}
+export type WorktreeGitCommandResult =
+  | { readonly ok: true; readonly stdout: string; readonly stderr: string }
+  | { readonly ok: false; readonly stdout: string; readonly stderr: string; readonly error: string };
 
 export interface WorktreeGitRunner {
   runGit(options: WorktreeGitCommandOptions): Promise<WorktreeGitCommandResult>;
@@ -46,24 +38,18 @@ export interface WorktreeAddFailure {
   readonly cleanup?: WorktreeGitCommandResult;
 }
 
-export interface GitWorktreeProbe {
-  readonly ok: boolean;
-  readonly inside: boolean;
-  readonly error?: string;
-}
+export type GitWorktreeProbe = { readonly ok: true; readonly inside: boolean } | { readonly ok: false; readonly error: string };
 
-export interface WorktreeRemovalOutcome extends WorktreeGitCommandResult {
-  readonly path: string;
-}
+export type WorktreeRemovalOutcome = WorktreeGitCommandResult & { readonly path: string };
 
 export class WorktreeCleanupError extends AggregateError {
   readonly outcomes: readonly WorktreeRemovalOutcome[];
 
   constructor(outcomes: readonly WorktreeRemovalOutcome[]) {
     const failures = outcomes.filter((outcome) => !outcome.ok);
-    const details = failures.map((failure) => `${failure.path} (${worktreeRemovalError(failure)})`);
+    const details = failures.map((failure) => `${failure.path} (${failure.error})`);
     super(
-      failures.map((failure) => new Error(`Failed to remove isolated worktree ${failure.path}: ${worktreeRemovalError(failure)}`)),
+      failures.map((failure) => new Error(`Failed to remove isolated worktree ${failure.path}: ${failure.error}`)),
       `Failed to remove ${failures.length} isolated worktree${failures.length === 1 ? "" : "s"}: ${details.join(", ")}`,
     );
     this.name = "WorktreeCleanupError";
@@ -77,7 +63,6 @@ export interface WorktreePatch {
 }
 
 export interface WorktreeRegistryOptions {
-  readonly repoCwd: string;
   readonly runner?: WorktreeGitRunner;
   readonly patchCapture?: WorktreePatchCapture;
   readonly timeoutMs?: number;
@@ -111,7 +96,7 @@ export class WorktreeRegistry {
   private readonly patchCapture: WorktreePatchCapture;
   private readonly timeoutMs: number;
 
-  constructor(private readonly repoCwd: string, options: Omit<WorktreeRegistryOptions, "repoCwd"> = {}) {
+  constructor(private readonly repoCwd: string, options: WorktreeRegistryOptions = {}) {
     this.runner = options.runner ?? spawnGitRunner;
     this.patchCapture = options.patchCapture ?? captureWorktreePatch;
     this.timeoutMs = options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS;
@@ -131,6 +116,8 @@ export class WorktreeRegistry {
 
   async add(signal?: AbortSignal, baseline?: WorktreeBaseline): Promise<WorktreeRef | WorktreeAddFailure> {
     const added = await addWorktree({ repoCwd: this.repoCwd, runner: this.runner, signal, timeoutMs: this.timeoutMs, baseline });
+    // A rejected `git worktree add` creates nothing; tracking it would make cleanup fail on a path git never knew.
+    if ("error" in added && !existsSync(added.path)) return added;
     this.register(added.path);
     if (added.snapshot === true) this.snapshots.add(added.path);
     if ("error" in added) {
@@ -198,12 +185,7 @@ export class WorktreeRegistry {
       runner: this.runner,
       timeoutMs: this.timeoutMs,
       snapshot: this.snapshots.has(path),
-    }).catch((error: unknown) => ({
-      ok: false,
-      stdout: "",
-      stderr: "",
-      error: unknownErrorMessage(error),
-    }));
+    }).catch(toGitFailure);
     if (result.ok) {
       this.paths.delete(path);
       this.snapshots.delete(path);
@@ -230,8 +212,8 @@ export async function isGitWorktree(options: {
       signal: options.signal,
       timeoutMs: options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS,
     })
-    .catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: unknownErrorMessage(error) }));
-  if (!result.ok) return { ok: false, inside: false, error: result.error ?? (result.stderr.trim() || "git worktree probe failed") };
+    .catch(toGitFailure);
+  if (!result.ok) return { ok: false, error: result.error };
   return { ok: true, inside: result.stdout.trim() === "true" };
 }
 
@@ -254,7 +236,7 @@ export async function addWorktree(options: {
       signal: options.signal,
       timeoutMs,
     })
-    .catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: unknownErrorMessage(error) }));
+    .catch(toGitFailure);
   if (result.ok) {
     const patch = options.baseline?.patch;
     if (patch !== undefined && patch.trim().length > 0) {
@@ -264,22 +246,20 @@ export async function addWorktree(options: {
         runner,
         signal: options.signal,
         timeoutMs,
-      }).catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: unknownErrorMessage(error) }));
-      if (!prepared.ok) return { path, error: prepared.error ?? (prepared.stderr.trim() || "failed to prepare worktree baseline") };
+      }).catch(toGitFailure);
+      if (!prepared.ok) return { path, error: prepared.error };
     }
     return await finalizeWorktreeRef({ path, runner, signal: options.signal, timeoutMs });
   }
 
-  const message = result.error ?? (result.stderr.trim() || "git worktree add failed");
-  if (!isInvalidHeadError(message)) return { path, error: message };
+  if (!isInvalidHeadError(result.error)) return { path, error: result.error };
 
   return await addUnbornRepositoryWorktree({
     repoCwd: options.repoCwd,
     path,
-    addError: message,
+    addError: result.error,
     runner,
     signal: options.signal,
-    snapshotTimeoutMs: options.timeoutMs,
     timeoutMs,
   });
 }
@@ -290,13 +270,12 @@ async function addUnbornRepositoryWorktree(options: {
   readonly addError: string;
   readonly runner: WorktreeGitRunner;
   readonly signal?: AbortSignal;
-  readonly snapshotTimeoutMs?: number;
   readonly timeoutMs: number;
 }): Promise<WorktreeRef | WorktreeAddFailure> {
   const snapshotError = await createUnbornRepoSnapshot({
     repoCwd: options.repoCwd,
     path: options.path,
-    timeoutMs: options.snapshotTimeoutMs,
+    timeoutMs: options.timeoutMs,
     signal: options.signal,
   })
     .then(() => undefined)
@@ -331,12 +310,12 @@ async function finalizeWorktreeRef(options: {
       signal: options.signal,
       timeoutMs: options.timeoutMs,
     })
-    .catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: unknownErrorMessage(error) }));
+    .catch(toGitFailure);
   if (!resolved.ok) {
     return {
       path: options.path,
       snapshot: options.snapshot,
-      error: resolved.error ?? (resolved.stderr.trim() || "failed to resolve isolated worktree baseline"),
+      error: resolved.error,
     };
   }
   const baselineOid = resolved.stdout.trim();
@@ -410,19 +389,19 @@ export async function captureWorktreePatch(options: {
       signal: options.signal,
       timeoutMs,
     })
-    .catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: unknownErrorMessage(error) }));
-  if (!intentToAdd.ok) return { error: intentToAdd.error ?? (intentToAdd.stderr.trim() || "git add -N failed before patch capture") };
+    .catch(toGitFailure);
+  if (!intentToAdd.ok) return { error: intentToAdd.error };
 
   const diff = await runner
     .runGit({
       cwd: options.worktreePath,
-      args: ["diff", "--binary", "--full-index", "--no-ext-diff", "--no-color", options.baselineOid, "--"],
+      args: ["diff", "--binary", "--full-index", "--no-ext-diff", ...GIT_DIFF_MACHINE_FORMAT, options.baselineOid, "--"],
       signal: options.signal,
       timeoutMs,
       maxBufferBytes: WORKTREE_DIFF_MAX_BYTES,
     })
-    .catch((error: unknown) => ({ ok: false, stdout: "", stderr: "", error: unknownErrorMessage(error) }));
-  if (!diff.ok) return { error: diff.error ?? (diff.stderr.trim() || "worktree diff capture failed") };
+    .catch(toGitFailure);
+  if (!diff.ok) return { error: diff.error };
   return { patch: diff.stdout, changed: diff.stdout.trim().length > 0 };
 }
 
@@ -435,7 +414,7 @@ export async function validateWorktreePatch(options: {
 }): Promise<WorktreeGitCommandResult> {
   const hasPatch = options.candidate.patch.trim().length > 0;
   if (options.candidate.changed !== hasPatch) {
-    return invalidPatchResult("cached worktree patch changed flag does not match patch content");
+    return gitFailure("cached worktree patch changed flag does not match patch content");
   }
   if (!hasPatch) return { ok: true, stdout: "", stderr: "" };
 
@@ -448,29 +427,31 @@ export async function validateWorktreePatch(options: {
       signal: options.signal,
       timeoutMs,
     })
-    .catch((error: unknown) => invalidPatchResult(unknownErrorMessage(error)));
+    .catch(toGitFailure);
 }
 
-function invalidPatchResult(error: string): WorktreeGitCommandResult {
+function gitFailure(error: string): WorktreeGitCommandResult {
   return { ok: false, stdout: "", stderr: "", error };
 }
 
+function toGitFailure(error: unknown): WorktreeGitCommandResult {
+  return gitFailure(unknownErrorMessage(error));
+}
+
 async function createUnbornRepoSnapshot(options: {
   readonly repoCwd: string;
   readonly path: string;
   readonly signal?: AbortSignal;
-  readonly timeoutMs?: number;
+  readonly timeoutMs: number;
 }): Promise<void> {
-  const timeoutMs = options.timeoutMs ?? DEFAULT_WORKTREE_TIMEOUT_MS;
+  const { timeoutMs } = options;
   const rootProbe = await runGitCommand({
     cwd: options.repoCwd,
     args: ["rev-parse", "--show-toplevel"],
     signal: options.signal,
     timeoutMs,
   });
-  if (!rootProbe.ok) {
-    throw new Error(rootProbe.error ?? (rootProbe.stderr.trim() || "failed to resolve unborn repository root"));
-  }
+  if (!rootProbe.ok) throw new Error(rootProbe.error);
   const sourceRoot = parseGitTopLevel(rootProbe.stdout, options.repoCwd);
   if (!sourceRoot) throw new Error("unborn repository root probe returned an invalid path");
 
@@ -480,10 +461,12 @@ async function createUnbornRepoSnapshot(options: {
   await cp(sourceRoot, options.path, {
     recursive: true,
     force: true,
+    // Keep link targets as stored, like a git checkout; resolved targets would point into the source repo.
+    verbatimSymlinks: true,
     filter: (source) => {
       const resolvedSource = resolve(source);
       if (resolvedSource === targetRoot || resolvedSource.startsWith(`${targetRoot}${sep}`)) return false;
-      return !isExcludedSnapshotPath(sourceRoot, resolvedSource);
+      return !isExcludedDeclaredInput(portableRelativePath(sourceRoot, resolvedSource), FINGERPRINT_EXCLUDED_RELATIVE_PATHS);
     },
   });
   await requireGitCommand({ cwd: options.path, args: ["init"], signal: options.signal, timeoutMs });
@@ -520,60 +503,15 @@ function syntheticCommitArgs(hooksPath: string, message: string): readonly strin
 
 async function requireGitCommand(options: WorktreeGitCommandOptions): Promise<void> {
   const result = await runGitCommand(options);
-  if (!result.ok) throw new Error(result.error ?? (result.stderr.trim() || "git command failed"));
-}
-
-function parseGitTopLevel(output: string, cwd: string): string | undefined {
-  const withoutLf = output.endsWith("\n") ? output.slice(0, -1) : output;
-  const value = withoutLf.endsWith("\r") ? withoutLf.slice(0, -1) : withoutLf;
-  if (value.length === 0 || value.includes("\n") || value.includes("\0")) return undefined;
-  const root = resolve(cwd, value);
-  const cwdFromRoot = relative(root, resolve(cwd));
-  return isAbsolute(cwdFromRoot) || cwdFromRoot === ".." || cwdFromRoot.startsWith(`..${sep}`) ? undefined : root;
-}
-
-function isExcludedSnapshotPath(sourceRoot: string, source: string): boolean {
-  const path = relative(sourceRoot, source);
-  if (path.length === 0) return false;
-  const segments = path.split(sep);
-  if (segments.includes(".git")) return true;
-  return segments.some((segment, index) => segment === ".pi" && segments[index + 1] === ".workflow-runs");
+  if (!result.ok) throw new Error(result.error);
 }
 
 function isInvalidHeadError(message: string): boolean {
   return /invalid reference:\s*HEAD/i.test(message) || /ambiguous argument ['"]?HEAD/i.test(message) || /unknown revision or path.*HEAD/i.test(message);
 }
 
-function isGitObjectId(value: string): boolean {
-  return /^[0-9a-f]{40,64}$/i.test(value);
-}
-
-export const spawnGitRunner: WorktreeGitRunner = {
-  async runGit(options) {
-    return await runGitCommand(options);
-  },
-};
+export const spawnGitRunner: WorktreeGitRunner = { runGit: runGitCommand };
 
 async function runGitCommand(options: WorktreeGitCommandOptions): Promise<WorktreeGitCommandResult> {
-  const env = { ...process.env, ...options.env };
-  delete env.GIT_EXTERNAL_DIFF;
-  delete env.GIT_DIFF_OPTS;
-  return await runBoundedProcess({
-    file: "git",
-    args: options.args,
-    cwd: options.cwd,
-    env,
-    stdin: options.stdin,
-    signal: options.signal,
-    timeoutMs: options.timeoutMs,
-    maxBufferBytes: options.maxBufferBytes,
-    abortError: "git worktree command aborted",
-    timeoutError: `git worktree command timed out after ${options.timeoutMs}ms`,
-    maxBufferError: options.maxBufferBytes === undefined ? undefined : `git worktree command exceeded ${options.maxBufferBytes} bytes`,
-    exitError: (stderr, code, signal) => stderr.trim() || `git exited with code ${code ?? `signal ${signal ?? "unknown"}`}`,
-  });
-}
-
-function worktreeRemovalError(outcome: WorktreeRemovalOutcome): string {
-  return outcome.error ?? (outcome.stderr.trim() || "unknown error");
+  return await runGit({ ...options, label: "git worktree command" });
 }

package/.pi/extensions/pi-workflow-engine/workflows/code-review.ts

@@ -3,22 +3,22 @@ import { Type } from "typebox";
 import {
   type AdvisoryVerified,
   type AdvisoryLens,
-  synthesizeAdvisoryReport,
+  concludeLensReview,
+  emptyAdvisoryReport,
   finishAdvisoryReport,
   formatEvidence,
   formatLocation,
-  normalizePath,
-  publishVerifiedKeptProgress,
   runLensVerificationPipeline,
+  EMPTY_LENS_REVIEW_STATS,
   verdictConfidence,
   DEFAULT_ADVISORY_TOOL_HINTS,
   DEFAULT_ADVISORY_TOOLS,
 } from "../src/workflow-advisory-utils.ts";
 import { formatReviewDiffTarget, parseAllowedDiffCommand } from "../src/review-diff-target.ts";
-import { buildCodeReviewScopeBlock } from "../src/review/code-review-orchestration.ts";
+import { changedLines, diffAnchor } from "../src/review/review-diff-lines.ts";
 import type { ReviewContext } from "../src/review/review-report.ts";
-import { captureReviewMaterial, type ReviewMaterialCaptureResult } from "../src/review/review-snapshot.ts";
-import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../src/types.ts";
+import { captureReviewMaterial } from "../src/review/review-snapshot.ts";
+import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
 
 export const meta: WorkflowMeta = {
   name: "code-review",
@@ -45,60 +45,39 @@ const ANGLES: AdvisoryLens[] = [
 
 const PER_ANGLE = 6;
 
-/** Parse a unified diff into the set of added/changed new-file line numbers per file. */
-export function changedLines(diff: string): Map<string, Set<number>> {
-  const byFile = new Map<string, Set<number>>();
-  let file: string | null = null;
-  let newLine = 0;
-  for (const raw of diff.split("\n")) {
-    if (raw.startsWith("+++ ")) {
-      const path = raw.slice(4).trim();
-      file = path === "/dev/null" ? null : normalizePath(path);
-      if (file && !byFile.has(file)) byFile.set(file, new Set());
-    } else if (raw.startsWith("@@")) {
-      const match = /\+(\d+)/.exec(raw);
-      newLine = match ? Number(match[1]) : 0;
-    } else if (file === null || raw.startsWith("---") || raw.startsWith("\\")) {
-      // file header, deletion, or "No newline" marker — record nothing
-    } else if (raw.startsWith("+")) {
-      byFile.get(file)!.add(newLine++);
-    } else if (!raw.startsWith("-")) {
-      newLine++; // context line advances the new-file counter; deletions do not
-    }
-  }
-  return byFile;
-}
-
-/** Is a finding inside the diff? File-level findings count if the file changed; ±1 line of fuzz. */
-export function inDiff(changed: Map<string, Set<number>>, file: string, line?: number): boolean {
-  const set = changed.get(normalizePath(file));
-  if (!set) return false;
-  if (line == null) return true;
-  return set.has(line) || set.has(line - 1) || set.has(line + 1);
+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` : "")
+  );
 }
 
 export interface CodeReviewDependencies {
-  readonly captureReviewMaterial?: (
-    target: Parameters<typeof captureReviewMaterial>[0],
-    cwd: string,
-    signal?: AbortSignal,
-  ) => Promise<ReviewMaterialCaptureResult>;
+  readonly captureReviewMaterial?: typeof captureReviewMaterial;
 }
 
 export default async function run(api: WorkflowApi, dependencies: CodeReviewDependencies = {}): Promise<unknown> {
   const { agent, phase, log, progress, args, cwd, signal } = api;
   const challengeConfig = parseChallengeArgs(args);
-  const target = challengeConfig.args.trim();
-  let fileCount = 0;
-  let rawCandidateCount = 0;
-  let droppedCandidateCount = 0;
-  const makeStats = (verified: number, kept: number): WorkflowRunStats => ({
-    files: fileCount,
-    candidates: rawCandidateCount,
-    verified,
-    kept,
-    dropped: droppedCandidateCount,
-  });
+  const target = challengeConfig.args;
 
   // ─── Phase 0: Scope ───
   phase("Scope");
@@ -122,11 +101,6 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
     { phase: "Scope", label: "scope", tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS, profile: "medium", schema: ScopeSchema },
   );
 
-  if (!scope) {
-    return { summary: "No changes found to review.", findings: [], nextSteps: ["Provide a PR, ref range, or changed files to review."], stats: makeStats(0, 0) };
-  }
-
-  fileCount = scope.files.length;
   progress({ type: "summary", key: "files", value: scope.files.join(", ") || "(none)" });
   const diffTarget = parseAllowedDiffCommand(scope.diffCommand);
   if ("error" in diffTarget) {
@@ -134,11 +108,11 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
   }
   const diffCommand = formatReviewDiffTarget(diffTarget);
   progress({ type: "summary", key: "diffCommand", value: diffCommand });
-  progress({ type: "counter", key: "files", label: "files", value: fileCount });
+  progress({ type: "counter", key: "files", label: "files", value: scope.files.length });
+  const noChanges = (summary: string, nextSteps = ["Provide a PR, ref range, or changed files to review."]) =>
+    finishAdvisoryReport(emptyAdvisoryReport(summary, nextSteps, { ...EMPTY_LENS_REVIEW_STATS, files: scope.files.length }), []);
 
-  if (scope.files.length === 0) {
-    return { summary: "No changes found to review.", findings: [], nextSteps: ["Provide a PR, ref range, or changed files to review."], stats: makeStats(0, 0) };
-  }
+  if (scope.files.length === 0) return noChanges("No changes found to review.");
 
   log(`${scope.files.length} changed files`);
 
@@ -150,6 +124,14 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
   const diffText = reviewMaterial.diff;
   const changed = changedLines(diffText);
   progress({ type: "summary", key: "diffBytes", value: Buffer.byteLength(diffText) });
+  // Findings anchor only on files with a new-side text hunk; without one, skip the finder fan-out.
+  if (changed.size === 0) {
+    if (!diffText.trim()) return noChanges(`No changes found to review: \`${diffCommand}\` has no added or modified files.`);
+    return noChanges(
+      `Nothing to review line by line: \`${diffCommand}\` only deletes or renames files, changes file modes, or touches binary files; there are no added lines to anchor findings on.`,
+      ["Inspect the deleted, renamed, mode-changed or binary files directly; code-review anchors findings on added lines only."],
+    );
+  }
   if (reviewMaterial.snapshot.status === "unavailable") {
     log(`review snapshot unavailable (${reviewMaterial.snapshot.reason}) — patch previews will be unavailable`);
   }
@@ -179,9 +161,10 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
     lenses: ANGLES,
     perLens: PER_ANGLE,
     boundCandidate: (candidate, lens) => {
-      const anchor = candidate.reviewAnchor ?? candidate.locations.find((location) => inDiff(changed, location.file, location.line));
-      return anchor && inDiff(changed, anchor.file, anchor.line)
-        ? { ...candidate, category: lens.category, reviewAnchor: anchor } : undefined;
+      const reviewAnchor = candidate.reviewAnchor
+        ? diffAnchor(changed, candidate.reviewAnchor)
+        : candidate.locations.map((location) => diffAnchor(changed, location)).find((anchor) => anchor !== undefined);
+      return reviewAnchor ? { ...candidate, category: lens.category, reviewAnchor } : undefined;
     },
     finderPrompt: (lens) =>
       `## Code-review finder — ${lens.label}\n\n${scopeBlock}\n` +
@@ -198,35 +181,23 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
       "Run the diff command, read the relevant file(s), and return exactly one verdict (CONFIRMED / PLAUSIBLE / NOT_SUBSTANTIATED / REFUTED) " +
       "with evidence quoting the line(s). Use NOT_SUBSTANTIATED when evidence is insufficient; use REFUTED only for concrete disproof. Structured output only.",
   });
-  rawCandidateCount += pipelineResult.rawCandidates;
-  droppedCandidateCount += pipelineResult.dropped;
-  const { coverage } = pipelineResult;
-  const verified = await challengeFindings(api, pipelineResult.verified, scopeBlock, challengeConfig.options, coverage);
-  const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
-  const stats = makeStats(verified.length, surviving.length);
-  publishVerifiedKeptProgress({ progress, log }, verified.length, surviving.length);
-
-  if (surviving.length === 0) {
-    return finishAdvisoryReport({ summary: "No findings survived verification.", findings: [], nextSteps: ["No code-review action is recommended from this workflow run."], stats, reviewContext }, coverage, verified);
-  }
-
-  // ─── Synthesize: rank, merge, report ───
-  const rank = (finding: AdvisoryVerified): number => (finding.category === "cleanup" ? 2 : 0) + (finding.verdict !== "CONFIRMED" ? 1 : 0);
-  const ranked = [...surviving].sort((a, b) => rank(a) - rank(b));
-  const block = ranked
-    .map(
-      (finding, index) =>
-        `### [${index}] IDs: ${finding.sourceCandidateIds.join(", ")} ${formatLocation(finding)} (${finding.verdict}${finding.category === "cleanup" ? ", cleanup" : ""})\n` +
-        `Category: ${finding.category}\nConfidence: ${verdictConfidence(finding.verdict)}\n` +
-        `${finding.summary}\nImpact: ${finding.impact}\nEvidence: ${formatEvidence(finding.evidence)}`,
-    )
-    .join("\n\n");
-
-  const resolved = await synthesizeAdvisoryReport(api,
-    `## Synthesis: final code-review report\n\n${ranked.length} findings survived independent verification.\n\n${block}\n\n` +
+  const verified = await challengeFindings(api, pipelineResult.verified, scopeBlock, challengeConfig.options, pipelineResult.coverage);
+  const report = await concludeLensReview(api, pipelineResult, verified, {
+    files: scope.files.length,
+    rank,
+    formatFinding: (finding, index) =>
+      `### [${index}] IDs: ${finding.sourceCandidateIds.join(", ")} ${formatLocation(finding)} (${finding.verdict}${finding.category === "cleanup" ? ", cleanup" : ""})\n` +
+      `Category: ${finding.category}\nConfidence: ${verdictConfidence(finding.verdict)}\n` +
+      `${finding.summary}\nImpact: ${finding.impact}\nEvidence: ${formatEvidence(finding.evidence)}`,
+    empty: { summary: "No findings survived verification.", nextSteps: ["No code-review action is recommended from this workflow run."] },
+    synthesisPrompt: (block, ranked) =>
+      `## Synthesis: final code-review report\n\n${ranked.length} findings survived independent verification.\n\n${block}\n\n` +
       "Merge findings with the same root cause, rank most-severe first (correctness bugs above cleanups), and produce the final advisory report. " +
       "Return summary, ID selections with severity (low/medium/high) and advisory recommendation, and nextSteps. Evidence and confidence are reconstructed from verified records. Structured output only.",
-    ranked, coverage,
-  );
-  return finishAdvisoryReport({ ...resolved, stats: { ...stats, kept: resolved.findings.length }, reviewContext }, coverage, verified);
+  });
+  return { ...report, reviewContext };
+}
+
+function rank(finding: AdvisoryVerified): number {
+  return (finding.category === "cleanup" ? 2 : 0) + (finding.verdict !== "CONFIRMED" ? 1 : 0);
 }