@linxiraos/pi-utils 1.1.4 → 1.1.6

package/src/math-delimiters.ts

@@ -0,0 +1,143 @@
+/**
+ * LaTeX delimiter grammar for agent-authored Markdown: where does a math span
+ * begin and end, in source offsets. Carries no rendering policy — what to do
+ * with an unclosed opener, whether a body is typesettable, and how it is
+ * displayed belong to the renderer (Unicode in the TUI, KaTeX in collab web).
+ */
+
+/** Opening delimiter. Each closer (`$`, `$$`, `\)`, `\]`) is as wide as its opener. */
+export type MathOpener = "$" | "$$" | "\\(" | "\\[";
+
+/** A closed math span found in the source. */
+export interface MathSpan {
+	opener: MathOpener;
+	/** True for the display forms `$$…$$` and `\[…\]`. */
+	display: boolean;
+	/** Offset one past the closing delimiter. */
+	end: number;
+	/** Source between the delimiters, verbatim. */
+	body: string;
+}
+
+/** An own-line display block: opener and closer each alone on their line. */
+export interface MathBlock {
+	/** Both delimiter lines, the body, and the trailing newline. */
+	raw: string;
+	body: string;
+}
+
+// Display math blocks: opening `$$` / `\[` and closing `$$` / `\]` each alone on
+// their own line (≤3 leading spaces). Matched at the block level — before
+// paragraph/list parsing — so a multi-line equation (e.g. a matrix with `\\`
+// row breaks) survives as one unit and blank lines inside the block don't split
+// it. The own-line requirement leaves inline `$$…$$` inside prose to the span
+// grammar below. `\r?\n` at each line boundary keeps the grammar CRLF-safe for
+// direct callers; marked-fed renderers already normalize line endings first.
+const MATH_BLOCK_DOLLAR = /^ {0,3}\$\$[ \t]*\r?\n([\s\S]+?)\r?\n {0,3}\$\$[ \t]*(?:\r?\n|$)/;
+const MATH_BLOCK_BRACKET = /^ {0,3}\\\[[ \t]*\r?\n([\s\S]+?)\r?\n {0,3}\\\][ \t]*(?:\r?\n|$)/;
+
+/**
+ * Leftmost offset at or after `from` where an opener could begin. A scan hint,
+ * not a decision: whether that candidate is really math — escaped, currency,
+ * unclosed — is decided by {@link mathSpanAt}.
+ */
+// Three indexOf scans instead of a `/\$|\\\(|\\\[/` alternation — marked calls
+// this on the remaining source at every inline position, where the alternation
+// showed up in CPU profiles (part of a ~4.3% start() tail).
+export function mathStartIndex(source: string, from = 0): number | undefined {
+	let best = source.indexOf("$", from);
+	const paren = source.indexOf("\\(", from);
+	if (paren !== -1 && (best === -1 || paren < best)) best = paren;
+	const bracket = source.indexOf("\\[", from);
+	if (bracket !== -1 && (best === -1 || bracket < best)) best = bracket;
+	return best === -1 ? undefined : best;
+}
+
+/** Math opener at `at`, or `undefined` when no delimiter starts there. */
+export function mathOpenerAt(source: string, at: number): MathOpener | undefined {
+	const first = source.charCodeAt(at);
+	if (first === 0x24 /* $ */) return source.charCodeAt(at + 1) === 0x24 ? "$$" : "$";
+	if (first !== 0x5c /* \ */) return undefined;
+	const second = source.charCodeAt(at + 1);
+	if (second === 0x28 /* ( */) return "\\(";
+	if (second === 0x5b /* [ */) return "\\[";
+	return undefined;
+}
+
+/**
+ * The span opened at `at`, or `undefined` when the run is not math — including
+ * an opener the source escaped, so `\$x$` and `\\(x\)` are literal text.
+ *
+ * `from` bounds how far back the escape scan may look. Leave it at 0 when
+ * reading raw source. Pass the offset your own walk resumed at if you have
+ * already consumed the escapes behind it, as `renderMathInText` does: after it
+ * emits the `\\` of `\\\(x\)`, the `\(` that follows is a real opener even
+ * though a backslash precedes it.
+ */
+export function mathSpanAt(source: string, at: number, from = 0): MathSpan | undefined {
+	const opener = mathOpenerAt(source, at);
+	if (opener === undefined || escapedAt(source, at, from)) return undefined;
+	const bodyStart = at + opener.length;
+	const closeAt = opener === "$" ? dollarCloserIndex(source, at) : closerIndex(source, opener, bodyStart);
+	if (closeAt === -1) return undefined;
+	const body = source.slice(bodyStart, closeAt);
+	// `dollarCloserIndex` already rejects an all-space `$…$`; `$$ $$` needs the
+	// same guard here, while `\(\)` and `\[\]` are unambiguous enough to keep.
+	if (opener === "$$" && body.trim() === "") return undefined;
+	return { opener, display: opener === "$$" || opener === "\\[", end: closeAt + opener.length, body };
+}
+
+/** The own-line display block starting at offset 0, or `undefined`. */
+export function mathBlockAt(source: string): MathBlock | undefined {
+	const match = MATH_BLOCK_DOLLAR.exec(source) ?? MATH_BLOCK_BRACKET.exec(source);
+	if (!match || match[1].trim() === "") return undefined;
+	return { raw: match[0], body: match[1] };
+}
+
+/**
+ * Offset of the `$$` / `\)` / `\]` that closes a span, or -1. In `\(a \\) b\)`
+ * the `\\` is a TeX row break, so that `)` is body text and the span closes at
+ * the final `\)`.
+ */
+function closerIndex(source: string, opener: MathOpener, from: number): number {
+	// Dollar closers equal their openers; the bracket forms flip the bracket.
+	const closer = opener === "\\(" ? "\\)" : opener === "\\[" ? "\\]" : opener;
+	for (let at = source.indexOf(closer, from); at !== -1; at = source.indexOf(closer, at + 1)) {
+		if (!escapedAt(source, at, from)) return at;
+	}
+	return -1;
+}
+
+/** An odd run of backslashes back to `from` escapes the delimiter at `index`. */
+function escapedAt(source: string, index: number, from: number): boolean {
+	let backslashes = 0;
+	for (let at = index - 1; at >= from && source.charCodeAt(at) === 0x5c /* \ */; at--) backslashes++;
+	return backslashes % 2 === 1;
+}
+
+/**
+ * Offset of the `$` that closes an inline span opened at `open`, or -1. Pandoc's
+ * anti-currency heuristics: the opener must not be followed by whitespace, the
+ * closer must not be preceded by whitespace nor followed by a digit, `\$` is a
+ * literal dollar, and the span may not cross a newline — so "$5 and $10" is
+ * prose, not math.
+ */
+function dollarCloserIndex(source: string, open: number): number {
+	const after = source[open + 1];
+	if (after === undefined || after === " " || after === "\t" || after === "\n" || after === "$") return -1;
+	for (let at = open + 1; at < source.length; at++) {
+		const char = source[at];
+		if (char === "\\") {
+			at++;
+			continue;
+		}
+		if (char === "\n") return -1;
+		if (char !== "$") continue;
+		const before = source[at - 1];
+		if (before === " " || before === "\t") return -1;
+		const next = source[at + 1];
+		if (next !== undefined && next >= "0" && next <= "9") continue; // currency: keep scanning
+		return source.slice(open + 1, at).trim().length > 0 ? at : -1;
+	}
+	return -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;
 }
 
