@oh-my-pi/pi-utils 18.15.0 → 18.17.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/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/dirs.ts

@@ -656,6 +656,15 @@ export function getReportsDir(): string {
 	return dirs.rootSubdir("reports", "state");
 }
 
+/**
+ * Get the self-update state directory (~/.omp/update): the background
+ * auto-update's status file and worker log, and the lock that keeps two
+ * installs (`omp update`, auto-update) from running at once.
+ */
+export function getUpdateStateDir(): string {
+	return dirs.rootSubdir("update", "state");
+}
+
 /**
  * Get the logs directory (~/.omp/logs). `bun test` processes get
  * `<tmpdir>/omp-test-logs-<uid>` instead, so suites never write into the

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 "@oh-my-pi/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";
@@ -22,6 +23,7 @@ export * from "./mime";
 export * from "./path";
 export * from "./path-tree";
 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,8 +22,10 @@ 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";
+import { isRecord } from "./type-guards";
 /** Severity names accepted by the centralized logger. */
 export type LogLevel = "error" | "warn" | "info" | "debug";
 
@@ -38,8 +40,103 @@ export interface LogEvent {
 /** Receives each structured log event after the local transport path runs. */
 export type LogSink = (event: LogEvent) => void;
 
+/**
+ * Destination that takes this thread's log records in place of its own
+ * transports and sinks (a worker thread routing records to the main thread's
+ * logger); see {@link setLogForwarder}.
+ */
+export interface LogForwarder {
+	/**
+	 * Take one record. Its context is already merged over the enclosing
+	 * {@link withContext} fields and reduced to plain JSON data, so it survives
+	 * a structured clone; `timestamp` is when the record was logged.
+	 */
+	emit(event: LogEvent): void;
+	/** Write every record emitted so far on the receiving side; backs {@link flush}. */
+	flush(): void;
+}
+
 const logSinks = new Set<LogSink>();
 
+/** Set by {@link setLogForwarder}: records go there instead of to local transports and sinks. */
+let logForwarder: LogForwarder | undefined;
+
+/**
+ * Route every later record logged on this thread to `forwarder` instead of the
+ * local transports and sinks, which then stay unused (no log file is opened);
+ * {@link flush} asks the forwarder to flush. `undefined` restores local logging.
+ * For worker threads, whose main thread owns the process log file.
+ */
+export function setLogForwarder(forwarder: LogForwarder | undefined): void {
+	logForwarder = forwarder;
+}
+
+/**
+ * Log a record another thread forwarded (see {@link setLogForwarder}): written
+ * to the local transports with its own timestamp, then handed to the sinks. Its
+ * context is taken as is; the caller's enclosing {@link withContext} is not
+ * merged in. On a thread that forwards itself, the record is forwarded on.
+ */
+export function emitForeign(event: LogEvent): void {
+	const forwarder = logForwarder;
+	if (forwarder) {
+		try {
+			forwarder.emit(event);
+		} catch {
+			// Forwarding is as best-effort as local writes.
+		}
+		return;
+	}
+	try {
+		emitLocally(event.level, event.message, event.context, event.timestamp);
+	} catch {
+		// Silently ignore logging failures
+	}
+	dispatchToSinks(event);
+}
+
+/** Forward one record logged on this thread; never throws. */
+function forwardRecord(
+	forwarder: LogForwarder,
+	level: LogLevel,
+	message: string,
+	context: Record<string, unknown> | undefined,
+): void {
+	try {
+		forwarder.emit({ level, message, context: forwardableContext(context), timestamp: new Date() });
+	} catch {
+		// Forwarding is as best-effort as local writes.
+	}
+}
+
+/**
+ * The call's context merged over the enclosing {@link withContext} fields (call
+ * fields win, as for sinks), as plain JSON data: errors become
+ * `{ name, message, stack, … }` exactly as in the log file. A context that
+ * cannot be serialized (a cycle, a bigint) is dropped from the record.
+ */
+function forwardableContext(context: Record<string, unknown> | undefined): Record<string, unknown> | undefined {
+	// An Error passed as the context carries its fields as non-enumerable properties.
+	let merged = context instanceof Error ? errorToRecord(context) : context;
+	const scoped = logContextStorage.getStore();
+	if (scoped) {
+		try {
+			merged = { ...scoped, ...merged };
+		} catch {
+			// A throwing getter must not turn a log call into a failure; keep the call's own fields.
+		}
+	}
+	if (merged === undefined) return undefined;
+	try {
+		const parsed: unknown = JSON.parse(
+			mayContainError(merged) ? JSON.stringify(merged, jsonReplacer) : JSON.stringify(merged),
+		);
+		return isRecord(parsed) ? parsed : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 /** Register an out-of-band log sink and return a disposer. */
 export function registerLogSink(sink: LogSink): () => void {
 	logSinks.add(sink);
@@ -61,7 +158,11 @@ function emitToSinks(level: LogLevel, message: string, context: Record<string, u
 			// 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() };
+	dispatchToSinks({ level, message, context: merged, timestamp: new Date() });
+}
+
+function dispatchToSinks(event: LogEvent): void {
+	if (logSinks.size === 0) return;
 	for (const sink of logSinks) {
 		try {
 			sink(event);
@@ -81,15 +182,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 +225,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);
@@ -207,19 +299,21 @@ function ensureDir(dir: string): string {
  * forensic logs showed only an opaque empty object.
  */
 function jsonReplacer(_key: string, value: unknown): unknown {
-	if (value instanceof Error) {
-		const out: Record<string, unknown> = {
-			name: value.name,
-			message: value.message,
-			stack: value.stack,
-		};
-		// Preserve `.cause` and any custom enumerable fields the caller attached.
-		const errAsRecord = value as unknown as Record<string, unknown>;
-		for (const k in errAsRecord) out[k] = errAsRecord[k];
-		if (value.cause !== undefined) out.cause = value.cause;
-		return out;
-	}
-	return value;
+	return value instanceof Error ? errorToRecord(value) : value;
+}
+
+/** An Error's fields as a plain object: name, message, stack, enumerable extras, and `cause`. */
+function errorToRecord(value: Error): Record<string, unknown> {
+	const out: Record<string, unknown> = {
+		name: value.name,
+		message: value.message,
+		stack: value.stack,
+	};
+	// Preserve `.cause` and any custom enumerable fields the caller attached.
+	const errAsRecord = value as unknown as Record<string, unknown>;
+	for (const k in errAsRecord) out[k] = errAsRecord[k];
+	if (value.cause !== undefined) out.cause = value.cause;
+	return out;
 }
 
 // Values visited by the Error pre-scan before falling back to the replacer.
@@ -286,12 +380,16 @@ export function withoutContext<T>(fn: () => T): T {
 	return logContextStorage.exit(fn);
 }
 
-/** Serialize one log record: timestamp, level, pid, message, then context fields. */
+/**
+ * Serialize one log record: timestamp, level, pid, message, then the `scoped`
+ * ({@link withContext}) fields and the context fields.
+ */
 function formatLogRecord(
 	level: LogLevel,
 	message: string,
 	context: Record<string, unknown> | undefined,
 	timestamp: string,
+	scoped: Readonly<Record<string, unknown>> | undefined,
 ): string {
 	const metadata =
 		!FORMAT_TOKEN_PATTERN.test(message) && context !== null && typeof context === "object" ? context : undefined;
@@ -301,7 +399,6 @@ 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];
@@ -378,7 +475,8 @@ function resolveFileLevelRank(): number {
  */
 export function flush(): void {
 	try {
-		activeTransports?.file?.flush();
+		if (logForwarder) logForwarder.flush();
+		else activeTransports?.file?.flush();
 	} catch {
 		// Flushing diagnostics must never mask the caller's own work or failure.
 	}
@@ -413,13 +511,25 @@ function getLocalTransports(): LocalTransports {
 	return activeTransports;
 }
 
-function emitLocally(level: LogLevel, message: string, context: Record<string, unknown> | undefined): void {
+/**
+ * Write one record to the local transports. A `foreignTimestamp` marks a record
+ * another thread logged ({@link emitForeign}): it keeps that time and gets no
+ * {@link withContext} fields of this call stack, while the file still rotates by
+ * the current day so a late record cannot reopen an earlier day's file.
+ */
+function emitLocally(
+	level: LogLevel,
+	message: string,
+	context: Record<string, unknown> | undefined,
+	foreignTimestamp?: Date,
+): void {
 	const transports = getLocalTransports();
 	const rank = LOG_LEVEL_RANK[level];
 	const file = rank <= transports.fileLevelRank ? transports.file : undefined;
 	if (!file && !transports.console) return;
 	const now = new Date();
-	const line = formatLogRecord(level, message, context, formatLocalTimestamp(now));
+	const scoped = foreignTimestamp ? undefined : logContextStorage.getStore();
+	const line = formatLogRecord(level, message, context, formatLocalTimestamp(foreignTimestamp ?? now), scoped);
 	file?.write(line, rank <= IMMEDIATE_FLUSH_RANK || exiting, localDay(now));
 	if (transports.console) fs.writeSync(1, `${line}${os.EOL}`);
 }
@@ -446,6 +556,7 @@ export function setTransports(opts: { console?: boolean; file?: boolean | string
  * @param context - The context to log.
  */
 export function error(message: string, context?: Record<string, unknown>): void {
+	if (logForwarder) return forwardRecord(logForwarder, "error", message, context);
 	try {
 		emitLocally("error", message, context);
 	} catch {
@@ -460,6 +571,7 @@ export function error(message: string, context?: Record<string, unknown>): void
  * @param context - The context to log.
  */
 export function warn(message: string, context?: Record<string, unknown>): void {
+	if (logForwarder) return forwardRecord(logForwarder, "warn", message, context);
 	try {
 		emitLocally("warn", message, context);
 	} catch {
@@ -474,6 +586,7 @@ export function warn(message: string, context?: Record<string, unknown>): void {
  * @param context - The context to log.
  */
 export function info(message: string, context?: Record<string, unknown>): void {
+	if (logForwarder) return forwardRecord(logForwarder, "info", message, context);
 	try {
 		emitLocally("info", message, context);
 	} catch {
@@ -488,6 +601,7 @@ export function info(message: string, context?: Record<string, unknown>): void {
  * @param context - The context to log.
  */
 export function debug(message: string, context?: Record<string, unknown>): void {
+	if (logForwarder) return forwardRecord(logForwarder, "debug", message, context);
 	try {
 		emitLocally("debug", message, context);
 	} catch {

package/src/path.ts

@@ -1,3 +1,4 @@
+import * as os from "node:os";
 import * as path from "node:path";
 
 const WINDOWS_DRIVE_PATH = /^([A-Za-z]):[\\/](.*)$/;
@@ -54,3 +55,16 @@ export function isFullyQualifiedPath(filePath: string, platform: NodeJS.Platform
 	}
 	return true;
 }
+
+/** Expands a leading `~` (`~`, `~/…`, `~\…`, `~name`) to `home`, the user's home directory by default. */
+export function expandTilde(filePath: string, home?: string): string {
+	const h = home ?? os.homedir();
+	if (filePath === "~") return h;
+	if (filePath.startsWith("~/") || filePath.startsWith("~\\")) {
+		return h + filePath.slice(1);
+	}
+	if (filePath.startsWith("~")) {
+		return path.join(h, filePath.slice(1));
+	}
+	return filePath;
+}

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";
+	}
+}