pi-crew 0.11.11 → 0.11.13

package/src/runtime/child-pi/child-pi-steering.ts

@@ -16,6 +16,15 @@ import * as fs from "node:fs";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { killProcessTree } from "./child-pi-kill.ts";
 
+/** The wrap-up advisory delivered at the soft turn limit. Shared by BOTH
+ * transports so the wording stays single-sourced:
+ *   - json mode: appended to the steering JSONL file the child polls
+ *     (PI_CREW_STEERING_FILE) inside onTurnEnd below.
+ *   - rpc mode (U14): sent over the wire via RpcClient.steer() from
+ *     child-pi-rpc.ts, gated by isStreaming (an idle steer would QUEUE and
+ *     poison the NEXT run — PoC nuance 1, upgrade-spec 2026-10-09 U14). */
+export const STEER_WRAP_UP_MESSAGE = "You have reached your turn limit. Wrap up immediately — provide your final answer now.";
+
 /** Action emitted by the controller when a `turn_end` event is processed. */
 export type SteeringAction =
 	| { kind: "steer" }
@@ -65,14 +74,7 @@ export class ChildPiSteeringController {
 			// a failed write must NOT kill the worker.
 			if (steeringFile) {
 				try {
-					fs.appendFileSync(
-						steeringFile,
-						JSON.stringify({
-							type: "steer",
-							message: "You have reached your turn limit. Wrap up immediately — provide your final answer now.",
-						}) + "\n",
-						"utf-8",
-					);
+					fs.appendFileSync(steeringFile, JSON.stringify({ type: "steer", message: STEER_WRAP_UP_MESSAGE }) + "\n", "utf-8");
 				} catch (err) {
 					logInternalError("child-pi.steer-write-failed", err instanceof Error ? err : new Error(String(err)), `pid=${pid}`);
 				}

package/src/runtime/child-pi/child-pi-streams.ts

@@ -130,6 +130,28 @@ export function compactChildPiEvent(event: unknown): unknown | undefined {
 	return record.type ? { type: record.type } : undefined;
 }
 
+/**
+ * U14 (child-pi protocol v2): `true` when the event is the FINAL assistant
+ * event of a run — an assistant `message_end` with stopReason "stop" and no
+ * pending toolCall part. Shared by BOTH transports (the json stdout funnel in
+ * child-pi.ts and the rpc event subscription in child-pi-rpc.ts) so the
+ * final-drain arming condition cannot drift between modes.
+ *
+ * Extracted from child-pi.ts (U14) — pure motion, zero behavior change.
+ */
+export function isFinalAssistantEvent(event: unknown): boolean {
+	const obj = asRecord(event);
+	if (obj?.type !== "message_end") return false;
+	const message = asRecord(obj.message);
+	const role = message?.role;
+	if (role !== undefined && role !== "assistant") return false;
+	const stopReason =
+		typeof message?.stopReason === "string" ? message.stopReason : typeof obj.stopReason === "string" ? obj.stopReason : undefined;
+	if (stopReason !== undefined && stopReason !== "stop") return false;
+	const content = Array.isArray(message?.content) ? message.content : [];
+	return !content.some((part) => asRecord(part)?.type === "toolCall");
+}
+
 function displayTextFromCompactEvent(event: unknown): string | undefined {
 	const record = asRecord(event);
 	if (!record) return undefined;
@@ -297,27 +319,55 @@ export class ChildPiLineObserver {
 			parsed = undefined;
 		}
 		if (parsed !== undefined) {
-			const rawTexts = extractText(parsed);
-			if (rawTexts.length > 0) {
-				// F9: trim from the front if the push would exceed the cap. Slice's
-				// second arg excludes the index, so this drops the oldest entries
-				// while keeping the freshly pushed tail.
-				this.rawTextEvents.push(...rawTexts);
-				const rawOverflow = this.rawTextEvents.length - ChildPiLineObserver.MAX_RAW_TEXT_EVENTS;
-				if (rawOverflow > 0) this.rawTextEvents.splice(0, rawOverflow);
-				// Also capture raw assistant text as intermediate findings — the last raw
-				// text may be a partial answer before the worker ran out of budget.
-				const last = rawTexts[rawTexts.length - 1];
-				if (last.trim().length > 0) {
-					this.intermediateFindings.push(last.trim());
-					const findingsOverflow = this.intermediateFindings.length - ChildPiLineObserver.MAX_INTERMEDIATE_FINDINGS;
-					if (findingsOverflow > 0) this.intermediateFindings.splice(0, findingsOverflow);
-				}
+			this.processParsedEvent(parsed);
+		} else {
+			// OPT-PHASE2: construct the non-JSON fallback directly when parsing failed,
+			// so a broken line triggers exactly ONE (failed) parse instead of two.
+			this.dispatchCompact(nonJsonLineResult(line));
+		}
+	}
+
+	/**
+	 * U14 (child-pi protocol v2): feed an ALREADY-PARSED agent event through
+	 * the exact same pipeline as a parsed stdout JSON line — raw assistant-text
+	 * extraction, compaction, onJsonEvent dispatch, transcript append, and
+	 * display-line emission. The rpc transport (child-pi-rpc.ts) receives
+	 * parsed event objects from RpcClient.onEvent (the RpcClient owns the
+	 * stdout JSONL wire), so this is its entry into the observer. Non-object
+	 * values are dropped (parity with the non-JSON text fallback, which never
+	 * reaches this path).
+	 */
+	observeEvent(event: unknown): void {
+		if (event === null || typeof event !== "object") return;
+		this.processParsedEvent(event);
+	}
+
+	/** Shared post-parse pipeline for BOTH transports (text lines + rpc events). */
+	private processParsedEvent(parsed: unknown): void {
+		const rawTexts = extractText(parsed);
+		if (rawTexts.length > 0) {
+			// F9: trim from the front if the push would exceed the cap. Slice's
+			// second arg excludes the index, so this drops the oldest entries
+			// while keeping the freshly pushed tail.
+			this.rawTextEvents.push(...rawTexts);
+			const rawOverflow = this.rawTextEvents.length - ChildPiLineObserver.MAX_RAW_TEXT_EVENTS;
+			if (rawOverflow > 0) this.rawTextEvents.splice(0, rawOverflow);
+			// Also capture raw assistant text as intermediate findings — the last raw
+			// text may be a partial answer before the worker ran out of budget.
+			const last = rawTexts[rawTexts.length - 1];
+			if (last.trim().length > 0) {
+				this.intermediateFindings.push(last.trim());
+				const findingsOverflow = this.intermediateFindings.length - ChildPiLineObserver.MAX_INTERMEDIATE_FINDINGS;
+				if (findingsOverflow > 0) this.intermediateFindings.splice(0, findingsOverflow);
 			}
 		}
-		// OPT-PHASE2: construct the non-JSON fallback directly when parsing failed,
-		// so a broken line triggers exactly ONE (failed) parse instead of two.
-		const compact = parsed !== undefined ? compactChildPiLine(line, parsed) : nonJsonLineResult(line);
+		// (preParsed is always defined here — the line-based JSON.parse happened
+		// in emitLine; the rpc path never had a line at all.)
+		this.dispatchCompact(compactChildPiLine("", parsed));
+	}
+
+	/** Dispatch a compacted line/event to the consumer callbacks + transcript. */
+	private dispatchCompact(compact: { persistedLine: string; event?: unknown; displayLine?: string; json: boolean }): void {
 		if (compact.event !== undefined) {
 			try {
 				this.input.onJsonEvent?.(compact.event);

package/src/runtime/child-pi/child-pi.ts

@@ -3,7 +3,6 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentConfig } from "../../agents/agent-config.ts";
 import { loadConfig } from "../../config/config.ts";
-import { getCrewEnv } from "../../config/env-vars.ts";
 import type { PiTeamsConfig } from "../../config/types.ts";
 import { registerChildProcess, unregisterChildProcess } from "../../extension/crew-cleanup.ts";
 import type { WorkerExitStatus } from "../../state/types.ts";
@@ -18,12 +17,23 @@ import { classifyOnExit, getSurfaceRuntimeController, makeTerminalEventProbe } f
 import type { SurfaceGateEnvSnapshot } from "../surface/resolve-surface.ts";
 import type { SurfaceProvider } from "../surface/surface-provider.ts";
 import { prepareSurfaceSpawn, type SurfaceExitInfo, type SurfaceSpawnOutcome, waitForSurfaceExit } from "../surface/surface-spawn.ts";
-import { FINAL_DRAIN_MS, HARD_KILL_MS, POST_EXIT_STDIO_GUARD_MS, RESPONSE_TIMEOUT_MS } from "./child-pi-constants.ts";
+import {
+	FINAL_DRAIN_MS,
+	HARD_KILL_MS,
+	POST_EXIT_STDIO_GUARD_MS,
+	RESPONSE_TIMEOUT_MS,
+	resolveResponseTimeoutMs,
+} from "./child-pi-constants.ts";
 import { clearHardKillTimer, killProcessTree, registerActiveChild, unregisterActiveChild } from "./child-pi-kill.ts";
+// U14 (child-pi protocol v2): the rpc transport branch — opt-in via
+// PI_CREW_CHILD_PI_MODE=rpc; json stays the default transport (phase 1).
+import { resolveChildPiRpcMode, tryChildPiRpcRun } from "./child-pi-rpc.ts";
 import { buildFinalChildPiSpawnOptions, prepareSpawnContext } from "./child-pi-spawn.ts";
 import { ChildPiSteeringController } from "./child-pi-steering.ts";
 // Internal helpers for active-child bookkeeping (extracted to child-pi-kill.ts).
-import { ChildPiLineObserver } from "./child-pi-streams.ts";
+// U14: isFinalAssistantEvent moved to child-pi-streams.ts (shared by BOTH
+// transports) and is re-exported below to keep the module surface stable.
+import { ChildPiLineObserver, isFinalAssistantEvent } from "./child-pi-streams.ts";
 // Phase 2.3: the six timer constructs moved to child-pi-timers.ts (pure motion).
 import { createChildPiTimers } from "./child-pi-timers.ts";
 import { runMockChildPi } from "./mock-fixtures.ts";
@@ -51,7 +61,7 @@ export {
 // owns the canary + filter + spread sequence; lives in child-pi-spawn.ts.
 export { buildChildPiSpawnOptions, buildFinalChildPiSpawnOptions } from "./child-pi-spawn.ts";
 // ── Re-export from child-pi-streams.ts (H-7 decomposition step 4) ──
-export { ChildPiLineObserver } from "./child-pi-streams.ts";
+export { ChildPiLineObserver, isFinalAssistantEvent } from "./child-pi-streams.ts";
 
 import { checkCrewDepth, cleanupTempDir, resolveHermeticWorkers } from "../model/pi-args.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "../process/post-exit-stdio-guard.ts";
@@ -399,19 +409,6 @@ function asRecord(value: unknown): Record<string, unknown> | undefined {
 	return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
 }
 
-function isFinalAssistantEvent(event: unknown): boolean {
-	const obj = asRecord(event);
-	if (obj?.type !== "message_end") return false;
-	const message = asRecord(obj.message);
-	const role = message?.role;
-	if (role !== undefined && role !== "assistant") return false;
-	const stopReason =
-		typeof message?.stopReason === "string" ? message.stopReason : typeof obj.stopReason === "string" ? obj.stopReason : undefined;
-	if (stopReason !== undefined && stopReason !== "stop") return false;
-	const content = Array.isArray(message?.content) ? message.content : [];
-	return !content.some((part) => asRecord(part)?.type === "toolCall");
-}
-
 /**
  * Discover the project crew config for the surface gate. The discovered config
  * DEFAULTS surface off (`visibleAgents: []`) — headless unless explicitly opted
@@ -789,6 +786,17 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 	// awaited) or null → fall through to the classic headless spawn below.
 	const surfaceResult = await trySurfaceBranch(input, depthEnv, builtArgs, mergedEnv, builtEnv, tempDir);
 	if (surfaceResult) return surfaceResult;
+	// U14 (child-pi protocol v2 — upgrade-spec 2026-10-09): `--mode rpc`
+	// transport, opt-in via PI_CREW_CHILD_PI_MODE=rpc (json remains the
+	// phase-1 default — the flag is the BOTH-directions regression lever).
+	// Returns null when rpc cannot run here (no absolute cli script) so the
+	// json branch below stays the fail-safe path. Surface TUI panes are
+	// unaffected — trySurfaceBranch consumed builtArgs above and never
+	// reaches this point in surface mode.
+	if (resolveChildPiRpcMode()) {
+		const rpcResult = await tryChildPiRpcRun({ input, effectiveTask, ctx: spawnPrep.ctx, workerSession, sessionRecoveryEnabled });
+		if (rpcResult) return rpcResult;
+	}
 	try {
 		return await new Promise<ChildPiRunResult>((resolve) => {
 			// Compose the final SpawnOptions: canary + filter + spread are now
@@ -841,19 +849,10 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			let finalDrainFiredMonotonicMs: number | undefined;
 			const spawnMonotonicMs = performance.now();
 			let finalAssistantEventMonotonicMs: number | undefined;
-			// FIX (Round 14): Bound the env-controlled response timeout to
-			// [1_000ms, 3_600_000ms] (1s–1h) so a hostile or accidental value
-			// (e.g. 1, or 999_999_999) cannot disable the timeout or cause
-			// instant kills. Out-of-range values fall back to the input or
-			// built-in default.
-			const RESPONSE_TIMEOUT_MIN_MS = 1_000;
-			const RESPONSE_TIMEOUT_MAX_MS = 3_600_000;
-			const responseTimeoutEnv = Number.parseInt(getCrewEnv("PI_TEAMS_CHILD_RESPONSE_TIMEOUT_MS") ?? "", 10);
-			const envInRange =
-				Number.isFinite(responseTimeoutEnv) &&
-				responseTimeoutEnv >= RESPONSE_TIMEOUT_MIN_MS &&
-				responseTimeoutEnv <= RESPONSE_TIMEOUT_MAX_MS;
-			const responseTimeoutMs = envInRange ? responseTimeoutEnv : (input.responseTimeoutMs ?? RESPONSE_TIMEOUT_MS);
+			// FIX (Round 14) — the env-override bounds live in
+			// resolveResponseTimeoutMs (child-pi-constants.ts, U14: shared with the
+			// rpc transport so watchdog budgets cannot drift between modes).
+			const responseTimeoutMs = resolveResponseTimeoutMs(input);
 			let responseTimeoutHit = false;
 			let forcedFinalDrain = false;
 			let abortRequested = input.signal?.aborted === true;

package/src/runtime/child-pi/owned-process.ts

@@ -0,0 +1,434 @@
+/**
+ * owned-process.ts — U15: OwnedProcess pattern, Node 22 port.
+ *
+ * Ported from gajae-code `packages/coding-agent/src/runtime/process-lifecycle.ts`
+ * (fork pi-mono v0.8.2) per spec U15 of pi-crew-upgrade-spec-2026-10-09.md:
+ * the Bun `ptree.spawn` core is re-expressed with `node:child_process.spawn`
+ * `{detached:true}` — pi-crew's child-pi spawns already use detached+setsid
+ * (child-pi-spawn.ts), they were only missing the group-kill discipline:
+ *
+ *   - Process-group ownership: a detached child is its own group leader, so
+ *     `process.kill(-pgid, sig)` signals the WHOLE descendant tree — including
+ *     `sh -c "worker &"` backgrounded descendants, pi-crew's real zombie
+ *     vector (proof-of-pattern round 9: root SIGKILL left 2 children
+ *     reparented to ppid=1 while the group stayed signalable).
+ *   - Escalating dispose with hard cap: SIGTERM group → poll gracefulMs (2s)
+ *     → SIGKILL → poll cap (2s) → warn + give up. A wedged child can never
+ *     block shutdown forever.
+ *   - Root-exit drain-reconcile (250ms): when the root exits on its own but
+ *     the group still has live members, the owner reaps the group — no child
+ *     outlives its owner.
+ *   - PID-recycle guard: once terminal, dispose() is a settled no-op and
+ *     never re-probes a pgid the OS may have recycled into an unrelated group.
+ *   - Idempotent/concurrent dispose share ONE in-flight promise; bounded
+ *     `awaitExit` never rejects.
+ *   - Postmortem registry (postmortem-registry.ts) reaps every still-live
+ *     owned group on exit/SIGINT/SIGTERM/SIGHUP/uncaught/unhandled; owners
+ *     deregister only AFTER teardown completed.
+ *
+ * GOTCHA (round 9, MUST keep): do NOT `unref()` the root child handle. The
+ * root-exit drain-reconcile needs the 'exit' event delivered; unref'ing the
+ * handle starves exit-event delivery when the rest of the loop is idle and
+ * the reconcile silently never runs. Internal poll/delay timers unref
+ * THEMSELVES (they must not pin the loop), but the child handle stays ref'd.
+ *
+ * Known limit (spec, grep-verified in the fork): no parent-death detection —
+ * if THIS owner process is SIGKILLed, no postmortem runs. That case is owned
+ * by the complementary child-side PI_CREW_PARENT_PID guard (zombie-scanner +
+ * background-runner parent-guard), which stays in place untouched.
+ *
+ * rpc-socket-security.ts is explicitly NOT ported (spec: defer until an UDS
+ * transport exists — see U14/U15 lane notes).
+ */
+
+import { type ChildProcess, spawn } from "node:child_process";
+import * as fs from "node:fs";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { registerPostmortemCleanup } from "./postmortem-registry.ts";
+
+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 children drain immediately; a
+// root that backgrounded descendants keeps the owner registered past this
+// window and the group is then reaped by dispose().
+const ROOT_EXIT_DRAIN_MS = 250;
+const POLL_INTERVAL_MS = 20;
+
+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 true or `timeoutMs` elapses. Returns the final value. */
+async function pollUntil(predicate: () => boolean, timeoutMs: number, intervalMs = POLL_INTERVAL_MS): 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";
+	}
+}
+
+/**
+ * Read the process-group id of `pid` from /proc (Linux). Returns undefined
+ * when /proc is unavailable (non-Linux) or the stat line is unparseable.
+ * Authoritative group-leadership check on Linux.
+ */
+function readPgidFromProc(pid: number): number | undefined {
+	try {
+		const stat = fs.readFileSync(`/proc/${pid}/stat`, "utf8");
+		// Layout: pid (comm) state ppid pgrp session ... — comm may contain
+		// spaces and parens, so fields are counted AFTER the last ')'.
+		const close = stat.lastIndexOf(")");
+		if (close === -1) return undefined;
+		const fields = stat
+			.slice(close + 2)
+			.trim()
+			.split(/\s+/);
+		const pgrp = Number(fields[2]);
+		return Number.isInteger(pgrp) && pgrp > 0 ? pgrp : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Options shared by {@link spawnOwnedProcess} and {@link adoptOwnedProcess}. */
+export interface OwnedProcessOptions {
+	/** Grace period (ms) between SIGTERM and SIGKILL on dispose. Default 2000. */
+	gracefulMs?: number;
+	/** Label used in diagnostics. */
+	name?: string;
+	/**
+	 * When aborted, the owned process tree is disposed (escalating kill).
+	 * The listener is removed on settle so long-lived signals never leak.
+	 */
+	signal?: AbortSignal;
+}
+
+export interface SpawnOwnedOptions extends OwnedProcessOptions {
+	cwd?: string;
+	env?: NodeJS.ProcessEnv;
+	/**
+	 * 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;
+}
+
+/** 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 child process owned by the runtime with guaranteed group teardown. */
+export interface OwnedProcess {
+	readonly child: ChildProcess;
+	readonly pid: number | undefined;
+	/** Process-group id when the child leads its own group, else undefined. */
+	readonly pgid: number | undefined;
+	/** Resolves with the exit code when the root child exits. Never rejects. */
+	readonly exited: Promise<number | null>;
+	/** `true` once dispose() has started. */
+	readonly disposed: boolean;
+	/**
+	 * `true` once teardown/reconciliation confirmed the tree is gone. A late
+	 * dispose() is then a settled no-op (PID-recycle guard).
+	 */
+	readonly terminated: boolean;
+	/**
+	 * Wait for the root child to exit, optionally bounded by `timeoutMs`.
+	 * 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;
+	registerPostmortemCleanup("child-pi:owned-processes", () => disposeAllOwnedProcesses());
+}
+
+/** Create the OwnedProcess wrapper around a spawned (or adoptable) child. */
+function createOwnedProcess(child: ChildProcess, pgid: number | undefined, opts: OwnedProcessOptions): OwnedProcess {
+	const gracefulMs = opts.gracefulMs ?? DEFAULT_GRACEFUL_MS;
+
+	ensureOwnedPostmortem();
+
+	// exited: resolves exactly once with the exit code (null on spawn error or
+	// signal death without a code). Never rejects — reconcile relies on that.
+	let exitSettled = false;
+	let resolveExit!: (code: number | null) => void;
+	const exited = new Promise<number | null>((resolve) => {
+		resolveExit = resolve;
+	});
+	const settleExit = (code: number | null): void => {
+		if (exitSettled) return;
+		exitSettled = true;
+		resolveExit(code);
+	};
+	if (child.exitCode !== null || child.signalCode !== null) {
+		// Already exited before adoption/creation (signal death leaves exitCode
+		// null with signalCode set) — settle immediately, the events are gone.
+		settleExit(child.exitCode);
+	} else {
+		child.once("exit", (code) => settleExit(code));
+		// Spawn failures ('error', pid undefined) must not leave a hanging
+		// promise — resolve null so drain-reconcile can deregister.
+		child.once("error", () => settleExit(null));
+	}
+
+	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);
+			} catch {
+				// Group already gone; nothing to do.
+			}
+			return;
+		}
+		// Single-process fallback (Windows / non-group child, e.g. the U14 rpc
+		// branch which spawns without detached). child.kill() is best-effort;
+		// fall through to process.kill() when it reports no delivery.
+		if (signal === "SIGKILL" || !child.kill(signal)) {
+			try {
+				process.kill(pid, signal);
+			} catch {
+				/* already gone */
+			}
+		}
+	};
+
+	const owner: OwnedProcess = {
+		child,
+		get pid() {
+			return child.pid;
+		},
+		get pgid() {
+			return pgid;
+		},
+		get exited() {
+			return exited;
+		},
+		get disposed() {
+			return disposed;
+		},
+		get terminated() {
+			return terminated;
+		},
+		async awaitExit({ timeoutMs }: { timeoutMs?: number } = {}): Promise<AwaitExitResult> {
+			const exitedResult = exited.then((code) => ({ exited: true as const, code }));
+			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))) {
+							logInternalError(
+								"child-pi.owned-sigkill-cap",
+								new Error(`owned process group still alive after SIGKILL cap (${SIGKILL_REAP_CAP_MS}ms); giving up`),
+								`name=${opts.name} pgid=${pgid}`,
+								"warn",
+							);
+						}
+						return;
+					}
+					// Single-process fallback (Windows / processGroup:false / rpc child).
+					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) {
+					logInternalError(
+						"child-pi.owned-dispose-failed",
+						err instanceof Error ? err : new Error(String(err)),
+						`name=${opts.name}`,
+					);
+				} finally {
+					// Deregister only AFTER teardown completed so a postmortem firing
+					// mid-grace still sees the owner and awaits this in-flight 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 exited.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;
+}
+
+/**
+ * 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. POSIX: spawned `detached:true` so the child is its own
+ * session+group leader (pgid === pid).
+ */
+export function spawnOwnedProcess(command: string, args: string[], opts: SpawnOwnedOptions = {}): OwnedProcess {
+	const useGroup = (opts.processGroup ?? true) && isPosix;
+	const child = spawn(command, args, {
+		cwd: opts.cwd,
+		env: opts.env,
+		stdio: "ignore",
+		detached: useGroup,
+	});
+	// Round-9 gotcha: do NOT child.unref() — the root handle must stay ref'd
+	// or the exit event starves when the rest of the loop is idle, killing the
+	// drain-reconcile above. Callers that want fire-and-forget semantics get
+	// them from the postmortem registry instead.
+	return createOwnedProcess(child, useGroup ? child.pid : undefined, opts);
+}
+
+/**
+ * Adopt an ALREADY-spawned child into the owned-process registry. Group
+ * leadership is resolved conservatively:
+ *   - Linux: read the child's real pgrp from /proc — authoritative (covers
+ *     the U14 rpc branch, whose RpcClient spawns WITHOUT detached: pgrp ≠ pid
+ *     ⇒ single-process fallback, exactly the deferred behavior noted there).
+ *   - Other POSIX: a live group with id === child.pid implies the child leads
+ *     it (same pid-recycle exposure as the legacy killProcessPid group path).
+ *   - Windows: no process groups ⇒ single-process fallback.
+ */
+export function adoptOwnedProcess(child: ChildProcess, opts: OwnedProcessOptions = {}): OwnedProcess {
+	let pgid: number | undefined;
+	if (isPosix && child.pid !== undefined) {
+		const pgrp = readPgidFromProc(child.pid);
+		if (pgrp !== undefined) {
+			pgid = pgrp === child.pid ? child.pid : undefined;
+		} else if (groupAlive(child.pid)) {
+			pgid = child.pid;
+		}
+	}
+	return createOwnedProcess(child, pgid, opts);
+}
+
+/** Number of currently live owned processes. Exposed for leak assertions/tests. */
+export function liveOwnedProcessCount(): number {
+	return liveOwners.size;
+}
+
+/** Dispose every live owned process (owner-scoped teardown, postmortem, tests). */
+export async function disposeAllOwnedProcesses(): Promise<void> {
+	await Promise.allSettled([...liveOwners].map((owner) => owner.dispose()));
+}