@linxiraos/pi-utils 1.4.4 → 1.4.7

package/src/postmortem.ts

@@ -27,10 +27,26 @@ interface CleanupRegistration {
 	id: string;
 	callback: (reason: Reason) => Promise<void> | void;
 	exitOnly: boolean;
+	/** How long a pass waits for this callback, when longer than {@link CLEANUP_DEADLINE_MS}. */
+	deadlineMs: number | undefined;
+	/** Printed to stderr when exit waits on this callback alone; see {@link CleanupRegistrationOptions.waitMessage}. */
+	waitMessage: string | undefined;
 	cancelled: boolean;
 	lastPass: number;
 }
 
+/** The deadline of one cleanup pass, which callbacks with their own `deadlineMs` hold open. */
+interface CleanupPassDeadline {
+	/**
+	 * Keep the pass open until `pending` settles, for at most `deadlineMs`. A
+	 * `waitMessage` is printed to stderr if the pass is still waiting on it once
+	 * every other callback has finished.
+	 */
+	extend(pending: Promise<unknown>, deadlineMs: number, waitMessage?: string): void;
+	/** Whether a callback with its own deadline still holds the pass open. */
+	extended(): boolean;
+}
+
 // Active cleanup callbacks in registration order. Registrations survive
 // keep-alive passes; `lastPass` enforces at-most-once invocation per pass.
 const callbackList: CleanupRegistration[] = [];
@@ -42,6 +58,8 @@ let activeCleanupKeepAlive = false;
 // Promises of callbacks invoked late (registered while a pass runs), joined by
 // the active pass before it settles so `cleanup()`/signal exits await them.
 let activeLatePromises: Promise<void>[] | undefined;
+// Deadline of the running pass, so callbacks invoked late can extend it too.
+let activePassDeadline: CleanupPassDeadline | undefined;
 const CLEANUP_DEADLINE_MS = 10_000;
 /**
  * Symbol stamped by the extension-load guard onto the throwing replacement it
@@ -122,7 +140,7 @@ export function exitProcess(code: number): never {
 let cleanupPromise: Promise<void> | undefined;
 let stdioDisconnectRegistrations = 0;
 
-/** User-facing command printed before fatal cleanup so interrupted work can be resumed. */
+/** User-facing command printed after fatal or SIGTERM cleanup so interrupted work can be resumed. */
 export interface FatalRecoveryHint {
 	/** Stable label identifying the recoverable session or process. */
 	label: string;
@@ -184,10 +202,75 @@ function runCleanup(reason: Reason, keepAlive = false): Promise<void> {
 		}
 	};
 
+	// The pass ends once every callback settles, or at the deadline: CLEANUP_DEADLINE_MS,
+	// held open while a callback with a longer `deadlineMs` is still pending.
+	const deadline = Promise.withResolvers<void>();
+	const deadlineTimers: NodeJS.Timeout[] = [];
+	let baseDeadlineElapsed = false;
+	let openExtensions = 0;
+	let passDone = false;
+	const expireIfDue = (): void => {
+		if (passDone || !baseDeadlineElapsed || openExtensions > 0) return;
+		passDone = true;
+		logger.error("Cleanup deadline exceeded; proceeding with exit", { reason });
+		settle();
+		deadline.resolve();
+	};
+	// Holds that still keep the pass open and have a message for the user. The
+	// message is printed once the pass waits on nothing else, so a terminal owner
+	// has already released the screen and the user sees why exit is slow.
+	const announced: { message: string; until: number; open: () => boolean }[] = [];
+	let othersSettled = false;
+	const announce = (): void => {
+		if (passDone || !othersSettled) return;
+		for (const hold of announced.splice(0)) {
+			if (!hold.open()) continue;
+			const seconds = Math.max(1, Math.ceil((hold.until - Date.now()) / 1000));
+			try {
+				fs.writeSync(2, `${hold.message} (up to ${seconds} s)…\n`);
+			} catch {}
+		}
+	};
+	const passDeadline: CleanupPassDeadline = {
+		extend(pending, deadlineMs, waitMessage) {
+			if (passDone || deadlineMs <= 0) return;
+			openExtensions++;
+			let open = true;
+			const close = (): void => {
+				if (!open) return;
+				open = false;
+				openExtensions--;
+				// Check on a later macrotask: when this was the last pending callback, the
+				// pass completes first and no deadline is reported.
+				deadlineTimers.push(setTimeout(expireIfDue, 0));
+			};
+			deadlineTimers.push(setTimeout(close, deadlineMs));
+			pending.then(close, close);
+			if (waitMessage !== undefined) {
+				announced.push({ message: waitMessage, until: Date.now() + deadlineMs, open: () => open });
+				// On a later macrotask, so a callback that is already done closes first.
+				if (othersSettled) deadlineTimers.push(setTimeout(announce, 0));
+			}
+		},
+		extended: () => !passDone && openExtensions > 0,
+	};
+	activePassDeadline = passDeadline;
+
 	// Snapshot the pass. Registrations added while a keep-alive cleanup runs are
 	// invoked by register() when appropriate and remain active for later passes.
