pi-pr-review 1.16.0 → 1.17.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.17.1](https://github.com/10ego/pi-pr-review/compare/v1.17.0...v1.17.1) (2026-08-31)
+
+
+### Bug Fixes
+
+* **review:** start batch deadline at reviewer dispatch ([#124](https://github.com/10ego/pi-pr-review/issues/124)) ([26a38af](https://github.com/10ego/pi-pr-review/commit/26a38af6559223c6403913de32026c7d2eee5d2b))
+
+## [1.17.0](https://github.com/10ego/pi-pr-review/compare/v1.16.0...v1.17.0) (2026-08-29)
+
+
+### Features
+
+* **review:** configure default review mode ([#122](https://github.com/10ego/pi-pr-review/issues/122)) ([52028be](https://github.com/10ego/pi-pr-review/commit/52028be9fcc91713e54378e3d50f31a3cd9cd642))
+
 ## [1.16.0](https://github.com/10ego/pi-pr-review/compare/v1.15.16...v1.16.0) (2026-08-28)
 
 

package/README.md

@@ -59,7 +59,7 @@ The semantic result is predictable human-readable Markdown in every mode. GitHub
 | `/pr-review 123 --deep` | One integrated heavy reviewer for the whole PR. |
 | `/pr-review 123 --include-closed` | Reviews a closed or merged PR without asking first. |
 
-`--quick`, `--major-only`, `--balanced`, `--full`, and `--deep` are mutually exclusive.
+`--quick`, `--major-only`, `--balanced`, `--full`, and `--deep` are mutually exclusive. When no mode flag is supplied, `/pr-review` uses the configured default mode; this is `balanced` until changed with `/pr-review-config`.
 
 `--deep` trades parallel lens coverage for holistic judgment: a single heavy-tier reviewer receives the complete diff plus repository tools and reviews the change as one story—intent, approach, cross-file behavior, and test fit. It uses the same deadline, artifact, degradation, extraction, and publication machinery as every other mode. Without `--include-closed` or `--review-closed`, Pi asks before reviewing a non-open PR.
 
@@ -115,7 +115,7 @@ The viewer intentionally cannot send prompts, steering, or follow-ups to reviewe
 
 ## Configure models
 
-`/pr-review-config` opens an interactive settings menu in the TUI. Use `/pr-review-config show` for a text summary or `key=value` arguments for direct changes.
+`/pr-review-config` opens an interactive settings menu in the TUI. Its **default review mode** selector replaces the former parallelism control: reviewer count and concurrency are derived from the selected mode. Use `/pr-review-config show` for a text summary or `key=value` arguments for direct changes.
 
 | Tier | Purpose |
 |---|---|
@@ -126,6 +126,7 @@ The viewer intentionally cannot send prompts, steering, or follow-ups to reviewe
 Common settings:
 
 ```text
+/pr-review-config default_review_mode=balanced
 /pr-review-config light=provider/model heavy=provider/model:high
 /pr-review-config heavy_fallbacks=provider/backup:high,provider/backup2
 /pr-review-config light_thinking=low medium_thinking=medium heavy_thinking=high
@@ -147,12 +148,13 @@ Configuration is stored in:
 - user scope: `~/.pi/agent/pr-review.json`;
 - project scope: `<repo>/.pi/pr-review.json`, applied only when the project is trusted.
 
-A trusted project can override model, tool, and publication settings. Verification profiles are always user-only.
+A trusted project can override the default review mode, model, tool, and publication settings. Explicit `/pr-review --quick|--balanced|--full|--deep` flags override the configured default. Verification profiles are always user-only.
 
 Example:
 
 ```json
 {
+  "defaultReviewMode": "balanced",
   "tiers": {
     "light": "provider/fast-model",
     "medium": "provider/balanced-model",
@@ -189,13 +191,13 @@ Example:
 }
 ```
 
-Every invocation has a host-owned monotonic 15-minute hard cap, including the two GitHub identity/lifecycle preflights, synthesis, termination grace, and reserved cleanup. The dependent preflight calls share the one invocation budget, so they cannot each add an independent command timeout before review timing begins. Defaults bound light/medium/heavy attempts to 3/6/8 minutes, a fallback attempt to 3 minutes, and the concurrent batch to 12 minutes. The complete `deadlines` object may be replaced at user scope or by a trusted project; partial, malformed, non-integer, out-of-range, or internally inconsistent objects are rejected as a unit and the last valid/default finite budget remains active. Supported inclusive ranges are: attempts 30–720 seconds, fallback 30–360 seconds, batch 60–840 seconds, synthesis 10–120 seconds, total 120–1200 seconds, TERM grace 0.1–15 seconds, cleanup reserve 1–30 seconds, and minimum useful fallback 10–120 seconds. Minimum fallback must not exceed its attempt cap, and batch + synthesis + termination grace + cleanup must fit inside total.
+Every invocation has a host-owned monotonic 15-minute hard cap, including the two GitHub identity/lifecycle preflights, parent orchestration, synthesis, termination grace, and reserved cleanup. The dependent preflight calls share the one invocation budget, so they cannot each add an independent command timeout before review timing begins. The reviewer batch window activates once, at the first reviewer dispatch: preflight and diff capture remain charged to the total cap but cannot exhaust `batchMs` before any reviewer starts. The activated batch is still truncated by the original total deadline and its synthesis/termination/cleanup reserves. Defaults bound light/medium/heavy attempts to 3/6/8 minutes, a fallback attempt to 3 minutes, and the concurrent batch to 12 minutes. The complete `deadlines` object may be replaced at user scope or by a trusted project; partial, malformed, non-integer, out-of-range, or internally inconsistent objects are rejected as a unit and the last valid/default finite budget remains active. Supported inclusive ranges are: attempts 30–720 seconds, fallback 30–360 seconds, batch 60–840 seconds, synthesis 10–120 seconds, total 120–1200 seconds, TERM grace 0.1–15 seconds, cleanup reserve 1–30 seconds, and minimum useful fallback 10–120 seconds. Minimum fallback must not exceed its attempt cap, and batch + synthesis + termination grace + cleanup must fit inside total.
 
 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. 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 reviewer, 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. Host lane artifacts are authoritative for completeness in both directions: a false assistant completion claim cannot upgrade incomplete lanes, and a paraphrased or omitted `Lane completeness` line cannot downgrade a host-complete batch away from the concise renderer.
 
-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.
+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 invocation time consumed before each attempt, batch/total time remaining at dispatch, 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

@@ -56,7 +56,7 @@ import {
 	type ReviewLaneLifecycle,
 } from "../lib/pr-review-artifacts.ts";
 import { runWithConcurrency } from "../lib/pr-review-concurrency.ts";
-import { attemptDeadline, fallbackBudget, type ReviewBudget } from "../lib/pr-review-deadlines.ts";
+import { activateReviewBatch, attemptDeadline, fallbackBudget, type ReviewBudget } from "../lib/pr-review-deadlines.ts";
 import { buildExtractionSystemPrompt, buildExtractionTask, MAX_EXTRACTION_OUTPUT_BYTES } from "../lib/pr-review-extract.ts";
 import { loadReviewContext } from "../lib/pr-review-context.ts";
 import {
@@ -91,6 +91,8 @@ import {
 	resolveAllowStalePublishSetting,
 	resolveAutoPostSetting,
 	resolveApproveMaxPriorityLevelSetting,
+	resolveDefaultReviewModeSetting,
+	REVIEW_MODES,
 	type ApproveMaxPriorityLevel,
 	type ReviewMode,
 } from "../lib/pr-review-publish.ts";
@@ -175,6 +177,8 @@ const TIER_PURPOSE: Record<Tier, string> = {
 };
 
 interface PrReviewConfig {
+	/** Review topology used when /pr-review has no explicit mode flag. */
+	defaultReviewMode: ReviewMode;
 	/** Tier label -> model spec (e.g. "anthropic/model", "openai/model:high"). */
 	tiers: Partial<Record<Tier, string>>;
 	/** Tier label -> ordered fallback model specs used for quota/capacity failures. */
@@ -258,6 +262,17 @@ function normalizeToolPolicies(
 	return out;
 }
 
+function resolveDefaultReviewModeForContext(ctx: Pick<ExtensionContext, "cwd" | "isProjectTrusted">) {
+	const user = readConfigFile(userConfigPath());
+	let project: Partial<PrReviewConfig> | undefined;
+	try {
+		if (ctx.isProjectTrusted()) project = readConfigFile(projectConfigPath(ctx.cwd));
+	} catch {
+		/* user config only */
+	}
+	return resolveDefaultReviewModeSetting(user, project);
+}
+
 function resolveAutoPostForContext(ctx: Pick<ExtensionContext, "cwd" | "isProjectTrusted">) {
 	const user = readConfigFile(userConfigPath());
 	let project: Partial<PrReviewConfig> | undefined;
@@ -315,7 +330,9 @@ function loadConfig(ctx: Pick<ExtensionContext, "cwd" | "isProjectTrusted">): Pr
 	const allowStale = resolveAllowStalePublishSetting(user, project);
 	const allowStaleApprovals = resolveAllowStaleApprovalsSetting(user, project);
 	const approveMaxPriority = resolveApproveMaxPriorityLevelSetting(user, project);
+	const defaultReviewMode = resolveDefaultReviewModeSetting(user, project);
 	return {
+		defaultReviewMode: defaultReviewMode.valid ? defaultReviewMode.value : "balanced",
 		tiers: { ...(user.tiers ?? {}), ...(project.tiers ?? {}) },
 		fallbacks: { ...normalizeFallbacks(user.fallbacks, true), ...normalizeFallbacks(project.fallbacks, true) },
 		thinkingLevels: {
@@ -345,7 +362,9 @@ function readUserConfig(): PrReviewConfig {
 	const allowStale = resolveAllowStalePublishSetting(raw);
 	const allowStaleApprovals = resolveAllowStaleApprovalsSetting(raw);
 	const approveMaxPriority = resolveApproveMaxPriorityLevelSetting(raw);
+	const defaultReviewMode = resolveDefaultReviewModeSetting(raw);
 	return {
+		defaultReviewMode: defaultReviewMode.valid ? defaultReviewMode.value : "balanced",
 		tiers: { ...(raw.tiers ?? {}) },
 		fallbacks: normalizeFallbacks(raw.fallbacks),
 		thinkingLevels: normalizeThinkingLevels(raw.thinkingLevels, "User pr-review config"),
@@ -891,6 +910,12 @@ interface ModelAttemptReport {
 	forcedTermination?: boolean;
 	deadlineMs?: number;
 	configuredDeadlineMs?: number;
+	/** Invocation time already consumed before this model attempt was scheduled. */
+	budgetElapsedBeforeAttemptMs?: number;
+	/** Remaining absolute reviewer-batch window at scheduling time; may be negative. */
+	batchRemainingBeforeAttemptMs?: number;
+	/** Remaining total invocation window at scheduling time. */
+	totalRemainingBeforeAttemptMs?: number;
 }
 
 interface SubagentPassResult {
@@ -967,16 +992,32 @@ async function runSubagentAttempt(
 	onText?: (text: string) => void,
 	beforeSpawn?: () => boolean,
 	budget?: ReviewBudget,
-): Promise<{ result: RunResult; notice: string; elapsedMs: number; deadlineMs?: number }> {
+): Promise<{
+	result: RunResult;
+	notice: string;
+	elapsedMs: number;
+	deadlineMs?: number;
+	budgetElapsedBeforeAttemptMs?: number;
+	batchRemainingBeforeAttemptMs?: number;
+	totalRemainingBeforeAttemptMs?: number;
+}> {
 	let tmp: { dir: string; filePath: string } | undefined;
 	const startedAt = monotonicNow();
+	const budgetElapsedBeforeAttemptMs = budget ? startedAt - budget.startedAtMs : undefined;
+	const batchRemainingBeforeAttemptMs = budget ? budget.batchDeadlineMs - startedAt : undefined;
+	const totalRemainingBeforeAttemptMs = budget ? budget.totalDeadlineMs - startedAt : undefined;
 	const deadlineAtMs = budget
 		? attemptDeadline(budget, pass.tier, attempt.kind === "fallback", () => startedAt)
 		: undefined;
 	const deadlineMs = deadlineAtMs === undefined ? undefined : Math.max(0, deadlineAtMs - startedAt);
 	try {
 		if (deadlineAtMs !== undefined && deadlineAtMs <= startedAt) {
-			throw new Error("Review attempt timed out before it could start within the batch deadline.");
+			throw new Error(
+				`Review attempt timed out before it could start within the batch deadline ` +
+				`(invocation elapsed ${Math.round(budgetElapsedBeforeAttemptMs!)}ms; ` +
+				`batch remaining ${Math.round(batchRemainingBeforeAttemptMs!)}ms; ` +
+				`total remaining ${Math.round(totalRemainingBeforeAttemptMs!)}ms).`,
+			);
 		}
 		const args = buildReviewBaseArgs();
 		if (attempt.spec) args.push("--model", attempt.spec);
@@ -1045,13 +1086,24 @@ async function runSubagentAttempt(
 		fileBackedAccessObserved = !!pass.fileBackedRequiredReads?.length &&
 			pass.fileBackedRequiredReads.every((range) => completedFileBackedReads.has(`${range.offset}:${range.limit}`));
 		result.fileBackedAccessObserved = fileBackedAccessObserved;
-		return { result, notice: noticeForAttempt(pass.tier, attempt), elapsedMs: monotonicNow() - startedAt, deadlineMs };
+		return {
+			result,
+			notice: noticeForAttempt(pass.tier, attempt),
+			elapsedMs: monotonicNow() - startedAt,
+			deadlineMs,
+			budgetElapsedBeforeAttemptMs,
+			batchRemainingBeforeAttemptMs,
+			totalRemainingBeforeAttemptMs,
+		};
 	} catch (e) {
 		return {
 			result: { text: "", exitCode: 1, stderr: "", errorMessage: errMessage(e), toolElapsedMs: 0, toolCallCount: 0 },
 			notice: noticeForAttempt(pass.tier, attempt),
 			elapsedMs: monotonicNow() - startedAt,
 			deadlineMs,
+			budgetElapsedBeforeAttemptMs,
+			batchRemainingBeforeAttemptMs,
+			totalRemainingBeforeAttemptMs,
 		};
 	} finally {
 		if (tmp) {
@@ -1200,6 +1252,9 @@ function retainPassArtifact(pass: SubagentPassRequest, result: SubagentPassResul
 			forcedTermination: attempt.forcedTermination,
 			deadlineMs: attempt.deadlineMs,
 			configuredDeadlineMs: attempt.configuredDeadlineMs,
+			budgetElapsedBeforeAttemptMs: attempt.budgetElapsedBeforeAttemptMs,
+			batchRemainingBeforeAttemptMs: attempt.batchRemainingBeforeAttemptMs,
+			totalRemainingBeforeAttemptMs: attempt.totalRemainingBeforeAttemptMs,
 		})),
 		fallbackUsed: result.fallbackUsed,
 		elapsedMs: result.elapsedMs,
@@ -1244,7 +1299,15 @@ async function runSubagentPass(
 			fallbackBudgetRejected = true;
 			break;
 		}
-		const { result, notice, elapsedMs, deadlineMs } = await runSubagentAttempt(
+		const {
+			result,
+			notice,
+			elapsedMs,
+			deadlineMs,
+			budgetElapsedBeforeAttemptMs,
+			batchRemainingBeforeAttemptMs,
+			totalRemainingBeforeAttemptMs,
+		} = await runSubagentAttempt(
 			config,
 			ctx,
 			pass,
@@ -1301,6 +1364,9 @@ async function runSubagentPass(
 			configuredDeadlineMs: budget
 				? (attempt.kind === "fallback" ? budget.config.fallbackAttemptMs : budget.config.attemptMs[tier])
 				: undefined,
+			budgetElapsedBeforeAttemptMs,
+			batchRemainingBeforeAttemptMs,
+			totalRemainingBeforeAttemptMs,
 		});
 
 		if (lifecycle === "complete") {
@@ -1748,6 +1814,7 @@ export default function registerPrReviewSubagents(
 			});
 			const artifactPublisher = loopCoordinator.createArtifactPublisher(lease, ctx);
 			const config = loadConfig(ctx);
+			const reviewBudget = lease.budget ? activateReviewBatch(lease.budget) : undefined;
 			const result = await runSubagentPass(
 				config,
 				ctx,
@@ -1766,7 +1833,7 @@ export default function registerPrReviewSubagents(
 				executionSignal,
 				(text) => onUpdate?.({ content: [{ type: "text", text }] }),
 				() => loopCoordinator.isLeaseActive(lease, ctx),
-				lease.budget,
+				reviewBudget,
 			);
 
 			const warnings = [...thinkingWarnings(config, [tier]), ...(lease.budget?.warnings ?? [])];
@@ -1959,6 +2026,7 @@ export default function registerPrReviewSubagents(
 			// reviewer may run concurrently, and no caller/model tuning knob exists.
 			const reviewerConcurrency = passes.length;
 			const config = loadConfig(ctx);
+			const reviewBudget = lease.budget ? activateReviewBatch(lease.budget) : undefined;
 			const batchStartedAt = monotonicNow();
 
 			const tierPriority: Record<Tier, number> = { heavy: 0, medium: 1, light: 2 };
@@ -1974,7 +2042,7 @@ export default function registerPrReviewSubagents(
 					executionSignal,
 					undefined,
 					() => loopCoordinator.isLeaseActive(lease, ctx),
-					lease.budget,
+					reviewBudget,
 				);
 				const endOffsetMs = monotonicNow() - batchStartedAt;
 				result.startOffsetMs = startOffsetMs;
@@ -2072,7 +2140,7 @@ export default function registerPrReviewSubagents(
 	});
 
 	pi.registerCommand("pr-review-config", {
-		description: "Open review-tier settings, or show/set models, thinking, and fallbacks for /pr-review",
+		description: "Open review settings, or set the default mode, models, thinking, and publication policy",
 		handler: async (args, ctx) => {
 			// Extension commands execute before input events, so revoke explicitly.
 			loopCoordinator.clear();
@@ -2085,7 +2153,7 @@ export default function registerPrReviewSubagents(
 			}
 
 			try {
-				// Direct set: `/pr-review-config light=... heavy=... heavy_fallbacks=...`
+				// Direct set: `/pr-review-config default_review_mode=full light=... heavy=...`
 				if (parsed.hasChanges) {
 					const next = applyConfigPatch(readUserConfig(), parsed.patch);
 					writeUserConfig(next);
@@ -2145,6 +2213,7 @@ function shouldOpenConfigMenu(args: string, ctx: ExtensionContext): boolean {
 }
 
 const CONFIG_COMPLETIONS: Array<{ value: string; label: string }> = [
+	{ value: "default_review_mode=", label: "default_review_mode=<quick|balanced|full|deep> — topology used when no mode flag is supplied" },
 	...TIERS.map((t) => ({ value: `${t}=`, label: `${t}=<model> — ${TIER_PURPOSE[t]}` })),
 	...TIERS.map((t) => ({
 		value: `${t}_fallbacks=`,
@@ -2233,6 +2302,7 @@ function tierFromCompoundKey(key: string): Tier {
 }
 
 interface ConfigPatch {
+	defaultReviewMode?: ReviewMode;
 	tiers: Partial<Record<Tier, string | null>>;
 	fallbacks: Partial<Record<Tier, string[] | null>>;
 	thinkingLevels: Partial<Record<Tier, ThinkingLevel | null>>;
@@ -2256,7 +2326,11 @@ function parseConfigArgs(args: string): { patch: ConfigPatch; hasChanges: boolea
 		}
 		const key = token.slice(0, eq).replace(/^--?/, "").toLowerCase();
 		const value = token.slice(eq + 1);
-		if ((TIERS as string[]).includes(key)) {
+		if (key === "default_review_mode" || key === "defaultreviewmode" || key === "default-review-mode") {
+			const normalized = value.toLowerCase();
+			if (REVIEW_MODES.includes(normalized as ReviewMode)) patch.defaultReviewMode = normalized as ReviewMode;
+			else errors.push(`invalid ${key} "${value}" (expected ${REVIEW_MODES.join("|")})`);
+		} else if ((TIERS as string[]).includes(key)) {
 			patch.tiers[key as Tier] = value === "" || value === "unset" ? null : value;
 		} else if (isFallbackKey(key)) {
 			const tier = tierFromCompoundKey(key);
@@ -2308,11 +2382,12 @@ function parseConfigArgs(args: string): { patch: ConfigPatch; hasChanges: boolea
 			patch.tools = splitCommaList(value);
 		} else {
 			errors.push(
-				`unknown key "${key}" (expected light|medium|heavy|<tier>_fallbacks|<tier>_thinking|<tier>_tool_policy|auto_post_reviews|allow_stale_publish|allow_stale_approvals|approve_max_priority_level|tools)`,
+				`unknown key "${key}" (expected default_review_mode|light|medium|heavy|<tier>_fallbacks|<tier>_thinking|<tier>_tool_policy|auto_post_reviews|allow_stale_publish|allow_stale_approvals|approve_max_priority_level|tools)`,
 			);
 		}
 	}
 	const hasChanges =
+		patch.defaultReviewMode !== undefined ||
 		Object.keys(patch.tiers).length > 0 ||
 		Object.keys(patch.fallbacks).length > 0 ||
 		Object.keys(patch.thinkingLevels).length > 0 ||
@@ -2327,6 +2402,7 @@ function parseConfigArgs(args: string): { patch: ConfigPatch; hasChanges: boolea
 
 function applyConfigPatch(base: PrReviewConfig, patch: ConfigPatch): PrReviewConfig {
 	const next: PrReviewConfig = {
+		defaultReviewMode: base.defaultReviewMode,
 		tiers: { ...base.tiers },
 		fallbacks: normalizeFallbacks(base.fallbacks),
 		thinkingLevels: normalizeThinkingLevels(base.thinkingLevels, "PR review config"),
@@ -2339,6 +2415,7 @@ function applyConfigPatch(base: PrReviewConfig, patch: ConfigPatch): PrReviewCon
 		tools: [...base.tools],
 		deadlines: base.deadlines,
 	};
+	if (patch.defaultReviewMode !== undefined) next.defaultReviewMode = patch.defaultReviewMode;
 	for (const tier of TIERS) {
 		if (tier in patch.tiers) {
 			const value = patch.tiers[tier];
@@ -2388,6 +2465,7 @@ function summarizeConfig(
 	} catch {
 		/* ignore */
 	}
+	const defaultReviewMode = resolveDefaultReviewModeForContext(ctx);
 	const autoPost = resolveAutoPostForContext(ctx);
 	const allowStale = resolveAllowStaleForContext(ctx);
 	const allowStaleApprovals = resolveAllowStaleApprovalsForContext(ctx);
@@ -2401,6 +2479,7 @@ function summarizeConfig(
 			(t) =>
 				`| \`${t}\` | ${user.tiers[t] ? `\`${user.tiers[t]}\`` : "_unset_"} | ${effective.tiers[t] ? `\`${effective.tiers[t]}\`` : "_pi default_"} | ${TIER_PURPOSE[t]} |`,
 		),
+		`| \`defaultReviewMode\` | \`${user.defaultReviewMode}\` | \`${effective.defaultReviewMode}\` (${defaultReviewMode.source}) | topology used when no explicit mode flag is supplied; default \`balanced\` |`,
 		`| \`autoPostReviews\` | \`${user.autoPostReviews}\` | \`${effective.autoPostReviews}\` (${autoPost.source}) | automatically post one GitHub review; default \`false\` |`,
 		`| \`allowStalePublish\` | \`${user.allowStalePublish}\` | \`${effective.allowStalePublish}\` (${allowStale.source}) | permit body-only stale publication with reviewed/current SHAs; default \`true\` |`,
 		`| \`allowStaleApprovals\` | \`${user.allowStaleApprovals}\` | \`${effective.allowStaleApprovals}\` (${allowStaleApprovals.source}) | permit qualified stale fully parsed reviews to record APPROVE; default \`false\` |`,
@@ -2420,6 +2499,10 @@ function summarizeConfig(
 	if (projectPath) lines.push(`Project overlay (trusted): \`${projectPath}\``);
 	const warnings = thinkingWarnings(effective);
 	if (warnings.length) lines.push("", ...warnings);
+	if (!defaultReviewMode.valid) lines.push(`Default review mode config error: ${defaultReviewMode.error}`);
+	else if (defaultReviewMode.source === "project") {
+		lines.push("Default review mode is controlled by the trusted project overlay; this command edits user config only.");
+	}
 	if (!autoPost.valid) lines.push(`Automatic posting config error: ${autoPost.error}`);
 	else if (autoPost.source === "project") {
 		lines.push("Automatic posting is controlled by the trusted project overlay; this command edits user config only.");
@@ -2441,7 +2524,8 @@ function summarizeConfig(
 		"## Usage",
 		"- Open the settings menu: `/pr-review-config`",
 		"- Print this summary: `/pr-review-config show`",
-		"- Set directly: `/pr-review-config light=provider/model heavy=provider/model:high`",
+		"- Set the no-flag review topology: `/pr-review-config default_review_mode=balanced`",
+		"- Set models directly: `/pr-review-config light=provider/model heavy=provider/model:high`",
 		"- Set fallback chain: `/pr-review-config heavy_fallbacks=provider/backup:high,provider/backup2`",
 		"- Set tier thinking: `/pr-review-config light_thinking=low medium_thinking=medium heavy_thinking=high`",
 		"- Enable automatic GitHub review posting: `/pr-review-config auto_post_reviews=true`",
@@ -2570,6 +2654,13 @@ function configMenuItems(cfg: PrReviewConfig, available: string[]): SettingItem[
 	const current = cfg.tools.join(",");
 	const toolValues = [current, ...TOOLS_PRESETS.filter((p) => p !== current)];
 	return [
+		{
+			id: "default_review_mode",
+			label: "default review mode",
+			description: "Topology used when /pr-review has no explicit mode flag. Enter/Space cycles values.",
+			currentValue: cfg.defaultReviewMode,
+			values: [...REVIEW_MODES],
+		},
 		...tierItems,
 		...fallbackItems,
 		...thinkingItems,
@@ -2628,6 +2719,7 @@ async function showConfigMenu(
 
 			let settingsList: SettingsList;
 			const refresh = () => {
+				settingsList.updateValue("default_review_mode", draft.defaultReviewMode);
 				for (const tier of TIERS) {
 					settingsList.updateValue(tier, draft.tiers[tier] ?? UNSET);
 					settingsList.updateValue(`${tier}_fallbacks`, draft.fallbacks[tier]?.join(",") || "(none)");
@@ -2641,7 +2733,13 @@ async function showConfigMenu(
 			};
 
 			const persist = (id: string, newValue: string) => {
-				if ((TIERS as string[]).includes(id)) {
+				if (id === "default_review_mode") {
+					if (!REVIEW_MODES.includes(newValue as ReviewMode)) {
+						ctx.ui.notify(`Invalid review mode: ${newValue}`, "error");
+						return;
+					}
+					draft.defaultReviewMode = newValue as ReviewMode;
+				} else if ((TIERS as string[]).includes(id)) {
 					if (newValue === "__unset__") delete draft.tiers[id as Tier];
 					else draft.tiers[id as Tier] = newValue;
 				} else if (isFallbackKey(id)) {
@@ -2689,7 +2787,9 @@ async function showConfigMenu(
 				try {
 					writeUserConfig(draft);
 					refresh();
-					const shown = id === "tools"
+					const shown = id === "default_review_mode"
+						? draft.defaultReviewMode
+						: id === "tools"
 						? draft.tools.join(",")
 						: id === "auto_post_reviews"
 							? String(draft.autoPostReviews)
@@ -2706,7 +2806,17 @@ async function showConfigMenu(
 									: isToolPolicyKey(id)
 										? (draft.toolPolicies[tierFromCompoundKey(id)] ?? INHERIT_TOOL_POLICY)
 										: (draft.tiers[id as Tier] ?? UNSET);
-					if (id === "auto_post_reviews") {
+					if (id === "default_review_mode") {
+						const effective = resolveDefaultReviewModeForContext(ctx);
+						if (effective.source === "project") {
+							ctx.ui.notify(
+								`User defaultReviewMode saved as ${shown}, but trusted project config remains effective at ${effective.value}. Edit ${projectConfigPath(ctx.cwd)}.`,
+								"warning",
+							);
+						} else {
+							ctx.ui.notify(`PR review config: ${id} = ${shown} (effective ${effective.value})`, "info");
+						}
+					} else if (id === "auto_post_reviews") {
 						const effective = resolveAutoPostForContext(ctx);
 						if (effective.source === "project") {
 							ctx.ui.notify(

package/extensions/review-table.ts

@@ -39,6 +39,7 @@ import {
 	resolveAutoPostSetting,
 	canonicalReviewSnapshot,
 	resolveApproveMaxPriorityLevelSetting,
+	resolveDefaultReviewModeSetting,
 	type PublishResult,
 	resolveRepositoryBinding,
 	resolveReviewHostBinding,
@@ -50,6 +51,7 @@ import {
 	type CompletedReviewRecord,
 	type CompletedReviewSessionIdentity,
 	type ReviewInvocation,
+	type ReviewModeResolution,
 } from "../lib/pr-review-publish.ts";
 import { demoteHeadings, mergeExtractedFindings, safeReviewBody, synthesizeReviewArtifact, type ReviewSynthesisArtifact } from "../lib/pr-review-markdown.ts";
 import { resolveReviewDeadlinesForContext } from "../lib/pr-review-deadline-config.ts";
@@ -373,6 +375,7 @@ function readJsonObject(filePath: string): ConfigReadResult {
 }
 
 interface PublishingConfigResolution {
+	defaultReviewMode: ReviewModeResolution;
 	autoPost: AutoPostResolution;
 	allowStale: AutoPostResolution;
 	allowStaleApprovals: AutoPostResolution;
@@ -382,7 +385,8 @@ interface PublishingConfigResolution {
 function invalidPublishingConfig(source: "user" | "project", error: string): PublishingConfigResolution {
 	const invalid = { value: false, valid: false, source, error } as const;
 	const invalidLevel = { value: "off" as const, valid: false, source, error } as const;
-	return { autoPost: invalid, allowStale: invalid, allowStaleApprovals: invalid, approveMaxPriority: invalidLevel };
+	const invalidMode = { value: "balanced" as const, valid: false, source, error } as const;
+	return { defaultReviewMode: invalidMode, autoPost: invalid, allowStale: invalid, allowStaleApprovals: invalid, approveMaxPriority: invalidLevel };
 }
 
 function resolvePublishingConfig(ctx: ExtensionContext): PublishingConfigResolution {
@@ -398,6 +402,7 @@ function resolvePublishingConfig(ctx: ExtensionContext): PublishingConfigResolut
 		/* user config only */
 	}
 	return {
+		defaultReviewMode: resolveDefaultReviewModeSetting(user.value, project?.value),
 		autoPost: resolveAutoPostSetting(user.value, project?.value),
 		allowStale: resolveAllowStalePublishSetting(user.value, project?.value),
 		allowStaleApprovals: resolveAllowStaleApprovalsSetting(user.value, project?.value),
@@ -911,8 +916,18 @@ export default function registerReviewTable(
 			return { action: "handled" as const };
 		}
 
-		// Freeze trusted publication config and target binding before review tools or optional PR code can run.
+		// Freeze trusted mode/publication config and target binding before review tools or optional PR code can run.
 		const publishingConfig = resolvePublishingConfig(ctx);
+		const explicitReviewMode = parsed.reviewMode;
+		if (explicitReviewMode === undefined && !publishingConfig.defaultReviewMode.valid) {
+			ctx.ui.notify(`Invalid /pr-review invocation: ${publishingConfig.defaultReviewMode.error}`, "error");
+			return { action: "handled" as const };
+		}
+		const resolvedReviewMode = explicitReviewMode ?? publishingConfig.defaultReviewMode.value;
+		const resolvedParsed = { ...parsed, reviewMode: resolvedReviewMode };
+		const transformedInput = explicitReviewMode === undefined
+			? `${event.text.trimEnd()} --${resolvedReviewMode}`
+			: event.text;
 		const deadlineResolution = resolveReviewDeadlinesForContext(ctx);
 		const budget = createReviewBudget(deadlineResolution);
 		const preflight = {
@@ -952,7 +967,7 @@ export default function registerReviewTable(
 		}
 		activePreflight = undefined;
 		const gate = loopCoordinator.begin(
-			parsed,
+			resolvedParsed,
 			publishingConfig.autoPost,
 			source,
 			ctx,
@@ -969,6 +984,9 @@ export default function registerReviewTable(
 			persistTelemetry("cleared");
 			return { action: "handled" as const };
 		}
+		if (transformedInput !== event.text) {
+			return { action: "transform" as const, text: transformedInput, images: event.images };
+		}
 	});
 
 	pi.on("turn_start", (_event, ctx) => {

package/lib/pr-review-artifacts.ts

@@ -29,6 +29,12 @@ export interface ReviewLaneAttemptArtifact {
 	readonly deadlineMs?: number;
 	/** Configured tier/fallback cap before batch/total truncation. */
 	readonly configuredDeadlineMs?: number;
+	/** Invocation time already consumed before this attempt was scheduled. */
+	readonly budgetElapsedBeforeAttemptMs?: number;
+	/** Remaining reviewer-batch window at scheduling time; negative means dispatch was already late. */
+	readonly batchRemainingBeforeAttemptMs?: number;
+	/** Remaining total invocation window at scheduling time. */
+	readonly totalRemainingBeforeAttemptMs?: number;
 }
 
 export interface ExpectedReviewLane {
@@ -676,6 +682,9 @@ function attemptArtifactSnapshot(value: unknown): ReviewLaneAttemptArtifact | un
 		const forcedTermination = source.forcedTermination;
 		const deadlineMs = source.deadlineMs;
 		const configuredDeadlineMs = source.configuredDeadlineMs;
+		const budgetElapsedBeforeAttemptMs = source.budgetElapsedBeforeAttemptMs;
+		const batchRemainingBeforeAttemptMs = source.batchRemainingBeforeAttemptMs;
+		const totalRemainingBeforeAttemptMs = source.totalRemainingBeforeAttemptMs;
 		// --- Validation phase (locals only). ---
 		if (!isInteger(ordinal)) return undefined;
 		if (!isString(rawText)) return undefined;
@@ -700,6 +709,9 @@ function attemptArtifactSnapshot(value: unknown): ReviewLaneAttemptArtifact | un
 		if (!optional(forcedTermination, isBoolean)) return undefined;
 		if (!optional(deadlineMs, isFiniteNumber)) return undefined;
 		if (!optional(configuredDeadlineMs, isFiniteNumber)) return undefined;
+		if (!optional(budgetElapsedBeforeAttemptMs, isFiniteNumber)) return undefined;
+		if (!optional(batchRemainingBeforeAttemptMs, isFiniteNumber)) return undefined;
+		if (!optional(totalRemainingBeforeAttemptMs, isFiniteNumber)) return undefined;
 		// --- Snapshot phase. ---
 		const snapshot: Record<string, unknown> = {
 			ordinal,
@@ -726,6 +738,9 @@ function attemptArtifactSnapshot(value: unknown): ReviewLaneAttemptArtifact | un
 		withOptional(snapshot, "forcedTermination", forcedTermination);
 		withOptional(snapshot, "deadlineMs", deadlineMs);
 		withOptional(snapshot, "configuredDeadlineMs", configuredDeadlineMs);
+		withOptional(snapshot, "budgetElapsedBeforeAttemptMs", budgetElapsedBeforeAttemptMs);
+		withOptional(snapshot, "batchRemainingBeforeAttemptMs", batchRemainingBeforeAttemptMs);
+		withOptional(snapshot, "totalRemainingBeforeAttemptMs", totalRemainingBeforeAttemptMs);
 		return Object.freeze(snapshot) as ReviewLaneAttemptArtifact;
 	} catch {
 		// A throwing getter is a malformed attempt, never a crash at this boundary.

package/lib/pr-review-deadlines.ts

@@ -105,6 +105,8 @@ export function resolveReviewDeadlines(user: unknown, project?: unknown): Deadli
 
 export interface ReviewBudget {
 	readonly startedAtMs: number;
+	/** First reviewer dispatch time. Undefined until the batch window is activated. */
+	readonly batchStartedAtMs?: number;
 	readonly totalDeadlineMs: number;
 	readonly batchDeadlineMs: number;
 	readonly config: ReviewDeadlineConfig;
@@ -130,6 +132,37 @@ export function createReviewBudget(
 	});
 }
 
+const activatedBatchBudgets = new WeakMap<ReviewBudget, ReviewBudget>();
+
+/**
+ * Start the reviewer-batch window once, at the first reviewer dispatch.
+ *
+ * PR binding, diff capture, and parent orchestration remain charged to the total
+ * invocation deadline, but no longer consume `batchMs` before a reviewer exists.
+ * The original synthesis and termination reserves remain hard upper bounds.
+ */
+export function activateReviewBatch(
+	budget: ReviewBudget,
+	now: MonotonicNow = monotonicNow,
+): ReviewBudget {
+	if (budget.batchStartedAtMs !== undefined) return budget;
+	const existing = activatedBatchBudgets.get(budget);
+	if (existing) return existing;
+	const batchStartedAtMs = now();
+	const terminationReserveMs = budget.config.terminationGraceMs + budget.config.cleanupReserveMs;
+	const batchDeadlineMs = Math.min(
+		batchStartedAtMs + budget.config.batchMs,
+		budget.totalDeadlineMs - budget.config.synthesisMs - terminationReserveMs,
+	);
+	const activated = Object.freeze({
+		...budget,
+		batchStartedAtMs,
+		batchDeadlineMs,
+	});
+	activatedBatchBudgets.set(budget, activated);
+	return activated;
+}
+
 export function attemptDeadline(
 	budget: ReviewBudget,
 	tier: ReviewTier,

package/lib/pr-review-publish.ts

@@ -7,6 +7,7 @@ import { monotonicNow, type MonotonicNow } from "./pr-review-telemetry.ts";
 
 export type PublishMode = "auto" | "force" | "disabled";
 export type ReviewMode = "quick" | "balanced" | "full" | "deep";
+export const REVIEW_MODES: readonly ReviewMode[] = ["quick", "balanced", "full", "deep"];
 export type AutoPostSource = "default" | "user" | "project";
 export type CompletionAction = "continue_tools" | "accept_final" | "clear_invocation";
 
@@ -30,6 +31,47 @@ export interface ApproveMaxPriorityLevelResolution {
 	readonly error?: string;
 }
 
+export interface ReviewModeResolution {
+	readonly value: ReviewMode;
+	readonly valid: boolean;
+	readonly source: AutoPostSource;
+	readonly error?: string;
+}
+
+function isReviewMode(value: unknown): value is ReviewMode {
+	return typeof value === "string" && REVIEW_MODES.includes(value as ReviewMode);
+}
+
+/** Resolve the default reviewer topology, with a trusted project overlaying user config. */
+export function resolveDefaultReviewModeSetting(
+	user: unknown,
+	trustedProject?: unknown,
+): ReviewModeResolution {
+	if (hasOwn(trustedProject, "defaultReviewMode")) {
+		const value = (trustedProject as { defaultReviewMode?: unknown }).defaultReviewMode;
+		return isReviewMode(value)
+			? { value, valid: true, source: "project" }
+			: {
+					value: "balanced",
+					valid: false,
+					source: "project",
+					error: `project defaultReviewMode must be one of: ${REVIEW_MODES.join(", ")}`,
+				};
+	}
+	if (hasOwn(user, "defaultReviewMode")) {
+		const value = (user as { defaultReviewMode?: unknown }).defaultReviewMode;
+		return isReviewMode(value)
+			? { value, valid: true, source: "user" }
+			: {
+					value: "balanced",
+					valid: false,
+					source: "user",
+					error: `user defaultReviewMode must be one of: ${REVIEW_MODES.join(", ")}`,
+				};
+	}
+	return { value: "balanced", valid: true, source: "default" };
+}
+
 function isValidApproveLevel(value: unknown): value is ApproveMaxPriorityLevel {
 	return value === "off" || (typeof value === "string" && APPROVE_PRIORITY_LEVELS.includes(value as (typeof APPROVE_PRIORITY_LEVELS)[number]));
 }
@@ -233,7 +275,15 @@ export function parsePublishMode(input: string): PublishModeParseResult {
 	return {
 		matched: true,
 		mode: disabled ? "disabled" : force ? "force" : "auto",
-		reviewMode: deep ? "deep" : full ? "full" : quick || majorOnly ? "quick" : "balanced",
+		...(deep
+			? { reviewMode: "deep" as const }
+			: full
+				? { reviewMode: "full" as const }
+				: quick || majorOnly
+					? { reviewMode: "quick" as const }
+					: balanced
+						? { reviewMode: "balanced" as const }
+						: {}),
 		prNumber: requested,
 		allowNonOpen: tokens.includes("--include-closed") || tokens.includes("--review-closed"),
 	};

package/package.json

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

package/prompts/pr-review.md

@@ -54,7 +54,7 @@ Arguments for this run: `$@`
 - `$1` is the PR number (required).
 - `--comment` explicitly requests one GitHub review for this run, even when automatic posting is disabled. A fully parsed, complete Markdown review may qualify for host-gated `APPROVE`; degraded Markdown remains `COMMENT`, and assistant text never directly selects the GitHub event.
 - `--no-comment` suppresses posting for this run, even when automatic posting is enabled.
-- With no review-mode flag, use the balanced five-reviewer default.
+- With no review-mode flag in the user's invocation, the host appends the configured default mode before expanding this prompt. The installation default is balanced.
 - `--quick` selects three P0–P2 reviewers; `--major-only` is its compatibility alias.
 - `--balanced` explicitly selects the five-reviewer default.
 - `--full` selects six all-severity reviewers, including conventions/maintainability.