pi-workflow-engine 0.12.0 → 1.0.0

package/.pi/extensions/pi-workflow-engine/src/review/github-pr-comments.ts

@@ -1,6 +1,7 @@
 import { throwIfAborted } from "../cancellation.ts";
-import { isCommentableIssue, type ReviewIssue } from "./review-issues.ts";
-import type { ReviewContext } from "./review-report.ts";
+import { isFiniteNumber, isRecord } from "../guards.ts";
+import type { CommentableReviewIssue, ReviewIssue } from "./review-issues.ts";
+import { unknownErrorMessage } from "../unknown-error.ts";
 
 export interface ExecResultLike {
   readonly stdout: string;
@@ -30,24 +31,16 @@ export type InlineCommentStatus =
   | { readonly issueId: string; readonly status: "skipped"; readonly reason: string }
   | { readonly issueId: string; readonly status: "failed"; readonly reason: string };
 
-const PR_VIEW_JSON_FIELDS = "number,headRefOid,url";
-
 export async function resolveGitHubPrContext(
   exec: ExecLike,
   cwd: string,
-  reviewContext: ReviewContext | undefined,
+  number: number,
   signal?: AbortSignal,
 ): Promise<ResolveGitHubPrContextResult> {
-  const parsedNumber = reviewContext?.diffTarget.kind === "pull-request" ? reviewContext.diffTarget.number : undefined;
-  const prArgs = parsedNumber
-    ? ["pr", "view", String(parsedNumber), "--json", PR_VIEW_JSON_FIELDS]
-    : ["pr", "view", "--json", PR_VIEW_JSON_FIELDS];
-  const prView = await runJson(exec, cwd, prArgs, signal);
+  const prView = await runJson(exec, cwd, ["pr", "view", String(number), "--json", "headRefOid,url"], signal);
   if (!prView.ok) return { ok: false, reason: prView.reason };
 
-  const number = numberField(prView.value, "number") ?? parsedNumber;
   const headSha = stringField(prView.value, "headRefOid");
-  if (number === undefined) return { ok: false, reason: "No GitHub PR number found." };
   if (!headSha) return { ok: false, reason: "GitHub PR head SHA is missing." };
 
   const url = stringField(prView.value, "url");
@@ -82,15 +75,13 @@ ${evidence}
 Recommendation: ${finding.recommendation}`;
 }
 
-export async function postInlineComment(
+async function postInlineComment(
   exec: ExecLike,
   cwd: string,
   prContext: GitHubPrContext,
-  issue: ReviewIssue,
+  issue: CommentableReviewIssue,
   signal?: AbortSignal,
 ): Promise<InlineCommentStatus> {
-  if (!isCommentableIssue(issue)) return { issueId: issue.id, status: "skipped", reason: "Finding has no commentable file/line." };
-
   const result = await runCommand(exec, cwd, [
     "api",
     `repos/${prContext.owner}/${prContext.repo}/pulls/${prContext.number}/comments`,
@@ -113,7 +104,7 @@ export async function postInlineComments(
   exec: ExecLike,
   cwd: string,
   prContext: GitHubPrContext,
-  issues: readonly ReviewIssue[],
+  issues: readonly CommentableReviewIssue[],
   signal?: AbortSignal,
 ): Promise<InlineCommentStatus[]> {
   throwIfAborted(signal);
@@ -125,14 +116,14 @@ export async function postInlineComments(
   const statuses: InlineCommentStatus[] = [];
   for (const issue of issues) {
     throwIfAborted(signal);
-    const key = inlineCommentKey(issue, prContext.headSha);
-    if (key && existing.keys.has(key)) {
+    const key = commentKey(buildInlineCommentBody(issue), issue.file, issue.line, prContext.headSha);
+    if (existing.keys.has(key)) {
       statuses.push({ issueId: issue.id, status: "skipped", reason: "An identical inline comment already exists on this PR head." });
       continue;
     }
     const status = await postInlineComment(exec, cwd, prContext, issue, signal);
     statuses.push(status);
-    if (key && status.status === "posted") existing.keys.add(key);
+    if (status.status === "posted") existing.keys.add(key);
   }
   return statuses;
 }
@@ -161,7 +152,7 @@ async function runJson(
   try {
     return { ok: true, value: JSON.parse(result.stdout) };
   } catch (error) {
-    return { ok: false, reason: error instanceof Error ? `Invalid gh JSON: ${error.message}` : "Invalid gh JSON." };
+    return { ok: false, reason: `Invalid gh JSON: ${unknownErrorMessage(error)}` };
   }
 }
 
@@ -179,7 +170,7 @@ async function runCommand(
     return { ok: true, stdout: result.stdout };
   } catch (error) {
     throwIfAborted(signal);
-    return { ok: false, reason: error instanceof Error ? error.message : "gh command failed." };
+    return { ok: false, reason: unknownErrorMessage(error) };
   }
 }
 
@@ -197,10 +188,6 @@ function parseExistingInlineCommentKeys(value: unknown): Set<string> | undefined
   return keys;
 }
 
-function inlineCommentKey(issue: ReviewIssue, headSha: string): string | undefined {
-  return isCommentableIssue(issue) ? commentKey(buildInlineCommentBody(issue), issue.file, issue.line, headSha) : undefined;
-}
-
 function commentKey(body: string, path: string, line: number, headSha: string): string {
   return JSON.stringify([body, path, line, headSha]);
 }
@@ -208,7 +195,7 @@ function commentKey(body: string, path: string, line: number, headSha: string):
 function numberField(value: unknown, key: string): number | undefined {
   if (!isRecord(value)) return undefined;
   const field = value[key];
-  return typeof field === "number" && Number.isFinite(field) ? field : undefined;
+  return isFiniteNumber(field) ? field : undefined;
 }
 
 function stringField(value: unknown, key: string): string | undefined {
@@ -243,7 +230,3 @@ function parsePostedCommentUrl(stdout: string): string | undefined {
     return undefined;
   }
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
-}

package/.pi/extensions/pi-workflow-engine/src/review/patch-validation.ts

@@ -0,0 +1,119 @@
+import { createHash } from "node:crypto";
+import { Type, type Static } from "typebox";
+import { throwIfAborted } from "../cancellation.ts";
+import { runBoundedProcess, type BoundedProcessResult } from "../process-runner.ts";
+import { WorktreeRegistry, type WorktreeBaseline } from "../worktree.ts";
+import { unknownErrorMessage } from "../unknown-error.ts";
+import { fingerprintReviewWorktreeBaseline } from "./review-snapshot.ts";
+
+export const PatchEvaluationSchema = Type.Object({
+  outcome: Type.Union([Type.Literal("accepted"), Type.Literal("rejected"), Type.Literal("blocked")]),
+  reason: Type.String(),
+  checks: Type.Array(Type.Object({
+    file: Type.String({ description: "Executable for a focused validation command, not a shell command string." }),
+    args: Type.Array(Type.String()),
+    required: Type.Boolean(),
+    regression: Type.Optional(Type.Object({
+      baselinePatch: Type.String({ description: "Test-only patch to apply to the original baseline to reproduce the bug; exclude the repair." }),
+      expectedFailure: Type.String({ description: "Specific failure text proving the intended defect, not a missing dependency or setup error." }),
+    })),
+  }), { maxItems: 6 }),
+});
+export type PatchEvaluation = Static<typeof PatchEvaluationSchema>;
+export type PatchCandidateStatus = "verified" | "rejected" | "blocked" | "no-patch";
+export interface PatchValidation {
+  status: PatchCandidateStatus;
+  baselineFingerprint: string;
+  baselineOid?: string;
+  patchHash: string;
+  checks: { file: string; args: string[]; required: boolean; stage: "candidate" | "baseline"; result: BoundedProcessResult }[];
+  evaluation?: PatchEvaluation;
+  reason: string;
+  cleanupError?: string;
+}
+export function initialPatchValidation(baseline: WorktreeBaseline, baselineOid: string | undefined, patch: string): PatchValidation {
+  return { status: patch.trim() ? "blocked" : "no-patch", baselineFingerprint: fingerprintReviewWorktreeBaseline(baseline), ...(baselineOid ? { baselineOid } : {}),
+    patchHash: createHash("sha256").update(patch).digest("hex"), checks: [], reason: patch.trim() ? "Independent evaluation has not completed." : "The implementer produced no patch; this does not establish that no change is needed." };
+}
+
+interface PatchValidationOptions {
+  cwd: string; baseline: WorktreeBaseline; baselineOid: string; patch: string;
+  evaluation: PatchEvaluation; signal?: AbortSignal;
+}
+
+/** Reconstruct the exact reviewed baseline and retain evidence even if cleanup fails. */
+export async function validateCandidatePatch(options: PatchValidationOptions): Promise<PatchValidation> {
+  const validation = initialPatchValidation(options.baseline, options.baselineOid, options.patch);
+  validation.evaluation = options.evaluation;
+  if (!options.patch.trim()) return validation;
+  const worktrees = new WorktreeRegistry(options.cwd);
+  let result = validation;
+  try {
+    result = await evaluateCandidateInWorktrees(worktrees, options, validation);
+  } catch (error) {
+    throwIfAborted(options.signal);
+    result = { ...validation, status: "blocked", reason: unknownErrorMessage(error) };
+  } finally {
+    try {
+      await worktrees.removeAll();
+    } catch (error) {
+      const cleanupError = unknownErrorMessage(error);
+      result = {
+        ...result,
+        status: result.status === "verified" ? "blocked" : result.status,
+        cleanupError,
+        reason: `${result.reason}\nCleanup failed: ${cleanupError}`,
+      };
+    }
+    throwIfAborted(options.signal);
+  }
+  return result;
+}
+
+async function evaluateCandidateInWorktrees(
+  worktrees: WorktreeRegistry, options: PatchValidationOptions, validation: PatchValidation,
+): Promise<PatchValidation> {
+  const candidate = await worktrees.add(options.signal, options.baseline);
+  if ("error" in candidate) return { ...validation, reason: candidate.error };
+  if (candidate.baselineOid !== options.baselineOid) return { ...validation, status: "rejected", reason: "Candidate was produced from a different baseline." };
+  const applied = await worktrees.applyPatch(candidate.path, options.patch, options.signal);
+  if (!applied.ok) return { ...validation, status: "rejected", reason: applied.error };
+  const rejected = options.evaluation.outcome === "rejected" ? [options.evaluation.reason] : [];
+  const blocked = options.evaluation.outcome === "blocked" ? [options.evaluation.reason] : [];
+  if (!options.evaluation.checks.some((check) => check.required)) blocked.push("No required behavior check was selected.");
+  for (const check of options.evaluation.checks) {
+    const result = await runCheck(check, candidate.path, options.signal);
+    validation.checks.push({ ...check, stage: "candidate", result });
+    throwIfAborted(options.signal);
+    if (!result.ok) {
+      if (result.failure.kind === "exit") rejected.push(`${check.file}: ${result.failure.message}`);
+      else if (check.required) blocked.push(`${check.file}: ${result.failure.message}`);
+    }
+    if (check.regression) {
+      const original = await worktrees.add(options.signal, options.baseline);
+      if ("error" in original) { blocked.push(`Baseline worktree setup failed: ${original.error}`); continue; }
+      const testApplied = await worktrees.applyPatch(original.path, check.regression.baselinePatch, options.signal);
+      if (!testApplied.ok) { blocked.push(`Baseline regression setup failed: ${testApplied.error}`); continue; }
+      const baselineResult = await runCheck(check, original.path, options.signal);
+      validation.checks.push({ ...check, stage: "baseline", result: baselineResult });
+      throwIfAborted(options.signal);
+      if (baselineResult.ok || baselineResult.failure.kind !== "exit" || !check.regression.expectedFailure.trim() ||
+        !(baselineResult.stdout + baselineResult.stderr).includes(check.regression.expectedFailure)) {
+        blocked.push(`${check.file}: baseline did not reproduce the expected failure: ${check.regression.expectedFailure}`);
+      }
+    }
+  }
+  // Tests must not silently replace the candidate under evaluation.
+  const after = await worktrees.capturePatch(candidate.path, candidate.baselineOid, options.signal);
+  if ("error" in after) blocked.push(`Candidate capture failed: ${after.error}`);
+  else if (after.patch !== options.patch) blocked.push("Validation checks changed the candidate patch.");
+  if (rejected.length > 0) return { ...validation, status: "rejected", reason: [...rejected, ...blocked].join("\n") };
+  if (blocked.length > 0) return { ...validation, status: "blocked", reason: blocked.join("\n") };
+  return { ...validation, status: "verified", reason: "Independent evaluation and all required checks passed." };
+}
+
+function runCheck(check: PatchEvaluation["checks"][number], cwd: string, signal?: AbortSignal): Promise<BoundedProcessResult> {
+  return runBoundedProcess({ file: check.file, args: check.args, cwd, signal, timeoutMs: 120_000, maxBufferBytes: 1 << 20,
+    abortError: "Validation aborted", timeoutError: "Validation timed out", maxBufferError: "Validation output exceeded its limit",
+    exitError: (stderr, code) => stderr.trim() || `Validation exited with ${code}` });
+}

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

@@ -104,7 +104,7 @@ async function handleCommentAction(
   }
 
   const exec = toExecLike(pi);
-  const resolved = await resolveGitHubPrContext(exec, ctx.cwd, context, ctx.signal);
+  const resolved = await resolveGitHubPrContext(exec, ctx.cwd, context.diffTarget.number, ctx.signal);
   if (!resolved.ok) {
     await queueCommentFallback(pi, ctx, commentable, context, baseline.ref, resolved.reason);
     return;

package/.pi/extensions/pi-workflow-engine/src/review/review-diff-lines.ts

@@ -0,0 +1,54 @@
+import { repoPathCandidates } from "../advisory-evidence.ts";
+import type { AdvisoryLocation } from "../advisory-schema.ts";
+
+const C_QUOTE_ESCAPES: Readonly<Record<string, number>> = { a: 7, b: 8, t: 9, n: 10, v: 11, f: 12, r: 13, '"': 34, "\\": 92 };
+
+/** Undo git's C-style quoting of unusual path names, e.g. `"b/caf\303\251.txt"`. */
+function unquoteGitPath(path: string): string {
+  if (path.length < 2 || !path.startsWith('"') || !path.endsWith('"')) return path;
+  const bytes: number[] = [];
+  for (const [, escape, literal] of path.slice(1, -1).matchAll(/\\([0-7]{3}|.)|([^\\]+)/g)) {
+    if (literal !== undefined) bytes.push(...Buffer.from(literal));
+    else if (escape !== undefined) bytes.push(escape.length === 3 ? parseInt(escape, 8) : (C_QUOTE_ESCAPES[escape] ?? escape.charCodeAt(0)));
+  }
+  return Buffer.from(bytes).toString("utf8");
+}
+
+/** Parse a unified diff into the set of added/changed new-file line numbers per file. */
+export function changedLines(diff: string): Map<string, Set<number>> {
+  const byFile = new Map<string, Set<number>>();
+  let file: string | null = null;
+  let newLine = 0;
+  for (const raw of diff.split("\n")) {
+    if (raw.startsWith("+++ ")) {
+      const path = unquoteGitPath(raw.slice(4).trim());
+      file = path === "/dev/null" ? null : path.replace(/^b\//, "");
+      if (file && !byFile.has(file)) byFile.set(file, new Set());
+    } else if (raw.startsWith("@@")) {
+      const match = /\+(\d+)/.exec(raw);
+      newLine = match ? Number(match[1]) : 0;
+    } else if (file === null || raw.startsWith("---") || raw.startsWith("\\")) {
+      // file header, deletion, or "No newline" marker — record nothing
+    } else if (raw.startsWith("+")) {
+      byFile.get(file)!.add(newLine++);
+    } else if (!raw.startsWith("-")) {
+      newLine++; // context line advances the new-file counter; deletions do not
+    }
+  }
+  return byFile;
+}
+
+/**
+ * The location re-keyed to its repo-relative diff path when it is inside the diff, else undefined.
+ * The exact path wins; a stray `./`, `a/` or `b/` prefix is tolerated. File-level locations count
+ * if the file changed; lines get ±1 of fuzz.
+ */
+export function diffAnchor(changed: ReadonlyMap<string, ReadonlySet<number>>, location: AdvisoryLocation): AdvisoryLocation | undefined {
+  for (const file of repoPathCandidates(location.file)) {
+    const lines = changed.get(file);
+    if (!lines) continue;
+    const { line } = location;
+    return line == null || lines.has(line) || lines.has(line - 1) || lines.has(line + 1) ? { ...location, file } : undefined;
+  }
+  return undefined;
+}

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

@@ -1,5 +1,8 @@
+import { initialPatchValidation, PatchEvaluationSchema, validateCandidatePatch, type PatchValidation } from "./patch-validation.ts";
+import { isFatalWorkflowError } from "../cancellation.ts";
+import { unknownErrorMessage } from "../unknown-error.ts";
 import type { ParallelSettledError } from "../concurrency.ts";
-import type { LoadedWorkflow, WorkflowApi, WorkflowModule } from "../types.ts";
+import type { IsolatedAgentResult, LoadedWorkflow, WorkflowApi, WorkflowModule } from "../types.ts";
 import type { WorktreeBaseline } from "../worktree.ts";
 import { loadWorkflow } from "../workflow-module.ts";
 import { serializeReviewIssue, type ReviewIssue } from "./review-issues.ts";
@@ -14,6 +17,7 @@ export interface ReviewFixPreview {
   readonly result: string;
   readonly patch: string;
   readonly changed: boolean;
+  readonly validation: PatchValidation;
 }
 
 export interface ReviewFixFailure {
@@ -28,7 +32,7 @@ export interface ReviewFixWorkflowResult {
   readonly fixes: readonly ReviewFixOutcome[];
 }
 
-export type ReviewFixWorkflowApi = Pick<WorkflowApi, "agent" | "parallel" | "phase">;
+export type ReviewFixWorkflowApi = Pick<WorkflowApi, "agent" | "parallel" | "phase" | "cwd" | "signal">;
 
 /** Build an ephemeral workflow that generates one isolated patch preview per finding. */
 export function createReviewFixWorkflow(
@@ -40,9 +44,9 @@ export function createReviewFixWorkflow(
     meta: {
       name: "code-review-fix-previews",
       description: "Generate isolated patch previews for selected code-review findings.",
-      phases: [{ title: REVIEW_FIX_PHASE }],
+      phases: [{ title: REVIEW_FIX_PHASE }, { title: "Validate patch previews" }],
     },
-    default: (api) => runReviewFixWorkflow(api, issues, context),
+    default: (api) => runReviewFixWorkflow(api, issues, context, baseline),
   };
   return loadWorkflow(
     module,
@@ -76,6 +80,7 @@ export async function runReviewFixWorkflow(
   api: ReviewFixWorkflowApi,
   issues: readonly ReviewIssue[],
   context: ReviewContext | undefined,
+  baseline: WorktreeBaseline,
 ): Promise<ReviewFixWorkflowResult> {
   api.phase(REVIEW_FIX_PHASE);
   const settled = await api.parallel(
@@ -84,16 +89,18 @@ export async function runReviewFixWorkflow(
         isolation: "worktree",
         label: `fix:${issue.id}`,
         phase: REVIEW_FIX_PHASE,
-        thinkingLevel: "medium",
+        profile: "medium",
         cacheKey: `review-fix:${issue.id}`,
         tools: [...REVIEW_FIX_TOOLS],
         toolHints: ["search"],
       });
+      const validation = await evaluateReviewFix(api, { issue, baseline, isolated });
       return {
         findingId: issue.id,
         result: isolated.result,
         patch: isolated.patch,
         changed: isolated.changed,
+        validation,
       };
     }),
     { settled: true },
@@ -103,11 +110,11 @@ export async function runReviewFixWorkflow(
     entry.ok ? entry.value : { findingId: issues[index]!.id, error: entry.error },
   );
   const successful = fixes.filter(isReviewFixPreview);
-  const changed = successful.filter((fix) => fix.changed).length;
+  const count = (status: PatchValidation["status"]) => successful.filter((fix) => fix.validation.status === status).length;
   const failed = fixes.length - successful.length;
 
   return {
-    summary: `Generated ${changed} patch preview(s); ${successful.length - changed} finding(s) needed no changes; ${failed} attempt(s) failed.`,
+    summary: `${count("verified")} verified candidate(s); ${count("rejected")} rejected; ${count("blocked")} blocked; ${count("no-patch")} no-patch; ${failed} attempt(s) failed.`,
     fixes,
   };
 }
@@ -115,3 +122,30 @@ export async function runReviewFixWorkflow(
 function isReviewFixPreview(outcome: ReviewFixOutcome): outcome is ReviewFixPreview {
   return "patch" in outcome;
 }
+
+/** `baseline` was already revalidated against the reviewed snapshot identity by resolveReviewWorktreeBaseline. */
+async function evaluateReviewFix(api: ReviewFixWorkflowApi, input: {
+  issue: ReviewIssue; baseline: WorktreeBaseline; isolated: IsolatedAgentResult<string>;
+}): Promise<PatchValidation> {
+  const { issue, baseline, isolated } = input;
+  const validation = initialPatchValidation(baseline, isolated.baselineOid, isolated.patch);
+  if (!isolated.patch.trim()) return validation;
+  if (!isolated.baselineOid) return { ...validation, reason: "Candidate has no recorded baseline identity." };
+  try {
+    const evaluated = await api.agent(
+      `Independently evaluate a candidate repair. Your fresh worktree contains the exact reviewed baseline plus the captured patch. The implementer's report is not validation evidence. Inspect the finding, callers and tests. Reject incorrect repairs; return blocked if required validation is unavailable. Select at most six focused deterministic checks with executable and argument arrays. Require at least one meaningful behavior check. If a regression test is applicable, supply a test-only baselinePatch and specific expectedFailure so the engine can prove it fails before the repair and passes after. Do not edit, install dependencies, commit or change branches. The engine will execute checks independently.\nFinding: ${JSON.stringify(serializeReviewIssue(issue))}\nBaseline: ${isolated.baselineOid}\nPatch SHA-256: ${validation.patchHash}\nPatch:\n${isolated.patch}`,
+      { isolation: "worktree", candidatePatch: { baselineOid: isolated.baselineOid, patch: isolated.patch },
+        label: `evaluate:${issue.id}`, phase: "Validate patch previews", profile: "medium", resume: "off",
+        tools: ["read", "bash", "grep", "find", "ls"], toolHints: ["search"], schema: PatchEvaluationSchema },
+    );
+    // Drift here is usually a test byproduct in the evaluator's worktree, not evidence against the repair.
+    if (evaluated.baselineOid !== isolated.baselineOid || evaluated.patch !== isolated.patch) {
+      return { ...validation, status: "blocked", reason: "Evaluator session changed its workspace (candidate patch or baseline drifted); independent checks were not run.", evaluation: evaluated.result };
+    }
+    return await validateCandidatePatch({ cwd: api.cwd, baseline,
+        baselineOid: isolated.baselineOid, patch: isolated.patch, evaluation: evaluated.result, signal: api.signal });
+  } catch (error) {
+    if (isFatalWorkflowError(error, api.signal)) throw error;
+    return { ...validation, status: "blocked", reason: unknownErrorMessage(error) };
+  }
+}

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

