@linxiraos/pi-utils 1.1.14 → 1.1.16

package/src/peek-file.ts

@@ -1,67 +1,20 @@
 /**
  * Read the first `maxBytes` of a file (offset 0) and pass that slice to `op`.
  *
- * Buffers are reused to avoid allocating on every peek: sync uses one growable
- * `Uint8Array`; async uses a small fixed pool of `Buffer`s with a bounded wait
- * queue, falling back to a fresh allocation when the pool and queue are saturated
- * or when `maxBytes` exceeds the pool slot size.
+ * Synchronous peeks reuse one growable `Uint8Array`; asynchronous peeks allocate
+ * their result window so callback-retained slices cannot be changed by a later read.
  */
 import * as fs from "node:fs";
 
-/** Async pool slot size; larger peeks allocate ad hoc. */
-const POOLED_BUFFER_SIZE = 512;
-const ASYNC_POOL_SIZE = 10;
-/** Cap waiter queue so heavy concurrency does not queue unbounded; overflow uses alloc. */
-const MAX_ASYNC_WAITERS = 4;
 const INITIAL_SYNC_BUFFER_SIZE = 1024;
-const EMPTY_BUFFER = Buffer.alloc(0);
+const EMPTY_BUFFER = new Uint8Array(0);
 
-const asyncPool = Array.from({ length: ASYNC_POOL_SIZE }, () => Buffer.allocUnsafe(POOLED_BUFFER_SIZE));
-const availableAsyncPoolIndexes = Array.from({ length: ASYNC_POOL_SIZE }, (_, index) => index);
-const asyncPoolWaiters: Array<(index: number) => void> = [];
 let syncPool = new Uint8Array(INITIAL_SYNC_BUFFER_SIZE);
 
