@oh-my-pi/pi-utils 18.0.9 → 18.0.11

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [18.0.11] - 2026-08-29
+
+### Fixed
+
+- Fixed runtime installation getting stuck for up to 60 seconds after an installer crash or forced termination, allowing subsequent installation attempts to proceed normally.
+
+## [18.0.10] - 2026-08-28
+
+### Added
+
+- Added `postmortem.drainStdout` to flush buffered standard output before process exit or exec-replacement.
+- Added an `exitOnly` option to `postmortem.register` for resources that should remain available during keep-alive cleanup and be released only on actual process exit.
+- Added `hexToOklch` and `oklchToHex` color conversion utilities with sRGB gamut mapping that reduces chroma when necessary.
+- Added `checkpointWal` to checkpoint committed SQLite WAL frames without blocking concurrent readers.
+
+### Fixed
+
+- Fixed repeatable `postmortem` cleanup behavior so persistent resources and callbacks registered during cleanup remain active until the eventual process exit.
+- Fixed asynchronous `postmortem` cleanup so callbacks registered during a cleanup pass are awaited before cleanup completes, including during signal-driven exits.
+
 ## [18.0.9] - 2026-08-28
 
 ### Fixed

package/dist/types/async.d.ts

@@ -17,4 +17,6 @@ export declare class AsyncDrain<T> {
     constructor(delayMs?: number);
     /** Queue `value`; `hnd` receives the whole batch when the window closes. */
     push(value: T, hnd: (values: T[]) => Promise<void> | void): Promise<void>;
+    /** Runs the pending batch handler immediately and returns its completion promise. */
+    flush(): Promise<void>;
 }

package/dist/types/color.d.ts

@@ -82,6 +82,40 @@ export declare function adjustHsv(hex: string, adj: HSVAdjustment): string;
  * Convert HSL (h: 0-360, s: 0-1, l: 0-1) to a CSS hex string.
  */
 export declare function hslToHex(h: number, s: number, l: number): string;
+export interface OKLCH {
+    /** Perceptual lightness (0-1) */
+    l: number;
+    /** Chroma (0 = gray; sRGB peaks around 0.37) */
+    c: number;
+    /** Hue in degrees (0-360) */
+    h: number;
+}
+/**
+ * Convert a hex color to OKLCH (perceptual lightness/chroma/hue).
+ *
+ * Unlike HSL, equal `l`/`c` values look equally bright and colorful across
+ * hues, so carrying them between colors preserves the palette's "weight".
+ */
+export declare function hexToOklch(hex: string): OKLCH;
+/**
+ * The sRGB gamut cusp for an OKLCH hue: the lightness/chroma point where the
+ * hue reaches its maximum chroma inside sRGB.
+ *
+ * The cusp lightness varies wildly per hue (yellow ≈ 0.97, blue ≈ 0.45), so
+ * transferring absolute OKLCH lightness/chroma between hues distorts
+ * vividness; normalize against the cusp instead. See `getSessionAccentHex`.
+ */
+export declare function oklchCusp(h: number): {
+    l: number;
+    c: number;
+};
+/**
+ * Convert OKLCH to a CSS hex string, gamut-mapping by chroma reduction.
+ *
+ * Out-of-gamut inputs keep their lightness and hue while chroma is bisected
+ * down until the color fits sRGB, matching CSS Color 4's recommended intent.
+ */
+export declare function oklchToHex(oklch: OKLCH): string;
 /**
  * Perceptual luma (gamma-encoded BT.709 weights over raw sRGB), normalized to 0..1.
  *

package/dist/types/postmortem.d.ts

@@ -123,15 +123,33 @@ export declare function interceptUnhandledRejections(interceptor: (reason: unkno
  * through an uncaught exception or unhandled rejection.
  */
 export declare function registerFatalRecoveryHint(provider: FatalRecoveryHintProvider): () => void;
