@agent-device/proxy 0.21.27 → 0.21.28-nightly.20261014.57

package/dist/process.mjs

@@ -98,6 +98,9 @@ function parseBooleanLiteral(value) {
 const BARE_COMMAND_RE = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;
 const EXEC_DIAGNOSTIC_ARG_LIMIT = 6;
 const commandExecutorOverrideScope = new AsyncLocalStorage();
+async function withoutCommandExecutorOverride(fn) {
+	return await commandExecutorOverrideScope.run(void 0, fn);
+}
 const requestCommandEnvScope = new AsyncLocalStorage();
 /** Effective toolchain selection; an explicitly empty request value selects `xcode-select`. */
 function commandDeveloperDir() {
@@ -619,43 +622,95 @@ function isProcessZombie(pid) {
 	if (isWindowsHostPlatform()) return false;
 	return readProcessField(pid, "state=")?.startsWith("Z") ?? false;
 }
+/**
+* What the host says about each pid named, from one process-tool snapshot. An unanswered pid is
+* missing from the map, which is unknown evidence rather than absence: a caller that signals on
+* the answer must stay fail-closed. Use {@link readHostProcessIdentityObservationsAsync} from a
+* path that is already waiting; this one blocks the event loop for the whole snapshot.
+*/
 function readHostProcessIdentityObservations(pids) {
-	const observations = /* @__PURE__ */ new Map();
 	const selected = uniquePositivePids(pids);
-	if (selected.length === 0) return observations;
-	if (isWindowsHostPlatform()) {
-		for (const row of readWindowsProcessRows(selected, WINDOWS_PS_TIMEOUT_MS)) {
-			if (row.startTime === null) continue;
-			observations.set(row.pid, {
-				state: "R",
-				startTime: row.startTime
-			});
-		}
-		return observations;
+	if (selected.length === 0) return /* @__PURE__ */ new Map();
+	return readHostProcessIdentitySnapshot(selected, readHostProcessIdentityRowsSync(selected));
+}
+/**
+* {@link readHostProcessIdentityObservations} off the event loop, with the same one-snapshot
+* guarantee and the same fail-closed answer. A daemon request path that only decides whether to
+* pay a cost must not stall every other request, timer, and abort handler behind a
+* `spawnSync` of the host process tool.
+*/
+async function readHostProcessIdentityObservationsAsync(pids) {
+	const selected = uniquePositivePids(pids);
+	if (selected.length === 0) return /* @__PURE__ */ new Map();
+	return readHostProcessIdentitySnapshot(selected, await withoutCommandExecutorOverride(() => readHostProcessIdentityRowsAsync(selected)));
+}
+function readHostProcessIdentitySnapshot(pids, rows) {
+	const selected = uniquePositivePids(pids);
+	const observations = /* @__PURE__ */ new Map();
+	if (selected.length === 0 || rows.length === 0) return observations;
+	const named = new Set(selected);
+	for (const row of rows) {
+		if (!named.has(row.pid)) continue;
+		observations.set(row.pid, {
+			state: row.state,
+			startTime: row.startTime
+		});
 	}
+	return observations;
+}
+const HOST_PROCESS_IDENTITY_PS_ARGS = (pids) => [
+	"-p",
+	pids.join(","),
+	"-o",
+	"pid=,state=,lstart="
+];
+function readHostProcessIdentityRowsSync(pids) {
+	if (isWindowsHostPlatform()) return windowsProcessIdentityRows(readWindowsProcessRows(pids, WINDOWS_PS_TIMEOUT_MS));
 	try {
-		const result = runCmdSync(HOST_PS_COMMAND, [
-			"-p",
-			selected.join(","),
-			"-o",
-			"pid=,state=,lstart="
-		], {
+		const result = runCmdSync(HOST_PS_COMMAND, HOST_PROCESS_IDENTITY_PS_ARGS(pids), {
 			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;
+		return result.exitCode !== 0 ? [] : parseHostProcessIdentityRows(result.stdout);
+	} catch {
+		return [];
+	}
+}
+async function readHostProcessIdentityRowsAsync(pids) {
+	const selected = uniquePositivePids(pids);
+	if (selected.length === 0) return [];
+	if (isWindowsHostPlatform()) return windowsProcessIdentityRows(await readWindowsProcessRowsAsync(selected, WINDOWS_PS_TIMEOUT_MS));
+	try {
+		const result = await runCmd(HOST_PS_COMMAND, HOST_PROCESS_IDENTITY_PS_ARGS(selected), {
+			allowFailure: true,
+			timeoutMs: PS_TIMEOUT_MS
+		});
+		return result.exitCode !== 0 ? [] : parseHostProcessIdentityRows(result.stdout);
+	} catch {
+		return [];
+	}
+}
+function parseHostProcessIdentityRows(stdout) {
+	const rows = [];
+	for (const line of 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;
+		rows.push({
+			pid,
+			state: match[2],
+			startTime: match[3]
+		});
+	}
+	return rows;
+}
+function windowsProcessIdentityRows(rows) {
+	return rows.flatMap((row) => row.startTime === null ? [] : [{
+		pid: row.pid,
+		state: "R",
+		startTime: row.startTime
+	}]);
 }
 function readProcessField(pid, field) {
 	if (!Number.isInteger(pid) || pid <= 0) return null;
@@ -752,6 +807,18 @@ function readWindowsProcessRows(pids, timeoutMs) {
 		return [];
 	}
 }
+async function readWindowsProcessRowsAsync(pids, timeoutMs) {
+	try {
+		const result = await runCmd(WINDOWS_PROCESS_TOOL, windowsProcessQueryArgs(pids), {
+			allowFailure: true,
+			timeoutMs
+		});
+		if (result.exitCode !== 0) return [];
+		return parseWindowsProcessRows(result.stdout);
+	} catch {
+		return [];
+	}
+}
 function readWindowsProcessField(pid, field) {
 	const row = readWindowsProcessRows([pid], WINDOWS_PS_TIMEOUT_MS).find((candidate) => candidate.pid === pid);
 	if (!row) return null;
@@ -857,6 +924,163 @@ async function waitForProcessExit(pid, timeoutMs) {
 	}
 	return !isProcessAlive(pid);
 }
+/**
+* Projects a retained verdict onto the keys a caller may publish. A caller adds its own artifact
+* paths beside these; a layer that forwards the verdict forwards only these, so an inner surface's
+* file paths and advice cannot ride along under an outer surface's message.
+*/
+function confirmedProcessStopDetails(retained, pid) {
+	return {
+		reason: retained.reason,
+		signal: "signal" in retained ? retained.signal : void 0,
+		errno: retained.reason === "signal-failed" ? retained.errno : void 0,
+		pid
+	};
+}
+/**
+* Names a pid the stop left alone. This is the one verdict that must not say the process is still
+* running: the host refused to describe it, so nothing was ever signaled to it.
+*/
+function describeUnconfirmedProcessStop(pid, claimedAs) {
+	return `pid ${pid} could not be confirmed as ${claimedAs}, so no signal was sent to it`;
+}
+/**
+* Whether `reason` names a retained stop verdict. Forwarding gates on this rather than on error text,
+* so an unrelated failure's details cannot be forwarded as one.
+*/
+function isConfirmedProcessStopReason(value) {
+	return value === "signal-failed" || value === "exit-timeout" || value === "identity-unverified";
+}
+/**
+* The verdict a nested layer published, or nothing when the error carries no stop verdict. A wrapper
+* that flattens the inner message keeps the verdict in `details` and drops the inner surface's file
+* paths and advice, which describe a file the caller of the wrapper was not asked about.
+*/
+function readConfirmedProcessStopDetails(details) {
+	const reason = details?.reason;
+	const pid = details?.pid;
+	if (!isConfirmedProcessStopReason(reason) || typeof pid !== "number") return void 0;
+	const signal = details?.signal;
+	const errno = details?.errno;
+	return {
+		reason,
+		signal: signal === "SIGTERM" || signal === "SIGKILL" ? signal : void 0,
+		errno: reason === "signal-failed" && typeof errno === "string" ? errno : void 0,
+		pid
+	};
+}
+/**
+* Signals one process TERM then KILL and proves which way the recorded process ended, so a caller
+* only forgets one it watched leave. Identity settles it both ways: unreadable identity retains
+* rather than signaling a process this caller cannot name, while a released pid, a zombie, or a
+* start time the host contradicts proves it gone. A refusal is not absence, so each stage waits.
+*/
+async function stopProcessAndConfirmExit(target, budget) {
+	if (target.pid === process.pid) throw new RangeError("Cannot stop the current process");
+	const identity = await proveStopTargetIdentity(target);
+	if (identity === "gone") return { status: "stopped" };
+	if (identity === "unverified") return {
+		status: "retained",
+		reason: "identity-unverified"
+	};
+	const term = await proveSignalStage(target, "SIGTERM", budget.termTimeoutMs);
+	if (term.proof === "exited") return { status: "stopped" };
+	if (term.proof === "refused") return retainedSignalFailure("SIGTERM", term.errno);
+	const kill = await proveSignalStage(target, "SIGKILL", budget.killTimeoutMs);
+	if (kill.proof === "exited") return { status: "stopped" };
+	if (kill.proof === "refused") return retainedSignalFailure("SIGKILL", kill.errno);
+	return {
+		status: "retained",
+		reason: "exit-timeout",
+		signal: "SIGKILL"
+	};
+}
+/**
+* Whether the live pid still names the process the caller recorded, read once before anything is
+* signaled. `ours` needs a claim the host confirmed: two recorded facts that no readable fact
+* contradicts only prove the host is silent, and silence about a pid this caller may not own is
+* exactly what must not become permission to signal it.
+*/
+async function proveStopTargetIdentity(target) {
+	if (!isStopPidLive(target.pid)) return "gone";
+	const facts = await readProcessIdentityFacts(target.pid);
+	if (facts.zombie) return "gone";
+	if (target.identity.startTime && facts.startTime && facts.startTime !== target.identity.startTime) return "gone";
+	if (target.identity.matches && facts.command && !target.identity.matches(facts.command)) return "gone";
+	const confirmedStartTime = Boolean(target.identity.startTime && facts.startTime);
+	const confirmedCommand = Boolean(target.identity.matches && facts.command);
+	return confirmedStartTime || confirmedCommand ? "ours" : "unverified";
+}
+function retainedSignalFailure(signal, errno) {
+	return {
+		status: "retained",
+		reason: "signal-failed",
+		signal,
+		errno
+	};
+}
+async function proveSignalStage(target, signal, timeoutMs) {
+	const errno = signalProcessForStop(target.pid, signal);
+	if (errno === "ESRCH") return { proof: "exited" };
+	if (await waitForStopPidRelease(target.pid, timeoutMs)) return { proof: "exited" };
+	if (await proveRecordedProcessGone(target)) return { proof: "exited" };
+	return errno === void 0 ? { proof: "survived" } : {
+		proof: "refused",
+		errno
+	};
+}
+const STOP_LIVENESS_POLL_MS = 50;
+/**
+* Whether `kill(pid, 0)` finds the process. `isProcessAlive` reads every answer but `EPERM` as
+* absence, which suits a best-effort sweep and not a stop: here only `ESRCH` releases a pid, and an
+* answer that is not about the process at all must not become permission to forget it.
+*/
+function isStopPidLive(pid) {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		const code = error.code;
+		if (code === "ESRCH") return false;
+		if (code === "EPERM") return true;
+		throw error;
+	}
+}
+async function waitForStopPidRelease(pid, timeoutMs) {
+	const deadline = Date.now() + timeoutMs;
+	for (;;) {
+		if (!isStopPidLive(pid)) return true;
+		if (Date.now() >= deadline) return false;
+		await sleep(Math.min(STOP_LIVENESS_POLL_MS, Math.max(0, deadline - Date.now())));
+	}
+}
+/**
+* Whether the pid outliving its budget still proves the recorded process is gone, which the answer to
+* `kill(pid, 0)` cannot: `EPERM` also comes back for a zombie awaiting its parent, and on Windows for
+* a process that exited while its object still had handles. A start time the host contradicts proves
+* the pid changed hands; the process table holding no row does not, because a hidden or unreadable
+* process is missing from it too.
+*/
+async function proveRecordedProcessGone(target) {
+	const facts = await readProcessIdentityFacts(target.pid);
+	if (facts.zombie) return true;
+	const startTime = target.identity.startTime;
+	return Boolean(startTime && facts.startTime && facts.startTime !== startTime);
+}
+/** The errno that refused the signal, or `undefined` when the host accepted it. */
+function signalProcessForStop(pid, signal) {
+	if (!Number.isInteger(pid) || pid <= 0) return "ESRCH";
+	try {
+		process.kill(pid, signal);
+		return;
+	} catch (error) {
+		const code = error.code;
+		if (typeof code === "string" && ERRNO_CODE.test(code)) return code;
+		throw error;
+	}
+}
+const ERRNO_CODE = /^E[A-Z0-9]+$/;
 async function stopPidsWithEscalation(options) {
 	const pids = uniquePositivePids(options.pids, { excludePid: process.pid });
 	if (pids.length === 0) return;
@@ -1309,4 +1533,4 @@ function classifyOwnerStateDirectory(stateDir) {
 	}
 }
 //#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 };
+export { classifyOwnerLiveness, classifyOwnerLivenessFromObservation, confirmedProcessStopDetails, createOwnedProcessRecordStore, describeUnconfirmedProcessStop, expandProcessTree, hostCurrentWorkingDirectory, hostEnvironment, hostNodeExecutablePath, hostNodeVersion, hostPlatform, hostProcessId, isProcessAlive, isProcessGroupAlive, isProcessPid, isProcessZombie, listHostProcesses, ownerIdentityDiffers, ownerIdentityMatches, readConfirmedProcessStopDetails, readCurrentOwnerIdentity, readHostCpuArch, readHostCpuArchSync, readHostEnvironmentVariable, readHostProcessIdentityObservations, readHostProcessIdentityObservationsAsync, readOwnedProcessRecordFile, readProcessCommand, readProcessIdentityFacts, readProcessStartTime, reapOwnedProcessRecordsAtStartup, signalPidsBestEffort, signalProcessGroupBestEffort, stopPidsWithEscalation, stopProcessAndConfirmExit, uniquePositivePids, waitForProcessExit, writeHostStderr };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-device/proxy",
-  "version": "0.21.27",
+  "version": "0.21.28-nightly.20261014.57",
   "type": "module",
   "description": "Transport-neutral authenticating proxy in front of an agent-device daemon.",
   "license": "MIT",
@@ -25,9 +25,9 @@
     "dist"
   ],
   "devDependencies": {
-    "@agent-device/contracts": "0.0.0",
     "@agent-device/host-kit": "0.0.0",
-    "@agent-device/kernel": "0.0.0"
+    "@agent-device/kernel": "0.0.0",
+    "@agent-device/contracts": "0.0.0"
   },
   "scripts": {
     "build": "tsdown --config tsdown.config.ts"