pi-pr-review 1.10.5 → 1.10.6

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.10.6](https://github.com/10ego/pi-pr-review/compare/v1.10.5...v1.10.6) (2026-07-17)
+
+
+### Bug Fixes
+
+* **publish:** simplify reliable review posting ([#31](https://github.com/10ego/pi-pr-review/issues/31)) ([7d93560](https://github.com/10ego/pi-pr-review/commit/7d935604b620a51b04708633da7c4dc0850d6096))
+
 ## [1.10.5](https://github.com/10ego/pi-pr-review/compare/v1.10.4...v1.10.5) (2026-07-17)
 
 

package/README.md

@@ -182,21 +182,23 @@ Publishing is off by default.
 /pr-review-config auto_post_reviews=true
 ```
 
-The extension—not the model—owns publishing. It creates one formal review with the event hardcoded to `COMMENT`; it never submits `APPROVE` or `REQUEST_CHANGES`. Before writing, it verifies the current PR head, validates inline anchors, and checks for a review of the same head by the current GitHub identity.
+The extension—not the model—owns publishing. After a successful review, it caches one validated completed review per repository and PR in the current Pi session. `autoPostReviews` and `--comment` publish that cached review after completion; `--no-comment` suppresses publication for the run.
 
-If the agent's final review is not valid exact-contract JSON, the extension logs the validation reason and automatically asks the same agent to correct its completed output once, with all tools disabled and without changing the captured posting authority. A valid correction is cached and publication is attempted under the original flags/config. If that single correction is also invalid or attempts to call a tool, publication stops and reports the error instead of looping. Overlapping input cancels the correction, remains unqueued, and must be retried after the agent settles.
+If the agent's final review is not valid exact-contract JSON, the extension logs the reason and automatically asks the same agent to correct its completed output once, with tools disabled and the original posting authority unchanged. An invalid correction, a tool call, or overlapping input stops publication rather than starting another correction loop.
 
-Closed or merged PRs use a body-only review. Open PRs attach eligible P0–P3 findings as inline comments and keep nits or off-diff findings in the review body. When GitHub omits patch metadata needed to validate an inline anchor, the affected finding remains in the review summary instead of blocking publication. When multiple findings target the same diff anchor, the first is attached inline and later findings remain in the review body so publication neither fails nor drops review content.
+You can publish the cache later with `/pr-review-publish 123`, or directly ask the agent to “post the inline review,” “post it as an inline review,” or “publish the review for PR #123.” The extension handles that request directly before an agent turn. `/pr-review-publish` and a matching direct request publish only the cache; they never start or rerun review agents. Unnumbered direct requests select the latest cached review for the current repository. Only fresh interactive/RPC input can use the direct path.
 
-After a review completes, you can directly ask the agent to “post the inline review” or “post it as an inline review.” The extension handles that request directly before an agent turn, selecting the latest cached review for an unnumbered request or the named PR in “publish the review for PR #123.” Only fresh interactive/RPC input can trigger this path; extension-generated, queued, or steering input cannot. The extension publishes only validated cached content, never replacement model-authored text, and never starts or reruns review agents. A direct request permits stale publication.
+Every authorized publish path builds one `COMMENT` payload and sends at most one GitHub review `POST`; it never submits `APPROVE` or `REQUEST_CHANGES` and never retries a rejected write with a fallback POST. For a current, open PR, the first 50 eligible P0–P3 findings with valid, unique diff anchors are inline. All other findings that pass content validation stay in the top-level review body, including nits, off-diff findings, unavailable diff metadata, duplicate anchors, and overflow. Stale or authorized non-open reviews are body-only.
 
-Stale publication is also enabled by default through `allowStalePublish: true`; disable it with `/pr-review-config allow_stale_publish=false`. Automatic posting and `/pr-review-publish` without an override use the setting captured when the review starts. The explicit `--allow-stale` flag remains available when the captured setting disabled stale publication:
+The same safety gates apply to every path: captured posting authority, exact repository/PR/review binding, safe locations, no reserved review markers, bounded bodies and payloads, current-head and stale policy, draft and lifecycle checks, non-open authorization, same-head duplicate detection, and a final head check. Unknown or invalid states fail closed before a write.
+
+Stale publication is enabled by default through `allowStalePublish: true`; disable it with `/pr-review-config allow_stale_publish=false`. Automatic posting and `/pr-review-publish` use the setting captured when the review starts unless the command supplies the explicit override:
 
 ```text
 /pr-review-publish 123 --allow-stale
 ```
 
-Inline comments are always disabled for stale reviews because the original anchors may no longer be valid. The stale review is body-only and displays a warning containing both the reviewed and current commit hashes. The cache is stored in the current Pi session, survives extension reloads and session resumes, and is bound to that session instance's ID and creation metadata as well as the repository.
+A matching direct request permits stale publication. Inline comments are always disabled for stale reviews because the original anchors may no longer be valid; the body identifies both the reviewed and current commit. The session-backed cache survives extension reloads and session resumes and remains bound to the originating session instance and repository.
 
 ## Optional verification
 

package/extensions/review-table.ts

@@ -39,9 +39,7 @@ import {
 	type AutoPostResolution,
 	type CompletedReviewRecord,
 	type CompletedReviewSessionIdentity,
-	type RepositoryBinding,
 	type ReviewInvocation,
-	type ReviewLike,
 } from "../lib/pr-review-publish.ts";
 import {
 	ReviewLoopCoordinator,
@@ -379,51 +377,48 @@ function notifyPublishResult(
 	}
 }
 
-async function maybePublishReview(
-	text: string,
-	invocation: ReviewInvocation,
+type ReviewPublicationOrigin =
+	| { readonly kind: "frozen-invocation" }
+	| { readonly kind: "publish-command"; readonly stalePolicy: "frozen" | "allow-stale" }
+	| { readonly kind: "direct-request" };
+
+async function publishCompletedReview(
+	record: CompletedReviewRecord,
+	origin: ReviewPublicationOrigin,
 	ctx: ExtensionContext,
-	expectedRepository?: RepositoryBinding,
 ): Promise<void> {
-	const authority = decideReviewPublication(invocation);
-	if (authority.error) {
-		ctx.ui.notify(`PR review was not posted: ${authority.error}`, "error");
-		return;
-	}
-	if (!authority.publish) return;
-	const parsed = parsePublishableReview(text);
-	if (!parsed.review) {
-		ctx.ui.notify(`PR review was not posted: ${parsed.error}`, "error");
-		return;
-	}
-	const bindingError = validateReviewInvocation(parsed.review, invocation);
-	if (bindingError) {
-		ctx.ui.notify(`PR review was not posted: ${bindingError}`, "error");
+	const decision = origin.kind === "frozen-invocation"
+		? decideReviewPublication(record.invocation)
+		: undefined;
+	if (decision?.error) {
+		ctx.ui.notify(`PR review was not posted: ${decision.error}`, "error");
 		return;
 	}
-	if (!shouldPublishReview(parsed.review)) return;
-	const headSha = parsed.review.pr?.head_sha;
+	if (decision && !decision.publish) return;
+	const explicitStale = origin.kind === "direct-request" ||
+		(origin.kind === "publish-command" && origin.stalePolicy === "allow-stale");
+	const allowStale = explicitStale || record.invocation.allowStalePublish;
+	const source = decision?.source ?? (origin.kind === "frozen-invocation"
+		? "frozen invocation"
+		: origin.kind === "direct-request"
+			? "direct user request"
+			: origin.stalePolicy === "allow-stale" ? "publish-only --allow-stale" : "publish-only");
+
+	const headSha = record.review.pr?.head_sha;
 	if (typeof headSha !== "string") {
-		ctx.ui.notify("PR review was not posted: final JSON is missing pr.head_sha", "error");
-		return;
-	}
-	if (!expectedRepository) {
-		ctx.ui.notify(
-			"PR review was not posted because its repository identity could not be established before caching; no publish-only cache is available. Rerun /pr-review when GitHub repository lookup is working.",
-			"error",
-		);
+		ctx.ui.notify("PR review was not posted: cached final JSON is missing pr.head_sha", "error");
 		return;
 	}
 	const result = await publishPullReview({
 		cwd: ctx.cwd,
-		prNumber: invocation.prNumber,
+		prNumber: record.invocation.prNumber,
 		headSha,
-		allowNonOpen: invocation.allowNonOpen,
-		allowStale: invocation.allowStalePublish,
-		expectedRepository,
-		review: parsed.review as ReviewLike,
+		allowNonOpen: record.invocation.allowNonOpen,
+		allowStale,
+		expectedRepository: record.repository,
+		review: record.review,
 	});
-	notifyPublishResult(result, authority.source ?? "frozen invocation", ctx);
+	notifyPublishResult(result, source, ctx);
 }
 
 export default function registerReviewTable(
@@ -447,15 +442,41 @@ export default function registerReviewTable(
 		}
 		restoreCompletedReviewBranch(completedReviews, ctx.sessionManager.getBranch(), session);
 	};
-	let pendingCompletion:
-		| {
-				text: string;
-				invocation: ReviewInvocation;
-				repository?: RepositoryBinding;
-				record?: CompletedReviewRecord;
-				session?: CompletedReviewSessionIdentity;
-		  }
-		| undefined;
+	type PendingCompletion =
+		| { readonly record: CompletedReviewRecord; readonly session?: CompletedReviewSessionIdentity }
+		| { readonly error: string };
+	let pendingCompletion: PendingCompletion | undefined;
+	const completionError = (invocation: ReviewInvocation, failure?: string): PendingCompletion | undefined => {
+		const decision = decideReviewPublication(invocation);
+		const error = decision.error ?? (decision.publish ? failure : undefined);
+		return error ? { error } : undefined;
+	};
+	const resolveCompletion = async (
+		parsed: ReturnType<typeof parsePublishableReview>,
+		invocation: ReviewInvocation,
+		ctx: ExtensionContext,
+	): Promise<PendingCompletion | undefined> => {
+		if (!parsed.review) return completionError(invocation, parsed.error ?? "final review JSON is invalid");
+		const bindingError = validateReviewInvocation(parsed.review, invocation);
+		if (bindingError) return completionError(invocation, bindingError);
+		if (!shouldPublishReview(parsed.review)) return completionError(invocation);
+		try {
+			const repository = await resolveRepositoryBinding(ctx.cwd);
+			// Cache before publication preflight; persist after Pi stores the assistant message.
+			const record = completedReviews.remember(parsed.review, invocation, repository);
+			const session = sessionIdentity(ctx);
+			if (!session) {
+				ctx.ui.notify("Completed review cache will not survive reload: session identity is unavailable", "warning");
+			}
+			return session ? { record, session } : { record };
+		} catch (error) {
+			ctx.ui.notify(`Completed review is not available to publish-only: ${String(error)}`, "warning");
+			return completionError(
+				invocation,
+				"its repository identity could not be established before caching; no publish-only cache is available. Rerun /pr-review when GitHub repository lookup is working.",
+			);
+		}
+	};
 	let outputRepairAttempted = false;
 	let outputRepairCancelled = false;
 	const telemetryTracker = new ReviewTelemetryTracker();
@@ -469,44 +490,24 @@ export default function registerReviewTable(
 		}
 	};
 
-	type CachedPublication =
-		| { result: Awaited<ReturnType<typeof publishPullReview>> }
-		| { error: string };
-	const publishCachedReview = async (
+	type CachedReviewResolution = { record: CompletedReviewRecord } | { error: string };
+	const resolveCachedReview = async (
 		requestedPrNumber: number | undefined,
-		allowStaleOverride: boolean | undefined,
 		ctx: ExtensionContext,
-	): Promise<CachedPublication> => {
-		let repository: RepositoryBinding;
+	): Promise<CachedReviewResolution> => {
 		try {
-			repository = await resolveRepositoryBinding(ctx.cwd);
-		} catch (error) {
-			return { error: `Cannot resolve the current GitHub repository: ${String(error)}` };
-		}
-		const completed = requestedPrNumber === undefined
-			? completedReviews.latest(repository)
-			: completedReviews.get(requestedPrNumber, repository);
-		if (!completed) {
+			const repository = await resolveRepositoryBinding(ctx.cwd);
+			const record = requestedPrNumber === undefined
+				? completedReviews.latest(repository)
+				: completedReviews.get(requestedPrNumber, repository);
+			if (record) return { record };
 			const target = requestedPrNumber === undefined ? "the latest PR" : `PR #${requestedPrNumber}`;
 			return {
 				error: `No completed review for ${target} is cached for this repository in the current extension session. Publishing never starts or reruns a review.`,
 			};
+		} catch (error) {
+			return { error: `Cannot resolve the current GitHub repository: ${String(error)}` };
 		}
-		const prNumber = completed.invocation.prNumber;
-		const headSha = completed.review.pr?.head_sha;
-		if (typeof headSha !== "string") return { error: "Cached PR review is missing pr.head_sha" };
-		const allowStale = allowStaleOverride ?? completed.invocation.allowStalePublish;
-		return {
-			result: await publishPullReview({
-				cwd: ctx.cwd,
-				prNumber,
-				headSha,
-				allowNonOpen: completed.invocation.allowNonOpen,
-				allowStale,
-				expectedRepository: completed.repository,
-				review: completed.review,
-			}),
-		};
 	};
 
 	pi.registerCommand("pr-review-publish", {
@@ -535,20 +536,15 @@ export default function registerReviewTable(
 				);
 				return;
 			}
-			const published = await publishCachedReview(
-				parsed.prNumber,
-				parsed.allowStale ? true : undefined,
-				ctx,
-			);
-			if ("error" in published) {
-				ctx.ui.notify(published.error, "error");
+			const resolved = await resolveCachedReview(parsed.prNumber, ctx);
+			if ("error" in resolved) {
+				ctx.ui.notify(resolved.error, "error");
 				return;
 			}
-			notifyPublishResult(
-				published.result,
-				parsed.allowStale ? "publish-only --allow-stale" : "publish-only",
-				ctx,
-			);
+			await publishCompletedReview(resolved.record, {
+				kind: "publish-command",
+				stalePolicy: parsed.allowStale ? "allow-stale" : "frozen",
+			}, ctx);
 		},
 	});
 
