@oh-my-pi/pi-utils 18.0.8 → 18.0.10

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [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
+
+- Fixed error handling so unrelated aborted requests and closed-connection failures are no longer silently suppressed.
+
 ## [18.0.8] - 2026-08-27
 
 ### Added

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

@@ -107,10 +107,10 @@ export declare function registerStdioDisconnectHandling(): () => void;
  */
 export declare function markExpectedCleanupError<T extends object>(reason: T): T;
 /**
- * Whether `reason` (or any error in its `cause` chain) was marked via
- * {@link markExpectedCleanupError}. Walks the chain because the unhandled
- * reason is often a wrapper (`AbortError`) with the marked abort reason as
- * its `cause`.
+ * Whether `reason` (or any object in its bounded `cause` chain) was explicitly
+ * marked via {@link markExpectedCleanupError}. Runtime error names and codes
+ * are intentionally insufficient: unmarked `AbortError` and socket failures
+ * can originate from application code and must remain fatal when unhandled.
  */
 export declare function isExpectedCleanupError(reason: unknown): boolean;
 /**
@@ -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/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.8",
+	"version": "18.0.10",
 	"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.8"
+		"@oh-my-pi/pi-natives": "18.0.10"
 	},
 	"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;
 }
 
@@ -263,25 +319,29 @@ const EXPECTED_CLEANUP = Symbol.for("omp.expectedCleanupError");
  * consumer. Returns the same error for inline use at the `abort()` callsite.
  */
 export function markExpectedCleanupError<T extends object>(reason: T): T {
-	(reason as Record<PropertyKey, unknown>)[EXPECTED_CLEANUP] = true;
+	Reflect.set(reason, EXPECTED_CLEANUP, true);
 	return reason;
 }
 
-/**
- * Whether `reason` (or any error in its `cause` chain) was marked via
- * {@link markExpectedCleanupError}. Walks the chain because the unhandled
- * reason is often a wrapper (`AbortError`) with the marked abort reason as
- * its `cause`.
- */
-export function isExpectedCleanupError(reason: unknown): boolean {
+function hasExpectedCleanupMarker(reason: unknown): boolean {
 	let current: unknown = reason;
 	for (let depth = 0; depth < 8 && current !== null && typeof current === "object"; depth++) {
-		if ((current as Record<PropertyKey, unknown>)[EXPECTED_CLEANUP] === true) return true;
-		current = (current as { cause?: unknown }).cause;
+		if (Reflect.get(current, EXPECTED_CLEANUP) === true) return true;
+		current = Reflect.get(current, "cause");
 	}
 	return false;
 }
 
+/**
+ * Whether `reason` (or any object in its bounded `cause` chain) was explicitly
+ * marked via {@link markExpectedCleanupError}. Runtime error names and codes
+ * are intentionally insufficient: unmarked `AbortError` and socket failures
+ * can originate from application code and must remain fatal when unhandled.
+ */
+export function isExpectedCleanupError(reason: unknown): boolean {
+	return hasExpectedCleanupMarker(reason);
+}
+
 /** Interceptors consulted by the global `unhandledRejection` handler before the fatal path. */
 const rejectionInterceptors = new Set<(reason: unknown) => boolean>();
 
@@ -366,7 +426,10 @@ if (isMainThread) {
 			process.stderr.write(`Inspector opened: ${url}\n`);
 		})
 		.on("uncaughtException", async thrown => {
-			if (isExpectedCleanupError(thrown)) {
+			// Only explicitly marked exceptions are safe here. Structural
+			// AbortError/socket classification is limited to promise rejections:
+			// a synchronously thrown error may indicate an application bug.
+			if (hasExpectedCleanupMarker(thrown)) {
 				logger.warn("Ignoring expected cleanup exception", { err: thrown });
 				return;
 			}
@@ -457,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. */
@@ -516,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);
 
@@ -523,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/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