pi-workflow-engine 0.11.0 → 0.12.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

@@ -266,11 +266,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

@@ -12,13 +12,15 @@ import {
   formatLocation,
   normalizePath,
   primaryLocation,
+  publishVerifiedKeptProgress,
   recordVerdictProgress,
   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, dedupeCodeReviewCandidates } 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";
@@ -62,7 +64,6 @@ const ANGLES: Angle[] = [
 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>> {
@@ -137,7 +138,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: TOOLS, toolHints: TOOL_HINTS, profile: "medium", schema: ScopeSchema },
   );
 
   if (!scope) {
@@ -183,27 +184,14 @@ 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}`;
-  };
+  const scopeBlock = buildCodeReviewScopeBlock({
+    diffCommand,
+    files: scope.files,
+    summary: scope.summary,
+    conventions: scope.conventions,
+    diffText,
+    target,
+  });
 
   // ─── Find barrier → dedup → Verify ───
   phase("Find");
@@ -217,7 +205,7 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
           `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 },
+        { phase: "Find", label: `find:${angle.label}`, tools: TOOLS, toolHints: TOOL_HINTS, profile: "small", schema: AdvisoryCandidatesSchema },
       );
       const raw = (found?.candidates ?? []).slice(0, PER_ANGLE);
       rawCandidateCount += raw.length;
@@ -243,16 +231,8 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
     }),
   );
 
-  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 })),
-  );
+  // Dedup after all finders complete so verifier agents cannot consume the global cap before full candidate discovery.
+  const novel = dedupeCodeReviewCandidates(compactResults(perAngle));
 
   phase("Verify");
   const verdicts = await parallel(
@@ -269,7 +249,7 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
           label: `verify:${location.file.split("/").pop() ?? location.file}`,
           tools: TOOLS,
           toolHints: TOOL_HINTS,
-          thinkingLevel: "low",
+          profile: "small",
           schema: AdvisoryVerdictSchema,
         },
       );
@@ -282,11 +262,7 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
   const verified = compactResults(verdicts);
   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 };
@@ -314,7 +290,7 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
       phase: "Synthesize",
       label: "synthesize",
       tools: [],
-      thinkingLevel: "medium",
+      profile: "medium",
       resume: "read-only",
       schema: AdvisoryReportSchema,
     },

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

@@ -4,15 +4,16 @@ import {
   AdvisoryReportSchema,
   AdvisoryVerdictSchema,
   type AdvisoryCandidate,
-  type AdvisoryReport,
   type AdvisoryVerdict,
 } from "../src/advisory-schema.ts";
 import {
   advisoryDedupKey as dedupKey,
   backfillAdvisoryFindings,
+  emptyAdvisoryReport,
   formatEvidence,
   formatLocation,
   primaryLocation,
+  publishVerifiedKeptProgress,
   recordVerdictProgress,
   DEFAULT_ADVISORY_TOOL_HINTS,
   DEFAULT_ADVISORY_TOOLS,
@@ -89,11 +90,11 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       "Inspect relevant files, package/test configuration, and safe diagnostic commands. " +
       "Safe commands are read-only commands such as status, grep, listing files, typecheck/test commands, or commands explicitly requested by the user. " +
       "Do not run mutation, install, commit, network, or destructive commands. Return scoped files, observations, and constraints. Structured output only.",
-    { phase: "Scope", label: "scope", tools: TOOLS, toolHints: TOOL_HINTS, thinkingLevel: "medium", schema: ScopeSchema },
+    { phase: "Scope", label: "scope", tools: TOOLS, toolHints: TOOL_HINTS, profile: "medium", schema: ScopeSchema },
   );
 
   if (!scope) {
-    return emptyReport(
+    return emptyAdvisoryReport(
       "Diagnosis could not establish a scope.",
       ["Provide the failing command, error message, or regression description and rerun diagnose."],
       makeStats(0, 0),
@@ -121,7 +122,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
           `Consider ONLY this hypothesis lens:\n${lens.text}\n\n` +
           `Surface up to ${PER_LENS} root-cause hypotheses. Use category exactly "${lens.category}". ` +
           "Each hypothesis must include a one-line summary, locations, impact explaining how it produces the symptom, and an optional recommendation for the next validation step. Structured output only.",
-        { phase: "Hypothesize", label: `hypothesize:${lens.label}`, tools: TOOLS, toolHints: TOOL_HINTS, thinkingLevel: "low", schema: AdvisoryCandidatesSchema },
+        { phase: "Hypothesize", label: `hypothesize:${lens.label}`, tools: TOOLS, toolHints: TOOL_HINTS, profile: "small", schema: AdvisoryCandidatesSchema },
       );
       const candidates = (found?.candidates ?? []).slice(0, PER_LENS).map((candidate) => ({ ...candidate, lens }));
       rawCandidateCount += candidates.length;
@@ -162,7 +163,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
             label: `verify:${location.file.split("/").pop() ?? location.file}`,
             tools: TOOLS,
             toolHints: TOOL_HINTS,
-            thinkingLevel: "low",
+            profile: "small",
             schema: AdvisoryVerdictSchema,
           },
         );
