pi-pr-review 1.5.0 → 1.5.2

package/README.md

@@ -130,11 +130,13 @@ The orchestrator (which fetches the PR, merges findings, and emits the JSON) and
 Type `/` in the pi editor and pick `pr-review`, or:
 
 ```
-/pr-review 123                            # use autoPostReviews (false by default)
-/pr-review 123 --comment                  # force one COMMENT review for this run
-/pr-review 123 --no-comment               # suppress posting for this run
-/pr-review 123 --include-closed           # review a closed/merged PR without a confirmation prompt
-/pr-review 123 --review-closed --comment  # review and attempt a body-only COMMENT review
+/pr-review 123                                  # use autoPostReviews (false by default)
+/pr-review 123 --comment                        # force one COMMENT review for this run
+/pr-review 123 --no-comment                     # suppress posting for this run
+/pr-review 123 --include-closed                 # review a closed/merged PR without a confirmation prompt
+/pr-review 123 --review-closed --comment        # review and attempt a body-only COMMENT review
+/pr-review-publish 123                          # publish the completed review cached in this session
+/pr-review-publish 123 --allow-stale            # publish it after the PR head changed; never rerun the model
 ```
 
 `123` is the PR number in the current repo.
@@ -147,7 +149,19 @@ Closed/merged PRs no longer hard-skip. If you run `/pr-review 123` on a non-open
 
 `autoPostReviews` is a strict top-level boolean and defaults to `false`. A trusted project `.pi/pr-review.json` value overlays the user value; malformed effective values never enable posting. `/pr-review-config` edits user scope only and displays the effective value/source—if a trusted project overlay wins, edit that project file or use `--no-comment` for the run. Invocation flags are captured before prompt expansion: `--comment` forces posting for one run, `--no-comment` suppresses it, and using both is rejected.
 
-Publishing is extension-owned—the model never constructs the write request, and final JSON marked `disposition: "skipped"` is never published. It creates exactly one formal pull-request review containing a top-level body and associated P0–P3 inline comments. The GitHub event is hardcoded to `COMMENT`; the publisher cannot send `APPROVE` or `REQUEST_CHANGES`, even when the review's suggested verdict is `request_changes`. It validates the current head and every inline diff anchor before the single POST, so an invalid open-PR inline comment fails without leaving a partial review. Closed/merged PRs require either `--include-closed`/`--review-closed` or the one-shot affirmative confirmation, then use one body-only `COMMENT` review with inline findings folded into the body. Unknown or unconfirmed non-open lifecycle states fail without posting.
+Publishing is extension-owned—the model never constructs the write request, and final JSON marked `disposition: "skipped"` is never published. It creates exactly one formal pull-request review. The top-level body contains overview/verdict information, inline-vs-summary counts, nits, and findings that cannot be posted inline; successfully attached P0–P3 findings appear only in their associated inline comments, not duplicated in the top-level body. The GitHub event is hardcoded to `COMMENT`; the publisher cannot send `APPROVE` or `REQUEST_CHANGES`, even when the review's suggested verdict is `request_changes`. It validates the current head and every inline diff anchor before the single POST, so an invalid open-PR inline comment fails without leaving a partial review. Closed/merged PRs require either `--include-closed`/`--review-closed` or the one-shot affirmative confirmation, then use one body-only `COMMENT` review with each formerly-inline finding folded into the body exactly once. Unknown or unconfirmed non-open lifecycle states fail without posting.
+
+### Publishing a completed review after a new commit
+
+The latest valid, reviewed final result for each repository and PR is cached before GitHub publication preflight for the current extension session. If a commit lands after review generation and the normal stale-head guard refuses to post, do **not** rerun `/pr-review` with `--comment` and do not ask the model to bypass its write policy. Use the extension-owned publish-only command:
+
+```
+/pr-review-publish 123 --allow-stale
+```
+
+This command calls no review model and reuses the completed result for PR `123`. The default `/pr-review-publish 123` still rejects a stale head; `--allow-stale` is the explicit acknowledgement. A stale review is posted as one body-only formal `COMMENT` review against the head observed during preflight, begins with a warning that shows both the reviewed and observed full SHAs, and keeps every finding in the body. Inline comments are intentionally disabled because their original diff anchors may no longer be valid. Repository binding, duplicate, draft, lifecycle, payload-size, identity, and final head-stability checks remain active. If another commit lands during the publish preflight, run the same publish-only command again to acknowledge that newer observed head.
+
+The in-memory cache is discarded when a new pi session starts or extensions reload. `/pr-review-publish` explicitly refuses to start or rerun a review when no cached result exists, and it will not publish an older cached result while a new review of the same PR is active.
 
 ### Duplicate review handling
 

package/extensions/review-table.ts

@@ -19,15 +19,19 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import {
 	classifyAssistantCompletion,
+	CompletedReviewCache,
 	isNonOpenConfirmationPrompt,
+	parsePublishExistingArgs,
 	parsePublishMode,
 	parsePublishableReview,
 	publishPullReview,
 	resolveAutoPostSetting,
+	resolveRepositoryBinding,
 	ReviewInvocationGate,
 	shouldPublishReview,
 	validateReviewInvocation,
 	type AutoPostResolution,
+	type RepositoryBinding,
 	type ReviewInvocation,
 	type ReviewLike,
 } from "../lib/pr-review-publish.ts";
@@ -310,7 +314,28 @@ function resolvePublishingConfig(ctx: ExtensionContext): AutoPostResolution {
 	return resolveAutoPostSetting(user.value, project?.value);
 }
 
