@linxiraos/pi-utils 1.4.6 → 1.4.9

package/src/postmortem.ts

@@ -10,6 +10,7 @@ import * as fs from "node:fs";
 import { APP_NAME, CLI_BIN_NAME } from "./dirs";
 import * as logger from "./logger";
 import { restoreTerminalStderr } from "./stderr-guard";
+import { toError } from "./type-guards";
 
 // Cleanup reasons, in order of priority/meaning.
 export enum Reason {
@@ -276,7 +277,7 @@ function runCleanup(reason: Reason, keepAlive = false): Promise<void> {
 	const cleanupSettled = Promise.allSettled(promises).then(async results => {
 		for (const result of results) {
 			if (result.status === "rejected") {
-				const err = result.reason instanceof Error ? result.reason : new Error(String(result.reason));
+				const err = toError(result.reason);
 				logger.error("Cleanup callback failed", { err, stack: err.stack });
 			}
 		}
@@ -307,9 +308,7 @@ function runCleanup(reason: Reason, keepAlive = false): Promise<void> {
 	return cleanupPromise;
 }
 
-// Register signal and error event handlers to trigger cleanup before exit.
-// Main thread: full signal handling (SIGINT, SIGTERM, SIGHUP) + exceptions + exit
-// Worker thread: exit only (workers use self.addEventListener for exceptions)
+// CLI-owned main threads handle signals and fatal errors; workers handle exit only.
 let inspectorOpened = false;
 
 /** Origin of an EPIPE raised by a process communication channel. */
@@ -558,13 +557,47 @@ export function isExpectedCleanupError(reason: unknown): boolean {
 /** Interceptors consulted by the global `unhandledRejection` handler before the fatal path. */
 const rejectionInterceptors = new Set<(reason: unknown) => boolean>();
 
+function interceptRejection(reason: unknown): boolean {
+	for (const interceptor of rejectionInterceptors) {
+		try {
+			if (interceptor(reason)) return true;
+		} catch (interceptorErr) {
+			logger.warn("Unhandled-rejection interceptor threw; continuing with fatal path", { err: interceptorErr });
+		}
+	}
+	return false;
+}
+
+/**
+ * Without the CLI's handlers (SDK embedding), interceptors still need a listener. It exists only while
+ * interceptors do, and rethrows what none consumes unless the host listens too, keeping Bun's default.
+ */
+let embeddedRejectionListener: ((reason: unknown) => void) | undefined;
+
 /**
  * Register an interceptor consulted before an unhandled rejection tears the
  * process down. A consuming interceptor owns reporting and keeps the process alive.
  */
 export function interceptUnhandledRejections(interceptor: (reason: unknown) => boolean): () => void {
 	rejectionInterceptors.add(interceptor);
-	return () => rejectionInterceptors.delete(interceptor);
+	if (!processHandlersInstalled && Bun.isMainThread && !embeddedRejectionListener) {
+		const listener = (reason: unknown) => {
+			if (interceptRejection(reason) || process.listenerCount("unhandledRejection") > 1) return;
+			throw reason;
+		};
+		embeddedRejectionListener = listener;
+		process.on("unhandledRejection", listener);
+	}
+	return () => {
+		rejectionInterceptors.delete(interceptor);
+		if (rejectionInterceptors.size === 0) removeEmbeddedRejectionListener();
+	};
+}
+
+function removeEmbeddedRejectionListener(): void {
+	if (!embeddedRejectionListener) return;
+	process.off("unhandledRejection", embeddedRejectionListener);
+	embeddedRejectionListener = undefined;
 }
 
 /**
@@ -676,7 +709,7 @@ function handleWorkerSendEpipe(err: Error): boolean {
  * 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 err = toError(error);
 	const report = `${Bun.inspect(error, { colors: process.stderr.isTTY === true })}\n`;
 	if (!Bun.isMainThread) {
 		process.stderr.write(`${report}${formatFatalRecoveryHints(fatalRecoveryHintProviders)}`);
@@ -685,7 +718,22 @@ export async function fatal(error: unknown): Promise<never> {
 	return exitAfterFatal(report, "Fatal error", err, Reason.UNHANDLED_REJECTION);
 }
 
-if (Bun.isMainThread) {
+// Exit-time cleanup is safe in any host: it neither delays nor triggers an exit. Signal and fatal
+// handlers change the process lifecycle, so only {@link installProcessHandlers} adds them.
+process.on("exit", () => {
+	void runCleanup(Reason.EXIT); // fire and forget (exit imminent)
+});
+
+let processHandlersInstalled = false;
+
+/** Installs OMP's process-wide signal and fatal handlers for a CLI-owned process. */
+export function installProcessHandlers(): void {
+	if (processHandlersInstalled) return;
+	processHandlersInstalled = true;
+	removeEmbeddedRejectionListener();
+	// Workers report failures through their own error listeners to the parent.
+	if (!Bun.isMainThread) return;
+
 	process
 		.on("SIGINT", async () => {
 			await runCleanup(Reason.SIGINT);
@@ -706,7 +754,7 @@ if (Bun.isMainThread) {
 				logger.warn("Ignoring expected cleanup exception", { err: thrown });
 				return;
 			}
-			const err = thrown instanceof Error ? thrown : new Error(String(thrown));
+			const err = toError(thrown);
 			// 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.
@@ -739,21 +787,13 @@ if (Bun.isMainThread) {
 			);
 		})
 		.on("unhandledRejection", async reason => {
-			const err = reason instanceof Error ? reason : new Error(String(reason));
+			const err = toError(reason);
 			if (handleWorkerSendEpipe(err)) return;
 			if (isExpectedCleanupError(reason)) {
 				logger.warn("Ignoring expected cleanup rejection", { err });
 				return;
 			}
-			for (const interceptor of rejectionInterceptors) {
-				try {
-					if (interceptor(reason)) return;
-				} catch (interceptorErr) {
-					logger.warn("Unhandled-rejection interceptor threw; continuing with fatal path", {
-						err: interceptorErr,
-					});
-				}
-			}
+			if (interceptRejection(reason)) return;
 			await exitAfterFatal(
 				formatFatalError("Unhandled Rejection", err),
 				"Unhandled rejection",
@@ -761,9 +801,6 @@ if (Bun.isMainThread) {
 				Reason.UNHANDLED_REJECTION,
 			);
 		})
-		.on("exit", async () => {
-			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
@@ -777,14 +814,6 @@ if (Bun.isMainThread) {
 			await runCleanup(Reason.SIGHUP);
 			exitProcess(129); // 128 + SIGHUP (1)
 		});
-} else {
-	// Worker thread: only register exit handler for cleanup.
-	// DO NOT register uncaughtException/unhandledRejection handlers here -
-	// they would swallow errors before the worker's own handlers (self.addEventListener)
-	// can report failures back to the parent thread.
-	process.on("exit", () => {
-		void runCleanup(Reason.EXIT);
-	});
 }
 
 /** Controls when a registered cleanup callback participates in cleanup passes. */
@@ -811,8 +840,7 @@ export interface CleanupRegistrationOptions {
 }
 
 /**
- * Registers a cleanup callback for shutdown, signals, fatal errors, and
- * repeatable manual cleanup passes.
+ * Registers a cleanup callback for manual passes and, when installed, process shutdown.
  *
  * Registrations persist across keep-alive {@link cleanup} passes and run at
  * most once per pass. Set `exitOnly` for resources the continuing process still
@@ -849,7 +877,7 @@ export function register(
 			const pending = invokeCleanup(registration, reason, keepAlive, cleanupPass);
 			if (!pending) return;
 			const tracked = pending.catch(error => {
-				const err = error instanceof Error ? error : new Error(String(error));
+				const err = toError(error);
 				logger.error("Cleanup callback failed", { err, id, stack: err.stack });
 			});
 			// Join the active pass so cleanup()/signal exits await it; after a
@@ -859,7 +887,7 @@ export function register(
 				activePassDeadline?.extend(tracked, registration.deadlineMs, registration.waitMessage);
 			}
 		} catch (error) {
-			const err = error instanceof Error ? error : new Error(String(error));
+			const err = toError(error);
 			logger.error("Cleanup callback failed", { err, id, stack: err.stack });
 		}
 	};

package/src/runtime-install.ts

@@ -4,6 +4,7 @@ import * as Module from "node:module";
 import * as path from "node:path";
 import { withFileLock } from "./file-lock";
 import { isEexist, isEnoent } from "./fs-error";
+import { isRecord } from "./type-guards";
 
 /**
  * On-demand runtime dependency support for native-heavy optional packages
@@ -32,10 +33,6 @@ const RUNTIME_CONDITIONS: Record<string, true> = { node: true, require: true, de
 /** Extension probes appended to a `main`/`exports` target that lacks one. */
 const RUNTIME_EXTENSIONS: readonly string[] = [".js", ".cjs", ".mjs", ".json", ".node"];
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /**
  * Walk a conditional `exports` target (string, array of fallbacks, or a
  * condition object) and return the first relative path that matches a runtime

package/src/sqlite.ts

@@ -2,15 +2,43 @@
 import { Database } from "bun:sqlite";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { installSqliteLockShim } from "@linxiraos/pi-natives/sqlite-locks";
 import { getDbBusyTimeoutMs } from "./env";
 import { withFileLockSync } from "./file-lock";
 import { isEnoent } from "./fs-error";
+import { toError } from "./type-guards";
 import * as logger from "./logger";
 
 const BUSY_MAX_ATTEMPTS = 4;
 const BUSY_BASE_DELAY_MS = 100;
 const SQLITE_STORE_SUFFIXES = ["-wal", "-shm", "-journal", ""];
 
+let sqliteLockShimInstalled: boolean | undefined;
+
+/**
+ * Moves this process's SQLite locks onto open-file-description locks (Linux), once.
+ *
+ * SQLite's POSIX record locks belong to the process, so any close of another
+ * descriptor of a database or its `-shm` released them, including Bun's own file
+ * APIs and the bash tool's builtins; a peer omp then unlinked the WAL under the live
+ * connection (issue #15586). Call before the process opens its first database: a
+ * connection opened earlier keeps POSIX locks. Returns whether the shim is active; a
+ * Linux build where it cannot be installed (Bun's SQLite layout changed) logs a warning
+ * once, and callers with a UI surface it.
+ */
+export function ensureSqliteLockShim(): boolean {
+	if (sqliteLockShimInstalled === undefined) {
+		sqliteLockShimInstalled = installSqliteLockShim();
+		if (!sqliteLockShimInstalled && process.platform === "linux") {
+			logger.warn("SQLite OFD lock shim unavailable; in-process reads of a live store can release its locks", {
+				bun: Bun.version,
+				issue: "https://github.com/can1357/oh-my-pi/issues/15586",
+			});
+		}
+	}
+	return sqliteLockShimInstalled;
+}
+
 /**
  * A store's identity as `dev:ino:birthtimeMs`, `null` when the path holds no
  * file, or `undefined` when the stat itself failed and no conclusion is safe.
@@ -100,7 +128,7 @@ function closeFailedDatabase(db: Database | undefined, error: unknown, identity:
 	try {
 		db?.close();
 	} catch (closeError) {
-		const original = error instanceof Error ? error : new Error(String(error));
+		const original = toError(error);
 		const detail = closeError instanceof Error ? closeError.message : String(closeError);
 		original.message += `; failed to close the SQLite handle: ${detail}`;
 		throw new SqliteAttemptFailure(original, identity, { canRecover: false });
@@ -152,6 +180,7 @@ async function openWithBusyRetries<T>(
 		let db: Database | undefined;
 		const identity = sqliteFileIdentity(dbPath);
 		try {
+			ensureSqliteLockShim();
 			db = new Database(dbPath);
 			// WAL recovery can bypass the busy handler; both it and retries are needed (#2421).
 			db.run(`PRAGMA busy_timeout = ${getDbBusyTimeoutMs()}`);
@@ -175,6 +204,7 @@ function openOnce<T>(dbPath: string, initialize: (db: Database) => T, options: S
 	let db: Database | undefined;
 	const identity = sqliteFileIdentity(dbPath);
 	try {
+		ensureSqliteLockShim();
 		db = new Database(dbPath);
 		db.run(`PRAGMA busy_timeout = ${getDbBusyTimeoutMs()}`);
 		return initialize(db);
@@ -333,7 +363,7 @@ export function openSqliteDatabaseSync<T>(
 
 /** Adds the failing store's path to an error without losing SQLite result codes or its original stack. */
 export function annotateSqliteError(error: unknown, dbPath: string): Error {
-	const annotated = error instanceof Error ? error : new Error(String(error));
+	const annotated = toError(error);
 	annotated.message = `Database "${dbPath}": ${annotated.message}`;
 	return annotated;
 }

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