@@ -178,14 +179,10 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
   const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
   const refuted = 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 emptyReport(
+    return emptyAdvisoryReport(
       "No root-cause hypothesis survived verification.",
       ["Capture the exact failing command and error output.", "Rerun diagnose with a narrower symptom or more evidence."],
       stats,
@@ -216,13 +213,13 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       phase: "Synthesize",
       label: "synthesize",
       tools: [],
-      thinkingLevel: "medium",
+      profile: "medium",
       resume: "read-only",
       schema: AdvisoryReportSchema,
     },
   );
 
-  if (!report) return emptyReport("Synthesis produced no output.", ["Inspect verifier evidence manually or rerun diagnose with a narrower symptom."], stats);
+  if (!report) return emptyAdvisoryReport("Synthesis produced no output.", ["Inspect verifier evidence manually or rerun diagnose with a narrower symptom."], stats);
 
   const findings = backfillAdvisoryFindings(report.findings, ranked, {
     impact: "Impact not restated by synthesis.",
@@ -231,10 +228,6 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
   return { ...report, findings, stats };
 }
 
-function emptyReport(summary: string, nextSteps: string[], stats: WorkflowRunStats): AdvisoryReport & { stats: WorkflowRunStats } {
-  return { summary, findings: [], nextSteps, stats };
-}
-
 function dedupe(candidates: Hypothesis[], onDropped: (dropped: number) => void): Hypothesis[] {
   const seen = new Set<string>();
   const novel: Hypothesis[] = [];

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

@@ -2,13 +2,14 @@ import { Type } from "typebox";
 import {
   AdvisoryReportSchema,
   type AdvisoryCandidate,
-  type AdvisoryReport,
   type AdvisoryVerdict,
 } from "../src/advisory-schema.ts";
 import {
   backfillAdvisoryFindings,
+  emptyAdvisoryReport,
   formatEvidence,
   formatLocation,
+  publishVerifiedKeptProgress,
   runLensVerificationPipeline,
   DEFAULT_ADVISORY_TOOL_HINTS,
   DEFAULT_ADVISORY_TOOLS,
@@ -80,11 +81,11 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       "Inspect repository structure, scripts, likely hot-path files, and any existing benchmark or measurement commands. " +
       "Prefer identifying what to measure before claiming bottlenecks. Return files, commands, summary, and known measurements or the lack of them. " +
       `This workflow will fan out across ${PERF_LENSES.length} lenses with up to ${PER_LENS} candidates per lens. Structured output only.`,
-    { phase: "Scope", label: "scope", tools: TOOLS, toolHints: TOOL_HINTS, thinkingLevel: "medium", schema: ScopeSchema },
+    { phase: "Scope", label: "scope", tools: TOOLS, toolHints: TOOL_HINTS, profile: "medium", schema: ScopeSchema },
   );
 
   if (!scope || scope.files.length === 0) {
-    return emptyReport(
+    return emptyAdvisoryReport(
       "No performance-relevant files were identified.",
       ["Provide a slow command, workload, file path, or user-visible latency concern to review."],
       makeStats(0, 0),
@@ -139,14 +140,10 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
   const verified = pipelineResult.verified;
   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 emptyReport(
+    return emptyAdvisoryReport(
       "No performance finding survived verification.",
       ["Add or run a focused measurement for the target workload before optimizing.", "Rerun perf-review with benchmark output or a narrower slow path."],
       stats,
@@ -172,13 +169,13 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       phase: "Synthesize",
       label: "synthesize",
       tools: [],
-      thinkingLevel: "medium",
+      profile: "medium",
       resume: "read-only",
       schema: AdvisoryReportSchema,
     },
   );
 
-  if (!report) return emptyReport("Synthesis produced no output.", ["Inspect verifier evidence manually or rerun perf-review with a narrower target."], stats);
+  if (!report) return emptyAdvisoryReport("Synthesis produced no output.", ["Inspect verifier evidence manually or rerun perf-review with a narrower target."], stats);
 
   const findings = backfillAdvisoryFindings(report.findings, ranked, {
     impact: "Performance impact not restated by synthesis.",
@@ -187,10 +184,6 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
   return { ...report, findings, stats };
 }
 
-function emptyReport(summary: string, nextSteps: string[], stats: WorkflowRunStats): AdvisoryReport & { stats: WorkflowRunStats } {
-  return { summary, findings: [], nextSteps, stats };
-}
-
 function rank(finding: Verified): number {
   const verdictRank = finding.verdict === "CONFIRMED" ? 0 : 1;
   const measurementPenalty = finding.category === "measurement" ? 1 : 0;