@oh-my-pi/pi-coding-agent 17.0.0 → 17.0.2

package/src/tools/bash.ts

@@ -177,6 +177,8 @@ export interface BashToolDetails {
 	wallTimeMs?: number;
 	/** Exit code of a command that ran to completion but failed (non-zero). */
 	exitCode?: number;
+	/** True when the command was killed by its timeout deadline (not a failure). */
+	timedOut?: boolean;
 	terminalId?: string;
 	async?: {
 		state: "running" | "completed" | "failed";
@@ -208,10 +210,6 @@ function normalizeResultOutput(result: BashResult | BashInteractiveResult): stri
 	return result.output || "";
 }
 
-function isInteractiveResult(result: BashResult | BashInteractiveResult): result is BashInteractiveResult {
-	return "timedOut" in result;
-}
-
 function normalizeBashEnv(env: Record<string, string> | undefined): Record<string, string> | undefined {
 	if (!env || Object.keys(env).length === 0) return undefined;
 	const normalized: Record<string, string> = {};
@@ -439,12 +437,15 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 	}
 
 	/**
-	 * Throw for outcomes that are *not* a completed command: user/timeout
-	 * aborts and a missing exit status. The foreground and bridge callers plus
-	 * the async job manager rely on these throwing so cancellations surface as
-	 * aborts and jobs are recorded as failed. A definite non-zero exit is a
-	 * completed command that failed; #buildCompletedResult surfaces it as an
-	 * error *result* (carrying execution details) rather than a throw.
+	 * Throw for outcomes that are *not* a completed command: user aborts and a
+	 * missing exit status. Timeouts are handled separately by
+	 * #buildCompletedResult, which returns a non-throwing error result with
+	 * details.timedOut=true so the renderer can show a warning border. The
+	 * foreground and bridge callers plus the async job manager rely on these
+	 * throwing so cancellations surface as aborts and jobs are recorded as
+	 * failed. A definite non-zero exit is a completed command that failed;
+	 * #buildCompletedResult surfaces it as an error *result* (carrying
+	 * execution details) rather than a throw.
 	 */
 	#throwIfUnfinished(
 		result: BashResult | BashInteractiveResult,
@@ -452,13 +453,14 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 		outputText: string,
 	): void {
 		if (result.cancelled) {
-			// executeBash output already carries a `[Command cancelled]` notice from
-			// the sink; PTY/bridge interactive output does not, so annotate it here.
+			// Local executor output already carries a leading `[Command cancelled]`
+			// notice from the sink; PTY/bridge output does not, so annotate only
+			// the latter.
 			const out = normalizeResultOutput(result);
-			const annotated = isInteractiveResult(result) && out ? `${out}\n\n[Command aborted]` : out;
+			const annotated = out.startsWith("[Command cancelled]") ? out : out ? `${out}\n\n[Command aborted]` : out;
 			throw new ToolError(annotated || "Command aborted");
 		}
-		if (isInteractiveResult(result) && result.timedOut) {
+		if (result.timedOut === true) {
 			const out = normalizeResultOutput(result);
 			const message =
 				timeoutSec === undefined ? "Command timed out" : `Command timed out after ${timeoutSec} seconds`;
@@ -496,8 +498,12 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 		if (failedExit) outputLines.push("", formatExitCodeNotice(exitCode));
 		const outputText = outputLines.join("\n");
 
-		// Aborts / timeouts / missing-status still propagate as thrown errors.
-		this.#throwIfUnfinished(result, timeoutSec, outputText);
+		// Timeouts are not failures — the command ran its course. Return an error
+		// result (isError=true for the model) but flag timedOut so the renderer
+		// uses a warning border instead of error red. Both interactive and
+		// non-interactive results carry an explicit `timedOut` field from the
+		// executor/PTY layer.
+		const isTimeout = result.timedOut === true;
 
 		const details: BashToolDetails = {};
 		if (timeoutSec === undefined) {
@@ -517,6 +523,29 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 		if (failedExit) {
 			details.exitCode = exitCode;
 		}
+
+		if (isTimeout) {
+			details.timedOut = true;
+			const message =
+				timeoutSec === undefined ? "Command timed out" : `Command timed out after ${timeoutSec} seconds`;
+			// executeBash has already emitted this leading sink notice. PTY output
+			// has not, so provide the LLM-facing annotation exactly once.
+			if (!normalizeResultOutput(result).startsWith(`[${message}]\n`)) {
+				outputLines.push("", `[${message}]`);
+			}
+			const timeoutOutputText = await enforceInlineByteCap(outputLines.join("\n"), {
+				saveArtifact: full => saveBashOriginalArtifact(this.session, full),
+			});
+			return toolResult(details)
+				.text(timeoutOutputText)
+				.truncationFromSummary(result, { direction: "tail" })
+				.error()
+				.done();
+		}
+
+		// Non-timeout cancellations and missing exit status still propagate as thrown errors.
+		this.#throwIfUnfinished(result, timeoutSec, outputText);
+
 		// Final defense at the tool-result boundary: no bash path (client bridge,
 		// head-retention spill, minimizer miss) may emit more than
 		// ~DEFAULT_MAX_BYTES inline. No-op for already-bounded output.
@@ -992,12 +1021,8 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 								outputLines: current.output.length > 0 ? current.output.split("\n").length : 0,
 								outputBytes: current.output.length,
 							};
-							return this.#buildCompletedResult(timedOutResult, timeoutSec, {
-								requestedTimeoutSec,
-								notices: pendingNotices,
-								terminalId: handle.terminalId,
-								wallTimeMs: performance.now() - bridgeWallTimeStart,
-							});
+							this.#throwIfUnfinished(timedOutResult, timeoutSec, this.#formatResultOutput(timedOutResult));
+							throw new ToolError("Command timed out");
 						}
 
 						if (raced.kind === "exit") {
@@ -1102,20 +1127,27 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 				});
 		const wallTimeMs = performance.now() - wallTimeStart;
 		if (result.cancelled) {
-			const out = normalizeResultOutput(result);
-			// PTY output carries no cancel/timeout notice of its own; annotate so
-			// the model can tell an abort from a plain failure.
-			const message = isInteractiveResult(result) && out ? `${out}\n\n[Command aborted]` : out || "Command aborted";
-			if (signal?.aborted) {
-				throw new ToolAbortError(message);
+			// A cancelled result is either a timeout (the command's deadline fired)
+			// or a user/system abort. Timeouts are handled by #buildCompletedResult
+			// which returns a non-throwing error result with details.timedOut=true
+			// so the renderer can show a warning border instead of error red.
+			// Both interactive and non-interactive results carry an explicit
+			// `timedOut` field from the executor/PTY layer.
+			const isTimeout = result.timedOut === true;
+			if (!isTimeout) {
+				const out = normalizeResultOutput(result);
+				// The local executor already prepends `[Command cancelled]`; PTY
+				// output does not, so preserve one cancellation notice in either case.
+				const message = out.startsWith("[Command cancelled]")
+					? out
+					: out
+						? `${out}\n\n[Command aborted]`
+						: "Command aborted";
+				if (signal?.aborted) {
+					throw new ToolAbortError(message);
+				}
+				throw new ToolError(message);
 			}
-			throw new ToolError(message);
-		}
-		if (isInteractiveResult(result) && result.timedOut) {
-			const out = normalizeResultOutput(result);
-			const message =
-				timeoutSec === undefined ? "Command timed out" : `Command timed out after ${timeoutSec} seconds`;
-			throw new ToolError(out ? `${out}\n\n[${message}]` : message);
 		}
 		return this.#buildCompletedResult(result, timeoutSec, {
 			requestedTimeoutSec,
@@ -1253,6 +1285,8 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 			const isError = result.isError === true;
 			const isPartial = options.isPartial === true;
 			const success = !isPartial && !isError;
+			const details = result.details;
+			const isTimeout = details?.timedOut === true;
 			const header =
 				config.showHeader === false
 					? undefined
@@ -1263,12 +1297,11 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 										title: config.resolveTitle(args, options),
 									}
 								: {
-										icon: isPartial ? "pending" : "error",
+										icon: isPartial ? "pending" : isTimeout ? "warning" : "error",
 										title: config.resolveTitle(args, options),
 									},
 							uiTheme,
 						);
