@khorsheed/dsh-ankh-guard 0.1.1 → 0.3.0

package/lib/cli.js

@@ -1,14 +1,1032 @@
 #!/usr/bin/env node
 import { i as resolveStateDir, n as isDirectInvocation, r as resolveRepoDir, t as SRC_ARTIFACT_PATTERN } from "./defaults-CduvOcGq.js";
-import { _ as writeUnexpectedExitRecord, b as resetToCheckpoint, d as writeAdoptionRecord, h as writeRestartOutcome, l as readSkillRegistration, p as writeInstanceLaunchAsSupervisor, s as readInstanceLaunch, v as commitCheckpoint, y as currentHead } from "./restart-context-DmnQXNf-.js";
-import { c as stateFile, i as setCheckpoint, n as loadState, o as verifyCredential, r as recordCredential, s as lastGoodBootRevision, t as clearCredential } from "./state-Dhx9VG44.js";
-import { n as findPidOnPort, r as killPidTree, t as discoverLaunchCommand } from "./processes-hCAmwma-.js";
+import { A as writeStableLaunchSpec, C as prepareLaunchCutover, D as selectedLaunchSpec, E as recordCutoverEvent, F as workingTreeChanges, M as currentHead, N as isWorkingTreeClean, O as summarizeLaunchState, P as resetToCheckpoint, T as readLaunchState, _ as writeRestartOutcome, b as activeCutover, c as readInstanceLaunch, f as writeAdoptionRecord, h as writeInstanceLaunchAsSupervisor, j as commitCheckpoint, k as writeCutoverControl, p as writeCompositionRecovery, u as readSkillRegistration, w as readCutoverReceipt, x as commandSha256, y as writeUnexpectedExitRecord } from "./restart-context-DlaDZWKq.js";
+import { _ as processIdentity, c as appendTestLifecycleEvent, d as registerTestProcess, f as discoverLaunchCommand, h as killPidTree, l as appendTestLifecycleEventForProcess, m as findPidOnPort, n as TEST_PROCESS_ROLE_ENV, p as findOwnedListener, r as TEST_PROCESS_TEMP_ROOT_ENV, t as TEST_PROCESS_PORT_ENV, u as registerCurrentTestProcess, v as processIdentityMatches } from "./test-seam-dwvaKjRp.js";
+import { a as setProvenDeployment, c as lastGoodBootRevision, d as pidAlive, f as stateFile, i as setCheckpoint, l as livePidIn, n as loadState, r as recordCredential, s as verifyCredential, t as clearCredential, u as liveWatchdogPid } from "./state-CZMypGkB.js";
 import { execFileSync, spawn } from "node:child_process";
