pi-workflow-engine 0.4.0 → 0.6.1

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

@@ -0,0 +1,132 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { truncateDisplay, type WorkflowThemeColor } from "../ui/workflow-format.ts";
+import { formatIssueLocation, type ReviewIssue } from "./review-issues.ts";
+
+export interface RenderIssuesTableOptions {
+  readonly maxRows?: number;
+}
+
+const DEFAULT_MAX_ROWS = 12;
+const ID_WIDTH = 4;
+const SEVERITY_WIDTH = 6;
+const CONFIDENCE_WIDTH = 6;
+const CATEGORY_WIDTH = 8;
+const LOCATION_WIDTH = 30;
+const SUMMARY_WIDTH = 58;
+
+export function renderIssuesTable(issues: readonly ReviewIssue[], theme: Theme, options: RenderIssuesTableOptions = {}): string {
+  const maxRows = options.maxRows ?? DEFAULT_MAX_ROWS;
+  const visible = maxRows >= 0 ? issues.slice(0, maxRows) : issues;
+  const lines = [
+    renderRow(["ID", "Sev", "Conf", "Cat", "Location", "Summary"], theme.fg("dim", "│"), theme, true),
+    theme.fg("dim", renderSeparator()),
+  ];
+
+  for (const issue of visible) {
+    lines.push(
+      renderRow(
+        [
+          issue.id,
+          issue.finding.severity,
+          issue.finding.confidence,
+          issue.finding.category,
+          formatIssueLocation(issue),
+          issue.finding.summary,
+        ],
+        theme.fg("dim", "│"),
+        theme,
+        false,
+        issue,
+      ),
+    );
+  }
+
+  if (issues.length > visible.length) {
+    lines.push(theme.fg("dim", `… ${issues.length - visible.length} more finding(s)`));
+  }
+
+  return lines.join("\n");
+}
+
+export function renderIssueDetails(issue: ReviewIssue, theme: Theme): string {
+  return renderIssueDetailLines(issue, theme, 120).join("\n");
+}
+
+export function renderIssueDetailLines(issue: ReviewIssue, theme: Theme, width: number): string[] {
+  const finding = issue.finding;
+  const metadata = `${finding.category} · severity ${finding.severity} · confidence ${finding.confidence}`;
+  const lines = [`${theme.fg("accent", issue.id)} ${theme.fg("text", finding.summary)}`];
+  lines.push(...fieldLines("Metadata", metadata, width, theme));
+  lines.push(...fieldLines("Location", formatIssueLocation(issue), width, theme, "accent"));
+  lines.push(...fieldLines("Impact", finding.impact, width, theme));
+  lines.push(...fieldLines("Evidence", finding.evidence.join("; ") || "(none cited)", width, theme));
+  lines.push(...fieldLines("Recommendation", finding.recommendation, width, theme));
+  return lines.flatMap((line) => wrapTextWithAnsi(line, Math.max(10, width)));
+}
+
+function fieldLines(label: string, value: string, width: number, theme: Theme, valueColor: WorkflowThemeColor = "muted"): string[] {
+  const prefix = `  ${theme.fg("dim", `${label}:`)}`;
+  const separator = " ";
+  const valueText = theme.fg(valueColor, value);
+  const available = Math.max(10, width - visibleWidth(`${label}:  `) - 2);
+  const wrapped = wrapTextWithAnsi(valueText, available);
+  if (wrapped.length === 0) return [`${prefix}${separator}`];
+  const continuation = " ".repeat(visibleWidth(`${label}:  `) + 2);
+  return wrapped.map((line, index) => (index === 0 ? `${prefix}${separator}${line}` : `${continuation}${line}`));
+}
+
+function renderRow(
+  cells: readonly [string, string, string, string, string, string],
+  separator: string,
+  theme: Theme,
+  header: boolean,
+  issue?: ReviewIssue,
+): string {
+  const rendered = [
+    cell(cells[0], ID_WIDTH),
+    colorCell(cell(cells[1], SEVERITY_WIDTH), header ? "dim" : severityColor(issue?.finding.severity ?? "low"), theme),
+    colorCell(cell(cells[2], CONFIDENCE_WIDTH), header ? "dim" : confidenceColor(issue?.finding.confidence ?? "low"), theme),
+    cell(cells[3], CATEGORY_WIDTH),
+    cell(cells[4], LOCATION_WIDTH),
+    cell(cells[5], SUMMARY_WIDTH),
+  ];
+  if (header) {
+    return rendered.map((entry) => theme.fg("dim", entry)).join(` ${separator} `);
+  }
+  return rendered.join(` ${separator} `);
+}
+
+function cell(value: string, width: number): string {
+  return truncateDisplay(value, width).padEnd(width, " ");
+}
+
+function colorCell(value: string, color: WorkflowThemeColor, theme: Theme): string {
+  return theme.fg(color, value);
+}
+
+function renderSeparator(): string {
+  return [ID_WIDTH, SEVERITY_WIDTH, CONFIDENCE_WIDTH, CATEGORY_WIDTH, LOCATION_WIDTH, SUMMARY_WIDTH].map((width) => "─".repeat(width)).join("─┼─");
+}
+
+function severityColor(severity: ReviewIssue["finding"]["severity"]): WorkflowThemeColor {
+  switch (severity) {
+    case "high":
+      return "error";
+    case "medium":
+      return "warning";
+    case "low":
+      return "muted";
+  }
+}
+
+function confidenceColor(confidence: ReviewIssue["finding"]["confidence"]): WorkflowThemeColor {
+  switch (confidence) {
+    case "high":
+      return "success";
+    case "medium":
+      return "warning";
+    case "low":
+      return "muted";
+  }
+}

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

