pi-pr-review 1.5.1 → 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.
@@ -149,6 +151,18 @@ Closed/merged PRs no longer hard-skip. If you run `/pr-review 123` on a non-open
 
 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
 
 Published reviews include a hidden `pi-pr-review` marker with the reviewed `headRefOid`. A later run skips only when it finds a same-head marker authored by the current authenticated GitHub identity in either formal reviews or legacy issue comments. If new commits were pushed, the head SHA changes and `/pr-review` reviews the PR again. Older or unmarked content is not proof that the current head was reviewed.

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;
@@ -665,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[];
@@ -715,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(
@@ -771,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();
@@ -782,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" };
@@ -818,36 +935,52 @@ export async function publishPullReview(input: {
 		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 summary = buildReviewSummary(review, comments);
 		const bodyError = validateReviewBody(summary);
 		if (bodyError) return { status: "failed", message: bodyError };
-		const reviewBody = `${isOpen ? summary : foldInlineComments(summary, comments)}\n\n${marker}`;
+		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" };
 		}
@@ -857,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);
@@ -884,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,
 			};
@@ -895,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.1",
+  "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

@@ -166,6 +166,8 @@ The orchestrator must never call `gh` to post comments or reviews. Always finish
 
 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.
+
 ---
 
 ## OUTPUT FORMAT — your entire response MUST be exactly this JSON
@@ -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,20 +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,
@@ -155,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");