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

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [Unreleased]
 
+## [18.0.8] - 2026-08-27
+
+### Added
+
+- Added the Linux `subreaper` spawn option to retain reparented descendants for process-tree cleanup.
+
+### Fixed
+
+- Keep project-directory state unchanged when changing directories fails.
+- Fixed `ptree` timeout cleanup and output capture so timed commands retain their deadline through descendant-held pipes and untimed commands read output to EOF.
+
+## [18.0.7] - 2026-08-26
+
+### Added
+
+- Added `math-delimiters`, the LaTeX span/block delimiter grammar (`mathStartIndex`, `mathOpenerAt`, `mathSpanAt`, `mathBlockAt`) shared by every Markdown renderer: pandoc's anti-currency rules for `$…$`, own-line display blocks, and delimiters matched by backslash parity, so an escaped `\$x$` stays literal and a TeX row break cannot end a span early.
+- Added `RequestError.sessionBusy(message, data)` to represent ACP session-busy errors (`-32003`) through the shared JSON-RPC transport.
+- Exported `getComposerCacheDir` for resolving the per-project Composer cache directory, including support for `XDG_CACHE_HOME`.
+
+### Fixed
+
+- Fixed OMP sessions unexpectedly exiting during socket cleanup or optional-worker communication on Bun.
+
 ## [18.0.6] - 2026-08-26
 
 ### Added

package/README.md

