@oh-my-pi/pi-utils 18.16.0 → 18.18.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## [Unreleased]
 
+## [18.18.0] - 2026-11-07
+
+### Fixed
+
+- Fixed abort signals leaving command output reads blocked when a descendant keeps stdout or stderr open after the root process exits. ([#18309](https://github.com/can1357/oh-my-pi/pull/18309) by [@eggpeat](https://github.com/eggpeat))
+
+## [18.17.0] - 2026-11-06
+
+### Added
+
+- Added `getUpdateStateDir()`, returning the auto-update state directory (`~/.omp/update`).
+- Added `logger.setLogForwarder()` and `logger.emitForeign()` to forward log records across threads, preserving context and timestamps.
+- Added `expandTilde()` to expand a leading `~` to the home directory.
+
+### Fixed
+
+- Fixed `spawn`/`exec` timeouts never firing when the command's root exited before `spawn()` returned, which let a descendant holding stdout or stderr stall output reads until it exited.
+- `ptree` commands with `subreaper: true` now reliably terminate all descendants on graceful shutdown.
+- `fatal()` in a worker thread now reaches the parent's `error` listeners instead of only exiting with code 1.
+- Fixed the terminal stderr guard leaking a copy of the terminal into processes spawned from native code.
+
 ## [18.16.0] - 2026-11-02
 
 ### Added

package/dist/types/dirs.d.ts

@@ -142,6 +142,12 @@ export declare function getAgentDir(): string;
 export declare function getProjectAgentDir(cwd?: string): string;
 /** Get the reports directory (~/.omp/reports). */
 export declare function getReportsDir(): string;
+/**
+ * Get the self-update state directory (~/.omp/update): the background
+ * auto-update's status file and worker log, and the lock that keeps two
+ * installs (`omp update`, auto-update) from running at once.
+ */
+export declare function getUpdateStateDir(): string;
 /**
  * Get the logs directory (~/.omp/logs). `bun test` processes get
  * `<tmpdir>/omp-test-logs-<uid>` instead, so suites never write into the

package/dist/types/logger.d.ts

@@ -9,6 +9,35 @@ export interface LogEvent {
 }
 /** Receives each structured log event after the local transport path runs. */
 export type LogSink = (event: LogEvent) => void;
+/**
+ * Destination that takes this thread's log records in place of its own
+ * transports and sinks (a worker thread routing records to the main thread's
+ * logger); see {@link setLogForwarder}.
+ */
+export interface LogForwarder {
+    /**
+     * Take one record. Its context is already merged over the enclosing
+     * {@link withContext} fields and reduced to plain JSON data, so it survives
+     * a structured clone; `timestamp` is when the record was logged.
+     */
+    emit(event: LogEvent): void;
+    /** Write every record emitted so far on the receiving side; backs {@link flush}. */
+    flush(): void;
+}
+/**
+ * Route every later record logged on this thread to `forwarder` instead of the
+ * local transports and sinks, which then stay unused (no log file is opened);
+ * {@link flush} asks the forwarder to flush. `undefined` restores local logging.
+ * For worker threads, whose main thread owns the process log file.
+ */
+export declare function setLogForwarder(forwarder: LogForwarder | undefined): void;
+/**
+ * Log a record another thread forwarded (see {@link setLogForwarder}): written
+ * to the local transports with its own timestamp, then handed to the sinks. Its
+ * context is taken as is; the caller's enclosing {@link withContext} is not
+ * merged in. On a thread that forwards itself, the record is forwarded on.
+ */
+export declare function emitForeign(event: LogEvent): void;
 /** Register an out-of-band log sink and return a disposer. */
 export declare function registerLogSink(sink: LogSink): () => void;
 /**

package/dist/types/path.d.ts

@@ -8,3 +8,5 @@ export declare function stripWindowsExtendedLengthPathPrefix(filePath: string, p
  * On POSIX, requires an absolute path.
  */
 export declare function isFullyQualifiedPath(filePath: string, platform?: NodeJS.Platform): boolean;
+/** Expands a leading `~` (`~`, `~/…`, `~\…`, `~name`) to `home`, the user's home directory by default. */
+export declare function expandTilde(filePath: string, home?: string): string;

package/dist/types/procmgr.d.ts

@@ -40,7 +40,7 @@ export declare function resolveBasicShell(): string | undefined;
  * Resolve the external shell to advertise on Windows.
  *
  * A host bash is OPTIONAL: bash tool commands always execute in the embedded
- * brush-core shell. The resolved binary only serves the spawn-a-shell paths
+ * bash engine (pi-shell). The resolved binary only serves the spawn-a-shell paths
  * (interactive PTY sessions, ACP client terminals, SHELL env), so this
  * prefers a real Git Bash when one exists and otherwise falls back to
  * cmd.exe — it never fails.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-utils",
-	"version": "18.16.0",
+	"version": "18.18.0",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"cli",
@@ -49,15 +49,15 @@
 	},
 	"scripts": {
 		"check": "oxlint . && oxfmt --check --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts' && bun run check:types",
-		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"check:types": "bun check --no-script -p tsconfig.json",
 		"lint": "oxlint .",
 		"test": "bun test --parallel",
 		"fix": "oxlint --fix --fix-suggestions . && bun run fmt",
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "18.16.0",
-		"@oh-my-pi/pi-natives": "18.16.0"
+		"@oh-my-pi/omptype": "18.18.0",
+		"@oh-my-pi/pi-natives": "18.18.0"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/dirs.ts

@@ -656,6 +656,15 @@ export function getReportsDir(): string {
 	return dirs.rootSubdir("reports", "state");
 }
 
+/**
+ * Get the self-update state directory (~/.omp/update): the background
+ * auto-update's status file and worker log, and the lock that keeps two
+ * installs (`omp update`, auto-update) from running at once.
+ */
+export function getUpdateStateDir(): string {
+	return dirs.rootSubdir("update", "state");
+}
+
 /**
  * Get the logs directory (~/.omp/logs). `bun test` processes get
  * `<tmpdir>/omp-test-logs-<uid>` instead, so suites never write into the

package/src/logger.ts

@@ -25,6 +25,7 @@ import { RotatingFileSink } from "./logger/rotating-file";
 import { isPidAlive } from "./pid";
 import { setStderrRedirectTarget } from "./stderr-guard";
 import { drainModuleLoadEvents } from "./timing-buffer";
+import { isRecord } from "./type-guards";
 /** Severity names accepted by the centralized logger. */
 export type LogLevel = "error" | "warn" | "info" | "debug";
 
@@ -39,8 +40,103 @@ export interface LogEvent {
 /** Receives each structured log event after the local transport path runs. */
 export type LogSink = (event: LogEvent) => void;
 
+/**
+ * Destination that takes this thread's log records in place of its own
+ * transports and sinks (a worker thread routing records to the main thread's
+ * logger); see {@link setLogForwarder}.
+ */
+export interface LogForwarder {
+	/**
+	 * Take one record. Its context is already merged over the enclosing
+	 * {@link withContext} fields and reduced to plain JSON data, so it survives
+	 * a structured clone; `timestamp` is when the record was logged.
+	 */
+	emit(event: LogEvent): void;
+	/** Write every record emitted so far on the receiving side; backs {@link flush}. */
+	flush(): void;
+}
+
 const logSinks = new Set<LogSink>();
 
+/** Set by {@link setLogForwarder}: records go there instead of to local transports and sinks. */
+let logForwarder: LogForwarder | undefined;
+
+/**
+ * Route every later record logged on this thread to `forwarder` instead of the
+ * local transports and sinks, which then stay unused (no log file is opened);
+ * {@link flush} asks the forwarder to flush. `undefined` restores local logging.
+ * For worker threads, whose main thread owns the process log file.
+ */
+export function setLogForwarder(forwarder: LogForwarder | undefined): void {
+	logForwarder = forwarder;
+}
+
+/**
+ * Log a record another thread forwarded (see {@link setLogForwarder}): written
+ * to the local transports with its own timestamp, then handed to the sinks. Its
+ * context is taken as is; the caller's enclosing {@link withContext} is not
+ * merged in. On a thread that forwards itself, the record is forwarded on.
+ */
+export function emitForeign(event: LogEvent): void {
+	const forwarder = logForwarder;
+	if (forwarder) {
+		try {
+			forwarder.emit(event);
+		} catch {
+			// Forwarding is as best-effort as local writes.
+		}
+		return;
+	}
+	try {
+		emitLocally(event.level, event.message, event.context, event.timestamp);
+	} catch {
+		// Silently ignore logging failures
+	}
+	dispatchToSinks(event);
+}
+
+/** Forward one record logged on this thread; never throws. */
+function forwardRecord(
+	forwarder: LogForwarder,
+	level: LogLevel,
+	message: string,
+	context: Record<string, unknown> | undefined,
+): void {
+	try {
+		forwarder.emit({ level, message, context: forwardableContext(context), timestamp: new Date() });
+	} catch {
+		// Forwarding is as best-effort as local writes.
+	}
+}
+
+/**
+ * The call's context merged over the enclosing {@link withContext} fields (call
+ * fields win, as for sinks), as plain JSON data: errors become
+ * `{ name, message, stack, … }` exactly as in the log file. A context that
+ * cannot be serialized (a cycle, a bigint) is dropped from the record.
+ */
+function forwardableContext(context: Record<string, unknown> | undefined): Record<string, unknown> | undefined {
+	// An Error passed as the context carries its fields as non-enumerable properties.
+	let merged = context instanceof Error ? errorToRecord(context) : context;
+	const scoped = logContextStorage.getStore();
+	if (scoped) {
+		try {
+			merged = { ...scoped, ...merged };
+		} catch {
+			// A throwing getter must not turn a log call into a failure; keep the call's own fields.
+		}
+	}
+	if (merged === undefined) return undefined;
+	try {
+		const parsed: unknown = JSON.parse(
+			mayContainError(merged) ? JSON.stringify(merged, jsonReplacer) : JSON.stringify(merged),
+		);
+		return isRecord(parsed) ? parsed : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 /** Register an out-of-band log sink and return a disposer. */
 export function registerLogSink(sink: LogSink): () => void {
 	logSinks.add(sink);
@@ -62,7 +158,11 @@ function emitToSinks(level: LogLevel, message: string, context: Record<string, u
 			// A throwing getter must not turn a log call into a failure; sinks get the call's own fields.
 		}
 	}
-	const event: LogEvent = { level, message, context: merged, timestamp: new Date() };
+	dispatchToSinks({ level, message, context: merged, timestamp: new Date() });
+}
+
+function dispatchToSinks(event: LogEvent): void {
+	if (logSinks.size === 0) return;
 	for (const sink of logSinks) {
 		try {
 			sink(event);
@@ -199,19 +299,21 @@ function ensureDir(dir: string): string {
  * forensic logs showed only an opaque empty object.
  */
 function jsonReplacer(_key: string, value: unknown): unknown {
-	if (value instanceof Error) {
-		const out: Record<string, unknown> = {
-			name: value.name,
-			message: value.message,
-			stack: value.stack,
-		};
-		// Preserve `.cause` and any custom enumerable fields the caller attached.
-		const errAsRecord = value as unknown as Record<string, unknown>;
-		for (const k in errAsRecord) out[k] = errAsRecord[k];
-		if (value.cause !== undefined) out.cause = value.cause;
-		return out;
-	}
-	return value;
+	return value instanceof Error ? errorToRecord(value) : value;
+}
+
+/** An Error's fields as a plain object: name, message, stack, enumerable extras, and `cause`. */
+function errorToRecord(value: Error): Record<string, unknown> {
+	const out: Record<string, unknown> = {
+		name: value.name,
+		message: value.message,
+		stack: value.stack,
+	};
+	// Preserve `.cause` and any custom enumerable fields the caller attached.
+	const errAsRecord = value as unknown as Record<string, unknown>;
+	for (const k in errAsRecord) out[k] = errAsRecord[k];
+	if (value.cause !== undefined) out.cause = value.cause;
+	return out;
 }
 
 // Values visited by the Error pre-scan before falling back to the replacer.
@@ -278,12 +380,16 @@ export function withoutContext<T>(fn: () => T): T {
 	return logContextStorage.exit(fn);
 }
 
-/** Serialize one log record: timestamp, level, pid, message, then context fields. */
+/**
+ * Serialize one log record: timestamp, level, pid, message, then the `scoped`
+ * ({@link withContext}) fields and the context fields.
+ */
 function formatLogRecord(
 	level: LogLevel,
 	message: string,
 	context: Record<string, unknown> | undefined,
 	timestamp: string,
+	scoped: Readonly<Record<string, unknown>> | undefined,
 ): string {
 	const metadata =
 		!FORMAT_TOKEN_PATTERN.test(message) && context !== null && typeof context === "object" ? context : undefined;
@@ -293,7 +399,6 @@ function formatLogRecord(
 		pid: process.pid,
 		message: metadata?.message ? `${message} ${metadata.message}` : message,
 	};
-	const scoped = logContextStorage.getStore();
 	if (scoped) {
 		for (const key of Object.keys(scoped)) {
 			if (key !== "level" && key !== "timestamp" && key !== "message") entry[key] = scoped[key];
@@ -370,7 +475,8 @@ function resolveFileLevelRank(): number {
  */
 export function flush(): void {
 	try {
-		activeTransports?.file?.flush();
+		if (logForwarder) logForwarder.flush();
+		else activeTransports?.file?.flush();
 	} catch {
 		// Flushing diagnostics must never mask the caller's own work or failure.
 	}
@@ -405,13 +511,25 @@ function getLocalTransports(): LocalTransports {
 	return activeTransports;
 }
 
-function emitLocally(level: LogLevel, message: string, context: Record<string, unknown> | undefined): void {
+/**
+ * Write one record to the local transports. A `foreignTimestamp` marks a record
+ * another thread logged ({@link emitForeign}): it keeps that time and gets no
+ * {@link withContext} fields of this call stack, while the file still rotates by
+ * the current day so a late record cannot reopen an earlier day's file.
+ */
+function emitLocally(
+	level: LogLevel,
+	message: string,
+	context: Record<string, unknown> | undefined,
+	foreignTimestamp?: Date,
+): void {
 	const transports = getLocalTransports();
 	const rank = LOG_LEVEL_RANK[level];
 	const file = rank <= transports.fileLevelRank ? transports.file : undefined;
 	if (!file && !transports.console) return;
 	const now = new Date();
-	const line = formatLogRecord(level, message, context, formatLocalTimestamp(now));
+	const scoped = foreignTimestamp ? undefined : logContextStorage.getStore();
+	const line = formatLogRecord(level, message, context, formatLocalTimestamp(foreignTimestamp ?? now), scoped);
 	file?.write(line, rank <= IMMEDIATE_FLUSH_RANK || exiting, localDay(now));
 	if (transports.console) fs.writeSync(1, `${line}${os.EOL}`);
 }
@@ -438,6 +556,7 @@ export function setTransports(opts: { console?: boolean; file?: boolean | string
  * @param context - The context to log.
  */
 export function error(message: string, context?: Record<string, unknown>): void {
+	if (logForwarder) return forwardRecord(logForwarder, "error", message, context);
 	try {
 		emitLocally("error", message, context);
 	} catch {
@@ -452,6 +571,7 @@ export function error(message: string, context?: Record<string, unknown>): void
  * @param context - The context to log.
  */
 export function warn(message: string, context?: Record<string, unknown>): void {
+	if (logForwarder) return forwardRecord(logForwarder, "warn", message, context);
 	try {
 		emitLocally("warn", message, context);
 	} catch {
@@ -466,6 +586,7 @@ export function warn(message: string, context?: Record<string, unknown>): void {
  * @param context - The context to log.
  */
 export function info(message: string, context?: Record<string, unknown>): void {
+	if (logForwarder) return forwardRecord(logForwarder, "info", message, context);
 	try {
 		emitLocally("info", message, context);
 	} catch {
@@ -480,6 +601,7 @@ export function info(message: string, context?: Record<string, unknown>): void {
  * @param context - The context to log.
  */
 export function debug(message: string, context?: Record<string, unknown>): void {
+	if (logForwarder) return forwardRecord(logForwarder, "debug", message, context);
 	try {
 		emitLocally("debug", message, context);
 	} catch {

package/src/path.ts

@@ -1,3 +1,4 @@
+import * as os from "node:os";
 import * as path from "node:path";
 
 const WINDOWS_DRIVE_PATH = /^([A-Za-z]):[\\/](.*)$/;
@@ -54,3 +55,16 @@ export function isFullyQualifiedPath(filePath: string, platform: NodeJS.Platform
 	}
 	return true;
 }
+
+/** Expands a leading `~` (`~`, `~/…`, `~\…`, `~name`) to `home`, the user's home directory by default. */
+export function expandTilde(filePath: string, home?: string): string {
+	const h = home ?? os.homedir();
+	if (filePath === "~") return h;
+	if (filePath.startsWith("~/") || filePath.startsWith("~\\")) {
+		return h + filePath.slice(1);
+	}
+	if (filePath.startsWith("~")) {
+		return path.join(h, filePath.slice(1));
+	}
+	return filePath;
+}

package/src/postmortem.ts

@@ -713,6 +713,8 @@ export async function fatal(error: unknown): Promise<never> {
 	const report = `${Bun.inspect(error, { colors: process.stderr.isTTY === true })}\n`;
 	if (!Bun.isMainThread) {
 		process.stderr.write(`${report}${formatFatalRecoveryHints(fatalRecoveryHintProviders)}`);
+		// An explicit exit alone leaves the parent only `close` with code 1; this reaches its `error` listeners.
+		reportError(err);
 		process.exit(1);
 	}
 	return exitAfterFatal(report, "Fatal error", err, Reason.UNHANDLED_REJECTION);

package/src/procmgr.ts

@@ -142,7 +142,7 @@ export function resolveBasicShell(): string | undefined {
  * Resolve the external shell to advertise on Windows.
  *
  * A host bash is OPTIONAL: bash tool commands always execute in the embedded
- * brush-core shell. The resolved binary only serves the spawn-a-shell paths
+ * bash engine (pi-shell). The resolved binary only serves the spawn-a-shell paths
  * (interactive PTY sessions, ACP client terminals, SHELL env), so this
  * prefers a real Git Bash when one exists and otherwise falls back to
  * cmd.exe — it never fails.

package/src/ptree.ts

@@ -7,6 +7,7 @@
  * - Convenience helpers: captureText / execText, AbortSignal, timeouts.
  */
 
+import * as os from "node:os";
 import { Process, type ProcessTerminateOptions } from "@oh-my-pi/pi-natives";
 import type { Spawn, Subprocess } from "bun";
 
@@ -183,18 +184,22 @@ export class ChildProcess<In extends InMask = InMask> {
 	#stderrDone: Promise<void>;
 	#exited: Promise<number>;
 	#openPipeReaders = 1;
-	// Set by attachTimeout() at the command deadline; untimed commands keep
-	// complete EOF-based capture. Active pipe readers are cancelled at cutoff so
-	// their pending read() settles as done and partial output is kept.
+	// Set at the command deadline or on abort; otherwise commands keep complete
+	// EOF-based capture. Active pipe readers are cancelled at cutoff so their
+	// pending read() settles as done and partial output is kept.
 	#cutoff = false;
-	/** Readers of piped stdio; the timeout cancels them so pending reads settle. */
+	/** Readers of piped stdio; timeout and abort cancel them so pending reads settle. */
 	#pipeReaders = new Set<{ cancel(reason?: unknown): Promise<void> }>();
+	// Each registration reconciles its listener with root-exit and reader activity.
+	// Keeping the registration after idle lets a later output read re-arm the signal.
+	#abortRegistrations?: Set<() => void>;
 	#timeoutTimer?: NodeJS.Timeout;
 	#stderrStream?: ReadableStream<Uint8Array>;
 	// Termination in flight after kill(); aborted exits await it before reporting.
 	#terminating?: Promise<boolean | void>;
-	// A hard subreaper sweep must remain authoritative across overlapping kill requests.
-	#hardKillSweep?: Promise<void>;
+	// The one stop sequence of a subreaper-supervised command; a later hard
+	// kill request ends its grace period, and any other later request is a no-op.
+	#subreaperStop?: { escalate: () => void };
 	#terminateGroup: boolean;
 	#hardKillTree: boolean;
 	// Windows has no process groups. Retaining the root's native handle pins
@@ -247,11 +252,13 @@ export class ChildProcess<In extends InMask = InMask> {
 			this.#openPipeReaders--;
 			this.#stderrTail += dec.decode();
 			trim();
+			this.#syncAbortListeners();
 		})();
 
 		proc.exited
 			.catch(() => null)
 			.then(async exitCode => {
+				this.#syncAbortListeners();
 				if (this.#exitReasonPending) {
 					this.#exitReason = this.#exitReasonPending;
 					reject(this.#exitReasonPending);
@@ -339,22 +346,31 @@ export class ChildProcess<In extends InMask = InMask> {
 			// group leader; wait() still needs to report the later deadline.
 			if (this.proc.exitCode !== null) this.#exitReason = reason;
 		}
-		// An AbortSignal can race a timeout after its hard subreaper sweep has
-		// started. Do not replace that sweep with a normal root termination: the
-		// root must stay alive until adopted descendants have been collected.
-		if (this.#hardKillSweep) return;
-		if (gracefulMs !== undefined && gracefulMs < 0 && this.#hardKillTree && this.proc.exitCode === null) {
-			// Keep the subreaper alive while descendants are killed. A single
-			// killTree() snapshot can miss a worker whose parent exits during the
-			// walk and reparents it to the subreaper after that root was enumerated.
-			const root = Process.fromPid(this.proc.pid);
+		// A command under the Linux subreaper is stopped without ever signalling
+		// the subreaper politely: SIGTERM would end it, its orphaned descendants
+		// would reparent to init, and the SIGKILL that follows would not find a
+		// descendant that ignored SIGTERM. One stop sequence serves every kill
+		// request; a hard request during its grace period ends the grace early.
+		if (this.#subreaperStop) {
+			if (gracefulMs !== undefined && gracefulMs < 0) this.#subreaperStop.escalate();
+			return;
+		}
+		if (this.#hardKillTree && this.proc.exitCode === null && this.proc.signalCode === null) {
+			let root: Process | null = null;
+			try {
+				root = Process.fromPid(this.proc.pid);
+			} catch {
+				// No usable native handle: the direct-signal fallback below still ends the subreaper.
+			}
 			if (root) {
-				const sweep = this.#hardKillSubreaperTree(root).catch(e => void e);
-				this.#hardKillSweep = sweep;
-				this.#terminating = sweep;
-				void sweep.finally(() => {
-					if (this.#hardKillSweep === sweep) this.#hardKillSweep = undefined;
-				});
+				const { promise: escalated, resolve: escalate } = Promise.withResolvers<void>();
+				const graceMs = gracefulMs === undefined ? 1000 : gracefulMs;
+				if (graceMs < 0) escalate();
+				// A stop that fails part-way (a native handle that cannot be used)
+				// must not count as a finished termination: signal the subreaper directly.
+				const stop = this.#stopSubreaperTree(root, graceMs, escalated).catch(() => this.#signalChild(graceMs));
+				this.#subreaperStop = { escalate };
+				this.#terminating = stop;
 				return;
 			}
 		}
@@ -421,6 +437,57 @@ export class ChildProcess<In extends InMask = InMask> {
 		if (this.proc.exitCode === null && this.proc.signalCode === null) signal("SIGKILL");
 	}
 
+	/**
+	 * Stop a subreaper-supervised command: SIGTERM to each of the subreaper's
+	 * children and their trees (never the subreaper itself), then, after
+	 * `gracefulMs`, the subreaper's own exit, or `escalated`, the hard sweep.
+	 * A negative `gracefulMs` skips the SIGTERM; zero sends it and sweeps at once.
+	 * The subreaper stays alive through the grace period, so a descendant
+	 * orphaned in it is still the subreaper's child when the sweep runs.
+	 *
+	 * A subreaper with no child has not launched the command yet (or the
+	 * command has ended). It is looked at again while frozen with SIGSTOP and,
+	 * when still childless, killed, so a command cancelled before its launch
+	 * never starts. Freeze, kill and resume all go through `root`, the native
+	 * handle pinned to the subreaper's identity, never through the numeric pid:
+	 * once the subreaper has been reaped and its pid reused, they signal
+	 * nothing. The resume runs on every way out of the frozen section,
+	 * including a throw; it is a no-op on a killed subreaper. The grace timer is
+	 * cleared as soon as the sequence moves on, so a finished stop never keeps
+	 * the caller's process alive.
+	 */
+	async #stopSubreaperTree(root: Process, gracefulMs: number, escalated: Promise<void>): Promise<void> {
+		let children = root.children();
+		if (children.length === 0) {
+			try {
+				root.killTree(os.constants.signals.SIGSTOP);
+				children = root.children();
+				if (children.length === 0) {
+					root.killTree(9);
+					return;
+				}
+				// It launched the command just before the freeze: the first wave
+				// goes to the snapshot taken while it cannot fork.
+				for (const child of children) child.killTree(gracefulMs < 0 ? 9 : 15);
+			} finally {
+				root.killTree(os.constants.signals.SIGCONT);
+			}
+		} else {
+			// The subreaper launches one command; once it has a child, no later launch can escape the snapshot.
+			for (const child of children) child.killTree(gracefulMs < 0 ? 9 : 15);
+		}
+		if (gracefulMs >= 0) {
+			const { promise: graceOver, resolve: endGrace } = Promise.withResolvers<void>();
+			const graceTimer = setTimeout(endGrace, gracefulMs);
+			try {
+				await Promise.race([this.proc.exited, graceOver, escalated]);
+			} finally {
+				clearTimeout(graceTimer);
+			}
+		}
+		await this.#hardKillSubreaperTree(root);
+	}
+
 	async #hardKillSubreaperTree(root: Process): Promise<void> {
 		try {
 			const deadline = Date.now() + SUBREAPER_KILL_WINDOW_MS;
@@ -460,12 +527,13 @@ export class ChildProcess<In extends InMask = InMask> {
 	}
 
 	/**
-	 * Read a pipe fully, stopping early only at an explicit command deadline.
+	 * Read a pipe fully, stopping early only at an explicit command deadline or abort.
 	 */
 	async #readStream(stream: ReadableStream<Uint8Array>): Promise<string> {
-		this.#openPipeReaders++;
 		const reader = stream.getReader();
+		this.#openPipeReaders++;
 		this.#pipeReaders.add(reader);
+		this.#syncAbortListeners();
 		const dec = new TextDecoder();
 		let out = "";
 		try {
@@ -481,15 +549,18 @@ export class ChildProcess<In extends InMask = InMask> {
 		} catch {
 			// A cancelled or failed read keeps whatever was already collected.
 		}
+		const tail = dec.decode();
 		this.#pipeReaders.delete(reader);
 		this.#openPipeReaders--;
-		return out + dec.decode();
+		this.#syncAbortListeners();
+		return out + tail;
 	}
 
 	async #readBytes(): Promise<Uint8Array<ArrayBuffer>> {
 		const reader = this.proc.stdout.getReader();
 		this.#openPipeReaders++;
 		this.#pipeReaders.add(reader);
+		this.#syncAbortListeners();
 		const chunks: Uint8Array[] = [];
 		let length = 0;
 		try {
@@ -509,6 +580,7 @@ export class ChildProcess<In extends InMask = InMask> {
 			this.#pipeReaders.delete(reader);
 			this.#openPipeReaders--;
 			reader.releaseLock();
+			this.#syncAbortListeners();
 		}
 		const bytes = new Uint8Array(length);
 		let offset = 0;
@@ -591,11 +663,43 @@ export class ChildProcess<In extends InMask = InMask> {
 	// ── Signal / timeout ─────────────────────────────────────────────────
 
 	attachSignal(signal: AbortSignal): void {
-		const cleanup = this.#exited.catch(() => {});
-		const onAbort = () => this.kill(new AbortError(signal.reason, "<cancelled>"));
-		if (signal.aborted) return void onAbort();
-		signal.addEventListener("abort", onAbort, { once: true });
-		cleanup.finally(() => signal.removeEventListener("abort", onAbort));
+		this.#exited.catch(() => {});
+		let attached = false;
+		const onAbort = () => {
+			// The { once: true } listener has removed itself at this point.
+			attached = false;
+			const rootRunning = this.proc.exitCode === null && this.proc.signalCode === null;
+			if (rootRunning || this.#openPipeReaders > 0) {
+				this.#abortRegistrations?.delete(sync);
+			}
+			this.kill(new AbortError(signal.reason, "<cancelled>"));
+			this.#cutoffOutput();
+		};
+		const sync = () => {
+			const rootRunning = this.proc.exitCode === null && this.proc.signalCode === null;
+			const active = rootRunning || this.#openPipeReaders > 0;
+			if (signal.aborted) {
+				if (active) onAbort();
+				return;
+			}
+			if (active === attached) return;
+			if (active) signal.addEventListener("abort", onAbort, { once: true });
+			else signal.removeEventListener("abort", onAbort);
+			attached = active;
+		};
+		(this.#abortRegistrations ??= new Set()).add(sync);
+		if (signal.aborted) onAbort();
+		else sync();
+	}
+
+	#syncAbortListeners(): void {
+		if (!this.#abortRegistrations) return;
+		for (const sync of this.#abortRegistrations) sync();
+	}
+
+	#cutoffOutput(): void {
+		this.#cutoff = true;
+		for (const reader of this.#pipeReaders) reader.cancel().catch(() => {});
 	}
 
 	#clearTimeout(): void {
@@ -605,7 +709,9 @@ export class ChildProcess<In extends InMask = InMask> {
 	}
 
 	attachTimeout(ms: number): void {
-		if (ms <= 0 || this.proc.killed) return;
+		// Not skipped for a root Bun already reports as exited (`proc.killed`): it can
+		// exit before spawn() returns, while a descendant still holds its pipes.
+		if (ms <= 0) return;
 		this.#exited.catch(() => {});
 		// One unref'd deadline controls both termination and pipe collection.
 		// A clean command clears it in wait(), so fast invocations do not hold
@@ -620,8 +726,7 @@ export class ChildProcess<In extends InMask = InMask> {
 			) {
 				this.kill(new TimeoutError(ms, this.#stderrTail), -1);
 			}
-			this.#cutoff = true;
-			for (const reader of this.#pipeReaders) reader.cancel().catch(() => {});
+			this.#cutoffOutput();
 		}, ms);
 		timer.unref?.();
 		this.#timeoutTimer = timer;

package/src/stderr-guard.ts

@@ -14,9 +14,14 @@
  * so diagnostics stay greppable and Bun native-crash reports (which abort
  * before any JS cleanup can restore fd 2) are preserved.
  *
- * Only dup/dup2 go through bun:ffi. fcntl is deliberately avoided: it is
- * variadic, and the arm64-darwin ABI passes variadic arguments on the stack,
- * so a fixed-arity FFI signature would read garbage for the third argument.
+ * Only dup2 goes through bun:ffi. The saved copy of fd 2 comes from opening
+ * `/dev/fd/2` instead of `dup(2)`, because Bun opens files close-on-exec: a
+ * plain dup would leak the terminal into every child spawned without explicit
+ * fd handling (Rust `Command`, gitoxide filter drivers), which could then read
+ * the user's keystrokes and terminal replies. fcntl is deliberately avoided:
+ * it is variadic, and the arm64-darwin ABI passes variadic arguments on the
+ * stack, so a fixed-arity FFI signature would read garbage for the third
+ * argument.
  */
 import { dlopen, FFIType } from "bun:ffi";
 import * as fs from "node:fs";
@@ -27,7 +32,6 @@ const STDOUT_FILENO = 1;
 const STDERR_FILENO = 2;
 
 interface LibcFdOps {
-	dup(fd: number): number;
 	dup2(oldFd: number, newFd: number): number;
 }
 
@@ -44,7 +48,6 @@ function libcFdOps(): LibcFdOps | null {
 	for (const candidate of candidates) {
 		try {
 			const libc = dlopen(candidate, {
-				dup: { args: [FFIType.i32], returns: FFIType.i32 },
 				dup2: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
 			});
 			libcFdOpsCache = libc.symbols;
@@ -102,6 +105,15 @@ export function suppressTerminalStderr(options?: SuppressTerminalStderrOptions):
 	const libc = libcFdOps();
 	if (!libc) return false;
 
+	// First, so a fd 2 that cannot be reopened (a socket: Linux refuses
+	// `/dev/fd/N` for those) leaves the guard inert with no redirect file made.
+	let saved: number;
+	try {
+		saved = fs.openSync(`/dev/fd/${STDERR_FILENO}`, fs.constants.O_WRONLY);
+	} catch {
+		return false;
+	}
+
 	let redirectFd: number;
 	try {
 		const redirectPath = options?.redirectPath ?? redirectTarget ?? getLogPath();
@@ -115,15 +127,11 @@ export function suppressTerminalStderr(options?: SuppressTerminalStderrOptions):
 		try {
 			redirectFd = fs.openSync("/dev/null", "w");
 		} catch {
+			fs.closeSync(saved);
 			return false;
 		}
 	}
 
-	const saved = libc.dup(STDERR_FILENO);
-	if (saved === -1) {
-		fs.closeSync(redirectFd);
-		return false;
-	}
 	if (libc.dup2(redirectFd, STDERR_FILENO) === -1) {
 		fs.closeSync(redirectFd);
 		fs.closeSync(saved);