@oh-my-pi/pi-coding-agent 15.10.10 → 15.10.11

package/src/tools/write.ts

@@ -25,6 +25,8 @@ import { parseArchivePathCandidates } from "./archive-reader";
 import { assertEditableFile } from "./auto-generated-guard";
 import {
 	type ConflictEntry,
+	conflictRegionPresent,
+	conflictRegionsEqual,
 	expandContentTokens,
 	getConflictHistory,
 	parseConflictUri,
@@ -39,6 +41,7 @@ import {
 	formatErrorDetail,
 	formatExpandHint,
 	formatMoreItems,
+	formatStatusIcon,
 	getLspBatchRequest,
 	replaceTabs,
 	shortenPath,
@@ -266,7 +269,14 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 	readonly name = "write";
 	readonly approval = (args: unknown) => {
 		const rawPath = (args as Partial<WriteParams>).path;
-		return typeof rawPath === "string" && isInternalUrlPath(rawPath) ? "read" : "write";
+		if (typeof rawPath !== "string" || !isInternalUrlPath(rawPath)) return "write";
+		// Internal URLs are usually session-local artifacts (read tier), but a
+		// scheme whose handler exposes a `write` hook mutates handler-owned
+		// user data (e.g. vault:// notes, host-owned mcp:// URIs) and must take
+		// the write tier so always-ask mode actually prompts.
+		const match = /^([a-z][a-z0-9+.-]*):\/\//i.exec(rawPath.trim());
+		const handler = match ? InternalUrlRouter.instance().getHandler(match[1]!.toLowerCase()) : undefined;
+		return handler?.write ? "write" : "read";
 	};
 	readonly formatApprovalDetails = (args: unknown): string[] => {
 		const params = args as Partial<WriteParams>;
@@ -349,7 +359,18 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 		content: string,
 		resolvedArchivePath: ResolvedArchiveWritePath,
 	): Promise<AgentToolResult<WriteToolDetails>> {
-		const isZip = resolvedArchivePath.absolutePath.toLowerCase().endsWith(".zip");
+		// Resolve symlinks before the tmp+rename swap: renaming over a symlink
+		// replaces the link itself with a regular file instead of writing
+		// through to its target.
+		const finalPath = resolvedArchivePath.exists
+			? await fs.realpath(resolvedArchivePath.absolutePath).catch(() => resolvedArchivePath.absolutePath)
+			: resolvedArchivePath.absolutePath;
+		const lowerPath = finalPath.toLowerCase();
+		const isZip = lowerPath.endsWith(".zip");
+		const isGzip = lowerPath.endsWith(".tar.gz") || lowerPath.endsWith(".tgz");
+		// Rewrites are whole-archive: write to a temp file and rename so a
+		// crash/disk-full mid-write can't destroy the original archive.
+		const tmpPath = `${finalPath}.tmp-${process.pid}`;
 
 		const parentDir = path.dirname(resolvedArchivePath.absolutePath);
 		if (parentDir && parentDir !== ".") {
@@ -377,8 +398,10 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 			try {
 				const { zipSync } = await loadFflate();
 				const zipBuffer = zipSync(zipEntries);
-				await Bun.write(resolvedArchivePath.absolutePath, zipBuffer);
+				await Bun.write(tmpPath, zipBuffer);
+				await fs.rename(tmpPath, finalPath);
 			} catch (error) {
+				await fs.rm(tmpPath, { force: true }).catch(() => {});
 				throw new ToolError(error instanceof Error ? error.message : String(error));
 			}
 		} else {
@@ -406,8 +429,12 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 			archiveEntries[resolvedArchivePath.archiveSubPath] = content;
 
 			try {
-				await Bun.Archive.write(resolvedArchivePath.absolutePath, archiveEntries);
+				// `Bun.Archive.write` never infers compression from the extension;
+				// request gzip explicitly so `.tar.gz`/`.tgz` stay compressed.
+				await Bun.Archive.write(tmpPath, archiveEntries, isGzip ? { compress: "gzip" } : undefined);
+				await fs.rename(tmpPath, finalPath);
 			} catch (error) {
+				await fs.rm(tmpPath, { force: true }).catch(() => {});
 				throw new ToolError(error instanceof Error ? error.message : String(error));
 			}
 		}
@@ -583,7 +610,24 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 		invalidateFsScanAfterWrite(absolutePath);
 		this.session.bumpFileMutationVersion?.(absolutePath);
 		this.session.fileSnapshotStore?.invalidate(absolutePath);
-		this.session.conflictHistory?.invalidate(entry.id);
+		const history = this.session.conflictHistory;
+		history?.invalidate(entry.id);
+		if (history) {
+			// Drop stale duplicate registrations of the same region: a re-read
+			// after an out-of-band shift registers a fresh id at the new
+			// startLine while the stale twin persists at the old one. A DISTINCT
+			// conflict block that is merely byte-identical still occurs in the
+			// post-splice content and must stay addressable.
+			for (const other of history.entries()) {
+				if (
+					other.absolutePath === absolutePath &&
+					conflictRegionsEqual(other, entry) &&
+					!conflictRegionPresent(newContent, other)
+				) {
+					history.invalidate(other.id);
+				}
+			}
+		}
 
 		const header = maybeWriteSnapshotHeader(this.session, absolutePath, newContent);
 		const range =
@@ -690,17 +734,41 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 			fileEntries.sort((a, b) => b.startLine - a.startLine);
 
 			let text: string;
+			const resolvedEntries: ConflictEntry[] = [];
+			const staleEntries: ConflictEntry[] = [];
+			let failure: string | undefined;
 			try {
 				text = await Bun.file(absolutePath).text();
-				for (const entry of fileEntries) {
+			} catch (error) {
+				failedFiles.push({
+					displayPath: sample.displayPath,
+					count: fileEntries.length,
+					error: error instanceof Error ? error.message : String(error),
+				});
+				continue;
+			}
+			for (const entry of fileEntries) {
+				try {
 					const expanded = expandContentTokens(replacementContent, entry);
 					text = spliceConflict(text, entry, expanded);
+					resolvedEntries.push(entry);
+				} catch (error) {
+					// A locate-miss for a region an earlier entry already spliced
+					// in this pass is a stale duplicate registration (re-read after
+					// an out-of-band shift) — treat it as already resolved.
+					if (resolvedEntries.some(done => conflictRegionsEqual(done, entry))) {
+						staleEntries.push(entry);
+						continue;
+					}
+					failure = error instanceof Error ? error.message : String(error);
+					break;
 				}
-			} catch (error) {
+			}
+			if (failure !== undefined) {
 				failedFiles.push({
 					displayPath: sample.displayPath,
 					count: fileEntries.length,
-					error: error instanceof Error ? error.message : String(error),
+					error: failure,
 				});
 				continue;
 			}
@@ -709,10 +777,11 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 			invalidateFsScanAfterWrite(absolutePath);
 			this.session.bumpFileMutationVersion?.(absolutePath);
 			this.session.fileSnapshotStore?.invalidate(absolutePath);
-			for (const entry of fileEntries) history.invalidate(entry.id);
+			for (const entry of resolvedEntries) history.invalidate(entry.id);
+			for (const entry of staleEntries) history.invalidate(entry.id);
 			const header = maybeWriteSnapshotHeader(this.session, absolutePath, text);
-			succeededFiles.push({ displayPath: sample.displayPath, count: fileEntries.length, header });
-			totalResolvedIds += fileEntries.length;
+			succeededFiles.push({ displayPath: sample.displayPath, count: resolvedEntries.length, header });
+			totalResolvedIds += resolvedEntries.length;
 			if (diagnostics) allDiagnostics.push(diagnostics);
 		}
 
@@ -751,7 +820,11 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 			if (failedFiles.length > 0 && succeededFiles.length === 0) {
 				throw new ToolError(resultText);
 			}
-			return { content: [{ type: "text", text: resultText }], details: {} };
+			return {
+				content: [{ type: "text", text: resultText }],
+				details: {},
+				isError: failedFiles.length > 0 ? true : undefined,
+			};
 		}
 		const mergedSummary = allDiagnostics.map(d => d.summary).join("\n");
 		const mergedMessages = allDiagnostics.flatMap(d => d.messages ?? []);
@@ -760,6 +833,7 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 			details: {
 				meta: outputMeta().diagnostics(mergedSummary, mergedMessages).get(),
 			},
+			isError: failedFiles.length > 0 ? true : undefined,
 		};
 	}
 
