pi-workflow-engine 0.11.0 → 0.12.0

package/.pi/extensions/pi-workflow-engine/src/research-evidence.ts

@@ -0,0 +1,289 @@
+import {
+  MAX_RESEARCH_LANES,
+  MAX_VERIFICATION_CLAIMS,
+  type ResearchClaimCandidate,
+  type ResearchEvidence,
+  type ResearchLane,
+  type ResearchLaneResult,
+  type ResearchPlan,
+  type ResearchReport,
+  type ResearchReportEntry,
+  type ResearchSource,
+  type ResearchVerification,
+} from "./research-contract.ts";
+
+const TRACKING_PARAMETERS = new Set(["fbclid", "gclid", "mc_cid", "mc_eid", "ref_src"]);
+const IMPORTANCE_RANK: Readonly<Record<ResearchEvidence["importance"], number>> = { high: 0, medium: 1, low: 2 };
+
+export function normalizeResearchLanes(plan: ResearchPlan): ResearchLane[] {
+  const seen = new Set<string>();
+  const lanes: ResearchLane[] = [];
+  for (const lane of plan.lanes) {
+    const id = normalizedText(lane.id);
+    const title = normalizedText(lane.title);
+    const objective = normalizedText(lane.objective);
+    const queries = dedupeText(lane.queries).slice(0, 4);
+    if (!id || !title || !objective || queries.length === 0 || seen.has(id.toLowerCase())) continue;
+    seen.add(id.toLowerCase());
+    lanes.push({ id, title, objective, queries });
+    if (lanes.length >= MAX_RESEARCH_LANES) break;
+  }
+  return lanes;
+}
+
+export function sanitizeLaneResults(results: readonly ResearchLaneResult[]): ResearchLaneResult[] {
+  return results.map((result) => ({
+    laneId: normalizedText(result.laneId),
+    gaps: dedupeText(result.gaps),
+    evidence: dedupeEvidence(result.evidence.map(sanitizeEvidence).filter(isDefined)),
+  }));
+}
+
+export function buildClaimCandidates(results: readonly ResearchLaneResult[]): ResearchClaimCandidate[] {
+  const byClaim = new Map<string, { claim: string; importance: ResearchEvidence["importance"]; evidence: ResearchEvidence[] }>();
+  for (const item of results.flatMap((result) => result.evidence)) {
+    const key = normalizedText(item.claim).toLowerCase();
+    if (!key) continue;
+    const current = byClaim.get(key);
+    if (!current) {
+      byClaim.set(key, { claim: normalizedText(item.claim), importance: item.importance, evidence: [item] });
+      continue;
+    }
+    if (IMPORTANCE_RANK[item.importance] < IMPORTANCE_RANK[current.importance]) current.importance = item.importance;
+    current.evidence = dedupeEvidence([...current.evidence, item]);
+  }
+  return [...byClaim.values()]
+    .sort((left, right) => IMPORTANCE_RANK[left.importance] - IMPORTANCE_RANK[right.importance])
+    .slice(0, MAX_VERIFICATION_CLAIMS);
+}
+
+export function sanitizeVerification(
+  verification: ResearchVerification,
+  candidate: ResearchClaimCandidate,
+): ResearchVerification {
+  const sources = dedupeSources(verification.sources);
+  const verdict = (verification.verdict === "SUPPORTED" || verification.verdict === "CONFLICTED") && sources.length === 0
+    ? "UNCERTAIN"
+    : verification.verdict;
+  return {
+    claim: candidate.claim,
+    verdict,
+    explanation: normalizedText(verification.explanation) || "Independent verification returned no explanation.",
+    sources,
+  };
+}
+
+export function unavailableVerification(candidate: ResearchClaimCandidate): ResearchVerification {
+  return {
+    claim: candidate.claim,
+    verdict: "UNCERTAIN",
+    explanation: "Independent verification did not complete; gathered evidence remains unverified.",
+    sources: dedupeSources(candidate.evidence.map((item) => item.source)),
+  };
+}
+
+export function sanitizeResearchReport(
+  report: ResearchReport,
+  verifications: readonly ResearchVerification[],
+): ResearchReport {
+  const sources = dedupeSources(
+    verifications
+      .filter((verification) => verification.verdict !== "REJECTED")
+      .flatMap((verification) => verification.sources),
+  );
+  const uncertainties = sanitizeEntries(
+    report.uncertainties,
+    verificationSources(verifications, "UNCERTAIN"),
+    false,
+  );
+  const supportedClaims = sanitizeEntries(
+    report.supportedClaims,
+    verificationSources(verifications, "SUPPORTED"),
+    true,
+    uncertainties,
+  );
+  const conflictingEvidence = sanitizeEntries(
+    report.conflictingEvidence,
+    verificationSources(verifications, "CONFLICTED"),
+    true,
+    uncertainties,
+  );
+  const inferences = sanitizeEntries(
+    report.inferences,
+    verificationSources(verifications, "INFERENCE"),
+    false,
+  );
+  return {
+    answer: normalizedText(report.answer),
+    supportedClaims,
+    conflictingEvidence,
+    uncertainties,
+    inferences,
+    sources,
+    limitations: dedupeText(report.limitations),
+    nextSteps: dedupeText(report.nextSteps),
+  };
+}
+
+function verificationSources(
+  verifications: readonly ResearchVerification[],
+  verdict: ResearchVerification["verdict"],
+): ReadonlyMap<string, ReadonlyMap<string, ResearchSource>> {
+  const byClaim = new Map<string, Map<string, ResearchSource>>();
+  for (const verification of verifications) {
+    if (verification.verdict !== verdict) continue;
+    const key = normalizedText(verification.claim).toLowerCase();
+    const claimSources = byClaim.get(key) ?? new Map<string, ResearchSource>();
+    dedupeSources(
+      verification.sources,
+    ).forEach((source) => claimSources.set(source.url, source));
+    byClaim.set(key, claimSources);
+  }
+  return byClaim;
+}
+
+export function fallbackResearchReport(
+  verifications: readonly ResearchVerification[],
+  limitation: string,
+): ResearchReport {
+  const entry = (verification: ResearchVerification): ResearchReportEntry => ({
+    claim: verification.claim,
+    explanation: verification.explanation,
+    citations: verification.sources,
+  });
+  return {
+    answer: "The synthesis stage did not complete; independently verified claims are grouped below without additional model interpretation.",
+    supportedClaims: verifications.filter((item) => item.verdict === "SUPPORTED").map(entry),
+    conflictingEvidence: verifications.filter((item) => item.verdict === "CONFLICTED").map(entry),
+    uncertainties: verifications.filter((item) => item.verdict === "UNCERTAIN").map(entry),
+    inferences: verifications.filter((item) => item.verdict === "INFERENCE").map(entry),
+    sources: dedupeSources(verifications.flatMap((verification) => verification.sources)),
+    limitations: [limitation],
+    nextSteps: ["Review the verified claim groups and rerun synthesis if a narrative answer is required."],
+  };
+}
+
+export function unavailableResearchReport(reason: "empty-question" | "missing-capability" | "no-evidence"): ResearchReport {
+  const message = reason === "empty-question"
+    ? "No research question was provided."
+    : reason === "missing-capability"
+      ? "Research could not start because pi exposed no installed external web-search or URL-extraction tool."
+      : "Research completed without enough direct-page evidence to support an answer.";
+  const nextStep = reason === "empty-question"
+    ? "Run `/workflow research <question>` and include any source, date, or geography constraints in the arguments."
+    : reason === "missing-capability"
+      ? "Install or enable a pi tool that can search the web or extract HTTP(S) pages, then rerun the workflow."
+      : "Check the installed external-search tool, narrow the question, or provide preferred source domains.";
+  return {
+    answer: message,
+    supportedClaims: [],
+    conflictingEvidence: [],
+    uncertainties: [],
+    inferences: [],
+    sources: [],
+    limitations: [message],
+    nextSteps: [nextStep],
+  };
+}
+
+export function canonicalSourceUrl(raw: string): string | undefined {
+  try {
+    const url = new URL(raw.trim());
+    if ((url.protocol !== "http:" && url.protocol !== "https:") || url.username || url.password) return undefined;
+    if (isSearchResultsUrl(url)) return undefined;
+    url.hash = "";
+    for (const key of [...url.searchParams.keys()]) {
+      if (key.toLowerCase().startsWith("utm_") || TRACKING_PARAMETERS.has(key.toLowerCase())) url.searchParams.delete(key);
+    }
+    url.searchParams.sort();
+    if (url.pathname.length > 1 && url.pathname.endsWith("/")) url.pathname = url.pathname.slice(0, -1);
+    return url.toString();
+  } catch {
+    return undefined;
+  }
+}
+
+export function dedupeSources(sources: readonly ResearchSource[]): ResearchSource[] {
+  const byUrl = new Map<string, ResearchSource>();
+  for (const source of sources) {
+    const url = canonicalSourceUrl(source.url);
+    const title = normalizedText(source.title);
+    if (!url || !title || byUrl.has(url)) continue;
+    const publishedAt = source.publishedAt === undefined ? undefined : normalizedText(source.publishedAt);
+    byUrl.set(url, { title, url, ...(publishedAt ? { publishedAt } : {}) });
+  }
+  return [...byUrl.values()];
+}
+
+function sanitizeEvidence(item: ResearchEvidence): ResearchEvidence | undefined {
+  const source = dedupeSources([item.source])[0];
+  const claim = normalizedText(item.claim);
+  const evidence = normalizedText(item.evidence);
+  if (!source || !claim || !evidence) return undefined;
+  return { claim, importance: item.importance, stance: item.stance, evidence, source };
+}
+
+function dedupeEvidence(evidence: readonly ResearchEvidence[]): ResearchEvidence[] {
+  const seen = new Set<string>();
+  return evidence.filter((item) => {
+    const key = `${item.claim.toLowerCase()}\0${item.stance}\0${item.source.url}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function sanitizeEntries(
+  entries: readonly ResearchReportEntry[],
+  allowedByClaim: ReadonlyMap<string, ReadonlyMap<string, ResearchSource>>,
+  requireCitation: boolean,
+  demoted: ResearchReportEntry[] = [],
+): ResearchReportEntry[] {
+  const sanitized: ResearchReportEntry[] = [];
+  for (const entry of entries) {
+    const claim = normalizedText(entry.claim);
+    const explanation = normalizedText(entry.explanation);
+    if (!claim || !explanation) continue;
+    const allowed = allowedByClaim.get(claim.toLowerCase()) ?? new Map<string, ResearchSource>();
+    const citations = dedupeSources(entry.citations)
+      .map((source) => allowed.get(source.url))
+      .filter(isDefined);
+    if (requireCitation && citations.length === 0) {
+      demoted.push({ claim, explanation: `${explanation} No verified direct-page citation survived validation.`, citations: [] });
+      continue;
+    }
+    sanitized.push({ claim, explanation, citations });
+  }
+  return sanitized;
+}
+
+function isSearchResultsUrl(url: URL): boolean {
+  const host = url.hostname.toLowerCase().replace(/^www\./, "");
+  const path = url.pathname.replace(/\/+$/, "") || "/";
+  if (/^(?:google\.[a-z.]+|bing\.com|search\.yahoo\.com|search\.brave\.com|yandex\.[a-z.]+)$/.test(host)) {
+    return path === "/search" || path === "/results" || path === "/yandsearch";
+  }
+  if (host === "duckduckgo.com") return (path === "/" || path === "/html" || path === "/lite") && url.searchParams.has("q");
+  return false;
+}
+
+function dedupeText(values: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const value of values) {
+    const normalized = normalizedText(value);
+    const key = normalized.toLowerCase();
+    if (!normalized || seen.has(key)) continue;
+    seen.add(key);
+    result.push(normalized);
+  }
+  return result;
+}
+
+function normalizedText(value: string): string {
+  return value.trim().replace(/\s+/g, " ");
+}
+
+function isDefined<T>(value: T | undefined): value is T {
+  return value !== undefined;
+}

package/.pi/extensions/pi-workflow-engine/src/resume-context.ts

@@ -1,6 +1,7 @@
 import { lstat } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { throwIfAborted } from "./cancellation.ts";
+import { isMissingPathError } from "./filesystem-error.ts";
 import type {
   EffectiveAgentSessionIdentity,
   EffectiveToolIdentity,
@@ -66,6 +67,10 @@ export interface AgentResumeContext extends VerifiedAgentResumeBaseContext {
   readonly skills: readonly ResolvedSkillIdentity[];
 }
 
+export interface ResumeContextComparisonOptions {
+  readonly allowWorkflowSourceMismatch?: boolean;
+}
+
 type RepositoryRevision =
   | { readonly state: "git"; readonly head: string }
   | { readonly state: "unborn" };
@@ -306,57 +311,85 @@ async function captureGitVisibleStateUnchecked(
   ]);
   throwIfAborted(signal);
 
-  for (const [operation, result] of [
-    ["unstaged diff capture", unstaged],
-    ["unstaged mode capture", unstagedRaw],
-    ["staged diff capture", staged],
-    ["untracked path capture", untrackedPaths],
-    ["index entry capture", indexEntries],
-    ["tracked flag capture", trackedFlags],
-  ] as const) {
-    if (!result.ok) return { kind: "unverifiable", reason: processFailureReason(`git ${operation}`, result) };
-  }
+  const validated = validateGitVisibleOutputs({ unstaged, unstagedRaw, staged, untrackedPaths, indexEntries, trackedFlags });
+  if (!validated.ok) return { kind: "unverifiable", reason: validated.reason };
+
+  const untracked = await captureDeclaredInputFingerprint({
+    root: cwd,
+    inputs: validated.untrackedPaths.filter((path) => !isFingerprintExcludedPath(path)),
+    excludedRelativePaths: FINGERPRINT_EXCLUDED_RELATIVE_PATHS,
+    maxBytes: CONTENT_FINGERPRINT_MAX_BYTES,
+    maxEntries: GIT_UNTRACKED_MAX_ENTRIES,
+    signal,
+  });
+  if (untracked.kind === "unverifiable") return untracked;
+
+  return {
+    kind: "verified",
+    fingerprint: combineFingerprints([
+      ["unstaged", validated.unstaged],
+      ["staged", validated.staged],
+      ["index", validated.indexEntries],
+      ["untracked", untracked.fingerprint],
+    ]),
+  };
+}
+
+interface GitVisibleProcessOutputs {
+  readonly unstaged: BoundedProcessResult;
+  readonly unstagedRaw: BoundedProcessResult;
+  readonly staged: BoundedProcessResult;
+  readonly untrackedPaths: BoundedProcessResult;
+  readonly indexEntries: BoundedProcessResult;
+  readonly trackedFlags: BoundedProcessResult;
+}
+
+type ValidatedGitVisibleOutputs =
+  | {
+      readonly ok: true;
+      readonly unstaged: string;
+      readonly staged: string;
+      readonly indexEntries: string;
+      readonly untrackedPaths: readonly string[];
+    }
+  | { readonly ok: false; readonly reason: string };
+
+function validateGitVisibleOutputs(outputs: GitVisibleProcessOutputs): ValidatedGitVisibleOutputs {
+  const { unstaged, unstagedRaw, staged, untrackedPaths, indexEntries, trackedFlags } = outputs;
+  if (!unstaged.ok) return { ok: false, reason: processFailureReason("git unstaged diff capture", unstaged) };
+  if (!unstagedRaw.ok) return { ok: false, reason: processFailureReason("git unstaged mode capture", unstagedRaw) };
+  if (!staged.ok) return { ok: false, reason: processFailureReason("git staged diff capture", staged) };
+  if (!untrackedPaths.ok) return { ok: false, reason: processFailureReason("git untracked path capture", untrackedPaths) };
+  if (!indexEntries.ok) return { ok: false, reason: processFailureReason("git index entry capture", indexEntries) };
+  if (!trackedFlags.ok) return { ok: false, reason: processFailureReason("git tracked flag capture", trackedFlags) };
 
   const unsafeWorktreeMode = rawWorktreeModeFailure(unstagedRaw.stdout);
-  if (unsafeWorktreeMode) return { kind: "unverifiable", reason: unsafeWorktreeMode };
+  if (unsafeWorktreeMode) return { ok: false, reason: unsafeWorktreeMode };
 
   for (const record of parseNullTerminatedRecords(indexEntries.stdout, "git index entry capture")) {
     const entry = parseIndexEntry(record);
     if (entry.stage !== 0) {
-      return { kind: "unverifiable", reason: "git-visible repository state contains unmerged paths" };
+      return { ok: false, reason: "git-visible repository state contains unmerged paths" };
     }
     const unsafe = unsafeTrackedModeReason(entry.mode, entry.path);
-    if (unsafe) return { kind: "unverifiable", reason: unsafe };
+    if (unsafe) return { ok: false, reason: unsafe };
   }
 
   const unsafeFlag = parseNullTerminatedRecords(trackedFlags.stdout, "git tracked flag capture")
     .find((record) => record[0] !== "H");
   if (unsafeFlag) {
     return {
-      kind: "unverifiable",
+      ok: false,
       reason: `git-visible repository state contains an unsupported tracked-file flag: ${unsafeFlag[0] ?? "unknown"}`,
     };
   }
 
-  const untracked = await captureDeclaredInputFingerprint({
-    root: cwd,
-    inputs: parseNullTerminatedRecords(untrackedPaths.stdout, "git untracked path capture")
-      .filter((path) => !isFingerprintExcludedPath(path)),
-    excludedRelativePaths: FINGERPRINT_EXCLUDED_RELATIVE_PATHS,
-    maxBytes: CONTENT_FINGERPRINT_MAX_BYTES,
-    maxEntries: GIT_UNTRACKED_MAX_ENTRIES,
-    signal,
-  });
-  if (untracked.kind === "unverifiable") return untracked;
-
   return {
-    kind: "verified",
-    fingerprint: combineFingerprints([
-      ["unstaged", unstaged.stdout],
-      ["staged", staged.stdout],
-      ["index", indexEntries.stdout],
-      ["untracked", untracked.fingerprint],
-    ]),
+    ok: true,
+    unstaged: unstaged.stdout,
+    staged: staged.stdout,
+    indexEntries: indexEntries.stdout,
+    untrackedPaths: parseNullTerminatedRecords(untrackedPaths.stdout, "git untracked path capture"),
   };
 }
 
@@ -470,7 +503,11 @@ export function createAgentResumeContext(
   };
 }
 
-export function resumeContextMismatchReason(stored: AgentResumeContext, current: AgentResumeContext): string | undefined {
+export function resumeContextMismatchReason(
+  stored: AgentResumeContext,
+  current: AgentResumeContext,
+  options: ResumeContextComparisonOptions = {},
+): string | undefined {
   if (stored.repository.state !== current.repository.state) return "repository state changed";
   if (
     (stored.repository.state === "git" || stored.repository.state === "isolated") &&
@@ -483,7 +520,10 @@ export function resumeContextMismatchReason(stored: AgentResumeContext, current:
     return "working tree contents changed";
   }
   if (stored.workflow.name !== current.workflow.name) return "workflow name changed";
-  if (stored.workflow.sourceFingerprint !== current.workflow.sourceFingerprint) return "workflow source changed";
+  if (
+    !options.allowWorkflowSourceMismatch
+    && stored.workflow.sourceFingerprint !== current.workflow.sourceFingerprint
+  ) return "workflow source changed";
   if (stored.session.runtimeVersion !== current.session.runtimeVersion) return "coding-agent runtime changed";
   if (stored.session.systemPromptFingerprint !== current.session.systemPromptFingerprint) return "effective system prompt changed";
   if (
@@ -619,10 +659,6 @@ function isEffectiveToolIdentity(value: unknown): value is EffectiveToolIdentity
   );
 }
 
-function isMissingPathError(error: unknown): boolean {
-  return error instanceof Error && "code" in error && error.code === "ENOENT";
-}
-
 function parseNullTerminatedRecords(output: string, operation: string): string[] {
   if (output.length === 0) return [];
   if (!output.endsWith("\0")) throw new Error(`${operation} returned unterminated data`);

package/.pi/extensions/pi-workflow-engine/src/review/code-review-orchestration.ts

@@ -0,0 +1,49 @@
+import type { AdvisoryCandidate } from "../advisory-schema.ts";
+import { normalizePath, primaryLocation } from "../workflow-advisory-utils.ts";
+
+const DIFF_EMBED_CAP = 60_000;
+
+export function buildCodeReviewScopeBlock(input: {
+  readonly diffCommand: string;
+  readonly files: readonly string[];
+  readonly summary: string;
+  readonly conventions?: string;
+  readonly diffText: string;
+  readonly target: string;
+}): string {
+  const diffBlock = input.diffText
+    ? `\n## Diff (review is bounded to these changed lines)\n\`\`\`diff\n${
+        input.diffText.length > DIFF_EMBED_CAP
+          ? `${input.diffText.slice(0, DIFF_EMBED_CAP)}\n... (truncated — run \`${input.diffCommand}\` for the full diff)`
+          : input.diffText
+      }\n\`\`\`\n`
+    : "";
+  return (
+    `## Diff command\n${input.diffCommand}\n\n## Changed files\n${input.files.map((file) => `- ${file}`).join("\n")}\n\n` +
+    `## Summary\n${input.summary}\n\n## Conventions\n${input.conventions ?? "(none noted)"}\n` +
+    diffBlock +
+    (input.target ? `\n## User instructions (verbatim)\n${input.target}\n` : "")
+  );
+}
+
+export function dedupeCodeReviewCandidates<Context>(
+  groups: readonly { readonly angle: Context; readonly candidates: readonly AdvisoryCandidate[] }[],
+): Array<{ readonly angle: Context; readonly candidate: AdvisoryCandidate }> {
+  const seen = new Set<string>();
+  return groups.flatMap(({ angle, candidates }) =>
+    candidates
+      .filter((candidate) => {
+        const key = codeReviewDedupKey(candidate);
+        if (seen.has(key)) return false;
+        seen.add(key);
+        return true;
+      })
+      .map((candidate) => ({ angle, candidate })),
+  );
+}
+
+function codeReviewDedupKey(candidate: AdvisoryCandidate): string {
+  const location = primaryLocation(candidate);
+  const lineKey = location.line != null ? Math.round(location.line / 5) * 5 : candidate.summary.slice(0, 40).toLowerCase();
+  return `${normalizePath(location.file)}:${lineKey}`;
+}

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

@@ -1,7 +1,7 @@
 import { Type, type Static } from "typebox";
 import { Value } from "typebox/value";
 import { AdvisoryReportWithStatsSchema } from "../advisory-schema.ts";
-import { formatReviewDiffTarget, isReviewDiffTarget, ReviewDiffTargetSchema } from "../diff-capture.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({

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

@@ -3,6 +3,7 @@ import type { WorkflowRunOptions } from "../types.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 =
   | {
@@ -46,6 +47,6 @@ export async function showReviewResultsViewer(
 ): Promise<ReviewIssueSelection> {
   return await ctx.ui.custom<ReviewIssueSelection>(
     (tui, theme, _keybindings, done) => new ReviewResultsViewer(issues, "code-review", tui, theme, done),
-    { overlay: true, overlayOptions: { anchor: "center", width: "80%", minWidth: 40, maxHeight: "80%", margin: 1 } },
+    WORKFLOW_VIEWER_OVERLAY_OPTIONS,
   );
 }

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

@@ -1,11 +1,10 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { matchesKey, visibleWidth, type Component, type TUI } 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 VIEWPORT_HEIGHT_RATIO = 0.8;
-const VIEWPORT_MARGIN_ROWS = 2;
 const SPLIT_WIDTH = 96;
 const LIST_MIN_WIDTH = 34;
 const LIST_MAX_WIDTH = 48;
@@ -34,8 +33,8 @@ export class ReviewResultsViewer implements Component {
   render(width: number): string[] {
     const outerWidth = Math.max(4, width);
     const contentWidth = Math.max(1, outerWidth - 4);
-    const innerHeight = Math.max(1, this.modalHeight() - 2);
-    const body = fitRows(this.renderBody(contentWidth, innerHeight), innerHeight);
+    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)),
@@ -94,20 +93,13 @@ export class ReviewResultsViewer implements Component {
     }
   }
 
-  private modalHeight(): number {
-    const terminalRows = Math.max(1, this.tui.terminal.rows);
-    const availableRows = Math.max(1, terminalRows - VIEWPORT_MARGIN_ROWS);
-    const proportionalRows = Math.floor(terminalRows * VIEWPORT_HEIGHT_RATIO);
-    return Math.min(availableRows, Math.max(3, proportionalRows));
-  }
-
   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 = fitRows([this.theme.fg("success", "No findings.")], contentHeight);
+      content = fitWorkflowViewerRows([this.theme.fg("success", "No findings.")], contentHeight);
     } else if (width >= SPLIT_WIDTH) {
       content = this.renderSplit(width, contentHeight);
     } else {
@@ -118,7 +110,7 @@ export class ReviewResultsViewer implements Component {
       this.headerLine(width),
       warning,
       this.theme.fg("borderMuted", "─".repeat(width)),
-      ...fitRows(content, contentHeight),
+      ...fitWorkflowViewerRows(content, contentHeight),
       this.theme.fg("borderMuted", "─".repeat(width)),
       this.helpLine(width),
     ];
@@ -131,7 +123,7 @@ export class ReviewResultsViewer implements Component {
     const details = this.renderDetailPane(detailWidth, height);
     const divider = this.theme.fg("borderMuted", "│");
     return Array.from({ length: height }, (_value, index) =>
-      `${padAnsi(list[index] ?? "", listWidth)} ${divider} ${padAnsi(details[index] ?? "", detailWidth)}`,
+      `${fitWorkflowViewerRow(list[index] ?? "", listWidth)} ${divider} ${fitWorkflowViewerRow(details[index] ?? "", detailWidth)}`,
     );
   }
 
@@ -171,7 +163,7 @@ export class ReviewResultsViewer implements Component {
       width,
     );
     const indicator = truncateDisplay(this.theme.fg("dim", `${range}${arrows ? ` ${arrows}` : ""}`), width);
-    return [heading, ...fitRows(visible, itemRows), indicator].slice(0, height);
+    return [heading, ...fitWorkflowViewerRows(visible, itemRows), indicator].slice(0, height);
   }
 
   private renderIssueRow(issue: ReviewIssue, index: number, width: number): string {
@@ -185,7 +177,7 @@ export class ReviewResultsViewer implements Component {
   private renderDetailPane(width: number, height: number): string[] {
     if (height <= 0) return [];
     const issue = this.issues[this.cursor];
-    if (!issue) return fitRows([this.theme.fg("dim", "No finding selected.")], height);
+    if (!issue) return fitWorkflowViewerRows([this.theme.fg("dim", "No finding selected.")], height);
 
     const bodyHeight = Math.max(0, height - 2);
     const heading = truncateDisplay(
@@ -206,7 +198,7 @@ export class ReviewResultsViewer implements Component {
       this.theme.fg("dim", `${this.detailsExpanded ? "Lines" : "Collapsed"} ${range}${arrows ? ` ${arrows}` : ""}`),
       width,
     );
-    return [heading, ...fitRows(visible, bodyHeight), indicator].slice(0, height);
+    return [heading, ...fitWorkflowViewerRows(visible, bodyHeight), indicator].slice(0, height);
   }
 
   private headerLine(width: number): string {
@@ -229,7 +221,7 @@ export class ReviewResultsViewer implements Component {
   }
 
   private borderedRow(content: string, width: number): string {
-    return `${this.theme.fg("border", "│")} ${padAnsi(content, width)} ${this.theme.fg("border", "│")}`;
+    return `${this.theme.fg("border", "│")} ${fitWorkflowViewerRow(content, width)} ${this.theme.fg("border", "│")}`;
   }
 
   private requestRender(): void {
@@ -300,17 +292,6 @@ export class ReviewResultsViewer implements Component {
   }
 }
 
-function fitRows(lines: readonly string[], height: number): string[] {
-  const visible = lines.slice(0, Math.max(0, height));
-  return [...visible, ...Array.from({ length: Math.max(0, height - visible.length) }, () => "")];
-}
-
-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 ? "↓" : ""}`;
 }