+/** Controls when a registered cleanup callback participates in cleanup passes. */
+export interface CleanupRegistrationOptions {
+    /**
+     * Run only on a real exit, never during a manual keep-alive cleanup.
+     * The registration remains armed when a keep-alive pass skips it.
+     */
+    exitOnly?: boolean;
+}
 /**
- * Register a process cleanup callback, to be run on shutdown, signal, or fatal error.
+ * Registers a cleanup callback for shutdown, signals, fatal errors, and
+ * repeatable manual cleanup passes.
+ *
+ * Registrations persist across keep-alive {@link cleanup} passes and run at
+ * most once per pass. Set `exitOnly` for resources the continuing process still
+ * holds (open databases, cached handles): keep-alive passes skip the callback
+ * without consuming its registration, while the eventual real exit runs it.
+ *
+ * A callback registered during a running keep-alive pass joins future passes;
+ * normal callbacks also run immediately for the current pass. Registrations
+ * made during a real exit run immediately.
  *
- * Returns a Callback instance that can be used to cancel (unregister) or manually clean up.
- * If register is called after cleanup already began, invokes callback on a microtask.
+ * Returns a function that permanently cancels the registration.
  */
-export declare function register(id: string, callback: (reason: Reason) => void | Promise<void>): () => void;
+export declare function register(id: string, callback: (reason: Reason) => void | Promise<void>, options?: CleanupRegistrationOptions): () => void;
 /**
- * Runs all cleanup callbacks without exiting.
+ * Runs all cleanup callbacks without exiting, then re-arms the system so
+ * resources opened afterwards are still cleaned at the eventual real exit.
  * Use this in workers or when you need to clean up but continue execution.
  */
 export declare function cleanup(): Promise<void>;
@@ -140,6 +158,12 @@ export interface QuitOptions {
     /** Wait for buffered stdout before exiting; disable after the terminal has disconnected. */
     drainStdout?: boolean;
 }
+/**
+ * Waits (bounded) for buffered stdout to reach the terminal. Used before
+ * process exit and before an exec-replace, where unflushed output would be
+ * lost with the process image.
+ */
+export declare function drainStdout(): Promise<void>;
 /**
  * Runs all cleanup callbacks and exits through the current `process.exit`.
  *

package/dist/types/runtime-install.d.ts

@@ -73,6 +73,13 @@ export interface EnsureRuntimeInstalledOptions {
 export declare function writeRuntimeManifest(runtimeDir: string, install: RuntimeInstallSpec): 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 declare function ensureRuntimeInstalled(options: EnsureRuntimeInstalledOptions): Promise<string>;

package/dist/types/sqlite.d.ts

@@ -7,6 +7,9 @@
  * 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 declare function checkpointWal(db: Database): void;
 /**
  * SQLite's busy result-code family — base `SQLITE_BUSY` plus the extended
  * variants `SQLITE_BUSY_RECOVERY` (concurrent WAL recovery), `SQLITE_BUSY_SNAPSHOT`,

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "18.0.9",
+	"version": "18.0.11",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://omp.sh",
 	"author": "Stencil Labs, Inc.",
@@ -31,7 +31,7 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.0.9"
+		"@oh-my-pi/pi-natives": "18.0.11"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/async.ts

@@ -59,6 +59,7 @@ export function withTimeout<T>(promise: Promise<T>, ms: number, message: string,
 export class AsyncDrain<T> {
 	#queue?: T[];
 	#promise = Promise.resolve();
+	#flush?: () => void;
 
 	constructor(readonly delayMs: number = 0) {}
 
@@ -66,21 +67,28 @@ export class AsyncDrain<T> {
 	push(value: T, hnd: (values: T[]) => Promise<void> | void): Promise<void> {
 		let queue = this.#queue;
 		if (!queue) {
-			this.#queue = queue = [];
+			const batch: T[] = [];
+			this.#queue = batch;
+			queue = batch;
 			const { promise, resolve, reject } = Promise.withResolvers<void>();
 			const exec = (): void => {
+				if (this.#queue !== batch) return;
+				this.#queue = undefined;
+				this.#flush = undefined;
 				try {
-					if (this.#queue === queue) {
-						this.#queue = undefined;
-					}
-					resolve(hnd(queue!));
+					resolve(hnd(batch));
 				} catch (error) {
 					reject(error);
 				}
 			};
 			if (this.delayMs > 0) {
-				setTimeout(exec, this.delayMs);
+				const timer = setTimeout(exec, this.delayMs);
+				this.#flush = () => {
+					clearTimeout(timer);
+					exec();
+				};
 			} else {
+				this.#flush = exec;
 				queueMicrotask(exec);
 			}
 			this.#promise = promise;
@@ -88,4 +96,10 @@ export class AsyncDrain<T> {
 		queue.push(value);
 		return this.#promise;
 	}
+
+	/** Runs the pending batch handler immediately and returns its completion promise. */
+	flush(): Promise<void> {
+		this.#flush?.();
+		return this.#promise;
+	}
 }

