@khorsheed/dsh-ankh-guard 0.1.1 → 0.2.0

package/lib/restart-context-DUyExi9O.js

@@ -0,0 +1,1245 @@
+import { f as stateFile } from "./state-CZMypGkB.js";
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+//#region lib/types/git.js
+/**
+* Git helpers for the self-restart guard: the credential binds to the current
+* HEAD, checkpoints are real commits, and rollback is a hard reset. All calls
+* are synchronous child-process invocations scoped to the repo directory.
+*/
+/**
+* The repository's current HEAD, or null when the directory is not inside a
+* git repository (or git itself is unavailable).
+* @param repoDir - repository directory.
+* @returns the full HEAD sha, or null.
+*/
+function currentHead(repoDir) {
+	try {
+		const out = execFileSync("git", ["rev-parse", "HEAD"], {
+			cwd: repoDir,
+			encoding: "utf8",
+			stdio: "pipe"
+		}).trim();
+		return out.length > 0 ? out : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Porcelain entries for every tracked or untracked working-tree change.
+* `null` means git could not inspect the checkout; callers must fail closed.
+*/
+function workingTreeChanges(repoDir) {
+	try {
+		return execFileSync("git", [
+			"status",
+			"--porcelain=v1",
+			"-z",
+			"--untracked-files=all"
+		], {
+			cwd: repoDir,
+			encoding: "utf8",
+			stdio: "pipe"
+		}).split("\0").filter((entry) => entry !== "");
+	} catch {
+		return null;
+	}
+}
+/** Whether the checkout has no staged, unstaged, or untracked changes. */
+function isWorkingTreeClean(repoDir) {
+	const changes = workingTreeChanges(repoDir);
+	return changes !== null && changes.length === 0;
+}
+/**
+* Record a clean HEAD directly, or commit the whole dirty working tree as an
+* explicitly approved checkpoint snapshot. Dirty commits use a temporary git
+* index: a hook/commit failure leaves the caller's real index untouched.
+* @param repoDir - repository directory.
+* @param message - checkpoint commit message.
+* @param artifactPattern - staged paths matching this are reported as
+* build-artifact-looking warnings (deployment-specific — see
+* SRC_ARTIFACT_PATTERN in defaults.ts; omit for none).
+* @returns the new HEAD sha, or a failure reason.
+*/
+function commitCheckpoint(repoDir, message, artifactPattern, includeDirty = false) {
+	let tempDir;
+	try {
+		const changes = workingTreeChanges(repoDir);
+		if (changes === null) return {
+			ok: false,
+			error: "git checkpoint failed: working tree status is unavailable"
+		};
+		if (changes.length > 0 && !includeDirty) {
+			const shown = changes.slice(0, 10).map((entry) => `  ${entry}`).join("\n");
+			const more = changes.length > 10 ? `\n  … (${changes.length - 10} more)` : "";
+			return {
+				ok: false,
+				error: `checkpoint refused: working tree has ${changes.length} change(s); review them, then rerun with --include-dirty to commit the complete snapshot:\n${shown}${more}`
+			};
+		}
+		const previousHead = currentHead(repoDir);
+		if (previousHead === null) return {
+			ok: false,
+			error: "git checkpoint failed: current HEAD is unavailable"
+		};
+		if (changes.length === 0) return {
+			ok: true,
+			sha: previousHead,
+			artifacts: [],
+			createdCommit: false
+		};
+		const indexPathRaw = execFileSync("git", [
+			"rev-parse",
+			"--git-path",
+			"index"
+		], {
+			cwd: repoDir,
+			encoding: "utf8",
+			stdio: "pipe"
+		}).trim();
+		const indexPath = resolve(repoDir, indexPathRaw);
+		tempDir = mkdtempSync(join(tmpdir(), "ankh-guard-index-"));
+		const tempIndex = join(tempDir, "index");
+		copyFileSync(indexPath, tempIndex);
+		const env = {
+			...process.env,
+			GIT_INDEX_FILE: tempIndex
+		};
+		execFileSync("git", ["add", "-A"], {
+			cwd: repoDir,
+			env,
+			stdio: "pipe"
+		});
+		const staged = execFileSync("git", [
+			"diff",
+			"--cached",
+			"--name-only"
+		], {
+			cwd: repoDir,
+			env,
+			encoding: "utf8"
+		});
+		const artifacts = artifactPattern === void 0 ? [] : staged.split("\n").filter((file) => artifactPattern.test(file));
+		execFileSync("git", [
+			"commit",
+			"-m",
+			message
+		], {
+			cwd: repoDir,
+			env,
+			stdio: "pipe"
+		});
+		const sha = currentHead(repoDir);
+		if (sha === null) return {
+			ok: false,
+			error: "checkpoint commit succeeded but HEAD became unreadable"
+		};
+		try {
+			execFileSync("git", [
+				"reset",
+				"--mixed",
+				"HEAD"
+			], {
+				cwd: repoDir,
+				stdio: "pipe"
+			});
+		} catch (error) {
+			try {
+				execFileSync("git", [
+					"update-ref",
+					"HEAD",
+					previousHead,
+					sha
+				], {
+					cwd: repoDir,
+					stdio: "pipe"
+				});
+			} catch {}
+			return {
+				ok: false,
+				error: `checkpoint commit could not settle the real index: ${String(error)}`
+			};
+		}
+		return {
+			ok: true,
+			sha,
+			artifacts,
+			createdCommit: true
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error: `git checkpoint failed: ${String(error)}`
+		};
+	} finally {
+		if (tempDir !== void 0) rmSync(tempDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/**
+* Roll the checkout back to a checkpoint commit WITHOUT losing work: the
+* discarded HEAD becomes a `guard-backup-*` branch, and uncommitted tracked
+* changes become a second `-wip` anchor commit (`git stash create` snapshots
+* the worktree without touching it; untracked files survive `reset --hard`
+* on their own). Every reset path — the watchdog, the CLI, the agent-facing
+* service — funnels through here, so recovery never depends on the reflog.
+* @param repoDir - repository directory.
+* @param sha - the checkpoint commit to reset to.
+* @returns success with the recovery anchor refs, or a failure reason.
+*/
+function resetToCheckpoint(repoDir, sha) {
+	const anchors = [];
+	try {
+		const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[-:T]/g, "").replace(/\..*$/, "");
+		const anchor = `guard-backup-${stamp.slice(0, 8)}-${stamp.slice(8)}-${Math.random().toString(36).slice(2, 6)}`;
+		const head = currentHead(repoDir);
+		if (head !== null && head !== sha) try {
+			execFileSync("git", [
+				"branch",
+				anchor,
+				"HEAD"
+			], {
+				cwd: repoDir,
+				stdio: "pipe"
+			});
+			anchors.push(anchor);
+		} catch {}
+		let wip = "";
+		try {
+			wip = execFileSync("git", ["stash", "create"], {
+				cwd: repoDir,
+				encoding: "utf8"
+			}).trim();
+		} catch {}
+		if (wip !== "") try {
+			execFileSync("git", [
+				"branch",
+				`${anchor}-wip`,
+				wip
+			], {
+				cwd: repoDir,
+				stdio: "pipe"
+			});
+			anchors.push(`${anchor}-wip`);
+		} catch {}
+		execFileSync("git", [
+			"reset",
+			"--hard",
+			sha
+		], {
+			cwd: repoDir,
+			stdio: "pipe"
+		});
+		return {
+			ok: true,
+			anchors
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error: `git reset --hard ${sha} failed: ${String(error)}`,
+			anchors
+		};
+	}
+}
+//#endregion
+//#region lib/types/launch-spec.js
+/**
+* Durable launch-configuration cutovers.
+*
+* A launch change is not a repository rollback: the command, home, credential
+* repository, host root, profile, port, readiness handoff, and recovery choice
+* move as one unit. The selected side lives in launch-spec.json (one atomic
+* write); the redacted,
+* append-only-ish operational receipt lives in launch-cutover.json. The full
+* commands never enter the receipt because a launch command may carry secret
+* environment values.
+*/
+function atomicWriteJson(file, value) {
+	mkdirSync(dirname(file), { recursive: true });
+	const tmp = `${file}.${process.pid}.tmp`;
+	writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 384 });
+	renameSync(tmp, file);
+	try {
+		chmodSync(file, 384);
+	} catch {}
+}
+function isLaunchSpec(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const spec = value;
+	return spec.version === 1 && typeof spec.command === "string" && spec.command !== "" && Number.isInteger(spec.port) && (spec.port ?? 0) > 0 && (spec.port ?? 0) <= 65535 && typeof spec.home === "string" && spec.home !== "" && typeof spec.credentialRepo === "string" && spec.credentialRepo !== "" && typeof spec.harnessRoot === "string" && spec.harnessRoot !== "" && typeof spec.profile === "string" && spec.profile !== "" && (spec.preflight === void 0 || isLaunchPreflightSpec(spec.preflight));
+}
+function isLaunchPreflightSpec(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const spec = value;
+	return spec.version === 1 && (spec.surface === "source" || spec.surface === "built") && typeof spec.runnerExecutable === "string" && spec.runnerExecutable !== "" && Array.isArray(spec.runnerRuntimeArgs) && spec.runnerRuntimeArgs.every((arg) => typeof arg === "string") && typeof spec.runnerPath === "string" && spec.runnerPath !== "" && typeof spec.runnerSha256 === "string" && /^[a-f0-9]{64}$/.test(spec.runnerSha256) && typeof spec.installAnchor === "string" && spec.installAnchor !== "" && typeof spec.installAnchorSha256 === "string" && /^[a-f0-9]{64}$/.test(spec.installAnchorSha256) && typeof spec.hostPackageVersion === "string" && spec.hostPackageVersion !== "" && typeof spec.targetCommandSha256 === "string" && /^[a-f0-9]{64}$/.test(spec.targetCommandSha256) && (spec.candidateProbeCommand === void 0 ? spec.candidateProbeSha256 === void 0 && spec.candidateProbeProvenance === void 0 : typeof spec.candidateProbeCommand === "string" && spec.candidateProbeCommand !== "" && typeof spec.candidateProbeSha256 === "string" && /^[a-f0-9]{64}$/.test(spec.candidateProbeSha256) && (spec.candidateProbeProvenance === void 0 || spec.candidateProbeProvenance === "caller-supplied"));
+}
+function commandSha256(command) {
+	return createHash("sha256").update(command).digest("hex");
+}
+function isTransitionReference(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const reference = value;
+	return reference.version === 1 && typeof reference.planPath === "string" && reference.planPath !== "" && typeof reference.planSha256 === "string" && /^[a-f0-9]{64}$/.test(reference.planSha256) && Number.isInteger(reference.operationCount) && (reference.operationCount ?? 0) > 0;
+}
+/** Read the selected launch state, or null for a deployment predating this protocol. */
+function readLaunchState(stateDir) {
+	try {
+		const parsed = JSON.parse(readFileSync(stateFile(stateDir, "launchSpec"), "utf8"));
+		if (parsed.version !== 1) return null;
+		if (parsed.mode === "stable" && isLaunchSpec(parsed.active)) return parsed;
+		if (parsed.mode === "cutover" && typeof parsed.cutoverId === "string" && (parsed.selected === "target" || parsed.selected === "previous") && isLaunchSpec(parsed.previous) && isLaunchSpec(parsed.target) && (parsed.transition === void 0 || isTransitionReference(parsed.transition))) return parsed;
+		return null;
+	} catch {
+		return null;
+	}
+}
+/** The exact spec a newly starting supervisor must honor. */
+function selectedLaunchSpec(state) {
+	if (state.mode === "stable") return state.active;
+	return state[state.selected];
+}
+/** Persist an ordinary, non-transactional active spec. */
+function writeStableLaunchSpec(stateDir, spec, ifAbsent = false) {
+	if (!isLaunchSpec(spec)) throw new Error("invalid launch specification");
+	if (ifAbsent && readLaunchState(stateDir) !== null) return false;
+	atomicWriteJson(stateFile(stateDir, "launchSpec"), {
+		version: 1,
+		mode: "stable",
+		active: spec
+	});
+	return true;
+}
+function summarizeLaunchSpec(spec) {
+	return {
+		commandSha256: commandSha256(spec.command).slice(0, 16),
+		port: spec.port,
+		home: spec.home,
+		credentialRepo: spec.credentialRepo,
+		harnessRoot: spec.harnessRoot,
+		profile: spec.profile,
+		...spec.preflight === void 0 ? {} : { preflight: {
+			surface: spec.preflight.surface,
+			runnerExecutable: spec.preflight.runnerExecutable,
+			runnerRuntimeArgs: spec.preflight.runnerRuntimeArgs,
+			runnerPath: spec.preflight.runnerPath,
+			runnerSha256: spec.preflight.runnerSha256,
+			installAnchor: spec.preflight.installAnchor,
+			installAnchorSha256: spec.preflight.installAnchorSha256,
+			hostPackageVersion: spec.preflight.hostPackageVersion,
+			targetCommandSha256: spec.preflight.targetCommandSha256,
+			...spec.preflight.candidateProbeSha256 === void 0 ? {} : {
+				candidateProbeSha256: spec.preflight.candidateProbeSha256,
+				candidateProbeProvenance: "caller-supplied"
+			}
+		} }
+	};
+}
+/** Safe operator view: preserve topology and selection without printing commands. */
+function summarizeLaunchState(state) {
+	if (state === null) return null;
+	if (state.mode === "stable") return {
+		version: state.version,
+		mode: state.mode,
+		active: summarizeLaunchSpec(state.active)
+	};
+	return {
+		version: state.version,
+		mode: state.mode,
+		cutoverId: state.cutoverId,
+		selected: state.selected,
+		previous: summarizeLaunchSpec(state.previous),
+		target: summarizeLaunchSpec(state.target),
+		...state.transition === void 0 ? {} : { transition: {
+			planSha256: state.transition.planSha256,
+			operationCount: state.transition.operationCount
+		} }
+	};
+}
+/** Read the durable receipt, or null when absent/malformed. */
+function readCutoverReceipt(stateDir) {
+	try {
+		const receipt = JSON.parse(readFileSync(stateFile(stateDir, "launchCutover"), "utf8"));
+		if (receipt.version !== 1 || typeof receipt.id !== "string" || !Array.isArray(receipt.events)) return null;
+		if (receipt.browserHandoff === void 0) {
+			const legacy = receipt.authentication?.browserHandoff;
+			const status = legacy === "off" ? "off" : legacy === "not-required" ? "not-required" : legacy === "failed" ? "failed" : legacy === "accepted" ? "fallback-opened" : "pending";
+			receipt.browserHandoff = {
+				required: status !== "off",
+				status
+			};
+			if (legacy === "accepted") receipt.authentication.browserHandoff = status;
+		}
+		if (receipt.readiness?.role === "target") {
+			receipt.targetValidation ??= {};
+			receipt.targetValidation.readiness ??= receipt.readiness;
+			if (receipt.targetValidation.canary === void 0 && receipt.canary !== void 0) receipt.targetValidation.canary = receipt.canary;
+		} else if (receipt.readiness?.role === "previous") {
+			receipt.recovery.validation ??= {};
+			receipt.recovery.validation.readiness ??= receipt.readiness;
+			if (receipt.recovery.validation.canary === void 0 && receipt.canary !== void 0) {
+				receipt.recovery.validation.canary = receipt.canary;
+				delete receipt.canary;
+			}
+		}
+		return receipt;
+	} catch {
+		return null;
+	}
+}
+/** Persist an operator control request for the current watchdog to consume. */
+function writeCutoverControl(stateDir, cutoverId, action, now) {
+	const active = activeCutover(stateDir);
+	if (active === null || active.receipt.id !== cutoverId) throw new Error(`cutover ${cutoverId} is not active`);
+	const request = {
+		version: 1,
+		cutoverId,
+		action,
+		requestedAt: now
+	};
+	if (action === "restore-previous") atomicWriteJson(stateFile(stateDir, "cutoverRestorePrevious"), request);
+	else {
+		const existing = readControlFile(stateFile(stateDir, "cutoverRestorePrevious"));
+		if (existing?.cutoverId === cutoverId) return existing;
+		atomicWriteJson(stateFile(stateDir, "cutoverAbort"), request);
+	}
+	const effective = readCutoverControl(stateDir);
+	return effective?.cutoverId === cutoverId ? effective : request;
+}
+function readControlFile(file) {
+	try {
+		const value = JSON.parse(readFileSync(file, "utf8"));
+		if (value.version !== 1 || typeof value.cutoverId !== "string" || value.action !== "abort" && value.action !== "restore-previous" || typeof value.requestedAt !== "number") return null;
+		return value;
+	} catch {
+		return null;
+	}
+}
+function readCutoverControl(stateDir) {
+	const restore = readControlFile(stateFile(stateDir, "cutoverRestorePrevious"));
+	if (restore?.action === "restore-previous") return restore;
+	const legacy = readControlFile(stateFile(stateDir, "cutoverControl"));
+	if (legacy?.action === "restore-previous") return legacy;
+	return readControlFile(stateFile(stateDir, "cutoverAbort")) ?? legacy;
+}
+function clearCutoverControl(stateDir, cutoverId) {
+	for (const role of [
+		"cutoverRestorePrevious",
+		"cutoverAbort",
+		"cutoverControl"
+	]) {
+		const file = stateFile(stateDir, role);
+		if (readControlFile(file)?.cutoverId === cutoverId) rmSync(file, { force: true });
+	}
+}
+/**
+* Prepare one cutover. The receipt lands first; the single launch-state rename
+* is the commit point selecting target. A crash before that rename leaves the
+* previous stable state authoritative and the old supervisor untouched.
+*/
+function prepareLaunchCutover(stateDir, input) {
+	if (!isLaunchSpec(input.previous) || !isLaunchSpec(input.target)) throw new Error("invalid launch specification");
+	if (input.id === "") throw new Error("cutover id is required");
+	if (!Number.isInteger(input.previousSupervisorPid) || input.previousSupervisorPid <= 0) throw new Error("invalid previous supervisor pid");
+	if (input.previousSupervisorStartToken === "") throw new Error("previous supervisor start identity is required");
+	for (const [label, value] of Object.entries({
+		previousChildPid: input.previousOwnership.childPid,
+		previousListenerPid: input.previousOwnership.listenerPid
+	})) if (!Number.isInteger(value) || value <= 0) throw new Error(`invalid ${label}`);
+	if (input.previousOwnership.childStartToken === "" || input.previousOwnership.listenerStartToken === "") throw new Error("previous child/listener start identity is required");
+	if (input.previous.port !== input.target.port) throw new Error("online cutover requires previous and target to use the same port");
+	if (input.transition !== void 0) {
+		if (!isTransitionReference(input.transition)) throw new Error("invalid transition reference");
+		if (input.previous.home !== input.target.home) throw new Error("filesystem transition requires previous and target to share one home");
+	}
+	for (const role of [
+		"cutoverRestorePrevious",
+		"cutoverAbort",
+		"cutoverControl"
+	]) rmSync(stateFile(stateDir, role), { force: true });
+	rmSync(stateFile(stateDir, "browserHandoffRequest"), { force: true });
+	rmSync(stateFile(stateDir, "browserHandoffAck"), { force: true });
+	const receipt = {
+		version: 1,
+		id: input.id,
+		phase: "prepared",
+		preparedAt: input.now,
+		updatedAt: input.now,
+		...input.initiator !== void 0 && input.initiator !== "" ? { initiator: input.initiator } : {},
+		previous: summarizeLaunchSpec(input.previous),
+		target: summarizeLaunchSpec(input.target),
+		...input.transition === void 0 ? {} : { transition: {
+			planSha256: input.transition.planSha256,
+			operationCount: input.transition.operationCount,
+			phase: "pending"
+		} },
+		supervisor: {
+			previousPid: input.previousSupervisorPid,
+			previousStartToken: input.previousSupervisorStartToken
+		},
+		child: { previousPid: input.previousOwnership.childPid },
+		ownership: { previous: input.previousOwnership },
+		authentication: { browserHandoff: input.browserHandoff === "required" ? "pending" : "off" },
+		browserHandoff: {
+			required: input.browserHandoff === "required",
+			status: input.browserHandoff === "required" ? "pending" : "off"
+		},
+		...input.target.preflight?.candidateProbeSha256 === void 0 ? {} : { preflight: {
+			surface: input.target.preflight.surface,
+			runnerExecutable: input.target.preflight.runnerExecutable,
+			runnerRuntimeArgs: input.target.preflight.runnerRuntimeArgs,
+			runnerPath: input.target.preflight.runnerPath,
+			runnerSha256: input.target.preflight.runnerSha256,
+			installAnchor: input.target.preflight.installAnchor,
+			installAnchorSha256: input.target.preflight.installAnchorSha256,
+			hostPackageVersion: input.target.preflight.hostPackageVersion,
+			targetCommandSha256: input.target.preflight.targetCommandSha256,
+			candidateProbeSha256: input.target.preflight.candidateProbeSha256,
+			candidateProbeProvenance: "caller-supplied",
+			candidateProbe: "pass",
+			composition: "pass"
+		} },
+		attempts: [],
+		failureCount: {
+			target: 0,
+			previous: 0
+		},
+		recovery: {
+			policy: input.recoveryPolicy,
+			result: "pending"
+		},
+		events: [{
+			at: input.now,
+			kind: "prepared"
+		}]
+	};
+	atomicWriteJson(stateFile(stateDir, "launchCutover"), receipt);
+	atomicWriteJson(stateFile(stateDir, "launchSpec"), {
+		version: 1,
+		mode: "cutover",
+		cutoverId: input.id,
+		selected: "target",
+		previous: input.previous,
+		target: input.target,
+		...input.transition === void 0 ? {} : { transition: input.transition }
+	});
+	return receipt;
+}
+function updateRestartRecord(stateDir, receipt, outcome) {
+	const error = outcome === "restored" ? "launch cutover failed; the previous complete launch specification was restored" : outcome === "awaiting-user" ? "launch cutover failed; recovery policy requires waiting for user action" : outcome === "prepare-failed" ? "launch cutover was not started; the previous launch specification remains active" : void 0;
+	atomicWriteJson(stateFile(stateDir, "lastRestart"), {
+		exitAt: Date.now(),
+		...receipt.initiator !== void 0 ? { initiator: receipt.initiator } : {},
+		...receipt.child.previousPid !== void 0 ? { pid: receipt.child.previousPid } : {},
+		...error !== void 0 ? { error } : {},
+		cutover: {
+			id: receipt.id,
+			outcome,
+			receipt: stateFile(stateDir, "launchCutover")
+		}
+	});
+}
+function requireReceipt(stateDir, id) {
+	const receipt = readCutoverReceipt(stateDir);
+	if (receipt === null || receipt.id !== id) throw new Error(`cutover receipt ${id} is not active`);
+	return receipt;
+}
+function appendEvent(receipt, kind, detail, now) {
+	receipt.updatedAt = now;
+	receipt.events = [...receipt.events, {
+		at: now,
+		kind,
+		...detail !== void 0 && detail !== "" ? { detail } : {}
+	}].slice(-100);
+}
+/**
+* Apply one watchdog event. Arguments are deliberately credential-free; the
+* launch URL itself never crosses this boundary or lands in the receipt.
+*/
+function recordCutoverEvent(stateDir, id, kind, args, now) {
+	const receipt = requireReceipt(stateDir, id);
+	const numberAt = (index, label) => {
+		const value = Number(args[index]);
+		if (!Number.isInteger(value) || value < 0) throw new Error(`${kind}: invalid ${label}`);
+		return value;
+	};
+	const pidAt = (index, label) => {
+		const value = numberAt(index, label);
+		if (value === 0) throw new Error(`${kind}: invalid ${label}`);
+		return value;
+	};
+	let terminal;
+	let stableSpec;
+	switch (kind) {
+		case "driver-started":
+			receipt.phase = "supervisor-starting";
+			receipt.supervisor.targetDriverPid = pidAt(0, "driver pid");
+			if (args[1] === void 0 || args[1] === "") throw new Error("driver-started: driver start identity is required");
+			receipt.supervisor.targetDriverStartToken = args[1];
+			break;
+		case "supervisor-ready":
+			receipt.phase = "supervisor-ready";
+			receipt.supervisor.targetPid = pidAt(0, "supervisor pid");
+			if (args[1] === void 0 || args[1] === "") throw new Error("supervisor-ready: supervisor start identity is required");
+			receipt.supervisor.targetStartToken = args[1];
+			break;
+		case "previous-supervisor-retired": {
+			const outcome = args[0];
+			if (outcome !== "yielded" && outcome !== "identity-gone" && outcome !== "forced") throw new Error("previous-supervisor-retired: invalid outcome");
+			receipt.supervisor.previousRetirement = outcome;
+			break;
+		}
+		case "child-started": {
+			const role = args[0];
+			if (role !== "target" && role !== "previous") throw new Error("child-started: invalid role");
+			const attempt = numberAt(1, "attempt");
+			const childPid = pidAt(2, "child pid");
+			const childStartToken = args[3];
+			if (childStartToken === void 0 || childStartToken === "") throw new Error("child-started: child start identity is required");
+			if (role === "target" && receipt.transition !== void 0 && receipt.transition.phase !== "applied") throw new Error("child-started: target transition has not been applied");
+			if (role === "previous" && receipt.transition !== void 0 && receipt.transition.phase !== "rolled-back") throw new Error("child-started: previous transition has not been rolled back");
+			receipt.phase = role === "target" ? "target-starting" : "restoring";
+			if (role === "target") receipt.child.targetPid = childPid;
+			else receipt.child.restoredPid = childPid;
+			receipt.authentication = { browserHandoff: receipt.authentication.browserHandoff === "off" ? "off" : "pending" };
+			receipt.browserHandoff = {
+				required: receipt.browserHandoff.required,
+				status: receipt.browserHandoff.required ? "pending" : "off"
+			};
+			rmSync(stateFile(stateDir, "browserHandoffAck"), { force: true });
+			delete receipt.readiness;
+			delete receipt.canary;
+			if (role === "target") receipt.targetValidation = {};
+			else receipt.recovery.validation = {};
+			receipt.attempts.push({
+				role,
+				number: attempt,
+				childPid,
+				childStartToken,
+				startedAt: now
+			});
+			break;
+		}
+		case "ownership-stable": {
+			const role = args[0];
+			if (role !== "target" && role !== "previous") throw new Error("ownership-stable: invalid role");
+			const ownership = {
+				childPid: pidAt(1, "child pid"),
+				childStartToken: args[2] ?? "",
+				listenerPid: pidAt(3, "listener pid"),
+				listenerStartToken: args[4] ?? ""
+			};
+			if (ownership.childStartToken === "" || ownership.listenerStartToken === "") throw new Error("ownership-stable: child/listener start identity is required");
+			const stableWindowMs = numberAt(5, "stable window");
+			const retryCount = numberAt(6, "retry count");
+			if (stableWindowMs < 1 || retryCount !== 0) throw new Error("ownership-stable: stable window must be positive and retry count must be zero");
+			const attempt = [...receipt.attempts].reverse().find((candidate) => candidate.role === role && candidate.outcome === void 0);
+			if (attempt === void 0 || attempt.childPid !== ownership.childPid || attempt.childStartToken !== ownership.childStartToken) throw new Error(`ownership-stable: ${role} identity does not match the active attempt`);
+			if (role === "target") receipt.ownership.target = ownership;
+			else receipt.ownership.restored = ownership;
+			receipt.readiness = {
+				role,
+				childPid: ownership.childPid,
+				listenerPid: ownership.listenerPid,
+				stableWindowMs,
+				retryCount
+			};
+			if (role === "target") {
+				receipt.targetValidation ??= {};
+				receipt.targetValidation.readiness = receipt.readiness;
+			} else {
+				receipt.recovery.validation ??= {};
+				receipt.recovery.validation.readiness = receipt.readiness;
+			}
+			break;
+		}
+		case "transport":
+			receipt.authentication.transportStatus = numberAt(0, "HTTP status");
+			break;
+		case "launch-url":
+			receipt.authentication.launchUrlObserved = true;
+			break;
+		case "auth-exchange":
+			receipt.authentication.exchangeStatus = numberAt(0, "HTTP status");
+			break;
+		case "authenticated":
+			receipt.authentication.authenticatedStatus = numberAt(0, "HTTP status");
+			break;
+		case "browser-handoff": {
+			const outcome = args[0];
+			if (outcome !== "acknowledged" && outcome !== "off" && outcome !== "failed") throw new Error("browser-handoff: invalid outcome");
+			if (outcome === "acknowledged") {
+				const channel = args[1];
+				const authentication = args[2];
+				const authority = args[3];
+				if (channel !== "original-tab" && channel !== "fallback-tab" || authentication !== "existing-cookie" && authentication !== "launch-url" || authority === void 0 || authority === "") throw new Error("browser-handoff: invalid acknowledgement evidence");
+				if (receipt.readiness === void 0) throw new Error("browser-handoff: server readiness is not proven");
+				if (receipt.readiness.role === "target" && receipt.targetValidation?.canary?.outcome !== "pass") throw new Error("browser-handoff: target canary has not passed");
+				if (receipt.readiness.role === "previous" && receipt.recovery.validation?.canary === void 0) throw new Error("browser-handoff: restored-previous canary has not settled");
+				receipt.browserHandoff = {
+					required: true,
+					status: "acknowledged",
+					channel,
+					authentication,
+					authority,
+					acknowledgedAt: now
+				};
+			} else receipt.browserHandoff = {
+				required: outcome !== "off",
+				status: outcome
+			};
+			receipt.authentication.browserHandoff = receipt.browserHandoff.status;
+			break;
+		}
+		case "browser-fallback-opened":
+			if (!receipt.browserHandoff.required) throw new Error("browser-fallback-opened: handoff is disabled");
+			if (receipt.readiness?.role === "target" && receipt.targetValidation?.canary?.outcome !== "pass") throw new Error("browser-fallback-opened: target canary has not passed");
+			if (receipt.readiness?.role === "previous" && receipt.recovery.validation?.canary === void 0) throw new Error("browser-fallback-opened: restored-previous canary has not settled");
+			receipt.browserHandoff = {
+				required: true,
+				status: "fallback-opened"
+			};
+			receipt.authentication.browserHandoff = "fallback-opened";
+			break;
+		case "control-requested": {
+			const action = args[0];
+			if (action !== "abort" && action !== "restore-previous") throw new Error("control-requested: invalid action");
+			receipt.recovery.detail = action === "restore-previous" ? "operator explicitly requested restoration of the previous complete launch specification" : `operator aborted the cutover; applying pre-approved ${receipt.recovery.policy} policy`;
+			break;
+		}
+		case "attempt-failed": {
+			const role = args[0];
+			if (role !== "target" && role !== "previous") throw new Error("attempt-failed: invalid role");
+			const attempt = numberAt(1, "attempt");
+			const detail = args.slice(2).join(" ");
+			const found = [...receipt.attempts].reverse().find((candidate) => candidate.role === role && candidate.number === attempt);
+			if (found !== void 0) {
+				found.outcome = "failed";
+				if (detail !== "") found.detail = detail;
+			}
+			receipt.failureCount ??= {
+				target: 0,
+				previous: 0
+			};
+			receipt.failureCount[role] += 1;
+			receipt.phase = role === "target" ? "target-retrying" : "restoring";
+			receipt.recovery.detail = detail;
+			break;
+		}
+		case "restoring":
+			if (receipt.transition !== void 0 && receipt.transition.phase !== "rolled-back") throw new Error("restoring: filesystem transition has not been rolled back");
+			receipt.phase = "restoring";
+			receipt.recovery.detail = args.join(" ");
+			receipt.authentication = { browserHandoff: receipt.authentication.browserHandoff === "off" ? "off" : "pending" };
+			receipt.browserHandoff = {
+				required: receipt.browserHandoff.required,
+				status: receipt.browserHandoff.required ? "pending" : "off"
+			};
+			rmSync(stateFile(stateDir, "browserHandoffAck"), { force: true });
+			delete receipt.readiness;
+			delete receipt.canary;
+			receipt.recovery.validation = {};
+			{
+				const state = readLaunchState(stateDir);
+				if (state?.mode !== "cutover" || state.cutoverId !== id) throw new Error("restoring: cutover launch state is missing");
+				atomicWriteJson(stateFile(stateDir, "launchSpec"), {
+					...state,
+					selected: "previous"
+				});
+			}
+			break;
+		case "transition": {
+			if (receipt.transition === void 0) throw new Error("transition: cutover has no transition plan");
+			const outcome = args[0];
+			if (args[1] !== receipt.transition.planSha256) throw new Error("transition: plan digest does not match");
+			if (outcome === "applied") {
+				if (receipt.transition.phase === "rolled-back") throw new Error("transition: a rolled-back plan cannot be applied");
+				receipt.transition = {
+					...receipt.transition,
+					phase: "applied"
+				};
+			} else if (outcome === "rolled-back") receipt.transition = {
+				...receipt.transition,
+				phase: "rolled-back"
+			};
+			else if (outcome === "apply-failed" || outcome === "rollback-failed") receipt.transition = {
+				...receipt.transition,
+				phase: "failed",
+				failureOperation: outcome === "apply-failed" ? "apply" : "rollback",
+				...args.length > 2 ? { detail: args.slice(2).join(" ") } : {}
+			};
+			else throw new Error("transition: invalid outcome");
+			break;
+		}
+		case "canary": {
+			const explicitRole = args[0] === "target" || args[0] === "previous" ? args[0] : void 0;
+			const role = explicitRole ?? receipt.readiness?.role;
+			const outcomeIndex = explicitRole === void 0 ? 0 : 1;
+			const outcome = args[outcomeIndex];
+			if (role !== "target" && role !== "previous" || outcome !== "pass" && outcome !== "fail" && outcome !== "skipped") throw new Error("canary: invalid role or outcome");
+			if (role === "target" && outcome === "skipped") throw new Error("canary: target canary cannot be skipped");
+			const detail = args.slice(outcomeIndex + 1).join(" ");
+			const canary = {
+				outcome,
+				...detail === "" ? {} : { detail }
+			};
+			if (role === "target") {
+				receipt.targetValidation ??= {};
+				receipt.targetValidation.canary = canary;
+				receipt.canary = canary;
+			} else {
+				receipt.recovery.validation ??= {};
+				receipt.recovery.validation.canary = canary;
+				delete receipt.canary;
+			}
+			break;
+		}
+		case "ready": {
+			const role = args[0];
+			if (role !== "target" && role !== "previous") throw new Error("ready: invalid role");
+			const state = readLaunchState(stateDir);
+			if (state?.mode !== "cutover" || state.cutoverId !== id) throw new Error("ready: cutover launch state is missing");
+			const ownership = role === "target" ? receipt.ownership?.target : receipt.ownership?.restored;
+			if (ownership === void 0 || receipt.readiness?.role !== role || receipt.readiness.childPid !== ownership.childPid || receipt.readiness.listenerPid !== ownership.listenerPid || receipt.readiness.retryCount !== 0) throw new Error(`ready: ${role} child/listener ownership was not stable and proven`);
+			const found = [...receipt.attempts].reverse().find((candidate) => candidate.role === role && candidate.outcome === void 0);
+			if (found === void 0 || found.childPid !== ownership.childPid || found.childStartToken !== ownership.childStartToken) throw new Error(`ready: ${role} ownership does not match the active attempt`);
+			if (role === "target" && receipt.targetValidation?.canary?.outcome !== "pass") throw new Error("ready: target canary has not passed");
+			if (role === "previous" && receipt.recovery.validation?.canary === void 0) throw new Error("ready: restored-previous canary has not settled");
+			if (role === "target" && receipt.transition !== void 0 && receipt.transition.phase !== "applied") throw new Error("ready: target transition is not applied");
+			if (role === "previous" && receipt.transition !== void 0 && receipt.transition.phase !== "rolled-back") throw new Error("ready: previous transition is not rolled back");
+			if (receipt.authentication.launchUrlObserved === true && receipt.browserHandoff.required && receipt.browserHandoff.status !== "acknowledged") throw new Error("ready: authenticated launch URL has no browser acknowledgement");
+			found.outcome = "ready";
+			if (role === "target") {
+				receipt.phase = "ready";
+				receipt.recovery.result = "not-needed";
+				terminal = "target-ready";
+			} else {
+				receipt.phase = "restored";
+				receipt.recovery.result = "restored";
+				terminal = "restored";
+			}
+			if (receipt.authentication.browserHandoff === "pending" && receipt.authentication.launchUrlObserved !== true) {
+				receipt.authentication.browserHandoff = "not-required";
+				receipt.browserHandoff = {
+					required: receipt.browserHandoff.required,
+					status: "not-required"
+				};
+			}
+			stableSpec = state[role];
+			atomicWriteJson(stateFile(stateDir, "instanceLaunch"), {
+				command: state[role].command,
+				source: "supervisor",
+				supervised: true,
+				port: state[role].port,
+				recordedAt: now
+			});
+			break;
+		}
+		case "awaiting-user":
+			receipt.phase = "awaiting-user";
+			receipt.recovery.result = "waiting-for-user";
+			receipt.recovery.detail = args.join(" ");
+			terminal = "awaiting-user";
+			break;
+		case "prepare-failed": {
+			const state = readLaunchState(stateDir);
+			if (state?.mode === "cutover" && state.cutoverId === id) stableSpec = state.previous;
+			receipt.phase = "prepare-failed";
+			receipt.recovery.result = "prepare-failed";
+			receipt.recovery.detail = args.join(" ");
+			terminal = "prepare-failed";
+			break;
+		}
+		default: throw new Error(`unknown cutover event ${kind}`);
+	}
+	appendEvent(receipt, kind, args.join(" "), now);
+	if (terminal !== void 0) updateRestartRecord(stateDir, receipt, terminal);
+	atomicWriteJson(stateFile(stateDir, "launchCutover"), receipt);
+	if (terminal !== void 0) clearCutoverControl(stateDir, id);
+	if (terminal !== void 0) {
+		if (terminal !== "target-ready" && terminal !== "restored") rmSync(stateFile(stateDir, "browserHandoffRequest"), { force: true });
+		rmSync(stateFile(stateDir, "browserHandoffAck"), { force: true });
+	}
+	if (stableSpec !== void 0) atomicWriteJson(stateFile(stateDir, "launchSpec"), {
+		version: 1,
+		mode: "stable",
+		active: stableSpec
+	});
+	return receipt;
+}
+/** A restarted instance must not wake/report while the watchdog is still proving the cutover. */
+function cutoverBlocksWake(stateDir) {
+	const state = readLaunchState(stateDir);
+	if (state?.mode !== "cutover") return false;
+	const receipt = readCutoverReceipt(stateDir);
+	if (receipt === null || receipt.id !== state.cutoverId) return true;
+	return ![
+		"ready",
+		"restored",
+		"awaiting-user",
+		"prepare-failed"
+	].includes(receipt.phase);
+}
+/** The active transaction's full specs plus its redacted policy receipt. */
+function activeCutover(stateDir) {
+	const state = readLaunchState(stateDir);
+	const receipt = readCutoverReceipt(stateDir);
+	if (state?.mode !== "cutover" || receipt === null || receipt.id !== state.cutoverId) return null;
+	if (receipt.phase === "ready" || receipt.phase === "restored" || receipt.phase === "prepare-failed") return null;
+	return {
+		state,
+		receipt
+	};
+}
+//#endregion
+//#region lib/types/restart-context.js
+/**
+* Restart-record context injection and interrupted-session continuity. After
+* a scheduled restart, the FULL report waits for the initiating session's
+* root agent, whenever it resumes (session restore is lazy, so no other
+* session is ever woken for reporting); a record without an initiator is
+* claimed by the first root agent created. Separately, a snapshot written at
+* SIGTERM time (`interrupted-sessions.json`) records which root sessions had
+* a live turn when the process stopped, so the next restart boot can resume
+* those sessions and queue a "continue" turn. Pure logic reads the durable
+* files; the plugin wires them into `agent/created` and `agent.followup`.
+*/
+/** Absolute path of the restart record inside a state directory. */
+function restartRecordFile(stateDir) {
+	return stateFile(stateDir, "lastRestart");
+}
+/** Absolute path of the interrupted-session snapshot inside a state directory. */
+function interruptedSnapshotFile(stateDir) {
+	return stateFile(stateDir, "interruptedSessions");
+}
+/**
+* The pending restart record, or null when none is awaiting a report (absent,
+* unparseable, or settled). The record stays pending until the initiator
+* resumes or the next restart replaces it (a new exitAt) — those are the only
+* retirement paths.
+* @param stateDir - state directory.
+* @returns the record without `reportedAt`, or null.
+*/
+function pendingRestartRecord(stateDir) {
+	const file = restartRecordFile(stateDir);
+	if (!existsSync(file)) return null;
+	try {
+		const record = JSON.parse(readFileSync(file, "utf8"));
+		return record.reportedAt !== void 0 ? null : record;
+	} catch {
+		return null;
+	}
+}
+/**
+* The model-visible restart report (Chinese product copy, factual).
+* @param record - the pending restart record.
+* @param canaryPending - whether the restart marker is still present (the
+* watchdog has not yet run/cleared the canary).
+* @returns the report text, or an empty string for a malformed record.
+*/
+function restartContextText(record, canaryPending) {
+	if (record.exitAt === void 0 && record.error === void 0) return "";
+	const time = record.exitAt !== void 0 ? new Date(record.exitAt).toISOString() : "未知时间";
+	if (record.cutover !== void 0) {
+		if (record.cutover.outcome === "target-ready") return `[ankh-guard] 服务于 ${time} 完成启动配置切换；新 supervisor 与 child 已接管，应用就绪证明（受保护宿主需要时包含认证交接）和金丝雀均通过。耐久回执：${record.cutover.receipt}。请读取回执中的 PID、配置摘要、认证、重试与恢复字段，并向用户生成最终报告。`;
+		if (record.cutover.outcome === "restored") return `[ankh-guard] 服务于 ${time} 尝试切换启动配置失败，但已按重启前批准的策略恢复上一份完整启动配置并重新就绪。耐久回执：${record.cutover.receipt}。请读取回执并向用户报告失败、重试和恢复结果。`;
+		if (record.cutover.outcome === "awaiting-user") return `[ankh-guard] 服务于 ${time} 切换启动配置失败；批准的策略是停留等待用户，watchdog 未擅自重置仓库。耐久回执：${record.cutover.receipt}。请读取回执并向用户报告当前等待点。`;
+		return `[ankh-guard] 启动配置切换在停止旧实例前失败，上一份启动配置仍有效。耐久回执：${record.cutover.receipt}。请读取回执并向用户报告准备阶段失败。`;
+	}
+	if (record.compositionRecovered === true) return `[ankh-guard] 服务于 ${time} 前后连续启动失败，watchdog 已自动回滚到上次健康的 profile 组合并恢复。${record.detail !== void 0 ? `回滚内容：${record.detail}。` : ""}原组合已备份到 state 的 composition-backup-* 目录。建议用户修复或卸载相关插件后重新安装验证。请向用户简要回报本次自动恢复与上述建议。`;
+	if (record.unexpected === true) return `[ankh-guard] 服务最近发生过一次非计划退出（崩溃或被手动停止）：${time}，watchdog 已自动拉起实例。请向用户简要回报这次非计划重启。`;
+	return `[ankh-guard] 服务最近重启过：${time}，退出${record.error !== void 0 ? `失败（${record.error}）` : "成功"}，${canaryPending ? "金丝雀尚未完成" : "金丝雀已处理"}。请向用户简要回报本次重启结果。`;
+}
+/**
+* The model-visible "continue" prompt for a session whose turn was
+* interrupted by the restart (its log tail was closed with
+* `reason.kind === 'interrupted'` by crash-recovery repair).
+* @param exitAt - epoch milliseconds of the exit that interrupted the turn.
+* @returns the prompt text.
+*/
+function continueInterruptedText(exitAt) {
+	return `[ankh-guard] 服务于 ${new Date(exitAt).toISOString()} 重启，你上次正在进行的回合被中断（日志已标记 interrupted）。请检查当前状态并继续未完成的任务；若任务已不再适用，简要说明原因后停止。`;
+}
+/**
+* The combined prompt for a session that is BOTH the restart's initiator and
+* an interrupted session: one turn continues the work and reports the
+* restart, instead of two near-duplicate turns.
+* @param record - the pending restart record.
+* @param canaryPending - whether the restart marker is still present.
+* @returns the prompt text, or an empty string for a malformed record.
+*/
+function continueAndReportText(record, canaryPending) {
+	if (record.exitAt === void 0 && record.error === void 0) return "";
+	const time = record.exitAt !== void 0 ? new Date(record.exitAt).toISOString() : "未知时间";
+	if (record.cutover !== void 0) return `[ankh-guard] 服务于 ${time} 发生启动配置切换：${record.cutover.outcome === "target-ready" ? "新启动配置的应用就绪证明（受保护宿主需要时包含认证交接）与金丝雀均已通过" : record.cutover.outcome === "restored" ? "目标启动失败，上一份完整启动配置已恢复并重新就绪" : record.cutover.outcome === "awaiting-user" ? "目标启动失败，watchdog 正按批准策略等待用户" : "切换在停止旧实例前失败，上一份启动配置仍有效"}。你上次正在进行的回合被中断（日志已标记 interrupted）。耐久回执：${record.cutover.receipt}。请检查当前状态并继续未完成的任务，读取回执后向用户报告 supervisor/child PID、配置摘要、认证、重试与恢复结果。`;
+	if (record.compositionRecovered === true) return `[ankh-guard] 服务于 ${time} 前后连续启动失败，watchdog 已自动回滚到上次健康的 profile 组合并恢复（最近的插件变更已卸载）。你上次正在进行的回合被中断（日志已标记 interrupted）。请检查当前状态并继续未完成的任务，并向用户简要回报本次自动恢复；若任务已不再适用，简要说明原因后停止。`;
+	if (record.unexpected === true) return `[ankh-guard] 服务于 ${time} 发生非计划退出（崩溃或被手动停止），watchdog 已自动拉起实例。你上次正在进行的回合被中断（日志已标记 interrupted）。请检查当前状态并继续未完成的任务，并向用户简要回报这次非计划重启；若任务已不再适用，简要说明原因后停止。`;
+	return `[ankh-guard] 服务于 ${time} 重启，退出${record.error !== void 0 ? `失败（${record.error}）` : "成功"}，${canaryPending ? "金丝雀尚未完成" : "金丝雀已处理"}。你上次正在进行的回合被中断（日志已标记 interrupted）。请检查当前状态并继续未完成的任务，并向用户简要回报本次重启结果；若任务已不再适用，简要说明原因后停止。`;
+}
+/**
+* Acknowledge a restart record so it injects exactly once.
+* @param stateDir - state directory.
+* @param record - the record being reported.
+* @param now - epoch milliseconds of the acknowledgement.
+*/
+function acknowledgeRestartRecord(stateDir, record, now) {
+	try {
+		atomicWrite(restartRecordFile(stateDir), `${JSON.stringify({
+			...record,
+			reportedAt: now
+		})}\n`);
+	} catch {}
+}
+/**
+* Record an unplanned-exit recovery (the watchdog respawned the instance with
+* no restart marker), unless a record still awaits its report. Returns whether
+* the record was written — the caller (CLI verb, invoked by the watchdog) logs
+* either way, so the watchdog log must never claim a write that was skipped.
+* @param stateDir - state directory.
+* @param now - epoch milliseconds of the recovery.
+* @returns true when the record was written, false when a pending record was kept.
+*/
+function writeUnexpectedExitRecord(stateDir, now) {
+	if (pendingRestartRecord(stateDir) !== null) return false;
+	mkdirSync(stateDir, { recursive: true });
+	atomicWrite(restartRecordFile(stateDir), `${JSON.stringify({
+		exitAt: now,
+		unexpected: true
+	})}\n`);
+	return true;
+}
+/**
+* Record the restart verb's outcome for the report machinery (the restart
+* verb is otherwise invisible to it: it writes no marker and no record, so a
+* restart it drove would never be reported to any session). Mirrors the exit
+* agent's record semantics; a still-pending earlier record is replaced only
+* by a completed newer restart.
+* @param stateDir - state directory.
+* @param record - the outcome fields (exitAt/pid for a stop, error on failure).
+*/
+function writeRestartOutcome(stateDir, record) {
+	mkdirSync(stateDir, { recursive: true });
+	atomicWrite(restartRecordFile(stateDir), `${JSON.stringify(record)}\n`);
+}
+/**
+* Record the watchdog's ADOPTION takeover — the first restart a deployment
+* ever sees: `supervise` handed the port to the watchdog, which stopped the
+* pre-existing owner and booted the supervised instance. The session that
+* established supervision promised the user a verification report; without
+* this record nothing wakes it after the bounce (the adoption writes no
+* restart marker and no outcome record). Never overwrites a record that still
+* awaits its report.
+* @param stateDir - state directory.
+* @param now - epoch milliseconds of the takeover boot.
+* @param initiator - the session that established supervision, when known.
+* @returns whether the record was written.
+*/
+function writeAdoptionRecord(stateDir, now, initiator) {
+	if (pendingRestartRecord(stateDir) !== null) return false;
+	mkdirSync(stateDir, { recursive: true });
+	atomicWrite(restartRecordFile(stateDir), `${JSON.stringify({
+		exitAt: now,
+		...initiator !== void 0 && initiator !== "" ? { initiator } : {}
+	})}\n`);
+	return true;
+}
+/**
+* Record a composition rollback recovery: repeated boot failures whose
+* subject lived outside the checkout (a freshly installed plugin is the
+* common case) were recovered by restoring the last healthy profile
+* composition. The service is UP again minus the newest plugin change — the
+* recovery must be reported, never silent.
+*
+* Pending-record policy: a pending record with real diagnostics (error /
+* unexpected) is kept; a BARE exit outcome (exitAt/pid only) is merged over —
+* the watchdog knows the boot actually failed and recovered, so its record is
+* the truthful one, and it inherits the exit record's initiator so the report
+* still reaches its owner.
+* @param stateDir - state directory.
+* @param now - epoch milliseconds of the recovery boot.
+* @param detail - what changed in the rolled-back composition (e.g. the
+* unmounted bundle rows), for the report text.
+* @returns whether the record was written.
+*/
+function writeCompositionRecovery(stateDir, now, detail) {
+	const pending = pendingRestartRecord(stateDir);
+	if (pending !== null && (pending.error !== void 0 || pending.unexpected === true || pending.compositionRecovered === true)) return false;
+	mkdirSync(stateDir, { recursive: true });
+	atomicWrite(restartRecordFile(stateDir), `${JSON.stringify({
+		exitAt: now,
+		compositionRecovered: true,
+		...detail !== void 0 && detail !== "" ? { detail } : {},
+		...pending?.initiator !== void 0 ? { initiator: pending.initiator } : {}
+	})}\n`);
+	return true;
+}
+/**
+* Persist the launch record (atomic). The instance-facing side of
+* {@link writeInstanceLaunch}: only an `instance`-sourced record may be
+* replaced by another — a `supervisor` record carries the FULL supervision
+* chain (watchdog, launch wrapper) and the inner process must not overwrite
+* it with its own bare argv.
+* @param stateDir - state directory.
+* @param launch - the launch facts.
+* @returns whether the record was written.
+*/
+function writeInstanceLaunch(stateDir, launch) {
+	if (readInstanceLaunch(stateDir)?.source === "supervisor") return false;
+	mkdirSync(stateDir, { recursive: true });
+	atomicWrite(stateFile(stateDir, "instanceLaunch"), `${JSON.stringify(launch)}\n`);
+	return true;
+}
+/** POSIX single-quote one word for a shell command line. */
+function shellQuote(word) {
+	return `'${word.replace(/'/g, "'\\''")}'`;
+}
+/**
+* Render the instance's launch as a shell command: cwd, DSH_* env, and the
+* FULL node invocation — execArgv included, because a tsx chain
+* (`node --import tsx …`) rendered without it becomes a bare `node bin.ts`
+* that cannot load TypeScript sources.
+*/
+/**
+* Per-invocation transients, never launch configuration: the restart driver's
+* own marker, the calling session's identity, and the shell/web hand-off
+* vars. A recorded launch must not leak them into the next instance (a
+* restart driver reading DSH_ANKH_RESTART_DRIVER would misbehave; a stale
+* DSH_SESSION_ID misattributes reports).
+*/
+const TRANSIENT_ENV_KEYS = /* @__PURE__ */ new Set([
+	"DSH_ANKH_RESTART_DRIVER",
+	"DSH_SESSION_ID",
+	"DSH_SESSION_JSONL",
+	"DSH_WEB_URL",
+	"DSH_SHELL"
+]);
+function buildLaunchCommand(execPath, execArgv, args, cwd, env) {
+	const envPart = Object.entries(env).filter(([key]) => !TRANSIENT_ENV_KEYS.has(key)).map(([key, value]) => `${key}=${shellQuote(value)}`).join(" ");
+	const argv = [
+		execPath,
+		...execArgv,
+		...args
+	].map(shellQuote).join(" ");
+	return `cd ${shellQuote(cwd)} && ${envPart !== "" ? `${envPart} ` : ""}${argv}`;
+}
+/** Replace any record unconditionally (the supervisor's own write path). */
+function writeInstanceLaunchAsSupervisor(stateDir, launch) {
+	mkdirSync(stateDir, { recursive: true });
+	atomicWrite(stateFile(stateDir, "instanceLaunch"), `${JSON.stringify(launch)}\n`);
+}
+/**
+* Read the launch record, or null when absent/unparseable (older deployments,
+* or the plugin never applied in this home).
+* @param stateDir - state directory.
+* @returns the record, or null.
+*/
+function readInstanceLaunch(stateDir) {
+	try {
+		const launch = JSON.parse(readFileSync(stateFile(stateDir, "instanceLaunch"), "utf8"));
+		return typeof launch.command === "string" ? launch : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Read the shutdown snapshot, or null when absent/unparseable. Malformed
+* snapshots are dropped by the caller's delete-after-read, never retried.
+* @param stateDir - state directory.
+* @returns the snapshot, or null.
+*/
+function readInterruptedSnapshot(stateDir) {
+	const file = interruptedSnapshotFile(stateDir);
+	if (!existsSync(file)) return null;
+	try {
+		const snapshot = JSON.parse(readFileSync(file, "utf8"));
+		if (!Array.isArray(snapshot.resume) || !Array.isArray(snapshot.interrupted)) return null;
+		return snapshot;
+	} catch {
+		return null;
+	}
+}
+/**
+* Write the shutdown snapshot (synchronous — called from a signal handler).
+* The state directory is created on demand: a fresh deployment has no
+* `$DSH_HOME/state` yet, and a missing directory must not silently drop the
+* snapshot.
+* @param stateDir - state directory.
+* @param snapshot - the snapshot to persist.
+*/
+function writeInterruptedSnapshot(stateDir, snapshot) {
+	try {
+		mkdirSync(stateDir, { recursive: true });
+		atomicWrite(interruptedSnapshotFile(stateDir), `${JSON.stringify(snapshot)}\n`);
+	} catch {}
+}
+/** Write a small durable file atomically (tmp + rename in the same directory). */
+function atomicWrite(file, content) {
+	const tmp = `${file}.${process.pid}.tmp`;
+	writeFileSync(tmp, content);
+	renameSync(tmp, file);
+}
+/**
+* Persist the skill-registration outcome (atomic, best-effort). A migration
+* or repackaging that drops the skill is otherwise invisible until someone
+* notices the catalog entry missing — this record lets `check-env` surface it.
+* @param stateDir - state directory.
+* @param record - the outcome of this boot's registration attempt.
+*/
+function writeSkillRegistration(stateDir, record) {
+	try {
+		mkdirSync(stateDir, { recursive: true });
+		atomicWrite(stateFile(stateDir, "skillRegistration"), `${JSON.stringify(record)}\n`);
+	} catch {}
+}
+/**
+* Read the skill-registration record, or null when absent/unparseable (the
+* plugin never applied with this state dir, or predates the record).
+* @param stateDir - state directory.
+* @returns the record, or null.
+*/
+function readSkillRegistration(stateDir) {
+	try {
+		const record = JSON.parse(readFileSync(stateFile(stateDir, "skillRegistration"), "utf8"));
+		return typeof record.registered === "boolean" && typeof record.at === "number" ? record : null;
+	} catch {
+		return null;
+	}
+}
+/** The tool whose open call means the turn is parked waiting for the human. */
+const USER_INPUT_TOOL = "ask_user_question";
+/**
+* Whether the session's last turn ended PARKED on user input: interrupted
+* while waiting on an open `ask_user_question` call, or on an approval
+* (`approval/asked` with no `approval/decided` in the same turn / after the
+* turn's start). A parked turn has no interrupted WORK — the card persists in
+* the log and the user answers whenever — so the restart resume must leave
+* such sessions alone (no resume, no continue injection, no replayed card).
+* @param events - the session's durable events (crash-repair already applied).
+* @returns whether the last interrupted turn was parked on user input.
+*/
+function isParkedOnUserInput(events) {
+	let parkedTurn;
+	let parkedTurnStartSeq = -1;
+	for (const event of events) {
+		const reason = event.data["reason"];
+		if (event.type === "turn/end" && reason?.kind === "interrupted") parkedTurn = event.data["turn"];
+	}
+	if (parkedTurn === void 0) return false;
+	for (const event of events) if (event.type === "turn/start" && event.data["turn"] === parkedTurn) parkedTurnStartSeq = event.seq ?? -1;
+	let lastToolName;
+	let pendingApproval = false;
+	for (const event of events) {
+		if (!(event.data["turn"] === parkedTurn || parkedTurnStartSeq >= 0 && (event.seq ?? -1) >= parkedTurnStartSeq)) continue;
+		if (event.type === "tool/call") lastToolName = event.data["name"];
+		if (event.type === "approval/asked") pendingApproval = true;
+		if (event.type === "approval/decided") pendingApproval = false;
+	}
+	return lastToolName === USER_INPUT_TOOL || pendingApproval;
+}
+//#endregion
+export { writeStableLaunchSpec as A, prepareLaunchCutover as C, selectedLaunchSpec as D, recordCutoverEvent as E, workingTreeChanges as F, currentHead as M, isWorkingTreeClean as N, summarizeLaunchState as O, resetToCheckpoint as P, cutoverBlocksWake as S, readLaunchState as T, writeRestartOutcome as _, interruptedSnapshotFile as a, activeCutover as b, readInstanceLaunch as c, restartContextText as d, writeAdoptionRecord as f, writeInterruptedSnapshot as g, writeInstanceLaunchAsSupervisor as h, continueInterruptedText as i, commitCheckpoint as j, writeCutoverControl as k, readInterruptedSnapshot as l, writeInstanceLaunch as m, buildLaunchCommand as n, isParkedOnUserInput as o, writeCompositionRecovery as p, continueAndReportText as r, pendingRestartRecord as s, acknowledgeRestartRecord as t, readSkillRegistration as u, writeSkillRegistration as v, readCutoverReceipt as w, commandSha256 as x, writeUnexpectedExitRecord as y };