@oh-my-pi/pi-utils 18.13.1 → 18.13.3

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [18.13.3] - 2026-10-28
+
+### Changed
+
+- Updated Bun engine requirement to ≥1.4.4
+
+## [18.13.2] - 2026-10-27
+
+### Added
+
+- Added `deadlineMs` and `waitMessage` cleanup registration options: shutdown waits longer for that callback, but only while it is still pending, and says so on stderr once nothing else is left to wait for ([#17128](https://github.com/can1357/oh-my-pi/pull/17128) by [@sjawhar](https://github.com/sjawhar))
+- A process stopped by SIGTERM now prints its registered recovery commands after the terminal is handed back, so a stopped omp session shows `omp --resume <id>` instead of leaving its last frame above the shell prompt like a crash ([#17119](https://github.com/can1357/oh-my-pi/pull/17119) by [@sjawhar](https://github.com/sjawhar))
+
+### Fixed
+
+- Fixed plain TAR archives requiring a whole-container memory buffer to list entries or read a selected member ([#17175](https://github.com/can1357/oh-my-pi/pull/17175) by [@alphastorm](https://github.com/alphastorm))
+
 ## [18.13.1] - 2026-10-27
 
 ### Added

package/README.md

@@ -29,7 +29,7 @@ Import from the root barrel or per-module subpaths (`@oh-my-pi/pi-utils/<module>
 bun add @oh-my-pi/pi-utils
 ```
 
-Ships TypeScript source directly (no build step); requires Bun ≥ 1.3.14.
+Ships TypeScript source directly (no build step); requires Bun ≥ 1.4.4.
 
 ## References
 

package/dist/types/acp/protocol.d.ts

@@ -93,6 +93,7 @@ export interface ToolCallLocation extends Meta {
 export interface ToolCall extends Meta {
     toolCallId: ToolCallId;
     title: string;
+    name?: string | null;
     kind?: ToolKind | null;
     status?: ToolCallStatus | null;
     content?: ToolCallContent[] | null;

package/dist/types/ar/tar.d.ts

@@ -6,7 +6,7 @@ export declare function readTarEntriesFromBuffer(buffer: Uint8Array, options: Fo
  * pass over `open()` walks the headers, and member reads open it again.
  */
 export declare function readTarEntriesFromStream(open: () => AsyncIterable<Uint8Array>, options: FormatReadOptions): Promise<ArchiveIndexEntry[]>;
-/** Read and index a tar source after one bounded whole-stream read. */
+/** Index a plain tar by ranging over headers and retaining lazy member offsets. */
 export declare const readTar: FormatReader;
 /** Detect a tar header, including legacy pre-ustar archives, by its checksum. */
 export declare function sniffTar(bytes: Uint8Array): boolean;

package/dist/types/ar/types.d.ts

@@ -8,7 +8,7 @@ export type WritableArchiveFormat = "zip" | "tar" | "tar.gz" | "tar.zst" | "asar
  * Where to read an archive from: an extension-inferred filesystem path, a
  * format-tagged filesystem path, in-memory bytes, or any caller-provided
  * {@link ByteSource} (e.g. `httpByteSource` for ranged remote reads).
- * File- and source-backed ZIP/ASAR/RAR/7z/ISO are read lazily.
+ * File- and source-backed TAR/ZIP/ASAR/RAR/7z/ISO are read lazily.
  */
 export type ArchiveSource = string | {
     bytes: Uint8Array;

package/dist/types/index.d.ts

@@ -10,7 +10,6 @@ export * from "./file-lock.js";
 export * from "./format.js";
 export * from "./frontmatter.js";
 export * from "./fs-error.js";
-export * from "./fs-open.js";
 export * from "./incoming-json.js";
 export * from "./json.js";
 export * from "./json-parse.js";

package/dist/types/json.d.ts

@@ -2,6 +2,13 @@
  * Try to parse JSON, returning null on failure.
  */
 export declare function tryParseJson<T = unknown>(content: string): T | null;
+/**
+ * Index just past the JSON object or array that opens at `text[start]`, or -1
+ * when it does not close within `text`. String literals are skipped, honoring
+ * escapes, so brackets inside values do not count. Malformed input yields some
+ * end that a parser then rejects.
+ */
+export declare function jsonContainerEnd(text: string, start: number): number;
 /**
  * Serialize JSON while preserving bigint precision as decimal strings.
  *

package/dist/types/postmortem.d.ts

@@ -52,7 +52,7 @@ export declare const NATIVE_PROCESS_EXIT: unique symbol;
  * signal and fatal exit.
  */
 export declare function exitProcess(code: number): never;
-/** 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;
@@ -168,7 +168,10 @@ export declare function isExpectedCleanupError(reason: unknown): boolean;
 export declare function interceptUnhandledRejections(interceptor: (reason: unknown) => boolean): () => void;
 /**
  * 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 declare function registerFatalRecoveryHint(provider: FatalRecoveryHintProvider): () => void;
 /**
@@ -182,6 +185,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;
 }
 /**
  * Registers a cleanup callback for shutdown, signals, fatal errors, and

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-utils",
-	"version": "18.13.1",
+	"version": "18.13.3",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"cli",
@@ -57,12 +57,12 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.13.1"
+		"@oh-my-pi/pi-natives": "18.13.3"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"
 	},
 	"engines": {
-		"bun": ">=1.3.14"
+		"bun": ">=1.4.4"
 	}
 }

package/src/acp/protocol.ts

@@ -102,6 +102,7 @@ export interface ToolCallLocation extends Meta {
 export interface ToolCall extends Meta {
 	toolCallId: ToolCallId;
 	title: string;
+	name?: string | null;
 	kind?: ToolKind | null;
 	status?: ToolCallStatus | null;
 	content?: ToolCallContent[] | null;

package/src/ar/tar.ts

@@ -16,7 +16,7 @@ import {
 	normalizeArchiveEntryPath,
 	normalizeArchiveLookupPath,
 } from "./paths";
-import { readAllBytes } from "./source";
+import type { ByteSource } from "./source";
 import type { ArchiveIndexEntry, FormatReader, FormatReadOptions, MemberSource } from "./types";
 
 const BLOCK_SIZE = 512;
@@ -53,8 +53,44 @@ interface PendingTarLink {
 	targetPath: string;
 }
 
+interface TarCursor {
+	readonly position: number;
+	read(length: number): Promise<Uint8Array>;
+	skip(length: number): Promise<boolean>;
+}
+
+/** Seek over plain tar payloads without fetching their bytes. */
+class TarSourceCursor implements TarCursor {
+	readonly #source: ByteSource;
+	#position = 0;
+
+	constructor(source: ByteSource) {
+		this.#source = source;
+	}
+
+	get position(): number {
+		return this.#position;
+	}
+
+	async read(length: number): Promise<Uint8Array> {
+		const size = Math.min(length, this.#source.size - this.#position);
+		if (size === 0) return new Uint8Array(0);
+		const end = this.#position + size;
+		const bytes = await this.#source.read(this.#position, end);
+		if (bytes.byteLength !== size) throw new ArchiveError("Invalid archive: truncated data");
+		this.#position = end;
+		return bytes;
+	}
+
+	async skip(length: number): Promise<boolean> {
+		if (length > this.#source.size - this.#position) return false;
+		this.#position += length;
+		return true;
+	}
+}
+
 /** Forward-only reader over tar bytes that arrive in chunks: one buffer, or a decompressing stream. */
-class TarByteStream {
+class TarByteStream implements TarCursor {
 	readonly #chunks: AsyncIterator<Uint8Array> | Iterator<Uint8Array>;
 	#chunk: Uint8Array = new Uint8Array(0);
 	#position = 0;
@@ -119,6 +155,27 @@ interface TarPayload {
 	read(offset: number, size: number, memberPath: string): Promise<Uint8Array>;
 }
 
+class TarSourcePayload implements TarPayload {
+	readonly #source: ByteSource;
+
+	constructor(source: ByteSource) {
+		this.#source = source;
+	}
+
+	async read(offset: number, size: number, memberPath: string): Promise<Uint8Array> {
+		try {
+			const bytes = await this.#source.read(offset, offset + size);
+			if (bytes.byteLength !== size) {
+				throw new ArchiveError(`Archive member '${formatArchivePathForError(memberPath)}' is truncated`);
+			}
+			return bytes;
+		} catch (error) {
+			if (error instanceof ArchiveError) throw error;
+			throw new ArchiveError(error instanceof Error ? error.message : "Failed to read tar member");
+		}
+	}
+}
+
 class TarBufferPayload implements TarPayload {
 	readonly #buffer: Uint8Array;
 
@@ -533,7 +590,7 @@ function resolvePendingLinks(
 
 /** Read one metadata record's payload, bounded by `maxIndexSize`, and step over its padding. */
 async function readTarMetadata(
-	stream: TarByteStream,
+	stream: TarCursor,
 	size: number,
 	limits: ArchiveLimits,
 	what: string,
@@ -551,7 +608,7 @@ async function readTarMetadata(
  * stepped over, never held: entries point into `payload` by stream offset.
  */
 async function readTarEntries(
-	stream: TarByteStream,
+	stream: TarCursor,
 	payload: TarPayload,
 	options: FormatReadOptions,
 ): Promise<ArchiveIndexEntry[]> {
@@ -737,18 +794,17 @@ export async function readTarEntriesFromStream(
 	}
 }
 
-/** Read and index a tar source after one bounded whole-stream read. */
+/** Index a plain tar by ranging over headers and retaining lazy member offsets. */
 export const readTar: FormatReader = async (source, options) => {
-	assertInMemorySize(source.size, options.limits);
-	let bytes: Uint8Array;
+	if (!Number.isSafeInteger(source.size) || source.size < 0) {
+		throw new ArchiveError("Archive is too large to read safely");
+	}
 	try {
-		bytes = await readAllBytes(source);
+		return await readTarEntries(new TarSourceCursor(source), new TarSourcePayload(source), options);
 	} catch (error) {
 		if (error instanceof ArchiveError) throw error;
 		throw new ArchiveError(error instanceof Error ? error.message : "Failed to read tar archive");
 	}
-	if (bytes.byteLength !== source.size) throw new ArchiveError("Invalid archive: truncated data");
-	return readTarEntriesFromBuffer(bytes, options);
 };
 
 /** Detect a tar header, including legacy pre-ustar archives, by its checksum. */

package/src/ar/types.ts

@@ -37,7 +37,7 @@ export type WritableArchiveFormat = "zip" | "tar" | "tar.gz" | "tar.zst" | "asar
  * Where to read an archive from: an extension-inferred filesystem path, a
  * format-tagged filesystem path, in-memory bytes, or any caller-provided
  * {@link ByteSource} (e.g. `httpByteSource` for ranged remote reads).
- * File- and source-backed ZIP/ASAR/RAR/7z/ISO are read lazily.
+ * File- and source-backed TAR/ZIP/ASAR/RAR/7z/ISO are read lazily.
  */
 export type ArchiveSource =
 	| string

package/src/index.ts

@@ -10,7 +10,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";

package/src/json.ts

@@ -9,6 +9,31 @@ export function tryParseJson<T = unknown>(content: string): T | null {
 	}
 }
 
+/**
+ * Index just past the JSON object or array that opens at `text[start]`, or -1
+ * when it does not close within `text`. String literals are skipped, honoring
+ * escapes, so brackets inside values do not count. Malformed input yields some
+ * end that a parser then rejects.
+ */
+export function jsonContainerEnd(text: string, start: number): number {
+	let depth = 0;
+	for (let index = start; index < text.length; index++) {
+		const code = text.charCodeAt(index);
+		if (code === 0x22) {
+			for (index++; index < text.length; index++) {
+				const inner = text.charCodeAt(index);
+				if (inner === 0x5c) index++;
+				else if (inner === 0x22) break;
+			}
+		} else if (code === 0x7b || code === 0x5b) {
+			depth++;
+		} else if ((code === 0x7d || code === 0x5d) && --depth === 0) {
+			return index + 1;
+		}
+	}
+	return -1;
+}
+
 /**
  * Serialize JSON while preserving bigint precision as decimal strings.
  *

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/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/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);
-}