@tangle-network/sdk-cli-runner 0.0.0-stage → 0.3.0

package/dist/index.mjs

@@ -0,0 +1,2275 @@
+import { spawn } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, constants, fstatSync, fsyncSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { open } from "node:fs/promises";
+//#region src/attachment-error.ts
+/** An attachment cannot be delivered to a native CLI. */
+var InvalidAttachmentError = class extends Error {
+	code = "invalid_attachment";
+	statusCode = 400;
+	constructor(message) {
+		super(message);
+		this.name = "InvalidAttachmentError";
+	}
+};
+//#endregion
+//#region src/spawn-env.ts
+/**
+* Merge adapter environment overrides onto a base environment for `spawn`.
+*
+* An adapter scrubs an inherited variable by setting it to `undefined` (the
+* claude-code and codex adapters strip a router key under OAuth so the CLI
+* keeps its stored tokens). A plain spread keeps such a key in the object,
+* and what the child then sees depends on the spawner. Deleting the key makes
+* the scrub unconditional.
+*/
+function mergeSpawnEnv(base, overrides) {
+	const merged = { ...base };
+	if (!overrides) return merged;
+	for (const [key, value] of Object.entries(overrides)) if (value === void 0) delete merged[key];
+	else merged[key] = value;
+	return merged;
+}
+//#endregion
+//#region src/child-env.ts
+const DEFAULT_CHILD_PATH = "/usr/local/bin:/usr/bin:/bin";
+function resolveSandboxToolBinDirs(env) {
+	const value = env.SANDBOX_TOOL_BIN_DIRS?.trim();
+	if (!value) return [];
+	const segments = value.split(":");
+	for (const segment of segments) if (!segment || !isAbsolute(segment)) throw new Error(`SANDBOX_TOOL_BIN_DIRS must be a colon-separated list of absolute paths with no empty segments, got: ${value}`);
+	return segments;
+}
+/**
+* Make bare harness command names (`claude`, `codex`, `kimi`) resolve the way
+* every spawned CLI expects, and let the CLI's own children inherit the same
+* resolution. Thin sandbox images deliver toolchain binaries through a
+* read-only Nix profile exposed as NIX_BIN_PATH, deliberately NOT on the
+* container's PATH (PATH-wide scans slow sidecar startup), so it is prepended
+* here; SANDBOX_TOOL_BIN_DIRS is appended. Both spawn paths call this: the
+* exec runner and the JSON-RPC bridge (rpc-stdio-process.ts), whose app-server spawn
+* skipped it and died with ENOENT on a thin image (GTM's codex synthetic
+* customer, 40/40 turns).
+*/
+function applyChildToolPath(processEnv) {
+	const nixBinPath = processEnv.NIX_BIN_PATH?.trim();
+	if (nixBinPath) addPathEntries(processEnv, nixBinPath.split(":"), "prepend");
+	addPathEntries(processEnv, resolveSandboxToolBinDirs(processEnv), "append");
+}
+/** Add the entries PATH lacks, each once, before or after the current PATH. */
+function addPathEntries(processEnv, entries, position) {
+	const currentPath = processEnv.PATH ?? DEFAULT_CHILD_PATH;
+	const seen = new Set(currentPath.split(":"));
+	const added = entries.filter((entry) => {
+		if (!entry || seen.has(entry)) return false;
+		seen.add(entry);
+		return true;
+	});
+	if (added.length === 0) return;
+	processEnv.PATH = position === "prepend" ? `${added.join(":")}:${currentPath}` : `${currentPath}:${added.join(":")}`;
+}
+/**
+* The environment a spawned CLI runs with: the parent's (unless
+* `inheritEnv: false`) merged with the adapter's overrides, a PWD that agrees
+* with the working directory, and the sandbox tool path.
+*/
+function buildChildEnv(config) {
+	const { cwd, env, inheritEnv, spawnOptions } = config;
+	const processEnv = mergeSpawnEnv(inheritEnv === false ? {} : process.env, env);
+	const spawnCwd = spawnOptions && "cwd" in spawnOptions ? spawnOptions.cwd : cwd;
+	const childCwd = typeof spawnCwd === "string" ? spawnCwd : spawnCwd instanceof URL && spawnCwd.protocol === "file:" ? fileURLToPath(spawnCwd) : void 0;
+	if (!(!!env && "PWD" in env && env.PWD === void 0) && childCwd !== void 0 && childCwd.length > 0) processEnv.PWD = resolve(childCwd);
+	applyChildToolPath(processEnv);
+	return processEnv;
+}
+//#endregion
+//#region src/child-killer.ts
+const SIGKILL_ESCALATION_MS = 1e3;
+/**
+* Signals a spawned CLI, its whole process group when it leads one. A
+* consumer launch's `terminate` also runs, once, on the first kill: it owns
+* what the local child cannot signal (a container, a scope).
+*/
+var ChildKiller = class {
+	escalationTimer;
+	termination;
+	constructor(child, detached, terminate) {
+		this.child = child;
+		this.detached = detached;
+		this.terminate = terminate;
+	}
+	kill(killSignal) {
+		if (this.terminate && !this.termination) this.termination = this.terminate().then(() => void 0, (error) => error instanceof Error ? error.message : String(error));
+		if (this.detached && this.child.pid && process.platform !== "win32") try {
+			process.kill(-this.child.pid, killSignal);
+			return true;
+		} catch {}
+		return this.child.kill(killSignal);
+	}
+	/** The launch's termination failure, once it settles; undefined when none ran or it succeeded. */
+	terminated() {
+		return this.termination ?? Promise.resolve(void 0);
+	}
+	get escalating() {
+		return this.escalationTimer !== void 0;
+	}
+	/** SIGKILL after a grace period unless `stillRunning` says the child left. */
+	escalate(stillRunning) {
+		this.escalationTimer = setTimeout(() => {
+			if (stillRunning()) this.kill("SIGKILL");
+		}, SIGKILL_ESCALATION_MS);
+		this.escalationTimer.unref();
+	}
+	clearEscalation() {
+		if (this.escalationTimer) clearTimeout(this.escalationTimer);
+	}
+};
+//#endregion
+//#region src/cli-deadlines.ts
+/**
+* The optional fixed wall-clock bound of one CLI process. Callers that bound a
+* turn by its abort signal leave `timeoutMs` unset and arm nothing here.
+*/
+var CliDeadlines = class {
+	timedOut = false;
+	timeoutReason;
+	timeoutDiagnostic;
+	fixedTimerId;
+	constructor(config, child, killer, spawnedAt) {
+		this.config = config;
+		this.child = child;
+		this.killer = killer;
+		this.spawnedAt = spawnedAt;
+	}
+	arm() {
+		const { timeoutMs } = this.config;
+		if (!(timeoutMs && timeoutMs > 0)) return;
+		this.fixedTimerId = setTimeout(() => this.killOnTimeout(timeoutMs), timeoutMs);
+	}
+	clearAll() {
+		if (this.fixedTimerId) clearTimeout(this.fixedTimerId);
+		this.killer.clearEscalation();
+	}
+	killOnTimeout(budgetMs) {
+		if (this.timedOut) return;
+		this.timedOut = true;
+		this.timeoutReason = "fixed";
+		this.timeoutDiagnostic = `"${this.config.command}" ran past its deadline of ${budgetMs}ms; killed after ${Date.now() - this.spawnedAt}ms`;
+		this.killer.kill("SIGTERM");
+		this.killer.escalate(() => this.child.exitCode === null);
+	}
+};
+//#endregion
+//#region src/raw-capture.ts
+/** Hard encoded-byte bound across canonical JSON spool files, including live writers.
+* Temporary trim copies and filesystem allocation are separate from this budget.
+*/
+const RAW_CAPTURE_TOTAL_CAP_BYTES = 64 * 1024 * 1024;
+const RAW_CAPTURE_FRAME_BYTES = 64 * 1024;
+const RAW_CAPTURE_TAIL_BYTES = 32 * 1024;
+const RAW_ROOT = "/root/.sidecar/raw-evidence";
+/** The root-private spool: one `<sha256(HOME)>/process-io.frames` per runtime HOME. */
+const RAW_CAPTURE_ROOT = RAW_ROOT;
+const CAPTURE_FLAGS = constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW;
+const REGISTRY_KEY = Symbol.for("tangle.sdk-cli-runner.raw-capture-writers");
+const shared = globalThis;
+const registry = shared[REGISTRY_KEY] ?? {
+	liveWriters: /* @__PURE__ */ new Map(),
+	generations: /* @__PURE__ */ new Map(),
+	losses: /* @__PURE__ */ new Map(),
+	trims: /* @__PURE__ */ new Map()
+};
+shared[REGISTRY_KEY] = registry;
+const { liveWriters, generations } = registry;
+registry.losses ??= /* @__PURE__ */ new Map();
+const losses = registry.losses;
+registry.trims ??= /* @__PURE__ */ new Map();
+const trims = registry.trims;
+registry.retained ??= /* @__PURE__ */ new Set();
+const retainedCaptures = registry.retained;
+const activeAttempt = new AsyncLocalStorage();
+/** Bind Sidecar-owned attempt identity before entering a provider adapter. */
+function withRawCaptureAttempt(attempt, run) {
+	if (!attempt.executionId || !Number.isSafeInteger(attempt.ordinal) || attempt.ordinal < 1 || !attempt.providerSessionId) throw new Error("Invalid raw capture attempt identity");
+	return activeAttempt.run(attempt, run);
+}
+/** The sidecar owns this directory; the CLI's writable HOME cannot contain its evidence. */
+function resolveRawCapturePath(runtimeHome) {
+	if (!isAbsolute(runtimeHome)) throw new Error("runtimeHome must be absolute for raw capture");
+	return join(RAW_ROOT, createHash("sha256").update(resolve(runtimeHome)).digest("hex"), "process-io.frames");
+}
+function assertProtectedCaptureDirectory(directory) {
+	if (process.getuid?.() !== 0) throw new Error("sidecar raw capture requires root ownership");
+	for (const part of [
+		"/root",
+		"/root/.sidecar",
+		RAW_ROOT,
+		directory
+	]) {
+		const entry = lstatSync(part);
+		if (!entry.isDirectory() || entry.isSymbolicLink() || entry.uid !== 0 || (entry.mode & 63) !== 0 || realpathSync(part) !== part) throw new Error(`raw capture parent is not protected: ${part}`);
+	}
+}
+/**
+* Opt one runtime HOME in to full capture, inside the shared byte budget, when
+* the platform default is off. The Sidecar calls this for a session created with retention
+* "workspace", whose retained evidence must include process I/O. An explicit
+* SIDECAR_RAW_CAPTURE_MODE=none or PHI redaction still disables it.
+*/
+function allowRetainedRawCapture(runtimeHome) {
+	retainedCaptures.add(resolve(resolveRawCapturePath(runtimeHome)));
+}
+/** Delete a session's private spool only after its evidence has been archived. */
+function removeRawCapture(runtimeHome) {
+	retainedCaptures.delete(resolve(resolveRawCapturePath(runtimeHome)));
+	const directory = dirname(resolveRawCapturePath(runtimeHome));
+	try {
+		assertProtectedCaptureDirectory(directory);
+	} catch (error) {
+		if (error.code === "ENOENT") return;
+		throw error;
+	}
+	rmSync(directory, {
+		recursive: true,
+		force: true
+	});
+	pruneClosedEmptyCapture(join(directory, "process-io.frames"));
+}
+function captureCapacityError(cause) {
+	return ["ENOSPC", "EDQUOT"].includes(cause.code ?? "");
+}
+/**
+* Retained evidence must be complete: a tail that drops bytes reports the
+* capture incomplete, so a retained session gets full capture, inside the
+* shared byte budget, unless the operator pinned the platform to tail.
+*/
+function resolveRawCaptureMode(file, protectedPath, requested) {
+	const trustedMode = process.env.SIDECAR_RAW_CAPTURE_MODE;
+	const retained = retainedCaptures.has(resolve(file));
+	return protectedPath ? trustedMode === "none" || process.env.TELEMETRY_REDACT === "phi" || requested === "none" ? "none" : (trustedMode === "full" || trustedMode !== "tail" && retained) && requested !== "tail" ? "full" : trustedMode === "tail" || trustedMode === "full" || retained ? "tail" : "none" : requested ?? "full";
+}
+function openCaptureTarget(path, protectedPath) {
+	const opened = openSync(path, CAPTURE_FLAGS, 384);
+	const target = fstatSync(opened);
+	if (!target.isFile() || target.nlink !== 1 || (target.mode & 63) !== 0 || protectedPath && target.uid !== 0) {
+		closeSync(opened);
+		throw new Error("raw capture target must be a private regular file");
+	}
+	return opened;
+}
+function markCaptureIncomplete(state, record) {
+	state.captureIncomplete = true;
+	const terminal = record.terminal;
+	if (typeof terminal === "object" && terminal !== null) {
+		const result = terminal;
+		result.captureError ??= "diagnostic_capture_truncated";
+	}
+}
+/**
+* Reopen the path when a trim replaced the file. Returns false when the
+* reopen hit a full filesystem and the capture has failed.
+*/
+function reopenReplacedCapture(state, record) {
+	const current = generations.get(state.path) ?? 0;
+	if (current === state.generation) return true;
+	closeSync(state.fd);
+	state.fd = -1;
+	try {
+		state.fd = openCaptureTarget(state.path, state.protectedPath);
+	} catch (error) {
+		if (!captureCapacityError(error)) throw error;
+		state.captureFailed = true;
+		return false;
+	}
+	state.generation = current;
+	const currentLoss = losses.get(state.path) ?? 0;
+	if (state.loss !== currentLoss) {
+		state.loss = currentLoss;
+		state.sequence = 0;
+		markCaptureIncomplete(state, record);
+		Object.assign(record, { captureDropped: true });
+	}
+	return true;
+}
+function encodeCaptureFrame(metadata, payload, attempt) {
+	const frame = { ...metadata };
+	for (const key of [
+		"executionId",
+		"ordinal",
+		"providerSessionId"
+	]) delete frame[key];
+	return Buffer.from(`${JSON.stringify({
+		...frame,
+		...payload ? { base64Bytes: payload.toString("base64") } : {},
+		...attempt ? {
+			executionId: attempt.executionId,
+			ordinal: attempt.ordinal,
+			providerSessionId: attempt.providerSessionId
+		} : {}
+	})}\n`);
+}
+function writeCaptureLine(state, record, metadata, payload) {
+	let line = encodeCaptureFrame(metadata, payload, state.attempt);
+	let recordStart;
+	try {
+		if (state.protectedPath) {
+			if (reserveCaptureBytes(state.captureRoot, state.path, line.length)) {
+				state.generation = generations.get(state.path) ?? 0;
+				state.loss = losses.get(state.path) ?? 0;
+				state.sequence = 1;
+				metadata.sequence = 0;
+				markCaptureIncomplete(state, record);
+				Object.assign(metadata, { captureDropped: true });
+				line = encodeCaptureFrame(metadata, payload, state.attempt);
+			}
+		}
+		recordStart = fstatSync(state.fd).size;
+		for (let offset = 0; offset < line.length;) {
+			const written = writeSync(state.fd, line, offset, line.length - offset);
+			if (written <= 0) throw new Error("raw capture write made no progress");
+			offset += written;
+		}
+	} catch (error) {
+		if (!captureCapacityError(error)) throw error;
+		if (recordStart !== void 0) try {
+			ftruncateSync(state.fd, recordStart);
+		} catch {
+			process.emitWarning("Raw capture rollback failed; diagnostic capture is incomplete.", { code: "RAW_CAPTURE_ROLLBACK_FAILED" });
+		}
+		state.captureFailed = true;
+	}
+}
+function appendCaptureRecord(state, record, payload) {
+	if (state.closed) throw new Error("raw capture is closed");
+	if (state.captureFailed) return;
+	if (!reopenReplacedCapture(state, record)) return;
+	const attempt = state.attempt;
+	writeCaptureLine(state, record, {
+		processId: state.processId,
+		sequence: state.sequence++,
+		at: (/* @__PURE__ */ new Date()).toISOString(),
+		...record,
+		...attempt ? {
+			executionId: attempt.executionId,
+			ordinal: attempt.ordinal,
+			providerSessionId: attempt.providerSessionId
+		} : {}
+	}, payload);
+}
+function frameCapture(state, mode, stream, bytes, metadata) {
+	if (mode === "tail") {
+		const previous = state.tails.get(stream);
+		state.tails.set(stream, {
+			bytes: Buffer.concat([previous?.bytes ?? Buffer.alloc(0), bytes.subarray(-RAW_CAPTURE_TAIL_BYTES)]).subarray(-RAW_CAPTURE_TAIL_BYTES),
+			total: (previous?.total ?? 0) + bytes.length,
+			...metadata ? { metadata } : {}
+		});
+		return;
+	}
+	for (let offset = 0; offset < bytes.length || bytes.length === 0 && offset === 0; offset += RAW_CAPTURE_FRAME_BYTES) {
+		const payload = bytes.subarray(offset, offset + RAW_CAPTURE_FRAME_BYTES);
+		appendCaptureRecord(state, {
+			stream,
+			sha256: createHash("sha256").update(payload).digest("hex"),
+			sizeBytes: payload.length,
+			...metadata ? { metadata } : {}
+		}, payload);
+		if (!bytes.length) break;
+	}
+}
+function closeCapture(state, result) {
+	if (state.closed) return;
+	try {
+		for (const [stream, tail] of state.tails) {
+			if (tail.total > tail.bytes.length) state.captureIncomplete = true;
+			appendCaptureRecord(state, {
+				stream,
+				sizeBytes: tail.bytes.length,
+				sha256: createHash("sha256").update(tail.bytes).digest("hex"),
+				omittedBytes: tail.total - tail.bytes.length,
+				captureMode: "tail",
+				...tail.metadata ? { metadata: tail.metadata } : {}
+			}, tail.bytes);
+		}
+		state.tails.clear();
+		appendCaptureRecord(state, { terminal: {
+			code: null,
+			signal: null,
+			timedOut: false,
+			timeoutReason: null,
+			captureError: null,
+			...result,
+			...state.captureIncomplete ? { captureError: result.captureError ?? "diagnostic_capture_truncated" } : {}
+		} });
+		if (!state.captureFailed) try {
+			fsyncSync(state.fd);
+		} catch (error) {
+			if (!captureCapacityError(error)) throw error;
+		}
+	} finally {
+		state.closed = true;
+		state.release();
+		if (state.fd >= 0) closeSync(state.fd);
+		pruneClosedEmptyCapture(state.path);
+	}
+}
+function registerCaptureWriter(path, processId) {
+	const writers = liveWriters.get(path) ?? /* @__PURE__ */ new Set();
+	writers.add(processId);
+	liveWriters.set(path, writers);
+	return () => {
+		writers.delete(processId);
+		if (writers.size === 0 && liveWriters.get(path) === writers) liveWriters.delete(path);
+	};
+}
+/** One process appends exact byte frames to a sidecar-owned session file. */
+function openRawCapture(file, options) {
+	if (!isAbsolute(file)) throw new Error("raw capture path must be absolute");
+	const directory = dirname(file);
+	const protectedPath = resolve(file).startsWith(`${RAW_ROOT}/`);
+	const mode = resolveRawCaptureMode(file, protectedPath, options?.mode);
+	const disabled = {
+		frame(_stream, _bytes, _metadata) {},
+		close(_result) {}
+	};
+	if (mode === "none") return disabled;
+	try {
+		mkdirSync(directory, {
+			recursive: true,
+			mode: 448
+		});
+	} catch (error) {
+		if (protectedPath && captureCapacityError(error)) return disabled;
+		throw error;
+	}
+	if (protectedPath) assertProtectedCaptureDirectory(directory);
+	const parent = lstatSync(directory);
+	if (!parent.isDirectory() || parent.isSymbolicLink() || (parent.mode & 63) !== 0) throw new Error("raw capture directory must be a private real directory");
+	const path = resolve(file);
+	let fd;
+	try {
+		fd = openCaptureTarget(path, protectedPath);
+	} catch (error) {
+		if (protectedPath && captureCapacityError(error)) return disabled;
+		throw error;
+	}
+	const generation = generations.get(path) ?? 0;
+	const loss = losses.get(path) ?? 0;
+	const processId = randomUUID();
+	const state = {
+		path,
+		protectedPath,
+		captureRoot: protectedPath ? RAW_ROOT : directory,
+		fd,
+		captureFailed: false,
+		captureIncomplete: false,
+		tails: /* @__PURE__ */ new Map(),
+		generation,
+		loss,
+		processId,
+		release: registerCaptureWriter(path, processId),
+		attempt: options?.unbound === true ? void 0 : activeAttempt.getStore(),
+		sequence: 0,
+		closed: false
+	};
+	return {
+		frame(stream, bytes, metadata) {
+			frameCapture(state, mode, stream, bytes, metadata);
+		},
+		close(result) {
+			closeCapture(state, result);
+		}
+	};
+}
+/** Empty closed evidence has no payload to preserve; never prune caller-owned paths. */
+function pruneClosedEmptyCapture(path, writing) {
+	if (path === writing || !path.startsWith(`${RAW_ROOT}/`) || liveWriters.get(path)?.size || trims.get(path)) return false;
+	const directory = dirname(path);
+	if (dirname(directory) !== RAW_ROOT || !/^[a-f0-9]{64}$/.test(directory.slice(28))) return false;
+	try {
+		assertProtectedCaptureDirectory(directory);
+		const before = lstatSync(path);
+		if (!before.isFile() || before.isSymbolicLink() || before.size !== 0 || before.nlink !== 1 || before.uid !== 0 || (before.mode & 63) !== 0) return false;
+		const handle = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+		try {
+			const opened = fstatSync(handle);
+			if (!opened.isFile() || opened.size !== 0 || opened.nlink !== 1 || opened.dev !== before.dev || opened.ino !== before.ino) return false;
+		} finally {
+			closeSync(handle);
+		}
+		unlinkSync(path);
+	} catch (error) {
+		if (error.code !== "ENOENT") return false;
+	}
+	try {
+		rmdirSync(directory);
+	} catch {}
+	generations.delete(path);
+	losses.delete(path);
+	return true;
+}
+/** Reclaim oldest whole spools before writing, even when an attempt is live. */
+function reserveCaptureBytes(root, writing, bytes) {
+	const files = [];
+	for (const entry of readdirSync(root, { withFileTypes: true })) {
+		const candidate = entry.isDirectory() && /^[a-f0-9]{64}$/.test(entry.name) ? join(root, entry.name, "process-io.frames") : entry.isFile() && entry.name === "process-io.frames" ? join(root, entry.name) : void 0;
+		if (!candidate) continue;
+		try {
+			const stat = lstatSync(candidate);
+			if (stat.size === 0 && pruneClosedEmptyCapture(candidate, writing)) continue;
+			if (stat.isFile() && !stat.isSymbolicLink()) files.push({
+				path: candidate,
+				size: stat.size,
+				modified: stat.mtimeMs,
+				dev: stat.dev,
+				ino: stat.ino
+			});
+		} catch (error) {
+			if (error.code !== "ENOENT") throw error;
+			pruneClosedEmptyCapture(candidate, writing);
+		}
+	}
+	let total = files.reduce((sum, item) => sum + item.size, 0);
+	let reset = false;
+	for (const item of files.sort((a, b) => a.modified - b.modified)) {
+		if (total + bytes + 128 <= 67108864) break;
+		const handle = openSync(item.path, constants.O_WRONLY | constants.O_NOFOLLOW);
+		try {
+			const opened = fstatSync(handle);
+			if (!opened.isFile() || opened.nlink !== 1 || opened.dev !== item.dev || opened.ino !== item.ino) throw new Error("Raw capture spool changed during capacity admission");
+			ftruncateSync(handle, 0);
+		} finally {
+			closeSync(handle);
+		}
+		generations.set(item.path, (generations.get(item.path) ?? 0) + 1);
+		losses.set(item.path, (losses.get(item.path) ?? 0) + 1);
+		total -= item.size;
+		if (item.path === writing) reset = true;
+		else pruneClosedEmptyCapture(item.path, writing);
+	}
+	if (total + bytes + 128 > 67108864) throw Object.assign(/* @__PURE__ */ new Error("Raw capture capacity unavailable"), { code: "EDQUOT" });
+	return reset;
+}
+const LINE_HEAD = /^\{"processId":"([a-f0-9-]{36})","sequence":(\d+),"at":"([^"]+)"/u;
+const LINE_ATTEMPT = /"executionId":("(?:[^"\\]|\\.)*"),"ordinal":(\d+),"providerSessionId":"(?:[^"\\]|\\.)*"\}$/u;
+/** Read complete lines from `start` to the current end, without loading the file. */
+async function* lines(path) {
+	const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+	try {
+		const chunk = Buffer.allocUnsafe(1 << 20);
+		let carry = Buffer.alloc(0);
+		let carryOffset = 0;
+		for (let position = 0;;) {
+			const { bytesRead } = await handle.read(chunk, 0, chunk.length, position);
+			if (bytesRead === 0) break;
+			position += bytesRead;
+			let data = Buffer.concat([carry, chunk.subarray(0, bytesRead)]);
+			let dataOffset = carryOffset;
+			for (;;) {
+				const newline = data.indexOf(10);
+				if (newline < 0) break;
+				yield {
+					line: data.subarray(0, newline + 1),
+					offset: dataOffset
+				};
+				data = data.subarray(newline + 1);
+				dataOffset += newline + 1;
+			}
+			carry = Buffer.from(data);
+			carryOffset = dataOffset;
+		}
+	} finally {
+		await handle.close();
+	}
+}
+/** The processes in one capture file, in file order, with their sizes. */
+async function summarizeRawCapture(file) {
+	const path = resolve(file);
+	const processes = /* @__PURE__ */ new Map();
+	let sizeBytes = 0;
+	for await (const { line, offset } of lines(path)) {
+		sizeBytes = offset + line.length;
+		const text = line.toString("utf8", 0, Math.min(line.length, 160));
+		const head = LINE_HEAD.exec(text);
+		if (!head) continue;
+		const [, processId, , at] = head;
+		let entry = processes.get(processId);
+		if (!entry) {
+			const tail = line.toString("utf8", Math.max(0, line.length - 600), line.length).trimEnd();
+			const attempt = LINE_ATTEMPT.exec(tail);
+			entry = {
+				processId,
+				...attempt ? {
+					executionId: JSON.parse(attempt[1]),
+					ordinal: Number(attempt[2])
+				} : {},
+				bytes: 0,
+				firstAt: at,
+				firstOffset: offset,
+				closed: false,
+				live: false
+			};
+			processes.set(processId, entry);
+		}
+		entry.bytes += line.length;
+		if (line.includes("\"terminal\":{")) entry.closed = true;
+	}
+	const writers = liveWriters.get(path);
+	for (const entry of processes.values()) if (writers?.has(entry.processId)) entry.live = true;
+	return {
+		sizeBytes,
+		processes: [...processes.values()]
+	};
+}
+/**
+* Remove whole processes from a capture file. A process is dropped with all
+* of its lines or not at all, so every remaining process still reads as a
+* complete sequence. A process this sidecar is still writing is never
+* dropped. Frames written while the file is rewritten are carried into the
+* replacement before it takes the path.
+*/
+async function trimRawCapture(file, drop) {
+	const path = resolve(file);
+	const writers = liveWriters.get(path);
+	const dropping = new Set([...drop].filter((id) => !writers?.has(id)));
+	const beforeBytes = lstatSync(path).size;
+	const originalLoss = losses.get(path) ?? 0;
+	if (dropping.size === 0) return {
+		beforeBytes,
+		afterBytes: beforeBytes,
+		droppedBytes: 0
+	};
+	trims.set(path, (trims.get(path) ?? 0) + 1);
+	try {
+		const temporary = `${path}.trim-${process.pid}-${randomUUID()}`;
+		const output = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 384);
+		try {
+			let scanned = 0;
+			for await (const { line, offset } of lines(path)) {
+				scanned = offset + line.length;
+				const head = LINE_HEAD.exec(line.toString("utf8", 0, Math.min(line.length, 160)));
+				if (head && dropping.has(head[1])) continue;
+				for (let written = 0; written < line.length;) written += writeSync(output, line, written, line.length - written);
+			}
+			if ((losses.get(path) ?? 0) !== originalLoss) {
+				rmSync(temporary, { force: true });
+				const afterBytes = statSync(path).size;
+				return {
+					beforeBytes,
+					afterBytes,
+					droppedBytes: Math.max(0, beforeBytes - afterBytes)
+				};
+			}
+			const source = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+			try {
+				const end = fstatSync(source).size;
+				const tail = Buffer.allocUnsafe(1 << 20);
+				for (let position = scanned; position < end;) {
+					const read = readSync(source, tail, 0, Math.min(tail.length, end - position), position);
+					if (read <= 0) break;
+					for (let written = 0; written < read;) written += writeSync(output, tail, written, read - written);
+					position += read;
+				}
+			} finally {
+				closeSync(source);
+			}
+			fsyncSync(output);
+			renameSync(temporary, path);
+			generations.set(path, (generations.get(path) ?? 0) + 1);
+		} catch (error) {
+			rmSync(temporary, { force: true });
+			throw error;
+		} finally {
+			closeSync(output);
+		}
+		const afterBytes = statSync(path).size;
+		return {
+			beforeBytes,
+			afterBytes,
+			droppedBytes: Math.max(0, beforeBytes - afterBytes)
+		};
+	} finally {
+		const active = (trims.get(path) ?? 1) - 1;
+		if (active > 0) trims.set(path, active);
+		else trims.delete(path);
+		pruneClosedEmptyCapture(path);
+	}
+}
+//#endregion
+//#region src/process-capture.ts
+/**
+* Bytes a process with a deferred raw capture may print before the capture
+* opens. A held CLI waits on stdin and prints next to nothing; one that prints
+* more is not a quiet spare, and it is stopped rather than held unbounded.
+*/
+const DEFERRED_CAPTURE_PENDING_BYTES = 1024 * 1024;
+/**
+* The raw byte capture of one CLI process. A deferred capture opens in
+* `begin`, inside the turn that takes the process; until then its frames wait
+* here, in order. A capture failure stops the process through `onFailure`.
+*/
+var ProcessCapture = class {
+	error;
+	rawCapture;
+	pendingFrames;
+	pendingBytes = 0;
+	constructor(path, deferred, onFailure) {
+		this.path = path;
+		this.onFailure = onFailure;
+		this.rawCapture = path && !deferred ? openRawCapture(path) : void 0;
+		this.pendingFrames = path && deferred ? [] : void 0;
+	}
+	/** The process failed to start: close the capture with the cause. */
+	closeAfterSpawnFailure(error) {
+		this.rawCapture?.close({ spawnError: error instanceof Error ? error.message : String(error) });
+	}
+	frame(stream, chunk) {
+		if (!this.rawCapture && !this.pendingFrames || this.error) return;
+		try {
+			if (stream !== "stdin" && !Buffer.isBuffer(chunk)) throw new Error(`${stream} was decoded before byte capture`);
+			const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+			if (this.pendingFrames) {
+				this.pendingBytes += bytes.length;
+				if (this.pendingBytes > DEFERRED_CAPTURE_PENDING_BYTES) throw new Error(`printed more than ${DEFERRED_CAPTURE_PENDING_BYTES} bytes before its capture opened`);
+				this.pendingFrames.push({
+					stream,
+					bytes
+				});
+				return;
+			}
+			this.rawCapture?.frame(stream, bytes);
+		} catch (error) {
+			this.error = error instanceof Error ? error.message : String(error);
+			this.onFailure();
+		}
+	}
+	finish(result) {
+		this.pendingFrames = void 0;
+		try {
+			this.rawCapture?.close({
+				...result,
+				captureError: this.error ?? null
+			});
+		} catch (error) {
+			this.error ??= error instanceof Error ? error.message : String(error);
+		}
+	}
+	/** Open a deferred capture in the caller's attempt and flush held frames. */
+	begin() {
+		if (this.error) throw new Error(`raw capture failed before a turn took the process: ${this.error}`);
+		if (!this.pendingFrames || !this.path) return;
+		const held = this.pendingFrames;
+		this.pendingFrames = void 0;
+		this.rawCapture = openRawCapture(this.path);
+		for (const frame of held) this.frame(frame.stream, frame.bytes);
+	}
+};
+//#endregion
+//#region src/owned-process-tree.ts
+function identity(pid) {
+	try {
+		const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+		const fields = stat.slice(stat.lastIndexOf(")") + 2).trim().split(/\s+/);
+		const group = Number(fields[2]);
+		if (!Number.isSafeInteger(group) || !fields[19]) throw new Error(`Cannot read process identity for ${pid}`);
+		return {
+			pid,
+			parent: Number(fields[1]),
+			group,
+			start: fields[19],
+			state: fields[0]
+		};
+	} catch (error) {
+		if (["ENOENT", "ESRCH"].includes(error.code ?? "")) return void 0;
+		throw error;
+	}
+}
+/** Observed Linux descendants retain their identity across process-group changes. */
+var OwnedProcessTree = class {
+	processes = /* @__PURE__ */ new Map();
+	groups = /* @__PURE__ */ new Map();
+	root;
+	constructor(rootPid) {
+		const root = identity(rootPid);
+		this.root = root;
+		if (root) {
+			this.processes.set(rootPid, root);
+			if (root.group === rootPid) this.groups.set(rootPid, root.start);
+		}
+	}
+	capture() {
+		const queue = [...this.processes.values()];
+		const seen = /* @__PURE__ */ new Set();
+		for (let index = 0; index < queue.length; index++) {
+			const expected = queue[index];
+			const key = `${expected.pid}:${expected.start}`;
+			if (seen.has(key)) continue;
+			seen.add(key);
+			const current = identity(expected.pid);
+			if (!current || current.start !== expected.start || current.state === "Z" || current.state === "X") {
+				if (this.processes.get(expected.pid)?.start === expected.start) this.processes.delete(expected.pid);
+				continue;
+			}
+			this.processes.set(current.pid, current);
+			if (current.group === current.pid) this.groups.set(current.group, current.start);
+			let children;
+			try {
+				children = readFileSync(`/proc/${current.pid}/task/${current.pid}/children`, "utf8");
+			} catch (error) {
+				if (["ENOENT", "ESRCH"].includes(error.code ?? "")) continue;
+				throw error;
+			}
+			for (const value of children.trim().split(/\s+/).filter(Boolean)) {
+				const pid = Number(value);
+				if (!Number.isSafeInteger(pid) || pid <= 0) throw new Error("Invalid child process identity");
+				const child = identity(pid);
+				if (!child || child.parent !== current.pid) continue;
+				this.processes.set(pid, child);
+				queue.push(child);
+			}
+		}
+		const liveGroups = new Set([...this.processes.values()].map((member) => member.group));
+		for (const group of this.groups.keys()) if (!liveGroups.has(group)) this.groups.delete(group);
+	}
+	live() {
+		return [...this.processes.values()].flatMap((expected) => {
+			const current = identity(expected.pid);
+			return current && current.start === expected.start && current.state !== "Z" && current.state !== "X" ? [current] : [];
+		});
+	}
+	hasLiveProcesses() {
+		this.capture();
+		if (this.live().length > 0) return true;
+		const root = this.root;
+		if (!root || !this.ownsRootGroup()) return false;
+		try {
+			process.kill(-root.group, 0);
+		} catch (error) {
+			if (error.code === "ESRCH") return false;
+			throw error;
+		}
+		for (const entry of readdirSync("/proc")) {
+			if (!/^[1-9][0-9]*$/.test(entry)) continue;
+			const member = identity(Number(entry));
+			if (member && member.group === root.group && member.state !== "Z" && member.state !== "X") this.processes.set(member.pid, member);
+		}
+		return this.live().length > 0;
+	}
+	ownsRootGroup() {
+		if (!this.root || this.root.group !== this.root.pid) return false;
+		const current = identity(this.root.pid);
+		return !current || current.start === this.root.start;
+	}
+	signal(signal) {
+		this.capture();
+		const signaledGroups = /* @__PURE__ */ new Set();
+		if (this.root && this.ownsRootGroup()) try {
+			process.kill(-this.root.group, signal);
+			signaledGroups.add(-this.root.group);
+		} catch (error) {
+			if (error.code !== "ESRCH") throw error;
+		}
+		for (const member of this.live()) {
+			const groupStart = this.groups.get(member.group);
+			const leader = groupStart === void 0 ? void 0 : identity(member.group);
+			const target = groupStart !== void 0 && (!leader || leader.start === groupStart) ? -member.group : member.pid;
+			if (target < 0 && signaledGroups.has(target)) continue;
+			try {
+				process.kill(target, signal);
+				if (target < 0) signaledGroups.add(target);
+			} catch (error) {
+				if (error.code !== "ESRCH") throw error;
+			}
+		}
+	}
+};
+//#endregion
+//#region src/process-group.ts
+const TERM_GRACE_MS = 250;
+const KILL_CONFIRM_MS = 1e3;
+/**
+* The process group a detached CLI leads. It outlives its leader when the CLI
+* leaves children behind (MCP servers, a backgrounded shell), so a run is
+* finished only once every member is gone. On Linux the members are read by
+* identity, so a reused pid or a zombie never counts as live.
+*/
+var CliProcessGroup = class {
+	tree;
+	constructor(leader) {
+		this.leader = leader;
+		this.tree = process.platform === "linux" ? ownedTree(leader) : void 0;
+	}
+	alive() {
+		if (this.tree) return this.tree.hasLiveProcesses();
+		try {
+			process.kill(-this.leader, 0);
+			return true;
+		} catch (error) {
+			return error.code !== "ESRCH";
+		}
+	}
+	signal(signal) {
+		if (this.tree) {
+			this.tree.signal(signal);
+			return;
+		}
+		try {
+			process.kill(-this.leader, signal);
+		} catch (error) {
+			if (error.code !== "ESRCH") throw error;
+		}
+	}
+	/** SIGTERM, a short grace, SIGKILL, then wait until no member is left. */
+	async stop() {
+		if (!this.alive()) return;
+		this.signal("SIGTERM");
+		const graceEnd = Date.now() + TERM_GRACE_MS;
+		while (this.alive() && Date.now() < graceEnd) await pause();
+		if (!this.alive()) return;
+		this.signal("SIGKILL");
+		const confirmEnd = Date.now() + KILL_CONFIRM_MS;
+		while (this.alive() && Date.now() < confirmEnd) await pause();
+		if (this.alive()) throw new Error(`process group ${this.leader} survived SIGKILL`);
+	}
+};
+function ownedTree(leader) {
+	try {
+		return new OwnedProcessTree(leader);
+	} catch {
+		return;
+	}
+}
+function pause() {
+	return new Promise((resolve) => setTimeout(resolve, 10));
+}
+/** The newest `maxBytes` of a stream, decoded once at the end. */
+var RollingByteCapture = class {
+	chunks = [];
+	bytes = 0;
+	constructor(maxBytes) {
+		this.maxBytes = maxBytes;
+		if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) throw new Error("maxOutputBytes must be a non-negative safe integer");
+	}
+	append(chunk) {
+		if (this.maxBytes === 0) return;
+		const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+		this.chunks.push(buffer);
+		this.bytes += buffer.length;
+		while (this.bytes > this.maxBytes) {
+			const first = this.chunks[0];
+			const excess = this.bytes - this.maxBytes;
+			if (first.length <= excess) {
+				this.chunks.shift();
+				this.bytes -= first.length;
+			} else {
+				this.chunks[0] = first.subarray(excess);
+				this.bytes -= excess;
+			}
+		}
+	}
+	text() {
+		return Buffer.concat(this.chunks, this.bytes).toString("utf8");
+	}
+};
+//#endregion
+//#region src/stream-parser.ts
+/**
+* Creates a stdout stream parser. Three modes:
+*
+* - "json"  (default): newline-delimited JSON, JSON.parse per line.
+* - "lines": plaintext, raw trimmed line per `transform` call.
+* - "raw":   no per-line splitting — accumulate the entire stream into a
+*            single buffer and deliver it via `onComplete(buffer)`.
+*
+* See StreamParserConfig docstring for the full contract per mode.
+*/
+function createStreamParser(config) {
+	let buffer = "";
+	const { parseAs = "json", transform, onEvent, onError, onComplete } = config;
+	if (parseAs === "raw") return {
+		push(chunk) {
+			buffer += chunk;
+		},
+		end() {
+			onComplete?.(buffer);
+			buffer = "";
+		}
+	};
+	function processLine(line) {
+		const trimmed = line.trim();
+		if (!trimmed) return;
+		if (parseAs === "lines") {
+			const event = transform ? transform(trimmed) : trimmed;
+			if (event !== null) onEvent(event);
+			return;
+		}
+		try {
+			const parsed = JSON.parse(trimmed);
+			const event = transform ? transform(parsed) : parsed;
+			if (event !== null) onEvent(event);
+		} catch (error) {
+			onError?.(error instanceof Error ? error : new Error(String(error)), trimmed);
+		}
+	}
+	return {
+		push(chunk) {
+			buffer += chunk;
+			let newlineIndex = buffer.indexOf("\n");
+			while (newlineIndex !== -1) {
+				const line = buffer.slice(0, newlineIndex);
+				buffer = buffer.slice(newlineIndex + 1);
+				processLine(line);
+				newlineIndex = buffer.indexOf("\n");
+			}
+		},
+		end() {
+			if (buffer.trim()) processLine(buffer);
+			buffer = "";
+			onComplete?.();
+		}
+	};
+}
+//#endregion
+//#region src/cli-process.ts
+const DEFAULT_MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
+/**
+* Spawns a CLI process with streaming support.
+*
+* @param config - Configuration for the process
+* @param parserConfig - Optional streaming parser for stdout
+* @returns Handle to the running process
+*/
+function spawnCliProcess(config, parserConfig) {
+	if (config.launcher) throw new Error("A launcher may wait for capacity: use launchCliProcess");
+	assertSpawnable(config);
+	const processEnv = buildChildEnv(config);
+	const detached = isDetached(config);
+	assertRawCaptureStdio(config);
+	let killer;
+	const capture = openProcessCapture(config, () => killer?.kill("SIGTERM"));
+	let child;
+	try {
+		child = spawnChild(config, processEnv, detached);
+	} catch (error) {
+		capture.closeAfterSpawnFailure(error);
+		throw error;
+	}
+	killer = new ChildKiller(child, detached);
+	return attachCliProcess(config, parserConfig, {
+		launch: { child },
+		killer,
+		capture,
+		detached
+	});
+}
+/**
+* Start a CLI through the config's `launcher` (or `spawn` without one) and
+* attach the same capture, deadlines, abort and exit handling as
+* `spawnCliProcess`. The launcher receives the fully assembled environment.
+*/
+async function launchCliProcess(config, parserConfig) {
+	const { launcher } = config;
+	if (!launcher) return spawnCliProcess(config, parserConfig);
+	if (config.isolatedIdentity) throw new Error("A consumer launcher owns the child's identity");
+	assertSpawnable(config);
+	const detached = isDetached(config);
+	assertRawCaptureStdio(config);
+	let killer;
+	const capture = openProcessCapture(config, () => killer?.kill("SIGTERM"));
+	let launch;
+	try {
+		const launched = launcher({
+			command: config.command,
+			args: config.args,
+			cwd: config.cwd,
+			env: buildChildEnv(config),
+			stdio: config.spawnOptions?.stdio ?? [
+				"pipe",
+				"pipe",
+				"pipe"
+			],
+			detached,
+			...config.signal ? { signal: config.signal } : {}
+		});
+		launch = launched instanceof Promise ? await launched : launched;
+	} catch (error) {
+		capture.closeAfterSpawnFailure(error);
+		throw error;
+	}
+	killer = new ChildKiller(launch.child, detached, launch.terminate?.bind(launch));
+	return attachCliProcess(config, parserConfig, {
+		launch,
+		killer,
+		capture,
+		detached
+	});
+}
+function isDetached(config) {
+	return config.spawnOptions?.detached ?? process.platform !== "win32";
+}
+function openProcessCapture(config, onFailure) {
+	return new ProcessCapture(config.rawCapturePath, config.rawCaptureDeferred, onFailure);
+}
+function attachCliProcess(config, parserConfig, run) {
+	const { launch, killer, capture, detached } = run;
+	const child = launch.child;
+	const spawnedAt = Date.now();
+	const stdin = watchStdinFailure(child, killer);
+	const group = config.ownProcessGroup && detached && process.platform !== "win32" && child.pid ? new CliProcessGroup(child.pid) : void 0;
+	child.stdout?.on("data", (chunk) => capture.frame("stdout", chunk));
+	child.stderr?.on("data", (chunk) => capture.frame("stderr", chunk));
+	const deadlines = new CliDeadlines(config, child, killer, spawnedAt);
+	deadlines.arm();
+	const abort = killOnAbort(config.signal, child, killer);
+	const exitPromise = createExitPromise(child, {
+		deadlines,
+		capture,
+		stdin,
+		endParser: attachStdoutParser(child, parserConfig),
+		abort,
+		group,
+		killer,
+		release: launch.release?.bind(launch)
+	});
+	return {
+		pid: child.pid,
+		process: child,
+		write(data) {
+			if (!child.stdin || child.stdin.destroyed) throw new Error("Cannot write to closed stdin");
+			const text = typeof data === "string" ? data : JSON.stringify(data);
+			capture.frame("stdin", text);
+			if (capture.error) throw new Error(`stdin capture failed: ${capture.error}`);
+			child.stdin.write(text);
+			if (typeof data === "object") {
+				capture.frame("stdin", "\n");
+				if (capture.error) throw new Error(`stdin capture failed: ${capture.error}`);
+				child.stdin.write("\n");
+			}
+		},
+		closeInput() {
+			child.stdin?.end();
+		},
+		kill(killSignal = "SIGTERM") {
+			return killer.kill(killSignal);
+		},
+		beginRawCapture() {
+			capture.begin();
+		},
+		exitPromise
+	};
+}
+function assertSpawnable(config) {
+	if (config.signal?.aborted) {
+		const error = /* @__PURE__ */ new Error("CLI process aborted before spawn");
+		error.name = "AbortError";
+		throw error;
+	}
+}
+function assertRawCaptureStdio(config) {
+	if (!config.rawCapturePath || config.spawnOptions?.stdio === void 0) return;
+	const io = config.spawnOptions.stdio;
+	if (!Array.isArray(io) || io.length !== 3 || !["pipe", "ignore"].includes(String(io[0])) || io[1] !== "pipe" || io[2] !== "pipe") throw new Error("raw capture requires piped stdout and stderr, with pipe or ignored stdin");
+}
+function spawnChild(config, processEnv, detached) {
+	const { command, args, cwd, spawnOptions, isolatedIdentity } = config;
+	const isolated = isolatedIdentity !== void 0;
+	if (isolated && (process.platform !== "linux" || process.getuid?.() !== 0 || !Number.isSafeInteger(isolatedIdentity.uid) || isolatedIdentity.uid <= 0 || !Number.isSafeInteger(isolatedIdentity.gid) || isolatedIdentity.gid <= 0 || spawnOptions?.uid !== isolatedIdentity.uid || spawnOptions?.gid !== isolatedIdentity.gid)) throw new Error("Isolated CLI identity requires a matching root-owned Linux launch");
+	const { uid: _uid, gid: _gid, ...safeSpawnOptions } = spawnOptions ?? {};
+	return spawn(isolated ? "/usr/bin/setpriv" : command, isolated ? [
+		"--reuid",
+		String(isolatedIdentity.uid),
+		"--regid",
+		String(isolatedIdentity.gid),
+		"--clear-groups",
+		"--no-new-privs",
+		"--",
+		command,
+		...args
+	] : args, {
+		cwd,
+		env: processEnv,
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		],
+		detached,
+		...isolated ? safeSpawnOptions : spawnOptions
+	});
+}
+function watchStdinFailure(child, killer) {
+	const failure = { error: void 0 };
+	child.stdin?.on("error", (error) => {
+		if (failure.error !== void 0) return;
+		failure.error = error.message;
+		killer.kill("SIGTERM");
+		if (!killer.escalating) killer.escalate(() => child.exitCode === null && child.signalCode === null);
+	});
+	return failure;
+}
+function killOnAbort(signal, child, killer) {
+	const abort = { aborted: false };
+	if (!signal) return abort;
+	const abortHandler = () => {
+		abort.aborted = true;
+		killer.kill("SIGTERM");
+		if (!killer.escalating) killer.escalate(() => child.exitCode === null && child.signalCode === null);
+	};
+	signal.addEventListener("abort", abortHandler, { once: true });
+	if (signal.aborted) abortHandler();
+	child.once("close", () => {
+		signal.removeEventListener("abort", abortHandler);
+	});
+	return abort;
+}
+/**
+* Feed stdout to a streaming parser. Returns the function that ends it, or
+* undefined when there is no parser or no stdout.
+*/
+function attachStdoutParser(child, parserConfig) {
+	if (!(parserConfig && child.stdout)) return void 0;
+	const parser = createStreamParser(parserConfig);
+	let parserEnded = false;
+	const endParser = () => {
+		if (parserEnded) return;
+		parserEnded = true;
+		parser.end();
+	};
+	const decoder = new StringDecoder("utf8");
+	child.stdout.on("data", (chunk) => {
+		parser.push(decoder.write(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+	});
+	child.stdout.on("end", () => {
+		const tail = decoder.end();
+		if (tail) parser.push(tail);
+		endParser();
+	});
+	return endParser;
+}
+function createExitPromise(child, run) {
+	const { deadlines, capture, stdin, endParser, abort, group, killer } = run;
+	let released = false;
+	const release = () => {
+		if (released) return;
+		released = true;
+		run.release?.();
+	};
+	return new Promise((resolve) => {
+		child.once("close", async (code, exitSignal) => {
+			deadlines.clearAll();
+			endParser?.();
+			const processGroupError = await group?.stop().then(() => void 0, (error) => error instanceof Error ? error.message : String(error));
+			const terminateError = await killer.terminated();
+			release();
+			capture.finish({
+				code,
+				signal: exitSignal,
+				timedOut: deadlines.timedOut,
+				timeoutReason: deadlines.timeoutReason ?? null,
+				stdinError: stdin.error ?? null
+			});
+			resolve({
+				code,
+				signal: exitSignal,
+				success: code === 0 && capture.error === void 0 && stdin.error === void 0 && processGroupError === void 0,
+				timedOut: deadlines.timedOut,
+				timeoutReason: deadlines.timeoutReason,
+				timeoutDiagnostic: deadlines.timeoutDiagnostic,
+				stdinError: stdin.error,
+				captureError: capture.error,
+				...abort.aborted ? { aborted: true } : {},
+				...processGroupError === void 0 ? {} : { processGroupError },
+				...terminateError === void 0 ? {} : { terminateError }
+			});
+		});
+		child.once("error", (error) => {
+			deadlines.clearAll();
+			release();
+			capture.finish({
+				spawnError: error instanceof Error ? error.message : String(error),
+				stdinError: stdin.error ?? null
+			});
+			resolve({
+				code: null,
+				signal: null,
+				success: false,
+				timedOut: false,
+				spawnError: error instanceof Error ? error.message : String(error),
+				stdinError: stdin.error,
+				captureError: capture.error,
+				...abort.aborted ? { aborted: true } : {}
+			});
+		});
+	});
+}
+/**
+* Executes a CLI command and waits for completion. Without a parser it
+* returns stdout; stdout and stderr keep their newest `maxOutputBytes`.
+*/
+async function execCli(config, parserConfig, options = {}) {
+	const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+	const stderr = new RollingByteCapture(maxOutputBytes);
+	const stdout = new RollingByteCapture(maxOutputBytes);
+	const events = [];
+	const startedAt = Date.now();
+	const cliProcess = await launchCliProcess(config, parserConfig ? {
+		...parserConfig,
+		onEvent: (event) => {
+			events.push(event);
+			parserConfig.onEvent(event);
+		}
+	} : void 0);
+	cliProcess.process.stderr?.on("data", (chunk) => stderr.append(chunk));
+	if (!parserConfig) cliProcess.process.stdout?.on("data", (chunk) => stdout.append(chunk));
+	return {
+		exit: await cliProcess.exitPromise,
+		stderr: stderr.text(),
+		durationMs: Date.now() - startedAt,
+		...parserConfig ? { events } : { stdout: stdout.text() }
+	};
+}
+//#endregion
+//#region src/held-spare.ts
+/**
+* A parser that holds the spare's output until a turn adopts the process, then
+* hands the turn's own parser everything the CLI printed so far, in order.
+*/
+function createDeferredParser() {
+	const held = [];
+	let target;
+	const deliver = (entry, to) => {
+		if (entry.kind === "error") to.onError?.(entry.error, entry.line);
+		else if (entry.kind === "complete") to.onComplete?.(entry.raw);
+		else try {
+			const event = to.transform ? to.transform(entry.raw) : entry.raw;
+			if (event !== null) to.onEvent(event);
+		} catch (error) {
+			to.onError?.(error instanceof Error ? error : new Error(String(error)), JSON.stringify(entry.raw));
+		}
+	};
+	const take = (entry) => {
+		if (target) deliver(entry, target);
+		else held.push(entry);
+	};
+	return {
+		config: {
+			transform: (raw) => raw,
+			onEvent: (raw) => take({
+				kind: "event",
+				raw
+			}),
+			onError: (error, line) => take({
+				kind: "error",
+				error,
+				line
+			}),
+			onComplete: (raw) => take({
+				kind: "complete",
+				raw
+			})
+		},
+		attach(next) {
+			target = next;
+			for (const entry of held.splice(0)) deliver(entry, next);
+		}
+	};
+}
+/** How long a spare no turn adopted keeps its process. */
+const HELD_SPARE_IDLE_MS = 12e4;
+/**
+* How long a stopped spare has to exit after SIGTERM before it is killed.
+* Its HOME stays taken, and a turn that waits for it waits, until it exits.
+*/
+const HELD_SPARE_STOP_GRACE_MS = 2e3;
+function createHeldSpareRegistry() {
+	const spares = /* @__PURE__ */ new Map();
+	const stop = (spare) => {
+		if (spare.state === "claimed" || spare.state === "stopped") return;
+		spare.state = "stopped";
+		if (spare.idleTimer) clearTimeout(spare.idleTimer);
+		const forget = () => {
+			if (spares.get(spare.home) === spare) spares.delete(spare.home);
+		};
+		const force = setTimeout(() => spare.process.kill("SIGKILL"), HELD_SPARE_STOP_GRACE_MS);
+		force.unref();
+		const exited = () => {
+			clearTimeout(force);
+			forget();
+		};
+		spare.process.exitPromise.then(exited, exited);
+		spare.controller.abort();
+		spare.process.kill();
+	};
+	const claim = (spare) => {
+		spare.state = "claimed";
+		if (spare.idleTimer) clearTimeout(spare.idleTimer);
+		if (spares.get(spare.home) === spare) spares.delete(spare.home);
+	};
+	return {
+		spareFor: (home) => home ? spares.get(home) : void 0,
+		register: (spare) => {
+			spares.set(spare.home, spare);
+		},
+		has: (home) => spares.has(home),
+		stop,
+		claim,
+		adopt: (spare, turn) => {
+			if (spare.state === "stopped" || spare.state === "claimed") throw new Error(`A ${spare.state} spare cannot be adopted`);
+			try {
+				spare.process.beginRawCapture?.();
+			} catch (error) {
+				stop(spare);
+				throw error;
+			}
+			claim(spare);
+			spare.parser.attach(turn.parser);
+			const kill = () => spare.process.kill();
+			if (turn.signal.aborted) kill();
+			else turn.signal.addEventListener("abort", kill, { once: true });
+			return {
+				...spare.process,
+				exitPromise: spare.process.exitPromise.finally(() => turn.signal.removeEventListener("abort", kill))
+			};
+		},
+		discard: async () => {
+			const stopping = [];
+			for (const spare of [...spares.values()]) {
+				stop(spare);
+				stopping.push(spare.process.exitPromise.catch(() => void 0));
+			}
+			await Promise.all(stopping);
+		}
+	};
+}
+/** The argument after `flag`, if any. */
+function argAfter(args, flag) {
+	const at = args.indexOf(flag);
+	return at >= 0 ? args[at + 1] : void 0;
+}
+/**
+* Whether two launches are the same process. `comparable` maps an environment
+* value to what must match (a harness drops the lines it allows to differ);
+* the default compares values as they are. Returns the names of what differs
+* (never values: environments hold credentials), empty when equal.
+*/
+function launchDifferences(spare, turn, comparable = (_key, value) => value) {
+	const differences = [];
+	if (spare.args.length !== turn.args.length || spare.args.some((arg, index) => arg !== turn.args[index])) differences.push("args");
+	const keys = new Set([...Object.keys(spare.env), ...Object.keys(turn.env)]);
+	for (const key of keys) if (comparable(key, spare.env[key]) !== comparable(key, turn.env[key])) differences.push(`env:${key}`);
+	return differences;
+}
+//#endregion
+//#region src/rpc-bridge-errors.ts
+var JsonRpcError = class extends Error {
+	constructor(code, message, data) {
+		super(message);
+		this.code = code;
+		this.data = data;
+		this.name = "JsonRpcError";
+	}
+};
+var BridgeClosedError = class extends Error {
+	/** The child's last stderr, bounded; kept off the message, which callers log. */
+	stderrTail;
+	constructor(reason, options) {
+		super(`RpcBridge closed: ${reason}`, options?.cause ? { cause: options.cause } : void 0);
+		this.name = "BridgeClosedError";
+		if (options?.stderrTail) this.stderrTail = options.stderrTail;
+	}
+};
+const STDERR_TAIL_CHARS = 2e3;
+/**
+* What ended the child, in words a log reader can act on: the spawn errno
+* (ENOENT: command not found; EACCES; EAGAIN), the exit code and the signal.
+* "process-error before response to initialize" alone named none of them.
+*/
+function describeClose(reason) {
+	const errno = reason.error?.code;
+	const parts = [
+		reason.error ? `${errno ? `${errno}: ` : ""}${reason.error.message}` : void 0,
+		reason.code === null ? void 0 : `exit=${reason.code}`,
+		reason.signal ? `signal=${reason.signal}` : void 0
+	].filter((part) => part !== void 0);
+	return parts.length ? ` [${parts.join("; ")}]` : "";
+}
+var BridgeBackpressureError = class extends Error {
+	constructor(pending, limit) {
+		super(`RpcBridge backpressure: ${pending} pending requests at limit ${limit}`);
+		this.pending = pending;
+		this.limit = limit;
+		this.name = "BridgeBackpressureError";
+	}
+};
+var RpcRequestTimeoutError = class extends Error {
+	constructor(method, timeoutMs) {
+		super(`RpcBridge request "${method}" timed out after ${timeoutMs}ms`);
+		this.method = method;
+		this.timeoutMs = timeoutMs;
+		this.name = "RpcRequestTimeoutError";
+	}
+};
+//#endregion
+//#region src/rpc-byte-capture.ts
+/**
+* Exact byte capture of an RPC bridge's process I/O: one capture for the
+* process lifetime, or one per admitted turn on a retained process. A capture
+* failure stops the child through `killChild`.
+*/
+var RpcByteCapture = class {
+	error;
+	lifetime;
+	turn;
+	turnFrameMetadata;
+	processExit;
+	constructor(path, perTurn, killChild, beforeFrame, spawnErrorMessage) {
+		this.perTurn = perTurn;
+		this.killChild = killChild;
+		this.beforeFrame = beforeFrame;
+		this.spawnErrorMessage = spawnErrorMessage;
+		this.lifetime = path ? openRawCapture(path, perTurn ? { unbound: true } : void 0) : void 0;
+	}
+	closeAfterSpawnFailure(error) {
+		this.lifetime?.close({ spawnError: error instanceof Error ? error.message : String(error) });
+	}
+	frame(stream, bytes) {
+		this.beforeFrame();
+		const capture = this.turn ?? this.lifetime;
+		if (!capture || this.error) return;
+		try {
+			capture.frame(stream, bytes, this.turn ? this.turnFrameMetadata : void 0);
+		} catch (error) {
+			this.error = error instanceof Error ? error.message : String(error);
+			this.killChild("SIGTERM");
+		}
+	}
+	/** Capture the child's stdout and stderr bytes and its exit. */
+	attach(child) {
+		child.stdout?.on("data", (chunk) => this.frameChunk("stdout", chunk));
+		child.stderr?.on("data", (chunk) => this.frameChunk("stderr", chunk));
+		child.once("close", (code, exitSignal) => {
+			this.processExit = {
+				code,
+				signal: exitSignal
+			};
+			try {
+				this.lifetime?.close({
+					code,
+					signal: exitSignal,
+					timedOut: false,
+					timeoutReason: null,
+					captureError: this.error ?? null,
+					spawnError: this.spawnErrorMessage()
+				});
+			} catch (error) {
+				this.error ??= error instanceof Error ? error.message : String(error);
+			}
+		});
+	}
+	/**
+	* Bind a capture to one serialized turn. Returns the function that closes it
+	* with the turn's result and throws if capture failed.
+	*/
+	beginTurn(path, metadata, pid, bridgeClosed) {
+		if (bridgeClosed || this.turn || this.lifetime && !this.perTurn) throw new Error("RPC turn capture requires a live unbound bridge");
+		const capture = openRawCapture(path);
+		this.turn = capture;
+		this.turnFrameMetadata = {
+			...metadata,
+			pid
+		};
+		return (result) => {
+			try {
+				capture.close({
+					...result,
+					...this.processExit ? { processExit: this.processExit } : {},
+					captureError: this.error ?? null,
+					spawnError: this.spawnErrorMessage()
+				});
+				if (this.error) throw new Error(this.error);
+			} finally {
+				if (this.turn === capture) {
+					this.turn = void 0;
+					this.turnFrameMetadata = void 0;
+				}
+			}
+		};
+	}
+	frameChunk(stream, chunk) {
+		if (!Buffer.isBuffer(chunk)) {
+			this.error = `${stream} was decoded before byte capture`;
+			this.killChild("SIGTERM");
+		} else this.frame(stream, chunk);
+	}
+};
+//#endregion
+//#region src/rpc-dispatcher.ts
+/**
+* JSON-RPC traffic of one bridge: outbound requests awaiting responses,
+* inbound notifications and reverse requests routed to their handlers, and the
+* NDJSON framing of stdout.
+*/
+var RpcDispatcher = class {
+	pending = /* @__PURE__ */ new Map();
+	notificationHandlers = /* @__PURE__ */ new Map();
+	requestHandlers = /* @__PURE__ */ new Map();
+	nextId = 1;
+	stdoutBuffer = "";
+	constructor(host) {
+		this.host = host;
+	}
+	get pendingCount() {
+		return this.pending.size;
+	}
+	request(method, params, options) {
+		const { maxPendingRequests, defaultRequestTimeoutMs } = this.host;
+		if (this.host.isClosed()) return Promise.reject(new BridgeClosedError(`request(${method}) after close`));
+		if (this.pending.size >= maxPendingRequests) return Promise.reject(new BridgeBackpressureError(this.pending.size, maxPendingRequests));
+		const id = String(this.nextId++);
+		const timeoutMs = options?.timeoutMs ?? defaultRequestTimeoutMs;
+		return new Promise((resolve, reject) => {
+			const entry = {
+				resolve,
+				reject,
+				method,
+				startedAt: Date.now()
+			};
+			if (timeoutMs > 0) {
+				entry.timer = setTimeout(() => {
+					if (this.pending.delete(id)) reject(new RpcRequestTimeoutError(method, timeoutMs));
+				}, timeoutMs);
+				entry.timer.unref();
+			}
+			this.pending.set(id, entry);
+			try {
+				this.host.writeFrame({
+					jsonrpc: "2.0",
+					id,
+					method,
+					params
+				});
+			} catch (err) {
+				this.pending.delete(id);
+				if (entry.timer) clearTimeout(entry.timer);
+				reject(err instanceof Error ? err : new Error(String(err)));
+			}
+		});
+	}
+	notify(method, params) {
+		if (this.host.isClosed()) throw new BridgeClosedError(`notify(${method}) after close`);
+		this.host.writeFrame({
+			jsonrpc: "2.0",
+			method,
+			params
+		});
+	}
+	onNotification(method, handler) {
+		let set = this.notificationHandlers.get(method);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.notificationHandlers.set(method, set);
+		}
+		set.add(handler);
+		return () => {
+			set?.delete(handler);
+		};
+	}
+	onRequest(method, handler) {
+		if (this.requestHandlers.has(method)) throw new Error(`RpcBridge: request handler for "${method}" already registered. Unregister the existing handler first.`);
+		this.requestHandlers.set(method, handler);
+		return () => {
+			if (this.requestHandlers.get(method) === handler) this.requestHandlers.delete(method);
+		};
+	}
+	/** Split decoded stdout into NDJSON lines and dispatch each envelope. */
+	consumeStdoutChunk(chunk) {
+		this.stdoutBuffer += chunk;
+		let nl = this.stdoutBuffer.indexOf("\n");
+		while (nl !== -1) {
+			const line = this.stdoutBuffer.slice(0, nl).trim();
+			this.stdoutBuffer = this.stdoutBuffer.slice(nl + 1);
+			if (line.length > 0) try {
+				const env = JSON.parse(line);
+				this.handleEnvelope(env);
+			} catch (err) {
+				this.host.logger.warn("stdout JSON parse error — line dropped", {
+					error: err instanceof Error ? err.message : String(err),
+					sample: line.slice(0, 200)
+				});
+			}
+			nl = this.stdoutBuffer.indexOf("\n");
+		}
+	}
+	/** Reject every pending request — fail loud, never hang. */
+	rejectAll(reason, stderrBuffer) {
+		for (const [id, req] of this.pending) {
+			if (req.timer) clearTimeout(req.timer);
+			req.reject(new BridgeClosedError(`${reason.reason} before response to ${req.method} (id=${id})${describeClose(reason)}`, {
+				...reason.error ? { cause: reason.error } : {},
+				stderrTail: stderrBuffer.slice(-STDERR_TAIL_CHARS)
+			}));
+		}
+		this.pending.clear();
+	}
+	handleEnvelope(envelope) {
+		if (envelope.id !== void 0 && envelope.id !== null && envelope.method === void 0) {
+			this.handleResponse(envelope);
+			return;
+		}
+		if (envelope.method && (envelope.id === void 0 || envelope.id === null)) {
+			this.handleNotification(envelope.method, envelope.params);
+			return;
+		}
+		if (envelope.method && envelope.id !== void 0 && envelope.id !== null) {
+			this.handleRequest(envelope.method, envelope.id, envelope.params);
+			return;
+		}
+		this.host.logger.warn("malformed envelope", { envelope });
+	}
+	handleResponse(envelope) {
+		const key = String(envelope.id);
+		const req = this.pending.get(key);
+		if (!req) {
+			this.host.logger.warn("unmatched response id", { id: envelope.id });
+			return;
+		}
+		this.pending.delete(key);
+		if (req.timer) clearTimeout(req.timer);
+		if (envelope.error) req.reject(new JsonRpcError(envelope.error.code, envelope.error.message, envelope.error.data));
+		else req.resolve(envelope.result);
+	}
+	handleNotification(method, params) {
+		const { logger } = this.host;
+		const handlers = this.notificationHandlers.get(method);
+		if (!handlers || handlers.size === 0) {
+			logger.debug("no handler for notification", { method });
+			return;
+		}
+		for (const handler of handlers) try {
+			const result = handler(params);
+			if (result instanceof Promise) result.catch((err) => {
+				logger.warn("notification handler rejected", {
+					method,
+					error: err instanceof Error ? err.message : String(err)
+				});
+			});
+		} catch (err) {
+			logger.warn("notification handler threw", {
+				method,
+				error: err instanceof Error ? err.message : String(err)
+			});
+		}
+	}
+	handleRequest(method, id, params) {
+		const handler = this.requestHandlers.get(method);
+		if (!handler) {
+			this.sendErrorResponse(id, -32601, `Method not found: ${method}`);
+			return;
+		}
+		Promise.resolve().then(() => handler(params)).then((result) => this.sendResponse(id, result), (err) => {
+			const message = err instanceof Error ? err.message : String(err);
+			const code = err instanceof JsonRpcError ? err.code : -32e3;
+			const data = err instanceof JsonRpcError ? err.data : void 0;
+			this.sendErrorResponse(id, code, message, data);
+		});
+	}
+	sendResponse(id, result) {
+		if (this.host.isClosed()) return;
+		try {
+			this.host.writeFrame({
+				jsonrpc: "2.0",
+				id,
+				result
+			});
+		} catch (err) {
+			this.host.logger.warn("failed to write response", {
+				id,
+				error: err instanceof Error ? err.message : String(err)
+			});
+		}
+	}
+	sendErrorResponse(id, code, message, data) {
+		if (this.host.isClosed()) return;
+		try {
+			this.host.writeFrame({
+				jsonrpc: "2.0",
+				id,
+				error: {
+					code,
+					message,
+					data
+				}
+			});
+		} catch (err) {
+			this.host.logger.warn("failed to write error response", {
+				id,
+				error: err instanceof Error ? err.message : String(err)
+			});
+		}
+	}
+};
+//#endregion
+//#region src/rpc-process-owner.ts
+function reportCleanupFailure(logger, message, error) {
+	try {
+		logger.error(message, { error: String(error) });
+	} catch {}
+}
+/**
+* Signals and reaps the child of an RPC bridge, plus the descendants it owns
+* when the bridge owns a process group.
+*/
+var RpcProcessOwner = class {
+	ownsProcessGroup;
+	ownedTree;
+	treeCaptureTimer;
+	treeCaptureError;
+	ownedTermination;
+	closeDeadline;
+	constructor(child, isolatedLaunch, detached, hardCloseDeadlineMs, logger, onTerminationFailure) {
+		this.child = child;
+		this.isolatedLaunch = isolatedLaunch;
+		this.hardCloseDeadlineMs = hardCloseDeadlineMs;
+		this.logger = logger;
+		this.onTerminationFailure = onTerminationFailure;
+		this.ownsProcessGroup = detached && process.platform !== "win32";
+		try {
+			if (this.ownsProcessGroup && process.platform === "linux" && child.pid) this.ownedTree = new OwnedProcessTree(child.pid);
+		} catch (error) {
+			this.kill("SIGKILL");
+			throw error;
+		}
+		if (this.ownedTree) {
+			this.captureTree();
+			this.treeCaptureTimer = setInterval(() => this.captureTree(), 50);
+			this.treeCaptureTimer.unref();
+		}
+	}
+	/** Wall-clock instant by which a close must finish; fixed by the first caller. */
+	deadline() {
+		this.closeDeadline ??= Date.now() + this.hardCloseDeadlineMs;
+		return this.closeDeadline;
+	}
+	kill(killSignal) {
+		const child = this.child;
+		if (this.ownedTree) try {
+			this.ownedTree.signal(killSignal);
+			return true;
+		} catch (error) {
+			this.treeCaptureError ??= error instanceof Error ? error : new Error(String(error));
+			if (child.exitCode === null && child.signalCode === null) return child.kill(killSignal);
+			return false;
+		}
+		if (this.ownsProcessGroup && child.pid) try {
+			process.kill(-child.pid, killSignal);
+			return true;
+		} catch {}
+		return this.isolatedLaunch ? this.isolatedLaunch.kill(killSignal) : child.kill(killSignal);
+	}
+	isRunning() {
+		const child = this.child;
+		if (this.ownedTree) return this.ownedTree.hasLiveProcesses();
+		if (this.ownsProcessGroup && child.pid) try {
+			process.kill(-child.pid, 0);
+			return true;
+		} catch (error) {
+			return error.code !== "ESRCH";
+		}
+		return child.exitCode === null && child.signalCode === null;
+	}
+	captureTree() {
+		try {
+			this.ownedTree?.capture();
+		} catch (error) {
+			this.treeCaptureError ??= error instanceof Error ? error : new Error(String(error));
+		}
+	}
+	/** Terminate and reap every owned process; rejects on a survivor or fault. */
+	finish() {
+		if (!this.ownsProcessGroup) return Promise.resolve();
+		this.ownedTermination ??= this.terminateOwned();
+		this.ownedTermination.catch((error) => {
+			reportCleanupFailure(this.logger, "Owned process cleanup failed", error);
+			this.onTerminationFailure(error);
+		});
+		return this.ownedTermination;
+	}
+	async terminateOwned() {
+		const deadline = this.deadline();
+		if (this.treeCaptureTimer) clearInterval(this.treeCaptureTimer);
+		this.captureTree();
+		this.kill("SIGTERM");
+		try {
+			if (this.isRunning()) {
+				await new Promise((resolve) => setTimeout(resolve, Math.min(100, Math.max(0, deadline - Date.now()))));
+				this.kill("SIGKILL");
+				const reapDeadline = Math.min(Date.now() + 900, deadline);
+				while (this.isRunning() && Date.now() < reapDeadline) await new Promise((resolve) => setTimeout(resolve, Math.min(10, Math.max(0, reapDeadline - Date.now()))));
+				if (this.isRunning()) throw new Error("RpcBridge owned processes survived forced shutdown");
+			}
+		} catch (error) {
+			this.kill("SIGKILL");
+			throw error;
+		}
+		if (this.treeCaptureError) throw this.treeCaptureError;
+	}
+};
+//#endregion
+//#region src/rpc-lifecycle.ts
+/**
+* When an RPC bridge is open, closing or closed: the single settlement of the
+* close reason, and the drain, EOF, SIGTERM and SIGKILL sequence behind
+* `close()`.
+*/
+var RpcLifecycle = class {
+	closed = false;
+	exitReason;
+	childError;
+	closeHandlers = /* @__PURE__ */ new Set();
+	childClosed = false;
+	closing;
+	resolveChildClose = () => {};
+	childClosePromise = new Promise((resolve) => {
+		this.resolveChildClose = resolve;
+	});
+	constructor(child, owner, dispatcher, policy, logger, stderrText) {
+		this.child = child;
+		this.owner = owner;
+		this.dispatcher = dispatcher;
+		this.policy = policy;
+		this.logger = logger;
+		this.stderrText = stderrText;
+	}
+	/** Watch the child and abort signal. */
+	attach(child, signal) {
+		child.once("close", (code, exitSignal) => {
+			this.onChildClose(code, exitSignal);
+		});
+		child.once("error", (error) => {
+			this.childError = error;
+		});
+		if (this.owner.ownsProcessGroup) child.once("exit", () => {
+			this.closed = true;
+			this.owner.finish();
+		});
+		if (signal) {
+			const onAbort = () => {
+				this.logger.warn("AbortSignal fired — closing bridge");
+				this.close().catch((error) => reportCleanupFailure(this.logger, "RPC abort cleanup failed", error));
+			};
+			if (signal.aborted) onAbort();
+			else {
+				signal.addEventListener("abort", onAbort, { once: true });
+				child.once("exit", () => signal.removeEventListener("abort", onAbort));
+			}
+		}
+	}
+	onClose(handler) {
+		if (this.exitReason) {
+			try {
+				handler(this.exitReason);
+			} catch {}
+			return () => {};
+		}
+		this.closeHandlers.add(handler);
+		return () => this.closeHandlers.delete(handler);
+	}
+	/** Settle the close reason once: reject pending requests, notify handlers. */
+	settleClose(reason) {
+		if (this.exitReason) return;
+		this.exitReason = reason;
+		this.closed = true;
+		this.dispatcher.rejectAll(reason, this.stderrText());
+		for (const handler of this.closeHandlers) try {
+			handler(reason);
+		} catch (err) {
+			this.logger.warn("close handler threw", { error: err instanceof Error ? err.message : String(err) });
+		}
+	}
+	settleProcessError(error) {
+		this.settleClose({
+			code: this.child.exitCode,
+			signal: this.child.signalCode,
+			reason: "process-error",
+			error: error instanceof Error ? error : new Error(String(error))
+		});
+	}
+	close(graceMs = this.policy.defaultCloseGraceMs) {
+		if (!this.owner.ownsProcessGroup) return this.closeOperation(graceMs);
+		this.closing ??= this.closeOperation(graceMs).catch((error) => {
+			this.settleProcessError(error);
+			throw error;
+		});
+		return this.closing;
+	}
+	onChildClose(code, exitSignal) {
+		this.childClosed = true;
+		this.resolveChildClose();
+		const reason = {
+			code,
+			signal: exitSignal,
+			...this.childError ? { error: this.childError } : {},
+			reason: this.childError ? "process-error" : "process-exit"
+		};
+		if (this.owner.ownsProcessGroup) this.owner.finish().then(() => this.settleClose(reason), (error) => this.settleClose({
+			...reason,
+			error: error instanceof Error ? error : new Error(String(error)),
+			reason: "process-error"
+		}));
+		else this.settleClose(reason);
+	}
+	async closeOperation(graceMs) {
+		const { hardCloseDeadlineMs } = this.policy;
+		if (this.closed) {
+			await this.closeSettledBridge();
+			return;
+		}
+		const nativeDeadline = this.owner.deadline() - (this.owner.ownsProcessGroup ? 1e3 : 0);
+		const remaining = () => Math.max(0, nativeDeadline - Date.now());
+		this.closed = true;
+		this.owner.captureTree();
+		await this.drainPending(graceMs, remaining);
+		this.endStdin();
+		await this.awaitStdinEof(remaining);
+		this.terminateChild(graceMs, remaining);
+		await Promise.race([this.childClosePromise, new Promise((resolve) => setTimeout(resolve, remaining()).unref())]);
+		await this.owner.finish();
+		if (!this.exitReason) {
+			this.logger.error("close() hard deadline hit — child not reaped", {
+				hardCloseDeadlineMs,
+				pid: this.child.pid
+			});
+			this.settleClose({
+				code: null,
+				signal: null,
+				reason: "graceful"
+			});
+		}
+	}
+	/** A second close() on a bridge whose close was already settled. */
+	async closeSettledBridge() {
+		const child = this.child;
+		if (this.childClosed) {
+			await this.owner.finish();
+			return;
+		}
+		if (this.exitReason?.reason === "graceful" && child.exitCode === null && child.signalCode === null) this.owner.kill("SIGKILL");
+		await Promise.race([this.childClosePromise, new Promise((resolve) => setTimeout(resolve, this.policy.hardCloseDeadlineMs).unref())]);
+		await this.owner.finish();
+	}
+	/** Drain: give in-flight requests up to graceMs to complete naturally. */
+	async drainPending(graceMs, remaining) {
+		const drainBudget = Math.min(graceMs, remaining());
+		if (this.dispatcher.pendingCount > 0 && drainBudget > 0) await Promise.race([new Promise((resolve) => {
+			const check = () => {
+				if (this.dispatcher.pendingCount === 0 || remaining() === 0) resolve();
+				else setTimeout(check, 25).unref();
+			};
+			check();
+		}), new Promise((resolve) => setTimeout(resolve, drainBudget).unref())]);
+	}
+	/** Close stdin to signal end-of-input — well-behaved agents exit on EOF. */
+	endStdin() {
+		try {
+			this.child.stdin?.end();
+		} catch (err) {
+			this.logger.debug("stdin.end() threw", { error: err instanceof Error ? err.message : String(err) });
+		}
+	}
+	async awaitStdinEof(remaining) {
+		const eofBudget = Math.min(Math.max(this.policy.stdinCloseGraceMs, 0), remaining());
+		if (eofBudget > 0 && !this.exitReason) {
+			let eofTimer;
+			try {
+				await Promise.race([this.childClosePromise, new Promise((resolve) => {
+					eofTimer = setTimeout(resolve, eofBudget);
+				})]);
+			} finally {
+				if (eofTimer) clearTimeout(eofTimer);
+			}
+		}
+	}
+	/** SIGTERM if still alive, then SIGKILL after another grace window. */
+	terminateChild(graceMs, remaining) {
+		const stillOwned = () => this.owner.ownsProcessGroup || this.child.exitCode === null && this.child.signalCode === null;
+		if (!(stillOwned() && remaining() > 0)) return;
+		this.owner.kill("SIGTERM");
+		const sigkillDelay = Math.min(Math.max(graceMs, 100), remaining());
+		const sigkillTimer = setTimeout(() => {
+			if (stillOwned()) {
+				this.logger.warn("SIGKILL — close grace expired");
+				this.owner.kill("SIGKILL");
+			}
+		}, sigkillDelay);
+		sigkillTimer.unref();
+		this.childClosePromise.then(() => {
+			clearTimeout(sigkillTimer);
+		});
+	}
+};
+//#endregion
+//#region src/rpc-stdio-process.ts
+const DEFAULT_MAX_PENDING = 1024;
+const DEFAULT_MAX_STDERR_BYTES = 65536;
+const DEFAULT_CLOSE_GRACE_MS = 2e3;
+const DEFAULT_REQUEST_TIMEOUT_MS = 6e4;
+const DEFAULT_HARD_CLOSE_DEADLINE_MS = 1e4;
+const noopLogger = {
+	debug: () => {},
+	warn: () => {},
+	error: () => {}
+};
+/**
+* Spawn an RpcBridge over a long-running stdio child process.
+*
+* The bridge is usable immediately after this call — outbound writes
+* before the child has booted are buffered by Node's stdin pipe. Inbound
+* dispatch starts as soon as the child writes its first line.
+*/
+function spawnRpcBridge(config) {
+	const { maxPendingRequests = DEFAULT_MAX_PENDING, maxStderrBytes = DEFAULT_MAX_STDERR_BYTES, defaultRequestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS, defaultCloseGraceMs = DEFAULT_CLOSE_GRACE_MS, hardCloseDeadlineMs = DEFAULT_HARD_CLOSE_DEADLINE_MS, logger = noopLogger, rawCapturePath, rawCapturePerTurn = false, detached = false, stdinCloseGraceMs = 0 } = config;
+	const processEnv = mergeSpawnEnv(process.env, config.env);
+	applyChildToolPath(processEnv);
+	const capture = new RpcByteCapture(rawCapturePath, rawCapturePerTurn, (killSignal) => owner.kill(killSignal), () => owner.captureTree(), () => lifecycle.childError?.message ?? null);
+	let child;
+	let isolatedLaunch;
+	try {
+		({child, isolatedLaunch} = spawnBridgeChild(config, processEnv));
+	} catch (error) {
+		capture.closeAfterSpawnFailure(error);
+		throw error;
+	}
+	const owner = new RpcProcessOwner(child, isolatedLaunch, detached, hardCloseDeadlineMs, logger, (error) => lifecycle.settleProcessError(error));
+	capture.attach(child);
+	const stderr = new StderrTail(maxStderrBytes);
+	const dispatcher = new RpcDispatcher({
+		logger,
+		maxPendingRequests,
+		defaultRequestTimeoutMs,
+		isClosed: () => lifecycle.closed,
+		writeFrame: (envelope) => writeFrame(envelope)
+	});
+	const lifecycle = new RpcLifecycle(child, owner, dispatcher, {
+		defaultCloseGraceMs,
+		hardCloseDeadlineMs,
+		stdinCloseGraceMs
+	}, logger, () => stderr.text);
+	const writeFrame = (envelope) => {
+		if (lifecycle.closed) throw new BridgeClosedError("write after close");
+		if (!child.stdin || child.stdin.destroyed) throw new BridgeClosedError("stdin destroyed");
+		const bytes = Buffer.from(`${JSON.stringify(envelope)}\n`);
+		capture.frame("stdin", bytes);
+		if (capture.error) throw new Error(`stdin capture failed: ${capture.error}`);
+		child.stdin.write(bytes);
+	};
+	attachOutputStreams(child, dispatcher, stderr);
+	lifecycle.attach(child, config.signal);
+	return {
+		captureTurn(path, metadata) {
+			return capture.beginTurn(path, metadata, child.pid, lifecycle.closed);
+		},
+		get pid() {
+			return child.pid;
+		},
+		get closed() {
+			return lifecycle.closed;
+		},
+		get process() {
+			return child;
+		},
+		request(method, params, options) {
+			return dispatcher.request(method, params, options);
+		},
+		notify(method, params) {
+			dispatcher.notify(method, params);
+		},
+		onNotification(method, handler) {
+			return dispatcher.onNotification(method, handler);
+		},
+		onRequest(method, handler) {
+			return dispatcher.onRequest(method, handler);
+		},
+		onClose: (handler) => lifecycle.onClose(handler),
+		close: (graceMs) => lifecycle.close(graceMs),
+		getStderrTail: () => stderr.text
+	};
+}
+/** Start the bridge's child: through the runner for an isolated identity. */
+function spawnBridgeChild(config, processEnv) {
+	const { command, args, cwd, env, uid, gid, isolatedIdentity } = config;
+	if (isolatedIdentity) {
+		const isolatedLaunch = spawnCliProcess({
+			command,
+			args,
+			cwd,
+			env,
+			isolatedIdentity,
+			spawnOptions: {
+				uid: uid ?? isolatedIdentity.uid,
+				gid: gid ?? isolatedIdentity.gid
+			}
+		});
+		return {
+			child: isolatedLaunch.process,
+			isolatedLaunch
+		};
+	}
+	return {
+		child: spawn(command, args, {
+			cwd,
+			env: processEnv,
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			],
+			...uid === void 0 ? {} : { uid },
+			...gid === void 0 ? {} : { gid },
+			detached: (config.detached ?? false) && process.platform !== "win32"
+		}),
+		isolatedLaunch: void 0
+	};
+}
+/** The last `maxBytes` characters of a child's stderr. */
+var StderrTail = class {
+	text = "";
+	constructor(maxBytes) {
+		this.maxBytes = maxBytes;
+	}
+	/** The decoder's final flush is kept whole, past the cap. */
+	appendUntrimmed(chunk) {
+		this.text += chunk;
+	}
+	append(chunk) {
+		this.text += chunk;
+		if (this.text.length > this.maxBytes) this.text = this.text.slice(this.text.length - this.maxBytes);
+	}
+};
+function attachOutputStreams(child, dispatcher, stderr) {
+	const stdoutDecoder = new StringDecoder("utf8");
+	child.stdout?.on("data", (chunk) => dispatcher.consumeStdoutChunk(stdoutDecoder.write(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))));
+	child.stdout?.on("end", () => {
+		const tail = stdoutDecoder.end();
+		if (tail) dispatcher.consumeStdoutChunk(tail);
+	});
+	const stderrDecoder = new StringDecoder("utf8");
+	child.stderr?.on("data", (chunk) => {
+		stderr.append(stderrDecoder.write(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+	});
+	child.stderr?.on("end", () => {
+		stderr.appendUntrimmed(stderrDecoder.end());
+	});
+}
+//#endregion
+//#region src/shell-quote.ts
+function shellQuote(value) {
+	return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+//#endregion
+export { BridgeClosedError, HELD_SPARE_IDLE_MS, InvalidAttachmentError, JsonRpcError, RAW_CAPTURE_ROOT, RAW_CAPTURE_TOTAL_CAP_BYTES, RpcRequestTimeoutError, allowRetainedRawCapture, argAfter, createDeferredParser, createHeldSpareRegistry, createStreamParser, execCli, launchCliProcess, launchDifferences, mergeSpawnEnv, openRawCapture, removeRawCapture, resolveRawCapturePath, shellQuote, spawnCliProcess, spawnRpcBridge, summarizeRawCapture, trimRawCapture, withRawCaptureAttempt };
+
+//# sourceMappingURL=index.mjs.map