@@ -784,6 +858,9 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 				const scheme = parsed.protocol.replace(/:$/, "").toLowerCase();
 				const handler = internalRouter.getHandler(scheme);
 				if (handler?.write) {
+					// Handler-owned writes (vault:// notes, host URIs) mutate user
+					// data outside the local sandbox — plan mode must reject them.
+					enforcePlanModeWrite(this.session, path, { op: "update" });
 					await handler.write(parsed, cleanContent, { cwd: this.session.cwd, signal });
 					let resultText = `Successfully wrote ${cleanContent.length} bytes to ${path}`;
 					if (stripped) {
@@ -872,6 +949,8 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 					throw new ToolError(error instanceof Error ? error.message : String(error));
 				}
 				invalidateFsScanAfterWrite(absolutePath);
+				this.session.bumpFileMutationVersion?.(absolutePath);
+				const madeExecutable = await maybeMarkExecutableForShebang(absolutePath, cleanContent);
 				const displayPath = formatPathRelativeToCwd(absolutePath, this.session.cwd);
 				const header = maybeWriteSnapshotHeader(this.session, absolutePath, cleanContent);
 				const writeLine = `Successfully wrote ${cleanContent.length} bytes to ${displayPath}`;
@@ -881,7 +960,7 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 				}
 				return {
 					content: [{ type: "text", text: resultText }],
-					details: { resolvedPath: absolutePath },
+					details: { resolvedPath: absolutePath, madeExecutable: madeExecutable || undefined },
 				};
 			}
 
