@linxiraos/pi-utils 1.4.0 → 1.4.1

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [1.4.1] - 2026-10-23
+
+- Version alignment with the 1.4.1 release line (no behavioral changes).
+
 ## [1.4.0] - 2026-10-21
 
 - Version line moves to 1.4.0 with the rest of the suite; no user-visible change in this package.

package/README.md

@@ -6,7 +6,7 @@ Shared utilities for [omp](https://github.com/can1357/oh-my-pi) packages. Zero c
 
 | Module                                                                                                             | Purpose                                                                                      |
 | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
-| `logger`                                                                                                           | Centralized logger writing to `~/.zeta/logs/` with rotation (TUI-safe — never stdout)         |
+| `logger`                                                                                                           | Centralized logger writing to `~/.zeta/logs/` (`bun test`: temp dir), rotating, never stdout  |
 | `prompt`                                                                                                           | Handlebars-based prompt templating and formatting helpers                                    |
 | `dirs`                                                                                                             | Path helpers for zetacode config directories (`~/.zeta`, XDG-aware on Linux)                       |
 | `stream`                                                                                                           | `readStream` / `readLines` helpers over `ReadableStream`                                     |

package/dist/types/acp/connection.d.ts

@@ -7,7 +7,15 @@ export interface CreateTerminalResponse {
 }
 /** Client callbacks handled by a client-side connection. */
 export interface Client {
-    requestPermission(params: RequestPermissionRequest): MaybePromise<RequestPermissionResponse>;
+    /**
+     * Serve a permission elicit. `options.signal` aborts when the agent
+     * cancels the request (`$/cancel_request`) — e.g. user steering superseded
+     * the dialog — so a held handler can end instead of stranding the
+     * connection's clean-EOF drain.
+     */
+    requestPermission(params: RequestPermissionRequest, options?: {
+        signal?: AbortSignal;
+    }): MaybePromise<RequestPermissionResponse>;
     sessionUpdate(params: SessionNotification): MaybePromise<void>;
     readTextFile?(params: ReadTextFileRequest): MaybePromise<ReadTextFileResponse>;
     writeTextFile?(params: WriteTextFileRequest): MaybePromise<WriteTextFileResponse | void>;
@@ -45,6 +53,15 @@ export declare class AgentSideConnection {
     sessionUpdate(params: SessionNotification): Promise<void>;
     /** Requests permission from the client. */
     requestPermission(params: RequestPermissionRequest): Promise<RequestPermissionResponse>;
+    /**
+     * Requests permission from the client, returning a handle that cancels the
+     * pending wire request (`$/cancel_request`) — used when user steering
+     * supersedes an open permission dialog instead of waiting behind it.
+     */
+    requestPermissionWithCancel(params: RequestPermissionRequest): {
+        promise: Promise<RequestPermissionResponse>;
+        cancel(): void;
+    };
     /** Reads a client-side text file. */
     readTextFile(params: ReadTextFileRequest): Promise<ReadTextFileResponse>;
     /** Writes a client-side text file. */

package/dist/types/acp/transport.d.ts

@@ -69,17 +69,41 @@ export declare class RequestError extends Error {
     /** Converts this error into a JSON-RPC error payload. */
     toErrorResponse(): ErrorResponse;
 }
-type Dispatcher = (method: string, params: unknown, notification: boolean) => MaybePromise<unknown>;
+type Dispatcher = (method: string, params: unknown, notification: boolean, 
+/** Abort signal for an inbound *request*: fires when the peer cancels it via `$/cancel_request`. */
+signal?: AbortSignal) => MaybePromise<unknown>;
+/** Options for {@link RpcConnection}. */
+export interface RpcConnectionOptions {
+    /**
+     * The dispatcher honors the abort signal it receives for inbound requests.
+     * Only then does a peer `$/cancel_request` abort the handler and answer the
+     * request `-32800` immediately; otherwise the handler runs to completion and
+     * its real result is the response, since answering "cancelled" while the
+     * work keeps going would hide its outcome from the peer.
+     */
+    honorsInboundCancellation?: boolean;
+}
 /** Correlated bidirectional JSON-RPC connection. */
 export declare class RpcConnection {
     #private;
-    constructor(stream: Stream, dispatcher: Dispatcher);
+    constructor(stream: Stream, dispatcher: Dispatcher, options?: RpcConnectionOptions);
     /** Signal aborted when the stream closes. */
     get signal(): AbortSignal;
     /** Promise resolved when the stream closes. */
     get closed(): Promise<void>;
     /** Sends a correlated JSON-RPC request. */
     request<Response>(method: string, params?: unknown): Promise<Response>;
+    /**
+     * Sends a JSON-RPC request whose pending entry can be cancelled locally:
+     * `cancel()` rejects the promise with a request-cancelled error, notifies
+     * the peer via `$/cancel_request`, and drops the pending entry so a late
+     * response is ignored. Used for agent→client requests a mid-turn event can
+     * supersede (e.g. a permission elicit cancelled when user steering arrives).
+     */
+    requestCancellable<Response>(method: string, params?: unknown): {
+        promise: Promise<Response>;
+        cancel(): void;
+    };
     /** Sends a JSON-RPC notification. */
     notify(method: string, params?: unknown): Promise<void>;
     /** Closes the connection and rejects outstanding requests. */

package/dist/types/ar/codecs/gzip.d.ts

@@ -1,6 +1,9 @@
+import { type ByteSource } from "../source.js";
 /** gzip magic: 0x1f 0x8b. */
 export declare function isGzip(bytes: Uint8Array): boolean;
 /** Decompress one gzip stream, bounded so a gzip bomb cannot inflate without limit. */
 export declare function gzipDecompress(bytes: Uint8Array, maxOutput: number): Promise<Uint8Array>;
+/** Decompress a gzip source as a stream of chunks, bounded to `maxOutput` bytes, for output too large to hold at once. */
+export declare function gzipDecompressStream(source: ByteSource, maxOutput: number): AsyncGenerator<Uint8Array>;
 /** Compress bytes as one gzip stream (tar.gz writing). */
 export declare function gzipCompress(bytes: Uint8Array): Promise<Uint8Array>;

package/dist/types/ar/codecs/zstd.d.ts

@@ -1,6 +1,9 @@
+import { type ByteSource } from "../source.js";
 /** zstd frame magic: 28 b5 2f fd. */
 export declare function isZstd(bytes: Uint8Array): boolean;
 /** Decompress one zstd frame, bounded to `maxOutput` bytes. */
 export declare function zstdDecompress(bytes: Uint8Array, maxOutput: number): Promise<Uint8Array>;
+/** Decompress a zstd source as a stream of chunks, bounded to `maxOutput` bytes, for output too large to hold at once. */
+export declare function zstdDecompressStream(source: ByteSource, maxOutput: number): AsyncGenerator<Uint8Array>;
 /** Compress bytes as one zstd frame (tar.zst writing). */
 export declare function zstdCompress(bytes: Uint8Array): Promise<Uint8Array>;

package/dist/types/ar/limits.d.ts

@@ -9,6 +9,8 @@ export interface ArchiveLimits {
     maxEntries: number;
     /** Max bytes for any archive fully materialized in memory (tar buffers, solid/decompressed streams). */
     maxInMemorySize: number;
+    /** Max decompressed bytes in one pass over a compressed tar too large for `maxInMemorySize`. */
+    maxStreamSize: number;
     /** Max bytes for archive metadata (ZIP central directory, ASAR JSON header, RAR/7z header areas). */
     maxIndexSize: number;
     /** Max declared bytes for a single extracted member. */

package/dist/types/ar/source.d.ts

@@ -1,3 +1,4 @@
+import { type Transform } from "node:stream";
 /**
  * A byte window into an archive — file-backed (lazy, ranged reads) or
  * in-memory. Format readers index through this so ZIP/ASAR/RAR payloads are
@@ -17,6 +18,14 @@ export declare function memoryByteSource(buffer: Uint8Array): ByteSource;
 export declare function fileByteSource(filePath: string): ByteSource;
 /** Materialize an entire {@link ByteSource}; use only under a limits check. */
 export declare function readAllBytes(source: ByteSource): Promise<Uint8Array>;
+/** Chunk size for streamed decompression, on both the compressed and the decompressed side. */
+export declare const STREAM_CHUNK_SIZE: number;
+/**
+ * Decompress a {@link ByteSource} through `decoder` chunk by chunk, so neither
+ * the compressed nor the decompressed stream is ever held whole. Output past
+ * `maxOutput` bytes fails, so a decompression bomb cannot run without bound.
+ */
+export declare function decodeByteSource(source: ByteSource, decoder: Transform, maxOutput: number): AsyncGenerator<Uint8Array>;
 /** Options for {@link httpByteSource}. */
 export interface HttpByteSourceOptions {
     /** Extra request headers (e.g. authorization). */

package/dist/types/ar/tar.d.ts

@@ -1,6 +1,11 @@
 import type { ArchiveIndexEntry, FormatReader, FormatReadOptions } from "./types.js";
-/** Index an already-decompressed tar buffer with bounded GNU, ustar, and PAX handling. */
-export declare function readTarEntriesFromBuffer(buffer: Uint8Array, options: FormatReadOptions): ArchiveIndexEntry[];
+/** Index an already-decompressed tar buffer; members are views into it. */
+export declare function readTarEntriesFromBuffer(buffer: Uint8Array, options: FormatReadOptions): Promise<ArchiveIndexEntry[]>;
+/**
+ * Index a decompressed tar stream that is too large to hold in memory: one
+ * pass over `open()` walks the headers, and member reads open it again.
+ */
+export declare function readTarEntriesFromStream(open: () => AsyncIterable<Uint8Array>, options: FormatReadOptions): Promise<ArchiveIndexEntry[]>;
 /** Read and index a tar source after one bounded whole-stream read. */
 export declare const readTar: FormatReader;
 /** Detect a tar header, including legacy pre-ustar archives, by its checksum. */

package/dist/types/dirs.d.ts

@@ -49,7 +49,14 @@ export declare function normalizeProfileName(profile: string | undefined): strin
 export declare function resolveProfileEnv(zeta: string | undefined): string | undefined;
 /** Profile-independent config root (~/.zeta), shared by every zeta profile. */
 export declare function getBaseConfigRoot(): string;
-export declare function resolveEquivalentPath(inputPath: string): string;
+export interface EquivalentPathOptions {
+    /**
+     * Resolve a path that does not exist yet through its deepest existing ancestor, keeping the
+     * missing suffix, so a symlinked parent canonicalizes the same before and after the path appears.
+     */
+    throughMissing?: boolean;
+}
+export declare function resolveEquivalentPath(inputPath: string, options?: EquivalentPathOptions): string;
 export declare function normalizePathForComparison(inputPath: string): string;
 /**
  * Compare paths already normalized by {@link normalizePathForComparison}.

package/dist/types/env.d.ts

@@ -1,3 +1,4 @@
+export * from "./test-runtime.js";
 export * from "./worker-host.js";
 /**
  * Strict shell-identifier shape. Used for dotenv keys we accept into
@@ -81,8 +82,6 @@ export declare function $envExact(name: string, env?: Record<string, string | un
  * Empty, invalid, NaN, zero, or negative values return `defaultValue`.
  */
 export declare function $envpos(name: string, defaultValue: number): number;
-/** True when the process is an explicitly marked test child or Bun is running a test entrypoint. */
-export declare function isBunTestRuntime(): boolean;
 /**
  * True when real-terminal side effects must be suppressed: stdout escape/frame
  * writes, stdin raw-mode + resume, CSI/OSC capability probes, SIGWINCH, window

package/dist/types/fs-open.d.ts

@@ -2,7 +2,8 @@
  * `fs.openSync` with close-on-exec, matching Node's default.
  *
  * libuv adds `O_CLOEXEC` inside `uv__fs_open`, so on Node every `fs` descriptor
- * dies at `exec`. Bun's `fs.open*` does not, and descriptors it returns survive
+ * dies at `exec`. Bun's `fs.open*` did not before 1.4.3 (still allowed by the
+ * `bun@>=1.4` pin), and descriptors it returns survive
  * into any child spawned through a path that does not close strays itself — the
  * bash tool's shell `fork`/`exec`s user commands and hands them the lot. Use
  * this for every descriptor kept open past such a spawn (session transcripts,

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

@@ -0,0 +1,2 @@
+/** True when the process is an explicitly marked test child or Bun is running a test entrypoint. */
+export declare function isBunTestRuntime(): boolean;

package/package.json

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

package/src/acp/connection.ts

@@ -47,7 +47,16 @@ export interface CreateTerminalResponse {
 }
 /** Client callbacks handled by a client-side connection. */
 export interface Client {
-	requestPermission(params: RequestPermissionRequest): MaybePromise<RequestPermissionResponse>;
+	/**
+	 * Serve a permission elicit. `options.signal` aborts when the agent
+	 * cancels the request (`$/cancel_request`) — e.g. user steering superseded
+	 * the dialog — so a held handler can end instead of stranding the
+	 * connection's clean-EOF drain.
+	 */
+	requestPermission(
+		params: RequestPermissionRequest,
+		options?: { signal?: AbortSignal },
+	): MaybePromise<RequestPermissionResponse>;
 	sessionUpdate(params: SessionNotification): MaybePromise<void>;
 	readTextFile?(params: ReadTextFileRequest): MaybePromise<ReadTextFileResponse>;
 	writeTextFile?(params: WriteTextFileRequest): MaybePromise<WriteTextFileResponse | void>;
@@ -90,6 +99,17 @@ export class AgentSideConnection {
 	requestPermission(params: RequestPermissionRequest): Promise<RequestPermissionResponse> {
 		return this.#connection.request("session/request_permission", params);
 	}
+	/**
+	 * Requests permission from the client, returning a handle that cancels the
+	 * pending wire request (`$/cancel_request`) — used when user steering
+	 * supersedes an open permission dialog instead of waiting behind it.
+	 */
+	requestPermissionWithCancel(params: RequestPermissionRequest): {
+		promise: Promise<RequestPermissionResponse>;
+		cancel(): void;
+	} {
+		return this.#connection.requestCancellable<RequestPermissionResponse>("session/request_permission", params);
+	}
 	/** Reads a client-side text file. */
 	readTextFile(params: ReadTextFileRequest): Promise<ReadTextFileResponse> {
 		return this.#connection.request("fs/read_text_file", params);
@@ -168,10 +188,18 @@ export class ClientSideConnection {
 	#connection: RpcConnection;
 
 	constructor(toClient: (connection: ClientSideConnection) => Client, stream: Stream) {
-		this.#connection = new RpcConnection(stream, async (method, params, notification) => {
-			if (!client) throw RequestError.internalError(undefined, "Client is not initialized");
-			return dispatchClient(client, method, params, notification);
-		});
+		// Client handlers receive the cancel signal (`requestPermission`'s
+		// `options.signal`), so a peer `$/cancel_request` may answer `-32800`
+		// at once. The agent side keeps the default: its handlers ignore the
+		// signal, and `session/cancel` is ACP's cancellation path for prompts.
+		this.#connection = new RpcConnection(
+			stream,
+			async (method, params, notification, signal) => {
+				if (!client) throw RequestError.internalError(undefined, "Client is not initialized");
+				return dispatchClient(client, method, params, notification, signal);
+			},
+			{ honorsInboundCancellation: true },
+		);
 		const client = toClient(this);
 	}
 	/** Signal aborted when the transport closes. */
@@ -272,10 +300,11 @@ async function dispatchClient(
 	method: string,
 	params: unknown,
 	notification: boolean,
+	signal?: AbortSignal,
 ): Promise<unknown> {
 	switch (method) {
 		case "session/request_permission":
-			return client.requestPermission(params as RequestPermissionRequest);
+			return client.requestPermission(params as RequestPermissionRequest, { signal });
 		case "session/update":
 			return client.sessionUpdate(params as SessionNotification);
 		case "fs/read_text_file":
@@ -322,6 +351,9 @@ async function dispatchClient(
 				params as CompleteElicitationNotification,
 			);
 		default:
+			// The transport already aborted the matching inbound handler;
+			// like the agent side, the notification itself carries no work.
+			if (method === "$/cancel_request") return;
 			if (notification && client.extNotification)
 				return client.extNotification(method, params as Record<string, unknown>);
 			if (!notification && client.extMethod) return client.extMethod(method, params as Record<string, unknown>);

package/src/acp/transport.ts

@@ -105,9 +105,27 @@ function createStandardError(
 	return new RequestError(code, additionalMessage ? `${message}: ${additionalMessage}` : message, data);
 }
 
-type Dispatcher = (method: string, params: unknown, notification: boolean) => MaybePromise<unknown>;
+type Dispatcher = (
+	method: string,
+	params: unknown,
+	notification: boolean,
+	/** Abort signal for an inbound *request*: fires when the peer cancels it via `$/cancel_request`. */
+	signal?: AbortSignal,
+) => MaybePromise<unknown>;
 type Pending = { resolve(value: unknown): void; reject(reason: unknown): void };
 
+/** Options for {@link RpcConnection}. */
+export interface RpcConnectionOptions {
+	/**
+	 * The dispatcher honors the abort signal it receives for inbound requests.
+	 * Only then does a peer `$/cancel_request` abort the handler and answer the
+	 * request `-32800` immediately; otherwise the handler runs to completion and
+	 * its real result is the response, since answering "cancelled" while the
+	 * work keeps going would hide its outcome from the peer.
+	 */
+	honorsInboundCancellation?: boolean;
+}
+
 /** Bound on clean-EOF inbound drain so `closed` cannot hang if a handler never settles. */
 const INBOUND_DRAIN_TIMEOUT_MS = 30_000;
 
@@ -117,15 +135,18 @@ export class RpcConnection {
 	#pending = new Map<JsonRpcId, Pending>();
 	#inbound = new Set<Promise<void>>();
 	#openInboundIds = new Set<JsonRpcId>();
+	/** Abort controller per inbound request, fired by a peer `$/cancel_request` (opt-in). */
+	#inboundCancellers: Map<JsonRpcId, AbortController> | undefined;
 	#writable: WritableStream<AnyMessage>;
 	#writeTail: Promise<void> = Promise.resolve();
 	#abort = new AbortController();
 	#closed = Promise.withResolvers<void>();
 	#dispatcher: Dispatcher;
 
-	constructor(stream: Stream, dispatcher: Dispatcher) {
+	constructor(stream: Stream, dispatcher: Dispatcher, options?: RpcConnectionOptions) {
 		this.#writable = stream.writable;
 		this.#dispatcher = dispatcher;
+		this.#inboundCancellers = options?.honorsInboundCancellation ? new Map() : undefined;
 		void this.#read(stream.readable);
 	}
 
@@ -141,6 +162,48 @@ export class RpcConnection {
 	/** Sends a correlated JSON-RPC request. */
 	request<Response>(method: string, params?: unknown): Promise<Response> {
 		if (this.signal.aborted) return Promise.reject(new Error("Connection closed"));
+		return this.#beginRequest(method, params).deferred.promise as Promise<Response>;
+	}
+
+	/**
+	 * Sends a JSON-RPC request whose pending entry can be cancelled locally:
+	 * `cancel()` rejects the promise with a request-cancelled error, notifies
+	 * the peer via `$/cancel_request`, and drops the pending entry so a late
+	 * response is ignored. Used for agent→client requests a mid-turn event can
+	 * supersede (e.g. a permission elicit cancelled when user steering arrives).
+	 */
+	requestCancellable<Response>(
+		method: string,
+		params?: unknown,
+	): {
+		promise: Promise<Response>;
+		cancel(): void;
+	} {
+		if (this.signal.aborted) {
+			return {
+				promise: Promise.reject(new Error("Connection closed")),
+				cancel: () => {},
+			};
+		}
+		const { id, deferred } = this.#beginRequest(method, params);
+		return {
+			promise: deferred.promise as Promise<Response>,
+			cancel: () => {
+				if (!this.#pending.delete(id)) return;
+				deferred.reject(RequestError.requestCancelled({ requestId: id, method }));
+				void this.notify("$/cancel_request", { requestId: id }).catch(() => undefined);
+			},
+		};
+	}
+
+	/** Shared request plumbing: allocate an id, register the pending entry, write the frame. */
+	#beginRequest(
+		method: string,
+		params: unknown,
+	): {
+		id: number;
+		deferred: { promise: Promise<unknown>; resolve: (value?: unknown) => void; reject: (reason?: unknown) => void };
+	} {
 		const id = this.#nextId++;
 		const deferred = Promise.withResolvers<unknown>();
 		this.#pending.set(id, deferred);
@@ -148,7 +211,7 @@ export class RpcConnection {
 			this.#pending.delete(id);
 			deferred.reject(error);
 		});
-		return deferred.promise as Promise<Response>;
+		return { id, deferred };
 	}
 
 	/** Sends a JSON-RPC notification. */
@@ -235,6 +298,18 @@ export class RpcConnection {
 		}
 		if (!("method" in message)) return;
 		if (!("id" in message)) {
+			// ACP v1 names the cancelled request `requestId`. A cancelled
+			// inbound request must still be answered (spec: result or
+			// `-32800`): the handler is aborted and the error response is
+			// written here, so a late-settling handler lands in `#respond`'s
+			// closed-id no-op instead of answering a request the peer gave
+			// up on.
+			if (message.method === "$/cancel_request" && this.#inboundCancellers) {
+				this.#cancelInbound(
+					this.#inboundCancellers,
+					(message.params as { requestId?: JsonRpcId } | undefined)?.requestId,
+				);
+			}
 			try {
 				await this.#dispatcher(message.method, message.params, true);
 			} catch {
@@ -242,8 +317,11 @@ export class RpcConnection {
 			}
 			return;
 		}
+		const cancellers = this.#inboundCancellers;
+		const canceller = cancellers ? new AbortController() : undefined;
+		if (canceller) cancellers?.set(message.id, canceller);
 		try {
-			const result = await this.#dispatcher(message.method, message.params, false);
+			const result = await this.#dispatcher(message.method, message.params, false, canceller?.signal);
 			await this.#respond(message.id, { result: result ?? {} });
 		} catch (error) {
 			const protocolError =
@@ -251,6 +329,25 @@ export class RpcConnection {
 					? error
 					: RequestError.internalError({ details: error instanceof Error ? error.message : String(error) });
 			await this.#respond(message.id, { error: protocolError.toErrorResponse() });
+		} finally {
+			cancellers?.delete(message.id);
 		}
 	}
+
+	#cancelInbound(cancellers: Map<JsonRpcId, AbortController>, id: JsonRpcId | undefined): void {
+		if (id === undefined) return;
+		const canceller = cancellers.get(id);
+		if (canceller) {
+			cancellers.delete(id);
+			canceller.abort(RequestError.requestCancelled({ requestId: id }));
+		}
+		// Spec: a cancelled request still gets a response. Answer `-32800`
+		// here — synchronously with the notification — so the peer is never
+		// left waiting on a handler that may never settle. `#respond` closes
+		// the id, so a late handler result (a handler that ignored its abort
+		// signal) lands in the closed-id no-op instead of answering twice.
+		void this.#respond(id, { error: RequestError.requestCancelled({ requestId: id }).toErrorResponse() }).catch(
+			() => undefined,
+		);
+	}
 }

package/src/ar/codecs/gzip.ts

@@ -1,6 +1,7 @@
 import { promisify } from "node:util";
 import * as zlib from "node:zlib";
 import { ArchiveError } from "../error";
+import { type ByteSource, decodeByteSource, STREAM_CHUNK_SIZE } from "../source";
 
 const gzipAsync = promisify(zlib.gzip);
 const gunzipAsync = promisify(zlib.gunzip);
@@ -19,6 +20,11 @@ export async function gzipDecompress(bytes: Uint8Array, maxOutput: number): Prom
 	}
 }
 
+/** Decompress a gzip source as a stream of chunks, bounded to `maxOutput` bytes, for output too large to hold at once. */
+export function gzipDecompressStream(source: ByteSource, maxOutput: number): AsyncGenerator<Uint8Array> {
+	return decodeByteSource(source, zlib.createGunzip({ chunkSize: STREAM_CHUNK_SIZE }), maxOutput);
+}
+
 /** Compress bytes as one gzip stream (tar.gz writing). */
 export function gzipCompress(bytes: Uint8Array): Promise<Uint8Array> {
 	return gzipAsync(bytes);

package/src/ar/codecs/zstd.ts

@@ -1,6 +1,7 @@
 import { promisify } from "node:util";
 import * as zlib from "node:zlib";
 import { ArchiveError } from "../error";
+import { type ByteSource, decodeByteSource, STREAM_CHUNK_SIZE } from "../source";
 
 const zstdCompressAsync = promisify(zlib.zstdCompress);
 const zstdDecompressAsync = promisify(zlib.zstdDecompress);
@@ -19,6 +20,11 @@ export async function zstdDecompress(bytes: Uint8Array, maxOutput: number): Prom
 	}
 }
 
+/** Decompress a zstd source as a stream of chunks, bounded to `maxOutput` bytes, for output too large to hold at once. */
+export function zstdDecompressStream(source: ByteSource, maxOutput: number): AsyncGenerator<Uint8Array> {
+	return decodeByteSource(source, zlib.createZstdDecompress({ chunkSize: STREAM_CHUNK_SIZE }), maxOutput);
+}
+
 /** Compress bytes as one zstd frame (tar.zst writing). */
 export function zstdCompress(bytes: Uint8Array): Promise<Uint8Array> {
 	return zstdCompressAsync(bytes);

package/src/ar/deb.ts

@@ -135,7 +135,7 @@ async function readDebImpl(source: ByteSource, options: FormatReadOptions): Prom
 		}
 		const compressed = await readOuterMember(outerEntry);
 		const tarBytes = await decompressDebTar(compressed, tar.compression, options);
-		const innerEntries = readTarEntriesFromBuffer(tarBytes, options);
+		const innerEntries = await readTarEntriesFromBuffer(tarBytes, options);
 		for (const innerEntry of innerEntries) {
 			upsertArchiveEntry(result, tar.kind === "control" ? prefixControlEntry(innerEntry) : innerEntry);
 		}

package/src/ar/limits.ts

@@ -13,6 +13,8 @@ export interface ArchiveLimits {
 	maxEntries: number;
 	/** Max bytes for any archive fully materialized in memory (tar buffers, solid/decompressed streams). */
 	maxInMemorySize: number;
+	/** Max decompressed bytes in one pass over a compressed tar too large for `maxInMemorySize`. */
+	maxStreamSize: number;
 	/** Max bytes for archive metadata (ZIP central directory, ASAR JSON header, RAR/7z header areas). */
 	maxIndexSize: number;
 	/** Max declared bytes for a single extracted member. */
@@ -26,6 +28,7 @@ export interface ArchiveLimits {
 export const DEFAULT_ARCHIVE_LIMITS: ArchiveLimits = {
 	maxEntries: 1_000_000,
 	maxInMemorySize: 256 * 1024 * 1024,
+	maxStreamSize: 4 * 1024 * 1024 * 1024,
 	maxIndexSize: 64 * 1024 * 1024,
 	maxMemberSize: 64 * 1024 * 1024,
 	maxPathBytes: 4096,

package/src/ar/registry.ts

@@ -1,25 +1,27 @@
 import * as path from "node:path";
+import { formatBytes } from "../format";
 import { readArj, sniffArj } from "./arj";
 import { readAsar, sniffAsar } from "./asar";
 import { readUInt32LE } from "./bytes";
 import { readCab, sniffCab } from "./cab";
 import { bzip2Decompress, isBzip2 } from "./codecs/bzip2";
-import { gzipDecompress, isGzip } from "./codecs/gzip";
+import { gzipDecompressStream, isGzip } from "./codecs/gzip";
 import { lzmaAloneDecompress } from "./codecs/lzma";
 import { isCompressZ, lzwDecompress } from "./codecs/lzw";
 import { isXz, xzDecompress } from "./codecs/xz";
-import { isZstd, zstdDecompress } from "./codecs/zstd";
+import { isZstd, zstdDecompressStream } from "./codecs/zstd";
 import { readCpio, sniffCpio } from "./cpio";
 import { readDeb, sniffDeb } from "./deb";
+import { ArchiveError } from "./error";
 import { readIso, sniffIso } from "./iso";
 import { assertInMemorySize } from "./limits";
 import { readLzh, sniffLzh } from "./lzh";
 import { readRar, sniffRar } from "./rar";
 import { readRpm, sniffRpm } from "./rpm";
 import { readSevenZip, sniffSevenZip } from "./sevenzip";
-import { readAllBytes } from "./source";
-import { readTar, readTarEntriesFromBuffer, sniffTar } from "./tar";
-import type { ArchiveFormat, ArchiveIndexEntry, FormatReader, MemberSource } from "./types";
+import { type ByteSource, readAllBytes } from "./source";
+import { readTar, readTarEntriesFromBuffer, readTarEntriesFromStream, sniffTar } from "./tar";
+import type { ArchiveFormat, ArchiveIndexEntry, FormatReader, FormatReadOptions, MemberSource } from "./types";
 import { readUnixAr, sniffUnixAr } from "./unix-ar";
 import { readZip, sniffZip } from "./zip";
 
@@ -100,6 +102,21 @@ class BufferMember implements MemberSource {
 	}
 }
 
+/** Index decompressed bytes as tar when they are one, else as a single stem-named member. */
+async function readDecompressed(inner: Uint8Array, options: FormatReadOptions): Promise<ArchiveIndexEntry[]> {
+	assertInMemorySize(inner.byteLength, options.limits);
+	if (sniffTar(inner)) {
+		return readTarEntriesFromBuffer(inner, options);
+	}
+	const entry: ArchiveIndexEntry = {
+		path: stemMemberName(options.archivePath),
+		isDirectory: false,
+		size: inner.byteLength,
+		storage: { type: "member", source: new BufferMember(inner) },
+	};
+	return [entry];
+}
+
 /**
  * Reader for one compressed stream: decompress bounded, then index the inner
  * bytes as tar when they are one, else surface a single stem-named member.
@@ -109,28 +126,50 @@ class BufferMember implements MemberSource {
 function compressedReader(decompress: (bytes: Uint8Array, maxOutput: number) => Promise<Uint8Array>): FormatReader {
 	return async (source, options) => {
 		assertInMemorySize(source.size, options.limits);
-		const inner = await decompress(await readAllBytes(source), options.limits.maxInMemorySize);
-		assertInMemorySize(inner.byteLength, options.limits);
-		if (sniffTar(inner)) {
-			return readTarEntriesFromBuffer(inner, options);
+		return readDecompressed(await decompress(await readAllBytes(source), options.limits.maxInMemorySize), options);
+	};
+}
+
+/**
+ * {@link compressedReader} for codecs that decompress as a stream. Output that
+ * fits `maxInMemorySize` is indexed the same way; a tar that inflates past it
+ * is indexed by a streaming header walk instead, its members decompressed
+ * again when read, so memory stays bounded by the limits either way. Each pass
+ * stops at `maxStreamSize`.
+ */
+function streamedReader(
+	decompress: (source: ByteSource, maxOutput: number) => AsyncIterable<Uint8Array>,
+): FormatReader {
+	return async (source, options) => {
+		const { maxInMemorySize, maxStreamSize } = options.limits;
+		const chunks: Uint8Array[] = [];
+		let size = 0;
+		for await (const chunk of decompress(source, maxStreamSize)) {
+			chunks.push(chunk);
+			size += chunk.byteLength;
+			if (size > maxInMemorySize) break;
+		}
+		// Copy out what is needed, then drop the chunks so they are not held alongside it.
+		const kept = Buffer.concat(chunks, size <= maxInMemorySize ? size : Math.min(size, 512));
+		chunks.length = 0;
+		if (size <= maxInMemorySize) return readDecompressed(kept, options);
+		// Past the limit only a tar has headers to walk; its first 512-byte block tells.
+		if (!sniffTar(kept)) {
+			throw new ArchiveError(
+				`Archive is too large to read in memory (decompressed > ${formatBytes(maxInMemorySize)} limit)`,
+			);
 		}
-		const entry: ArchiveIndexEntry = {
-			path: stemMemberName(options.archivePath),
-			isDirectory: false,
-			size: inner.byteLength,
-			storage: { type: "member", source: new BufferMember(inner) },
-		};
-		return [entry];
+		return readTarEntriesFromStream(() => decompress(source, maxStreamSize), options);
 	};
 }
 
 const READERS: Record<ArchiveFormat, FormatReader> = {
 	zip: readZip,
 	tar: readTar,
-	"tar.gz": compressedReader(gzipDecompress),
+	"tar.gz": streamedReader(gzipDecompressStream),
 	"tar.bz2": compressedReader(bzip2Decompress),
 	"tar.xz": compressedReader(xzDecompress),
-	"tar.zst": compressedReader(zstdDecompress),
+	"tar.zst": streamedReader(zstdDecompressStream),
 	"tar.Z": compressedReader(lzwDecompress),
 	asar: readAsar,
 	rar: readRar,
@@ -143,10 +182,10 @@ const READERS: Record<ArchiveFormat, FormatReader> = {
 	deb: readDeb,
 	lzh: readLzh,
 	arj: readArj,
-	gz: compressedReader(gzipDecompress),
+	gz: streamedReader(gzipDecompressStream),
 	bz2: compressedReader(bzip2Decompress),
 	xz: compressedReader(xzDecompress),
-	zst: compressedReader(zstdDecompress),
+	zst: streamedReader(zstdDecompressStream),
 	Z: compressedReader(lzwDecompress),
 	lzma: compressedReader(lzmaAloneDecompress),
 };

package/src/ar/source.ts

@@ -1,3 +1,5 @@
+import { Readable, type Transform } from "node:stream";
+import { formatBytes } from "../format";
 import { LRUCache } from "../lru";
 import { ArchiveError } from "./error";
 
@@ -62,6 +64,44 @@ export async function readAllBytes(source: ByteSource): Promise<Uint8Array> {
 	return source.read(0, source.size);
 }
 
+/** Chunk size for streamed decompression, on both the compressed and the decompressed side. */
+export const STREAM_CHUNK_SIZE = 1024 * 1024;
+
+async function* readChunks(source: ByteSource): AsyncGenerator<Uint8Array> {
+	for (let start = 0; start < source.size; start += STREAM_CHUNK_SIZE) {
+		yield await source.read(start, Math.min(source.size, start + STREAM_CHUNK_SIZE));
+	}
+}
+
+/**
+ * Decompress a {@link ByteSource} through `decoder` chunk by chunk, so neither
+ * the compressed nor the decompressed stream is ever held whole. Output past
+ * `maxOutput` bytes fails, so a decompression bomb cannot run without bound.
+ */
+export async function* decodeByteSource(
+	source: ByteSource,
+	decoder: Transform,
+	maxOutput: number,
+): AsyncGenerator<Uint8Array> {
+	const input = Readable.from(readChunks(source));
+	input.once("error", error => decoder.destroy(error));
+	let output = 0;
+	try {
+		for await (const chunk of input.pipe(decoder)) {
+			output += chunk.byteLength;
+			if (output > maxOutput) {
+				throw new ArchiveError(`Archive decompresses past the ${formatBytes(maxOutput)} stream limit`);
+			}
+			yield chunk;
+		}
+	} catch (error) {
+		if (error instanceof ArchiveError) throw error;
+		throw new ArchiveError(error instanceof Error ? error.message : String(error));
+	} finally {
+		input.destroy();
+	}
+}
+
 /** Options for {@link httpByteSource}. */
 export interface HttpByteSourceOptions {
 	/** Extra request headers (e.g. authorization). */

package/src/ar/tar.ts

@@ -53,13 +53,141 @@ interface PendingTarLink {
 	targetPath: string;
 }
 
-class TarMemberSource implements MemberSource {
+/** Forward-only reader over tar bytes that arrive in chunks: one buffer, or a decompressing stream. */
+class TarByteStream {
+	readonly #chunks: AsyncIterator<Uint8Array> | Iterator<Uint8Array>;
+	#chunk: Uint8Array = new Uint8Array(0);
+	#position = 0;
+
+	constructor(chunks: AsyncIterable<Uint8Array> | Iterable<Uint8Array>) {
+		this.#chunks = Symbol.asyncIterator in chunks ? chunks[Symbol.asyncIterator]() : chunks[Symbol.iterator]();
+	}
+
+	/** Bytes consumed so far. */
+	get position(): number {
+		return this.#position;
+	}
+
+	/** The next `length` bytes; shorter only when the stream ends first. */
+	async read(length: number): Promise<Uint8Array> {
+		if (this.#chunk.byteLength >= length) {
+			const bytes = this.#chunk.subarray(0, length);
+			this.#chunk = this.#chunk.subarray(length);
+			this.#position += length;
+			return bytes;
+		}
+		const bytes = new Uint8Array(length);
+		let filled = 0;
+		while (filled < length && (this.#chunk.byteLength > 0 || (await this.#next()))) {
+			const take = Math.min(length - filled, this.#chunk.byteLength);
+			bytes.set(this.#chunk.subarray(0, take), filled);
+			this.#chunk = this.#chunk.subarray(take);
+			filled += take;
+		}
+		this.#position += filled;
+		return filled === length ? bytes : bytes.subarray(0, filled);
+	}
+
+	/** Step over `length` bytes; false when the stream ends first. */
+	async skip(length: number): Promise<boolean> {
+		let remaining = length;
+		while (remaining > 0) {
+			if (this.#chunk.byteLength === 0 && !(await this.#next())) return false;
+			const take = Math.min(remaining, this.#chunk.byteLength);
+			this.#chunk = this.#chunk.subarray(take);
+			this.#position += take;
+			remaining -= take;
+		}
+		return true;
+	}
+
+	/** Stop the underlying stream without draining it. */
+	async close(): Promise<void> {
+		await this.#chunks.return?.();
+	}
+
+	async #next(): Promise<boolean> {
+		const result = await this.#chunks.next();
+		if (result.done) return false;
+		this.#chunk = result.value;
+		return true;
+	}
+}
+
+/** Where an indexed tar's member bytes come from, by offset into the tar stream. */
+interface TarPayload {
+	read(offset: number, size: number, memberPath: string): Promise<Uint8Array>;
+}
+
+class TarBufferPayload implements TarPayload {
 	readonly #buffer: Uint8Array;
+
+	constructor(buffer: Uint8Array) {
+		this.#buffer = buffer;
+	}
+
+	async read(offset: number, size: number, memberPath: string): Promise<Uint8Array> {
+		if (size > this.#buffer.byteLength - offset) {
+			throw new ArchiveError(`Archive member '${formatArchivePathForError(memberPath)}' is truncated`);
+		}
+		const bytes = this.#buffer.subarray(offset, offset + size);
+		if (bytes.byteLength !== size) {
+			throw new ArchiveError(`Archive member '${formatArchivePathForError(memberPath)}' has an invalid size`);
+		}
+		return bytes;
+	}
+}
+
+/**
+ * Member bytes of a tar too large to hold decompressed: each read decompresses
+ * the stream again up to the member. Reads are serialized, and a read ahead of
+ * the previous one continues that pass, so reading every member in archive
+ * order decompresses the stream once.
+ */
+class TarStreamPayload implements TarPayload {
+	readonly #open: () => AsyncIterable<Uint8Array>;
+	#stream: TarByteStream | undefined;
+	#pending: Promise<unknown> = Promise.resolve();
+
+	constructor(open: () => AsyncIterable<Uint8Array>) {
+		this.#open = open;
+	}
+
+	read(offset: number, size: number, memberPath: string): Promise<Uint8Array> {
+		const bytes = this.#pending.then(() => this.#readAt(offset, size, memberPath));
+		this.#pending = bytes.catch(() => undefined);
+		return bytes;
+	}
+
+	async #readAt(offset: number, size: number, memberPath: string): Promise<Uint8Array> {
+		let stream = this.#stream;
+		this.#stream = undefined;
+		if (!stream || stream.position > offset) {
+			await stream?.close();
+			stream = new TarByteStream(this.#open());
+		}
+		try {
+			const bytes = (await stream.skip(offset - stream.position)) ? await stream.read(size) : undefined;
+			if (bytes?.byteLength !== size) {
+				throw new ArchiveError(`Archive member '${formatArchivePathForError(memberPath)}' is truncated`);
+			}
+			this.#stream = stream;
+			// A view into a decoder chunk would keep the whole chunk alive with the member.
+			return bytes.byteLength === bytes.buffer.byteLength ? bytes : new Uint8Array(bytes);
+		} catch (error) {
+			await stream.close();
+			throw error;
+		}
+	}
+}
+
+class TarMemberSource implements MemberSource {
+	readonly #payload: TarPayload;
 	readonly #dataOffset: number;
 	readonly #sparse: boolean;
 
-	constructor(buffer: Uint8Array, dataOffset: number, sparse: boolean) {
-		this.#buffer = buffer;
+	constructor(payload: TarPayload, dataOffset: number, sparse: boolean) {
+		this.#payload = payload;
 		this.#dataOffset = dataOffset;
 		this.#sparse = sparse;
 	}
@@ -70,14 +198,7 @@ class TarMemberSource implements MemberSource {
 				`Archive member '${formatArchivePathForError(memberPath)}' is a sparse file and cannot be read`,
 			);
 		}
-		if (size > this.#buffer.byteLength - this.#dataOffset) {
-			throw new ArchiveError(`Archive member '${formatArchivePathForError(memberPath)}' is truncated`);
-		}
-		const bytes = this.#buffer.subarray(this.#dataOffset, this.#dataOffset + size);
-		if (bytes.byteLength !== size) {
-			throw new ArchiveError(`Archive member '${formatArchivePathForError(memberPath)}' has an invalid size`);
-		}
-		return bytes;
+		return this.#payload.read(this.#dataOffset, size, memberPath);
 	}
 }
 
@@ -172,7 +293,6 @@ function checksumMatches(buffer: Uint8Array, offset: number): boolean {
 }
 
 function parsePaxRecords(data: Uint8Array, limits: ArchiveLimits): Map<string, string> {
-	assertIndexSize(data.byteLength, limits, "tar PAX metadata");
 	const attrs = new Map<string, string>();
 	let pos = 0;
 	while (pos < data.byteLength) {
@@ -295,7 +415,6 @@ function applyOldGnuNameRecords(
 	pendingLinks: Map<ArchiveIndexEntry, PendingTarLink>,
 	limits: ArchiveLimits,
 ): void {
-	assertIndexSize(data.byteLength, limits, "old-GNU name metadata");
 	const terminator = data.indexOf(0);
 	const end = terminator === -1 ? data.byteLength : terminator;
 	let start = 0;
@@ -412,10 +531,31 @@ function resolvePendingLinks(
 	if (unresolved.size > 0) throw new ArchiveError("Archive contains cyclic or unsupported links");
 }
 
-/** Index an already-decompressed tar buffer with bounded GNU, ustar, and PAX handling. */
-export function readTarEntriesFromBuffer(buffer: Uint8Array, options: FormatReadOptions): ArchiveIndexEntry[] {
+/** Read one metadata record's payload, bounded by `maxIndexSize`, and step over its padding. */
+async function readTarMetadata(
+	stream: TarByteStream,
+	size: number,
+	limits: ArchiveLimits,
+	what: string,
+): Promise<Uint8Array> {
+	assertIndexSize(size, limits, what);
+	const data = await stream.read(size);
+	if (data.byteLength !== size || !(await stream.skip(paddedSize(size) - size))) {
+		throw new ArchiveError("Archive member data is truncated");
+	}
+	return data;
+}
+
+/**
+ * Walk tar headers with bounded GNU, ustar, and PAX handling. Member data is
+ * stepped over, never held: entries point into `payload` by stream offset.
+ */
+async function readTarEntries(
+	stream: TarByteStream,
+	payload: TarPayload,
+	options: FormatReadOptions,
+): Promise<ArchiveIndexEntry[]> {
 	const { limits } = options;
-	assertInMemorySize(buffer.byteLength, limits);
 	const entries = new Map<string, ArchiveIndexEntry>();
 	const pendingLinks = new Map<ArchiveIndexEntry, PendingTarLink>();
 	const addEntry = (entry: ArchiveIndexEntry, pendingLink?: PendingTarLink): void => {
@@ -426,61 +566,58 @@ export function readTarEntriesFromBuffer(buffer: Uint8Array, options: FormatRead
 		if (pendingLink) pendingLinks.set(indexed, pendingLink);
 		assertEntryCount(entries.size, limits);
 	};
-	let offset = 0;
 	let longName: string | undefined;
 	let longLink: string | undefined;
 	let localPax: Map<string, string> | undefined;
 	const globalPax = new Map<string, string>();
 	let sawTerminator = false;
 
-	while (offset + BLOCK_SIZE <= buffer.byteLength) {
-		if (isZeroBlock(buffer, offset)) {
+	for (
+		let header = await stream.read(BLOCK_SIZE);
+		header.byteLength === BLOCK_SIZE;
+		header = await stream.read(BLOCK_SIZE)
+	) {
+		if (isZeroBlock(header, 0)) {
 			sawTerminator = true;
 			break;
 		}
-		if (!checksumMatches(buffer, offset)) throw new ArchiveError("Invalid or corrupt tar archive header");
-		const headerOffset = offset;
-		const typeFlag = String.fromCharCode(buffer[headerOffset + TYPEFLAG_OFFSET] || 0x30);
-		let size = readTarSize(buffer, headerOffset + SIZE_OFFSET);
-		let name = readTarString(buffer, headerOffset + NAME_OFFSET, NAME_LENGTH);
-		if (isUstarHeader(buffer, headerOffset)) {
-			const prefix = readTarString(buffer, headerOffset + PREFIX_OFFSET, PREFIX_LENGTH);
+		if (!checksumMatches(header, 0)) throw new ArchiveError("Invalid or corrupt tar archive header");
+		const typeFlag = String.fromCharCode(header[TYPEFLAG_OFFSET] || 0x30);
+		let size = readTarSize(header, SIZE_OFFSET);
+		let name = readTarString(header, NAME_OFFSET, NAME_LENGTH);
+		if (isUstarHeader(header, 0)) {
+			const prefix = readTarString(header, PREFIX_OFFSET, PREFIX_LENGTH);
 			if (prefix) name = `${prefix}/${name}`;
 		}
-		let linkName = readTarString(buffer, headerOffset + LINKNAME_OFFSET, LINKNAME_LENGTH);
-		const mtime = readTarNumeric(buffer, headerOffset + MTIME_OFFSET, MTIME_LENGTH);
-		const rawMode = readTarNumeric(buffer, headerOffset + MODE_OFFSET, MODE_LENGTH);
+		let linkName = readTarString(header, LINKNAME_OFFSET, LINKNAME_LENGTH);
+		const mtime = readTarNumeric(header, MTIME_OFFSET, MTIME_LENGTH);
+		const rawMode = readTarNumeric(header, MODE_OFFSET, MODE_LENGTH);
 		const mode = Number.isSafeInteger(rawMode) && rawMode >= 0 ? rawMode : undefined;
-		offset += BLOCK_SIZE;
-		const dataBlocks = paddedSize(size);
-		if (dataBlocks > buffer.byteLength - offset) throw new ArchiveError("Archive member data is truncated");
-		const data = buffer.subarray(offset, offset + size);
 
 		if (typeFlag === "L") {
-			assertIndexSize(data.byteLength, limits, "GNU long-name metadata");
+			const data = await readTarMetadata(stream, size, limits, "GNU long-name metadata");
 			longName = readMetadataPath(data, "GNU long path", limits);
-			offset += dataBlocks;
 			continue;
 		}
 		if (typeFlag === "K") {
-			assertIndexSize(data.byteLength, limits, "GNU long-link metadata");
+			const data = await readTarMetadata(stream, size, limits, "GNU long-link metadata");
 			longLink = readMetadataPath(data, "GNU long link target", limits);
-			offset += dataBlocks;
 			continue;
 		}
 		if (typeFlag === "N") {
+			const data = await readTarMetadata(stream, size, limits, "old-GNU name metadata");
 			applyOldGnuNameRecords(data, entries, pendingLinks, limits);
-			offset += dataBlocks;
 			continue;
 		}
 		if (typeFlag === "x" || typeFlag === "X") {
-			localPax = parsePaxRecords(data, limits);
-			offset += dataBlocks;
+			localPax = parsePaxRecords(await readTarMetadata(stream, size, limits, "tar PAX metadata"), limits);
 			continue;
 		}
 		if (typeFlag === "g") {
-			applyGlobalPax(globalPax, parsePaxRecords(data, limits));
-			offset += dataBlocks;
+			applyGlobalPax(
+				globalPax,
+				parsePaxRecords(await readTarMetadata(stream, size, limits, "tar PAX metadata"), limits),
+			);
 			continue;
 		}
 		if (typeFlag === "M") throw new ArchiveError("GNU multi-volume tar members are not supported");
@@ -499,22 +636,18 @@ export function readTarEntriesFromBuffer(buffer: Uint8Array, options: FormatRead
 		const paxSparseRealSize = paxAttribute(globalPax, localPax, "GNU.sparse.realsize");
 		if (paxSparseRealSize !== undefined) displaySize = parsePaxSize(paxSparseRealSize, "sparse real size");
 		const sparse = typeFlag === "S" || paxDeclaresSparse(globalPax, localPax);
-		if (typeFlag === "S" && buffer[headerOffset + GNU_SPARSE_ISEXTENDED_OFFSET] === 1) {
+		if (typeFlag === "S" && header[GNU_SPARSE_ISEXTENDED_OFFSET] === 1) {
 			let extended = true;
 			while (extended) {
-				if (offset + BLOCK_SIZE > buffer.byteLength) {
-					throw new ArchiveError("Archive sparse metadata is truncated");
-				}
-				extended = buffer[offset + GNU_SPARSE_CONT_ISEXTENDED_OFFSET] === 1;
-				offset += BLOCK_SIZE;
+				const block = await stream.read(BLOCK_SIZE);
+				if (block.byteLength < BLOCK_SIZE) throw new ArchiveError("Archive sparse metadata is truncated");
+				extended = block[GNU_SPARSE_CONT_ISEXTENDED_OFFSET] === 1;
 			}
 		}
-		const dataOffset = offset;
-		const memberDataBlocks = paddedSize(size);
-		if (memberDataBlocks > buffer.byteLength - dataOffset) {
+		const dataOffset = stream.position;
+		if (!(await stream.skip(paddedSize(size)))) {
 			throw new ArchiveError(`Archive member '${formatArchivePathForError(name)}' is truncated`);
 		}
-		offset += memberDataBlocks;
 		longName = undefined;
 		longLink = undefined;
 		localPax = undefined;
@@ -567,7 +700,7 @@ export function readTarEntriesFromBuffer(buffer: Uint8Array, options: FormatRead
 			size: displaySize,
 			mtimeMs,
 			mode,
-			storage: { type: "member", source: new TarMemberSource(buffer, dataOffset, sparse) },
+			storage: { type: "member", source: new TarMemberSource(payload, dataOffset, sparse) },
 		});
 	}
 	if (!sawTerminator) throw new ArchiveError("Not a valid tar archive: missing terminating zero block");
@@ -575,6 +708,35 @@ export function readTarEntriesFromBuffer(buffer: Uint8Array, options: FormatRead
 	return [...entries.values()];
 }
 
+/** Index an already-decompressed tar buffer; members are views into it. */
+export async function readTarEntriesFromBuffer(
+	buffer: Uint8Array,
+	options: FormatReadOptions,
+): Promise<ArchiveIndexEntry[]> {
+	assertInMemorySize(buffer.byteLength, options.limits);
+	return readTarEntries(new TarByteStream([buffer]), new TarBufferPayload(buffer), options);
+}
+
+/**
+ * Index a decompressed tar stream that is too large to hold in memory: one
+ * pass over `open()` walks the headers, and member reads open it again.
+ */
+export async function readTarEntriesFromStream(
+	open: () => AsyncIterable<Uint8Array>,
+	options: FormatReadOptions,
+): Promise<ArchiveIndexEntry[]> {
+	const stream = new TarByteStream(open());
+	try {
+		const entries = await readTarEntries(stream, new TarStreamPayload(open), options);
+		// Decompress past the terminator to the end, so the codec still checks the
+		// stream's trailer (gzip CRC and length) as a whole-stream decompression does.
+		await stream.skip(Number.POSITIVE_INFINITY);
+		return entries;
+	} finally {
+		await stream.close();
+	}
+}
+
 /** Read and index a tar source after one bounded whole-stream read. */
 export const readTar: FormatReader = async (source, options) => {
 	assertInMemorySize(source.size, options.limits);

package/src/dirs.ts

@@ -18,6 +18,7 @@ import * as path from "node:path";
 import { expandWindowsLongPath } from "@linxiraos/pi-natives/path";
 import { engines, version } from "../package.json" with { type: "json" };
 import { isEnoent, isEnotdir } from "./fs-error";
+import { isBunTestRuntime } from "./test-runtime";
 
 /** App name (e.g. "zeta") — product-level identity: config-dir root, log file
  * names, provider attribution headers, splash wordmark. NOT the CLI command. */
@@ -166,12 +167,33 @@ function standardizeProjectPath(p: string): string {
 	return process.platform === "win32" ? expandWindowsLongPath(p) : standardizeMacOSPath(p);
 }
 
-export function resolveEquivalentPath(inputPath: string): string {
+export interface EquivalentPathOptions {
+	/**
+	 * Resolve a path that does not exist yet through its deepest existing ancestor, keeping the
+	 * missing suffix, so a symlinked parent canonicalizes the same before and after the path appears.
+	 */
+	throughMissing?: boolean;
+}
+
+export function resolveEquivalentPath(inputPath: string, options?: EquivalentPathOptions): string {
 	const resolvedPath = path.resolve(inputPath);
 	try {
 		return fs.realpathSync(resolvedPath);
 	} catch {
-		return resolvedPath;
+		if (!options?.throughMissing) return resolvedPath;
+	}
+	const missing: string[] = [];
+	let current = resolvedPath;
+	for (;;) {
+		const parent = path.dirname(current);
+		if (parent === current) return resolvedPath;
+		missing.unshift(path.basename(current));
+		current = parent;
+		try {
+			return path.join(fs.realpathSync(current), ...missing);
+		} catch {
+			// Keep walking: a higher ancestor may exist.
+		}
 	}
 }
 
@@ -654,6 +676,10 @@ export function getReportsDir(): string {
 
 /** Get the logs directory (~/.zeta/logs). */
 export function getLogsDir(): string {
+	if (isBunTestRuntime()) {
+		const uid = typeof process.getuid === "function" ? process.getuid() : os.userInfo().username;
+		return path.join(os.tmpdir(), `omp-test-logs-${uid}`);
+	}
 	return dirs.rootSubdir("logs", "state");
 }
 

package/src/env.ts

@@ -3,7 +3,9 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { parseEnv } from "node:util";
 import { getAgentDir, getConfigRootDir, getProjectDir, refreshDirsFromEnv } from "./dirs";
+import { isBunTestRuntime } from "./test-runtime";
 
+export * from "./test-runtime";
 export * from "./worker-host";
 
 const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -370,15 +372,6 @@ export function $envpos(name: string, defaultValue: number): number {
 	return parsed;
 }
 
-const BUN_TEST_ENTRY_PATTERN = /[._](?:test|spec)\.[cm]?[jt]sx?$/;
-
-/** True when the process is an explicitly marked test child or Bun is running a test entrypoint. */
-export function isBunTestRuntime(): boolean {
-	if (Bun.env.PI_TEST_RUNTIME === "1") return true;
-	const hasTestEnvironment = Bun.env.BUN_ENV === "test" || Bun.env.NODE_ENV === "test";
-	return hasTestEnvironment && BUN_TEST_ENTRY_PATTERN.test(Bun.main);
-}
-
 let terminalHeadless = isBunTestRuntime();
 
 /**

package/src/frontmatter.ts

@@ -2,8 +2,13 @@ import { YAML } from "bun";
 import { truncate } from "./format";
 import * as logger from "./logger";
 
-function stripHtmlComments(content: string): string {
-	return content.replace(/<!--[\s\S]*?-->/g, "");
+function stripLeadingHtmlComments(content: string): string {
+	const leading = /^(?:(?:\s*<!--[\s\S]*?-->)+)/.exec(content);
+	if (!leading) return content;
+	const rest = content.slice(leading[0].length);
+	// Only repair a comment that precedes frontmatter; leave a plain document
+	// (and every body) byte-identical so HTML comments inside it survive.
+	return /^\s*---/.test(rest) ? rest.replace(/^\s+/, "") : content;
 }
 
 /** Convert kebab-case to camelCase (e.g. "thinking-level" -> "thinkingLevel") */
@@ -142,7 +147,8 @@ export function parseFrontmatter(
 	const frontmatter: Record<string, unknown> = { ...fallback };
 
 	const newlineNormalized = normalize ? content.replace(/\r\n?/g, "\n") : content;
-	const normalized = normalize && repair ? stripHtmlComments(newlineNormalized) : newlineNormalized;
+	const repairHtmlComments = normalize && repair;
+	const normalized = repairHtmlComments ? stripLeadingHtmlComments(newlineNormalized) : newlineNormalized;
 	if (!normalized.startsWith("---")) {
 		return { frontmatter, body: normalized };
 	}
@@ -152,7 +158,8 @@ export function parseFrontmatter(
 		return { frontmatter, body: normalized };
 	}
 
-	const metadata = normalized.slice(4, endIndex);
+	const rawMetadata = normalized.slice(4, endIndex);
+	const metadata = repairHtmlComments ? rawMetadata.replace(/<!--[\s\S]*?-->/g, "") : rawMetadata;
 	const body = normalized.slice(endIndex + 4).trim();
 
 	try {

package/src/fs-open.ts

@@ -15,7 +15,8 @@ const O_CLOEXEC = process.platform === "linux" ? 0o2000000 : process.platform ==
  * `fs.openSync` with close-on-exec, matching Node's default.
  *
  * libuv adds `O_CLOEXEC` inside `uv__fs_open`, so on Node every `fs` descriptor
- * dies at `exec`. Bun's `fs.open*` does not, and descriptors it returns survive
+ * dies at `exec`. Bun's `fs.open*` did not before 1.4.3 (still allowed by the
+ * `bun@>=1.4` pin), and descriptors it returns survive
  * into any child spawned through a path that does not close strays itself — the
  * bash tool's shell `fork`/`exec`s user commands and hands them the lot. Use
  * this for every descriptor kept open past such a spawn (session transcripts,

package/src/test-runtime.ts

@@ -0,0 +1,8 @@
+const BUN_TEST_ENTRY_PATTERN = /[._](?:test|spec)\.[cm]?[jt]sx?$/;
+
+/** True when the process is an explicitly marked test child or Bun is running a test entrypoint. */
+export function isBunTestRuntime(): boolean {
+	if (Bun.env.PI_TEST_RUNTIME === "1") return true;
+	const hasTestEnvironment = Bun.env.BUN_ENV === "test" || Bun.env.NODE_ENV === "test";
+	return hasTestEnvironment && BUN_TEST_ENTRY_PATTERN.test(Bun.main);
+}