-import { existsSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
+import { chmodSync, constants, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
 import { connect } from "node:net";
-import { homedir } from "node:os";
-import { dirname, join, resolve, sep } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+//#region lib/types/deployment-proof.js
+/**
+* Reusable evidence for a pure, same-launch restart.
+*
+* A green credential is deliberately short lived: it authorizes one stop
+* close to the observed build/test run. Once that stop has completed
+* readiness and canary, however, the exact deployed inputs are known-good.
+* This module fingerprints those inputs so a later pure restart can reuse the
+* expensive proof without turning "same git HEAD" into a weak proxy for
+* "same deployment".
+*/
+const PROFILE_FILES = [
+	"cordis.patch.yml",
+	"cordis.yml",
+	"package.json",
+	"pnpm-lock.yaml",
+	"pnpm-workspace.yaml"
+];
+const HOST_RUNTIME_FILES = [
+	"package.json",
+	"pnpm-lock.yaml",
+	"pnpm-workspace.yaml",
+	"node_modules/.modules.yaml",
+	"node_modules/.pnpm-workspace-state-v1.json"
+];
+const SKIPPED_PACKAGE_DIRS = /* @__PURE__ */ new Set([
+	".git",
+	"coverage",
+	"node_modules"
+]);
+function hashChunk(hash, kind, logicalPath, value = "") {
+	hash.update(kind);
+	hash.update("\0");
+	hash.update(logicalPath);
+	hash.update("\0");
+	hash.update(value);
+	hash.update("\0");
+}
+/**
+* Hash a runtime tree, following links so a linked package cannot drift
+* outside the fingerprint. Real-directory de-duplication permits legal link
+* cycles without recursion loops. Special/dangling/unreadable nodes fail
+* closed.
+*/
+function hashRuntimePath(hash, absolutePath, logicalPath, seenDirectories, packageRoot = false) {
+	const info = lstatSync(absolutePath);
+	if (info.isSymbolicLink()) {
+		hashChunk(hash, "link", logicalPath, readlinkSync(absolutePath));
+		let target;
+		try {
+			target = realpathSync(absolutePath);
+		} catch (error) {
+			throw new Error(`deployment fingerprint refused dangling link ${logicalPath}: ${String(error)}`);
+		}
+		hashRuntimePath(hash, target, `${logicalPath}/@target`, seenDirectories, packageRoot);
+		return;
+	}
+	if (info.isFile()) {
+		hashChunk(hash, "file", logicalPath, readFileSync(absolutePath));
+		return;
+	}
+	if (!info.isDirectory()) throw new Error(`deployment fingerprint refused special file ${logicalPath}`);
+	const realDirectory = realpathSync(absolutePath);
+	if (seenDirectories.has(realDirectory)) {
+		hashChunk(hash, "cycle", logicalPath);
+		return;
+	}
+	seenDirectories.add(realDirectory);
+	hashChunk(hash, "dir", logicalPath);
+	for (const name of readdirSync(absolutePath).sort((left, right) => Buffer.from(left).compare(Buffer.from(right)))) {
+		if (packageRoot && SKIPPED_PACKAGE_DIRS.has(name)) {
+			hashChunk(hash, "excluded-dir", `${logicalPath}/${name}`);
+			continue;
+		}
+		hashRuntimePath(hash, join(absolutePath, name), `${logicalPath}/${name}`, seenDirectories, packageRoot);
+	}
+}
+function hashOptionalPath(hash, root, relativePath) {
+	const absolutePath = join(root, relativePath);
+	if (!existsSync(absolutePath)) {
+		hashChunk(hash, "absent", relativePath);
+		return;
+	}
+	hashRuntimePath(hash, absolutePath, relativePath, /* @__PURE__ */ new Set());
+}
+function dependencyInstallPath(profileDir, dependency) {
+	return join(profileDir, "node_modules", ...dependency.split("/"));
+}
+function fileDependencyPath(profileDir, specifier) {
+	if (!specifier.startsWith("file:")) return void 0;
+	const pathname = specifier.slice(5);
+	return isAbsolute(pathname) ? pathname : resolve(profileDir, pathname);
+}
+/** Hash profile inputs, installed direct packages, and file: source archives. */
+function profileRuntimeSha256(spec) {
+	const profileDir = join(spec.home, "profiles", spec.profile);
+	const manifestPath = join(profileDir, "package.json");
+	if (!existsSync(manifestPath)) throw new Error(`deployment fingerprint requires ${manifestPath}`);
+	let manifest;
+	try {
+		manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+	} catch (error) {
+		throw new Error(`deployment fingerprint could not parse profile package.json: ${String(error)}`);
+	}
+	const hash = createHash("sha256");
+	for (const file of PROFILE_FILES) hashOptionalPath(hash, profileDir, file);
+	const dependencies = Object.entries(manifest.dependencies ?? {}).sort(([left], [right]) => Buffer.from(left).compare(Buffer.from(right)));
+	for (const [name, source] of dependencies) {
+		const installed = dependencyInstallPath(profileDir, name);
+		if (!existsSync(installed)) throw new Error(`deployment fingerprint requires installed profile dependency ${name}`);
+		hashRuntimePath(hash, installed, `installed/${name}`, /* @__PURE__ */ new Set(), true);
+		const archive = fileDependencyPath(profileDir, source);
+		if (archive !== void 0) {
+			if (!existsSync(archive)) throw new Error(`deployment fingerprint requires file dependency archive for ${name}`);
+			hashRuntimePath(hash, archive, `source-archive/${name}`, /* @__PURE__ */ new Set());
+		}
+	}
+	return hash.digest("hex");
+}
+/**
+* Hash the host install metadata and any explicitly bound built execution
+* surface. Source surfaces are content-bound by the clean harness git tree.
+*/
+function hostRuntimeSha256(spec) {
+	const hash = createHash("sha256");
+	for (const file of HOST_RUNTIME_FILES) hashOptionalPath(hash, spec.harnessRoot, file);
+	if (spec.preflight !== void 0) {
+		hashRuntimePath(hash, spec.preflight.runnerPath, "preflight/runner", /* @__PURE__ */ new Set());
+		hashRuntimePath(hash, spec.preflight.installAnchor, "preflight/install-anchor", /* @__PURE__ */ new Set());
+		if (spec.preflight.surface === "built") hashRuntimePath(hash, dirname(spec.preflight.installAnchor), "preflight/built-host-package", /* @__PURE__ */ new Set(), true);
+	}
+	return hash.digest("hex");
+}
+function cleanRevision(root, role) {
+	const revision = currentHead(root);
+	if (revision === null) throw new Error(`deployment fingerprint requires ${role} to be a git repository`);
+	if (!isWorkingTreeClean(root)) throw new Error(`deployment fingerprint requires a clean ${role}`);
+	return revision;
+}
+function captureDeploymentFingerprint(spec) {
+	if (spec.preflight === void 0) throw new Error("deployment fingerprint requires an explicit source/built preflight execution binding");
+	if (spec.preflight.targetCommandSha256 !== commandSha256(spec.command)) throw new Error("deployment fingerprint refused a preflight binding for a different launch command");
+	if (fileSha256$1(spec.preflight.runnerPath) !== spec.preflight.runnerSha256) throw new Error("deployment fingerprint refused a changed preflight runner");
+	if (fileSha256$1(spec.preflight.installAnchor) !== spec.preflight.installAnchorSha256) throw new Error("deployment fingerprint refused a changed preflight install anchor");
+	return {
+		version: 1,
+		credentialRevision: cleanRevision(spec.credentialRepo, "credential repository"),
+		harnessRevision: cleanRevision(spec.harnessRoot, "harness root"),
+		launchSpecSha256: commandSha256(JSON.stringify(spec)),
+		profileSha256: profileRuntimeSha256(spec),
+		hostRuntimeSha256: hostRuntimeSha256(spec)
+	};
+}
+function deploymentFingerprintSha256(fingerprint) {
+	return commandSha256(JSON.stringify(fingerprint));
+}
+function credentialCommandSha256(credential) {
+	return commandSha256(credential.command);
+}
+function fileSha256$1(path) {
+	return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+function proofCredentialMatches(proof, credential) {
+	return credential !== void 0 && credential.revision === proof.credential.revision && credential.recordedAt === proof.credential.recordedAt && credential.scope === proof.credential.scope && credentialCommandSha256(credential) === proof.credential.commandSha256;
+}
+function verifyProvenDeployment(stateDir, spec) {
+	const state = loadState(stateDir);
+	const proof = state.provenDeployment;
+	if (proof === void 0) return {
+		ok: false,
+		reason: "no proven deployment recorded by a completed restart canary"
+	};
+	if (!proofCredentialMatches(proof, state.credential)) return {
+		ok: false,
+		reason: "proven deployment no longer matches the recorded build/test credential"
+	};
+	let current;
+	try {
+		current = captureDeploymentFingerprint(spec);
+	} catch (error) {
+		return {
+			ok: false,
+			reason: error instanceof Error ? error.message : String(error)
+		};
+	}
+	const currentSha256 = deploymentFingerprintSha256(current);
+	if (currentSha256 !== proof.fingerprintSha256 || JSON.stringify(current) !== JSON.stringify(proof.fingerprint)) return {
+		ok: false,
+		reason: `proven deployment fingerprint changed (${proof.fingerprintSha256.slice(0, 16)} -> ${currentSha256.slice(0, 16)}) — rebuild, test, and record again`
+	};
+	return {
+		ok: true,
+		reason: `proven deployment valid (${proof.credential.scope} @ ${proof.credential.revision}, fingerprint ${proof.fingerprintSha256.slice(0, 16)})`,
+		authorization: {
+			version: 1,
+			kind: "proven-deployment",
+			revision: proof.credential.revision,
+			evidenceSha256: proof.fingerprintSha256
+		}
+	};
+}
+/** Fresh evidence wins; an exact prior deployment is the same-launch fallback. */
+function verifyRestartEvidence(stateDir, spec, maxAgeMinutes, now = Date.now()) {
+	const state = loadState(stateDir);
+	const credential = state.credential;
+	const fresh = verifyCredential(state, currentHead(spec.credentialRepo), now, maxAgeMinutes, isWorkingTreeClean(spec.credentialRepo));
+	if (fresh.ok && credential !== void 0) return {
+		...fresh,
+		authorization: {
+			version: 1,
+			kind: "fresh-credential",
+			revision: credential.revision,
+			evidenceSha256: credentialCommandSha256(credential)
+		}
+	};
+	const proven = verifyProvenDeployment(stateDir, spec);
+	if (proven.ok) return proven;
+	return {
+		ok: false,
+		reason: `${fresh.reason}; pure-restart reuse unavailable: ${proven.reason}`
+	};
+}
+/** Revalidate the exact evidence selected before the scheduled stop. */
+function verifyRestartAuthorization(stateDir, spec, authorization) {
+	const state = loadState(stateDir);
+	if (authorization.kind === "proven-deployment") {
+		const proven = verifyProvenDeployment(stateDir, spec);
+		if (!proven.ok || proven.authorization?.evidenceSha256 !== authorization.evidenceSha256) return {
+			ok: false,
+			reason: `scheduled proven-deployment authorization changed: ${proven.reason}`
+		};
+		return proven;
+	}
+	const credential = state.credential;
+	if (credential === void 0 || credential.revision !== authorization.revision || credentialCommandSha256(credential) !== authorization.evidenceSha256) return {
+		ok: false,
+		reason: "scheduled credential authorization no longer matches durable state"
+	};
+	if (currentHead(spec.credentialRepo) !== credential.revision || !isWorkingTreeClean(spec.credentialRepo)) return {
+		ok: false,
+		reason: "scheduled credential authorization no longer matches a clean repository HEAD"
+	};
+	return {
+		ok: true,
+		reason: `scheduled fresh credential still matches ${credential.revision}`,
+		authorization
+	};
+}
+/**
+* Promote a fresh credential after the boot's readiness/canary boundary. A
+* proof-authorized pure restart retains the existing proof unchanged.
+*/
+function proveCurrentDeployment(stateDir, spec, authorization, now = Date.now()) {
+	const authorized = verifyRestartAuthorization(stateDir, spec, authorization);
+	if (!authorized.ok) return authorized;
+	if (authorization.kind === "proven-deployment") return {
+		...authorized,
+		reason: `${authorized.reason}; existing deployment proof retained`
+	};
+	const credential = loadState(stateDir).credential;
+	if (credential === void 0) return {
+		ok: false,
+		reason: "credential disappeared before deployment proof was recorded"
+	};
+	let fingerprint;
+	try {
+		fingerprint = captureDeploymentFingerprint(spec);
+	} catch (error) {
+		return {
+			ok: false,
+			reason: error instanceof Error ? error.message : String(error)
+		};
+	}
+	if (fingerprint.credentialRevision !== credential.revision) return {
+		ok: false,
+		reason: "deployment fingerprint revision differs from the credential revision"
+	};
+	const fingerprintSha256 = deploymentFingerprintSha256(fingerprint);
+	const proof = {
+		version: 1,
+		provenAt: now,
+		credential: {
+			revision: credential.revision,
+			recordedAt: credential.recordedAt,
+			scope: credential.scope,
+			commandSha256: credentialCommandSha256(credential)
+		},
+		fingerprint,
+		fingerprintSha256
+	};
+	setProvenDeployment(stateDir, proof, now);
+	return {
+		ok: true,
+		reason: `recorded proven deployment ${fingerprintSha256.slice(0, 16)} for ${credential.revision}`,
+		authorization: {
+			version: 1,
+			kind: "proven-deployment",
+			revision: credential.revision,
+			evidenceSha256: fingerprintSha256
+		}
+	};
+}
+//#endregion
+//#region lib/types/temp-artifact.js
+/** Owner proof for a crash-left temporary artifact that may later be reaped. */
+const TEMP_ARTIFACT_OWNER_FILE = ".ankh-guard-owner.json";
+/**
+* Bind one private temporary artifact to the exact process identity creating
+* it. A later reaper may remove the artifact only after this identity is gone.
+*/
+function writeTempArtifactOwner(root, kind) {
+	const owner = processIdentity(process.pid);
+	if (owner === null) throw new Error(`cannot capture temporary-artifact owner identity for pid ${process.pid}`);
+	const record = {
+		version: 1,
+		kind,
+		createdAt: Date.now(),
+		owner
+	};
+	writeFileSync(join(root, TEMP_ARTIFACT_OWNER_FILE), `${JSON.stringify(record)}\n`, {
+		flag: "wx",
+		mode: 384
+	});
+	return record;
+}
+//#endregion
+//#region lib/types/transition.js
+/**
+* Reversible filesystem transitions for launch cutovers.
+*
+* A transition plan names home-relative paths that the next host cannot read.
+* The guard moves those paths into a cutover-scoped quarantine only after the
+* previous process has stopped. If the target is rejected, target-created
+* replacements are retained separately before the previous bytes are restored.
+*/
+const MAX_OPERATIONS = 64;
+const CUTOVER_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,159}$/;
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function exactKeys(value, expected, label) {
+	const actual = Object.keys(value).sort();
+	const wanted = [...expected].sort();
+	if (actual.length !== wanted.length || actual.some((key, index) => key !== wanted[index])) throw new Error(`${label} requires exactly: ${wanted.join(", ")}`);
+}
+function canonicalDirectory(path, label) {
+	if (!isAbsolute(path)) throw new Error(`${label} must be absolute`);
+	let canonical;
+	try {
+		canonical = realpathSync(path);
+	} catch {
+		throw new Error(`${label} does not exist: ${path}`);
+	}
+	if (!statSync(canonical).isDirectory()) throw new Error(`${label} must be a directory: ${path}`);
+	return canonical;
+}
+function pathExists(path) {
+	try {
+		lstatSync(path);
+		return true;
+	} catch (error) {
+		if (error.code === "ENOENT") return false;
+		throw error;
+	}
+}
+function normalizeRelativePath(path) {
+	if (typeof path !== "string" || path === "" || isAbsolute(path) || path.includes("\\") || path.includes("\0")) throw new Error("transition operation path must be a non-empty home-relative POSIX path");
+	const parts = path.split("/");
+	if (parts.some((part) => part === "" || part === "." || part === "..")) throw new Error(`transition operation path contains an empty or traversal segment: ${path}`);
+	return parts.join(sep);
+}
+function overlaps(left, right) {
+	return left === right || left.startsWith(`${right}${sep}`) || right.startsWith(`${left}${sep}`);
+}
+function assertPathHasNoSymlink(home, path) {
+	let current = home;
+	for (const part of path.split(sep)) {
+		current = join(current, part);
+		if (!pathExists(current)) return;
+		const stat = lstatSync(current);
+		if (stat.isSymbolicLink()) throw new Error(`transition path crosses a symbolic link: ${path}`);
+		if (current !== join(home, path) && !stat.isDirectory()) throw new Error(`transition path has a non-directory ancestor: ${path}`);
+	}
+}
+function assertOperationScope(plan, stateDir) {
+	const paths = plan.operations.map((operation) => operation.path);
+	for (let index = 0; index < paths.length; index++) {
+		const path = paths[index];
+		assertPathHasNoSymlink(plan.home, path);
+		for (const other of paths.slice(index + 1)) if (overlaps(path, other)) throw new Error(`transition paths may not overlap: ${path} and ${other}`);
+	}
+	if (stateDir === void 0) return;
+	const canonicalState = canonicalDirectory(stateDir, "transition state directory");
+	const stateRelative = relative(plan.home, canonicalState);
+	if (stateRelative === "") throw new Error("transition state directory must not equal the transition home");
+	if (!stateRelative.startsWith(`..${sep}`) && stateRelative !== ".." && !isAbsolute(stateRelative)) {
+		for (const path of paths) if (overlaps(path, stateRelative)) throw new Error(`transition path overlaps the guard state directory: ${path}`);
+	}
+}
+/**
+* Validate and normalize an untrusted transition plan.
+* @param raw - Parsed JSON plan.
+* @param expectedHome - Home shared by the previous and target launch specs.
+* @param stateDir - Guard state directory, which no operation may move.
+* @returns A canonical plan safe for durable preparation.
+*/
+function validateTransitionPlan(raw, expectedHome, stateDir) {
+	if (!isObject(raw)) throw new Error("transition plan must be an object");
+	exactKeys(raw, [
+		"schemaVersion",
+		"home",
+		"operations"
+	], "transition plan");
+	if (raw.schemaVersion !== 1) throw new Error("transition plan requires schemaVersion: 1");
+	if (typeof raw.home !== "string") throw new Error("transition plan home must be a string");
+	const home = canonicalDirectory(raw.home, "transition plan home");
+	if (home !== canonicalDirectory(expectedHome, "cutover home")) throw new Error("transition plan home must equal the cutover home");
+	if (!Array.isArray(raw.operations) || raw.operations.length === 0 || raw.operations.length > MAX_OPERATIONS) throw new Error(`transition plan requires 1-${MAX_OPERATIONS} operations`);
+	const seen = /* @__PURE__ */ new Set();
+	const plan = {
+		schemaVersion: 1,
+		home,
+		operations: raw.operations.map((operation, index) => {
+			if (!isObject(operation)) throw new Error(`transition operation ${index} must be an object`);
+			exactKeys(operation, [
+				"expect",
+				"kind",
+				"path"
+			], `transition operation ${index}`);
+			if (operation.kind !== "quarantine") throw new Error(`transition operation ${index} has unsupported kind`);
+			if (operation.expect !== "present" && operation.expect !== "absent") throw new Error(`transition operation ${index} requires expect: present or absent`);
+			const path = normalizeRelativePath(operation.path);
+			if (seen.has(path)) throw new Error(`transition operation path is duplicated: ${path}`);
+			seen.add(path);
+			return {
+				kind: "quarantine",
+				path,
+				expect: operation.expect
+			};
+		})
+	};
+	assertOperationScope(plan, stateDir);
+	return plan;
+}
+function jsonBytes(value) {
+	return Buffer.from(`${JSON.stringify(value, null, 2)}\n`);
+}
+function sha256(value) {
+	return createHash("sha256").update(value).digest("hex");
+}
+function atomicWrite(file, bytes) {
+	mkdirSync(dirname(file), { recursive: true });
+	const temporary = `${file}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+	writeFileSync(temporary, bytes, {
+		flag: "wx",
+		mode: 384
+	});
+	try {
+		renameSync(temporary, file);
+		try {
+			chmodSync(file, 384);
+		} catch {}
+	} finally {
+		rmSync(temporary, { force: true });
+	}
+}
+function atomicWriteJson(file, value) {
+	atomicWrite(file, jsonBytes(value));
+}
+function transitionRoot(stateDir, cutoverId) {
+	if (!CUTOVER_ID_PATTERN.test(cutoverId)) throw new Error("transition cutover id is invalid");
+	return join(canonicalDirectory(stateDir, "transition state directory"), "launch-transitions", cutoverId);
+}
+function expectedPlanPath(stateDir, cutoverId) {
+	return join(transitionRoot(stateDir, cutoverId), "plan.json");
+}
+/**
+* Persist the immutable plan and an empty crash-recovery journal before the previous host stops.
+* @param raw - Validated or untrusted plan JSON.
+* @param expectedHome - Shared launch home.
+* @param stateDir - Guard state directory.
+* @param cutoverId - Unique launch cutover identifier.
+* @returns Reference stored in the launch state and redacted receipt.
+*/
+function prepareTransition(raw, expectedHome, stateDir, cutoverId) {
+	const plan = validateTransitionPlan(raw, expectedHome, stateDir);
+	const root = transitionRoot(stateDir, cutoverId);
+	if (pathExists(root)) throw new Error(`transition directory already exists for cutover ${cutoverId}`);
+	if (statSync(plan.home).dev !== statSync(canonicalDirectory(stateDir, "transition state directory")).dev) throw new Error("transition home and state directory must be on the same filesystem");
+	for (const operation of plan.operations) {
+		const source = join(plan.home, operation.path);
+		if (pathExists(source) !== (operation.expect === "present")) throw new Error(`transition source ${operation.path} is ${pathExists(source) ? "present" : "absent"}, expected ${operation.expect}`);
+		if (pathExists(source) && lstatSync(source).dev !== statSync(canonicalDirectory(stateDir, "transition state directory")).dev) throw new Error(`transition source is on a different filesystem: ${operation.path}`);
+	}
+	mkdirSync(root, {
+		recursive: true,
+		mode: 448
+	});
+	const planPath = join(root, "plan.json");
+	const bytes = jsonBytes(plan);
+	atomicWrite(planPath, bytes);
+	const planSha256 = sha256(bytes);
+	const record = {
+		version: 1,
+		cutoverId,
+		planSha256,
+		phase: "prepared",
+		entries: plan.operations.map((operation) => ({
+			path: operation.path,
+			original: operation.expect,
+			apply: "pending",
+			rollback: "pending"
+		})),
+		updatedAt: Date.now()
+	};
+	atomicWriteJson(join(root, "state.json"), record);
+	return {
+		version: 1,
+		planPath,
+		planSha256,
+		operationCount: plan.operations.length
+	};
+}
+function parseRecord(raw, cutoverId, reference, plan) {
+	if (!isObject(raw) || raw.version !== 1 || raw.cutoverId !== cutoverId || raw.planSha256 !== reference.planSha256 || typeof raw.updatedAt !== "number" || ![
+		"prepared",
+		"applying",
+		"applied",
+		"rolling-back",
+		"rolled-back",
+		"failed"
+	].includes(String(raw.phase)) || !Array.isArray(raw.entries) || raw.entries.length !== plan.operations.length) throw new Error("transition state is malformed or does not match its plan");
+	const entries = raw.entries;
+	for (let index = 0; index < entries.length; index++) {
+		const entry = entries[index];
+		if (!isObject(entry) || entry.path !== plan.operations[index]?.path || !["present", "absent"].includes(String(entry.original)) || ![
+			"pending",
+			"moving",
+			"absent",
+			"quarantined"
+		].includes(String(entry.apply)) || ![
+			"pending",
+			"moving-target",
+			"target-retained",
+			"target-absent",
+			"restoring",
+			"restored"
+		].includes(String(entry.rollback))) throw new Error(`transition state entry ${index} is malformed`);
+	}
+	return raw;
+}
+function loadTransition(reference, expectedHome, stateDir, cutoverId) {
+	if (reference.version !== 1 || !/^[a-f0-9]{64}$/.test(reference.planSha256) || !Number.isInteger(reference.operationCount) || reference.operationCount < 1) throw new Error("transition reference is malformed");
+	const planPath = expectedPlanPath(stateDir, cutoverId);
+	if (resolve(reference.planPath) !== planPath) throw new Error("transition plan path is outside its cutover directory");
+	const bytes = readFileSync(planPath);
+	if (sha256(bytes) !== reference.planSha256) throw new Error("transition plan changed after preparation");
+	let rawPlan;
+	try {
+		rawPlan = JSON.parse(bytes.toString("utf8"));
+	} catch {
+		throw new Error("transition plan is not valid JSON");
+	}
+	const plan = validateTransitionPlan(rawPlan, expectedHome, stateDir);
+	if (plan.operations.length !== reference.operationCount) throw new Error("transition operation count changed after preparation");
+	const root = dirname(planPath);
+	const stateFile = join(root, "state.json");
+	let rawRecord;
+	try {
+		rawRecord = JSON.parse(readFileSync(stateFile, "utf8"));
+	} catch {
+		throw new Error("transition state is unreadable");
+	}
+	return {
+		plan,
+		record: parseRecord(rawRecord, cutoverId, reference, plan),
+		root,
+		stateFile
+	};
+}
+function writeRecord(loaded) {
+	loaded.record.updatedAt = Date.now();
+	atomicWriteJson(loaded.stateFile, loaded.record);
+}
+function previousPath(root, path) {
+	return join(root, "previous", path);
+}
+function rejectedTargetPath(root, path) {
+	return join(root, "rejected-target", path);
+}
+function markFailure(loaded, operation, error) {
+	const detail = error instanceof Error ? error.message : String(error);
+	loaded.record.phase = "failed";
+	loaded.record.failure = {
+		operation,
+		detail
+	};
+	try {
+		writeRecord(loaded);
+	} catch {}
+	throw new Error(`transition ${operation} failed: ${detail}`);
+}
+function reconcileMovingApply(loaded, entry) {
+	const source = join(loaded.plan.home, entry.path);
+	const retained = previousPath(loaded.root, entry.path);
+	const sourceExists = pathExists(source);
+	const retainedExists = pathExists(retained);
+	if (!sourceExists && retainedExists) {
+		entry.original = "present";
+		entry.apply = "quarantined";
+		writeRecord(loaded);
+		return true;
+	}
+	if (sourceExists && !retainedExists) {
+		entry.apply = "pending";
+		writeRecord(loaded);
+		return false;
+	}
+	throw new Error(`cannot reconcile interrupted quarantine for ${entry.path}`);
+}
+/**
+* Apply a prepared transition after the previous host has stopped.
+* @param reference - Immutable reference from the launch state.
+* @param expectedHome - Shared launch home.
+* @param stateDir - Guard state directory.
+* @param cutoverId - Active cutover identifier.
+* @returns Idempotent apply result.
+*/
+function applyTransition(reference, expectedHome, stateDir, cutoverId) {
+	const loaded = loadTransition(reference, expectedHome, stateDir, cutoverId);
+	if (loaded.record.phase === "rolled-back") throw new Error("a rolled-back transition cannot be applied again");
+	if (loaded.record.phase === "applied") return {
+		phase: "applied",
+		changed: [],
+		unchanged: loaded.record.entries.map((entry) => entry.path)
+	};
+	const changed = [];
+	const unchanged = [];
+	loaded.record.phase = "applying";
+	delete loaded.record.failure;
+	writeRecord(loaded);
+	try {
+		for (const entry of loaded.record.entries) {
+			assertPathHasNoSymlink(loaded.plan.home, entry.path);
+			if (entry.apply === "quarantined" || entry.apply === "absent") {
+				unchanged.push(entry.path);
+				continue;
+			}
+			if (entry.apply === "moving" && reconcileMovingApply(loaded, entry)) {
+				unchanged.push(entry.path);
+				continue;
+			}
+			const source = join(loaded.plan.home, entry.path);
+			const retained = previousPath(loaded.root, entry.path);
+			const sourceExists = pathExists(source);
+			if (sourceExists !== (entry.original === "present")) throw new Error(`transition source changed after preparation: ${entry.path}`);
+			if (!sourceExists) {
+				if (pathExists(retained)) throw new Error(`unexpected retained source for absent path ${entry.path}`);
+				entry.apply = "absent";
+				writeRecord(loaded);
+				unchanged.push(entry.path);
+				continue;
+			}
+			if (lstatSync(source).isSymbolicLink()) throw new Error(`transition source is a symbolic link: ${entry.path}`);
+			if (pathExists(retained)) throw new Error(`transition quarantine destination already exists: ${entry.path}`);
+			entry.apply = "moving";
+			writeRecord(loaded);
+			mkdirSync(dirname(retained), {
+				recursive: true,
+				mode: 448
+			});
+			renameSync(source, retained);
+			entry.apply = "quarantined";
+			writeRecord(loaded);
+			changed.push(entry.path);
+		}
+		loaded.record.phase = "applied";
+		writeRecord(loaded);
+		return {
+			phase: "applied",
+			changed,
+			unchanged
+		};
+	} catch (error) {
+		return markFailure(loaded, "apply", error);
+	}
+}
+function finishTargetRetention(loaded, entry) {
+	const source = join(loaded.plan.home, entry.path);
+	const target = rejectedTargetPath(loaded.root, entry.path);
+	const sourceExists = pathExists(source);
+	const targetExists = pathExists(target);
+	if (entry.rollback === "moving-target") {
+		if (!sourceExists && targetExists) {
+			entry.rollback = "target-retained";
+			writeRecord(loaded);
+			return;
+		}
+		if (!sourceExists || targetExists) throw new Error(`cannot reconcile rejected target output for ${entry.path}`);
+	}
+	if (sourceExists) {
+		if (targetExists) throw new Error(`rejected target quarantine already exists for ${entry.path}`);
+		entry.rollback = "moving-target";
+		writeRecord(loaded);
+		mkdirSync(dirname(target), {
+			recursive: true,
+			mode: 448
+		});
+		renameSync(source, target);
+		entry.rollback = "target-retained";
+	} else entry.rollback = targetExists ? "target-retained" : "target-absent";
+	writeRecord(loaded);
+}
+function finishPreviousRestore(loaded, entry) {
+	if (entry.original === "absent") {
+		entry.rollback = "restored";
+		writeRecord(loaded);
+		return;
+	}
+	if (entry.original !== "present") throw new Error(`transition original state is unknown for ${entry.path}`);
+	const source = join(loaded.plan.home, entry.path);
+	const retained = previousPath(loaded.root, entry.path);
+	const sourceExists = pathExists(source);
+	const retainedExists = pathExists(retained);
+	if (entry.rollback === "restoring") {
+		if (sourceExists && !retainedExists) {
+			entry.rollback = "restored";
+			writeRecord(loaded);
+			return;
+		}
+		if (sourceExists || !retainedExists) throw new Error(`cannot reconcile previous-state restore for ${entry.path}`);
+	}
+	if (sourceExists || !retainedExists) throw new Error(`previous-state quarantine is incomplete for ${entry.path}`);
+	entry.rollback = "restoring";
+	writeRecord(loaded);
+	mkdirSync(dirname(source), { recursive: true });
+	renameSync(retained, source);
+	entry.rollback = "restored";
+	writeRecord(loaded);
+}
+/**
+* Roll back an applied or partially applied transition before previous starts.
+* Target-created replacements are retained for diagnosis rather than deleted.
+* @param reference - Immutable reference from the launch state.
+* @param expectedHome - Shared launch home.
+* @param stateDir - Guard state directory.
+* @param cutoverId - Active cutover identifier.
+* @returns Idempotent rollback result.
+*/
+function rollbackTransition(reference, expectedHome, stateDir, cutoverId) {
+	const loaded = loadTransition(reference, expectedHome, stateDir, cutoverId);
+	if (loaded.record.phase === "rolled-back") return {
+		phase: "rolled-back",
+		changed: [],
+		unchanged: loaded.record.entries.map((entry) => entry.path)
+	};
+	const changed = [];
+	const unchanged = [];
+	loaded.record.phase = "rolling-back";
+	delete loaded.record.failure;
+	writeRecord(loaded);
+	try {
+		for (const entry of [...loaded.record.entries].reverse()) {
+			if (entry.rollback === "restored") {
+				unchanged.push(entry.path);
+				continue;
+			}
+			if (entry.apply === "moving") reconcileMovingApply(loaded, entry);
+			if (entry.apply === "pending") {
+				entry.rollback = "restored";
+				writeRecord(loaded);
+				unchanged.push(entry.path);
+				continue;
+			}
+			assertPathHasNoSymlink(loaded.plan.home, entry.path);
+			if (entry.rollback !== "restoring") finishTargetRetention(loaded, entry);
+			finishPreviousRestore(loaded, entry);
+			changed.push(entry.path);
+		}
+		loaded.record.phase = "rolled-back";
+		writeRecord(loaded);
+		return {
+			phase: "rolled-back",
+			changed,
+			unchanged
+		};
+	} catch (error) {
+		return markFailure(loaded, "rollback", error);
+	}
+}
+function snapshotCopyError(source, error) {
+	if (error.code === "ELOOP") return /* @__PURE__ */ new Error(`preflight snapshot refused an unresolvable symbolic-link cycle at ${source}`);
+	return /* @__PURE__ */ new Error(`preflight snapshot could not safely copy ${source}: ${String(error)}`);
+}
+/**
+* Top-level home entries that never join a preflight snapshot: scratch is
+* ephemeral by definition, and copying it can push prepare+canary past the
+* credential's freshness window (observed: a 24 GB scratch expired the
+* credential mid-cutover, the target canary then failed and restored).
+*/
+const SNAPSHOT_SKIPPED_TOP_LEVEL = /* @__PURE__ */ new Set(["scratch"]);
+function canonicalSnapshotSource(source) {
+	try {
+		return realpathSync(source);
+	} catch (error) {
+		throw snapshotCopyError(source, error);
+	}
+}
+function createContainedSnapshotLink(destination, target, directory) {
+	const targetFromLink = relative(dirname(destination), target) || ".";
+	symlinkSync(targetFromLink, destination, directory ? "dir" : "file");
+}
+/** Copy physical entries once; source symlinks become deferred graph edges. */
+function copySnapshotNode(source, destination, context) {
+	let linkMetadata;
+	try {
+		linkMetadata = lstatSync(source);
+	} catch (error) {
+		throw snapshotCopyError(source, error);
+	}
+	if (linkMetadata.isSymbolicLink()) {
+		context.pendingLinks.push({
+			source,
+			destination
+		});
+		return;
+	}
+	if (linkMetadata.isSocket() || linkMetadata.isFIFO()) {
+		context.skippedRuntimeEntries++;
+		return;
+	}
+	if (!linkMetadata.isDirectory() && !linkMetadata.isFile()) throw new Error(`preflight snapshot refused a special filesystem entry at ${source}`);
+	const canonical = canonicalSnapshotSource(source);
+	const existing = context.destinations.get(canonical);
+	if (existing !== void 0) {
+		createContainedSnapshotLink(destination, existing, linkMetadata.isDirectory());
+		return;
+	}
+	context.destinations.set(canonical, destination);
+	if (linkMetadata.isDirectory()) {
+		mkdirSync(destination, { mode: 448 });
+		context.directories.push({
+			destination,
+			mode: linkMetadata.mode & 4095,
+			atime: linkMetadata.atime,
+			mtime: linkMetadata.mtime
+		});
+		try {
+			for (const name of readdirSync(canonical)) {
+				if (canonical === context.rootCanonical && SNAPSHOT_SKIPPED_TOP_LEVEL.has(name)) continue;
+				copySnapshotNode(join(canonical, name), join(destination, name), context);
+			}
+		} catch (error) {
+			if (error instanceof Error && error.message.startsWith("preflight snapshot ")) throw error;
+			throw snapshotCopyError(source, error);
+		}
+		return;
+	}
+	try {
+		copyFileSync(canonical, destination, constants.COPYFILE_FICLONE);
+		chmodSync(destination, linkMetadata.mode & 4095);
+		utimesSync(destination, linkMetadata.atime, linkMetadata.mtime);
+	} catch (error) {
+		throw snapshotCopyError(source, error);
+	}
+}
+/**
+* Preserve Node's ancestor node_modules lookup for an external package while
+* avoiding one copy per package link. Other external targets are materialized
+* individually and still deduplicated by canonical path.
+*/
+function externalMaterializationAnchor(target) {
+	const parsed = resolve(target).split(sep);
+	const nodeModulesIndex = parsed.indexOf("node_modules");
+	if (nodeModulesIndex >= 0) return {
+		source: parsed.slice(0, nodeModulesIndex + 1).join(sep) || sep,
+		destination: "node_modules"
+	};
+	return {
+		source: target,
+		destination: basename(target) || "target"
+	};
+}
+function resolveSnapshotLinks(context) {
+	for (let index = 0; index < context.pendingLinks.length; index++) {
+		const link = context.pendingLinks[index];
+		const target = canonicalSnapshotSource(link.source);
+		let metadata;
+		try {
+			metadata = statSync(target);
+		} catch (error) {
+			throw snapshotCopyError(link.source, error);
+		}
+		if (metadata.isSocket() || metadata.isFIFO()) {
+			context.skippedRuntimeEntries++;
+			continue;
+		}
+		if (!metadata.isDirectory() && !metadata.isFile()) throw new Error(`preflight snapshot refused a link to a special filesystem entry at ${link.source}`);
+		let mapped = context.destinations.get(target);
+		if (mapped === void 0) {
+			const anchor = externalMaterializationAnchor(target);
+			const canonicalAnchor = canonicalSnapshotSource(anchor.source);
+			mapped = context.destinations.get(target);
+			if (mapped === void 0) {
+				mkdirSync(context.externalRoot, {
+					recursive: true,
+					mode: 448
+				});
+				const anchorDestination = join(context.externalRoot, sha256(Buffer.from(canonicalAnchor)), anchor.destination);
+				mkdirSync(dirname(anchorDestination), {
+					recursive: true,
+					mode: 448
+				});
+				copySnapshotNode(canonicalAnchor, anchorDestination, context);
+				mapped = context.destinations.get(target);
+			}
+		}
+		if (mapped === void 0) throw new Error(`preflight snapshot could not map symbolic-link target for ${link.source}`);
+		createContainedSnapshotLink(link.destination, mapped, metadata.isDirectory());
+	}
+}
+function pathIsWithin(root, path) {
+	const offset = relative(root, path);
+	return offset === "" || !isAbsolute(offset) && offset !== ".." && !offset.startsWith(`..${sep}`);
+}
+/** Prove every retained link resolves to a writable target inside the snapshot. */
+function assertSnapshotLinksContained(path, canonicalRoot) {
+	const metadata = lstatSync(path);
+	if (metadata.isSymbolicLink()) {
+		const target = canonicalSnapshotSource(path);
+		if (!pathIsWithin(canonicalRoot, target)) throw new Error(`preflight snapshot retained a writable link escape at ${path}`);
+		const targetMetadata = statSync(target);
+		if (!targetMetadata.isDirectory() && !targetMetadata.isFile()) throw new Error(`preflight snapshot retained a link to a special filesystem entry at ${path}`);
+		return;
+	}
+	if (metadata.isDirectory()) {
+		for (const name of readdirSync(path)) assertSnapshotLinksContained(join(path, name), canonicalRoot);
+		return;
+	}
+	if (!metadata.isFile()) throw new Error(`preflight snapshot retained a special filesystem entry at ${path}`);
+}
+function finalizeSnapshotDirectories(context) {
+	for (const directory of [...context.directories].reverse()) {
+		chmodSync(directory.destination, directory.mode);
+		utimesSync(directory.destination, directory.atime, directory.mtime);
+	}
+}
+/**
+* Clone a live home while retaining a contained package-link graph. Internal
+* links are rebuilt against copied nodes; external targets are deduplicated in
+* a snapshot-owned materialization area. No retained link resolves outside the
+* snapshot root, so writes through pnpm/Cordis links cannot reach live bytes.
+* Runtime entries without copyable content (sockets, FIFOs — and links to
+* them) are skipped and counted, never copied; the top-level scratch/ tree is
+* excluded for size. Device nodes still fail closed.
+* @param sourceHome - Live dsh home to read.
+* @returns Isolated home, an idempotent cleanup callback, and the count of skipped runtime entries.
+*/
+function createPreflightSnapshot(sourceHome) {
+	const root = mkdtempSync(join(tmpdir(), "ankh-transition-preflight-"));
+	const home = join(root, "home");
+	try {
+		writeTempArtifactOwner(root, "preflight-snapshot");
+		const source = canonicalDirectory(sourceHome, "preflight source home");
+		const context = {
+			externalRoot: join(root, "materialized"),
+			rootCanonical: source,
+			destinations: /* @__PURE__ */ new Map(),
+			pendingLinks: [],
+			directories: [],
+			skippedRuntimeEntries: 0
+		};
+		copySnapshotNode(source, home, context);
+		resolveSnapshotLinks(context);
+		assertSnapshotLinksContained(root, realpathSync(root));
+		finalizeSnapshotDirectories(context);
+		return {
+			home,
+			root,
+			skippedRuntimeEntries: context.skippedRuntimeEntries,
+			cleanup: () => {
+				rmSync(root, {
+					recursive: true,
+					force: true
+				});
+			}
+		};
+	} catch (error) {
+		rmSync(root, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+}
+function createTransitionPreflightSnapshot(plan) {
+	const snapshot = createPreflightSnapshot(plan.home);
+	try {
+		const stateDir = join(snapshot.root, "guard-state");
+		mkdirSync(stateDir, {
+			recursive: true,
+			mode: 448
+		});
+		applyTransition(prepareTransition({
+			...plan,
+			home: snapshot.home
+		}, snapshot.home, stateDir, "preflight"), snapshot.home, stateDir, "preflight");
+		return {
+			home: snapshot.home,
+			cleanup: snapshot.cleanup
+		};
+	} catch (error) {
+		snapshot.cleanup();
+		throw error;
+	}
+}
+//#endregion
 //#region lib/types/cli.js
 /**
 * CLI for the self-restart guard — the interface the agent and the launcher
@@ -21,9 +1039,11 @@ import { fileURLToPath } from "node:url";
 *   record   — record a green credential for the current HEAD
 *   status   — print the full state (credential, checkpoint, audit)
 *   clear    — drop the credential
-*   checkpoint — commit the whole tree as a pre-batch snapshot
+*   checkpoint — record clean HEAD, or explicitly commit a reviewed dirty snapshot
 *   reset    — `git reset --hard` to a checkpoint commit (rollback)
 *   canary   — post-restart probe: verify (+ optional TCP port check)
+*   verify-restart — watchdog-facing validation of a scheduled authorization
+*   record-proven-deployment — watchdog-facing promotion after canary
 *   restart  — DETACHED restart: gate → stop → start → probe → canary.
 *              Owns the whole loop in a process that outlives the restarted
 *              instance, so the post-restart canary runs even though the
@@ -37,9 +1057,8 @@ import { fileURLToPath } from "node:url";
 */
 const FULL_ACCESS_HINT = "hint: the restart loop spawns detached processes and signals them — a sandboxed session (not full-access) will fail with EPERM. You CANNOT switch the sandbox yourself (that is the point of it): ask the user to run /permission danger-full-access in THIS session (the settings page only affects NEW sessions; an open persistent terminal fences the switch)\n";
 /**
-* Printed (by verify/record, and as a refusal-grade warning in schedule-exit)
-* while no watchdog supervises the instance: a bare exit now leaves the
-* service DOWN — the first-install bootstrap gap.
+* Printed by verify/record while no watchdog supervises the instance. The
+* stop-capable schedule-exit verb has its own hard refusal for this state.
 */
 const NO_WATCHDOG_HINT = "warning: no live watchdog supervises the instance — a bare exit now leaves the service DOWN. Before the first restart, run `supervise --port N --start \"CMD\"` (it adopts the running instance and respawns ANY exit), or drive the restart with `restart` yourself\n";
 /**
@@ -75,35 +1094,41 @@ function sandboxGate(verb, options, io) {
 	return false;
 }
 /**
-* 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.
+* Resolve the restart's initiating session. An explicit --initiator that
+* contradicts the shell's own DSH_SESSION_ID routes the wake-up report to a
+* session that is not the caller — observed 2026-08-29: an agent invented a
+* branch-derived slug ('skill-styles-merge'), the report went to a session
+* that does not exist, and the actual scheduler was never woken. Warn loudly;
+* do not refuse — scheduling on behalf of another session is legitimate.
+* @param explicit - the --initiator flag value, when given.
+* @param io - CLI streams.
+* @returns the initiator to record (explicit wins, else the env default).
 */
-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;
-	}
+function resolveInitiator(explicit, io) {
+	const fromEnv = process.env.DSH_SESSION_ID;
+	if (explicit !== void 0 && explicit !== "" && fromEnv !== void 0 && explicit !== fromEnv) io.stderr(`warning: --initiator ${JSON.stringify(explicit)} does not match this session's DSH_SESSION_ID ${JSON.stringify(fromEnv)} — the restart report will be routed to ${JSON.stringify(explicit)} and THIS session will not be woken. Omit --initiator to route it to the current session.\n`);
+	return explicit !== void 0 && explicit !== "" ? explicit : fromEnv;
 }
-/** 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;
-	}
+function testChildEnv(role, env, options = {}) {
+	if (process.env["ANKH_GUARD_TEST_RUN_DIR"] === void 0) return env;
+	return {
+		...env,
+		[TEST_PROCESS_ROLE_ENV]: role,
+		...options.port === void 0 ? {} : { [TEST_PROCESS_PORT_ENV]: String(options.port) },
+		...options.tempRoot === void 0 ? {} : { [TEST_PROCESS_TEMP_ROOT_ENV]: options.tempRoot }
+	};
 }
-/** The live supervising watchdog's pid, or null when none is (pidfile + kill 0). */
-function liveWatchdogPid(stateDir) {
-	const raw = livePidIn(stateFile(stateDir, "watchdogPid"));
-	return raw === null ? null : Number(raw);
+function registerSpawnedTestProcess(child, role, options = {}) {
+	if (child.pid === void 0) return;
+	registerTestProcess(child.pid, role, {
+		source: "parent-observer",
+		...options.port === void 0 ? {} : { port: options.port },
+		...options.tempRoot === void 0 ? {} : { tempRoot: options.tempRoot }
+	});
+	appendTestLifecycleEventForProcess(child.pid, role, "child-spawned", {
+		childPid: child.pid,
+		role
+	}, "parent-observer");
 }
 /**
 * Cross-session restart mutual exclusion: two concurrent restarts would both
@@ -183,29 +1208,52 @@ function cliInvocation(args) {
 const USAGE = `usage: dsh-ankh-guard <command> [args] [flags]
 commands:
   verify [--state-dir DIR] [--repo DIR] [--max-age MIN]
-  record <scope> [--command CMD] [--state-dir DIR] [--repo DIR]
+  record <scope> [--state-dir DIR] [--repo DIR] --run -- PROGRAM [ARG...]
+  record <scope> [--state-dir DIR] [--repo DIR] --trust-command --command CMD
   status [--state-dir DIR]
   clear [--state-dir DIR]
-  checkpoint [--message MSG] [--repo DIR] [--state-dir DIR]
+  checkpoint [--message MSG] [--include-dirty] [--repo DIR] [--state-dir DIR]
   reset <sha> [--repo DIR]
   canary [--port N] [--state-dir DIR] [--repo DIR] [--max-age MIN]
+  verify-restart [--state-dir DIR]   # watchdog-facing: revalidate the scheduled authorization
+  record-proven-deployment [--state-dir DIR]   # watchdog-facing: promote/retain proof after canary
   check-env [--state-dir DIR] [--repo DIR]   # sandbox / watchdog / git readiness probe
-  preflight [--profile NAME] [--timeout-ms MS]
+  preflight [--profile NAME] [--harness-root DIR] [--timeout-ms MS]
+          [--preflight-surface source|built --preflight-install-anchor FILE] [--preflight-runner FILE]
   record-unexpected-exit [--state-dir DIR]   # watchdog-facing: record an unplanned-exit recovery
   record-adoption [--initiator ID] [--state-dir DIR]   # watchdog-facing: record the first (adoption) takeover
+  record-composition-recovery [--state-dir DIR]   # watchdog-facing: record a composition-rollback recovery
+  configure-launch --port N --start "CMD" [--home DIR] [--repo DIR] --harness-root DIR [--profile NAME]
+          --preflight-surface source|built [--preflight-runner FILE] --preflight-install-anchor FILE [--if-absent]
+  launch-status [--state-dir DIR]
+  transition-apply CUTOVER_ID [--state-dir DIR]      # watchdog-facing: apply the prepared transition
+  transition-rollback CUTOVER_ID [--state-dir DIR]   # watchdog-facing: restore previous state before previous starts
+  abort-cutover [--state-dir DIR]      # apply the recovery policy approved by reconfigure
+  restore-previous [--state-dir DIR]   # explicit new authorization to restore the complete previous spec
+  reconfigure --start "CMD" --on-failure restore-previous|wait-for-user [--port N]
+          [--home DIR] [--repo DIR] [--harness-root DIR] [--profile NAME] [--browser-handoff required|off]
+          --preflight-surface source|built [--preflight-runner FILE] --preflight-install-anchor FILE
+          --candidate-probe-command "CMD"
+          [--transition-file FILE] [--delay-ms MS] [--supervisor-yield-timeout-ms MS] [--preflight-timeout-ms MS] [--state-dir DIR]
   restart --port N --start "CMD" [--pid PID] [--timeout-ms MS] [--delay-ms MS] [--stop-timeout-ms MS] [--rollback]
-          [--profile NAME] [--preflight-timeout-ms MS] [--state-dir DIR] [--repo DIR] [--max-age MIN]
-  schedule-exit --port N --delay-ms MS [--initiator ID] [--log FILE] [--profile NAME]
-          [--preflight-timeout-ms MS] [--state-dir DIR] [--repo DIR]
-  supervise --port N --start "CMD" [--foreground] [--log FILE] [--state-dir DIR] [--repo DIR] [--home DIR]
+          [--profile NAME] [--harness-root DIR] [--preflight-timeout-ms MS] [--state-dir DIR] [--repo DIR] [--max-age MIN]
+  schedule-exit [--port N] --delay-ms MS [--initiator ID] [--log FILE] [--profile NAME]
+          [--harness-root DIR] [--preflight-timeout-ms MS] [--state-dir DIR] [--repo DIR]
+  supervise --port N --start "CMD" [--foreground] [--log FILE] [--state-dir DIR] [--repo DIR] [--harness-root DIR] [--home DIR]
 flags:
   --state-dir DIR  state directory (default: $DSH_HOME/state, else <cwd>/.dsh-guard-state)
   --repo DIR       repository the credential binds to (default: cwd)
+  --harness-root DIR  dsh host checkout used by preflight and exported to the
+                   child as DSH_HARNESS; launch-state initialization requires
+                   this flag or an existing DSH_HARNESS
   --max-age MIN    credential freshness window in minutes (default: 10)
   --port N         canary/restart/supervise: TCP port that must be listening
-  --command CMD    record: the command that produced the green state
+  --run -- PROGRAM [ARG...]  record: execute this exact argv in --repo and record only on exit 0
+  --trust-command  record: explicitly trust an external orchestrator's already-green --command
+  --command CMD    record --trust-command: description of the externally proven command
   --message MSG    checkpoint: batch description
-  --start "CMD"    restart/supervise: the shell command that starts the instance
+  --include-dirty  checkpoint: after review, explicitly commit every staged, unstaged, and untracked change
+  --start "CMD"    restart/supervise/reconfigure: the shell command that starts the instance
                    (optional once the plugin has booted — it records the launch
                    command to <state-dir>/instance-launch.json)
   --pid PID        restart: process to stop (default: the listener on --port)
@@ -216,18 +1264,37 @@ flags:
                    logs can take tens of seconds to flush)
   --delay-ms MS    restart: sleep before stopping, so the current turn can finish first
                    (agent-driven graceful self-restart: schedule, complete, then restart);
-                   schedule-exit: delay before the detached exit agent kills the host
+                   schedule-exit: delay before the detached exit agent kills the host;
+                   reconfigure: grace after successor supervisor claim before old-child stop
   --log FILE       supervise (detached only — with --foreground the external supervisor's
                    redirection owns the log) / schedule-exit: log file (default: <state-dir>/*.log)
   --home DIR       supervise: the dsh home the supervised instance boots with (profiles,
                    credentials — default: $DSH_HOME; required when that is unset)
   --initiator ID   schedule-exit: session id that requested the exit (default: $DSH_SESSION_ID);
-                   recorded in last-restart.json so the restart report returns to that session
-  --profile NAME   preflight/schedule-exit/restart: the dsh profile to dry-run (default:
+                   recorded in last-restart.json so the restart report returns to that session.
+                   Do NOT invent a value: a mismatched id routes the wake-up away from you
+                   (the CLI warns when ID contradicts this shell's $DSH_SESSION_ID)
+  --profile NAME   preflight/schedule-exit/restart/reconfigure: the dsh profile to dry-run (default:
                    $DSH_PROFILE, else "web")
   --preflight-timeout-ms MS  schedule-exit/restart: bound on the composition preflight (default 120000)
+  --preflight-surface MODE  configure-launch/reconfigure: explicit successor module surface, source or built
+  --preflight-runner FILE  runner file to bind by absolute path and SHA-256 (default: this package's matching face)
+  --preflight-install-anchor FILE  the exact successor dsh package.json; built imports resolve from this npm toolchain
+  --candidate-probe-command CMD  reconfigure: caller-supplied one-shot probe, durably co-bound with --start SHA-256
   --rollback       restart: on failure, git reset --hard to the recorded checkpoint
-  --force          restart/schedule-exit/supervise: override the sandbox probe refusal
+  --on-failure POLICY  reconfigure: REQUIRED pre-approved recovery policy:
+                   restore-previous (restore the complete previous launch spec) or
+                   wait-for-user (park without resetting a repository)
+  --browser-handoff MODE  reconfigure: required (default) or off; when a protected
+                   root announces a same-authority launch URL, readiness requires
+                   303 cookie exchange and authenticated / = 200; browser handoff
+                   separately requires an original/fallback page acknowledgement
+  --transition-file FILE  reconfigure: a schema-v1 reversible quarantine plan.
+                   The guard validates and preflights it on an isolated home,
+                   then applies it only after previous stops; recovery retains
+                   target-created replacements before restoring previous bytes.
+  --if-absent      configure-launch: initialize only; keep an existing selected spec
+  --force          restart/schedule-exit/supervise/reconfigure: override the sandbox probe refusal
   --sync           restart: run the whole loop in-process (debug/tests; the default
                    self-detaches a driver so the loop survives the caller's teardown)
 `;
@@ -240,16 +1307,21 @@ function parse(argv) {
 	const options = {
 		stateDir: "",
 		repoDir: "",
+		harnessRoot: "",
 		home: "",
 		maxAgeMinutes: 10,
 		port: void 0,
 		command: void 0,
+		run: false,
+		runArgv: void 0,
 		message: void 0,
+		detail: void 0,
 		start: void 0,
 		pid: void 0,
 		timeoutMs: void 0,
 		delayMs: void 0,
 		stopTimeoutMs: void 0,
+		supervisorYieldTimeoutMs: void 0,
 		log: void 0,
 		foreground: false,
 		rollback: false,
@@ -257,7 +1329,19 @@ function parse(argv) {
 		sync: false,
 		initiator: void 0,
 		profile: void 0,
-		preflightTimeoutMs: void 0
+		preflightTimeoutMs: void 0,
+		preflightSurface: void 0,
+		preflightRunner: void 0,
+		preflightInstallAnchor: void 0,
+		candidateProbeCommand: void 0,
+		onFailure: void 0,
+		browserHandoff: "required",
+		ifAbsent: false,
+		trustCommand: false,
+		includeDirty: false,
+		takeoverFrom: void 0,
+		cutoverId: void 0,
+		transitionFile: void 0
 	};
 	const positionals = [];
 	let i = 0;
@@ -269,6 +1353,10 @@ function parse(argv) {
 	try {
 		for (; i < argv.length; i++) {
 			const arg = argv[i] ?? "";
+			if (arg === "--") {
+				options.runArgv = argv.slice(i + 1);
+				break;
+			}
 			switch (arg) {
 				case "--state-dir":
 					options.stateDir = flagValue(arg, true) ?? "";
@@ -282,6 +1370,10 @@ function parse(argv) {
 					options.repoDir = flagValue(arg, true) ?? "";
 					i++;
 					break;
+				case "--harness-root":
+					options.harnessRoot = flagValue(arg, true) ?? "";
+					i++;
+					break;
 				case "--max-age": {
 					const raw = flagValue(arg, true);
 					const n = Number(raw);
@@ -302,10 +1394,23 @@ function parse(argv) {
 					options.command = flagValue(arg, true) ?? "";
 					i++;
 					break;
+				case "--run":
+					options.run = true;
+					break;
+				case "--trust-command":
+					options.trustCommand = true;
+					break;
+				case "--include-dirty":
+					options.includeDirty = true;
+					break;
 				case "--message":
 					options.message = flagValue(arg, true) ?? "";
 					i++;
 					break;
+				case "--detail":
+					options.detail = flagValue(arg, true);
+					i++;
+					break;
 				case "--start":
 					options.start = flagValue(arg, true) ?? "";
 					i++;
@@ -342,6 +1447,14 @@ function parse(argv) {
 					i++;
 					break;
 				}
+				case "--supervisor-yield-timeout-ms": {
+					const raw = flagValue(arg, true);
+					const n = Number(raw);
+					if (raw === void 0 || !Number.isInteger(n) || n < 100) throw new Error("--supervisor-yield-timeout-ms must be an integer >= 100");
+					options.supervisorYieldTimeoutMs = n;
+					i++;
+					break;
+				}
 				case "--foreground":
 					options.foreground = true;
 					break;
@@ -361,6 +1474,58 @@ function parse(argv) {
 					i++;
 					break;
 				}
+				case "--preflight-surface": {
+					const value = flagValue(arg, true);
+					if (value !== "source" && value !== "built") throw new Error("--preflight-surface must be source or built");
+					options.preflightSurface = value;
+					i++;
+					break;
+				}
+				case "--preflight-runner":
+					options.preflightRunner = flagValue(arg, true) ?? "";
+					i++;
+					break;
+				case "--preflight-install-anchor":
+					options.preflightInstallAnchor = flagValue(arg, true) ?? "";
+					i++;
+					break;
+				case "--candidate-probe-command":
+					options.candidateProbeCommand = flagValue(arg, true) ?? "";
+					i++;
+					break;
+				case "--on-failure": {
+					const value = flagValue(arg, true);
+					if (value !== "restore-previous" && value !== "wait-for-user") throw new Error("--on-failure must be restore-previous or wait-for-user");
+					options.onFailure = value;
+					i++;
+					break;
+				}
+				case "--browser-handoff": {
+					const value = flagValue(arg, true);
+					if (value !== "required" && value !== "off") throw new Error("--browser-handoff must be required or off");
+					options.browserHandoff = value;
+					i++;
+					break;
+				}
+				case "--takeover-from": {
+					const raw = flagValue(arg, true);
+					const value = Number(raw);
+					if (raw === void 0 || !Number.isInteger(value) || value <= 0) throw new Error("--takeover-from must be a positive pid");
+					options.takeoverFrom = value;
+					i++;
+					break;
+				}
+				case "--cutover-id":
+					options.cutoverId = flagValue(arg, true) ?? "";
+					i++;
+					break;
+				case "--transition-file":
+					options.transitionFile = flagValue(arg, true) ?? "";
+					i++;
+					break;
+				case "--if-absent":
+					options.ifAbsent = true;
+					break;
 				case "--rollback":
 					options.rollback = true;
 					break;
@@ -416,6 +1581,68 @@ async function sleep(ms) {
 		setTimeout(resolve, ms);
 	});
 }
+/** Execute the exact argv used as credential evidence, streaming diagnostics. */
+async function runCredentialCommand(argv, cwd, io) {
+	const executable = argv[0];
+	if (executable === void 0 || executable === "") return {
+		ok: false,
+		detail: "no program was provided after --"
+	};
+	return new Promise((resolvePromise) => {
+		let settled = false;
+		const settle = (result) => {
+			if (settled) return;
+			settled = true;
+			resolvePromise(result);
+		};
+		let child;
+		try {
+			child = spawn(executable, argv.slice(1), {
+				cwd,
+				env: testChildEnv("credential-command", { ...process.env }, { tempRoot: cwd }),
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				]
+			});
+			registerSpawnedTestProcess(child, "credential-command", { tempRoot: cwd });
+		} catch (error) {
+			settle({
+				ok: false,
+				detail: `could not start ${JSON.stringify(executable)}: ${String(error)}`
+			});
+			return;
+		}
+		child.stdout.on("data", (chunk) => {
+			io.stdout(chunk.toString());
+		});
+		child.stderr.on("data", (chunk) => {
+			io.stderr(chunk.toString());
+		});
+		child.once("error", (error) => {
+			settle({
+				ok: false,
+				detail: `could not start ${JSON.stringify(executable)}: ${String(error)}`
+			});
+		});
+		child.once("exit", (code, signal) => {
+			if (code === 0) settle({ ok: true });
+			else settle({
+				ok: false,
+				detail: signal === null ? `command exited ${code ?? "without a status"}` : `command was terminated by ${signal}`
+			});
+		});
+	});
+}
+/** Stable, non-shell rendering for credential audit metadata. */
+function renderArgv(argv) {
+	return argv.map((word) => JSON.stringify(word)).join(" ");
+}
+/** The credential gate always includes uncommitted and untracked inputs. */
+function verifyRepoCredential(stateDir, repoDir, maxAgeMinutes) {
+	return verifyCredential(loadState(stateDir), currentHead(repoDir), Date.now(), maxAgeMinutes, isWorkingTreeClean(repoDir));
+}
 /**
 * How the spawned watchdog should invoke the guard CLI: the built form runs
 * `node <cli>`; the source form needs tsx with an absolute path (the watchdog
@@ -456,6 +1683,23 @@ function exitAgentInvocation() {
 const DEFAULT_PREFLIGHT_TIMEOUT_MS = 12e4;
 /** A pending restart marker older than this is stale — its watchdog died mid-flow. */
 const RESTART_MARKER_TTL_MS = 9e5;
+function isRestartAuthorization(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const authorization = value;
+	return authorization.version === 1 && (authorization.kind === "fresh-credential" || authorization.kind === "proven-deployment") && typeof authorization.revision === "string" && authorization.revision !== "" && typeof authorization.evidenceSha256 === "string" && /^[a-f0-9]{64}$/.test(authorization.evidenceSha256);
+}
+function readRestartRequestMarker(stateDir) {
+	try {
+		const marker = JSON.parse(readFileSync(stateFile(stateDir, "restartRequested"), "utf8"));
+		if (typeof marker !== "object" || marker === null) return null;
+		return {
+			...typeof marker.requestedAt === "number" ? { requestedAt: marker.requestedAt } : {},
+			...isRestartAuthorization(marker.authorization) ? { authorization: marker.authorization } : {}
+		};
+	} catch {
+		return null;
+	}
+}
 /**
 * The restart marker's state. Every verb that can stop the instance must
 * consult this (and the restart lock) — a stop right invisible to the other
@@ -464,12 +1708,8 @@ const RESTART_MARKER_TTL_MS = 9e5;
 function restartMarkerState(stateDir) {
 	const file = stateFile(stateDir, "restartRequested");
 	if (!existsSync(file)) return "none";
-	try {
-		const marker = JSON.parse(readFileSync(file, "utf8"));
-		return typeof marker.requestedAt === "number" && Date.now() - marker.requestedAt <= RESTART_MARKER_TTL_MS ? "fresh" : "stale";
-	} catch {
-		return "stale";
-	}
+	const marker = readRestartRequestMarker(stateDir);
+	return marker?.requestedAt !== void 0 && Date.now() - marker.requestedAt <= RESTART_MARKER_TTL_MS ? "fresh" : "stale";
 }
 /** Captured preflight output is diagnostics, not a log — cap it before it can grow without bound. */
 const PREFLIGHT_OUTPUT_CAP = 65536;
@@ -502,11 +1742,12 @@ const preflightInternals = {
 };
 /**
 * The harness checkout the live instance boots from (and the preflight
-* runner resolves the official published packages from): the `--repo` target
-* when given, else `DSH_HARNESS`, else the conventional default.
+* runner resolves the official published packages from): the
+* `--harness-root` target when given, else `DSH_HARNESS`, else the
+* conventional default. Credential repositories never enter this resolver.
 */
-function resolveHarnessRoot(optionRepoDir, env = process.env) {
-	if (optionRepoDir !== void 0 && optionRepoDir !== "") return optionRepoDir;
+function resolveHarnessRoot(optionHarnessRoot, env = process.env) {
+	if (optionHarnessRoot !== void 0 && optionHarnessRoot !== "") return optionHarnessRoot;
 	const fromEnv = env.DSH_HARNESS;
 	return fromEnv !== void 0 && fromEnv.trim() !== "" ? fromEnv : join(homedir(), "code/deepseek-harness");
 }
@@ -522,7 +1763,69 @@ function resolveRunnerCommand(harnessRoot) {
 	const here = dirname(fileURLToPath(import.meta.url));
 	const runner = existsSync(join(here, "preflight-runner.ts")) ? join(here, "preflight-runner.ts") : existsSync(join(here, "preflight-runner.js")) ? join(here, "preflight-runner.js") : void 0;
 	if (runner === void 0) return void 0;
-	return `node --import ${shellQuote(tsx)} ${shellQuote(runner)}`;
+	return `node --import ${shellQuote(tsx)} ${shellQuote(runner)} --host-surface source --install-anchor ${shellQuote(join(harnessRoot, "apps", "cli", "package.json"))}`;
+}
+function fileSha256(file) {
+	return createHash("sha256").update(readFileSync(file)).digest("hex");
+}
+function killSpawnGroup(pid) {
+	if (pid === void 0) return;
+	try {
+		process.kill(-pid, "SIGKILL");
+	} catch {}
+}
+function defaultPreflightRunner(surface) {
+	const here = dirname(fileURLToPath(import.meta.url));
+	return (surface === "source" ? [
+		join(here, "preflight-runner.ts"),
+		join(here, "..", "src", "preflight-runner.ts"),
+		join(here, "preflight-runner.js"),
+		join(here, "..", "lib", "preflight-runner.js")
+	] : [join(here, "preflight-runner.js"), join(here, "..", "lib", "preflight-runner.js")]).find((file) => existsSync(file));
+}
+/** Build and validate the explicit preflight contract persisted with a launch spec. */
+function resolvePreflightSpec(options, command, harnessRoot, requireCandidate) {
+	if (options.preflightSurface === void 0) throw new Error("--preflight-surface source|built is required; the guard will not infer the successor execution surface");
+	if (options.preflightInstallAnchor === void 0 || options.preflightInstallAnchor === "") throw new Error("--preflight-install-anchor FILE is required and must name the successor dsh package.json");
+	const installAnchor = resolve(options.preflightInstallAnchor);
+	let manifest;
+	try {
+		manifest = JSON.parse(readFileSync(installAnchor, "utf8"));
+	} catch (error) {
+		throw new Error(`preflight install anchor is unreadable: ${String(error)}`);
+	}
+	if (manifest.name !== "@deepseek-ai/dsh") throw new Error("preflight install anchor must be @deepseek-ai/dsh/package.json");
+	if (typeof manifest.version !== "string" || manifest.version === "") throw new Error("preflight install anchor must declare the dsh package version");
+	const configuredRunner = options.preflightRunner ?? defaultPreflightRunner(options.preflightSurface);
+	if (configuredRunner === void 0 || configuredRunner === "") throw new Error(`no ${options.preflightSurface} preflight runner exists; build ankh-guard or pass --preflight-runner FILE`);
+	const runnerPath = resolve(configuredRunner);
+	if (!existsSync(runnerPath)) throw new Error(`preflight runner does not exist: ${runnerPath}`);
+	if (options.preflightSurface === "built" && !runnerPath.endsWith(".js")) throw new Error("built preflight requires a JavaScript runner");
+	const runnerRuntimeArgs = [];
+	if (options.preflightSurface === "source") {
+		const tsx = join(harnessRoot, "node_modules", "tsx", "dist", "esm", "index.mjs");
+		if (!existsSync(tsx)) throw new Error(`source preflight requires the target checkout's tsx runtime: ${tsx}`);
+		runnerRuntimeArgs.push("--import", tsx);
+	}
+	const candidateProbeCommand = options.candidateProbeCommand;
+	if (requireCandidate && (candidateProbeCommand === void 0 || candidateProbeCommand.trim() === "")) throw new Error("--candidate-probe-command CMD is required; the caller must derive it from the target executable/argv before the previous host stops");
+	return {
+		version: 1,
+		surface: options.preflightSurface,
+		runnerExecutable: process.execPath,
+		runnerRuntimeArgs,
+		runnerPath,
+		runnerSha256: fileSha256(runnerPath),
+		installAnchor,
+		installAnchorSha256: fileSha256(installAnchor),
+		hostPackageVersion: manifest.version,
+		targetCommandSha256: commandSha256(command),
+		...candidateProbeCommand === void 0 || candidateProbeCommand.trim() === "" ? {} : {
+			candidateProbeCommand,
+			candidateProbeSha256: commandSha256(candidateProbeCommand),
+			candidateProbeProvenance: "caller-supplied"
+		}
+	};
 }
 /** POSIX single-quote one word for the shell command line. */
 function shellQuote(word) {
@@ -568,13 +1871,57 @@ function redactLaunchCommand(command) {
 * @param profile - the dsh profile to dry-run.
 * @param timeoutMs - bound on the whole subprocess run; a timeout kills it.
 * @param harnessRoot - harness checkout for the runner (default: DSH_HARNESS / ~/code/deepseek-harness).
+* @param home - dsh home the dry-run must read instead of ambient process state.
 * @returns the classified outcome.
 */
-async function runPreflightCheck(profile, timeoutMs, harnessRoot) {
-	const override = process.env.DSH_PREFLIGHT_COMMAND;
+async function runPreflightCheck(profile, timeoutMs, harnessRoot, home, binding) {
+	const override = binding === void 0 ? process.env.DSH_PREFLIGHT_COMMAND : void 0;
 	let command;
+	let executable;
+	let argv = [];
 	let usingRunner = false;
-	if (override !== void 0 && override !== "") command = override;
+	if (binding !== void 0) {
+		let runnerSha;
+		try {
+			runnerSha = fileSha256(binding.runnerPath);
+		} catch {
+			return {
+				kind: "infra-failed",
+				output: "",
+				detail: `the bound preflight runner is unavailable: ${binding.runnerPath}`
+			};
+		}
+		if (runnerSha !== binding.runnerSha256) return {
+			kind: "infra-failed",
+			output: "",
+			detail: "the bound preflight runner changed after launch configuration"
+		};
+		try {
+			if (fileSha256(binding.installAnchor) !== binding.installAnchorSha256) return {
+				kind: "infra-failed",
+				output: "",
+				detail: "the bound dsh install anchor changed after launch configuration"
+			};
+		} catch {
+			return {
+				kind: "infra-failed",
+				output: "",
+				detail: `the bound dsh install anchor is unavailable: ${binding.installAnchor}`
+			};
+		}
+		executable = binding.runnerExecutable;
+		argv = [
+			...binding.runnerRuntimeArgs,
+			binding.runnerPath,
+			"--host-surface",
+			binding.surface,
+			"--install-anchor",
+			binding.installAnchor,
+			"--profile",
+			profile
+		];
+		usingRunner = true;
+	} else if (override !== void 0 && override !== "") command = override;
 	else {
 		const root = harnessRoot ?? resolveHarnessRoot(void 0);
 		const runner = preflightInternals.resolveRunner(root);
@@ -594,13 +1941,19 @@ async function runPreflightCheck(profile, timeoutMs, harnessRoot) {
 	return await new Promise((resolvePromise) => {
 		let output = "";
 		let timedOut = false;
-		const child = usingRunner ? spawn(command, {
+		const preflightEnv = testChildEnv("composition-preflight", {
+			...process.env,
+			DSH_HARNESS: harnessForRunner,
+			...home === void 0 ? {} : { DSH_HOME: home }
+		}, { ...home === void 0 ? {} : { tempRoot: home } });
+		const child = executable === void 0 ? spawn(command ?? "", {
 			shell: true,
-			env: {
-				...process.env,
-				DSH_HARNESS: harnessForRunner
-			}
-		}) : spawn(command, { shell: true });
+			env: preflightEnv
+		}) : spawn(executable, argv, {
+			shell: false,
+			env: preflightEnv
+		});
+		registerSpawnedTestProcess(child, "composition-preflight", { ...home === void 0 ? {} : { tempRoot: home } });
 		const append = (chunk) => {
 			if (output.length < PREFLIGHT_OUTPUT_CAP) output += chunk.toString("utf8");
 		};
@@ -642,6 +1995,61 @@ async function runPreflightCheck(profile, timeoutMs, harnessRoot) {
 		});
 	});
 }
+/** Execute the caller-supplied one-shot probe under the target home/root. */
+async function runCandidateProbe(binding, targetCommand, timeoutMs, harnessRoot, home) {
+	if (binding.targetCommandSha256 !== commandSha256(targetCommand)) return {
+		kind: "infra-failed",
+		output: "",
+		detail: "candidate probe is bound to a different target launch command"
+	};
+	if (binding.candidateProbeCommand === void 0 || binding.candidateProbeSha256 === void 0 || commandSha256(binding.candidateProbeCommand) !== binding.candidateProbeSha256) return {
+		kind: "infra-failed",
+		output: "",
+		detail: "candidate probe command is missing or changed after binding"
+	};
+	return await new Promise((resolvePromise) => {
+		let output = "";
+		let timedOut = false;
+		const child = spawn(binding.candidateProbeCommand, {
+			shell: true,
+			detached: true,
+			env: testChildEnv("candidate-probe", {
+				...process.env,
+				DSH_HARNESS: harnessRoot,
+				DSH_HOME: home,
+				ANKH_TARGET_COMMAND_SHA256: binding.targetCommandSha256
+			}, { tempRoot: home })
+		});
+		registerSpawnedTestProcess(child, "candidate-probe", { tempRoot: home });
+		const append = (chunk) => {
+			if (output.length < PREFLIGHT_OUTPUT_CAP) output += chunk.toString("utf8");
+		};
+		child.stdout.on("data", append);
+		child.stderr.on("data", append);
+		const timer = setTimeout(() => {
+			timedOut = true;
+			killSpawnGroup(child.pid);
+			child.kill("SIGKILL");
+		}, timeoutMs);
+		child.on("close", (code) => {
+			clearTimeout(timer);
+			if (timedOut) resolvePromise({
+				kind: "infra-failed",
+				output,
+				detail: `candidate probe timed out after ${timeoutMs} ms`
+			});
+			else if (code === 0) resolvePromise({
+				kind: "pass",
+				output
+			});
+			else resolvePromise({
+				kind: "composition-failed",
+				output,
+				detail: `candidate probe exited ${String(code)}`
+			});
+		});
+	});
+}
 /** The profile a gated verb dry-runs: the flag, then $DSH_PROFILE, then the deployment default. */
 function resolveProfileName(options) {
 	const flag = options.profile ?? "";
@@ -649,22 +2057,85 @@ function resolveProfileName(options) {
 	const env = process.env.DSH_PROFILE ?? "";
 	return env !== "" ? env : "web";
 }
-/**
-* The home the supervised instance boots with (the watchdog exports it as
-* DSH_HOME): the explicit flag first, then the environment — the same
-* flag-over-env order as every other resolver in this CLI (and as the
-* installers' own --home). Undefined when neither names one: supervise fails
-* loud rather than boot the instance on a home guessed from the state dir.
-*/
-function resolveWdHome(optionHome, env = process.env) {
-	if (optionHome !== "") return optionHome;
-	const fromEnv = env.DSH_HOME;
-	return fromEnv !== void 0 && fromEnv !== "" ? fromEnv : void 0;
+/**
+* The home the supervised instance boots with (the watchdog exports it as
+* DSH_HOME): the explicit flag first, then the environment — the same
+* flag-over-env order as every other resolver in this CLI (and as the
+* installers' own --home). Undefined when neither names one: supervise fails
+* loud rather than boot the instance on a home guessed from the state dir.
+*/
+function resolveWdHome(optionHome, env = process.env) {
+	if (optionHome !== "") return optionHome;
+	const fromEnv = env.DSH_HOME;
+	return fromEnv !== void 0 && fromEnv !== "" ? fromEnv : void 0;
+}
+/** A persisted launch spec must never guess which checkout is the host. */
+function resolveLaunchHarnessRoot(optionHarnessRoot, selected, env = process.env) {
+	if (optionHarnessRoot !== "") return optionHarnessRoot;
+	if (selected !== void 0 && selected !== "") return selected;
+	const fromEnv = env.DSH_HARNESS;
+	return fromEnv !== void 0 && fromEnv.trim() !== "" ? fromEnv : void 0;
+}
+function launchSpec(input) {
+	return {
+		version: 1,
+		command: input.command,
+		port: input.port,
+		home: resolve(input.home),
+		credentialRepo: resolve(input.credentialRepo),
+		harnessRoot: resolve(input.harnessRoot),
+		profile: input.profile,
+		...input.preflight === void 0 ? {} : { preflight: input.preflight }
+	};
+}
+function sameLaunchSpec(left, right) {
+	return left.command === right.command && left.port === right.port && left.home === right.home && left.credentialRepo === right.credentialRepo && left.harnessRoot === right.harnessRoot && left.profile === right.profile && JSON.stringify(left.preflight) === JSON.stringify(right.preflight);
+}
+/** Resolve supervise's complete spec; a post-wait refresh always prefers durable state. */
+function resolveSuperviseSpec(options, stateDir, repoDir, io, preferDurable = false) {
+	const durable = readLaunchState(stateDir);
+	const selected = durable === null ? void 0 : selectedLaunchSpec(durable);
+	const recorded = readInstanceLaunch(stateDir);
+	const port = preferDurable && selected !== void 0 ? selected.port : options.port ?? selected?.port ?? recorded?.port;
+	if (port === void 0) {
+		io.stderr(`supervise requires --port N and --start "CMD" on first configuration\n\n${USAGE}`);
+		return;
+	}
+	const command = !preferDurable && options.start !== void 0 && options.start !== "" ? options.start : selected?.command ?? resolveStartCommand(void 0, stateDir, "supervise", io, port);
+	if (command === void 0 || command === "") {
+		io.stderr(`supervise requires --port N and --start "CMD" on first configuration\n\n${USAGE}`);
+		return;
+	}
+	const home = !preferDurable && options.home !== "" ? options.home : selected?.home ?? resolveWdHome("");
+	if (home === void 0) {
+		io.stderr("supervise needs the dsh home: pass --home DIR or set DSH_HOME — the supervised instance reads its profiles/credentials from there, and deriving one from --state-dir would guess wrong\n");
+		return;
+	}
+	const harnessRoot = resolveLaunchHarnessRoot(!preferDurable ? options.harnessRoot : "", selected?.harnessRoot);
+	if (harnessRoot === void 0) {
+		io.stderr("supervise needs the dsh host checkout: pass --harness-root DIR or set DSH_HARNESS. The credential --repo is a separate role and is never used as the host root.\n");
+		return;
+	}
+	return launchSpec({
+		command,
+		port,
+		home,
+		credentialRepo: !preferDurable && options.repoDir !== "" ? repoDir : selected?.credentialRepo ?? repoDir,
+		harnessRoot,
+		profile: !preferDurable && options.profile !== void 0 && options.profile !== "" ? options.profile : selected?.profile ?? resolveProfileName(options),
+		...selected?.preflight === void 0 || selected.command !== command ? {} : { preflight: selected.preflight }
+	});
+}
+/** Existing full spec. The legacy launch record lacks both repository roles. */
+function resolvePreviousSpec(stateDir, io) {
+	const state = readLaunchState(stateDir);
+	if (state !== null) return selectedLaunchSpec(state);
+	io.stderr("reconfigure refused: no complete durable previous launch specification is available. The legacy instance-launch record does not identify credential repo, host root, home, and profile independently. Run `configure-launch --port N --start \"CURRENT CMD\" --home DIR --repo CREDENTIAL_REPO --harness-root HOST_ROOT --profile NAME` first.\n");
 }
 /** The first ~40 lines of captured preflight output, newline-terminated, or empty. */
 function summarizeOutput(output) {
 	if (output.trim() === "") return "";
-	const lines = output.split("\n");
+	const lines = output.replace(/([?&](?:token|grant)=)[^\s&#"']+/gi, "$1<redacted>").split("\n");
 	return `${(lines.length > 41 ? [...lines.slice(0, 40), `… (${lines.length - 40} more lines)`] : lines).join("\n").replace(/\n+$/, "")}\n`;
 }
 /**
@@ -676,10 +2147,12 @@ function summarizeOutput(output) {
 * @param timeoutMs - bound on the preflight subprocess.
 * @param io - output sinks.
 * @param harnessRoot - harness checkout for the standalone runner.
+* @param home - dsh home to dry-run.
 * @returns whether the verb may proceed.
 */
-async function preflightGate(verb, profile, timeoutMs, io, harnessRoot) {
-	const outcome = await runPreflightCheck(profile, timeoutMs, harnessRoot);
+async function preflightGate(verb, profile, timeoutMs, io, harnessRoot, home, binding) {
+	io.stdout(`composition preflight START (profile ${JSON.stringify(profile)}, timeout ${timeoutMs} ms)\n`);
+	const outcome = await runPreflightCheck(profile, timeoutMs, harnessRoot, home, binding);
 	switch (outcome.kind) {
 		case "pass":
 			io.stdout(`composition preflight PASS (profile ${JSON.stringify(profile)})\n`);
@@ -695,6 +2168,54 @@ async function preflightGate(verb, profile, timeoutMs, io, harnessRoot) {
 			return false;
 	}
 }
+async function candidateProbeGate(target, timeoutMs, io, home) {
+	if (target.preflight === void 0) {
+		io.stderr("reconfigure refused: target has no explicit candidate probe binding\n");
+		return false;
+	}
+	const outcome = await runCandidateProbe(target.preflight, target.command, timeoutMs, target.harnessRoot, home);
+	if (outcome.kind === "pass") {
+		io.stdout(`candidate command probe PASS (target command ${target.preflight.targetCommandSha256.slice(0, 16)})\n`);
+		return true;
+	}
+	io.stderr(`reconfigure refused: candidate command probe ${outcome.kind === "composition-failed" ? "failed" : "could not execute"}${outcome.detail === void 0 ? "" : ` — ${outcome.detail}`}:\n${summarizeOutput(outcome.output)}`);
+	return false;
+}
+/** Same-launch verbs follow the durable host root unless explicitly overridden. */
+function preflightHarnessRoot(options, stateDir) {
+	if (options.harnessRoot !== "") return resolveHarnessRoot(options.harnessRoot);
+	const state = readLaunchState(stateDir);
+	return state === null ? resolveHarnessRoot(void 0) : selectedLaunchSpec(state).harnessRoot;
+}
+/**
+* A same-launch restart must use the exact durable supervisor configuration.
+* Explicit flags may confirm that configuration, but may not silently replace
+* one field while the live watchdog still owns a different command.
+*/
+function stableScheduleSpec(options, stateDir, resolvedRepoDir, io) {
+	const state = readLaunchState(stateDir);
+	if (state === null) return null;
+	if (state.mode !== "stable") {
+		io.stderr(`schedule-exit refused: launch state is still in cutover mode (${state.cutoverId}); settle its receipt before a same-launch restart\n`);
+		return;
+	}
+	const active = state.active;
+	const conflicts = [];
+	if (options.port !== void 0 && options.port !== active.port) conflicts.push(`port ${options.port} != ${active.port}`);
+	if (options.repoDir !== "" && resolve(resolvedRepoDir) !== resolve(active.credentialRepo)) conflicts.push(`credential repo ${resolve(resolvedRepoDir)} != ${resolve(active.credentialRepo)}`);
+	if (options.harnessRoot !== "" && resolve(options.harnessRoot) !== resolve(active.harnessRoot)) conflicts.push(`harness root ${resolve(options.harnessRoot)} != ${resolve(active.harnessRoot)}`);
+	if (options.profile !== void 0 && options.profile !== "" && options.profile !== active.profile) conflicts.push(`profile ${options.profile} != ${active.profile}`);
+	if (conflicts.length > 0) {
+		io.stderr(`schedule-exit refused: explicit flags conflict with the durable active launch specification (${conflicts.join("; ")}). Use reconfigure for launch changes.\n`);
+		return;
+	}
+	const recorded = readInstanceLaunch(stateDir);
+	if (recorded === null || recorded.source !== "supervisor" || recorded.supervised !== true || recorded.command !== active.command || recorded.port !== active.port) {
+		io.stderr("schedule-exit refused: the live instance launch record does not prove that its supervisor owns the durable active launch specification. Re-establish supervision or use reconfigure; do not stop the host on an inferred command.\n");
+		return;
+	}
+	return active;
+}
 /**
 * Wait for a pid to exit; SIGKILL (the whole descendant tree) after the
 * deadline. @param onEscalate - invoked right before the SIGKILL, so the
@@ -748,6 +2269,29 @@ function rollbackToKnownGood(stateDir, repoDir, io) {
 * @returns the process exit code: 0 ok, 1 gate denied / failure, 2 usage error.
 */
 async function runCli(argv, io) {
+	const verdictFile = process.env.DSH_ANKH_VERDICT_FILE;
+	let recorded;
+	const note = (stage, reason) => {
+		if (recorded !== void 0) return;
+		recorded = {
+			stage,
+			reason
+		};
+		if (verdictFile !== void 0) try {
+			writeFileSync(verdictFile, `${JSON.stringify(recorded)}\n`, { mode: 384 });
+		} catch {}
+	};
+	/** Record + print a one-line refusal, preserving the site's exit code. */
+	const refuse = (stage, message, code = 1) => {
+		note(stage, message.trim().split("\n", 1)[0] ?? message.trim());
+		io.stderr(message.endsWith("\n") ? message : `${message}\n`);
+		return code;
+	};
+	/** Record a refusal whose human text a gate already printed. */
+	const refuseQuiet = (stage, reason, code = 1) => {
+		note(stage, reason);
+		return code;
+	};
 	const parsed = parse(argv);
 	if ("error" in parsed) {
 		io.stderr(parsed.error);
@@ -758,7 +2302,8 @@ async function runCli(argv, io) {
 	const repoDir = resolveRepoDir(options.repoDir);
 	switch (command) {
 		case "verify": {
-			const result = verifyCredential(loadState(stateDir), currentHead(repoDir), Date.now(), options.maxAgeMinutes);
+			const launch = readLaunchState(stateDir);
+			const result = launch?.mode === "stable" && resolve(launch.active.credentialRepo) === resolve(repoDir) ? verifyRestartEvidence(stateDir, launch.active, options.maxAgeMinutes) : verifyRepoCredential(stateDir, repoDir, options.maxAgeMinutes);
 			io.stdout(`${result.reason}\n`);
 			if (result.ok) {
 				io.stdout(FULL_ACCESS_HINT);
@@ -772,17 +2317,65 @@ async function runCli(argv, io) {
 				io.stderr(`record requires a <scope>\n\n${USAGE}`);
 				return 2;
 			}
-			const head = currentHead(repoDir);
-			if (head === null) {
+			if (positionals.length > 1) {
+				io.stderr(`record accepts one <scope>; put the evidence command after --run --\n\n${USAGE}`);
+				return 2;
+			}
+			if (options.run && options.trustCommand) {
+				io.stderr("record requires exactly one proof mode: --run or --trust-command\n");
+				return 2;
+			}
+			if (options.run && options.command !== void 0) {
+				io.stderr("record --run derives its audit command from the exact argv after --; do not also pass --command\n");
+				return 2;
+			}
+			if (options.runArgv !== void 0 && !options.run) {
+				io.stderr("record command argv after -- requires --run\n");
+				return 2;
+			}
+			if (!options.run && !options.trustCommand) {
+				io.stderr("record refuses self-attestation: use --run -- PROGRAM [ARG...] so the guard observes exit 0, or --trust-command --command CMD only from an external orchestrator that already observed the command\n");
+				return 2;
+			}
+			if (options.run && (options.runArgv === void 0 || options.runArgv.length === 0)) {
+				io.stderr("record --run requires -- PROGRAM [ARG...]\n");
+				return 2;
+			}
+			if (options.trustCommand && (options.command === void 0 || options.command.trim() === "")) {
+				io.stderr("record --trust-command requires a non-empty --command description\n");
+				return 2;
+			}
+			const headBefore = currentHead(repoDir);
+			if (headBefore === null) {
 				io.stderr("cannot record a credential outside a git repository\n");
 				return 1;
 			}
+			if (!isWorkingTreeClean(repoDir)) {
+				io.stderr("cannot record a credential while the working tree has staged, unstaged, or untracked changes\n");
+				return 1;
+			}
+			let evidenceCommand = options.command ?? "";
+			if (options.run) {
+				const runArgv = options.runArgv ?? [];
+				clearCredential(stateDir, Date.now());
+				evidenceCommand = renderArgv(runArgv);
+				io.stdout(`running credential evidence: ${evidenceCommand}\n`);
+				const evidence = await runCredentialCommand(runArgv, repoDir, io);
+				if (!evidence.ok) {
+					io.stderr(`credential evidence failed: ${evidence.detail}; no credential recorded\n`);
+					return 1;
+				}
+				if (currentHead(repoDir) !== headBefore || !isWorkingTreeClean(repoDir)) {
+					io.stderr("credential evidence exited 0 but changed HEAD or left the working tree dirty; no credential recorded\n");
+					return 1;
+				}
+			}
 			recordCredential(stateDir, {
 				scope,
-				revision: head,
-				command: options.command ?? ""
+				revision: headBefore,
+				command: evidenceCommand
 			}, Date.now());
-			io.stdout(`recorded green credential: ${scope} @ ${head}\n`);
+			io.stdout(`recorded green credential: ${scope} @ ${headBefore}${options.trustCommand ? " (external proof trusted)" : ""}\n`);
 			io.stdout(FULL_ACCESS_HINT);
 			if (liveWatchdogPid(stateDir) === null) io.stderr(NO_WATCHDOG_HINT);
 			return 0;
@@ -792,13 +2385,190 @@ async function runCli(argv, io) {
 			io.stdout(`${JSON.stringify(state, null, 2)}\n`);
 			return 0;
 		}
+		case "configure-launch": {
+			if (options.ifAbsent && readLaunchState(stateDir) !== null) {
+				io.stdout("launch specification already exists — kept it unchanged (--if-absent)\n");
+				return 0;
+			}
+			if (options.port === void 0 || options.start === void 0 || options.start === "") {
+				io.stderr(`configure-launch requires --port N and --start "CMD"\n\n${USAGE}`);
+				return 2;
+			}
+			const home = resolveWdHome(options.home);
+			if (home === void 0) {
+				io.stderr("configure-launch requires --home DIR or DSH_HOME\n");
+				return 2;
+			}
+			const harnessRoot = resolveLaunchHarnessRoot(options.harnessRoot);
+			if (harnessRoot === void 0) {
+				io.stderr("configure-launch requires --harness-root DIR or DSH_HARNESS; --repo names the independent credential/rollback repository\n");
+				return 2;
+			}
+			let preflight;
+			try {
+				preflight = resolvePreflightSpec(options, options.start, harnessRoot, false);
+			} catch (error) {
+				io.stderr(`configure-launch refused: ${error instanceof Error ? error.message : String(error)}\n`);
+				return 2;
+			}
+			const spec = launchSpec({
+				command: options.start,
+				port: options.port,
+				home,
+				credentialRepo: repoDir,
+				harnessRoot,
+				profile: resolveProfileName(options),
+				preflight
+			});
+			const written = writeStableLaunchSpec(stateDir, spec, options.ifAbsent);
+			if (written) writeInstanceLaunchAsSupervisor(stateDir, {
+				command: spec.command,
+				source: "supervisor",
+				supervised: true,
+				port: spec.port,
+				recordedAt: Date.now()
+			});
+			io.stdout(written ? `launch specification recorded for :${spec.port} (command sha is in launch-status)\n` : "launch specification already exists — kept it unchanged (--if-absent)\n");
+			return 0;
+		}
+		case "launch-status":
+			io.stdout(`${JSON.stringify({
+				launch: summarizeLaunchState(readLaunchState(stateDir)),
+				receipt: readCutoverReceipt(stateDir)
+			}, null, 2)}\n`);
+			return 0;
+		case "transition-apply":
+		case "transition-rollback": {
+			const id = positionals[0];
+			if (id === void 0 || positionals.length !== 1) {
+				io.stderr(`${command} requires one CUTOVER_ID\n`);
+				return 2;
+			}
+			const transaction = activeCutover(stateDir);
+			if (transaction === null || transaction.receipt.id !== id || transaction.state.transition === void 0) {
+				io.stderr(`${command} refused: cutover ${id} has no active prepared transition\n`);
+				return 1;
+			}
+			const reference = transaction.state.transition;
+			const identityIsLive = (pid, startToken) => pid !== void 0 && startToken !== void 0 && processIdentityMatches({
+				pid,
+				startToken
+			});
+			if (command === "transition-apply") {
+				if (transaction.state.selected !== "target") {
+					io.stderr("transition-apply refused: the target launch specification is not selected\n");
+					return 1;
+				}
+				const previous = transaction.receipt.ownership.previous;
+				if (identityIsLive(previous.childPid, previous.childStartToken) || identityIsLive(previous.listenerPid, previous.listenerStartToken)) {
+					io.stderr("transition-apply refused: the proven previous process is still alive\n");
+					return 1;
+				}
+				try {
+					const result = applyTransition(reference, transaction.state.previous.home, stateDir, id);
+					recordCutoverEvent(stateDir, id, "transition", ["applied", reference.planSha256], Date.now());
+					io.stdout(`transition applied (${result.changed.length} changed, ${result.unchanged.length} unchanged)\n`);
+					return 0;
+				} catch (error) {
+					try {
+						recordCutoverEvent(stateDir, id, "transition", [
+							"apply-failed",
+							reference.planSha256,
+							error instanceof Error ? error.message : String(error)
+						], Date.now());
+					} catch {}
+					io.stderr(`transition-apply failed: ${String(error)}\n`);
+					return 1;
+				}
+			}
+			const liveTarget = transaction.receipt.attempts.some((attempt) => attempt.role === "target" && identityIsLive(attempt.childPid, attempt.childStartToken));
+			const targetOwnership = transaction.receipt.ownership.target;
+			if (liveTarget || targetOwnership !== void 0 && (identityIsLive(targetOwnership.childPid, targetOwnership.childStartToken) || identityIsLive(targetOwnership.listenerPid, targetOwnership.listenerStartToken))) {
+				io.stderr("transition-rollback refused: a proven target process is still alive\n");
+				return 1;
+			}
+			try {
+				const result = rollbackTransition(reference, transaction.state.previous.home, stateDir, id);
+				recordCutoverEvent(stateDir, id, "transition", ["rolled-back", reference.planSha256], Date.now());
+				io.stdout(`transition rolled back (${result.changed.length} changed, ${result.unchanged.length} unchanged)\n`);
+				return 0;
+			} catch (error) {
+				try {
+					recordCutoverEvent(stateDir, id, "transition", [
+						"rollback-failed",
+						reference.planSha256,
+						error instanceof Error ? error.message : String(error)
+					], Date.now());
+				} catch {}
+				io.stderr(`transition-rollback failed: ${String(error)}\n`);
+				return 1;
+			}
+		}
+		case "abort-cutover":
+		case "restore-previous": {
+			const transaction = activeCutover(stateDir);
+			if (transaction === null) {
+				io.stderr(`${command} refused: no nonterminal launch cutover is active\n`);
+				return 1;
+			}
+			const watchdogPid = liveWatchdogPid(stateDir);
+			if (watchdogPid === null) {
+				io.stderr(`${command} refused: no live watchdog can consume the durable control request\n`);
+				return 1;
+			}
+			const requested = command === "restore-previous" ? "restore-previous" : "abort";
+			try {
+				const control = writeCutoverControl(stateDir, transaction.receipt.id, requested, Date.now());
+				appendTestLifecycleEvent("control-marker-written", {
+					action: control.action,
+					watchdogPid
+				}, "parent-observer");
+				try {
+					process.kill(watchdogPid, "SIGUSR2");
+					appendTestLifecycleEvent("signal-result", {
+						signal: "SIGUSR2",
+						targetPid: watchdogPid,
+						result: "sent"
+					}, "parent-observer");
+				} catch (error) {
+					appendTestLifecycleEvent("signal-result", {
+						signal: "SIGUSR2",
+						targetPid: watchdogPid,
+						result: String(error)
+					}, "parent-observer");
+					throw error;
+				}
+				io.stdout(control.action === "restore-previous" ? `cutover ${control.cutoverId}: explicit restore-previous requested; watchdog ${watchdogPid} will stop only the proven target identity and relaunch the complete previous spec\n` : `cutover ${control.cutoverId}: abort requested; watchdog ${watchdogPid} will apply the pre-approved ${transaction.receipt.recovery.policy} policy\n`);
+				return 0;
+			} catch (error) {
+				io.stderr(`${command} failed: ${String(error)}\n`);
+				return 1;
+			}
+		}
+		case "cutover-event": {
+			const id = positionals[0];
+			const kind = positionals[1];
+			if (id === void 0 || kind === void 0) {
+				io.stderr("cutover-event requires <id> <kind> [values...]\n");
+				return 2;
+			}
+			try {
+				recordCutoverEvent(stateDir, id, kind, positionals.slice(2), Date.now());
+				return 0;
+			} catch (error) {
+				io.stderr(`cutover-event failed: ${String(error)}\n`);
+				return 1;
+			}
+		}
 		case "clear":
 			clearCredential(stateDir, Date.now());
 			io.stdout("credential cleared\n");
 			return 0;
 		case "checkpoint": {
 			const message = options.message ?? "batch snapshot";
-			const result = commitCheckpoint(repoDir, `dsh-ankh-guard checkpoint: ${message}`, SRC_ARTIFACT_PATTERN);
+			const changes = workingTreeChanges(repoDir);
+			if (options.includeDirty && changes !== null && changes.length > 0) io.stdout(`checkpoint includes ${changes.length} reviewed working-tree change(s)\n`);
+			const result = commitCheckpoint(repoDir, `dsh-ankh-guard checkpoint: ${message}`, SRC_ARTIFACT_PATTERN, options.includeDirty);
 			if (!result.ok) {
 				io.stderr(`${result.error}\n`);
 				return 1;
@@ -807,7 +2577,7 @@ async function runCli(argv, io) {
 				revision: result.sha,
 				message
 			}, Date.now());
-			io.stdout(`checkpoint committed: ${result.sha}\n`);
+			io.stdout(result.createdCommit ? `checkpoint committed: ${result.sha}\n` : `checkpoint recorded at existing clean HEAD: ${result.sha}\n`);
 			if (result.artifacts.length > 0) {
 				io.stdout(`warning: ${result.artifacts.length} build-artifact-looking file(s) swept in (bare tsc emission? real build output belongs in lib/):\n`);
 				for (const file of result.artifacts.slice(0, 5)) io.stdout(`  ${file}\n`);
@@ -830,7 +2600,7 @@ async function runCli(argv, io) {
 			return 0;
 		}
 		case "canary": {
-			const verdict = verifyCredential(loadState(stateDir), currentHead(repoDir), Date.now(), options.maxAgeMinutes);
+			const verdict = verifyRepoCredential(stateDir, repoDir, options.maxAgeMinutes);
 			io.stdout(`verify: ${verdict.ok ? "PASS" : "FAIL"} — ${verdict.reason}\n`);
 			let ok = verdict.ok;
 			if (options.port !== void 0) {
@@ -841,8 +2611,61 @@ async function runCli(argv, io) {
 			io.stdout(ok ? "canary PASS\n" : "canary FAIL\n");
 			return ok ? 0 : 1;
 		}
+		case "verify-restart": {
+			if (restartMarkerState(stateDir) !== "fresh") {
+				io.stderr("restart authorization is missing or stale\n");
+				return 1;
+			}
+			const launch = readLaunchState(stateDir);
+			if (launch === null) {
+				io.stderr("restart authorization cannot be verified without durable launch state\n");
+				return 1;
+			}
+			const spec = selectedLaunchSpec(launch);
+			const marker = readRestartRequestMarker(stateDir);
+			const verdict = marker?.authorization === void 0 ? verifyRepoCredential(stateDir, spec.credentialRepo, options.maxAgeMinutes) : verifyRestartAuthorization(stateDir, spec, marker.authorization);
+			io.stdout(`${verdict.ok ? "restart evidence PASS" : "restart evidence FAIL"} — ${verdict.reason}\n`);
+			return verdict.ok ? 0 : 1;
+		}
+		case "record-proven-deployment": {
+			if (restartMarkerState(stateDir) !== "fresh") {
+				io.stderr("deployment proof refused: restart authorization is missing or stale\n");
+				return 1;
+			}
+			const launch = readLaunchState(stateDir);
+			if (launch === null || launch.mode !== "stable") {
+				io.stderr("deployment proof refused: no stable durable launch specification is selected\n");
+				return 1;
+			}
+			let authorization = readRestartRequestMarker(stateDir)?.authorization;
+			if (authorization === void 0) {
+				const credential = loadState(stateDir).credential;
+				const fresh = verifyRepoCredential(stateDir, launch.active.credentialRepo, options.maxAgeMinutes);
+				if (!fresh.ok || credential === void 0) {
+					io.stderr(`deployment proof refused: ${fresh.reason}\n`);
+					return 1;
+				}
+				authorization = {
+					version: 1,
+					kind: "fresh-credential",
+					revision: credential.revision,
+					evidenceSha256: commandSha256(credential.command)
+				};
+			}
+			const result = proveCurrentDeployment(stateDir, launch.active, authorization);
+			(result.ok ? io.stdout : io.stderr)(`${result.ok ? "deployment proof PASS" : "deployment proof FAIL"} — ${result.reason}\n`);
+			return result.ok ? 0 : 1;
+		}
 		case "preflight": {
-			const outcome = await runPreflightCheck(resolveProfileName(options), options.timeoutMs ?? DEFAULT_PREFLIGHT_TIMEOUT_MS, resolveHarnessRoot(options.repoDir));
+			const harnessRoot = resolveHarnessRoot(options.harnessRoot);
+			let binding;
+			if (options.preflightSurface !== void 0 || options.preflightInstallAnchor !== void 0 || options.preflightRunner !== void 0) try {
+				binding = resolvePreflightSpec(options, "standalone-preflight", harnessRoot, false);
+			} catch (error) {
+				io.stderr(`preflight refused: ${error instanceof Error ? error.message : String(error)}\n`);
+				return 2;
+			}
+			const outcome = await runPreflightCheck(resolveProfileName(options), options.timeoutMs ?? DEFAULT_PREFLIGHT_TIMEOUT_MS, harnessRoot, void 0, binding);
 			if (outcome.kind === "unavailable") {
 				io.stderr("preflight unavailable outside the dsh app layout\n");
 				return 3;
@@ -862,6 +2685,11 @@ async function runCli(argv, io) {
 			io.stdout(written ? "[watchdog] adoption takeover — left a report record for the supervising session\n" : "[watchdog] adoption takeover — a report record is still pending, left it untouched\n");
 			return 0;
 		}
+		case "record-composition-recovery": {
+			const written = writeCompositionRecovery(stateDir, Date.now(), options.detail);
+			io.stdout(written ? "[watchdog] composition rollback recovery — left a report record for the next session\n" : "[watchdog] composition rollback recovery — a report record is still pending, left it untouched\n");
+			return 0;
+		}
 		case "check-env": {
 			const sandboxed = envInternals.sandboxedByProbe();
 			io.stdout(`sandbox: ${sandboxed ? "SANDBOXED — detached processes are reaped when the turn ends; ask the user for /permission danger-full-access in THIS session" : "unsandboxed (full access)"}\n`);
@@ -900,6 +2728,188 @@ async function runCli(argv, io) {
 			io.stdout(`git repo: ${currentHead(repoDir) !== null ? `yes (${repoDir})` : `no (${repoDir}) — git init + initial commit before record`}\n`);
 			return sandboxed ? 1 : 0;
 		}
+		case "reconfigure": {
+			if (options.start === void 0 || options.start === "") {
+				io.stderr(`reconfigure requires --start "CMD"\n\n${USAGE}`);
+				return 2;
+			}
+			if (options.onFailure === void 0) {
+				io.stderr("reconfigure refused: --on-failure restore-previous|wait-for-user is required so recovery is explicitly approved before the old instance stops\n");
+				return 2;
+			}
+			const inFlightCutover = activeCutover(stateDir);
+			if (inFlightCutover !== null) return refuse("cutover-active", `reconfigure refused: launch cutover ${inFlightCutover.receipt.id} is still ${inFlightCutover.receipt.phase}; inspect it with \`launch-status\` and settle/retry that transaction first\n`);
+			const previous = resolvePreviousSpec(stateDir, io);
+			if (previous === void 0) return refuseQuiet("previous-spec", "reconfigure refused: could not resolve the active launch specification (see stderr)", 2);
+			let target = launchSpec({
+				command: options.start,
+				port: options.port ?? previous.port,
+				home: options.home !== "" ? options.home : previous.home,
+				credentialRepo: options.repoDir !== "" ? repoDir : previous.credentialRepo,
+				harnessRoot: options.harnessRoot !== "" ? options.harnessRoot : previous.harnessRoot,
+				profile: options.profile !== void 0 && options.profile !== "" ? options.profile : previous.profile
+			});
+			try {
+				target = {
+					...target,
+					preflight: resolvePreflightSpec(options, target.command, target.harnessRoot, true)
+				};
+			} catch (error) {
+				io.stderr(`reconfigure refused: ${error instanceof Error ? error.message : String(error)}\n`);
+				return 2;
+			}
+			if (target.port !== previous.port) return refuse("port-mismatch", `reconfigure refused: online supervisor handoff keeps one authority and port (${previous.port}); target requested ${target.port}. Move ports as a separately supervised deployment, then cut traffic over.\n`, 2);
+			if (sameLaunchSpec(previous, target)) return refuse("identical", "reconfigure refused: target launch specification is identical to the active specification\n", 2);
+			let transitionPlan;
+			if (options.transitionFile !== void 0) {
+				let raw;
+				try {
+					raw = JSON.parse(readFileSync(resolve(options.transitionFile), "utf8"));
+				} catch (error) {
+					io.stderr(`reconfigure refused: transition plan is unreadable: ${String(error)}\n`);
+					return 2;
+				}
+				try {
+					transitionPlan = validateTransitionPlan(raw, previous.home, stateDir);
+					validateTransitionPlan(raw, target.home, stateDir);
+				} catch (error) {
+					io.stderr(`reconfigure refused: ${String(error)}\n`);
+					return 2;
+				}
+			}
+			const previousSupervisorPid = liveWatchdogPid(stateDir);
+			if (previousSupervisorPid === null) return refuse("unsupervised", "reconfigure refused: no live watchdog owns the old instance. Establish supervision first; an online handoff cannot promise continuity without an old supervisor.\n");
+			const gate = verifyRepoCredential(stateDir, target.credentialRepo, options.maxAgeMinutes);
+			if (!gate.ok) return refuse("credential", `reconfigure refused: ${gate.reason}\n`);
+			if (!sandboxGate("reconfigure", options, io)) return refuseQuiet("sandbox", "reconfigure refused: the environment is sandboxed, so the detached replacement supervisor would be reaped mid-flight");
+			const snapshotStartedAt = Date.now();
+			let snapshot;
+			try {
+				snapshot = transitionPlan === void 0 ? createPreflightSnapshot(target.home) : createTransitionPreflightSnapshot(transitionPlan);
+			} catch (error) {
+				return refuse("preflight-snapshot", `reconfigure refused: could not prepare an isolated${transitionPlan === void 0 ? "" : " transitioned"} home: ${String(error)}\n`);
+			}
+			const snapshotMs = Date.now() - snapshotStartedAt;
+			if (snapshotMs > options.maxAgeMinutes * 6e4 / 2) io.stdout(`note: the isolated-home snapshot took ${Math.round(snapshotMs / 1e3)}s — over half the ${options.maxAgeMinutes}min credential window; re-record the credential immediately before reconfigure, and keep the home slim (top-level scratch/ is excluded from the copy)\n`);
+			try {
+				const timeout = options.preflightTimeoutMs ?? DEFAULT_PREFLIGHT_TIMEOUT_MS;
+				if (!await candidateProbeGate(target, timeout, io, snapshot.home)) return refuseQuiet("preflight", "reconfigure refused: the candidate probe failed (see stderr)");
+				if (!await preflightGate("reconfigure", target.profile, timeout, io, target.harnessRoot, snapshot.home, target.preflight)) return refuseQuiet("preflight", "reconfigure refused: the composition preflight failed (see stderr for the failing entries)");
+				io.stdout(`${transitionPlan === void 0 ? "candidate" : "filesystem transition"} preflight PASS on an isolated copy of the live home\n`);
+			} finally {
+				snapshot.cleanup();
+			}
+			const lock = acquireRestartLock(stateDir);
+			if (!lock.ok) return refuse("lock", `reconfigure refused: a restart is in flight (pid ${lock.holder})\n`);
+			const cutoverId = `${Date.now()}-${process.pid}`;
+			let driverPid;
+			try {
+				if (restartMarkerState(stateDir) === "fresh") return refuse("marker", "reconfigure refused: a scheduled exit is already pending\n");
+				const initiator = resolveInitiator(options.initiator, io);
+				const previousSupervisor = processIdentity(previousSupervisorPid);
+				if (previousSupervisor === null) throw new Error(`could not capture a start identity for watchdog ${previousSupervisorPid}`);
+				const previousOwned = findOwnedListener(previous.port, previousSupervisorPid);
+				if (previousOwned === null) throw new Error(`the listener on :${previous.port} is not uniquely owned by watchdog ${previousSupervisorPid}; refusing a port-inferred takeover`);
+				if (!processIdentityMatches(previousSupervisor)) throw new Error(`watchdog ${previousSupervisorPid} changed while ownership was captured; refusing a recycled-PID takeover`);
+				const transition = transitionPlan === void 0 ? void 0 : prepareTransition(transitionPlan, previous.home, stateDir, cutoverId);
+				prepareLaunchCutover(stateDir, {
+					id: cutoverId,
+					previous,
+					target,
+					recoveryPolicy: options.onFailure,
+					browserHandoff: options.browserHandoff,
+					previousSupervisorPid,
+					previousSupervisorStartToken: previousSupervisor.startToken,
+					previousOwnership: {
+						childPid: previousOwned.child.pid,
+						childStartToken: previousOwned.child.startToken,
+						listenerPid: previousOwned.listener.pid,
+						listenerStartToken: previousOwned.listener.startToken
+					},
+					...transition === void 0 ? {} : { transition },
+					...initiator !== void 0 ? { initiator } : {},
+					now: Date.now()
+				});
+				const logPath = options.log ?? stateFile(stateDir, "watchdogLog");
+				mkdirSync(dirname(logPath), { recursive: true });
+				const driverArgs = [
+					"supervise",
+					"--foreground",
+					"--state-dir",
+					stateDir,
+					"--takeover-from",
+					String(previousSupervisorPid),
+					"--cutover-id",
+					cutoverId,
+					"--delay-ms",
+					String(options.delayMs ?? 5e3),
+					"--supervisor-yield-timeout-ms",
+					String(options.supervisorYieldTimeoutMs ?? 15e3),
+					...initiator !== void 0 ? ["--initiator", initiator] : []
+				];
+				const cutoverDriverEnv = { ...process.env };
+				delete cutoverDriverEnv.DSH_ANKH_VERDICT_FILE;
+				const driver = spawn(process.execPath, cliInvocation(driverArgs), {
+					detached: true,
+					stdio: [
+						"ignore",
+						openSync(logPath, "a"),
+						openSync(logPath, "a")
+					],
+					env: testChildEnv("cutover-supervisor-driver", cutoverDriverEnv, {
+						port: previous.port,
+						tempRoot: stateDir
+					})
+				});
+				registerSpawnedTestProcess(driver, "cutover-supervisor-driver", {
+					port: previous.port,
+					tempRoot: stateDir
+				});
+				driver.unref();
+				driverPid = driver.pid;
+				if (driverPid === void 0) throw new Error("could not detach the replacement supervisor driver");
+				const takeoverDeadline = Date.now() + 15e3;
+				let replacementPid;
+				while (Date.now() < takeoverDeadline) {
+					const receipt = readCutoverReceipt(stateDir);
+					const candidate = receipt?.supervisor.targetPid;
+					const candidateStartToken = receipt?.supervisor.targetStartToken;
+					if (candidate !== void 0 && candidateStartToken !== void 0 && processIdentityMatches({
+						pid: candidate,
+						startToken: candidateStartToken
+					}) && livePidIn(stateFile(stateDir, "watchdogPid")) === String(candidate)) {
+						replacementPid = candidate;
+						break;
+					}
+					try {
+						process.kill(driverPid, 0);
+					} catch {
+						break;
+					}
+					await sleep(100);
+				}
+				if (replacementPid === void 0) throw new Error("replacement watchdog did not claim supervision within 15000 ms");
+				io.stdout(`launch cutover ${cutoverId} prepared: supervisor ${previousSupervisorPid} → ${replacementPid}; the replacement watchdog stops the old child in ${options.delayMs ?? 5e3} ms\nreceipt: ${stateFile(stateDir, "launchCutover")}\n`);
+				return 0;
+			} catch (error) {
+				if (driverPid !== void 0) {
+					try {
+						process.kill(-driverPid, "SIGTERM");
+					} catch {
+						try {
+							process.kill(driverPid, "SIGTERM");
+						} catch {}
+					}
+					await waitForExit(driverPid, 2e3);
+				}
+				try {
+					recordCutoverEvent(stateDir, cutoverId, "prepare-failed", [String(error)], Date.now());
+				} catch {}
+				return refuse("preparation", `reconfigure refused before stopping the old instance: ${String(error)}\n`);
+			} finally {
+				lock.release();
+			}
+		}
 		case "restart": {
 			const port = options.port ?? readInstanceLaunch(stateDir)?.port;
 			if (port === void 0) {
@@ -908,21 +2918,22 @@ async function runCli(argv, io) {
 			}
 			const start = resolveStartCommand(options.start, stateDir, "restart", io, port);
 			if (start === void 0) return 2;
+			const restartCutover = activeCutover(stateDir);
+			if (restartCutover !== null) return refuse("cutover-active", `restart refused: launch cutover ${restartCutover.receipt.id} is ${restartCutover.receipt.phase}; a second stop would violate its recovery policy\n`);
 			const isDriver = process.env.DSH_ANKH_RESTART_DRIVER === "1";
-			const gate = verifyCredential(loadState(stateDir), currentHead(repoDir), Date.now(), options.maxAgeMinutes);
-			if (!gate.ok) {
-				io.stderr(`restart refused: ${gate.reason}\n`);
-				return 1;
-			}
-			if (!sandboxGate("restart", options, io)) return 1;
-			if (!isDriver && !await preflightGate("restart", resolveProfileName(options), options.preflightTimeoutMs ?? DEFAULT_PREFLIGHT_TIMEOUT_MS, io, resolveHarnessRoot(options.repoDir))) return 1;
-			if (restartMarkerState(stateDir) === "fresh") {
-				io.stderr("restart refused: a scheduled exit is still pending (restart-requested.json) — its exit agent would kill the instance this restart starts; wait for it or remove the stale marker\n");
-				return 1;
-			}
+			const gate = verifyRepoCredential(stateDir, repoDir, options.maxAgeMinutes);
+			if (!gate.ok) return refuse("credential", `restart refused: ${gate.reason}\n`);
+			if (!sandboxGate("restart", options, io)) return refuseQuiet("sandbox", "restart refused: the environment is sandboxed, so the detached restart driver would be reaped mid-flight");
+			if (!isDriver && !await preflightGate("restart", resolveProfileName(options), options.preflightTimeoutMs ?? DEFAULT_PREFLIGHT_TIMEOUT_MS, io, preflightHarnessRoot(options, stateDir))) return refuseQuiet("preflight", "restart refused: the composition preflight failed (see stderr for the failing entries)");
+			if (restartMarkerState(stateDir) === "fresh") return refuse("marker", "restart refused: a scheduled exit is still pending (restart-requested.json) — its exit agent would kill the instance this restart starts; wait for it or remove the stale marker\n");
 			if (options.sync !== true && !isDriver) {
 				const logPath = options.log ?? stateFile(stateDir, "restartLog");
 				mkdirSync(dirname(logPath), { recursive: true });
+				const restartDriverEnv = {
+					...process.env,
+					DSH_ANKH_RESTART_DRIVER: "1"
+				};
+				delete restartDriverEnv.DSH_ANKH_VERDICT_FILE;
 				const driver = spawn(process.execPath, cliInvocation(argv), {
 					detached: true,
 					stdio: [
@@ -930,23 +2941,23 @@ async function runCli(argv, io) {
 						openSync(logPath, "a"),
 						openSync(logPath, "a")
 					],
-					env: {
-						...process.env,
-						DSH_ANKH_RESTART_DRIVER: "1"
-					}
+					env: testChildEnv("restart-driver", restartDriverEnv, {
+						port,
+						tempRoot: stateDir
+					})
+				});
+				registerSpawnedTestProcess(driver, "restart-driver", {
+					port,
+					tempRoot: stateDir
 				});
 				driver.unref();
-				if (driver.pid === void 0) {
-					io.stderr("restart refused: could not detach the restart driver\n");
-					return 1;
-				}
+				if (driver.pid === void 0) return refuse("spawn", "restart refused: could not detach the restart driver\n");
 				const lock = acquireRestartLock(stateDir, driver.pid);
 				if (!lock.ok) {
 					try {
 						process.kill(driver.pid, "SIGKILL");
 					} catch {}
-					io.stderr(/^\d+$/.test(lock.holder) ? `restart refused: another restart is already in flight (pid ${lock.holder})\n` : `restart refused: cannot claim the restart lock (${lock.holder}) — remove ${stateFile(stateDir, "restartLock")} if it is stale\n`);
-					return 1;
+					return refuse("lock", /^\d+$/.test(lock.holder) ? `restart refused: another restart is already in flight (pid ${lock.holder})\n` : `restart refused: cannot claim the restart lock (${lock.holder}) — remove ${stateFile(stateDir, "restartLock")} if it is stale\n`);
 				}
 				io.stdout(`restart driver detached (pid ${driver.pid}) — log ${logPath}\nthe instance stops in ${options.delayMs ?? 0} ms and comes back on its own; check the log or \`status\` afterwards\n`);
 				return 0;
@@ -955,7 +2966,7 @@ async function runCli(argv, io) {
 			if (options.sync === true) {
 				const lock = acquireRestartLock(stateDir);
 				if (!lock.ok) {
-					io.stderr(/^\d+$/.test(lock.holder) ? `restart refused: another restart is already in flight (pid ${lock.holder})\n` : `restart refused: cannot claim the restart lock (${lock.holder}) — remove ${stateFile(stateDir, "restartLock")} if it is stale\n`);
+					refuse("lock", /^\d+$/.test(lock.holder) ? `restart refused: another restart is already in flight (pid ${lock.holder})\n` : `restart refused: cannot claim the restart lock (${lock.holder}) — remove ${stateFile(stateDir, "restartLock")} if it is stale\n`);
 					return 1;
 				}
 				restartLock = lock;
@@ -985,12 +2996,21 @@ async function runCli(argv, io) {
 				const stoppedAt = Date.now();
 				const startEnv = { ...process.env };
 				delete startEnv.DSH_ANKH_RESTART_DRIVER;
-				spawn(start, {
+				for (const key of Object.keys(startEnv)) if (key.startsWith("WD_")) delete startEnv[key];
+				const child = spawn(start, {
 					shell: true,
 					detached: true,
 					stdio: "ignore",
-					env: startEnv
-				}).unref();
+					env: testChildEnv("restart-instance-root", startEnv, {
+						port,
+						tempRoot: stateDir
+					})
+				});
+				registerSpawnedTestProcess(child, "restart-instance-root", {
+					port,
+					tempRoot: stateDir
+				});
+				child.unref();
 				io.stdout(`started: ${start}\n`);
 				const timeoutMs = options.timeoutMs ?? 6e4;
 				const deadline = Date.now() + timeoutMs;
@@ -1002,7 +3022,7 @@ async function runCli(argv, io) {
 					}
 					await sleep(500);
 				}
-				const initiator = options.initiator ?? process.env.DSH_SESSION_ID;
+				const initiator = resolveInitiator(options.initiator, io);
 				if (!listening) {
 					io.stderr(`new instance not listening on 127.0.0.1:${port} within ${timeoutMs}ms\n`);
 					writeRestartOutcome(stateDir, {
@@ -1014,7 +3034,7 @@ async function runCli(argv, io) {
 					if (options.rollback) rollbackToKnownGood(stateDir, repoDir, io);
 					return 1;
 				}
-				const post = verifyCredential(loadState(stateDir), currentHead(repoDir), Date.now(), options.maxAgeMinutes);
+				const post = verifyRepoCredential(stateDir, repoDir, options.maxAgeMinutes);
 				io.stdout(`canary verify: ${post.ok ? "PASS" : "FAIL"} — ${post.reason}\n`);
 				io.stdout(`canary port: PASS — listening on 127.0.0.1:${port}\n`);
 				if (!post.ok) {
@@ -1040,27 +3060,28 @@ async function runCli(argv, io) {
 			}
 		}
 		case "supervise": {
-			const port = options.port;
-			if (port === void 0) {
-				io.stderr(`supervise requires --port N and --start "CMD"\n\n${USAGE}`);
-				return 2;
+			let spec = resolveSuperviseSpec(options, stateDir, repoDir, io);
+			if (spec === void 0) return 2;
+			let transaction = activeCutover(stateDir);
+			if (options.cutoverId !== void 0 && (transaction === null || transaction.receipt.id !== options.cutoverId)) {
+				io.stderr(`supervise refused: cutover ${options.cutoverId} is not the selected launch transaction\n`);
+				return 1;
 			}
-			const start = resolveStartCommand(options.start, stateDir, "supervise", io, port);
-			if (start === void 0) return 2;
-			writeInstanceLaunchAsSupervisor(stateDir, {
-				command: start,
-				source: "supervisor",
-				supervised: true,
-				...port !== void 0 ? { port } : {},
-				recordedAt: Date.now()
-			});
-			const wdHome = resolveWdHome(options.home);
-			if (wdHome === void 0) {
-				io.stderr("supervise needs the dsh home: pass --home DIR or set DSH_HOME — the supervised instance reads its profiles/credentials from there, and deriving one from --state-dir would guess wrong\n");
-				return 2;
+			if (options.cutoverId === void 0 && transaction?.receipt.phase === "awaiting-user") {
+				io.stderr(`supervise: cutover ${transaction.receipt.id} is waiting for user action; refusing to restart the rejected target automatically (receipt ${stateFile(stateDir, "launchCutover")})\n`);
+				return 0;
 			}
 			if (options.foreground !== true && !sandboxGate("supervise", options, io)) return 2;
+			if (options.cutoverId !== void 0) try {
+				const driverIdentity = processIdentity(process.pid);
+				if (driverIdentity === null) throw new Error(`could not capture driver ${process.pid} start identity`);
+				recordCutoverEvent(stateDir, options.cutoverId, "driver-started", [String(process.pid), driverIdentity.startToken], Date.now());
+			} catch (error) {
+				io.stderr(`supervise refused: could not persist cutover driver PID: ${String(error)}\n`);
+				return 1;
+			}
 			const pidfile = stateFile(stateDir, "watchdogPid");
+			let waitedForWatchdog = false;
 			if (existsSync(pidfile)) {
 				const existing = readFileSync(pidfile, "utf8").trim();
 				const existingPid = Number(existing);
@@ -1072,24 +3093,61 @@ async function runCli(argv, io) {
 						existingAlive = false;
 					}
 					if (existingAlive) {
-						if (options.foreground) {
-							io.stdout(`watchdog ${existing} already supervises the port — waiting for it to exit, then taking over (foreground)\n`);
-							while (true) {
-								try {
-									process.kill(existingPid, 0);
-								} catch {
-									break;
-								}
-								await sleep(1e3);
+						if (options.takeoverFrom !== void 0) {
+							if (existingPid !== options.takeoverFrom) {
+								io.stderr(`supervise takeover refused: expected watchdog ${options.takeoverFrom}, but pidfile names live ${existingPid}\n`);
+								return 1;
 							}
-							io.stdout(`watchdog ${existing} exited — taking over\n`);
 						} else {
-							io.stdout(`already supervised by pid ${existing}\n`);
-							return 0;
+							const durable = readLaunchState(stateDir);
+							if (options.start !== void 0 && durable !== null && !sameLaunchSpec(spec, selectedLaunchSpec(durable))) {
+								io.stderr("supervise refused: a live watchdog owns a different launch specification; use `reconfigure --on-failure ...` so the supervisor and full config move transactionally\n");
+								return 1;
+							}
+							if (durable === null) writeStableLaunchSpec(stateDir, spec);
+							if (options.foreground) {
+								io.stdout(`watchdog ${existing} already supervises the port — waiting for it to exit, then taking over (foreground)\n`);
+								const existingIdentity = processIdentity(existingPid);
+								if (existingIdentity === null) {
+									io.stderr(`supervise refused: could not capture watchdog ${existingPid} start identity before waiting\n`);
+									return 1;
+								}
+								while (processIdentityMatches(existingIdentity)) await sleep(1e3);
+								waitedForWatchdog = true;
+								io.stdout(`watchdog ${existing} exited — taking over\n`);
+							} else {
+								io.stdout(`already supervised by pid ${existing}\n`);
+								return 0;
+							}
 						}
 					}
 				}
 			}
+			if (waitedForWatchdog) {
+				const refreshed = resolveSuperviseSpec(options, stateDir, repoDir, io, true);
+				if (refreshed === void 0) return 2;
+				spec = refreshed;
+				transaction = activeCutover(stateDir);
+				if (options.cutoverId !== void 0 && (transaction === null || transaction.receipt.id !== options.cutoverId)) {
+					io.stderr(`supervise refused after wait: cutover ${options.cutoverId} is no longer the selected launch transaction\n`);
+					return 1;
+				}
+				if (options.cutoverId === void 0 && transaction?.receipt.phase === "awaiting-user") {
+					io.stderr(`supervise: cutover ${transaction.receipt.id} settled awaiting-user while this supervisor waited; refusing to restart the rejected target (receipt ${stateFile(stateDir, "launchCutover")})\n`);
+					return 0;
+				}
+				io.stdout("launch state refreshed after wait — using the durable selected specification\n");
+			}
+			const previousOwnership = transaction?.receipt.ownership?.previous;
+			if (transaction !== null && (previousOwnership === void 0 || !Number.isInteger(previousOwnership.childPid) || previousOwnership.childPid <= 0 || !Number.isInteger(previousOwnership.listenerPid) || previousOwnership.listenerPid <= 0 || previousOwnership.childStartToken === "" || previousOwnership.listenerStartToken === "")) {
+				io.stderr(`supervise refused: active cutover ${transaction.receipt.id} predates authoritative child/listener ownership evidence; refusing to infer or kill a process by port. Keep the existing host untouched and settle the transaction explicitly.\n`);
+				return 1;
+			}
+			const previousSupervisorStart = transaction?.receipt.supervisor?.previousStartToken;
+			if (transaction !== null && (previousSupervisorStart === void 0 || previousSupervisorStart === "")) {
+				io.stderr(`supervise refused: active cutover ${transaction.receipt.id} predates supervisor start identity evidence; refusing a PID-only takeover. Keep the existing host untouched and settle the transaction explicitly.\n`);
+				return 1;
+			}
 			const watchdog = fileURLToPath(new URL("../scripts/dsh-watchdog.sh", import.meta.url));
 			if (!existsSync(watchdog)) {
 				io.stderr(`watchdog script not found at ${watchdog}\n`);
@@ -1099,23 +3157,67 @@ async function runCli(argv, io) {
 				io.stderr("supervise: --log has no effect with --foreground — output follows the external supervisor's redirection (launchd StandardOutPath / systemd StandardOutput=); drop --log\n");
 				return 2;
 			}
+			if (transaction === null) {
+				writeStableLaunchSpec(stateDir, spec);
+				writeInstanceLaunchAsSupervisor(stateDir, {
+					command: spec.command,
+					source: "supervisor",
+					supervised: true,
+					port: spec.port,
+					recordedAt: Date.now()
+				});
+			}
+			const supervisorBaseEnv = { ...process.env };
+			delete supervisorBaseEnv.DSH_ANKH_VERDICT_FILE;
+			for (const key of Object.keys(supervisorBaseEnv)) if (key.startsWith("WD_")) delete supervisorBaseEnv[key];
 			const env = {
-				...process.env,
-				WD_PORT: String(port),
-				WD_HOME: wdHome,
+				...supervisorBaseEnv,
+				WD_PORT: String(spec.port),
+				WD_HOME: spec.home,
 				WD_STATE_DIR: stateDir,
-				WD_REPO: repoDir,
-				WD_START: start,
+				WD_REPO: spec.credentialRepo,
+				WD_HARNESS_ROOT: spec.harnessRoot,
+				WD_START: spec.command,
 				DSH_ANKH_SUPERVISED: "1",
-				WD_INITIATOR: process.env.DSH_SESSION_ID ?? "",
-				WD_ADOPTION: findPidOnPort(port) !== null ? "1" : "0",
-				WD_WAIT_OWNER: options.foreground ? "0" : "1",
-				WD_GUARD: guardInvocation()
+				WD_INITIATOR: options.initiator ?? process.env.DSH_SESSION_ID ?? "",
+				WD_ADOPTION: transaction === null && findPidOnPort(spec.port) !== null ? "1" : "0",
+				WD_PROFILE: spec.profile,
+				WD_WAIT_OWNER: options.takeoverFrom !== void 0 || !options.foreground ? "1" : "0",
+				WD_GUARD: guardInvocation(),
+				...options.takeoverFrom !== void 0 ? {
+					WD_TAKEOVER_FROM: String(options.takeoverFrom),
+					WD_TAKEOVER_FROM_START: previousSupervisorStart ?? ""
+				} : {},
+				...transaction !== null && previousOwnership !== void 0 ? {
+					WD_CUTOVER_ID: transaction.receipt.id,
+					WD_CUTOVER_ROLE: transaction.state.selected,
+					WD_CUTOVER_POLICY: transaction.receipt.recovery.policy,
+					WD_BROWSER_HANDOFF: transaction.receipt.authentication.browserHandoff === "off" ? "off" : "required",
+					WD_CUTOVER_DELAY_SECONDS: String((options.delayMs ?? 5e3) / 1e3),
+					WD_SUPERVISOR_YIELD_TIMEOUT_MS: String(options.supervisorYieldTimeoutMs ?? 15e3),
+					WD_PREVIOUS_START: transaction.state.previous.command,
+					WD_PREVIOUS_HOME: transaction.state.previous.home,
+					WD_PREVIOUS_REPO: transaction.state.previous.credentialRepo,
+					WD_PREVIOUS_HARNESS_ROOT: transaction.state.previous.harnessRoot,
+					WD_PREVIOUS_PROFILE: transaction.state.previous.profile,
+					WD_PREVIOUS_CHILD_PID: String(previousOwnership.childPid),
+					WD_PREVIOUS_CHILD_START: previousOwnership.childStartToken,
+					WD_PREVIOUS_LISTENER_PID: String(previousOwnership.listenerPid),
+					WD_PREVIOUS_LISTENER_START: previousOwnership.listenerStartToken,
+					...transaction.state.transition === void 0 ? {} : { WD_TRANSITION_PLAN_SHA256: transaction.state.transition.planSha256 }
+				} : {}
 			};
 			if (options.foreground) {
 				const child = spawn("bash", [watchdog, "--supervise"], {
 					stdio: "inherit",
-					env
+					env: testChildEnv("watchdog-foreground", env, {
+						port: spec.port,
+						tempRoot: stateDir
+					})
+				});
+				registerSpawnedTestProcess(child, "watchdog-foreground", {
+					port: spec.port,
+					tempRoot: stateDir
 				});
 				return await new Promise((resolve) => {
 					child.on("exit", (c) => {
@@ -1132,27 +3234,81 @@ async function runCli(argv, io) {
 					openSync(logPath, "a"),
 					openSync(logPath, "a")
 				],
-				env
+				env: testChildEnv("watchdog-detached", env, {
+					port: spec.port,
+					tempRoot: stateDir
+				})
+			});
+			registerSpawnedTestProcess(child, "watchdog-detached", {
+				port: spec.port,
+				tempRoot: stateDir
+			});
+			let spawnError;
+			child.once("error", (error) => {
+				spawnError = error;
 			});
 			child.unref();
-			io.stdout(`watchdog spawned (pid ${child.pid ?? "unknown"}) — supervises :${port}, log ${logPath}\n`);
-			return 0;
+			const spawnedPid = child.pid;
+			if (spawnedPid === void 0) {
+				io.stderr("supervise refused: watchdog process has no pid\n");
+				return 1;
+			}
+			const claimDeadline = Date.now() + 5e3;
+			while (Date.now() < claimDeadline && spawnError === void 0) {
+				if (liveWatchdogPid(stateDir) === spawnedPid) {
+					io.stdout(`watchdog spawned and ready (pid ${spawnedPid}) — supervises :${spec.port}, log ${logPath}\n`);
+					return 0;
+				}
+				try {
+					process.kill(spawnedPid, 0);
+				} catch {
+					break;
+				}
+				await sleep(50);
+			}
+			try {
+				process.kill(-spawnedPid, "SIGTERM");
+			} catch {
+				try {
+					process.kill(spawnedPid, "SIGTERM");
+				} catch {}
+			}
+			io.stderr(`supervise refused: watchdog ${spawnedPid} did not claim ${pidfile} within 5000 ms${spawnError === void 0 ? "" : ` (${String(spawnError)})`}; inspect ${logPath}\n`);
+			return 1;
 		}
 		case "schedule-exit": {
-			const port = options.port ?? readInstanceLaunch(stateDir)?.port;
 			const delayMs = options.delayMs;
-			if (port === void 0 || delayMs === void 0) {
-				io.stderr(`schedule-exit requires --port N and --delay-ms MS\n\n${USAGE}`);
+			if (delayMs === void 0) {
+				io.stderr(`schedule-exit requires --delay-ms MS (and --port N before durable launch configuration exists)\n\n${USAGE}`);
+				return 2;
+			}
+			const scheduledCutover = activeCutover(stateDir);
+			if (scheduledCutover !== null) {
+				io.stderr(`schedule-exit refused: launch cutover ${scheduledCutover.receipt.id} is ${scheduledCutover.receipt.phase}; let that transaction settle before scheduling another stop\n`);
+				return 1;
+			}
+			const durableSpec = stableScheduleSpec(options, stateDir, repoDir, io);
+			if (durableSpec === void 0) return 1;
+			const port = durableSpec?.port ?? options.port ?? readInstanceLaunch(stateDir)?.port;
+			if (port === void 0) {
+				io.stderr(`schedule-exit requires --port N before a durable launch specification exists\n\n${USAGE}`);
 				return 2;
 			}
-			const gate = verifyCredential(loadState(stateDir), currentHead(repoDir), Date.now(), options.maxAgeMinutes);
+			const credentialRepo = durableSpec?.credentialRepo ?? repoDir;
+			const profile = durableSpec?.profile ?? resolveProfileName(options);
+			const harnessRoot = durableSpec?.harnessRoot ?? preflightHarnessRoot(options, stateDir);
+			if (liveWatchdogPid(stateDir) === null) {
+				io.stderr(`schedule-exit refused: no live watchdog owns the instance on :${port}; establish supervision first. A scheduled exit here would leave the service down.\n`);
+				return 1;
+			}
+			const gate = durableSpec === null ? verifyRepoCredential(stateDir, credentialRepo, options.maxAgeMinutes) : verifyRestartEvidence(stateDir, durableSpec, options.maxAgeMinutes);
 			if (!gate.ok) {
 				io.stderr(`schedule-exit refused: ${gate.reason}\n`);
 				return 1;
 			}
+			io.stdout(`restart evidence PASS — ${gate.reason}\n`);
 			if (!sandboxGate("schedule-exit", options, io)) return 1;
-			if (!await preflightGate("schedule-exit", resolveProfileName(options), options.preflightTimeoutMs ?? DEFAULT_PREFLIGHT_TIMEOUT_MS, io, resolveHarnessRoot(options.repoDir))) return 1;
-			if (liveWatchdogPid(stateDir) === null) io.stderr(NO_WATCHDOG_HINT);
+			if (!await preflightGate("schedule-exit", profile, options.preflightTimeoutMs ?? DEFAULT_PREFLIGHT_TIMEOUT_MS, io, harnessRoot, durableSpec?.home, durableSpec?.preflight)) return 1;
 			const lock = acquireRestartLock(stateDir);
 			if (!lock.ok) {
 				io.stderr(`schedule-exit refused: a restart is in flight (pid ${lock.holder}) — the exit agent would kill the instance it is starting\n`);
@@ -1166,11 +3322,12 @@ async function runCli(argv, io) {
 					return 1;
 				}
 				if (markerState === "stale" && existsSync(markerFile)) io.stderr("warning: overwriting a stale restart marker (a previous schedule never completed)\n");
-				const initiator = options.initiator ?? process.env.DSH_SESSION_ID;
+				const initiator = resolveInitiator(options.initiator, io);
 				mkdirSync(stateDir, { recursive: true });
 				writeFileSync(stateFile(stateDir, "restartRequested"), `${JSON.stringify({
 					reason: "scheduled self-restart",
 					requestedAt: Date.now(),
+					...gate.authorization === void 0 ? {} : { authorization: gate.authorization },
 					...initiator !== void 0 ? { initiator } : {}
 				})}\n`);
 				const resultFile = stateFile(stateDir, "lastRestart");
@@ -1183,16 +3340,23 @@ async function runCli(argv, io) {
 						openSync(logPath, "a"),
 						openSync(logPath, "a")
 					],
-					env: {
+					env: testChildEnv("schedule-exit-agent", {
 						...process.env,
 						WD_PORT: String(port),
 						WD_DELAY_MS: String(delayMs),
 						WD_RESULT_FILE: resultFile,
 						...initiator !== void 0 ? { WD_INITIATOR: initiator } : {}
-					}
+					}, {
+						port,
+						tempRoot: stateDir
+					})
+				});
+				registerSpawnedTestProcess(child, "schedule-exit-agent", {
+					port,
+					tempRoot: stateDir
 				});
 				child.unref();
-				io.stdout(`exit scheduled in ${delayMs} ms (agent pid ${child.pid ?? "unknown"}) — watchdog will respawn and run the canary\n`);
+				io.stdout(`exit scheduled in ${delayMs} ms (exit-agent pid ${child.pid ?? "unknown"}) — watchdog will respawn and run the canary\n`);
 				return 0;
 			} finally {
 				lock.release();
@@ -1203,14 +3367,17 @@ async function runCli(argv, io) {
 			return 2;
 	}
 }
-if (isDirectInvocation(import.meta.url)) runCli(process.argv.slice(2), {
-	stdout: (line) => process.stdout.write(line),
-	stderr: (line) => process.stderr.write(line)
-}).then((code) => {
-	process.exitCode = code;
-}).catch((error) => {
-	process.stderr.write(`ankh-guard: ${String(error)}\n`);
-	process.exitCode = 1;
-});
+if (isDirectInvocation(import.meta.url)) {
+	registerCurrentTestProcess();
+	runCli(process.argv.slice(2), {
+		stdout: (line) => process.stdout.write(line),
+		stderr: (line) => process.stderr.write(line)
+	}).then((code) => {
+		process.exitCode = code;
+	}).catch((error) => {
+		process.stderr.write(`ankh-guard: ${String(error)}\n`);
+		process.exitCode = 1;
+	});
+}
 //#endregion
 export { envInternals, parse, preflightInternals, resolveHarnessRoot, resolvePreflightBin, resolveRunnerCommand, resolveWdHome, runCli, runPreflightCheck };