pi-workflow-engine 0.13.0 → 1.0.0

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

@@ -1,312 +1,229 @@
-import type { Theme } from "@earendil-works/pi-coding-agent";
-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";
-
+import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { decodeKittyPrintable, matchesKey, visibleWidth, type Component, type TUI } from "@earendil-works/pi-tui";
+import { findingPathColumn, renderFindingDetail, renderFindingRow, sortIssuesForDisplay } from "./review-format.ts";
+import { dot, fit, frame, GLYPH, keyHints, overlayHeight, scrollHint } from "../ui/kit.ts";
+import { isCommentableIssue, type ReviewIssue, type ReviewIssueSelection } from "./review-issues.ts";
+import { WORKFLOW_VIEWER_OVERLAY_OPTIONS } from "../ui/workflow-viewer-layout.ts";
+
+/** Inner width from which the list and the detail pane sit side by side. */
 const SPLIT_WIDTH = 96;
-const LIST_MIN_WIDTH = 34;
-const LIST_MAX_WIDTH = 48;
-const DETAIL_SCROLL_STEP = 5;
+const SPLIT_LIST_SHARE = 0.5;
+const SPLIT_LIST_MIN = 40;
+const SPLIT_LIST_MAX = 64;
+/** Stacked layout keeps at least this many detail rows below the list. */
+const STACKED_DETAIL_MIN = 6;
+const PREFIX_WIDTH = 4;
 
 type ViewerTui = Pick<TUI, "requestRender" | "terminal">;
+type Hint = readonly [key: string, description: string];
+
+export interface ReviewResultsViewerContext {
+  readonly ui: Pick<ExtensionContext["ui"], "custom">;
+}
+
+export async function showReviewResultsViewer(
+  ctx: ReviewResultsViewerContext,
+  issues: readonly ReviewIssue[],
+): Promise<ReviewIssueSelection> {
+  return await ctx.ui.custom<ReviewIssueSelection>(
+    (tui, theme, _keybindings, done) => new ReviewResultsViewer(issues, tui, theme, done),
+    WORKFLOW_VIEWER_OVERLAY_OPTIONS,
+  );
+}
 
+/**
+ * Framed findings triage overlay: most severe first, a selectable list with the cursor finding's full
+ * detail beside it (or below it when narrow), and selection-gated patch-preview and PR-comment actions.
+ */
 export class ReviewResultsViewer implements Component {
+  private readonly issues: readonly ReviewIssue[];
+  private readonly reportOrder: readonly ReviewIssue[];
   private readonly selected = new Set<string>();
   private cursor = 0;
   private listScroll = 0;
   private detailScroll = 0;
-  private detailsExpanded = true;
+  private detailClipped = false;
   private warning: string | undefined;
+  private detailHeightCache: { readonly width: number; readonly rows: number } | undefined;
 
   constructor(
-    private readonly issues: readonly ReviewIssue[],
-    private readonly workflowName: string,
+    issues: readonly ReviewIssue[],
     private readonly tui: ViewerTui,
     private readonly theme: Theme,
     private readonly done: (result: ReviewIssueSelection) => void,
-  ) {}
+  ) {
+    this.reportOrder = issues;
+    this.issues = sortIssuesForDisplay(issues);
+  }
 
