pi-pr-review 1.12.1 → 1.12.2

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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)
 
 

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.
 

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";
@@ -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);
@@ -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,

package/extensions/review-table.ts

@@ -781,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) => {
@@ -804,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);

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,6 +1,6 @@
 {
   "name": "pi-pr-review",
-  "version": "1.12.1",
+  "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",