-/** Returns a pool slot index, or `-1` when the caller should use a standalone buffer. */
-function acquireAsyncPoolIndex(): Promise<number> | number {
-	const index = availableAsyncPoolIndexes.pop();
-	if (index !== undefined) {
-		return index;
-	}
-	if (asyncPoolWaiters.length >= MAX_ASYNC_WAITERS) {
-		return -1;
-	}
-	const { promise, resolve } = Promise.withResolvers<number>();
-	asyncPoolWaiters.push(resolve);
-	return promise;
-}
-
-function releaseAsyncPoolIndex(index: number): void {
-	if (index < 0) {
-		return;
-	}
-	const waiter = asyncPoolWaiters.shift();
-	if (waiter) {
-		waiter(index);
-		return;
-	}
-	availableAsyncPoolIndexes.push(index);
-}
-
-async function withAsyncPoolBuffer<T>(maxBytes: number, op: (buffer: Buffer) => Promise<T>): Promise<T> {
-	if (maxBytes <= 0) {
-		return op(EMPTY_BUFFER);
-	}
-	if (maxBytes > POOLED_BUFFER_SIZE) {
-		return op(Buffer.allocUnsafe(maxBytes));
-	}
-
-	const poolIndex = await acquireAsyncPoolIndex();
-	const buffer = poolIndex >= 0 ? asyncPool[poolIndex] : Buffer.allocUnsafe(maxBytes);
-	try {
-		return await op(buffer.subarray(0, maxBytes));
-	} finally {
-		releaseAsyncPoolIndex(poolIndex);
-	}
+function allocateWindow(length: number): Uint8Array {
+	const buffer = Buffer.allocUnsafe(length);
+	// A plain view preserves Uint8Array.slice semantics without zeroing bytes the read replaces.
+	return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
 }
 
 function withSyncPoolBuffer<T>(maxBytes: number, op: (buffer: Uint8Array) => T): T {
@@ -104,10 +57,9 @@ export async function peekFile<T>(filePath: string, maxBytes: number, op: (heade
 
 	const fileHandle = await fs.promises.open(filePath, "r");
 	try {
-		return await withAsyncPoolBuffer(maxBytes, async buffer => {
-			const { bytesRead } = await fileHandle.read(buffer, 0, buffer.byteLength, 0);
-			return op(buffer.subarray(0, bytesRead));
-		});
+		const buffer = allocateWindow(maxBytes);
+		const { bytesRead } = await fileHandle.read(buffer, 0, buffer.byteLength, 0);
+		return op(buffer.subarray(0, bytesRead));
 	} finally {
 		await fileHandle.close();
 	}
@@ -116,9 +68,8 @@ export async function peekFile<T>(filePath: string, maxBytes: number, op: (heade
 /**
  * Read up to the last `maxBytes` of `filePath` and pass that slice to `op`.
  *
- * The tail mirror of {@link peekFile}: same pooled-buffer strategy (no per-call
- * allocation for small reads), but the read is positioned at `size - len` so the
- * window ends at EOF. When the file is shorter than `maxBytes`, the whole file is
+ * The tail mirror of {@link peekFile}: the read is positioned at `size - len` so
+ * the window ends at EOF. When the file is shorter than `maxBytes`, the whole file is
  * returned. A multi-byte codepoint straddling the leading cut decodes to a
  * replacement char — callers that parse line-oriented tails drop the partial
  * leading line anyway.
@@ -135,10 +86,9 @@ export async function peekFileTail<T>(filePath: string, maxBytes: number, op: (t
 		if (len <= 0) {
 			return op(EMPTY_BUFFER);
 		}
-		return await withAsyncPoolBuffer(len, async buffer => {
-			const { bytesRead } = await fileHandle.read(buffer, 0, buffer.byteLength, size - len);
-			return op(buffer.subarray(0, bytesRead));
-		});
+		const buffer = allocateWindow(len);
+		const { bytesRead } = await fileHandle.read(buffer, 0, buffer.byteLength, size - len);
+		return op(buffer.subarray(0, bytesRead));
 	} finally {
 		await fileHandle.close();
 	}
@@ -168,7 +118,7 @@ export async function peekFileEnds<T>(
 		const headLen = prefixBytes > 0 ? Math.min(prefixBytes, size) : 0;
 		const tailLen = suffixBytes > 0 ? Math.min(suffixBytes, size) : 0;
 
-		const head = headLen > 0 ? Buffer.allocUnsafe(headLen) : EMPTY_BUFFER;
+		const head = headLen > 0 ? allocateWindow(headLen) : EMPTY_BUFFER;
 		const headBytesRead = headLen > 0 ? (await fileHandle.read(head, 0, head.byteLength, 0)).bytesRead : 0;
 		const headSlice = head.subarray(0, headBytesRead);
 
@@ -179,7 +129,7 @@ export async function peekFileEnds<T>(
 			return op(headSlice, headSlice.subarray(Math.max(0, headBytesRead - tailLen)));
 		}
 
-		const tail = Buffer.allocUnsafe(tailLen);
+		const tail = allocateWindow(tailLen);
 		const { bytesRead: tailBytesRead } = await fileHandle.read(tail, 0, tail.byteLength, size - tailLen);
 		return op(headSlice, tail.subarray(0, tailBytesRead));
 	} finally {

package/src/postmortem.ts

@@ -7,8 +7,6 @@
  */
 
 import * as fs from "node:fs";
-import inspector from "node:inspector";
-import { isMainThread } from "node:worker_threads";
 import * as logger from "./logger";
 import { restoreTerminalStderr } from "./stderr-guard";
 
@@ -59,6 +57,26 @@ export const NATIVE_PROCESS_EXIT = Symbol.for("omp.postmortem.nativeProcessExit"
 
 type HardExitFn = (code?: number) => never;
 
+/**
+ * Walk a guarded exit primitive down to the native it shadows.
+ *
+ * `withHostGuard` stamps each throwing replacement with the primitive it
+ * shadows under {@link NATIVE_PROCESS_EXIT}; nested guard windows stack, so a
+ * single unwrap can still land on another throwing stub. Follow the chain
+ * (cycle-guarded) until a link carries no stamp — that link is native.
+ */
+function nativeHardExit(fn: HardExitFn | undefined): HardExitFn | undefined {
+	let current = fn;
+	const seen = new Set<HardExitFn>();
+	while (typeof current === "function" && !seen.has(current)) {
+		seen.add(current);
+		const behind = Reflect.get(current, NATIVE_PROCESS_EXIT);
+		if (typeof behind !== "function") return current;
+		current = behind as HardExitFn;
+	}
+	return typeof current === "function" ? current : undefined;
+}
+
 /**
  * Hard-exit the process through the native primitive, resolved on every call.
  *
@@ -70,14 +88,30 @@ type HardExitFn = (code?: number) => never;
  * init could freeze the throwing stub forever and turn every later shutdown
  * (SIGHUP/SIGINT/fatal) into an unhandled-rejection loop (#7393). When the
  * guard is active the stub carries the native exit under
- * {@link NATIVE_PROCESS_EXIT}; unwrapping it lets a mid-guard signal still exit
- * (#6488). Otherwise the current `process.reallyExit`/`process.exit` is native.
+ * {@link NATIVE_PROCESS_EXIT} (#6488).
+ *
+ * Both globals are reinstalled to their natives before exiting: Bun's
+ * `process.exit` re-reads `process.reallyExit` at call time, so exiting through
+ * one primitive while its sibling still holds the throwing stub re-enters the
+ * guard and loops the rejection storm (#11789). After restoring, `reallyExit`
+ * (the low-level primitive) is preferred; `process.exit` and finally `SIGKILL`
+ * are fallbacks so a poisoned or absent chain can never leave the process alive.
  */
-function exitProcess(code: number): never {
-	const current: HardExitFn = typeof process.reallyExit === "function" ? process.reallyExit : process.exit;
-	const behind = Reflect.get(current, NATIVE_PROCESS_EXIT);
-	const nativeExit = typeof behind === "function" ? (behind as HardExitFn) : current;
-	return nativeExit.call(process, code) as never;
+export function exitProcess(code: number): never {
+	const reallyExit = nativeHardExit(typeof process.reallyExit === "function" ? process.reallyExit : undefined);
+	const exit = nativeHardExit(process.exit as HardExitFn);
+	if (reallyExit) process.reallyExit = reallyExit as typeof process.reallyExit;
+	if (exit) process.exit = exit as typeof process.exit;
+	try {
+		reallyExit?.call(process, code);
+	} catch {}
+	try {
+		exit?.call(process, code);
+	} catch {}
+	try {
+		process.kill(process.pid, "SIGKILL");
+	} catch {}
+	throw new Error(`exitProcess(${code}) failed to terminate the process`);
 }
 let cleanupPromise: Promise<void> | undefined;
 let stdioDisconnectRegistrations = 0;
@@ -290,19 +324,47 @@ function faultWorkerIpcChannels(err: Error): void {
 }
 
 /**
- * Treat unhandled stdout EPIPE rejections as a graceful peer disconnect.
+ * Graceful shutdown driven by `process.stdout`'s own `error` event.
  *
- * Stdio protocol servers call this for their process lifetime so a closed
- * client pipe runs registered cleanup callbacks instead of the fatal path.
- * The returned callback removes the registration.
+ * A closed stdout consumer (`omp --help | head`, an ACP client dropping the
+ * pipe) delivers the broken-pipe write here — attributable to stdout by
+ * construction, unlike a process-wide `syscall: "write"` match that a closed
+ * subprocess stdin or socket would also satisfy — so it runs cleanup and exits
+ * 0 (Unix `| head` semantics).
+ *
+ * Only the broken-pipe case is claimed. A non-EPIPE stdout error (a revoked PTY
+ * reporting `EIO`) is left for other `error` listeners: the TUI installs its own
+ * stdout handler that treats a disconnect as SIGHUP/exit-129, and this listener
+ * is installed first on an interactive launch, so forcing a fatal exit here
+ * would preempt that established path. Attaching a listener already suppresses
+ * Node's default throw, so deferring is a safe no-op when no other listener runs.
+ */
+function onStdoutDisconnect(err: Error): void {
+	if (classifyBrokenPipe(err) !== "stdio-write") return;
+	logger.warn("Stdout peer disconnected; shutting down gracefully", { err });
+	void runQuit(0, "native", { drainStdout: false });
+}
+
+/**
+ * Treat a closed stdout consumer as a graceful peer disconnect for the caller's
+ * active lifetime. Attaches one shared `process.stdout` `error` listener,
+ * ref-counted across registrants (the ACP protocol server, the one-shot CLI
+ * entry). The returned callback removes the registration; the listener detaches
+ * when the last registrant unregisters.
  */
 export function registerStdioDisconnectHandling(): () => void {
 	let registered = true;
+	if (Bun.isMainThread && stdioDisconnectRegistrations === 0) {
+		process.stdout.on("error", onStdoutDisconnect);
+	}
 	stdioDisconnectRegistrations++;
 	return () => {
 		if (!registered) return;
 		registered = false;
 		stdioDisconnectRegistrations--;
+		if (Bun.isMainThread && stdioDisconnectRegistrations === 0) {
+			process.stdout.removeListener("error", onStdoutDisconnect);
+		}
 	};
 }
 
@@ -416,48 +478,52 @@ async function exitAfterFatal(output: string, logMessage: string, err: Error, re
 	}
 }
 
+/** Contain an EPIPE from an optional worker IPC `send()` (#2997, #9158). */
+function handleWorkerSendEpipe(err: Error): boolean {
+	if (!isIpcSendEpipe(err)) return false;
+	logger.warn("Ignoring EPIPE from worker IPC send; optional subsystem will self-recover", { err });
+	return true;
+}
+
 /**
  * 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 output = `${Bun.inspect(error, { colors: process.stderr.isTTY === true })}\n${formatFatalRecoveryHints()}`;
-	if (!isMainThread) {
+	if (!Bun.isMainThread) {
 		process.stderr.write(output);
 		process.exit(1);
 	}
 	return exitAfterFatal(output, "Fatal error", err, Reason.UNHANDLED_REJECTION);
 }
 
-if (isMainThread) {
+if (Bun.isMainThread) {
 	process
 		.on("SIGINT", async () => {
 			await runCleanup(Reason.SIGINT);
 			exitProcess(130); // 128 + SIGINT (2)
 		})
-		.on("SIGUSR1", () => {
+		.on("SIGUSR1", async () => {
 			if (inspectorOpened) return;
 			inspectorOpened = true;
+			// Signal-only boundary: successful startup never constructs inspector.
+			const { default: inspector } = await import("node:inspector");
 			inspector.open(undefined, undefined, false);
 			const url = inspector.url();
 			process.stderr.write(`Inspector opened: ${url}\n`);
 		})
 		.on("uncaughtException", async thrown => {
-			// Only explicitly marked exceptions are safe here. Structural
-			// AbortError/socket classification is limited to promise rejections:
-			// a synchronously thrown error may indicate an application bug.
+			// Expected cleanup is safe globally; unrelated synchronous errors stay fatal.
 			if (hasExpectedCleanupMarker(thrown)) {
 				logger.warn("Ignoring expected cleanup exception", { err: thrown });
 				return;
 			}
 			const err = thrown instanceof Error ? thrown : new Error(String(thrown));
-			// Bun can surface a worker IPC send race through uncaughtException
-			// instead of unhandledRejection. Apply the same optional-worker
-			// containment in either global error channel.
-			if (isIpcSendEpipe(err)) {
-				logger.warn("Ignoring EPIPE from worker IPC send; optional subsystem will self-recover", { err });
-				return;
-			}
+			// 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.
+			if (handleWorkerSendEpipe(err)) return;
 			// A malformed advanced-serialization frame from a worker subprocess
 			// surfaces here as a process-level uncaughtException (oven-sh/bun#37287)
 			// rather than in the channel's ipc() callback, and Bun gives no way to
@@ -466,7 +532,7 @@ if (isMainThread) {
 			// worker so its owning client rejects in-flight requests and recycles
 			// the subprocess — a worker that sent a bad frame but stays alive would
 			// otherwise never fire onExit and leave callers awaiting forever.
-			// Mirrors the ipc-send EPIPE containment below (#9158, #2997).
+			// See the analogous worker IPC containment in handleBrokenPipe (#9158, #2997).
 			if (isWorkerIpcDeserializeError(err)) {
 				logger.warn("Malformed worker IPC frame; faulting active worker subsystems", { err });
 				faultWorkerIpcChannels(err);
@@ -487,25 +553,7 @@ if (isMainThread) {
 		})
 		.on("unhandledRejection", async reason => {
 			const err = reason instanceof Error ? reason : new Error(String(reason));
-			const brokenPipeSource = classifyBrokenPipe(err);
-			// EPIPE from an IPC `send()` (`syscall: "send"`) originates from a
-			// worker subprocess whose pipe broke between the exit being observed
-			// and the next `proc.send()` — a race window that Bun surfaces as an
-			// async rejection rather than the synchronous "cannot be used after
-			// the process has exited" guard. Every `send()` target is an optional
-			// worker subsystem (TTS, STT, tiny-title, MCP servers), so a broken
-			// send pipe must never take down the whole session. Log and continue
-			// instead of exiting; the owning client detects the dead worker via
-			// its own `onExit`/error path and respawns or disables it. See #2997.
-			if (brokenPipeSource === "ipc-send") {
-				logger.warn("Ignoring EPIPE from worker IPC send; optional subsystem will self-recover", { err });
-				return;
-			}
-			if (brokenPipeSource === "stdio-write" && stdioDisconnectRegistrations > 0) {
-				logger.warn("Stdio peer disconnected; shutting down gracefully", { err });
-				await runQuit(0, "native");
-				return;
-			}
+			if (handleWorkerSendEpipe(err)) return;
 			if (isExpectedCleanupError(reason)) {
 				logger.warn("Ignoring expected cleanup rejection", { err });
 				return;
@@ -656,7 +704,7 @@ export async function drainStdout(): Promise<void> {
 async function runQuit(code: number, exitMode: "guarded" | "native", options: QuitOptions = {}): Promise<void> {
 	await runCleanup(Reason.MANUAL);
 
-	if (!isMainThread) {
+	if (!Bun.isMainThread) {
 		return; // Workers: cleanup done, let worker exit naturally
 	}
 

package/src/procmgr.ts

@@ -4,8 +4,10 @@ import { Process, ProcessStatus } from "@linxiraos/pi-natives";
 import type { Subprocess } from "bun";
 import { getAgentDir, MAIN_CONFIG_FILENAMES } from "./dirs";
 import { $env, filterChildShellEnv } from "./env";
+import { isExecutable } from "./executable";
 import { $which } from "./which";
 
+export { isExecutable };
 export interface ShellConfig {
 	shell: string;
 	args: string[];
@@ -20,18 +22,6 @@ export interface ShellConfigOptions {
 }
 let cachedShellConfig: ShellConfig | null = null;
 
-/**
- * Check if a shell binary is executable.
- */
-export function isExecutable(path: string): boolean {
-	try {
-		fs.accessSync(path, fs.constants.X_OK);
-		return true;
-	} catch {
-		return false;
-	}
-}
-
 /**
  * Build the spawn environment (cached).
  */

package/src/ptree.ts

@@ -17,6 +17,8 @@ type PipedSubprocess<In extends InMask = InMask> = Subprocess<In, "pipe", "pipe"
 
 const LINUX_SUBREAPER_COMMAND_ENV = "OMP_PTREE_SUBREAPER_COMMAND";
 const LINUX_SUBREAPER_BUN_BE_BUN_ENV = "OMP_PTREE_SUBREAPER_BUN_BE_BUN";
+const SUBREAPER_KILL_WINDOW_MS = 100;
+const SUBREAPER_KILL_POLL_MS = 5;
 
 /**
  * Build the Linux child-subreaper entrypoint.
@@ -189,6 +191,8 @@ export class ChildProcess<In extends InMask = InMask> {
 	#stderrStream?: ReadableStream<Uint8Array>;
 	// Termination in flight after kill(); aborted exits await it before reporting.
 	#terminating?: Promise<boolean | void>;
+	// A hard subreaper sweep must remain authoritative across overlapping kill requests.
+	#hardKillSweep?: Promise<void>;
 	#terminateGroup: boolean;
 	#hardKillTree: boolean;
 	// Windows has no process groups. Retaining the root's native handle pins
@@ -340,14 +344,22 @@ export class ChildProcess<In extends InMask = InMask> {
 			// group leader; wait() still needs to report the later deadline.
 			if (this.proc.exitCode !== null) this.#exitReason = reason;
 		}
+		// An AbortSignal can race a timeout after its hard subreaper sweep has
+		// started. Do not replace that sweep with a normal root termination: the
+		// root must stay alive until adopted descendants have been collected.
+		if (this.#hardKillSweep) return;
 		if (gracefulMs !== undefined && gracefulMs < 0 && this.#hardKillTree && this.proc.exitCode === null) {
-			// terminate() sends its polite wave to the root before rebuilding the
-			// hard-kill tree. A subreaper root can die in that gap and release its
-			// adopted descendants, so snapshot and hard-kill the live tree first.
+			// Keep the subreaper alive while descendants are killed. A single
+			// killTree() snapshot can miss a worker whose parent exits during the
+			// walk and reparents it to the subreaper after that root was enumerated.
 			const root = Process.fromPid(this.proc.pid);
 			if (root) {
-				root.killTree(9);
-				this.#terminating = Promise.resolve();
+				const sweep = this.#hardKillSubreaperTree(root).catch(e => void e);
+				this.#hardKillSweep = sweep;
+				this.#terminating = sweep;
+				void sweep.finally(() => {
+					if (this.#hardKillSweep === sweep) this.#hardKillSweep = undefined;
+				});
 				return;
 			}
 		}
@@ -386,6 +398,25 @@ export class ChildProcess<In extends InMask = InMask> {
 		}
 	}
 
+	async #hardKillSubreaperTree(root: Process): Promise<void> {
+		try {
+			const deadline = Date.now() + SUBREAPER_KILL_WINDOW_MS;
+			let emptySweeps = 0;
+			while (emptySweeps < 2 && Date.now() < deadline) {
+				const children = root.children();
+				if (children.length === 0) {
+					emptySweeps++;
+				} else {
+					emptySweeps = 0;
+					for (const child of children) child.killTree(9);
+				}
+				if (emptySweeps < 2) await Bun.sleep(SUBREAPER_KILL_POLL_MS);
+			}
+		} finally {
+			root.killTree(9);
+		}
+	}
+
 	// ── Output helpers ───────────────────────────────────────────────────
 
 	async #throwIfAborted(): Promise<void> {

package/src/snowflake.ts

@@ -4,6 +4,7 @@ function randu32() {
 
 const EPOCH = 1420070400000;
 const MAX_SEQ = 0x3fffff;
+const MAX_DT = 2 ** 42 - 1;
 
 // Snowflake as a hex string (16 chars, zero-padded).
 //
@@ -25,14 +26,24 @@ namespace Snowflake {
 	//
 	export const MAX_SEQUENCE = MAX_SEQ;
 
+	// Last timestamp representable in the 42-bit timestamp field (~year 2154).
+	//
+	export const MAX_TIMESTAMP = EPOCH + MAX_DT;
+
 	// Formats a sequence and timestamp into a snowflake hex string.
 	//
 	// dt fits well within BigInt range: (dt << 22) | seq stays under 2^64 for
 	// any dt < 2^42 (~year 2154), so a single 64-bit format is exact — and
 	// measures ~1.7x faster than stitching four 16-bit hex segments.
 	//
+	// dt is saturated into [0, 2^42) so the result is always a valid snowflake:
+	// a negative delta (a timestamp before EPOCH) would otherwise render a
+	// leading "-", and a delta past ~2154 would widen the string beyond 16
+	// chars. Both cases produce a value that fails this module's own valid().
+	//
 	export function formatParts(dt: number, seq: number): Snowflake {
-		return ((BigInt(dt) << 22n) | BigInt(seq)).toString(16).padStart(16, "0") as Snowflake;
+		const clamped = Math.min(Math.max(dt, 0), MAX_DT);
+		return ((BigInt(clamped) << 22n) | BigInt(seq)).toString(16).padStart(16, "0") as Snowflake;
 	}
 
 	// Snowflake generator type.