pi-workflow-engine 0.2.0 → 0.4.0

package/.pi/extensions/pi-workflow-engine/src/ui/workflow-result-renderer.ts

@@ -0,0 +1,198 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Box, type Component, Text } from "@earendil-works/pi-tui";
+import type { AdvisoryFinding, AdvisoryLocation, AdvisoryReport } from "../advisory-schema.ts";
+import type { PerfAggregate } from "../perf.ts";
+import { badge, formatCount, type WorkflowThemeColor } from "./workflow-format.ts";
+
+export interface WorkflowPerfDetails {
+  readonly enabled: boolean;
+  readonly startedAt: number;
+  readonly aggregates: readonly PerfAggregate[];
+}
+
+export interface WorkflowResultEnvelope {
+  name: string;
+  result: unknown;
+  completedAt: number;
+  perf?: WorkflowPerfDetails;
+}
+
+export interface AdvisoryWorkflowResult extends AdvisoryReport {
+  stats?: Record<string, string | number>;
+}
+
+export function isWorkflowResult(value: unknown): value is WorkflowResultEnvelope {
+  if (!isRecord(value)) return false;
+  return typeof value.name === "string" && "result" in value && typeof value.completedAt === "number";
+}
+
+function isAdvisoryLocation(value: unknown): value is AdvisoryLocation {
+  if (!isRecord(value)) return false;
+  if (typeof value.file !== "string") return false;
+  if (value.line !== undefined && typeof value.line !== "number") return false;
+  if (value.symbol !== undefined && typeof value.symbol !== "string") return false;
+  return true;
+}
+
+function isAdvisoryFinding(value: unknown): value is AdvisoryFinding {
+  if (!isRecord(value)) return false;
+  if (typeof value.summary !== "string") return false;
+  if (typeof value.category !== "string") return false;
+  if (!isSeverity(value.severity)) return false;
+  if (!isConfidence(value.confidence)) return false;
+  if (!Array.isArray(value.locations) || !value.locations.every(isAdvisoryLocation)) return false;
+  if (!Array.isArray(value.evidence) || !value.evidence.every((entry) => typeof entry === "string")) return false;
+  if (typeof value.impact !== "string") return false;
+  if (typeof value.recommendation !== "string") return false;
+  return true;
+}
+
+export function isAdvisoryReport(value: unknown): value is AdvisoryWorkflowResult {
+  if (!isRecord(value)) return false;
+  if (typeof value.summary !== "string" || !Array.isArray(value.findings)) return false;
+  if (!value.findings.every(isAdvisoryFinding)) return false;
+  if (!Array.isArray(value.nextSteps) || !value.nextSteps.every((entry) => typeof entry === "string")) return false;
+  if (value.stats !== undefined && !isStats(value.stats)) return false;
+  return true;
+}
+
+export function renderWorkflowResult(name: string, result: unknown, expanded: boolean, theme: Theme): Component {
+  const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+  box.addChild(new Text(renderWorkflowResultText(name, result, expanded, theme), 0, 0));
+  return box;
+}
+
+export function renderWorkflowResultText(name: string, result: unknown, expanded: boolean, theme: Theme): string {
+  if (isAdvisoryReport(result)) {
+    return renderAdvisoryResult(name, result, expanded, theme);
+  }
+  return renderGenericWorkflowResult(name, result, expanded, theme);
+}
+
+function renderAdvisoryResult(name: string, result: AdvisoryWorkflowResult, expanded: boolean, theme: Theme): string {
+  const icon = theme.fg("success", "✓");
+  const title = theme.fg("accent", theme.bold(`Workflow: ${name}`));
+  const lines = [`${icon} ${title}`, theme.fg("muted", result.summary)];
+  const stats = statsLine(result.stats, theme);
+  if (stats) lines.push(stats);
+
+  if (result.findings.length === 0) {
+    lines.push(theme.fg("success", "No findings."));
+    if (expanded && result.nextSteps.length > 0) renderNextSteps(result.nextSteps, lines, theme);
+    return lines.join("\n");
+  }
+
+  const findings = expanded ? result.findings : result.findings.slice(0, 3);
+  lines.push(theme.fg("dim", expanded ? "Findings:" : "Top findings:"));
+  for (const finding of findings) {
+    lines.push(renderAdvisoryFinding(finding, expanded, theme));
+  }
+  if (!expanded && result.findings.length > findings.length) {
+    lines.push(theme.fg("dim", `… ${result.findings.length - findings.length} more finding(s)`));
+  }
+  if (expanded && result.nextSteps.length > 0) renderNextSteps(result.nextSteps, lines, theme);
+  return lines.join("\n");
+}
+
+function renderAdvisoryFinding(finding: AdvisoryFinding, expanded: boolean, theme: Theme): string {
+  const location = formatLocation(finding.locations[0]);
+  let text =
+    `  ${badge(finding.category, "accent", theme)} ` +
+    `${badge(finding.severity, severityColor(finding.severity), theme)} ` +
+    `${badge(`${finding.confidence} confidence`, confidenceColor(finding.confidence), theme)} ` +
+    `${theme.fg("accent", location)} ${theme.fg("muted", finding.summary)}`;
+  if (expanded) {
+    text += `\n    ${theme.fg("dim", `Impact: ${finding.impact}`)}`;
+    text += `\n    ${theme.fg("dim", `Evidence: ${finding.evidence.join("; ") || "(none cited)"}`)}`;
+    text += `\n    ${theme.fg("dim", `Recommendation: ${finding.recommendation}`)}`;
+  }
+  return text;
+}
+
+function renderNextSteps(nextSteps: string[], lines: string[], theme: Theme): void {
+  lines.push(theme.fg("dim", "Next steps:"));
+  for (const step of nextSteps) {
+    lines.push(`  - ${theme.fg("muted", step)}`);
+  }
+}
+
+function formatLocation(location: AdvisoryLocation | undefined): string {
+  if (!location) return "(no location)";
+  const line = location.line != null ? `:${location.line}` : "";
+  const symbol = location.symbol ? ` (${location.symbol})` : "";
+  return `${location.file}${line}${symbol}`;
+}
+
+function severityColor(severity: AdvisoryFinding["severity"]): WorkflowThemeColor {
+  switch (severity) {
+    case "high":
+      return "error";
+    case "medium":
+      return "warning";
+    case "low":
+      return "muted";
+  }
+}
+
+function confidenceColor(confidence: AdvisoryFinding["confidence"]): WorkflowThemeColor {
+  switch (confidence) {
+    case "high":
+      return "success";
+    case "medium":
+      return "warning";
+    case "low":
+      return "muted";
+  }
+}
+
+function renderGenericWorkflowResult(name: string, result: unknown, expanded: boolean, theme: Theme): string {
+  const lines = [`${theme.fg("success", "✓")} ${theme.fg("accent", theme.bold(`Workflow: ${name}`))}`];
+  const summary = extractSummary(result);
+  if (summary) lines.push(theme.fg("muted", summary));
+  if (expanded) lines.push(theme.fg("dim", safeJson(result)));
+  else if (!summary) lines.push(theme.fg("dim", "Result available in expanded view."));
+  return lines.join("\n");
+}
+
+function statsLine(stats: Record<string, string | number> | undefined, theme: Theme): string | undefined {
+  if (!stats) return undefined;
+  const ordered = ["files", "candidates", "dropped", "verified", "kept"];
+  const parts = ordered.flatMap((key) => {
+    const value = stats[key];
+    if (value === undefined) return [];
+    return [`${key} ${typeof value === "number" ? formatCount(value) : value}`];
+  });
+  if (parts.length === 0) return undefined;
+  return theme.fg("dim", parts.join(" · "));
+}
+
+function extractSummary(value: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  if (isRecord(value) && typeof value.summary === "string") return value.summary;
+  return undefined;
+}
+
+function safeJson(value: unknown): string {
+  try {
+    return JSON.stringify(value, null, 2) ?? String(value);
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+
+function isSeverity(value: unknown): value is AdvisoryFinding["severity"] {
+  return value === "low" || value === "medium" || value === "high";
+}
+
+function isConfidence(value: unknown): value is AdvisoryFinding["confidence"] {
+  return value === "low" || value === "medium" || value === "high";
+}
+
+function isStats(value: unknown): value is Record<string, string | number> {
+  if (!isRecord(value)) return false;
+  return Object.values(value).every((entry) => typeof entry === "string" || typeof entry === "number");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/.pi/extensions/pi-workflow-engine/src/ui/workflow-widget.ts

@@ -0,0 +1,182 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { AgentRowSnapshot, PhaseSnapshot, WorkflowProgressSnapshot } from "../progress.ts";
+import { agentDetailParts, agentLabelColor, formatCount, formatDuration, statusIcon, truncateDisplay } from "./workflow-format.ts";
+
+const MAX_WIDGET_LINES = 12;
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+export interface WorkflowWidget {
+  nextFrame(): void;
+  render(width: number, theme: Theme): string[];
+  invalidate(): void;
+}
+
+export function createWorkflowWidget(snapshotProvider: () => WorkflowProgressSnapshot): WorkflowWidget {
+  return new LiveWorkflowWidget(snapshotProvider);
+}
+
+export function renderWorkflowWidgetLines(
+  snapshot: WorkflowProgressSnapshot,
+  frame: number,
+  width: number,
+  theme: Theme,
+): string[] {
+  const safeWidth = Math.max(1, width);
+  const counts = countAgents(snapshot.phases);
+  const active = counts.running + counts.queued;
+  const elapsed = formatDuration((snapshot.doneAt ?? Date.now()) - snapshot.startedAt);
+  const spinner = active > 0 ? theme.fg("accent", SPINNER[frame % SPINNER.length]) : theme.fg("success", "✓");
+
+  const headingParts = [`${counts.done}/${counts.total} done`, elapsed];
+  if (counts.running > 0) headingParts.unshift(`${counts.running} running`);
+  if (counts.queued > 0) headingParts.unshift(`${counts.queued} queued`);
+  if (counts.failed > 0) headingParts.unshift(theme.fg("error", `${counts.failed} failed`));
+
+  const lines: string[] = [
+    truncateDisplay(
+      `${spinner} ${theme.bold(snapshot.title)} ${theme.fg("dim", "·")} ${theme.fg("muted", snapshot.currentPhase)} ${theme.fg("dim", "·")} ${headingParts.join(` ${theme.fg("dim", "·")} `)}`,
+      safeWidth,
+    ),
+  ];
+
+  const footer = footerLine(snapshot, theme);
+  const bodyBudget = Math.max(0, MAX_WIDGET_LINES - lines.length - (footer ? 1 : 0));
+  const body = visibleBodyLines(snapshot.phases, bodyBudget, theme);
+  const reserveHiddenLine = body.hidden > 0 && bodyBudget > 0;
+  const visibleBodyLinesToRender = reserveHiddenLine ? body.lines.slice(0, Math.max(0, bodyBudget - 1)) : body.lines;
+  const hidden = body.hidden + (body.lines.length - visibleBodyLinesToRender.length);
+
+  for (const line of visibleBodyLinesToRender) lines.push(truncateDisplay(line, safeWidth));
+  if (hidden > 0 && lines.length < MAX_WIDGET_LINES) {
+    lines.push(truncateDisplay(`${theme.fg("dim", "└─")} ${theme.fg("dim", `+${hidden} more`)}`, safeWidth));
+  }
+  if (footer && lines.length < MAX_WIDGET_LINES) lines.push(truncateDisplay(footer, safeWidth));
+
+  return lines.slice(0, MAX_WIDGET_LINES).map((line) => truncateDisplay(line, safeWidth));
+}
+
+class LiveWorkflowWidget implements WorkflowWidget {
+  private frame = 0;
+  private cachedWidth: number | undefined;
+  private cachedFrame: number | undefined;
+  private cachedDoneAt: number | undefined;
+  private cachedLines: string[] | undefined;
+
+  constructor(private readonly snapshotProvider: () => WorkflowProgressSnapshot) {}
+
+  nextFrame(): void {
+    this.frame = (this.frame + 1) % SPINNER.length;
+    this.invalidate();
+  }
+
+  render(width: number, theme: Theme): string[] {
+    const snapshot = this.snapshotProvider();
+    if (
+      this.cachedLines &&
+      this.cachedWidth === width &&
+      this.cachedFrame === this.frame &&
+      this.cachedDoneAt === snapshot.doneAt
+    ) {
+      return this.cachedLines;
+    }
+
+    this.cachedLines = renderWorkflowWidgetLines(snapshot, this.frame, width, theme);
+    this.cachedWidth = width;
+    this.cachedFrame = this.frame;
+    this.cachedDoneAt = snapshot.doneAt;
+    return this.cachedLines;
+  }
+
+  invalidate(): void {
+    this.cachedWidth = undefined;
+    this.cachedFrame = undefined;
+    this.cachedDoneAt = undefined;
+    this.cachedLines = undefined;
+  }
+}
+
+interface AgentCounts {
+  queued: number;
+  running: number;
+  done: number;
+  failed: number;
+  total: number;
+}
+
+function countAgents(phases: readonly PhaseSnapshot[]): AgentCounts {
+  const counts: AgentCounts = { queued: 0, running: 0, done: 0, failed: 0, total: 0 };
+  for (const phase of phases) {
+    for (const agent of phase.agents) {
+      counts[agent.status]++;
+      counts.total++;
+    }
+  }
+  return counts;
+}
+
+function visibleBodyLines(phases: readonly PhaseSnapshot[], budget: number, theme: Theme): { lines: string[]; hidden: number } {
+  const lines: string[] = [];
+  let totalRows = 0;
+  const visit = (phase: PhaseSnapshot): void => {
+    if (phase.agents.length === 0 && phase.title === "Workflow") return;
+    const counts = countPhaseAgents(phase);
+    totalRows++;
+    if (lines.length < budget) lines.push(phaseLine(phase.title, counts, theme));
+    appendAgentGroup(phase.agents, (agent) => agent.status === "running" || agent.status === "queued", lines, budget, theme, () => totalRows++);
+    appendAgentGroup(phase.agents, (agent) => agent.status === "failed", lines, budget, theme, () => totalRows++);
+    appendAgentGroup(phase.agents, (agent) => agent.status === "done", lines, budget, theme, () => totalRows++);
+  };
+
+  for (const phase of phases) {
+    if (phase.agents.some((agent) => agent.status === "running" || agent.status === "queued")) visit(phase);
+  }
+  for (const phase of phases) {
+    if (!phase.agents.some((agent) => agent.status === "running" || agent.status === "queued")) visit(phase);
+  }
+
+  return { lines, hidden: Math.max(0, totalRows - lines.length) };
+}
+
+function appendAgentGroup(
+  agents: readonly AgentRowSnapshot[],
+  include: (agent: AgentRowSnapshot) => boolean,
+  lines: string[],
+  budget: number,
+  theme: Theme,
+  countRow: () => void,
+): void {
+  for (const agent of agents) {
+    if (!include(agent)) continue;
+    countRow();
+    if (lines.length < budget) lines.push(agentLine(agent, theme));
+  }
+}
+
+function countPhaseAgents(phase: PhaseSnapshot): AgentCounts {
+  const counts: AgentCounts = { queued: 0, running: 0, done: 0, failed: 0, total: phase.agents.length };
+  for (const agent of phase.agents) counts[agent.status]++;
+  return counts;
+}
+
+function phaseLine(title: string, counts: AgentCounts, theme: Theme): string {
+  const parts: string[] = [];
+  if (counts.running > 0) parts.push(`${counts.running} running`);
+  if (counts.done > 0) parts.push(`${counts.done} done`);
+  if (counts.failed > 0) parts.push(`${counts.failed} failed`);
+  return `${theme.fg("dim", "├─")} ${theme.fg(counts.running > 0 ? "accent" : "muted", title)}${parts.length ? ` ${theme.fg("dim", `(${parts.join(" · ")})`)}` : ""}`;
+}
+
+function agentLine(agent: AgentRowSnapshot, theme: Theme): string {
+  const detailParts = agentDetailParts(agent, { includeQueuedStatus: false });
+  const activity = detailParts.length > 0 ? ` ${theme.fg("dim", `· ${detailParts.join(" · ")}`)}` : "";
+  return `${theme.fg("dim", "│  ")} ${statusIcon(agent.status, theme)} ${theme.fg(agentLabelColor(agent), agent.label)}${activity}`;
+}
+
+function footerLine(snapshot: WorkflowProgressSnapshot, theme: Theme): string | undefined {
+  const counters = snapshot.counters.slice(0, 4).map((counter) => `${counter.label} ${formatCount(counter.value)}`);
+  const latestLog = snapshot.logs[snapshot.logs.length - 1];
+  const parts = counters.length > 0 ? counters : [];
+  if (latestLog) parts.push(latestLog);
+  if (parts.length === 0) return undefined;
+  return `${theme.fg("dim", "└─")} ${theme.fg("dim", parts.join(" · "))}`;
+}

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

@@ -0,0 +1,263 @@
+import { AdvisoryCandidatesSchema, AdvisoryVerdictSchema, type AdvisoryCandidate, type AdvisoryFinding, type AdvisoryLocation, type AdvisoryReport, type AdvisoryVerdict } from "./advisory-schema.ts";
+import type { AgentOptions, WorkflowApi, WorkflowProgressEvent } from "./types.ts";
+
+export interface AdvisoryLens {
+  label: string;
+  category: string;
+  text: string;
+}
+
+export type AdvisoryVerified<Candidate extends AdvisoryCandidate = AdvisoryCandidate> = Candidate & {
+  verdict: AdvisoryVerdict["verdict"];
+  evidence: string[];
+  confidence?: AdvisoryVerdict["confidence"];
+};
+
+export interface LensVerificationPipelineResult<Verified> {
+  verified: Verified[];
+  rawCandidates: number;
+  dropped: number;
+  refuted: number;
+}
+
+const DEFAULT_ADVISORY_TOOLS = ["read", "bash"];
+
+export type AdvisorySchedulingMode = "pipeline" | "finder-barrier";
+
+export interface LensVerificationPipelineOptions<Lens extends AdvisoryLens, Verified extends AdvisoryVerified> {
+  api: Pick<WorkflowApi, "agent" | "parallel" | "pipeline" | "progress" | "log">;
+  lenses: readonly Lens[];
+  perLens: number;
+  tools?: AgentOptions["tools"];
+  finderPhase?: string;
+  verifierPhase?: string;
+  schedulingMode?: AdvisorySchedulingMode;
+  finderPrompt(lens: Lens): string;
+  verifierPrompt(candidate: AdvisoryCandidate): string;
+  makeVerified(candidate: AdvisoryCandidate, lens: Lens, verdict: AdvisoryVerdict): Verified;
+}
+
+export interface AdvisoryBackfillDefaults {
+  impact: string;
+  recommendation?: string;
+}
+
+interface FoundForLens<Lens> {
+  lens: Lens;
+  candidates: AdvisoryCandidate[];
+}
+
+interface NovelCandidate<Lens> {
+  lens: Lens;
+  candidate: AdvisoryCandidate;
+}
+
+export async function runLensVerificationPipeline<Lens extends AdvisoryLens, Verified extends AdvisoryVerified>(
+  options: LensVerificationPipelineOptions<Lens, Verified>,
+): Promise<LensVerificationPipelineResult<Verified>> {
+  const {
+    api,
+    lenses,
+    perLens,
+    tools = DEFAULT_ADVISORY_TOOLS,
+    finderPhase = "Find",
+    verifierPhase = "Verify",
+    schedulingMode = "pipeline",
+    finderPrompt,
+    verifierPrompt,
+    makeVerified,
+  } = options;
+  const seen = new Set<string>();
+  let rawCandidates = 0;
+  let dropped = 0;
+  let refuted = 0;
+
+  const findForLens = async (lens: Lens): Promise<FoundForLens<Lens>> => {
+    const found = await api.agent(finderPrompt(lens), {
+      phase: finderPhase,
+      label: `find:${lens.label}`,
+      tools,
+      thinkingLevel: "low",
+      schema: AdvisoryCandidatesSchema,
+    });
+    const candidates = (found?.candidates ?? []).slice(0, perLens);
+    rawCandidates += candidates.length;
+    api.progress({ type: "counter_delta", key: "candidates", label: "candidates", delta: candidates.length });
+    for (const candidate of candidates) {
+      api.progress({
+        type: "lane_item",
+        lane: "Candidates",
+        title: candidate.summary,
+        subtitle: formatLocation(candidate),
+        status: "pending",
+        details: candidate.impact,
+      });
+    }
+    return { lens, candidates };
+  };
+
+  const dedupeFound = (found: FoundForLens<Lens>): NovelCandidate<Lens>[] => {
+    const novel = candidatesNovelToRun(found.candidates, seen).map((candidate) => ({ lens: found.lens, candidate }));
+    const droppedForLens = found.candidates.length - novel.length;
+    if (droppedForLens > 0) {
+      dropped += droppedForLens;
+      api.progress({ type: "counter_delta", key: "dropped", label: "dropped", delta: droppedForLens });
+      api.log(`find:${found.lens.label}: dropped ${droppedForLens} duplicate candidate(s)`);
+    }
+    return novel;
+  };
+
+  const verifyCandidate = async ({ lens, candidate }: NovelCandidate<Lens>): Promise<Verified | null> => {
+    const location = primaryLocation(candidate);
+    const judged = await api.agent(verifierPrompt(candidate), {
+      phase: verifierPhase,
+      label: `verify:${location.file.split("/").pop() ?? location.file}`,
+      tools,
+      thinkingLevel: "low",
+      schema: AdvisoryVerdictSchema,
+    });
+    if (!judged) return null;
+    recordVerdictProgress(api.progress, candidate, judged, () => {
+      refuted += 1;
+    });
+    return makeVerified(candidate, lens, judged);
+  };
+
+  if (schedulingMode === "finder-barrier") {
+    const found = await api.parallel(lenses.map((lens) => async () => findForLens(lens)));
+    const novel = found.flatMap(dedupeFound);
+    const verdicts = await api.parallel(novel.map((entry) => async () => verifyCandidate(entry)));
+    return { verified: verdicts.filter((value): value is Verified => value !== null), rawCandidates, dropped, refuted };
+  }
+
+  const perLensVerified = await api.pipeline(
+    lenses,
+    async (_prev, lens) => findForLens(lens),
+    async (found) => {
+      const novel = dedupeFound(found);
+      const verdicts = await api.parallel(novel.map((entry) => async () => verifyCandidate(entry)));
+      return verdicts.filter((value): value is Verified => value !== null);
+    },
+  );
+
+  return { verified: perLensVerified.flat(), rawCandidates, dropped, refuted };
+}
+
+function candidatesNovelToRun(candidates: readonly AdvisoryCandidate[], seen: Set<string>): AdvisoryCandidate[] {
+  return candidates.filter((candidate) => {
+    const key = advisoryDedupKey(candidate);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+export function primaryLocation(candidate: Pick<AdvisoryCandidate, "locations">): AdvisoryLocation {
+  return candidate.locations[0] ?? { file: "" };
+}
+
+export function formatLocation(candidate: Pick<AdvisoryCandidate, "locations">): string {
+  const location = primaryLocation(candidate);
+  const line = location.line != null ? `:${location.line}` : "";
+  const symbol = location.symbol ? ` (${location.symbol})` : "";
+  return `${location.file}${line}${symbol}`;
+}
+
+export function formatEvidence(evidence: readonly string[]): string {
+  return evidence.join("; ");
+}
+
+export function normalizePath(path: string): string {
+  return path.replace(/^\.\//, "").replace(/^[ab]\//, "");
+}
+
+export function advisoryDedupKey(candidate: AdvisoryCandidate): string {
+  const location = primaryLocation(candidate);
+  const lineKey = location.line != null ? Math.round(location.line / 5) * 5 : "file";
+  return `${candidate.category}:${normalizePath(location.file)}:${lineKey}:${candidate.summary.slice(0, 60).toLowerCase()}`;
+}
+
+export function verdictLane(verdict: AdvisoryVerdict["verdict"]): string {
+  switch (verdict) {
+    case "CONFIRMED":
+      return "Confirmed";
+    case "PLAUSIBLE":
+      return "Plausible";
+    case "REFUTED":
+      return "Refuted";
+  }
+}
+
+export function verdictStatus(verdict: AdvisoryVerdict["verdict"]): "success" | "warning" | "error" {
+  switch (verdict) {
+    case "CONFIRMED":
+      return "success";
+    case "PLAUSIBLE":
+      return "warning";
+    case "REFUTED":
+      return "error";
+  }
+}
+
+export function verdictConfidence(verdict: AdvisoryVerdict["verdict"]): "high" | "medium" | "low" {
+  switch (verdict) {
+    case "CONFIRMED":
+      return "high";
+    case "PLAUSIBLE":
+      return "medium";
+    case "REFUTED":
+      return "low";
+  }
+}
+
+export function sameFinding(candidate: Pick<AdvisoryCandidate, "locations">, finding: Pick<AdvisoryFinding, "locations" | "summary">): boolean {
+  return findingLocationKey(candidate) === findingLocationKey(finding);
+}
+
+export function findingLocationKey(value: Pick<AdvisoryCandidate, "locations"> | Pick<AdvisoryFinding, "locations">): string {
+  const location = primaryLocation(value);
+  return `${normalizePath(location.file)}:${location.line ?? "file"}`;
+}
+
+export function recordVerdictProgress(
+  progress: (event: WorkflowProgressEvent) => void,
+  candidate: Pick<AdvisoryCandidate, "locations" | "summary">,
+  verdict: Pick<AdvisoryVerdict, "verdict" | "evidence">,
+  onRefuted?: () => void,
+): void {
+  progress({ type: "counter_delta", key: `verdict.${verdict.verdict.toLowerCase()}`, label: verdict.verdict, delta: 1 });
+  if (verdict.verdict === "REFUTED") {
+    onRefuted?.();
+    progress({ type: "counter_delta", key: "refuted", label: "refuted", delta: 1 });
+  }
+  progress({
+    type: "lane_item",
+    lane: verdictLane(verdict.verdict),
+    title: candidate.summary,
+    subtitle: formatLocation(candidate),
+    status: verdictStatus(verdict.verdict),
+    details: formatEvidence(verdict.evidence),
+  });
+}
+
+export function backfillAdvisoryFindings<Source extends AdvisoryVerified>(
+  findings: AdvisoryReport["findings"],
+  ranked: readonly Source[],
+  defaults: AdvisoryBackfillDefaults,
+): AdvisoryReport["findings"] {
+  const rankedByLocation = new Map<string, Source>();
+  for (const candidate of ranked) {
+    const key = findingLocationKey(candidate);
+    if (!rankedByLocation.has(key)) rankedByLocation.set(key, candidate);
+  }
+
+  return findings.map((finding) => {
+    const source = rankedByLocation.get(findingLocationKey(finding));
+    return {
+      ...finding,
+      evidence: finding.evidence.length > 0 ? finding.evidence : (source?.evidence ?? []),
+      impact: finding.impact || source?.impact || defaults.impact,
+      recommendation: finding.recommendation || source?.recommendation || defaults.recommendation || "",
+    };
+  });
+}

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

@@ -0,0 +1,24 @@
+import type { WorkflowModule } from "./types.ts";
+import * as codeReview from "../workflows/code-review.ts";
+import * as ping from "../workflows/ping.ts";
+import * as refactorScout from "../workflows/refactor-scout.ts";
+import * as diagnose from "../workflows/diagnose.ts";
+import * as perfReview from "../workflows/perf-review.ts";
+
+/**
+ * Workflows statically imported by the extension. These are loaded through pi's own
+ * jiti instance (because they're part of the extension's module graph), so they share
+ * pi's bundled `typebox` / SDK — guaranteeing schema validation works.
+ *
+ * To add a guaranteed workflow: drop a `.ts` in `workflows/`, import it here, and add
+ * it to this array. (Drop-in workflows discovered at runtime are also supported — see
+ * discovery.ts — but the static registry is the always-correct path.)
+ *
+ * Do not replace these built-in imports with dynamic imports unless a dedicated test
+ * proves pi's jiti virtual modules preserve the same bundled `typebox` identity for
+ * dynamically imported built-ins. Startup optimizations should happen at the extension
+ * entrypoint/discovery boundary first.
+ */
+export const BUILTIN_WORKFLOWS: WorkflowModule[] = [codeReview, ping, refactorScout, diagnose, perfReview];
+export const BUILTIN_WORKFLOW_FILES = new Set(["code-review.ts", "ping.ts", "refactor-scout.ts", "diagnose.ts", "perf-review.ts"]);
+export const BUILTIN_WORKFLOW_NAMES = BUILTIN_WORKFLOWS.map((mod) => mod.meta.name);