@@ -0,0 +1,90 @@
+import { formatIssueLocation, type ReviewContext, type ReviewIssue } from "./review-issues.ts";
+
+export interface ReviewHandoffPayload {
+  readonly context: ReviewContext | undefined;
+  readonly issues: readonly ReviewHandoffIssue[];
+}
+
+export interface ReviewHandoffIssue {
+  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 buildFixHandoffPrompt(issues: readonly ReviewIssue[], context: ReviewContext | undefined): string {
+  return `Use the workflow-code-review-actions skill if available.
+
+Mode: fix selected code-review findings.
+
+Selected findings JSON:
+\`\`\`json
+${JSON.stringify(toHandoffPayload(issues, context))}
+\`\`\`
+
+Instructions:
+- Inspect the selected issue JSON before editing.
+- Make minimal edits that address only the selected findings.
+- Preserve unrelated user changes and avoid broad refactors.
+- Run focused validation if an appropriate local check is available.
+- Do not post GitHub PR comments or any upstream review comments.
+- Summarize changed files and validation results when done.`;
+}
+
+export function buildCommentHandoffPrompt(issues: readonly ReviewIssue[], context: ReviewContext | undefined, reason: string): string {
+  return `Use the workflow-code-review-actions skill if available.
+
+Mode: post inline GitHub PR comments for selected code-review findings.
+
+Fallback reason: ${reason}
+
+Selected findings JSON:
+\`\`\`json
+${JSON.stringify(toHandoffPayload(issues, context))}
+\`\`\`
+
+Instructions:
+- Do not edit files or make code changes.
+- Prefer installed GitHub MCP/tools if present; otherwise use the GitHub CLI (gh).
+- With gh, resolve the PR using \`gh pr view\` and \`gh repo view\`, then call \`gh api repos/{owner}/{repo}/pulls/{number}/comments\` with \`commit_id\`, \`path\`, \`line\`, and \`side=RIGHT\`.
+- Do not post duplicate comments.
+- Do not post line-less findings as inline comments.
+- Ask the user if the upstream PR cannot be identified.
+- Summarize posted, skipped, and failed comments when done.`;
+}
+
+function toHandoffPayload(issues: readonly ReviewIssue[], context: ReviewContext | undefined): ReviewHandoffPayload {
+  return {
+    context,
+    issues: issues.map(toHandoffIssue),
+  };
+}
+
+function toHandoffIssue(issue: ReviewIssue): ReviewHandoffIssue {
+  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,
+  };
+}

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

@@ -0,0 +1,61 @@
+import type { AdvisoryFinding, AdvisoryReport } from "../advisory-schema.ts";
+
+export type ReviewIssueAction = "fix" | "comment" | "close";
+
+export interface ReviewIssueSelection {
+  readonly action: ReviewIssueAction;
+  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;
+  readonly workflowName: string;
+  readonly file?: string;
+  readonly line?: number;
+  readonly symbol?: string;
+  readonly finding: AdvisoryFinding;
+}
+
+export interface ReviewReportWithContext extends AdvisoryReport {
+  readonly stats?: Record<string, string | number>;
+  readonly reviewContext?: ReviewContext;
+}
+
+export function toReviewIssues(name: string, report: Pick<AdvisoryReport, "findings">): ReviewIssue[] {
+  return report.findings.map((finding, index) => {
+    const location = finding.locations[0];
+    return {
+      id: formatIssueId(index),
+      index,
+      workflowName: name,
+      file: location?.file,
+      line: location?.line,
+      symbol: location?.symbol,
+      finding,
+    };
+  });
+}
+
+export function formatIssueLocation(issue: ReviewIssue): string {
+  if (!issue.file) return "(no location)";
+  const line = issue.line != null ? `:${issue.line}` : "";
+  const symbol = issue.symbol ? ` (${issue.symbol})` : "";
+  return `${issue.file}${line}${symbol}`;
+}
+
+export function isCommentableIssue(issue: ReviewIssue): boolean {
+  return typeof issue.file === "string" && issue.file.trim().length > 0 && typeof issue.line === "number" && Number.isFinite(issue.line);
+}
+
+function formatIssueId(index: number): string {
+  return `R${String(index + 1).padStart(3, "0")}`;
+}

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