package/src/color.ts

@@ -272,6 +272,179 @@ function linearizeChannel(channel: number): number {
 	const c = channel / 255;
 	return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
 }
+/** Gamma-encode a linear 0..1 channel back to 0..255 sRGB. */
+function delinearizeChannel(linear: number): number {
+	const c = linear <= 0.0031308 ? linear * 12.92 : 1.055 * linear ** (1 / 2.4) - 0.055;
+	return c * 255;
+}
+
+export interface OKLCH {
+	/** Perceptual lightness (0-1) */
+	l: number;
+	/** Chroma (0 = gray; sRGB peaks around 0.37) */
+	c: number;
+	/** Hue in degrees (0-360) */
+	h: number;
+}
+
+/** Convert linear sRGB (0..1 channels) to OKLab (Björn Ottosson's reference matrices). */
+function linearRgbToOklab(r: number, g: number, b: number): { L: number; a: number; b: number } {
+	const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+	const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+	const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+	return {
+		L: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+		a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+		b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+	};
+}
+
+/** Convert OKLab back to linear sRGB; channels may fall outside 0..1 when out of gamut. */
+function oklabToLinearRgb(L: number, a: number, b: number): { r: number; g: number; b: number } {
+	const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+	const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+	const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+	return {
+		r: 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+		g: -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+		b: -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+	};
+}
+
+/**
+ * Convert a hex color to OKLCH (perceptual lightness/chroma/hue).
+ *
+ * Unlike HSL, equal `l`/`c` values look equally bright and colorful across
+ * hues, so carrying them between colors preserves the palette's "weight".
+ */
+export function hexToOklch(hex: string): OKLCH {
+	const rgb = hexToRgb(hex);
+	const lab = linearRgbToOklab(linearizeChannel(rgb.r), linearizeChannel(rgb.g), linearizeChannel(rgb.b));
+	const c = Math.hypot(lab.a, lab.b);
+	let h = (Math.atan2(lab.b, lab.a) * 180) / Math.PI;
+	if (h < 0) h += 360;
+	return { l: lab.L, c, h };
+}
+
+/**
+ * Max OKLab saturation (C/L) that stays inside sRGB for the hue direction
+ * `(a, b)`, via Björn Ottosson's polynomial fit plus one Halley refinement.
+ */
+function computeMaxSaturation(a: number, b: number): number {
+	// Select the channel that clips first for this hue direction.
+	let k0: number, k1: number, k2: number, k3: number, k4: number;
+	let wl: number, wm: number, ws: number;
+	if (-1.88170328 * a - 0.80936493 * b > 1) {
+		// red channel
+		k0 = 1.19086277;
+		k1 = 1.76576728;
+		k2 = 0.59662641;
+		k3 = 0.75515197;
+		k4 = 0.56771245;
+		wl = 4.0767416621;
+		wm = -3.3077115913;
+		ws = 0.2309699292;
+	} else if (1.81444104 * a - 1.19445276 * b > 1) {
+		// green channel
+		k0 = 0.73956515;
+		k1 = -0.45954404;
+		k2 = 0.08285427;
+		k3 = 0.1254107;
+		k4 = 0.14503204;
+		wl = -1.2684380046;
+		wm = 2.6097574011;
+		ws = -0.3413193965;
+	} else {
+		// blue channel
+		k0 = 1.35733652;
+		k1 = -0.00915799;
+		k2 = -1.1513021;
+		k3 = -0.50559606;
+		k4 = 0.00692167;
+		wl = -0.0041960863;
+		wm = -0.7034186147;
+		ws = 1.707614701;
+	}
+	const S = k0 + k1 * a + k2 * b + k3 * a * a + k4 * a * b;
+
+	// One Halley step against f = (channel at S) - 0: polishes the fit to
+	// well below hex quantization error.
+	const kl = 0.3963377774 * a + 0.2158037573 * b;
+	const km = -0.1055613458 * a - 0.0638541728 * b;
+	const ks = -0.0894841775 * a - 1.291485548 * b;
+	const l_ = 1 + S * kl;
+	const m_ = 1 + S * km;
+	const s_ = 1 + S * ks;
+	const f = wl * l_ ** 3 + wm * m_ ** 3 + ws * s_ ** 3;
+	const f1 = wl * 3 * kl * l_ * l_ + wm * 3 * km * m_ * m_ + ws * 3 * ks * s_ * s_;
+	const f2 = wl * 6 * kl * kl * l_ + wm * 6 * km * km * m_ + ws * 6 * ks * ks * s_;
+	return S - (f * f1) / (f1 * f1 - 0.5 * f * f2);
+}
+
+/**
+ * The sRGB gamut cusp for an OKLCH hue: the lightness/chroma point where the
+ * hue reaches its maximum chroma inside sRGB.
+ *
+ * The cusp lightness varies wildly per hue (yellow ≈ 0.97, blue ≈ 0.45), so
+ * transferring absolute OKLCH lightness/chroma between hues distorts
+ * vividness; normalize against the cusp instead. See `getSessionAccentHex`.
+ */
+export function oklchCusp(h: number): { l: number; c: number } {
+	const hRad = (h * Math.PI) / 180;
+	const a = Math.cos(hRad);
+	const b = Math.sin(hRad);
+	const sCusp = computeMaxSaturation(a, b);
+	const rgb = oklabToLinearRgb(1, sCusp * a, sCusp * b);
+	const lCusp = Math.cbrt(1 / Math.max(rgb.r, rgb.g, rgb.b));
+	return { l: lCusp, c: lCusp * sCusp };
+}
+
+/** Slack allowed on linear channels before a color counts as out of sRGB gamut. */
+const GAMUT_EPSILON = 1e-4;
+
+/** True when all linear channels sit inside sRGB (within {@link GAMUT_EPSILON}). */
+function inSrgbGamut(rgb: { r: number; g: number; b: number }): boolean {
+	return (
+		rgb.r >= -GAMUT_EPSILON &&
+		rgb.r <= 1 + GAMUT_EPSILON &&
+		rgb.g >= -GAMUT_EPSILON &&
+		rgb.g <= 1 + GAMUT_EPSILON &&
+		rgb.b >= -GAMUT_EPSILON &&
+		rgb.b <= 1 + GAMUT_EPSILON
+	);
+}
+
+/**
+ * Convert OKLCH to a CSS hex string, gamut-mapping by chroma reduction.
+ *
+ * Out-of-gamut inputs keep their lightness and hue while chroma is bisected
+ * down until the color fits sRGB, matching CSS Color 4's recommended intent.
+ */
+export function oklchToHex(oklch: OKLCH): string {
+	const l = Math.max(0, Math.min(1, oklch.l));
+	const hRad = (oklch.h * Math.PI) / 180;
+	const cos = Math.cos(hRad);
+	const sin = Math.sin(hRad);
+	const at = (c: number) => oklabToLinearRgb(l, c * cos, c * sin);
+
+	let rgb = at(oklch.c);
+	if (!inSrgbGamut(rgb)) {
+		// `lo` always fits (chroma 0 is the gray axis), `hi` never does.
+		let lo = 0;
+		let hi = oklch.c;
+		for (let i = 0; i < 20; i++) {
+			const mid = (lo + hi) / 2;
+			if (inSrgbGamut(at(mid))) lo = mid;
+			else hi = mid;
+		}
+		rgb = at(lo);
+	}
+	return rgbToHex({
+		r: Math.max(0, Math.min(255, delinearizeChannel(rgb.r))),
+		g: Math.max(0, Math.min(255, delinearizeChannel(rgb.g))),
+		b: Math.max(0, Math.min(255, delinearizeChannel(rgb.b))),
+	});
+}
 
 /**
  * Perceptual luma (gamma-encoded BT.709 weights over raw sRGB), normalized to 0..1.

package/src/postmortem.ts

@@ -24,10 +24,25 @@ export enum Reason {
 	MANUAL = "manual", // Manual cleanup (not triggered by process)
 }
 
-// Internal list of active cleanup callbacks (in registration order)
-const callbackList: ((reason: Reason) => Promise<void> | void)[] = [];
-// Tracks cleanup run state (to prevent recursion/reentry issues)
+interface CleanupRegistration {
+	id: string;
+	callback: (reason: Reason) => Promise<void> | void;
+	exitOnly: boolean;
+	cancelled: boolean;
+	lastPass: number;
+}
+
+// Active cleanup callbacks in registration order. Registrations survive
+// keep-alive passes; `lastPass` enforces at-most-once invocation per pass.
+const callbackList: CleanupRegistration[] = [];
+// Tracks cleanup run state (to prevent recursion/reentry issues).
 let cleanupStage: "idle" | "running" | "complete" = "idle";
+let cleanupPass = 0;
+let activeCleanupReason: Reason | undefined;
+let activeCleanupKeepAlive = false;
+// Promises of callbacks invoked late (registered while a pass runs), joined by
+// the active pass before it settles so `cleanup()`/signal exits await them.
+let activeLatePromises: Promise<void>[] | undefined;
 const CLEANUP_DEADLINE_MS = 10_000;
 /**
  * Symbol stamped by the extension-load guard onto the throwing replacement it
@@ -78,13 +93,32 @@ export interface FatalRecoveryHint {
 type FatalRecoveryHintProvider = () => FatalRecoveryHint | undefined;
 const fatalRecoveryHintProviders = new Set<FatalRecoveryHintProvider>();
 
+function invokeCleanup(
+	registration: CleanupRegistration,
+	reason: Reason,
+	keepAlive: boolean,
+	pass: number,
+): Promise<void> | void {
+	if (registration.cancelled || registration.lastPass === pass) return;
+	if (registration.exitOnly && keepAlive) return;
+	registration.lastPass = pass;
+	return registration.callback(reason);
+}
+
 /**
  * Internal: runs all registered cleanup callbacks for the given reason.
- * Ensures each callback is invoked at most once. Handles errors and prevents reentrancy.
+ * Ensures each registration is invoked at most once per pass, handles errors,
+ * and prevents reentrancy.
+ *
+ * `keepAlive` marks a manual cleanup that keeps the process running (see
+ * {@link cleanup}). Such a pass returns the stage to `idle`; registrations stay
+ * active for later resources and the eventual real exit. Exit-only callbacks
+ * skip keep-alive passes without consuming their registration. An exit-driven
+ * pass instead settles to `complete` and stays there.
  *
  * Returns a Promise that settles after all cleanups complete or error out.
  */