-  invalidate(): void {}
+  invalidate(): void {
+    this.detailHeightCache = undefined;
+  }
 
   render(width: number): string[] {
-    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))}╯`),
-    ];
+    const inner = Math.max(1, width - 4);
+    this.detailClipped = false;
+    const body = this.issues.length === 0
+      ? [this.theme.fg("muted", "No findings.")]
+      : inner >= SPLIT_WIDTH ? this.renderSplit(inner) : this.renderStacked(inner);
+    return frame(body, width, this.theme, {
+      title: `${this.theme.fg("accent", this.theme.bold("Review findings"))}${dot(this.theme)}${this.theme.fg("muted", "code-review")}`,
+      right: this.counts(),
+      footer: this.footer(inner),
+    });
   }
 
   handleInput(data: string): void {
-    const digitJump = digitJumpIndex(data);
-    if (digitJump !== undefined) {
-      this.jumpTo(digitJump);
-      return;
-    }
-
-    if (matchesKey(data, "up")) {
-      this.moveCursor(-1);
-      return;
-    }
-    if (matchesKey(data, "down")) {
-      this.moveCursor(1);
-      return;
-    }
-    if (matchesKey(data, "space") || data === " ") {
-      this.toggleCurrent();
-      return;
-    }
-    if (data === "a") {
-      this.toggleAllVisible();
-      return;
-    }
-    if (matchesKey(data, "enter") || matchesKey(data, "return") || data === "\r") {
-      this.detailsExpanded = !this.detailsExpanded;
-      this.detailScroll = 0;
-      this.warning = undefined;
-      this.requestRender();
-      return;
-    }
-    if (matchesKey(data, "pageUp") || matchesKey(data, "left")) {
-      this.scrollDetail(-DETAIL_SCROLL_STEP);
-      return;
-    }
-    if (matchesKey(data, "pageDown") || matchesKey(data, "right")) {
-      this.scrollDetail(DETAIL_SCROLL_STEP);
-      return;
-    }
-    if (data === "f") {
-      this.finishSelected("fix");
-      return;
-    }
-    if (data === "c") {
-      this.finishSelected("comment");
-      return;
-    }
-    if (data === "q" || matchesKey(data, "escape") || matchesKey(data, "esc")) {
+    const key = decodeKittyPrintable(data) ?? data;
+    if (key === "q" || matchesKey(data, "escape")) {
       this.done({ action: "close", issueIds: this.selectedIssueIds() });
+      return;
     }
+    this.warning = undefined;
+    if (matchesKey(data, "up") || key === "k") this.moveCursor(-1);
+    else if (matchesKey(data, "down") || key === "j") this.moveCursor(1);
+    else if (matchesKey(data, "home") || key === "g") this.moveCursor(-this.issues.length);
+    else if (matchesKey(data, "end") || key === "G") this.moveCursor(this.issues.length);
+    else if (matchesKey(data, "pageUp")) this.detailScroll = Math.max(0, this.detailScroll - this.pageSize());
+    else if (matchesKey(data, "pageDown")) this.detailScroll += this.pageSize();
+    else if (matchesKey(data, "space") || matchesKey(data, "enter")) this.toggleCurrent();
+    else if (key === "a") this.toggleAll();
+    else if (key === "f") this.finish("fix");
+    else if (key === "c") this.finish("comment");
+    this.tui.requestRender();
   }
 
-  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);
-    }
-
-    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, 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);
+  private renderSplit(inner: number): string[] {
+    const listWidth = Math.min(SPLIT_LIST_MAX, Math.max(SPLIT_LIST_MIN, Math.floor(inner * SPLIT_LIST_SHARE)));
+    const detailWidth = Math.max(1, inner - listWidth - 3);
+    const height = Math.min(this.bodyCeiling(), Math.max(this.issues.length, this.detailHeight(detailWidth)));
+    const list = this.renderList(listWidth, height);
+    const detail = this.renderDetail(detailWidth, height);
     const divider = this.theme.fg("borderMuted", "│");
-    return Array.from({ length: height }, (_value, index) =>
-      `${fitWorkflowViewerRow(list[index] ?? "", listWidth)} ${divider} ${fitWorkflowViewerRow(details[index] ?? "", detailWidth)}`,
-    );
+    const rows: string[] = [];
+    for (let index = 0; index < height; index++) rows.push(`${fit(list[index] ?? "", listWidth)} ${divider} ${detail[index] ?? ""}`);
+    return rows;
   }
 
-  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;
+  private renderStacked(inner: number): string[] {
+    const ceiling = this.bodyCeiling();
+    const detailNeed = this.detailHeight(inner);
+    const listRows = Math.max(1, Math.min(this.issues.length, ceiling - 1 - Math.min(detailNeed, STACKED_DETAIL_MIN)));
+    const detailRows = Math.max(1, Math.min(detailNeed, ceiling - listRows - 1));
+    const detail = this.renderDetail(inner, detailRows);
     return [
-      ...this.renderIssuePane(width, listHeight),
-      this.theme.fg("borderMuted", "─".repeat(width)),
-      ...this.renderDetailPane(width, detailHeight),
+      ...this.renderList(inner, listRows),
+      this.theme.fg("borderMuted", "─".repeat(inner)),
+      ...detail,
+      ...new Array<string>(Math.max(0, detailRows - detail.length)).fill(""),
     ];
   }
 
-  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 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);
+  /** Finding rows with cursor and selection marks; a scroll hint takes the last row only when clipped. */
+  private renderList(width: number, height: number): string[] {
+    const rows = this.issues.length > height ? Math.max(1, height - 1) : height;
     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);
+    if (this.cursor >= this.listScroll + rows) this.listScroll = this.cursor - rows + 1;
+    this.listScroll = Math.max(0, Math.min(this.listScroll, this.issues.length - rows));
+    const visible = this.issues.slice(this.listScroll, this.listScroll + rows).map((issue, offset) => this.renderRow(issue, this.listScroll + offset, width));
+    const hint = scrollHint(this.listScroll, this.issues.length - this.listScroll - visible.length, this.theme);
+    return hint && this.issues.length > height ? [...visible, `${" ".repeat(PREFIX_WIDTH)}${hint}`] : visible;
   }
 
-  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 renderRow(issue: ReviewIssue, index: number, width: number): string {
+    const cursor = index === this.cursor ? this.theme.fg("accent", GLYPH.cursor) : " ";
+    const mark = this.selected.has(issue.id) ? this.theme.fg("success", GLYPH.running) : this.theme.fg("dim", GLYPH.queued);
+    return `${cursor} ${mark} ${renderFindingRow(issue, Math.max(1, width - PREFIX_WIDTH), this.theme, findingPathColumn(this.issues))}`;
   }
 
-  private renderDetailPane(width: number, height: number): string[] {
-    if (height <= 0) return [];
+  private renderDetail(width: number, height: number): string[] {
     const issue = this.issues[this.cursor];
-    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);
+    if (!issue) return [];
+    const lines = renderFindingDetail(issue, width, this.theme);
+    if (lines.length <= height) {
+      this.detailScroll = 0;
+      return lines;
+    }
+    this.detailClipped = true;
+    const rows = Math.max(1, height - 1);
+    this.detailScroll = Math.max(0, Math.min(this.detailScroll, lines.length - rows));
+    const below = lines.length - this.detailScroll - rows;
+    const hint = scrollHint(this.detailScroll, below, this.theme) ?? "";
+    return [...lines.slice(this.detailScroll, this.detailScroll + rows), hint];
+  }
+
+  /** The tallest finding detail at this width, so the overlay keeps one height while the cursor moves. */
+  private detailHeight(width: number): number {
+    if (this.detailHeightCache?.width !== width) {
+      const rows = Math.max(0, ...this.issues.map((issue) => renderFindingDetail(issue, width, this.theme).length));
+      this.detailHeightCache = { width, rows };
+    }
+    return this.detailHeightCache.rows;
   }
 
-  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)} ${this.theme.fg("dim", `· ${count} · ${selected}`)}`,
-      width,
-    );
+  private bodyCeiling(): number {
+    return Math.max(3, overlayHeight(this.tui.terminal.rows, Number.MAX_SAFE_INTEGER) - 2);
   }
 
