@oh-my-pi/pi-utils 18.12.2 → 18.12.4

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [18.12.4] - 2026-10-20
+
+### Breaking Changes
+
+- `readTarEntriesFromBuffer()` in `@oh-my-pi/pi-utils/ar/tar` now returns `Promise<ArchiveIndexEntry[]>` instead of `ArchiveIndexEntry[]`; `await` its result ([#16394](https://github.com/can1357/oh-my-pi/pull/16394) by [@will-bogusz](https://github.com/will-bogusz))
+
+### Added
+
+- Added `maxStreamSize` to `ArchiveLimits` (default 4 GB): the most a large `.tar.gz` or `.tar.zst` may decompress in one pass, so a decompression bomb fails instead of running without bound ([#16394](https://github.com/can1357/oh-my-pi/pull/16394) by [@will-bogusz](https://github.com/will-bogusz))
+
+### Fixed
+
+- Fixed `bun test` runs writing their logs into your real `~/.omp/logs`: test processes now log to a per-user `omp-test-logs-<uid>/` under the OS temp dir ([#16386](https://github.com/can1357/oh-my-pi/pull/16386) by [@will-bogusz](https://github.com/will-bogusz))
+- Fixed `.tar.gz` and `.tar.zst` archives that decompress past 256 MB failing to list or read with a raw `Cannot create a Buffer larger than …` error; a bare `.gz` or `.zst` that large now names the archive size limit ([#16394](https://github.com/can1357/oh-my-pi/pull/16394) by [@will-bogusz](https://github.com/will-bogusz))
+- Fixed frontmatter repair deleting HTML comments from document bodies and plain markdown; it now strips only leading comments ahead of the opening delimiter, so prompt bodies keep their comments ([#16481](https://github.com/can1357/oh-my-pi/pull/16481) by [@adi-IL](https://github.com/adi-IL)).
+
 ## [18.12.2] - 2026-10-18
 
 ### Added

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 `~/.omp/logs/` with rotation (TUI-safe — never stdout)         |
+| `logger`                                                                                                           | Centralized logger writing to `~/.omp/logs/` (`bun test`: temp dir), rotating, never stdout  |
 | `prompt`                                                                                                           | Handlebars-based prompt templating and formatting helpers                                    |
 | `dirs`                                                                                                             | Path helpers for omp config directories (`~/.omp`, XDG-aware on Linux)                       |
 | `stream`                                                                                                           | `readStream` / `readLines` helpers over `ReadableStream`                                     |

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

@@ -44,7 +44,14 @@ export declare function normalizeProfileName(profile: string | undefined): strin
 export declare function resolveProfileEnv(omp: string | undefined, pi: string | undefined): string | undefined;
 /** Profile-independent config root (~/.omp), shared by every omp 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}.
@@ -135,7 +142,12 @@ export declare function getAgentDir(): string;
 export declare function getProjectAgentDir(cwd?: string): string;
 /** Get the reports directory (~/.omp/reports). */
 export declare function getReportsDir(): string;
-/** Get the logs directory (~/.omp/logs). */
+/**
+ * Get the logs directory (~/.omp/logs). `bun test` processes get
+ * `<tmpdir>/omp-test-logs-<uid>` instead, so suites never write into the
+ * developer's real logs; the uid suffix (as for the test session-owners dir)
+ * keeps users of a shared `/tmp` from owning each other's directory.
+ */
 export declare function getLogsDir(): string;
 /**
  * Local-timezone `YYYY-MM-DD` day key (zero-padded), formatted exactly like

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
@@ -82,8 +83,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/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": "@oh-my-pi/pi-utils",
-	"version": "18.12.2",
+	"version": "18.12.4",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"cli",
@@ -57,7 +57,7 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.12.2"
+		"@oh-my-pi/pi-natives": "18.12.4"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

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

@@ -17,6 +17,7 @@ import * as path from "node:path";
 import { expandWindowsLongPath } from "@oh-my-pi/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. "omp") */
 export const APP_NAME: string = "omp";
@@ -160,12 +161,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.
+		}
 	}
 }
 
@@ -634,8 +656,17 @@ export function getReportsDir(): string {
 	return dirs.rootSubdir("reports", "state");
 }
 
-/** Get the logs directory (~/.omp/logs). */
+/**
+ * Get the logs directory (~/.omp/logs). `bun test` processes get
+ * `<tmpdir>/omp-test-logs-<uid>` instead, so suites never write into the
+ * developer's real logs; the uid suffix (as for the test session-owners dir)
+ * keeps users of a shared `/tmp` from owning each other's directory.
+ */
 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_]*$/;
@@ -378,15 +380,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/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);
+}