-	const promises = callbackList.toReversed().map(registration => {
-		return Promise.try(() => invokeCleanup(registration, reason, keepAlive, pass));
+	const snapshot = callbackList.toReversed();
+	const promises = snapshot.map(registration => {
+		return Promise.try(() => {
+			const pending = invokeCleanup(registration, reason, keepAlive, pass);
+			if (pending && registration.deadlineMs !== undefined) {
+				passDeadline.extend(pending, registration.deadlineMs, registration.waitMessage);
+			}
+			return pending;
+		});
+	});
+	void Promise.allSettled(promises.filter((_, index) => snapshot[index]?.deadlineMs === undefined)).then(() => {
+		othersSettled = true;
+		deadlineTimers.push(setTimeout(announce, 0));
 	});
 
 	const cleanupSettled = Promise.allSettled(promises).then(async results => {
@@ -202,14 +285,20 @@ function runCleanup(reason: Reason, keepAlive = false): Promise<void> {
 		while (late.length > 0) await Promise.allSettled(late.splice(0));
 		settle();
 	});
-	const deadline = Promise.withResolvers<void>();
-	const deadlineTimer = setTimeout(() => {
-		logger.error("Cleanup deadline exceeded; proceeding with exit", { reason });
-		settle();
-		deadline.resolve();
-	}, CLEANUP_DEADLINE_MS);
+	deadlineTimers.push(
+		setTimeout(() => {
+			baseDeadlineElapsed = true;
+			// The pass no longer waits on the other callbacks, so a hold still open is
+			// what exit waits on; terminal owners released the screen synchronously.
+			othersSettled = true;
+			announce();
+			expireIfDue();
+		}, CLEANUP_DEADLINE_MS),
+	);
 	const passPromise = Promise.race([cleanupSettled, deadline.promise]).finally(() => {
-		clearTimeout(deadlineTimer);
+		passDone = true;
+		for (const timer of deadlineTimers) clearTimeout(timer);
+		if (activePassDeadline === passDeadline) activePassDeadline = undefined;
 		// A re-armed pass must drop only its own settled promise; an older
 		// deadline-limited pass may finish after a newer one has already started.
 		if (keepAlive && cleanupPass === pass && cleanupPromise === passPromise) cleanupPromise = undefined;
@@ -480,7 +569,10 @@ export function interceptUnhandledRejections(interceptor: (reason: unknown) => b
 
 /**
  * Register a synchronous recovery command to print when the process exits
- * through an uncaught exception or unhandled rejection.
+ * through an uncaught exception, an unhandled rejection, or SIGTERM.
+ *
+ * Providers are read once cleanup finishes (or hits its deadline), so they
+ * report what teardown left behind: a session it saved or one it dropped.
  */
 export function registerFatalRecoveryHint(provider: FatalRecoveryHintProvider): () => void {
 	fatalRecoveryHintProviders.add(provider);
@@ -494,10 +586,10 @@ function escapeFatalHintText(value: string): string {
 	});
 }
 
-function formatFatalRecoveryHints(): string {
+function formatFatalRecoveryHints(providers: Iterable<FatalRecoveryHintProvider>): string {
 	const lines: string[] = [];
 	const seenCommands = new Set<string>();
-	for (const provider of fatalRecoveryHintProviders) {
+	for (const provider of providers) {
 		try {
 			const hint = provider();
 			if (!hint?.command || seenCommands.has(hint.command)) continue;
@@ -519,21 +611,54 @@ function formatFatalError(label: string, err: Error): string {
 	return `\n[${label}] ${name}: ${message}${formattedStack}\n`;
 }
 
+/** Write a final report to stderr once terminal owners have handed the terminal back. */
+function writeTerminalReport(output: string): void {
+	restoreTerminalStderr();
+	// A revoked terminal can make stream writes raise another fatal error. Use
+	// the descriptor directly so failure stays synchronous and contained.
+	try {
+		fs.writeSync(2, output);
+	} catch {}
+}
+
+let recoveryHintsWritten = false;
+
+/**
+ * Print the recovery commands at most once per process. Callers snapshot the
+ * providers before cleanup, because a session's own cleanup unregisters its
+ * provider, and call this after cleanup, because teardown can still save the
+ * session (an unsent draft, an aborted first reply) or drop an empty one.
+ */
+function writeRecoveryHints(providers: readonly FatalRecoveryHintProvider[], heading = ""): void {
+	if (recoveryHintsWritten) return;
+	const hints = formatFatalRecoveryHints(providers);
+	if (!hints) return;
+	recoveryHintsWritten = true;
+	writeTerminalReport(`${heading}${hints}`);
+}
+
 async function exitAfterFatal(output: string, logMessage: string, err: Error, reason: Reason): Promise<never> {
-	const forcedExit = setTimeout(() => exitProcess(1), CLEANUP_DEADLINE_MS);
+	const hintProviders = [...fatalRecoveryHintProviders];
+	// The forced exit backs up the pass deadline, so it waits while a callback with
+	// its own `deadlineMs` holds the pass open; that pass still ends at its deadline.
+	const forceExit = (): void => {
+		if (activePassDeadline?.extended()) {
+			forcedExit = setTimeout(forceExit, CLEANUP_DEADLINE_MS);
+			return;
+		}
+		writeRecoveryHints(hintProviders);
+		exitProcess(1);
+	};
+	let forcedExit = setTimeout(forceExit, CLEANUP_DEADLINE_MS);
 	try {
 		// Cleanup callbacks are invoked synchronously before runCleanup returns its
 		// completion promise. TUI owners therefore hand the cursor back before the
 		// fatal report is written, while slower resource cleanup continues afterward.
 		const cleanup = runCleanup(reason);
-		restoreTerminalStderr();
-		// A revoked terminal can make stream writes raise another fatal error. Use
-		// the descriptor directly so failure stays synchronous and contained.
-		try {
-			fs.writeSync(2, output);
-		} catch {}
+		writeTerminalReport(output);
 		logger.error(logMessage, { err });
 		await cleanup;
+		writeRecoveryHints(hintProviders);
 	} finally {
 		clearTimeout(forcedExit);
 		exitProcess(1);
@@ -552,12 +677,12 @@ function handleWorkerSendEpipe(err: Error): boolean {
  */
 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()}`;
+	const report = `${Bun.inspect(error, { colors: process.stderr.isTTY === true })}\n`;
 	if (!Bun.isMainThread) {
-		process.stderr.write(output);
+		process.stderr.write(`${report}${formatFatalRecoveryHints(fatalRecoveryHintProviders)}`);
 		process.exit(1);
 	}
-	return exitAfterFatal(output, "Fatal error", err, Reason.UNHANDLED_REJECTION);
+	return exitAfterFatal(report, "Fatal error", err, Reason.UNHANDLED_REJECTION);
 }
 
 if (Bun.isMainThread) {
@@ -607,7 +732,7 @@ if (Bun.isMainThread) {
 				return;
 			}
 			await exitAfterFatal(
-				`${formatFatalError("Uncaught Exception", err)}${formatFatalRecoveryHints()}`,
+				formatFatalError("Uncaught Exception", err),
 				"Uncaught exception",
 				err,
 				Reason.UNCAUGHT_EXCEPTION,
@@ -630,7 +755,7 @@ if (Bun.isMainThread) {
 				}
 			}
 			await exitAfterFatal(
-				`${formatFatalError("Unhandled Rejection", err)}${formatFatalRecoveryHints()}`,
+				formatFatalError("Unhandled Rejection", err),
 				"Unhandled rejection",
 				err,
 				Reason.UNHANDLED_REJECTION,
@@ -640,7 +765,12 @@ if (Bun.isMainThread) {
 			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
+			// hints still print once.
+			const hintProviders = [...fatalRecoveryHintProviders];
 			await runCleanup(Reason.SIGTERM);
+			writeRecoveryHints(hintProviders, "\n[Stopped by SIGTERM]");
 			exitProcess(143); // 128 + SIGTERM (15)
 		})
 		.on("SIGHUP", async () => {
@@ -664,6 +794,20 @@ export interface CleanupRegistrationOptions {
 	 * The registration remains armed when a keep-alive pass skips it.
 	 */
 	exitOnly?: boolean;
+	/**
+	 * How long a pass waits for this callback, when that is longer than the
+	 * default 10 s cleanup deadline. It extends the pass only while the callback
+	 * is still pending: one that settles early ends its hold at once.
+	 */
+	deadlineMs?: number;
+	/**
+	 * With `deadlineMs`: a line printed to stderr, with the remaining wait
+	 * appended, if exit is still waiting on this callback once every other
+	 * callback has finished (a terminal owner has then released the screen), or
+	 * at the default 10 s deadline when another callback is still running.
+	 * Nothing is printed when the callback finishes first.
+	 */
+	waitMessage?: string;
 }
 
 /**
@@ -690,6 +834,8 @@ export function register(
 		id,
 		callback,
 		exitOnly: options.exitOnly ?? false,
+		deadlineMs: options.deadlineMs,
+		waitMessage: options.waitMessage,
 		cancelled: false,
 		lastPass: 0,
 	};
@@ -709,6 +855,9 @@ export function register(
 			// Join the active pass so cleanup()/signal exits await it; after a
 			// completed exit pass there is nothing left to join.
 			activeLatePromises?.push(tracked);
+			if (registration.deadlineMs !== undefined) {
+				activePassDeadline?.extend(tracked, registration.deadlineMs, registration.waitMessage);
+			}
 		} catch (error) {
 			const err = error instanceof Error ? error : new Error(String(error));
 			logger.error("Cleanup callback failed", { err, id, stack: err.stack });

package/src/process-name.ts

@@ -10,9 +10,11 @@
  * setter) and additionally drive `prctl` via `bun:ffi` on Linux, mirroring the
  * libc-FFI pattern in `ttyid.ts` / `stderr-guard.ts`.
  *
- * macOS has no clean userspace equivalent for the shebang-run path, and on
- * Windows / compiled binaries the kernel derives the name from the exec'd file,
- * so those paths already report correctly; there we only set `process.title`.
+ * macOS has no clean userspace equivalent for the shebang-run path, so there
+ * we only set `process.title`. Windows derives the name from the exec'd file,
+ * and there Bun's `process.title` setter is libuv's `SetConsoleTitleW`: every
+ * omp child attached to a pane's console (workers, `browser-relay`, servers)
+ * would overwrite that pane's tab title, so Windows skips it entirely.
  */
 import { dlopen, FFIType, ptr } from "bun:ffi";
 import * as os from "node:os";
@@ -21,17 +23,20 @@ import * as os from "node:os";
 const PR_SET_NAME = 15;
 
 /**
- * Set both the JS `process.title` and — on Linux — the kernel `comm` name.
+ * Set the JS `process.title` (except on Windows, see above) and — on Linux —
+ * the kernel `comm` name.
  *
  * Never throws: `bun:ffi` unavailability or a failed syscall degrades silently
  * to the `process.title`-only behavior, so it is safe to call at startup.
  */
 export function setProcessName(name: string): void {
+	const platform = os.platform();
+	if (platform === "win32") return;
 	try {
 		process.title = name;
 	} catch {}
 
-	if (os.platform() !== "linux") return;
+	if (platform !== "linux") return;
 
 	// glibc first, then the generic soname for musl-style layouts (see stderr-guard.ts).
 	for (const soname of ["libc.so.6", "libc.so"]) {

package/src/stream.ts

@@ -2,6 +2,7 @@ const trailingEvents = new WeakSet<ServerSentEvent>();
 
 import { abortableSource } from "./abortable";
 import { parseStreamingJson } from "./json-parse";
+import { isWhitespace } from "./json-lexer";
 
 const LF = 0x0a;
 const CR = 0x0d;
@@ -613,9 +614,11 @@ export async function* readSseEvents(
  */
 export function parseJsonlLenient<T>(buffer: string, options: { onMalformedRecord?: () => void } = {}): T[] {
 	let entries: T[] | undefined;
+	let cursor = 0;
+	const len = buffer.length;
 
-	while (buffer.length > 0) {
-		const { values, error, read, done } = Bun.JSONL.parseChunk(buffer);
+	while (cursor < len) {
+		const { values, error, read, done } = Bun.JSONL.parseChunk(buffer, cursor);
 		if (values.length > 0) {
 			const ext = values as T[];
 			if (!entries) {
@@ -625,18 +628,22 @@ export function parseJsonlLenient<T>(buffer: string, options: { onMalformedRecor
 			}
 		}
 		if (error) {
-			const nextNewline = buffer.indexOf("\n", read);
-			const malformedEnd = nextNewline === -1 ? buffer.length : nextNewline;
-			if (buffer.substring(read, malformedEnd).trim().length > 0) options.onMalformedRecord?.();
+			let malformedStart = read;
+			while (malformedStart < len && isWhitespace(buffer.charCodeAt(malformedStart))) {
+				malformedStart++;
+			}
+			const nextNewline = buffer.indexOf("\n", malformedStart);
+			const malformedEnd = nextNewline === -1 ? len : nextNewline;
+			if (buffer.substring(malformedStart, malformedEnd).trim().length > 0) options.onMalformedRecord?.();
 			if (nextNewline === -1) break;
-			buffer = buffer.substring(nextNewline + 1);
+			cursor = nextNewline + 1;
 			continue;
 		}
-		if (read === 0) {
-			if (buffer.trim().length > 0) options.onMalformedRecord?.();
+		if (read === cursor) {
+			if (buffer.substring(cursor).trim().length > 0) options.onMalformedRecord?.();
 			break;
 		}
-		buffer = buffer.substring(read);
+		cursor = read;
 		if (done) break;
 	}
 	return entries ?? [];

package/src/which.ts

@@ -261,3 +261,30 @@ export function $which(command: string, options?: WhichOptions): string | null {
 	}
 	return result;
 }
+
+/**
+ * Locate every match for `command` on PATH, in PATH order, uncached.
+ *
+ * Callers that probe candidates (e.g. the Python eval backend) use this so a broken
+ * first hit — a version-manager shim with no version selected, a Windows Store alias —
+ * does not hide a working binary further down PATH. On macOS the Xcode/CLT toolchain
+ * match is appended last, mirroring {@link $which}'s fallback.
+ *
+ * @param command - Binary name to resolve
+ * @param options - `PATH` (defaults to `process.env.PATH`) and `cwd` for relative entries
+ * @returns Distinct filesystem paths; empty when nothing matches
+ */
+export function $whichAll(command: string, options?: Bun.WhichOptions): string[] {
+	const searchPath = options?.PATH ?? process.env.PATH ?? "";
+	const matches: string[] = [];
+	for (const dir of searchPath.split(path.delimiter)) {
+		if (!dir) continue;
+		const match = Bun.which(command, { cwd: options?.cwd, PATH: dir });
+		if (match && !matches.includes(match)) matches.push(match);
+	}
+	if (os.platform() === "darwin" && isXcodeBin(command)) {
+		const toolchainMatch = getMacosToolPaths().get(command);
+		if (toolchainMatch && !matches.includes(toolchainMatch)) matches.push(toolchainMatch);
+	}
+	return matches;
+}

package/dist/types/fs-open.d.ts

@@ -1,17 +0,0 @@
-/**
- * `fs.openSync` with close-on-exec, matching Node's default.
- *
- * libuv adds `O_CLOEXEC` inside `uv__fs_open`, so on Node every `fs` descriptor
- * dies at `exec`. Bun's `fs.open*` did not before 1.4.3 (still allowed by the
- * `bun@>=1.4` pin), and descriptors it returns survive
- * into any child spawned through a path that does not close strays itself — the
- * bash tool's shell `fork`/`exec`s user commands and hands them the lot. Use
- * this for every descriptor kept open past such a spawn (session transcripts,
- * logs, spools); a child must never hold a writable handle to them (#13224).
- *
- * Flags are numeric only: the bit cannot be OR-ed into `"a"`/`"w+"` strings.
- *
- * @example
- * const fd = openCloexecSync(logPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_APPEND);
- */
-export declare function openCloexecSync(filePath: string, flags: number, mode?: number): number;

package/src/fs-open.ts

@@ -1,32 +0,0 @@
-/** Close-on-exec file opens for descriptors held past a child spawn. */
-import * as fs from "node:fs";
-
-/**
- * `O_CLOEXEC`, which neither Node nor Bun exposes in `fs.constants`.
- *
- * Kernel ABI values: `0o2000000` on Linux, `0x0100_0000` on Darwin. Windows has
- * no `exec` and its CRT handles are inherited only when a spawn explicitly asks
- * for it, so the bit is 0 there — as it is on any other platform, where adding
- * an unknown flag bit would be worse than leaving the descriptor inheritable.
- */
-const O_CLOEXEC = process.platform === "linux" ? 0o2000000 : process.platform === "darwin" ? 0x0100_0000 : 0;
-
-/**
- * `fs.openSync` with close-on-exec, matching Node's default.
- *
- * libuv adds `O_CLOEXEC` inside `uv__fs_open`, so on Node every `fs` descriptor
- * dies at `exec`. Bun's `fs.open*` did not before 1.4.3 (still allowed by the
- * `bun@>=1.4` pin), and descriptors it returns survive
- * into any child spawned through a path that does not close strays itself — the
- * bash tool's shell `fork`/`exec`s user commands and hands them the lot. Use
- * this for every descriptor kept open past such a spawn (session transcripts,
- * logs, spools); a child must never hold a writable handle to them (#13224).
- *
- * Flags are numeric only: the bit cannot be OR-ed into `"a"`/`"w+"` strings.
- *
- * @example
- * const fd = openCloexecSync(logPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_APPEND);
- */
-export function openCloexecSync(filePath: string, flags: number, mode?: number): number {
-	return fs.openSync(filePath, flags | O_CLOEXEC, mode);
-}