@jameslovespancakes/pi-plus 1.0.10 → 1.0.12

package/src/domains/workflows/runtime/review/code-review-orchestration.ts

@@ -0,0 +1,24 @@
+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` : "")
+  );
+}

package/src/domains/workflows/runtime/review/github-pr-comments.ts

@@ -0,0 +1,249 @@
+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;
+  readonly stderr?: string;
+  readonly code: number;
+  readonly killed?: boolean;
+}
+
+export type ExecLike = (
+  command: string,
+  args: string[],
+  options?: { readonly cwd?: string; readonly timeout?: number; readonly signal?: AbortSignal },
+) => Promise<ExecResultLike>;
+
+export interface GitHubPrContext {
+  readonly owner: string;
+  readonly repo: string;
+  readonly number: number;
+  readonly headSha: string;
+  readonly url?: string;
+}
+
+export type ResolveGitHubPrContextResult = { readonly ok: true; readonly context: GitHubPrContext } | { readonly ok: false; readonly reason: string };
+
+export type InlineCommentStatus =
+  | { readonly issueId: string; readonly status: "posted"; readonly url?: string }
+  | { 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,
+  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);
+  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");
+  const baseFromUrl = parsePullRequestUrl(url);
+  let owner = baseFromUrl?.owner;
+  let repo = baseFromUrl?.repo;
+  if (!owner || !repo) {
+    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);
+    owner = owner ?? parsed?.owner;
+    repo = repo ?? parsed?.repo;
+  }
+  if (!owner || !repo) return { ok: false, reason: "GitHub repository owner/name is missing." };
+
+  return { ok: true, context: { owner, repo, number, headSha, url } };
+}
+
+export function buildInlineCommentBody(issue: ReviewIssue): string {
+  const finding = issue.finding;
+  const evidence = finding.evidence.length > 0 ? finding.evidence.map((entry) => `- ${entry}`).join("\n") : "- (none cited)";
+  return `**${issue.id}: ${finding.summary}**
+
+Severity: ${finding.severity} · Confidence: ${finding.confidence} · Category: ${finding.category}
+
+Impact: ${finding.impact}
+
+Evidence:
+${evidence}
+
+Recommendation: ${finding.recommendation}`;
+}
+
+export async function postInlineComment(
+  exec: ExecLike,
+  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." };
+
+  const result = await runCommand(exec, cwd, [
+    "api",
+    `repos/${prContext.owner}/${prContext.repo}/pulls/${prContext.number}/comments`,
+    "-f",
+    `body=${buildInlineCommentBody(issue)}`,
+    "-f",
+    `commit_id=${prContext.headSha}`,
+    "-f",
+    `path=${issue.file}`,
+    "-F",
+    `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) };
+}
+
+export async function postInlineComments(
+  exec: ExecLike,
+  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) {
+    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;
+}
+
+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[],
+  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) };
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? `Invalid gh JSON: ${error.message}` : "Invalid gh JSON." };
+  }
+}
+
+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, 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];
+  return typeof field === "number" && Number.isFinite(field) ? field : undefined;
+}
+
+function stringField(value: unknown, key: string): string | undefined {
+  if (!isRecord(value)) return undefined;
+  const field = value[key];
+  return typeof field === "string" && field.trim().length > 0 ? field : undefined;
+}
+
+function parseNameWithOwner(value: string | undefined): { readonly owner: string; readonly repo: string } | undefined {
+  if (!value) return undefined;
+  const [owner, repo, extra] = value.split("/");
+  if (!owner || !repo || extra !== undefined) return undefined;
+  return { owner, repo };
+}
+
+function parsePullRequestUrl(value: string | undefined): { readonly owner: string; readonly repo: string } | undefined {
+  if (!value) return undefined;
+  try {
+    const parsed = new URL(value);
+    const [owner, repo, type, number, extra] = parsed.pathname.split("/").filter(Boolean);
+    if (!owner || !repo || type !== "pull" || !number || extra !== undefined) return undefined;
+    return { owner, repo };
+  } catch {
+    return undefined;
+  }
+}
+
+function parsePostedCommentUrl(stdout: string): string | undefined {
+  try {
+    return stringField(JSON.parse(stdout), "html_url");
+  } catch {
+    return undefined;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/src/domains/workflows/runtime/review/patch-validation.ts

@@ -0,0 +1,120 @@
+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; expectedFingerprint: string; 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 (validation.baselineFingerprint !== options.expectedFingerprint) return { ...validation, status: "rejected", reason: "Stale reviewed baseline identity." };
+  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 ?? applied.stderr };
+  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 ?? testApplied.stderr}`); 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/src/domains/workflows/runtime/review/review-actions.ts

@@ -0,0 +1,180 @@
+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 { 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,
+  resolveBaseline: ReviewBaselineResolver = resolveReviewWorktreeBaseline,
+): Promise<LoadedWorkflow | undefined> {
+  if (!action || action.action === "close") return;
+  const selected = selectedIssues(issues, action.issueIds);
+  if (action.action === "fix") {
+    return await handleFixAction(ctx, selected, context, resolveBaseline);
+  }
+  await handleCommentAction(pi, ctx, selected, context, resolveBaseline);
+}
+
+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;
+  }
+  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(
+  pi: ReviewActionPi,
+  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) {
+    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, ctx.signal);
+  if (!resolved.ok) {
+    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, 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));
+    await queueCommentFallback(
+      pi,
+      ctx,
+      commentable.filter((issue) => failedIds.has(issue.id)),
+      context,
+      baseline.ref,
+      "Direct gh posting failed for one or more selected findings.",
+    );
+  }
+}
+
+async function queueCommentFallback(
+  pi: ReviewActionPi,
+  ctx: ReviewActionContext,
+  issues: readonly ReviewIssue[],
+  context: ReviewContext | undefined,
+  verifiedHead: string,
+  reason: string,
+): Promise<void> {
+  if (issues.length === 0) return;
+  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");
+}
+
+function toExecLike(pi: ReviewActionPi): ExecLike {
+  return async (command, args, options) => await pi.exec(command, args, options);
+}
+
+function selectedIssues(issues: readonly ReviewIssue[], issueIds: readonly string[]): ReviewIssue[] {
+  const selected = new Set(issueIds);
+  return issues.filter((issue) => selected.has(issue.id));
+}
+
+function summarizeStatuses(statuses: readonly InlineCommentStatus[]): { readonly posted: number; readonly skipped: number; readonly failed: number } {
+  let posted = 0;
+  let skipped = 0;
+  let failed = 0;
+  for (const status of statuses) {
+    if (status.status === "posted") posted++;
+    else if (status.status === "skipped") skipped++;
+    else failed++;
+  }
+  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/src/domains/workflows/runtime/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));
+}