-function runCleanup(reason: Reason): Promise<void> {
+function runCleanup(reason: Reason, keepAlive = false): Promise<void> {
 	switch (cleanupStage) {
 		case "idle":
 			cleanupStage = "running";
@@ -95,30 +129,52 @@ function runCleanup(reason: Reason): Promise<void> {
 			return Promise.resolve();
 	}
 
-	// Call .cleanup() for each callback that is still "armed".
-	// Use Promise.try to handle sync/async, but only those armed.
-	const promises = callbackList.toReversed().map(callback => {
-		return Promise.try(() => callback(reason));
+	const pass = ++cleanupPass;
+	activeCleanupReason = reason;
+	activeCleanupKeepAlive = keepAlive;
+	const late: Promise<void>[] = [];
+	activeLatePromises = late;
+	const settle = (): void => {
+		if (activeLatePromises === late) activeLatePromises = undefined;
+		if (cleanupPass !== pass) return;
+		cleanupStage = keepAlive ? "idle" : "complete";
+		if (keepAlive) {
+			activeCleanupReason = undefined;
+			activeCleanupKeepAlive = false;
+		}
+	};
+
+	// Snapshot the pass. Registrations added while a keep-alive cleanup runs are
+	// invoked by register() when appropriate and remain active for later passes.
+	const promises = callbackList.toReversed().map(registration => {
+		return Promise.try(() => invokeCleanup(registration, reason, keepAlive, pass));
 	});
 
-	const cleanupSettled = Promise.allSettled(promises).then(results => {
+	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));
 				logger.error("Cleanup callback failed", { err, stack: err.stack });
 			}
 		}
-		cleanupStage = "complete";
+		// Join callbacks registered while this pass ran (already error-caught);
+		// each batch may register more. The deadline race still bounds the pass.
+		while (late.length > 0) await Promise.allSettled(late.splice(0));
+		settle();
 	});
 	const deadline = Promise.withResolvers<void>();
 	const deadlineTimer = setTimeout(() => {
 		logger.error("Cleanup deadline exceeded; proceeding with exit", { reason });
-		cleanupStage = "complete";
+		settle();
 		deadline.resolve();
 	}, CLEANUP_DEADLINE_MS);
-	cleanupPromise = Promise.race([cleanupSettled, deadline.promise]).finally(() => {
+	const passPromise = Promise.race([cleanupSettled, deadline.promise]).finally(() => {
 		clearTimeout(deadlineTimer);
+		// A re-armed pass must drop only its own settled promise; an older
+		// deadline-limited pass may finish after a newer one has already started.
+		if (keepAlive && cleanupPass === pass && cleanupPromise === passPromise) cleanupPromise = undefined;
 	});
+	cleanupPromise = passPromise;
 	return cleanupPromise;
 }
 
@@ -464,57 +520,92 @@ if (isMainThread) {
 	});
 }
 