@@ -0,0 +1,56 @@
+import type { ExtensionCommandContext } 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 { ReviewResultsViewer } from "./review-results-viewer.ts";
+
+export type ReviewResultsPresentationDecision =
+  | {
+      readonly kind: "send";
+      readonly reason: "tool-invocation" | "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 };
+
+export interface ReviewResultsDecisionInput {
+  readonly workflowName: string;
+  readonly result: unknown;
+  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 extensionContextMode(ctx: ExtensionCommandContext): string | undefined {
+  const candidate = (ctx as ExtensionCommandContext & { readonly mode?: unknown }).mode;
+  return typeof candidate === "string" ? candidate : undefined;
+}
+
+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" };
+  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 };
+}
+
+export async function maybeShowReviewResultsViewer(
+  ctx: ReviewResultsViewerContext,
+  decision: ReviewResultsPresentationDecision,
+): Promise<ReviewIssueSelection | undefined> {
+  if (decision.kind !== "open") return undefined;
+
+  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 } },
+  );
+}

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

@@ -0,0 +1,240 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { matchesKey, visibleWidth, type Component } 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";
+
+const MIN_WIDTH = 40;
+const SPLIT_WIDTH = 96;
+const LIST_MIN_WIDTH = 34;
+const LIST_MAX_WIDTH = 48;
+const DETAIL_SCROLL_STEP = 5;
+
+export class ReviewResultsViewer implements Component {
+  private readonly selected = new Set<string>();
+  private cursor = 0;
+  private detailScroll = 0;
+  private detailsExpanded = true;
+  private warning: string | undefined;
+
+  constructor(
+    private readonly issues: readonly ReviewIssue[],
+    private readonly workflowName: string,
+    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)];
+  }
+
+  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")) {
+      this.done({ action: "close", issueIds: this.selectedIssueIds() });
+    }
+  }
+
+  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];
+
+    const split = width >= SPLIT_WIDTH;
+    const content = split ? this.renderSplit(width) : this.renderStacked(width);
+    return [header, ...warning, ...content, help];
+  }
+
+  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 renderStacked(width: number): string[] {
+    return [...this.renderIssueList(width), this.theme.fg("dim", "─".repeat(Math.max(1, width))), ...this.renderDetail(width)];
+  }
+
+  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 renderDetail(width: number): string[] {
+    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));
+  }
+
+  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);
+  }
+
+  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);
+  }
+
+  private topBorder(innerWidth: number): string {
+    return `┌${this.theme.fg("dim", "─".repeat(innerWidth))}┐`;
+  }
+
+  private bottomBorder(innerWidth: number): string {
+    return `└${this.theme.fg("dim", "─".repeat(innerWidth))}┘`;
+  }
+
+  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();
+  }
+
+  private toggleCurrent(): void {
+    const issue = this.issues[this.cursor];
+    if (!issue) return;
+    this.toggleIssue(issue.id);
+    this.warning = undefined;
+    this.requestRender();
+  }
+
+  private toggleAllVisible(): 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();
+  }
+
+  private scrollDetail(delta: number): void {
+    this.detailScroll = Math.max(0, this.detailScroll + delta);
+    this.warning = undefined;
+    this.requestRender();
+  }
+
+  private finishSelected(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();
+      return;
+    }
+    this.done({ action, issueIds });
+  }
+
+  private toggleIssue(id: string): void {
+    if (this.selected.has(id)) this.selected.delete(id);
+    else this.selected.add(id);
+  }
+
+  private selectedIssueIds(): string[] {
+    return this.issues.filter((issue) => this.selected.has(issue.id)).map((issue) => issue.id);
+  }
+}
+
+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 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";
+  }
+}

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

@@ -2,6 +2,7 @@ import type { Static, TSchema } from "typebox";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Pipeline } from "./concurrency.ts";
 import type { PerfSink, PerfSnapshot } from "./perf.ts";