@@ -1,132 +1,67 @@
 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";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { dot, fit, GLYPH, hangingWrap, severityBadge, severityRank, truncatePath } from "../ui/kit.ts";
+import type { ReviewIssue } from "./review-issues.ts";
 
-export interface RenderIssuesTableOptions {
-  readonly maxRows?: number;
+/** Most severe first; report order (and so the stable R-number) breaks ties. */
+export function sortIssuesForDisplay(issues: readonly ReviewIssue[]): ReviewIssue[] {
+  return issues
+    .map((issue, index) => ({ issue, index }))
+    .sort((a, b) => severityRank(a.issue.finding.severity) - severityRank(b.issue.finding.severity) || a.index - b.index)
+    .map(({ issue }) => issue);
 }
 
-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)));
+/** `src/cache.ts:13`, without the symbol; the detail view shows the symbol on its own. */
+export function issuePath(issue: ReviewIssue): string {
+  if (!issue.file) return "no location";
+  return issue.line === undefined ? issue.file : `${issue.file}:${issue.line}`;
 }
 
-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}`));
+/**
+ * One aligned row: `HIGH R003  src/cache.ts:13      The parser accepts an empty value…`.
+ * `pathColumn` (from `findingPathColumn`) narrows the location column to the paths actually listed.
+ */
+export function renderFindingRow(issue: ReviewIssue, width: number, theme: Theme, pathColumn?: number): string {
+  const head = `${severityBadge(issue.finding.severity, theme)} ${theme.fg("dim", issue.id)}`;
+  const room = Math.max(0, width - visibleWidth(head) - 2);
+  const pathWidth = Math.min(pathColumn ?? Number.POSITIVE_INFINITY, maxPathWidth(room));
+  if (room < pathWidth + 10) return fit(`${head}  ${theme.fg("text", issue.finding.summary)}`, width);
+  const path = theme.fg("accent", fit(truncatePath(issuePath(issue), pathWidth), pathWidth));
+  return fit(`${head}  ${path}  ${theme.fg("text", issue.finding.summary)}`, width);
 }
 
-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 maxPathWidth(room: number): number {
+  return Math.min(Math.max(16, Math.floor(room * 0.38)), 34);
 }
 
-function cell(value: string, width: number): string {
-  return truncateDisplay(value, width).padEnd(width, " ");
+/** A location column as wide as the longest listed path, never below 12 columns. */
+export function findingPathColumn(issues: readonly ReviewIssue[]): number {
+  return Math.max(12, ...issues.map((issue) => visibleWidth(issuePath(issue))));
 }
 
-function colorCell(value: string, color: WorkflowThemeColor, theme: Theme): string {
-  return theme.fg(color, value);
-}
+const LABEL_WIDTH = 10;
 
-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";
-  }
+/** The full finding: headline, wrapped summary, then aligned Location / Impact / Evidence / Fix sections. */
+export function renderFindingDetail(issue: ReviewIssue, width: number, theme: Theme): string[] {
+  const finding = issue.finding;
+  const meta = [finding.category, `confidence ${finding.confidence}`, finding.verdict?.toLowerCase()].filter(Boolean).join(dot(theme));
+  const lines = [
+    `${severityBadge(finding.severity, theme)} ${theme.fg("accent", theme.bold(issue.id))}${dot(theme)}${theme.fg("muted", meta)}`,
+    ...hangingWrap(theme.bold(finding.summary), width),
+    "",
+  ];
+  const location = [theme.fg("accent", issuePath(issue)), issue.symbol ? theme.fg("muted", issue.symbol) : undefined].filter(Boolean).join(dot(theme));
+  lines.push(...labelledLines("Location", [location], width, theme));
+  lines.push(...labelledLines("Impact", [finding.impact], width, theme));
+  const evidence = finding.evidence.length > 0 ? finding.evidence.map((item) => `${GLYPH.bullet} ${item}`) : [theme.fg("dim", "none cited")];
+  lines.push(...labelledLines("Evidence", evidence, width, theme, "  "));
+  lines.push(...labelledLines("Fix", [finding.recommendation], width, theme));
+  return lines;
 }
 
-function confidenceColor(confidence: ReviewIssue["finding"]["confidence"]): WorkflowThemeColor {
-  switch (confidence) {
-    case "high":
-      return "success";
-    case "medium":
-      return "warning";
-    case "low":
-      return "muted";
-  }
+/** A dim label column (10 wide) with each item wrapped beside it, so result sections align with finding details. */
+export function labelledLines(label: string, items: readonly string[], width: number, theme: Theme, itemIndent = ""): string[] {
+  const first = theme.fg("dim", label.padEnd(LABEL_WIDTH, " "));
+  const rest = " ".repeat(LABEL_WIDTH);
+  return items.flatMap((item, index) => hangingWrap(item, width, index === 0 ? first : rest, rest + itemIndent));
 }

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

@@ -23,7 +23,7 @@ Instructions:
 - Do not edit files or make code changes.
 - Prefer installed GitHub MCP/tools if present; otherwise use the GitHub CLI (gh).
 - Before posting, resolve the current PR head and require it to equal the verified reviewed head \`${verifiedHead}\`; stop if it differs.
-- 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\`.
+- With gh, resolve the PR using \`gh pr view <context.diffTarget.number> --json headRefOid,url\` and take owner/repo from the PR \`url\` (the base repository, so fork PRs are commented upstream), 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.