@@ -17,6 +17,7 @@ Shared utilities for [oh-my-pi](https://github.com/can1357/oh-my-pi) packages. Z
 | `fs-error` | Errno guards (`isEnoent` and friends) |
 | `env` / `worker-host` | Environment plumbing and side-effect-free worker-host entry contract (`workerHostEntry`) |
 | `abortable` / `async` | AbortSignal-aware stream/promise helpers |
+| `math-delimiters` | LaTeX span/block delimiter grammar (offsets only) shared by the TUI and collab-web renderers |
 | `peek-file` | Read the first N bytes of a file with pooled buffers |
 | `frontmatter`, `glob`, `mime`, `temp`, `format`, `color`, `snowflake`, `tab-spacing`, `path-tree`, `sanitize-text` | Smaller single-purpose helpers |
 

package/dist/types/acp/transport.d.ts

@@ -55,6 +55,13 @@ export declare class RequestError extends Error {
     static authRequired(data?: unknown, additionalMessage?: string): RequestError;
     /** Creates a resource-not-found error. */
     static resourceNotFound(uri?: string): RequestError;
+    /**
+     * Creates a session-busy error: the agent/session is already processing, so the
+     * request can be retried once idle (steer/follow-up/wait) instead of treating it
+     * as a fault. `message` carries the caller's user-facing wording; `data` should
+     * keep the stable discriminator shape (`reason: "session_busy"`).
+     */
+    static sessionBusy(message: string, data?: unknown): RequestError;
     /** Converts this error into a JSON-RPC result. */
     toResult(): {
         error: ErrorResponse;

package/dist/types/dirs.d.ts

@@ -48,6 +48,10 @@ export declare function relativePathWithinRoot(root: string, candidate: string):
 export declare function getProjectDir(): string;
 /** Set the project directory. */
 export declare function setProjectDir(dir: string): void;
+/** Reset the cached project directory (test seam). */
+export declare function __resetProjectDirCacheForTests(): void;
+/** Whether a path is absent or not a directory. Other stat failures return false. */
+export declare function directoryIsMissing(dir: string): Promise<boolean>;
 /**
  * Whether `dir` resolves to an existing directory. Any stat failure — a deleted
  * path (ENOENT), permission error, or a non-directory — returns `false`, so
@@ -55,6 +59,21 @@ export declare function setProjectDir(dir: string): void;
  * working directory before {@link setProjectDir} throws on it.
  */
 export declare function directoryExists(dir: string): Promise<boolean>;
+/**
+ * Whether `dir` both exists and can be entered. POSIX `stat` succeeds for a
+ * directory whose own search/execute permission is denied (it only needs
+ * +x on the parent chain), so existence alone does not imply `chdir` works.
+ * Callers that adopt a directory as a working directory must check this
+ * rather than {@link directoryExists} alone.
+ */
+export declare function directoryIsEnterable(dir: string): Promise<boolean>;
+/** Whether `dir` is enterable, synchronous variant. See {@link directoryIsEnterable}. */
+export declare function directoryIsEnterableSync(dir: string): boolean;
+/**
+ * Project directory when it is enterable, otherwise a safe fallback.
+ * Used by spawns that must preserve project-relative behavior when healthy.
+ */
+export declare function getSafeProjectCwd(): string;
 /** Get the config directory name relative to home (e.g. ".omp" or PI_CONFIG_DIR override). */
 export declare function getConfigDirName(): string;
 /** Get the config agent directory name relative to home (e.g. ".omp/agent" or PI_CONFIG_DIR + "/agent"). */
@@ -228,6 +247,8 @@ export declare function getModelDbPath(agentDir?: string): string;
 export declare function getTinyModelsCacheDir(agentDir?: string): string;
 /** Get the document conversion cache directory (~/.omp/agent/cache/document-conversions; XDG default: $XDG_CACHE_HOME/omp/cache/document-conversions). */
 export declare function getDocumentConversionCacheDir(agentDir?: string): string;
+/** Get the per-project composer speculative cache directory (~/.omp/agent/cache/composer; XDG default: $XDG_CACHE_HOME/omp/cache/composer). */
+export declare function getComposerCacheDir(agentDir?: string): string;
 /** Get the sessions directory (~/.omp/agent/sessions). */
 export declare function getSessionsDir(agentDir?: string): string;
 /** Get the content-addressed blob store directory (~/.omp/agent/blobs). */
@@ -274,6 +295,13 @@ export declare function getProjectPluginOverridesPath(cwd?: string): string;
 export declare function getMCPConfigPath(scope: "user" | "project", cwd?: string): string;
 /** Get the SSH config file path. */
 export declare function getSSHConfigPath(scope: "user" | "project", cwd?: string): string;
+/**
+ * Application label for usage attribution (`OMP_APP_NAME`), defaulting to
+ * `omp`. Embedders that drive omp programmatically (robomp, CI bots, …) set
+ * the env var so broker-side per-client burn tracking can answer "what did
+ * app X use" instead of folding everything into one install-wide bucket.
+ */
+export declare function getAppName(): string;
 /**
  * Persistent per-install UUID stored at `~/.omp/install-id`.
  *

package/dist/types/index.d.ts

@@ -14,6 +14,7 @@ export * from "./json.js";
 export * from "./json-parse.js";
 export * as logger from "./logger.js";
 export * from "./loop-phase.js";
+export * from "./math-delimiters.js";
 export * from "./mermaid-ascii.js";
 export * from "./mime.js";
 export * from "./path.js";

package/dist/types/math-delimiters.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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;
+}
+/**
+ * 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}.
+ */
+export declare function mathStartIndex(source: string, from?: number): number | undefined;
+/** Math opener at `at`, or `undefined` when no delimiter starts there. */
+export declare function mathOpenerAt(source: string, at: number): MathOpener | 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 declare function mathSpanAt(source: string, at: number, from?: number): MathSpan | undefined;
+/** The own-line display block starting at offset 0, or `undefined`. */
+export declare function mathBlockAt(source: string): MathBlock | undefined;

package/dist/types/postmortem.d.ts

@@ -44,6 +44,19 @@ export type BrokenPipeSource = "ipc-send" | "stdio-write";
 export declare function classifyBrokenPipe(err: Error): BrokenPipeSource | undefined;
 /** Whether an EPIPE came from an IPC `send()` to an optional worker. */
 export declare function isIpcSendEpipe(err: Error): boolean;
+/**
+ * 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 declare function isInternalSocketClosedError(err: unknown): boolean;
 /**
  * Detect Bun's advanced-serialization (structured-clone) IPC decode failure.
  *

package/dist/types/ptree.d.ts

@@ -10,6 +10,13 @@ import type { Spawn, Subprocess } from "bun";
 type InMask = "pipe" | "ignore" | Buffer | Uint8Array | null;
 /** A Bun subprocess with stdout/stderr always piped (stdin may vary). */
 type PipedSubprocess<In extends InMask = InMask> = Subprocess<In, "pipe", "pipe">;
+/**
+ * Build the Linux child-subreaper entrypoint.
+ *
+ * @internal Exported so tests can force a missing first libc soname and verify
+ * the loader continues to the next candidate.
+ */
+export declare function createLinuxSubreaperScript(libcCandidates?: readonly string[]): string;
 /**
  * Base for all exceptions representing child process nonzero exit, killed, or
  * cancellation.
@@ -63,7 +70,7 @@ export declare class ChildProcess<In extends InMask = InMask> {
     #private;
     readonly proc: PipedSubprocess<In>;
     readonly exposeStderr: boolean;
-    constructor(proc: PipedSubprocess<In>, exposeStderr: boolean, retainFullStderr?: boolean);
+    constructor(proc: PipedSubprocess<In>, exposeStderr: boolean, retainFullStderr?: boolean, terminateGroup?: boolean, hardKillTree?: boolean);
     get pid(): number;
     get exited(): Promise<number>;
     get exitCode(): number | null;
@@ -93,6 +100,13 @@ export declare class ChildProcess<In extends InMask = InMask> {
 type ChildSpawnOptions<In extends InMask = InMask> = Omit<Spawn.SpawnOptions<In, "pipe", "pipe">, "stdout" | "stderr" | "detached"> & {
     signal?: AbortSignal;
     detached?: boolean;
+    /**
+     * On Linux, supervise the command from a child subreaper so descendants
+     * remain reachable after changing session and reparenting. Other platforms
+     * ignore this option. macOS process groups cannot retain a daemonized
+     * descendant that creates a new session and reparents to launchd.
+     */
+    subreaper?: boolean;
     /** Expose and retain complete stderr for a later `wait({ stderr: "full" })`. */
     stderr?: "full" | null;
 };

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "18.0.6",
+	"version": "18.0.8",
 	"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.6"
+		"@oh-my-pi/pi-natives": "18.0.8"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/acp/transport.ts

@@ -77,6 +77,15 @@ export class RequestError extends Error {
 			uri === undefined ? undefined : { uri },
 		);
 	}
+	/**
+	 * Creates a session-busy error: the agent/session is already processing, so the
+	 * request can be retried once idle (steer/follow-up/wait) instead of treating it
+	 * as a fault. `message` carries the caller's user-facing wording; `data` should
+	 * keep the stable discriminator shape (`reason: "session_busy"`).
+	 */
+	static sessionBusy(message: string, data?: unknown): RequestError {
+		return new RequestError(-32003, message, data);
+	}
 	/** Converts this error into a JSON-RPC result. */
 	toResult(): { error: ErrorResponse } {
 		return { error: this.toErrorResponse() };

package/src/dirs.ts

@@ -15,6 +15,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { engines, version } from "../package.json" with { type: "json" };
+import { isEnoent, isEnotdir } from "./fs-error";
 
 /** App name (e.g. "omp") */
 export const APP_NAME: string = "omp";
@@ -178,17 +179,50 @@ export function relativePathWithinRoot(root: string, candidate: string): string
 	return relative || null;
 }
 
-let projectDir = standardizeMacOSPath(process.cwd());
+let projectDir: string | undefined;
 
 /** Get the project directory. */
 export function getProjectDir(): string {
+	if (projectDir === undefined) {
+		try {
+			projectDir = standardizeMacOSPath(process.cwd());
+		} catch {
+			const candidates = [process.env.PWD, os.homedir(), os.tmpdir()];
+			for (const candidate of candidates) {
+				if (!candidate || !path.isAbsolute(candidate)) continue;
+				try {
+					process.chdir(candidate);
+					projectDir = standardizeMacOSPath(candidate);
+					break;
+				} catch {}
+			}
+			if (projectDir === undefined) {
+				throw new Error("Unable to determine an accessible working directory");
+			}
+		}
+	}
 	return projectDir;
 }
 
 /** Set the project directory. */
 export function setProjectDir(dir: string): void {
-	projectDir = standardizeMacOSPath(path.resolve(dir));
-	process.chdir(projectDir);
+	const resolved = standardizeMacOSPath(path.resolve(dir));
+	process.chdir(resolved);
+	projectDir = resolved;
+}
+
+/** Reset the cached project directory (test seam). */
+export function __resetProjectDirCacheForTests(): void {
+	projectDir = undefined;
+}
+
+/** Whether a path is absent or not a directory. Other stat failures return false. */
+export async function directoryIsMissing(dir: string): Promise<boolean> {
+	try {
+		return !(await fs.promises.stat(dir)).isDirectory();
+	} catch (error) {
+		return isEnoent(error) || isEnotdir(error);
+	}
 }
 
 /**
@@ -205,6 +239,44 @@ export async function directoryExists(dir: string): Promise<boolean> {
 	}
 }
 
+/**
+ * Whether `dir` both exists and can be entered. POSIX `stat` succeeds for a
+ * directory whose own search/execute permission is denied (it only needs
+ * +x on the parent chain), so existence alone does not imply `chdir` works.
+ * Callers that adopt a directory as a working directory must check this
+ * rather than {@link directoryExists} alone.
+ */
+export async function directoryIsEnterable(dir: string): Promise<boolean> {
+	try {
+		const [stats] = await Promise.all([fs.promises.stat(dir), fs.promises.access(dir, fs.constants.X_OK)]);
+		return stats.isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+/** Whether `dir` is enterable, synchronous variant. See {@link directoryIsEnterable}. */
+export function directoryIsEnterableSync(dir: string): boolean {
+	try {
+		fs.accessSync(dir, fs.constants.X_OK);
+		return fs.statSync(dir).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Project directory when it is enterable, otherwise a safe fallback.
+ * Used by spawns that must preserve project-relative behavior when healthy.
+ */
+export function getSafeProjectCwd(): string {
+	try {
+		const dir = getProjectDir();
+		if (directoryIsEnterableSync(dir)) return dir;
+	} catch {}
+	return os.homedir();
+}
+
 /** Get the config directory name relative to home (e.g. ".omp" or PI_CONFIG_DIR override). */
 export function getConfigDirName(): string {
 	return process.env.PI_CONFIG_DIR || CONFIG_DIR_NAME;
@@ -791,6 +863,10 @@ export function getTinyModelsCacheDir(agentDir?: string): string {
 export function getDocumentConversionCacheDir(agentDir?: string): string {
 	return dirs.agentSubdir(agentDir, path.join("cache", "document-conversions"), "cache");
 }
+/** Get the per-project composer speculative cache directory (~/.omp/agent/cache/composer; XDG default: $XDG_CACHE_HOME/omp/cache/composer). */
+export function getComposerCacheDir(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, path.join("cache", "composer"), "cache");
+}
 
 /** Get the sessions directory (~/.omp/agent/sessions). */
 export function getSessionsDir(agentDir?: string): string {
@@ -955,6 +1031,17 @@ export function getSSHConfigPath(scope: "user" | "project", cwd: string = getPro
 let cachedInstallId: string | null = null;
 
 const INSTALL_ID_FILE = "install-id";
+/**
+ * Application label for usage attribution (`OMP_APP_NAME`), defaulting to
+ * `omp`. Embedders that drive omp programmatically (robomp, CI bots, …) set
+ * the env var so broker-side per-client burn tracking can answer "what did
+ * app X use" instead of folding everything into one install-wide bucket.
+ */
+export function getAppName(): string {
+	const value = process.env.OMP_APP_NAME?.trim();
+	return value ? value : "omp";
+}
+
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 /**

package/src/env.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { getAgentDir, getConfigRootDir, refreshDirsFromEnv } from "./dirs";
+import { getAgentDir, getConfigRootDir, getProjectDir, refreshDirsFromEnv } from "./dirs";
 
 export * from "./worker-host";
 
@@ -228,7 +228,7 @@ export function parseEnvFile(filePath: string): Record<string, string> {
 const homeEnv = parseEnvFile(path.join(os.homedir(), ".env"));
 const piEnv = parseEnvFile(path.join(getConfigRootDir(), ".env"));
 const agentEnv = parseEnvFile(path.join(getAgentDir(), ".env"));
-const projectEnv = parseEnvFile(path.join(process.cwd(), ".env"));
+const projectEnv = parseEnvFile(path.join(getProjectDir(), ".env"));
 
 for (const key of Object.keys(Bun.env)) {
 	const value = Bun.env[key];

package/src/index.ts

@@ -14,6 +14,7 @@ export * from "./json";
 export * from "./json-parse";
 export * as logger from "./logger";
 export * from "./loop-phase";
+export * from "./math-delimiters";
 export * from "./mermaid-ascii";
 export * from "./mime";
 export * from "./path";

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

@@ -146,6 +146,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.
  *
@@ -338,9 +365,17 @@ 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 => {
+			if (isExpectedCleanupError(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 +392,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 => {

package/src/ptree.ts

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