@khorsheed/dsh-ankh-guard 0.1.1 → 0.2.0

package/lib/{state-Dhx9VG44.js → state-4f7yny39.js}

@@ -44,8 +44,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) {
@@ -74,10 +92,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 +115,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 +143,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 +177,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 +206,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 +249,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 +262,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 +283,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, setCheckpoint as i, stateFile as l, loadState as n, stateFilePath as o, recordCredential as r, verifyCredential as s, clearCredential as t };

package/lib/state-CZMypGkB.js

@@ -0,0 +1,323 @@
+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
+/**
+* The guard's state-directory protocol: every file that lives in the state
+* dir, named exactly once. Five writers in three languages (this package's
+* TS, the watchdog's bash, the schedule-exit exit agent's inline JS, and the
+* two supervisor installers) read and write these — a literal drifting in
+* any one of them splits the protocol silently (three review rounds of path
+* bugs came from exactly that). The bash sides are pinned by
+* tests/state-files.spec.ts, which asserts every state-dir literal in the
+* watchdog and both installers appears here, and that no script re-derives
+* the directory from the home.
+*/
+/** Every state-directory file name, keyed by role. */
+const STATE_FILES = {
+	/** The guard's credential/checkpoint/audit state (state.ts). */
+	guard: "self-restart-guard.json",
+	/** Watchdog-stamped last deployment-proven revision. */
+	lastGoodBoot: "last-good-boot.json",
+	/** schedule-exit → watchdog: an intentional restart, run the canary. */
+	restartRequested: "restart-requested.json",
+	/** The exit agent's restart outcome record (the report's source). */
+	lastRestart: "last-restart.json",
+	/** The SIGTERM snapshot of interrupted sessions. */
+	interruptedSessions: "interrupted-sessions.json",
+	/** The supervising watchdog's pidfile. */
+	watchdogPid: "watchdog.pid",
+	/** Cross-session mutual exclusion for the restart verb. */
+	restartLock: "restart.lock",
+	/** The detached restart driver's log. */
+	restartLog: "restart.log",
+	/** Marker: exit the watchdog without respawn. */
+	watchdogStop: "watchdog-stop",
+	/** Marker: the watchdog gave up; a crash page holds the port. */
+	watchdogGaveUp: "watchdog-gave-up",
+	/** The current boot attempt's captured output. */
+	bootAttemptLog: "boot-attempt.log",
+	/** The watchdog's own log. */
+	watchdogLog: "watchdog.log",
+	/** The watchdog's stderr, captured separately by the supervisor installers. */
+	watchdogStderrLog: "watchdog.stderr.log",
+	/** The exit agent's log. */
+	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",
+	/** 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) {
+	return join(stateDir, STATE_FILES[role]);
+}
+/**
+* The last deployment-proven revision, stamped by the watchdog on every
+* healthy boot, or undefined. Lives here rather than in the credential core:
+* the stamp is written by the watchdog and proves the deployment composed and
+* came up — a green credential only ever proves build+test passed.
+* @param stateDir - state directory.
+* @returns the stamped revision, or undefined.
+*/
+function lastGoodBootRevision(stateDir) {
+	try {
+		const stamp = JSON.parse(readFileSync(stateFile(stateDir, "lastGoodBoot"), "utf8"));
+		return typeof stamp.revision === "string" && stamp.revision !== "" ? stamp.revision : void 0;
+	} catch {
+		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
+/**
+* Pure credential/checkpoint state core for the self-restart guard.
+*
+* 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 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. */
+function stateFilePath(stateDir) {
+	return stateFile(stateDir, "guard");
+}
+/** A fresh, credential-less state. */
+function emptyState() {
+	return { audit: [] };
+}
+function isCredential(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const c = value;
+	return typeof c.scope === "string" && typeof c.revision === "string" && typeof c.recordedAt === "number" && typeof c.command === "string";
+}
+function isCheckpoint(value) {
+	if (typeof value !== "object" || value === null) return false;
+	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" || 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
+* loud misconfiguration error (never silently ignored).
+* @param stateDir - directory holding the state file.
+* @returns the parsed state.
+*/
+function loadState(stateDir) {
+	try {
+		const raw = readFileSync(stateFilePath(stateDir), "utf8");
+		const parsed = JSON.parse(raw);
+		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) {
+		if (error?.code === "ENOENT") return emptyState();
+		throw new Error(`ankh-guard: unreadable state file ${stateFilePath(stateDir)}: ${String(error)}`);
+	}
+}
+/** Persist a state (creates the directory as needed). */
+function saveState(stateDir, state) {
+	mkdirSync(stateDir, { recursive: true });
+	const file = stateFilePath(stateDir);
+	const tmp = `${file}.${process.pid}.tmp`;
+	writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
+	renameSync(tmp, file);
+}
+function withAudit(state, entry) {
+	return {
+		...state,
+		audit: [...state.audit, entry].slice(-50)
+	};
+}
+/**
+* Record a green-build credential bound to {@link RecordInput.revision}.
+* @param stateDir - state directory.
+* @param input - scope, the git HEAD, and the command that went green.
+* @param now - epoch milliseconds (injected for deterministic tests).
+* @returns the persisted state.
+*/
+function recordCredential(stateDir, input, now) {
+	const credential = {
+		...input,
+		recordedAt: now
+	};
+	const { provenDeployment: _oldProof, ...withoutOldProof } = withAudit(loadState(stateDir), {
+		action: "record",
+		ts: now,
+		detail: `${input.scope} @ ${input.revision}`
+	});
+	const updated = {
+		...withoutOldProof,
+		credential
+	};
+	saveState(stateDir, updated);
+	return updated;
+}
+/**
+* Drop the credential (checkpoint and audit survive).
+* @param stateDir - state directory.
+* @param now - epoch milliseconds (injected for deterministic tests).
+* @returns the persisted state.
+*/
+function clearCredential(stateDir, now) {
+	const audited = withAudit(loadState(stateDir), {
+		action: "clear",
+		ts: now,
+		detail: "credential cleared"
+	});
+	const updated = { audit: audited.audit };
+	if (audited.checkpoint !== void 0) updated.checkpoint = audited.checkpoint;
+	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.
+* @param input - the checkpoint commit SHA and its message.
+* @param now - epoch milliseconds (injected for deterministic tests).
+* @returns the persisted state.
+*/
+function setCheckpoint(stateDir, input, now) {
+	const checkpoint = {
+		...input,
+		recordedAt: now
+	};
+	const updated = {
+		...withAudit(loadState(stateDir), {
+			action: "checkpoint",
+			ts: now,
+			detail: `${input.revision} ${input.message}`
+		}),
+		checkpoint
+	};
+	saveState(stateDir, updated);
+	return updated;
+}
+/**
+* Answer the gate: a credential is valid only when present, recorded on the
+* CURRENT revision, and younger than {@link maxAgeMinutes}.
+* @param state - the loaded state.
+* @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, workingTreeClean = true) {
+	const credential = state.credential;
+	if (credential === void 0) return {
+		ok: false,
+		reason: "no green-build credential recorded"
+	};
+	if (currentRevision === null) return {
+		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`
+	};
+	const ageMs = now - credential.recordedAt;
+	const maxMs = maxAgeMinutes * 6e4;
+	if (ageMs > maxMs) return {
+		ok: false,
+		reason: `green credential is stale (${Math.round(ageMs / 6e4)} min old, limit ${maxAgeMinutes} min) — rebuild and re-record`
+	};
+	const leftMs = Math.max(0, maxMs - ageMs);
+	return {
+		ok: true,
+		reason: `green credential valid (${credential.scope} @ ${credential.revision}, ${Math.round(leftMs / 6e4)} min left)`
+	};
+}
+//#endregion
+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-DnvLWTeO.js

@@ -0,0 +1,119 @@
+import { o as processGroupId, s as processIdentity } from "./processes-BjZgJjQr.js";
+import { createHash } from "node:crypto";
+import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+//#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 { TEST_RUN_DIR_ENV as a, appendTestLifecycleEvent as c, registerTestProcess as d, TEST_REGISTER_BIN_ENV as i, appendTestLifecycleEventForProcess as l, TEST_PROCESS_ROLE_ENV as n, TEST_RUN_TOKEN_ENV as o, TEST_PROCESS_TEMP_ROOT_ENV as r, TEST_SLEEP_SCALE_ENV as s, TEST_PROCESS_PORT_ENV as t, registerCurrentTestProcess 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 {};