@agent-device/proxy 0.0.0-stage → 0.21.23

package/dist/process.mjs

@@ -0,0 +1,1147 @@
+import { i as redactDiagnosticData, n as createRequestCanceledError, t as AppError } from "./errors.mjs";
+import crypto from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
+import fs from "node:fs";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+//#region ../host-kit/src/internal/diagnostics.ts
+const diagnosticsStorage = new AsyncLocalStorage();
+function updateDiagnosticsScope(options) {
+	const scope = diagnosticsStorage.getStore();
+	if (!scope) return;
+	Object.assign(scope, options);
+}
+function getDiagnosticsMeta() {
+	const scope = diagnosticsStorage.getStore();
+	if (!scope) return {};
+	const { diagnosticId, requestId, session, command, debug, flushOnSuccess } = scope;
+	return {
+		diagnosticId,
+		requestId,
+		session,
+		command,
+		debug,
+		flushOnSuccess
+	};
+}
+function emitDiagnostic(event) {
+	const scope = diagnosticsStorage.getStore();
+	if (!scope) return;
+	const payload = {
+		ts: (/* @__PURE__ */ new Date()).toISOString(),
+		level: event.level ?? "info",
+		phase: event.phase,
+		session: scope.session,
+		requestId: scope.requestId,
+		command: scope.command,
+		durationMs: event.durationMs,
+		data: event.data ? redactScopeData(scope, event.data) : void 0
+	};
+	scope.events.push(payload);
+	scope.phaseCounts.set(event.phase, (scope.phaseCounts.get(event.phase) ?? 0) + 1);
+	if (!scope.debug && !scope.traceLogPath) return;
+	const fileLine = `${JSON.stringify(payload)}\n`;
+	try {
+		if (scope.debug && scope.logPath) {
+			appendDiagnosticLine(scope, scope.logPath, fileLine);
+			scope.liveWrittenEventCount = scope.events.length;
+		}
+		if (scope.traceLogPath) appendDiagnosticLine(scope, scope.traceLogPath, fileLine);
+		if (scope.debug && !scope.logPath && !scope.traceLogPath) process.stderr.write(`[agent-device][diag] ${fileLine}`);
+	} catch {}
+}
+/** Longest-first so an overlapping shorter literal cannot truncate a longer one. */
+function sortedScopeSensitiveValues(scope) {
+	scope.sortedSensitiveValues ??= [...scope.sensitiveValues].sort((left, right) => right.length - left.length);
+	return scope.sortedSensitiveValues;
+}
+function redactScopeData(scope, input) {
+	return replaceSensitiveValues(redactDiagnosticData(input), sortedScopeSensitiveValues(scope));
+}
+function replaceSensitiveValues(value, sensitiveValues) {
+	if (typeof value === "string") return sensitiveValues.reduce((output, sensitive) => output.replaceAll(sensitive, "[REDACTED]"), value);
+	if (Array.isArray(value)) return value.map((entry) => replaceSensitiveValues(entry, sensitiveValues));
+	if (!value || typeof value !== "object") return value;
+	return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, replaceSensitiveValues(entry, sensitiveValues)]));
+}
+function appendDiagnosticLine(scope, logPath, line) {
+	const dir = path.dirname(logPath);
+	if (!scope.ensuredDirectories.has(dir)) {
+		fs.mkdirSync(dir, { recursive: true });
+		scope.ensuredDirectories.add(dir);
+	}
+	fs.appendFileSync(logPath, line, "utf8");
+}
+//#endregion
+//#region ../kernel/src/source-value.ts
+const BOOLEAN_TRUE_VALUES = /* @__PURE__ */ new Set([
+	"1",
+	"true",
+	"yes",
+	"on"
+]);
+const BOOLEAN_FALSE_VALUES = /* @__PURE__ */ new Set([
+	"0",
+	"false",
+	"no",
+	"off"
+]);
+function parseBooleanLiteral(value) {
+	const normalized = value.trim().toLowerCase();
+	if (BOOLEAN_TRUE_VALUES.has(normalized)) return true;
+	if (BOOLEAN_FALSE_VALUES.has(normalized)) return false;
+}
+//#endregion
+//#region ../host-kit/src/internal/exec.ts
+const BARE_COMMAND_RE = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;
+const EXEC_DIAGNOSTIC_ARG_LIMIT = 6;
+const commandExecutorOverrideScope = new AsyncLocalStorage();
+const requestCommandEnvScope = new AsyncLocalStorage();
+/** Effective toolchain selection; an explicitly empty request value selects `xcode-select`. */
+function commandDeveloperDir() {
+	const requestEnv = requestCommandEnvScope.getStore();
+	if (requestEnv && Object.hasOwn(requestEnv, "DEVELOPER_DIR")) return requestEnv.DEVELOPER_DIR || void 0;
+	return process.env.DEVELOPER_DIR || void 0;
+}
+function resolveSpawnEnv(env) {
+	const requestEnv = requestCommandEnvScope.getStore();
+	if (!requestEnv) return env;
+	return {
+		...env ?? process.env,
+		...requestEnv
+	};
+}
+async function runCmd(cmd, args, options = {}) {
+	const overrideResult = commandExecutorOverrideScope.getStore()?.(cmd, args, options);
+	if (overrideResult) return coerceExecResult(await overrideResult);
+	return await runSpawnedCommand(cmd, args, options);
+}
+/**
+* Normalize an exec result produced outside this module. Tool providers,
+* executor overrides, and SDK-supplied adb executors are plain callbacks whose
+* results cross an unchecked boundary; coercing once here lets downstream code
+* trust the ExecResult types instead of re-wrapping fields defensively at every
+* use. A non-number exitCode coerces to 1 — the same failure branch such a
+* result already landed in at every `exitCode !== 0` guard.
+*/
+function coerceExecResult(result) {
+	const stdout = typeof result.stdout === "string" ? result.stdout : String(result.stdout ?? "");
+	const stderr = typeof result.stderr === "string" ? result.stderr : String(result.stderr ?? "");
+	const exitCode = typeof result.exitCode === "number" ? result.exitCode : 1;
+	if (stdout === result.stdout && stderr === result.stderr && exitCode === result.exitCode) return result;
+	return {
+		...result,
+		stdout,
+		stderr,
+		exitCode
+	};
+}
+function runSpawnedCommand(cmd, args, options = {}) {
+	const executable = normalizeExecutableCommand(cmd);
+	const execTrace = createExecTraceContext();
+	return new Promise((resolve, reject) => {
+		const child = spawn(executable, args, {
+			cwd: options.cwd,
+			env: resolveSpawnEnv(options.env),
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			],
+			detached: options.detached,
+			windowsHide: true,
+			shell: false
+		});
+		options.onSpawn?.(child);
+		let stdout = "";
+		const stdoutChunks = options.binaryStdout ? [] : void 0;
+		let stderr = "";
+		let didTimeout = false;
+		const timeoutMs = normalizeTimeoutMs(options.timeoutMs);
+		let timeoutHandle = null;
+		let settled = false;
+		function finish() {
+			if (settled) return false;
+			settled = true;
+			if (timeoutHandle) clearTimeout(timeoutHandle);
+			abort.dispose();
+			destroyCommandStreams(child);
+			execTrace.emitForegroundCompletion(cmd, args);
+			return true;
+		}
+		function fail(error) {
+			if (finish()) reject(error);
+		}
+		function settle(code) {
+			if (!finish()) return;
+			const finalExitCode = code ?? 1;
+			if (!abort.didAbort && didTimeout && timeoutMs) {
+				reject(createTimeoutError(executable, cmd, args, timeoutMs, finalExitCode, stdout, stderr));
+				return;
+			}
+			const failure = commandCloseFailure(abort, executable, cmd, args, finalExitCode, options.allowFailure, stdout, stderr);
+			if (failure) {
+				reject(failure);
+				return;
+			}
+			resolve({
+				stdout,
+				stderr,
+				exitCode: finalExitCode,
+				stdoutBuffer: stdoutChunks ? Buffer.concat(stdoutChunks) : void 0
+			});
+		}
+		const settlement = createCommandKillSettlement({
+			killProcessTree: () => killProcessTree(child, options),
+			settle
+		});
+		const abort = watchCommandAbort(options, settlement.requestKill);
+		timeoutHandle = timeoutMs ? setTimeout(() => {
+			didTimeout = true;
+			settlement.requestKill();
+		}, timeoutMs) : null;
+		if (!options.binaryStdout) child.stdout.setEncoding("utf8");
+		child.stderr.setEncoding("utf8");
+		writeChildStdin(child, options.stdin).catch((error) => {
+			if (abort.didAbort || didTimeout) return;
+			if (isEpipeError(error)) return;
+			fail(createStdinError(executable, cmd, args, error));
+			killProcessTree(child, options);
+		});
+		child.stdout.on("data", (chunk) => {
+			if (options.binaryStdout) {
+				stdoutChunks?.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+				return;
+			}
+			const text = String(chunk);
+			stdout += text;
+			options.onStdoutChunk?.(text);
+		});
+		child.stderr.on("data", (chunk) => {
+			const text = String(chunk);
+			stderr += text;
+			options.onStderrChunk?.(text);
+		});
+		child.on("error", (err) => {
+			fail(spawnRejectionError(abort, executable, cmd, args, err));
+		});
+		child.once("exit", settlement.recordExit);
+		child.once("close", settle);
+	});
+}
+function runCmdSync(cmd, args, options = {}) {
+	const executable = normalizeExecutableCommand(cmd);
+	const result = spawnSync(executable, args, {
+		cwd: options.cwd,
+		env: resolveSpawnEnv(options.env),
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		],
+		encoding: options.binaryStdout ? void 0 : "utf8",
+		input: options.stdin,
+		timeout: normalizeTimeoutMs(options.timeoutMs),
+		windowsHide: true,
+		shell: false,
+		...options.maxBuffer !== void 0 ? { maxBuffer: options.maxBuffer } : {}
+	});
+	if (result.error) {
+		const code = result.error.code;
+		if (code === "ETIMEDOUT") throw new AppError("COMMAND_FAILED", `${executable} timed out after ${normalizeTimeoutMs(options.timeoutMs)}ms`, {
+			cmd,
+			args,
+			timeoutMs: normalizeTimeoutMs(options.timeoutMs)
+		}, result.error);
+		if (code === "ENOENT") throw createMissingToolError(executable, cmd, result.error);
+		throw createCommandFailedError(executable, cmd, args, result.error);
+	}
+	const stdoutBuffer = options.binaryStdout ? Buffer.isBuffer(result.stdout) ? result.stdout : Buffer.from(result.stdout ?? "") : void 0;
+	const stdout = options.binaryStdout ? "" : typeof result.stdout === "string" ? result.stdout : (result.stdout ?? "").toString();
+	const stderr = typeof result.stderr === "string" ? result.stderr : (result.stderr ?? "").toString();
+	const exitCode = result.status ?? 1;
+	if (exitCode !== 0 && !options.allowFailure) throw createExitError(executable, cmd, args, exitCode, stdout, stderr);
+	return {
+		stdout,
+		stderr,
+		exitCode,
+		stdoutBuffer
+	};
+}
+function createExecTraceContext() {
+	const diagnosticsMeta = getDiagnosticsMeta();
+	const diagnosticsDebugEnabled = diagnosticsMeta.debug === true;
+	const envTraceEnabled = parseBooleanLiteral(process.env.AGENT_DEVICE_EXEC_TRACE ?? "") === true;
+	if (!diagnosticsDebugEnabled && !envTraceEnabled) return createDisabledExecTraceContext();
+	if (envTraceEnabled && diagnosticsMeta.flushOnSuccess !== true) updateDiagnosticsScope({ flushOnSuccess: true });
+	const startedAtMs = Date.now();
+	let completionEmitted = false;
+	return {
+		emitForegroundCompletion: (cmd, args) => {
+			if (completionEmitted) return;
+			completionEmitted = true;
+			emitExecCommandDiagnostic({
+				cmd,
+				args,
+				startedAtMs
+			});
+		},
+		emitBackgroundSpawn: (cmd, args) => {
+			emitExecCommandDiagnostic({
+				cmd,
+				args,
+				data: { event: "spawn" }
+			});
+		},
+		emitBackgroundCompletion: (cmd, args, event) => {
+			if (completionEmitted) return;
+			completionEmitted = true;
+			emitExecCommandDiagnostic({
+				cmd,
+				args,
+				startedAtMs,
+				data: { event }
+			});
+		}
+	};
+}
+function createDisabledExecTraceContext() {
+	return {
+		emitForegroundCompletion: () => {},
+		emitBackgroundSpawn: () => {},
+		emitBackgroundCompletion: () => {}
+	};
+}
+function emitExecCommandDiagnostic(params) {
+	const argsPrefix = params.args.slice(0, EXEC_DIAGNOSTIC_ARG_LIMIT);
+	emitDiagnostic({
+		level: "debug",
+		phase: "exec_command",
+		durationMs: params.startedAtMs === void 0 ? void 0 : Math.max(0, Date.now() - params.startedAtMs),
+		data: {
+			command: params.cmd,
+			argsPrefix,
+			...params.args.length > argsPrefix.length ? { omittedArgCount: params.args.length - argsPrefix.length } : {},
+			...params.data ?? {}
+		}
+	});
+}
+function normalizeExecutableCommand(cmd) {
+	const candidate = normalizeExecutableLookup(cmd);
+	if (!candidate) throw new AppError("INVALID_ARGS", `Invalid executable command: ${JSON.stringify(cmd)}`, {
+		cmd,
+		hint: "Use a bare command name from PATH or an absolute executable path."
+	});
+	return candidate;
+}
+function createSpawnError(executable, cmd, args, err) {
+	if (err.code === "ENOENT") return createMissingToolError(executable, cmd, err);
+	return createCommandFailedError(executable, cmd, args, err);
+}
+function createMissingToolError(executable, cmd, cause) {
+	return new AppError("TOOL_MISSING", `${executable} not found in PATH`, { cmd }, cause);
+}
+function createCommandFailedError(executable, cmd, args, cause) {
+	return new AppError("COMMAND_FAILED", `Failed to run ${executable}`, {
+		cmd,
+		args
+	}, cause);
+}
+function createStdinError(executable, cmd, args, cause) {
+	return new AppError("COMMAND_FAILED", `Failed to write stdin for ${executable}`, {
+		cmd,
+		args
+	}, cause instanceof Error ? cause : void 0);
+}
+function createCommandCanceledError(executable, cmd, args) {
+	return createRequestCanceledError({
+		cmd,
+		args,
+		executable
+	});
+}
+function createTimeoutError(executable, cmd, args, timeoutMs, exitCode, stdout, stderr) {
+	return new AppError("COMMAND_FAILED", `${executable} timed out after ${timeoutMs}ms`, {
+		cmd,
+		args,
+		stdout,
+		stderr,
+		exitCode,
+		timeoutMs
+	});
+}
+function createExitError(executable, cmd, args, exitCode, stdout, stderr) {
+	return new AppError("COMMAND_FAILED", `${executable} exited with code ${exitCode}`, execFailureDetails({
+		stdout,
+		stderr,
+		exitCode
+	}, {
+		cmd,
+		args
+	}));
+}
+const XCRUN_TOOL_NOT_FOUND_STDERR = /xcrun: error: unable to find utility "([^"]+)"/;
+function xcrunToolNotFoundDetails(stderr) {
+	const tool = XCRUN_TOOL_NOT_FOUND_STDERR.exec(stderr)?.[1];
+	if (!tool) return {};
+	const developerDir = commandDeveloperDir();
+	const source = developerDir ? `DEVELOPER_DIR ${developerDir}` : "the developer dir selected by xcode-select (see xcode-select -p)";
+	return {
+		reason: "xcrun-tool-not-found",
+		developerDir: developerDir ?? null,
+		hint: `xcrun could not find ${tool} in ${source}. Export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer (or your Xcode's path) before running agent-device, or run sudo xcode-select -s /Applications/Xcode.app.`
+	};
+}
+/**
+* Exit-failure details for normalizeError, including null exit codes from signalled processes.
+*/
+function execFailureDetails(result, extra) {
+	return {
+		stdout: result.stdout,
+		stderr: result.stderr,
+		exitCode: result.exitCode,
+		processExitError: true,
+		...extra,
+		...xcrunToolNotFoundDetails(result.stderr)
+	};
+}
+function spawnRejectionError(abort, executable, cmd, args, err) {
+	return abort.didAbort ? createCommandCanceledError(executable, cmd, args) : createSpawnError(executable, cmd, args, err);
+}
+function commandCloseFailure(abort, executable, cmd, args, exitCode, allowFailure, stdout, stderr) {
+	if (abort.didAbort) return createCommandCanceledError(executable, cmd, args);
+	if (exitCode !== 0 && !allowFailure) return createExitError(executable, cmd, args, exitCode, stdout, stderr);
+	return null;
+}
+function normalizeExecutableLookup(cmd) {
+	const candidate = cmd.trim();
+	if (!candidate || candidate.includes("\0")) return null;
+	if (path.isAbsolute(candidate)) return candidate;
+	if (candidate.includes("/") || candidate.includes("\\")) return null;
+	return BARE_COMMAND_RE.test(candidate) ? candidate : null;
+}
+function normalizeTimeoutMs(value) {
+	if (!Number.isFinite(value)) return void 0;
+	const timeout = Math.floor(value);
+	if (timeout <= 0) return void 0;
+	return timeout;
+}
+function createCommandKillSettlement(input) {
+	let killRequested = false;
+	let exited = false;
+	let exitCode = null;
+	const settleIfKilledAndGone = () => {
+		if (killRequested && exited) input.settle(exitCode);
+	};
+	return {
+		requestKill: () => {
+			killRequested = true;
+			input.killProcessTree();
+			settleIfKilledAndGone();
+		},
+		recordExit: (code) => {
+			exited = true;
+			exitCode = code ?? 1;
+			settleIfKilledAndGone();
+		}
+	};
+}
+function watchCommandAbort(options, onKill) {
+	let didAbort = false;
+	const onAbort = () => {
+		didAbort = true;
+		onKill();
+	};
+	if (options.signal?.aborted) onAbort();
+	else options.signal?.addEventListener("abort", onAbort, { once: true });
+	return {
+		get didAbort() {
+			return didAbort;
+		},
+		dispose: () => {
+			options.signal?.removeEventListener("abort", onAbort);
+		}
+	};
+}
+/**
+* Best-effort process-group signalling, shared by host-kit callers. This lives below
+* host-process.ts to avoid an import cycle. Only positive integer pids are accepted:
+* zero targets this process's group, and negative values can target unrelated processes.
+*/
+function signalProcessGroupBestEffort(pid, signal) {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(-pid, signal);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function killProcessTree(child, options) {
+	if (!options.kill) {
+		signalProcessTree(child, options.detached, "SIGKILL");
+		return;
+	}
+	signalProcessTree(child, options.detached, options.kill.signal);
+	const escalation = setTimeout(() => signalProcessTree(child, options.detached, "SIGKILL"), options.kill.graceMs);
+	escalation.unref();
+	child.once("exit", () => clearTimeout(escalation));
+}
+function signalProcessTree(child, detached, signal) {
+	if (detached && child.pid && process.platform !== "win32") {
+		signalProcessGroupBestEffort(child.pid, signal);
+		return;
+	}
+	if (child.exitCode !== null || child.signalCode !== null) return;
+	child.kill(signal);
+}
+/**
+* A kill that cannot reach an inherited-pipe holder must at least stop this process
+* from holding the other end of those pipes open after it has settled.
+*/
+function destroyCommandStreams(child) {
+	child.stdin?.destroy();
+	child.stdout?.destroy();
+	child.stderr?.destroy();
+}
+async function writeChildStdin(child, stdin) {
+	if (!child.stdin) return;
+	if (stdin === void 0) {
+		child.stdin?.end();
+		return;
+	}
+	await pipeline(Readable.from([stdin]), child.stdin);
+}
+function isEpipeError(error) {
+	return error instanceof Error && "code" in error && error.code === "EPIPE";
+}
+//#endregion
+//#region ../host-kit/src/internal/timeouts.ts
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//#endregion
+//#region ../host-kit/src/internal/host-process.ts
+const PS_TIMEOUT_MS = 1e3;
+const HOST_PS_COMMAND = process.platform === "win32" ? "ps" : "/bin/ps";
+function hostEnvironment() {
+	return process.env;
+}
+function readHostEnvironmentVariable(name) {
+	return hostEnvironment()[name];
+}
+function writeHostStderr(value) {
+	process.stderr.write(value);
+}
+function hostCurrentWorkingDirectory() {
+	return process.cwd();
+}
+function hostNodeExecutablePath() {
+	return process.execPath;
+}
+function hostNodeVersion() {
+	return process.version;
+}
+function hostPlatform() {
+	return process.platform;
+}
+function hostProcessId() {
+	return process.pid;
+}
+function isProcessAlive(pid) {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error.code === "EPERM";
+	}
+}
+function isProcessGroupAlive(pid) {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(-pid, 0);
+		return true;
+	} catch (error) {
+		return error.code === "EPERM";
+	}
+}
+/**
+* Reads who owns a pid, off the event loop, with a budget the caller names. The three fields
+* are read concurrently so a loaded host pays one budget for the set rather than one per
+* field. Use this rather than the synchronous probes when the answer decides whether a
+* process is signaled: waiting is reversible and signaling the wrong process is not.
+*/
+async function readProcessIdentityFacts(pid, timeoutMs = PS_TIMEOUT_MS) {
+	const [startTime, command, state] = await Promise.all([
+		readProcessFieldAsync(pid, "lstart=", timeoutMs),
+		readProcessFieldAsync(pid, "command=", timeoutMs),
+		readProcessFieldAsync(pid, "state=", timeoutMs)
+	]);
+	return {
+		startTime,
+		command,
+		zombie: state === null ? null : state.startsWith("Z")
+	};
+}
+function readProcessStartTime(pid) {
+	return readProcessField(pid, "lstart=");
+}
+function readProcessCommand(pid) {
+	return readProcessField(pid, "command=");
+}
+function isProcessZombie(pid) {
+	return readProcessField(pid, "state=")?.startsWith("Z") ?? false;
+}
+function readHostProcessIdentityObservations(pids) {
+	const observations = /* @__PURE__ */ new Map();
+	const selected = uniquePositivePids(pids);
+	if (selected.length === 0) return observations;
+	try {
+		const result = runCmdSync("ps", [
+			"-p",
+			selected.join(","),
+			"-o",
+			"pid=,state=,lstart="
+		], {
+			allowFailure: true,
+			timeoutMs: PS_TIMEOUT_MS
+		});
+		if (result.exitCode !== 0) return observations;
+		for (const line of result.stdout.split("\n")) {
+			const match = /^\s*(\d+)\s+(\S+)\s+(.+?)\s*$/.exec(line);
+			if (!match) continue;
+			const pid = Number.parseInt(match[1], 10);
+			if (!Number.isInteger(pid) || pid <= 0) continue;
+			observations.set(pid, {
+				state: match[2],
+				startTime: match[3]
+			});
+		}
+	} catch {}
+	return observations;
+}
+function readProcessField(pid, field) {
+	if (!Number.isInteger(pid) || pid <= 0) return null;
+	try {
+		return processFieldValue(runCmdSync(HOST_PS_COMMAND, [
+			"-p",
+			String(pid),
+			"-o",
+			field
+		], {
+			allowFailure: true,
+			timeoutMs: PS_TIMEOUT_MS
+		}));
+	} catch {
+		return null;
+	}
+}
+async function readProcessFieldAsync(pid, field, timeoutMs) {
+	if (!Number.isInteger(pid) || pid <= 0) return null;
+	try {
+		return processFieldValue(await runCmd(HOST_PS_COMMAND, [
+			"-p",
+			String(pid),
+			"-o",
+			field
+		], {
+			allowFailure: true,
+			timeoutMs
+		}));
+	} catch {
+		return null;
+	}
+}
+function processFieldValue(result) {
+	if (result.exitCode !== 0) return null;
+	const value = result.stdout.trim();
+	return value.length > 0 ? value : null;
+}
+function parseHostProcessList(stdout) {
+	const processes = [];
+	for (const line of stdout.split("\n")) {
+		const match = /^\s*(\d+)\s+(\d+)\s+(.+?)\s*$/.exec(line);
+		if (!match) continue;
+		const pid = Number.parseInt(match[1], 10);
+		const ppid = Number.parseInt(match[2], 10);
+		const command = match[3];
+		if (!Number.isInteger(pid) || pid <= 0) continue;
+		processes.push({
+			pid,
+			ppid: Number.isInteger(ppid) && ppid > 0 ? ppid : void 0,
+			command
+		});
+	}
+	return processes;
+}
+async function listHostProcesses(options) {
+	const result = await (options.runCommand ?? runCmd)(options.runCommand ? "ps" : HOST_PS_COMMAND, [
+		"-ax",
+		"-o",
+		"pid=,ppid=,command="
+	], {
+		allowFailure: true,
+		timeoutMs: options.timeoutMs
+	});
+	if (result.exitCode !== 0) return [];
+	return parseHostProcessList(result.stdout);
+}
+function expandProcessTree(rootPids, processes) {
+	const selected = new Set(uniquePositivePids(rootPids));
+	let changed = true;
+	while (changed) {
+		changed = false;
+		for (const processInfo of processes) {
+			if (processInfo.ppid === void 0 || !selected.has(processInfo.ppid)) continue;
+			if (selected.has(processInfo.pid)) continue;
+			selected.add(processInfo.pid);
+			changed = true;
+		}
+	}
+	return processes.filter((processInfo) => selected.has(processInfo.pid));
+}
+function uniquePositivePids(values, options = {}) {
+	return [...new Set(values)].filter((pid) => Number.isInteger(pid) && pid > 0 && pid !== options.excludePid);
+}
+function signalPidsBestEffort(pidsToSignal, signal) {
+	const pids = uniquePositivePids(pidsToSignal, { excludePid: process.pid });
+	let signaled = 0;
+	for (const pid of pids) try {
+		process.kill(pid, signal);
+		signaled += 1;
+	} catch {}
+	return signaled;
+}
+async function waitForProcessExit(pid, timeoutMs) {
+	if (!isProcessAlive(pid)) return true;
+	const start = Date.now();
+	while (Date.now() - start < timeoutMs) {
+		await sleep(50);
+		if (!isProcessAlive(pid)) return true;
+	}
+	return !isProcessAlive(pid);
+}
+async function stopPidsWithEscalation(options) {
+	const pids = uniquePositivePids(options.pids, { excludePid: process.pid });
+	if (pids.length === 0) return;
+	signalPidsBestEffort(pids, "SIGTERM");
+	await Promise.all(pids.map(async (pid) => await waitForProcessExit(pid, options.termTimeoutMs)));
+	signalPidsBestEffort(pids.filter((pid) => isProcessAlive(pid)), "SIGKILL");
+	await Promise.all(pids.map(async (pid) => await waitForProcessExit(pid, options.killTimeoutMs)));
+}
+const SYSCTL_TIMEOUT_MS = 1e3;
+const APPLE_SILICON_SYSCTL = ["-n", "hw.optional.arm64"];
+let pendingHostCpuArch;
+let settledHostCpuArch;
+/**
+* The machine's native CPU architecture in Apple naming (`arm64`, `x86_64`), which is what
+* simulators on a Mac run by default. Other CPUs keep Node's `process.arch` name. Resolved once
+* per process.
+*/
+function readHostCpuArch() {
+	if (settledHostCpuArch !== void 0) return Promise.resolve(settledHostCpuArch);
+	pendingHostCpuArch ??= resolveHostCpuArch(process.platform, process.arch).then(settleHostCpuArch);
+	return pendingHostCpuArch;
+}
+/**
+* {@link readHostCpuArch} for a caller that cannot await. It shares the same per-process value,
+* resolving it with a blocking `sysctl` only when nothing has resolved it yet.
+*/
+function readHostCpuArchSync() {
+	return settledHostCpuArch ?? settleHostCpuArch(hostCpuArchName(process.platform === "darwin" && isAppleSiliconMacSync(), process.arch));
+}
+function settleHostCpuArch(arch) {
+	settledHostCpuArch ??= arch;
+	return settledHostCpuArch;
+}
+async function resolveHostCpuArch(platform, nodeArch) {
+	return hostCpuArchName(platform === "darwin" && await isAppleSiliconMac(), nodeArch);
+}
+function hostCpuArchName(appleSilicon, nodeArch) {
+	if (appleSilicon) return "arm64";
+	return nodeArch === "x64" ? "x86_64" : nodeArch;
+}
+async function isAppleSiliconMac() {
+	try {
+		const result = await runCmd("/usr/sbin/sysctl", APPLE_SILICON_SYSCTL, {
+			allowFailure: true,
+			timeoutMs: SYSCTL_TIMEOUT_MS
+		});
+		return result.exitCode === 0 && result.stdout.trim() === "1";
+	} catch {
+		return false;
+	}
+}
+function isAppleSiliconMacSync() {
+	try {
+		const result = runCmdSync("/usr/sbin/sysctl", APPLE_SILICON_SYSCTL, {
+			allowFailure: true,
+			timeoutMs: SYSCTL_TIMEOUT_MS
+		});
+		return result.exitCode === 0 && result.stdout.trim() === "1";
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region ../host-kit/src/internal/owned-process-reaper.ts
+const DEFAULT_TERM_TIMEOUT_MS = 1500;
+const DEFAULT_KILL_TIMEOUT_MS = 1e3;
+async function reapOwnedProcessRecordsAtStartup(store, options = {}) {
+	const summary = createReapSummary();
+	const policy = createReapPolicy(options);
+	for (const entry of store.read()) {
+		if (!isDecodedRecord(entry)) continue;
+		const retained = await reapDecodedEntry(entry, policy, summary);
+		if (retained.length === 0) store.clear(entry.scope);
+		else if (retained.length !== entry.records.length) store.replace(entry.scope, retained);
+	}
+	return Object.freeze(summary);
+}
+function isDecodedRecord(entry) {
+	return entry.status === "decoded";
+}
+function createReapSummary() {
+	return {
+		inspected: 0,
+		inspectedPids: [],
+		terminated: 0,
+		terminatedPids: [],
+		missing: 0,
+		missingPids: [],
+		ownershipLost: 0,
+		ownershipLostPids: [],
+		skippedForOpenWebSession: false
+	};
+}
+function createReapPolicy(options) {
+	return {
+		openWebSession: (options.openWebSessionNames ?? []).length > 0,
+		purposes: options.purposes ? new Set(options.purposes) : void 0,
+		termTimeoutMs: options.termTimeoutMs ?? DEFAULT_TERM_TIMEOUT_MS,
+		killTimeoutMs: options.killTimeoutMs ?? DEFAULT_KILL_TIMEOUT_MS
+	};
+}
+async function reapDecodedEntry(entry, policy, summary) {
+	const retained = [];
+	for (const record of entry.records) {
+		if (shouldRetainWithoutInspection(entry.scope.kind, record, policy)) {
+			retained.push(record);
+			if (isOpenWebSessionSkip(entry.scope.kind, record, policy)) summary.skippedForOpenWebSession = true;
+			continue;
+		}
+		summary.inspected += 1;
+		summary.inspectedPids.push(record.pid);
+		appendReapOutcome(summary, record, await reapOwnedProcess(record, policy), retained);
+	}
+	return retained;
+}
+function shouldRetainWithoutInspection(scope, record, policy) {
+	return !isSelectedPurpose(record, policy) || isOpenWebSessionSkip(scope, record, policy);
+}
+function isSelectedPurpose(record, policy) {
+	return policy.purposes === void 0 || policy.purposes.has(record.purpose);
+}
+function isOpenWebSessionSkip(scope, record, policy) {
+	return scope === "daemon" && record.purpose === "managed-web-browser" && policy.openWebSession;
+}
+function appendReapOutcome(summary, record, outcome, retained) {
+	if (outcome === "terminated") {
+		summary.terminated += 1;
+		summary.terminatedPids.push(record.pid);
+		return;
+	}
+	if (outcome === "missing") {
+		summary.missing += 1;
+		summary.missingPids.push(record.pid);
+		return;
+	}
+	summary.ownershipLost += 1;
+	summary.ownershipLostPids.push(record.pid);
+	retained.push(record);
+}
+async function reapOwnedProcess(record, policy) {
+	const initial = inspectOwnedProcess(record);
+	if (initial !== void 0) return initial;
+	signalBestEffort(record.pid, initialSignalFor(record));
+	return await escalateOwnedProcess(record, policy);
+}
+function inspectOwnedProcess(record) {
+	if (record.pid === process.pid || !isProcessAlive(record.pid) || isProcessZombie(record.pid)) return "missing";
+	return matchesRecord(record) ? void 0 : "ownership-lost";
+}
+function initialSignalFor(record) {
+	return record.purpose === "simctl-screen-recording" ? "SIGINT" : "SIGTERM";
+}
+async function escalateOwnedProcess(record, policy) {
+	const termOutcome = await waitForOwnedProcessExit(record, policy.termTimeoutMs);
+	if (termOutcome === "exited") return "terminated";
+	if (termOutcome === "ownership-lost") return "ownership-lost";
+	signalBestEffort(record.pid, "SIGKILL");
+	return await waitForOwnedProcessExit(record, policy.killTimeoutMs) === "exited" ? "terminated" : "ownership-lost";
+}
+async function waitForOwnedProcessExit(record, timeoutMs) {
+	await waitForProcessExit(record.pid, timeoutMs);
+	if (!isProcessAlive(record.pid) || isProcessZombie(record.pid)) return "exited";
+	return matchesRecord(record) ? "owned-alive" : "ownership-lost";
+}
+function matchesRecord(record) {
+	return readProcessStartTime(record.pid) === record.startTime && readProcessCommand(record.pid) === record.command;
+}
+function signalBestEffort(pid, signal) {
+	try {
+		process.kill(pid, signal);
+	} catch {}
+}
+//#endregion
+//#region ../host-kit/src/internal/atomic-file.ts
+/**
+* Gives a specialized durable publisher a canonical temp path and cleanup
+* ownership while it performs its own open/fsync/safety protocol.
+*/
+function withAtomicPublishTempPathSync(destination, publish) {
+	const temporaryPath = createAtomicPublishTempPath(destination);
+	try {
+		return publish(temporaryPath);
+	} finally {
+		try {
+			fs.rmSync(temporaryPath, { force: true });
+		} catch (error) {
+			emitDiagnostic({
+				level: "warn",
+				phase: "atomic_file_cleanup_failed",
+				data: {
+					destination,
+					temporaryPath,
+					error: error instanceof Error ? error.message : String(error)
+				}
+			});
+		}
+	}
+}
+/** Returns the canonical same-directory temp path used by atomic publishers. */
+function createAtomicPublishTempPath(destination) {
+	return path.join(path.dirname(destination), `.${path.basename(destination)}.${process.pid}-${crypto.randomUUID()}.tmp`);
+}
+//#endregion
+//#region ../host-kit/src/internal/owned-process-record.ts
+const RECORD_FILE_NAME = "owned-processes.json";
+const RECORD_VERSION = 1;
+function createOwnedProcessRecordStore(options) {
+	const stateDir = path.resolve(options.stateDir);
+	const sessionsDir = path.resolve(options.sessionsDir);
+	const daemonPath = path.join(stateDir, RECORD_FILE_NAME);
+	const resolvePath = (scope) => {
+		if (scope.kind === "daemon") return daemonPath;
+		const sessionDir = path.resolve(options.resolveSessionDir(scope.sessionId));
+		if (path.dirname(sessionDir) !== sessionsDir) throw new TypeError("owned process session scope must resolve directly under the sessions dir");
+		return path.join(sessionDir, RECORD_FILE_NAME);
+	};
+	return Object.freeze({
+		replace(scope, records) {
+			const normalized = normalizeRecords(records);
+			const recordPath = resolvePath(scope);
+			if (normalized.length === 0) {
+				clearRecordPath(recordPath);
+				return;
+			}
+			const directory = path.dirname(recordPath);
+			fs.mkdirSync(directory, { recursive: true });
+			withAtomicPublishTempPathSync(recordPath, (temporaryPath) => {
+				const descriptor = fs.openSync(temporaryPath, "wx", 384);
+				try {
+					fs.writeFileSync(descriptor, `${JSON.stringify({
+						version: RECORD_VERSION,
+						processes: normalized
+					})}\n`, "utf8");
+					fs.fsyncSync(descriptor);
+				} finally {
+					fs.closeSync(descriptor);
+				}
+				assertSafeRecordDestination(recordPath);
+				fs.renameSync(temporaryPath, recordPath);
+			});
+		},
+		clear(scope) {
+			clearRecordPath(resolvePath(scope));
+		},
+		read() {
+			return readRecordFiles(sessionsDir, daemonPath);
+		}
+	});
+}
+function readOwnedProcessRecordFile(recordPath, scope) {
+	let value;
+	try {
+		assertSafeRecordDestination(recordPath);
+		value = JSON.parse(fs.readFileSync(recordPath, "utf8"));
+	} catch (error) {
+		return {
+			scope,
+			path: recordPath,
+			status: "invalid",
+			records: [],
+			message: errorMessage(error)
+		};
+	}
+	if (!isRecordFile(value)) return {
+		scope,
+		path: recordPath,
+		status: "invalid",
+		records: [],
+		message: "owned process record must contain version 1 and a processes array"
+	};
+	try {
+		return {
+			scope,
+			path: recordPath,
+			status: "decoded",
+			records: normalizeRecords(value.processes)
+		};
+	} catch (error) {
+		return {
+			scope,
+			path: recordPath,
+			status: "invalid",
+			records: [],
+			message: errorMessage(error)
+		};
+	}
+}
+function readRecordFiles(sessionsDir, daemonPath) {
+	const entries = [];
+	if (fileExists(daemonPath)) entries.push(readOwnedProcessRecordFile(daemonPath, { kind: "daemon" }));
+	if (!fs.existsSync(sessionsDir)) return entries;
+	for (const entry of fs.readdirSync(sessionsDir, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+		if (!entry.isDirectory()) continue;
+		const recordPath = path.join(sessionsDir, entry.name, RECORD_FILE_NAME);
+		if (fileExists(recordPath)) entries.push(readOwnedProcessRecordFile(recordPath, {
+			kind: "session",
+			sessionId: entry.name
+		}));
+	}
+	return entries;
+}
+function normalizeRecords(records) {
+	const seen = /* @__PURE__ */ new Set();
+	const normalized = [];
+	for (const record of records) {
+		if (!isValidOwnedProcessRecord(record)) throw new TypeError("owned process record has an invalid identity or purpose");
+		if (seen.has(record.pid)) throw new TypeError(`duplicate owned process pid ${record.pid}`);
+		seen.add(record.pid);
+		normalized.push(Object.freeze({
+			pid: record.pid,
+			startTime: record.startTime,
+			command: record.command,
+			purpose: record.purpose
+		}));
+	}
+	return normalized.sort((left, right) => left.pid - right.pid);
+}
+function isValidOwnedProcessRecord(record) {
+	return Number.isInteger(record.pid) && record.pid > 0 && typeof record.startTime === "string" && record.startTime.length > 0 && typeof record.command === "string" && record.command.length > 0 && typeof record.purpose === "string" && record.purpose.length > 0;
+}
+function isRecordFile(value) {
+	return typeof value === "object" && value !== null && "version" in value && value.version === RECORD_VERSION && "processes" in value && Array.isArray(value.processes);
+}
+function clearRecordPath(recordPath) {
+	try {
+		assertSafeRecordDestination(recordPath);
+		fs.unlinkSync(recordPath);
+	} catch (error) {
+		if (!isMissingFile(error)) throw error;
+	}
+}
+function assertSafeRecordDestination(recordPath) {
+	try {
+		const stats = fs.lstatSync(recordPath);
+		if (stats.isSymbolicLink()) throw new Error("Refusing to follow an owned process record symlink");
+		if (!stats.isFile()) throw new Error("Owned process record is not a regular file");
+	} catch (error) {
+		if (!isMissingFile(error)) throw error;
+	}
+}
+function fileExists(filePath) {
+	try {
+		return fs.lstatSync(filePath).isFile();
+	} catch {
+		return false;
+	}
+}
+function isMissingFile(error) {
+	return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : "owned process record is invalid";
+}
+//#endregion
+//#region ../host-kit/src/internal/owner-identity.ts
+/** A process id accepted by Node's native signal API. */
+function isProcessPid(value) {
+	return typeof value === "number" && Number.isInteger(value) && value > 0 && value <= 2147483647;
+}
+function readCurrentOwnerIdentity() {
+	return {
+		pid: process.pid,
+		startTime: readProcessStartTime(process.pid)
+	};
+}
+function ownerIdentityMatches(left, right) {
+	return left.pid === right.pid && left.startTime === right.startTime;
+}
+/**
+* Positive proof that two records name DIFFERENT processes. Deliberately not
+* the negation of {@link ownerIdentityMatches}: equal pids with an unreadable
+* start time on either side are unproven rather than different, so a caller
+* that acts on this can never mistake one owner for two and hand its resource
+* away.
+*/
+function ownerIdentityDiffers(left, right) {
+	if (left.pid !== right.pid) return true;
+	return Boolean(left.startTime && right.startTime && left.startTime !== right.startTime);
+}
+/**
+* This is deliberately proof-oriented, in both directions. A filesystem read
+* error is not proof that an owner state directory disappeared, so callers
+* must surface it as an unknown owner rather than treating the resource as
+* free. Likewise a failed `ps` read (it shells out with a short timeout and
+* loses under CPU contention) is not proof the owner died, so it never
+* condemns a pid that kill(pid, 0) says is alive. Death is only concluded
+* from positive evidence: the pid is gone or the process is a zombie (already
+* terminated, merely unreaped). A different readable start time proves PID
+* reuse, but remains a distinct result so each ownership policy must decide
+* explicitly whether that proof permits recovery. An unreadable start time is
+* not proof of reuse. An owner recorded without a start time stays fail-closed
+* while its pid is alive: there is no same-clock-domain proof of birth order (wall-clock
+* arithmetic over `ps etime` shifts under clock steps), and misreading a live
+* owner as recycled would let a waiter steal a held resource.
+*/
+function classifyOwnerLiveness(params) {
+	return classifyOwnerLivenessFromObservation(params);
+}
+function classifyOwnerLivenessFromObservation(params, observation) {
+	const { owner, stateDir } = params;
+	if (!isProcessPid(owner.pid)) return "unknown";
+	if (!isProcessAlive(owner.pid)) return "owner-process-dead";
+	if (observation !== void 0 ? observation?.state.startsWith("Z") : isProcessZombie(owner.pid)) return "owner-process-dead";
+	if (owner.startTime) {
+		const currentStartTime = observation !== void 0 ? observation?.startTime ?? null : readProcessStartTime(owner.pid);
+		if (currentStartTime !== null && currentStartTime !== owner.startTime) return "owner-process-reused";
+	}
+	return stateDir ? classifyOwnerStateDirectory(stateDir) : "live";
+}
+function classifyOwnerStateDirectory(stateDir) {
+	try {
+		fs.statSync(stateDir);
+		return "live";
+	} catch (error) {
+		const code = error?.code;
+		if (code === "ENOENT" || code === "ENOTDIR") return "owner-state-dir-gone";
+		return "unknown";
+	}
+}
+//#endregion
+export { classifyOwnerLiveness, classifyOwnerLivenessFromObservation, createOwnedProcessRecordStore, expandProcessTree, hostCurrentWorkingDirectory, hostEnvironment, hostNodeExecutablePath, hostNodeVersion, hostPlatform, hostProcessId, isProcessAlive, isProcessGroupAlive, isProcessPid, isProcessZombie, listHostProcesses, ownerIdentityDiffers, ownerIdentityMatches, readCurrentOwnerIdentity, readHostCpuArch, readHostCpuArchSync, readHostEnvironmentVariable, readHostProcessIdentityObservations, readOwnedProcessRecordFile, readProcessCommand, readProcessIdentityFacts, readProcessStartTime, reapOwnedProcessRecordsAtStartup, signalPidsBestEffort, signalProcessGroupBestEffort, stopPidsWithEscalation, uniquePositivePids, waitForProcessExit, writeHostStderr };