@khorsheed/dsh-ankh-guard 0.1.1 → 0.3.0

package/lib/{state-Dhx9VG44.js → state-CZMypGkB.js}

@@ -1,3 +1,4 @@
+import { c as appendTestLifecycleEvent } from "./test-seam-dwvaKjRp.js";
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 //#region lib/types/state-files.js
@@ -44,8 +45,26 @@ const STATE_FILES = {
 	scheduleExitLog: "schedule-exit.log",
 	/** How the current instance was launched (recorded by the plugin at apply). */
 	instanceLaunch: "instance-launch.json",
+	/** The atomically selected full launch configuration (stable or in cutover). */
+	launchSpec: "launch-spec.json",
+	/** Redacted durable receipt for the latest launch-configuration cutover. */
+	launchCutover: "launch-cutover.json",
+	/** Legacy combined operator-control marker, retained for rolling upgrades. */
+	cutoverControl: "launch-cutover-control.json",
+	/** Operator → watchdog: abort according to the pre-approved recovery policy. */
+	cutoverAbort: "launch-cutover-abort.json",
+	/** Monotonic stronger operator action: explicitly restore the previous spec. */
+	cutoverRestorePrevious: "launch-cutover-restore-previous.json",
+	/** Original browser-tab registry: per-tab capability hashes only; retained through terminal recovery. */
+	browserHandoffRequest: "browser-handoff-request.json",
+	/** Browser → watchdog acknowledgement for one proven final process. */
+	browserHandoffAck: "browser-handoff-ack.json",
 	/** Whether the restart-protocol skill registered at apply (and why not). */
-	skillRegistration: "skill-registration.json"
+	skillRegistration: "skill-registration.json",
+	/** Directory: the healthy-boot snapshot of the profile composition inputs. */
+	lastGoodComposition: "last-good-composition",
+	/** Directory prefix: a failing composition backed up before rollback restores over it. */
+	compositionBackup: "composition-backup-"
 };
 /** Absolute path of a state file inside a state directory. */
 function stateFile(stateDir, role) {
@@ -67,6 +86,42 @@ function lastGoodBootRevision(stateDir) {
 		return;
 	}
 }
