@f5xc-salesdemos/pi-utils 14.0.2

package/src/logger.ts

@@ -0,0 +1,204 @@
+/**
+ * Centralized file logger for xcsh.
+ *
+ * Logs to ~/.xcsh/logs/ with size-based rotation, supporting concurrent xcsh instances.
+ * Each log entry includes process.pid for traceability.
+ */
+import * as fs from "node:fs";
+import winston from "winston";
+import DailyRotateFile from "winston-daily-rotate-file";
+import { getLogsDir } from "./dirs";
+
+/** Ensure logs directory exists */
+function ensureLogsDir(): string {
+	const logsDir = getLogsDir();
+	if (!fs.existsSync(logsDir)) {
+		fs.mkdirSync(logsDir, { recursive: true });
+	}
+	return logsDir;
+}
+
+/** Custom format that includes pid and flattens metadata */
+const logFormat = winston.format.combine(
+	winston.format.timestamp({ format: "YYYY-MM-DDTHH:mm:ss.SSSZ" }),
+	winston.format.printf(({ timestamp, level, message, ...meta }) => {
+		const entry: Record<string, unknown> = {
+			timestamp,
+			level,
+			pid: process.pid,
+			message,
+		};
+		// Flatten metadata into entry
+		for (const [key, value] of Object.entries(meta)) {
+			if (key !== "level" && key !== "timestamp" && key !== "message") {
+				entry[key] = value;
+			}
+		}
+		return JSON.stringify(entry);
+	}),
+);
+
+/** Size-based rotating file transport */
+const fileTransport = new DailyRotateFile({
+	dirname: ensureLogsDir(),
+	filename: "xcsh.%DATE%.log",
+	datePattern: "YYYY-MM-DD",
+	maxSize: "10m",
+	maxFiles: 5,
+	zippedArchive: true,
+});
+
+/** The winston logger instance */
+const winstonLogger = winston.createLogger({
+	level: "debug",
+	format: logFormat,
+	transports: [fileTransport],
+	// Don't exit on error - logging failures shouldn't crash the app
+	exitOnError: false,
+});
+
+/**
+ * Log an error message.
+ * @param message - The message to log.
+ * @param context - The context to log.
+ */
+export function error(message: string, context?: Record<string, unknown>): void {
+	try {
+		winstonLogger.error(message, context);
+	} catch {
+		// Silently ignore logging failures
+	}
+}
+
+/**
+ * Log a warning message.
+ * @param message - The message to log.
+ * @param context - The context to log.
+ */
+export function warn(message: string, context?: Record<string, unknown>): void {
+	try {
+		winstonLogger.warn(message, context);
+	} catch {
+		// Silently ignore logging failures
+	}
+}
+
+/**
+ * Log a debug message.
+ * @param message - The message to log.
+ * @param context - The context to log.
+ */
+export function debug(message: string, context?: Record<string, unknown>): void {
+	try {
+		winstonLogger.debug(message, context);
+	} catch {
+		// Silently ignore logging failures
+	}
+}
+
+const LOGGED_TIMING_THRESHOLD_MS = 5;
+
+/** Sequential wall-clock markers (next marker closes the previous segment). */
+let gTimings: [op: string, ts: number][] = [];
+
+/** Await-accurate durations (safe for parallel work; sums can overlap). */
+let gAsyncSpans: [op: string, durationMs: number][] = [];
+
+/** Whether to record timings. */
+let gRecordTimings = false;
+
+/**
+ * Print collected timings to stderr.
+ * Wall segments are gaps between consecutive {@link time} markers only; they are wrong when
+ * concurrent code also calls {@link time} (e.g. parallel capability loads). Use {@link timeAsync}
+ * for those awaits instead.
+ */
+export function printTimings(): void {
+	if (!gRecordTimings || gTimings.length === 0) {
+		console.error("\n--- Startup Timings ---\n(no markers)\n");
+		return;
+	}
+
+	const endTs = performance.now();
+	gTimings.push(["(end)", endTs]);
+
+	console.error("\n--- Startup timings (wall segments between time() markers) ---");
+	const firstTs = gTimings[0][1];
+	for (let i = 0; i < gTimings.length - 1; i++) {
+		const [op, ts] = gTimings[i];
+		const [, nextTs] = gTimings[i + 1];
+		const dur = nextTs - ts;
+		if (dur > LOGGED_TIMING_THRESHOLD_MS) {
+			console.error(`  ${op}: ${dur}ms`);
+		}
+	}
+	console.error(`  span (first marker → end): ${endTs - firstTs}ms`);
+
+	if (gAsyncSpans.length > 0) {
+		console.error("\n--- Async (await-accurate; parallel spans may overlap) ---");
+		for (const [op, dur] of gAsyncSpans) {
+			if (dur > LOGGED_TIMING_THRESHOLD_MS) {
+				console.error(`  ${op}: ${dur}ms`);
+			}
+		}
+	}
+
+	console.error("------------------------\n");
+
+	gTimings.pop();
+}
+
+/**
+ * Begin recording startup timings. Seeds the timeline so the first segment is meaningful.
+ */
+export function startTiming(): void {
+	gTimings = [["(startup)", performance.now()]];
+	gAsyncSpans = [];
+	gRecordTimings = true;
+}
+
+/**
+ * End timing window and clear buffers.
+ */
+export function endTiming(): void {
+	gTimings = [];
+	gAsyncSpans = [];
+	gRecordTimings = false;
+}
+
+function recordAsyncSpan(op: string, start: number): void {
+	const dur = performance.now() - start;
+	if (dur > LOGGED_TIMING_THRESHOLD_MS) {
+		gAsyncSpans.push([op, dur]);
+	}
+}
+
+/**
+ * Wall-clock segment boundary: duration for this label runs until the next {@link time} call.
+ * Do not use across `await` when other tasks may call {@link time}; use {@link timeAsync} for the awaited work.
+ */
+export function time(op: string): void;
+export function time<T, A extends unknown[]>(op: string, fn: (...args: A) => T, ...args: A): T;
+export function time<T, A extends unknown[]>(op: string, fn?: (...args: A) => T, ...args: A): T | undefined {
+	if (fn === undefined) {
+		if (gRecordTimings) {
+			gTimings.push([op, performance.now()]);
+		}
+		return undefined as T;
+	} else if (gRecordTimings) {
+		const start = performance.now();
+		try {
+			const result = fn(...args);
+			if (result instanceof Promise) {
+				return result.finally(recordAsyncSpan.bind(null, op, start)) as T;
+			}
+			recordAsyncSpan(op, start);
+			return result;
+		} catch (error) {
+			recordAsyncSpan(op, start);
+			throw error;
+		}
+	} else {
+		return fn(...args);
+	}
+}