-  private helpLine(width: number): string {
-    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 pageSize(): number {
+    return Math.max(1, Math.floor(this.bodyCeiling() / 2));
   }
 
-  private borderedRow(content: string, width: number): string {
-    return `${this.theme.fg("border", "│")} ${fitWorkflowViewerRow(content, width)} ${this.theme.fg("border", "│")}`;
+  private counts(): string {
+    const findings = `${this.issues.length} finding${this.issues.length === 1 ? "" : "s"}`;
+    const selected = this.selected.size > 0 ? this.theme.fg("success", `${this.selected.size} selected`) : undefined;
+    return [this.theme.fg("muted", findings), selected].filter(Boolean).join(dot(this.theme));
   }
 
-  private requestRender(): void {
-    this.tui.requestRender();
+  /** Key hints in the bottom border; a transient warning replaces them until the next key. */
+  private footer(inner: number): string {
+    if (this.warning) return this.theme.fg("warning", `${GLYPH.warning} ${this.warning}`);
+    const scroll: Hint[] = this.detailClipped ? [["pgup/pgdn", "scroll"]] : [];
+    const variants: Hint[][] = [
+      [["↑↓", "move"], ["space", "select"], ["a", "all"], ["f", "patch preview"], ["c", "PR comment"], ...scroll, ["q", "close"]],
+      [["↑↓", "move"], ["space", "select"], ["a", "all"], ["f", "patch"], ["c", "comment"], ...scroll, ["q", "close"]],
+      [["space", "select"], ["f", "patch"], ["c", "comment"], ["q", "close"]],
+      [["space", "select"], ["q", "close"]],
+    ];
+    const rendered = variants.map((hints) => keyHints(hints, this.theme));
+    return rendered.find((hints) => visibleWidth(hints) <= inner - 2) ?? rendered[rendered.length - 1] ?? "";
   }
 
   private moveCursor(delta: number): void {
     if (this.issues.length === 0) return;
-    this.cursor = Math.min(this.issues.length - 1, Math.max(0, this.cursor + delta));
-    this.detailScroll = 0;
-    this.warning = undefined;
-    this.requestRender();
-  }
-
-  private jumpTo(index: number): void {
-    if (index < 0 || index >= this.issues.length) {
-      this.warning = `No finding ${index + 1}.`;
-      this.requestRender();
-      return;
-    }
-    this.cursor = index;
-    this.detailScroll = 0;
-    this.warning = undefined;
-    this.requestRender();
+    const next = Math.min(this.issues.length - 1, Math.max(0, this.cursor + delta));
+    if (next !== this.cursor) this.detailScroll = 0;
+    this.cursor = next;
   }
 
   private toggleCurrent(): void {
     const issue = this.issues[this.cursor];
     if (!issue) return;
-    this.toggleIssue(issue.id);
-    this.warning = undefined;
-    this.requestRender();
+    if (this.selected.has(issue.id)) this.selected.delete(issue.id);
+    else this.selected.add(issue.id);
   }
 
-  private toggleAllVisible(): void {
+  private toggleAll(): void {
     const allSelected = this.issues.length > 0 && this.issues.every((issue) => this.selected.has(issue.id));
     this.selected.clear();
-    if (!allSelected) {
-      for (const issue of this.issues) this.selected.add(issue.id);
-    }
-    this.warning = undefined;
-    this.requestRender();
+    if (!allSelected) for (const issue of this.issues) this.selected.add(issue.id);
   }
 
-  private scrollDetail(delta: number): void {
-    this.detailScroll = Math.max(0, this.detailScroll + delta);
-    this.warning = undefined;
-    this.requestRender();
-  }
-
-  private finishSelected(action: "fix" | "comment"): void {
+  private finish(action: "fix" | "comment"): void {
     const issueIds = this.selectedIssueIds();
     if (issueIds.length === 0) {
-      this.warning = `Select at least one finding before pressing ${action === "fix" ? "f" : "c"}.`;
-      this.requestRender();
+      this.warning = `Select findings first (space or a), then press ${action === "fix" ? "f" : "c"}`;
+      return;
+    }
+    if (action === "comment" && !this.issues.some((issue) => this.selected.has(issue.id) && isCommentableIssue(issue))) {
+      this.warning = "None of the selected findings has a file and line to comment on";
       return;
     }
     this.done({ action, issueIds });
   }
 
-  private toggleIssue(id: string): void {
-    if (this.selected.has(id)) this.selected.delete(id);
-    else this.selected.add(id);
-  }
-
+  /** Selected ids in report order, which keeps follow-up prompts and comments stable. */
   private selectedIssueIds(): string[] {
-    return this.issues.filter((issue) => this.selected.has(issue.id)).map((issue) => issue.id);
-  }
-}
-
-function scrollArrows(hasAbove: boolean, hasBelow: boolean): string {
-  return `${hasAbove ? "↑" : ""}${hasBelow ? "↓" : ""}`;
-}
-
-function digitJumpIndex(data: string): number | undefined {
-  return data.length === 1 && data >= "1" && data <= "9" ? Number(data) - 1 : undefined;
-}
-
-function severityColor(severity: ReviewIssue["finding"]["severity"]): Parameters<Theme["fg"]>[0] {
-  switch (severity) {
-    case "high":
-      return "error";
-    case "medium":
-      return "warning";
-    case "low":
-      return "muted";
+    return this.reportOrder.filter((issue) => this.selected.has(issue.id)).map((issue) => issue.id);
   }
 }

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

@@ -2,14 +2,14 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 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 type { WorkflowResultEnvelope } 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";
+import { showReviewResultsViewer } from "./review-results-viewer.ts";
+import { isReviewReport, type ReviewReport } from "./review-report.ts";
 
-interface RetainedCodeReviewResult {
+export interface RetainedCodeReviewResult {
   readonly report: ReviewReport;
   readonly concurrency: number;
   readonly parallelSubmissionLimit?: number;
@@ -22,8 +22,8 @@ export interface ReviewSessionCoordinatorDependencies {
     ctx: ExtensionContext,
     workflow: LoadedWorkflow,
     options: ResolvedWorkflowRunOptions,
-  ) => Promise<WorkflowExecution>;
-  readonly publish: (execution: WorkflowExecution) => void;
+  ) => Promise<WorkflowResultEnvelope>;
+  readonly publish: (envelope: WorkflowResultEnvelope) => void;
 }
 
 /** Owns retained code-review state and every path that presents or acts on it. */
@@ -35,46 +35,39 @@ export class ReviewSessionCoordinator {
     private readonly dependencies: ReviewSessionCoordinatorDependencies,
   ) {}
 
+  /** Retains a code-review result for this session and returns it; any other result retains nothing. */
   remember(
     ctx: ExtensionContext,
-    execution: WorkflowExecution,
+    envelope: WorkflowResultEnvelope,
     options: ResolvedWorkflowRunOptions,
-  ): void {
-    const name = execution.envelope.name;
-    if (name !== "code-review") return;
+  ): RetainedCodeReviewResult | undefined {
+    if (envelope.name !== "code-review") return undefined;
     const key = sessionKey(ctx);
-    const report = codeReviewReport(name, execution.envelope.result);
-    if (!report) {
+    const report = envelope.result;
+    if (!isReviewReport(report)) {
       this.sessions.delete(key);
-      return;
+      return undefined;
     }
-    this.sessions.set(key, {
+    const retained: RetainedCodeReviewResult = {
       report,
       concurrency: options.concurrency,
       parallelSubmissionLimit: options.parallelSubmissionLimit ?? undefined,
       perf: options.perf,
-      budget: new ReviewFixBudgetLedger(options.budget, execution.envelope.usage),
-    });
+      budget: new ReviewFixBudgetLedger(options.budget, envelope.usage),
+    };
+    this.sessions.set(key, retained);
+    return retained;
   }
 
+  /** Opens the findings viewer for a result remember() just retained, when explicitly requested. */
   async present(
     ctx: ExtensionContext,
-    execution: WorkflowExecution,
+    retained: RetainedCodeReviewResult | undefined,
     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);
+    if (!retained || retained.report.findings.length === 0) return;
+    if (options.resultViewer !== "open" || ctx.mode !== "tui" || !ctx.hasUI) return;
+    await this.openAndHandle(ctx, retained);
   }
 
   async reopen(ctx: ExtensionContext): Promise<void> {
@@ -92,18 +85,15 @@ export class ReviewSessionCoordinator {
       return;
     }
 
-    await this.openAndHandle(ctx, retained, toReviewIssues("code-review", retained.report));
+    await this.openAndHandle(ctx, retained);
   }
 
   dispose(ctx: ExtensionContext): void {
     this.sessions.delete(sessionKey(ctx));
   }
 
-  private async openAndHandle(
-    ctx: ExtensionContext,
-    retained: RetainedCodeReviewResult,
-    issues: readonly ReviewIssue[],
-  ): Promise<void> {
+  private async openAndHandle(ctx: ExtensionContext, retained: RetainedCodeReviewResult): Promise<void> {
+    const issues = toReviewIssues(retained.report);
     let action: ReviewIssueSelection | undefined;
     try {
       action = await showReviewResultsViewer(ctx, issues);
@@ -132,8 +122,8 @@ export class ReviewSessionCoordinator {
     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);
+      const envelope = await this.dependencies.runFollowUp(ctx, followUp, followUpOptions(retained, ctx.signal));
+      this.dependencies.publish(envelope);
     } finally {
       if (lease?.ok) lease.release();
     }