+/** Controls when a registered cleanup callback participates in cleanup passes. */
+export interface CleanupRegistrationOptions {
+	/**
+	 * Run only on a real exit, never during a manual keep-alive cleanup.
+	 * The registration remains armed when a keep-alive pass skips it.
+	 */
+	exitOnly?: boolean;
+}
+
 /**
- * Register a process cleanup callback, to be run on shutdown, signal, or fatal error.
+ * Registers a cleanup callback for shutdown, signals, fatal errors, and
+ * repeatable manual cleanup passes.
+ *
+ * Registrations persist across keep-alive {@link cleanup} passes and run at
+ * most once per pass. Set `exitOnly` for resources the continuing process still
+ * holds (open databases, cached handles): keep-alive passes skip the callback
+ * without consuming its registration, while the eventual real exit runs it.
+ *
+ * A callback registered during a running keep-alive pass joins future passes;
+ * normal callbacks also run immediately for the current pass. Registrations
+ * made during a real exit run immediately.
  *
- * Returns a Callback instance that can be used to cancel (unregister) or manually clean up.
- * If register is called after cleanup already began, invokes callback on a microtask.
+ * Returns a function that permanently cancels the registration.
  */
-export function register(id: string, callback: (reason: Reason) => void | Promise<void>): () => void {
-	let done = false;
-	const exec = (reason: Reason) => {
-		if (done) return;
-		done = true;
+export function register(
+	id: string,
+	callback: (reason: Reason) => void | Promise<void>,
+	options: CleanupRegistrationOptions = {},
+): () => void {
+	const registration: CleanupRegistration = {
+		id,
+		callback,
+		exitOnly: options.exitOnly ?? false,
+		cancelled: false,
+		lastPass: 0,
+	};
+	const cancel = (): void => {
+		registration.cancelled = true;
+		const index = callbackList.indexOf(registration);
+		if (index >= 0) callbackList.splice(index, 1);
+	};
+	const invokeLate = (reason: Reason, keepAlive: boolean): void => {
 		try {
-			return callback(reason);
-		} catch (e) {
-			const err = e instanceof Error ? e : new Error(String(e));
+			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));
+				logger.error("Cleanup callback failed", { err, id, stack: err.stack });
+			});
+			// Join the active pass so cleanup()/signal exits await it; after a
+			// completed exit pass there is nothing left to join.
+			activeLatePromises?.push(tracked);
+		} catch (error) {
+			const err = error instanceof Error ? error : new Error(String(error));
 			logger.error("Cleanup callback failed", { err, id, stack: err.stack });
 		}
 	};
 
