pi-workflow-engine 0.10.3 → 0.12.0

package/.pi/extensions/pi-workflow-engine/src/review/review-issues.ts

@@ -7,14 +7,6 @@ export interface ReviewIssueSelection {
   readonly issueIds: readonly string[];
 }
 
-export interface ReviewContext {
-  readonly workflowName: string;
-  readonly target: string;
-  readonly diffCommand: string;
-  readonly files: readonly string[];
-  readonly summary?: string;
-}
-
 export interface ReviewIssue {
   readonly id: string;
   readonly index: number;
@@ -25,9 +17,22 @@ export interface ReviewIssue {
   readonly finding: AdvisoryFinding;
 }
 
-export interface ReviewReportWithContext extends AdvisoryReport {
-  readonly stats?: Record<string, string | number>;
-  readonly reviewContext?: ReviewContext;
+/** Stable prompt-facing representation shared by review follow-up actions. */
+export interface SerializedReviewIssue {
+  readonly id: string;
+  readonly summary: string;
+  readonly category: string;
+  readonly severity: string;
+  readonly confidence: string;
+  readonly location: {
+    readonly file?: string;
+    readonly line?: number;
+    readonly symbol?: string;
+    readonly display: string;
+  };
+  readonly impact: string;
+  readonly evidence: readonly string[];
+  readonly recommendation: string;
 }
 
 export function toReviewIssues(name: string, report: Pick<AdvisoryReport, "findings">): ReviewIssue[] {
@@ -52,7 +57,28 @@ export function formatIssueLocation(issue: ReviewIssue): string {
   return `${issue.file}${line}${symbol}`;
 }
 
-export function isCommentableIssue(issue: ReviewIssue): boolean {
+export function serializeReviewIssue(issue: ReviewIssue): SerializedReviewIssue {
+  return {
+    id: issue.id,
+    summary: issue.finding.summary,
+    category: issue.finding.category,
+    severity: issue.finding.severity,
+    confidence: issue.finding.confidence,
+    location: {
+      file: issue.file,
+      line: issue.line,
+      symbol: issue.symbol,
+      display: formatIssueLocation(issue),
+    },
+    impact: issue.finding.impact,
+    evidence: issue.finding.evidence,
+    recommendation: issue.finding.recommendation,
+  };
+}
+
+export function isCommentableIssue(
+  issue: ReviewIssue,
+): issue is ReviewIssue & { readonly file: string; readonly line: number } {
   return typeof issue.file === "string" && issue.file.trim().length > 0 && typeof issue.line === "number" && Number.isFinite(issue.line);
 }
 

package/.pi/extensions/pi-workflow-engine/src/review/review-report.ts

@@ -0,0 +1,42 @@
+import { Type, type Static } from "typebox";
+import { Value } from "typebox/value";
+import { AdvisoryReportWithStatsSchema } from "../advisory-schema.ts";
+import { formatReviewDiffTarget, isReviewDiffTarget, ReviewDiffTargetSchema } from "../review-diff-target.ts";
+
+/** Atomic identity of the exact diff and post-change snapshot that were reviewed. */
+export const ReviewSnapshotIdentitySchema = Type.Object({
+  diffFingerprint: Type.String({ pattern: "^[0-9a-fA-F]{64}$" }),
+  baselineFingerprint: Type.String({ pattern: "^[0-9a-fA-F]{64}$" }),
+});
+
+export const ReviewContextSchema = Type.Object({
+  workflowName: Type.String(),
+  target: Type.String(),
+  diffTarget: ReviewDiffTargetSchema,
+  files: Type.Array(Type.String()),
+  summary: Type.Optional(Type.String()),
+  snapshot: Type.Optional(ReviewSnapshotIdentitySchema),
+});
+
+export const ReviewReportSchema = Type.Object({
+  ...AdvisoryReportWithStatsSchema.properties,
+  reviewContext: Type.Optional(ReviewContextSchema),
+});
+
+export type ReviewSnapshotIdentity = Static<typeof ReviewSnapshotIdentitySchema>;
+export type ReviewContext = Static<typeof ReviewContextSchema>;
+export type ReviewReport = Static<typeof ReviewReportSchema>;
+
+export function isReviewReport(value: unknown): value is ReviewReport {
+  if (!Value.Check(ReviewReportSchema, value)) return false;
+  return value.reviewContext === undefined || isReviewContext(value.reviewContext);
+}
+
+export function isReviewContext(value: unknown): value is ReviewContext {
+  return Value.Check(ReviewContextSchema, value) && isReviewDiffTarget(value.diffTarget);
+}
+
+/** Prompt-facing context retains the canonical display command without persisting duplicate identity. */
+export function serializeReviewContext(context: ReviewContext | undefined): (ReviewContext & { readonly diffCommand: string }) | undefined {
+  return context ? { ...context, diffCommand: formatReviewDiffTarget(context.diffTarget) } : undefined;
+}

package/.pi/extensions/pi-workflow-engine/src/review/review-results-flow.ts

@@ -1,15 +1,16 @@
-import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { WorkflowRunOptions } from "../types.ts";
-import { isAdvisoryReport, type AdvisoryWorkflowResult } from "../ui/workflow-result-renderer.ts";
 import { toReviewIssues, type ReviewIssue, type ReviewIssueSelection } from "./review-issues.ts";
+import { isReviewReport, type ReviewReport } from "./review-report.ts";
 import { ReviewResultsViewer } from "./review-results-viewer.ts";
+import { WORKFLOW_VIEWER_OVERLAY_OPTIONS } from "../ui/workflow-viewer-layout.ts";
 
 export type ReviewResultsPresentationDecision =
   | {
       readonly kind: "send";
-      readonly reason: "tool-invocation" | "not-code-review" | "not-advisory" | "no-findings" | "disabled" | "not-tui" | "not-requested";
+      readonly reason: "not-code-review" | "not-advisory" | "no-findings" | "disabled" | "not-tui" | "not-requested";
     }
-  | { readonly kind: "open"; readonly report: AdvisoryWorkflowResult; readonly issues: readonly ReviewIssue[]; readonly findingCount: number };
+  | { readonly kind: "open"; readonly issues: readonly ReviewIssue[] };
 
 export interface ReviewResultsDecisionInput {
   readonly workflowName: string;
@@ -17,40 +18,35 @@ export interface ReviewResultsDecisionInput {
   readonly mode?: string;
   readonly hasUI: boolean;
   readonly resultViewer?: WorkflowRunOptions["resultViewer"];
-  readonly invocationKind?: "command" | "tool";
 }
 
-export interface ReviewResultsViewerContext {
-  readonly ui: Pick<ExtensionCommandContext["ui"], "custom">;
+export function codeReviewReport(workflowName: string, result: unknown): ReviewReport | undefined {
+  return workflowName === "code-review" && isReviewReport(result) ? result : undefined;
 }
 
-export function extensionContextMode(ctx: ExtensionCommandContext): string | undefined {
-  const candidate = (ctx as ExtensionCommandContext & { readonly mode?: unknown }).mode;
-  return typeof candidate === "string" ? candidate : undefined;
+export interface ReviewResultsViewerContext {
+  readonly ui: Pick<ExtensionContext["ui"], "custom">;
 }
 
 export function decideReviewResultsPresentation(input: ReviewResultsDecisionInput): ReviewResultsPresentationDecision {
-  if (input.invocationKind === "tool") return { kind: "send", reason: "tool-invocation" };
   if (input.workflowName !== "code-review") return { kind: "send", reason: "not-code-review" };
-  if (!isAdvisoryReport(input.result)) return { kind: "send", reason: "not-advisory" };
-  if (input.result.findings.length === 0) return { kind: "send", reason: "no-findings" };
+  const report = codeReviewReport(input.workflowName, input.result);
+  if (!report) return { kind: "send", reason: "not-advisory" };
+  if (report.findings.length === 0) return { kind: "send", reason: "no-findings" };
   if (input.resultViewer === "skip") return { kind: "send", reason: "disabled" };
   if (input.mode !== "tui" || !input.hasUI) return { kind: "send", reason: "not-tui" };
 
   if (input.resultViewer !== "open") return { kind: "send", reason: "not-requested" };
 
-  const issues = toReviewIssues(input.workflowName, input.result);
-  return { kind: "open", report: input.result, issues, findingCount: issues.length };
+  return { kind: "open", issues: toReviewIssues(input.workflowName, report) };
 }
 
-export async function maybeShowReviewResultsViewer(
+export async function showReviewResultsViewer(
   ctx: ReviewResultsViewerContext,
-  decision: ReviewResultsPresentationDecision,
-): Promise<ReviewIssueSelection | undefined> {
-  if (decision.kind !== "open") return undefined;
-
+  issues: readonly ReviewIssue[],
+): Promise<ReviewIssueSelection> {
   return await ctx.ui.custom<ReviewIssueSelection>(
-    (tui, theme, _keybindings, done) => new ReviewResultsViewer(decision.issues, "code-review", theme, () => tui.requestRender(), done),
-    { overlay: true, overlayOptions: { anchor: "right-center", width: "80%", maxHeight: "90%", margin: 1 } },
+    (tui, theme, _keybindings, done) => new ReviewResultsViewer(issues, "code-review", tui, theme, done),
+    WORKFLOW_VIEWER_OVERLAY_OPTIONS,
   );
 }

package/.pi/extensions/pi-workflow-engine/src/review/review-results-viewer.ts

@@ -1,18 +1,21 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { matchesKey, visibleWidth, type Component } from "@earendil-works/pi-tui";
+import { matchesKey, type Component, type TUI } from "@earendil-works/pi-tui";
 import { renderIssueDetailLines } from "./review-format.ts";
 import { formatIssueLocation, type ReviewIssue, type ReviewIssueSelection } from "./review-issues.ts";
 import { truncateDisplay } from "../ui/workflow-format.ts";
+import { fitWorkflowViewerRow, fitWorkflowViewerRows, workflowViewerHeight } from "../ui/workflow-viewer-layout.ts";
 
-const MIN_WIDTH = 40;
 const SPLIT_WIDTH = 96;
 const LIST_MIN_WIDTH = 34;
 const LIST_MAX_WIDTH = 48;
 const DETAIL_SCROLL_STEP = 5;
 
+type ViewerTui = Pick<TUI, "requestRender" | "terminal">;
+
 export class ReviewResultsViewer implements Component {
   private readonly selected = new Set<string>();
   private cursor = 0;
+  private listScroll = 0;
   private detailScroll = 0;
   private detailsExpanded = true;
   private warning: string | undefined;
@@ -20,18 +23,23 @@ export class ReviewResultsViewer implements Component {
   constructor(
     private readonly issues: readonly ReviewIssue[],
     private readonly workflowName: string,
+    private readonly tui: ViewerTui,
     private readonly theme: Theme,
-    private readonly requestRender: () => void,
     private readonly done: (result: ReviewIssueSelection) => void,
   ) {}
 
   invalidate(): void {}
 
   render(width: number): string[] {
-    const outerWidth = Math.max(MIN_WIDTH, width);
-    const innerWidth = Math.max(1, outerWidth - 2);
-    const body = this.renderBody(innerWidth);
-    return [this.topBorder(innerWidth), ...body.map((line) => `│${padAnsi(line, innerWidth)}│`), this.bottomBorder(innerWidth)];
+    const outerWidth = Math.max(4, width);
+    const contentWidth = Math.max(1, outerWidth - 4);
+    const innerHeight = Math.max(1, workflowViewerHeight(this.tui.terminal.rows) - 2);
+    const body = fitWorkflowViewerRows(this.renderBody(contentWidth, innerHeight), innerHeight);
+    return [
+      this.theme.fg("borderAccent", `╭${"─".repeat(Math.max(0, outerWidth - 2))}╮`),
+      ...body.map((line) => this.borderedRow(line, contentWidth)),
+      this.theme.fg("borderAccent", `╰${"─".repeat(Math.max(0, outerWidth - 2))}╯`),
+    ];
   }
 
   handleInput(data: string): void {
@@ -85,73 +93,139 @@ export class ReviewResultsViewer implements Component {
     }
   }
 
-  private renderBody(width: number): string[] {
-    const header = this.headerLine(width);
-    const help = this.helpLine(width);
-    const warning = this.warning ? [this.theme.fg("warning", this.warning)] : [];
-    if (this.issues.length === 0) return [header, this.theme.fg("success", "No findings."), ...warning, help];
+  private renderBody(width: number, height: number): string[] {
+    const warning = this.warning ? this.theme.fg("warning", this.warning) : "";
+    const chromeRows = 5;
+    const contentHeight = Math.max(1, height - chromeRows);
+    let content: string[];
+    if (this.issues.length === 0) {
+      content = fitWorkflowViewerRows([this.theme.fg("success", "No findings.")], contentHeight);
+    } else if (width >= SPLIT_WIDTH) {
+      content = this.renderSplit(width, contentHeight);
+    } else {
+      content = this.renderStacked(width, contentHeight);
+    }
 
-    const split = width >= SPLIT_WIDTH;
-    const content = split ? this.renderSplit(width) : this.renderStacked(width);
-    return [header, ...warning, ...content, help];
+    return [
+      this.headerLine(width),
+      warning,
+      this.theme.fg("borderMuted", "─".repeat(width)),
+      ...fitWorkflowViewerRows(content, contentHeight),
+      this.theme.fg("borderMuted", "─".repeat(width)),
+      this.helpLine(width),
+    ];
   }
 
-  private renderSplit(width: number): string[] {
-    const listWidth = Math.min(LIST_MAX_WIDTH, Math.max(LIST_MIN_WIDTH, Math.floor(width * 0.42)));
-    const detailWidth = Math.max(20, width - listWidth - 3);
-    const list = this.renderIssueList(listWidth);
-    const details = this.renderDetail(detailWidth);
-    const rows = Math.max(list.length, details.length);
-    const lines: string[] = [];
-    for (let index = 0; index < rows; index++) {
-      lines.push(`${padAnsi(list[index] ?? "", listWidth)} ${this.theme.fg("dim", "│")} ${padAnsi(details[index] ?? "", detailWidth)}`);
-    }
-    return lines;
+  private renderSplit(width: number, height: number): string[] {
+    const listWidth = Math.min(LIST_MAX_WIDTH, Math.max(LIST_MIN_WIDTH, Math.floor(width * 0.38)));
+    const detailWidth = Math.max(1, width - listWidth - 3);
+    const list = this.renderIssuePane(listWidth, height);
+    const details = this.renderDetailPane(detailWidth, height);
+    const divider = this.theme.fg("borderMuted", "│");
+    return Array.from({ length: height }, (_value, index) =>
+      `${fitWorkflowViewerRow(list[index] ?? "", listWidth)} ${divider} ${fitWorkflowViewerRow(details[index] ?? "", detailWidth)}`,
+    );
   }
 
-  private renderStacked(width: number): string[] {
-    return [...this.renderIssueList(width), this.theme.fg("dim", "─".repeat(Math.max(1, width))), ...this.renderDetail(width)];
+  private renderStacked(width: number, height: number): string[] {
+    if (height < 7) return this.renderCompact(width, height);
+    const listHeight = Math.max(3, Math.min(height - 4, Math.floor(height * 0.38)));
+    const detailHeight = height - listHeight - 1;
+    return [
+      ...this.renderIssuePane(width, listHeight),
+      this.theme.fg("borderMuted", "─".repeat(width)),
+      ...this.renderDetailPane(width, detailHeight),
+    ];
   }
 
-  private renderIssueList(width: number): string[] {
-    return this.issues.map((issue, index) => {
-      const cursor = index === this.cursor ? this.theme.fg("accent", ">") : " ";
-      const checked = this.selected.has(issue.id) ? this.theme.fg("success", "x") : " ";
-      const severity = this.theme.fg(severityColor(issue.finding.severity), issue.finding.severity);
-      const row = `${cursor} [${checked}] ${issue.id} ${severity} ${issue.finding.category} ${formatIssueLocation(issue)} — ${issue.finding.summary}`;
-      return truncateDisplay(row, width);
-    });
+  private renderCompact(width: number, height: number): string[] {
+    if (height <= 0) return [];
+    const issue = this.issues[this.cursor];
+    const selected = issue ? this.renderIssueRow(issue, this.cursor, width) : this.theme.fg("dim", "No finding selected.");
+    if (height === 1) return [selected];
+    return [selected, ...this.renderDetailPane(width, height - 1)];
   }
 
-  private renderDetail(width: number): string[] {
+  private renderIssuePane(width: number, height: number): string[] {
+    if (height <= 0) return [];
+    const itemRows = Math.max(0, height - 2);
+    if (itemRows === 0) this.listScroll = 0;
+    const maxStart = Math.max(0, this.issues.length - itemRows);
+    if (this.cursor < this.listScroll) this.listScroll = this.cursor;
+    if (itemRows > 0 && this.cursor >= this.listScroll + itemRows) this.listScroll = this.cursor - itemRows + 1;
+    this.listScroll = Math.min(maxStart, Math.max(0, this.listScroll));
+    const end = Math.min(this.issues.length, this.listScroll + itemRows);
+    const visible = this.issues.slice(this.listScroll, end).map((issue, offset) => this.renderIssueRow(issue, this.listScroll + offset, width));
+    const range = this.issues.length === 0 || itemRows === 0 ? `0/${this.issues.length}` : `${this.listScroll + 1}–${end}/${this.issues.length}`;
+    const arrows = scrollArrows(this.listScroll > 0, end < this.issues.length);
+    const heading = truncateDisplay(
+      `${this.theme.fg("accent", this.theme.bold("Findings"))} ${this.theme.fg("muted", `${this.cursor + 1}/${Math.max(1, this.issues.length)}`)}`,
+      width,
+    );
+    const indicator = truncateDisplay(this.theme.fg("dim", `${range}${arrows ? ` ${arrows}` : ""}`), width);
+    return [heading, ...fitWorkflowViewerRows(visible, itemRows), indicator].slice(0, height);
+  }
+
+  private renderIssueRow(issue: ReviewIssue, index: number, width: number): string {
+    const cursor = index === this.cursor ? this.theme.fg("accent", ">") : " ";
+    const checked = this.selected.has(issue.id) ? this.theme.fg("success", "x") : " ";
+    const severity = this.theme.fg(severityColor(issue.finding.severity), issue.finding.severity);
+    const row = `${cursor} [${checked}] ${issue.id} ${severity} ${issue.finding.category} ${formatIssueLocation(issue)} — ${issue.finding.summary}`;
+    return truncateDisplay(row, width);
+  }
+
+  private renderDetailPane(width: number, height: number): string[] {
+    if (height <= 0) return [];
     const issue = this.issues[this.cursor];
-    if (!issue) return [this.theme.fg("dim", "No finding selected.")];
-    if (!this.detailsExpanded) return [this.theme.fg("accent", issue.id), issue.finding.summary, this.theme.fg("dim", "Press enter to expand details.")];
-    const lines = renderIssueDetailLines(issue, this.theme, width);
-    const maxScroll = Math.max(0, lines.length - 1);
-    this.detailScroll = Math.min(this.detailScroll, maxScroll);
-    const visible = lines.slice(this.detailScroll, this.detailScroll + 14);
-    if (this.detailScroll > 0) visible.unshift(this.theme.fg("dim", "↑ more"));
-    if (this.detailScroll + 14 < lines.length) visible.push(this.theme.fg("dim", "↓ more"));
-    return visible.map((line) => truncateDisplay(line, width));
+    if (!issue) return fitWorkflowViewerRows([this.theme.fg("dim", "No finding selected.")], height);
+
+    const bodyHeight = Math.max(0, height - 2);
+    const heading = truncateDisplay(
+      `${this.theme.fg("accent", this.theme.bold("Details"))} ${this.theme.fg("muted", issue.id)}`,
+      width,
+    );
+    const lines = this.detailsExpanded
+      ? renderIssueDetailLines(issue, this.theme, width)
+      : [issue.finding.summary, this.theme.fg("dim", "Press enter to expand details.")];
+    if (bodyHeight === 0) this.detailScroll = 0;
+    const maxScroll = Math.max(0, lines.length - bodyHeight);
+    this.detailScroll = Math.min(maxScroll, Math.max(0, this.detailScroll));
+    const end = Math.min(lines.length, this.detailScroll + bodyHeight);
+    const visible = lines.slice(this.detailScroll, end).map((line) => truncateDisplay(line, width));
+    const range = lines.length === 0 || bodyHeight === 0 ? `0/${lines.length}` : `${this.detailScroll + 1}–${end}/${lines.length}`;
+    const arrows = scrollArrows(this.detailScroll > 0, bodyHeight === 0 ? lines.length > 0 : end < lines.length);
+    const indicator = truncateDisplay(
+      this.theme.fg("dim", `${this.detailsExpanded ? "Lines" : "Collapsed"} ${range}${arrows ? ` ${arrows}` : ""}`),
+      width,
+    );
+    return [heading, ...fitWorkflowViewerRows(visible, bodyHeight), indicator].slice(0, height);
   }
 
   private headerLine(width: number): string {
     const count = `${this.issues.length} finding${this.issues.length === 1 ? "" : "s"}`;
     const selected = `${this.selected.size} selected`;
-    return truncateDisplay(`${this.theme.fg("accent", this.theme.bold("Review results"))} ${this.theme.fg("muted", this.workflowName)} · ${count} · ${selected}`, width);
+    return truncateDisplay(
+      `${this.theme.fg("accent", this.theme.bold("Review results"))} ${this.theme.fg("muted", this.workflowName)} ${this.theme.fg("dim", `· ${count} · ${selected}`)}`,
+      width,
+    );
   }
 
   private helpLine(width: number): string {
-    return truncateDisplay(this.theme.fg("dim", "↑/↓ move · 1-9 jump · space tag · a all · enter expand/collapse · ←/→ scroll · f fix · c comment · q close"), width);
+    const help = width >= 110
+      ? "↑↓ findings · 1-9 jump · space select · a all · enter details · ←→ scroll · f fix · c comment · q close"
+      : "q close · ↑↓ move · space select · enter details · ←→ scroll · f fix · c comment";
+    return truncateDisplay(
+      this.theme.fg("dim", help),
+      width,
+    );
   }
 
-  private topBorder(innerWidth: number): string {
-    return `┌${this.theme.fg("dim", "─".repeat(innerWidth))}┐`;
+  private borderedRow(content: string, width: number): string {
+    return `${this.theme.fg("border", "│")} ${fitWorkflowViewerRow(content, width)} ${this.theme.fg("border", "│")}`;
   }
 
-  private bottomBorder(innerWidth: number): string {
-    return `└${this.theme.fg("dim", "─".repeat(innerWidth))}┘`;
+  private requestRender(): void {
+    this.tui.requestRender();
   }
 
   private moveCursor(delta: number): void {
@@ -218,10 +292,8 @@ export class ReviewResultsViewer implements Component {
   }
 }
 
-function padAnsi(text: string, width: number): string {
-  const truncated = truncateDisplay(text, width);
-  const padding = Math.max(0, width - visibleWidth(truncated));
-  return `${truncated}${" ".repeat(padding)}`;
+function scrollArrows(hasAbove: boolean, hasBelow: boolean): string {
+  return `${hasAbove ? "↑" : ""}${hasBelow ? "↓" : ""}`;
 }
 
 function digitJumpIndex(data: string): number | undefined {

package/.pi/extensions/pi-workflow-engine/src/review/review-session-coordinator.ts

@@ -0,0 +1,153 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { sessionKey } from "../session-identity.ts";
+import { resolveWorkflowRunOptions, type ResolvedWorkflowRunOptions } from "../options.ts";
+import type { LoadedWorkflow } from "../types.ts";
+import type { WorkflowExecution } from "../workflow-execution.ts";
+import { handleReviewViewerAction } from "./review-actions.ts";
+import { ReviewFixBudgetLedger } from "./review-budget.ts";
+import { toReviewIssues, type ReviewIssue, type ReviewIssueSelection } from "./review-issues.ts";
+import { codeReviewReport, decideReviewResultsPresentation, showReviewResultsViewer } from "./review-results-flow.ts";
+import type { ReviewReport } from "./review-report.ts";
+
+interface RetainedCodeReviewResult {
+  readonly report: ReviewReport;
+  readonly concurrency: number;
+  readonly parallelSubmissionLimit?: number;
+  readonly perf: boolean;
+  readonly budget: ReviewFixBudgetLedger;
+}
+
+export interface ReviewSessionCoordinatorDependencies {
+  readonly runFollowUp: (
+    ctx: ExtensionContext,
+    workflow: LoadedWorkflow,
+    options: ResolvedWorkflowRunOptions,
+  ) => Promise<WorkflowExecution>;
+  readonly publish: (execution: WorkflowExecution) => void;
+}
+
+/** Owns retained code-review state and every path that presents or acts on it. */
+export class ReviewSessionCoordinator {
+  private readonly sessions = new Map<string, RetainedCodeReviewResult>();
+
+  constructor(
+    private readonly pi: Pick<ExtensionAPI, "sendUserMessage" | "exec">,
+    private readonly dependencies: ReviewSessionCoordinatorDependencies,
+  ) {}
+
+  remember(
+    ctx: ExtensionContext,
+    execution: WorkflowExecution,
+    options: ResolvedWorkflowRunOptions,
+  ): void {
+    const name = execution.envelope.name;
+    if (name !== "code-review") return;
+    const key = sessionKey(ctx);
+    const report = codeReviewReport(name, execution.envelope.result);
+    if (!report) {
+      this.sessions.delete(key);
+      return;
+    }
+    this.sessions.set(key, {
+      report,
+      concurrency: options.concurrency,
+      parallelSubmissionLimit: options.parallelSubmissionLimit ?? undefined,
+      perf: options.perf,
+      budget: new ReviewFixBudgetLedger(options.budget, execution.envelope.usage),
+    });
+  }
+
+  async present(
+    ctx: ExtensionContext,
+    execution: WorkflowExecution,
+    options: ResolvedWorkflowRunOptions,
+  ): Promise<void> {
+    const name = execution.envelope.name;
+    const decision = decideReviewResultsPresentation({
+      workflowName: name,
+      result: execution.envelope.result,
+      mode: ctx.mode,
+      hasUI: ctx.hasUI,
+      resultViewer: options.resultViewer,
+    });
+    if (decision.kind !== "open") return;
+
+    const retained = this.sessions.get(sessionKey(ctx));
+    if (!retained) return;
+    await this.openAndHandle(ctx, retained, decision.issues);
+  }
+
+  async reopen(ctx: ExtensionContext): Promise<void> {
+    if (!ctx.hasUI || ctx.mode !== "tui") {
+      ctx.ui.notify("Code-review results viewer requires the TUI", "warning");
+      return;
+    }
+    const retained = this.sessions.get(sessionKey(ctx));
+    if (!retained) {
+      ctx.ui.notify("No code-review result is available yet. Run /workflow code-review first.", "warning");
+      return;
+    }
+    if (retained.report.findings.length === 0) {
+      ctx.ui.notify("The last code review had no findings", "info");
+      return;
+    }
+
+    await this.openAndHandle(ctx, retained, toReviewIssues("code-review", retained.report));
+  }
+
+  dispose(ctx: ExtensionContext): void {
+    this.sessions.delete(sessionKey(ctx));
+  }
+
+  private async openAndHandle(
+    ctx: ExtensionContext,
+    retained: RetainedCodeReviewResult,
+    issues: readonly ReviewIssue[],
+  ): Promise<void> {
+    let action: ReviewIssueSelection | undefined;
+    try {
+      action = await showReviewResultsViewer(ctx, issues);
+    } catch {
+      ctx.ui.notify("Review completed, but the findings viewer could not be opened.", "warning");
+      return;
+    }
+    await this.runAction(ctx, retained, action, issues);
+  }
+
+  private async runAction(
+    ctx: ExtensionContext,
+    retained: RetainedCodeReviewResult,
+    action: ReviewIssueSelection | undefined,
+    issues: readonly ReviewIssue[],
+  ): Promise<void> {
+    const lease = action?.action === "fix" ? retained.budget.acquire() : undefined;
+    if (lease && !lease.ok) {
+      const message = lease.reason === "exhausted"
+        ? "Review-fix previews are unavailable because this review's output-token budget is exhausted."
+        : "A review-fix preview is already running for this review.";
+      ctx.ui.notify(message, "warning");
+      return;
+    }
+
+    try {
+      const followUp = await handleReviewViewerAction(this.pi, ctx, action, issues, retained.report.reviewContext);
+      if (!followUp) return;
+      const execution = await this.dependencies.runFollowUp(ctx, followUp, followUpOptions(retained, ctx.signal));
+      this.dependencies.publish(execution);
+    } finally {
+      if (lease?.ok) lease.release();
+    }
+  }
+}
+
+function followUpOptions(retained: RetainedCodeReviewResult, signal: AbortSignal | undefined): ResolvedWorkflowRunOptions {
+  return resolveWorkflowRunOptions({
+    concurrency: retained.concurrency,
+    parallelSubmissionLimit: retained.parallelSubmissionLimit,
+    budget: retained.budget.remaining,
+    perf: retained.perf,
+    resultViewer: "skip",
+    signal,
+    onUsageSnapshot: (usage) => retained.budget.record(usage),
+  }, {});
+}