@@ -946,11 +1025,23 @@ function normalizeDisplayText(text: string): string {
 	return text.replace(/\r/g, "");
 }
 
+/**
+ * Minimum line-number gutter width for write previews. The streaming preview's
+ * gutter must stay byte-stable as the line count grows: a width derived purely
+ * from `String(totalLines).length` widens at the 10/100/1000-line crossings,
+ * rewriting every already-rendered row — which forces the transcript's commit
+ * audit to recommit the block's committed prefix (a full duplicate in native
+ * scrollback). Reserving 3 digits keeps the gutter constant through 999 lines
+ * and keeps the streamed rows byte-identical to the final result render.
+ */
+const WRITE_GUTTER_MIN_WIDTH = 3;
+
 function formatStreamingContent(
 	content: string,
 	expanded: boolean,
 	language: string | undefined,
 	uiTheme: Theme,
+	spinnerFrame?: number,
 ): string {
 	if (!content) return "";
 	const lines = normalizeDisplayText(content).split("\n");
@@ -963,7 +1054,7 @@ function formatStreamingContent(
 	const visibleLines = lines.slice(startIndex);
 	const hidden = startIndex;
 	const highlighted = highlightCode(visibleLines.join("\n"), language);
-	const lineNumberWidth = String(totalLines).length;
+	const lineNumberWidth = Math.max(WRITE_GUTTER_MIN_WIDTH, String(totalLines).length);
 
 	let text = "\n\n";
 	if (hidden > 0) {
@@ -975,7 +1066,12 @@ function formatStreamingContent(
 		const body = replaceTabs(highlighted[i] ?? "");
 		text += `${gutter}${body}\n`;
 	}
-	text += uiTheme.fg("dim", `… (streaming)`);
+	// The animated glyph lives on this trailing line — inside the transcript's
+	// volatile-tail holdback — never in the header: an animating head row pins
+	// the native-scrollback commit boundary at the top of the block, so a long
+	// expanded preview could never scroll-append mid-stream.
+	const spinner = spinnerFrame !== undefined ? `${formatStatusIcon("running", uiTheme, spinnerFrame)} ` : "";
+	text += `${spinner}${uiTheme.fg("dim", `… (streaming)`)}`;
 	return text;
 }
 
@@ -991,7 +1087,7 @@ function renderContentPreview(
 	const maxLines = expanded ? totalLines : Math.min(totalLines, WRITE_PREVIEW_LINES);
 	const visibleLines = rawLines.slice(0, maxLines);
 	const highlighted = highlightCode(visibleLines.join("\n"), language);
-	const lineNumberWidth = String(maxLines).length;
+	const lineNumberWidth = Math.max(WRITE_GUTTER_MIN_WIDTH, String(totalLines).length);
 	const hidden = totalLines - maxLines;
 
 	let text = "\n\n";
@@ -1016,10 +1112,14 @@ export const writeToolRenderer = {
 		const lang = getLanguageFromPath(rawPath) ?? "text";
 		const langIcon = uiTheme.fg("muted", uiTheme.getLangIcon(lang));
 		const pathDisplay = filePath ? uiTheme.fg("accent", filePath) : uiTheme.fg("toolOutput", "…");
+		// Static pending icon, never the animated glyph: the header is the head
+		// row of the framed block, and native-scrollback commits are prefix-only
+		// — an animating head row would pin the commit boundary at the top and
+		// keep a tall expanded preview from scroll-appending mid-stream. The
+		// liveness cue rides the trailing "(streaming)" line instead.
 		const header = renderStatusLine(
 			{
 				icon: "pending",
-				spinnerFrame: options?.spinnerFrame,
 				title: "Write",
 				description: `${langIcon} ${pathDisplay}`,
 			},
@@ -1027,7 +1127,7 @@ export const writeToolRenderer = {
 		);
 		return framedBlock(uiTheme, width => {
 			const body = args.content
-				? formatStreamingContent(args.content, Boolean(options?.expanded), lang, uiTheme)
+				? formatStreamingContent(args.content, Boolean(options?.expanded), lang, uiTheme, options?.spinnerFrame)
 				: "";
 			const bodyLines = body ? body.split("\n") : [];
 			while (bodyLines.length > 0 && bodyLines[0].trim() === "") bodyLines.shift();

package/src/tui/output-block.ts

@@ -13,7 +13,7 @@ export interface OutputBlockOptions {
 	header?: string;
 	headerMeta?: string;
 	state?: State;
-	sections?: Array<{ label?: string; lines: string[]; separator?: boolean }>;
+	sections?: Array<{ label?: string; lines: readonly string[]; separator?: boolean }>;
 	width: number;
 	applyBg?: boolean;
 	contentPaddingLeft?: number;
@@ -186,8 +186,8 @@ export function renderOutputBlock(options: OutputBlockOptions, theme: Theme): st
 export class CachedOutputBlock {
 	#cache?: RenderCache;
 
-	/** Render with caching. Returns cached result if options haven't changed. */
-	render(options: OutputBlockOptions, theme: Theme): string[] {
+	/** Render with caching. Returns the cached (shared, caller-immutable) lines if options haven't changed. */
+	render(options: OutputBlockOptions, theme: Theme): readonly string[] {
 		const key = this.#buildKey(options);
 		if (this.#cache?.key === key) return this.#cache.lines;
 		const lines = renderOutputBlock(options, theme);
@@ -234,7 +234,7 @@ export function framedBlock(theme: Theme, build: (width: number) => OutputBlockO
 	// flush, no extra padding/background) the same way `markFramedBlockComponent`
 	// blocks are treated.
 	return markFramedBlockComponent({
-		render: (width: number): string[] => block.render(build(width), theme),
+		render: (width: number): readonly string[] => block.render(build(width), theme),
 		invalidate: () => block.invalidate(),
 	});
 }

package/src/utils/changelog.ts

@@ -1,4 +1,4 @@
-import { isEnoent, logger } from "@oh-my-pi/pi-utils";
+import { getLastChangelogVersionPath, isEnoent, logger } from "@oh-my-pi/pi-utils";
 
 export interface ChangelogEntry {
 	major: number;
@@ -104,3 +104,29 @@ export function getNewEntries(entries: ChangelogEntry[], lastVersion: string): C
 
 // Re-export getChangelogPath from paths.ts for convenience
 export { getChangelogPath } from "../config";
+
+/**
+ * Last omp version whose changelog the user has seen. Stored as a plain-text
+ * marker file (`~/.omp/agent/last-changelog-version`) rather than in
+ * `config.yml`, so version bumps never dirty user-tracked config files.
+ */
+export async function readLastChangelogVersion(agentDir?: string): Promise<string | undefined> {
+	try {
+		const value = (await Bun.file(getLastChangelogVersionPath(agentDir)).text()).trim();
+		return value || undefined;
+	} catch (error) {
+		if (!isEnoent(error)) {
+			logger.warn("Failed to read last-changelog-version marker", { error: String(error) });
+		}
+		return undefined;
+	}
+}
+
+/** Persist the last-seen changelog version marker. Best-effort: failures are logged, never thrown. */
+export async function writeLastChangelogVersion(version: string, agentDir?: string): Promise<void> {
+	try {
+		await Bun.write(getLastChangelogVersionPath(agentDir), version);
+	} catch (error) {
+		logger.warn("Failed to persist last-changelog-version marker", { error: String(error) });
+	}
+}

package/src/utils/file-mentions.ts

@@ -11,6 +11,7 @@ import { formatHashlineHeader, formatNumberedLines, type SnapshotStore } from "@
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import type { ImageContent } from "@oh-my-pi/pi-ai";
 import { formatAge, formatBytes, readImageMetadata } from "@oh-my-pi/pi-utils";
+import { canonicalSnapshotKey } from "../edit/file-snapshot-store";
 import { normalizeToLF } from "../edit/normalize";
 import type { FileMentionMessage } from "../session/messages";
 import {
@@ -259,7 +260,7 @@ export async function generateFileMentionMessages(
 			const normalized = snapshotStore ? normalizeToLF(content) : content;
 			let { output, lineCount } = buildTextOutput(normalized);
 			if (snapshotStore) {
-				const tag = snapshotStore.record(absolutePath, normalized);
+				const tag = snapshotStore.record(canonicalSnapshotKey(absolutePath), normalized);
 				output = `${formatHashlineHeader(resolvedPath, tag)}\n${formatNumberedLines(output)}`;
 			}
 			files.push({ path: resolvedPath, content: output, lineCount });

package/src/web/scrapers/arxiv.ts

@@ -1,4 +1,3 @@
-import { parseHTML } from "linkedom";
 import type { RenderResult, SpecialHandler } from "./types";
 import { buildResult, loadPage } from "./types";
 import { convertWithMarkit, fetchBinary } from "./utils";
@@ -31,6 +30,7 @@ export const handleArxiv: SpecialHandler = async (
 		if (!result.ok) return null;
 
 		// Parse the Atom feed response
+		const { parseHTML } = await import("linkedom");
 		const doc = parseHTML(result.content).document;
 		const entry = doc.querySelector("entry");
 

package/src/web/scrapers/go-pkg.ts

@@ -1,5 +1,4 @@
 import { tryParseJson } from "@oh-my-pi/pi-utils";
-import { parseHTML } from "linkedom";
 import type { RenderResult, SpecialHandler } from "./types";
 import { buildResult, htmlToBasicMarkdown, loadPage } from "./types";
 
@@ -97,6 +96,7 @@ export const handleGoPkg: SpecialHandler = async (
 			});
 		}
 
+		const { parseHTML } = await import("linkedom");
 		const doc = parseHTML(pageResult.content).document;
 
 		// Extract actual module path from breadcrumb or header

package/src/web/scrapers/iacr.ts

@@ -1,4 +1,3 @@
-import { parseHTML } from "linkedom";
 import type { RenderResult, SpecialHandler } from "./types";
 import { buildResult, loadPage } from "./types";
 import { convertWithMarkit, fetchBinary } from "./utils";
@@ -30,6 +29,7 @@ export const handleIacr: SpecialHandler = async (
 
 		if (!result.ok) return null;
 
+		const { parseHTML } = await import("linkedom");
 		const doc = parseHTML(result.content).document;
 
 		// Extract metadata from the page

package/src/web/scrapers/readthedocs.ts

@@ -1,7 +1,6 @@
 /**
  * Read the Docs handler for web-fetch
  */
-import { parseHTML } from "linkedom";
 import { buildResult, htmlToBasicMarkdown, loadPage, type RenderResult, type SpecialHandler } from "./types";
 
 export const handleReadTheDocs: SpecialHandler = async (
@@ -39,6 +38,7 @@ export const handleReadTheDocs: SpecialHandler = async (
 	}
 
 	// Parse HTML
+	const { parseHTML } = await import("linkedom");
 	const root = parseHTML(result.content).document;
 
 	// Extract main content from common Read the Docs selectors

package/src/web/scrapers/twitter.ts

@@ -1,4 +1,4 @@
-import { type HTMLElement, parseHTML } from "linkedom";
+import type { HTMLElement } from "linkedom";
 import { ToolAbortError } from "../../tools/tool-errors";
 import type { RenderResult, SpecialHandler } from "./types";
 import { buildResult, loadPage } from "./types";
@@ -33,6 +33,7 @@ export const handleTwitter: SpecialHandler = async (
 
 			if (result.ok && result.content.length > 500) {
 				// Parse the Nitter HTML
+				const { parseHTML } = await import("linkedom");
 				const doc = parseHTML(result.content).document;
 
 				// Extract tweet content

package/src/web/scrapers/types.ts

@@ -1,6 +1,7 @@
 /**
  * Shared types and utilities for web-fetch handlers
  */
+import { scheduler } from "node:timers/promises";
 import { ptree } from "@oh-my-pi/pi-utils";
 import type TurndownService from "turndown";
 
@@ -70,6 +71,12 @@ export interface LoadPageOptions {
 	body?: string;
 	maxBytes?: number;
 	signal?: AbortSignal;
+	/**
+	 * Return true to skip reading the response body for this content type
+	 * (lowercased mime, no params). The caller is expected to re-fetch the
+	 * payload as binary; this avoids streaming + decoding huge binaries twice.
+	 */
+	skipBodyForContentType?: (contentType: string) => boolean;
 }
 
 export interface LoadPageResult {
@@ -78,6 +85,51 @@ export interface LoadPageResult {
 	finalUrl: string;
 	ok: boolean;
 	status?: number;
+	/** True when the body was cut mid-stream at maxBytes. */
+	truncated?: boolean;
+	/** Last transport-level error message when ok is false. */
+	error?: string;
+	/** True when the body read was skipped via skipBodyForContentType. */
+	bodySkipped?: boolean;
+}
+
+const RETRY_AFTER_MAX_MS = 10_000;
+
+/** Parse a Retry-After header (seconds or HTTP-date) into a bounded delay. */
+function parseRetryAfterMs(value: string | null): number {
+	if (!value) return 1_000;
+	const seconds = Number(value);
+	if (Number.isFinite(seconds)) return Math.min(Math.max(seconds, 0) * 1000, RETRY_AFTER_MAX_MS);
+	const date = Date.parse(value);
+	if (!Number.isNaN(date)) return Math.min(Math.max(date - Date.now(), 0), RETRY_AFTER_MAX_MS);
+	return 1_000;
+}
+
+function charsetFromContentType(header: string): string | undefined {
+	return /charset\s*=\s*"?([\w-]+)"?/i.exec(header)?.[1];
+}
+
+/**
+ * Decode a response body honoring the declared charset (Content-Type header,
+ * then a cheap <meta charset> sniff), falling back to UTF-8.
+ */
+function decodeBody(bytes: Buffer, contentTypeHeader: string): string {
+	let label = charsetFromContentType(contentTypeHeader);
+	if (!label) {
+		// All charsets we can decode are ASCII-compatible in the prefix, so a
+		// latin1 view of the first 2KB is enough to find a <meta charset>.
+		label = /<meta[^>]+charset\s*=\s*["']?([\w-]+)/i.exec(bytes.subarray(0, 2048).toString("latin1"))?.[1];
+	}
+	if (label && !/^utf-?8$/i.test(label)) {
+		try {
+			// Bun.Encoding's union is narrower than the runtime, which accepts
+			// WHATWG labels (shift_jis, euc-kr, gbk, big5, …); unknowns throw here.
+			return new TextDecoder(label as Bun.Encoding).decode(bytes);
+		} catch {
+			// Unknown/unsupported label — fall back to UTF-8.
+		}
+	}
+	return bytes.toString("utf-8");
 }
 
 /**
@@ -86,6 +138,8 @@ export interface LoadPageResult {
 export async function loadPage(url: string, options: LoadPageOptions = {}): Promise<LoadPageResult> {
 	const { timeout = 20, headers = {}, maxBytes = MAX_BYTES, signal, method = "GET", body } = options;
 
+	let lastError: string | undefined;
+	let retried429 = false;
 	for (let attempt = 0; attempt < USER_AGENTS.length; attempt++) {
 		if (signal?.aborted) {
 			throw new ToolAbortError();
@@ -114,9 +168,31 @@ export async function loadPage(url: string, options: LoadPageOptions = {}): Prom
 
 			const response = await fetch(url, requestInit);
 
-			const contentType = response.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase() ?? "";
+			const rawContentType = response.headers.get("content-type") ?? "";
+			const contentType = rawContentType.split(";")[0]?.trim().toLowerCase() ?? "";
 			const finalUrl = response.url;
 
+			if (response.status === 429 && !retried429) {
+				// Rate limited: retry once, honoring a bounded Retry-After. The
+				// wait observes the caller's signal so an Esc during the backoff
+				// does not stall for up to the full delay.
+				retried429 = true;
+				const delayMs = parseRetryAfterMs(response.headers.get("retry-after"));
+				void response.body?.cancel().catch(() => {});
+				try {
+					await scheduler.wait(delayMs, { signal });
+				} catch {
+					throw new ToolAbortError();
+				}
+				attempt--; // Reuse the same user agent for the retry.
+				continue;
+			}
+
+			if (response.ok && options.skipBodyForContentType?.(contentType)) {
+				void response.body?.cancel().catch(() => {});
+				return { content: "", contentType, finalUrl, ok: true, status: response.status, bodySkipped: true };
+			}
+
 			const reader = response.body?.getReader();
 			if (!reader) {
 				return { content: "", contentType, finalUrl, ok: false, status: response.status };
@@ -124,6 +200,7 @@ export async function loadPage(url: string, options: LoadPageOptions = {}): Prom
 
 			const chunks: Uint8Array[] = [];
 			let totalSize = 0;
+			let truncated = false;
 
 			while (true) {
 				const { done, value } = await reader.read();
@@ -133,32 +210,34 @@ export async function loadPage(url: string, options: LoadPageOptions = {}): Prom
 				totalSize += value.length;
 
 				if (totalSize > maxBytes) {
-					reader.cancel();
+					truncated = true;
+					void reader.cancel().catch(() => {});
 					break;
 				}
 			}
 
-			const content = Buffer.concat(chunks).toString("utf-8");
+			const content = decodeBody(Buffer.concat(chunks), rawContentType);
 			if (isBotBlocked(response.status, content) && attempt < USER_AGENTS.length - 1) {
 				continue;
 			}
 
 			if (!response.ok) {
-				return { content, contentType, finalUrl, ok: false, status: response.status };
+				return { content, contentType, finalUrl, ok: false, status: response.status, truncated };
 			}
 
-			return { content, contentType, finalUrl, ok: true, status: response.status };
-		} catch {
+			return { content, contentType, finalUrl, ok: true, status: response.status, truncated };
+		} catch (error) {
 			if (signal?.aborted) {
 				throw new ToolAbortError();
 			}
+			lastError = error instanceof Error ? error.message : String(error);
 			if (attempt === USER_AGENTS.length - 1) {
-				return { content: "", contentType: "", finalUrl: url, ok: false };
+				return { content: "", contentType: "", finalUrl: url, ok: false, error: lastError };
 			}
 		}
 	}
 
-	return { content: "", contentType: "", finalUrl: url, ok: false };
+	return { content: "", contentType: "", finalUrl: url, ok: false, error: lastError };
 }
 
 /** Module-level Turndown instance — built lazily on first use. */

package/src/web/scrapers/wikipedia.ts

@@ -1,4 +1,3 @@
-import { parseHTML } from "linkedom";
 import type { RenderResult, SpecialHandler } from "./types";
 import { buildResult, loadPage } from "./types";
 
@@ -45,6 +44,7 @@ export const handleWikipedia: SpecialHandler = async (
 		const contentResult = await loadPage(contentUrl, { timeout, signal });
 
 		if (contentResult.ok) {
+			const { parseHTML } = await import("linkedom");
 			const doc = parseHTML(contentResult.content).document;
 
 			// Extract main content sections

package/src/web/scrapers/youtube.ts

@@ -288,12 +288,17 @@ export const handleYouTube: SpecialHandler = async (
 			}
 		}
 	} finally {
-		throwIfAborted(signal);
 		// Cleanup temp files (fire-and-forget with error suppression)
 		Array.fromAsync(new Bun.Glob(`${tmpBase}*`).scan({ absolute: true }))
 			.then(tmpFiles => Promise.all(tmpFiles.map(f => fs.unlink(f).catch(() => {}))))
 			.catch(() => {});
 	}
+	// Only a user-initiated abort is fatal; the per-fetch time budget expiring
+	// just means partial metadata/transcript, which we surface as a note.
+	throwIfAborted(userSignal);
+	if (signal?.aborted) {
+		notes.push("Fetch time budget exhausted; metadata/transcript may be incomplete");
+	}
 
 	// Build markdown output
 	let md = `# ${title}\n\n`;

package/src/web/search/index.ts

@@ -150,7 +150,7 @@ async function executeSearch(
 		lastProvider = provider;
 		try {
 			const response = await provider.search({
-				query: params.query.replace(/202\d/g, String(new Date().getFullYear())), // LUL
+				query: params.query,
 				limit: params.limit,
 				recency: params.recency,
 				systemPrompt: webSearchSystemPrompt,

package/src/web/search/providers/codex.ts

@@ -7,8 +7,9 @@
  * SQLite store, never POSTs the broker sentinel to an OpenAI token endpoint.
  */
 import * as os from "node:os";
-import { type AuthStorage, type FetchImpl, getBundledModels } from "@oh-my-pi/pi-ai";
+import type { AuthStorage, FetchImpl } from "@oh-my-pi/pi-ai";
 import { decodeJwt } from "@oh-my-pi/pi-ai/oauth/openai-codex";
+import { getBundledModels } from "@oh-my-pi/pi-catalog/models";
 import { $env, readSseJson } from "@oh-my-pi/pi-utils";
 import packageJson from "../../../../package.json" with { type: "json" };
 import type { SearchResponse, SearchSource } from "../../../web/search/types";