+import type { WorkflowProgressSnapshot } from "./progress.ts";
 
 /** Metadata every workflow module must export. */
 export interface WorkflowMeta {
@@ -23,12 +24,15 @@ export interface WorkflowRunOptions {
   perf?: boolean;
   concurrency?: number;
   parallelSubmissionLimit?: number;
+  resultViewer?: "open" | "skip";
   /** Additional abort signal to compose with the host context signal. */
   signal?: AbortSignal;
   /** Internal recorder override for command/tool invocation timing. */
   perfRecorder?: PerfSink;
   /** Called with the final performance snapshot when perf is enabled. */
   onPerfSnapshot?: (snapshot: PerfSnapshot) => void;
+  /** Called with the final completed progress snapshot after live workflow UI teardown. */
+  onProgressSnapshot?: (snapshot: WorkflowProgressSnapshot) => void;
 }
 
 /** Options for a single `agent()` call. */

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

@@ -1,5 +1,5 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { matchesKey, type TUI, visibleWidth } from "@earendil-works/pi-tui";
+import { matchesKey, type TUI, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import type { AgentRowSnapshot, WorkflowLaneItemSnapshot, WorkflowProgressSnapshot } from "../progress.ts";
 import { agentDetailParts, formatCount, formatDuration, statusIcon, truncateDisplay } from "./workflow-format.ts";
 
@@ -89,7 +89,7 @@ export class WorkflowInspector {
     const count = Math.max(1, this.itemCount(this.currentSection()));
     lines.push(
       this.row(
-        `${th.fg("dim", `${body.length} lines · ${pct} · ${selected}/${count}`)} ${th.fg("dim", "· tab sections · ↑↓ select · enter expand · q/esc close")}`,
+        `${th.fg("dim", `${body.length} lines · ${pct} · ${selected}/${count}`)} ${th.fg("dim", "· tab sections · ↑↓ select · enter expand/collapse · q/esc close")}`,
         inner,
       ),
     );
@@ -208,7 +208,7 @@ export class WorkflowInspector {
     return lines.length > 0 ? lines : [{ text: `    ${this.theme.fg("dim", "No details yet.")}` }];
   }
 
-  private findingLines(snapshot: WorkflowProgressSnapshot, _width: number): InspectorLine[] {
+  private findingLines(snapshot: WorkflowProgressSnapshot, width: number): InspectorLine[] {
     const lines: InspectorLine[] = [];
     let selectableIndex = -1;
     const overflowByLane = new Map(snapshot.laneOverflow);
@@ -221,7 +221,7 @@ export class WorkflowInspector {
         const key = `finding:${lane}:${index}:${item.createdAt}`;
         const selected = this.currentSection() === "Findings" && this.selected.Findings === selectableIndex;
         lines.push({ text: this.findingLine(item, selected), selectable: true, key });
-        if (this.expanded.has(key) && item.details) lines.push({ text: `    ${this.theme.fg("dim", item.details)}` });
+        if (this.expanded.has(key)) lines.push(...this.findingDetails(item, width));
       });
     }
     return lines.length > 0 ? lines : [{ text: this.theme.fg("dim", "No findings lanes yet.") }];
@@ -233,6 +233,24 @@ export class WorkflowInspector {
     return selected ? this.theme.bg("selectedBg", text) : text;
   }
 
+  private findingDetails(item: WorkflowLaneItemSnapshot, width: number): InspectorLine[] {
+    return [
+      ...this.detailFieldLines("Title", item.title, width, "text"),
+      ...this.detailFieldLines("Location", item.subtitle || "(unknown)", width, "accent"),
+      ...this.detailFieldLines("Status", item.status, width, "muted"),
+      ...this.detailFieldLines("Details", item.details || "(no details)", width, "muted"),
+    ];
+  }
+
+  private detailFieldLines(label: string, value: string, width: number, color: Parameters<Theme["fg"]>[0]): InspectorLine[] {
+    const plainPrefix = `  ${label}: `;
+    const prefix = `    ${this.theme.fg("dim", `${label}:`)} `;
+    const continuation = `    ${" ".repeat(visibleWidth(`${label}: `))}`;
+    const wrapped = wrapTextWithAnsi(this.theme.fg(color, value), Math.max(10, width - visibleWidth(plainPrefix) - 4));
+    if (wrapped.length === 0) return [{ text: prefix }];
+    return wrapped.map((line, index) => ({ text: `${index === 0 ? prefix : continuation}${line}` }));
+  }
+
   private logLines(snapshot: WorkflowProgressSnapshot): InspectorLine[] {
     if (snapshot.logs.length === 0) return [{ text: this.theme.fg("dim", "No logs yet.") }];
     return snapshot.logs.map((log, index) => {