pi-workflow-engine 0.10.2 → 0.11.0

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

@@ -1,4 +1,6 @@
-import { isCommentableIssue, type ReviewContext, type ReviewIssue } from "./review-issues.ts";
+import { throwIfAborted } from "../cancellation.ts";
+import { isCommentableIssue, type ReviewIssue } from "./review-issues.ts";
+import type { ReviewContext } from "./review-report.ts";
 
 export interface ExecResultLike {
   readonly stdout: string;
@@ -34,12 +36,13 @@ export async function resolveGitHubPrContext(
   exec: ExecLike,
   cwd: string,
   reviewContext: ReviewContext | undefined,
+  signal?: AbortSignal,
 ): Promise<ResolveGitHubPrContextResult> {
-  const parsedNumber = parsePrNumber(reviewContext?.diffCommand);
+  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);
+  const prView = await runJson(exec, cwd, prArgs, signal);
   if (!prView.ok) return { ok: false, reason: prView.reason };
 
   const number = numberField(prView.value, "number") ?? parsedNumber;
@@ -52,7 +55,7 @@ export async function resolveGitHubPrContext(
   let owner = baseFromUrl?.owner;
   let repo = baseFromUrl?.repo;
   if (!owner || !repo) {
-    const repoView = await runJson(exec, cwd, ["repo", "view", "--json", "nameWithOwner"]);
+    const repoView = await runJson(exec, cwd, ["repo", "view", "--json", "nameWithOwner"], signal);
     if (!repoView.ok) return { ok: false, reason: repoView.reason };
     const nameWithOwner = stringField(repoView.value, "nameWithOwner");
     const parsed = parseNameWithOwner(nameWithOwner);
@@ -84,6 +87,7 @@ export async function postInlineComment(
   cwd: string,
   prContext: GitHubPrContext,
   issue: ReviewIssue,
+  signal?: AbortSignal,
 ): Promise<InlineCommentStatus> {
   if (!isCommentableIssue(issue)) return { issueId: issue.id, status: "skipped", reason: "Finding has no commentable file/line." };
 
@@ -100,7 +104,7 @@ export async function postInlineComment(
     `line=${issue.line}`,
     "-f",
     "side=RIGHT",
-  ]);
+  ], signal);
   if (!result.ok) return { issueId: issue.id, status: "failed", reason: result.reason };
   return { issueId: issue.id, status: "posted", url: parsePostedCommentUrl(result.stdout) };
 }
@@ -110,24 +114,49 @@ export async function postInlineComments(
   cwd: string,
   prContext: GitHubPrContext,
   issues: readonly ReviewIssue[],
+  signal?: AbortSignal,
 ): Promise<InlineCommentStatus[]> {
+  throwIfAborted(signal);
+  const existing = await loadExistingInlineCommentKeys(exec, cwd, prContext, signal);
+  if (!existing.ok) {
+    return issues.map((issue) => ({ issueId: issue.id, status: "failed", reason: existing.reason }));
+  }
+
   const statuses: InlineCommentStatus[] = [];
   for (const issue of issues) {
-    statuses.push(await postInlineComment(exec, cwd, prContext, issue));
+    throwIfAborted(signal);
+    const key = inlineCommentKey(issue, prContext.headSha);
+    if (key && 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);
   }
   return statuses;
 }
 
