@khorsheed/dsh-ankh-guard 0.1.1 → 0.2.0

package/lib/invariant.js

@@ -1,5 +1,5 @@
 import { i as resolveStateDir } from "./defaults-CduvOcGq.js";
-import { a as stateFilePath, n as loadState } from "./state-Dhx9VG44.js";
+import { n as loadState, o as stateFilePath } from "./state-CZMypGkB.js";
 import { existsSync } from "node:fs";
 //#region lib/types/invariant.js
 /**

package/lib/preflight-runner.js

@@ -1,7 +1,8 @@
 import { n as isDirectInvocation } from "./defaults-CduvOcGq.js";
-import { existsSync, mkdtempSync, readFileSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { existsSync, mkdtempSync, statSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 //#region lib/types/preflight-runner.js
 /**
@@ -11,10 +12,11 @@ import { pathToFileURL } from "node:url";
 * deploy line) was wiped by the upstream reset and cannot be re-applied
 * without re-forking apps/cli on every release — which we cannot upstream
 * (no PR access). This runner replaces it WITHOUT touching the harness: it
-* resolves the official published packages (`@deepseek-ai/dsh-app-boot`,
-* `dsh-home-paths`, `dsh-launch-environment`, `dsh-cmdline`) from the LIVE
-* harness checkout's node_modules, so it always dry-runs the exact engine
-* the next boot will use and follows host updates automatically.
+* resolves the official packages (`@deepseek-ai/dsh-app-boot`,
+* `dsh-home-paths`, `dsh-launch-environment`, `dsh-cmdline`) from an explicit
+* execution binding: source files in the host checkout for a source launch,
+* or the npm toolchain selected by a built launch's dsh package.json. It never
+* infers that choice from Node's execArgv.
 *
 * What it verifies (same contract as the old patch):
 * - the profile's full patch stack composes (bundle layers from
@@ -33,8 +35,8 @@ import { pathToFileURL } from "node:url";
 *   error, env load failure): NOT a verdict on the composition.
 *
 * Run directly (any profile) or via the guard CLI:
-*   node --import <harness>/node_modules/tsx/dist/esm/index.mjs \
-*     packages/ankh-guard/src/preflight-runner.ts --profile web [--patch FILE]...
+*   node packages/ankh-guard/lib/preflight-runner.js --profile web \
+*     --host-surface built --install-anchor <toolchain>/node_modules/@deepseek-ai/dsh/package.json
 *
 * @module @khorsheed/dsh-ankh-guard/preflight-runner
 */
@@ -49,6 +51,17 @@ const PROFILE_ROOT_FILENAME = "cordis.yml";
 const HOME_PATCH_FILENAME = "cordis.patch.yml";
 const TELEMETRY_ROW_ID = "session-telemetry-otel";
 const DSH_HARNESS_ENV = "DSH_HARNESS";
