@linxiraos/pi-utils 1.1.6 → 1.1.8

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## [Unreleased]
 
+## [1.1.8] - 2026-09-04
+
+- Added `symlinkDirectorySync` — Windows-correct directory links (junction) for tests and tooling that must link temp trees without elevation.
+- Extended the temp-removal retry window to 7.5s: measured Windows handle-release latency after a child process dies reaches ~5s, and the previous 2s window flaked suites cleaning up trees containing SQLite databases.
+
 ## [1.1.6] - 2026-08-30
 
 - 同步上游 OMP v18.0.10（`33cc6b9a043a`）。
@@ -11,12 +16,6 @@
 
 - 同步上游 OMP v18.0.5 / v18.0.6：新增 browsers / json 工具，SHA-2/SHA-3 在 ARM64 上加速。
 
-## [1.1.3] - 2026-08-25
-
-### Fixed
-
-- Republished as 1.1.3 to reset the latest tag after the broken 1.1.2 (no functional change over 1.1.1).
-
 ## [1.1.2] - 2026-08-25
 
 ### Fixed

package/dist/types/async.d.ts

@@ -1,9 +1,9 @@
 /**
  * Wrap a promise with a timeout and optional abort signal.
- * Rejects with the given message if the timeout fires first.
- * Cleans up all listeners on settlement.
+ * Rejects with the given error or a new error containing the given message if
+ * the timeout fires first. Cleans up all listeners on settlement.
  */
-export declare function withTimeout<T>(promise: Promise<T>, ms: number, message: string, signal?: AbortSignal): Promise<T>;
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, timeout: string | Error, signal?: AbortSignal): Promise<T>;
 /**
  * Coalesces rapid-fire writes into one deferred batch. `push` queues a value
  * and returns a promise for the batch flush; the first push of a batch arms a

package/dist/types/env.d.ts

@@ -16,6 +16,15 @@ export declare function isValidEnvName(name: string): boolean;
 export declare function isSafeEnvName(name: string): boolean;
 export declare function isSafeEnvValue(value: string): boolean;
 export declare function isMacosMallocStackLoggingEnvName(name: string): boolean;
+/**
+ * True when running inside a WSL (Windows Subsystem for Linux) distribution.
+ *
+ * WSL reports `linux` for `process.platform`, so the only reliable signal is
+ * the `WSL_DISTRO_NAME`/`WSL_INTEROP` variables the interop layer injects.
+ * Callers use this to translate Windows drive paths to their `/mnt/<drive>`
+ * mounts and to route clipboard access through `powershell.exe`.
+ */
+export declare function isWsl(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): boolean;
 export declare function filterProcessEnv(env: Record<string, string | undefined>): Record<string, string>;
 /** Filters process env for child shells without launch-cwd dotenv values. */
 export declare function filterChildShellEnv(env: Record<string, string | undefined>, cwd?: string): Record<string, string>;

package/dist/types/fetch-retry.d.ts

@@ -14,6 +14,8 @@
  *  - `Please retry in 250ms` / `Please retry in 12s`
  *  - `"retryDelay": "34.074824224s"` (JSON error detail field)
  *  - `try again in 250ms` / `try again in 12s` / `try again in 5 min` / `try again in ~158 min`
+ *  - `retry-after-ms=98497000`
+ *  - `Your limit will reset at 2026-09-01 09:44:51` / `将在 2026-09-01 09:44:51 重置`
  *
  * Returns `undefined` if no signal is found.
  */

package/dist/types/index.d.ts

@@ -14,6 +14,7 @@ export * from "./json.js";
 export * from "./json-parse.js";
 export * as logger from "./logger.js";
 export * from "./loop-phase.js";
+export * from "./materialize-string.js";
 export * from "./math-delimiters.js";
 export * from "./mermaid-ascii.js";
 export * from "./mime.js";

package/dist/types/materialize-string.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Copy text into independent UTF-16 backing storage before a bounded substring outlives its source.
+ *
+ * The UTF-16 round trip preserves every JavaScript code unit, including lone
+ * surrogates that a UTF-8 round trip would replace.
+ */
+export declare function materializeString(text: string): string;

package/dist/types/path.d.ts

@@ -1,2 +1,4 @@
+/** Maps an absolute Windows drive path to the drive's default WSL mount. */
+export declare function windowsPathToWslMount(filePath: string): string | undefined;
 /** Removes Win32 extended-length prefixes before passing paths to Bun APIs. */
 export declare function stripWindowsExtendedLengthPathPrefix(filePath: string, platform?: NodeJS.Platform): string;

package/dist/types/postmortem.d.ts