-function parsePrNumber(diffCommand: string | undefined): number | undefined {
-  if (!diffCommand) return undefined;
-  const match = /(?:^|\s)gh\s+pr\s+diff\s+(\d+)(?:\s|$)/.exec(diffCommand);
-  if (!match) return undefined;
-  const parsed = Number(match[1]);
-  return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+async function loadExistingInlineCommentKeys(
+  exec: ExecLike,
+  cwd: string,
+  prContext: GitHubPrContext,
+  signal: AbortSignal | undefined,
+): Promise<{ readonly ok: true; readonly keys: Set<string> } | { readonly ok: false; readonly reason: string }> {
+  const endpoint = `repos/${prContext.owner}/${prContext.repo}/pulls/${prContext.number}/comments`;
+  const result = await runJson(exec, cwd, ["api", endpoint, "--paginate", "--slurp"], signal);
+  if (!result.ok) return { ok: false, reason: `Could not inspect existing PR comments: ${result.reason}` };
+  const keys = parseExistingInlineCommentKeys(result.value);
+  return keys ? { ok: true, keys } : { ok: false, reason: "Could not inspect existing PR comments: unexpected GitHub response." };
 }
 
-async function runJson(exec: ExecLike, cwd: string, args: string[]): Promise<{ readonly ok: true; readonly value: unknown } | { readonly ok: false; readonly reason: string }> {
-  const result = await runCommand(exec, cwd, args);
+async function runJson(
+  exec: ExecLike,
+  cwd: string,
+  args: string[],
+  signal?: AbortSignal,
+): Promise<{ readonly ok: true; readonly value: unknown } | { readonly ok: false; readonly reason: string }> {
+  const result = await runCommand(exec, cwd, args, signal);
   if (!result.ok) return result;
   try {
     return { ok: true, value: JSON.parse(result.stdout) };
@@ -136,16 +165,46 @@ async function runJson(exec: ExecLike, cwd: string, args: string[]): Promise<{ r
   }
 }
 
-async function runCommand(exec: ExecLike, cwd: string, args: string[]): Promise<{ readonly ok: true; readonly stdout: string } | { readonly ok: false; readonly reason: string }> {
+async function runCommand(
+  exec: ExecLike,
+  cwd: string,
+  args: string[],
+  signal?: AbortSignal,
+): Promise<{ readonly ok: true; readonly stdout: string } | { readonly ok: false; readonly reason: string }> {
+  throwIfAborted(signal);
   try {
-    const result = await exec("gh", args, { cwd, timeout: 30_000 });
+    const result = await exec("gh", args, { cwd, timeout: 30_000, signal });
+    throwIfAborted(signal);
     if (result.code !== 0) return { ok: false, reason: result.stderr?.trim() || `gh exited with code ${result.code}` };
     return { ok: true, stdout: result.stdout };
   } catch (error) {
+    throwIfAborted(signal);
     return { ok: false, reason: error instanceof Error ? error.message : "gh command failed." };
   }
 }
 
+function parseExistingInlineCommentKeys(value: unknown): Set<string> | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const comments = value.every(Array.isArray) ? value.flat() : value;
+  const keys = new Set<string>();
+  for (const comment of comments) {
+    const body = stringField(comment, "body");
+    const path = stringField(comment, "path");
+    const line = numberField(comment, "line");
+    const headSha = stringField(comment, "commit_id");
+    if (body && path && line !== undefined && headSha) keys.add(commentKey(body, path, line, headSha));
+  }
+  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]);
+}
+
 function numberField(value: unknown, key: string): number | undefined {
   if (!isRecord(value)) return undefined;
   const field = value[key];

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

@@ -1,40 +1,69 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { throwIfAborted } from "../cancellation.ts";
+import type { LoadedWorkflow } from "../types.ts";
+import { unknownErrorMessage } from "../unknown-error.ts";
+import type { WorktreeBaseline } from "../worktree.ts";
 import { postInlineComments, resolveGitHubPrContext, type ExecLike, type InlineCommentStatus } from "./github-pr-comments.ts";
-import { buildCommentHandoffPrompt, buildFixHandoffPrompt } from "./review-handoff.ts";
-import { isCommentableIssue, type ReviewContext, type ReviewIssue, type ReviewIssueSelection } from "./review-issues.ts";
+import { createReviewFixWorkflow } from "./review-fix-workflow.ts";
+import { buildCommentHandoffPrompt } from "./review-handoff.ts";
+import { isCommentableIssue, type ReviewIssue, type ReviewIssueSelection } from "./review-issues.ts";
+import type { ReviewContext } from "./review-report.ts";
+import { resolveReviewWorktreeBaseline, ReviewSnapshotUnavailableError } from "./review-snapshot.ts";
 
 export type ReviewActionPi = Pick<ExtensionAPI, "sendUserMessage" | "exec">;
 export interface ReviewActionContext {
   readonly cwd: string;
+  readonly signal?: AbortSignal;
   readonly ui: {
     confirm(title: string, message: string): Promise<boolean>;
     notify(message: string, type?: "info" | "warning" | "error"): void;
   };
 }
 
+export type ReviewBaselineResolver = (
+  context: ReviewContext | undefined,
+  cwd: string,
+  signal?: AbortSignal,
+) => Promise<WorktreeBaseline>;
+
 export async function handleReviewViewerAction(
   pi: ReviewActionPi,
   ctx: ReviewActionContext,
   action: ReviewIssueSelection | undefined,
   issues: readonly ReviewIssue[],
   context: ReviewContext | undefined,
-): Promise<void> {
+  resolveBaseline: ReviewBaselineResolver = resolveReviewWorktreeBaseline,
+): Promise<LoadedWorkflow | undefined> {
   if (!action || action.action === "close") return;
   const selected = selectedIssues(issues, action.issueIds);
   if (action.action === "fix") {
-    handleFixAction(pi, ctx, selected, context);
-    return;
+    return await handleFixAction(ctx, selected, context, resolveBaseline);
   }
-  await handleCommentAction(pi, ctx, selected, context);
+  await handleCommentAction(pi, ctx, selected, context, resolveBaseline);
 }
 
-function handleFixAction(pi: ReviewActionPi, ctx: ReviewActionContext, selected: readonly ReviewIssue[], context: ReviewContext | undefined): void {
+async function handleFixAction(
+  ctx: ReviewActionContext,
+  selected: readonly ReviewIssue[],
+  context: ReviewContext | undefined,
+  resolveBaseline: ReviewBaselineResolver,
+): Promise<LoadedWorkflow | undefined> {
+  throwIfAborted(ctx.signal);
   if (selected.length === 0) {
     ctx.ui.notify("No selected findings to fix", "warning");
     return;
   }
-  pi.sendUserMessage(buildFixHandoffPrompt(selected, context), { deliverAs: "followUp" });
-  ctx.ui.notify(`Queued fix request for ${selected.length} selected finding(s)`, "info");
+  ctx.ui.notify("Verifying the reviewed snapshot before generating patch previews", "info");
+  let baseline: WorktreeBaseline;
+  try {
+    baseline = await resolveBaseline(context, ctx.cwd, ctx.signal);
+  } catch (error) {
+    throwIfAborted(ctx.signal);
+    ctx.ui.notify(formatSnapshotError("Patch preview", error), "warning");
+    return;
+  }
+  ctx.ui.notify(`Generating isolated patch previews for ${selected.length} selected finding(s)`, "info");
+  return createReviewFixWorkflow(selected, context, baseline);
 }
 
 async function handleCommentAction(
@@ -42,53 +71,84 @@ async function handleCommentAction(
   ctx: ReviewActionContext,
   selected: readonly ReviewIssue[],
   context: ReviewContext | undefined,
+  resolveBaseline: ReviewBaselineResolver,
 ): Promise<void> {
   const commentable = selected.filter(isCommentableIssue);
   if (commentable.length === 0) {
     ctx.ui.notify("No selected findings have file and line information for inline PR comments", "warning");
     return;
   }
+  if (context?.diffTarget.kind !== "pull-request") {
+    ctx.ui.notify("PR comments are available only for findings captured from a verified pull-request diff.", "warning");
+    return;
+  }
 
+  throwIfAborted(ctx.signal);
   const confirmed = await ctx.ui.confirm(
     "Post inline PR comments?",
     `Post ${commentable.length} selected finding(s) to the upstream PR using GitHub CLI if available?`,
   );
   if (!confirmed) {
-    queueCommentFallback(pi, ctx, commentable, context, "User chose parent-agent fallback instead of direct gh posting.");
+    ctx.ui.notify("PR comment posting cancelled", "info");
+    return;
+  }
+
+  ctx.ui.notify("Verifying the reviewed snapshot before posting PR comments", "info");
+  let baseline: WorktreeBaseline;
+  try {
+    baseline = await resolveBaseline(context, ctx.cwd, ctx.signal);
+  } catch (error) {
+    throwIfAborted(ctx.signal);
+    ctx.ui.notify(formatSnapshotError("PR comments", error), "warning");
     return;
   }
 
   const exec = toExecLike(pi);
-  const resolved = await resolveGitHubPrContext(exec, ctx.cwd, context);
+  const resolved = await resolveGitHubPrContext(exec, ctx.cwd, context, ctx.signal);
   if (!resolved.ok) {
-    queueCommentFallback(pi, ctx, commentable, context, resolved.reason);
+    await queueCommentFallback(pi, ctx, commentable, context, baseline.ref, resolved.reason);
+    return;
+  }
+  if (resolved.context.headSha !== baseline.ref) {
+    ctx.ui.notify("PR comments unavailable because the pull request head changed after snapshot verification.", "warning");
     return;
   }
 
-  const statuses = await postInlineComments(exec, ctx.cwd, resolved.context, commentable);
+  const statuses = await postInlineComments(exec, ctx.cwd, resolved.context, commentable, ctx.signal);
   const summary = summarizeStatuses(statuses);
   ctx.ui.notify(`PR comments: ${summary.posted} posted, ${summary.skipped} skipped, ${summary.failed} failed`, summary.failed > 0 ? "warning" : "info");
   if (summary.failed > 0) {
     const failedIds = new Set(statuses.filter((status) => status.status === "failed").map((status) => status.issueId));
-    queueCommentFallback(
+    await queueCommentFallback(
       pi,
       ctx,
       commentable.filter((issue) => failedIds.has(issue.id)),
       context,
+      baseline.ref,
       "Direct gh posting failed for one or more selected findings.",
     );
   }
 }
 
-function queueCommentFallback(
+async function queueCommentFallback(
   pi: ReviewActionPi,
   ctx: ReviewActionContext,
   issues: readonly ReviewIssue[],
   context: ReviewContext | undefined,
+  verifiedHead: string,
   reason: string,
-): void {
+): Promise<void> {
   if (issues.length === 0) return;
-  pi.sendUserMessage(buildCommentHandoffPrompt(issues, context, reason), { deliverAs: "followUp" });
+  const confirmed = await ctx.ui.confirm(
+    "Queue PR comment fallback?",
+    `${reason}\n\nQueue ${issues.length} finding(s) for the parent agent to post after rechecking the PR head?`,
+  );
+  throwIfAborted(ctx.signal);
+  if (!confirmed) {
+    ctx.ui.notify("PR comment fallback cancelled", "info");
+    return;
+  }
+  pi.sendUserMessage(buildCommentHandoffPrompt(issues, context, verifiedHead, reason), { deliverAs: "followUp" });
   ctx.ui.notify(`Queued PR comment request for ${issues.length} selected finding(s)`, "info");
 }
 
@@ -112,3 +172,9 @@ function summarizeStatuses(statuses: readonly InlineCommentStatus[]): { readonly
   }
   return { posted, skipped, failed };
 }
+
+function formatSnapshotError(action: "Patch preview" | "PR comments", error: unknown): string {
+  return error instanceof ReviewSnapshotUnavailableError
+    ? `${action} unavailable because ${error.message}`
+    : `${action} unavailable: ${unknownErrorMessage(error)}`;
+}

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

@@ -0,0 +1,45 @@
+import type { WorkflowUsageSnapshot } from "../usage.ts";
+
+export type ReviewFixLease =
+  | { readonly ok: true; readonly release: () => void }
+  | { readonly ok: false; readonly reason: "busy" | "exhausted" };
+
+/** Session-local budget ledger that serializes fix previews and records every finalized run. */
+export class ReviewFixBudgetLedger {
+  private inFlight = false;
+  private remainingBudget: number | undefined;
+
+  constructor(budget: number | null | undefined, initialUsage: WorkflowUsageSnapshot | undefined) {
+    this.remainingBudget = remainingWorkflowBudget(budget, initialUsage);
+  }
+
+  get remaining(): number | undefined {
+    return this.remainingBudget;
+  }
+
+  acquire(): ReviewFixLease {
+    if (this.remainingBudget === 0) return { ok: false, reason: "exhausted" };
+    if (this.inFlight) return { ok: false, reason: "busy" };
+    this.inFlight = true;
+    let released = false;
+    return {
+      ok: true,
+      release: () => {
+        if (released) return;
+        released = true;
+        this.inFlight = false;
+      },
+    };
+  }
+
+  record(usage: WorkflowUsageSnapshot): void {
+    this.remainingBudget = remainingWorkflowBudget(this.remainingBudget, usage);
+  }
+}
+
+export function remainingWorkflowBudget(
+  budget: number | null | undefined,
+  usage: WorkflowUsageSnapshot | undefined,
+): number | undefined {
+  return budget == null ? undefined : Math.max(0, budget - (usage?.totals.output ?? 0));
+}

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

@@ -0,0 +1,117 @@
+import type { ParallelSettledError } from "../concurrency.ts";
+import type { 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";
+import type { ReviewContext } from "./review-report.ts";
+import { serializeReviewContext } from "./review-report.ts";
+
+const REVIEW_FIX_PHASE = "Generate patch previews";
+const REVIEW_FIX_TOOLS = ["read", "bash", "edit", "write", "grep", "find", "ls"];
+
+export interface ReviewFixPreview {
+  readonly findingId: string;
+  readonly result: string;
+  readonly patch: string;
+  readonly changed: boolean;
+}
+
+export interface ReviewFixFailure {
+  readonly findingId: string;
+  readonly error: ParallelSettledError;
+}
+
+export type ReviewFixOutcome = ReviewFixPreview | ReviewFixFailure;
+
+export interface ReviewFixWorkflowResult {
+  readonly summary: string;
+  readonly fixes: readonly ReviewFixOutcome[];
+}
+
+export type ReviewFixWorkflowApi = Pick<WorkflowApi, "agent" | "parallel" | "phase">;
+
+/** Build an ephemeral workflow that generates one isolated patch preview per finding. */
+export function createReviewFixWorkflow(
+  issues: readonly ReviewIssue[],
+  context: ReviewContext | undefined,
+  baseline: WorktreeBaseline,
+): LoadedWorkflow {
+  const module: WorkflowModule = {
+    meta: {
+      name: "code-review-fix-previews",
+      description: "Generate isolated patch previews for selected code-review findings.",
+      phases: [{ title: REVIEW_FIX_PHASE }],
+    },
+    default: (api) => runReviewFixWorkflow(api, issues, context),
+  };
+  return loadWorkflow(
+    module,
+    {
+      kind: "unverifiable",
+      reason: "ephemeral review-fix workflows capture runtime findings and do not have immutable module provenance",
+    },
+    baseline,
+  );
+}
+
+export function buildFixAgentPrompt(issue: ReviewIssue, context: ReviewContext | undefined): string {
+  return `Generate a patch preview for exactly one verified code-review finding in your disposable git worktree.
+
+Selected finding JSON:
+\`\`\`json
+${JSON.stringify({ context: serializeReviewContext(context), issue: serializeReviewIssue(issue) })}
+\`\`\`
+
+Instructions:
+- Inspect the finding and cited evidence before editing.
+- Make the smallest edit that addresses only this finding.
+- Preserve unrelated user changes and avoid broad refactors.
+- Run focused validation if an appropriate local check is available.
+- Do not create commits or branches; the engine captures your worktree diff automatically.
+- Do not post GitHub PR comments or any upstream review comments.
+- Finish with a concise summary of changed files and validation results; this text is returned alongside the captured patch.`;
+}
+
+export async function runReviewFixWorkflow(
+  api: ReviewFixWorkflowApi,
+  issues: readonly ReviewIssue[],
+  context: ReviewContext | undefined,
+): Promise<ReviewFixWorkflowResult> {
+  api.phase(REVIEW_FIX_PHASE);
+  const settled = await api.parallel(
+    issues.map((issue) => async (): Promise<ReviewFixPreview> => {
+      const isolated = await api.agent(buildFixAgentPrompt(issue, context), {
+        isolation: "worktree",
+        label: `fix:${issue.id}`,
+        phase: REVIEW_FIX_PHASE,
+        thinkingLevel: "medium",
+        cacheKey: `review-fix:${issue.id}`,
+        tools: [...REVIEW_FIX_TOOLS],
+        toolHints: ["search"],
+      });
+      return {
+        findingId: issue.id,
+        result: isolated.result,
+        patch: isolated.patch,
+        changed: isolated.changed,
+      };
+    }),
+    { settled: true },
+  );
+
+  const fixes = settled.map((entry, index): ReviewFixOutcome =>
+    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 failed = fixes.length - successful.length;
+
+  return {
+    summary: `Generated ${changed} patch preview(s); ${successful.length - changed} finding(s) needed no changes; ${failed} attempt(s) failed.`,
+    fixes,
+  };
+}
+
+function isReviewFixPreview(outcome: ReviewFixOutcome): outcome is ReviewFixPreview {
+  return "patch" in outcome;
+}

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

@@ -1,47 +1,13 @@
-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 {
+import { serializeReviewIssue, type ReviewIssue } from "./review-issues.ts";
+import type { ReviewContext } from "./review-report.ts";
+import { serializeReviewContext } from "./review-report.ts";
+
+export function buildCommentHandoffPrompt(
+  issues: readonly ReviewIssue[],
+  context: ReviewContext | undefined,
+  verifiedHead: string,
+  reason: string,
+): string {
   return `Use the workflow-code-review-actions skill if available.
 
 Mode: post inline GitHub PR comments for selected code-review findings.
@@ -56,6 +22,7 @@ ${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).
+- 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\`.
 - Do not post duplicate comments.
 - Do not post line-less findings as inline comments.
@@ -63,28 +30,9 @@ Instructions:
 - 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 {
+function toHandoffPayload(issues: readonly ReviewIssue[], context: ReviewContext | undefined) {
   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,
+    context: serializeReviewContext(context),
+    issues: issues.map(serializeReviewIssue),
   };
 }

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

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