@linxiraos/pi-utils 1.1.20 → 1.1.22

package/src/index.ts

@@ -10,6 +10,7 @@ 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";
@@ -62,3 +63,42 @@ export function structuredCloneJSON<T>(value: T): T {
 	}
 	return JSON.parse(JSON.stringify(value)) as T;
 }
+
+/**
+ * Deep-copies a JSON-shaped tree (arrays and plain or null-prototype objects)
+ * so later mutation of the source can never reach the copy. Strings and other
+ * primitives are immutable and shared, so the cost is O(containers) instead of
+ * `structuredClone`'s O(bytes) — the difference matters for hot paths that
+ * re-copy large string payloads (e.g. streamed tool-call arguments) per delta.
+ *
+ * Copies own enumerable string keys only. Any other object (class instance,
+ * Date, Map, inherited-prototype object) is copied with {@link structuredCloneJSON}.
+ * Not cycle-safe: callers MUST pass acyclic data, as any JSON-serializable value is.
+ */
+export function cloneJsonTree<T>(value: T): T {
+	return cloneJsonNode(value) as T;
+}
+
+function isJsonRecord(value: object): value is Record<string, unknown> {
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+
+function cloneJsonNode(value: unknown): unknown {
+	if (value === null || typeof value !== "object") return value;
+	if (Array.isArray(value)) return value.map(cloneJsonNode);
+	if (!isJsonRecord(value)) return structuredCloneJSON(value);
+	const out: Record<string, unknown> = {};
+	for (const key in value) {
+		if (!Object.hasOwn(value, key)) continue;
+		const child = cloneJsonNode(value[key]);
+		// Assigning `__proto__` would swap the copy's prototype instead of
+		// creating the own data property JSON.parse produces.
+		if (key === "__proto__") {
+			Object.defineProperty(out, key, { value: child, enumerable: true, writable: true, configurable: true });
+		} else {
+			out[key] = child;
+		}
+	}
+	return out;
+}

package/src/logger/rotating-file.ts

@@ -1,8 +1,9 @@
 /** Behavior-compatible reimplementation of winston-daily-rotate-file's used surface. */
-import * as crypto from "node:crypto";
 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";
 
 interface AuditEntry {
 	readonly date: number;
@@ -25,6 +26,15 @@ export interface RotatingFileOptions {
 	readonly auditFile: string;
 	readonly maxBytes: number;
 	readonly maxFiles: number;
+	/**
+	 * Called with the new active file path whenever the sink opens a different
+	 * file — construction, local-day rotation, and size rotation alike.
+	 *
+	 * Consumers that hold their own descriptor on the active log (the macOS
+	 * stderr guard dup2s it onto fd 2) use this to follow the sink instead of
+	 * staying pinned to a file the sink later prunes.
+	 */
+	readonly onRotate?: (filePath: string) => void;
 }
 
 function isAuditEntry(value: unknown): value is AuditEntry {
@@ -41,6 +51,7 @@ export class RotatingFileSink {
 	readonly #auditFile: string;
 	readonly #maxBytes: number;
 	readonly #maxFiles: number;
+	readonly #onRotate: ((filePath: string) => void) | undefined;
 	#files: AuditEntry[];
 	#activeDay: string | undefined;
 	#activeIndex = 0;
@@ -61,9 +72,10 @@ export class RotatingFileSink {
 		this.#auditFile = options.auditFile;
 		this.#maxBytes = options.maxBytes;
 		this.#maxFiles = options.maxFiles;
+		this.#onRotate = options.onRotate;
 		this.#files = this.#readAudit();
 		const now = new Date();
-		this.#selectFile(this.#localDay(now));
+		this.#selectFile(localDay(now));
 		const activePath = this.#activePath;
 		if (activePath) {
 			this.#registerFile(activePath, now.getTime());
@@ -73,7 +85,12 @@ export class RotatingFileSink {
 
 	#openFd(filePath: string): void {
 		this.#closeFd();
-		this.#fd = fs.openSync(filePath, "a");
+		this.#fd = openCloexecSync(filePath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_APPEND);
+		try {
+			this.#onRotate?.(filePath);
+		} catch {
+			// A rotation observer must never break logging.
+		}
 	}
 
 	#closeFd(): void {
@@ -92,7 +109,7 @@ export class RotatingFileSink {
 		if (this.#closed) return;
 		const prevPath = this.#activePath;
 		const now = new Date();
-		this.#selectFile(this.#localDay(now));
+		this.#selectFile(localDay(now));
 		const activePath = this.#activePath;
 		if (!activePath) return;
 		// Rotation moved the active path: close the old descriptor BEFORE
@@ -120,10 +137,6 @@ export class RotatingFileSink {
 		this.#closeFd();
 	}
 
-	#localDay(date: Date): string {
-		return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
-	}
-
 	#selectFile(day: string): void {
 		if (day !== this.#activeDay) {
 			this.#activeDay = day;
@@ -151,7 +164,7 @@ export class RotatingFileSink {
 
 	#registerFile(filePath: string, date: number): void {
 		if (this.#files.some(file => file.name === filePath)) return;
-		const hash = crypto.createHash("sha256").update(`${filePath}LOG_FILE${date}`).digest("hex");
+		const hash = Bun.SHA256.hash(`${filePath}LOG_FILE${date}`, "hex");
 		this.#files.push({ date, name: filePath, hash });
 		while (this.#files.length > this.#maxFiles) {
 			const removed = this.#files.shift();

package/src/logger.ts

@@ -6,7 +6,7 @@
  * (the auth broker, etc.) call {@link setTransports} to swap in a console
  * transport so a process supervisor (pm2, journald, k8s) captures the logs.
  *
- * Each entry includes `process.pid` so concurrent omp instances stay
+ * Each entry includes `process.pid` so concurrent zeta instances stay
  * traceable.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -14,8 +14,9 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { isPromise } from "node:util/types";
-import { getLogsDir } from "./dirs";
+import { getLogsDir, localDay } from "./dirs";
 import { RotatingFileSink } from "./logger/rotating-file";
+import { setStderrRedirectTarget } from "./stderr-guard";
 import { drainModuleLoadEvents } from "./timing-buffer";
 /** Severity names accepted by the centralized logger. */
 export type LogLevel = "error" | "warn" | "info" | "debug";
@@ -82,14 +83,10 @@ function pruneStaleProcessLogs(dir: string): void {
 		return;
 	}
 	const current = new Date();
-	const currentDate =
-		`${current.getFullYear()}-${String(current.getMonth() + 1).padStart(2, "0")}-` +
-		String(current.getDate()).padStart(2, "0");
+	const currentDate = localDay(current);
 	const cutoff = new Date(current);
 	cutoff.setDate(cutoff.getDate() - (RETAINED_STALE_LOG_DAYS - 1));
-	const cutoffDate =
-		`${cutoff.getFullYear()}-${String(cutoff.getMonth() + 1).padStart(2, "0")}-` +
-		String(cutoff.getDate()).padStart(2, "0");
+	const cutoffDate = localDay(cutoff);
 
 	const staleLogsByProcessDay = new Map<string, Array<{ path: string; rollover: number }>>();
 	for (const entry of entries) {
@@ -258,6 +255,8 @@ function makeFileTransport(dir?: string): RotatingFileSink {
 		maxBytes: 10 * 1024 * 1024,
 		maxFiles: 5,
 		auditFile: path.join(logsDir, `.zeta.${process.pid}-audit.json`),
+		// Keep the stderr guard's fd 2 on the file this sink is writing.
+		onRotate: setStderrRedirectTarget,
 	});
 }
 
@@ -644,7 +643,9 @@ function printSpan(span: Span, depth: number, lines: string[]): void {
 	const tag = parallel ? " [parallel]" : "";
 	const self = selfTimeOf(span);
 	const selfStr = span.children.length > 0 && self > LOGGED_TIMING_THRESHOLD_MS ? ` (self ${fmtMs(self)})` : "";
-	lines.push(`${indent}${span.op}: ${fmtMs(dur)}${selfStr}${tag}`);
+	// Start offset from process origin: gaps between consecutive siblings are
+	// the parent's own (unspanned) work, which duration alone cannot locate.
+	lines.push(`${indent}${span.op}: ${fmtMs(dur)}${selfStr}${tag} @${span.start.toFixed(0)}ms`);
 
 	// Split children into work spans and module-load spans for summarization.
 	const work: Span[] = [];

package/src/mermaid-ascii.ts

@@ -1,14 +1,20 @@
-import { type AsciiRenderOptions, renderMermaidASCII } from "./vendor/mermaid-ascii";
+import { type MermaidRenderOptions, renderMermaidAscii } from "@linxiraos/pi-natives";
 
-export type { AsciiRenderOptions as MermaidAsciiRenderOptions };
+/**
+ * Native Mermaid → ASCII/Unicode renderer (flowchart, state, sequence, class,
+ * ER, xychart). Synchronous because callers render inside the compositor;
+ * throws on empty input, an unknown flowchart header, or an invalid
+ * `direction`/`colorMode` value.
+ */
+export { renderMermaidAscii };
 
-export function renderMermaidAscii(source: string, options?: AsciiRenderOptions): string {
-	return renderMermaidASCII(source, options);
-}
+/** Options for {@link renderMermaidAscii}; every field optional. */
+export type MermaidAsciiRenderOptions = MermaidRenderOptions;
 
-export function renderMermaidAsciiSafe(source: string, options?: AsciiRenderOptions): string | null {
+/** {@link renderMermaidAscii}, returning `null` instead of throwing. */
+export function renderMermaidAsciiSafe(source: string, options?: MermaidAsciiRenderOptions): string | null {
 	try {
-		return renderMermaidASCII(source, options);
+		return renderMermaidAscii(source, options);
 	} catch {
 		return null;
 	}

package/src/module-timer.ts

@@ -40,6 +40,7 @@
  * - **Dev runs only.** In the compiled `omp` binary every module is pre-bundled
  *   into bunfs, so `onLoad` never fires; profile with a `bun --preload` dev run.
  */
+import { readFileSync } from "node:fs";
 import { plugin } from "bun";
 import { moduleLoadBuffer } from "./timing-buffer";
 
@@ -48,8 +49,8 @@ import { moduleLoadBuffer } from "./timing-buffer";
 // `{ contents, loader: "js" }`, Bun forces ESM and CJS modules fail to load
 // (e.g. `Missing 'default' export`). Our own source tree (where the interesting
 // timing lives) is uniformly TypeScript, so a TS-only filter is both safe and
-// sufficient.
-const MODULE_LOADER_FILTER = /\.[mc]?tsx?$/;
+// sufficient. Declaration files are imported as text assets, never evaluated.
+const MODULE_LOADER_FILTER = /^(?!.*\.d\.[mc]?ts$).*\.[mc]?tsx?$/;
 const MODULE_COMPLETE_KEY: symbol = Symbol.for("omp.moduleLoadComplete");
 const MODULE_BODY_START_KEY: symbol = Symbol.for("omp.moduleBodyStart");
 const STATIC_IMPORT_PATTERN =
@@ -133,10 +134,12 @@ if (process.env.PI_TIMING) {
 	plugin({
 		name: "pi-module-load-timer",
 		setup(build) {
-			build.onLoad({ filter: MODULE_LOADER_FILTER }, async args => {
+			// Synchronous on purpose: a module served by an async onLoad cannot be
+			// `require()`d (cli.ts requires postmortem through Bun's CJS bridge).
+			build.onLoad({ filter: MODULE_LOADER_FILTER }, args => {
 				starts.set(args.path, performance.now());
 				childSetFor(importsByPath, args.path);
-				const contents = await Bun.file(args.path).text();
+				const contents = readFileSync(args.path, "utf8");
 				addImportEdges(importsByPath, args.path, contents);
 				return {
 					contents: instrumentContents(args.path, contents),

package/src/postmortem.ts

@@ -7,6 +7,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";
 
@@ -368,6 +369,62 @@ export function registerStdioDisconnectHandling(): () => void {
 	};
 }
 
+/**
+ * Fail a process entry whose event loop drains while `work` is still pending.
+ *
+ * The CLI starts from a floating `runCli()` call because top-level await breaks
+ * `--bytecode` builds. When a one-shot command awaits a promise that never
+ * settles and holds no live handle, the loop drains and Bun exits 0 without
+ * output: an unfinished command reported as success. `beforeExit` fires in
+ * that state; explicit exits (`process.exit`, {@link quit},
+ * {@link exitProcess}, the signal handlers) never emit it.
+ *
+ * `beforeExit` alone is not the verdict: on Windows Bun emits it while I/O is
+ * still in flight and then keeps running the loop, so a command that goes on
+ * to complete must keep its own exit code (#13470). The verdict is taken at
+ * `exit` instead, and only when the last `beforeExit` was final: an unref'd
+ * timer armed there runs only if the loop turns again, clearing the mark
+ * before a later explicit exit. Any later drain emits `beforeExit` again and
+ * re-arms it, so other `beforeExit` listeners (LSP shutdown) still run before
+ * the process exits 1.
+ *
+ * `describe` names what was running (e.g. the resolved subcommand) at report
+ * time; it must return only a command name, never user arguments.
+ */
+export function reportUnsettledEntry(work: Promise<unknown>, describe?: () => string | undefined): void {
+	let pending = true;
+	let drained = false;
+	const settled = (): void => {
+		pending = false;
+	};
+	// Observe both outcomes without claiming the rejection: the caller's `.catch` still owns it.
+	void work.then(settled, settled);
+	process.on("beforeExit", () => {
+		if (!pending) return;
+		drained = true;
+		setTimeout(() => {
+			drained = false;
+		}, 0).unref();
+	});
+	process.once("exit", code => {
+		if (!pending || !drained) return;
+		// A non-zero code is already a failure verdict — an explicit
+		// `process.exit(n)` (possibly on the same loop turn as a Windows
+		// mid-I/O `beforeExit`, before the clearing timer runs) or an
+		// `exitCode` the command set. Overwriting it with 1 and a second
+		// "ended before completing" line only obscures the real error.
+		if (code !== 0) return;
+		const command = describe?.();
+		const subject = command ? `\`${CLI_BIN_NAME} ${command}\`` : "command";
+		const message = `${subject} ended before completing: the event loop drained while it was still pending (rerun with PI_DEBUG_STARTUP=1 to see the last phase reached)`;
+		try {
+			fs.writeSync(2, `${CLI_BIN_NAME}: ${message}\n`);
+		} catch {}
+		logger.error(message, { command });
+		process.exitCode = 1;
+	});
+}
+
 // 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.

package/src/procmgr.ts

@@ -20,7 +20,10 @@ export interface ShellConfigOptions {
 	/** File path or runtime layer that supplied the active shell setting. */
 	configSource?: string;
 }
-let cachedShellConfig: ShellConfig | null = null;
+/** Auto-resolved shell (no custom path); stable for the process lifetime. */
+let cachedDefaultShellConfig: ShellConfig | null = null;
+/** Config for the most recent custom `shellPath`; never served once the path is cleared. */
+let cachedCustomShellConfig: ShellConfig | null = null;
 
 /**
  * Build the spawn environment (cached).
@@ -177,6 +180,9 @@ export function resolveWindowsShell(env: Record<string, string | undefined> = Bu
  *    {@link resolveWindowsShell}) — never fails
  * 3. On Unix: $SHELL if bash/zsh, then fallback paths
  * 4. Fallback: sh
+ *
+ * Custom and auto-resolved configs are cached separately, so clearing
+ * `shellPath` mid-process immediately falls back to the platform default.
  */
 export function getShellConfig(customShellPath?: string, options: ShellConfigOptions = {}): ShellConfig {
 	const configSource = options.configSource ?? path.join(getAgentDir(), MAIN_CONFIG_FILENAMES[0]);
@@ -187,36 +193,30 @@ export function getShellConfig(customShellPath?: string, options: ShellConfigOpt
 		if (!fs.existsSync(customShellPath)) {
 			throw new Error(`Custom shell path not found: ${customShellPath}\nPlease update shellPath in ${configSource}`);
 		}
-		if (cachedShellConfig?.shell !== customShellPath) {
-			cachedShellConfig = buildConfig(customShellPath);
+		if (cachedCustomShellConfig?.shell !== customShellPath) {
+			cachedCustomShellConfig = buildConfig(customShellPath);
 		}
-		return cachedShellConfig;
-	}
-	if (cachedShellConfig) {
-		return cachedShellConfig;
+		return cachedCustomShellConfig;
 	}
+	cachedDefaultShellConfig ??= buildConfig(resolveDefaultShell());
+	return cachedDefaultShellConfig;
+}
 
+/** Platform shell discovery used when no custom `shellPath` is configured. */
+function resolveDefaultShell(): string {
 	if (process.platform === "win32") {
-		cachedShellConfig = buildConfig(resolveWindowsShell());
-		return cachedShellConfig;
+		return resolveWindowsShell();
 	}
 
 	// Unix: prefer user's shell from $SHELL if it's bash/zsh and executable
 	const userShell = Bun.env.SHELL;
 	const isValidShell = userShell && (userShell.includes("bash") || userShell.includes("zsh"));
 	if (isValidShell && isExecutable(userShell)) {
-		cachedShellConfig = buildConfig(userShell);
-		return cachedShellConfig;
+		return userShell;
 	}
 
 	// 4. Fallback: use basic shell
-	const basicShell = resolveBasicShell();
-	if (basicShell) {
-		cachedShellConfig = buildConfig(basicShell);
-		return cachedShellConfig;
-	}
-	cachedShellConfig = buildConfig("sh");
-	return cachedShellConfig;
+	return resolveBasicShell() ?? "sh";
 }
 
 /**

package/src/ptree.ts

@@ -462,7 +462,7 @@ export class ChildProcess<In extends InMask = InMask> {
 		return out + dec.decode();
 	}
 
-	async #readBytes(): Promise<Uint8Array> {
+	async #readBytes(): Promise<Uint8Array<ArrayBuffer>> {
 		const reader = this.proc.stdout.getReader();
 		this.#openPipeReaders++;
 		const chunks: Uint8Array[] = [];
@@ -497,7 +497,7 @@ export class ChildProcess<In extends InMask = InMask> {
 		return bytes;
 	}
 
-	async #readOutputBytes(waitForCleanExit = false): Promise<Uint8Array> {
+	async #readOutputBytes(waitForCleanExit = false): Promise<Uint8Array<ArrayBuffer>> {
 		const p = this.#readBytes();
 		if (this.#nothrow) return p;
 		const bytes = waitForCleanExit ? (await Promise.all([p, this.exitedCleanly]))[0] : await p;
@@ -514,7 +514,7 @@ export class ChildProcess<In extends InMask = InMask> {
 	}
 
 	async arrayBuffer(): Promise<ArrayBuffer> {
-		return (await this.#readOutputBytes()).buffer as ArrayBuffer;
+		return (await this.#readOutputBytes()).buffer;
 	}
 
 	async bytes(): Promise<Uint8Array> {

package/src/runtime-install.ts

@@ -172,9 +172,43 @@ function resolverRegistry(): ResolverRegistration[] {
 	holder[REGISTRY] ??= [];
 	return holder[REGISTRY];
 }
-function pathContains(root: string, candidate: string): boolean {
-	const relative = path.relative(root, candidate);
-	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+/** Canonical form of a path, memoized: resolution is per module request, and roots repeat. */
+const canonicalPaths = new Map<string, string>();
+
+/**
+ * Canonical form of `target` for path comparison: symlinks and Windows
+ * junctions resolved, drive/segment casing folded on Windows. Non-existent
+ * paths fall back to `path.resolve`, which still normalizes separators.
+ *
+ * Comparisons must canonicalize because the two sides come from different
+ * worlds: the stock resolver hands back realpath-resolved filenames, while a
+ * registered runtime root is whatever the caller configured (a cache under a
+ * junctioned `F:\Programs\…`, a home directory symlinked onto another volume,
+ * macOS `/tmp` → `/private/tmp`).
+ */
+function canonicalPath(target: string): string {
+	const cached = canonicalPaths.get(target);
+	if (cached !== undefined) return cached;
+	let canonical: string;
+	try {
+		canonical = fs.realpathSync.native(target);
+	} catch {
+		canonical = path.resolve(target);
+	}
+	if (process.platform === "win32") canonical = canonical.toLowerCase();
+	canonicalPaths.set(target, canonical);
+	return canonical;
+}
+
+/**
+ * Path of `candidate` relative to `root` when `candidate` is inside (or is)
+ * `root`, else `null`. Both sides are canonicalized, so a runtime cache
+ * reached through a link still matches the filenames the resolver reports.
+ */
+function relativeWithin(root: string, candidate: string): string | null {
+	const relative = path.relative(canonicalPath(root), canonicalPath(candidate));
+	if (relative !== "" && (relative.startsWith("..") || path.isAbsolute(relative))) return null;
+	return relative;
 }
 
 function parentFilename(parent: unknown): string | null {
@@ -243,11 +277,12 @@ export function installRuntimeModuleResolver({ runtimeNodeModules, stubs = {} }:
 		if (bare) {
 			const parentFile = parentFilename(parent);
 			for (const registration of resolverRegistry()) {
-				const parentInRuntime = parentFile !== null && pathContains(registration.runtimeNodeModules, parentFile);
+				const parentInRuntime =
+					parentFile !== null && relativeWithin(registration.runtimeNodeModules, parentFile) !== null;
 				if (parentInRuntime) {
 					const stub = registration.stubs[request];
 					if (stub) return stub;
-					if (!stockResolved || !pathContains(registration.runtimeNodeModules, stockResolved)) {
+					if (!stockResolved || relativeWithin(registration.runtimeNodeModules, stockResolved) === null) {
 						const fallback = resolveRuntimeModule(registration.runtimeNodeModules, request);
 						if (fallback) return fallback;
 					}
@@ -260,8 +295,9 @@ export function installRuntimeModuleResolver({ runtimeNodeModules, stubs = {} }:
 					// it with the top-level instance would cross major versions.
 					const { packageName } = splitBareSpecifier(request);
 					const pkgDir = path.join(registration.runtimeNodeModules, ...packageName.split("/"));
-					if (!stockResolved.startsWith(pkgDir + path.sep)) continue;
-					if (path.relative(pkgDir, stockResolved).split(path.sep).includes("node_modules")) continue;
+					const relative = relativeWithin(pkgDir, stockResolved);
+					if (relative === null || relative === "") continue;
+					if (relative.split(path.sep).includes("node_modules")) continue;
 					const expected = resolveRuntimeModule(registration.runtimeNodeModules, request);
 					if (expected) return expected;
 				} else {

package/src/sqlite.ts

@@ -58,6 +58,31 @@ export interface SqliteOpenOptions {
 	onCorruptionPreserved?: (backupPath: string, error: unknown) => void;
 }
 
+/**
+ * Bun's multi-statement `db.run()` reports only the final statement's step
+ * error (oven-sh/bun#37415), so a corrupt page hit mid-script can resurface as
+ * an unrelated failure such as "no such table". When an initializer fails for
+ * any other reason, a `quick_check` on the still-open handle decides whether
+ * the store itself is damaged. Runs only on the failure path.
+ */
+function revealHiddenCorruption(db: Database | undefined, error: unknown): unknown {
+	if (!db || isSqliteCorruptionError(error) || isSqliteBusyError(error)) return error;
+	let detail: string;
+	let code: unknown = "SQLITE_CORRUPT";
+	let errno: unknown = 11;
+	try {
+		const rows = db.query<{ quick_check: string }, []>("PRAGMA quick_check(1)").all();
+		if (rows[0]?.quick_check === "ok") return error;
+		detail = `database disk image is malformed (${rows[0]?.quick_check})`;
+	} catch (probeError) {
+		if (!isSqliteCorruptionError(probeError)) return error;
+		detail = probeError instanceof Error ? probeError.message : String(probeError);
+		({ code, errno } = probeError as { code: unknown; errno?: unknown });
+	}
+	const original = error instanceof Error ? error.message : String(error);
+	return Object.assign(new Error(`${detail}; initialization failed: ${original}`, { cause: error }), { code, errno });
+}
+
 async function openWithBusyRetries<T>(
 	dbPath: string,
 	initialize: (db: Database) => T | Promise<T>,
@@ -71,7 +96,8 @@ async function openWithBusyRetries<T>(
 			// WAL recovery can bypass the busy handler; both it and retries are needed (#2421).
 			db.run(`PRAGMA busy_timeout = ${getDbBusyTimeoutMs()}`);
 			return await initialize(db);
-		} catch (error) {
+		} catch (caught) {
+			const error = options.recoverCorruption ? revealHiddenCorruption(db, caught) : caught;
 			if (options.recoverCorruption && isSqliteCorruptionError(error)) {
 				throw new SqliteAttemptFailure(error, identity, { db });
 			}
@@ -91,7 +117,8 @@ function openOnce<T>(dbPath: string, initialize: (db: Database) => T, options: S
 		db = new Database(dbPath);
 		db.run(`PRAGMA busy_timeout = ${getDbBusyTimeoutMs()}`);
 		return initialize(db);
-	} catch (error) {
+	} catch (caught) {
+		const error = options.recoverCorruption ? revealHiddenCorruption(db, caught) : caught;
 		if (options.recoverCorruption && isSqliteCorruptionError(error)) {
 			throw new SqliteAttemptFailure(error, identity, { db });
 		}