@oh-my-pi/pi-utils 18.2.0 → 18.2.1

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [18.2.1] - 2026-09-15
+
+### Added
+
+- Added the public `postmortem.exitProcess()` utility for host-owned hard exits that must bypass temporary process-exit guards ([#11789](https://github.com/can1357/oh-my-pi/issues/11789)).
+- Added `readSseJsonOrText`: like `readSseJson`, but a `data:` frame that is not valid JSON is yielded as its raw text instead of raising a `SyntaxError`, so a consumer can classify a reverse proxy's plain-text throttle page (`429 Too Many Requests`) that arrives after the stream headers were already sent. `readSseJson` is unchanged and shares the framing with it.
+
+### Fixed
+
+- Reading an EPUB, PPTX or XLSX whose XML has a mismatched or stray end tag no longer hangs the session forever; the parser recovers and the document converts ([#12018](https://github.com/can1357/oh-my-pi/pull/12018) by [@kaluli123123](https://github.com/kaluli123123)).
+- Fixed `filterChildShellEnv` forwarding the host process's `GIT_DIR`, `GIT_WORK_TREE`, and related repo-location overrides to child shells, where `git` would ignore the command's `cwd`.
+- ACP JSON-RPC now drains accepted inbound requests on clean stdin EOF before resolving `closed`, so in-flight methods such as `session/new` still receive a success or explicit error response instead of being dropped on exit 0 ([#11567](https://github.com/can1357/oh-my-pi/issues/11567)).
+- Fixed provider-local usage-limit reset timestamps making `waitForUsageReset` sessions resume up to eight hours late while preserving longest-window semantics for naive UTC timestamps ([#11014](https://github.com/can1357/oh-my-pi/issues/11014)).
+- `registerStdioDisconnectHandling()` now drives graceful shutdown from `process.stdout`'s own `error` event, so a closed stdout consumer exits cleanly while an unrelated write EPIPE (subprocess stdin, socket) stays fatal ([#10930](https://github.com/can1357/oh-my-pi/issues/10930)).
+- Fixed Linux `ptree` timeout cleanup occasionally leaving session-escaped descendants running during subreaper adoption.
+
 ## [18.2.0] - 2026-09-15
 
 ### Breaking Changes

package/dist/types/dirs.d.ts

@@ -281,6 +281,13 @@ export declare function getAgentModulesDir(agentDir?: string): string;
 export declare function getMemoriesDir(agentDir?: string): string;
 /** Get the terminal sessions directory (~/.omp/agent/terminal-sessions). */
 export declare function getTerminalSessionsDir(agentDir?: string): string;
+/**
+ * Get the persistent registry of custom session files
+ * (~/.omp/agent/custom-session-files). Each `--session-dir`/`--session`
+ * transcript is recorded here as one marker file so storage GC can scan its
+ * exact path after its terminal breadcrumb is overwritten by a later session.
+ */
+export declare function getCustomSessionFilesDir(agentDir?: string): string;
 /** Get the crash log path (~/.omp/agent/omp-crash.log). */
 export declare function getCrashLogPath(agentDir?: string): string;
 /** Get the debug log path (~/.omp/agent/omp-debug.log). */

package/dist/types/env.d.ts

@@ -26,6 +26,14 @@ export declare function isMacosMallocStackLoggingEnvName(name: string): boolean;
  */
 export declare function isWsl(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): boolean;
 export declare function filterProcessEnv(env: Record<string, string | undefined>): Record<string, string>;
+/**
+ * Removes {@link GIT_REPO_LOCATION_ENV_NAMES} from a copied child env in place.
+ *
+ * Windows environment lookups are case-insensitive, so a block that spells a
+ * variable `git_dir` is just as binding there; match case-insensitively on
+ * win32 and exactly elsewhere (POSIX env names are case-sensitive).
+ */
+export declare function stripGitRepoLocationEnv(env: Record<string, string>, platform?: NodeJS.Platform): void;
 /** 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/executable.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Check if a file path exists, is a regular file, and has effective execute permission.
+ */
+export declare function isExecutable(filePath: string): boolean;

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

@@ -1,3 +1,8 @@
+/** Provider-specific interpretation for timezone-naive retry timestamps. */
+export interface RetryHintOptions {
+    /** UTC offset appended to an absolute reset stamp that omits its timezone. */
+    naiveResetTimezoneOffset?: string;
+}
 /**
  * Server-suggested retry delay extraction. Merges the patterns historically used
  *
@@ -15,14 +20,14 @@
  *  - `try again in 250ms` / `try again in 12s` / `try again in 5 min` / `try again in ~158 min`
  *  - `retry-after-ms=98497000` / `retry-after-ms: 7200000` / `retry-after-ms = 7200000`
  *  - `Your limit will reset at 2026-09-01 09:44:51` / `将在 2026-09-01 09:44:51 重置`
- *    (offset-bearing only; a timezone-naive stamp is provider wall clock in
- *    an unknown zone and only resolves when no relative signal is present)
+ *    (a provider offset makes a naive wall clock authoritative; otherwise it
+ *    resolves only when no relative signal is present)
  *
  * Returns `undefined` if no signal is found, or `0` when the provider
  * explicitly asks for an immediate retry (`retry-after…=0`, or an absolute
  * reset timestamp that has already elapsed).
  */
-export declare function extractRetryHint(source: Response | Headers | null | undefined, body?: string): number | undefined;
+export declare function extractRetryHint(source: Response | Headers | null | undefined, body?: string, options?: RetryHintOptions): number | undefined;
 export interface FetchWithRetryOptions extends RequestInit {
     /** Total fetch attempts (initial + retries). Default `5`. */
     maxAttempts?: number;

package/dist/types/file-lock.d.ts

@@ -16,6 +16,8 @@ declare function tryAcquireLock(lockPath: string): NativeFileLock | null;
 export declare function acquireFileLock(filePath: string, options?: FileLockOptions): Promise<FileLockHandle>;
 /** Run `fn` while holding an OS-backed exclusive lock for `filePath`. */
 export declare function withFileLock<T>(filePath: string, fn: () => Promise<T>, options?: FileLockOptions): Promise<T>;
+/** Run synchronous `fn` while holding an OS-backed exclusive lock for `filePath`. */
+export declare function withFileLockSync<T>(filePath: string, fn: () => T, options?: FileLockOptions): T;
 /**
  * Test-only acquisition handle for forcing ownership handoffs. This is not
  * part of the supported package API.

package/dist/types/index.d.ts

@@ -4,6 +4,7 @@ export * from "./binary.js";
 export * from "./color.js";
 export * from "./dirs.js";
 export * from "./env.js";
+export * from "./executable.js";
 export * from "./fetch-retry.js";
 export * from "./file-lock.js";
 export * from "./format.js";

package/dist/types/mime.d.ts

@@ -1,3 +1,4 @@
+export declare const IMAGE_METADATA_HEADER_BYTES: number;
 export declare const SUPPORTED_IMAGE_MIME_TYPES: Set<string>;
 export type ImageMetadata = {
     mimeType: "image/png";

package/dist/types/path.d.ts

@@ -2,3 +2,9 @@
 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;
+/**
+ * Test whether a path is fully qualified and drive-independent.
+ * On Windows, requires a drive letter with separator (e.g. `C:\`) or UNC (`\\server\share` or `//server/share`).
+ * On POSIX, requires an absolute path.
+ */
+export declare function isFullyQualifiedPath(filePath: string, platform?: NodeJS.Platform): boolean;

package/dist/types/postmortem.d.ts

@@ -27,6 +27,27 @@ export declare enum Reason {
  * instances across bundles/realms.
  */
 export declare const NATIVE_PROCESS_EXIT: unique symbol;
+/**
+ * Hard-exit the process through the native primitive, resolved on every call.
+ *
+ * The native exit is deliberately re-resolved here rather than bound at module
+ * load: the extension/hook loader's `withHostGuard` transiently swaps
+ * `process.reallyExit`/`process.exit` for a stub that throws
+ * `ExtensionExitError`, and the shipped bundle defers this module's evaluation
+ * until first access — which can land inside that guard window, so binding at
+ * init could freeze the throwing stub forever and turn every later shutdown
+ * (SIGHUP/SIGINT/fatal) into an unhandled-rejection loop (#7393). When the
+ * guard is active the stub carries the native exit under
+ * {@link NATIVE_PROCESS_EXIT} (#6488).
+ *
+ * Both globals are reinstalled to their natives before exiting: Bun's
+ * `process.exit` re-reads `process.reallyExit` at call time, so exiting through
+ * one primitive while its sibling still holds the throwing stub re-enters the
+ * guard and loops the rejection storm (#11789). After restoring, `reallyExit`
+ * (the low-level primitive) is preferred; `process.exit` and finally `SIGKILL`
+ * are fallbacks so a poisoned or absent chain can never leave the process alive.
+ */
+export declare function exitProcess(code: number): never;
 /** User-facing command printed before fatal cleanup so interrupted work can be resumed. */
 export interface FatalRecoveryHint {
     /** Stable label identifying the recoverable session or process. */
@@ -91,11 +112,11 @@ export declare function isWorkerIpcDeserializeError(err: unknown): boolean;
  */
 export declare function registerWorkerIpcFaultHandler(handler: (err: Error) => void): () => void;
 /**
- * Treat unhandled stdout EPIPE rejections as a graceful peer disconnect.
- *
- * Stdio protocol servers call this for their process lifetime so a closed
- * client pipe runs registered cleanup callbacks instead of the fatal path.
- * The returned callback removes the registration.
+ * Treat a closed stdout consumer as a graceful peer disconnect for the caller's
+ * active lifetime. Attaches one shared `process.stdout` `error` listener,
+ * ref-counted across registrants (the ACP protocol server, the one-shot CLI
+ * entry). The returned callback removes the registration; the listener detaches
+ * when the last registrant unregisters.
  */
 export declare function registerStdioDisconnectHandling(): () => void;
 /**

package/dist/types/procmgr.d.ts

@@ -1,4 +1,6 @@
 import type { Subprocess } from "bun";
+import { isExecutable } from "./executable.js";
+export { isExecutable };
 export interface ShellConfig {
     shell: string;
     args: string[];
@@ -10,10 +12,6 @@ export interface ShellConfigOptions {
     /** File path or runtime layer that supplied the active shell setting. */
     configSource?: string;
 }
-/**
- * Check if a shell binary is executable.
- */
-export declare function isExecutable(path: string): boolean;
 /**
  * Get shell args for the resolved shell.
  * cmd.exe takes `/c`; PowerShell (powershell.exe / pwsh) takes

package/dist/types/snowflake.d.ts

@@ -5,6 +5,7 @@ declare namespace Snowflake {
     const PATTERN: RegExp;
     const EPOCH_TIMESTAMP = 1420070400000;
     const MAX_SEQUENCE = 4194303;
+    const MAX_TIMESTAMP: number;
     function formatParts(dt: number, seq: number): Snowflake;
     class Source {
         #private;

package/dist/types/stream.d.ts

@@ -1,5 +1,31 @@
 export declare function readLines(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<Uint8Array>;
 export declare function readJsonl<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<T>;
+/**
+ * Amortized byte accumulator for chunked stream readers.
+ *
+ * Holds the unconsumed tail of a stream in a single growing `Buffer` so that
+ * appending N chunks costs O(total bytes) instead of re-copying the whole
+ * prefix per chunk. Backs {@link readLines}, {@link readJsonl} and
+ * {@link readSseEvents}; also usable directly when a reader needs its own
+ * framing loop (see `consume` and `flush`).
+ */
+export declare class ConcatSink {
+    #private;
+    append(chunk: Uint8Array): void;
+    reset(chunk: Uint8Array): void;
+    get isEmpty(): boolean;
+    /**
+     * The buffered bytes as a live view — invalidated by the next `append`,
+     * `reset` or `consume`.
+     */
+    flush(): Uint8Array | undefined;
+    /** Drop the first `count` buffered bytes, keeping the remainder. */
+    consume(count: number): void;
+    clear(): void;
+    appendAndFlushLines(chunk: Uint8Array): Generator<Uint8Array<ArrayBufferLike>, void, unknown>;
+    appendAndFlushText(chunk: Uint8Array, decoder: TextDecoder): string | undefined;
+    pullJSONL<T>(chunk: Uint8Array, beg: number, end: number): Generator<T, void, unknown>;
+}
 /**
  * Stream parsed JSON objects from SSE `data:` lines.
  *
@@ -18,6 +44,25 @@ export declare function readJsonl<T>(stream: ReadableStream<Uint8Array>, signal?
  */
 export type SseEventObserver = (event: ServerSentEvent) => void;
 export declare function readSseJson<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal, onEvent?: SseEventObserver): AsyncGenerator<T>;
+/**
+ * Like {@link readSseJson}, but a `data:` frame that is not valid JSON is yielded
+ * as its raw text instead of raising a `SyntaxError`. Cut-off container-shaped
+ * stream tails stay recoverable, exactly as they are in {@link readSseJson}.
+ *
+ * Consumers that only understand objects must treat a `string` yield as a
+ * transport-level failure (for example a `429 Too Many Requests` or an HTML
+ * throttle page from a reverse proxy that already committed to the stream). This
+ * exists because `readSseJson`'s baseline consumers span unrelated transports
+ * whose error handling a text yield would subtly change; new call sites opt in.
+ *
+ * Note that the text lane is only the frames `JSON.parse` *rejected*: a frame
+ * carrying a JSON-encoded string (`data: "429 Too Many Requests"`) parses, so it
+ * is yielded as that string and is indistinguishable from a rejected frame by
+ * type alone. Consumers branching on `typeof === "string"` therefore see both,
+ * which is the safe direction — each is classified as text rather than trusted as
+ * an event object.
+ */
+export declare function readSseJsonOrText<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal, onEvent?: SseEventObserver): AsyncGenerator<T | string>;
 /**
  * A single Server-Sent Event dispatched on a blank-line boundary.
  *

package/dist/types/which.d.ts

@@ -25,6 +25,12 @@ export interface WhichOptions extends Bun.WhichOptions {
      * Defaults to `WhichCachePolicy.Fresh`.
      */
     cache?: WhichCachePolicy;
+    /**
+     * Only search absolute directory entries in PATH, ignoring relative entries
+     * (e.g. `.` or `./bin`) and empty components to prevent resolving against
+     * an untrusted working directory.
+     */
+    requireAbsolutePaths?: boolean;
 }
 declare function darwinWhich(command: string, options?: Bun.WhichOptions): string | null;
 export declare const whichFresh: typeof darwinWhich;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-utils",
-	"version": "18.2.0",
+	"version": "18.2.1",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"cli",
@@ -54,7 +54,7 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.2.0"
+		"@oh-my-pi/pi-natives": "18.2.1"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/acp/transport.ts

@@ -108,10 +108,15 @@ function createStandardError(
 type Dispatcher = (method: string, params: unknown, notification: boolean) => MaybePromise<unknown>;
 type Pending = { resolve(value: unknown): void; reject(reason: unknown): void };
 
+/** Bound on clean-EOF inbound drain so `closed` cannot hang if a handler never settles. */
+const INBOUND_DRAIN_TIMEOUT_MS = 30_000;
+
 /** Correlated bidirectional JSON-RPC connection. */
 export class RpcConnection {
 	#nextId = 0;
 	#pending = new Map<JsonRpcId, Pending>();
+	#inbound = new Set<Promise<void>>();
+	#openInboundIds = new Set<JsonRpcId>();
 	#writable: WritableStream<AnyMessage>;
 	#writeTail: Promise<void> = Promise.resolve();
 	#abort = new AbortController();
@@ -179,8 +184,9 @@ export class RpcConnection {
 			while (true) {
 				const next = await reader.read();
 				if (next.done) break;
-				void this.#handle(next.value).catch(error => this.close(error));
+				this.#dispatch(next.value);
 			}
+			await this.#drainInbound();
 			this.close();
 		} catch (error) {
 			this.close(error);
@@ -189,6 +195,34 @@ export class RpcConnection {
 		}
 	}
 
+	#dispatch(message: AnyMessage): void {
+		if ("method" in message && "id" in message) this.#openInboundIds.add(message.id);
+		const task = this.#handle(message).catch(error => this.close(error));
+		this.#inbound.add(task);
+		void task.finally(() => this.#inbound.delete(task));
+	}
+
+	async #drainInbound(): Promise<void> {
+		if (this.#inbound.size === 0) return;
+		const drained = Promise.allSettled(this.#inbound).then(() => {});
+		let timer: Timer | undefined;
+		const timedOut = await Promise.race([
+			drained.then(() => false),
+			new Promise<boolean>(resolve => {
+				timer = setTimeout(() => resolve(true), INBOUND_DRAIN_TIMEOUT_MS);
+			}),
+		]);
+		if (timer !== undefined) clearTimeout(timer);
+		if (!timedOut) return;
+		const error = RequestError.internalError(undefined, "Inbound request drain timed out").toErrorResponse();
+		await Promise.allSettled([...this.#openInboundIds].map(id => this.#respond(id, { error })));
+	}
+
+	#respond(id: JsonRpcId, body: { result: unknown } | { error: ErrorResponse }): Promise<void> {
+		if (!this.#openInboundIds.delete(id)) return Promise.resolve();
+		return this.#write({ jsonrpc: "2.0", id, ...body });
+	}
+
 	async #handle(message: AnyMessage): Promise<void> {
 		if ("id" in message && !("method" in message)) {
 			const pending = this.#pending.get(message.id);
@@ -210,13 +244,13 @@ export class RpcConnection {
 		}
 		try {
 			const result = await this.#dispatcher(message.method, message.params, false);
-			await this.#write({ jsonrpc: "2.0", id: message.id, result: result ?? {} });
+			await this.#respond(message.id, { result: result ?? {} });
 		} catch (error) {
 			const protocolError =
 				error instanceof RequestError
 					? error
 					: RequestError.internalError({ details: error instanceof Error ? error.message : String(error) });
-			await this.#write({ jsonrpc: "2.0", id: message.id, error: protocolError.toErrorResponse() });
+			await this.#respond(message.id, { error: protocolError.toErrorResponse() });
 		}
 	}
 }

package/src/dirs.ts

@@ -931,6 +931,16 @@ export function getTerminalSessionsDir(agentDir?: string): string {
 	return dirs.agentSubdir(agentDir, "terminal-sessions", "state");
 }
 
+/**
+ * Get the persistent registry of custom session files
+ * (~/.omp/agent/custom-session-files). Each `--session-dir`/`--session`
+ * transcript is recorded here as one marker file so storage GC can scan its
+ * exact path after its terminal breadcrumb is overwritten by a later session.
+ */
+export function getCustomSessionFilesDir(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, "custom-session-files", "state");
+}
+
 /** Get the crash log path (~/.omp/agent/omp-crash.log). */
 export function getCrashLogPath(agentDir?: string): string {
 	return dirs.agentSubdir(agentDir, "omp-crash.log", "state");

package/src/env.ts

@@ -65,6 +65,48 @@ export function filterProcessEnv(env: Record<string, string | undefined>): Recor
 	}
 	return result;
 }
+/**
+ * Git variables that pin a repository location. They describe the checkout the
+ * agent process itself was launched from (git hooks, `git --git-dir` wrappers),
+ * so forwarding them to a child shell makes `git` ignore the command's `cwd`
+ * and mutate the wrong worktree or index. Stripped from child shell envs so git
+ * rediscovers the repository from the working directory. Mirrors the
+ * `env_remove` list in `crates/pi-vcs/src/git/cli.rs`.
+ */
+const GIT_REPO_LOCATION_ENV_NAMES = [
+	"GIT_DIR",
+	"GIT_COMMON_DIR",
+	"GIT_WORK_TREE",
+	"GIT_INDEX_FILE",
+	"GIT_OBJECT_DIRECTORY",
+	"GIT_ALTERNATE_OBJECT_DIRECTORIES",
+] as const;
+
+/**
+ * Removes {@link GIT_REPO_LOCATION_ENV_NAMES} from a copied child env in place.
+ *
+ * Windows environment lookups are case-insensitive, so a block that spells a
+ * variable `git_dir` is just as binding there; match case-insensitively on
+ * win32 and exactly elsewhere (POSIX env names are case-sensitive).
+ */
+export function stripGitRepoLocationEnv(
+	env: Record<string, string>,
+	platform: NodeJS.Platform = process.platform,
+): void {
+	if (platform !== "win32") {
+		for (const name of GIT_REPO_LOCATION_ENV_NAMES) {
+			delete env[name];
+		}
+		return;
+	}
+	const folded = new Set<string>(GIT_REPO_LOCATION_ENV_NAMES.map(name => name.toLowerCase()));
+	for (const key of Object.keys(env)) {
+		if (folded.has(key.toLowerCase())) {
+			delete env[key];
+		}
+	}
+}
+
 // Bun autoloads the project's dotenv files into `process.env` before user code
 // runs — including inside `bun build --compile` binaries — so a snapshot of
 // `Bun.env` is only pre-dotenv when autoloading was explicitly disabled. Linux
@@ -181,6 +223,9 @@ export function filterChildShellEnv(
 			delete result[key];
 		}
 	}
+	// Last, after dotenv merging: no source (inherited, launcher, or dotenv) may
+	// pin the child shell to the agent's own repository.
+	stripGitRepoLocationEnv(result);
 	return result;
 }
 

package/src/executable.ts

@@ -0,0 +1,17 @@
+import * as fs from "node:fs";
+
+/**
+ * Check if a file path exists, is a regular file, and has effective execute permission.
+ */
+export function isExecutable(filePath: string): boolean {
+	try {
+		const stat = fs.statSync(filePath);
+		if (!stat.isFile()) return false;
+		if (process.platform !== "win32") {
+			fs.accessSync(filePath, fs.constants.X_OK);
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}

package/src/fetch-retry.ts

@@ -20,7 +20,11 @@ const RESET_IN_HR_MIN_PATTERN = /resets?\s+in\s+~?\s*(\d+(?:\.\d+)?)\s*hr\s*(\d+
 // "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;
+// Both grammars carry a timezone-naive wall clock. The default reading is UTC;
+// a provider-specific offset (Z.AI/Zhipu Beijing time) is applied only through
+// `RetryHintOptions.naiveResetTimezoneOffset`, never inferred from the language.
 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*重置/;
+const RESET_AT_PATTERNS: readonly RegExp[] = [WILL_RESET_AT_PATTERN, CN_RESET_AT_PATTERN];
 // "retry-after-ms=98497000" / "retry-after-ms: 7200000" / "retry-after-ms = 7200000"
 const RETRY_AFTER_MS_BODY_PATTERN = /\bretry-after-ms\s*[:=]\s*([0-9]+)\b/i;
 
@@ -34,6 +38,12 @@ const RETRY_AFTER_MS_BODY_PATTERN = /\bretry-after-ms\s*[:=]\s*([0-9]+)\b/i;
 // ignores the naive stamp) sleeps first, and the retry after it is the
 // probe — success proves skew, a fresh 429 re-anchors with live timing.
 
+/** Provider-specific interpretation for timezone-naive retry timestamps. */
+export interface RetryHintOptions {
+	/** UTC offset appended to an absolute reset stamp that omits its timezone. */
+	naiveResetTimezoneOffset?: string;
+}
+
 /**
  * Server-suggested retry delay extraction. Merges the patterns historically used
  *
@@ -51,14 +61,18 @@ const RETRY_AFTER_MS_BODY_PATTERN = /\bretry-after-ms\s*[:=]\s*([0-9]+)\b/i;
  *  - `try again in 250ms` / `try again in 12s` / `try again in 5 min` / `try again in ~158 min`
  *  - `retry-after-ms=98497000` / `retry-after-ms: 7200000` / `retry-after-ms = 7200000`
  *  - `Your limit will reset at 2026-09-01 09:44:51` / `将在 2026-09-01 09:44:51 重置`
- *    (offset-bearing only; a timezone-naive stamp is provider wall clock in
- *    an unknown zone and only resolves when no relative signal is present)
+ *    (a provider offset makes a naive wall clock authoritative; otherwise it
+ *    resolves only when no relative signal is present)
  *
  * Returns `undefined` if no signal is found, or `0` when the provider
  * explicitly asks for an immediate retry (`retry-after…=0`, or an absolute
  * reset timestamp that has already elapsed).
  */
-export function extractRetryHint(source: Response | Headers | null | undefined, body?: string): number | undefined {
+export function extractRetryHint(
+	source: Response | Headers | null | undefined,
+	body?: string,
+	options?: RetryHintOptions,
+): number | undefined {
 	const headers = source instanceof Headers ? source : (source?.headers ?? undefined);
 	if (headers) {
 		const retryAfterMs = headers.get("retry-after-ms");
@@ -142,25 +156,20 @@ export function extractRetryHint(source: Response | Headers | null | undefined,
 			consider(totalMs > 0 ? totalMs : undefined);
 		}
 	}
-	for (const pattern of [WILL_RESET_AT_PATTERN, CN_RESET_AT_PATTERN]) {
+	for (const pattern of RESET_AT_PATTERNS) {
 		const match = pattern.exec(body);
 		if (!match?.[1]) continue;
 		// Offset-bearing stamps are unambiguous and compete by longest-wins.
-		// Naive stamps (provider wall clock, unknown zone) resolve after the
-		// relative signals below, and only when nothing unambiguous was
-		// found — never by guessing the zone against a conflicting signal.
+		// A configured provider offset makes an otherwise naive wall clock
+		// unambiguous too. Without one, preserve the relative-signal-first
+		// fallback and interpret the wall clock as UTC only when it stands alone.
 		const normalized = match[1].replace(" ", "T");
 		const hasOffset = /(?:Z|[+-][0-9]{2}:?[0-9]{2})$/i.test(normalized);
-		if (hasOffset) {
-			const parsed = Date.parse(normalized);
-			if (!Number.isNaN(parsed) && parsed > Date.now()) {
-				consider(parsed - Date.now());
-			}
-		} else {
-			const parsed = Date.parse(`${normalized}Z`);
-			if (!Number.isNaN(parsed) && parsed > Date.now()) {
-				considerNaive(parsed - Date.now());
-			}
+		const configuredOffset = options?.naiveResetTimezoneOffset;
+		const parsed = Date.parse(hasOffset ? normalized : `${normalized}${configuredOffset ?? "Z"}`);
+		if (!Number.isNaN(parsed) && parsed > Date.now()) {
+			if (hasOffset || configuredOffset !== undefined) consider(parsed - Date.now());
+			else considerNaive(parsed - Date.now());
 		}
 	}
 	// OpenCode Go compound remainder ("Resets in 2hr 15min"): the generic

package/src/file-lock.ts

@@ -48,6 +48,19 @@ export async function acquireFileLock(filePath: string, options: FileLockOptions
 	throw new Error(`Failed to acquire lock for ${filePath} after ${opts.retries} attempts`);
 }
 
+function acquireLockSync(filePath: string, options: FileLockOptions = {}): NativeFileLock {
+	const opts = { ...DEFAULT_OPTIONS, ...options };
+	const lockPath = getLockPath(filePath);
+
+	for (let attempt = 0; attempt < opts.retries; attempt++) {
+		const lock = tryAcquireLock(lockPath);
+		if (lock) return lock;
+		if (attempt + 1 < opts.retries && opts.retryDelayMs > 0) Bun.sleepSync(opts.retryDelayMs);
+	}
+
+	throw new Error(`Failed to acquire lock for ${filePath} after ${opts.retries} attempts`);
+}
+
 /** Run `fn` while holding an OS-backed exclusive lock for `filePath`. */
 export async function withFileLock<T>(
 	filePath: string,
@@ -62,6 +75,16 @@ export async function withFileLock<T>(
 	}
 }
 
+/** Run synchronous `fn` while holding an OS-backed exclusive lock for `filePath`. */
+export function withFileLockSync<T>(filePath: string, fn: () => T, options: FileLockOptions = {}): T {
+	const lock = acquireLockSync(filePath, options);
+	try {
+		return fn();
+	} finally {
+		lock.release();
+	}
+}
+
 /**
  * Test-only acquisition handle for forcing ownership handoffs. This is not
  * part of the supported package API.

package/src/index.ts

@@ -4,6 +4,7 @@ export * from "./binary";
 export * from "./color";
 export * from "./dirs";
 export * from "./env";
+export * from "./executable";
 export * from "./fetch-retry";
 export * from "./file-lock";
 export * from "./format";

package/src/logger.ts

@@ -289,12 +289,11 @@ function getLocalTransports(): LocalTransports {
 
 function emitLocally(level: LogLevel, message: string, context: Record<string, unknown> | undefined): void {
 	const transports = getLocalTransports();
-	const info = normalizeLogInfo(level, message, context);
 	if (!transports.file && !transports.console) return;
-
+	const info = normalizeLogInfo(level, message, context);
 	const line = formatLogInfo(info);
 	if (transports.file) transports.file.write(line);
-	if (transports.console) fs.writeSync(1, `${formatLogInfo(info)}${os.EOL}`);
+	if (transports.console) fs.writeSync(1, `${line}${os.EOL}`);
 }
 
 /**

package/src/mime.ts

@@ -1,7 +1,6 @@
 import { peekFile, peekFileSync } from "./peek-file";
 
-const DEFAULT_IMAGE_METADATA_HEADER_BYTES = 256 * 1024;
-
+export const IMAGE_METADATA_HEADER_BYTES = 256 * 1024;
 const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 const JPEG_MAGIC = Buffer.from([0xff, 0xd8, 0xff]);
 const WEBP_RIFF_MAGIC = Buffer.from([0x52, 0x49, 0x46, 0x46]);
@@ -144,16 +143,13 @@ export function parseImageMetadata(header: Uint8Array): ImageMetadata | null {
 	);
 }
 
-export function readImageMetadataSync(
-	filePath: string,
-	maxBytes = DEFAULT_IMAGE_METADATA_HEADER_BYTES,
-): ImageMetadata | null {
+export function readImageMetadataSync(filePath: string, maxBytes = IMAGE_METADATA_HEADER_BYTES): ImageMetadata | null {
 	return peekFileSync(filePath, maxBytes, parseImageMetadata);
 }
 
 export function readImageMetadata(
 	filePath: string,
-	maxBytes = DEFAULT_IMAGE_METADATA_HEADER_BYTES,
+	maxBytes = IMAGE_METADATA_HEADER_BYTES,
 ): Promise<ImageMetadata | null> {
 	return peekFile(filePath, maxBytes, parseImageMetadata);
 }

package/src/path.ts

@@ -40,3 +40,17 @@ export function stripWindowsExtendedLengthPathPrefix(
 
 	return filePath;
 }
+
+/**
+ * Test whether a path is fully qualified and drive-independent.
+ * On Windows, requires a drive letter with separator (e.g. `C:\`) or UNC (`\\server\share` or `//server/share`).
+ * On POSIX, requires an absolute path.
+ */
+export function isFullyQualifiedPath(filePath: string, platform: NodeJS.Platform = process.platform): boolean {
+	const p = platform === "win32" ? path.win32 : path.posix;
+	if (!p.isAbsolute(filePath)) return false;
+	if (platform === "win32") {
+		return /^[a-zA-Z]:[/\\]/.test(filePath) || /^[\\/]{2}[^\\/]/.test(filePath);
+	}
+	return true;
+}

package/src/postmortem.ts

@@ -57,6 +57,26 @@ export const NATIVE_PROCESS_EXIT = Symbol.for("omp.postmortem.nativeProcessExit"
 
 type HardExitFn = (code?: number) => never;
 
+/**
+ * Walk a guarded exit primitive down to the native it shadows.
+ *
+ * `withHostGuard` stamps each throwing replacement with the primitive it
+ * shadows under {@link NATIVE_PROCESS_EXIT}; nested guard windows stack, so a
+ * single unwrap can still land on another throwing stub. Follow the chain
+ * (cycle-guarded) until a link carries no stamp — that link is native.
+ */
+function nativeHardExit(fn: HardExitFn | undefined): HardExitFn | undefined {
+	let current = fn;
+	const seen = new Set<HardExitFn>();
+	while (typeof current === "function" && !seen.has(current)) {
+		seen.add(current);
+		const behind = Reflect.get(current, NATIVE_PROCESS_EXIT);
+		if (typeof behind !== "function") return current;
+		current = behind as HardExitFn;
+	}
+	return typeof current === "function" ? current : undefined;
+}
+
 /**
  * Hard-exit the process through the native primitive, resolved on every call.
  *
@@ -68,14 +88,30 @@ type HardExitFn = (code?: number) => never;
  * init could freeze the throwing stub forever and turn every later shutdown
  * (SIGHUP/SIGINT/fatal) into an unhandled-rejection loop (#7393). When the
  * guard is active the stub carries the native exit under
- * {@link NATIVE_PROCESS_EXIT}; unwrapping it lets a mid-guard signal still exit
- * (#6488). Otherwise the current `process.reallyExit`/`process.exit` is native.
+ * {@link NATIVE_PROCESS_EXIT} (#6488).
+ *
+ * Both globals are reinstalled to their natives before exiting: Bun's
+ * `process.exit` re-reads `process.reallyExit` at call time, so exiting through
+ * one primitive while its sibling still holds the throwing stub re-enters the
+ * guard and loops the rejection storm (#11789). After restoring, `reallyExit`
+ * (the low-level primitive) is preferred; `process.exit` and finally `SIGKILL`
+ * are fallbacks so a poisoned or absent chain can never leave the process alive.
  */
-function exitProcess(code: number): never {
-	const current: HardExitFn = typeof process.reallyExit === "function" ? process.reallyExit : process.exit;
-	const behind = Reflect.get(current, NATIVE_PROCESS_EXIT);
-	const nativeExit = typeof behind === "function" ? (behind as HardExitFn) : current;
-	return nativeExit.call(process, code) as never;
+export function exitProcess(code: number): never {
+	const reallyExit = nativeHardExit(typeof process.reallyExit === "function" ? process.reallyExit : undefined);
+	const exit = nativeHardExit(process.exit as HardExitFn);
+	if (reallyExit) process.reallyExit = reallyExit as typeof process.reallyExit;
+	if (exit) process.exit = exit as typeof process.exit;
+	try {
+		reallyExit?.call(process, code);
+	} catch {}
+	try {
+		exit?.call(process, code);
+	} catch {}
+	try {
+		process.kill(process.pid, "SIGKILL");
+	} catch {}
+	throw new Error(`exitProcess(${code}) failed to terminate the process`);
 }
 let cleanupPromise: Promise<void> | undefined;
 let stdioDisconnectRegistrations = 0;
@@ -288,19 +324,47 @@ function faultWorkerIpcChannels(err: Error): void {
 }
 
 /**
- * Treat unhandled stdout EPIPE rejections as a graceful peer disconnect.
+ * Graceful shutdown driven by `process.stdout`'s own `error` event.
  *
- * Stdio protocol servers call this for their process lifetime so a closed
- * client pipe runs registered cleanup callbacks instead of the fatal path.
- * The returned callback removes the registration.
+ * A closed stdout consumer (`omp --help | head`, an ACP client dropping the
+ * pipe) delivers the broken-pipe write here — attributable to stdout by
+ * construction, unlike a process-wide `syscall: "write"` match that a closed
+ * subprocess stdin or socket would also satisfy — so it runs cleanup and exits
+ * 0 (Unix `| head` semantics).
+ *
+ * Only the broken-pipe case is claimed. A non-EPIPE stdout error (a revoked PTY
+ * reporting `EIO`) is left for other `error` listeners: the TUI installs its own
+ * stdout handler that treats a disconnect as SIGHUP/exit-129, and this listener
+ * is installed first on an interactive launch, so forcing a fatal exit here
+ * would preempt that established path. Attaching a listener already suppresses
+ * Node's default throw, so deferring is a safe no-op when no other listener runs.
+ */
+function onStdoutDisconnect(err: Error): void {
+	if (classifyBrokenPipe(err) !== "stdio-write") return;
+	logger.warn("Stdout peer disconnected; shutting down gracefully", { err });
+	void runQuit(0, "native", { drainStdout: false });
+}
+
+/**
+ * Treat a closed stdout consumer as a graceful peer disconnect for the caller's
+ * active lifetime. Attaches one shared `process.stdout` `error` listener,
+ * ref-counted across registrants (the ACP protocol server, the one-shot CLI
+ * entry). The returned callback removes the registration; the listener detaches
+ * when the last registrant unregisters.
  */
 export function registerStdioDisconnectHandling(): () => void {
 	let registered = true;
+	if (Bun.isMainThread && stdioDisconnectRegistrations === 0) {
+		process.stdout.on("error", onStdoutDisconnect);
+	}
 	stdioDisconnectRegistrations++;
 	return () => {
 		if (!registered) return;
 		registered = false;
 		stdioDisconnectRegistrations--;
+		if (Bun.isMainThread && stdioDisconnectRegistrations === 0) {
+			process.stdout.removeListener("error", onStdoutDisconnect);
+		}
 	};
 }
 
@@ -414,6 +478,13 @@ async function exitAfterFatal(output: string, logMessage: string, err: Error, re
 	}
 }
 
+/** Contain an EPIPE from an optional worker IPC `send()` (#2997, #9158). */
+function handleWorkerSendEpipe(err: Error): boolean {
+	if (!isIpcSendEpipe(err)) return false;
+	logger.warn("Ignoring EPIPE from worker IPC send; optional subsystem will self-recover", { err });
+	return true;
+}
+
 /**
  * Reports a caught top-level failure after terminal owners restore their display, then exits.
  */
@@ -443,21 +514,16 @@ if (Bun.isMainThread) {
 			process.stderr.write(`Inspector opened: ${url}\n`);
 		})
 		.on("uncaughtException", async thrown => {
-			// Only explicitly marked exceptions are safe here. Structural
-			// AbortError/socket classification is limited to promise rejections:
-			// a synchronously thrown error may indicate an application bug.
+			// Expected cleanup is safe globally; unrelated synchronous errors stay fatal.
 			if (hasExpectedCleanupMarker(thrown)) {
 				logger.warn("Ignoring expected cleanup exception", { err: thrown });
 				return;
 			}
 			const err = thrown instanceof Error ? thrown : new Error(String(thrown));
-			// Bun can surface a worker IPC send race through uncaughtException
-			// instead of unhandledRejection. Apply the same optional-worker
-			// containment in either global error channel.
-			if (isIpcSendEpipe(err)) {
-				logger.warn("Ignoring EPIPE from worker IPC send; optional subsystem will self-recover", { err });
-				return;
-			}
+			// A worker IPC `send()` race can surface through either global error event;
+			// contain it in both. Stdout write disconnects are attributed to stdout by
+			// registerStdioDisconnectHandling's `error` listener, not classified here.
+			if (handleWorkerSendEpipe(err)) return;
 			// A malformed advanced-serialization frame from a worker subprocess
 			// surfaces here as a process-level uncaughtException (oven-sh/bun#37287)
 			// rather than in the channel's ipc() callback, and Bun gives no way to
@@ -466,7 +532,7 @@ if (Bun.isMainThread) {
 			// worker so its owning client rejects in-flight requests and recycles
 			// the subprocess — a worker that sent a bad frame but stays alive would
 			// otherwise never fire onExit and leave callers awaiting forever.
-			// Mirrors the ipc-send EPIPE containment below (#9158, #2997).
+			// See the analogous worker IPC containment in handleBrokenPipe (#9158, #2997).
 			if (isWorkerIpcDeserializeError(err)) {
 				logger.warn("Malformed worker IPC frame; faulting active worker subsystems", { err });
 				faultWorkerIpcChannels(err);
@@ -487,25 +553,7 @@ if (Bun.isMainThread) {
 		})
 		.on("unhandledRejection", async reason => {
 			const err = reason instanceof Error ? reason : new Error(String(reason));
-			const brokenPipeSource = classifyBrokenPipe(err);
-			// EPIPE from an IPC `send()` (`syscall: "send"`) originates from a
-			// worker subprocess whose pipe broke between the exit being observed
-			// and the next `proc.send()` — a race window that Bun surfaces as an
-			// async rejection rather than the synchronous "cannot be used after
-			// the process has exited" guard. Every `send()` target is an optional
-			// worker subsystem (TTS, STT, tiny-title, MCP servers), so a broken
-			// send pipe must never take down the whole session. Log and continue
-			// instead of exiting; the owning client detects the dead worker via
-			// its own `onExit`/error path and respawns or disables it. See #2997.
-			if (brokenPipeSource === "ipc-send") {
-				logger.warn("Ignoring EPIPE from worker IPC send; optional subsystem will self-recover", { err });
-				return;
-			}
-			if (brokenPipeSource === "stdio-write" && stdioDisconnectRegistrations > 0) {
-				logger.warn("Stdio peer disconnected; shutting down gracefully", { err });
-				await runQuit(0, "native");
-				return;
-			}
+			if (handleWorkerSendEpipe(err)) return;
 			if (isExpectedCleanupError(reason)) {
 				logger.warn("Ignoring expected cleanup rejection", { err });
 				return;

package/src/procmgr.ts

@@ -4,8 +4,10 @@ import { Process, ProcessStatus } from "@oh-my-pi/pi-natives";
 import type { Subprocess } from "bun";
 import { getAgentDir, MAIN_CONFIG_FILENAMES } from "./dirs";
 import { $env, filterChildShellEnv } from "./env";
+import { isExecutable } from "./executable";
 import { $which } from "./which";
 
+export { isExecutable };
 export interface ShellConfig {
 	shell: string;
 	args: string[];
@@ -20,18 +22,6 @@ export interface ShellConfigOptions {
 }
 let cachedShellConfig: ShellConfig | null = null;
 
-/**
- * Check if a shell binary is executable.
- */
-export function isExecutable(path: string): boolean {
-	try {
-		fs.accessSync(path, fs.constants.X_OK);
-		return true;
-	} catch {
-		return false;
-	}
-}
-
 /**
  * Build the spawn environment (cached).
  */

package/src/ptree.ts

@@ -17,6 +17,8 @@ type PipedSubprocess<In extends InMask = InMask> = Subprocess<In, "pipe", "pipe"
 
 const LINUX_SUBREAPER_COMMAND_ENV = "OMP_PTREE_SUBREAPER_COMMAND";
 const LINUX_SUBREAPER_BUN_BE_BUN_ENV = "OMP_PTREE_SUBREAPER_BUN_BE_BUN";
+const SUBREAPER_KILL_WINDOW_MS = 100;
+const SUBREAPER_KILL_POLL_MS = 5;
 
 /**
  * Build the Linux child-subreaper entrypoint.
@@ -189,6 +191,8 @@ export class ChildProcess<In extends InMask = InMask> {
 	#stderrStream?: ReadableStream<Uint8Array>;
 	// Termination in flight after kill(); aborted exits await it before reporting.
 	#terminating?: Promise<boolean | void>;
+	// A hard subreaper sweep must remain authoritative across overlapping kill requests.
+	#hardKillSweep?: Promise<void>;
 	#terminateGroup: boolean;
 	#hardKillTree: boolean;
 	// Windows has no process groups. Retaining the root's native handle pins
@@ -340,14 +344,22 @@ export class ChildProcess<In extends InMask = InMask> {
 			// group leader; wait() still needs to report the later deadline.
 			if (this.proc.exitCode !== null) this.#exitReason = reason;
 		}
+		// An AbortSignal can race a timeout after its hard subreaper sweep has
+		// started. Do not replace that sweep with a normal root termination: the
+		// root must stay alive until adopted descendants have been collected.
+		if (this.#hardKillSweep) return;
 		if (gracefulMs !== undefined && gracefulMs < 0 && this.#hardKillTree && this.proc.exitCode === null) {
-			// terminate() sends its polite wave to the root before rebuilding the
-			// hard-kill tree. A subreaper root can die in that gap and release its
-			// adopted descendants, so snapshot and hard-kill the live tree first.
+			// Keep the subreaper alive while descendants are killed. A single
+			// killTree() snapshot can miss a worker whose parent exits during the
+			// walk and reparents it to the subreaper after that root was enumerated.
 			const root = Process.fromPid(this.proc.pid);
 			if (root) {
-				root.killTree(9);
-				this.#terminating = Promise.resolve();
+				const sweep = this.#hardKillSubreaperTree(root).catch(e => void e);
+				this.#hardKillSweep = sweep;
+				this.#terminating = sweep;
+				void sweep.finally(() => {
+					if (this.#hardKillSweep === sweep) this.#hardKillSweep = undefined;
+				});
 				return;
 			}
 		}
@@ -386,6 +398,25 @@ export class ChildProcess<In extends InMask = InMask> {
 		}
 	}
 
+	async #hardKillSubreaperTree(root: Process): Promise<void> {
+		try {
+			const deadline = Date.now() + SUBREAPER_KILL_WINDOW_MS;
+			let emptySweeps = 0;
+			while (emptySweeps < 2 && Date.now() < deadline) {
+				const children = root.children();
+				if (children.length === 0) {
+					emptySweeps++;
+				} else {
+					emptySweeps = 0;
+					for (const child of children) child.killTree(9);
+				}
+				if (emptySweeps < 2) await Bun.sleep(SUBREAPER_KILL_POLL_MS);
+			}
+		} finally {
+			root.killTree(9);
+		}
+	}
+
 	// ── Output helpers ───────────────────────────────────────────────────
 
 	async #throwIfAborted(): Promise<void> {

package/src/snowflake.ts

@@ -4,6 +4,7 @@ function randu32() {
 
 const EPOCH = 1420070400000;
 const MAX_SEQ = 0x3fffff;
+const MAX_DT = 2 ** 42 - 1;
 
 // Snowflake as a hex string (16 chars, zero-padded).
 //
@@ -25,14 +26,24 @@ namespace Snowflake {
 	//
 	export const MAX_SEQUENCE = MAX_SEQ;
 
+	// Last timestamp representable in the 42-bit timestamp field (~year 2154).
+	//
+	export const MAX_TIMESTAMP = EPOCH + MAX_DT;
+
 	// Formats a sequence and timestamp into a snowflake hex string.
 	//
 	// dt fits well within BigInt range: (dt << 22) | seq stays under 2^64 for
 	// any dt < 2^42 (~year 2154), so a single 64-bit format is exact — and
 	// measures ~1.7x faster than stitching four 16-bit hex segments.
 	//
+	// dt is saturated into [0, 2^42) so the result is always a valid snowflake:
+	// a negative delta (a timestamp before EPOCH) would otherwise render a
+	// leading "-", and a delta past ~2154 would widen the string beyond 16
+	// chars. Both cases produce a value that fails this module's own valid().
+	//
 	export function formatParts(dt: number, seq: number): Snowflake {
-		return ((BigInt(dt) << 22n) | BigInt(seq)).toString(16).padStart(16, "0") as Snowflake;
+		const clamped = Math.min(Math.max(dt, 0), MAX_DT);
+		return ((BigInt(clamped) << 22n) | BigInt(seq)).toString(16).padStart(16, "0") as Snowflake;
 	}
 
 	// Snowflake generator type.

package/src/stream.ts

@@ -57,11 +57,16 @@ export async function* readJsonl<T>(stream: ReadableStream<Uint8Array>, signal?:
 	}
 }
 
-// =============================================================================
-// SSE (Server-Sent Events)
-// =============================================================================
-
-class ConcatSink {
+/**
+ * Amortized byte accumulator for chunked stream readers.
+ *
+ * Holds the unconsumed tail of a stream in a single growing `Buffer` so that
+ * appending N chunks costs O(total bytes) instead of re-copying the whole
+ * prefix per chunk. Backs {@link readLines}, {@link readJsonl} and
+ * {@link readSseEvents}; also usable directly when a reader needs its own
+ * framing loop (see `consume` and `flush`).
+ */
+export class ConcatSink {
 	#space?: Buffer;
 	#length = 0;
 	#skipLeadingLf = false;
@@ -102,11 +107,26 @@ class ConcatSink {
 		return this.#length === 0;
 	}
 
+	/**
+	 * The buffered bytes as a live view — invalidated by the next `append`,
+	 * `reset` or `consume`.
+	 */
 	flush(): Uint8Array | undefined {
 		if (!this.#length) return undefined;
 		return this.#space!.subarray(0, this.#length);
 	}
 
+	/** Drop the first `count` buffered bytes, keeping the remainder. */
+	consume(count: number) {
+		if (count <= 0) return;
+		if (count >= this.#length) {
+			this.#length = 0;
+			return;
+		}
+		this.#space!.copyWithin(0, count, this.#length);
+		this.#length -= count;
+	}
+
 	clear() {
 		this.#length = 0;
 	}
@@ -207,6 +227,10 @@ class ConcatSink {
 	}
 }
 
+// =============================================================================
+// SSE (Server-Sent Events)
+// =============================================================================
+
 /**
  * Stream parsed JSON objects from SSE `data:` lines.
  *
@@ -246,11 +270,24 @@ function isRecoverableTrailingJson(data: string): boolean {
 	return typeof recovered === "object" && recovered !== null;
 }
 
-export async function* readSseJson<T>(
+/**
+ * One dispatched `data:` frame from {@link readSseFrames}: either the parsed JSON
+ * value, or the text of a frame `JSON.parse` rejected together with the
+ * `SyntaxError` it raised (so the strict reader can rethrow it unchanged).
+ */
+type SseFrame<T> = { ok: true; value: T } | { ok: false; raw: string; error: SyntaxError };
+
+/**
+ * Shared `data:`-line framing for {@link readSseJson} and
+ * {@link readSseJsonOrText}: skips empty events, stops at the OpenAI `[DONE]`
+ * sentinel, notifies the diagnostic observer, and treats a container-shaped
+ * stream tail as a clean end of iteration.
+ */
+async function* readSseFrames<T>(
 	stream: ReadableStream<Uint8Array>,
 	signal?: AbortSignal,
 	onEvent?: SseEventObserver,
-): AsyncGenerator<T> {
+): AsyncGenerator<SseFrame<T>> {
 	for await (const sse of readSseEvents(stream, signal)) {
 		const isTrailing = trailingEvents.has(sse);
 		notifySseEventObserver(onEvent, sse);
@@ -260,16 +297,60 @@ export async function* readSseJson<T>(
 			continue;
 		}
 		try {
-			yield JSON.parse(data) as T;
+			yield { ok: true, value: JSON.parse(data) as T };
 		} catch (err) {
 			if (err instanceof SyntaxError && isTrailing && isRecoverableTrailingJson(data)) {
 				return;
 			}
+			if (err instanceof SyntaxError) {
+				yield { ok: false, raw: data, error: err };
+				continue;
+			}
 			throw err;
 		}
 	}
 }
 
+export async function* readSseJson<T>(
+	stream: ReadableStream<Uint8Array>,
+	signal?: AbortSignal,
+	onEvent?: SseEventObserver,
+): AsyncGenerator<T> {
+	for await (const frame of readSseFrames<T>(stream, signal, onEvent)) {
+		if (!frame.ok) throw frame.error;
+		yield frame.value;
+	}
+}
+
+/**
+ * Like {@link readSseJson}, but a `data:` frame that is not valid JSON is yielded
+ * as its raw text instead of raising a `SyntaxError`. Cut-off container-shaped
+ * stream tails stay recoverable, exactly as they are in {@link readSseJson}.
+ *
+ * Consumers that only understand objects must treat a `string` yield as a
+ * transport-level failure (for example a `429 Too Many Requests` or an HTML
+ * throttle page from a reverse proxy that already committed to the stream). This
+ * exists because `readSseJson`'s baseline consumers span unrelated transports
+ * whose error handling a text yield would subtly change; new call sites opt in.
+ *
+ * Note that the text lane is only the frames `JSON.parse` *rejected*: a frame
+ * carrying a JSON-encoded string (`data: "429 Too Many Requests"`) parses, so it
+ * is yielded as that string and is indistinguishable from a rejected frame by
+ * type alone. Consumers branching on `typeof === "string"` therefore see both,
+ * which is the safe direction — each is classified as text rather than trusted as
+ * an event object.
+ */
+export async function* readSseJsonOrText<T>(
+	stream: ReadableStream<Uint8Array>,
+	signal?: AbortSignal,
+	onEvent?: SseEventObserver,
+): AsyncGenerator<T | string> {
+	for await (const frame of readSseFrames<T>(stream, signal, onEvent)) {
+		if (!frame.ok) yield frame.raw;
+		else yield frame.value;
+	}
+}
+
 /**
  * A single Server-Sent Event dispatched on a blank-line boundary.
  *

package/src/which.ts

@@ -11,6 +11,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { isFullyQualifiedPath } from "./path";
 
 type CacheKey = string | bigint | number;
 
@@ -179,6 +180,12 @@ export interface WhichOptions extends Bun.WhichOptions {
 	 * Defaults to `WhichCachePolicy.Fresh`.
 	 */
 	cache?: WhichCachePolicy;
+	/**
+	 * Only search absolute directory entries in PATH, ignoring relative entries
+	 * (e.g. `.` or `./bin`) and empty components to prevent resolving against
+	 * an untrusted working directory.
+	 */
+	requireAbsolutePaths?: boolean;
 }
 
 // Darwin-specific "which" shim: consult Xcode/CLT toolchain directories after $PATH.
@@ -192,6 +199,15 @@ function darwinWhich(command: string, options?: Bun.WhichOptions): string | null
 	return null;
 }
 
+function filterAbsoluteSearchPath(rawPath: string | undefined): string | null {
+	if (!rawPath) return null;
+	const safePath = rawPath
+		.split(path.delimiter)
+		.filter(dir => dir.length > 0 && isFullyQualifiedPath(dir))
+		.join(path.delimiter);
+	return safePath || null;
+}
+
 // Which function that incorporates Darwin Xcode logic if platform reports as 'darwin'.
 // Look `Bun.which` up per call rather than capturing it at import, so a `Bun.which`
 // stub installed later (the per-test seam) is honoured on every platform.
@@ -219,8 +235,15 @@ function cacheKey(command: string, options?: Bun.WhichOptions): CacheKey {
  */
 export function $which(command: string, options?: WhichOptions): string | null {
 	const cachePolicy = options?.cache ?? WhichCachePolicy.Cached;
-	const lookupOptions =
+	let lookupOptions =
 		options?.PATH !== undefined || process.env.PATH === undefined ? options : { ...options, PATH: process.env.PATH };
+
+	if (options?.requireAbsolutePaths) {
+		const safePath = filterAbsoluteSearchPath(lookupOptions?.PATH);
+		if (!safePath) return null;
+		lookupOptions = { ...lookupOptions, PATH: safePath };
+	}
+
 	let key: CacheKey | undefined;
 
 	if (cachePolicy !== WhichCachePolicy.Bypass) {
@@ -232,6 +255,9 @@ export function $which(command: string, options?: WhichOptions): string | null {
 	}
 
 	const result = whichFresh(command, lookupOptions);
+	if (result && options?.requireAbsolutePaths && !isFullyQualifiedPath(result)) {
+		return null;
+	}
 	if (key != null && cachePolicy !== WhichCachePolicy.ReadOnly) {
 		toolCache.set(key, result);
 	}

package/src/xml.ts

@@ -104,6 +104,12 @@ class XmlReader {
 				this.#readProcessingInstruction(document);
 				continue;
 			}
+			if (this.#xml.startsWith("</", this.#position)) {
+				// Stray end tag with no element open: skip it instead of parsing it as a new element,
+				// whose empty name would leave #readElement stuck on the `/`.
+				this.#skipThrough(">");
+				continue;
+			}
 			if (this.#xml[this.#position] === "<") {
 				const element = this.#readElement("");
 				this.#addValue(document, element.name, element.name, element.value, element.leaf, null);
@@ -138,6 +144,11 @@ class XmlReader {
 				this.#position++;
 				this.#skipWhitespace();
 				value = this.#readAttributeValue();
+			} else if (attributeName === "") {
+				// Markup #readName cannot consume (the stray `/` in `<a / >`): skip the character
+				// so the loop always makes progress.
+				this.#position++;
+				continue;
 			}
 			attributes.push([attributeName, value]);
 		}
@@ -153,6 +164,11 @@ class XmlReader {
 					this.#position = close < 0 ? this.#xml.length : close + 1;
 					break;
 				}
+				if (this.#xml.startsWith("</", this.#position)) {
+					// End tag for an ancestor (an unclosed `<br>` inside `<p>`, or plain mismatched
+					// markup): close this element implicitly and leave the tag to its owner.
+					break;
+				}
 				if (this.#xml.startsWith("<![CDATA[", this.#position)) {
 					const end = this.#xml.indexOf("]]>", this.#position + 9);
 					const raw = this.#xml.slice(this.#position + 9, end < 0 ? this.#xml.length : end);