pi-workflow-engine 0.11.0 → 0.13.0

package/.pi/extensions/pi-workflow-engine/src/workflow-run-store.ts

@@ -0,0 +1,172 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { validateWorkflowRunId, WORKFLOW_RUNS_DIR } from "./journal.ts";
+import type { WorkflowProgressSnapshot } from "./progress-types.ts";
+import {
+  isWorkflowRunRecord,
+  transitionWorkflowRun,
+  updateWorkflowRunProgress,
+  type WorkflowRunRecord,
+  type WorkflowRunTransition,
+} from "./workflow-run-record.ts";
+
+export const WORKFLOW_RUN_RECORD_KEEP = 50;
+export const WORKFLOW_RUN_RECORD_SUFFIX = ".run.json";
+
+const MAX_RECORD_BYTES = 4 << 20;
+
+export interface WorkflowRunStore {
+  save(record: WorkflowRunRecord): Promise<void>;
+  load(runId: string): Promise<WorkflowRunRecord | undefined>;
+  list(): Promise<WorkflowRunRecord[]>;
+  prune(keep?: number): Promise<void>;
+}
+
+export class ProjectWorkflowRunStore implements WorkflowRunStore {
+  constructor(private readonly cwd: string) {}
+
+  async save(record: WorkflowRunRecord): Promise<void> {
+    const path = workflowRunRecordPath(this.cwd, record.runId);
+    const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    const content = `${JSON.stringify(record)}\n`;
+    if (Buffer.byteLength(content) > MAX_RECORD_BYTES) {
+      throw new Error(`Workflow run record exceeded ${MAX_RECORD_BYTES} bytes.`);
+    }
+    await mkdir(dirname(path), { recursive: true });
+    try {
+      await writeFile(temporaryPath, content, { encoding: "utf8", mode: 0o600 });
+      await rename(temporaryPath, path);
+    } finally {
+      await rm(temporaryPath, { force: true }).catch(() => undefined);
+    }
+  }
+
+  async load(runId: string): Promise<WorkflowRunRecord | undefined> {
+    return await loadWorkflowRunRecord(workflowRunRecordPath(this.cwd, runId));
+  }
+
+  async list(): Promise<WorkflowRunRecord[]> {
+    const dir = join(this.cwd, WORKFLOW_RUNS_DIR);
+    let files: string[];
+    try {
+      files = await readdir(dir);
+    } catch {
+      return [];
+    }
+    const records = await Promise.all(
+      files
+        .filter((file) => file.endsWith(WORKFLOW_RUN_RECORD_SUFFIX))
+        .map((file) => loadWorkflowRunRecord(join(dir, file))),
+    );
+    return records
+      .filter((record): record is WorkflowRunRecord => record !== undefined)
+      .sort((left, right) => right.updatedAt - left.updatedAt);
+  }
+
+  async prune(keep = WORKFLOW_RUN_RECORD_KEEP): Promise<void> {
+    const dir = join(this.cwd, WORKFLOW_RUNS_DIR);
+    let files: string[];
+    try {
+      files = await readdir(dir);
+    } catch {
+      return;
+    }
+    const candidates = await Promise.all(
+      files
+        .filter((file) => file.endsWith(WORKFLOW_RUN_RECORD_SUFFIX))
+        .map(async (file) => {
+          const path = join(dir, file);
+          try {
+            const info = await stat(path);
+            return { path, mtimeMs: info.mtimeMs };
+          } catch {
+            return undefined;
+          }
+        }),
+    );
+    const stale = candidates
+      .filter((entry): entry is { readonly path: string; readonly mtimeMs: number } => entry !== undefined)
+      .sort((left, right) => right.mtimeMs - left.mtimeMs)
+      .slice(Math.max(0, keep));
+    await Promise.all(stale.map((entry) => rm(entry.path, { force: true }).catch(() => undefined)));
+  }
+}
+
+/** Owns one run record and coalesces progress writes while a prior atomic save is in flight. */
+export class DurableWorkflowRun {
+  private record: WorkflowRunRecord;
+  private pending: WorkflowRunRecord | undefined;
+  private draining: Promise<void> | undefined;
+  private writeFailure: unknown;
+  private writeFailed = false;
+
+  constructor(
+    private readonly store: WorkflowRunStore,
+    initial: WorkflowRunRecord,
+    private readonly onWriteFailure?: (error: unknown) => void,
+  ) {
+    this.record = initial;
+    this.queue(initial);
+  }
+
+  updateProgress(progress: WorkflowProgressSnapshot, at = Date.now()): void {
+    this.record = updateWorkflowRunProgress(this.record, progress, at);
+    this.queue(this.record);
+  }
+
+  transition(transition: WorkflowRunTransition): void {
+    this.record = transitionWorkflowRun(this.record, transition);
+    this.queue(this.record);
+  }
+
+  async flush(): Promise<void> {
+    while (this.draining) await this.draining;
+    if (this.writeFailed) throw this.writeFailure;
+  }
+
+  private queue(record: WorkflowRunRecord): void {
+    this.pending = record;
+    if (this.draining) return;
+    this.draining = this.drain().finally(() => {
+      this.draining = undefined;
+      if (this.pending) this.queue(this.pending);
+    });
+  }
+
+  private async drain(): Promise<void> {
+    while (this.pending) {
+      const next = this.pending;
+      this.pending = undefined;
+      try {
+        await this.store.save(next);
+      } catch (error) {
+        this.writeFailed = true;
+        this.writeFailure = error;
+        try {
+          this.onWriteFailure?.(error);
+        } catch {
+          // Persistence observers must not create an unhandled rejection.
+        }
+      }
+    }
+  }
+}
+
+export function workflowRunRecordPath(cwd: string, runId: string): string {
+  return join(cwd, WORKFLOW_RUNS_DIR, `${validateWorkflowRunId(runId)}${WORKFLOW_RUN_RECORD_SUFFIX}`);
+}
+
+async function loadWorkflowRunRecord(path: string): Promise<WorkflowRunRecord | undefined> {
+  try {
+    const content = await readFile(path, "utf8");
+    if (Buffer.byteLength(content) > MAX_RECORD_BYTES) return undefined;
+    const parsed = JSON.parse(content) as unknown;
+    if (!isWorkflowRunRecord(parsed)) return undefined;
+    const file = basename(path);
+    const pathRunId = file.slice(0, -WORKFLOW_RUN_RECORD_SUFFIX.length);
+    return parsed.runId === pathRunId ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/.pi/extensions/pi-workflow-engine/src/workflow-usage-limit-scheduler.ts

@@ -0,0 +1,80 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { WorkflowRunRecord } from "./workflow-run-record.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+
+export interface WorkflowUsageLimitSchedulerClock {
+  now(): number;
+  setTimeout(callback: () => void, delayMs: number): unknown;
+  clearTimeout(handle: unknown): void;
+}
+
+interface ScheduledUsageLimitResume {
+  readonly sessionId: string;
+  readonly handle: unknown;
+}
+
+export const defaultWorkflowUsageLimitSchedulerClock: WorkflowUsageLimitSchedulerClock = {
+  now: () => Date.now(),
+  setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+  clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};
+
+/** One in-process timer per paused run. Durable records remain the source of truth. */
+export class WorkflowUsageLimitScheduler {
+  private readonly scheduled = new Map<string, ScheduledUsageLimitResume>();
+  private readonly inactiveSessions = new Set<string>();
+
+  constructor(
+    private readonly resume: (ctx: ExtensionContext, runId: string, attempt: number) => Promise<void>,
+    private readonly clock: WorkflowUsageLimitSchedulerClock = defaultWorkflowUsageLimitSchedulerClock,
+    private readonly log: (message: string) => void = (message) => process.stderr.write(`${message}\n`),
+  ) {}
+
+  arm(ctx: ExtensionContext, record: WorkflowRunRecord): boolean {
+    if (record.state !== "paused" || record.pause?.kind !== "provider_usage_limit") return false;
+    const pause = record.pause;
+    if (!pause.autoResume || pause.attempt >= pause.maxAttempts) return false;
+    const sessionId = ctx.sessionManager.getSessionId();
+    if (
+      this.inactiveSessions.has(sessionId)
+      || record.background?.origin.sessionId !== sessionId
+      || this.scheduled.has(record.runId)
+    ) {
+      return false;
+    }
+
+    const delayMs = Math.max(0, pause.nextEligibleAt - this.clock.now());
+    const handle = this.clock.setTimeout(() => {
+      this.scheduled.delete(record.runId);
+      void this.resume(ctx, record.runId, pause.attempt).catch((error: unknown) => {
+        this.log(`[workflow:${record.runId}] automatic provider-limit resume failed: ${unknownErrorMessage(error)}`);
+      });
+    }, delayMs);
+    this.scheduled.set(record.runId, { sessionId, handle });
+    return true;
+  }
+
+  cancel(runId: string): boolean {
+    const scheduled = this.scheduled.get(runId);
+    if (!scheduled) return false;
+    this.clock.clearTimeout(scheduled.handle);
+    this.scheduled.delete(runId);
+    return true;
+  }
+
+  cancelSession(ctx: Pick<ExtensionContext, "sessionManager">): void {
+    const sessionId = ctx.sessionManager.getSessionId();
+    this.inactiveSessions.add(sessionId);
+    for (const [runId, scheduled] of this.scheduled) {
+      if (scheduled.sessionId === sessionId) this.cancel(runId);
+    }
+  }
+
+  activateSession(ctx: Pick<ExtensionContext, "sessionManager">): void {
+    this.inactiveSessions.delete(ctx.sessionManager.getSessionId());
+  }
+
+  has(runId: string): boolean {
+    return this.scheduled.has(runId);
+  }
+}

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

@@ -3,6 +3,7 @@ import * as codeReview from "../workflows/code-review.ts";
 import * as refactorScout from "../workflows/refactor-scout.ts";
 import * as diagnose from "../workflows/diagnose.ts";
 import * as perfReview from "../workflows/perf-review.ts";
+import * as research from "../workflows/research.ts";
 import type { WorkflowModule } from "./types.ts";
 
 /**
@@ -33,6 +34,7 @@ export const BUILTIN_WORKFLOW_DEFINITIONS: readonly BuiltinWorkflowDefinition[]
   defineBuiltinWorkflow(refactorScout, "refactor-scout.ts"),
   defineBuiltinWorkflow(diagnose, "diagnose.ts"),
   defineBuiltinWorkflow(perfReview, "perf-review.ts"),
+  defineBuiltinWorkflow(research, "research.ts"),
 ];
 export const BUILTIN_WORKFLOWS = BUILTIN_WORKFLOW_DEFINITIONS.map(({ module }) => module);
 export const BUILTIN_WORKFLOW_FILES = new Set(BUILTIN_WORKFLOW_DEFINITIONS.map(({ filename }) => filename));

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

@@ -154,6 +154,13 @@ export class WorktreeRegistry {
     });
   }
 
+  async applyPatch(path: string, patch: string, signal?: AbortSignal): Promise<WorktreeGitCommandResult> {
+    return this.runner.runGit({
+      cwd: path, args: ["apply", "--index", "--binary", "-"],
+      stdin: patch, signal, timeoutMs: this.timeoutMs,
+    });
+  }
+
   async validatePatch(path: string, candidate: WorktreePatch, signal?: AbortSignal): Promise<WorktreeGitCommandResult> {
     return await validateWorktreePatch({
       worktreePath: path,
@@ -266,11 +273,48 @@ export async function addWorktree(options: {
   const message = result.error ?? (result.stderr.trim() || "git worktree add failed");
   if (!isInvalidHeadError(message)) return { path, error: message };
 
-  const snapshotError = await createUnbornRepoSnapshot({ repoCwd: options.repoCwd, path, timeoutMs: options.timeoutMs, signal: options.signal })
+  return await addUnbornRepositoryWorktree({
+    repoCwd: options.repoCwd,
+    path,
+    addError: message,
+    runner,
+    signal: options.signal,
+    snapshotTimeoutMs: options.timeoutMs,
+    timeoutMs,
+  });
+}
+
+async function addUnbornRepositoryWorktree(options: {
+  readonly repoCwd: string;
+  readonly path: string;
+  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,
+    signal: options.signal,
+  })
     .then(() => undefined)
     .catch((error: unknown) => unknownErrorMessage(error));
-  if (snapshotError !== undefined) return { path, snapshot: true, error: `git worktree add failed (${message}); unborn-repo snapshot fallback failed: ${snapshotError}` };
-  return await finalizeWorktreeRef({ path, snapshot: true, runner, signal: options.signal, timeoutMs });
+  if (snapshotError !== undefined) {
+    return {
+      path: options.path,
+      snapshot: true,
+      error: `git worktree add failed (${options.addError}); unborn-repo snapshot fallback failed: ${snapshotError}`,
+    };
+  }
+  return await finalizeWorktreeRef({
+    path: options.path,
+    snapshot: true,
+    runner: options.runner,
+    signal: options.signal,
+    timeoutMs: options.timeoutMs,
+  });
 }
 
 async function finalizeWorktreeRef(options: {

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

@@ -1,24 +1,21 @@
+import { challengeFindings, parseChallengeArgs } from "../src/advisory-challenge.ts";
 import { Type } from "typebox";
 import {
-  AdvisoryCandidatesSchema,
-  AdvisoryReportSchema,
-  AdvisoryVerdictSchema,
-  type AdvisoryCandidate,
-  type AdvisoryVerdict,
-} from "../src/advisory-schema.ts";
-import {
-  backfillAdvisoryFindings,
+  type AdvisoryVerified,
+  type AdvisoryLens,
+  synthesizeAdvisoryReport,
+  finishAdvisoryReport,
   formatEvidence,
   formatLocation,
   normalizePath,
-  primaryLocation,
-  recordVerdictProgress,
+  publishVerifiedKeptProgress,
+  runLensVerificationPipeline,
   verdictConfidence,
   DEFAULT_ADVISORY_TOOL_HINTS,
   DEFAULT_ADVISORY_TOOLS,
 } from "../src/workflow-advisory-utils.ts";
-import { compactResults } from "../src/concurrency.ts";
-import { formatReviewDiffTarget, parseAllowedDiffCommand } from "../src/diff-capture.ts";
+import { formatReviewDiffTarget, parseAllowedDiffCommand } from "../src/review-diff-target.ts";
+import { buildCodeReviewScopeBlock } from "../src/review/code-review-orchestration.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";
@@ -26,7 +23,7 @@ import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../src/types.t
 export const meta: WorkflowMeta = {
   name: "code-review",
   description: "Fan-out review of the branch's open PR (or branch vs main): scope → per-angle find → independent verify → synthesize.",
-  phases: [{ title: "Scope" }, { title: "Find" }, { title: "Verify" }, { title: "Synthesize" }],
+  phases: [{ title: "Scope" }, { title: "Find" }, { title: "Verify" }, { title: "Challenge" }, { title: "Synthesize" }],
 };
 
 // ─── Schemas (the contracts that make orchestration plain code) ───
@@ -37,32 +34,16 @@ const ScopeSchema = Type.Object({
   conventions: Type.Optional(Type.String({ description: "Relevant AGENTS.md / project conventions" })),
 });
 
-type Candidate = AdvisoryCandidate;
-
-interface Angle {
-  label: string;
-  kind: "bug" | "cleanup";
-  text: string;
-}
-interface Verified extends Candidate {
-  verdict: AdvisoryVerdict["verdict"];
-  evidence: string[];
-  kind: "bug" | "cleanup";
-}
-
 // The review lenses — this is the part you customise to your codebase's real failure modes.
-const ANGLES: Angle[] = [
-  { label: "logic-bugs", kind: "bug", text: "Off-by-one errors, wrong conditionals, incorrect return values, broken control flow." },
-  { label: "error-paths", kind: "bug", text: "Unhandled errors, swallowed exceptions, missing awaits, partial failure leaving inconsistent state." },
-  { label: "edge-cases", kind: "bug", text: "Empty/null inputs, boundary values, concurrency races, resource leaks." },
-  { label: "simplification", kind: "cleanup", text: "Dead code, needless complexity, duplicated logic, clearer equivalents." },
-  { label: "conventions", kind: "cleanup", text: "Violations of the project conventions noted in scope (naming, idioms, banned patterns)." },
+const ANGLES: AdvisoryLens[] = [
+  { label: "logic-bugs", category: "bug", text: "Off-by-one errors, wrong conditionals, incorrect return values, broken control flow." },
+  { label: "error-paths", category: "bug", text: "Unhandled errors, swallowed exceptions, missing awaits, partial failure leaving inconsistent state." },
+  { label: "edge-cases", category: "bug", text: "Empty/null inputs, boundary values, concurrency races, resource leaks." },
+  { label: "simplification", category: "cleanup", text: "Dead code, needless complexity, duplicated logic, clearer equivalents." },
+  { label: "conventions", category: "cleanup", text: "Violations of the project conventions noted in scope (naming, idioms, banned patterns)." },
 ];
 
-const TOOLS = DEFAULT_ADVISORY_TOOLS;
-const TOOL_HINTS = DEFAULT_ADVISORY_TOOL_HINTS;
 const PER_ANGLE = 6;
-const DIFF_EMBED_CAP = 60_000;
 
 /** 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>> {
@@ -105,8 +86,9 @@ export interface CodeReviewDependencies {
 }
 
 export default async function run(api: WorkflowApi, dependencies: CodeReviewDependencies = {}): Promise<unknown> {
-  const { agent, parallel, phase, log, progress, args, cwd, signal } = api;
-  const target = args.trim();
+  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;
@@ -137,7 +119,7 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
       "Then: list the changed files, summarize the change in one paragraph (mention the PR if one was found), " +
       "and read any relevant AGENTS.md or project docs noting conventions a reviewer should know.\n" +
       "Return diffCommand exactly as a reviewer should run it. Structured output only.",
-    { phase: "Scope", label: "scope", tools: TOOLS, toolHints: TOOL_HINTS, thinkingLevel: "medium", schema: ScopeSchema },
+    { phase: "Scope", label: "scope", tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS, profile: "medium", schema: ScopeSchema },
   );
 
   if (!scope) {
@@ -183,147 +165,68 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
       : {}),
   };
 
-  const diffBlock = diffText
-    ? `\n## Diff (review is bounded to these changed lines)\n\`\`\`diff\n${
-        diffText.length > DIFF_EMBED_CAP
-          ? `${diffText.slice(0, DIFF_EMBED_CAP)}\n... (truncated — run \`${diffCommand}\` for the full diff)`
-          : diffText
-      }\n\`\`\`\n`
-    : "";
-
-  const scopeBlock =
-    `## Diff command\n${diffCommand}\n\n## Changed files\n${scope.files.map((file) => `- ${file}`).join("\n")}\n\n` +
-    `## Summary\n${scope.summary}\n\n## Conventions\n${scope.conventions ?? "(none noted)"}\n` +
-    diffBlock +
-    (target ? `\n## User instructions (verbatim)\n${target}\n` : "");
-
-  // Dedup after all finders complete so verifier agents cannot consume the global cap before full candidate discovery.
-  const seen = new Set<string>();
-  const dedupKey = (candidate: Candidate): 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}`;
-  };
-
-  // ─── Find barrier → dedup → Verify ───
-  phase("Find");
-  const perAngle = await parallel(
-    ANGLES.map((angle) => async () => {
-      const found = await agent(
-        `## Code-review finder — ${angle.label}\n\n${scopeBlock}\n` +
-          `Review the change through ONLY this lens:\n${angle.text}\n` +
-          "Only flag issues on lines that are part of the diff above (run the diff command if it is not shown). " +
-          "You may read surrounding files for context, but never report issues in unchanged code. " +
-          `Surface up to ${PER_ANGLE} candidates. Use category exactly "${angle.kind}". Each candidate must include a one-line summary, ` +
-          "locations with the changed file and a line that appears in the diff, and impact describing the concrete failure or maintenance scenario. " +
-          "Pass through anything with a nameable impact — a separate verifier judges them next. Structured output only.",
-        { phase: "Find", label: `find:${angle.label}`, tools: TOOLS, toolHints: TOOL_HINTS, thinkingLevel: "low", schema: AdvisoryCandidatesSchema },
-      );
-      const raw = (found?.candidates ?? []).slice(0, PER_ANGLE);
-      rawCandidateCount += raw.length;
-      progress({ type: "counter_delta", key: "candidates", label: "candidates", delta: raw.length });
-      const bounded = raw.filter((candidate) => inDiff(changed, primaryLocation(candidate).file, primaryLocation(candidate).line));
-      const dropped = raw.length - bounded.length;
-      if (dropped > 0) {
-        droppedCandidateCount += dropped;
-        progress({ type: "counter_delta", key: "dropped", label: "dropped", delta: dropped });
-        log(`find:${angle.label}: dropped ${dropped} out-of-diff candidate(s)`);
-      }
-      for (const candidate of bounded) {
-        progress({
-          type: "lane_item",
-          lane: "Candidates",
-          title: candidate.summary,
-          subtitle: formatLocation(candidate),
-          status: "pending",
-          details: candidate.impact,
-        });
-      }
-      return { angle, candidates: bounded };
-    }),
-  );
-
-  const novel = compactResults(perAngle).flatMap(({ angle, candidates }) =>
-    candidates
-      .filter((candidate) => {
-        const key = dedupKey(candidate);
-        if (seen.has(key)) return false;
-        seen.add(key);
-        return true;
-      })
-      .map((candidate) => ({ angle, candidate })),
-  );
-
-  phase("Verify");
-  const verdicts = await parallel(
-    novel.map(({ angle, candidate }) => async (): Promise<Verified | null> => {
-      const location = primaryLocation(candidate);
-      const judged = await agent(
-        `## Code-review verifier\n\n${scopeBlock}\n## Candidate\n` +
-          `Location: ${formatLocation(candidate)}\n` +
-          `Category: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n\n` +
-          "Run the diff command, read the relevant file(s), and return exactly one verdict (CONFIRMED / PLAUSIBLE / REFUTED) " +
-          "with evidence quoting the line(s). Default toward REFUTED if you cannot substantiate it. Structured output only.",
-        {
-          phase: "Verify",
-          label: `verify:${location.file.split("/").pop() ?? location.file}`,
-          tools: TOOLS,
-          toolHints: TOOL_HINTS,
-          thinkingLevel: "low",
-          schema: AdvisoryVerdictSchema,
-        },
-      );
-      if (!judged) return null;
-      recordVerdictProgress(progress, candidate, judged);
-      return { ...candidate, verdict: judged.verdict, evidence: judged.evidence, kind: angle.kind };
-    }),
-  );
+  const scopeBlock = `Reviewed snapshot identity: ${JSON.stringify(reviewContext.snapshot ?? "unavailable")}\n` + buildCodeReviewScopeBlock({
+    diffCommand,
+    files: scope.files,
+    summary: scope.summary,
+    conventions: scope.conventions,
+    diffText,
+    target,
+  });
 
-  const verified = compactResults(verdicts);
+  const pipelineResult = await runLensVerificationPipeline({
+    api,
+    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;
+    },
+    finderPrompt: (lens) =>
+      `## Code-review finder — ${lens.label}\n\n${scopeBlock}\n` +
+      `Review the change through ONLY this lens:\n${lens.text}\n` +
+      "Only flag issues on lines that are part of the diff above (run the diff command if it is not shown). " +
+      "Set reviewAnchor to the changed line causing the issue; locations and discoveryEvidence may include unchanged callers and other files. " +
+      `Surface up to ${PER_ANGLE} candidates. Use category exactly "${lens.category}". Each candidate must include a one-line summary, ` +
+      "locations with the changed file and a line that appears in the diff, and impact describing the concrete failure or maintenance scenario. " +
+      "Pass through anything with a nameable impact — a separate verifier judges them next. Structured output only.",
+    verifierPrompt: (candidate) =>
+      `## Code-review verifier\n\n${scopeBlock}\n## Candidate\n` +
+      `Location: ${formatLocation(candidate)}\n` +
+      `Category: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n\n` +
+      "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);
-  progress({ type: "counter", key: "verified", label: "verified", value: verified.length });
-  progress({ type: "counter", key: "kept", label: "kept", value: surviving.length });
-  progress({ type: "summary", key: "verified", value: verified.length });
-  progress({ type: "summary", key: "kept", value: surviving.length });
-  log(`${verified.length} verified → ${surviving.length} kept`);
+  publishVerifiedKeptProgress({ progress, log }, verified.length, surviving.length);
 
   if (surviving.length === 0) {
-    return { summary: "No findings survived verification.", findings: [], nextSteps: ["No code-review action is recommended from this workflow run."], stats, reviewContext };
+    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 ───
-  phase("Synthesize");
-  const rank = (finding: Verified): number => (finding.kind === "cleanup" ? 2 : 0) + (finding.verdict === "PLAUSIBLE" ? 1 : 0);
+  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}] ${formatLocation(finding)} (${finding.verdict}${finding.kind === "cleanup" ? ", cleanup" : ""})\n` +
-        `Category: ${finding.kind}\nConfidence: ${verdictConfidence(finding.verdict)}\n` +
+        `### [${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 report = await agent(
+  const resolved = await synthesizeAdvisoryReport(api,
     `## 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, findings, and nextSteps. For each finding: category must be bug or cleanup; severity is impact level (low/medium/high), not category; " +
-      "confidence must be high for CONFIRMED and medium for PLAUSIBLE; copy locations and evidence arrays from the verified finding; impact is the concrete failure or maintenance scenario; recommendation is an advisory fix direction, not an edit. Structured output only.",
-    {
-      phase: "Synthesize",
-      label: "synthesize",
-      tools: [],
-      thinkingLevel: "medium",
-      resume: "read-only",
-      schema: AdvisoryReportSchema,
-    },
+      "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,
   );
-
-  if (!report) return { summary: "Synthesis produced no output.", findings: [], nextSteps: ["Re-run the workflow or inspect verifier evidence manually."], stats, reviewContext };
-
-  const findings = backfillAdvisoryFindings(report.findings, ranked, {
-    impact: "Impact not restated by synthesis.",
-  });
-  return { ...report, findings, stats, reviewContext };
+  return finishAdvisoryReport({ ...resolved, stats: { ...stats, kept: resolved.findings.length }, reviewContext }, coverage, verified);
 }