@linxiraos/pi-utils 1.1.14 → 1.1.16

package/dist/types/stream.d.ts

@@ -1,5 +1,43 @@
+/**
+ * Split a byte stream on LF boundaries.
+ *
+ * Every yielded line owns its bytes and remains unchanged after the generator
+ * advances or drains. Line terminators are excluded.
+ */
 export declare function readLines(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<Uint8Array>;
 export declare function readJsonl<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<T>;
+/**
+ * Amortized byte accumulator for chunked stream readers.
+ *
+ * Holds the unconsumed tail of a stream in a single growing `Buffer` so that
+ * appending N chunks costs O(total bytes) instead of re-copying the whole
+ * prefix per chunk. Backs {@link readLines}, {@link readJsonl} and
+ * {@link readSseEvents}; also usable directly when a reader needs its own
+ * framing loop (see `consume` and `flush`).
+ */
+export declare class ConcatSink {
+    #private;
+    append(chunk: Uint8Array): void;
+    reset(chunk: Uint8Array): void;
+    get isEmpty(): boolean;
+    /**
+     * The buffered bytes as a live view — invalidated by the next `append`,
+     * `reset` or `consume`.
+     */
+    flush(): Uint8Array | undefined;
+    /** Drop the first `count` buffered bytes, keeping the remainder. */
+    consume(count: number): void;
+    clear(): void;
+    /**
+     * Append a chunk and yield each complete LF-delimited line.
+     *
+     * Yielded lines are owned snapshots. Unlike {@link flush}, they remain
+     * valid after this sink or the input chunk is mutated.
+     */
+    appendAndFlushLines(chunk: Uint8Array): Generator<Uint8Array>;
+    appendAndFlushText(chunk: Uint8Array, decoder: TextDecoder): string | undefined;
+    pullJSONL<T>(chunk: Uint8Array, beg: number, end: number): Generator<T, void, unknown>;
+}
 /**
  * Stream parsed JSON objects from SSE `data:` lines.
  *
@@ -18,6 +56,25 @@ export declare function readJsonl<T>(stream: ReadableStream<Uint8Array>, signal?
  */
 export type SseEventObserver = (event: ServerSentEvent) => void;
 export declare function readSseJson<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal, onEvent?: SseEventObserver): AsyncGenerator<T>;
+/**
+ * Like {@link readSseJson}, but a `data:` frame that is not valid JSON is yielded
+ * as its raw text instead of raising a `SyntaxError`. Cut-off container-shaped
+ * stream tails stay recoverable, exactly as they are in {@link readSseJson}.
+ *
+ * Consumers that only understand objects must treat a `string` yield as a
+ * transport-level failure (for example a `429 Too Many Requests` or an HTML
+ * throttle page from a reverse proxy that already committed to the stream). This
+ * exists because `readSseJson`'s baseline consumers span unrelated transports
+ * whose error handling a text yield would subtly change; new call sites opt in.
+ *
+ * Note that the text lane is only the frames `JSON.parse` *rejected*: a frame
+ * carrying a JSON-encoded string (`data: "429 Too Many Requests"`) parses, so it
+ * is yielded as that string and is indistinguishable from a rejected frame by
+ * type alone. Consumers branching on `typeof === "string"` therefore see both,
+ * which is the safe direction — each is classified as text rather than trusted as
+ * an event object.
+ */
+export declare function readSseJsonOrText<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal, onEvent?: SseEventObserver): AsyncGenerator<T | string>;
 /**
  * A single Server-Sent Event dispatched on a blank-line boundary.
  *
@@ -34,6 +91,15 @@ export declare function readSseJson<T>(stream: ReadableStream<Uint8Array>, signa
 export interface ServerSentEvent {
     event: string | null;
     data: string;
+    /**
+     * Decoded wire lines for this event (`event:`/`data:`/etc.), for the
+     * diagnostic pipeline. Populated only when the reader opts in via
+     * {@link ReadSseEventsOptions.captureRaw} (or attaches an `onSseEvent`
+     * observer to the JSON readers, which opt in automatically); otherwise
+     * `[]`. Direct `readSseEvents` callers that need wire text must pass
+     * `{ captureRaw: true }` — the field is allocation-free by default so
+     * the token path pays no per-frame array/slice cost.
+     */
     raw: string[];
     id?: string;
     retry?: number;
