@linxiraos/pi-utils 1.4.7 → 1.4.10

package/src/ar/lzh.ts

@@ -1,3 +1,4 @@
+import { readUInt16LE, readUInt32LE } from "./bytes";
 import { crc16Arc } from "./checksums";
 import { ArchiveError } from "./error";
 import { assertArchiveMemberSize, assertEntryCount, assertIndexSize, assertInMemorySize } from "./limits";
@@ -279,16 +280,8 @@ function crc16WithZeroRange(bytes: Uint8Array, zeroStart: number, zeroEnd: numbe
 	return crc16Arc(bytes.subarray(zeroEnd), value);
 }
 
-function u16(bytes: Uint8Array, offset: number): number {
-	return bytes[offset]! | (bytes[offset + 1]! << 8);
-}
-
-function u32(bytes: Uint8Array, offset: number): number {
-	return (bytes[offset]! | (bytes[offset + 1]! << 8) | (bytes[offset + 2]! << 16) | (bytes[offset + 3]! << 24)) >>> 0;
-}
-
 function u64(bytes: Uint8Array, offset: number): number {
-	const value = u32(bytes, offset) + u32(bytes, offset + 4) * 0x100000000;
+	const value = readUInt32LE(bytes, offset) + readUInt32LE(bytes, offset + 4) * 0x100000000;
 	if (!Number.isSafeInteger(value)) throw new ArchiveError("LZH uses sizes too large to read safely");
 	return value;
 }
@@ -318,7 +311,8 @@ function decodeUtf16(bytes: Uint8Array): string {
 	return UTF16LE_DECODER.decode(bytes.subarray(0, end));
 }
 
