@oh-my-pi/pi-utils 16.3.9 → 16.3.11

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [16.3.10] - 2026-07-06
+
+### Added
+
+- Added `postmortem.markExpectedCleanupError()` / `postmortem.isExpectedCleanupError()` to tag errors thrown by routine resource teardown; the global `uncaughtException`/`unhandledRejection` handlers downgrade marked errors (walking the `cause` chain) to warnings instead of exiting the process.
+
+### Fixed
+
+- Bounded postmortem cleanup with a 10s deadline so a hanging cleanup callback can no longer wedge the process indefinitely after a fatal error or signal; the process now always reaches `process.exit`.
+
 ## [16.3.7] - 2026-07-05
 
 ### Added

package/dist/types/postmortem.d.ts

@@ -16,6 +16,21 @@ export declare enum Reason {
  * swallow at the global `unhandledRejection` level. See issue #2997.
  */
 export declare function isIpcSendEpipe(err: Error): boolean;
+/**
+ * Mark an error as expected cleanup fallout so the global fatal handlers
+ * downgrade it to a log line instead of tearing down the process. Use for
+ * abort reasons fired by routine resource teardown (browser run end, tab
+ * close) whose rejections may surface on fire-and-forget promises with no
+ * consumer. Returns the same error for inline use at the `abort()` callsite.
+ */
+export declare function markExpectedCleanupError<T extends object>(reason: T): T;
+/**
+ * Whether `reason` (or any error in its `cause` chain) was marked via
+ * {@link markExpectedCleanupError}. Walks the chain because the unhandled
+ * reason is often a wrapper (`AbortError`) with the marked abort reason as
+ * its `cause`.
+ */
+export declare function isExpectedCleanupError(reason: unknown): boolean;
 /**
  * Register a process cleanup callback, to be run on shutdown, signal, or fatal error.
  *

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "16.3.9",
+	"version": "16.3.11",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -31,7 +31,7 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "16.3.9",
+		"@oh-my-pi/pi-natives": "16.3.11",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",
 		"winston-daily-rotate-file": "^5.0.0"

package/src/postmortem.ts

@@ -25,6 +25,7 @@ export enum Reason {
 const callbackList: ((reason: Reason) => Promise<void> | void)[] = [];
 // Tracks cleanup run state (to prevent recursion/reentry issues)
 let cleanupStage: "idle" | "running" | "complete" = "idle";
+const CLEANUP_DEADLINE_MS = 10_000;
 
 /**
  * Internal: runs all registered cleanup callbacks for the given reason.
@@ -49,7 +50,7 @@ function runCleanup(reason: Reason): Promise<void> {
 		return Promise.try(() => callback(reason));
 	});
 
-	return Promise.allSettled(promises).then(results => {
+	const cleanupSettled = Promise.allSettled(promises).then(results => {
 		for (const result of results) {
 			if (result.status === "rejected") {
 				const err = result.reason instanceof Error ? result.reason : new Error(String(result.reason));
@@ -58,6 +59,16 @@ function runCleanup(reason: Reason): Promise<void> {
 		}
 		cleanupStage = "complete";
 	});
+	const deadline = Promise.withResolvers<void>();
+	const deadlineTimer = setTimeout(() => {
+		logger.error("Cleanup deadline exceeded; proceeding with exit", { reason });
+		cleanupStage = "complete";
+		deadline.resolve();
+	}, CLEANUP_DEADLINE_MS);
+	deadlineTimer.unref();
+	return Promise.race([cleanupSettled, deadline.promise]).finally(() => {
+		clearTimeout(deadlineTimer);
+	});
 }
 
 // Register signal and error event handlers to trigger cleanup before exit.
@@ -78,6 +89,38 @@ export function isIpcSendEpipe(err: Error): boolean {
 	return code === "EPIPE" && syscall === "send";
 }
 
+// Well-known key marking an error as an *expected* teardown artifact (e.g. a
+// browser run-scope abort at normal run end). `Symbol.for` so the marker
+// survives duplicate module instances across bundles/realms.
+const EXPECTED_CLEANUP = Symbol.for("omp.expectedCleanupError");
+
+/**
+ * Mark an error as expected cleanup fallout so the global fatal handlers
+ * downgrade it to a log line instead of tearing down the process. Use for
+ * abort reasons fired by routine resource teardown (browser run end, tab
+ * close) whose rejections may surface on fire-and-forget promises with no
+ * consumer. Returns the same error for inline use at the `abort()` callsite.
+ */
+export function markExpectedCleanupError<T extends object>(reason: T): T {
+	(reason as Record<PropertyKey, unknown>)[EXPECTED_CLEANUP] = true;
+	return reason;
+}
+
+/**
+ * Whether `reason` (or any error in its `cause` chain) was marked via
+ * {@link markExpectedCleanupError}. Walks the chain because the unhandled
+ * reason is often a wrapper (`AbortError`) with the marked abort reason as
+ * its `cause`.
+ */
+export function isExpectedCleanupError(reason: unknown): boolean {
+	let current: unknown = reason;
+	for (let depth = 0; depth < 8 && current !== null && typeof current === "object"; depth++) {
+		if ((current as Record<PropertyKey, unknown>)[EXPECTED_CLEANUP] === true) return true;
+		current = (current as { cause?: unknown }).cause;
+	}
+	return false;
+}
+
 function formatFatalError(label: string, err: Error): string {
 	const name = err.name || "Error";
 	const message = err.message || "(no message)";
@@ -101,6 +144,10 @@ if (isMainThread) {
 			process.stderr.write(`Inspector opened: ${url}\n`);
 		})
 		.on("uncaughtException", async err => {
+			if (isExpectedCleanupError(err)) {
+				logger.warn("Ignoring expected cleanup exception", { err });
+				return;
+			}
 			process.stderr.write(formatFatalError("Uncaught Exception", err));
 			logger.error("Uncaught exception", { err });
 			await runCleanup(Reason.UNCAUGHT_EXCEPTION);
@@ -121,6 +168,10 @@ if (isMainThread) {
 				logger.warn("Ignoring EPIPE from worker IPC send; optional subsystem will self-recover", { err });
 				return;
 			}
+			if (isExpectedCleanupError(reason)) {
+				logger.warn("Ignoring expected cleanup rejection", { err });
+				return;
+			}
 			process.stderr.write(formatFatalError("Unhandled Rejection", err));
 			logger.error("Unhandled rejection", { err });
 			await runCleanup(Reason.UNHANDLED_REJECTION);