package/src/mermaid-ascii.ts

@@ -0,0 +1,31 @@
+import { type AsciiRenderOptions, renderMermaidASCII } from "beautiful-mermaid";
+
+export type { AsciiRenderOptions as MermaidAsciiRenderOptions };
+
+export function renderMermaidAscii(source: string, options?: AsciiRenderOptions): string {
+	return renderMermaidASCII(source, options);
+}
+
+export function renderMermaidAsciiSafe(source: string, options?: AsciiRenderOptions): string | null {
+	try {
+		return renderMermaidASCII(source, options);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Extract mermaid code blocks from markdown text.
+ */
+export function extractMermaidBlocks(markdown: string): { source: string; hash: bigint }[] {
+	const blocks: { source: string; hash: bigint }[] = [];
+	const regex = /```mermaid\s*\n([\s\S]*?)```/g;
+
+	for (let match = regex.exec(markdown); match !== null; match = regex.exec(markdown)) {
+		const source = match[1].trim();
+		const hash = Bun.hash.xxHash64(source);
+		blocks.push({ source, hash });
+	}
+
+	return blocks;
+}

package/src/mime.ts

@@ -0,0 +1,159 @@
+import { peekFile, peekFileSync } from "./peek-file";
+
+const DEFAULT_IMAGE_METADATA_HEADER_BYTES = 256 * 1024;
+
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const JPEG_MAGIC = Buffer.from([0xff, 0xd8, 0xff]);
+const WEBP_RIFF_MAGIC = Buffer.from([0x52, 0x49, 0x46, 0x46]);
+const WEBP_MAGIC = Buffer.from([0x57, 0x45, 0x42, 0x50]);
+const PNG_IHDR = Buffer.from("IHDR");
+const GIF87A = Buffer.from("GIF87a");
+const GIF89A = Buffer.from("GIF89a");
+const WEBP_VP8X = Buffer.from("VP8X");
+const WEBP_VP8L = Buffer.from("VP8L");
+const WEBP_VP8 = Buffer.from("VP8 ");
+
+export const SUPPORTED_IMAGE_MIME_TYPES = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);
+
+export type ImageMetadata =
+	| { mimeType: "image/png"; width?: number; height?: number; channels?: number; hasAlpha?: boolean }
+	| { mimeType: "image/jpeg"; width?: number; height?: number; channels?: number; hasAlpha?: false }
+	| { mimeType: "image/gif"; width?: number; height?: number; channels?: 3; hasAlpha?: never }
+	| { mimeType: "image/webp"; width?: number; height?: number; channels?: number; hasAlpha?: boolean };
+
+function magicEquals(header: Uint8Array, offset: number, magic: Buffer): boolean {
+	if (header.length < offset + magic.length) {
+		return false;
+	}
+	return magic.equals(header.subarray(offset, offset + magic.length));
+}
+
+function parsePngMetadata(header: Uint8Array): ImageMetadata | null {
+	if (!magicEquals(header, 0, PNG_MAGIC)) return null;
+	if (!magicEquals(header, 12, PNG_IHDR)) return { mimeType: "image/png" };
+	if (header.length < 26) return { mimeType: "image/png" };
+
+	const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+	const width = view.getUint32(16, false);
+	const height = view.getUint32(20, false);
+	const colorType = view.getUint8(25);
+	if (colorType === 0) return { mimeType: "image/png", width, height, channels: 1, hasAlpha: false };
+	if (colorType === 2) return { mimeType: "image/png", width, height, channels: 3, hasAlpha: false };
+	if (colorType === 3) return { mimeType: "image/png", width, height, channels: 3 };
+	if (colorType === 4) return { mimeType: "image/png", width, height, channels: 2, hasAlpha: true };
+	if (colorType === 6) return { mimeType: "image/png", width, height, channels: 4, hasAlpha: true };
+	return { mimeType: "image/png", width, height };
+}
+
+function parseJpegMetadata(header: Uint8Array): ImageMetadata | null {
+	if (!magicEquals(header, 0, JPEG_MAGIC)) return null;
+	if (header.length < 4) return { mimeType: "image/jpeg" };
+
+	const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+	let offset = 2;
+	while (offset + 9 < header.length) {
+		if (header[offset] !== 0xff) {
+			offset += 1;
+			continue;
+		}
+
+		let markerOffset = offset + 1;
+		while (markerOffset < header.length && header[markerOffset] === 0xff) {
+			markerOffset += 1;
+		}
+		if (markerOffset >= header.length) break;
+
+		const marker = header[markerOffset];
+		const segmentOffset = markerOffset + 1;
+		if (marker === 0xd8 || marker === 0xd9 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+			offset = segmentOffset;
+			continue;
+		}
+		if (segmentOffset + 1 >= header.length) break;
+
+		const segmentLength = view.getUint16(segmentOffset, false);
+		if (segmentLength < 2) break;
+
+		const isStartOfFrame = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+		if (isStartOfFrame) {
+			if (segmentOffset + 7 >= header.length) break;
+			const height = view.getUint16(segmentOffset + 3, false);
+			const width = view.getUint16(segmentOffset + 5, false);
+			const channels = header[segmentOffset + 7];
+			return {
+				mimeType: "image/jpeg",
+				width,
+				height,
+				channels: Number.isFinite(channels) ? channels : undefined,
+				hasAlpha: false,
+			};
+		}
+
+		offset = segmentOffset + segmentLength;
+	}
+
+	return { mimeType: "image/jpeg" };
+}
+
+function parseGifMetadata(header: Uint8Array): ImageMetadata | null {
+	if (!magicEquals(header, 0, GIF87A) && !magicEquals(header, 0, GIF89A)) return null;
+	if (header.length < 10) return { mimeType: "image/gif" };
+	const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+	return {
+		mimeType: "image/gif",
+		width: view.getUint16(6, true),
+		height: view.getUint16(8, true),
+		channels: 3,
+	};
+}
+
+function parseWebpMetadata(header: Uint8Array): ImageMetadata | null {
+	if (!magicEquals(header, 0, WEBP_RIFF_MAGIC)) return null;
+	if (!magicEquals(header, 8, WEBP_MAGIC)) return null;
+	if (header.length < 30) return { mimeType: "image/webp" };
+
+	if (magicEquals(header, 12, WEBP_VP8X)) {
+		const hasAlpha = (header[20] & 0x10) !== 0;
+		const width = (header[24] | (header[25] << 8) | (header[26] << 16)) + 1;
+		const height = (header[27] | (header[28] << 8) | (header[29] << 16)) + 1;
+		return { mimeType: "image/webp", width, height, channels: hasAlpha ? 4 : 3, hasAlpha };
+	}
+
+	const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+	if (magicEquals(header, 12, WEBP_VP8L)) {
+		if (header.length < 25) return { mimeType: "image/webp" };
+		const bits = view.getUint32(21, true);
+		const width = (bits & 0x3fff) + 1;
+		const height = ((bits >> 14) & 0x3fff) + 1;
+		const hasAlpha = ((bits >> 28) & 0x1) === 1;
+		return { mimeType: "image/webp", width, height, channels: hasAlpha ? 4 : 3, hasAlpha };
+	}
+
+	if (magicEquals(header, 12, WEBP_VP8)) {
+		const width = view.getUint16(26, true) & 0x3fff;
+		const height = view.getUint16(28, true) & 0x3fff;
+		return { mimeType: "image/webp", width, height, channels: 3, hasAlpha: false };
+	}
+
+	return { mimeType: "image/webp" };
+}
+
+export function parseImageMetadata(header: Uint8Array): ImageMetadata | null {
+	return (
+		parsePngMetadata(header) ?? parseJpegMetadata(header) ?? parseGifMetadata(header) ?? parseWebpMetadata(header)
+	);
+}
+
+export function readImageMetadataSync(
+	filePath: string,
+	maxBytes = DEFAULT_IMAGE_METADATA_HEADER_BYTES,
+): ImageMetadata | null {
+	return peekFileSync(filePath, maxBytes, parseImageMetadata);
+}
+
+export function readImageMetadata(
+	filePath: string,
+	maxBytes = DEFAULT_IMAGE_METADATA_HEADER_BYTES,
+): Promise<ImageMetadata | null> {
+	return peekFile(filePath, maxBytes, parseImageMetadata);
+}

package/src/peek-file.ts

@@ -0,0 +1,114 @@
+/**
+ * Read the first `maxBytes` of a file (offset 0) and pass that slice to `op`.
+ *
+ * Buffers are reused to avoid allocating on every peek: sync uses one growable
+ * `Uint8Array`; async uses a small fixed pool of `Buffer`s with a bounded wait
+ * queue, falling back to a fresh allocation when the pool and queue are saturated
+ * or when `maxBytes` exceeds the pool slot size.
+ */
+import * as fs from "node:fs";
+
+/** Async pool slot size; larger peeks allocate ad hoc. */
+const POOLED_BUFFER_SIZE = 512;
+const ASYNC_POOL_SIZE = 10;
+/** Cap waiter queue so heavy concurrency does not queue unbounded; overflow uses alloc. */
+const MAX_ASYNC_WAITERS = 4;
+const INITIAL_SYNC_BUFFER_SIZE = 1024;
+const EMPTY_BUFFER = Buffer.alloc(0);
+
+const asyncPool = Array.from({ length: ASYNC_POOL_SIZE }, () => Buffer.allocUnsafe(POOLED_BUFFER_SIZE));
+const availableAsyncPoolIndexes = Array.from({ length: ASYNC_POOL_SIZE }, (_, index) => index);
+const asyncPoolWaiters: Array<(index: number) => void> = [];
+let syncPool = new Uint8Array(INITIAL_SYNC_BUFFER_SIZE);
+
+/** Returns a pool slot index, or `-1` when the caller should use a standalone buffer. */
+function acquireAsyncPoolIndex(): Promise<number> | number {
+	const index = availableAsyncPoolIndexes.pop();
+	if (index !== undefined) {
+		return index;
+	}
+	if (asyncPoolWaiters.length >= MAX_ASYNC_WAITERS) {
+		return -1;
+	}
+	const { promise, resolve } = Promise.withResolvers<number>();
+	asyncPoolWaiters.push(resolve);
+	return promise;
+}
+
+function releaseAsyncPoolIndex(index: number): void {
+	if (index < 0) {
+		return;
+	}
+	const waiter = asyncPoolWaiters.shift();
+	if (waiter) {
+		waiter(index);
+		return;
+	}
+	availableAsyncPoolIndexes.push(index);
+}
+
+async function withAsyncPoolBuffer<T>(maxBytes: number, op: (buffer: Buffer) => Promise<T>): Promise<T> {
+	if (maxBytes <= 0) {
+		return op(EMPTY_BUFFER);
+	}
+	if (maxBytes > POOLED_BUFFER_SIZE) {
+		return op(Buffer.allocUnsafe(maxBytes));
+	}
+
+	const poolIndex = await acquireAsyncPoolIndex();
+	const buffer = poolIndex >= 0 ? asyncPool[poolIndex] : Buffer.allocUnsafe(maxBytes);
+	try {
+		return await op(buffer.subarray(0, maxBytes));
+	} finally {
+		releaseAsyncPoolIndex(poolIndex);
+	}
+}
+
+function withSyncPoolBuffer<T>(maxBytes: number, op: (buffer: Uint8Array) => T): T {
+	if (maxBytes <= 0) {
+		return op(EMPTY_BUFFER);
+	}
+	if (maxBytes > syncPool.byteLength) {
+		syncPool = new Uint8Array(maxBytes + (maxBytes >> 1));
+	}
+	return op(syncPool.subarray(0, maxBytes));
+}
+
+/**
+ * Synchronously reads up to `maxBytes` from the start of `filePath` and returns `op(header)`.
+ * If the file is shorter, `header` is only the bytes actually read.
+ */
+export function peekFileSync<T>(filePath: string, maxBytes: number, op: (header: Uint8Array) => T): T {
+	if (maxBytes <= 0) {
+		return op(EMPTY_BUFFER);
+	}
+
+	const fileHandle = fs.openSync(filePath, "r");
+	try {
+		return withSyncPoolBuffer(maxBytes, buffer => {
+			const bytesRead = fs.readSync(fileHandle, buffer, 0, buffer.byteLength, 0);
+			return op(buffer.subarray(0, bytesRead));
+		});
+	} finally {
+		fs.closeSync(fileHandle);
+	}
+}
+
+/**
+ * Like {@link peekFileSync} but uses async I/O.
+ */
+export async function peekFile<T>(filePath: string, maxBytes: number, op: (header: Uint8Array) => T): Promise<T> {
+	if (maxBytes <= 0) {
+		return op(EMPTY_BUFFER);
+	}
+
+	const fileHandle = await fs.promises.open(filePath, "r");
+	try {
+		return await withAsyncPoolBuffer(maxBytes, async buffer => {
+			const { bytesRead } = await fileHandle.read(buffer, 0, buffer.byteLength, 0);
+			return op(buffer.subarray(0, bytesRead));
+		});
+	} finally {
+		await fileHandle.close();
+	}
+}

package/src/postmortem.ts

@@ -0,0 +1,197 @@
+/**
+ * Cleanup and postmortem handler utilities.
+ *
+ * This module provides a system for registering and running cleanup callbacks
+ * in response to process exit, signals, or fatal exceptions. It is intended to
+ * allow reliably releasing resources or shutting down subprocesses, files, sockets, etc.
+ */
+import inspector from "node:inspector";
+import { isMainThread } from "node:worker_threads";
+import { logger } from ".";
+
+// Cleanup reasons, in order of priority/meaning.
+export enum Reason {
+	PRE_EXIT = "pre_exit", // Pre-exit phase (not used by default)
+	EXIT = "exit", // Normal process exit
+	SIGINT = "sigint", // Ctrl-C or SIGINT
+	SIGTERM = "sigterm", // SIGTERM
+	SIGHUP = "sighup", // SIGHUP
+	UNCAUGHT_EXCEPTION = "uncaught_exception", // Fatal exception
+	UNHANDLED_REJECTION = "unhandled_rejection", // Unhandled promise rejection
+	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)
+let cleanupStage: "idle" | "running" | "complete" = "idle";
+
+/**
+ * Internal: runs all registered cleanup callbacks for the given reason.
+ * Ensures each callback is invoked at most once. Handles errors and prevents reentrancy.
+ *
+ * Returns a Promise that settles after all cleanups complete or error out.
+ */
+function runCleanup(reason: Reason): Promise<void> {
+	switch (cleanupStage) {
+		case "idle":
+			cleanupStage = "running";
+			break;
+		case "running":
+			logger.error("Cleanup invoked recursively", { stack: new Error().stack });
+			return Promise.resolve();
+		case "complete":
+			return Promise.resolve();
+	}
+
+	// Call .cleanup() for each callback that is still "armed".
+	// Use Promise.try to handle sync/async, but only those armed.
+	// Create a copy to avoid mutating the original array with reverse()
+	const promises = [...callbackList].reverse().map(callback => {
+		return Promise.try(() => callback(reason));
+	});
+
+	return Promise.allSettled(promises).then(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";
+	});
+}
+
+// Register signal and error event handlers to trigger cleanup before exit.
+// Main thread: full signal handling (SIGINT, SIGTERM, SIGHUP) + exceptions + exit
+// Worker thread: exit only (workers use self.addEventListener for exceptions)
+let inspectorOpened = false;
+
+function formatFatalError(label: string, err: Error): string {
+	const name = err.name || "Error";
+	const message = err.message || "(no message)";
+	const stack = err.stack || "";
+	const stackLines = stack.split("\n").slice(1);
+	const formattedStack = stackLines.length > 0 ? `\n${stackLines.join("\n")}` : "";
+	return `\n[${label}] ${name}: ${message}${formattedStack}\n`;
+}
+
+if (isMainThread) {
+	process
+		.on("SIGINT", async () => {
+			await runCleanup(Reason.SIGINT);
+			process.exit(130); // 128 + SIGINT (2)
+		})
+		.on("SIGUSR1", () => {
+			if (inspectorOpened) return;
+			inspectorOpened = true;
+			inspector.open(undefined, undefined, false);
+			const url = inspector.url();
+			process.stderr.write(`Inspector opened: ${url}\n`);
+		})
+		.on("uncaughtException", async err => {
+			process.stderr.write(formatFatalError("Uncaught Exception", err));
+			logger.error("Uncaught exception", { err, stack: err.stack });
+			await runCleanup(Reason.UNCAUGHT_EXCEPTION);
+			process.exit(1);
+		})
+		.on("unhandledRejection", async reason => {
+			const err = reason instanceof Error ? reason : new Error(String(reason));
+			process.stderr.write(formatFatalError("Unhandled Rejection", err));
+			logger.error("Unhandled rejection", { err, stack: err.stack });
+			await runCleanup(Reason.UNHANDLED_REJECTION);
+			process.exit(1);
+		})
+		.on("exit", async () => {
+			void runCleanup(Reason.EXIT); // fire and forget (exit imminent)
+		})
+		.on("SIGTERM", async () => {
+			await runCleanup(Reason.SIGTERM);
+			process.exit(143); // 128 + SIGTERM (15)
+		})
+		.on("SIGHUP", async () => {
+			await runCleanup(Reason.SIGHUP);
+			process.exit(129); // 128 + SIGHUP (1)
+		});
+} else {
+	// Worker thread: only register exit handler for cleanup.
+	// DO NOT register uncaughtException/unhandledRejection handlers here -
+	// they would swallow errors before the worker's own handlers (self.addEventListener)
+	// can report failures back to the parent thread.
+	process.on("exit", () => {
+		void runCleanup(Reason.EXIT);
+	});
+}
+
+/**
+ * Register a process cleanup callback, to be run on shutdown, signal, or fatal error.
+ *
+ * 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.
+ */
+export function register(id: string, callback: (reason: Reason) => void | Promise<void>): () => void {
+	let done = false;
+	const exec = (reason: Reason) => {
+		if (done) return;
+		done = true;
+		try {
+			return callback(reason);
+		} catch (e) {
+			const err = e instanceof Error ? e : new Error(String(e));
+			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") {
+		// If cleanup is already running/completed, warn and run on microtask.
+		logger.warn("Cleanup invoked recursively", { 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 () => {};
+	}
+
+	// Register callback as "armed" (active).
+	callbackList.push(exec);
+	return cancel;
+}
+
+/**
+ * Runs all cleanup callbacks without exiting.
+ * Use this in workers or when you need to clean up but continue execution.
+ */
+export function cleanup(): Promise<void> {
+	return runCleanup(Reason.MANUAL);
+}
+
+/**
+ * Runs all cleanup callbacks and exits.
+ *
+ * In main thread: waits for stdout drain, then calls process.exit().
+ * In workers: runs cleanup only (process.exit would kill entire process).
+ */
+export async function quit(code: number = 0): Promise<void> {
+	await runCleanup(Reason.MANUAL);
+
+	if (!isMainThread) {
+		return; // Workers: cleanup done, let worker exit naturally
+	}
+
+	if (process.stdout.writableLength > 0) {
+		const { promise, resolve } = Promise.withResolvers<void>();
+		process.stdout.once("drain", resolve);
+		await Promise.race([promise, Bun.sleep(5000)]);
+	}
+	process.exit(code);
+}