+/**
+* The empty root entry list every profile tree patches over — the exact
+* bytes the launcher's prepareProfile rewrites on every boot (the vendored
+* Loader's tree write-back can bake composed rows into this file, so both
+* the launcher and this dry-run always start from the empty root).
+*/
+const PROFILE_ROOT_CONFIG = `# dsh profile root — an empty entry list. The tree is composed as patches:
+# each bundle in package.json's dsh.profile.bundles, then cordis.patch.yml, then any
+# --patch overlays. Edit cordis.patch.yml, not this file.
+[]
+`;
 /** The guarded (or tracking) harness checkout the live instance boots from. */
 function resolveHarnessRoot(env = process.env) {
 	const fromEnv = env[DSH_HARNESS_ENV];
@@ -66,18 +79,9 @@ const HARNESS_PACKAGE_DIRS = {
 	"@deepseek-ai/dsh-cmdline": "packages/boot/cmdline"
 };
 /**
-* Whether this runtime can import TypeScript sources (the runner is launched
-* through tsx; a plain-node consumer of the published package cannot).
-*/
-function canImportTypeScript() {
-	return process.execArgv.some((arg) => arg.includes("tsx"));
-}
-/**
-* Dynamically import a harness package from the live checkout, SOURCE FIRST:
-* a source-launched prod instance (tsx … apps/cli/src/bin.ts) boots the
-* source, so the preflight engine must be the source too — a stale `lib/`
-* must never make the preflight greener than the real boot. The built entry
-* is the fallback for harnesses that ship only artifacts.
+* Dynamically import one host package from the explicitly selected surface.
+* A source launch uses checkout source and fails rather than falling back to
+* stale lib; a built launch resolves only through its npm install anchor.
 *
 * The composition layers below (bundle layers, user layers, overlays, the
 * agent-presets roots, the telemetry switch) mirror the launcher's private
@@ -89,27 +93,38 @@ function canImportTypeScript() {
 * @param name - package name (a key of {@link HARNESS_PACKAGE_DIRS}).
 * @returns the imported module.
 */
-async function loadHarnessPackage(root, name) {
+async function loadHarnessPackage(root, name, binding) {
+	if (binding.surface === "built") {
+		let entry;
+		try {
+			entry = createRequire(binding.installAnchor).resolve(name);
+		} catch (error) {
+			throw new Error(`built host package ${name} is not resolvable from ${binding.installAnchor}: ${String(error)}`, { cause: error });
+		}
+		return await import(__rewriteRelativeImportExtension(pathToFileURL(entry).href));
+	}
 	const relative = HARNESS_PACKAGE_DIRS[name];
 	if (relative === void 0) throw new Error(`no known harness layout entry for ${name}`);
 	const base = join(root, relative);
 	const source = join(base, "src", "index.ts");
-	if (canImportTypeScript() && existsSync(source)) try {
+	if (!existsSync(source)) throw new Error(`harness source entry does not exist: ${source}`);
+	try {
 		return await import(__rewriteRelativeImportExtension(pathToFileURL(source).href));
 	} catch (error) {
 		throw new Error(`harness source ${source} failed to import (this is what a source boot would hit): ${String(error)}`, { cause: error });
 	}
-	const entry = JSON.parse(readFileSync(join(base, "package.json"), "utf8")).main ?? "lib/index.js";
-	return await import(__rewriteRelativeImportExtension(pathToFileURL(join(base, entry)).href));
 }
 /** Thrown for harness-side load failures — preflight infrastructure, never a composition verdict. */
 var PreflightInfraError = class extends Error {};
 /**
 * Compose one profile's full patch stack through the launcher's layering —
 * bundle layers in `dsh.profile.bundles` order, the profile user layer, the
-* home-level user layer, `--patch` overlays, the agent-presets roots overlay,
-* then the telemetry switch. Exported so the drift tripwire can compare this
-* assembly against the launcher's own dump without booting anything.
+* home-level user layer, `--patch` overlays, the agent-presets roots overlay
+* (rc host line only; the 0.1.2 line's preset package self-ships its root),
+* then the telemetry switch. Two host API generations are mirrored and
+* feature-detected per run — see the `hostLine` branch below. Exported so
+* the drift tripwire can compare this assembly against the launcher's own
+* dump without booting anything.
 * @param profile - the profile name (same resolution as `--profile`).
 * @param patchFiles - `--patch` overlay paths, in argv order.
 * @param root - harness checkout root.
@@ -118,12 +133,15 @@ var PreflightInfraError = class extends Error {};
 * specific deployment must not silently compose a different home's tree.
 * @returns the patch stack and composed rows.
 */
-async function composePreflightPatches(profile, patchFiles, root, home) {
+async function composePreflightPatches(profile, patchFiles, root, home, binding = {
+	surface: "source",
+	installAnchor: join(root, "apps", "cli", "package.json")
+}) {
 	let appBoot;
 	let homePaths;
 	try {
-		appBoot = await loadHarnessPackage(root, "@deepseek-ai/dsh-app-boot");
-		homePaths = await loadHarnessPackage(root, "@deepseek-ai/dsh-home-paths");
+		appBoot = await loadHarnessPackage(root, "@deepseek-ai/dsh-app-boot", binding);
+		homePaths = await loadHarnessPackage(root, "@deepseek-ai/dsh-home-paths", binding);
 	} catch (error) {
 		throw new PreflightInfraError(`harness packages unavailable under ${root}: ${String(error)}`, { cause: error });
 	}
@@ -133,10 +151,17 @@ async function composePreflightPatches(profile, patchFiles, root, home) {
 	const loadOverlayPatches = appBoot.loadOverlayPatches;
 	const loadProfile = appBoot.loadProfile;
 	const resolveDshHome = homePaths.resolveDshHome;
-	const anchor = join(root, "apps", "cli", "package.json");
+	const anchor = binding.installAnchor;
 	const resolvedHome = resolveDshHome(home);
-	healProfilesModuleFallback(anchor);
+	const hostLine = "DEFAULT_PROFILE_PATCH_RELOAD" in appBoot ? "0.1.2" : "rc";
+	if (hostLine === "rc") healProfilesModuleFallback(anchor, resolvedHome);
 	const composed = loadProfile(NAME, profile, anchor, resolvedHome, { userLayer: true });
+	writeFileSync(join(composed.dir, PROFILE_ROOT_FILENAME), PROFILE_ROOT_CONFIG);
+	if (hostLine === "0.1.2") await healProfilesModuleFallback({
+		installAnchor: anchor,
+		profile: composed,
+		home: resolvedHome
+	});
 	const homePatches = loadOptionalPatches(NAME, join(resolvedHome, HOME_PATCH_FILENAME)) ?? [];
 	const overlays = patchFiles.flatMap((file) => loadOverlayPatches(NAME, resolve(file)));
 	const bundlePatches = composed.layers.flatMap((layer) => layer.patches);
@@ -154,12 +179,13 @@ async function composePreflightPatches(profile, patchFiles, root, home) {
 		overlays
 	])) if (typeof row.id === "string") rows.set(row.id, row);
 	const composedOverlays = [...overlays];
-	if (rows.has("agent-presets")) composedOverlays.push({
+	const shippedPresetRoot = binding.surface === "built" ? join(dirname(binding.installAnchor), "config", "agent-presets") : join(root, "apps", "cli", "config", "agent-presets");
+	if (rows.has("agent-presets") && existsSync(shippedPresetRoot)) composedOverlays.push({
 		id: "agent-presets",
 		config: {
 			...rows.get("agent-presets")?.config ?? {},
 			roots: [{
-				path: join(root, "apps/cli/config/agent-presets/"),
+				path: shippedPresetRoot,
 				trust: "system"
 			}]
 		}
@@ -190,6 +216,34 @@ async function composePreflightPatches(profile, patchFiles, root, home) {
 		profileDir: composed.dir
 	};
 }
+/**
+* The launcher's readiness signal, mirrored: 0.1.2's runProfile provides an
+* `appReady` service through provideCmdline and commits it once boot and host
+* setup settle. The rc line's provideCmdline ignores the field, so one
+* implementation serves both host lines.
+*/
+function createAppReadyStub() {
+	let committed = false;
+	const listeners = /* @__PURE__ */ new Set();
+	return {
+		service: { onReady(listener) {
+			if (committed) {
+				listener();
+				return () => {};
+			}
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		} },
+		commit() {
+			if (committed) return;
+			committed = true;
+			for (const listener of [...listeners]) listener();
+			listeners.clear();
+		}
+	};
+}
 /** Stat every registered client bundle; report one line per missing/unreadable artifact. */
 function missingClientArtifacts(ctx) {
 	const registry = ctx.get?.("clientModules");
@@ -218,14 +272,17 @@ function missingClientArtifacts(ctx) {
 * @param root - harness checkout root (default: DSH_HARNESS or ~/code/deepseek-harness).
 * @returns the process exit code (see the module contract).
 */
-async function runPreflight(profile, patchFiles = [], root = resolveHarnessRoot()) {
+async function runPreflight(profile, patchFiles = [], root = resolveHarnessRoot(), binding = {
+	surface: "source",
+	installAnchor: join(root, "apps", "cli", "package.json")
+}) {
 	let appBoot;
 	let launchEnvironment;
 	let cmdline;
 	try {
-		appBoot = await loadHarnessPackage(root, "@deepseek-ai/dsh-app-boot");
-		launchEnvironment = await loadHarnessPackage(root, "@deepseek-ai/dsh-launch-environment");
-		cmdline = await loadHarnessPackage(root, "@deepseek-ai/dsh-cmdline");
+		appBoot = await loadHarnessPackage(root, "@deepseek-ai/dsh-app-boot", binding);
+		launchEnvironment = await loadHarnessPackage(root, "@deepseek-ai/dsh-launch-environment", binding);
+		cmdline = await loadHarnessPackage(root, "@deepseek-ai/dsh-cmdline", binding);
 	} catch (error) {
 		process.stderr.write(`preflight could not execute (harness packages unavailable under ${root}): ${error instanceof Error ? error.message : String(error)}\n`);
 		return 3;
@@ -242,7 +299,7 @@ async function runPreflight(profile, patchFiles = [], root = resolveHarnessRoot(
 		return 3;
 	}
 	try {
-		const composed = await composePreflightPatches(profile, patchFiles, root);
+		const composed = await composePreflightPatches(profile, patchFiles, root, void 0, binding);
 		const patches = [...composed.patches];
 		const webserver = composed.rows.get("webserver");
 		if (webserver !== void 0) patches.push({
@@ -253,13 +310,16 @@ async function runPreflight(profile, patchFiles = [], root = resolveHarnessRoot(
 			}
 		});
 		const rootConfig = join(composed.profileDir, PROFILE_ROOT_FILENAME);
+		const appReady = createAppReadyStub();
 		const ctx = await boot(NAME, rootConfig, structuredClone(patches), (hostCtx) => {
 			hostCtx.provide?.(launchEnvironmentKey, environment);
 			provideCmdline(hostCtx, {
 				args: [],
-				exit: () => {}
+				exit: () => {},
+				ready: appReady.service
 			});
 		});
+		appReady.commit();
 		const missing = missingClientArtifacts(ctx);
 		await ctx.fiber.dispose();
 		if (missing.length > 0) {
@@ -277,20 +337,24 @@ async function runPreflight(profile, patchFiles = [], root = resolveHarnessRoot(
 		return 1;
 	}
 }
-/** Minimal argv parse for `--profile NAME` and repeatable `--patch FILE`. */
+/** Minimal argv parse; the host execution surface is mandatory and explicit. */
 function parsePreflightArgs(argv) {
 	const patchFiles = [];
 	let profile = "";
+	let surface = "";
+	let installAnchor = "";
 	for (let i = 0; i < argv.length; i++) {
 		const arg = argv[i];
 		if (arg === "--profile") profile = argv[++i] ?? "";
 		else if (arg === "--patch") {
 			const file = argv[++i];
 			if (file !== void 0) patchFiles.push(file);
-		} else if (arg === "--help" || arg === "-h") return {
+		} else if (arg === "--host-surface") surface = argv[++i] ?? "";
+		else if (arg === "--install-anchor") installAnchor = argv[++i] ?? "";
+		else if (arg === "--help" || arg === "-h") return {
 			profile: "",
 			patchFiles: [],
-			error: "usage: preflight-runner --profile <name> [--patch FILE]..."
+			error: "usage: preflight-runner --profile <name> --host-surface source|built --install-anchor FILE [--patch FILE]..."
 		};
 	}
 	if (profile === "") return {
@@ -298,18 +362,32 @@ function parsePreflightArgs(argv) {
 		patchFiles: [],
 		error: "preflight requires --profile <name>"
 	};
+	if (surface !== "source" && surface !== "built") return {
+		profile,
+		patchFiles,
+		error: "preflight requires --host-surface source|built"
+	};
+	if (installAnchor === "") return {
+		profile,
+		patchFiles,
+		error: "preflight requires --install-anchor FILE"
+	};
 	return {
 		profile,
-		patchFiles
+		patchFiles,
+		binding: {
+			surface,
+			installAnchor
+		}
 	};
 }
 if (isDirectInvocation(import.meta.url)) {
-	const { profile, patchFiles, error } = parsePreflightArgs(process.argv.slice(2));
-	if (error !== void 0) {
+	const { profile, patchFiles, binding, error } = parsePreflightArgs(process.argv.slice(2));
+	if (error !== void 0 || binding === void 0) {
 		process.stderr.write(`${error}\n`);
 		process.exit(2);
 	}
-	process.exitCode = await runPreflight(profile, patchFiles);
+	process.exitCode = await runPreflight(profile, patchFiles, resolveHarnessRoot(), binding);
 }
 //#endregion
 export { composePreflightPatches, parsePreflightArgs, resolveHarnessRoot, runPreflight };

package/lib/processes-BjZgJjQr.js

@@ -0,0 +1,344 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+//#region lib/types/processes.js
+/**
+* Process primitives shared by the guard CLI and the exit agent: locating the
+* listener on a port and killing a process tree. One owner — the watchdog's
+* bash side keeps its own copy (different runtime), but every TypeScript
+* caller goes through here.
+*/
+function executable(name, candidates) {
+	return candidates.find((candidate) => existsSync(candidate)) ?? name;
+}
+const LSOF = executable("lsof", ["/usr/sbin/lsof", "/usr/bin/lsof"]);
+const PS = executable("ps", ["/bin/ps", "/usr/bin/ps"]);
+const PGREP = executable("pgrep", ["/usr/bin/pgrep", "/bin/pgrep"]);
+const SYSCTL = executable("sysctl", ["/usr/sbin/sysctl", "/sbin/sysctl"]);
+const PYTHON = executable("python3", ["/usr/bin/python3", "/opt/homebrew/bin/python3"]);
+const DARWIN_START_TOKEN = [
+	"import ctypes,struct,sys",
+	"p=int(sys.argv[1])",
+	"b=ctypes.create_string_buffer(136)",
+	"n=ctypes.CDLL(\"/usr/lib/libproc.dylib\").proc_pidinfo(p,3,0,b,136)",
+	"n == 136 or sys.exit(1)",
+	"s,u=struct.unpack_from(\"QQ\",b.raw,120)",
+	"print(f\"darwin:{s}:{u}\",end=\"\")"
+].join(";");
+/** Every process listening on a TCP port. An empty list also covers unavailable lsof. */
+function findPidsOnPort(port) {
+	try {
+		const out = execFileSync(LSOF, [
+			`-tiTCP:${port}`,
+			"-sTCP:LISTEN",
+			"-P"
+		], {
+			encoding: "utf8",
+			stdio: "pipe"
+		}).trim();
+		return [...new Set(out.split("\n").map(Number).filter((pid) => Number.isInteger(pid) && pid > 0))];
+	} catch {
+		return [];
+	}
+}
+/** TCP listen ports owned directly by one PID, using the same absolute lsof resolution. */
+function listeningPortsForPid(pid) {
+	try {
+		const out = execFileSync(LSOF, [
+			"-nP",
+			"-a",
+			"-p",
+			String(pid),
+			"-iTCP",
+			"-sTCP:LISTEN"
+		], {
+			encoding: "utf8",
+			stdio: "pipe"
+		});
+		return [...new Set([...out.matchAll(/:(\d+) \(LISTEN\)/g)].map((match) => Number(match[1])).filter(Number.isInteger))];
+	} catch {
+		return [];
+	}
+}
+/** The first process listening on a TCP port, or null when none is (via lsof). */
+function findPidOnPort(port) {
+	return findPidsOnPort(port)[0]?.toString() ?? null;
+}
+/**
+* Current identity for a live process, or null when it cannot be proved.
+* Linux exposes a boot-scoped kernel start tick. Other POSIX hosts do not,
+* so bind the start instant to the boot, uid, session, and settled command.
+* This materially strengthens macOS ps(1)'s second-granularity lstart; all
+* guard captures occur after the watchdog/child has reached its steady argv.
+*/
+function processIdentity(pid) {
+	if (!Number.isInteger(pid) || pid <= 0) return null;
+	try {
+		const status = execFileSync(PS, [
+			"-o",
+			"stat=",
+			"-p",
+			String(pid)
+		], {
+			encoding: "utf8",
+			stdio: "pipe"
+		}).trim();
+		if (status === "" || status.startsWith("Z")) return null;
+		if (process.platform === "darwin") try {
+			const nativeStart = execFileSync(PYTHON, [
+				"-c",
+				DARWIN_START_TOKEN,
+				String(pid)
+			], {
+				encoding: "utf8",
+				stdio: "pipe"
+			}).trim();
+			if (/^darwin:\d+:\d+$/.test(nativeStart)) return {
+				pid,
+				startToken: nativeStart
+			};
+		} catch {}
+		const procStat = `/proc/${pid}/stat`;
+		if (existsSync(procStat)) {
+			const stat = readFileSync(procStat, "utf8");
+			const commandEnd = stat.lastIndexOf(")");
+			const startTicks = (commandEnd < 0 ? [] : stat.slice(commandEnd + 1).trim().split(/\s+/))[19];
+			if (startTicks === void 0 || startTicks === "") return null;
+			let bootId = "unknown-boot";
+			try {
+				bootId = readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim() || bootId;
+			} catch {}
+			return {
+				pid,
+				startToken: `linux:${bootId}:${startTicks}`
+			};
+		}
+		const processEvidence = execFileSync(PS, [
+			"-o",
+			"sess=",
+			"-o",
+			"uid=",
+			"-o",
+			"lstart=",
+			"-o",
+			"command=",
+			"-p",
+			String(pid)
+		], {
+			encoding: "utf8",
+			stdio: "pipe"
+		}).trim();
+		if (processEvidence === "") return null;
+		let bootEvidence = "unknown-boot";
+		try {
+			bootEvidence = execFileSync(SYSCTL, ["-n", "kern.boottime"], {
+				encoding: "utf8",
+				stdio: "pipe"
+			}).trim() || bootEvidence;
+		} catch {}
+		return {
+			pid,
+			startToken: `posix:${createHash("sha256").update(bootEvidence).update("\0").update(processEvidence).digest("hex")}`
+		};
+	} catch {
+		return null;
+	}
+}
+/** Whether the same, non-recycled process is still alive. */
+function processIdentityMatches(identity) {
+	return processIdentity(identity.pid)?.startToken === identity.startToken;
+}
+function parentPid(pid) {
+	try {
+		const value = Number(execFileSync(PS, [
+			"-o",
+			"ppid=",
+			"-p",
+			String(pid)
+		], {
+			encoding: "utf8",
+			stdio: "pipe"
+		}).trim());
+		return Number.isInteger(value) && value > 0 ? value : null;
+	} catch {
+		return null;
+	}
+}
+/** The live POSIX process-group id for one PID, or null when unavailable. */
+function processGroupId(pid) {
+	if (!Number.isInteger(pid) || pid <= 0) return null;
+	try {
+		const value = Number(execFileSync(PS, [
+			"-o",
+			"pgid=",
+			"-p",
+			String(pid)
+		], {
+			encoding: "utf8",
+			stdio: "pipe"
+		}).trim());
+		return Number.isInteger(value) && value > 0 ? value : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Prove that exactly one port listener belongs to a supervisor and return the
+* direct child root through which that supervisor owns it. This is captured
+* before cutover; the successor must stop this identity, never an arbitrary
+* process discovered later from the shared port.
+*/
+function findOwnedListener(port, supervisorPid) {
+	const listeners = findPidsOnPort(port);
+	if (listeners.length !== 1) return null;
+	const listenerPid = listeners[0];
+	if (listenerPid === void 0) return null;
+	const listener = processIdentity(listenerPid);
+	if (listener === null) return null;
+	let cursor = listenerPid;
+	let childRoot = null;
+	const seen = /* @__PURE__ */ new Set();
+	while (cursor > 0 && !seen.has(cursor)) {
+		seen.add(cursor);
+		const parent = parentPid(cursor);
+		if (parent === supervisorPid) {
+			childRoot = cursor;
+			break;
+		}
+		if (parent === null) return null;
+		cursor = parent;
+	}
+	if (childRoot === null) return null;
+	const child = processIdentity(childRoot);
+	return child === null ? null : {
+		child,
+		listener
+	};
+}
+/** POSIX single-quote one word for a shell command line. */
+function shellQuote(word) {
+	return `'${word.replace(/'/g, "'\\''")}'`;
+}
+/**
+* Discover how the process on a port was launched — its exact argv from
+* `ps -o command=`, its cwd from lsof, and its DSH_* environment from
+* `ps eww` — rendered as a shell command. This exists because the agent's
+* sandbox blocks ps entirely, so every fresh-machine agent fell into a
+* process-tree archaeology loop before its first restart; the CLI (running
+* unsandboxed) answers the same question mechanically and reliably. Returns
+* null when the process is gone or ps/lsof are unavailable.
+* @param pid - the listener's pid.
+*/
+function discoverLaunchCommand(pid) {
+	let argv;
+	let cwd;
+	try {
+		argv = execFileSync(PS, [
+			"-o",
+			"command=",
+			"-p",
+			pid
+		], {
+			encoding: "utf8",
+			stdio: "pipe"
+		}).trim();
+		if (argv === "") return null;
+	} catch (error) {
+		throw new Error(`ps unavailable: ${String(error)}`);
+	}
+	try {
+		const out = execFileSync(LSOF, [
+			"-a",
+			"-p",
+			pid,
+			"-d",
+			"cwd",
+			"-Fn"
+		], {
+			encoding: "utf8",
+			stdio: "pipe"
+		});
+		const match = /^n(.+)$/m.exec(out);
+		if (match === null) return null;
+		cwd = match[1] ?? "";
+	} catch (error) {
+		throw new Error(`lsof cwd unavailable: ${String(error)}`);
+	}
+	const TRANSIENT = /* @__PURE__ */ new Set([
+		"DSH_ANKH_RESTART_DRIVER",
+		"DSH_SESSION_ID",
+		"DSH_SESSION_JSONL",
+		"DSH_WEB_URL",
+		"DSH_SHELL"
+	]);
+	const env = {};
+	try {
+		const out = execFileSync(PS, [
+			"eww",
+			"-o",
+			"command",
+			"-p",
+			pid
+		], {
+			encoding: "utf8",
+			stdio: "pipe"
+		});
+		for (const token of out.split(/\s+/)) {
+			const eq = token.indexOf("=");
+			if (eq > 0 && token.slice(0, eq).startsWith("DSH_") && !TRANSIENT.has(token.slice(0, eq))) env[token.slice(0, eq)] = token.slice(eq + 1);
+		}
+	} catch {}
+	const envPart = Object.entries(env).map(([key, value]) => `${key}=${shellQuote(value)}`).join(" ");
+	return `cd ${shellQuote(cwd)} && ${envPart !== "" ? `${envPart} ` : ""}${argv}`;
+}
+/**
+* Kill a pid AND its descendants, deepest first (best effort). The supervised
+* instance may have forked children; a plain signal on the pid alone would
+* orphan them (the EADDRINUSE race the watchdog's EADDRINUSE branch exists
+* for). The process-group model is NOT assumed — the instance is not
+* setsid'd — so the sweep walks `pgrep -P` instead. `pgrep` missing or
+* returning nothing is fine: the pid itself still gets the signal.
+*/
+function signalFrozenTree(pid, signal) {
+	let safe = true;
+	let children = [];
+	try {
+		const out = execFileSync(PGREP, ["-P", String(pid)], {
+			encoding: "utf8",
+			stdio: "pipe"
+		}).trim();
+		children = out === "" ? [] : out.split("\n");
+	} catch {}
+	for (const raw of children) {
+		const child = Number(raw);
+		if (!Number.isInteger(child) || child <= 0) continue;
+		try {
+			process.kill(child, "SIGSTOP");
+		} catch {
+			continue;
+		}
+		if (parentPid(child) !== pid) {
+			safe = false;
+			try {
+				process.kill(child, "SIGCONT");
+			} catch {}
+			continue;
+		}
+		safe = signalFrozenTree(child, signal) && safe;
+	}
+	try {
+		process.kill(pid, signal);
+		if (signal !== "SIGKILL") process.kill(pid, "SIGCONT");
+	} catch {}
+	return safe;
+}
+function killPidTree(pid, signal) {
+	try {
+		process.kill(pid, "SIGSTOP");
+	} catch {
+		return;
+	}
+	signalFrozenTree(pid, signal);
+}
+//#endregion
+export { listeningPortsForPid as a, processIdentityMatches as c, killPidTree as i, findOwnedListener as n, processGroupId as o, findPidOnPort as r, processIdentity as s, discoverLaunchCommand as t };