+/**
+* Whether the pid named by this raw pid/lock-file content is alive. Empty
+* content reads as NO holder: Number('') is 0 and kill(0, 0) probes our own
+* process group (always succeeds), which once read as "alive" and refused
+* every restart forever — the bug that had to be fixed in two copies of this
+* logic before it was consolidated here.
+*/
+function pidAlive(raw) {
+	const pid = Number(raw);
+	if (raw === "" || !Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** The live pid named by a pid/lock file (as the raw string), or null when absent/stale. */
+function livePidIn(file) {
+	try {
+		const raw = readFileSync(file, "utf8").trim();
+		return pidAlive(raw) ? raw : null;
+	} catch {
+		return null;
+	}
+}
+/** The live supervising watchdog's pid, or null when none is (pidfile + kill 0). */
+function liveWatchdogPid(stateDir) {
+	const raw = livePidIn(stateFile(stateDir, "watchdogPid"));
+	const pid = raw === null ? null : Number(raw);
+	appendTestLifecycleEvent("watchdog-liveness-probe", {
+		pid: pid ?? 0,
+		live: pid !== null
+	}, "parent-observer");
+	return pid;
+}
 //#endregion
 //#region lib/types/state.js
 /**
@@ -74,10 +129,9 @@ function lastGoodBootRevision(stateDir) {
 *
 * The guard records one "green build" credential — bound to the git HEAD it
 * was recorded on and to a freshness window — and answers `verify()` against
-* the CURRENT head and wall clock. A self-restart may only proceed while the
-* credential is valid; the binding to HEAD means any tree change after
-* recording invalidates it, so a stale or post-hoc credential can never
-* authorize a restart of unverified code. Framework-free: the cordis plugin,
+* the CURRENT head and wall clock. A later fully gated boot may promote that
+* credential into a deployment proof whose exact runtime fingerprint can be
+* reused by the same-launch restart path. Framework-free: the cordis plugin,
 * the CLI, and the invariant companion all share this module.
 */
 /** Absolute path of the state file inside a state directory. */
@@ -98,10 +152,20 @@ function isCheckpoint(value) {
 	const c = value;
 	return typeof c.revision === "string" && typeof c.recordedAt === "number" && typeof c.message === "string";
 }
+function isSha256(value) {
+	return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+}
+function isProvenDeployment(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const proof = value;
+	const credential = proof.credential;
+	const fingerprint = proof.fingerprint;
+	return proof.version === 1 && typeof proof.provenAt === "number" && credential !== void 0 && typeof credential.revision === "string" && credential.revision !== "" && typeof credential.recordedAt === "number" && typeof credential.scope === "string" && isSha256(credential.commandSha256) && fingerprint?.version === 1 && typeof fingerprint.credentialRevision === "string" && fingerprint.credentialRevision !== "" && typeof fingerprint.harnessRevision === "string" && fingerprint.harnessRevision !== "" && isSha256(fingerprint.launchSpecSha256) && isSha256(fingerprint.profileSha256) && isSha256(fingerprint.hostRuntimeSha256) && isSha256(proof.fingerprintSha256);
+}
 function isAuditEntry(value) {
 	if (typeof value !== "object" || value === null) return false;
 	const e = value;
-	return (e.action === "record" || e.action === "clear" || e.action === "checkpoint") && typeof e.ts === "number" && typeof e.detail === "string";
+	return (e.action === "record" || e.action === "clear" || e.action === "checkpoint" || e.action === "prove-deployment") && typeof e.ts === "number" && typeof e.detail === "string";
 }
 /**
 * Read the state file; an absent file is an empty state, a malformed one is a
@@ -116,6 +180,7 @@ function loadState(stateDir) {
 		if (parsed === null || typeof parsed !== "object") return emptyState();
 		const state = { audit: Array.isArray(parsed.audit) ? parsed.audit.filter(isAuditEntry) : [] };
 		if (isCredential(parsed.credential)) state.credential = parsed.credential;
+		if (isProvenDeployment(parsed.provenDeployment)) state.provenDeployment = parsed.provenDeployment;
 		if (isCheckpoint(parsed.checkpoint)) state.checkpoint = parsed.checkpoint;
 		return state;
 	} catch (error) {
@@ -149,12 +214,13 @@ function recordCredential(stateDir, input, now) {
 		...input,
 		recordedAt: now
 	};
+	const { provenDeployment: _oldProof, ...withoutOldProof } = withAudit(loadState(stateDir), {
+		action: "record",
+		ts: now,
+		detail: `${input.scope} @ ${input.revision}`
+	});
 	const updated = {
-		...withAudit(loadState(stateDir), {
-			action: "record",
-			ts: now,
-			detail: `${input.scope} @ ${input.revision}`
-		}),
+		...withoutOldProof,
 		credential
 	};
 	saveState(stateDir, updated);
@@ -177,6 +243,19 @@ function clearCredential(stateDir, now) {
 	saveState(stateDir, updated);
 	return updated;
 }
+/** Persist a deployment proof after the watchdog has completed its canary. */
+function setProvenDeployment(stateDir, proof, now) {
+	const updated = {
+		...withAudit(loadState(stateDir), {
+			action: "prove-deployment",
+			ts: now,
+			detail: `${proof.credential.revision} ${proof.fingerprintSha256.slice(0, 16)}`
+		}),
+		provenDeployment: proof
+	};
+	saveState(stateDir, updated);
+	return updated;
+}
 /**
 * Persist a pre-batch checkpoint commit reference.
 * @param stateDir - state directory.
@@ -207,9 +286,10 @@ function setCheckpoint(stateDir, input, now) {
 * @param currentRevision - the git HEAD of the checkout, or null when unavailable.
 * @param now - epoch milliseconds (injected for deterministic tests).
 * @param maxAgeMinutes - freshness window.
+* @param workingTreeClean - whether staged, unstaged, and untracked inputs are absent.
 * @returns ok plus a human reason either way.
 */
-function verifyCredential(state, currentRevision, now, maxAgeMinutes) {
+function verifyCredential(state, currentRevision, now, maxAgeMinutes, workingTreeClean = true) {
 	const credential = state.credential;
 	if (credential === void 0) return {
 		ok: false,
@@ -219,6 +299,10 @@ function verifyCredential(state, currentRevision, now, maxAgeMinutes) {
 		ok: false,
 		reason: "current git HEAD unavailable (not inside a git repository?)"
 	};
+	if (!workingTreeClean) return {
+		ok: false,
+		reason: "working tree is dirty (staged, unstaged, or untracked changes exist) — commit or remove them, then rebuild and re-record"
+	};
 	if (credential.revision !== currentRevision) return {
 		ok: false,
 		reason: `green credential is bound to revision ${credential.revision}, but current HEAD is ${currentRevision} — the tree changed since it was recorded; rebuild and re-record`
@@ -236,4 +320,4 @@ function verifyCredential(state, currentRevision, now, maxAgeMinutes) {
 	};
 }
 //#endregion
-export { stateFilePath as a, stateFile as c, setCheckpoint as i, loadState as n, verifyCredential as o, recordCredential as r, lastGoodBootRevision as s, clearCredential as t };
+export { setProvenDeployment as a, lastGoodBootRevision as c, pidAlive as d, stateFile as f, setCheckpoint as i, livePidIn as l, loadState as n, stateFilePath as o, recordCredential as r, verifyCredential as s, clearCredential as t, liveWatchdogPid as u };

package/lib/test-seam-cli.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { d as registerTestProcess, l as appendTestLifecycleEventForProcess, u as registerCurrentTestProcess } from "./test-seam-dwvaKjRp.js";
+//#region lib/types/test-seam-cli.js
+/** Internal executable used only by dsh-watchdog.sh under an explicit test run. */
+const command = process.argv[2] ?? "register";
+if (command === "register-parent") {
+	const role = process.argv[3] ?? process.env["ANKH_GUARD_TEST_PROCESS_ROLE"] ?? "unknown";
+	registerTestProcess(process.ppid, role, { source: "child-self" });
+} else if (command === "event-parent") {
+	const role = process.argv[3] ?? process.env["ANKH_GUARD_TEST_PROCESS_ROLE"] ?? "unknown";
+	const event = process.argv[4] ?? "unknown";
+	appendTestLifecycleEventForProcess(process.ppid, role, event);
+} else if (command === "register-pid") {
+	const pid = Number(process.argv[3]);
+	const role = process.argv[4] ?? process.env["ANKH_GUARD_TEST_PROCESS_ROLE"] ?? "unknown";
+	registerTestProcess(pid, role, { source: "child-self" });
+} else if (command === "event-pid") {
+	const pid = Number(process.argv[3]);
+	const role = process.argv[4] ?? process.env["ANKH_GUARD_TEST_PROCESS_ROLE"] ?? "unknown";
+	const event = process.argv[5] ?? "unknown";
+	appendTestLifecycleEventForProcess(pid, role, event);
+} else registerCurrentTestProcess();
+//#endregion
+export {};

package/lib/test-seam-dwvaKjRp.js

@@ -0,0 +1,459 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+//#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
+//#region lib/types/test-seam.js
+/**
+* Explicit test-only process/event registration seam. Production execution is
+* inert unless a test runner supplies all ANKH_GUARD_TEST_* ownership values.
+*/
+const TEST_RUN_DIR_ENV = "ANKH_GUARD_TEST_RUN_DIR";
+const TEST_RUN_TOKEN_ENV = "ANKH_GUARD_TEST_RUN_TOKEN";
+const TEST_PROCESS_ROLE_ENV = "ANKH_GUARD_TEST_PROCESS_ROLE";
+const TEST_PROCESS_PORT_ENV = "ANKH_GUARD_TEST_PROCESS_PORT";
+const TEST_PROCESS_TEMP_ROOT_ENV = "ANKH_GUARD_TEST_PROCESS_TEMP_ROOT";
+const TEST_REGISTER_BIN_ENV = "ANKH_GUARD_TEST_REGISTER_BIN";
+const TEST_SLEEP_SCALE_ENV = "ANKH_GUARD_TEST_SLEEP_SCALE";
+function testCoordinates(env) {
+	const runDir = env[TEST_RUN_DIR_ENV];
+	const runToken = env[TEST_RUN_TOKEN_ENV];
+	if (runDir === void 0 || runDir === "" || runToken === void 0 || !/^[a-f0-9-]{16,}$/.test(runToken)) return null;
+	return {
+		runDir,
+		runToken
+	};
+}
+function safeRole(value) {
+	const role = value.trim().replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 80);
+	return role === "" ? "unknown" : role;
+}
+function appendTestLifecycleEventForProcess(subjectPid, roleValue, event, detail, source = "child-self", env = process.env) {
+	const coordinates = testCoordinates(env);
+	if (coordinates === null) return;
+	const role = safeRole(roleValue);
+	const identity = processIdentity(subjectPid);
+	const pgid = processGroupId(subjectPid);
+	const record = {
+		version: 1,
+		runToken: coordinates.runToken,
+		source,
+		role,
+		event: safeRole(event),
+		pid: subjectPid,
+		...pgid === null ? {} : { pgid },
+		...identity === null ? {} : { startToken: identity.startToken },
+		wallTimeMs: Date.now(),
+		monotonicNs: process.hrtime.bigint().toString(),
+		...detail === void 0 ? {} : { detail }
+	};
+	try {
+		const dir = join(coordinates.runDir, "events");
+		mkdirSync(dir, {
+			recursive: true,
+			mode: 448
+		});
+		appendFileSync(join(dir, `${subjectPid}-${source}.jsonl`), `${JSON.stringify(record)}\n`, { mode: 384 });
+	} catch {}
+}
+/** Record one credential-free event in this process's append-only event file. */
+function appendTestLifecycleEvent(event, detail, source = "child-self", env = process.env) {
+	appendTestLifecycleEventForProcess(process.pid, env["ANKH_GUARD_TEST_PROCESS_ROLE"] ?? "unknown", event, detail, source, env);
+}
+/**
+* Atomically publish an immutable PID/PGID/start-identity lease. The same PID
+* may be observed by its parent and then self-register; the first complete
+* record wins because both describe the same kernel start identity.
+*/
+function registerTestProcess(pid, role, options = {}) {
+	const env = options.env ?? process.env;
+	const coordinates = testCoordinates(env);
+	if (coordinates === null) return null;
+	const identity = options.identity ?? processIdentity(pid);
+	const pgid = processGroupId(pid);
+	if (identity === null || pgid === null) return null;
+	const portText = env[TEST_PROCESS_PORT_ENV];
+	const envPort = portText === void 0 ? void 0 : Number(portText);
+	const port = options.port ?? (Number.isInteger(envPort) && (envPort ?? 0) > 0 ? envPort : void 0);
+	const tempRoot = options.tempRoot ?? env["ANKH_GUARD_TEST_PROCESS_TEMP_ROOT"];
+	const record = {
+		version: 1,
+		runToken: coordinates.runToken,
+		role: safeRole(role),
+		pid,
+		pgid,
+		startToken: identity.startToken,
+		groupRoot: pgid === pid,
+		registeredAt: Date.now(),
+		source: options.source ?? (pid === process.pid ? "child-self" : "parent-observer"),
+		...tempRoot === void 0 || tempRoot === "" ? {} : { tempRoot },
+		...port === void 0 ? {} : { port }
+	};
+	try {
+		const dir = join(coordinates.runDir, "processes");
+		mkdirSync(dir, {
+			recursive: true,
+			mode: 448
+		});
+		const identityHash = createHash("sha256").update(identity.startToken).digest("hex").slice(0, 16);
+		writeFileSync(join(dir, `${pid}-${identityHash}.json`), `${JSON.stringify(record)}\n`, {
+			flag: "wx",
+			mode: 384
+		});
+	} catch (error) {
+		if (error.code !== "EEXIST") return null;
+	}
+	return record;
+}
+/** Self-register only when an explicit test role accompanies the run lease. */
+function registerCurrentTestProcess(env = process.env) {
+	const role = env[TEST_PROCESS_ROLE_ENV];
+	if (role === void 0 || role === "") return null;
+	const record = registerTestProcess(process.pid, role, {
+		env,
+		source: "child-self"
+	});
+	if (record !== null) appendTestLifecycleEvent("process-registered", { pgid: record.pgid }, "child-self", env);
+	return record;
+}
+//#endregion
+export { processIdentity as _, TEST_RUN_DIR_ENV as a, appendTestLifecycleEvent as c, registerTestProcess as d, discoverLaunchCommand as f, listeningPortsForPid as g, killPidTree as h, TEST_REGISTER_BIN_ENV as i, appendTestLifecycleEventForProcess as l, findPidOnPort as m, TEST_PROCESS_ROLE_ENV as n, TEST_RUN_TOKEN_ENV as o, findOwnedListener as p, TEST_PROCESS_TEMP_ROOT_ENV as r, TEST_SLEEP_SCALE_ENV as s, TEST_PROCESS_PORT_ENV as t, registerCurrentTestProcess as u, processIdentityMatches as v };

package/lib/test-seam.js

@@ -0,0 +1,2 @@
+import { a as TEST_RUN_DIR_ENV, c as appendTestLifecycleEvent, d as registerTestProcess, i as TEST_REGISTER_BIN_ENV, l as appendTestLifecycleEventForProcess, n as TEST_PROCESS_ROLE_ENV, o as TEST_RUN_TOKEN_ENV, r as TEST_PROCESS_TEMP_ROOT_ENV, s as TEST_SLEEP_SCALE_ENV, t as TEST_PROCESS_PORT_ENV, u as registerCurrentTestProcess } from "./test-seam-dwvaKjRp.js";
+export { TEST_PROCESS_PORT_ENV, TEST_PROCESS_ROLE_ENV, TEST_PROCESS_TEMP_ROOT_ENV, TEST_REGISTER_BIN_ENV, TEST_RUN_DIR_ENV, TEST_RUN_TOKEN_ENV, TEST_SLEEP_SCALE_ENV, appendTestLifecycleEvent, appendTestLifecycleEventForProcess, registerCurrentTestProcess, registerTestProcess };