@oh-my-pi/pi-utils 18.15.0 → 18.16.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [18.16.0] - 2026-11-02
+
+### Added
+
+- Added `isPidAlive` (signal-0 liveness probe) and `asStrictBytes` (a `Uint8Array` narrowed to its own `ArrayBuffer` for WebCrypto)
+- Added `ensureSqliteLockShim()`, which `openSqliteDatabase`/`openSqliteDatabaseSync` call before opening a store, so on Linux the process's SQLite locks are open-file-description locks that other closes of the file cannot release ([#15586](https://github.com/can1357/oh-my-pi/issues/15586))
+- Added `assertNotHeldOpen(path)` (`@oh-my-pi/pi-utils/held-file`), which throws `EBUSY` for a SQLite database or `-shm` this process holds open ([#15586](https://github.com/can1357/oh-my-pi/issues/15586))
+
+### Changed
+
+- `acp` runtime validators (`zNewSessionResponse`, `zSessionNotification`, …) now report each failing field's path and reason in `error.issues` instead of a single `Invalid <label>`; `ValidationError` issue paths are typed `PropertyKey[]` ([#17699](https://github.com/can1357/oh-my-pi/pull/17699))
+
 ## [18.15.0] - 2026-11-01
 
 ### Added

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

@@ -2,7 +2,7 @@ import type { ForkSessionResponse, LoadSessionResponse, NewSessionResponse, Prom
 /** Validation failure compatible with the used Zod error surface. */
 export interface ValidationError {
     issues: Array<{
-        path: Array<string | number>;
+        path: PropertyKey[];
         message: string;
     }>;
 }

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

@@ -1,3 +1,7 @@
+/** Undo the delta filter (shared by XZ and 7z) in place. */
+export declare function deltaDecode(bytes: Uint8Array, distance: number): void;
+/** Undo the x86 BCJ filter (shared by XZ and 7z) in place; `startOffset` is the stream position of `bytes[0]`. */
+export declare function x86Decode(bytes: Uint8Array, startOffset: number): void;
 /** Whether bytes begin with the XZ stream-header magic. */
 export declare function isXz(bytes: Uint8Array): boolean;
 /** Decompress all concatenated streams in an XZ container within `maxOutput`. */

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

@@ -1,6 +1,8 @@
 import type { FormatReader } from "./types.js";
 /** @internal Decode the static-Huffman LZSS stream shared by LZH and ARJ methods 1-3. */
 export declare function decompressLhStatic(packed: Uint8Array, outSize: number, dictionarySize: number, positionBits: number, positionSymbols: number, label: string): Uint8Array;
+/** MS-DOS packed date/time as UTC milliseconds; `undefined` for 0 or an out-of-range field. */
+export declare function dosTimeToMs(value: number): number | undefined;
 /** Probe whether bytes begin with an LZH/LHA member header. */
 export declare function sniffLzh(bytes: Uint8Array): boolean;
 /** Index an LZH/LHA archive and lazily decode its members from the bounded archive buffer. */

package/dist/types/bytes.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Narrow `bytes` to a view over its own whole `ArrayBuffer`, which is what
+ * `crypto.subtle.{digest,sign,importKey,encrypt,decrypt}` require under the
+ * strict TS DOM typings. Returns `bytes` itself when it already is one,
+ * otherwise a copy.
+ */
+export declare function asStrictBytes(bytes: Uint8Array): Uint8Array<ArrayBuffer>;

package/dist/types/held-file.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Throws an `EBUSY` error when `filePath` is a file this process holds open with
+ * locks: a SQLite database or `-shm` of a live connection. Always passes outside Linux.
+ */
+export declare function assertNotHeldOpen(filePath: string): void;

package/dist/types/index.d.ts

@@ -1,6 +1,7 @@
 export { once, untilAborted } from "./abortable.js";
 export * from "./async.js";
 export * from "./binary.js";
+export * from "./bytes.js";
 export * from "./color.js";
 export * from "./dirs.js";
 export * from "./env.js";
@@ -22,6 +23,7 @@ export * from "./mime.js";
 export * from "./path.js";
 export * from "./path-tree.js";
 export * from "./peek-file.js";
+export * from "./pid.js";
 export * as postmortem from "./postmortem.js";
 export * from "./process-name.js";
 export * as procmgr from "./procmgr.js";

package/dist/types/pid.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Signal-0 liveness probe: true unless the OS reports the pid as gone
+ * (`ESRCH`) or invalid (`EINVAL`). Any other failure, notably `EPERM` (alive
+ * but owned by another user), reads as alive, so callers never reclaim a
+ * resource a live process may still hold. Unlike `procmgr.isPidRunning`, this
+ * does not consult the process table's run state.
+ */
+export declare function isPidAlive(pid: number): boolean;

package/dist/types/sqlite.d.ts

@@ -1,5 +1,17 @@
 /** Shared SQLite opening, error attribution, and result-code classification for persistent stores. */
 import { Database } from "bun:sqlite";
+/**
+ * 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 declare function ensureSqliteLockShim(): boolean;
 /**
  * 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.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-utils",
-	"version": "18.15.0",
+	"version": "18.16.0",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"cli",
@@ -56,7 +56,8 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.15.0"
+		"@oh-my-pi/omptype": "18.16.0",
+		"@oh-my-pi/pi-natives": "18.16.0"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/acp/schema.ts

@@ -1,3 +1,4 @@
+import { type Type, type } from "@oh-my-pi/omptype";
 import type {
 	ForkSessionResponse,
 	LoadSessionResponse,
@@ -8,7 +9,7 @@ import type {
 
 /** Validation failure compatible with the used Zod error surface. */
 export interface ValidationError {
-	issues: Array<{ path: Array<string | number>; message: string }>;
+	issues: Array<{ path: PropertyKey[]; message: string }>;
 }
 /** Successful validation result. */
 export interface ValidationSuccess<T> {
@@ -26,129 +27,74 @@ export interface Validator<T> {
 	parse(value: unknown): T;
 }
 
-function validator<T>(check: (value: unknown) => boolean, label: string): Validator<T> {
+/**
+ * Wraps a structural schema in the Zod call shape. Schemas check the fields
+ * ACP consumers read and keep every other key, so the result is the full
+ * protocol value.
+ */
+function validator<T>(schema: Type, label: string): Validator<T> {
 	return {
 		safeParse(value) {
-			return check(value)
-				? { success: true, data: value as T }
-				: { success: false, error: { issues: [{ path: [], message: `Invalid ${label}` }] } };
+			const result = schema(value);
+			if (!(result instanceof type.errors)) return { success: true, data: result as T };
+			return {
+				success: false,
+				error: { issues: result.map(issue => ({ path: [...issue.path], message: issue.message })) },
+			};
 		},
 		parse(value) {
-			if (!check(value)) throw new Error(`Invalid ${label}`);
-			return value as T;
+			const result = schema(value);
+			if (result instanceof type.errors) throw new Error(`Invalid ${label}: ${result.summary}`);
+			return result as T;
 		},
 	};
 }
 
-function objectWithString(value: unknown, key: string): boolean {
-	return typeof value === "object" && value !== null && typeof (value as Record<string, unknown>)[key] === "string";
-}
-
-function validModes(value: unknown): boolean {
-	if (value === undefined || value === null) return true;
-	if (typeof value !== "object" || value === null) return false;
-	const modes = value as Record<string, unknown>;
-	return (
-		typeof modes.currentModeId === "string" &&
-		Array.isArray(modes.availableModes) &&
-		modes.availableModes.every(mode => objectWithString(mode, "id") && objectWithString(mode, "name"))
-	);
-}
+const Modes = type({
+	currentModeId: "string",
+	availableModes: type({ id: "string", name: "string" }).array(),
+}).or("null | undefined");
 
-function sessionResponse(value: unknown, needsId: boolean): boolean {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
-	const response = value as Record<string, unknown>;
-	if (needsId && typeof response.sessionId !== "string") return false;
-	if (!validModes(response.modes)) return false;
-	return (
-		response.configOptions === undefined || response.configOptions === null || Array.isArray(response.configOptions)
-	);
-}
+// Responses and notifications are also checked in-process, where absent optionals may be explicit `undefined`.
+const sessionResponseFields = { "modes?": Modes, "configOptions?": "unknown[] | null | undefined" } as const;
+const notArray = (value: object): boolean => !Array.isArray(value);
+const SessionResponse = type(sessionResponseFields).narrow(notArray);
+const IdentifiedSessionResponse = type({ sessionId: "string", ...sessionResponseFields }).narrow(notArray);
 
-function contentBlock(value: unknown): boolean {
-	if (typeof value !== "object" || value === null) return false;
-	const block = value as Record<string, unknown>;
-	switch (block.type) {
-		case "text":
-			return typeof block.text === "string";
-		case "image":
-		case "audio":
-			return typeof block.data === "string" && typeof block.mimeType === "string";
-		case "resource_link":
-			return typeof block.uri === "string" && typeof block.name === "string";
-		case "resource":
-			return typeof block.resource === "object" && block.resource !== null;
-		default:
-			return false;
-	}
-}
+const ContentBlock = type({ type: "'text'", text: "string" })
+	.or({ type: "'image' | 'audio'", data: "string", mimeType: "string" })
+	.or({ type: "'resource_link'", uri: "string", name: "string" })
+	.or({ type: "'resource'", resource: "object" });
 
-function sessionNotification(value: unknown): boolean {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
-	const notification = value as Record<string, unknown>;
-	if (
-		typeof notification.sessionId !== "string" ||
-		typeof notification.update !== "object" ||
-		notification.update === null
-	)
-		return false;
-	const update = notification.update as Record<string, unknown>;
-	if (typeof update.sessionUpdate !== "string") return false;
-	switch (update.sessionUpdate) {
-		case "agent_message_chunk":
-		case "agent_thought_chunk":
-		case "user_message_chunk":
-			return contentBlock(update.content);
-		case "tool_call":
-			return typeof update.toolCallId === "string" && typeof update.title === "string";
-		case "tool_call_update":
-			return typeof update.toolCallId === "string";
-		case "plan":
-			return Array.isArray(update.entries);
-		case "current_mode_update":
-			return typeof update.currentModeId === "string";
-		case "available_commands_update":
-			return Array.isArray(update.availableCommands);
-		case "config_option_update":
-			return Array.isArray(update.configOptions);
-		case "session_info_update":
-			return update.title === undefined || update.title === null || typeof update.title === "string";
-		case "usage_update":
-			return typeof update.size === "number" && typeof update.used === "number";
-		default:
-			return false;
-	}
-}
+const SessionUpdate = type({
+	sessionUpdate: "'agent_message_chunk' | 'agent_thought_chunk' | 'user_message_chunk'",
+	content: ContentBlock,
+})
+	.or({ sessionUpdate: "'tool_call'", toolCallId: "string", title: "string" })
+	.or({ sessionUpdate: "'tool_call_update'", toolCallId: "string" })
+	.or({ sessionUpdate: "'plan'", entries: "unknown[]" })
+	.or({ sessionUpdate: "'current_mode_update'", currentModeId: "string" })
+	.or({ sessionUpdate: "'available_commands_update'", availableCommands: "unknown[]" })
+	.or({ sessionUpdate: "'config_option_update'", configOptions: "unknown[]" })
+	.or({ sessionUpdate: "'session_info_update'", "title?": "string | null | undefined" })
+	.or({ sessionUpdate: "'usage_update'", size: "number", used: "number" });
 
 /** Validator for new-session responses. */
-export const zNewSessionResponse = validator<NewSessionResponse>(
-	value => sessionResponse(value, true),
-	"new session response",
-);
+export const zNewSessionResponse = validator<NewSessionResponse>(IdentifiedSessionResponse, "new session response");
 /** Validator for load-session responses. */
-export const zLoadSessionResponse = validator<LoadSessionResponse>(
-	value => sessionResponse(value, false),
-	"load session response",
-);
+export const zLoadSessionResponse = validator<LoadSessionResponse>(SessionResponse, "load session response");
 /** Validator for fork-session responses. */
-export const zForkSessionResponse = validator<ForkSessionResponse>(
-	value => sessionResponse(value, true),
-	"fork session response",
-);
+export const zForkSessionResponse = validator<ForkSessionResponse>(IdentifiedSessionResponse, "fork session response");
 /** Validator for prompt responses. */
-export const zPromptResponse = validator<PromptResponse>(value => {
-	if (typeof value !== "object" || value === null) return false;
-	const stopReason = (value as Record<string, unknown>).stopReason;
-	return (
-		stopReason === "end_turn" ||
-		stopReason === "max_tokens" ||
-		stopReason === "max_turn_requests" ||
-		stopReason === "refusal" ||
-		stopReason === "cancelled"
-	);
-}, "prompt response");
+export const zPromptResponse = validator<PromptResponse>(
+	type({ stopReason: "'end_turn' | 'max_tokens' | 'max_turn_requests' | 'refusal' | 'cancelled'" }),
+	"prompt response",
+);
 /** Validator for session notifications. */
-export const zSessionNotification = validator<SessionNotification>(sessionNotification, "session notification");
+export const zSessionNotification = validator<SessionNotification>(
+	type({ sessionId: "string", update: SessionUpdate }).narrow(notArray),
+	"session notification",
+);
 
 /** ACP runtime validators. */
 export const schema = {

package/src/ar/arj.ts

@@ -1,7 +1,8 @@
+import { readUInt16LE, readUInt32LE } from "./bytes";
 import { crc32 } from "./checksums";
 import { ArchiveError } from "./error";
 import { assertArchiveMemberSize, assertEntryCount, assertIndexSize, assertInMemorySize } from "./limits";
-import { decompressLhStatic } from "./lzh";
+import { decompressLhStatic, dosTimeToMs } from "./lzh";
 import { assertArchivePathBytes, assertArchivePathString, normalizeArchiveEntryPath } from "./paths";
 import { type ByteSource, readAllBytes } from "./source";
 import type { ArchiveIndexEntry, FormatReader, FormatReadOptions, MemberSource } from "./types";
@@ -11,14 +12,6 @@ const ARJ_SIGNATURE_1 = 0xea;
 const ARJ_MAX_BASIC_HEADER = 2600;
 const LEGACY_DECODER = new TextDecoder("windows-1252");
 
-function u16(bytes: Uint8Array, offset: number): number {
-	return bytes[offset]! | (bytes[offset + 1]! << 8);
-}
-
-function u32(bytes: Uint8Array, offset: number): number {
-	return (bytes[offset]! | (bytes[offset + 1]! << 8) | (bytes[offset + 2]! << 16) | (bytes[offset + 3]! << 24)) >>> 0;
-}
-
 function assertRange(bytes: Uint8Array, start: number, end: number, what: string): void {
 	if (
 		!Number.isSafeInteger(start) ||
@@ -31,18 +24,6 @@ function assertRange(bytes: Uint8Array, start: number, end: number, what: string
 	}
 }
 
-function dosTimeToMs(value: number): number | undefined {
-	if (value === 0) return undefined;
-	const year = 1980 + ((value >>> 25) & 0x7f);
-	const month = (value >>> 21) & 0x0f;
-	const day = (value >>> 16) & 0x1f;
-	const hour = (value >>> 11) & 0x1f;
-	const minute = (value >>> 5) & 0x3f;
-	const second = (value & 0x1f) * 2;
-	if (month < 1 || month > 12 || day < 1 || day > 31 || hour > 23 || minute > 59 || second > 59) return undefined;
-	return Date.UTC(year, month - 1, day, hour, minute, second);
-}
-
 function readCString(bytes: Uint8Array, start: number, end: number, field: string): { value: string; next: number } {
 	let terminator = start;
 	while (terminator < end && bytes[terminator] !== 0) terminator++;
@@ -63,26 +44,26 @@ function parseArjBlock(bytes: Uint8Array, offset: number, options: FormatReadOpt
 	if (bytes[offset] !== ARJ_SIGNATURE_0 || bytes[offset + 1] !== ARJ_SIGNATURE_1) {
 		throw new ArchiveError("Invalid ARJ header signature");
 	}
-	const bodySize = u16(bytes, offset + 2);
+	const bodySize = readUInt16LE(bytes, offset + 2);
 	if (bodySize === 0)
 		return { bodyStart: offset + 4, bodySize: 0, nextOffset: offset + 4, metadataSize: 4, isEnd: true };
 	if (bodySize < 30 || bodySize > ARJ_MAX_BASIC_HEADER) throw new ArchiveError("Invalid ARJ basic header size");
 	const bodyStart = offset + 4;
 	const bodyEnd = bodyStart + bodySize;
 	assertRange(bytes, bodyStart, bodyEnd + 4, "basic header");
-	if (crc32(bytes.subarray(bodyStart, bodyEnd)) !== u32(bytes, bodyEnd)) {
+	if (crc32(bytes.subarray(bodyStart, bodyEnd)) !== readUInt32LE(bytes, bodyEnd)) {
 		throw new ArchiveError("Invalid ARJ basic header CRC32");
 	}
 	let cursor = bodyEnd + 4;
 	let extensionCount = 0;
 	for (;;) {
 		assertRange(bytes, cursor, cursor + 2, "extended header size");
-		const extensionSize = u16(bytes, cursor);
+		const extensionSize = readUInt16LE(bytes, cursor);
 		cursor += 2;
 		if (extensionSize === 0) break;
 		if (++extensionCount > 65_535) throw new ArchiveError("Invalid ARJ archive: too many extended headers");
 		assertRange(bytes, cursor, cursor + extensionSize + 4, "extended header");
-		if (crc32(bytes.subarray(cursor, cursor + extensionSize)) !== u32(bytes, cursor + extensionSize)) {
+		if (crc32(bytes.subarray(cursor, cursor + extensionSize)) !== readUInt32LE(bytes, cursor + extensionSize)) {
 			throw new ArchiveError("Invalid ARJ extended header CRC32");
 		}
 		cursor += extensionSize + 4;
@@ -216,10 +197,10 @@ function normalizeHostPath(rawPath: string, hostOs: number): string {
 /** Probe whether bytes begin with a CRC-framed ARJ main header. */
 export function sniffArj(bytes: Uint8Array): boolean {
 	if (bytes.byteLength < 34 || bytes[0] !== ARJ_SIGNATURE_0 || bytes[1] !== ARJ_SIGNATURE_1) return false;
-	const size = u16(bytes, 2);
+	const size = readUInt16LE(bytes, 2);
 	if (size < 30 || size > ARJ_MAX_BASIC_HEADER || bytes.byteLength < size + 8) return false;
 	const body = bytes.subarray(4, 4 + size);
-	return body[0]! >= 30 && body[0]! <= size && body[6] === 2 && crc32(body) === u32(bytes, 4 + size);
+	return body[0]! >= 30 && body[0]! <= size && body[6] === 2 && crc32(body) === readUInt32LE(bytes, 4 + size);
 }
 
 /** Index an ARJ archive and lazily decode stored, static-Huffman, and fast-LZSS members. */
@@ -266,10 +247,10 @@ export const readArj: FormatReader = async (
 		const fileType = bytes[block.bodyStart + 6]!;
 		if ((flags & 0x01) !== 0) throw new ArchiveError("Encrypted ARJ members are unsupported");
 		if ((flags & 0x0c) !== 0) throw new ArchiveError("Multi-volume ARJ members are unsupported");
-		const packedSize = u32(bytes, block.bodyStart + 12);
-		const size = u32(bytes, block.bodyStart + 16);
-		const fileCrc = u32(bytes, block.bodyStart + 20);
-		const accessMode = u16(bytes, block.bodyStart + 26);
+		const packedSize = readUInt32LE(bytes, block.bodyStart + 12);
+		const size = readUInt32LE(bytes, block.bodyStart + 16);
+		const fileCrc = readUInt32LE(bytes, block.bodyStart + 20);
+		const accessMode = readUInt16LE(bytes, block.bodyStart + 26);
 		const filename = readCString(
 			bytes,
 			block.bodyStart + firstHeaderSize,
@@ -295,7 +276,7 @@ export const readArj: FormatReader = async (
 		if ((hostOs === 2 || hostOs === 8) && accessMode !== 0) {
 			mode = (isDirectory ? 0x4000 : 0x8000) | (accessMode & 0x0fff);
 		}
-		const rawMtime = u32(bytes, block.bodyStart + 8);
+		const rawMtime = readUInt32LE(bytes, block.bodyStart + 8);
 		const mtimeMs =
 			hostOs === 2 || hostOs === 8 ? (rawMtime === 0 ? undefined : rawMtime * 1000) : dosTimeToMs(rawMtime);
 		entries.push({

package/src/ar/asar.ts

@@ -2,6 +2,7 @@ import * as path from "node:path";
 import { readUInt32LE, writeUInt32LE } from "./bytes";
 import { ArchiveError } from "./error";
 import { assertArchiveMemberSize, assertEntryCount, assertIndexSize } from "./limits";
+import { isRecord } from "../type-guards";
 import {
 	assertArchivePathBytes,
 	assertArchivePathString,
@@ -55,14 +56,10 @@ function alignAsarPayload(size: number): number {
 	return size + ((4 - (size % 4)) % 4);
 }
 
-function isArchiveRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function parseIntegrity(value: unknown, entryPath: string, size: number): AsarIntegrity | undefined {
 	if (value === undefined) return undefined;
 	const label = formatArchivePathForError(entryPath);
-	if (!isArchiveRecord(value)) {
+	if (!isRecord(value)) {
 		throw invalidAsar(`file '${label}' has an invalid integrity record`);
 	}
 	if (value.algorithm !== "SHA256") {
@@ -228,7 +225,7 @@ async function readAsarIndex(source: ByteSource, options: FormatReadOptions): Pr
 	} catch {
 		throw invalidAsar("header is not valid JSON");
 	}
-	if (!isArchiveRecord(header) || !isArchiveRecord(header.files)) {
+	if (!isRecord(header) || !isRecord(header.files)) {
 		throw invalidAsar("root must contain a files object");
 	}
 
@@ -257,7 +254,7 @@ async function readAsarIndex(source: ByteSource, options: FormatReadOptions): Pr
 		) {
 			throw invalidAsar(`invalid entry name '${formatArchivePathForError(current.name)}'`);
 		}
-		if (!isArchiveRecord(current.node)) {
+		if (!isRecord(current.node)) {
 			throw invalidAsar(`entry '${formatArchivePathForError(current.name)}' must be an object`);
 		}
 		const entryPathBytes = current.parentPathBytes + (current.parentPath ? 1 : 0) + nameBytes;
@@ -295,7 +292,7 @@ async function readAsarIndex(source: ByteSource, options: FormatReadOptions): Pr
 		}
 
 		if ("files" in current.node) {
-			if (!isArchiveRecord(current.node.files)) {
+			if (!isRecord(current.node.files)) {
 				throw invalidAsar(`directory '${entryLabel}' must contain a files object`);
 			}
 			entries.push({ path: entryPath, isDirectory: true, size: 0 });

package/src/ar/codecs/xz.ts

@@ -1,3 +1,4 @@
+import { readUInt32BE } from "../bytes";
 import { crc32, crc64 } from "../checksums";
 import { ArchiveError } from "../error";
 import { lzma2Decompress } from "./lzma";
@@ -16,10 +17,6 @@ function write32LE(bytes: Uint8Array, offset: number, value: number): void {
 	bytes[offset + 3] = value >>> 24;
 }
 
-function read32BE(bytes: Uint8Array, offset: number): number {
-	return ((bytes[offset]! << 24) | (bytes[offset + 1]! << 16) | (bytes[offset + 2]! << 8) | bytes[offset + 3]!) >>> 0;
-}
-
 function write32BE(bytes: Uint8Array, offset: number, value: number): void {
 	bytes[offset] = value >>> 24;
 	bytes[offset + 1] = (value >>> 16) & 0xff;
@@ -155,7 +152,8 @@ interface XzFilter {
 	properties: Uint8Array;
 }
 
-function deltaDecode(bytes: Uint8Array, distance: number): void {
+/** Undo the delta filter (shared by XZ and 7z) in place. */
+export function deltaDecode(bytes: Uint8Array, distance: number): void {
 	const history = new Uint8Array(256);
 	let position = 0;
 	for (let index = 0; index < bytes.byteLength; index++) {
@@ -166,7 +164,8 @@ function deltaDecode(bytes: Uint8Array, distance: number): void {
 	}
 }
 
-function x86Decode(bytes: Uint8Array, startOffset: number): void {
+/** Undo the x86 BCJ filter (shared by XZ and 7z) in place; `startOffset` is the stream position of `bytes[0]`. */
+export function x86Decode(bytes: Uint8Array, startOffset: number): void {
 	const maskToBitNumber = [0, 1, 2, 2, 3] as const;
 	let previousMask = 0;
 	let previousPosition = 0xfffffffb;
@@ -267,7 +266,7 @@ function sparcDecode(bytes: Uint8Array, startOffset: number): void {
 			)
 		)
 			continue;
-		const source = (read32BE(bytes, index) << 2) >>> 0;
+		const source = (readUInt32BE(bytes, index) << 2) >>> 0;
 		let destination = (source - startOffset - index) >>> 2;
 		destination = (((0 - ((destination >>> 22) & 1)) << 22) & 0x3fffffff) | (destination & 0x3fffff) | 0x40000000;
 		write32BE(bytes, index, destination >>> 0);
@@ -356,7 +355,7 @@ function riscvDecode(bytes: Uint8Array, startOffset: number): void {
 				index += 2;
 				continue;
 			}
-			const address = (read32BE(bytes, index + 4) - startOffset - index) >>> 0;
+			const address = (readUInt32BE(bytes, index + 4) - startOffset - index) >>> 0;
 			instruction2 = ((instruction >>> 12) | (address << 20)) >>> 0;
 			instruction = (0x17 | (register << 7) | ((address + 0x800) & 0xfffff000)) >>> 0;
 		}

package/src/ar/lzh.ts

@@ -1,3 +1,4 @@
+import { readUInt16LE, readUInt32LE } from "./bytes";
 import { crc16Arc } from "./checksums";
 import { ArchiveError } from "./error";
 import { assertArchiveMemberSize, assertEntryCount, assertIndexSize, assertInMemorySize } from "./limits";
@@ -279,16 +280,8 @@ function crc16WithZeroRange(bytes: Uint8Array, zeroStart: number, zeroEnd: numbe
 	return crc16Arc(bytes.subarray(zeroEnd), value);
 }
 
-function u16(bytes: Uint8Array, offset: number): number {
-	return bytes[offset]! | (bytes[offset + 1]! << 8);
-}
-
-function u32(bytes: Uint8Array, offset: number): number {
-	return (bytes[offset]! | (bytes[offset + 1]! << 8) | (bytes[offset + 2]! << 16) | (bytes[offset + 3]! << 24)) >>> 0;
-}
-
 function u64(bytes: Uint8Array, offset: number): number {
-	const value = u32(bytes, offset) + u32(bytes, offset + 4) * 0x100000000;
+	const value = readUInt32LE(bytes, offset) + readUInt32LE(bytes, offset + 4) * 0x100000000;
 	if (!Number.isSafeInteger(value)) throw new ArchiveError("LZH uses sizes too large to read safely");
 	return value;
 }
@@ -318,7 +311,8 @@ function decodeUtf16(bytes: Uint8Array): string {
 	return UTF16LE_DECODER.decode(bytes.subarray(0, end));
 }
 
-function dosTimeToMs(value: number): number | undefined {
+/** MS-DOS packed date/time as UTC milliseconds; `undefined` for 0 or an out-of-range field. */
+export function dosTimeToMs(value: number): number | undefined {
 	if (value === 0) return undefined;
 	const year = 1980 + ((value >>> 25) & 0x7f);
 	const month = (value >>> 21) & 0x0f;
@@ -352,7 +346,7 @@ function processExtendedHeader(
 	switch (type) {
 		case 0x00:
 			if (data.byteLength < 2) throw new ArchiveError("Invalid LZH common extended header");
-			fields.commonCrc = u16(data, 0);
+			fields.commonCrc = readUInt16LE(data, 0);
 			fields.commonCrcOffset = absoluteDataOffset;
 			break;
 		case 0x01:
@@ -365,8 +359,8 @@ function processExtendedHeader(
 			throw new ArchiveError("Multi-volume LZH archives are unsupported");
 		case 0x41:
 			if (data.byteLength >= 16) {
-				const low = u32(data, 8);
-				const high = u32(data, 12);
+				const low = readUInt32LE(data, 8);
+				const high = readUInt32LE(data, 12);
 				const filetime = low + high * 0x100000000;
 				if (Number.isSafeInteger(filetime)) fields.mtimeMs = filetime / 10_000 - 11_644_473_600_000;
 			}
@@ -384,11 +378,11 @@ function processExtendedHeader(
 			break;
 		case 0x50:
 			if (data.byteLength < 2) throw new ArchiveError("Invalid LZH Unix permissions extended header");
-			fields.mode = u16(data, 0);
+			fields.mode = readUInt16LE(data, 0);
 			break;
 		case 0x54:
 			if (data.byteLength < 4) throw new ArchiveError("Invalid LZH Unix timestamp extended header");
-			fields.mtimeMs = u32(data, 0) * 1000;
+			fields.mtimeMs = readUInt32LE(data, 0) * 1000;
 			break;
 	}
 }
@@ -464,8 +458,8 @@ function parseLzhHeader(bytes: Uint8Array, offset: number, options: FormatReadOp
 	if (level > 2) throw new ArchiveError(`Unsupported LZH header level ${level}`);
 	const method = String.fromCharCode(...bytes.subarray(offset + 2, offset + 7));
 	if (!LHA_METHOD_PATTERN.test(method)) throw new ArchiveError(`Invalid LZH compression method '${method}'`);
-	let packedSize = u32(bytes, offset + 7);
-	let size = u32(bytes, offset + 11);
+	let packedSize = readUInt32LE(bytes, offset + 7);
+	let size = readUInt32LE(bytes, offset + 11);
 	let crc = 0;
 	let legacyFilename: string | undefined;
 	let mtimeMs: number | undefined;
@@ -486,22 +480,22 @@ function parseLzhHeader(bytes: Uint8Array, offset: number, options: FormatReadOp
 		if (22 + nameLength + 2 > headerLength + 2) throw new ArchiveError("Invalid LZH filename length");
 		assertArchivePathBytes(nameLength, "member path", options.limits.maxPathBytes);
 		legacyFilename = decodeLegacy(bytes.subarray(offset + 22, offset + 22 + nameLength));
-		crc = u16(bytes, offset + 22 + nameLength);
-		mtimeMs = dosTimeToMs(u32(bytes, offset + 15));
+		crc = readUInt16LE(bytes, offset + 22 + nameLength);
+		mtimeMs = dosTimeToMs(readUInt32LE(bytes, offset + 15));
 		if (level === 0) {
 			const extendedStart = offset + 24 + nameLength;
 			if (baseEnd - extendedStart >= 12) {
 				const extended = bytes.subarray(extendedStart, baseEnd);
 				if ((extended[0] === 0x55 || extended[0] === 0x4b) && extended[1] === 0) {
 					osId = extended[0]!;
-					fields.mtimeMs = u32(extended, 2) * 1000;
-					fields.mode = u16(extended, extended.byteLength - 6);
+					fields.mtimeMs = readUInt32LE(extended, 2) * 1000;
+					fields.mode = readUInt16LE(extended, extended.byteLength - 6);
 				}
 			}
 			dataStart = baseEnd;
 		} else {
 			osId = bytes[offset + 24 + nameLength]!;
-			let extensionSize = u16(bytes, baseEnd - 2);
+			let extensionSize = readUInt16LE(bytes, baseEnd - 2);
 			let cursor = baseEnd;
 			let totalExtensionSize = 0;
 			let extensionCount = 0;
@@ -519,7 +513,7 @@ function parseLzhHeader(bytes: Uint8Array, offset: number, options: FormatReadOp
 				}
 				processExtendedHeader(type, data, cursor + 1, fields);
 				const currentSize = extensionSize;
-				extensionSize = u16(bytes, dataEnd);
+				extensionSize = readUInt16LE(bytes, dataEnd);
 				cursor += currentSize;
 			}
 			dataStart = baseEnd + totalExtensionSize;
@@ -527,17 +521,17 @@ function parseLzhHeader(bytes: Uint8Array, offset: number, options: FormatReadOp
 			if (packedSize < 0) throw new ArchiveError("Invalid LZH level-1 packed size");
 		}
 	} else {
-		const headerLength = u16(bytes, offset);
+		const headerLength = readUInt16LE(bytes, offset);
 		if (headerLength < 26) throw new ArchiveError("Invalid LZH level-2 header size");
 		const headerEnd = offset + headerLength;
 		assertRange(bytes, offset, headerEnd, "header");
-		crc = u16(bytes, offset + 21);
+		crc = readUInt16LE(bytes, offset + 21);
 		osId = bytes[offset + 23]!;
-		mtimeMs = u32(bytes, offset + 15) * 1000;
+		mtimeMs = readUInt32LE(bytes, offset + 15) * 1000;
 		let cursor = offset + 24;
 		let extensionCount = 0;
 		while (cursor + 2 <= headerEnd) {
-			const extensionSize = u16(bytes, cursor);
+			const extensionSize = readUInt16LE(bytes, cursor);
 			if (extensionSize === 0) {
 				cursor += 2;
 				break;

package/src/ar/sevenzip/decode.ts

@@ -1,5 +1,6 @@
 import { crc32 } from "../checksums";
 import { lzma2Decompress, lzmaDecompress } from "../codecs/lzma";
+import { deltaDecode, x86Decode } from "../codecs/xz";
 import { ArchiveError } from "../error";
 import type { ArchiveLimits } from "../limits";
 import { assertInMemorySize } from "../limits";
@@ -81,62 +82,6 @@ function read32LE(bytes: Uint8Array, offset: number): number {
 	return (bytes[offset]! | (bytes[offset + 1]! << 8) | (bytes[offset + 2]! << 16) | (bytes[offset + 3]! << 24)) >>> 0;
 }
 
-function deltaDecode(bytes: Uint8Array, distance: number): void {
-	const history = new Uint8Array(256);
-	let position = 0;
-	for (let index = 0; index < bytes.byteLength; index++) {
-		const value = (bytes[index]! + history[(distance + position) & 0xff]!) & 0xff;
-		history[position] = value;
-		bytes[index] = value;
-		position = (position - 1) & 0xff;
-	}
-}
-
-function x86Decode(bytes: Uint8Array, startOffset: number): void {
-	const maskToBitNumber = [0, 1, 2, 2, 3] as const;
-	let previousMask = 0;
-	let previousPosition = 0xfffffffb;
-	if (bytes.byteLength < 5) return;
-	let position = 0;
-	const limit = bytes.byteLength - 5;
-	while (position <= limit) {
-		let byte = bytes[position]!;
-		if (byte !== 0xe8 && byte !== 0xe9) {
-			position++;
-			continue;
-		}
-		const absolutePosition = (startOffset + position) >>> 0;
-		const offset = (absolutePosition - previousPosition) >>> 0;
-		previousPosition = absolutePosition;
-		if (offset > 5) previousMask = 0;
-		else for (let index = 0; index < offset; index++) previousMask = ((previousMask & 0x77) << 1) >>> 0;
-		byte = bytes[position + 4]!;
-		if ((byte === 0 || byte === 0xff) && previousMask >>> 1 <= 4 && previousMask >>> 1 !== 3) {
-			let source = read32LE(bytes, position + 1);
-			let destination = 0;
-			for (;;) {
-				destination = (source - absolutePosition - 5) >>> 0;
-				if (previousMask === 0) break;
-				const bitIndex = maskToBitNumber[previousMask >>> 1]! * 8;
-				const testByte = (destination >>> (24 - bitIndex)) & 0xff;
-				if (testByte !== 0 && testByte !== 0xff) break;
-				const lowMask = bitIndex === 0 ? 0xffffffff : 2 ** (32 - bitIndex) - 1;
-				source = (destination ^ lowMask) >>> 0;
-			}
-			bytes[position + 4] = ~(((destination >>> 24) & 1) - 1) & 0xff;
-			bytes[position + 3] = destination >>> 16;
-			bytes[position + 2] = destination >>> 8;
-			bytes[position + 1] = destination;
-			position += 5;
-			previousMask = 0;
-		} else {
-			position++;
-			previousMask |= 1;
-			if (byte === 0 || byte === 0xff) previousMask |= 0x10;
-		}
-	}
-}
-
 /** Shared lazy decoder/cache for a single 7z folder (solid block). */
 export class SevenZipFolderSource {
 	readonly #source: ByteSource;

package/src/ar/tar.ts

@@ -1,5 +1,5 @@
 import * as path from "node:path";
-import { bytesMatchAscii } from "./bytes";
+import { bytesMatchAscii, indexOfAscii } from "./bytes";
 import { resolveArchiveLinkPath, upsertArchiveEntry } from "./entries";
 import { ArchiveError } from "./error";
 import {
@@ -419,13 +419,6 @@ function paxDeclaresSparse(
 	return paxAttribute(globalPax, localPax, PAX_SPARSE_MARKER) === "1";
 }
 
-function indexOfAscii(bytes: Uint8Array, value: string, start: number): number {
-	for (let offset = start; offset <= bytes.byteLength - value.length; offset++) {
-		if (bytesMatchAscii(bytes, offset, value)) return offset;
-	}
-	return -1;
-}
-
 function normalizeOldGnuName(value: string, field: string, limits: ArchiveLimits): string {
 	const portable = value.replace(/\\/g, "/");
 	if (path.posix.isAbsolute(portable)) throw new ArchiveError(`Invalid old-GNU ${field}`);

package/src/bytes.ts

@@ -0,0 +1,14 @@
+/**
+ * Narrow `bytes` to a view over its own whole `ArrayBuffer`, which is what
+ * `crypto.subtle.{digest,sign,importKey,encrypt,decrypt}` require under the
+ * strict TS DOM typings. Returns `bytes` itself when it already is one,
+ * otherwise a copy.
+ */
+export function asStrictBytes(bytes: Uint8Array): Uint8Array<ArrayBuffer> {
+	if (bytes.buffer instanceof ArrayBuffer && bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength) {
+		return bytes as Uint8Array<ArrayBuffer>;
+	}
+	const copy = new Uint8Array(bytes.byteLength);
+	copy.set(bytes);
+	return copy;
+}

package/src/held-file.ts

@@ -0,0 +1,22 @@
+/**
+ * Refuses overwriting a file this process holds open with locks (issue #15586).
+ *
+ * Writing over a live `agent.db` or its `-shm` destroys the store (a truncated
+ * `-shm` also faults the connection's memory map), so tools that write
+ * agent-chosen paths check here first.
+ */
+import { heldFileKind } from "@oh-my-pi/pi-natives/sqlite-locks";
+
+/**
+ * Throws an `EBUSY` error when `filePath` is a file this process holds open with
+ * locks: a SQLite database or `-shm` of a live connection. Always passes outside Linux.
+ */
+export function assertNotHeldOpen(filePath: string): void {
+	const kind = heldFileKind(filePath);
+	if (!kind) return;
+	const holder = kind === "locked" ? "a file lock" : "a SQLite connection";
+	throw Object.assign(
+		new Error(`EBUSY: '${filePath}' is held open by ${holder} in this process; overwriting it would destroy it`),
+		{ code: "EBUSY", path: filePath },
+	);
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 export { once, untilAborted } from "./abortable";
 export * from "./async";
 export * from "./binary";
+export * from "./bytes";
 export * from "./color";
 export * from "./dirs";
 export * from "./env";
@@ -22,6 +23,7 @@ export * from "./mime";
 export * from "./path";
 export * from "./path-tree";
 export * from "./peek-file";
+export * from "./pid";
 export * as postmortem from "./postmortem";
 export * from "./process-name";
 export * as procmgr from "./procmgr";

package/src/logger.ts

@@ -22,6 +22,7 @@ import * as path from "node:path";
 import { isPromise } from "node:util/types";
 import { getLogsDir, localDay } from "./dirs";
 import { RotatingFileSink } from "./logger/rotating-file";
+import { isPidAlive } from "./pid";
 import { setStderrRedirectTarget } from "./stderr-guard";
 import { drainModuleLoadEvents } from "./timing-buffer";
 /** Severity names accepted by the centralized logger. */
@@ -81,15 +82,6 @@ const LEGACY_AUDIT_PATTERN = /^\.[0-9a-f]{8,}-audit\.json$/;
 const RETAINED_STALE_LOGS_PER_PROCESS_DAY = 1;
 const RETAINED_STALE_LOG_DAYS = 5;
 
-function processIsRunning(pid: number): boolean {
-	try {
-		process.kill(pid, 0);
-		return true;
-	} catch (error) {
-		return !(error instanceof Error && "code" in error && (error.code === "ESRCH" || error.code === "EINVAL"));
-	}
-}
-
 /**
  * Retain one newest completed-process log per process/day within the current
  * and previous four local calendar days, remove completed-process audit files
@@ -133,7 +125,7 @@ function pruneStaleProcessLogs(dir: string): void {
 		const logMatch = PROCESS_LOG_PATTERN.exec(entry.name);
 		const auditMatch = PROCESS_AUDIT_PATTERN.exec(entry.name);
 		const pidText = logMatch?.[2] ?? auditMatch?.[1];
-		if (!pidText || processIsRunning(Number(pidText))) continue;
+		if (!pidText || isPidAlive(Number(pidText))) continue;
 
 		if (auditMatch) {
 			removeBestEffort(entryPath);

package/src/pid.ts

@@ -0,0 +1,16 @@
+/**
+ * Signal-0 liveness probe: true unless the OS reports the pid as gone
+ * (`ESRCH`) or invalid (`EINVAL`). Any other failure, notably `EPERM` (alive
+ * but owned by another user), reads as alive, so callers never reclaim a
+ * resource a live process may still hold. Unlike `procmgr.isPidRunning`, this
+ * does not consult the process table's run state.
+ */
+export function isPidAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException | undefined)?.code;
+		return code !== "ESRCH" && code !== "EINVAL";
+	}
+}

package/src/postmortem.ts

@@ -10,6 +10,7 @@ import * as fs from "node:fs";
 import { APP_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 });
 			}
 		}
@@ -708,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)}`);
@@ -753,7 +754,7 @@ export function installProcessHandlers(): void {
 				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.
@@ -786,7 +787,7 @@ export function installProcessHandlers(): void {
 			);
 		})
 		.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 });
@@ -876,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
@@ -886,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 "@oh-my-pi/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;
 }