-async function maybePublishReview(text: string, invocation: ReviewInvocation, ctx: ExtensionContext): Promise<void> {
+function notifyPublishResult(
+	result: Awaited<ReturnType<typeof publishPullReview>>,
+	source: string,
+	ctx: ExtensionContext,
+): void {
+	if (result.status === "posted") {
+		ctx.ui.notify(`PR review posted as COMMENT (${source})${result.url ? `: ${result.url}` : ""}`, "info");
+	} else if (result.status === "posted_degraded") {
+		ctx.ui.notify(`PR review posted (${source}): ${result.message}${result.url ? ` ${result.url}` : ""}`, "warning");
+	} else if (result.status === "skipped_duplicate") {
+		ctx.ui.notify("PR review not reposted: this reviewed head was already posted by the current GitHub identity", "info");
+	} else {
+		ctx.ui.notify(`PR review publish ${result.status}: ${result.message}`, "error");
+	}
+}
+
+async function maybePublishReview(
+	text: string,
+	invocation: ReviewInvocation,
+	ctx: ExtensionContext,
+	expectedRepository?: RepositoryBinding,
+): Promise<void> {
 	if (invocation.mode === "disabled") return;
 	const setting = resolvePublishingConfig(ctx);
 	if (invocation.mode === "auto") {
@@ -341,25 +366,76 @@ async function maybePublishReview(text: string, invocation: ReviewInvocation, ct
 		prNumber: invocation.prNumber,
 		headSha,
 		allowNonOpen: invocation.allowNonOpen,
+		expectedRepository,
 		review: parsed.review as ReviewLike,
 	});
 	const source = invocation.mode === "force" ? "--comment" : `${setting.source} config`;
-	if (result.status === "posted") {
-		ctx.ui.notify(`PR review posted as COMMENT (${source})${result.url ? `: ${result.url}` : ""}`, "info");
-	} else if (result.status === "posted_degraded") {
-		ctx.ui.notify(`PR review posted as body-only COMMENT for non-open PR (${source})`, "warning");
-	} else if (result.status === "skipped_duplicate") {
-		ctx.ui.notify("PR review not reposted: this head was already reviewed by the current GitHub identity", "info");
-	} else {
-		ctx.ui.notify(`PR review publish ${result.status}: ${result.message}`, "error");
-	}
+	notifyPublishResult(result, source, ctx);
 }
 
 export default function (pi: ExtensionAPI) {
 	const invocationGate = new ReviewInvocationGate();
+	const completedReviews = new CompletedReviewCache();
+
+	pi.registerCommand("pr-review-publish", {
+		description: "Publish a completed review from this session without rerunning the model",
+		handler: async (args, ctx) => {
+			const parsed = parsePublishExistingArgs(args ?? "");
+			if (parsed.error || !parsed.prNumber) {
+				ctx.ui.notify(
+					`Invalid /pr-review-publish command: ${parsed.error ?? "missing PR number"}. Usage: /pr-review-publish <PR-NUM> [--allow-stale]`,
+					"error",
+				);
+				return;
+			}
+			const active = invocationGate.peek();
+			if (active?.prNumber === parsed.prNumber) {
+				ctx.ui.notify(
+					`PR #${parsed.prNumber} is still being reviewed. The publish-only command will not post an older cached result while a new result is in progress.`,
+					"error",
+				);
+				return;
+			}
+			let repository: RepositoryBinding;
+			try {
+				repository = await resolveRepositoryBinding(ctx.cwd);
+			} catch (error) {
+				ctx.ui.notify(`Cannot resolve the current GitHub repository: ${String(error)}`, "error");
+				return;
+			}
+			const completed = completedReviews.get(parsed.prNumber, repository);
+			if (!completed) {
+				ctx.ui.notify(
+					`No completed review for PR #${parsed.prNumber} is cached for this repository in the current extension session. This command never starts or reruns a review.`,
+					"error",
+				);
+				return;
+			}
+			const headSha = completed.review.pr?.head_sha;
+			if (typeof headSha !== "string") {
+				ctx.ui.notify("Cached PR review is missing pr.head_sha", "error");
+				return;
+			}
+			const result = await publishPullReview({
+				cwd: ctx.cwd,
+				prNumber: parsed.prNumber,
+				headSha,
+				allowNonOpen: completed.invocation.allowNonOpen,
+				allowStale: parsed.allowStale,
+				expectedRepository: completed.repository,
+				review: completed.review,
+			});
+			notifyPublishResult(
+				result,
+				parsed.allowStale ? "publish-only --allow-stale" : "publish-only",
+				ctx,
+			);
+		},
+	});
 
 	pi.on("session_start", () => {
 		invocationGate.clear();
+		completedReviews.clear();
 	});
 
 	pi.on("input", (event, ctx) => {
@@ -406,7 +482,24 @@ export default function (pi: ExtensionAPI) {
 		if (!text.trim()) return;
 		const review = parseReview(text);
 		if (!review) return; // not a /pr-review JSON payload — leave untouched
-		if (invocation) await maybePublishReview(text, invocation, ctx);
+		if (invocation) {
+			const publishable = parsePublishableReview(text);
+			let repository: RepositoryBinding | undefined;
+			if (
+				publishable.review &&
+				!validateReviewInvocation(publishable.review, invocation) &&
+				shouldPublishReview(publishable.review)
+			) {
+				try {
+					repository = await resolveRepositoryBinding(ctx.cwd);
+					// Cache before publication preflight so a stale failure remains directly publishable.
+					completedReviews.remember(publishable.review, invocation, repository);
+				} catch (error) {
+					ctx.ui.notify(`Completed review is not available to publish-only: ${String(error)}`, "warning");
+				}
+			}
+			await maybePublishReview(text, invocation, ctx, repository);
+		}
 
 		// Keep raw JSON for automation; only prettify for interactive terminals.
 		if (ctx.mode !== "tui") return;

package/lib/pr-review-publish.ts

@@ -88,6 +88,26 @@ export interface ReviewInvocation {
 	allowNonOpen: boolean;
 }
 
+export interface PublishExistingParseResult {
+	prNumber?: number;
+	allowStale: boolean;
+	error?: string;
+}
+
+/** Parse the direct, model-free `/pr-review-publish` command arguments. */
+export function parsePublishExistingArgs(input: string): PublishExistingParseResult {
+	const tokens = input.trim().split(/\s+/).filter(Boolean);
+	const requested = Number(tokens[0]);
+	if (!Number.isInteger(requested) || requested <= 0) {
+		return { allowStale: false, error: "a positive PR number must be the first argument" };
+	}
+	const unknown = tokens.slice(1).filter((token) => token !== "--allow-stale");
+	if (unknown.length > 0) {
+		return { allowStale: false, error: `unknown argument${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}` };
+	}
+	return { prNumber: requested, allowStale: tokens.includes("--allow-stale") };
+}
+
 export type ReviewInvocationPhase = "reviewing" | "awaiting_confirmation" | "confirmed";
 
 export function isNonOpenConfirmationPrompt(text: string, prNumber: number): boolean {
@@ -246,6 +266,42 @@ export interface ReviewLike {
 	overall_confidence_score?: number;
 }
 
+export interface RepositoryBinding {
+	repository: string;
+	hostname: string;
+}
+
+export interface CompletedReviewRecord {
+	review: ReviewLike;
+	invocation: ReviewInvocation;
+	repository: RepositoryBinding;
+}
+
+function completedReviewKey(repository: RepositoryBinding, prNumber: number): string {
+	return `${repository.hostname.toLowerCase()}:${repository.repository.toLowerCase()}:${prNumber}`;
+}
+
+/** Session-scoped latest completed review per repository and PR. */
+export class CompletedReviewCache {
+	private readonly reviews = new Map<string, CompletedReviewRecord>();
+
+	remember(review: ReviewLike, invocation: ReviewInvocation, repository: RepositoryBinding): void {
+		this.reviews.set(completedReviewKey(repository, invocation.prNumber), {
+			review,
+			invocation: { ...invocation },
+			repository: { ...repository },
+		});
+	}
+
+	get(prNumber: number, repository: RepositoryBinding): CompletedReviewRecord | undefined {
+		return this.reviews.get(completedReviewKey(repository, prNumber));
+	}
+
+	clear(): void {
+		this.reviews.clear();
+	}
+}
+
 export interface PublishableReviewParseResult {
 	review?: ReviewLike;
 	error?: string;
@@ -349,7 +405,23 @@ function findingLocation(finding: ReviewFindingLike): string {
 	return `${location.absolute_file_path}:${start}${end !== start ? `-${end}` : ""} ${(location.side ?? "RIGHT").toUpperCase()}`;
 }
 
-export function buildReviewSummary(review: ReviewLike): string {
+function publishCommentAnchor(comment: PublishComment): string {
+	return `${comment.path}:${comment.side}:${comment.start_line ?? comment.line}:${comment.line}`;
+}
+
+function findingAnchor(finding: ReviewFindingLike): string | undefined {
+	const location = finding.code_location;
+	const path = location?.absolute_file_path;
+	const side = location?.side?.toUpperCase();
+	const start = location?.line_range?.start;
+	const end = location?.line_range?.end;
+	if (!path || (side !== "LEFT" && side !== "RIGHT") || !Number.isInteger(start) || !Number.isInteger(end)) {
+		return undefined;
+	}
+	return `${path}:${side}:${start}:${end}`;
+}
+
+export function buildReviewSummary(review: ReviewLike, inlineComments: PublishComment[] = []): string {
 	const lines: string[] = [];
 	const number = review.pr?.number;
 	const title = String(review.pr?.title ?? "").replace(/\r?\n/g, " ").trim();
@@ -360,18 +432,29 @@ export function buildReviewSummary(review: ReviewLike): string {
 		lines.push("### Strengths", "", ...review.strengths.map((strength) => `- ${String(strength).replace(/^\s*-\s*/, "").trim()}`), "");
 	}
 	const findings = Array.isArray(review.findings) ? review.findings : [];
-	lines.push(`### Findings — ${findings.length}`, "");
+	const inlineAnchors = new Set(inlineComments.map(publishCommentAnchor));
+	const summaryFindings = findings.filter((finding) => {
+		if (!finding.code_location?.commentable || !isInlineSeverity(finding)) return true;
+		const anchor = findingAnchor(finding);
+		return !anchor || !inlineAnchors.has(anchor);
+	});
+	lines.push(
+		`### Findings — ${findings.length} total (${inlineComments.length} inline, ${summaryFindings.length} summary-only)`,
+		"",
+	);
 	if (findings.length === 0) {
 		lines.push("_No issues found._", "");
+	} else if (summaryFindings.length === 0) {
+		lines.push(`_All ${inlineComments.length} findings are attached inline below this review._`, "");
 	} else {
-		lines.push("| Severity | Finding | Location |", "|---|---|---|");
-		for (const finding of findings) {
+		lines.push("| Severity | Summary-only finding | Location |", "|---|---|---|");
+		for (const finding of summaryFindings) {
 			lines.push(
 				`| ${cell(String(finding.severity ?? "—"))} | ${cell(String(finding.title ?? "(untitled)"))} | \`${cell(findingLocation(finding))}\` |`,
 			);
 		}
 		lines.push("");
-		for (const finding of findings) {
+		for (const finding of summaryFindings) {
 			lines.push(`#### ${String(finding.title ?? "Finding")}`, `\`${findingLocation(finding)}\``, "");
 			if (finding.body?.trim()) lines.push(finding.body.trim(), "");
 		}
@@ -506,6 +589,10 @@ export function validateInlineComments(
 			errors.push(`${label}: comment body is empty or too large`);
 			continue;
 		}
+		if (containsReservedReviewMarker(body)) {
+			errors.push(`${label}: comment body contains a reserved pi-pr-review marker`);
+			continue;
+		}
 		comments.push({
 			path,
 			body,
@@ -546,6 +633,10 @@ export function collectFoldedComments(review: ReviewLike): CommentValidationResu
 			errors.push(`${label}: folded comment body is empty or too large`);
 			continue;
 		}
+		if (containsReservedReviewMarker(body)) {
+			errors.push(`${label}: folded comment body contains a reserved pi-pr-review marker`);
+			continue;
+		}
 		comments.push({
 			path,
 			body,
@@ -630,6 +721,19 @@ async function ghJson<T>(args: string[], cwd: string): Promise<T> {
 	return JSON.parse(text) as T;
 }
 
+export async function resolveRepositoryBinding(cwd: string): Promise<RepositoryBinding> {
+	const repoInfo = await ghJson<{ nameWithOwner?: string; url?: string }>(
+		["repo", "view", "--json", "nameWithOwner,url"],
+		cwd,
+	);
+	const repository = String(repoInfo.nameWithOwner ?? "");
+	const hostname = new URL(String(repoInfo.url ?? "")).hostname;
+	if (!/^[^/\s]+\/[^/\s]+$/.test(repository) || !/^[a-z0-9.-]+$/i.test(hostname)) {
+		throw new Error("invalid GitHub repository or hostname");
+	}
+	return { repository, hostname };
+}
+
 function flattenPages<T>(value: unknown): T[] {
 	if (!Array.isArray(value)) return [];
 	if (value.every(Array.isArray)) return value.flat() as T[];
@@ -680,6 +784,50 @@ interface PullState {
 	head?: { sha?: string };
 }
 
+export interface HeadPublicationPlan {
+	reviewedHeadSha: string;
+	currentHeadSha: string;
+	stale: boolean;
+	commitId: string;
+	allowInlineComments: boolean;
+}
+
+/** Authorize a reviewed/current head pairing without silently weakening stale protection. */
+export function planHeadPublication(
+	reviewedHeadSha: string,
+	currentHeadSha: string | undefined,
+	allowStale: boolean,
+): { plan?: HeadPublicationPlan; error?: string } {
+	const reviewed = reviewedHeadSha.toLowerCase();
+	const current = currentHeadSha?.toLowerCase();
+	if (!current || !/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(current)) {
+		return { error: "GitHub returned an invalid current PR head SHA" };
+	}
+	const stale = current !== reviewed;
+	if (stale && !allowStale) {
+		return {
+			error: `PR head changed after review (${reviewed} -> ${current}); refusing to publish stale results. Use /pr-review-publish with --allow-stale to post the completed review without rerunning it`,
+		};
+	}
+	return {
+		plan: {
+			reviewedHeadSha: reviewed,
+			currentHeadSha: current,
+			stale,
+			commitId: stale ? current : reviewed,
+			allowInlineComments: !stale,
+		},
+	};
+}
+
+export function buildStaleReviewNotice(reviewedHeadSha: string, currentHeadSha: string): string {
+	return [
+		"> [!WARNING]",
+		`> This review was generated for commit \`${reviewedHeadSha}\`. At publish preflight, the PR pointed to \`${currentHeadSha}\`.`,
+		"> Inline findings were folded into this body because their original diff anchors may be stale.",
+	].join("\n");
+}
+
 export type PullLifecycle = "open" | "non_open";
 
 export function authorizePullLifecycle(
@@ -736,9 +884,11 @@ export async function publishPullReview(input: {
 	prNumber: number;
 	headSha: string;
 	allowNonOpen: boolean;
+	allowStale?: boolean;
+	expectedRepository?: RepositoryBinding;
 	review: ReviewLike;
 }): Promise<PublishResult> {
-	const { cwd, prNumber, headSha, allowNonOpen, review } = input;
+	const { cwd, prNumber, headSha, allowNonOpen, allowStale = false, expectedRepository, review } = input;
 	if (!Number.isInteger(prNumber) || prNumber <= 0) return { status: "failed", message: "invalid PR number" };
 	if (!/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/i.test(headSha)) return { status: "failed", message: "invalid head SHA" };
 	const normalizedHeadSha = headSha.toLowerCase();
@@ -747,29 +897,31 @@ export async function publishPullReview(input: {
 	let hostname: string;
 	let identity: string;
 	try {
-		const repoInfo = await ghJson<{ nameWithOwner?: string; url?: string }>(
-			["repo", "view", "--json", "nameWithOwner,url"],
-			cwd,
-		);
-		repository = String(repoInfo.nameWithOwner ?? "");
-		hostname = new URL(String(repoInfo.url ?? "")).hostname;
+		const binding = await resolveRepositoryBinding(cwd);
+		repository = binding.repository;
+		hostname = binding.hostname;
+		if (
+			expectedRepository &&
+			completedReviewKey(expectedRepository, prNumber) !== completedReviewKey(binding, prNumber)
+		) {
+			return { status: "failed", message: "current GitHub repository does not match the cached review repository" };
+		}
 		identity = await ghText(githubApiArgs(hostname, "user", "--jq", ".login"), cwd);
 	} catch (error) {
 		return { status: "failed", message: `GitHub identity/repository lookup failed: ${String(error)}` };
 	}
-	if (!/^[^/\s]+\/[^/\s]+$/.test(repository) || !/^[a-z0-9.-]+$/i.test(hostname) || !identity) {
-		return { status: "failed", message: "invalid GitHub repository, hostname, or identity" };
-	}
+	if (!identity) return { status: "failed", message: "invalid GitHub identity" };
 
 	const marker = canonicalReviewMarker(normalizedHeadSha);
 	const lockKey = `${hostname}:${repository}:${prNumber}:${normalizedHeadSha}:${identity.toLowerCase()}`;
 	return withPublishLock(lockKey, async () => {
 		let pull: PullState;
+		let headPlan: HeadPublicationPlan;
 		try {
 			pull = await ghJson<PullState>(githubApiArgs(hostname, `repos/${repository}/pulls/${prNumber}`), cwd);
-			if (pull.head?.sha?.toLowerCase() !== normalizedHeadSha) {
-				return { status: "failed", message: "PR head changed after review; refusing to publish stale results" };
-			}
+			const planned = planHeadPublication(normalizedHeadSha, pull.head?.sha, allowStale);
+			if (!planned.plan) return { status: "failed", message: planned.error ?? "invalid PR head" };
+			headPlan = planned.plan;
 			if (pull.draft) return { status: "failed", message: "draft PR reviews are not automatically published" };
 			const lifecycle = authorizePullLifecycle(pull.state, pull.merged_at, allowNonOpen);
 			if (!lifecycle.lifecycle) return { status: "failed", message: lifecycle.error ?? "invalid PR lifecycle" };
@@ -780,40 +932,55 @@ export async function publishPullReview(input: {
 			return { status: "failed", message: `GitHub preflight failed: ${String(error)}` };
 		}
 
-		const summary = buildReviewSummary(review);
-		const bodyError = validateReviewBody(summary);
-		if (bodyError) return { status: "failed", message: bodyError };
-
 		const lifecycle = authorizePullLifecycle(pull.state, pull.merged_at, allowNonOpen);
 		if (!lifecycle.lifecycle) return { status: "failed", message: lifecycle.error ?? "invalid PR lifecycle" };
 		const isOpen = lifecycle.lifecycle === "open";
-		const candidates = collectFoldedComments(review);
-		if (candidates.errors.length > 0) {
-			return { status: "failed", message: `inline candidate validation failed: ${candidates.errors.join("; ")}` };
-		}
-		let comments: PublishComment[] = candidates.comments;
-		if (isOpen && comments.length > 0) {
-			let filePages: unknown;
-			try {
-				filePages = await ghJson<unknown>(
-					githubApiArgs(hostname, "--paginate", "--slurp", `repos/${repository}/pulls/${prNumber}/files?per_page=100`),
-					cwd,
-				);
-			} catch (error) {
-				return { status: "failed", message: `changed-file lookup failed: ${String(error)}` };
+		let comments: PublishComment[] = [];
+		if (!isOpen) {
+			const candidates = collectFoldedComments(review);
+			if (candidates.errors.length > 0) {
+				return { status: "failed", message: `inline candidate validation failed: ${candidates.errors.join("; ")}` };
 			}
-			const validated = validateInlineComments(review, flattenPages<ChangedFileLike>(filePages));
-			if (validated.errors.length > 0) {
-				return { status: "failed", message: `inline validation failed: ${validated.errors.join("; ")}` };
+			comments = candidates.comments;
+		} else if (headPlan.allowInlineComments) {
+			const candidates = collectFoldedComments(review);
+			if (candidates.errors.length > 0) {
+				return { status: "failed", message: `inline candidate validation failed: ${candidates.errors.join("; ")}` };
+			}
+			if (candidates.comments.length > 0) {
+				let filePages: unknown;
+				try {
+					filePages = await ghJson<unknown>(
+						githubApiArgs(hostname, "--paginate", "--slurp", `repos/${repository}/pulls/${prNumber}/files?per_page=100`),
+						cwd,
+					);
+				} catch (error) {
+					return { status: "failed", message: `changed-file lookup failed: ${String(error)}` };
+				}
+				const validated = validateInlineComments(review, flattenPages<ChangedFileLike>(filePages));
+				if (validated.errors.length > 0) {
+					return { status: "failed", message: `inline validation failed: ${validated.errors.join("; ")}` };
+				}
+				comments = validated.comments;
 			}
-			comments = validated.comments;
 		}
 
-		const reviewBody = `${isOpen ? summary : foldInlineComments(summary, comments)}\n\n${marker}`;
+		const summary = buildReviewSummary(review, comments);
+		const bodyError = validateReviewBody(summary);
+		if (bodyError) return { status: "failed", message: bodyError };
+		const lifecycleBody = isOpen ? summary : foldInlineComments(summary, comments);
+		const disclosedBody = headPlan.stale
+			? `${buildStaleReviewNotice(headPlan.reviewedHeadSha, headPlan.currentHeadSha)}\n\n${lifecycleBody}`
+			: lifecycleBody;
+		const reviewBody = `${disclosedBody}\n\n${marker}`;
 		if (Buffer.byteLength(reviewBody, "utf8") > MAX_BODY_BYTES) {
 			return { status: "failed", message: "final review body exceeds 65536 UTF-8 bytes" };
 		}
-		const payload = buildPullReviewPayload(normalizedHeadSha, reviewBody, isOpen ? comments : []);
+		const payload = buildPullReviewPayload(
+			headPlan.commitId,
+			reviewBody,
+			isOpen && headPlan.allowInlineComments ? comments : [],
+		);
 		if (Buffer.byteLength(JSON.stringify(payload), "utf8") > MAX_PAYLOAD_BYTES) {
 			return { status: "failed", message: "review payload is too large" };
 		}
@@ -823,8 +990,11 @@ export async function publishPullReview(input: {
 				githubApiArgs(hostname, `repos/${repository}/pulls/${prNumber}`),
 				cwd,
 			);
-			if (refreshed.head?.sha?.toLowerCase() !== normalizedHeadSha) {
-				return { status: "failed", message: "PR head changed during publish preflight" };
+			if (refreshed.head?.sha?.toLowerCase() !== headPlan.currentHeadSha) {
+				return {
+					status: "failed",
+					message: "PR head changed during publish preflight; run the publish-only command again to acknowledge the new current head",
+				};
 			}
 			if (refreshed.draft) return { status: "failed", message: "PR became a draft during publish preflight" };
 			const refreshedLifecycle = authorizePullLifecycle(refreshed.state, refreshed.merged_at, allowNonOpen);
@@ -850,9 +1020,14 @@ export async function publishPullReview(input: {
 			} catch {
 				/* accepted response without parseable metadata */
 			}
+			const degraded = !isOpen || headPlan.stale;
 			return {
-				status: isOpen ? "posted" : "posted_degraded",
-				message: isOpen ? "GitHub COMMENT review posted" : "body-only COMMENT review posted for non-open PR",
+				status: degraded ? "posted_degraded" : "posted",
+				message: headPlan.stale
+					? `body-only stale COMMENT review posted (${headPlan.reviewedHeadSha} -> ${headPlan.currentHeadSha})`
+					: isOpen
+						? "GitHub COMMENT review posted"
+						: "body-only COMMENT review posted for non-open PR",
 				reviewId: response.id,
 				url: response.html_url,
 			};
@@ -861,7 +1036,7 @@ export async function publishPullReview(input: {
 		try {
 			if (await hasExistingMarker(cwd, hostname, repository, prNumber, identity, normalizedHeadSha)) {
 				return {
-					status: isOpen ? "posted" : "posted_degraded",
+					status: !isOpen || headPlan.stale ? "posted_degraded" : "posted",
 					message: "GitHub review found during failure reconciliation",
 					reconciled: true,
 				};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-pr-review",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "Model-agnostic GitHub PR code review prompt for pi. Pass a PR number; it derives the base and head branches from the PR in the current repo, reviews the diff, and returns structured JSON findings.",
   "keywords": [
     "pi-package",

package/prompts/pr-review.md

@@ -164,7 +164,9 @@ The orchestrator must never call `gh` to post comments or reviews. Always finish
 - `--comment` → force publication for this run, but never bypass validation, stale-head checks, or duplicate checks
 - `--no-comment` → suppress publication for this run
 
-When enabled, the extension creates exactly one formal GitHub pull-request review. Its top-level body contains the overview, verification, strengths, findings summary, and suggested verdict; eligible P0–P3 diff-anchored findings are attached as inline comments within that same review. The API event is hardcoded to `COMMENT`: publication never sends `APPROVE` or `REQUEST_CHANGES`, even when the suggested verdict is `request_changes`. It appends the same-head marker, verifies the current head, validates every inline anchor against GitHub diff metadata, and refuses partial open-PR publication. For a known closed/merged PR it requires either trusted `--include-closed`/`--review-closed` invocation authority or the one-shot affirmative confirmation flow, then posts one body-only `COMMENT` review with inline findings folded into the body. Unknown lifecycle states and unconfirmed non-open writes fail without posting or falling back to an issue comment.
+When enabled, the extension creates exactly one formal GitHub pull-request review. Its top-level body contains the overview, verification, strengths, suggested verdict, counts, nits, and findings that cannot be attached inline. Eligible P0–P3 diff-anchored findings are attached as inline comments within that same review and are omitted from the top-level issue list to avoid duplication. The API event is hardcoded to `COMMENT`: publication never sends `APPROVE` or `REQUEST_CHANGES`, even when the suggested verdict is `request_changes`. It appends the same-head marker, verifies the current head, validates every inline anchor against GitHub diff metadata, and refuses partial open-PR publication. For a known closed/merged PR it requires either trusted `--include-closed`/`--review-closed` invocation authority or the one-shot affirmative confirmation flow, then posts one body-only `COMMENT` review with each inline finding folded into the body exactly once. Unknown lifecycle states and unconfirmed non-open writes fail without posting or falling back to an issue comment.
+
+The extension caches the latest valid completed review per repository and PR before publication preflight for the current extension session. If publication reports that the PR head changed, the user can run `/pr-review-publish <PR-NUM> --allow-stale` to post that cached result without another model turn. This explicit stale override produces a body-only `COMMENT` review with the reviewed and preflight-observed SHAs disclosed and no potentially invalid inline anchors. Never rerun the review merely to change posting intent, and never attempt the GitHub write yourself.
 
 ---
 
@@ -202,7 +204,7 @@ Your final message must be **exactly one JSON object** matching the shape below
 }
 ```
 
-- `pr.head_sha` is the exact full `headRefOid` reviewed; the publisher rejects stale or missing head SHAs.
+- `pr.head_sha` is the exact full `headRefOid` reviewed; the publisher rejects missing SHAs and rejects stale SHAs by default unless the user explicitly invokes the publish-only `--allow-stale` override.
 - `disposition` is exactly `"reviewed"` or `"skipped"`. The extension never publishes `skipped` results.
 - `verdict` is exactly `"approve"`, `"request_changes"`, or `"comment"`.
 - `overall_correctness` is exactly `"patch is correct"` or `"patch is incorrect"`.

package/tests/pr-review-publish.test.ts

@@ -1,19 +1,27 @@
 import { describe, expect, test } from "bun:test";
-import { readFileSync } from "node:fs";
+import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import {
 	authorizePullLifecycle,
 	bodyHasHeadMarker,
 	buildPullReviewPayload,
+	buildReviewSummary,
+	buildStaleReviewNotice,
 	classifyAssistantCompletion,
 	canonicalReviewMarker,
 	collectFoldedComments,
+	CompletedReviewCache,
 	containsReservedReviewMarker,
 	foldInlineComments,
 	githubApiArgs,
 	isAffirmativeReviewConfirmation,
 	isNonOpenConfirmationPrompt,
 	parsePublishableReview,
+	parsePublishExistingArgs,
 	parsePublishMode,
+	planHeadPublication,
+	publishPullReview,
 	resolveAutoPostSetting,
 	ReviewInvocationGate,
 	shouldPublishReview,
@@ -154,6 +162,140 @@ describe("trusted invocation mode", () => {
 	});
 });
 
+describe("publish-only completed review command", () => {
+	test("requires an explicit PR and recognizes only the stale override", () => {
+		expect(parsePublishExistingArgs("7")).toEqual({ prNumber: 7, allowStale: false });
+		expect(parsePublishExistingArgs("7 --allow-stale")).toEqual({ prNumber: 7, allowStale: true });
+		expect(parsePublishExistingArgs("").error).toContain("positive PR number");
+		expect(parsePublishExistingArgs("7 --comment").error).toContain("unknown argument");
+	});
+
+	test("retains the latest completed review under its repository and PR", () => {
+		const cache = new CompletedReviewCache();
+		const invocation = { mode: "force" as const, prNumber: 7, allowNonOpen: false };
+		const repository = { hostname: "github.com", repository: "owner/repo" };
+		cache.remember(review, invocation, repository);
+		expect(cache.get(7, repository)).toEqual({ review, invocation, repository });
+		expect(cache.get(7, { hostname: "github.com", repository: "other/repo" })).toBeUndefined();
+		expect(cache.get(8, repository)).toBeUndefined();
+		cache.clear();
+		expect(cache.get(7, repository)).toBeUndefined();
+	});
+
+	test("keeps stale protection by default and degrades an explicit override", () => {
+		const reviewed = "a".repeat(40);
+		const current = "b".repeat(40);
+		expect(planHeadPublication(reviewed, current, false).error).toContain("--allow-stale");
+		const plan = planHeadPublication(reviewed, current, true).plan!;
+		expect(plan).toMatchObject({
+			reviewedHeadSha: reviewed,
+			currentHeadSha: current,
+			stale: true,
+			commitId: current,
+			allowInlineComments: false,
+		});
+		const body = `${buildStaleReviewNotice(reviewed, current)}\n\n${buildReviewSummary(review, [])}`;
+		const payload = buildPullReviewPayload(plan.commitId, body, []);
+		expect(payload.comments).toBeUndefined();
+		expect(payload.body).toContain(reviewed);
+		expect(payload.body).toContain(current);
+		expect(payload.body).toContain("[P2] Handle empty input");
+	});
+
+	test("posts an explicitly stale review body through gh without inline comments", async () => {
+		const dir = mkdtempSync(join(tmpdir(), "pi-pr-review-gh-"));
+		const gh = join(dir, "gh");
+		const payloadPath = join(dir, "payload.json");
+		writeFileSync(
+			gh,
+			`#!/usr/bin/env bash
+set -euo pipefail
+args="$*"
+if [[ "$args" == "repo view --json nameWithOwner,url" ]]; then
+  echo '{"nameWithOwner":"owner/repo","url":"https://github.com/owner/repo"}'
+elif [[ "$args" == *" user --jq .login"* ]]; then
+  echo 'reviewer'
+elif [[ "$args" == *"--method POST"* ]]; then
+  cat > "$GH_FAKE_PAYLOAD"
+  echo '{"id":42,"html_url":"https://github.com/owner/repo/pull/7#pullrequestreview-42"}'
+elif [[ "$args" == *"pulls/7/reviews?per_page=100"* || "$args" == *"issues/7/comments?per_page=100"* ]]; then
+  echo '[]'
+elif [[ "$args" == *"repos/owner/repo/pulls/7"* ]]; then
+  printf '{"state":"open","draft":false,"merged_at":null,"head":{"sha":"%s"}}\n' "$GH_FAKE_CURRENT"
+else
+  echo "unexpected gh args: $args" >&2
+  exit 1
+fi
+`,
+		);
+		chmodSync(gh, 0o755);
+		const previousPath = process.env.PATH;
+		const previousPayload = process.env.GH_FAKE_PAYLOAD;
+		const previousCurrent = process.env.GH_FAKE_CURRENT;
+		const current = "b".repeat(40);
+		process.env.PATH = `${dir}:${previousPath ?? ""}`;
+		process.env.GH_FAKE_PAYLOAD = payloadPath;
+		process.env.GH_FAKE_CURRENT = current;
+		try {
+			const input = {
+				cwd: dir,
+				prNumber: 7,
+				headSha: "a".repeat(40),
+				allowNonOpen: false,
+				expectedRepository: { hostname: "github.com", repository: "owner/repo" },
+				review,
+			};
+			const wrongRepository = await publishPullReview({
+				...input,
+				expectedRepository: { hostname: "github.com", repository: "other/repo" },
+				allowStale: true,
+			});
+			expect(wrongRepository.message).toContain("does not match the cached review repository");
+			const refused = await publishPullReview(input);
+			expect(refused.status).toBe("failed");
+			expect(refused.message).toContain("--allow-stale");
+			const posted = await publishPullReview({ ...input, allowStale: true });
+			expect(posted.status).toBe("posted_degraded");
+			const payload = JSON.parse(readFileSync(payloadPath, "utf8"));
+			expect(payload.commit_id).toBe(current);
+			expect(payload.comments).toBeUndefined();
+			expect(payload.body).toContain("a".repeat(40));
+			expect(payload.body).toContain(current);
+			expect(payload.body).toContain("At publish preflight");
+			expect(payload.body).toContain("[P2] Handle empty input");
+		} finally {
+			if (previousPath === undefined) delete process.env.PATH;
+			else process.env.PATH = previousPath;
+			if (previousPayload === undefined) delete process.env.GH_FAKE_PAYLOAD;
+			else process.env.GH_FAKE_PAYLOAD = previousPayload;
+			if (previousCurrent === undefined) delete process.env.GH_FAKE_CURRENT;
+			else process.env.GH_FAKE_CURRENT = previousCurrent;
+			rmSync(dir, { recursive: true, force: true });
+		}
+	});
+
+	test("preserves inline publication when the reviewed head is still current", () => {
+		const head = "a".repeat(40);
+		expect(planHeadPublication(head, head.toUpperCase(), false).plan).toMatchObject({
+			stale: false,
+			commitId: head,
+			allowInlineComments: true,
+		});
+	});
+
+	test("registers and documents a direct command rather than delegating stale publication to the model", () => {
+		const extension = readFileSync(new URL("../extensions/review-table.ts", import.meta.url), "utf8");
+		const readme = readFileSync(new URL("../README.md", import.meta.url), "utf8");
+		const prompt = readFileSync(new URL("../prompts/pr-review.md", import.meta.url), "utf8");
+		expect(extension).toContain('pi.registerCommand("pr-review-publish"');
+		expect(extension).toContain("This command never starts or reruns a review");
+		expect(extension).toContain("still being reviewed");
+		expect(readme).toContain("/pr-review-publish 123 --allow-stale");
+		expect(readme).toContain("Inline comments are intentionally disabled");
+		expect(prompt).toContain("without another model turn");
+	});
+});
+
 describe("non-open publication authorization", () => {
 	test("rejects direct unconfirmed closed and unknown states", () => {
 		expect(authorizePullLifecycle("closed", null, false).error).toContain("not authorized");
@@ -202,7 +344,11 @@ describe("atomic COMMENT review payload", () => {
 		const validated = validateInlineComments(review, changedFiles);
 		expect(validated.errors).toEqual([]);
 		expect(validated.comments).toHaveLength(1); // nits remain in the top-level summary
-		const payload = buildPullReviewPayload("a".repeat(40), "Top-level review", validated.comments);
+		const summary = buildReviewSummary(review, validated.comments);
+		expect(summary).toContain("2 total (1 inline, 1 summary-only)");
+		expect(summary).not.toContain("[P2] Handle empty input");
+		expect(summary).toContain("[nit] Rename tmp");
+		const payload = buildPullReviewPayload("a".repeat(40), summary, validated.comments);
 		expect(payload.event).toBe("COMMENT");
 		expect(payload).not.toHaveProperty("event", "REQUEST_CHANGES");
 		expect(payload.comments?.[0]).toMatchObject({
@@ -213,6 +359,29 @@ describe("atomic COMMENT review payload", () => {
 		});
 	});
 
+	test("keeps nits and noncommentable findings even when anchors collide", () => {
+		const colliding: ReviewLike = JSON.parse(JSON.stringify(review));
+		colliding.findings![1]!.code_location!.line_range = { start: 2, end: 3 };
+		colliding.findings!.push({
+			title: "[P3] Summary-only collision",
+			severity: "P3",
+			blocking: false,
+			body: "This finding intentionally remains in the summary.",
+			confidence_score: 0.8,
+			code_location: {
+				absolute_file_path: "src/parser.ts",
+				line_range: { start: 2, end: 3 },
+				side: "RIGHT",
+				commentable: false,
+			},
+		});
+		const validated = validateInlineComments(colliding, changedFiles);
+		expect(validated.errors).toEqual([]);
+		const summary = buildReviewSummary(colliding, validated.comments);
+		expect(summary).toContain("[nit] Rename tmp");
+		expect(summary).toContain("[P3] Summary-only collision");
+	});
+
 	test("rejects anchors outside changed diff metadata", () => {
 		const invalid: ReviewLike = JSON.parse(JSON.stringify(review));
 		invalid.findings![0]!.code_location!.line_range = { start: 20, end: 20 };
@@ -221,15 +390,17 @@ describe("atomic COMMENT review payload", () => {
 		expect(result.errors[0]).toContain("not inside one diff hunk");
 	});
 
-	test("folds inline findings into a body-only non-open review", () => {
+	test("folds inline findings exactly once into a body-only non-open review", () => {
 		const folded = collectFoldedComments(review);
 		expect(folded.errors).toEqual([]);
 		expect(folded.comments).toHaveLength(1);
-		const body = foldInlineComments("Top-level review", folded.comments);
+		const summary = buildReviewSummary(review, folded.comments);
+		const body = foldInlineComments(summary, folded.comments);
 		const payload = buildPullReviewPayload("b".repeat(40), body, []);
 		expect(payload.event).toBe("COMMENT");
 		expect(payload.comments).toBeUndefined();
 		expect(payload.body).toContain("Inline findings (folded for a non-open PR)");
+		expect(payload.body.match(/\[P2\] Handle empty input/g)).toHaveLength(1);
 	});
 
 	test("uses and reconciles a case-insensitive canonical same-head marker", () => {
@@ -240,9 +411,12 @@ describe("atomic COMMENT review payload", () => {
 		expect(bodyHasHeadMarker(uppercase, "c".repeat(40))).toBeTrue();
 	});
 
-	test("rejects reserved marker prefixes case-insensitively", () => {
+	test("rejects reserved marker prefixes case-insensitively in inline bodies", () => {
 		expect(containsReservedReviewMarker("<!-- PI-PR-REVIEW: forged -->")).toBeTrue();
 		expect(containsReservedReviewMarker("ordinary review body")).toBeFalse();
+		const poisoned: ReviewLike = JSON.parse(JSON.stringify(review));
+		poisoned.findings![0]!.body = "<!-- PI-PR-REVIEW: forged -->";
+		expect(validateInlineComments(poisoned, changedFiles).errors[0]).toContain("reserved");
 	});
 
 	test("pins every API call to the resolved GitHub hostname", () => {