@@ -123,6 +123,10 @@ export declare function interceptUnhandledRejections(interceptor: (reason: unkno
  * through an uncaught exception or unhandled rejection.
  */
 export declare function registerFatalRecoveryHint(provider: FatalRecoveryHintProvider): () => void;
+/**
+ * Reports a caught top-level failure after terminal owners restore their display, then exits.
+ */
+export declare function fatal(error: unknown): Promise<never>;
 /** Controls when a registered cleanup callback participates in cleanup passes. */
 export interface CleanupRegistrationOptions {
     /**

package/dist/types/runtime-install.d.ts

@@ -73,6 +73,13 @@ export interface EnsureRuntimeInstalledOptions {
 export declare function writeRuntimeManifest(runtimeDir: string, install: RuntimeInstallSpec): Promise<void>;
 /**
  * Materialize a pinned dependency set into `runtimeDir` (idempotent,
- * cross-process safe via a lock directory). Returns `runtimeDir`.
+ * cross-process safe). Returns `runtimeDir`.
+ *
+ * Serialization uses the OS-backed {@link withFileLock} at
+ * `${runtimeDir}.install.lock`, which the kernel releases on process death, so
+ * a crashed installer cannot wedge later attempts (issue #10120). The path is
+ * deliberately distinct from the legacy `${runtimeDir}.lock` mkdir directory;
+ * {@link withLegacyInstallLock} atomically reserves that namespace during the
+ * new install so older processes cannot cross the migration boundary.
  */
 export declare function ensureRuntimeInstalled(options: EnsureRuntimeInstalledOptions): Promise<string>;

package/dist/types/temp.d.ts

@@ -15,3 +15,10 @@ export declare class TempDir {
 /** Removes a path recursively, retrying transient Windows deletion failures. */
 export declare function removeWithRetries(target: string): Promise<void>;
 export declare function removeSyncWithRetries(target: string): void;
+/**
+ * Create a directory symlink in a platform-correct way. Windows denies
+ * unprivileged file/dir symlinks (EPERM on `fs.symlink` without a type), but
+ * allows directory *junctions*, which every test that links temp directories
+ * should use instead. POSIX ignores the type argument.
+ */
+export declare function symlinkDirectorySync(target: string, linkPath: string): void;

package/dist/types/vterm/query-responder.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Answers terminal capability queries emitted by programs on a headless PTY.
+ *
+ * A PTY that advertises `TERM=xterm-256color` but has no terminal behind it
+ * leaves capability probes unanswered: a program writes a query escape to
+ * stdout and blocks on stdin until the reply arrives (or its timeout expires,
+ * seconds later). This scanner watches raw PTY output for the standard queries
+ * and returns the bytes a real xterm-class terminal would send back, so the
+ * caller can write them into the PTY. It keeps no screen state — cursor
+ * position reports are answered with the home position — which makes it cheap
+ * enough to run on every byte of a long-lived supervised process. Use the full
+ * {@link Terminal} when the caller also renders the output.
+ *
+ * Queries can straddle chunk boundaries, so an unfinished trailing escape is
+ * carried into the next {@link feed}.
+ */
+export declare class TerminalQueryResponder {
+    #private;
+    /**
+     * Feed one raw PTY output chunk. Returns the reply bytes to write back into
+     * the PTY, or an empty string when the chunk held no answerable query.
+     */
+    feed(chunk: string): string;
+}

package/dist/types/vterm.d.ts

@@ -1,5 +1,6 @@
 /** Behavior-compatible reimplementation of @xterm/headless's used surface. */
 export * from "./vterm/buffer.js";
+export * from "./vterm/query-responder.js";
 export * from "./vterm/terminal.js";
 import { Terminal } from "./vterm/terminal.js";
 declare const vterm: {

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@linxiraos/pi-utils",
-	"version": "1.1.6",
+	"version": "1.1.8",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://linxira-os.github.io/zeta/",
 	"author": "Can Boluk",
@@ -31,7 +31,7 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@linxiraos/pi-natives": "1.1.6"
+		"@linxiraos/pi-natives": "1.1.8"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/acp/connection.ts

@@ -67,13 +67,11 @@ export class AgentSideConnection {
 	#connection: RpcConnection;
 
 	constructor(toAgent: (connection: AgentSideConnection) => Agent, stream: Stream) {
-		let agent: Agent | undefined;
 		this.#connection = new RpcConnection(stream, async (method, params, notification) => {
-			const target = agent;
-			if (!target) throw RequestError.internalError(undefined, "Agent is not initialized");
-			return dispatchAgent(target, method, params, notification);
+			if (!agent) throw RequestError.internalError(undefined, "Agent is not initialized");
+			return dispatchAgent(agent, method, params, notification);
 		});
-		agent = toAgent(this);
+		const agent = toAgent(this);
 	}
 
 	/** Signal aborted when the transport closes. */
@@ -170,13 +168,11 @@ export class ClientSideConnection {
 	#connection: RpcConnection;
 
 	constructor(toClient: (connection: ClientSideConnection) => Client, stream: Stream) {
-		let client: Client | undefined;
 		this.#connection = new RpcConnection(stream, async (method, params, notification) => {
-			const target = client;
-			if (!target) throw RequestError.internalError(undefined, "Client is not initialized");
-			return dispatchClient(target, method, params, notification);
+			if (!client) throw RequestError.internalError(undefined, "Client is not initialized");
+			return dispatchClient(client, method, params, notification);
 		});
-		client = toClient(this);
+		const client = toClient(this);
 	}
 	/** Signal aborted when the transport closes. */
 	get signal(): AbortSignal {

package/src/ar/entries.ts

@@ -45,7 +45,7 @@ export function upsertArchiveEntry(
  */
 export function ensureParentDirectories(map: Map<string, ArchiveIndexEntry>, limits: ArchiveLimits): void {
 	assertEntryCount(map.size, limits);
-	for (const entry of [...map.values()]) {
+	for (const entry of Array.from(map.values())) {
 		const parts = entry.path.split("/");
 		const stop = parts.length - 1;
 		for (let index = 1; index <= stop; index++) {

package/src/ar/sevenzip.ts

@@ -107,6 +107,7 @@ interface FileMetadata {
 }
 
 function readBoolVector(reader: HeaderReader, count: number): boolean[] {
+	// [suppressed] length preallocation
 	const result = new Array<boolean>(count);
 	let byte = 0;
 	let mask = 0;
@@ -122,12 +123,16 @@ function readBoolVector(reader: HeaderReader, count: number): boolean[] {
 }
 
 function readDefinedVector(reader: HeaderReader, count: number): boolean[] {
-	if (reader.readByte() !== 0) return new Array<boolean>(count).fill(true);
+	if (reader.readByte() !== 0) {
+		// [suppressed] length preallocation
+		return new Array<boolean>(count).fill(true);
+	}
 	return readBoolVector(reader, count);
 }
 
 function readDigests(reader: HeaderReader, count: number): Digests {
 	const defined = readDefinedVector(reader, count);
+	// [suppressed] length preallocation
 	const values = new Array<number | undefined>(count);
 	for (let index = 0; index < count; index++) if (defined[index]) values[index] = reader.readUInt32();
 	return { defined, values };
@@ -229,7 +234,10 @@ function parsePackInfo(reader: HeaderReader, streams: SevenZipStreams, options:
 		} else reader.skipSizedProperty();
 	}
 	if (streams.packSizes.length !== count) throw new ArchiveError("Invalid 7z PackInfo without complete sizes");
-	if (streams.packCrcs.length === 0) streams.packCrcs = new Array(count).fill(undefined);
+	if (streams.packCrcs.length === 0) {
+		// [suppressed] length preallocation
+		streams.packCrcs = new Array(count).fill(undefined);
+	}
 }
 
 function parseUnpackInfo(reader: HeaderReader, streams: SevenZipStreams, options: FormatReadOptions): void {
@@ -254,6 +262,7 @@ function parseUnpackInfo(reader: HeaderReader, streams: SevenZipStreams, options
 }
 
 function parseSubStreamsInfo(reader: HeaderReader, streams: SevenZipStreams): void {
+	// [suppressed] length preallocation
 	const counts = new Array<number>(streams.folders.length).fill(1);
 	let sizes: number[] | undefined;
 	let rawDigests: Digests | undefined;
@@ -398,6 +407,7 @@ function parseNames(reader: HeaderReader, count: number, external: Uint8Array[],
 function parseTimes(reader: HeaderReader, count: number, external: Uint8Array[]): Array<number | undefined> {
 	const defined = readDefinedVector(reader, count);
 	const values = selectPropertyStream(reader, external);
+	// [suppressed] length preallocation
 	const result = new Array<number | undefined>(count);
 	for (let index = 0; index < count; index++)
 		if (defined[index]) {
@@ -411,6 +421,7 @@ function parseTimes(reader: HeaderReader, count: number, external: Uint8Array[])
 function parseAttributes(reader: HeaderReader, count: number, external: Uint8Array[]): Array<number | undefined> {
 	const defined = readDefinedVector(reader, count);
 	const values = selectPropertyStream(reader, external);
+	// [suppressed] length preallocation
 	const result = new Array<number | undefined>(count);
 	for (let index = 0; index < count; index++) if (defined[index]) result[index] = values.readUInt32();
 	return result;
@@ -420,11 +431,15 @@ function parseFilesInfo(reader: HeaderReader, external: Uint8Array[], options: F
 	const count = reader.readNumber("file count");
 	assertEntryCount(count, options.limits);
 	const metadata: FileMetadata = {
+		// [suppressed] length preallocation
 		names: new Array<string>(count).fill(""),
+		// [suppressed] length preallocation
 		emptyStreams: new Array<boolean>(count).fill(false),
 		emptyFiles: [],
 		antiFiles: [],
+		// [suppressed] length preallocation
 		mtimes: new Array<number | undefined>(count),
+		// [suppressed] length preallocation
 		attributes: new Array<number | undefined>(count),
 	};
 	for (;;) {

package/src/async.ts

@@ -1,9 +1,14 @@
 /**
  * Wrap a promise with a timeout and optional abort signal.
- * Rejects with the given message if the timeout fires first.
- * Cleans up all listeners on settlement.
+ * Rejects with the given error or a new error containing the given message if
+ * the timeout fires first. Cleans up all listeners on settlement.
  */
-export function withTimeout<T>(promise: Promise<T>, ms: number, message: string, signal?: AbortSignal): Promise<T> {
+export function withTimeout<T>(
+	promise: Promise<T>,
+	ms: number,
+	timeout: string | Error,
+	signal?: AbortSignal,
+): Promise<T> {
 	if (signal?.aborted) {
 		const reason = signal.reason instanceof Error ? signal.reason : new Error("Aborted");
 		return Promise.reject(reason);
@@ -15,7 +20,7 @@ export function withTimeout<T>(promise: Promise<T>, ms: number, message: string,
 		if (settled) return;
 		settled = true;
 		if (signal) signal.removeEventListener("abort", onAbort);
-		reject(new Error(message));
+		reject(typeof timeout === "string" ? new Error(timeout) : timeout);
 	}, ms);
 
 	const onAbort = () => {

package/src/browsers.ts

@@ -39,6 +39,13 @@ export enum BrowserPlatform {
 	WIN32 = "win32",
 	WIN64 = "win64",
 }
+type ChromeForTestingPlatform = Exclude<BrowserPlatform, BrowserPlatform.LINUX_ARM>;
+
+function requireChromeForTestingPlatform(platform: BrowserPlatform): ChromeForTestingPlatform {
+	if (platform === BrowserPlatform.LINUX_ARM)
+		throw new Error("Chrome for Testing does not provide linux/arm64 builds");
+	return platform;
+}
 
 const BROWSERS = [
 	Browser.CHROME,
@@ -163,13 +170,13 @@ export function getDownloadUrl(
 
 /** Compute the executable path in Puppeteer's cache layout. */
 export function computeExecutablePath(options: ComputeExecutablePathOptions): string {
-	const platform = options.platform ?? detectBrowserPlatform();
-	if (!platform) throw new Error("Cannot determine a browser platform for this host");
+	const detectedPlatform = options.platform ?? detectBrowserPlatform();
+	if (!detectedPlatform) throw new Error("Cannot determine a browser platform for this host");
 	if (options.browser !== Browser.CHROME) throw new Error(`Unsupported browser executable: ${options.browser}`);
+	const platform = requireChromeForTestingPlatform(detectedPlatform);
 	const installDir = installationDir(options.cacheDir, options.browser, platform, options.buildId);
 	switch (platform) {
 		case BrowserPlatform.LINUX:
-		case BrowserPlatform.LINUX_ARM:
 			return path.join(installDir, "chrome-linux64", "chrome");
 		case BrowserPlatform.MAC:
 			return path.join(
@@ -292,9 +299,8 @@ async function fetchMetadata<T>(filename: string): Promise<T> {
 }
 
 function chromeArchivePlatform(platform: BrowserPlatform): string {
-	switch (platform) {
+	switch (requireChromeForTestingPlatform(platform)) {
 		case BrowserPlatform.LINUX:
-		case BrowserPlatform.LINUX_ARM:
 			return "linux64";
 		case BrowserPlatform.MAC:
 			return "mac-x64";

package/src/dom/core.ts

@@ -105,7 +105,7 @@ export class EventTarget {
 	dispatchEvent(event: Event): boolean {
 		if (!event.target) event.target = this;
 		event.currentTarget = this;
-		for (const listener of [...(this.#listeners.get(event.type) ?? [])]) {
+		for (const listener of Array.from(this.#listeners.get(event.type) ?? [])) {
 			if (typeof listener === "function") listener.call(this, event);
 			else listener.handleEvent(event);
 			if (event.propagationStopped) break;
@@ -196,7 +196,7 @@ export class Node extends EventTarget {
 		const node: Node = child;
 		if (node === this || node.contains(this)) throw new Error("The new child is an ancestor of this node");
 		if (child instanceof DocumentFragment) {
-			for (const nested of [...child.childNodes]) this.appendChild(nested);
+			for (const nested of Array.from(child.childNodes)) this.appendChild(nested);
 			return child;
 		}
 		child.parentNode?.removeChild(child);
@@ -212,7 +212,7 @@ export class Node extends EventTarget {
 		const index = this.childNodes.indexOf(reference);
 		if (index < 0) throw new Error("The reference node is not a child of this node");
 		if (child instanceof DocumentFragment) {
-			for (const nested of [...child.childNodes]) this.insertBefore(nested, reference);
+			for (const nested of Array.from(child.childNodes)) this.insertBefore(nested, reference);
 			return child;
 		}
 		child.parentNode?.removeChild(child);
@@ -681,7 +681,7 @@ export class Element extends Node {
 		const parent = this.parentNode;
 		if (!parent) return;
 		const fragment = parseFragment(value, this.documentForCreation(), this.parentElement?.localName);
-		for (const child of [...fragment.childNodes]) parent.insertBefore(child, this);
+		for (const child of Array.from(fragment.childNodes)) parent.insertBefore(child, this);
 		parent.removeChild(this);
 	}
 

package/src/env.ts

@@ -36,6 +36,18 @@ export function isMacosMallocStackLoggingEnvName(name: string): boolean {
 	return name === "MallocStackLogging" || name === "MallocStackLoggingNoCompact";
 }
 
+/**
+ * True when running inside a WSL (Windows Subsystem for Linux) distribution.
+ *
+ * WSL reports `linux` for `process.platform`, so the only reliable signal is
+ * the `WSL_DISTRO_NAME`/`WSL_INTEROP` variables the interop layer injects.
+ * Callers use this to translate Windows drive paths to their `/mnt/<drive>`
+ * mounts and to route clipboard access through `powershell.exe`.
+ */
+export function isWsl(platform: NodeJS.Platform = process.platform, env: NodeJS.ProcessEnv = process.env): boolean {
+	return platform === "linux" && Boolean(env.WSL_DISTRO_NAME || env.WSL_INTEROP);
+}
+
 export function filterProcessEnv(env: Record<string, string | undefined>): Record<string, string> {
 	const result: Record<string, string> = {};
 	for (const key in env) {

package/src/fetch-retry.ts

@@ -12,6 +12,12 @@ const RETRY_DELAY_FIELD_PATTERN = /"retryDelay":\s*"([0-9.]+)(ms|s)"/i;
 const TRY_AGAIN_PATTERN = /try again in\s+~?\s*([0-9.]+)\s*(ms|sec|s|minutes?|mins?|m|hours?|hrs?|h)\b/i;
 // "Your limit will reset in 13 minutes" / "reset in 13 minutes" / "will reset in 2h"
 const WILL_RESET_IN_PATTERN = /(?:will\s+)?reset in\s+~?\s*([0-9.]+)\s*(ms|sec|s|minutes?|mins?|m|hours?|hrs?|h)\b/i;
+// "Your limit will reset at 2026-09-01 09:44:51" / "reset at 2026-09-01T09:44:51Z"
+const WILL_RESET_AT_PATTERN =
+	/(?:will\s+)?reset at\s+([0-9]{4}-[0-9]{2}-[0-9]{2}[ T][0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]+)?(?:Z|[+-][0-9]{2}:?[0-9]{2})?)/i;
+const CN_RESET_AT_PATTERN = /将在\s*([0-9]{4}-[0-9]{2}-[0-9]{2}\s+[0-9]{2}:[0-9]{2}:[0-9]{2})\s*重置/;
+// "retry-after-ms=98497000"
+const RETRY_AFTER_MS_BODY_PATTERN = /\bretry-after-ms=([0-9]+)\b/i;
 
 /**
  * Server-suggested retry delay extraction. Merges the patterns historically used
@@ -29,6 +35,8 @@ const WILL_RESET_IN_PATTERN = /(?:will\s+)?reset in\s+~?\s*([0-9.]+)\s*(ms|sec|s
  *  - `Please retry in 250ms` / `Please retry in 12s`
  *  - `"retryDelay": "34.074824224s"` (JSON error detail field)
  *  - `try again in 250ms` / `try again in 12s` / `try again in 5 min` / `try again in ~158 min`
+ *  - `retry-after-ms=98497000`
+ *  - `Your limit will reset at 2026-09-01 09:44:51` / `将在 2026-09-01 09:44:51 重置`
  *
  * Returns `undefined` if no signal is found.
  */
@@ -85,11 +93,38 @@ export function extractRetryHint(source: Response | Headers | null | undefined,
 			if (totalMs > 0) return totalMs;
 		}
 	}
+	for (const pattern of [WILL_RESET_AT_PATTERN, CN_RESET_AT_PATTERN]) {
+		const match = pattern.exec(body);
+		if (match?.[1]) {
+			// Provider timestamps without an explicit offset are interpreted as UTC.
+			const normalized = match[1].replace(" ", "T");
+			const hasOffset = /(?:Z|[+-][0-9]{2}:?[0-9]{2})$/i.test(normalized);
+			const parsed = Date.parse(hasOffset ? normalized : `${normalized}Z`);
+			if (!Number.isNaN(parsed) && parsed > Date.now()) {
+				return parsed - Date.now();
+			}
+		}
+	}
 	// Account-reset hints ("will reset in …") take precedence over short
 	// retry hints ("please retry in 5s"): a body carrying both must honour the
 	// longer account window, not the shorter generic one. QUOTA_RESET_PATTERN
 	// ("reset after …") above already runs first and stays first.
-	for (const pattern of [WILL_RESET_IN_PATTERN, PLEASE_RETRY_PATTERN, RETRY_DELAY_FIELD_PATTERN, TRY_AGAIN_PATTERN]) {
+	const accountResetMatch = WILL_RESET_IN_PATTERN.exec(body);
+	if (accountResetMatch?.[1]) {
+		const value = Number.parseFloat(accountResetMatch[1]);
+		if (Number.isFinite(value) && value > 0) {
+			const unitMs = unitToMs(accountResetMatch[2]!);
+			if (unitMs !== undefined) return value * unitMs;
+		}
+	}
+
+	const retryAfterMsMatch = RETRY_AFTER_MS_BODY_PATTERN.exec(body);
+	if (retryAfterMsMatch?.[1]) {
+		const ms = Number(retryAfterMsMatch[1]);
+		if (Number.isFinite(ms) && ms > 0) return ms;
+	}
+
+	for (const pattern of [PLEASE_RETRY_PATTERN, RETRY_DELAY_FIELD_PATTERN, TRY_AGAIN_PATTERN]) {
 		const match = pattern.exec(body);
 		if (match?.[1]) {
 			const value = Number.parseFloat(match[1]);

package/src/format.ts

@@ -9,7 +9,7 @@ const DAY = 24 * HOUR;
  */
 export function formatDuration(ms: number): string {
 	if (!Number.isFinite(ms) || ms <= 0) return "0ms";
-	if (ms < SEC) return `${ms}ms`;
+	if (ms < SEC) return `${Math.floor(ms)}ms`;
 	if (ms < MIN) return `${(ms / SEC).toFixed(1)}s`;
 	if (ms < HOUR) {
 		const mins = Math.floor(ms / MIN);

package/src/frontmatter.ts

@@ -22,6 +22,7 @@ export function normalizeFrontmatterKeys<T>(obj: T): T {
 	if (obj === null || typeof obj !== "object") return obj;
 	if (Array.isArray(obj)) {
 		let changed = false;
+		// [suppressed] length preallocation
 		const out: unknown[] = new Array(obj.length);
 		for (let i = 0; i < obj.length; i++) {
 			const v = obj[i];

package/src/index.ts

@@ -14,6 +14,7 @@ export * from "./json";
 export * from "./json-parse";
 export * as logger from "./logger";
 export * from "./loop-phase";
+export * from "./materialize-string";
 export * from "./math-delimiters";
 export * from "./mermaid-ascii";
 export * from "./mime";

package/src/marked/core.ts

@@ -343,8 +343,15 @@ const DEFAULTS: MarkedOptions = {
 };
 const PUNCTUATION = /[!"#$%&'()*+,\-./:;<=>?@[\\\]^_`{|}~]/;
 
-function tokenList(links: Links = {}): TokensList {
+function tokenList(links: Links = Object.create(null)): TokensList {
 	const list = [] as unknown as TokensList;
+	// The reference-definition map is keyed by user-controlled labels. A plain
+	// `{}` inherits `Object.prototype`, so a reference-style link whose label is
+	// an inherited member (`[x][constructor]`, `[x][__proto__]`) resolves to a
+	// truthy non-definition and yields a link token with `href: undefined`
+	// (issue #10283). A null-prototype map makes such lookups miss, so the link
+	// correctly falls back to literal text, and label writes cannot pollute the
+	// prototype.
 	list.links = links;
 	return list;
 }

package/src/materialize-string.ts

@@ -0,0 +1,10 @@
+/**
+ * Copy text into independent UTF-16 backing storage before a bounded substring outlives its source.
+ *
+ * The UTF-16 round trip preserves every JavaScript code unit, including lone
+ * surrogates that a UTF-8 round trip would replace.
+ */
+export function materializeString(text: string): string {
+	if (text.length === 0) return "";
+	return Buffer.from(text, "utf16le").toString("utf16le");
+}

package/src/path.ts

@@ -1,3 +1,17 @@
+import * as path from "node:path";
+
+const WINDOWS_DRIVE_PATH = /^([A-Za-z]):[\\/](.*)$/;
+
+/** Maps an absolute Windows drive path to the drive's default WSL mount. */
+export function windowsPathToWslMount(filePath: string): string | undefined {
+	const normalized = path.win32.normalize(filePath.trim());
+	const match = WINDOWS_DRIVE_PATH.exec(normalized);
+	if (!match) return undefined;
+	const [, drive, rest] = match;
+	const segments = rest.split("\\").filter(Boolean);
+	return path.posix.join("/mnt", drive!.toLowerCase(), ...segments);
+}
+
 const WINDOWS_DRIVE_EXTENDED_PREFIX = /^\\\\[?]\\([A-Za-z]:[\\/].*)$/;
 const WINDOWS_UNC_EXTENDED_PREFIX = /^\\\\[?]\\UNC[\\/]([^\\/]+)[\\/](.+)$/i;
 const WINDOWS_DRIVE_EXTENDED_FORWARD_PREFIX = /^\/\/[?]\/([A-Za-z]:\/.*)$/;

package/src/postmortem.ts

@@ -222,7 +222,7 @@ export function isInternalSocketClosedError(err: unknown): boolean {
 	const internal = frames.every(frame => {
 		const trimmed = frame.trim();
 		if (trimmed === "" || trimmed === "at unknown" || trimmed === "at native") return true;
-		if (!/\(node:[^)]*\)$/.test(trimmed) && !/^at node:/.test(trimmed)) return false;
+		if (!/\(node:[^)]*\)$/.test(trimmed) && !trimmed.startsWith("at node:")) return false;
 		hasNetFrame ||= trimmed.includes("node:net:");
 		return true;
 	});
@@ -395,23 +395,40 @@ function formatFatalError(label: string, err: Error): string {
 	return `\n[${label}] ${name}: ${message}${formattedStack}\n`;
 }
 
-async function exitAfterFatal(label: string, logMessage: string, err: Error, reason: Reason): Promise<void> {
+async function exitAfterFatal(output: string, logMessage: string, err: Error, reason: Reason): Promise<never> {
 	const forcedExit = setTimeout(() => exitProcess(1), CLEANUP_DEADLINE_MS);
 	try {
+		// Cleanup callbacks are invoked synchronously before runCleanup returns its
+		// completion promise. TUI owners therefore hand the cursor back before the
+		// fatal report is written, while slower resource cleanup continues afterward.
+		const cleanup = runCleanup(reason);
 		restoreTerminalStderr();
 		// A revoked terminal can make stream writes raise another fatal error. Use
 		// the descriptor directly so failure stays synchronous and contained.
 		try {
-			fs.writeSync(2, `${formatFatalError(label, err)}${formatFatalRecoveryHints()}`);
+			fs.writeSync(2, output);
 		} catch {}
 		logger.error(logMessage, { err });
-		await runCleanup(reason);
+		await cleanup;
 	} finally {
 		clearTimeout(forcedExit);
 		exitProcess(1);
 	}
 }
 
+/**
+ * Reports a caught top-level failure after terminal owners restore their display, then exits.
+ */
+export async function fatal(error: unknown): Promise<never> {
+	const err = error instanceof Error ? error : new Error(String(error));
+	const output = `${Bun.inspect(error, { colors: process.stderr.isTTY === true })}\n${formatFatalRecoveryHints()}`;
+	if (!isMainThread) {
+		process.stderr.write(output);
+		process.exit(1);
+	}
+	return exitAfterFatal(output, "Fatal error", err, Reason.UNHANDLED_REJECTION);
+}
+
 if (isMainThread) {
 	process
 		.on("SIGINT", async () => {
@@ -461,7 +478,12 @@ if (isMainThread) {
 				});
 				return;
 			}
-			await exitAfterFatal("Uncaught Exception", "Uncaught exception", err, Reason.UNCAUGHT_EXCEPTION);
+			await exitAfterFatal(
+				`${formatFatalError("Uncaught Exception", err)}${formatFatalRecoveryHints()}`,
+				"Uncaught exception",
+				err,
+				Reason.UNCAUGHT_EXCEPTION,
+			);
 		})
 		.on("unhandledRejection", async reason => {
 			const err = reason instanceof Error ? reason : new Error(String(reason));
@@ -497,7 +519,12 @@ if (isMainThread) {
 					});
 				}
 			}
-			await exitAfterFatal("Unhandled Rejection", "Unhandled rejection", err, Reason.UNHANDLED_REJECTION);
+			await exitAfterFatal(
+				`${formatFatalError("Unhandled Rejection", err)}${formatFatalRecoveryHints()}`,
+				"Unhandled rejection",
+				err,
+				Reason.UNHANDLED_REJECTION,
+			);
 		})
 		.on("exit", async () => {
 			void runCleanup(Reason.EXIT); // fire and forget (exit imminent)

package/src/prompt.ts

@@ -196,6 +196,7 @@ export function format(content: string, options: PromptFormatOptions = {}): stri
 	} = options;
 	const isPreRender = renderPhase === "pre-render";
 	const lines = content.split("\n");
+	// [suppressed] length preallocation
 	const result: string[] = new Array(lines.length);
 	let n = 0; // logical length of `result` (pops are n--)
 	let inCodeBlock = false;

package/src/ring.ts

@@ -15,6 +15,7 @@ export class RingBuffer<T> {
 	 * @param capacity - The maximum number of elements the buffer can hold. Must be positive.
 	 */
 	constructor(public readonly capacity: number) {
+		// [suppressed] length preallocation
 		this.#buf = new Array(capacity);
 	}
 

package/src/runtime-install.ts

@@ -2,6 +2,8 @@ import * as fs from "node:fs";
 import * as fsp from "node:fs/promises";
 import * as Module from "node:module";
 import * as path from "node:path";
+import { withFileLock } from "./file-lock";
+import { isEexist, isEnoent } from "./fs-error";
 
 /**
  * On-demand runtime dependency support for native-heavy optional packages
@@ -303,25 +305,62 @@ export interface EnsureRuntimeInstalledOptions {
 	lockSleepMs?: number;
 }
 
-function isErrnoCode(error: unknown, code: string): boolean {
-	return typeof error === "object" && error !== null && "code" in error && error.code === code;
-}
+/** No runtime install plausibly runs this long, so older legacy lock directories are crash orphans. */
+const STALE_LEGACY_LOCK_MS = 10 * 60_000;
 
-async function acquireInstallLock(runtimeDir: string, attempts: number, sleepMs: number): Promise<() => Promise<void>> {
-	const lockDir = `${runtimeDir}.lock`;
-	await fsp.mkdir(path.dirname(lockDir), { recursive: true });
-	for (let attempt = 0; attempt < attempts; attempt++) {
+/**
+ * Run `fn` while reserving the pre-crash-safe `${runtimeDir}.lock` namespace.
+ *
+ * Versions through 18.0.10 serialized installs with a bare lock *directory*
+ * that only its creator removed; an installer killed outside that window
+ * (SIGKILL/OOM/Ctrl-C) left it unreleasable, wedging every later install for
+ * the full wait envelope (issue #10120). During an in-flight upgrade a legacy
+ * process may still legitimately own this directory, so poll until it is
+ * released and only force-reclaim once the directory is older than any
+ * plausible install ({@link STALE_LEGACY_LOCK_MS}) — never merely because a
+ * retry budget elapsed, which would delete a still-active legacy lock and let
+ * two installers race the same tree. Once the namespace is free, atomically
+ * create and retain a regular file through `fn`: an older process cannot
+ * acquire it between the handoff check and the new install. A file left by a
+ * crashed new installer can be reused immediately because the outer OS lock
+ * proves its owner is gone, unlike a legacy directory whose owner is unknown.
+ */
+async function withLegacyInstallLock<T>(runtimeDir: string, sleepMs: number, fn: () => Promise<T>): Promise<T> {
+	const legacy = `${runtimeDir}.lock`;
+	for (;;) {
 		try {
-			await fsp.mkdir(lockDir);
-			return async () => {
-				await fsp.rm(lockDir, { recursive: true, force: true });
-			};
+			const reservation = await fsp.open(legacy, "wx");
+			await reservation.close();
 		} catch (error) {
-			if (!isErrnoCode(error, "EEXIST")) throw error;
-			await Bun.sleep(sleepMs);
+			if (!isEexist(error)) throw error;
+			let stat: fs.Stats;
+			try {
+				stat = await fsp.stat(legacy);
+			} catch (statError) {
+				if (isEnoent(statError)) continue; // released between open and stat; retry
+				throw statError;
+			}
+			// A non-directory is a reservation left by a newer installer. The
+			// outer OS lock proves that installer is gone, so reuse it at once.
+			if (!stat.isDirectory()) break;
+			// A fresh directory may still belong to a live pre-18.x installer, so
+			// wait for it to finish; only a crash orphan (older than any plausible
+			// install) is force-reclaimed.
+			if (Date.now() - stat.mtimeMs > STALE_LEGACY_LOCK_MS) {
+				await fsp.rm(legacy, { recursive: true, force: true });
+			} else {
+				await Bun.sleep(sleepMs);
+			}
+			continue;
 		}
+		break;
+	}
+	// Retain the regular-file reservation across the install.
+	try {
+		return await fn();
+	} finally {
+		await fsp.rm(legacy, { force: true });
 	}
-	throw new Error(`Timed out waiting for runtime install lock: ${lockDir}`);
 }
 
 export async function writeRuntimeManifest(runtimeDir: string, install: RuntimeInstallSpec): Promise<void> {
@@ -363,7 +402,14 @@ async function runRuntimeInstall(runtimeDir: string): Promise<void> {
 
 /**
  * Materialize a pinned dependency set into `runtimeDir` (idempotent,
- * cross-process safe via a lock directory). Returns `runtimeDir`.
+ * cross-process safe). Returns `runtimeDir`.
+ *
+ * Serialization uses the OS-backed {@link withFileLock} at
+ * `${runtimeDir}.install.lock`, which the kernel releases on process death, so
+ * a crashed installer cannot wedge later attempts (issue #10120). The path is
+ * deliberately distinct from the legacy `${runtimeDir}.lock` mkdir directory;
+ * {@link withLegacyInstallLock} atomically reserves that namespace during the
+ * new install so older processes cannot cross the migration boundary.
  */
 export async function ensureRuntimeInstalled(options: EnsureRuntimeInstalledOptions): Promise<string> {
 	const { runtimeDir, install, onPhase, lockAttempts = 240, lockSleepMs = 250 } = options;
@@ -379,15 +425,20 @@ export async function ensureRuntimeInstalled(options: EnsureRuntimeInstalledOpti
 	if (await probeManifest.exists()) return runtimeDir;
 
 	onPhase?.("initiate");
-	const releaseLock = await acquireInstallLock(runtimeDir, lockAttempts, lockSleepMs);
-	try {
-		if (await probeManifest.exists()) return runtimeDir;
-		await writeRuntimeManifest(runtimeDir, install);
-		onPhase?.("download");
-		await runRuntimeInstall(runtimeDir);
-		onPhase?.("done");
-		return runtimeDir;
-	} finally {
-		await releaseLock();
-	}
+	// withFileLock does not create parent directories; the runtime cache dir may
+	// not exist yet on the very first install.
+	await fsp.mkdir(path.dirname(runtimeDir), { recursive: true });
+	return withFileLock(
+		`${runtimeDir}.install`,
+		() =>
+			withLegacyInstallLock(runtimeDir, lockSleepMs, async () => {
+				if (await probeManifest.exists()) return runtimeDir;
+				await writeRuntimeManifest(runtimeDir, install);
+				onPhase?.("download");
+				await runRuntimeInstall(runtimeDir);
+				onPhase?.("done");
+				return runtimeDir;
+			}),
+		{ retries: lockAttempts, retryDelayMs: lockSleepMs },
+	);
 }

package/src/temp.ts

@@ -78,10 +78,12 @@ function normalizePrefix(prefix?: string): string {
 }
 
 const kRemoveOptions = { recursive: true, force: true } as const;
-const kRemoveRetries = 40;
-// 50ms × 40 retries = 2s total retry window. Windows holds file locks on
-// SQLite DBs for up to ~1.5s after close(); the previous 25ms (1s total)
-// was too short for some test cleanup scenarios.
+const kRemoveRetries = 150;
+// 50ms × 150 retries = 7.5s total retry window. Windows releases file locks on
+// SQLite DBs (and spawned-process CWDs) asynchronously after close(); the
+// measured release latency reaches ~730ms–5s when a child process just died
+// holding the directory, and the previous 2s window flaked suites that clean
+// up temp trees containing agent.db.
 const kRemoveRetryDelayMs = 50;
 const kRetryableRemoveErrorCodes = new Set(["EBUSY", "EPERM", "ENOTEMPTY"]);
 const kSleepBuffer = new Int32Array(new SharedArrayBuffer(4));
@@ -132,3 +134,13 @@ function sleepSync(ms: number): void {
 	}
 	Atomics.wait(kSleepBuffer, 0, 0, ms);
 }
+
+/**
+ * Create a directory symlink in a platform-correct way. Windows denies
+ * unprivileged file/dir symlinks (EPERM on `fs.symlink` without a type), but
+ * allows directory *junctions*, which every test that links temp directories
+ * should use instead. POSIX ignores the type argument.
+ */
+export function symlinkDirectorySync(target: string, linkPath: string): void {
+	fs.symlinkSync(target, linkPath, process.platform === "win32" ? "junction" : "dir");
+}

package/src/template.ts

@@ -549,7 +549,7 @@ export function compile<T = unknown>(source: string, options: CompileOptions = {
 	const nodes = parseTemplate(stripStandalone(source));
 	return (context, runtime = {}) => {
 		const root = context ?? {};
-		const frame: Frame = { context: root, parents: [], root, data: { root, ...(runtime.data ?? {}) } };
+		const frame: Frame = { context: root, parents: [], root, data: { root, ...runtime.data } };
 		return renderNodes(nodes, frame, { helpers, partials, options, runtime });
 	};
 }
@@ -579,7 +579,7 @@ export class TemplateEngine {
 		const nodes = parseTemplate(stripStandalone(source));
 		return (context, runtime = {}) => {
 			const root = context ?? {};
-			const frame: Frame = { context: root, parents: [], root, data: { root, ...(runtime.data ?? {}) } };
+			const frame: Frame = { context: root, parents: [], root, data: { root, ...runtime.data } };
 			return renderNodes(nodes, frame, { helpers: this.#helpers, partials: this.#partials, options, runtime });
 		};
 	}

package/src/tls-fetch.ts

@@ -174,5 +174,5 @@ export function withExtraCaFetch<T extends { fetch?: FetchImpl } | undefined>(op
 	const fetchImpl = options?.fetch ?? (globalThis.fetch as FetchImpl);
 	const wrapped = wrapFetchForExtraCa(fetchImpl);
 	if (wrapped === fetchImpl && options?.fetch !== undefined) return options;
-	return { ...(options ?? {}), fetch: wrapped } as T;
+	return { ...options, fetch: wrapped } as T;
 }

package/src/turndown/html.ts

@@ -222,7 +222,7 @@ export function parseHtmlFragment(html: string): TurndownNode {
 	const stack: HtmlNode[] = [root];
 	for (const token of htmlTokens(html)) {
 		const parent = stack[stack.length - 1] ?? root;
-		if (token.startsWith("<!--") || /^<!/i.test(token)) continue;
+		if (token.startsWith("<!--") || token.startsWith("<!")) continue;
 		if (!token.startsWith("<")) {
 			parent.append(new HtmlText(decodeEntities(token)));
 			continue;

package/src/vterm/query-responder.ts

@@ -0,0 +1,76 @@
+/**
+ * Answers terminal capability queries emitted by programs on a headless PTY.
+ *
+ * A PTY that advertises `TERM=xterm-256color` but has no terminal behind it
+ * leaves capability probes unanswered: a program writes a query escape to
+ * stdout and blocks on stdin until the reply arrives (or its timeout expires,
+ * seconds later). This scanner watches raw PTY output for the standard queries
+ * and returns the bytes a real xterm-class terminal would send back, so the
+ * caller can write them into the PTY. It keeps no screen state — cursor
+ * position reports are answered with the home position — which makes it cheap
+ * enough to run on every byte of a long-lived supervised process. Use the full
+ * {@link Terminal} when the caller also renders the output.
+ *
+ * Queries can straddle chunk boundaries, so an unfinished trailing escape is
+ * carried into the next {@link feed}.
+ */
+export class TerminalQueryResponder {
+	/** Trailing bytes that may be the start of an unfinished query escape. */
+	#residual = "";
+
+	/**
+	 * Feed one raw PTY output chunk. Returns the reply bytes to write back into
+	 * the PTY, or an empty string when the chunk held no answerable query.
+	 */
+	feed(chunk: string): string {
+		const buffer = this.#residual + chunk;
+		let replies = "";
+		let lastEnd = 0;
+		QUERY.lastIndex = 0;
+		for (let match = QUERY.exec(buffer); match !== null; match = QUERY.exec(buffer)) {
+			lastEnd = match.index + match[0].length;
+			replies += replyFor(match);
+		}
+		// Keep only a short unmatched trailing escape: a query split across
+		// chunks completes on the next feed, while a long tail is ordinary output
+		// that can never become a query.
+		const tailEscape = buffer.lastIndexOf("\x1b");
+		this.#residual =
+			tailEscape >= lastEnd && buffer.length - tailEscape <= MAX_PARTIAL_QUERY ? buffer.slice(tailEscape) : "";
+		return replies;
+	}
+}
+
+/** Longest query escape we answer, bounding the cross-chunk residual. */
+const MAX_PARTIAL_QUERY = 32;
+
+/**
+ * CSI DSR/DA queries (final byte `n` or `c`) and OSC 10/11 color queries. Only
+ * forms with canned answers are matched; everything else stays plain output.
+ */
+const QUERY = /\x1b\[([?>=]?)([0-9;]*)([nc])|\x1b\](10|11);\?(\x07|\x1b\\)/gu;
+
+/** Reply a real xterm-class terminal would send for one matched query. */
+function replyFor(match: RegExpExecArray): string {
+	const final = match[3];
+	if (final !== undefined) {
+		const intermediate = match[1];
+		const params = match[2] ?? "";
+		if (final === "c") {
+			if (intermediate === ">") return "\x1b[>0;10;1c"; // secondary DA: VT100-class, firmware 10
+			if (intermediate === "" || intermediate === "0") return "\x1b[?1;2c"; // primary DA: VT100 with AVO
+			return ""; // tertiary (`=`) DA has no widely expected reply
+		}
+		if (intermediate !== "") return ""; // private DSR forms (DECXCPR, appearance) stay unanswered
+		const selector = params.split(";", 1)[0];
+		if (selector === "6") return "\x1b[1;1R"; // cursor position: home, there is no screen
+		if (selector === "5") return "\x1b[0n"; // device status: OK
+		return "";
+	}
+	// OSC color queries: neutral colors, terminated the way the request was.
+	const selector = match[4];
+	const terminator = match[5] ?? "\x07";
+	if (selector === "10") return `\x1b]10;rgb:ffff/ffff/ffff${terminator}`; // foreground
+	if (selector === "11") return `\x1b]11;rgb:0000/0000/0000${terminator}`; // background
+	return "";
+}

package/src/vterm.ts

@@ -1,5 +1,6 @@
 /** Behavior-compatible reimplementation of @xterm/headless's used surface. */
 export * from "./vterm/buffer";
+export * from "./vterm/query-responder";
 export * from "./vterm/terminal";
 
 import { Terminal } from "./vterm/terminal";