@@ -57,7 +123,16 @@ export interface ServerSentEvent {
  * }
  * ```
  */
-export declare function readSseEvents(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<ServerSentEvent>;
+export interface ReadSseEventsOptions {
+    /**
+     * Capture per-line wire text into `event.raw` for the diagnostic
+     * pipeline (`onSseEvent` observers, raw-SSE viewer). Off by default:
+     * every frame otherwise pays an array allocation plus one string slice
+     * per line on the token path.
+     */
+    captureRaw?: boolean;
+}
+export declare function readSseEvents(stream: ReadableStream<Uint8Array>, signal?: AbortSignal, options?: ReadSseEventsOptions): AsyncGenerator<ServerSentEvent>;
 /**
  * Parse a complete JSONL string, skipping malformed lines instead of throwing.
  *

package/dist/types/which.d.ts

@@ -1,7 +1,7 @@
 /**
  * Cache policy for which lookups.
  */
-export declare const enum WhichCachePolicy {
+export declare enum WhichCachePolicy {
     /**
      * Use cached result if available.
      */
@@ -22,9 +22,15 @@ export declare const enum WhichCachePolicy {
 export interface WhichOptions extends Bun.WhichOptions {
     /**
      * Cache policy for the lookup.
-     * Defaults to `WhichCachePolicy.Fresh`.
+     * Defaults to `WhichCachePolicy.Cached`.
      */
     cache?: WhichCachePolicy;
+    /**
+     * Only search absolute directory entries in PATH, ignoring relative entries
+     * (e.g. `.` or `./bin`) and empty components to prevent resolving against
+     * an untrusted working directory.
+     */
+    requireAbsolutePaths?: boolean;
 }
 declare function darwinWhich(command: string, options?: Bun.WhichOptions): string | null;
 export declare const whichFresh: typeof darwinWhich;

package/dist/types/yaml-config.d.ts

@@ -0,0 +1,2 @@
+/** Serialize config YAML without Bun's trailing space on block mapping headers. */
+export declare function stringifyYamlConfig(value: unknown): string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@linxiraos/pi-utils",
-	"version": "1.1.14",
+	"version": "1.1.16",
 	"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.1.14"
+		"@linxiraos/pi-natives": "1.1.16"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/acp/transport.ts

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

package/src/async.ts

@@ -1,3 +1,34 @@
+import { scheduler } from "node:timers/promises";
+
+/**
+ * Largest delay `setTimeout` (and `timers/promises` `scheduler.wait`)
+ * accepts without 32-bit signed overflow: larger values wrap and fire
+ * almost immediately instead of sleeping. Chunk day-scale provider waits
+ * (e.g. a monthly quota reset parsed from an error hint) so the full
+ * duration elapses instead of overflowing the timer.
+ */
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
+
+/**
+ * Abortable sleep for arbitrarily long delays. Waits longer than
+ * {@link MAX_TIMER_DELAY_MS} chunk the sleep into back-to-back timer waits
+ * so no single timer overflows; an abort during any chunk rejects like
+ * `scheduler.wait`.
+ *
+ * Uses a monotonic deadline so a timer that wakes prematurely is re-armed for
+ * the unelapsed duration instead of shortening the requested sleep.
+ */
+export async function sleepLong(delayMs: number, signal?: AbortSignal): Promise<void> {
+	signal?.throwIfAborted();
+	const deadline = performance.now() + delayMs;
+	while (true) {
+		const remaining = deadline - performance.now();
+		if (!(remaining > 0)) return;
+		await scheduler.wait(Math.min(remaining, MAX_TIMER_DELAY_MS), { signal });
+		signal?.throwIfAborted();
+	}
+}
+
 /**
  * Wrap a promise with a timeout and optional abort signal.
  * Rejects with the given error or a new error containing the given message if

package/src/browsers.ts

@@ -1,13 +1,14 @@
-/** Behavior-compatible reimplementation of @puppeteer/browsers' used surface. */
-
-import type * as fs from "node:fs";
+/** Managed Chrome-for-Testing installation with bounded downloads and atomic publication. */
 import * as fsp from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
 import { type ArchiveLimits, extractArchive } from "./ar";
+import { withFileLock } from "./file-lock";
 
 const CHROME_FOR_TESTING_BASE_URL = "https://storage.googleapis.com/chrome-for-testing-public";
-const CHROME_METADATA_BASE_URL = "https://googlechromelabs.github.io/chrome-for-testing";
+// Installation is outside browser/Eval operation deadlines, but a stalled CDN
+// must still release the cached install promise and permit a later attempt.
+const DOWNLOAD_TIMEOUT_MS = 5 * 60_000;
 
 /**
  * Archive ceilings for the managed browser download. The default archive
@@ -21,15 +22,6 @@ const BROWSER_ARCHIVE_LIMITS: Partial<ArchiveLimits> = {
 	maxInMemorySize: 1024 * 1024 * 1024,
 };
 
-/** Supported browser products. */
-export enum Browser {
-	CHROME = "chrome",
-	CHROMEHEADLESSSHELL = "chrome-headless-shell",
-	CHROMIUM = "chromium",
-	FIREFOX = "firefox",
-	CHROMEDRIVER = "chromedriver",
-}
-
 /** Browser download platform identifiers. */
 export enum BrowserPlatform {
 	LINUX = "linux",
@@ -47,34 +39,6 @@ function requireChromeForTestingPlatform(platform: BrowserPlatform): ChromeForTe
 	return platform;
 }
 
-const BROWSERS = [
-	Browser.CHROME,
-	Browser.CHROMEHEADLESSSHELL,
-	Browser.CHROMIUM,
-	Browser.FIREFOX,
-	Browser.CHROMEDRIVER,
-] as const;
-const BROWSER_PLATFORMS = [
-	BrowserPlatform.LINUX,
-	BrowserPlatform.LINUX_ARM,
-	BrowserPlatform.MAC,
-	BrowserPlatform.MAC_ARM,
-	BrowserPlatform.WIN32,
-	BrowserPlatform.WIN64,
-] as const;
-
-/** Chrome-for-Testing release channel tags accepted by {@link resolveBuildId}. */
-export enum BrowserTag {
-	CANARY = "canary",
-	NIGHTLY = "nightly",
-	BETA = "beta",
-	DEV = "dev",
-	DEVEDITION = "devedition",
-	STABLE = "stable",
-	ESR = "esr",
-	LATEST = "latest",
-}
-
 /** Download progress reported while a browser archive is streamed to disk. */
 export interface BrowserDownloadProgress {
 	downloadedBytes: number;
@@ -83,7 +47,6 @@ export interface BrowserDownloadProgress {
 
 /** Inputs used to locate an installed browser executable. */
 export interface ComputeExecutablePathOptions {
-	browser: Browser;
 	buildId: string;
 	cacheDir: string;
 	platform?: BrowserPlatform;
@@ -95,27 +58,14 @@ export interface InstallOptions extends ComputeExecutablePathOptions {
 	downloadProgressCallback?: (progress: BrowserDownloadProgress) => void;
 }
 
-/** Metadata for one browser installation found in a Puppeteer cache. */
+/** Metadata for a managed Chrome installation in Puppeteer's cache layout. */
 export interface InstalledBrowser {
-	browser: Browser;
 	buildId: string;
 	platform: BrowserPlatform;
 	path: string;
 	executablePath: string;
 }
 
-interface LastKnownGoodVersions {
-	channels: Record<string, { version: string }>;
-}
-
-interface MilestoneVersions {
-	milestones: Record<string, { version: string }>;
-}
-
-interface PatchVersions {
-	builds: Record<string, { version: string }>;
-}
-
 /** Detect the current host's Puppeteer browser platform. */
 export function detectBrowserPlatform(): BrowserPlatform | undefined {
 	const platform = os.platform();
@@ -126,43 +76,8 @@ export function detectBrowserPlatform(): BrowserPlatform | undefined {
 	return undefined;
 }
 
-/** Resolve a Chrome-for-Testing channel, milestone, or build prefix to a full build ID. */
-export async function resolveBuildId(
-	browser: Browser,
-	_platform: BrowserPlatform,
-	tag: string | BrowserTag,
-): Promise<string> {
-	if (browser !== Browser.CHROME && browser !== Browser.CHROMEHEADLESSSHELL && browser !== Browser.CHROMEDRIVER) {
-		return tag;
-	}
-	if (/^\d+\.\d+\.\d+\.\d+$/.test(tag)) return tag;
-
-	const channel = tag === BrowserTag.LATEST ? "Canary" : chromeChannelName(tag);
-	if (channel) {
-		const metadata = await fetchMetadata<LastKnownGoodVersions>("last-known-good-versions.json");
-		const version = metadata.channels[channel]?.version;
-		if (!version) throw new Error(`Chrome channel ${tag} was not found in Chrome-for-Testing metadata`);
-		return version;
-	}
-	if (/^\d+$/.test(tag)) {
-		const metadata = await fetchMetadata<MilestoneVersions>("latest-versions-per-milestone.json");
-		return metadata.milestones[tag]?.version ?? tag;
-	}
-	if (/^\d+\.\d+\.\d+$/.test(tag)) {
-		const metadata = await fetchMetadata<PatchVersions>("latest-patch-versions-per-build.json");
-		return metadata.builds[tag]?.version ?? tag;
-	}
-	return tag;
-}
-
 /** Return the Chrome-for-Testing archive URL for a browser build. */
-export function getDownloadUrl(
-	browser: Browser,
-	platform: BrowserPlatform,
-	buildId: string,
-	baseUrl = CHROME_FOR_TESTING_BASE_URL,
-): URL {
-	if (browser !== Browser.CHROME) throw new Error(`Unsupported browser download: ${browser}`);
+export function getDownloadUrl(platform: BrowserPlatform, buildId: string, baseUrl = CHROME_FOR_TESTING_BASE_URL): URL {
 	const archivePlatform = chromeArchivePlatform(platform);
 	const root = baseUrl.replace(/\/$/, "");
 	return new URL(`${root}/${buildId}/${archivePlatform}/chrome-${archivePlatform}.zip`);
@@ -172,9 +87,8 @@ export function getDownloadUrl(
 export function computeExecutablePath(options: ComputeExecutablePathOptions): string {
 	const detectedPlatform = options.platform ?? detectBrowserPlatform();
 	if (!detectedPlatform) throw new Error("Cannot determine a browser platform for this host");
-	if (options.browser !== Browser.CHROME) throw new Error(`Unsupported browser executable: ${options.browser}`);
 	const platform = requireChromeForTestingPlatform(detectedPlatform);
-	const installDir = installationDir(options.cacheDir, options.browser, platform, options.buildId);
+	const installDir = installationDir(options.cacheDir, platform, options.buildId);
 	switch (platform) {
 		case BrowserPlatform.LINUX:
 			return path.join(installDir, "chrome-linux64", "chrome");
@@ -203,99 +117,49 @@ export function computeExecutablePath(options: ComputeExecutablePathOptions): st
 	}
 }
 
-/** Scan a Puppeteer cache for browser installation directories. */
-export async function getInstalledBrowsers(options: { cacheDir: string }): Promise<InstalledBrowser[]> {
-	const installed: InstalledBrowser[] = [];
-	for (const browser of BROWSERS) {
-		const browserDir = path.join(options.cacheDir, browser);
-		let entries: fs.Dirent[];
-		try {
-			entries = await fsp.readdir(browserDir, { withFileTypes: true });
-		} catch (error) {
-			if (isMissingPath(error)) continue;
-			throw error;
-		}
-		for (const entry of entries) {
-			if (!entry.isDirectory()) continue;
-			const parsed = parseInstallationName(entry.name);
-			if (!parsed) continue;
-			const installPath = path.join(browserDir, entry.name);
-			try {
-				installed.push({
-					browser,
-					buildId: parsed.buildId,
-					platform: parsed.platform,
-					path: installPath,
-					executablePath: computeExecutablePath({
-						browser,
-						buildId: parsed.buildId,
-						cacheDir: options.cacheDir,
-						platform: parsed.platform,
-					}),
-				});
-			} catch {
-				// Other browser products are not part of the surface used by OMP.
-			}
-		}
-	}
-	return installed;
-}
-
 /** Download and unpack Chrome into Puppeteer's existing cache layout. */
 export async function install(options: InstallOptions): Promise<InstalledBrowser> {
 	const platform = options.platform ?? detectBrowserPlatform();
 	if (!platform) throw new Error("Cannot determine a browser platform for this host");
 	const executablePath = computeExecutablePath({ ...options, platform });
-	const installPath = installationDir(options.cacheDir, options.browser, platform, options.buildId);
+	const installPath = installationDir(options.cacheDir, platform, options.buildId);
 	if (await pathExists(executablePath)) {
-		return { browser: options.browser, buildId: options.buildId, platform, path: installPath, executablePath };
+		return { buildId: options.buildId, platform, path: installPath, executablePath };
 	}
 
-	await fsp.mkdir(options.cacheDir, { recursive: true });
-	const nonce = `${process.pid}-${crypto.randomUUID()}`;
-	const archivePath = path.join(options.cacheDir, `.browser-${nonce}.zip`);
-	const stagingPath = path.join(options.cacheDir, `.browser-${nonce}`);
-	try {
-		await downloadArchive(
-			getDownloadUrl(options.browser, platform, options.buildId, options.baseUrl),
-			archivePath,
-			options.downloadProgressCallback,
-		);
-		await extractArchive(archivePath, stagingPath, { limits: BROWSER_ARCHIVE_LIMITS });
-		await fsp.mkdir(path.dirname(installPath), { recursive: true });
-		await fsp.rm(installPath, { recursive: true, force: true });
-		await fsp.rename(stagingPath, installPath);
-	} finally {
-		await Promise.all([
-			fsp.rm(archivePath, { force: true }).catch(() => {}),
-			fsp.rm(stagingPath, { recursive: true, force: true }).catch(() => {}),
-		]);
-	}
-	if (!(await pathExists(executablePath)))
-		throw new Error(`Browser archive did not contain its expected executable: ${executablePath}`);
-	return { browser: options.browser, buildId: options.buildId, platform, path: installPath, executablePath };
-}
-
-function chromeChannelName(tag: string): string | undefined {
-	switch (tag) {
-		case BrowserTag.STABLE:
-			return "Stable";
-		case BrowserTag.BETA:
-			return "Beta";
-		case BrowserTag.DEV:
-			return "Dev";
-		case BrowserTag.CANARY:
-			return "Canary";
-		default:
-			return undefined;
-	}
-}
-
-async function fetchMetadata<T>(filename: string): Promise<T> {
-	const response = await fetch(`${CHROME_METADATA_BASE_URL}/${filename}`);
-	if (!response.ok)
-		throw new Error(`Failed to fetch Chrome-for-Testing metadata (${response.status} ${response.statusText})`);
-	return (await response.json()) as T;
+	await fsp.mkdir(path.dirname(installPath), { recursive: true });
+	return withFileLock(
+		`${installPath}.install`,
+		async () => {
+			// The in-process launch promise cannot serialize separate OMP sessions.
+			// Recheck under the OS lock: never replace a winner's running Chrome.
+			if (!(await pathExists(executablePath))) {
+				const nonce = `${process.pid}-${crypto.randomUUID()}`;
+				const archivePath = path.join(options.cacheDir, `.browser-${nonce}.zip`);
+				const stagingPath = path.join(options.cacheDir, `.browser-${nonce}`);
+				try {
+					await downloadArchive(
+						getDownloadUrl(platform, options.buildId, options.baseUrl),
+						archivePath,
+						options.downloadProgressCallback,
+					);
+					await extractArchive(archivePath, stagingPath, { limits: BROWSER_ARCHIVE_LIMITS });
+					if (!(await pathExists(path.join(stagingPath, path.relative(installPath, executablePath))))) {
+						throw new Error(`Browser archive did not contain its expected executable: ${executablePath}`);
+					}
+					await fsp.rm(installPath, { recursive: true, force: true });
+					await fsp.rename(stagingPath, installPath);
+				} finally {
+					await Promise.all([
+						fsp.rm(archivePath, { force: true }).catch(() => {}),
+						fsp.rm(stagingPath, { recursive: true, force: true }).catch(() => {}),
+					]);
+				}
+			}
+			return { buildId: options.buildId, platform, path: installPath, executablePath };
+		},
+		{ retries: Math.ceil(DOWNLOAD_TIMEOUT_MS / 100) + 1, retryDelayMs: 100 },
+	);
 }
 
 function chromeArchivePlatform(platform: BrowserPlatform): string {
@@ -313,17 +177,8 @@ function chromeArchivePlatform(platform: BrowserPlatform): string {
 	}
 }
 
-function installationDir(cacheDir: string, browser: Browser, platform: BrowserPlatform, buildId: string): string {
-	return path.join(cacheDir, browser, `${platform}-${buildId}`);
-}
-
-function parseInstallationName(name: string): { platform: BrowserPlatform; buildId: string } | undefined {
-	for (const platform of BROWSER_PLATFORMS) {
-		const prefix = `${platform}-`;
-		if (name.startsWith(prefix) && name.length > prefix.length)
-			return { platform, buildId: name.slice(prefix.length) };
-	}
-	return undefined;
+function installationDir(cacheDir: string, platform: BrowserPlatform, buildId: string): string {
+	return path.join(cacheDir, "chrome", `${platform}-${buildId}`);
 }
 
 function isMissingPath(error: unknown): boolean {
@@ -345,7 +200,7 @@ async function downloadArchive(
 	destination: string,
 	onProgress: ((progress: BrowserDownloadProgress) => void) | undefined,
 ): Promise<void> {
-	const response = await fetch(url);
+	const response = await fetch(url, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
 	if (!response.ok || !response.body) {
 		throw new Error(`Browser download failed (${response.status} ${response.statusText}) from ${url}`);
 	}

package/src/color.ts

@@ -239,7 +239,7 @@ const ANSI_16: readonly (readonly [number, number, number])[] = [
 const CUBE_STEPS = [0, 95, 135, 175, 215, 255] as const;
 
 /** Parse a 256-color palette index (0–255) to RGB (0..255). */
-function paletteToRgb(index: number): RGB | undefined {
+export function paletteToRgb(index: number): RGB | undefined {
 	if (!Number.isInteger(index) || index < 0 || index > 255) return undefined;
 	if (index < 16) {
 		const rgb = ANSI_16[index];

package/src/dirs.ts

@@ -104,7 +104,8 @@ function readProfileFromEnvSafe(): string | undefined {
 	}
 }
 
-function getBaseConfigRoot(): string {
+/** Profile-independent config root (~/.zeta), shared by every zeta profile. */
+export function getBaseConfigRoot(): string {
 	return path.join(os.homedir(), getConfigDirName());
 }
 
@@ -153,19 +154,31 @@ export function normalizePathForComparison(inputPath: string): string {
 	return process.platform === "win32" ? resolvedPath.toLowerCase() : resolvedPath;
 }
 
+/**
+ * Compare paths already normalized by {@link normalizePathForComparison}.
+ *
+ * Returns the relative path (an empty string when the paths are equal), or
+ * `null` when the candidate is outside the root. Callers classifying one
+ * candidate against several static roots can normalize each side once and
+ * reuse the public helpers' containment semantics without repeating realpath
+ * work.
+ */
+export function relativePathWithinNormalizedRoot(normalizedRoot: string, normalizedCandidate: string): string | null {
+	const relative = path.relative(normalizedRoot, normalizedCandidate);
+	if (relative !== "" && (relative.startsWith("..") || path.isAbsolute(relative))) return null;
+	return relative;
+}
+
 export function pathIsWithin(root: string, candidate: string): boolean {
 	const normalizedRoot = normalizePathForComparison(root);
 	const normalizedCandidate = normalizePathForComparison(candidate);
-	const relative = path.relative(normalizedRoot, normalizedCandidate);
-	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+	return relativePathWithinNormalizedRoot(normalizedRoot, normalizedCandidate) !== null;
 }
 
 export function relativePathWithinRoot(root: string, candidate: string): string | null {
-	if (!pathIsWithin(root, candidate)) return null;
 	const normalizedRoot = normalizePathForComparison(root);
 	const normalizedCandidate = normalizePathForComparison(candidate);
-	const relative = path.relative(normalizedRoot, normalizedCandidate);
-	return relative || null;
+	return relativePathWithinNormalizedRoot(normalizedRoot, normalizedCandidate) || null;
 }
 
 let projectDir: string | undefined;
@@ -687,6 +700,11 @@ export function getBrowserRelayDir(): string {
 	return dirs.rootSubdir("browser-relay", "data");
 }
 
+/** Get the profile root for Chromium browsers the browser tool spawns via `app.path` (~/.zeta/browser-profiles). */
+export function getBrowserProfilesDir(): string {
+	return dirs.rootSubdir("browser-profiles", "state");
+}
+
 /** Get DOCS_RS cache directory () */
 export function getDocsRsCacheDir(): string {
 	return dirs.rootSubdir("webcache", "cache");
@@ -893,6 +911,16 @@ export function getTerminalSessionsDir(agentDir?: string): string {
 	return dirs.agentSubdir(agentDir, "terminal-sessions", "state");
 }
 
+/**
+ * Get the persistent registry of custom session files
+ * (~/.zeta/agent/custom-session-files). Each `--session-dir`/`--session`
+ * transcript is recorded here as one marker file so storage GC can scan its
+ * exact path after its terminal breadcrumb is overwritten by a later session.
+ */
+export function getCustomSessionFilesDir(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, "custom-session-files", "state");
+}
+
 /** Get the crash log path (~/.zeta/agent/zeta-crash.log). */
 export function getCrashLogPath(agentDir?: string): string {
 	return dirs.agentSubdir(agentDir, "zeta-crash.log", "state");