-	const cancel = () => {
-		const index = callbackList.indexOf(exec);
-		if (index >= 0) {
-			callbackList.splice(index, 1);
-		}
-		done = true;
-	};
+	if (cleanupStage === "idle") {
+		callbackList.push(registration);
+		return cancel;
+	}
 
-	if (cleanupStage !== "idle") {
-		// Cleanup is already in progress or complete; run late registrations once
-		// without re-entering the global cleanup pass.
-		logger.debug("Cleanup already started; running late callback once", { id });
-		try {
-			callback(Reason.MANUAL);
-		} catch (e) {
-			const err = e instanceof Error ? e : new Error(String(e));
-			logger.error("Cleanup callback failed", { err, id, stack: err.stack });
-		}
-		return () => {};
+	const reason = activeCleanupReason ?? Reason.MANUAL;
+	if (cleanupStage === "running" && activeCleanupKeepAlive) {
+		// The current pass already snapshotted its callbacks. Keep the new owner
+		// registered for future passes; normal callbacks also join this pass now.
+		callbackList.push(registration);
+		if (!registration.exitOnly) invokeLate(reason, true);
+		return cancel;
 	}
 
-	// Register callback as "armed" (active).
-	callbackList.push(exec);
+	// A real exit is running or complete. There is no later pass to arm for, so
+	// invoke every late registration now, including exit-only callbacks.
+	logger.debug("Cleanup already started; running late callback once", { id });
+	invokeLate(reason, false);
 	return cancel;
 }
 
 /**
- * Runs all cleanup callbacks without exiting.
+ * Runs all cleanup callbacks without exiting, then re-arms the system so
+ * resources opened afterwards are still cleaned at the eventual real exit.
  * Use this in workers or when you need to clean up but continue execution.
  */
 export function cleanup(): Promise<void> {
-	return runCleanup(Reason.MANUAL);
+	return runCleanup(Reason.MANUAL, true);
 }
 
 /** Controls how manual process shutdown handles terminal output. */