@@ -630,9 +626,9 @@ export default function registerReviewTable(
 				);
 				return { action: "handled" as const };
 			}
-			const published = await publishCachedReview(directPublish.prNumber, true, ctx);
-			if ("error" in published) ctx.ui.notify(published.error, "error");
-			else notifyPublishResult(published.result, "direct user request", ctx);
+			const resolved = await resolveCachedReview(directPublish.prNumber, ctx);
+			if ("error" in resolved) ctx.ui.notify(resolved.error, "error");
+			else await publishCompletedReview(resolved.record, { kind: "direct-request" }, ctx);
 			return { action: "handled" as const };
 		}
 		if (loopCoordinator.phase() === "awaiting_confirmation") {
@@ -699,24 +695,21 @@ export default function registerReviewTable(
 		const pending = pendingCompletion;
 		pendingCompletion = undefined;
 		if (!pending) return;
-		if (pending.record && pending.session) {
+		if ("error" in pending) {
+			ctx.ui.notify(`PR review was not posted: ${pending.error}`, "error");
+			return;
+		}
+		if (pending.session) {
 			const currentSession = sessionIdentity(ctx);
-			if (
-				!currentSession ||
-				currentSession.id !== pending.session.id ||
-				currentSession.startedAt !== pending.session.startedAt
-			) {
+			if (!currentSession || currentSession.id !== pending.session.id || currentSession.startedAt !== pending.session.startedAt) {
 				ctx.ui.notify("Completed review was not persisted or posted because the session identity changed", "warning");
 				return;
 			}
 			const leaf = ctx.sessionManager.getLeafEntry();
-			const leafText = leaf?.type === "message" && leaf.message.role === "assistant"
-				? assistantText(leaf.message as { content?: MessagePart[] })
-				: "";
-			const leafReview = parsePublishableReview(leafText).review;
-			const reviewEntryId = leaf?.type === "message" && leaf.message.role === "assistant" && leafReview
-				? leaf.id
+			const leafReview = leaf?.type === "message" && leaf.message.role === "assistant"
+				? parsePublishableReview(assistantText(leaf.message as { content?: MessagePart[] })).review
 				: undefined;
+			const reviewEntryId = leafReview ? leaf?.id : undefined;
 			try {
 				// Persist before any GitHub preflight so a failed post always remains retryable.
 				pi.appendEntry(
@@ -727,7 +720,7 @@ export default function registerReviewTable(
 				ctx.ui.notify(`Completed review cache will not survive an extension reload: ${String(error)}`, "warning");
 			}
 		}
-		await maybePublishReview(pending.text, pending.invocation, ctx, pending.repository);
+		await publishCompletedReview(pending.record, { kind: "frozen-invocation" }, ctx);
 	});
 
 	pi.on("message_end", async (event, ctx) => {
@@ -777,7 +770,7 @@ export default function registerReviewTable(
 			return;
 		}
 
-		let publishable = active ? parsePublishableReview(text) : undefined;
+		const publishable = active ? parsePublishableReview(text) : undefined;
 		if (active && !publishable?.review && !outputRepairAttempted) {
 			const error = publishable?.error ?? "final review JSON is invalid";
 			if (loopCoordinator.suspendToolsForRepair()) {
@@ -810,36 +803,19 @@ export default function registerReviewTable(
 			outputRepairCancelled = false;
 			persistTelemetry("terminal_response");
 		}
-		const review = text.trim() ? parseReview(text) : null;
-		if (invocation) {
-			publishable ??= parsePublishableReview(text);
-			let repository: RepositoryBinding | undefined;
-			let record: CompletedReviewRecord | undefined;
-			let session: CompletedReviewSessionIdentity | undefined;
-			if (
-				publishable.review &&
-				!validateReviewInvocation(publishable.review, invocation) &&
-				shouldPublishReview(publishable.review)
-			) {
-				try {
-					repository = await resolveRepositoryBinding(ctx.cwd);
-					// Cache before publication preflight; persist after Pi stores the assistant message.
-					record = completedReviews.remember(publishable.review, invocation, repository);
-					session = sessionIdentity(ctx);
-					if (!session) {
-						ctx.ui.notify("Completed review cache will not survive reload: session identity is unavailable", "warning");
-					}
-				} catch (error) {
-					ctx.ui.notify(`Completed review is not available to publish-only: ${String(error)}`, "warning");
-				}
-			}
-			pendingCompletion = { text, invocation, repository, record, session };
-		}
+		const review = publishable?.review
+			? publishable.review as Review
+			: active
+				? null
+				: text.trim()
+					? parseReview(text)
+					: null;
+		if (invocation) pendingCompletion = await resolveCompletion(publishable!, invocation, ctx);
 		if (!review) return; // not a renderable /pr-review JSON payload — leave untouched
 
 		// Keep raw JSON for automation; only prettify for interactive terminals.
 		if (ctx.mode !== "tui") return;
-		const nonText = (event.message.content as MessagePart[]).filter((p) => p.type !== "text");
+		const nonText = event.message.content.filter((part) => part.type !== "text");
 		return {
 			message: {
 				...event.message,

package/lib/pr-review-publish.ts

@@ -301,6 +301,8 @@ export const MAX_INLINE_COMMENTS = 50;
 const MAX_BODY_BYTES = 65_536;
 const MAX_PAYLOAD_BYTES = 900_000;
 const RESERVED_MARKER_PREFIX = "<!-- pi-pr-review:";
+const CHANGED_FILE_LOOKUP_DIAGNOSTIC =
+	"changed-file lookup failed; all inline findings kept in the review summary";
 
 export interface PublishComment {
 	path: string;
@@ -626,6 +628,9 @@ export function parsePublishableReview(text: string): PublishableReviewParseResu
 		return { error: "final response is not exactly one JSON object" };
 	}
 	if (!isObject(value)) return { error: "final review must be a JSON object" };
+	if (containsReservedReviewMarker(JSON.stringify(value))) {
+		return { error: "review content contains a reserved pi-pr-review marker" };
+	}
 	const pr = value.pr;
 	if (!isObject(pr) || !Number.isInteger(pr.number) || Number(pr.number) <= 0 || typeof pr.title !== "string") {
 		return { error: "pr.number and pr.title are required" };
@@ -658,21 +663,8 @@ export function parsePublishableReview(text: string): PublishableReviewParseResu
 		if (!isConfidence(finding.confidence_score)) {
 			return { error: `finding ${index + 1} has invalid confidence_score` };
 		}
-		if (finding.code_location !== null) {
-			const location = finding.code_location;
-			if (!isObject(location) || typeof location.commentable !== "boolean") {
-				return { error: `finding ${index + 1} has invalid code_location` };
-			}
-			if (location.absolute_file_path !== null && typeof location.absolute_file_path !== "string") {
-				return { error: `finding ${index + 1} has invalid absolute_file_path` };
-			}
-			if (location.side !== null && location.side !== "LEFT" && location.side !== "RIGHT") {
-				return { error: `finding ${index + 1} has invalid side` };
-			}
-			if (!isObject(location.line_range) || !Number.isInteger(location.line_range.start) || !Number.isInteger(location.line_range.end)) {
-				return { error: `finding ${index + 1} has invalid line_range` };
-			}
-		}
+		const locationError = validateFindingLocation(finding as ReviewFindingLike, index);
+		if (locationError) return { error: locationError };
 	}
 	if (!isObject(value.notes)) return { error: "notes must be an object" };
 	for (const key of ["correctness", "security", "performance"] as const) {
@@ -694,6 +686,88 @@ export function shouldPublishReview(review: ReviewLike): boolean {
 	return review.disposition === "reviewed";
 }
 
+interface DiffHunk {
+	left: Set<number>;
+	right: Set<number>;
+}
+
+function parsePatchHunks(patch: string): DiffHunk[] {
+	const hunks: DiffHunk[] = [];
+	let current: DiffHunk | undefined;
+	let left = 0;
+	let right = 0;
+	for (const line of patch.split("\n")) {
+		const header = line.match(/^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+		if (header) {
+			left = Number(header[1]);
+			right = Number(header[2]);
+			current = { left: new Set<number>(), right: new Set<number>() };
+			hunks.push(current);
+			continue;
+		}
+		if (!current || line.startsWith("\\")) continue;
+		if (line.startsWith("+")) {
+			current.right.add(right++);
+		} else if (line.startsWith("-")) {
+			current.left.add(left++);
+		} else if (line.startsWith(" ")) {
+			current.left.add(left++);
+			current.right.add(right++);
+		}
+	}
+	return hunks;
+}
+
+export interface ChangedFileLike {
+	filename?: string;
+	patch?: string;
+}
+
+function safeRelativePath(value: string): boolean {
+	if (!value || value.startsWith("/") || value.includes("\\") || /[\0-\x1f\x7f]/.test(value)) return false;
+	const segments = value.split("/");
+	return segments.every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}
+
+function validateFindingLocation(finding: ReviewFindingLike, index: number): string | undefined {
+	const location = finding.code_location;
+	const label = `finding ${index + 1}`;
+	if (location === null) return undefined;
+	if (!isObject(location) || typeof location.commentable !== "boolean") {
+		return `${label} has invalid code_location`;
+	}
+	const path = location.absolute_file_path;
+	if (path !== null && typeof path !== "string") return `${label} has invalid absolute_file_path`;
+	const side = location.side;
+	if (side !== null && side !== "LEFT" && side !== "RIGHT") return `${label} has invalid side`;
+	const range = location.line_range;
+	if (!isObject(range) || !Number.isInteger(range.start) || !Number.isInteger(range.end)) {
+		return `${label} has invalid line_range`;
+	}
+	const start = Number(range.start);
+	const end = Number(range.end);
+	if (path === null) {
+		if (location.commentable) return `${label}: commentable location is missing a repo-relative path`;
+		if (side !== null || start !== 0 || end !== 0) {
+			return `${label}: location without a path must use null side and a 0:0 range`;
+		}
+		return undefined;
+	}
+	if (!safeRelativePath(path)) return `${label}: invalid repo-relative path`;
+	if (side !== "LEFT" && side !== "RIGHT") return `${label}: side must be LEFT or RIGHT`;
+	if (start <= 0 || end < start) return `${label}: invalid line range`;
+	return undefined;
+}
+
+function isInlineSeverity(finding: ReviewFindingLike): boolean {
+	const severity = String(finding.severity ?? "").toUpperCase();
+	return ["P0", "P1", "P2", "P3"].includes(severity);
+}
+
+function publishCommentAnchor(comment: PublishComment): string {
+	return `${comment.path}:${comment.side}:${comment.start_line ?? comment.line}:${comment.line}`;
+}
+
 function cell(value: string): string {
 	return value.replace(/\|/g, "\\|").replace(/\r?\n/g, " ").trim();
 }
@@ -707,10 +781,6 @@ function findingLocation(finding: ReviewFindingLike): string {
 	return `${location.absolute_file_path}:${start}${end !== start ? `-${end}` : ""} ${(location.side ?? "RIGHT").toUpperCase()}`;
 }
 
-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;
@@ -786,140 +856,141 @@ export function buildReviewSummary(review: ReviewLike, inlineComments: PublishCo
 	return lines.join("\n").trim();
 }
 
-interface DiffHunk {
-	left: Set<number>;
-	right: Set<number>;
-}
-
-function parsePatchHunks(patch: string): DiffHunk[] {
-	const hunks: DiffHunk[] = [];
-	let current: DiffHunk | undefined;
-	let left = 0;
-	let right = 0;
-	for (const line of patch.split("\n")) {
-		const header = line.match(/^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
-		if (header) {
-			left = Number(header[1]);
-			right = Number(header[2]);
-			current = { left: new Set<number>(), right: new Set<number>() };
-			hunks.push(current);
-			continue;
-		}
-		if (!current || line.startsWith("\\")) continue;
-		if (line.startsWith("+")) {
-			current.right.add(right++);
-		} else if (line.startsWith("-")) {
-			current.left.add(left++);
-		} else if (line.startsWith(" ")) {
-			current.left.add(left++);
-			current.right.add(right++);
-		}
-	}
-	return hunks;
-}
-
-export interface ChangedFileLike {
-	filename?: string;
-	patch?: string;
-}
-
-function safeRelativePath(value: string): boolean {
-	if (!value || value.startsWith("/") || value.includes("\\") || value.includes("\0")) return false;
-	const segments = value.split("/");
-	return segments.every((segment) => segment !== "" && segment !== "." && segment !== "..");
-}
-
-function isInlineSeverity(finding: ReviewFindingLike): boolean {
-	const severity = String(finding.severity ?? "").toUpperCase();
-	return ["P0", "P1", "P2", "P3"].includes(severity);
-}
-
-export interface CommentValidationResult {
+interface InlineSelection {
 	comments: PublishComment[];
+	diagnostics: string[];
 	errors: string[];
-	warnings?: string[];
 }
 
-export function validateInlineComments(
+function buildPublishComment(
+	path: string,
+	body: string,
+	side: "LEFT" | "RIGHT",
+	start: number,
+	end: number,
+): PublishComment {
+	return {
+		path,
+		body,
+		line: end,
+		side,
+		...(start < end ? { start_line: start, start_side: side } : {}),
+	};
+}
+
+function selectInlineComments(
 	review: ReviewLike,
-	changedFiles: ChangedFileLike[],
-): CommentValidationResult {
-	const errors: string[] = [];
-	const warnings: string[] = [];
-	const comments: PublishComment[] = [];
+	changedFiles: readonly ChangedFileLike[],
+): InlineSelection {
 	const files = new Map<string, ChangedFileLike>();
 	for (const file of changedFiles) {
-		if (file.filename) files.set(file.filename, file);
+		if (!file || typeof file.filename !== "string") continue;
+		const existing = files.get(file.filename);
+		if (!existing || (!existing.patch && file.patch)) files.set(file.filename, file);
 	}
+	const comments: PublishComment[] = [];
+	const diagnostics: string[] = [];
+	const errors: string[] = [];
 	const anchors = new Set<string>();
+	const hunkCache = new Map<string, DiffHunk[]>();
 	for (const [index, finding] of (review.findings ?? []).entries()) {
-		const location = finding.code_location;
-		if (!location?.commentable || !isInlineSeverity(finding)) continue;
-		const path = String(location.absolute_file_path ?? "");
-		const side = String(location.side ?? "").toUpperCase();
-		const start = location.line_range?.start;
-		const end = location.line_range?.end;
-		const label = `finding ${index + 1}`;
-		if (!safeRelativePath(path)) {
-			errors.push(`${label}: invalid repo-relative path`);
+		const locationError = finding.code_location === undefined
+			? undefined
+			: validateFindingLocation(finding, index);
+		if (locationError) {
+			errors.push(locationError);
 			continue;
 		}
-		if (side !== "LEFT" && side !== "RIGHT") {
-			errors.push(`${label}: side must be LEFT or RIGHT`);
+		if (!finding.code_location?.commentable || !isInlineSeverity(finding)) continue;
+		const location = finding.code_location;
+		const label = `finding ${index + 1}`;
+		const path = location.absolute_file_path as string;
+		const side = location.side as "LEFT" | "RIGHT";
+		const start = Number(location.line_range?.start);
+		const end = Number(location.line_range?.end);
+		const body = [
+			finding.title?.trim() ? `**${finding.title.trim()}**` : "",
+			finding.body?.trim(),
+		].filter(Boolean).join("\n\n");
+		if (!body || Buffer.byteLength(body, "utf8") > MAX_BODY_BYTES) {
+			errors.push(`${label}: comment body is empty or too large`);
 			continue;
 		}
-		if (!Number.isInteger(start) || !Number.isInteger(end) || Number(start) <= 0 || Number(end) < Number(start)) {
-			errors.push(`${label}: invalid line range`);
+		if (containsReservedReviewMarker(body)) {
+			errors.push(`${label}: comment body contains a reserved pi-pr-review marker`);
 			continue;
 		}
+		const comment = buildPublishComment(path, body, side, start, end);
 		const file = files.get(path);
 		if (!file) {
-			errors.push(`${label}: path is not a changed file`);
+			diagnostics.push(`${label}: path is not a changed file; kept in the review summary`);
 			continue;
 		}
-		if (!file.patch) {
-			// GitHub legitimately omits patch metadata for some large, binary, or transiently unavailable diffs.
-			// Keep the complete finding in the review summary rather than sending an unvalidated inline anchor.
-			warnings.push(`${label}: diff patch is unavailable; kept in the review summary`);
+		if (typeof file.patch !== "string" || file.patch.length === 0) {
+			diagnostics.push(`${label}: diff patch is unavailable; kept in the review summary`);
 			continue;
 		}
+		let hunks = hunkCache.get(path);
+		if (!hunks) {
+			hunks = parsePatchHunks(file.patch);
+			hunkCache.set(path, hunks);
+		}
 		const sideKey = side === "LEFT" ? "left" : "right";
-		const hunk = parsePatchHunks(file.patch).find(
-			(candidate) => candidate[sideKey].has(Number(start)) && candidate[sideKey].has(Number(end)),
-		);
-		if (!hunk) {
-			errors.push(`${label}: line range is not inside one diff hunk on ${side}`);
+		if (!hunks.some((hunk) => hunk[sideKey].has(start) && hunk[sideKey].has(end))) {
+			diagnostics.push(
+				`${label}: line range is not inside one diff hunk on ${side}; kept in the review summary`,
+			);
 			continue;
 		}
-		const anchor = `${path}:${side}:${start}:${end}`;
-		const body = [`**${String(finding.title ?? "Review finding").trim()}**`, finding.body?.trim()]
-			.filter(Boolean)
-			.join("\n\n");
-		if (!body || Buffer.byteLength(body, "utf8") > MAX_BODY_BYTES) {
-			errors.push(`${label}: comment body is empty or too large`);
+		const anchor = publishCommentAnchor(comment);
+		if (anchors.has(anchor)) {
+			diagnostics.push(`${label}: duplicate inline anchor; kept in the review summary`);
 			continue;
 		}
-		if (containsReservedReviewMarker(body)) {
-			errors.push(`${label}: comment body contains a reserved pi-pr-review marker`);
+		anchors.add(anchor);
+		if (comments.length >= MAX_INLINE_COMMENTS) {
+			diagnostics.push(
+				`${label}: inline comment limit of ${MAX_INLINE_COMMENTS} reached; kept in the review summary`,
+			);
 			continue;
 		}
-		// GitHub receives one comment per anchor; later findings remain in the top-level summary.
-		if (anchors.has(anchor)) continue;
-		anchors.add(anchor);
-		comments.push({
-			path,
-			body,
-			line: Number(end),
-			side,
-			...(Number(start) < Number(end) ? { start_line: Number(start), start_side: side } : {}),
-		});
+		comments.push(comment);
 	}
-	if (comments.length > MAX_INLINE_COMMENTS) {
-		errors.push(`too many inline comments (${comments.length}; max ${MAX_INLINE_COMMENTS})`);
+	return { comments, diagnostics, errors };
+}
+
+export interface CommentValidationResult {
+	comments: PublishComment[];
+	errors: string[];
+	warnings?: string[];
+}
+
+function canonicalReviewSnapshot(review: ReviewLike): PublishableReviewParseResult {
+	let serialized: string | undefined;
+	try {
+		serialized = JSON.stringify(review);
+	} catch {
+		return { error: "review could not be serialized for publication" };
+	}
+	if (typeof serialized !== "string") {
+		return { error: "review could not be serialized for publication" };
 	}
-	return { comments, errors, warnings };
+	return parsePublishableReview(serialized);
+}
+
+export function validateInlineComments(
+	review: ReviewLike,
+	changedFiles: readonly ChangedFileLike[],
+): CommentValidationResult {
+	const selected = selectInlineComments(review, changedFiles);
+	return {
+		comments: selected.comments,
+		errors: selected.errors,
+		warnings: selected.diagnostics,
+	};
 }
 
+/** Compatibility helper for callers that fold would-be inline findings into a body-only review. */
 export function collectFoldedComments(review: ReviewLike): CommentValidationResult {
 	const comments: PublishComment[] = [];
 	const errors: string[] = [];
@@ -950,17 +1021,12 @@ export function collectFoldedComments(review: ReviewLike): CommentValidationResu
 			errors.push(`${label}: folded comment body contains a reserved pi-pr-review marker`);
 			continue;
 		}
-		comments.push({
-			path,
-			body,
-			line: Number(end),
-			side,
-			...(Number(start) < Number(end) ? { start_line: Number(start), start_side: side } : {}),
-		});
+		comments.push(buildPublishComment(path, body, side, Number(start), Number(end)));
 	}
 	return { comments, errors, warnings: [] };
 }
 
+/** Compatibility formatter for body-only reviews assembled by earlier consumers. */
 export function foldInlineComments(summary: string, comments: PublishComment[]): string {
 	if (comments.length === 0) return summary;
 	const lines = [summary, "", "### Inline findings (folded for a non-open PR)", ""];
@@ -982,6 +1048,59 @@ function validateReviewBody(body: string): string | undefined {
 	return undefined;
 }
 
+function hasInlineCandidates(review: ReviewLike): boolean {
+	return (review.findings ?? []).some(
+		(finding) => finding.code_location?.commentable === true && isInlineSeverity(finding),
+	);
+}
+
+function buildLosslessReviewPayload(input: {
+	review: ReviewLike;
+	commitId: string;
+	markerHeadSha: string;
+	allowInlineComments: boolean;
+	changedFiles?: readonly ChangedFileLike[];
+	bodyPreamble?: string;
+	diagnostics?: readonly string[];
+}): { payload?: PullReviewPayload; diagnostics: string[]; errors: string[] } {
+	const diagnostics = [...(input.diagnostics ?? [])];
+	if (!/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/i.test(input.commitId)) {
+		return { diagnostics, errors: ["publication commit ID must be a full hexadecimal commit SHA"] };
+	}
+	if (!/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/i.test(input.markerHeadSha)) {
+		return { diagnostics, errors: ["publication marker head must be a full hexadecimal commit SHA"] };
+	}
+	const markerHeadSha = input.markerHeadSha.toLowerCase();
+	if (input.review.pr?.head_sha?.toLowerCase() !== markerHeadSha) {
+		return { diagnostics, errors: ["publication marker head does not match the validated review head"] };
+	}
+	if (input.bodyPreamble && containsReservedReviewMarker(input.bodyPreamble)) {
+		return { diagnostics, errors: ["publication preamble contains a reserved pi-pr-review marker"] };
+	}
+	const selected = input.allowInlineComments
+		? selectInlineComments(input.review, input.changedFiles ?? [])
+		: { comments: [], diagnostics: [], errors: [] };
+	diagnostics.push(...selected.diagnostics);
+	if (selected.errors.length > 0) return { diagnostics, errors: selected.errors };
+
+	let content = buildReviewSummary(input.review, selected.comments);
+	if (diagnostics.length > 0) {
+		content = `${content}\n\n### Publication diagnostics\n\n${diagnostics.map((item) => `- ${item}`).join("\n")}`;
+	}
+	if (input.bodyPreamble?.trim()) content = `${input.bodyPreamble.trim()}\n\n${content}`;
+	const bodyError = validateReviewBody(content);
+	if (bodyError) return { diagnostics, errors: [bodyError] };
+	const body = `${content}\n\n${canonicalReviewMarker(markerHeadSha)}`;
+	if (Buffer.byteLength(body, "utf8") > MAX_BODY_BYTES) {
+		return { diagnostics, errors: ["final review body exceeds 65536 UTF-8 bytes"] };
+	}
+	const payload = buildPullReviewPayload(input.commitId.toLowerCase(), body, selected.comments);
+	if (Buffer.byteLength(JSON.stringify(payload), "utf8") > MAX_PAYLOAD_BYTES) {
+		return { diagnostics, errors: ["review payload is too large"] };
+	}
+	return { payload, diagnostics, errors: [] };
+}
+
 interface GhResult {
 	stdout: string;
 	stderr: string;
@@ -1046,15 +1165,49 @@ export async function resolveRepositoryBinding(cwd: string): Promise<RepositoryB
 	return binding;
 }
 
-function flattenPages<T>(value: unknown): T[] {
-	if (!Array.isArray(value)) return [];
-	if (value.every(Array.isArray)) return value.flat() as T[];
-	return value as T[];
+function normalizeChangedFilePages(value: unknown): ChangedFileLike[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	if (value.some(Array.isArray) && !value.every(Array.isArray)) return undefined;
+	const entries: unknown[] = value.every(Array.isArray) ? value.flat() : value;
+	const files: ChangedFileLike[] = [];
+	for (const entry of entries) {
+		if (!isObject(entry) || typeof entry.filename !== "string") return undefined;
+		if (entry.patch !== undefined && entry.patch !== null && typeof entry.patch !== "string") {
+			return undefined;
+		}
+		files.push({
+			filename: entry.filename,
+			...(typeof entry.patch === "string" ? { patch: entry.patch } : {}),
+		});
+	}
+	return files;
 }
 
 interface AuthoredBody {
-	body?: string | null;
-	user?: { login?: string | null } | null;
+	body: string | null;
+	user: { login: string | null } | null;
+}
+
+function normalizeAuthoredBodyPages(value: unknown): AuthoredBody[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	if (value.some(Array.isArray) && !value.every(Array.isArray)) return undefined;
+	const entries: unknown[] = value.every(Array.isArray) ? value.flat() : value;
+	const authoredBodies: AuthoredBody[] = [];
+	for (const entry of entries) {
+		if (!isObject(entry) || (entry.body !== null && typeof entry.body !== "string")) {
+			return undefined;
+		}
+		const user = entry.user;
+		if (user === null) {
+			authoredBodies.push({ body: entry.body, user: null });
+			continue;
+		}
+		if (!isObject(user)) return undefined;
+		const login = user.login;
+		if (login !== null && typeof login !== "string") return undefined;
+		authoredBodies.push({ body: entry.body, user: { login } });
+	}
+	return authoredBodies;
 }
 
 export function bodyHasHeadMarker(body: string | null | undefined, normalizedHeadSha: string): boolean {
@@ -1078,11 +1231,15 @@ async function hasExistingMarker(
 		githubApiArgs(hostname, "--paginate", "--slurp", `repos/${repository}/pulls/${prNumber}/reviews?per_page=100`),
 		cwd,
 	);
+	const reviews = normalizeAuthoredBodyPages(reviewPages);
+	if (!reviews) throw new Error("invalid paginated pull review response");
 	const commentPages = await ghJson<unknown>(
 		githubApiArgs(hostname, "--paginate", "--slurp", `repos/${repository}/issues/${prNumber}/comments?per_page=100`),
 		cwd,
 	);
-	return [...flattenPages<AuthoredBody>(reviewPages), ...flattenPages<AuthoredBody>(commentPages)].some(
+	const comments = normalizeAuthoredBodyPages(commentPages);
+	if (!comments) throw new Error("invalid paginated issue comment response");
+	return [...reviews, ...comments].some(
 		(item) =>
 			item.user?.login?.toLowerCase() === identity.toLowerCase() &&
 			bodyHasHeadMarker(item.body, normalizedHeadSha),
@@ -1204,6 +1361,23 @@ export async function publishPullReview(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();
+	const snapshot = canonicalReviewSnapshot(review);
+	const validatedReview = snapshot.review;
+	if (!validatedReview) {
+		return {
+			status: "failed",
+			message: `publication planning failed: ${snapshot.error ?? "review is not publishable"}`,
+		};
+	}
+	if (!shouldPublishReview(validatedReview)) {
+		return { status: "failed", message: "only completed reviewed dispositions can be published" };
+	}
+	if (validatedReview.pr?.number !== prNumber) {
+		return { status: "failed", message: "validated review PR number does not match the publication target" };
+	}
+	if (validatedReview.pr?.head_sha?.toLowerCase() !== normalizedHeadSha) {
+		return { status: "failed", message: "validated review head does not match the publication target" };
+	}
 
 	let repository: string;
 	let hostname: string;
@@ -1224,7 +1398,6 @@ export async function publishPullReview(input: {
 	}
 	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;
@@ -1247,57 +1420,38 @@ 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";
-		let comments: PublishComment[] = [];
-		let inlineWarningCount = 0;
-		if (!isOpen) {
-			const candidates = collectFoldedComments(review);
-			if (candidates.errors.length > 0) {
-				return { status: "failed", message: `inline candidate validation failed: ${candidates.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;
-				inlineWarningCount = validated.warnings?.length ?? 0;
+		let allowInlineComments = isOpen && headPlan.allowInlineComments;
+		let changedFiles: readonly ChangedFileLike[] = [];
+		let changedFileLookupFailed = false;
+		if (allowInlineComments && hasInlineCandidates(validatedReview)) {
+			try {
+				const filePages = await ghJson<unknown>(
+					githubApiArgs(hostname, "--paginate", "--slurp", `repos/${repository}/pulls/${prNumber}/files?per_page=100`),
+					cwd,
+				);
+				const normalizedFiles = normalizeChangedFilePages(filePages);
+				if (!normalizedFiles) throw new Error("invalid changed-file JSON response");
+				changedFiles = normalizedFiles;
+			} catch {
+				allowInlineComments = false;
+				changedFileLookupFailed = true;
 			}
 		}
-
-		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(
-			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" };
+		const built = buildLosslessReviewPayload({
+			review: validatedReview,
+			commitId: headPlan.commitId,
+			markerHeadSha: normalizedHeadSha,
+			allowInlineComments,
+			changedFiles,
+			...(changedFileLookupFailed ? { diagnostics: [CHANGED_FILE_LOOKUP_DIAGNOSTIC] } : {}),
+			...(headPlan.stale
+				? { bodyPreamble: buildStaleReviewNotice(headPlan.reviewedHeadSha, headPlan.currentHeadSha) }
+				: {}),
+		});
+		if (!built.payload) {
+			return { status: "failed", message: `publication planning failed: ${built.errors.join("; ")}` };
 		}
+		const payload = built.payload;
 
 		try {
 			const refreshed = await ghJson<PullState>(
@@ -1322,10 +1476,12 @@ export async function publishPullReview(input: {
 			return { status: "failed", message: `final head check failed: ${String(error)}` };
 		}
 
-		const inlineWarning = inlineWarningCount > 0
-			? `; ${inlineWarningCount} inline finding${inlineWarningCount === 1 ? "" : "s"} kept in the summary because GitHub omitted diff patch metadata`
-			: "";
-		const degraded = !isOpen || headPlan.stale || inlineWarningCount > 0;
+		const inlineWarning = built.diagnostics.length === 0
+			? ""
+			: changedFileLookupFailed
+				? `; ${CHANGED_FILE_LOOKUP_DIAGNOSTIC}`
+				: `; ${built.diagnostics.length} inline finding${built.diagnostics.length === 1 ? "" : "s"} kept in the summary: ${built.diagnostics.join("; ")}`;
+		const degraded = !isOpen || headPlan.stale || built.diagnostics.length > 0;
 		const post = await runGh(
 			githubApiArgs(hostname, "--method", "POST", `repos/${repository}/pulls/${prNumber}/reviews`, "--input", "-"),
 			cwd,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-pr-review",
-  "version": "1.10.5",
+  "version": "1.10.6",
   "description": "Parallel AI code review for GitHub pull requests in the Pi coding agent, with model-agnostic tiered subagents, structured findings, optional verification, and safe COMMENT-only publishing.",
   "keywords": [
     "pi-package",

package/prompts/pr-review.md

@@ -194,9 +194,11 @@ 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, 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. If GitHub omits patch metadata needed to validate an anchor, that finding remains in the top-level body instead of blocking publication. If multiple findings share one diff anchor, the first is attached inline and later findings remain in the top-level body instead of failing publication or dropping content. 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 attempted 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.
+After exact-contract validation, the extension caches one validated completed review per repository and PR in the current Pi session. `autoPostReviews` and `--comment` publish that cached review after completion; `--no-comment` suppresses publication for the run. `/pr-review-publish` and a matching direct request publish only the cache and never start or rerun review agents. On a later turn, the extension intercepts that direct input before an agent turn and permits stale publication without asking the orchestrator to recreate the review.
 
-The extension caches the latest valid completed review per repository and PR before publication preflight in the current Pi session. The session-backed cache survives extension reloads and session resumes but is bound to the originating session instance and repository. On a later turn, the extension intercepts that direct input before an agent turn, publishes only extension-cached content, permits stale publication, and cannot rerun review agents. Stale publication is also enabled by default through the invocation-captured `allowStalePublish` setting. Every stale review is body-only, displays a warning with the reviewed and preflight-observed commit hashes, and omits potentially invalid inline anchors. If the captured setting disabled stale publication, the user can still run `/pr-review-publish <PR-NUM> --allow-stale`. Never rerun the review merely to change posting intent, and never attempt a direct GitHub write yourself.
+Every authorized publish path builds one `COMMENT` payload and sends at most one GitHub review `POST`. The event is always `COMMENT`, never `APPROVE` or `REQUEST_CHANGES`. For a current, open PR, the first 50 eligible P0–P3 findings with valid, unique diff anchors are inline. All other findings that pass content validation stay in the top-level review body, including nits, off-diff findings, unavailable diff metadata, duplicate anchors, and overflow. Stale reviews and authorized closed or merged reviews are body-only. A failed write never triggers a fallback POST.
+
+Every path retains the same safety gates: captured posting authority, exact repository/PR/review binding, safe locations, no reserved review markers, bounded bodies and payloads, current-head and stale policy, draft and lifecycle checks, non-open authorization, same-head duplicate detection, and a final head check. Unknown lifecycle states and unconfirmed non-open writes fail closed. The session-backed cache survives extension reloads and session resumes but remains bound to the originating session instance and repository. If the captured stale setting disabled publication, the user may explicitly run `/pr-review-publish <PR-NUM> --allow-stale`. Never rerun the review merely to change posting intent, and never attempt a direct GitHub write yourself.
 
 ---