@jameslovespancakes/pi-plus 1.0.11 → 1.0.12

package/src/domains/workflows/runtime/ui/workflow-widget.ts

@@ -0,0 +1,78 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { AgentRowSnapshot, WorkflowProgressSnapshot } from "../progress-types.ts";
+import { formatWorkflowUsageLine } from "../usage.ts";
+import { formatDuration, statusIcon } from "./workflow-format.ts";
+import { toDisplayLine } from "./display-text.ts";
+
+const MAX_WIDGET_LINES = 9;
+
+/** Compact live board shown above the editor. */
+export function renderWorkflowWidgetLines(snapshot: WorkflowProgressSnapshot, theme: Theme): string[] {
+  const agents = snapshot.phases.flatMap((phase) => phase.agents);
+  const ordered = [...agents].sort((left, right) => statusOrder(left.status) - statusOrder(right.status));
+  const counts = countAgents(agents);
+  const elapsed = formatDuration((snapshot.doneAt ?? Date.now()) - snapshot.startedAt);
+  const active = counts.running + counts.queued;
+  const icon = active > 0 ? theme.fg("accent", "●") : theme.fg("success", "✓");
+  const summary = [
+    `${counts.running} running`,
+    `${counts.queued} queued`,
+    `${counts.done}/${counts.total} done`,
+    ...(counts.failed > 0 ? [`${counts.failed} failed`] : []),
+    elapsed,
+  ].join(` ${theme.fg("dim", "·")} `);
+  const lines = [
+    `${icon} ${theme.bold(snapshot.title)} ${theme.fg("dim", `· ${snapshot.currentPhase} · ${summary}`)}`,
+  ];
+
+  const footer = footerLine(snapshot, theme);
+  const bodyLimit = Math.max(0, MAX_WIDGET_LINES - lines.length - 1);
+  for (const agent of ordered.slice(0, bodyLimit)) lines.push(agentLine(agent, theme));
+  const hidden = ordered.length - Math.min(ordered.length, bodyLimit);
+  if (hidden > 0 && lines.length < MAX_WIDGET_LINES) {
+    lines.push(theme.fg("dim", `  +${hidden} more · /workflow`));
+  } else if (footer && lines.length < MAX_WIDGET_LINES) {
+    lines.push(footer);
+  }
+  return lines.map((line) => line.replace(/[\r\n]+/g, " "));
+}
+
+interface AgentCounts {
+  queued: number;
+  running: number;
+  done: number;
+  failed: number;
+  total: number;
+}
+
+function countAgents(agents: readonly AgentRowSnapshot[]): AgentCounts {
+  const counts: AgentCounts = { queued: 0, running: 0, done: 0, failed: 0, total: agents.length };
+  for (const agent of agents) counts[agent.status]++;
+  return counts;
+}
+
+function statusOrder(status: AgentRowSnapshot["status"]): number {
+  return status === "running" ? 0 : status === "queued" ? 1 : status === "failed" ? 2 : 3;
+}
+
+function agentLine(agent: AgentRowSnapshot, theme: Theme): string {
+  const model = toDisplayLine(shortModel(agent.model ?? "host default"), 48);
+  const details: string[] = [];
+  if (agent.lastTool) details.push(toDisplayLine(agent.lastTool, 32));
+  if (agent.toolUses > 0) details.push(`${agent.toolUses} tool${agent.toolUses === 1 ? "" : "s"}`);
+  if (agent.startedAt !== undefined) details.push(formatDuration((agent.doneAt ?? Date.now()) - agent.startedAt));
+  const activity = details.length > 0 ? ` ${theme.fg("dim", `· ${details.join(" · ")}`)}` : "";
+  const color = agent.status === "failed" ? "error" : agent.status === "running" ? "text" : "muted";
+  return `  ${statusIcon(agent.status, theme)} ${theme.fg(color, toDisplayLine(agent.label, 64))} ${theme.fg("accent", model)}${activity}`;
+}
+
+function footerLine(snapshot: WorkflowProgressSnapshot, theme: Theme): string {
+  const usage = formatWorkflowUsageLine(snapshot.usage);
+  const latest = snapshot.logs.at(-1);
+  const parts = [usage, latest ? toDisplayLine(latest, 100) : undefined, "/workflow"].filter(Boolean);
+  return theme.fg("dim", `  ${parts.join(" · ")}`);
+}
+
+function shortModel(model: string): string {
+  return model.replace(/^openai-codex\//, "codex/").replace(/^anthropic\//, "");
+}

package/src/domains/workflows/runtime/unknown-error.ts

@@ -0,0 +1,8 @@
+/** Read an unknown thrown value without allowing hostile coercion to mask the original failure. */
+export function unknownErrorMessage(error: unknown): string {
+  try {
+    return error instanceof Error ? error.message : String(error);
+  } catch {
+    return "unknown error";
+  }
+}

package/src/domains/workflows/runtime/usage.ts

@@ -0,0 +1,341 @@
+export interface WorkflowUsageCost {
+  readonly input: number;
+  readonly output: number;
+  readonly cacheRead: number;
+  readonly cacheWrite: number;
+  readonly total: number;
+}
+
+export type WorkflowUsageCoverage = "none" | "partial" | "complete";
+
+export interface WorkflowUsageComponentCoverage {
+  readonly input: WorkflowUsageCoverage;
+  readonly output: WorkflowUsageCoverage;
+  readonly cacheRead: WorkflowUsageCoverage;
+  readonly cacheWrite: WorkflowUsageCoverage;
+}
+
+export interface WorkflowUsageTotals {
+  readonly input: number;
+  readonly output: number;
+  readonly cacheRead: number;
+  readonly cacheWrite: number;
+  readonly totalTokens: number;
+  readonly coverage: WorkflowUsageComponentCoverage;
+  readonly cost: WorkflowUsageCost;
+}
+
+export interface WorkflowAgentUsage {
+  readonly label: string;
+  readonly phase?: string;
+  readonly provider?: string;
+  readonly model?: string;
+  readonly assistantMessages: number;
+  readonly usage: WorkflowUsageTotals;
+}
+
+export interface WorkflowUsageSnapshot {
+  readonly agents: readonly WorkflowAgentUsage[];
+  readonly totals: WorkflowUsageTotals;
+  readonly assistantMessages: number;
+}
+
+export interface WorkflowUsageSink {
+  recordAgentSession(input: { label: string; phase?: string; messages: readonly unknown[] }): void;
+  snapshot(): WorkflowUsageSnapshot;
+}
+
+const ZERO_COST: WorkflowUsageCost = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
+const ZERO_COVERAGE: WorkflowUsageComponentCoverage = {
+  input: "none",
+  output: "none",
+  cacheRead: "none",
+  cacheWrite: "none",
+};
+const ZERO_TOTALS: WorkflowUsageTotals = {
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+  totalTokens: 0,
+  coverage: ZERO_COVERAGE,
+  cost: ZERO_COST,
+};
+
+interface AssistantUsageMessage {
+  readonly provider?: string;
+  readonly model?: string;
+  readonly usage: WorkflowUsageTotals;
+}
+
+export class WorkflowUsageRecorder implements WorkflowUsageSink {
+  private readonly agents: WorkflowAgentUsage[] = [];
+  private readonly onSnapshot?: (snapshot: WorkflowUsageSnapshot) => void;
+
+  constructor(onSnapshot?: (snapshot: WorkflowUsageSnapshot) => void) {
+    this.onSnapshot = onSnapshot;
+  }
+
+  recordAgentSession(input: { label: string; phase?: string; messages: readonly unknown[] }): void {
+    const assistantMessages = input.messages.flatMap((message) => {
+      const parsed = parseAssistantUsageMessage(message);
+      return parsed ? [parsed] : [];
+    });
+    if (assistantMessages.length === 0) return;
+
+    const usage = sumTotals(assistantMessages.map((message) => message.usage));
+    const latestMetadata = assistantMessages.findLast((message) => message.provider !== undefined || message.model !== undefined);
+    this.agents.push({
+      label: input.label,
+      phase: input.phase,
+      provider: latestMetadata?.provider,
+      model: latestMetadata?.model,
+      assistantMessages: assistantMessages.length,
+      usage,
+    });
+    this.onSnapshot?.(this.snapshot());
+  }
+
+  snapshot(): WorkflowUsageSnapshot {
+    const agents = this.agents.map((agent) => ({
+      ...agent,
+      usage: cloneTotals(agent.usage),
+    }));
+    return {
+      agents,
+      totals: sumTotals(agents.map((agent) => agent.usage)),
+      assistantMessages: agents.reduce((sum, agent) => sum + agent.assistantMessages, 0),
+    };
+  }
+}
+
+export function createWorkflowUsageRecorder(onSnapshot?: (snapshot: WorkflowUsageSnapshot) => void): WorkflowUsageSink {
+  return new WorkflowUsageRecorder(onSnapshot);
+}
+
+export function emptyWorkflowUsageTotals(): WorkflowUsageTotals {
+  return cloneTotals(ZERO_TOTALS);
+}
+
+export function isWorkflowUsageSnapshot(value: unknown): value is WorkflowUsageSnapshot {
+  if (!isRecord(value)) return false;
+  if (!Array.isArray(value.agents) || !value.agents.every(isWorkflowAgentUsage)) return false;
+  if (!isWorkflowUsageTotals(value.totals)) return false;
+  return finiteNumber(value.assistantMessages) !== undefined;
+}
+
+export function hasWorkflowUsage(snapshot: unknown): snapshot is WorkflowUsageSnapshot {
+  if (!isWorkflowUsageSnapshot(snapshot)) return false;
+  return snapshot.totals.totalTokens > 0 || snapshot.totals.cost.total > 0;
+}
+
+export function formatWorkflowUsageLine(snapshot: unknown): string | undefined {
+  if (!hasWorkflowUsage(snapshot)) return undefined;
+  const parts = formatWorkflowUsageComponents(snapshot.totals);
+  parts.push(`cost $${snapshot.totals.cost.total.toFixed(3)}`);
+  parts.push(`agents ${snapshot.agents.length}`);
+  return `Usage: ${parts.join(" · ")}`;
+}
+
+function formatWorkflowUsageComponents(totals: WorkflowUsageTotals): string[] {
+  const parts: string[] = [];
+  const completeCacheBreakdown =
+    totals.coverage.cacheRead === "complete" && totals.coverage.cacheWrite === "complete";
+  appendUsageComponent(parts, completeCacheBreakdown ? "fresh" : "input", totals.input, totals.coverage.input);
+  appendUsageComponent(parts, "cache read", totals.cacheRead, totals.coverage.cacheRead);
+  appendUsageComponent(parts, "cache write", totals.cacheWrite, totals.coverage.cacheWrite);
+  appendUsageComponent(parts, "output", totals.output, totals.coverage.output);
+
+  const knownComponents = totals.input + totals.output + totals.cacheRead + totals.cacheWrite;
+  if (parts.length === 0 && totals.totalTokens > 0) parts.push(`tokens ${formatUsageCount(totals.totalTokens)}`);
+  else if (!hasCompleteCoverage(totals.coverage) && totals.totalTokens !== knownComponents) {
+    parts.push(`total ${formatUsageCount(totals.totalTokens)}`);
+  }
+  return parts;
+}
+
+function appendUsageComponent(
+  parts: string[],
+  label: string,
+  value: number,
+  coverage: WorkflowUsageCoverage,
+): void {
+  if (value <= 0 || coverage === "none") return;
+  const count = formatUsageCount(value);
+  parts.push(`${label} ${coverage === "partial" ? `≥${count}` : count}`);
+}
+
+function isWorkflowAgentUsage(value: unknown): value is WorkflowAgentUsage {
+  if (!isRecord(value)) return false;
+  if (typeof value.label !== "string") return false;
+  if (value.phase !== undefined && typeof value.phase !== "string") return false;
+  if (value.provider !== undefined && typeof value.provider !== "string") return false;
+  if (value.model !== undefined && typeof value.model !== "string") return false;
+  if (finiteNumber(value.assistantMessages) === undefined) return false;
+  return isWorkflowUsageTotals(value.usage);
+}
+
+function isWorkflowUsageTotals(value: unknown): value is WorkflowUsageTotals {
+  if (!isRecord(value)) return false;
+  if (finiteNumber(value.input) === undefined) return false;
+  if (finiteNumber(value.output) === undefined) return false;
+  if (finiteNumber(value.cacheRead) === undefined) return false;
+  if (finiteNumber(value.cacheWrite) === undefined) return false;
+  if (finiteNumber(value.totalTokens) === undefined) return false;
+  if (!isWorkflowUsageCoverage(value.coverage)) return false;
+  return isWorkflowUsageCost(value.cost);
+}
+
+function isWorkflowUsageCoverage(value: unknown): value is WorkflowUsageComponentCoverage {
+  if (!isRecord(value)) return false;
+  return (
+    isCoverageValue(value.input) &&
+    isCoverageValue(value.output) &&
+    isCoverageValue(value.cacheRead) &&
+    isCoverageValue(value.cacheWrite)
+  );
+}
+
+function isWorkflowUsageCost(value: unknown): value is WorkflowUsageCost {
+  if (!isRecord(value)) return false;
+  return (
+    finiteNumber(value.input) !== undefined &&
+    finiteNumber(value.output) !== undefined &&
+    finiteNumber(value.cacheRead) !== undefined &&
+    finiteNumber(value.cacheWrite) !== undefined &&
+    finiteNumber(value.total) !== undefined
+  );
+}
+
+function parseAssistantUsageMessage(message: unknown): AssistantUsageMessage | undefined {
+  if (!isRecord(message)) return undefined;
+  if (message.role !== "assistant") return undefined;
+  const usage = parseUsageTotals(message.usage);
+  if (!usage) return undefined;
+  return {
+    provider: typeof message.provider === "string" ? message.provider : undefined,
+    model: typeof message.model === "string" ? message.model : undefined,
+    usage,
+  };
+}
+
+function parseUsageTotals(value: unknown): WorkflowUsageTotals | undefined {
+  if (!isRecord(value)) return undefined;
+  const input = finiteNumber(value.input);
+  const output = finiteNumber(value.output);
+  const cacheRead = finiteNumber(value.cacheRead);
+  const cacheWrite = finiteNumber(value.cacheWrite);
+  const reportedTotal = finiteNumber(value.totalTokens);
+  const cost = parseUsageCost(value.cost);
+  if (!cost) return undefined;
+  if (input === undefined && output === undefined && cacheRead === undefined && cacheWrite === undefined && reportedTotal === undefined) {
+    return undefined;
+  }
+  const coverage: WorkflowUsageComponentCoverage = {
+    input: input === undefined ? "none" : "complete",
+    output: output === undefined ? "none" : "complete",
+    cacheRead: cacheRead === undefined ? "none" : "complete",
+    cacheWrite: cacheWrite === undefined ? "none" : "complete",
+  };
+  const componentTotal = (input ?? 0) + (output ?? 0) + (cacheRead ?? 0) + (cacheWrite ?? 0);
+  return {
+    input: input ?? 0,
+    output: output ?? 0,
+    cacheRead: cacheRead ?? 0,
+    cacheWrite: cacheWrite ?? 0,
+    totalTokens: hasCompleteCoverage(coverage) ? componentTotal : (reportedTotal ?? componentTotal),
+    coverage,
+    cost,
+  };
+}
+
+function parseUsageCost(value: unknown): WorkflowUsageCost | undefined {
+  if (!isRecord(value)) return undefined;
+  const input = finiteNumber(value.input);
+  const output = finiteNumber(value.output);
+  const cacheRead = finiteNumber(value.cacheRead);
+  const cacheWrite = finiteNumber(value.cacheWrite);
+  const total = finiteNumber(value.total);
+  if (total === undefined) return undefined;
+  return {
+    input: input ?? 0,
+    output: output ?? 0,
+    cacheRead: cacheRead ?? 0,
+    cacheWrite: cacheWrite ?? 0,
+    total,
+  };
+}
+
+function sumTotals(values: readonly WorkflowUsageTotals[]): WorkflowUsageTotals {
+  const [first, ...rest] = values;
+  if (!first) return emptyWorkflowUsageTotals();
+  return rest.reduce(addTotals, cloneTotals(first));
+}
+
+function addTotals(left: WorkflowUsageTotals, right: WorkflowUsageTotals): WorkflowUsageTotals {
+  return {
+    input: left.input + right.input,
+    output: left.output + right.output,
+    cacheRead: left.cacheRead + right.cacheRead,
+    cacheWrite: left.cacheWrite + right.cacheWrite,
+    totalTokens: left.totalTokens + right.totalTokens,
+    coverage: {
+      input: combineCoverage(left.coverage.input, right.coverage.input),
+      output: combineCoverage(left.coverage.output, right.coverage.output),
+      cacheRead: combineCoverage(left.coverage.cacheRead, right.coverage.cacheRead),
+      cacheWrite: combineCoverage(left.coverage.cacheWrite, right.coverage.cacheWrite),
+    },
+    cost: {
+      input: left.cost.input + right.cost.input,
+      output: left.cost.output + right.cost.output,
+      cacheRead: left.cost.cacheRead + right.cost.cacheRead,
+      cacheWrite: left.cost.cacheWrite + right.cost.cacheWrite,
+      total: left.cost.total + right.cost.total,
+    },
+  };
+}
+
+function cloneTotals(value: WorkflowUsageTotals): WorkflowUsageTotals {
+  return {
+    input: value.input,
+    output: value.output,
+    cacheRead: value.cacheRead,
+    cacheWrite: value.cacheWrite,
+    totalTokens: value.totalTokens,
+    coverage: { ...value.coverage },
+    cost: { ...value.cost },
+  };
+}
+
+function combineCoverage(left: WorkflowUsageCoverage, right: WorkflowUsageCoverage): WorkflowUsageCoverage {
+  return left === right ? left : "partial";
+}
+
+function hasCompleteCoverage(coverage: WorkflowUsageComponentCoverage): boolean {
+  return (
+    coverage.input === "complete" &&
+    coverage.output === "complete" &&
+    coverage.cacheRead === "complete" &&
+    coverage.cacheWrite === "complete"
+  );
+}
+
+function isCoverageValue(value: unknown): value is WorkflowUsageCoverage {
+  return value === "none" || value === "partial" || value === "complete";
+}
+
+function formatUsageCount(count: number): string {
+  if (count < 1000) return count.toString();
+  if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
+  if (count < 1000000) return `${Math.round(count / 1000)}k`;
+  if (count < 10000000) return `${(count / 1000000).toFixed(1)}M`;
+  return `${Math.round(count / 1000000)}M`;
+}
+
+function finiteNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/src/domains/workflows/runtime/workflow-advisory-utils.ts

@@ -0,0 +1,245 @@
+import { AdvisoryCandidatesSchema, AdvisoryVerdictSchema, type AdvisoryCandidate, type IdentifiedAdvisoryCandidate, type AdvisoryLocation, type AdvisoryReport, type AdvisoryVerdict } from "./advisory-schema.ts";
+import { AdvisorySynthesisSchema, SYNTHESIS_ID_INSTRUCTIONS, withAdvisoryCoverage, collectAdvisoryStage, dedupeCandidates, identifyCandidates, uniqueLocations, type AdvisoryStageCoverage, type AdvisorySynthesis } from "./advisory-evidence.ts";
+import type { AgentOptions, WorkflowApi, WorkflowProgressEvent, WorkflowRunStats } from "./types.ts";
+
+export interface AdvisoryLens {
+  label: string;
+  category: string;
+  text: string;
+}
+
+export type AdvisoryVerified = IdentifiedAdvisoryCandidate & {
+  verdict: AdvisoryVerdict["verdict"];
+  evidence: string[];
+  confidence?: AdvisoryVerdict["confidence"];
+  challenge?: import("./advisory-challenge.ts").ChallengeRecord;
+};
+
+export interface LensVerificationPipelineResult {
+  verified: AdvisoryVerified[];
+  rawCandidates: number;
+  dropped: number;
+  refuted: number;
+  coverage: AdvisoryStageCoverage[];
+}
+
+/** Default concrete read/inspect tools for advisory workflows. */
+export const DEFAULT_ADVISORY_TOOLS: NonNullable<AgentOptions["tools"]> = ["read", "bash", "grep", "find", "ls"];
+
+/** Dynamically include installed grep/find/search-like extension tools. */
+export const DEFAULT_ADVISORY_TOOL_HINTS: NonNullable<AgentOptions["toolHints"]> = ["search"];
+
+export function emptyAdvisoryReport<Stats extends WorkflowRunStats>(
+  summary: string,
+  nextSteps: string[],
+  stats: Stats,
+): AdvisoryReport & { stats: Stats } {
+  return { summary, findings: [], nextSteps, stats };
+}
+
+export function publishVerifiedKeptProgress(
+  api: Pick<WorkflowApi, "progress" | "log">,
+  verified: number,
+  kept: number,
+): void {
+  api.progress({ type: "counter", key: "verified", label: "verified", value: verified });
+  api.progress({ type: "counter", key: "kept", label: "kept", value: kept });
+  api.progress({ type: "summary", key: "verified", value: verified });
+  api.progress({ type: "summary", key: "kept", value: kept });
+  api.log(`${verified} verified → ${kept} kept`);
+}
+
+export interface LensVerificationPipelineOptions {
+  api: Pick<WorkflowApi, "agent" | "parallel" | "phase" | "progress" | "log">;
+  lenses: readonly AdvisoryLens[];
+  perLens: number;
+  finderPhase?: "Find" | "Hypothesize";
+  finderPrompt(lens: AdvisoryLens): string;
+  verifierPrompt(candidate: IdentifiedAdvisoryCandidate): string;
+  boundCandidate?(candidate: IdentifiedAdvisoryCandidate, lens: AdvisoryLens): IdentifiedAdvisoryCandidate | undefined;
+}
+
+export interface AdvisoryBackfillDefaults {
+  impact: string;
+  recommendation?: string;
+}
+
+/** Finish all discovery before verification competes for the shared agent limit. */
+export async function runLensVerificationPipeline(
+  options: LensVerificationPipelineOptions,
+): Promise<LensVerificationPipelineResult> {
+  const { api, lenses, perLens, finderPhase = "Find", finderPrompt, verifierPrompt, boundCandidate } = options;
+  const coverage: AdvisoryStageCoverage[] = [];
+  let rawCandidates = 0;
+  let refuted = 0;
+  api.phase(finderPhase);
+  const found = await collectAdvisoryStage(api, "Find", lenses.map((lens) => ({ id: lens.label, run: async () => {
+    const result = await api.agent(finderPrompt(lens), {
+      phase: finderPhase, label: `${finderPhase.toLowerCase()}:${lens.label}`,
+      tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS,
+      profile: "small", schema: AdvisoryCandidatesSchema,
+    });
+    const raw = identifyCandidates(result.candidates.slice(0, perLens), lens.label);
+    rawCandidates += raw.length;
+    api.progress({ type: "counter_delta", key: "candidates", label: "candidates", delta: raw.length });
+    const candidates = boundCandidate ? raw.flatMap((candidate) => {
+      const bounded = boundCandidate(candidate, lens);
+      return bounded ? [bounded] : [];
+    }) : raw;
+    for (const candidate of candidates) {
+      api.progress({ type: "lane_item", lane: finderPhase === "Hypothesize" ? "Hypotheses" : "Candidates",
+        title: candidate.summary, subtitle: formatLocation(candidate), status: "pending", details: candidate.impact });
+    }
+    return candidates;
+  } })), coverage);
+  const candidates = dedupeCandidates(found.flat());
+  const dropped = rawCandidates - candidates.length;
+  if (dropped > 0) {
+    api.progress({ type: "counter_delta", key: "dropped", label: "dropped", delta: dropped });
+    api.log(`Dropped ${dropped} duplicate or out-of-scope candidate(s)`);
+  }
+  api.phase("Verify");
+  const verified = await collectAdvisoryStage(api, "Verify", candidates.map((candidate) => ({
+    id: candidate.candidateId, candidate, run: async (): Promise<AdvisoryVerified> => {
+      const location = primaryLocation(candidate);
+      const judged = await api.agent(`${verifierPrompt(candidate)}\nCandidate record: ${JSON.stringify(candidate)}`, {
+        phase: "Verify", label: `verify:${location.file.split("/").pop() ?? location.file}`,
+        tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS,
+        profile: "small", schema: AdvisoryVerdictSchema,
+      });
+      recordVerdictProgress(api.progress, candidate, judged, () => { refuted += 1; });
+      return { ...candidate, verdict: judged.verdict, evidence: judged.evidence, confidence: judged.confidence };
+    },
+  })), coverage);
+  return { verified, rawCandidates, dropped, refuted, coverage };
+}
+
+export async function synthesizeAdvisoryReport(
+  api: Pick<WorkflowApi, "agent" | "parallel" | "phase">,
+  prompt: string,
+  ranked: readonly AdvisoryVerified[],
+  coverage: AdvisoryStageCoverage[],
+): Promise<AdvisoryReport> {
+  api.phase("Synthesize");
+  const [report] = await collectAdvisoryStage(api, "Synthesize", [{ id: "synthesize", run: () => api.agent(
+    SYNTHESIS_ID_INSTRUCTIONS + prompt,
+    { phase: "Synthesize", label: "synthesize", tools: [], profile: "medium", resume: "read-only", schema: AdvisorySynthesisSchema },
+  ) }], coverage);
+  return resolveAdvisorySynthesis(report, ranked, {
+    impact: "Impact not restated by verification.",
+    recommendation: "Inspect the cited evidence and validate the smallest repair.",
+  }, coverage);
+}
+
+export function finishAdvisoryReport<T extends AdvisoryReport>(
+  report: T, coverage: AdvisoryStageCoverage[], verification: AdvisoryVerified[] = [],
+) {
+  return { ...withAdvisoryCoverage(report, coverage), verification };
+}
+
+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]\//, "");
+}
+
+const VERDICT_PRESENTATION = {
+  CONFIRMED: { lane: "Confirmed", status: "success", confidence: "high" },
+  PLAUSIBLE: { lane: "Plausible", status: "warning", confidence: "medium" },
+  NOT_SUBSTANTIATED: { lane: "Unresolved", status: "warning", confidence: "medium" },
+  REFUTED: { lane: "Refuted", status: "error", confidence: "low" },
+} satisfies Record<AdvisoryVerdict["verdict"], {
+  lane: string; status: "success" | "warning" | "error"; confidence: NonNullable<AdvisoryVerdict["confidence"]>;
+}>;
+
+export function verdictConfidence(verdict: AdvisoryVerdict["verdict"]): "high" | "medium" | "low" {
+  return VERDICT_PRESENTATION[verdict].confidence;
+}
+
+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: VERDICT_PRESENTATION[verdict.verdict].lane,
+    title: candidate.summary,
+    subtitle: formatLocation(candidate),
+    status: VERDICT_PRESENTATION[verdict.verdict].status,
+    details: formatEvidence(verdict.evidence),
+  });
+}
+
+export function backfillAdvisoryFindings<Source extends AdvisoryVerified>(
+  findings: AdvisorySynthesis["findings"],
+  ranked: readonly Source[],
+  defaults: AdvisoryBackfillDefaults,
+): AdvisoryReport["findings"] {
+  const sources = new Map(ranked.flatMap((source) => source.sourceCandidateIds.map((id) => [id, source] as const)));
+  const used = new Set<string>();
+  return findings.flatMap((selection) => {
+    const ids = [...new Set(selection.sourceCandidateIds)];
+    if (ids.length === 0 || ids.some((id) => !sources.has(id) || used.has(id))) return [];
+    const records = [...new Set(ids.map((id) => sources.get(id)!))];
+    if (records.some((record) => record.verdict === "REFUTED")) return [];
+    const sourceCandidateIds = [...new Set(records.flatMap((record) => record.sourceCandidateIds))];
+    if (sourceCandidateIds.some((id) => used.has(id))) return [];
+    sourceCandidateIds.forEach((id) => used.add(id));
+    const first = records[0]!;
+    return [{
+      sourceCandidateIds,
+      summary: [...new Set(records.map((record) => record.summary))].join("; "),
+      category: first.category,
+      severity: selection.severity,
+      verdict: records.some((record) => record.verdict === "NOT_SUBSTANTIATED") ? "NOT_SUBSTANTIATED" as const : records.some((record) => record.verdict === "PLAUSIBLE") ? "PLAUSIBLE" as const : "CONFIRMED" as const,
+      confidence: records.every((record) => record.verdict === "CONFIRMED") ? "high" as const : "medium" as const,
+      locations: uniqueLocations(records.flatMap((record) => record.locations)),
+      ...(first.reviewAnchor ? { reviewAnchor: first.reviewAnchor } : {}),
+      evidence: [...new Set(records.flatMap((record) => [...(record.discoveryEvidence ?? []), ...record.evidence]))],
+      impact: [...new Set(records.map((record) => record.impact || defaults.impact))].join("\n"),
+      recommendation: selection.recommendation || first.recommendation || defaults.recommendation || "",
+    }];
+  });
+}
+
+/** Retain verified records if synthesis fails, and expose invalid ID selections as a gap. */
+export function resolveAdvisorySynthesis<Source extends AdvisoryVerified>(
+  report: AdvisorySynthesis | undefined,
+  ranked: readonly Source[],
+  defaults: AdvisoryBackfillDefaults,
+  coverage: AdvisoryStageCoverage[],
+): AdvisoryReport {
+  if (!report) {
+    return {
+      summary: "Synthesis unavailable; verified records retained.",
+      findings: backfillAdvisoryFindings(ranked.map((finding) => ({ sourceCandidateIds: finding.sourceCandidateIds, severity: "medium", recommendation: finding.recommendation ?? defaults.recommendation ?? "Inspect verifier evidence." })), ranked, defaults),
+      nextSteps: ["Inspect verifier evidence or rerun synthesis."],
+    };
+  }
+  const findings = backfillAdvisoryFindings(report.findings, ranked, defaults);
+  if (findings.length !== report.findings.length) {
+    coverage.push({ stage: "Synthesis provenance", expected: report.findings.length, completed: findings.length,
+      failed: report.findings.length - findings.length, failures: [{ branch: "synthesize", reason: "Discarded invalid, repeated, or unverified candidate IDs." }] });
+  }
+  return { ...report, findings };
+}