pi-pr-review 1.12.0 → 1.12.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.12.2](https://github.com/10ego/pi-pr-review/compare/v1.12.1...v1.12.2) (2026-08-19)
+
+
+### Bug Fixes
+
+* **review:** defer synthesis cap while review work runs ([#65](https://github.com/10ego/pi-pr-review/issues/65)) ([2bcdd93](https://github.com/10ego/pi-pr-review/commit/2bcdd93678755fc9c6b209c2357487a3912d026f))
+
+## [1.12.1](https://github.com/10ego/pi-pr-review/compare/v1.12.0...v1.12.1) (2026-08-19)
+
+
+### Documentation
+
+* **review:** align publication guidance ([#63](https://github.com/10ego/pi-pr-review/issues/63)) ([fe019d3](https://github.com/10ego/pi-pr-review/commit/fe019d3729635d1ed7ba7fd1e72bc5983db87a01))
+
 ## [1.12.0](https://github.com/10ego/pi-pr-review/compare/v1.11.8...v1.12.0) (2026-08-19)
 
 

package/README.md

@@ -176,9 +176,9 @@ Every invocation has a host-owned monotonic 15-minute hard cap, including the tw
 
 A timed-out or retryable quota/rate-limit/capacity lane may start at most one configured fallback attempt. It starts only when at least `minimumFallbackMs` plus cleanup reserve remains; the host never changes the configured model, thinking level, or tool policy to save time. If a tier is unset, its existing nearest-configured-tier/Pi-default behavior is unchanged.
 
-On an attempt deadline the host records timeout separately from user cancellation, sends TERM to the original child, waits only `terminationGraceMs`, then sends KILL if no exit was observed and stops draining after the cleanup reserve. Partial assistant text and telemetry survive this lifecycle. Batch/total expiry stops queued work and waiting lanes; completed and partial artifacts proceed to Markdown synthesis or deterministic lane assembly, identify every incomplete lens/shard, and remain eligible for the safe body-only `COMMENT` publication path. A timed-out lane is never reported as `NO FINDINGS` or full coverage.
+On an attempt deadline the host records timeout separately from user cancellation, sends TERM to the original child, waits only `terminationGraceMs`, then sends KILL if no exit was observed and stops draining after the cleanup reserve. Partial assistant text and telemetry survive this lifecycle. The synthesis cap arms only once review work goes quiet: any turn that starts or any review tool that runs again while the cap is armed defers it, and it re-arms from the next turn end, so early review-tool turns (for example verification discovery) cannot starve later heavy lanes. Batch/total expiry stops queued work and waiting lanes; completed and partial artifacts proceed to Markdown synthesis or deterministic lane assembly, identify every incomplete lens/shard, and remain eligible for the safe body-only `COMMENT` publication path. A timed-out lane is never reported as `NO FINDINGS` or full coverage, and a lane ended by the host total or synthesis deadline is disclosed with that kind (`deadline_expired`) instead of being mistaken for its own attempt deadline expiring.
 
-Initial operating targets are ordinary-review p50 ≤ 6 minutes and p95 ≤ 12 minutes, and large-review p50 ≤ 10 minutes and p95 ≤ 14 minutes, with the 15-minute hard cap authoritative. Invocation telemetry starts before GitHub preflight and records configured deadline source/caps, termination grace, cleanup reserve, and active wall time; batch details record first event/output timing, lifecycle counts, configured and effective batch-truncated attempt deadlines, fallback starts/budget rejections, and termination grace/escalation data. These are initial production targets, not a promise that every provider completes before its host deadline.
+Initial operating targets are ordinary-review p50 ≤ 6 minutes and p95 ≤ 12 minutes, and large-review p50 ≤ 10 minutes and p95 ≤ 14 minutes, with the 15-minute hard cap authoritative. Invocation telemetry starts before GitHub preflight and records configured deadline source/caps, termination grace, cleanup reserve, and active wall time; batch details record first event/output timing, lifecycle counts, configured and effective batch-truncated attempt deadlines, fallback starts/budget rejections, external total/synthesis deadline expiries per lane, and termination grace/escalation data. These are initial production targets, not a promise that every provider completes before its host deadline.
 
 Ordinary reviewer output is reconstructed from every text part of the authoritative final assistant message in order. A zero process exit is not enough to mark a lane complete: completion also requires a terminal `stop` and the expected lane sections (or an explicitly emitted `NO FINDINGS.` where that response is allowed). Empty success is never synthesized into `NO FINDINGS.`; length-limited, malformed, timed-out, and failed attempts retain their raw text with an explicit lifecycle. Batch details include raw text, attempt artifacts, lifecycle counts and elapsed totals, while the displayed batch remains in deterministic input order.
 
@@ -212,7 +212,7 @@ Review semantics are Markdown-first. A deterministic tolerant parser normalizes
 
 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.
 
-Every authorized publish path builds one GitHub review payload and sends at most one review `POST`; it never submits `REQUEST_CHANGES` or retries a rejected write with a fallback POST. Fully parsed Markdown with one complete retained artifact for every host-registered dispatch and the exact visible `All requested lanes completed.` disclosure may emit a gated `APPROVE` through the same host binding, priority, lifecycle, self-author, and stale checks as strict JSON. Verdict fields outside the document preamble, hidden in CommonMark code/HTML blocks, or inside lazy container continuations, severity-tagged headings outside `Findings`, partial or contradictory lane disclosures, malformed or unsafe output, and lane-fallback artifacts remain body-only `COMMENT` reviews. Cache restore reclassifies persisted lane output and requires the exact host-recorded artifact key set, with every complete artifact matching the frozen invocation generation, tier, and minor-hygiene contract, and re-synthesizes the retained raw text under that frozen binding before retaining approval eligibility. For a current, open PR, the first 50 eligible P0–P3 findings with valid, unique diff anchors are inline. The concise top-level body starts with the verdict, points readers to inline findings, and places nits, off-diff findings, unavailable diff metadata, duplicate anchors, and overflow under `Other Notes`; overview, verification, strengths, and transport diagnostics stay out of the public summary. The complete original Markdown remains retained internally; if the concise body plus its canonical marker exceeds GitHub's limit, the host uses its sanitized, size-bounded Markdown projection instead of dropping the review. Stale or authorized non-open reviews are body-only. A stale approval additionally requires `allowStaleApprovals: true`.
+Every authorized publish path builds one GitHub review payload and sends at most one review `POST`; it never submits `REQUEST_CHANGES` or retries a rejected write with a fallback POST. Fully parsed Markdown with one complete retained artifact for every host-registered dispatch and a standalone visible `All requested lanes completed.` disclosure (matched case-insensitively, with an optional final period) may emit a gated `APPROVE` through the same host binding, priority, lifecycle, self-author, and stale checks as strict JSON. Verdict fields outside the document preamble, hidden in CommonMark code/HTML blocks, or inside lazy container continuations, severity-tagged headings outside `Findings`, partial or contradictory lane disclosures, malformed or unsafe output, and lane-fallback artifacts remain body-only `COMMENT` reviews. Cache restore reclassifies persisted lane output and requires the exact host-recorded artifact key set, with every complete artifact matching the frozen invocation generation, tier, and minor-hygiene contract, and re-synthesizes the retained raw text under that frozen binding before retaining approval eligibility. For a current, open PR, the first 50 eligible P0–P3 findings with valid, unique diff anchors are inline. The concise top-level body starts with the verdict, points readers to inline findings, and places nits, off-diff findings, unavailable diff metadata, duplicate anchors, and overflow under `Other Notes`; overview, verification, strengths, and transport diagnostics stay out of the public summary. The complete original Markdown remains retained internally; if the concise body plus its canonical marker exceeds GitHub's limit, the host uses its sanitized, size-bounded Markdown projection instead of dropping the review. Stale or authorized non-open reviews are body-only. A stale approval additionally requires `allowStaleApprovals: true`.
 
 All publication paths apply host-enforced safety gates: captured posting authority, repository and requested-PR binding, reviewed/current-head and stale policy, bounded bodies and payloads, draft and lifecycle checks, non-open authorization, authenticated-identity same-head duplicate detection, and a final head check. Fully or partially parsed review paths additionally enforce safe inline locations. Raw and lane-assembled fallbacks are body-only and `COMMENT`-only; assistant text cannot select event, commit, repository, hostname, API path, or inline anchors. Unknown or invalid host states fail closed before a write.
 

package/extensions/pr-review-subagent.ts

@@ -60,8 +60,10 @@ import { loadReviewContext, shardUnifiedDiff } from "../lib/pr-review-context.ts
 import {
 	combineAbortSignals,
 	ReviewLoopCoordinator,
+	reviewDeadlineKindOf,
 	reviewLoopDeniedResult,
 	type ReviewArtifactPublisher,
+	type ReviewDeadlineKind,
 	type ReviewFocusPublisher,
 } from "../lib/pr-review-loop.ts";
 import { runSelfReviewRpcSubprocess } from "../lib/pr-self-review-rpc.ts";
@@ -138,7 +140,7 @@ interface PrReviewConfig {
 	thinkingLevels: Partial<Record<Tier, ThinkingLevel>>;
 	/** Optional tier-level policy used when a tool call does not override it. */
 	toolPolicies: Partial<Record<Tier, ToolPolicy>>;
-	/** Automatically publish final review JSON as a GitHub COMMENT review. Disabled by default. */
+	/** Automatically publish the completed review as a host-gated GitHub COMMENT or APPROVE review. Disabled by default. */
 	autoPostReviews: boolean;
 	/** Permit stale publication as body-only with reviewed/current SHAs disclosed. Enabled by default. */
 	allowStalePublish: boolean;
@@ -489,6 +491,8 @@ interface RunResult {
 	errorMessage?: string;
 	model?: string;
 	timedOut?: boolean;
+	/** Which host invocation deadline (not the lane's own attempt deadline) ended this run. */
+	deadlineExpired?: ReviewDeadlineKind;
 	terminationGraceMs?: number;
 	forcedTermination?: boolean;
 	firstEventMs?: number;
@@ -553,8 +557,12 @@ export function runReviewSubprocess(
 			}
 		};
 		const onAbort = () => {
-			const reason = signal?.reason;
-			terminate(reason instanceof Error && /review (?:total|synthesis) deadline expired/i.test(reason.message) ? "timeout" : "abort");
+			// A host total/synthesis deadline is a timeout, not user cancellation.
+			// The kind is recorded only when it actually wins termination, so a
+			// coincidental host abort during an attempt-timeout drain cannot
+			// mislabel the lane.
+			const kind = reviewDeadlineKindOf(signal?.reason);
+			terminate(kind ? "timeout" : "abort", kind);
 		};
 		const cleanupAbort = () => {
 			if (killTimer) clearTimeout(killTimer);
@@ -665,7 +673,9 @@ export function runReviewSubprocess(
 			if (termination === "timeout") {
 				result.timedOut = true;
 				result.stopReason = "timeout";
-				result.errorMessage ??= "Review attempt exceeded its host deadline.";
+				result.errorMessage ??= result.deadlineExpired
+					? `Review ${result.deadlineExpired} deadline expired while this lane was still running.`
+					: "Review attempt exceeded its host deadline.";
 			} else if (termination === "abort") {
 				result.stopReason = "aborted";
 			} else if (error) result.errorMessage = error.message;
@@ -715,9 +725,10 @@ export function runReviewSubprocess(
 			groupKillDeadline = now() + (deadline?.terminationGraceMs ?? 5_000);
 			checkGroupCleanupGrace();
 		};
-		const terminate = (reason: "abort" | "timeout") => {
+		const terminate = (reason: "abort" | "timeout", deadlineKind?: ReviewDeadlineKind) => {
 			if (settled || termination) return;
 			termination = reason;
+			if (deadlineKind) result.deadlineExpired = deadlineKind;
 			terminationStartedAt = now();
 			pendingClose ??= { code: 1, processSignal: undefined };
 			if (processGroupId !== undefined) {
@@ -1052,6 +1063,7 @@ function retainPassArtifact(pass: SubagentPassRequest, result: SubagentPassResul
 		stopReason: result.stopReason,
 		errorMessage: result.errorMessage,
 		lifecycle: result.status,
+		deadlineExpired: result.deadlineExpired,
 		attempts: result.attempts.map((attempt, index) => ({
 			ordinal: index + 1,
 			kind: attempt.kind,
@@ -1064,6 +1076,7 @@ function retainPassArtifact(pass: SubagentPassRequest, result: SubagentPassResul
 			stopReason: attempt.stopReason,
 			errorMessage: attempt.errorMessage,
 			lifecycle: attempt.status,
+			deadlineExpired: attempt.deadlineExpired,
 			retryable: attempt.retryable,
 			elapsedMs: attempt.elapsedMs,
 			firstEventMs: attempt.firstEventMs,
@@ -1162,6 +1175,7 @@ async function runSubagentPass(
 			stopReason: result.stopReason,
 			errorMessage: result.errorMessage,
 			timedOut: result.timedOut,
+			deadlineExpired: result.deadlineExpired,
 			terminationGraceMs: result.terminationGraceMs,
 			forcedTermination: result.forcedTermination,
 			deadlineMs,
@@ -1191,6 +1205,7 @@ async function runSubagentPass(
 				toolPolicy,
 				elapsedMs: monotonicNow() - startedAt,
 				fallbackBudgetRejected,
+				deadlineExpired: result.deadlineExpired,
 				deadlineSource: budget?.source,
 				batchDeadlineMs: budget ? budget.batchDeadlineMs - budget.startedAtMs : undefined,
 				totalDeadlineMs: budget ? budget.totalDeadlineMs - budget.startedAtMs : undefined,
@@ -1228,6 +1243,7 @@ async function runSubagentPass(
 		toolPolicy,
 		elapsedMs: monotonicNow() - startedAt,
 		fallbackBudgetRejected,
+		deadlineExpired: final.deadlineExpired,
 		deadlineSource: budget?.source,
 		batchDeadlineMs: budget ? budget.batchDeadlineMs - budget.startedAtMs : undefined,
 		totalDeadlineMs: budget ? budget.totalDeadlineMs - budget.startedAtMs : undefined,
@@ -1249,6 +1265,12 @@ function formatAttemptSummary(result: SubagentPassResult): string {
 		.join(" → ")}`;
 }
 
+function deadlineExpiryCounts(results: readonly SubagentPassResult[]): Record<ReviewDeadlineKind, number> {
+	return Object.fromEntries(
+		(["total", "synthesis"] as const).map((kind) => [kind, results.filter((r) => r.deadlineExpired === kind).length]),
+	) as Record<ReviewDeadlineKind, number>;
+}
+
 function formatBatchResults(
 	results: SubagentPassResult[],
 	maxParallel: number,
@@ -1258,10 +1280,18 @@ function formatBatchResults(
 		(["complete", "partial", "timed_out", "failed"] as const).map((state) => [state, results.filter((r) => r.status === state).length]),
 	) as Record<ReviewLaneLifecycle, number>;
 	const incomplete = results.length - lifecycleCounts.complete;
+	const externalDeadlines = deadlineExpiryCounts(results);
+	const externalTotal = externalDeadlines.total + externalDeadlines.synthesis;
 	const lines = [
 		`Review subagents completed: ${lifecycleCounts.complete}/${results.length} semantically complete (max_parallel=${maxParallel}; partial=${lifecycleCounts.partial}; timed_out=${lifecycleCounts.timed_out}; failed=${lifecycleCounts.failed}).`,
 		...warnings,
 	];
+	if (externalTotal > 0) {
+		const kinds = (["total", "synthesis"] as const).filter((kind) => externalDeadlines[kind] > 0).join("/");
+		lines.push(
+			`WARNING: the host ${kinds} deadline expired while ${externalTotal} lane(s) were still running; those lane attempt budgets were not exceeded.`,
+		);
+	}
 	if (incomplete) {
 		lines.push(
 			`WARNING: ${incomplete} pass(es) are incomplete. Preserve their raw evidence, then rerun or cover those passes inline before finalizing.`,
@@ -1274,6 +1304,7 @@ function formatBatchResults(
 			`status: ${result.status}`,
 			`tool_policy: ${result.toolPolicy}`,
 			`elapsed_ms: ${result.elapsedMs}`,
+			...(result.deadlineExpired ? [`deadline_expired: ${result.deadlineExpired}`] : []),
 			result.notice,
 		);
 		const attemptSummary = formatAttemptSummary(result);
@@ -1612,7 +1643,7 @@ export default function registerPrReviewSubagents(
 			"Delegate one PR-review pass to an isolated subagent running on a configured model tier.",
 			"Pass tier (light|medium|heavy) plus an objective and the diff as context.",
 			"Model per tier is configured via /pr-review-config (stored in pr-review.json).",
-			"Returns the subagent's candidate findings; the orchestrator validates, filters, and emits the final JSON.",
+			"Returns the subagent's candidate findings; the orchestrator validates, filters, and emits the final Markdown review.",
 		].join(" "),
 		promptSnippet:
 			"Run a tiered PR-review pass (light/medium/heavy) in an isolated subagent on the configured model",
@@ -1896,6 +1927,7 @@ export default function registerPrReviewSubagents(
 					incompleteCount: incomplete.length,
 					fallbackStarts: results.filter((result) => result.attempts.length > 1).length,
 					fallbackBudgetRejections: results.filter((result) => result.fallbackBudgetRejected).length,
+					deadlineExpiries: deadlineExpiryCounts(results),
 					deadlineSource: lease.budget?.source,
 					deadlineWarnings: lease.budget?.warnings,
 					batchDeadlineMs: lease.budget ? lease.budget.batchDeadlineMs - lease.budget.startedAtMs : undefined,
@@ -1927,8 +1959,10 @@ export default function registerPrReviewSubagents(
 						status: r.status,
 						stopReason: r.stopReason,
 						errorMessage: r.errorMessage,
+						deadlineExpired: r.deadlineExpired,
 						fallbackUsed: r.fallbackUsed,
 						retryableFailure: r.retryableFailure,
+						retryableFailure: r.retryableFailure,
 						toolPolicy: r.toolPolicy,
 						elapsedMs: r.elapsedMs,
 						firstEventMs: r.attempts.at(-1)?.firstEventMs,
@@ -2033,7 +2067,7 @@ const CONFIG_COMPLETIONS: Array<{ value: string; label: string }> = [
 		value: `${t}_tool_policy=`,
 		label: `${t}_tool_policy=<none|configured|unset> — default tool access when a pass does not override it`,
 	})),
-	{ value: "auto_post_reviews=", label: "auto_post_reviews=<true|false> — automatically post COMMENT reviews (default false)" },
+	{ value: "auto_post_reviews=", label: "auto_post_reviews=<true|false> — automatically post host-gated reviews (default false)" },
 	{ value: "allow_stale_publish=", label: "allow_stale_publish=<true|false> — permit disclosed body-only stale publication (default true)" },
 	{ value: "tools=", label: "tools=read,bash,grep,find,ls — allowlist used by configured policy" },
 	{ value: "show", label: "show — print the current review config" },
@@ -2325,7 +2359,7 @@ function summarizeConfig(
 		"- Enable stale publication (default): `/pr-review-config allow_stale_publish=true`",
 		"- Permit qualified stale fully parsed reviews to record APPROVE: `/pr-review-config allow_stale_approvals=true`",
 		"- Keep stale reviews as COMMENT (default): `/pr-review-config allow_stale_approvals=false`",
-		"- Enable strict JSON approval for low-severity reviews: `/pr-review-config approve_max_priority_level=P2`",
+		"- Enable approval for qualified fully parsed reviews: `/pr-review-config approve_max_priority_level=P2`",
 		"- Disable auto-approve (default): `/pr-review-config approve_max_priority_level=off`",
 		"- Set tier tool policy: `/pr-review-config light_tool_policy=none`",
 		"- Clear a tier: `/pr-review-config medium=unset`",
@@ -2452,7 +2486,7 @@ function configMenuItems(cfg: PrReviewConfig, available: string[]): SettingItem[
 		{
 			id: "auto_post_reviews",
 			label: "user automatic posting setting",
-			description: "Post one GitHub COMMENT review after final JSON. Disabled by default.",
+			description: "Post one host-gated GitHub review after terminal synthesis. Disabled by default.",
 			currentValue: String(cfg.autoPostReviews),
 			values: ["false", "true"],
 		},

package/extensions/review-table.ts

@@ -1,12 +1,13 @@
 /**
  * review-table
  *
- * Renders the /pr-review final JSON response as a readable TUI review and owns
- * configured GitHub publication after valid final JSON. Publishing is bound to raw
- * invocation flags/config, validates current PR state and anchors, and can emit only
- * one formal COMMENT review with associated inline comments.
+ * Renders the /pr-review Markdown-first canonical artifact as a readable TUI review
+ * and owns configured GitHub publication after terminal synthesis. Publishing is
+ * bound to host invocation state, validates current PR state and anchors, and emits
+ * at most one formal COMMENT or qualified APPROVE review with associated inline comments.
  *
- * Rendering only rewrites interactive TUI output. Print/json/rpc modes retain raw JSON.
+ * Rendering only rewrites interactive TUI output. Print/json/rpc modes retain the raw
+ * assistant response.
  */
 
 import * as fs from "node:fs";
@@ -422,7 +423,7 @@ async function publishCompletedReview(
 
 	const headSha = record.review.pr?.head_sha;
 	if (typeof headSha !== "string") {
-		ctx.ui.notify("PR review was not posted: cached final JSON is missing pr.head_sha", "error");
+		ctx.ui.notify("PR review was not posted: cached review artifact is missing pr.head_sha", "error");
 		return;
 	}
 	const result = await publishPullReview({
@@ -780,13 +781,28 @@ export default function registerReviewTable(
 		}
 	});
 
+	pi.on("turn_start", (_event, ctx) => {
+		// A turn that begins after review work (even without a review tool in
+		// flight, e.g. while the orchestrator composes the batch call) means the
+		// synthesis phase is not active. Postpone the armed cap and re-arm it at
+		// this turn's end so early review-tool turns cannot starve later lanes.
+		// This read must never clear an expired binding: its retained artifacts
+		// are reserved for degraded synthesis, so no lease acquisition happens.
+		if (!loopCoordinator.peek()) return;
+		const generation = loopCoordinator.deferActiveSynthesis(ctx);
+		if (generation !== undefined) generationsReadyForSynthesis.add(generation);
+	});
+
 	pi.on("tool_execution_start", (event, ctx) => {
 		if (!loopCoordinator.peek()) return;
 		telemetryTracker.toolStarted(event.toolCallId, event.toolName, event.args);
 		const lease = loopCoordinator.acquire(ctx);
 		if (!lease) return;
 		activeToolGenerations.set(event.toolCallId, lease.generation);
-		if (reviewToolNames.has(event.toolName)) generationsWithReviewTools.add(lease.generation);
+		if (reviewToolNames.has(event.toolName)) {
+			generationsWithReviewTools.add(lease.generation);
+			loopCoordinator.deferSynthesis(lease.generation, ctx);
+		}
 	});
 
 	pi.on("tool_execution_end", (event) => {
@@ -803,6 +819,7 @@ export default function registerReviewTable(
 		// turn_end includes the complete tool-result set for the assistant turn.
 		// Start the synthesis cap here rather than at the first tool end so
 		// sequential or concurrently settling tool calls cannot consume it early.
+		// Turns that deferred the cap re-arm it here with a fresh synthesis window.
 		for (const generation of generationsReadyForSynthesis) {
 			generationsReadyForSynthesis.delete(generation);
 			loopCoordinator.beginSynthesis(generation, ctx);
@@ -913,9 +930,9 @@ export default function registerReviewTable(
 				: text.trim()
 					? parseReview(text)
 					: null;
-		if (!review) return; // not a renderable /pr-review JSON payload — leave untouched
+		if (!review) return; // not a renderable /pr-review artifact — leave untouched
 
-		// Keep raw JSON for automation; only prettify for interactive terminals.
+		// Keep the raw assistant response for automation; only prettify interactive TUI output.
 		if (ctx.mode !== "tui") return;
 		const nonText = event.message.content.filter((part) => part.type !== "text");
 		return {

package/lib/pr-review-artifacts.ts

@@ -1,3 +1,5 @@
+import type { ReviewDeadlineKind } from "./pr-review-deadlines.ts";
+
 export type ReviewLaneLifecycle = "complete" | "partial" | "timed_out" | "failed";
 
 export interface ReviewLaneAttemptArtifact {
@@ -12,6 +14,8 @@ export interface ReviewLaneAttemptArtifact {
 	readonly stopReason?: string;
 	readonly errorMessage?: string;
 	readonly lifecycle: ReviewLaneLifecycle;
+	/** Host total/synthesis deadline that ended this attempt, when it caused termination. */
+	readonly deadlineExpired?: ReviewDeadlineKind;
 	readonly retryable: boolean;
 	readonly elapsedMs: number;
 	readonly firstEventMs?: number;
@@ -49,6 +53,8 @@ export interface ReviewLaneArtifact {
 	readonly stopReason?: string;
 	readonly errorMessage?: string;
 	readonly lifecycle: ReviewLaneLifecycle;
+	/** Host total/synthesis deadline that ended this lane, when it caused termination. */
+	readonly deadlineExpired?: ReviewDeadlineKind;
 	readonly attempts: readonly ReviewLaneAttemptArtifact[];
 	readonly fallbackUsed: boolean;
 	readonly elapsedMs: number;

package/lib/pr-review-deadlines.ts

@@ -2,6 +2,9 @@ import { monotonicNow, type MonotonicNow } from "./pr-review-telemetry.ts";
 
 export type ReviewTier = "light" | "medium" | "heavy";
 
+/** Which host invocation deadline (total or synthesis) ended review work. */
+export type ReviewDeadlineKind = "total" | "synthesis";
+
 export interface ReviewDeadlineConfig {
 	attemptMs: Record<ReviewTier, number>;
 	fallbackAttemptMs: number;

package/lib/pr-review-loop.ts

@@ -21,7 +21,7 @@ import {
 	type ExpectedReviewLane,
 	type ReviewLaneArtifact,
 } from "./pr-review-artifacts.ts";
-import { createReviewBudget, type DeadlineResolution, type ReviewBudget } from "./pr-review-deadlines.ts";
+import { createReviewBudget, type DeadlineResolution, type ReviewBudget, type ReviewDeadlineKind } from "./pr-review-deadlines.ts";
 import { monotonicNow } from "./pr-review-telemetry.ts";
 
 export const REVIEW_LOOP_TOOL_NAMES = [
@@ -48,6 +48,30 @@ interface ReviewLoopBinding {
 	deadlineKind?: "total" | "synthesis";
 }
 
+export type { ReviewDeadlineKind };
+
+export interface ReviewDeadlineError extends Error {
+	readonly reviewDeadlineKind: ReviewDeadlineKind;
+}
+
+const REVIEW_DEADLINE_KIND_PATTERN = /review (total|synthesis) deadline expired/i;
+
+/** Host deadline aborts carry a typed kind so classification never depends on message text alone. */
+export function reviewDeadlineError(kind: ReviewDeadlineKind): ReviewDeadlineError {
+	return Object.assign(new Error(`review ${kind} deadline expired`), {
+		reviewDeadlineKind: kind,
+	}) as ReviewDeadlineError;
+}
+
+/** Identify the host total/synthesis deadline behind an abort reason, if any. */
+export function reviewDeadlineKindOf(reason: unknown): ReviewDeadlineKind | undefined {
+	if (!(reason instanceof Error)) return undefined;
+	const typed = (reason as Partial<ReviewDeadlineError>).reviewDeadlineKind;
+	if (typed === "total" || typed === "synthesis") return typed;
+	const matched = REVIEW_DEADLINE_KIND_PATTERN.exec(reason.message);
+	return matched ? (matched[1]!.toLowerCase() as ReviewDeadlineKind) : undefined;
+}
+
 export interface ReviewLoopLease {
 	readonly generation: number;
 	readonly signal: AbortSignal;
@@ -171,7 +195,7 @@ export class ReviewLoopCoordinator {
 				if (this.binding !== binding || binding.deadlineKind) return;
 				binding.deadlineKind = "total";
 				if (binding.synthesisTimer) clearTimeout(binding.synthesisTimer);
-				binding.controller.abort(new Error("review total deadline expired"));
+				binding.controller.abort(reviewDeadlineError("total"));
 				this.setToolsEnabled(false);
 				try { binding.onDeadline?.(); } catch { /* lifecycle callback is best-effort */ }
 			}, activeAllowanceMs);
@@ -246,10 +270,11 @@ export class ReviewLoopCoordinator {
 			activeTotalDeadline,
 		);
 		const expire = () => {
-			if (this.binding !== binding || binding.deadlineKind) return;
+			// A deferral between scheduling and firing must not abort live review work.
+			if (this.binding !== binding || binding.deadlineKind || !binding.synthesisStarted) return;
 			binding.deadlineKind = "synthesis";
 			if (binding.totalTimer) clearTimeout(binding.totalTimer);
-			binding.controller.abort(new Error("review synthesis deadline expired"));
+			binding.controller.abort(reviewDeadlineError("synthesis"));
 			this.setToolsEnabled(false);
 			try { binding.onDeadline?.(); } catch { /* lifecycle callback is best-effort */ }
 		};
@@ -259,6 +284,46 @@ export class ReviewLoopCoordinator {
 		return true;
 	}
 
+	/**
+	 * Postpone an armed, unexpired synthesis cap because review work is active
+	 * again. The cap re-arms the next time a turn ends with review tools done;
+	 * an expired or never-armed binding is left untouched.
+	 */
+	deferSynthesis(
+		generation: number,
+		ctx: Pick<ExtensionContext, "cwd" | "sessionManager">,
+	): boolean {
+		const binding = this.binding;
+		if (!binding || binding.generation !== generation || !sameBinding(binding, ctx)) return false;
+		return this.disarmSynthesis(binding);
+	}
+
+	/**
+	 * Defer the armed synthesis cap for the current binding without acquiring a
+	 * lease. Unlike acquire(), this never clears an aborted or expired binding,
+	 * so a turn that starts after a deadline expiry cannot destroy the retained
+	 * artifacts reserved for degraded synthesis. Returns the deferred generation.
+	 */
+	deferActiveSynthesis(
+		ctx: Pick<ExtensionContext, "cwd" | "sessionManager">,
+	): number | undefined {
+		const binding = this.binding;
+		const phase = this.invocationGate.phase();
+		if (!binding || this.suspendedTools !== undefined || (phase !== "reviewing" && phase !== "confirmed")) {
+			return undefined;
+		}
+		if (!sameBinding(binding, ctx) || binding.controller.signal.aborted) return undefined;
+		return this.disarmSynthesis(binding) ? binding.generation : undefined;
+	}
+
+	private disarmSynthesis(binding: ReviewLoopBinding): boolean {
+		if (binding.deadlineKind || binding.controller.signal.aborted || !binding.synthesisStarted) return false;
+		if (binding.synthesisTimer) clearTimeout(binding.synthesisTimer);
+		binding.synthesisTimer = undefined;
+		binding.synthesisStarted = false;
+		return true;
+	}
+
 	isLeaseActive(
 		lease: ReviewLoopLease,
 		ctx: Pick<ExtensionContext, "cwd" | "sessionManager">,

package/lib/pr-review-markdown.ts

@@ -553,6 +553,9 @@ function retainedLaneEvidence(lanes: readonly ReviewLaneArtifact[]): string {
 	const lines = ["## Host-retained lane evidence", ""];
 	for (const lane of lanes.slice(0, MAX_DISCLOSED_LANES)) {
 		lines.push(`### ${disclosedPassId(lane.passId)} — ${lane.lifecycle}`, "");
+		if (lane.deadlineExpired) {
+			lines.push(`Host ${lane.deadlineExpired} deadline expired while this lane was still running.`, "");
+		}
 		const text = retainedLaneText(lane);
 		if (text) lines.push(text, "");
 		else lines.push(`No substantive output was retained${lane.errorMessage ? `: ${lane.errorMessage}` : "."}`, "");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-pr-review",
-  "version": "1.12.0",
-  "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.",
+  "version": "1.12.2",
+  "description": "Parallel AI code review for GitHub pull requests in the Pi coding agent, with model-agnostic tiered subagents, structured findings, optional verification, and host-gated COMMENT or qualified APPROVE publishing.",
   "keywords": [
     "pi-package",
     "pi-extension",

package/prompts/pr-review.md

@@ -196,7 +196,7 @@ The orchestrator must never call `gh` to post comments or reviews. Always finish
 
 After host synthesis, the extension caches one validated completed review as a canonical host-owned artifact 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.
 
-Every authorized publish path builds one GitHub review payload and sends at most one review `POST`; the extension never submits `REQUEST_CHANGES`. Fully parsed Markdown with one complete retained artifact for every host-registered dispatch, the exact visible `All requested lanes completed.` disclosure, and retained strict host-bound JSON share the same gated `APPROVE` path. Verdict fields outside the document preamble, hidden in CommonMark code/HTML blocks, or inside lazy container continuations, severity-tagged headings outside `Findings`, contradictory lane disclosures, and partial, malformed, unsafe, or lane-fallback Markdown remain body-only `COMMENT`. Restored cache entries must reclassify retained lane output, reproduce the exact host-recorded artifact key set, and bind every complete artifact to the frozen invocation generation, tier, and minor-hygiene contract and re-synthesize the retained raw text under that frozen binding before preserving approval eligibility. For a current, open PR, the first 50 eligible P0–P3 findings with valid, unique diff anchors are inline. The public body contains the verdict, an inline-review cue when applicable, and `Other Notes` for nits and every finding that cannot be inline; overview, verification, strengths, and transport diagnostics remain only in the retained internal artifact. If that concise body plus its canonical marker exceeds GitHub's limit, the host publishes the sanitized, size-bounded original Markdown projection instead of dropping the review. Stale reviews and authorized closed or merged reviews are body-only. A stale review may record a qualified `APPROVE` only with the separate trusted `allowStaleApprovals: true` opt-in captured before review execution. A failed write never triggers a fallback POST.
+Every authorized publish path builds one GitHub review payload and sends at most one review `POST`; the extension never submits `REQUEST_CHANGES`. Fully parsed Markdown with one complete retained artifact for every host-registered dispatch, a standalone visible `All requested lanes completed.` disclosure (matched case-insensitively, with an optional final period), and retained strict host-bound JSON share the same gated `APPROVE` path. Verdict fields outside the document preamble, hidden in CommonMark code/HTML blocks, or inside lazy container continuations, severity-tagged headings outside `Findings`, contradictory lane disclosures, and partial, malformed, unsafe, or lane-fallback Markdown remain body-only `COMMENT`. Restored cache entries must reclassify retained lane output, reproduce the exact host-recorded artifact key set, and bind every complete artifact to the frozen invocation generation, tier, and minor-hygiene contract and re-synthesize the retained raw text under that frozen binding before preserving approval eligibility. For a current, open PR, the first 50 eligible P0–P3 findings with valid, unique diff anchors are inline. The public body contains the verdict, an inline-review cue when applicable, and `Other Notes` for nits and every finding that cannot be inline; overview, verification, strengths, and transport diagnostics remain only in the retained internal artifact. If that concise body plus its canonical marker exceeds GitHub's limit, the host publishes the sanitized, size-bounded original Markdown projection instead of dropping the review. Stale reviews and authorized closed or merged reviews are body-only. A stale review may record a qualified `APPROVE` only with the separate trusted `allowStaleApprovals: true` opt-in captured before review execution. 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.
 
@@ -225,7 +225,7 @@ Return Markdown using these stable headings. Do not emit a GitHub API payload an
 **Location:** `path/to/file.ts:10-12 RIGHT`
 
 ## Lane completeness
-<name any failed, timed-out, or partial lane and how its retained evidence was handled; otherwise say all requested lanes completed>
+<name any failed, timed-out, or partial lane and how its retained evidence was handled; otherwise write: All requested lanes completed.>
 
 ## Strengths and notes
 <useful strengths plus concise correctness, security, or performance notes>