@gajae-code/coding-agent 0.5.2 → 0.5.4

package/src/modes/components/tool-execution.ts

@@ -375,6 +375,7 @@ export class ToolExecutionComponent extends Container {
 				this.#renderState.spinnerFrame = this.#spinnerFrame;
 				this.#ui.requestRender();
 			}, 80);
+			this.#spinnerInterval?.unref?.();
 		} else if (!needsSpinner && this.#spinnerInterval) {
 			clearInterval(this.#spinnerInterval);
 			this.#spinnerInterval = undefined;
@@ -394,6 +395,11 @@ export class ToolExecutionComponent extends Container {
 		this.#editDiffAbort = undefined;
 	}
 
+	override dispose(): void {
+		this.stopAnimation();
+		super.dispose();
+	}
+
 	setExpanded(expanded: boolean): void {
 		this.#expanded = expanded;
 		this.#updateDisplay();

package/src/modes/controllers/extension-ui-controller.ts

@@ -36,9 +36,20 @@ export class ExtensionUiController {
 	#hookWidgetsAbove = new Map<string, ExtensionUiComponent>();
 	#hookWidgetsBelow = new Map<string, ExtensionUiComponent>();
 	#hookSelectorMouseReportingEnabled = false;
+	#activeHookCustomComponent?: Component & { dispose?(): void };
+	#activeHookCustomOverlay?: OverlayHandle;
 
 	constructor(private ctx: InteractiveModeContext) {}
 
+	#clearActiveHookCustom(): void {
+		const component = this.#activeHookCustomComponent;
+		const overlay = this.#activeHookCustomOverlay;
+		this.#activeHookCustomComponent = undefined;
+		this.#activeHookCustomOverlay = undefined;
+		component?.dispose?.();
+		overlay?.hide();
+	}
+
 	/**
 	 * Initialize the hook system with TUI-based UI context.
 	 */
@@ -301,7 +312,11 @@ export class ExtensionUiController {
 		spacerWhenEmpty: boolean,
 		leadingSpacer: boolean,
 	): void {
-		container.clear();
+		// Detach (not dispose): hook widgets are persistent instances owned by the
+		// #hookWidgets* maps and re-added on every rebuild. Disposal happens only on
+		// explicit removal (#removeHookWidget) or clearHookWidgets(), so a rebuild must
+		// not tear down a still-live widget (e.g. an extension CancellableLoader timer).
+		container.detachAll();
 
 		if (widgets.size === 0) {
 			if (spacerWhenEmpty) {
@@ -665,6 +680,9 @@ export class ExtensionUiController {
 					: undefined,
 			},
 		);
+		// Detach (not dispose) the reusable editor before mounting the transient hook UI, so the
+		// disposing clear() only tears down a prior transient — the editor is re-added intact on close.
+		this.ctx.editorContainer.detachChild(this.ctx.editor);
 		this.ctx.editorContainer.clear();
 		this.ctx.editorContainer.addChild(this.ctx.hookSelector);
 		this.ctx.ui.setFocus(this.ctx.hookSelector);
@@ -743,6 +761,9 @@ export class ExtensionUiController {
 				tui: this.ctx.ui,
 			},
 		);
+		// Detach (not dispose) the reusable editor before mounting the transient hook UI, so the
+		// disposing clear() only tears down a prior transient — the editor is re-added intact on close.
+		this.ctx.editorContainer.detachChild(this.ctx.editor);
 		this.ctx.editorContainer.clear();
 		this.ctx.editorContainer.addChild(this.ctx.hookInput);
 		this.ctx.ui.setFocus(this.ctx.hookInput);
@@ -791,6 +812,9 @@ export class ExtensionUiController {
 			editorOptions,
 		);
 
+		// Detach (not dispose) the reusable editor before mounting the transient hook UI, so the
+		// disposing clear() only tears down a prior transient — the editor is re-added intact on close.
+		this.ctx.editorContainer.detachChild(this.ctx.editor);
 		this.ctx.editorContainer.clear();
 		this.ctx.editorContainer.addChild(this.ctx.hookEditor);
 		this.ctx.ui.setFocus(this.ctx.hookEditor);
@@ -840,15 +864,12 @@ export class ExtensionUiController {
 
 		const { promise, resolve } = Promise.withResolvers<T>();
 		let component: (Component & { dispose?(): void }) | undefined;
-		let overlayHandle: OverlayHandle | undefined;
 		let closed = false;
 
 		const close = (result: T) => {
 			if (closed) return;
 			closed = true;
-			component?.dispose?.();
-			overlayHandle?.hide();
-			overlayHandle = undefined;
+			this.#clearActiveHookCustom();
 			if (!options?.overlay) {
 				this.ctx.editorContainer.clear();
 				this.ctx.editorContainer.addChild(this.ctx.editor);
@@ -859,14 +880,16 @@ export class ExtensionUiController {
 			resolve(result);
 		};
 
+		this.#clearActiveHookCustom();
 		Promise.try(() => factory(this.ctx.ui, theme, keybindings, close)).then(c => {
 			if (closed) {
 				c.dispose?.();
 				return;
 			}
 			component = c;
+			this.#activeHookCustomComponent = c;
 			if (options?.overlay) {
-				overlayHandle = this.ctx.ui.showOverlay(component, {
+				this.#activeHookCustomOverlay = this.ctx.ui.showOverlay(component, {
 					anchor: "bottom-center",
 					width: "100%",
 					maxHeight: "100%",
@@ -874,6 +897,9 @@ export class ExtensionUiController {
 				});
 				return;
 			}
+			// Detach (not dispose) the reusable editor before mounting the transient hook UI, so the
+			// disposing clear() only tears down a prior transient — the editor is re-added intact on close.
+			this.ctx.editorContainer.detachChild(this.ctx.editor);
 			this.ctx.editorContainer.clear();
 			this.ctx.editorContainer.addChild(component);
 			this.ctx.ui.setFocus(component);
@@ -895,6 +921,7 @@ export class ExtensionUiController {
 	}
 
 	clearHookWidgets(): void {
+		this.#clearActiveHookCustom();
 		for (const widget of this.#hookWidgetsAbove.values()) {
 			widget.dispose?.();
 		}

package/src/modes/controllers/input-controller.ts

@@ -84,6 +84,20 @@ export class InputController {
 				}
 				this.#steerConsumePending = false;
 			}
+			// Normal input state with user-typed text: Esc must not interrupt a
+			// running task (streaming turn, bash/eval). A double Esc within the
+			// 500ms window clears the composer instead. Bash/Python input modes
+			// keep their own Esc handling in the chain below.
+			if (!this.ctx.isBashMode && !this.ctx.isPythonMode && this.ctx.editor.getText().trim()) {
+				const now = Date.now();
+				if (now - this.ctx.lastComposerClearEscapeTime < 500) {
+					this.ctx.clearEditor();
+					this.ctx.lastComposerClearEscapeTime = 0;
+				} else {
+					this.ctx.lastComposerClearEscapeTime = now;
+				}
+				return;
+			}
 			if (this.ctx.loadingAnimation) {
 				if (this.ctx.cancelPendingSubmission()) {
 					return;
@@ -887,6 +901,11 @@ export class InputController {
 		this.ctx.session.agent.hideThinkingSummary = this.ctx.hideThinkingBlock;
 
 		// Rebuild chat from session messages
+		// Detach the live streaming component before the disposing clear() so the
+		// component we re-add below is not torn down (detach != dispose).
+		if (this.ctx.streamingComponent) {
+			this.ctx.chatContainer.detachChild(this.ctx.streamingComponent);
+		}
 		this.ctx.chatContainer.clear();
 		this.ctx.rebuildChatFromMessages();
 

package/src/modes/controllers/selector-controller.ts

@@ -684,7 +684,12 @@ export class SelectorController {
 					done();
 					this.ctx.ui.requestRender();
 				},
-				{ ...options, sessionId: this.ctx.session.sessionId },
+				{
+					...options,
+					sessionId: this.ctx.session.sessionId,
+					isFastForProvider: provider => this.ctx.session.isFastForProvider(provider),
+					isFastForSubagentProvider: provider => this.ctx.session.isFastForSubagentProvider(provider),
+				},
 			);
 			return { component: selector, focus: selector };
 		});

package/src/modes/interactive-mode.ts

@@ -292,6 +292,7 @@ export class InteractiveMode implements InteractiveModeContext {
 	#pendingSubmissionDispose: (() => void) | undefined;
 	lastSigintTime = 0;
 	lastEscapeTime = 0;
+	lastComposerClearEscapeTime = 0;
 	shutdownRequested = false;
 	#isShuttingDown = false;
 	hookSelector: HookSelectorComponent | undefined = undefined;
@@ -306,6 +307,7 @@ export class InteractiveMode implements InteractiveModeContext {
 	#baseSlashCommands: SlashCommand[] = [];
 	#baseReservedSlashCommandNames: Set<string> = new Set();
 	#cleanupUnsubscribe?: () => void;
+	#subprocessTeardownUnsubscribe?: () => void;
 	readonly #version: string;
 	readonly #changelogMarkdown: string | undefined;
 	#planModePreviousTools: string[] | undefined;
@@ -447,6 +449,14 @@ export class InteractiveMode implements InteractiveModeContext {
 		// Register session manager flush for signal handlers (SIGINT, SIGTERM, SIGHUP)
 		this.#cleanupUnsubscribe = postmortem.register("session-manager-flush", () => this.sessionManager.flush());
 
+		// Tear down subprocess-spawning tools (browser Chrome, Python eval kernel) on a
+		// signal kill (SIGINT/SIGTERM/SIGHUP) so they aren't reparented to PID 1 (#698).
+		// The graceful /quit path already releases these via session.dispose(); this hook
+		// is the bounded, idempotent fallback for an external kill that bypasses it.
+		this.#subprocessTeardownUnsubscribe = postmortem.register("session-subprocess-teardown", () =>
+			this.session.disposeChildSubprocesses(),
+		);
+
 		await logger.time(
 			"InteractiveMode.init:slashCommands",
 			this.refreshSlashCommandState.bind(this),
@@ -1908,6 +1918,9 @@ export class InteractiveMode implements InteractiveModeContext {
 		if (this.#cleanupUnsubscribe) {
 			this.#cleanupUnsubscribe();
 		}
+		if (this.#subprocessTeardownUnsubscribe) {
+			this.#subprocessTeardownUnsubscribe();
+		}
 		if (this.isInitialized) {
 			this.ui.stop();
 			this.isInitialized = false;

package/src/modes/types.ts

@@ -116,6 +116,7 @@ export interface InteractiveModeContext {
 	locallySubmittedUserSignatures: Set<string>;
 	lastSigintTime: number;
 	lastEscapeTime: number;
+	lastComposerClearEscapeTime: number;
 	shutdownRequested: boolean;
 	hookSelector: HookSelectorComponent | undefined;
 	hookInput: HookInputComponent | undefined;

package/src/modes/utils/ui-helpers.ts

@@ -706,13 +706,16 @@ export class UiHelpers {
 
 	/** Move pending bash components from pending area to chat */
 	flushPendingBashComponents(): void {
+		// Move (detach, not dispose) the live execution components from the pending
+		// area into the chat transcript — they are reused instances, so a disposing
+		// removeChild() would tear them down before re-adding.
 		for (const component of this.ctx.pendingBashComponents) {
-			this.ctx.pendingMessagesContainer.removeChild(component);
+			this.ctx.pendingMessagesContainer.detachChild(component);
 			this.ctx.chatContainer.addChild(component);
 		}
 		this.ctx.pendingBashComponents = [];
 		for (const component of this.ctx.pendingPythonComponents) {
-			this.ctx.pendingMessagesContainer.removeChild(component);
+			this.ctx.pendingMessagesContainer.detachChild(component);
 			this.ctx.chatContainer.addChild(component);
 		}
 		this.ctx.pendingPythonComponents = [];

package/src/prompts/agents/executor.md

@@ -37,7 +37,7 @@ This mode activates only when the assignment explicitly labels Executor as Ultra
 When active:
 - Start from the approved plan/spec/acceptance criteria, then user-facing contracts, then implementation code only as supporting evidence. Treat plan/code mismatches as blockers.
 - Exercise the real user-facing invocation rather than inspecting internals alone. Live artifacts must be runtime-valid: GUI/web needs a real automation transcript plus non-uniform screenshot; CLI needs executed argv-only replay; native/desktop/TUI needs a real screenshot, PTY capture with control codes, or app-automation transcript. `inlineEvidence` is supplemental only and is never sole proof for live surfaces.
-- For CLI evidence, emit argv-only replay JSON with `schemaVersion: 1`, `kind: "cli-replay"`, `replaySafe: true`, and `command` as a string array. Use only allowlisted deterministic executables/arguments, or mark unsafe/non-deterministic commands with audited `replayExempt` metadata plus a valid structural fallback artifact.
+- For CLI evidence, emit argv-only replay JSON with `schemaVersion: 1`, `kind: "cli-replay"`, `replaySafe: true`, and `command` as a string array. Use only allowlisted deterministic executables/arguments, or mark unsafe/non-deterministic commands with audited `replayExempt` metadata plus a valid structural fallback artifact. `replayExempt` must use exact fields `reasonCode`, `reason`, `approvedBy`, and `fallbackArtifactRefs`; allowed `reasonCode` values are exactly `unsafe_side_effect`, `requires_credentials`, `requires_network`, `non_deterministic_external`, `destructive`, `interactive_only`, and `platform_unavailable`.
 - Native/TUI evidence must be structural, not prose-only: screenshot, app transcript, or PTY artifact with terminal control codes.
 - Do not call the `ask` tool while an Ultragoal run is active; record unresolved decisions with `gjc ultragoal record-review-blockers`.
 - Try to break the work with adversarial cases, not just happy-path confirmations.

package/src/runtime/process-lifecycle.ts

@@ -0,0 +1,400 @@
+/**
+ * Shared runtime lifecycle foundation.
+ *
+ * Two minimal, deliberately small primitives that subsystem runtimes
+ * (DAP/LSP/MCP stdio, eval workers, etc.) adopt so spawned children and
+ * non-process resources cannot outlive their owner:
+ *
+ *   F1(a) `spawnOwnedProcess` — wraps `ptree.spawn` with explicit
+ *         process-group ownership, escalating (SIGTERM -> grace -> SIGKILL)
+ *         tree termination, bounded `awaitExit`, abort-listener cleanup on
+ *         settle, idempotent `dispose`, and a single postmortem hook that
+ *         reaps every still-live owned process group on fatal/normal shutdown.
+ *
+ *   F1(b) `registerResourceOwner` — a generic, idempotent postmortem adapter
+ *         for non-process resources (Bun Workers, VM contexts, timers,
+ *         sockets) built on the existing `postmortem.register` facility.
+ *
+ * Ownership is keyed to the *process group*, not the root process. A root that
+ * exits after backgrounding descendants (`sh -c "worker & exit 0"`) keeps the
+ * owner registered until the group is actually gone, so the descendant tree is
+ * still reaped by `dispose()`/postmortem.
+ *
+ * This module intentionally owns only these primitives. It does not migrate
+ * existing call sites; subsystem PRs adopt it incrementally.
+ *
+ * Note: `ptree.spawn` always pipes stdout/stderr. Adopters that expect output
+ * (DAP/LSP/MCP protocol servers) must consume `owner.child.stdout`; F1 does not
+ * drain it, so a chatty child whose stdout is never read can still block on a
+ * full pipe. That draining is the adopter's responsibility.
+ */
+import { logger, postmortem, ptree } from "@gajae-code/utils";
+
+const DEFAULT_GRACEFUL_MS = 2_000;
+// Hard cap for how long `dispose()` waits after SIGKILL before giving up so a
+// wedged, unkillable child can never block shutdown forever.
+const SIGKILL_REAP_CAP_MS = 2_000;
+// After the root process exits on its own, how long to wait for the process
+// group to drain before deregistering. Clean servers drain immediately; a root
+// that backgrounded descendants stays registered past this window.
+const ROOT_EXIT_DRAIN_MS = 250;
+
+const isPosix = process.platform !== "win32";
+
+const delay = (ms: number): Promise<void> =>
+	new Promise(resolve => {
+		const timer = setTimeout(resolve, Math.max(0, ms));
+		timer.unref?.();
+	});
+
+/** Poll `predicate` until it is true or `timeoutMs` elapses. Returns the final value. */
+async function pollUntil(predicate: () => boolean, timeoutMs: number, intervalMs = 20): Promise<boolean> {
+	if (predicate()) return true;
+	const deadline = Date.now() + Math.max(0, timeoutMs);
+	while (Date.now() < deadline) {
+		await delay(Math.min(intervalMs, Math.max(0, deadline - Date.now())));
+		if (predicate()) return true;
+	}
+	return predicate();
+}
+
+/** Whether a POSIX process group still has any member (zombies count as alive). */
+function groupAlive(pgid: number): boolean {
+	try {
+		process.kill(-pgid, 0);
+		return true;
+	} catch (err) {
+		// EPERM => the group exists but we cannot signal it; treat as alive.
+		return (err as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+/** Options for {@link spawnOwnedProcess}. */
+export interface SpawnOwnedOptions {
+	cwd?: string;
+	env?: Record<string, string | undefined>;
+	/** stdin mode passed through to the child. Defaults to `"ignore"`. */
+	stdin?: "pipe" | "ignore";
+	/** When aborted, the owned process tree is disposed (escalating kill). */
+	signal?: AbortSignal;
+	/** Grace period (ms) between SIGTERM and SIGKILL on dispose. Default 2000. */
+	gracefulMs?: number;
+	/**
+	 * Spawn the child as its own process-group leader so the whole descendant
+	 * tree can be signalled on dispose. Defaults to `true` on POSIX. Has no
+	 * effect on Windows, where teardown falls back to single-process kill.
+	 */
+	processGroup?: boolean;
+	/** Label used in diagnostics. */
+	name?: string;
+}
+
+/** Result of a bounded {@link OwnedProcess.awaitExit}. */
+export interface AwaitExitResult {
+	/** `true` when the process has exited; `false` when the timeout fired first. */
+	exited: boolean;
+	/** Exit code if known, else `null`. */
+	code: number | null;
+}
+
+/** A spawned child process owned by the runtime with guaranteed teardown. */
+export interface OwnedProcess {
+	readonly child: ptree.ChildProcess;
+	readonly pid: number | undefined;
+	/** Resolves/rejects when the root child exits (mirrors ptree's `exited`). */
+	readonly exited: Promise<number>;
+	/** `true` once `dispose()` has started. */
+	readonly disposed: boolean;
+	/**
+	 * Wait for the root child to exit, optionally bounded by `timeoutMs`. With no
+	 * timeout it resolves only when the child exits. Never rejects.
+	 */
+	awaitExit(opts?: { timeoutMs?: number }): Promise<AwaitExitResult>;
+	/**
+	 * Idempotently terminate the owned process *group*: SIGTERM the group, wait
+	 * `gracefulMs`, then SIGKILL, polling group liveness throughout. Removes the
+	 * abort listener and deregisters from the live-owner set only after teardown
+	 * has completed. Repeated/concurrent calls return the same in-flight promise.
+	 */
+	dispose(): Promise<void>;
+}
+
+const liveOwners = new Set<OwnedProcess>();
+let ownedPostmortemRegistered = false;
+
+function ensureOwnedPostmortem(): void {
+	if (ownedPostmortemRegistered) return;
+	ownedPostmortemRegistered = true;
+	postmortem.register("runtime:owned-processes", async () => {
+		await Promise.all([...liveOwners].map(owner => owner.dispose().catch(() => undefined)));
+	});
+}
+
+/**
+ * Spawn a child process owned by the runtime. The returned {@link OwnedProcess}
+ * is registered for postmortem cleanup and tears down its whole process group
+ * on dispose/abort.
+ */
+export function spawnOwnedProcess(cmd: string[], opts: SpawnOwnedOptions = {}): OwnedProcess {
+	const gracefulMs = opts.gracefulMs ?? DEFAULT_GRACEFUL_MS;
+	const useGroup = (opts.processGroup ?? true) && isPosix;
+
+	ensureOwnedPostmortem();
+
+	// We deliberately do NOT forward `opts.signal` to `ptree.spawn`: ptree's
+	// `attachSignal` only kills the single process, whereas owned teardown must
+	// signal the whole group. We wire our own abort listener below and remove it
+	// on settle so long-lived signals never accumulate listeners.
+	const child = ptree.spawn(cmd, {
+		cwd: opts.cwd,
+		env: opts.env,
+		stdin: opts.stdin ?? "ignore",
+		detached: useGroup,
+	});
+
+	// On POSIX with `detached`, the child is its own process-group leader, so the
+	// group id equals its pid. `undefined` => single-process (Windows/opt-out).
+	const pgid = useGroup ? child.pid : undefined;
+
+	let disposed = false;
+	let disposePromise: Promise<void> | undefined;
+	let deregistered = false;
+	// Terminal once teardown/reconciliation has confirmed the group is gone. A
+	// late dispose() must then be a true no-op and never re-probe a pgid the OS
+	// may have recycled into an unrelated group.
+	let terminated = false;
+	let onAbort: (() => void) | undefined;
+
+	const removeAbort = (): void => {
+		if (onAbort && opts.signal) {
+			opts.signal.removeEventListener("abort", onAbort);
+			onAbort = undefined;
+		}
+	};
+
+	const deregister = (): void => {
+		if (deregistered) return;
+		deregistered = true;
+		terminated = true;
+		liveOwners.delete(owner);
+		removeAbort();
+	};
+
+	const signalTree = (signal: NodeJS.Signals): void => {
+		const pid = child.pid;
+		if (pid === undefined) return;
+		if (pgid !== undefined) {
+			try {
+				// Negative pid signals the entire process group (child is leader).
+				process.kill(-pgid, signal);
+				return;
+			} catch {
+				// Group already gone; nothing to do.
+			}
+			return;
+		}
+		if (signal === "SIGKILL") {
+			try {
+				process.kill(pid, "SIGKILL");
+			} catch {
+				/* already gone */
+			}
+		} else {
+			// ptree's kill terminates the single process via the native handle.
+			child.kill();
+		}
+	};
+
+	const owner: OwnedProcess = {
+		child,
+		get pid() {
+			return child.pid;
+		},
+		get exited() {
+			return child.exited;
+		},
+		get disposed() {
+			return disposed;
+		},
+		async awaitExit({ timeoutMs }: { timeoutMs?: number } = {}): Promise<AwaitExitResult> {
+			const exitedResult = child.exited
+				.then(code => ({ exited: true as const, code: code as number | null }))
+				.catch(() => ({ exited: true as const, code: child.exitCode }));
+			if (timeoutMs === undefined) return exitedResult;
+			let timer: ReturnType<typeof setTimeout> | undefined;
+			const timeout = new Promise<AwaitExitResult>(resolve => {
+				timer = setTimeout(() => resolve({ exited: false, code: child.exitCode }), Math.max(0, timeoutMs));
+				timer.unref?.();
+			});
+			try {
+				return await Promise.race([exitedResult, timeout]);
+			} finally {
+				if (timer) clearTimeout(timer);
+			}
+		},
+		dispose(): Promise<void> {
+			// Already terminal (e.g. clean drain reconciled and deregistered):
+			// never re-probe the pgid; treat dispose as a settled no-op.
+			if (terminated) {
+				disposed = true;
+				if (!disposePromise) disposePromise = Promise.resolve();
+				return disposePromise;
+			}
+			if (disposePromise) return disposePromise;
+			disposed = true;
+			removeAbort();
+			disposePromise = (async () => {
+				try {
+					if (pgid !== undefined) {
+						// Group ownership: reap until the whole group is gone, even if
+						// the root has already exited (it may have backgrounded children).
+						if (!groupAlive(pgid)) return;
+						signalTree("SIGTERM");
+						if (await pollUntil(() => !groupAlive(pgid), gracefulMs)) return;
+						signalTree("SIGKILL");
+						if (!(await pollUntil(() => !groupAlive(pgid), SIGKILL_REAP_CAP_MS))) {
+							logger.warn("owned process group still alive after SIGKILL", {
+								name: opts.name,
+								pgid,
+							});
+						}
+						return;
+					}
+					// Single-process fallback (Windows / processGroup:false).
+					if (child.exitCode !== null) return;
+					signalTree("SIGTERM");
+					if ((await owner.awaitExit({ timeoutMs: gracefulMs })).exited) return;
+					signalTree("SIGKILL");
+					await owner.awaitExit({ timeoutMs: SIGKILL_REAP_CAP_MS });
+				} catch (err) {
+					logger.warn("owned process dispose failed", {
+						name: opts.name,
+						error: err instanceof Error ? err.message : String(err),
+					});
+				} finally {
+					// FIX: deregister only after teardown has completed so a postmortem
+					// firing mid-grace still sees the owner and awaits this dispose.
+					deregister();
+				}
+			})();
+			return disposePromise;
+		},
+	};
+
+	liveOwners.add(owner);
+
+	// When the root exits on its own (not via dispose), reconcile ownership by
+	// the *group*. After a short drain window: if the group is empty, deregister;
+	// if descendants are still alive, reap the owned group (no child outlives its
+	// owner). Either way the owner never lingers holding a stale pgid that the OS
+	// could later recycle and a stray dispose could mis-signal.
+	void child.exited
+		.catch(() => undefined)
+		.finally(() => {
+			if (disposed) return; // dispose() owns deregistration
+			if (pgid === undefined) {
+				deregister();
+				return;
+			}
+			void (async () => {
+				const drained = await pollUntil(() => !groupAlive(pgid), ROOT_EXIT_DRAIN_MS);
+				if (disposed) return;
+				if (drained) {
+					deregister();
+					return;
+				}
+				// Root exited but the owned group still has descendants: reap them.
+				// dispose() escalates SIGTERM->SIGKILL and deregisters in its finally.
+				await owner.dispose();
+			})();
+		});
+
+	if (opts.signal) {
+		if (opts.signal.aborted) {
+			void owner.dispose();
+		} else {
+			onAbort = () => void owner.dispose();
+			opts.signal.addEventListener("abort", onAbort, { once: true });
+		}
+	}
+
+	return owner;
+}
+
+/** Number of currently live owned processes. Exposed for leak assertions/tests. */
+export function liveOwnedProcessCount(): number {
+	return liveOwners.size;
+}
+
+/** Dispose every live owned process. For owner-scoped teardown and tests. */
+export async function disposeAllOwnedProcesses(): Promise<void> {
+	await Promise.all([...liveOwners].map(owner => owner.dispose().catch(() => undefined)));
+}
+
+// ── F1(b) generic resource owners ────────────────────────────────────────────
+
+type ResourceDisposer = () => void | Promise<void>;
+
+const resourceOwners = new Map<string, ResourceDisposer>();
+let resourcePostmortemRegistered = false;
+
+function ensureResourcePostmortem(): void {
+	if (resourcePostmortemRegistered) return;
+	resourcePostmortemRegistered = true;
+	// Postmortem isolates per-callback failures; swallow the aggregate here so
+	// shutdown continues, while direct callers of disposeAllResourceOwners still
+	// observe the AggregateError.
+	postmortem.register("runtime:resource-owners", () =>
+		disposeAllResourceOwners().catch(err => {
+			logger.warn("resource owner postmortem cleanup had failures", {
+				error: err instanceof Error ? err.message : String(err),
+			});
+		}),
+	);
+}
+
+/**
+ * Register a non-process resource for postmortem/fatal-exit cleanup.
+ *
+ * Idempotent by `name`: re-registering the same name replaces the prior
+ * disposer (last wins). Returns an unregister function that removes the owner
+ * only while it is still the active registration for that name.
+ */
+export function registerResourceOwner(name: string, disposer: ResourceDisposer): () => void {
+	resourceOwners.set(name, disposer);
+	ensureResourcePostmortem();
+	let unregistered = false;
+	return () => {
+		if (unregistered) return;
+		unregistered = true;
+		if (resourceOwners.get(name) === disposer) {
+			resourceOwners.delete(name);
+		}
+	};
+}
+
+/** Number of registered resource owners. Exposed for leak assertions/tests. */
+export function resourceOwnerCount(): number {
+	return resourceOwners.size;
+}
+
+/**
+ * Run and clear every registered resource disposer. Attempts all disposers even
+ * if some throw, then surfaces the failures as an `AggregateError` so callers
+ * can distinguish "all closed" from "a resource may still be alive".
+ */
+export async function disposeAllResourceOwners(): Promise<void> {
+	const disposers = [...resourceOwners.values()];
+	resourceOwners.clear();
+	const errors: unknown[] = [];
+	for (const disposer of disposers) {
+		try {
+			await disposer();
+		} catch (err) {
+			errors.push(err);
+		}
+	}
+	if (errors.length > 0) {
+		throw new AggregateError(errors, `${errors.length} resource disposer(s) failed during teardown`);
+	}
+}