@linxiraos/pi-utils 1.1.5 → 1.1.7

package/src/ptree.ts

@@ -15,6 +15,83 @@ type InMask = "pipe" | "ignore" | Buffer | Uint8Array | null;
 /** A Bun subprocess with stdout/stderr always piped (stdin may vary). */
 type PipedSubprocess<In extends InMask = InMask> = Subprocess<In, "pipe", "pipe">;
 
+const LINUX_SUBREAPER_COMMAND_ENV = "OMP_PTREE_SUBREAPER_COMMAND";
+const LINUX_SUBREAPER_BUN_BE_BUN_ENV = "OMP_PTREE_SUBREAPER_BUN_BE_BUN";
+
+/**
+ * Build the Linux child-subreaper entrypoint.
+ *
+ * @internal Exported so tests can force a missing first libc soname and verify
+ * the loader continues to the next candidate.
+ */
+export function createLinuxSubreaperScript(libcCandidates: readonly string[] = ["libc.so.6", "libc.so"]): string {
+	return `
+import { dlopen, FFIType } from "bun:ffi";
+
+let libc;
+for (const soname of ${JSON.stringify(libcCandidates)}) {
+	try {
+		libc = dlopen(soname, {
+			prctl: {
+				args: [FFIType.i32, FFIType.u64, FFIType.u64, FFIType.u64, FFIType.u64],
+				returns: FFIType.i32,
+			},
+			waitpid: {
+				args: [FFIType.i32, FFIType.ptr, FFIType.i32],
+				returns: FFIType.i32,
+			},
+		});
+		break;
+	} catch {}
+}
+if (!libc) throw new Error("failed to load libc for Linux child supervision");
+
+if (libc.symbols.prctl(36, 1, 0, 0, 0) !== 0) {
+	throw new Error("failed to become a Linux child subreaper");
+}
+
+const commandJson = Bun.env.${LINUX_SUBREAPER_COMMAND_ENV};
+if (!commandJson) throw new Error("missing supervised command");
+const callerBunBeBun = Bun.env.${LINUX_SUBREAPER_BUN_BE_BUN_ENV};
+delete Bun.env.${LINUX_SUBREAPER_COMMAND_ENV};
+delete Bun.env.${LINUX_SUBREAPER_BUN_BE_BUN_ENV};
+if (callerBunBeBun === undefined) delete Bun.env.BUN_BE_BUN;
+else Bun.env.BUN_BE_BUN = callerBunBeBun;
+const command = JSON.parse(commandJson);
+const child = Bun.spawn(command, {
+	stdin: "inherit",
+	stdout: "pipe",
+	stderr: "pipe",
+	windowsHide: true,
+	env: Bun.env,
+});
+
+async function relay(stream, destination) {
+	const writer = destination.writer();
+	for await (const chunk of stream) writer.write(chunk);
+	await writer.flush();
+}
+
+function hasLiveChildren() {
+	let childPid;
+	do {
+		childPid = libc.symbols.waitpid(-1, null, 1);
+	} while (childPid > 0);
+	return childPid === 0;
+}
+
+const [exitCode] = await Promise.all([
+	child.exited,
+	relay(child.stdout, Bun.stdout),
+	relay(child.stderr, Bun.stderr),
+]);
+while (hasLiveChildren()) await Bun.sleep(10);
+process.exit(exitCode ?? 1);
+`;
+}
+
+const LINUX_SUBREAPER_SCRIPT = createLinuxSubreaperScript();
+
 // ── Exceptions ───────────────────────────────────────────────────────────────
 
 /**
@@ -103,13 +180,30 @@ export class ChildProcess<In extends InMask = InMask> {
 	#exitReasonPending?: Exception;
 	#stderrDone: Promise<void>;
 	#exited: Promise<number>;
+	#openPipeReaders = 1;
+	// Pipe reads race this cutoff only when attachTimeout() configures a
+	// command deadline. Untimed commands preserve complete EOF-based capture.
+	#drainCutoff: Promise<void>;
+	#resolveDrainCutoff: () => void;
+	#timeoutTimer?: NodeJS.Timeout;
 	#stderrStream?: ReadableStream<Uint8Array>;
-
+	// Termination in flight after kill(); aborted exits await it before reporting.
+	#terminating?: Promise<boolean | void>;
+	#terminateGroup: boolean;
+	#hardKillTree: boolean;
+	// Windows has no process groups. Retaining the root's native handle pins
+	// its PID after exit so killTree() can still enumerate its original children.
+	#windowsRootProcess?: Process;
 	constructor(
 		readonly proc: PipedSubprocess<In>,
 		readonly exposeStderr: boolean,
 		retainFullStderr = exposeStderr,
+		terminateGroup = false,
+		hardKillTree = false,
 	) {
+		this.#terminateGroup = terminateGroup;
+		this.#hardKillTree = hardKillTree;
+		this.#windowsRootProcess = process.platform === "win32" ? (Process.fromPid(proc.pid) ?? undefined) : undefined;
 		if (retainFullStderr) this.#stderrChunks = [];
 		// Eagerly drain stderr into a truncated tail, retaining raw chunks only for explicit full capture.
 		const dec = new TextDecoder();
@@ -123,22 +217,39 @@ export class ChildProcess<In extends InMask = InMask> {
 			this.#stderrStream = teeStream;
 			stderrStream = drainStream;
 		}
+		// Normalize Bun's exited promise into our exitReason / exitedCleanly model.
+		const { promise, resolve, reject } = Promise.withResolvers<number>();
+		this.#exited = promise;
+		const drainCutoff = Promise.withResolvers<void>();
+		this.#drainCutoff = drainCutoff.promise;
+		this.#resolveDrainCutoff = drainCutoff.resolve;
+		// The cutoff remains pending for untimed commands, preserving complete
+		// EOF-based capture. attachTimeout() resolves it at the command deadline.
+
+		const pipeCutoff = this.#drainCutoff;
 		this.#stderrDone = (async () => {
+			const reader = stderrStream.getReader();
 			try {
-				for await (const chunk of stderrStream) {
-					this.#stderrChunks?.push(chunk);
-					this.#stderrTail += dec.decode(chunk, { stream: true });
+				for (;;) {
+					const chunk = await Promise.race([
+						reader.read().then(r => ({ cutoff: false as const, r })),
+						pipeCutoff.then(() => ({ cutoff: true as const })),
+					]);
+					if (chunk.cutoff) {
+						await reader.cancel().catch(() => {});
+						break;
+					}
+					if (chunk.r.done) break;
+					this.#stderrChunks?.push(chunk.r.value);
+					this.#stderrTail += dec.decode(chunk.r.value, { stream: true });
 					trim();
 				}
 			} catch {}
+			this.#openPipeReaders--;
 			this.#stderrTail += dec.decode();
 			trim();
 		})();
 
-		// Normalize Bun's exited promise into our exitReason / exitedCleanly model.
-		const { promise, resolve, reject } = Promise.withResolvers<number>();
-		this.#exited = promise;
-
 		proc.exited
 			.catch(() => null)
 			.then(async exitCode => {
@@ -153,6 +264,11 @@ export class ChildProcess<In extends InMask = InMask> {
 				}
 
 				await this.#stderrDone;
+				if (this.#exitReasonPending) {
+					this.#exitReason = this.#exitReasonPending;
+					reject(this.#exitReasonPending);
+					return;
+				}
 
 				if (exitCode !== null) {
 					this.#exitReason = new NonZeroExitError(exitCode, this.#stderrTail);
@@ -218,44 +334,160 @@ export class ChildProcess<In extends InMask = InMask> {
 	}
 
 	kill(reason?: Exception, gracefulMs?: number) {
-		if (reason && !this.#exitReasonPending) this.#exitReasonPending = reason;
-		if (!this.proc.killed)
-			void Process.fromPid(this.proc.pid)
-				?.terminate(gracefulMs === undefined ? undefined : { gracefulMs })
+		if (reason && !this.#exitReasonPending) {
+			this.#exitReasonPending = reason;
+			// The normalized exit promise may already have resolved from a dead
+			// group leader; wait() still needs to report the later deadline.
+			if (this.proc.exitCode !== null) this.#exitReason = reason;
+		}
+		if (gracefulMs !== undefined && gracefulMs < 0 && this.#hardKillTree && this.proc.exitCode === null) {
+			// terminate() sends its polite wave to the root before rebuilding the
+			// hard-kill tree. A subreaper root can die in that gap and release its
+			// adopted descendants, so snapshot and hard-kill the live tree first.
+			const root = Process.fromPid(this.proc.pid);
+			if (root) {
+				root.killTree(9);
+				this.#terminating = Promise.resolve();
+				return;
+			}
+		}
+		if (
+			this.proc.exitCode !== null &&
+			this.#terminateGroup &&
+			this.#openPipeReaders > 0 &&
+			process.platform !== "win32"
+		) {
+			// Bun detached children are POSIX session/process-group leaders. If
+			// the leader has exited, the native Process handle cannot rediscover
+			// its PGID, but a pipe-holding descendant keeps that exact group alive.
+			try {
+				process.kill(-this.proc.pid, "SIGKILL");
+			} catch {}
+			this.#terminating = Promise.resolve();
+			return;
+		}
+		if (this.proc.exitCode !== null && this.#windowsRootProcess && this.#openPipeReaders > 0) {
+			// The retained handle keeps the dead root PID reserved, making the
+			// Windows Toolhelp descendant walk identity-safe after root exit.
+			this.#windowsRootProcess.killTree();
+			this.#terminating = Promise.resolve();
+			return;
+		}
+		if (!this.proc.killed) {
+			const options =
+				gracefulMs === undefined
+					? this.#terminateGroup
+						? { group: true }
+						: undefined
+					: { gracefulMs, group: this.#terminateGroup };
+			this.#terminating = (this.#windowsRootProcess ?? Process.fromPid(this.proc.pid))
+				?.terminate(options)
 				?.catch(e => void e);
+		}
 	}
 
 	// ── Output helpers ───────────────────────────────────────────────────
 
+	async #throwIfAborted(): Promise<void> {
+		const exitReason = this.exitReason;
+		if (!exitReason?.aborted) return;
+		if (this.#terminating) await this.#terminating;
+		throw exitReason;
+	}
+
 	async text(): Promise<string> {
-		const p = new Response(this.stdout).text();
+		const p = this.#readStream(this.proc.stdout);
 		if (this.#nothrow) return p;
 		const [text] = await Promise.all([p, this.exitedCleanly]);
+		await this.#throwIfAborted();
 		return text;
 	}
 
-	async blob(): Promise<Blob> {
-		const p = new Response(this.stdout).blob();
+	/**
+	 * Read a pipe fully, stopping early only at an explicit command deadline.
+	 */
+	async #readStream(stream: ReadableStream<Uint8Array>): Promise<string> {
+		this.#openPipeReaders++;
+		const reader = stream.getReader();
+		const dec = new TextDecoder();
+		let out = "";
+		try {
+			for (;;) {
+				const chunk = await Promise.race([
+					reader.read().then(r => ({ cutoff: false as const, r })),
+					this.#drainCutoff.then(() => ({ cutoff: true as const })),
+				]);
+				if (chunk.cutoff) {
+					await reader.cancel().catch(() => {});
+					break;
+				}
+				if (chunk.r.done) break;
+				out += dec.decode(chunk.r.value, { stream: true });
+			}
+		} catch {
+			// A cancelled or failed read keeps whatever was already collected.
+		}
+		this.#openPipeReaders--;
+		return out + dec.decode();
+	}
+
+	async #readBytes(): Promise<Uint8Array> {
+		const reader = this.proc.stdout.getReader();
+		this.#openPipeReaders++;
+		const chunks: Uint8Array[] = [];
+		let length = 0;
+		try {
+			for (;;) {
+				const chunk = await Promise.race([
+					reader.read().then(r => ({ cutoff: false as const, r })),
+					this.#drainCutoff.then(() => ({ cutoff: true as const })),
+				]);
+				if (chunk.cutoff) {
+					await reader.cancel().catch(() => {});
+					break;
+				}
+				if (chunk.r.done) break;
+				chunks.push(chunk.r.value);
+				length += chunk.r.value.byteLength;
+			}
+		} catch {
+			// A cancelled or failed read keeps whatever was already collected.
+		} finally {
+			this.#openPipeReaders--;
+			reader.releaseLock();
+		}
+
+		const bytes = new Uint8Array(length);
+		let offset = 0;
+		for (const chunk of chunks) {
+			bytes.set(chunk, offset);
+			offset += chunk.byteLength;
+		}
+		return bytes;
+	}
+
+	async #readOutputBytes(waitForCleanExit = false): Promise<Uint8Array> {
+		const p = this.#readBytes();
 		if (this.#nothrow) return p;
-		const [blob] = await Promise.all([p, this.exitedCleanly]);
-		return blob;
+		const bytes = waitForCleanExit ? (await Promise.all([p, this.exitedCleanly]))[0] : await p;
+		await this.#throwIfAborted();
+		return bytes;
+	}
+
+	async blob(): Promise<Blob> {
+		return new Blob([await this.#readOutputBytes(true)]);
 	}
 
 	async json(): Promise<unknown> {
-		return new Response(this.stdout).json();
+		return JSON.parse(new TextDecoder().decode(await this.#readOutputBytes()));
 	}
 
 	async arrayBuffer(): Promise<ArrayBuffer> {
-		return new Response(this.stdout).arrayBuffer();
+		return (await this.#readOutputBytes()).buffer as ArrayBuffer;
 	}
 
 	async bytes(): Promise<Uint8Array> {
-		// Bun's `Response(stream).bytes()` returns the raw `ArrayBuffer` once the
-		// stream emits more than one chunk (subprocess stdout chunks past ~128 KB).
-		// Normalize at the contract boundary so every caller — SSH read,
-		// `decodeUtf8Text`, callers slicing with `.subarray` — sees a `Uint8Array`.
-		const body = (await new Response(this.stdout).bytes()) as Uint8Array | ArrayBuffer;
-		return body instanceof Uint8Array ? body : new Uint8Array(body);
+		return this.#readOutputBytes();
 	}
 
 	// ── Wait ─────────────────────────────────────────────────────────────
@@ -267,7 +499,7 @@ export class ChildProcess<In extends InMask = InMask> {
 			throw new Error('Full stderr capture must be requested when spawning the process (pass stderr: "full")');
 		}
 
-		const stdoutP = new Response(this.stdout).text();
+		const stdoutP = this.#readStream(this.proc.stdout);
 		const stderrP =
 			stderrMode === "full" && stderrChunks
 				? this.#stderrDone.then(() => new TextDecoder().decode(Buffer.concat(stderrChunks)))
@@ -282,12 +514,17 @@ export class ChildProcess<In extends InMask = InMask> {
 			if (err instanceof Exception) exitError = err;
 			else throw err;
 		}
-
+		this.#clearTimeout();
 		if (!exitError) exitError = this.exitReason;
 		if (!exitError && this.exitCode !== null && this.exitCode !== 0) {
 			exitError = new NonZeroExitError(this.exitCode, this.#stderrTail);
 		}
 
+		// On abort/timeout, hold the result until the tree is actually gone: the
+		// native terminate() is graceful-first, and reporting before it finishes
+		// would leave timed-out descendants alive past the caller's budget.
+		if (exitError?.aborted && this.#terminating) await this.#terminating;
+
 		const exitCode = this.exitCode ?? (exitError && !exitError.aborted ? exitError.exitCode : null);
 		const ok = exitCode === 0;
 
@@ -307,18 +544,32 @@ export class ChildProcess<In extends InMask = InMask> {
 		this.#exited.catch(() => {}).finally(() => signal.removeEventListener("abort", onAbort));
 	}
 
+	#clearTimeout(): void {
+		if (!this.#timeoutTimer) return;
+		clearTimeout(this.#timeoutTimer);
+		this.#timeoutTimer = undefined;
+	}
+
 	attachTimeout(ms: number): void {
 		if (ms <= 0 || this.proc.killed) return;
 		this.#exited.catch(() => {});
-		Promise.race([
-			Bun.sleep(ms).then(() => true),
-			this.proc.exited.then(
-				() => false,
-				() => false,
-			),
-		]).then(timedOut => {
-			if (timedOut) this.kill(new TimeoutError(ms, this.#stderrTail));
-		});
+		// One unref'd deadline controls both termination and pipe collection.
+		// A clean command clears it in wait(), so fast invocations do not hold
+		// the event loop for the unused remainder.
+		const timer = setTimeout(() => {
+			// A detached group can remain alive after its leader exits. Only use
+			// the dead-leader fallback while an inherited pipe proves that exact
+			// group still has a live member; this avoids stale-PGID reuse.
+			if (
+				this.proc.exitCode === null ||
+				(this.#openPipeReaders > 0 && (this.#terminateGroup || this.#windowsRootProcess))
+			) {
+				this.kill(new TimeoutError(ms, this.#stderrTail), -1);
+			}
+			this.#resolveDrainCutoff();
+		}, ms);
+		timer.unref?.();
+		this.#timeoutTimer = timer;
 	}
 
 	[Symbol.dispose](): void {
@@ -336,6 +587,13 @@ type ChildSpawnOptions<In extends InMask = InMask> = Omit<
 > & {
 	signal?: AbortSignal;
 	detached?: boolean;
+	/**
+	 * On Linux, supervise the command from a child subreaper so descendants
+	 * remain reachable after changing session and reparenting. Other platforms
+	 * ignore this option. macOS process groups cannot retain a daemonized
+	 * descendant that creates a new session and reparents to launchd.
+	 */
+	subreaper?: boolean;
 	/** Expose and retain complete stderr for a later `wait({ stderr: "full" })`. */
 	stderr?: "full" | null;
 };
@@ -345,15 +603,26 @@ function spawnInternal<In extends InMask = InMask>(
 	opts: ChildSpawnOptions<In> | undefined,
 	retainFullStderr: boolean,
 ): ChildProcess<In> {
-	const { timeout = -1, signal, stderr, ...rest } = opts ?? {};
-	const child = Bun.spawn(cmd, {
+	const { timeout = -1, signal, stderr, detached, subreaper = false, ...rest } = opts ?? {};
+	const useSubreaper = subreaper && process.platform === "linux";
+	const commandEnv = rest.env ?? Bun.env;
+	const child = Bun.spawn(useSubreaper ? [process.execPath, "-e", LINUX_SUBREAPER_SCRIPT] : cmd, {
 		stdin: "ignore",
 		stdout: "pipe",
 		stderr: "pipe",
 		windowsHide: true,
+		detached,
 		...rest,
+		env: useSubreaper
+			? {
+					...commandEnv,
+					BUN_BE_BUN: "1",
+					[LINUX_SUBREAPER_COMMAND_ENV]: JSON.stringify(cmd),
+					[LINUX_SUBREAPER_BUN_BE_BUN_ENV]: commandEnv.BUN_BE_BUN,
+				}
+			: rest.env,
 	});
-	const cp = new ChildProcess(child, stderr === "full", retainFullStderr);
+	const cp = new ChildProcess(child, stderr === "full", retainFullStderr, detached === true, useSubreaper);
 	if (signal) cp.attachSignal(signal);
 	if (timeout > 0) cp.attachTimeout(timeout);
 	return cp;

package/src/runtime-install.ts

@@ -2,6 +2,8 @@ import * as fs from "node:fs";
 import * as fsp from "node:fs/promises";
 import * as Module from "node:module";
 import * as path from "node:path";
+import { withFileLock } from "./file-lock";
+import { isEexist, isEnoent } from "./fs-error";
 
 /**
  * On-demand runtime dependency support for native-heavy optional packages
@@ -303,25 +305,62 @@ export interface EnsureRuntimeInstalledOptions {
 	lockSleepMs?: number;
 }
 
-function isErrnoCode(error: unknown, code: string): boolean {
-	return typeof error === "object" && error !== null && "code" in error && error.code === code;
-}
+/** No runtime install plausibly runs this long, so older legacy lock directories are crash orphans. */
+const STALE_LEGACY_LOCK_MS = 10 * 60_000;
 
-async function acquireInstallLock(runtimeDir: string, attempts: number, sleepMs: number): Promise<() => Promise<void>> {
-	const lockDir = `${runtimeDir}.lock`;
-	await fsp.mkdir(path.dirname(lockDir), { recursive: true });
-	for (let attempt = 0; attempt < attempts; attempt++) {
+/**
+ * Run `fn` while reserving the pre-crash-safe `${runtimeDir}.lock` namespace.
+ *
+ * Versions through 18.0.10 serialized installs with a bare lock *directory*
+ * that only its creator removed; an installer killed outside that window
+ * (SIGKILL/OOM/Ctrl-C) left it unreleasable, wedging every later install for
+ * the full wait envelope (issue #10120). During an in-flight upgrade a legacy
+ * process may still legitimately own this directory, so poll until it is
+ * released and only force-reclaim once the directory is older than any
+ * plausible install ({@link STALE_LEGACY_LOCK_MS}) — never merely because a
+ * retry budget elapsed, which would delete a still-active legacy lock and let
+ * two installers race the same tree. Once the namespace is free, atomically
+ * create and retain a regular file through `fn`: an older process cannot
+ * acquire it between the handoff check and the new install. A file left by a
+ * crashed new installer can be reused immediately because the outer OS lock
+ * proves its owner is gone, unlike a legacy directory whose owner is unknown.
+ */
+async function withLegacyInstallLock<T>(runtimeDir: string, sleepMs: number, fn: () => Promise<T>): Promise<T> {
+	const legacy = `${runtimeDir}.lock`;
+	for (;;) {
 		try {
-			await fsp.mkdir(lockDir);
-			return async () => {
-				await fsp.rm(lockDir, { recursive: true, force: true });
-			};
+			const reservation = await fsp.open(legacy, "wx");
+			await reservation.close();
 		} catch (error) {
-			if (!isErrnoCode(error, "EEXIST")) throw error;
-			await Bun.sleep(sleepMs);
+			if (!isEexist(error)) throw error;
+			let stat: fs.Stats;
+			try {
+				stat = await fsp.stat(legacy);
+			} catch (statError) {
+				if (isEnoent(statError)) continue; // released between open and stat; retry
+				throw statError;
+			}
+			// A non-directory is a reservation left by a newer installer. The
+			// outer OS lock proves that installer is gone, so reuse it at once.
+			if (!stat.isDirectory()) break;
+			// A fresh directory may still belong to a live pre-18.x installer, so
+			// wait for it to finish; only a crash orphan (older than any plausible
+			// install) is force-reclaimed.
+			if (Date.now() - stat.mtimeMs > STALE_LEGACY_LOCK_MS) {
+				await fsp.rm(legacy, { recursive: true, force: true });
+			} else {
+				await Bun.sleep(sleepMs);
+			}
+			continue;
 		}
+		break;
+	}
+	// Retain the regular-file reservation across the install.
+	try {
+		return await fn();
+	} finally {
+		await fsp.rm(legacy, { force: true });
 	}
-	throw new Error(`Timed out waiting for runtime install lock: ${lockDir}`);
 }
 
 export async function writeRuntimeManifest(runtimeDir: string, install: RuntimeInstallSpec): Promise<void> {
@@ -363,7 +402,14 @@ async function runRuntimeInstall(runtimeDir: string): Promise<void> {
 
 /**
  * Materialize a pinned dependency set into `runtimeDir` (idempotent,
- * cross-process safe via a lock directory). Returns `runtimeDir`.
+ * cross-process safe). Returns `runtimeDir`.
+ *
+ * Serialization uses the OS-backed {@link withFileLock} at
+ * `${runtimeDir}.install.lock`, which the kernel releases on process death, so
+ * a crashed installer cannot wedge later attempts (issue #10120). The path is
+ * deliberately distinct from the legacy `${runtimeDir}.lock` mkdir directory;
+ * {@link withLegacyInstallLock} atomically reserves that namespace during the
+ * new install so older processes cannot cross the migration boundary.
  */
 export async function ensureRuntimeInstalled(options: EnsureRuntimeInstalledOptions): Promise<string> {
 	const { runtimeDir, install, onPhase, lockAttempts = 240, lockSleepMs = 250 } = options;
@@ -379,15 +425,20 @@ export async function ensureRuntimeInstalled(options: EnsureRuntimeInstalledOpti
 	if (await probeManifest.exists()) return runtimeDir;
 
 	onPhase?.("initiate");
-	const releaseLock = await acquireInstallLock(runtimeDir, lockAttempts, lockSleepMs);
-	try {
-		if (await probeManifest.exists()) return runtimeDir;
-		await writeRuntimeManifest(runtimeDir, install);
-		onPhase?.("download");
-		await runRuntimeInstall(runtimeDir);
-		onPhase?.("done");
-		return runtimeDir;
-	} finally {
-		await releaseLock();
-	}
+	// withFileLock does not create parent directories; the runtime cache dir may
+	// not exist yet on the very first install.
+	await fsp.mkdir(path.dirname(runtimeDir), { recursive: true });
+	return withFileLock(
+		`${runtimeDir}.install`,
+		() =>
+			withLegacyInstallLock(runtimeDir, lockSleepMs, async () => {
+				if (await probeManifest.exists()) return runtimeDir;
+				await writeRuntimeManifest(runtimeDir, install);
+				onPhase?.("download");
+				await runRuntimeInstall(runtimeDir);
+				onPhase?.("done");
+				return runtimeDir;
+			}),
+		{ retries: lockAttempts, retryDelayMs: lockSleepMs },
+	);
 }

package/src/sqlite.ts

@@ -7,6 +7,12 @@
  * one implementation here prevents the classifiers from drifting between the
  * credential store and the model cache.
  */
+import type { Database } from "bun:sqlite";
+
+/** Checkpoints committed WAL frames without waiting for concurrent readers. */
+export function checkpointWal(db: Database): void {
+	db.run("PRAGMA wal_checkpoint(PASSIVE)");
+}
 
 /**
  * SQLite's busy result-code family — base `SQLITE_BUSY` plus the extended