-function dosTimeToMs(value: number): number | undefined {
+/** MS-DOS packed date/time as UTC milliseconds; `undefined` for 0 or an out-of-range field. */
+export function dosTimeToMs(value: number): number | undefined {
 	if (value === 0) return undefined;
 	const year = 1980 + ((value >>> 25) & 0x7f);
 	const month = (value >>> 21) & 0x0f;
@@ -352,7 +346,7 @@ function processExtendedHeader(
 	switch (type) {
 		case 0x00:
 			if (data.byteLength < 2) throw new ArchiveError("Invalid LZH common extended header");
-			fields.commonCrc = u16(data, 0);
+			fields.commonCrc = readUInt16LE(data, 0);
 			fields.commonCrcOffset = absoluteDataOffset;
 			break;
 		case 0x01:
@@ -365,8 +359,8 @@ function processExtendedHeader(
 			throw new ArchiveError("Multi-volume LZH archives are unsupported");
 		case 0x41:
 			if (data.byteLength >= 16) {
-				const low = u32(data, 8);
-				const high = u32(data, 12);
+				const low = readUInt32LE(data, 8);
+				const high = readUInt32LE(data, 12);
 				const filetime = low + high * 0x100000000;
 				if (Number.isSafeInteger(filetime)) fields.mtimeMs = filetime / 10_000 - 11_644_473_600_000;
 			}
@@ -384,11 +378,11 @@ function processExtendedHeader(
 			break;
 		case 0x50:
 			if (data.byteLength < 2) throw new ArchiveError("Invalid LZH Unix permissions extended header");
-			fields.mode = u16(data, 0);
+			fields.mode = readUInt16LE(data, 0);
 			break;
 		case 0x54:
 			if (data.byteLength < 4) throw new ArchiveError("Invalid LZH Unix timestamp extended header");
-			fields.mtimeMs = u32(data, 0) * 1000;
+			fields.mtimeMs = readUInt32LE(data, 0) * 1000;
 			break;
 	}
 }
@@ -464,8 +458,8 @@ function parseLzhHeader(bytes: Uint8Array, offset: number, options: FormatReadOp
 	if (level > 2) throw new ArchiveError(`Unsupported LZH header level ${level}`);
 	const method = String.fromCharCode(...bytes.subarray(offset + 2, offset + 7));
 	if (!LHA_METHOD_PATTERN.test(method)) throw new ArchiveError(`Invalid LZH compression method '${method}'`);
-	let packedSize = u32(bytes, offset + 7);
-	let size = u32(bytes, offset + 11);
+	let packedSize = readUInt32LE(bytes, offset + 7);
+	let size = readUInt32LE(bytes, offset + 11);
 	let crc = 0;
 	let legacyFilename: string | undefined;
 	let mtimeMs: number | undefined;
@@ -486,22 +480,22 @@ function parseLzhHeader(bytes: Uint8Array, offset: number, options: FormatReadOp
 		if (22 + nameLength + 2 > headerLength + 2) throw new ArchiveError("Invalid LZH filename length");
 		assertArchivePathBytes(nameLength, "member path", options.limits.maxPathBytes);
 		legacyFilename = decodeLegacy(bytes.subarray(offset + 22, offset + 22 + nameLength));
-		crc = u16(bytes, offset + 22 + nameLength);
-		mtimeMs = dosTimeToMs(u32(bytes, offset + 15));
+		crc = readUInt16LE(bytes, offset + 22 + nameLength);
+		mtimeMs = dosTimeToMs(readUInt32LE(bytes, offset + 15));
 		if (level === 0) {
 			const extendedStart = offset + 24 + nameLength;
 			if (baseEnd - extendedStart >= 12) {
 				const extended = bytes.subarray(extendedStart, baseEnd);
 				if ((extended[0] === 0x55 || extended[0] === 0x4b) && extended[1] === 0) {
 					osId = extended[0]!;
-					fields.mtimeMs = u32(extended, 2) * 1000;
-					fields.mode = u16(extended, extended.byteLength - 6);
+					fields.mtimeMs = readUInt32LE(extended, 2) * 1000;
+					fields.mode = readUInt16LE(extended, extended.byteLength - 6);
 				}
 			}
 			dataStart = baseEnd;
 		} else {
 			osId = bytes[offset + 24 + nameLength]!;
-			let extensionSize = u16(bytes, baseEnd - 2);
+			let extensionSize = readUInt16LE(bytes, baseEnd - 2);
 			let cursor = baseEnd;
 			let totalExtensionSize = 0;
 			let extensionCount = 0;
@@ -519,7 +513,7 @@ function parseLzhHeader(bytes: Uint8Array, offset: number, options: FormatReadOp
 				}
 				processExtendedHeader(type, data, cursor + 1, fields);
 				const currentSize = extensionSize;
-				extensionSize = u16(bytes, dataEnd);
+				extensionSize = readUInt16LE(bytes, dataEnd);
 				cursor += currentSize;
 			}
 			dataStart = baseEnd + totalExtensionSize;
@@ -527,17 +521,17 @@ function parseLzhHeader(bytes: Uint8Array, offset: number, options: FormatReadOp
 			if (packedSize < 0) throw new ArchiveError("Invalid LZH level-1 packed size");
 		}
 	} else {
-		const headerLength = u16(bytes, offset);
+		const headerLength = readUInt16LE(bytes, offset);
 		if (headerLength < 26) throw new ArchiveError("Invalid LZH level-2 header size");
 		const headerEnd = offset + headerLength;
 		assertRange(bytes, offset, headerEnd, "header");
-		crc = u16(bytes, offset + 21);
+		crc = readUInt16LE(bytes, offset + 21);
 		osId = bytes[offset + 23]!;
-		mtimeMs = u32(bytes, offset + 15) * 1000;
+		mtimeMs = readUInt32LE(bytes, offset + 15) * 1000;
 		let cursor = offset + 24;
 		let extensionCount = 0;
 		while (cursor + 2 <= headerEnd) {
-			const extensionSize = u16(bytes, cursor);
+			const extensionSize = readUInt16LE(bytes, cursor);
 			if (extensionSize === 0) {
 				cursor += 2;
 				break;

package/src/ar/sevenzip/decode.ts

@@ -1,5 +1,6 @@
 import { crc32 } from "../checksums";
 import { lzma2Decompress, lzmaDecompress } from "../codecs/lzma";
+import { deltaDecode, x86Decode } from "../codecs/xz";
 import { ArchiveError } from "../error";
 import type { ArchiveLimits } from "../limits";
 import { assertInMemorySize } from "../limits";
@@ -81,62 +82,6 @@ function read32LE(bytes: Uint8Array, offset: number): number {
 	return (bytes[offset]! | (bytes[offset + 1]! << 8) | (bytes[offset + 2]! << 16) | (bytes[offset + 3]! << 24)) >>> 0;
 }
 
-function deltaDecode(bytes: Uint8Array, distance: number): void {
-	const history = new Uint8Array(256);
-	let position = 0;
-	for (let index = 0; index < bytes.byteLength; index++) {
-		const value = (bytes[index]! + history[(distance + position) & 0xff]!) & 0xff;
-		history[position] = value;
-		bytes[index] = value;
-		position = (position - 1) & 0xff;
-	}
-}
-
-function x86Decode(bytes: Uint8Array, startOffset: number): void {
-	const maskToBitNumber = [0, 1, 2, 2, 3] as const;
-	let previousMask = 0;
-	let previousPosition = 0xfffffffb;
-	if (bytes.byteLength < 5) return;
-	let position = 0;
-	const limit = bytes.byteLength - 5;
-	while (position <= limit) {
-		let byte = bytes[position]!;
-		if (byte !== 0xe8 && byte !== 0xe9) {
-			position++;
-			continue;
-		}
-		const absolutePosition = (startOffset + position) >>> 0;
-		const offset = (absolutePosition - previousPosition) >>> 0;
-		previousPosition = absolutePosition;
-		if (offset > 5) previousMask = 0;
-		else for (let index = 0; index < offset; index++) previousMask = ((previousMask & 0x77) << 1) >>> 0;
-		byte = bytes[position + 4]!;
-		if ((byte === 0 || byte === 0xff) && previousMask >>> 1 <= 4 && previousMask >>> 1 !== 3) {
-			let source = read32LE(bytes, position + 1);
-			let destination = 0;
-			for (;;) {
-				destination = (source - absolutePosition - 5) >>> 0;
-				if (previousMask === 0) break;
-				const bitIndex = maskToBitNumber[previousMask >>> 1]! * 8;
-				const testByte = (destination >>> (24 - bitIndex)) & 0xff;
-				if (testByte !== 0 && testByte !== 0xff) break;
-				const lowMask = bitIndex === 0 ? 0xffffffff : 2 ** (32 - bitIndex) - 1;
-				source = (destination ^ lowMask) >>> 0;
-			}
-			bytes[position + 4] = ~(((destination >>> 24) & 1) - 1) & 0xff;
-			bytes[position + 3] = destination >>> 16;
-			bytes[position + 2] = destination >>> 8;
-			bytes[position + 1] = destination;
-			position += 5;
-			previousMask = 0;
-		} else {
-			position++;
-			previousMask |= 1;
-			if (byte === 0 || byte === 0xff) previousMask |= 0x10;
-		}
-	}
-}
-
 /** Shared lazy decoder/cache for a single 7z folder (solid block). */
 export class SevenZipFolderSource {
 	readonly #source: ByteSource;

package/src/ar/tar.ts

@@ -1,5 +1,5 @@
 import * as path from "node:path";
-import { bytesMatchAscii } from "./bytes";
+import { bytesMatchAscii, indexOfAscii } from "./bytes";
 import { resolveArchiveLinkPath, upsertArchiveEntry } from "./entries";
 import { ArchiveError } from "./error";
 import {
@@ -419,13 +419,6 @@ function paxDeclaresSparse(
 	return paxAttribute(globalPax, localPax, PAX_SPARSE_MARKER) === "1";
 }
 
-function indexOfAscii(bytes: Uint8Array, value: string, start: number): number {
-	for (let offset = start; offset <= bytes.byteLength - value.length; offset++) {
-		if (bytesMatchAscii(bytes, offset, value)) return offset;
-	}
-	return -1;
-}
-
 function normalizeOldGnuName(value: string, field: string, limits: ArchiveLimits): string {
 	const portable = value.replace(/\\/g, "/");
 	if (path.posix.isAbsolute(portable)) throw new ArchiveError(`Invalid old-GNU ${field}`);

package/src/async.ts

@@ -29,6 +29,19 @@ export async function sleepLong(delayMs: number, signal?: AbortSignal): Promise<
 	}
 }
 
+/**
+ * Wait for a wall-clock deadline, including time spent suspended. Some platforms
+ * exclude suspend from relative timers, so recheck at least once per second.
+ */
+export async function sleepUntil(deadlineMs: number, signal?: AbortSignal): Promise<void> {
+	while (true) {
+		signal?.throwIfAborted();
+		const remaining = deadlineMs - Date.now();
+		if (!(remaining > 0)) return;
+		await scheduler.wait(Math.min(remaining, 1_000), { signal });
+	}
+}
+
 /**
  * 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/bytes.ts

@@ -0,0 +1,14 @@
+/**
+ * Narrow `bytes` to a view over its own whole `ArrayBuffer`, which is what
+ * `crypto.subtle.{digest,sign,importKey,encrypt,decrypt}` require under the
+ * strict TS DOM typings. Returns `bytes` itself when it already is one,
+ * otherwise a copy.
+ */
+export function asStrictBytes(bytes: Uint8Array): Uint8Array<ArrayBuffer> {
+	if (bytes.buffer instanceof ArrayBuffer && bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength) {
+		return bytes as Uint8Array<ArrayBuffer>;
+	}
+	const copy = new Uint8Array(bytes.byteLength);
+	copy.set(bytes);
+	return copy;
+}

package/src/color.ts

@@ -311,6 +311,12 @@ function oklabToLinearRgb(L: number, a: number, b: number): { r: number; g: numb
 	};
 }
 
+/** Convert a hex color to OKLab. */
+function hexToOklab(hex: string): { L: number; a: number; b: number } {
+	const rgb = hexToRgb(hex);
+	return linearRgbToOklab(linearizeChannel(rgb.r), linearizeChannel(rgb.g), linearizeChannel(rgb.b));
+}
+
 /**
  * Convert a hex color to OKLCH (perceptual lightness/chroma/hue).
  *
@@ -318,14 +324,20 @@ function oklabToLinearRgb(L: number, a: number, b: number): { r: number; g: numb
  * hues, so carrying them between colors preserves the palette's "weight".
  */
 export function hexToOklch(hex: string): OKLCH {
-	const rgb = hexToRgb(hex);
-	const lab = linearRgbToOklab(linearizeChannel(rgb.r), linearizeChannel(rgb.g), linearizeChannel(rgb.b));
+	const lab = hexToOklab(hex);
 	const c = Math.hypot(lab.a, lab.b);
 	let h = (Math.atan2(lab.b, lab.a) * 180) / Math.PI;
 	if (h < 0) h += 360;
 	return { l: lab.L, c, h };
 }
 
+/** Perceptual distance between two hex colors: Euclidean OKLab, 0 when identical, 1 from black to white. */
+export function oklabDistance(a: string, b: string): number {
+	const x = hexToOklab(a);
+	const y = hexToOklab(b);
+	return Math.hypot(x.L - y.L, x.a - y.a, x.b - y.b);
+}
+
 /**
  * Max OKLab saturation (C/L) that stays inside sRGB for the hue direction
  * `(a, b)`, via Björn Ottosson's polynomial fit plus one Halley refinement.

package/src/env.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 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 { getActiveProfile, getAgentDir, getConfigRootDir, getProjectDir, refreshDirsFromEnv } from "./dirs";
 import { isBunTestRuntime } from "./test-runtime";
 
 export * from "./test-runtime";
@@ -278,11 +278,55 @@ export function parseEnvFile(filePath: string): Record<string, string> {
 	return result;
 }
 
+// Read-only compatibility with the old OMP agent directory. Off by default:
+// external OMP configuration must be explicitly imported. Set
+// ZETA_OMP_COMPAT=1 in the shell or a Zeta dotenv file to enable both the
+// legacy dotenv fallback and the models.yml/agent.db overlay.
+export function isOmpCompatEnabled(env: Record<string, string | undefined> = Bun.env): boolean {
+	const value = env.ZETA_OMP_COMPAT;
+	if (!value) return false;
+	const normalized = value.toLowerCase();
+	return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}
+
+function loadLegacyOmpEnv(): Record<string, string> {
+	const home = os.homedir();
+	const project = getProjectDir();
+	const profile = getActiveProfile();
+	const files = [
+		{ file: path.join(home, ".omp", ".env"), project: false },
+		{ file: path.join(home, ".omp", "agent", ".env"), project: false },
+		...(profile ? [{ file: path.join(home, ".omp", "profiles", profile, "agent", ".env"), project: false }] : []),
+		{ file: path.join(project, ".omp", ".env"), project: true },
+		{ file: path.join(project, ".omp", "agent", ".env"), project: true },
+	];
+	const merged: Record<string, string> = {};
+	const seen = new Set<string>();
+	for (const { file, project: projectFile } of files) {
+		if (seen.has(file)) continue;
+		seen.add(file);
+		for (const [key, value] of Object.entries(parseEnvFile(file))) {
+			merged[key] = value;
+			if (projectFile) projectEnvNamesLoadedByOmp.add(key);
+		}
+	}
+	return merged;
+}
+
 // Eagerly parse the user's $HOME/.env and the current project's .env (from cwd)
 const homeEnv = parseEnvFile(path.join(os.homedir(), ".env"));
 const piEnv = parseEnvFile(path.join(getConfigRootDir(), ".env"));
 const agentEnv = parseEnvFile(path.join(getAgentDir(), ".env"));
 const projectEnv = parseEnvFile(path.join(getProjectDir(), ".env"));
+// The switch itself may come from the shell or any Zeta dotenv file. Check the
+// same precedence before touching legacy OMP files; do not read them by default.
+const ompCompatValue =
+	Bun.env.ZETA_OMP_COMPAT ??
+	projectEnv.ZETA_OMP_COMPAT ??
+	agentEnv.ZETA_OMP_COMPAT ??
+	piEnv.ZETA_OMP_COMPAT ??
+	homeEnv.ZETA_OMP_COMPAT;
+const legacyOmpEnv = isOmpCompatEnabled({ ZETA_OMP_COMPAT: ompCompatValue }) ? loadLegacyOmpEnv() : {};
 
 for (const key of Object.keys(Bun.env)) {
 	const value = Bun.env[key];
@@ -291,7 +335,7 @@ for (const key of Object.keys(Bun.env)) {
 	}
 }
 
-for (const file of [projectEnv, agentEnv, piEnv, homeEnv]) {
+for (const file of [projectEnv, agentEnv, piEnv, homeEnv, legacyOmpEnv]) {
 	for (const key in file) {
 		if (!isMacosMallocStackLoggingEnvName(key) && !Bun.env[key]) {
 			Bun.env[key] = file[key];

package/src/file-lock.ts

@@ -45,6 +45,15 @@ export function tryAcquireFileLock(filePath: string): FileLockHandle | null {
 	return tryAcquireLock(getLockPath(filePath));
 }
 
+/**
+ * Whether any holder, including this process, owns the lease, observed without
+ * taking it, so a concurrent `tryAcquireFileLock` never meets the probe.
+ * Throws when the lock cannot be probed.
+ */
+export function isFileLockHeld(filePath: string): boolean {
+	return NativeFileLock.isHeld(getLockPath(filePath));
+}
+
 /** Acquire an exclusive lease; callers must release it when their operation ends. */
 export async function acquireFileLock(filePath: string, options: FileLockOptions = {}): Promise<FileLockHandle> {
 	const opts = { ...DEFAULT_OPTIONS, ...options };

package/src/held-file.ts

@@ -0,0 +1,22 @@
+/**
+ * Refuses overwriting a file this process holds open with locks (issue #15586).
+ *
+ * Writing over a live `agent.db` or its `-shm` destroys the store (a truncated
+ * `-shm` also faults the connection's memory map), so tools that write
+ * agent-chosen paths check here first.
+ */
+import { heldFileKind } from "@linxiraos/pi-natives/sqlite-locks";
+
+/**
+ * Throws an `EBUSY` error when `filePath` is a file this process holds open with
+ * locks: a SQLite database or `-shm` of a live connection. Always passes outside Linux.
+ */
+export function assertNotHeldOpen(filePath: string): void {
+	const kind = heldFileKind(filePath);
+	if (!kind) return;
+	const holder = kind === "locked" ? "a file lock" : "a SQLite connection";
+	throw Object.assign(
+		new Error(`EBUSY: '${filePath}' is held open by ${holder} in this process; overwriting it would destroy it`),
+		{ code: "EBUSY", path: filePath },
+	);
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 export { once, untilAborted } from "./abortable";
 export * from "./async";
 export * from "./binary";
+export * from "./bytes";
 export * from "./color";
 export * from "./dirs";
 export * from "./env";
@@ -23,6 +24,7 @@ export * from "./path";
 export * from "./path-tree";
 export * from "./ports";
 export * from "./peek-file";
+export * from "./pid";
 export * as postmortem from "./postmortem";
 export * from "./process-name";
 export * as procmgr from "./procmgr";

package/src/logger.ts

@@ -22,6 +22,7 @@ import * as path from "node:path";
 import { isPromise } from "node:util/types";
 import { getLogsDir, localDay } from "./dirs";
 import { RotatingFileSink } from "./logger/rotating-file";
+import { isPidAlive } from "./pid";
 import { setStderrRedirectTarget } from "./stderr-guard";
 import { drainModuleLoadEvents } from "./timing-buffer";
 /** Severity names accepted by the centralized logger. */
@@ -81,15 +82,6 @@ const LEGACY_AUDIT_PATTERN = /^\.[0-9a-f]{8,}-audit\.json$/;
 const RETAINED_STALE_LOGS_PER_PROCESS_DAY = 1;
 const RETAINED_STALE_LOG_DAYS = 5;
 
-function processIsRunning(pid: number): boolean {
-	try {
-		process.kill(pid, 0);
-		return true;
-	} catch (error) {
-		return !(error instanceof Error && "code" in error && (error.code === "ESRCH" || error.code === "EINVAL"));
-	}
-}
-
 /**
  * Retain one newest completed-process log per process/day within the current
  * and previous four local calendar days, remove completed-process audit files
@@ -133,7 +125,7 @@ function pruneStaleProcessLogs(dir: string): void {
 		const logMatch = PROCESS_LOG_PATTERN.exec(entry.name);
 		const auditMatch = PROCESS_AUDIT_PATTERN.exec(entry.name);
 		const pidText = logMatch?.[2] ?? auditMatch?.[1];
-		if (!pidText || processIsRunning(Number(pidText))) continue;
+		if (!pidText || isPidAlive(Number(pidText))) continue;
 
 		if (auditMatch) {
 			removeBestEffort(entryPath);

package/src/pid.ts

@@ -0,0 +1,16 @@
+/**
+ * Signal-0 liveness probe: true unless the OS reports the pid as gone
+ * (`ESRCH`) or invalid (`EINVAL`). Any other failure, notably `EPERM` (alive
+ * but owned by another user), reads as alive, so callers never reclaim a
+ * resource a live process may still hold. Unlike `procmgr.isPidRunning`, this
+ * does not consult the process table's run state.
+ */
+export function isPidAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException | undefined)?.code;
+		return code !== "ESRCH" && code !== "EINVAL";
+	}
+}

package/src/postmortem.ts

@@ -10,6 +10,7 @@ import * as fs from "node:fs";
 import { APP_NAME, CLI_BIN_NAME } from "./dirs";
 import * as logger from "./logger";
 import { restoreTerminalStderr } from "./stderr-guard";
+import { toError } from "./type-guards";
 
 // Cleanup reasons, in order of priority/meaning.
 export enum Reason {
@@ -276,7 +277,7 @@ function runCleanup(reason: Reason, keepAlive = false): Promise<void> {
 	const cleanupSettled = Promise.allSettled(promises).then(async results => {
 		for (const result of results) {
 			if (result.status === "rejected") {
-				const err = result.reason instanceof Error ? result.reason : new Error(String(result.reason));
+				const err = toError(result.reason);
 				logger.error("Cleanup callback failed", { err, stack: err.stack });
 			}
 		}
@@ -307,9 +308,7 @@ function runCleanup(reason: Reason, keepAlive = false): Promise<void> {
 	return cleanupPromise;
 }
 
-// Register signal and error event handlers to trigger cleanup before exit.
-// Main thread: full signal handling (SIGINT, SIGTERM, SIGHUP) + exceptions + exit
-// Worker thread: exit only (workers use self.addEventListener for exceptions)
+// CLI-owned main threads handle signals and fatal errors; workers handle exit only.
 let inspectorOpened = false;
 
 /** Origin of an EPIPE raised by a process communication channel. */
@@ -558,13 +557,47 @@ export function isExpectedCleanupError(reason: unknown): boolean {
 /** Interceptors consulted by the global `unhandledRejection` handler before the fatal path. */
 const rejectionInterceptors = new Set<(reason: unknown) => boolean>();
 
+function interceptRejection(reason: unknown): boolean {
+	for (const interceptor of rejectionInterceptors) {
+		try {
+			if (interceptor(reason)) return true;
+		} catch (interceptorErr) {
+			logger.warn("Unhandled-rejection interceptor threw; continuing with fatal path", { err: interceptorErr });
+		}
+	}
+	return false;
+}
+
+/**
+ * Without the CLI's handlers (SDK embedding), interceptors still need a listener. It exists only while
+ * interceptors do, and rethrows what none consumes unless the host listens too, keeping Bun's default.
+ */
+let embeddedRejectionListener: ((reason: unknown) => void) | undefined;
+
 /**
  * Register an interceptor consulted before an unhandled rejection tears the
  * process down. A consuming interceptor owns reporting and keeps the process alive.
  */
 export function interceptUnhandledRejections(interceptor: (reason: unknown) => boolean): () => void {
 	rejectionInterceptors.add(interceptor);
-	return () => rejectionInterceptors.delete(interceptor);
+	if (!processHandlersInstalled && Bun.isMainThread && !embeddedRejectionListener) {
+		const listener = (reason: unknown) => {
+			if (interceptRejection(reason) || process.listenerCount("unhandledRejection") > 1) return;
+			throw reason;
+		};
+		embeddedRejectionListener = listener;
+		process.on("unhandledRejection", listener);
+	}
+	return () => {
+		rejectionInterceptors.delete(interceptor);
+		if (rejectionInterceptors.size === 0) removeEmbeddedRejectionListener();
+	};
+}
+
+function removeEmbeddedRejectionListener(): void {
+	if (!embeddedRejectionListener) return;
+	process.off("unhandledRejection", embeddedRejectionListener);
+	embeddedRejectionListener = undefined;
 }
 
 /**
@@ -676,7 +709,7 @@ function handleWorkerSendEpipe(err: Error): boolean {
  * Reports a caught top-level failure after terminal owners restore their display, then exits.
  */
 export async function fatal(error: unknown): Promise<never> {
-	const err = error instanceof Error ? error : new Error(String(error));
+	const err = toError(error);
 	const report = `${Bun.inspect(error, { colors: process.stderr.isTTY === true })}\n`;
 	if (!Bun.isMainThread) {
 		process.stderr.write(`${report}${formatFatalRecoveryHints(fatalRecoveryHintProviders)}`);
@@ -685,7 +718,22 @@ export async function fatal(error: unknown): Promise<never> {
 	return exitAfterFatal(report, "Fatal error", err, Reason.UNHANDLED_REJECTION);
 }
 
-if (Bun.isMainThread) {
+// Exit-time cleanup is safe in any host: it neither delays nor triggers an exit. Signal and fatal
+// handlers change the process lifecycle, so only {@link installProcessHandlers} adds them.
+process.on("exit", () => {
+	void runCleanup(Reason.EXIT); // fire and forget (exit imminent)
+});
+
+let processHandlersInstalled = false;
+
+/** Installs OMP's process-wide signal and fatal handlers for a CLI-owned process. */
+export function installProcessHandlers(): void {
+	if (processHandlersInstalled) return;
+	processHandlersInstalled = true;
+	removeEmbeddedRejectionListener();
+	// Workers report failures through their own error listeners to the parent.
+	if (!Bun.isMainThread) return;
+
 	process
 		.on("SIGINT", async () => {
 			await runCleanup(Reason.SIGINT);
@@ -706,7 +754,7 @@ if (Bun.isMainThread) {
 				logger.warn("Ignoring expected cleanup exception", { err: thrown });
 				return;
 			}
-			const err = thrown instanceof Error ? thrown : new Error(String(thrown));
+			const err = toError(thrown);
 			// A worker IPC `send()` race can surface through either global error event;
 			// contain it in both. Stdout write disconnects are attributed to stdout by
 			// registerStdioDisconnectHandling's `error` listener, not classified here.
@@ -739,21 +787,13 @@ if (Bun.isMainThread) {
 			);
 		})
 		.on("unhandledRejection", async reason => {
-			const err = reason instanceof Error ? reason : new Error(String(reason));
+			const err = toError(reason);
 			if (handleWorkerSendEpipe(err)) return;
 			if (isExpectedCleanupError(reason)) {
 				logger.warn("Ignoring expected cleanup rejection", { err });
 				return;
 			}
-			for (const interceptor of rejectionInterceptors) {
-				try {
-					if (interceptor(reason)) return;
-				} catch (interceptorErr) {
-					logger.warn("Unhandled-rejection interceptor threw; continuing with fatal path", {
-						err: interceptorErr,
-					});
-				}
-			}
+			if (interceptRejection(reason)) return;
 			await exitAfterFatal(
 				formatFatalError("Unhandled Rejection", err),
 				"Unhandled rejection",
@@ -761,9 +801,6 @@ if (Bun.isMainThread) {
 				Reason.UNHANDLED_REJECTION,
 			);
 		})
-		.on("exit", async () => {
-			void runCleanup(Reason.EXIT); // fire and forget (exit imminent)
-		})
 		.on("SIGTERM", async () => {
 			// A stopped session otherwise leaves its last frame above the shell prompt,
 			// which reads as a crash. A repeated SIGTERM joins the same cleanup and the
@@ -777,14 +814,6 @@ if (Bun.isMainThread) {
 			await runCleanup(Reason.SIGHUP);
 			exitProcess(129); // 128 + SIGHUP (1)
 		});
-} else {
-	// Worker thread: only register exit handler for cleanup.
-	// DO NOT register uncaughtException/unhandledRejection handlers here -
-	// they would swallow errors before the worker's own handlers (self.addEventListener)
-	// can report failures back to the parent thread.
-	process.on("exit", () => {
-		void runCleanup(Reason.EXIT);
-	});
 }
 
 /** Controls when a registered cleanup callback participates in cleanup passes. */
@@ -811,8 +840,7 @@ export interface CleanupRegistrationOptions {
 }
 
 /**
- * Registers a cleanup callback for shutdown, signals, fatal errors, and
- * repeatable manual cleanup passes.
+ * Registers a cleanup callback for manual passes and, when installed, process shutdown.
  *
  * Registrations persist across keep-alive {@link cleanup} passes and run at
  * most once per pass. Set `exitOnly` for resources the continuing process still
@@ -849,7 +877,7 @@ export function register(
 			const pending = invokeCleanup(registration, reason, keepAlive, cleanupPass);
 			if (!pending) return;
 			const tracked = pending.catch(error => {
-				const err = error instanceof Error ? error : new Error(String(error));
+				const err = toError(error);
 				logger.error("Cleanup callback failed", { err, id, stack: err.stack });
 			});
 			// Join the active pass so cleanup()/signal exits await it; after a
@@ -859,7 +887,7 @@ export function register(
 				activePassDeadline?.extend(tracked, registration.deadlineMs, registration.waitMessage);
 			}
 		} catch (error) {
-			const err = error instanceof Error ? error : new Error(String(error));
+			const err = toError(error);
 			logger.error("Cleanup callback failed", { err, id, stack: err.stack });
 		}
 	};