-			const details = result.details;
 			const outputBlock = new CachedOutputBlock();
 
 			// Per-instance cache for the expensive inner lines computation. Mirrors
@@ -1408,7 +1441,7 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 					const framed = outputBlock.render(
 						{
 							header,
-							state: isPartial ? "pending" : isError ? "error" : "success",
+							state: isPartial ? "pending" : isError ? (isTimeout ? "warning" : "error") : "success",
 							sections: [
 								{
 									// Viewport-sized tail window in every state — streaming and final

package/src/tools/browser/registry.ts

@@ -47,6 +47,13 @@ export interface CmuxBrowserHandle extends BrowserHandleCommon {
 
 export type BrowserHandle = PuppeteerBrowserHandle | CmuxBrowserHandle;
 
+/** Controls bounded browser-handle teardown and identifies the owning resource in timeout diagnostics. */
+export interface ReleaseBrowserOptions {
+	kill: boolean;
+	timeoutMs?: number;
+	resource?: string;
+}
+
 const browsers = new Map<string, BrowserHandle>();
 
 function browserKey(kind: BrowserKind): string {
@@ -221,7 +228,7 @@ export function holdBrowser(handle: BrowserHandle): void {
 	handle.refCount++;
 }
 
-export async function releaseBrowser(handle: BrowserHandle, opts: { kill: boolean }): Promise<void> {
+export async function releaseBrowser(handle: BrowserHandle, opts: ReleaseBrowserOptions): Promise<void> {
 	handle.refCount = Math.max(0, handle.refCount - 1);
 	if (handle.refCount === 0) {
 		// Only evict if the registry still points at THIS handle. After a disconnect,
@@ -232,7 +239,7 @@ export async function releaseBrowser(handle: BrowserHandle, opts: { kill: boolea
 	}
 }
 
-async function disposeBrowserHandle(handle: BrowserHandle, opts: { kill: boolean }): Promise<void> {
+async function disposeBrowserHandle(handle: BrowserHandle, opts: ReleaseBrowserOptions): Promise<void> {
 	if ("client" in handle) {
 		handle.client.close();
 		return;

package/src/tools/browser/tab-supervisor.ts

@@ -1,4 +1,4 @@
-import { getPuppeteerDir, logger, postmortem, Snowflake, workerHostEntry } from "@oh-my-pi/pi-utils";
+import { getPuppeteerDir, logger, postmortem, Snowflake, withTimeout, workerHostEntry } from "@oh-my-pi/pi-utils";
 import type { Page, Target } from "puppeteer-core";
 import { callSessionTool } from "../../eval/js/tool-bridge";
 import { webpExclusionForModel } from "../../utils/image-loading";
@@ -123,6 +123,8 @@ export interface RunInTabOptions {
 
 export interface ReleaseTabOptions {
 	kill?: boolean;
+	/** Maximum time for each asynchronous cleanup resource before close fails with diagnostics. */
+	timeoutMs?: number;
 }
 
 const tabs = new Map<string, TabSession>();
@@ -135,6 +137,22 @@ const GRACE_MS = 750;
 // mapped to the kill reason. Lets the next `run` on that name explain WHY the tab
 // vanished instead of a bare "not alive". Cleared when the name is opened again.
 const killedTabs = new Map<string, string>();
+const DEFAULT_TAB_CLOSE_TIMEOUT_MS = 5_000;
+
+async function waitForTabCleanup<T>(
+	tab: TabSession,
+	timeoutMs: number,
+	pendingResource: string,
+	promise: Promise<T>,
+): Promise<T> {
+	const message = `Timed out after ${timeoutMs}ms closing ${tab.kindTag} browser tab ${JSON.stringify(tab.name)}; pending resource: ${pendingResource}`;
+	try {
+		return await withTimeout(promise, timeoutMs, message);
+	} catch (error) {
+		if (error instanceof Error && error.message === message) throw new ToolError(message);
+		throw error;
+	}
+}
 
 export function getTab(name: string): TabSession | undefined {
 	return tabs.get(name);
@@ -519,26 +537,42 @@ export async function releaseTab(name: string, opts: ReleaseTabOptions = {}): Pr
 		pending.reject(closeError);
 	}
 	tab.pending.clear();
+	const timeoutMs = opts.timeoutMs ?? DEFAULT_TAB_CLOSE_TIMEOUT_MS;
 	if (tab.backend === "cmux") {
-		let nonLastCloseError: unknown;
+		let closeError: unknown;
 		if (wasAlive && tab.cmuxOwnsSurface) {
 			try {
-				await tab.browser.client.request("surface.close", { surface_id: tab.targetId });
+				await waitForTabCleanup(
+					tab,
+					timeoutMs,
+					`cmux surface ${JSON.stringify(tab.targetId)} (surface.close)`,
+					tab.browser.client.request("surface.close", { surface_id: tab.targetId }, { timeoutMs }),
+				);
 			} catch (err) {
 				if (isLastSurfaceCloseError(err)) {
 					logger.debug("Leaving cmux browser surface open because it is the last surface in the workspace", {
 						error: err instanceof Error ? err.message : String(err),
 					});
 				} else {
-					nonLastCloseError = err;
+					closeError = err;
 				}
 			}
 		}
-		await releaseBrowser(tab.browser, { kill: opts.kill ?? false });
-		tabs.delete(name);
-		if (nonLastCloseError) throw nonLastCloseError;
+		try {
+			await releaseBrowser(tab.browser, {
+				kill: opts.kill ?? false,
+				timeoutMs,
+				resource: `tab ${JSON.stringify(name)}`,
+			});
+		} catch (error) {
+			closeError ??= error;
+		} finally {
+			tabs.delete(name);
+		}
+		if (closeError) throw closeError;
 		return true;
 	}
+	let cleanupError: unknown;
 	let forced = false;
 	if (wasAlive) {
 		try {
@@ -549,9 +583,30 @@ export async function releaseTab(name: string, opts: ReleaseTabOptions = {}): Pr
 		}
 	}
 	await tab.worker.terminate().catch(() => undefined);
-	if (forced && tab.kindTag === "headless") await closeOrphanTarget(tab);
-	await releaseBrowser(tab.browser, { kill: opts.kill ?? false });
-	tabs.delete(name);
+	if (forced && tab.kindTag === "headless") {
+		try {
+			await waitForTabCleanup(
+				tab,
+				timeoutMs,
+				`orphan CDP target ${JSON.stringify(tab.targetId)} (Page.close)`,
+				closeOrphanTarget(tab),
+			);
+		} catch (error) {
+			cleanupError = error;
+		}
+	}
+	try {
+		await releaseBrowser(tab.browser, {
+			kill: opts.kill ?? false,
+			timeoutMs,
+			resource: `tab ${JSON.stringify(name)}`,
+		});
+	} catch (error) {
+		cleanupError ??= error;
+	} finally {
+		tabs.delete(name);
+	}
+	if (cleanupError) throw cleanupError;
 	return true;
 }
 

package/src/tools/browser.ts

@@ -199,7 +199,7 @@ export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolD
 				case "open":
 					return await this.#open(name, params, details, timeoutMs, signal);
 				case "close":
-					return await this.#close(name, params, details, signal);
+					return await this.#close(name, params, details, timeoutMs, signal);
 				case "run":
 					return await this.#run(name, params, details, timeoutMs, signal);
 				default:
@@ -284,15 +284,16 @@ export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolD
 		name: string,
 		params: BrowserParams,
 		details: BrowserToolDetails,
+		timeoutMs: number,
 		signal?: AbortSignal,
 	): Promise<AgentToolResult<BrowserToolDetails>> {
 		const kill = !!params.kill;
 		if (params.all) {
-			const count = await untilAborted(signal, () => releaseAllTabs({ kill }));
+			const count = await untilAborted(signal, () => releaseAllTabs({ kill, timeoutMs }));
 			details.result = `Closed ${count} tab(s)`;
 			return toolResult(details).text(details.result).done();
 		}
-		const closed = await untilAborted(signal, () => releaseTab(name, { kill }));
+		const closed = await untilAborted(signal, () => releaseTab(name, { kill, timeoutMs }));
 		details.result = closed ? `Closed tab ${JSON.stringify(name)}` : `No tab named ${JSON.stringify(name)}`;
 		return toolResult(details).text(details.result).done();
 	}

package/src/tools/essential-tools.ts

@@ -0,0 +1,45 @@
+/**
+ * Canonical set of built-in tools that must stay top-level.
+ *
+ * These are the coding essentials the model always needs directly in its
+ * callable schema. `read`/`write` are additionally the `xd://` transport
+ * (`read xd://` lists devices, `write xd://<tool>` executes them), so demoting
+ * them under xdev makes every mounted device unreachable.
+ *
+ * Adapter boundaries (extension `registerTool`, SDK custom tools, RPC host
+ * tools) default an omitted `loadMode` to `"discoverable"`. A UI-only
+ * re-register of a built-in — e.g. wrapping `read`/`write`/`bash`/`edit`/`glob`
+ * to customize rendering — would then silently demote it to `discoverable` and,
+ * with `tools.xdev` on, unmount it from the top-level schema (issue #5764).
+ * {@link defaultLoadModeForToolName} pins these names to `"essential"` when the
+ * definition omits `loadMode`, so re-registering a built-in never demotes it.
+ */
+import type { ToolLoadMode } from "@oh-my-pi/pi-agent-core";
+
+/**
+ * Built-in tool names whose classes declare `loadMode = "essential"`. Kept in
+ * sync with the tool classes by `essential-tools.test.ts` (drift guard).
+ */
+export const ESSENTIAL_BUILTIN_TOOL_NAMES: Record<string, true> = {
+	read: true,
+	write: true,
+	bash: true,
+	edit: true,
+	glob: true,
+	eval: true,
+	task: true,
+	hub: true,
+	learn: true,
+	manage_skill: true,
+};
+
+/**
+ * Resolve a tool's presentation mode at an adapter boundary. An explicit
+ * `declared` mode always wins. When omitted, known essential built-in names
+ * default to `"essential"` (so a re-register never demotes them); everything
+ * else defaults to `"discoverable"`.
+ */
+export function defaultLoadModeForToolName(name: string, declared?: ToolLoadMode): ToolLoadMode {
+	if (declared) return declared;
+	return name in ESSENTIAL_BUILTIN_TOOL_NAMES ? "essential" : "discoverable";
+}

package/src/tools/eval.ts

@@ -768,5 +768,8 @@ async function summarizeFinal(
 		outputLines,
 		outputBytes,
 		artifactId: rawSummary.artifactId,
+		columnDroppedBytes: rawSummary.columnDroppedBytes,
+		columnTruncatedLines: rawSummary.columnTruncatedLines,
+		columnMax: rawSummary.columnMax,
 	};
 }

package/src/tools/gh.ts

@@ -10,7 +10,7 @@ import type {
 	ToolApprovalDecision,
 } from "@oh-my-pi/pi-agent-core";
 
-import { getWorktreeDir, hashPath, isEnoent, prompt, untilAborted } from "@oh-my-pi/pi-utils";
+import { getWorktreeDir, hashPath, isEnoent, logger, prompt, untilAborted } from "@oh-my-pi/pi-utils";
 import { type } from "arktype";
 import type { Settings } from "../config/settings";
 import githubDescription from "../prompts/tools/github.md" with { type: "text" };
@@ -239,6 +239,8 @@ const RUN_WATCH_TAIL_DEFAULT = 15;
 const RUN_WATCH_TAIL_MAX = 200;
 const REVIEW_COMMENTS_PAGE_SIZE = 100;
 const RUN_JOBS_PAGE_SIZE = 100;
+const PR_DIFF_FILES_PAGE_SIZE = 100;
+const PR_DIFF_FILES_MAX = 3000;
 const PR_URL_PATTERN = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/pull\/(\d+)(?:\/.*)?$/;
 const ISSUE_URL_PATTERN = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/issues\/(\d+)(?:\/.*)?$/;
 const RUN_URL_PATTERN = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/actions\/runs\/(\d+)(?:\/.*)?$/;
@@ -2931,6 +2933,160 @@ function parsePrDiffSection(section: string, startOffset: number, endOffset: num
 	return file;
 }
 
+/**
+ * A single entry from `GET /repos/{owner}/{repo}/pulls/{n}/files`. `patch` is
+ * absent for binary files and for individual file diffs GitHub deems too large
+ * to render.
+ */
+interface GhPrFileApi {
+	filename?: string;
+	previous_filename?: string;
+	status?: string;
+	additions?: number;
+	deletions?: number;
+	patch?: string;
+}
+
+interface GhPrApi {
+	changed_files?: number;
+}
+
+/**
+ * GitHub rejects the aggregate PR diff endpoint with HTTP 406 once the diff
+ * exceeds 20,000 lines. Detect that specific failure so the caller can fall
+ * back to the per-file endpoint instead of aborting the whole review.
+ */
+function isPrDiffTooLargeError(err: unknown): boolean {
+	const message = err instanceof Error ? err.message : String(err);
+	return (
+		/\bHTTP 406\b/.test(message) ||
+		/exceeded the maximum number of lines/i.test(message) ||
+		/\btoo_large\b/.test(message)
+	);
+}
+
+function formatSyntheticDiffPath(prefix: "a/" | "b/", path: string): string {
+	const prefixedPath = `${prefix}${path}`;
+	if (!/[\u0000-\u001F\s"\\]/.test(prefixedPath)) return prefixedPath;
+
+	let escaped = "";
+	for (const char of prefixedPath) {
+		switch (char) {
+			case "\\":
+				escaped += "\\\\";
+				break;
+			case '"':
+				escaped += '\\"';
+				break;
+			case "\n":
+				escaped += "\\n";
+				break;
+			case "\r":
+				escaped += "\\r";
+				break;
+			case "\t":
+				escaped += "\\t";
+				break;
+			default: {
+				const code = char.charCodeAt(0);
+				escaped += code < 32 ? `\\${code.toString(8).padStart(3, "0")}` : char;
+			}
+		}
+	}
+	return `"${escaped}"`;
+}
+
+/**
+ * Reconstruct a `diff --git` section from a single files-API entry. The API's
+ * `patch` field carries only the hunk body, so the `diff --git`/`---`/`+++`
+ * headers are synthesized to match `gh pr diff` output — this keeps
+ * {@link parsePrUnifiedDiff} and the review parser producing identical section
+ * boundaries and byte offsets. Files whose `patch` is omitted (binary or
+ * too-large) stay visible with an explicit marker rather than being dropped.
+ */
+function buildSyntheticDiffSection(file: GhPrFileApi): string | undefined {
+	const newPath = file.filename;
+	if (!newPath) return undefined;
+	const status = file.status ?? "modified";
+	const oldPath = file.previous_filename ?? newPath;
+	const oldDiffPath = formatSyntheticDiffPath("a/", oldPath);
+	const newDiffPath = formatSyntheticDiffPath("b/", newPath);
+	const lines: string[] = [`diff --git ${oldDiffPath} ${newDiffPath}`];
+	if (status === "added") {
+		lines.push("new file mode 100644");
+	} else if (status === "removed") {
+		lines.push("deleted file mode 100644");
+	} else if (status === "renamed" || file.previous_filename) {
+		lines.push(`rename from ${oldPath}`, `rename to ${newPath}`);
+	}
+	if (typeof file.patch === "string" && file.patch.length > 0) {
+		lines.push(status === "added" ? "--- /dev/null" : `--- ${oldDiffPath}`);
+		lines.push(status === "removed" ? "+++ /dev/null" : `+++ ${newDiffPath}`);
+		lines.push(file.patch);
+	} else {
+		lines.push(
+			`* patch unavailable (binary or too large); additions ${file.additions ?? 0}, deletions ${file.deletions ?? 0}`,
+		);
+	}
+	return lines.join("\n");
+}
+
+/**
+ * Fallback PR diff retrieval via the paginated per-file endpoint, used when the
+ * aggregate `gh pr diff` is rejected for exceeding GitHub's 20,000-line limit.
+ * The per-file patches are not subject to that aggregate cap, so even very
+ * large PRs can be reassembled into a synthetic unified diff.
+ */
+async function fetchPrDiffViaFilesApi(
+	cwd: string,
+	repo: string,
+	number: number,
+	signal: AbortSignal | undefined,
+): Promise<string> {
+	const pull = await git.github.json<GhPrApi>(
+		cwd,
+		["api", "--method", "GET", `/repos/${repo}/pulls/${number}`],
+		signal,
+		{ repoProvided: true },
+	);
+	if ((pull.changed_files ?? 0) > PR_DIFF_FILES_MAX) {
+		throw new ToolError(
+			`Pull request changes ${pull.changed_files} files, exceeding GitHub's ${PR_DIFF_FILES_MAX}-file limit for the per-file diff API.`,
+		);
+	}
+
+	const sections: string[] = [];
+	let page = 1;
+	while (true) {
+		const response = await git.github.json<GhPrFileApi[]>(
+			cwd,
+			[
+				"api",
+				"--method",
+				"GET",
+				`/repos/${repo}/pulls/${number}/files`,
+				"-F",
+				`per_page=${PR_DIFF_FILES_PAGE_SIZE}`,
+				"-F",
+				`page=${page}`,
+			],
+			signal,
+			{ repoProvided: true },
+		);
+		for (const file of response) {
+			const section = buildSyntheticDiffSection(file);
+			if (section) sections.push(section);
+		}
+		if (response.length < PR_DIFF_FILES_PAGE_SIZE) {
+			break;
+		}
+		page += 1;
+	}
+	// Trailing newline mirrors `gh pr diff` so downstream parsers splitting on
+	// `^diff --git ` see identical boundaries.
+	return sections.length > 0 ? `${sections.join("\n")}\n` : "";
+}
+
 async function fetchPrDiffFresh(
 	cwd: string,
 	repo: string,
@@ -2939,7 +3095,18 @@ async function fetchPrDiffFresh(
 ): Promise<{ rendered: string; sourceUrl: string | undefined; payload: PrDiffPayload }> {
 	const args = ["pr", "diff", String(number), "--color", "never"];
 	appendRepoFlag(args, repo, String(number));
-	const text = await git.github.text(cwd, args, signal, { repoProvided: true, trimOutput: false });
+	let text: string;
+	try {
+		text = await git.github.text(cwd, args, signal, { repoProvided: true, trimOutput: false });
+	} catch (err) {
+		if (!isPrDiffTooLargeError(err)) throw err;
+		logger.debug("gh pr diff exceeded GitHub's aggregate line limit; falling back to per-file API", {
+			repo,
+			number,
+			err: String(err),
+		});
+		text = await fetchPrDiffViaFilesApi(cwd, repo, number, signal);
+	}
 	const payload = parsePrUnifiedDiff(text);
 	// `rendered` already carries the verbatim diff; blank the payload copy so
 	// the cache row stores a potentially huge diff once instead of twice.