@@ -523,6 +614,18 @@ export interface QuitOptions {
 	drainStdout?: boolean;
 }
 
+/**
+ * Waits (bounded) for buffered stdout to reach the terminal. Used before
+ * process exit and before an exec-replace, where unflushed output would be
+ * lost with the process image.
+ */
+export async function drainStdout(): Promise<void> {
+	if (process.stdout.writableLength === 0) return;
+	const { promise, resolve } = Promise.withResolvers<void>();
+	process.stdout.once("drain", resolve);
+	await Promise.race([promise, Bun.sleep(5000)]);
+}
+
 async function runQuit(code: number, exitMode: "guarded" | "native", options: QuitOptions = {}): Promise<void> {
 	await runCleanup(Reason.MANUAL);
 
@@ -530,10 +633,8 @@ async function runQuit(code: number, exitMode: "guarded" | "native", options: Qu
 		return; // Workers: cleanup done, let worker exit naturally
 	}
 
-	if (options.drainStdout !== false && process.stdout.writableLength > 0) {
-		const { promise, resolve } = Promise.withResolvers<void>();
-		process.stdout.once("drain", resolve);
-		await Promise.race([promise, Bun.sleep(5000)]);
+	if (options.drainStdout !== false) {
+		await drainStdout();
 	}
 
 	switch (exitMode) {

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