@linxiraos/pi-utils 1.4.6 → 1.4.9

package/src/ar/codecs/xz.ts

@@ -1,3 +1,4 @@
+import { readUInt32BE } from "../bytes";
 import { crc32, crc64 } from "../checksums";
 import { ArchiveError } from "../error";
 import { lzma2Decompress } from "./lzma";
@@ -16,10 +17,6 @@ function write32LE(bytes: Uint8Array, offset: number, value: number): void {
 	bytes[offset + 3] = value >>> 24;
 }
 
-function read32BE(bytes: Uint8Array, offset: number): number {
-	return ((bytes[offset]! << 24) | (bytes[offset + 1]! << 16) | (bytes[offset + 2]! << 8) | bytes[offset + 3]!) >>> 0;
-}
-
 function write32BE(bytes: Uint8Array, offset: number, value: number): void {
 	bytes[offset] = value >>> 24;
 	bytes[offset + 1] = (value >>> 16) & 0xff;
@@ -155,7 +152,8 @@ interface XzFilter {
 	properties: Uint8Array;
 }
 
-function deltaDecode(bytes: Uint8Array, distance: number): void {
+/** Undo the delta filter (shared by XZ and 7z) in place. */
+export function deltaDecode(bytes: Uint8Array, distance: number): void {
 	const history = new Uint8Array(256);
 	let position = 0;
 	for (let index = 0; index < bytes.byteLength; index++) {
@@ -166,7 +164,8 @@ function deltaDecode(bytes: Uint8Array, distance: number): void {
 	}
 }
 
-function x86Decode(bytes: Uint8Array, startOffset: number): void {
+/** Undo the x86 BCJ filter (shared by XZ and 7z) in place; `startOffset` is the stream position of `bytes[0]`. */
+export function x86Decode(bytes: Uint8Array, startOffset: number): void {
 	const maskToBitNumber = [0, 1, 2, 2, 3] as const;
 	let previousMask = 0;
 	let previousPosition = 0xfffffffb;
@@ -267,7 +266,7 @@ function sparcDecode(bytes: Uint8Array, startOffset: number): void {
 			)
 		)
 			continue;
-		const source = (read32BE(bytes, index) << 2) >>> 0;
+		const source = (readUInt32BE(bytes, index) << 2) >>> 0;
 		let destination = (source - startOffset - index) >>> 2;
 		destination = (((0 - ((destination >>> 22) & 1)) << 22) & 0x3fffffff) | (destination & 0x3fffff) | 0x40000000;
 		write32BE(bytes, index, destination >>> 0);
@@ -356,7 +355,7 @@ function riscvDecode(bytes: Uint8Array, startOffset: number): void {
 				index += 2;
 				continue;
 			}
-			const address = (read32BE(bytes, index + 4) - startOffset - index) >>> 0;
+			const address = (readUInt32BE(bytes, index + 4) - startOffset - index) >>> 0;
 			instruction2 = ((instruction >>> 12) | (address << 20)) >>> 0;
 			instruction = (0x17 | (register << 7) | ((address + 0x800) & 0xfffff000)) >>> 0;
 		}

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/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";
@@ -10,7 +11,6 @@ export * from "./file-lock";
 export * from "./format";
 export * from "./frontmatter";
 export * from "./fs-error";
-export * from "./fs-open";
 export * from "./incoming-json";
 export * from "./json";
 export * from "./json-parse";
@@ -24,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/rotating-file.ts

@@ -3,7 +3,6 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { localDay } from "../dirs";
-import { openCloexecSync } from "../fs-open";
 
 /** Write batching for {@link RotatingFileSink}. */
 export interface RotatingFileBatchOptions {
@@ -87,7 +86,7 @@ export class RotatingFileSink {
 
 	#openFd(filePath: string): void {
 		this.#closeFd();
-		this.#fd = openCloexecSync(filePath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_APPEND);
+		this.#fd = fs.openSync(filePath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_APPEND);
 		try {
 			this.#onRotate?.(filePath);
 		} catch {

package/src/logger.ts

@@ -7,11 +7,13 @@
  * transport so a process supervisor (pm2, journald, k8s) captures the logs.
  *
  * Each entry includes `process.pid` so concurrent zeta instances stay
- * traceable. The file is created on the first record written. Records are
- * batched — one write per second or per 64 KiB — while `warn`/`error` records
- * are written at once together with everything buffered before them; exit,
- * fatal, and signal paths flush the rest. `ZETA_LOG_LEVEL` optionally limits
- * the levels written to the file (default: all).
+ * traceable, and the fields of the enclosing {@link withContext} (a session's
+ * `sessionId`) so sessions sharing one process stay apart. The file is created
+ * on the first record written. Records are batched — one write per second or
+ * per 64 KiB — while `warn`/`error` records are written at once together with
+ * everything buffered before them; exit, fatal, and signal paths flush the
+ * rest. `ZETA_LOG_LEVEL` optionally limits the levels written to the file
+ * (default: all).
  */
 import { AsyncLocalStorage } from "node:async_hooks";
 import * as fs from "node:fs";
@@ -20,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. */
@@ -48,7 +51,18 @@ export function registerLogSink(sink: LogSink): () => void {
 
 function emitToSinks(level: LogLevel, message: string, context: Record<string, unknown> | undefined): void {
 	if (logSinks.size === 0) return;
-	const event: LogEvent = { level, message, context, timestamp: new Date() };
+	// The enclosing {@link withContext} fields reach sinks as they reach the file;
+	// call-site fields win, and a record outside any context keeps its own object.
+	const scoped = logContextStorage.getStore();
+	let merged = context;
+	if (scoped) {
+		try {
+			merged = { ...scoped, ...context };
+		} catch {
+			// A throwing getter must not turn a log call into a failure; sinks get the call's own fields.
+		}
+	}
+	const event: LogEvent = { level, message, context: merged, timestamp: new Date() };
 	for (const sink of logSinks) {
 		try {
 			sink(event);
@@ -68,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
@@ -120,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);
@@ -251,6 +256,28 @@ function formatLocalTimestamp(date: Date): string {
 
 const FORMAT_TOKEN_PATTERN = /%[scdjifoO%]/;
 
+const logContextStorage = new AsyncLocalStorage<Readonly<Record<string, unknown>>>();
+
+/**
+ * Run `fn` with `context`'s fields on every record logged while it runs,
+ * including from the promises, timers and callbacks it starts. A nested call
+ * replaces the enclosing context, as a subagent's session replaces its
+ * parent's; a field passed to the log call itself wins. Fields are read as each
+ * record is written, so a getter stays current.
+ */
+export function withContext<T>(context: Readonly<Record<string, unknown>>, fn: () => T): T {
+	return logContextStorage.run(context, fn);
+}
+
+/**
+ * Run `fn` outside any {@link withContext}: for process-wide work started on
+ * behalf of one caller, such as a shared server's read loop, whose later
+ * records belong to no single caller.
+ */
+export function withoutContext<T>(fn: () => T): T {
+	return logContextStorage.exit(fn);
+}
+
 /** Serialize one log record: timestamp, level, pid, message, then context fields. */
 function formatLogRecord(
 	level: LogLevel,
@@ -266,6 +293,12 @@ function formatLogRecord(
 		pid: process.pid,
 		message: metadata?.message ? `${message} ${metadata.message}` : message,
 	};
+	const scoped = logContextStorage.getStore();
+	if (scoped) {
+		for (const key of Object.keys(scoped)) {
+			if (key !== "level" && key !== "timestamp" && key !== "message") entry[key] = scoped[key];
+		}
+	}
 	if (metadata) {
 		for (const key of Object.keys(metadata)) {
 			if (key !== "level" && key !== "timestamp" && key !== "message") entry[key] = metadata[key];

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/ports.ts

@@ -3,8 +3,9 @@
  *
  * OMP installs on the same machine use 30141/30142/3847, and common developer
  * tools squat on 3000/8080/8787/3847. Zeta therefore owns a dedicated block:
- * three uncommon ports, at least two apart, so a side-by-side OMP install and
- * unrelated services cannot take the gateway or the stats dashboard away.
+ * uncommon ports, at least two apart, so a side-by-side OMP install and
+ * unrelated services cannot take the gateway, stats dashboard, or browser
+ * relay away.
  *
  * Every default in the repository derives from these constants. The standalone
  * Electron shell (`desktop/src/main.ts`, not a Bun workspace package) carries
@@ -13,3 +14,4 @@
 export const ZETA_WEB_PORT = 43141;
 export const ZETA_GATEWAY_PORT = 43143;
 export const ZETA_STATS_PORT = 43147;
+export const ZETA_BROWSER_RELAY_PORT = 43153;