@oh-my-pi/pi-utils 17.2.3 → 17.2.5

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [17.2.5] - 2026-08-03
+
+### Added
+
+- Added utility functions `parseFlag()`, `getBrowserRelayDir()`, and `getGlobalDaemonRuntimeDir()` to support browser relay mode and global daemon runtime directory resolution.
+
+### Changed
+
+- Updated the lightweight CLI runner to support static command metadata, allowing root help to render without importing full command implementations.
+
+## [17.2.4] - 2026-08-01
+
+### Added
+
+- Added `getSecretPlaceholderKeyPath()`, `getDaemonRuntimeDir()`, `getProviderInFlightRoot()`, and `getMarketplacesRegistryPath()` to resolve secret key, daemon runtime, provider in-flight, and marketplace registry paths under their respective XDG categories (state, data) instead of the config root.
+- Existing installs enabling XDG keep their data: a legacy `~/.omp/agent/secret-placeholder.key` or `~/.omp/marketplaces.json` is copied to its XDG location on first resolution, so persisted transcripts still deobfuscate and added marketplaces survive the move.
+
+### Changed
+
+- Headless hosts (print/RPC/ACP/eval/SDK) now use a 1s SQLite `busy_timeout` for the session-critical databases (agent.db, history.db, stats.db) via `getDbBusyTimeoutMs()`, so lock contention no longer freezes the protocol loop for the full interactive 5s timeout; interactive hosts keep the 5s timeout.
+
+### Fixed
+
+- Fixed Bun test-runtime detection treating application-owned `NODE_ENV=test` and `BUN_ENV=test` values as test-runner signals ([#7261](https://github.com/can1357/oh-my-pi/issues/7261)).
+
 ## [17.2.1] - 2026-07-30
 
 ### Added

package/dist/types/cli.d.ts

@@ -70,22 +70,24 @@ export interface ParseOutput<F extends Record<string, FlagDescriptor> = Record<s
     args: ArgValues<A>;
     argv: string[];
 }
-export interface CommandCtor {
-    new (argv: string[], config: CliConfig): Command;
+export interface CommandMetadata {
     description?: string;
     hidden?: boolean;
-    strict?: boolean;
-    aliases?: string[];
-    examples?: string[];
     flags?: Record<string, FlagDescriptor>;
     args?: Record<string, ArgDescriptor>;
+    examples?: string[];
+}
+export interface CommandCtor extends CommandMetadata {
+    new (argv: string[], config: CliConfig): Command;
+    strict?: boolean;
+    aliases?: string[];
 }
 /** Configuration passed to every command instance and help renderers. */
-export interface CliConfig {
+export interface CliConfig<TCommand extends CommandMetadata = CommandCtor> {
     bin: string;
     version: string;
     /** All registered commands keyed by their canonical name. */
-    commands: Map<string, CommandCtor>;
+    commands: Map<string, TCommand>;
 }
 /** Minimal Command base matching the oclif surface we use. */
 export declare abstract class Command {
@@ -100,7 +102,7 @@ export declare abstract class Command {
     parse<C extends CommandCtor>(_Cmd: C): Promise<ParseOutput<NonNullable<C["flags"]> extends Record<string, FlagDescriptor> ? NonNullable<C["flags"]> : Record<string, FlagDescriptor>, NonNullable<C["args"]> extends Record<string, ArgDescriptor> ? NonNullable<C["args"]> : Record<string, ArgDescriptor>>>;
 }
 /** Render full root help: header, default command details, subcommand list. */
-export declare function renderRootHelp(config: CliConfig): void;
+export declare function renderRootHelp(config: CliConfig<CommandMetadata>): void;
 /** Build the single USAGE line for a command (without the leading label). */
 export declare function commandUsageLine(bin: string, id: string, Cmd: CommandCtor): string;
 /** Render help for a single command. */
@@ -109,6 +111,7 @@ export declare function renderCommandHelp(bin: string, id: string, Cmd: CommandC
 export interface CommandEntry {
     name: string;
     load: () => Promise<CommandCtor>;
+    help?: CommandMetadata;
     aliases?: string[];
 }
 export interface RunOptions {
@@ -116,8 +119,10 @@ export interface RunOptions {
     version: string;
     argv: string[];
     commands: CommandEntry[];
-    /** Custom help renderer. Receives fully-populated config. */
+    /** Custom help renderer with the fully loaded command constructors. */
     help?: (config: CliConfig) => Promise<void> | void;
+    /** Lightweight help renderer backed by static command metadata. */
+    metadataHelp?: (config: CliConfig<CommandMetadata>) => Promise<void> | void;
 }
 /**
  * Main entry point — replaces `run()` from @oclif/core.

package/dist/types/dirs.d.ts

@@ -153,6 +153,8 @@ export declare function getPythonEnvDir(): string;
 export declare function getPythonGatewayDir(): string;
 /** Get the puppeteer sandbox directory (~/.omp/puppeteer). */
 export declare function getPuppeteerDir(): string;
+/** Get the browser relay extension install directory (~/.omp/browser-relay). */
+export declare function getBrowserRelayDir(): string;
 /** Get DOCS_RS cache directory () */
 export declare function getDocsRsCacheDir(): string;
 /** Get the auto-QA grievances SQLite database path (~/.omp/autoqa.db; XDG: $XDG_DATA_HOME/omp/autoqa.db). */
@@ -237,6 +239,16 @@ export declare function getTerminalSessionsDir(agentDir?: string): string;
 export declare function getCrashLogPath(agentDir?: string): string;
 /** Get the debug log path (~/.omp/agent/omp-debug.log). */
 export declare function getDebugLogPath(agentDir?: string): string;
+/** Get the secret placeholder key path (~/.omp/agent/secret-placeholder.key; XDG default: $XDG_STATE_HOME/omp/secret-placeholder.key). Adopts a legacy key on first XDG resolution. */
+export declare function getSecretPlaceholderKeyPath(): string;
+/** Get the daemon runtime directory for a project (~/.omp/run/daemons/<hash>; XDG default: $XDG_STATE_HOME/omp/run/daemons/<hash>). */
+export declare function getDaemonRuntimeDir(projectDir: string): string;
+/** Get a profile-independent runtime directory for a machine-global daemon service. */
+export declare function getGlobalDaemonRuntimeDir(service: string): string;
+/** Get the provider in-flight root directory (~/.omp/run/provider-inflight; XDG default: $XDG_STATE_HOME/omp/run/provider-inflight). */
+export declare function getProviderInFlightRoot(): string;
+/** Get the marketplaces registry path (~/.omp/marketplaces.json; XDG default: $XDG_DATA_HOME/omp/marketplaces.json). Adopts a legacy registry on first XDG resolution. */
+export declare function getMarketplacesRegistryPath(): string;
 /** Get the project-level Python modules directory (.omp/modules). */
 export declare function getProjectModulesDir(cwd?: string): string;
 /** Get the project-level prompts directory (.omp/prompts). */

package/dist/types/env.d.ts

@@ -39,12 +39,31 @@ export declare const $env: Record<string, string>;
  * @returns The first environment variable value, or undefined if no value is found.
  */
 export declare function $pickenv(...keys: string[]): string | undefined;
+/**
+ * Read an environment variable by its EXACT, case-sensitive name.
+ *
+ * `process.env` / `Bun.env` lookups are case-insensitive on Windows (Node backs
+ * them with `uv_os_getenv`, Bun with a `CaseInsensitiveASCIIStringArrayHashMap`),
+ * so a lowercase literal like `public` silently resolves to a differently-cased
+ * system variable — Windows ships `PUBLIC=C:\Users\Public`. Enumerated keys are
+ * the only signal that preserves the real casing, so this trusts the lookup only
+ * when a key with identical casing is actually present. On POSIX (case-sensitive
+ * env) it is equivalent to a direct lookup.
+ *
+ * Use this instead of `process.env[name] ?? literal` wherever `name` may be a
+ * user-supplied literal (e.g. a stored API key) rather than a genuine env-var
+ * reference — otherwise the literal gets hijacked by a same-named system var.
+ *
+ * @param name - Environment variable name to look up.
+ * @param env - Environment source; defaults to `process.env`.
+ */
+export declare function $envExact(name: string, env?: Record<string, string | undefined>): string | undefined;
 /**
  * Parses a positive decimal integer from `$env[name]`.
  * Empty, invalid, NaN, zero, or negative values return `defaultValue`.
  */
 export declare function $envpos(name: string, defaultValue: number): number;
-/** True when `BUN_ENV` or `NODE_ENV` is the string `test`. */
+/** True when the process is an explicitly marked test child or Bun is running a test entrypoint. */
 export declare function isBunTestRuntime(): boolean;
 /**
  * True when real-terminal side effects must be suppressed: stdout escape/frame
@@ -77,6 +96,20 @@ export declare function isInteractiveHost(): boolean;
  * restore exact prior state. See {@link isInteractiveHost}.
  */
 export declare function setInteractiveHost(interactive: boolean): boolean;
+/**
+ * SQLite `busy_timeout` for the session-critical databases (agent.db,
+ * history.db, stats.db).
+ *
+ * Interactive hosts tolerate a longer synchronous wait on lock contention
+ * (SQLITE_BUSY during WAL recovery/checkpoint — see oh-my-pi#2421): the
+ * operator sees a brief freeze and the statement eventually completes.
+ * Headless hosts (print/RPC/ACP/eval/SDK) run a protocol on the same thread —
+ * a multi-second synchronous busy-wait freezes their event loop and stalls
+ * every in-flight frame with no liveness signal, so they use a short timeout
+ * and rely on the existing asynchronous open/retry paths to recover from
+ * contention instead of blocking.
+ */
+export declare function getDbBusyTimeoutMs(): number;
 /**
  * True when this code is running inside a `bun build --compile` standalone
  * binary. Detects via the embedded virtual-filesystem path markers
@@ -86,4 +119,6 @@ export declare function setInteractiveHost(interactive: boolean): boolean;
  * first for cheap fast-path detection.
  */
 export declare function isCompiledBinary(): boolean;
+/** Parse a boolean-ish env value ("1", "yes", "on", …); `def` when unset/empty. */
+export declare function parseFlag(value: string | undefined, def?: boolean): boolean;
 export declare function $flag(name: string, def?: boolean): boolean;

package/dist/types/postmortem.d.ts

@@ -15,6 +15,18 @@ export declare enum Reason {
     UNHANDLED_REJECTION = "unhandled_rejection",// Unhandled promise rejection
     MANUAL = "manual"
 }
+/**
+ * Symbol stamped by the extension-load guard onto the throwing replacement it
+ * installs over `process.exit` / `process.reallyExit`, carrying the native
+ * primitive that replacement shadows.
+ *
+ * Host-owned shutdown ({@link exitProcess}) reads through it so a signal that
+ * lands while the guard is active still terminates the process (#6488), while
+ * a signal that lands after the guard has restored the native exit also
+ * terminates cleanly (#7393). `Symbol.for` so it survives duplicate module
+ * instances across bundles/realms.
+ */
+export declare const NATIVE_PROCESS_EXIT: unique symbol;
 /** Origin of an EPIPE raised by a process communication channel. */
 export type BrokenPipeSource = "ipc-send" | "stdio-write";
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "17.2.3",
+	"version": "17.2.5",
 	"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": "17.2.3",
+		"@oh-my-pi/pi-natives": "17.2.5",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",
 		"winston-daily-rotate-file": "5.0.0"

package/src/cli.ts

@@ -133,23 +133,26 @@ export interface ParseOutput<
 // Command base class
 // ---------------------------------------------------------------------------
 
-export interface CommandCtor {
-	new (argv: string[], config: CliConfig): Command;
+export interface CommandMetadata {
 	description?: string;
 	hidden?: boolean;
-	strict?: boolean;
-	aliases?: string[];
-	examples?: string[];
 	flags?: Record<string, FlagDescriptor>;
 	args?: Record<string, ArgDescriptor>;
+	examples?: string[];
+}
+
+export interface CommandCtor extends CommandMetadata {
+	new (argv: string[], config: CliConfig): Command;
+	strict?: boolean;
+	aliases?: string[];
 }
 
 /** Configuration passed to every command instance and help renderers. */
-export interface CliConfig {
+export interface CliConfig<TCommand extends CommandMetadata = CommandCtor> {
 	bin: string;
 	version: string;
 	/** All registered commands keyed by their canonical name. */
-	commands: Map<string, CommandCtor>;
+	commands: Map<string, TCommand>;
 }
 
 /** Minimal Command base matching the oclif surface we use. */
@@ -290,7 +293,7 @@ export abstract class Command {
 // ---------------------------------------------------------------------------
 
 /** Render full root help: header, default command details, subcommand list. */
-export function renderRootHelp(config: CliConfig): void {
+export function renderRootHelp(config: CliConfig<CommandMetadata>): void {
 	const { bin, version, commands } = config;
 	const lines: string[] = [];
 	lines.push(`${bin} v${version}\n`);
@@ -299,7 +302,7 @@ export function renderRootHelp(config: CliConfig): void {
 
 	// Show the default command's flags/args/examples inline.
 	// The default command is the one marked hidden (it's the implicit entry point).
-	const defaultCmd = [...commands.values()].find(C => C.hidden);
+	const defaultCmd = [...commands.values()].find(command => command.hidden);
 	if (defaultCmd) {
 		renderCommandBody(lines, defaultCmd);
 	}
@@ -309,8 +312,8 @@ export function renderRootHelp(config: CliConfig): void {
 	if (visible.length > 0) {
 		lines.push("COMMANDS");
 		const maxLen = Math.max(...visible.map(([n]) => n.length));
-		for (const [name, C] of visible.sort((a, b) => a[0].localeCompare(b[0]))) {
-			lines.push(`  ${name.padEnd(maxLen + 2)}${C.description ?? ""}`);
+		for (const [name, command] of visible.sort((a, b) => a[0].localeCompare(b[0]))) {
+			lines.push(`  ${name.padEnd(maxLen + 2)}${command.description ?? ""}`);
 		}
 		lines.push("");
 	}
@@ -350,9 +353,9 @@ export function renderCommandHelp(bin: string, id: string, Cmd: CommandCtor): vo
 	process.stdout.write(lines.join("\n"));
 }
 
-function renderCommandBody(lines: string[], Cmd: CommandCtor): void {
-	const argDefs = Cmd.args ?? {};
-	const flagDefs = Cmd.flags ?? {};
+function renderCommandBody(lines: string[], command: CommandMetadata): void {
+	const argDefs = command.args ?? {};
+	const flagDefs = command.flags ?? {};
 
 	// Arguments
 	const argEntries = Object.entries(argDefs);
@@ -387,9 +390,9 @@ function renderCommandBody(lines: string[], Cmd: CommandCtor): void {
 	}
 
 	// Examples
-	if (Cmd.examples && Cmd.examples.length > 0) {
+	if (command.examples && command.examples.length > 0) {
 		lines.push("EXAMPLES");
-		for (const ex of Cmd.examples) {
+		for (const ex of command.examples) {
 			for (const line of ex.split("\n")) {
 				lines.push(`  ${line}`);
 			}
@@ -406,6 +409,7 @@ function renderCommandBody(lines: string[], Cmd: CommandCtor): void {
 export interface CommandEntry {
 	name: string;
 	load: () => Promise<CommandCtor>;
+	help?: CommandMetadata;
 	aliases?: string[];
 }
 
@@ -414,8 +418,10 @@ export interface RunOptions {
 	version: string;
 	argv: string[];
 	commands: CommandEntry[];
-	/** Custom help renderer. Receives fully-populated config. */
+	/** Custom help renderer with the fully loaded command constructors. */
 	help?: (config: CliConfig) => Promise<void> | void;
+	/** Lightweight help renderer backed by static command metadata. */
+	metadataHelp?: (config: CliConfig<CommandMetadata>) => Promise<void> | void;
 }
 
 /** Find a command entry by exact name or alias. */
@@ -437,11 +443,15 @@ export async function run(opts: RunOptions): Promise<void> {
 
 	// Top-level help
 	if (commandId === "--help" || commandId === "-h" || commandId === "help" || commandId === "") {
-		const config = await loadAllCommands(opts);
 		if (opts.help) {
-			await opts.help(config);
+			await opts.help(await loadAllCommands(opts));
 		} else {
-			renderRootHelp(config);
+			const config = await loadAllCommandMetadata(opts);
+			if (opts.metadataHelp) {
+				await opts.metadataHelp(config);
+			} else {
+				renderRootHelp(config);
+			}
 		}
 		return;
 	}
@@ -504,12 +514,16 @@ async function loadEntry(entry: CommandEntry): Promise<CommandCtor> {
 	return Cmd;
 }
 
-/** Resolve all command loaders for help/alias display. */
+/** Load every command constructor for backward-compatible custom help callbacks. */
 async function loadAllCommands(opts: RunOptions): Promise<CliConfig> {
-	const commands = new Map<string, CommandCtor>();
-	const loaded = await Promise.all(opts.commands.map(async e => [e.name, await loadEntry(e)] as const));
-	for (const [name, Cmd] of loaded) {
-		commands.set(name, Cmd);
-	}
-	return { bin: opts.bin, version: opts.version, commands };
+	const loaded = await Promise.all(opts.commands.map(async entry => [entry.name, await loadEntry(entry)] as const));
+	return { bin: opts.bin, version: opts.version, commands: new Map(loaded) };
+}
+
+/** Resolve static command metadata for lightweight root help. */
+async function loadAllCommandMetadata(opts: RunOptions): Promise<CliConfig<CommandMetadata>> {
+	const loaded = await Promise.all(
+		opts.commands.map(async entry => [entry.name, entry.help ?? (await loadEntry(entry))] as const),
+	);
+	return { bin: opts.bin, version: opts.version, commands: new Map(loaded) };
 }

package/src/dirs.ts

@@ -627,6 +627,11 @@ export function getPuppeteerDir(): string {
 	return dirs.rootSubdir("puppeteer", "cache");
 }
 
+/** Get the browser relay extension install directory (~/.omp/browser-relay). */
+export function getBrowserRelayDir(): string {
+	return dirs.rootSubdir("browser-relay", "data");
+}
+
 /** Get DOCS_RS cache directory () */
 export function getDocsRsCacheDir(): string {
 	return dirs.rootSubdir("webcache", "cache");
@@ -820,6 +825,58 @@ export function getDebugLogPath(agentDir?: string): string {
 	return dirs.agentSubdir(agentDir, `${APP_NAME}-debug.log`, "state");
 }
 
+/**
+ * Best-effort one-time copy of a legacy config-root file to its redirected XDG
+ * location. Existing installs that enable XDG after the file was created keep
+ * their data (e.g. a placeholder key whose loss would break deobfuscation of
+ * persisted transcripts). The legacy file is left in place for older omp
+ * versions sharing the profile.
+ */
+function adoptLegacyFile(legacyPath: string, targetPath: string): void {
+	if (targetPath === legacyPath) return;
+	try {
+		if (fs.existsSync(targetPath) || !fs.existsSync(legacyPath)) return;
+		fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+		fs.copyFileSync(legacyPath, targetPath, fs.constants.COPYFILE_EXCL);
+	} catch {
+		// Opportunistic: a copy race or unwritable XDG dir falls back to a fresh
+		// file at the new path — the pre-adoption behavior.
+	}
+}
+
+/** Get the secret placeholder key path (~/.omp/agent/secret-placeholder.key; XDG default: $XDG_STATE_HOME/omp/secret-placeholder.key). Adopts a legacy key on first XDG resolution. */
+export function getSecretPlaceholderKeyPath(): string {
+	const keyPath = dirs.agentSubdir(undefined, "secret-placeholder.key", "state");
+	adoptLegacyFile(path.join(dirs.agentDir, "secret-placeholder.key"), keyPath);
+	return keyPath;
+}
+
+/** Get the daemon runtime directory for a project (~/.omp/run/daemons/<hash>; XDG default: $XDG_STATE_HOME/omp/run/daemons/<hash>). */
+export function getDaemonRuntimeDir(projectDir: string): string {
+	const key = Bun.hash.wyhash(path.resolve(projectDir)).toString(16).padStart(16, "0");
+	return dirs.rootSubdir(path.join("run", "daemons", key), "state");
+}
+
+/** Get a profile-independent runtime directory for a machine-global daemon service. */
+export function getGlobalDaemonRuntimeDir(service: string): string {
+	if (!/^[a-z0-9][a-z0-9._-]*$/i.test(service)) {
+		throw new Error(`Invalid global daemon service name: ${JSON.stringify(service)}`);
+	}
+	return path.join(getBaseConfigRoot(), "run", "daemons", "global", service);
+}
+
+/** Get the provider in-flight root directory (~/.omp/run/provider-inflight; XDG default: $XDG_STATE_HOME/omp/run/provider-inflight). */
+export function getProviderInFlightRoot(): string {
+	return dirs.rootSubdir(path.join("run", "provider-inflight"), "state");
+}
+
+/** Get the marketplaces registry path (~/.omp/marketplaces.json; XDG default: $XDG_DATA_HOME/omp/marketplaces.json). Adopts a legacy registry on first XDG resolution. */
+export function getMarketplacesRegistryPath(): string {
+	const registryPath = dirs.rootSubdir("marketplaces.json", "data");
+	adoptLegacyFile(path.join(dirs.configRoot, "marketplaces.json"), registryPath);
+	return registryPath;
+}
+
 // =============================================================================
 // Project subdirectories (.omp/*)
 // =============================================================================

package/src/env.ts

@@ -246,6 +246,35 @@ export function $pickenv(...keys: string[]): string | undefined {
 	return undefined;
 }
 
+/**
+ * Read an environment variable by its EXACT, case-sensitive name.
+ *
+ * `process.env` / `Bun.env` lookups are case-insensitive on Windows (Node backs
+ * them with `uv_os_getenv`, Bun with a `CaseInsensitiveASCIIStringArrayHashMap`),
+ * so a lowercase literal like `public` silently resolves to a differently-cased
+ * system variable — Windows ships `PUBLIC=C:\Users\Public`. Enumerated keys are
+ * the only signal that preserves the real casing, so this trusts the lookup only
+ * when a key with identical casing is actually present. On POSIX (case-sensitive
+ * env) it is equivalent to a direct lookup.
+ *
+ * Use this instead of `process.env[name] ?? literal` wherever `name` may be a
+ * user-supplied literal (e.g. a stored API key) rather than a genuine env-var
+ * reference — otherwise the literal gets hijacked by a same-named system var.
+ *
+ * @param name - Environment variable name to look up.
+ * @param env - Environment source; defaults to `process.env`.
+ */
+export function $envExact(name: string, env: Record<string, string | undefined> = process.env): string | undefined {
+	const value = env[name];
+	if (value === undefined) return undefined;
+	// Enumeration preserves real key casing on Windows, unlike the getter; the
+	// value is trusted only when an exact-case entry actually exists.
+	for (const key in env) {
+		if (key === name) return value;
+	}
+	return undefined;
+}
+
 /**
  * Parses a positive decimal integer from `$env[name]`.
  * Empty, invalid, NaN, zero, or negative values return `defaultValue`.
@@ -258,9 +287,13 @@ export function $envpos(name: string, defaultValue: number): number {
 	return parsed;
 }
 
-/** True when `BUN_ENV` or `NODE_ENV` is the string `test`. */
+const BUN_TEST_ENTRY_PATTERN = /[._](?:test|spec)\.[cm]?[jt]sx?$/;
+
+/** True when the process is an explicitly marked test child or Bun is running a test entrypoint. */
 export function isBunTestRuntime(): boolean {
-	return Bun.env.BUN_ENV === "test" || Bun.env.NODE_ENV === "test";
+	if (Bun.env.PI_TEST_RUNTIME === "1") return true;
+	const hasTestEnvironment = Bun.env.BUN_ENV === "test" || Bun.env.NODE_ENV === "test";
+	return hasTestEnvironment && BUN_TEST_ENTRY_PATTERN.test(Bun.main);
 }
 
 let terminalHeadless = isBunTestRuntime();
@@ -314,6 +347,23 @@ export function setInteractiveHost(interactive: boolean): boolean {
 	return previous;
 }
 
+/**
+ * SQLite `busy_timeout` for the session-critical databases (agent.db,
+ * history.db, stats.db).
+ *
+ * Interactive hosts tolerate a longer synchronous wait on lock contention
+ * (SQLITE_BUSY during WAL recovery/checkpoint — see oh-my-pi#2421): the
+ * operator sees a brief freeze and the statement eventually completes.
+ * Headless hosts (print/RPC/ACP/eval/SDK) run a protocol on the same thread —
+ * a multi-second synchronous busy-wait freezes their event loop and stalls
+ * every in-flight frame with no liveness signal, so they use a short timeout
+ * and rely on the existing asynchronous open/retry paths to recover from
+ * contention instead of blocking.
+ */
+export function getDbBusyTimeoutMs(): number {
+	return isInteractiveHost() ? 5000 : 1000;
+}
+
 /**
  * True when this code is running inside a `bun build --compile` standalone
  * binary. Detects via the embedded virtual-filesystem path markers
@@ -339,8 +389,12 @@ const TRUTHY: Dict<boolean> = {
 	ON: true,
 	on: true,
 };
-export function $flag(name: string, def: boolean = false): boolean {
-	const value = $env[name];
+/** Parse a boolean-ish env value ("1", "yes", "on", …); `def` when unset/empty. */
+export function parseFlag(value: string | undefined, def = false): boolean {
 	if (!value) return def;
 	return TRUTHY[value] === true;
 }
+
+export function $flag(name: string, def: boolean = false): boolean {
+	return parseFlag($env[name], def);
+}

package/src/postmortem.ts

@@ -29,8 +29,41 @@ 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;
-const exitProcess =
-	typeof process.reallyExit === "function" ? process.reallyExit.bind(process) : process.exit.bind(process);
+/**
+ * Symbol stamped by the extension-load guard onto the throwing replacement it
+ * installs over `process.exit` / `process.reallyExit`, carrying the native
+ * primitive that replacement shadows.
+ *
+ * Host-owned shutdown ({@link exitProcess}) reads through it so a signal that
+ * lands while the guard is active still terminates the process (#6488), while
+ * a signal that lands after the guard has restored the native exit also
+ * terminates cleanly (#7393). `Symbol.for` so it survives duplicate module
+ * instances across bundles/realms.
+ */
+export const NATIVE_PROCESS_EXIT = Symbol.for("omp.postmortem.nativeProcessExit");
+
+type HardExitFn = (code?: number) => never;
+
+/**
+ * Hard-exit the process through the native primitive, resolved on every call.
+ *
+ * The native exit is deliberately re-resolved here rather than bound at module
+ * load: the extension/hook loader's `withHostGuard` transiently swaps
+ * `process.reallyExit`/`process.exit` for a stub that throws
+ * `ExtensionExitError`, and the shipped bundle defers this module's evaluation
+ * until first access — which can land inside that guard window, so binding at
+ * 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.
+ */
+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;
+}
 let cleanupPromise: Promise<void> | undefined;
 let stdioDisconnectRegistrations = 0;