@@ -146,6 +202,33 @@ export function isIpcSendEpipe(err: Error): boolean {
 	return classifyBrokenPipe(err) === "ipc-send";
 }
 
+/**
+ * Whether an uncaught error is Bun's asynchronous `ERR_SOCKET_CLOSED` thrown
+ * from inside `node:net` internals with no application frames on the stack.
+ *
+ * Bun ≥1.4 can fire the close callback of an already-closed `node:net` socket
+ * on a fresh stack; the throw bypasses every callsite try/catch and surfaces
+ * here as a process-level uncaughtException. Closing an already-closed socket
+ * is inherently a no-op — the socket owner's own `error`/`close` handlers
+ * still drive recovery — so tearing the session down for it is pure loss.
+ * Only frameless internal stacks qualify: an `ERR_SOCKET_CLOSED` raised
+ * through application code keeps the fatal path.
+ */
+export function isInternalSocketClosedError(err: unknown): boolean {
+	if (!(err instanceof Error) || !("code" in err) || err.code !== "ERR_SOCKET_CLOSED") return false;
+	const frames = (err.stack ?? "").split("\n").slice(1);
+	if (frames.length === 0) return false;
+	let hasNetFrame = false;
+	const internal = frames.every(frame => {
+		const trimmed = frame.trim();
+		if (trimmed === "" || trimmed === "at unknown" || trimmed === "at native") return true;
+		if (!/\(node:[^)]*\)$/.test(trimmed) && !/^at node:/.test(trimmed)) return false;
+		hasNetFrame ||= trimmed.includes("node:net:");
+		return true;
+	});
+	return internal && hasNetFrame;
+}
+
 /**
  * Detect Bun's advanced-serialization (structured-clone) IPC decode failure.
  *
@@ -236,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>();
 
@@ -338,9 +425,20 @@ if (isMainThread) {
 			const url = inspector.url();
 			process.stderr.write(`Inspector opened: ${url}\n`);
 		})
-		.on("uncaughtException", async err => {
-			if (isExpectedCleanupError(err)) {
-				logger.warn("Ignoring expected cleanup exception", { err });
+		.on("uncaughtException", async 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;
+			}
+			const err = thrown instanceof Error ? thrown : new Error(String(thrown));
+			// Bun can surface a worker IPC send race through uncaughtException
+			// instead of unhandledRejection. Apply the same optional-worker
+			// containment in either global error channel.
+			if (isIpcSendEpipe(err)) {
+				logger.warn("Ignoring EPIPE from worker IPC send; optional subsystem will self-recover", { err });
 				return;
 			}
 			// A malformed advanced-serialization frame from a worker subprocess
@@ -357,6 +455,12 @@ if (isMainThread) {
 				faultWorkerIpcChannels(err);
 				return;
 			}
+			if (isInternalSocketClosedError(err)) {
+				logger.warn("Ignoring async ERR_SOCKET_CLOSED from node:net internals; socket owner recovers itself", {
+					err,
+				});
+				return;
+			}
 			await exitAfterFatal("Uncaught Exception", "Uncaught exception", err, Reason.UNCAUGHT_EXCEPTION);
 		})
 		.on("unhandledRejection", async reason => {
@@ -416,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. */
@@ -475,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);
 
@@ -482,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) {