@khorsheed/dsh-ankh-guard 0.1.0 → 0.2.0

package/lib/index.js

@@ -1,15 +1,654 @@
 import { i as resolveStateDir, r as resolveRepoDir, t as SRC_ARTIFACT_PATTERN } from "./defaults-CduvOcGq.js";
-import { a as interruptedSnapshotFile, b as resetToCheckpoint, c as readInterruptedSnapshot, f as writeInstanceLaunch, g as writeSkillRegistration, i as continueInterruptedText, m as writeInterruptedSnapshot, n as buildLaunchCommand, o as pendingRestartRecord, r as continueAndReportText, t as acknowledgeRestartRecord, u as restartContextText, 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, t as clearCredential } from "./state-Dhx9VG44.js";
-import { execFileSync } from "node:child_process";
-import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { M as currentHead, N as isWorkingTreeClean, P as resetToCheckpoint, S as cutoverBlocksWake, a as interruptedSnapshotFile, b as activeCutover, c as readInstanceLaunch, d as restartContextText, g as writeInterruptedSnapshot, i as continueInterruptedText, j as commitCheckpoint, l as readInterruptedSnapshot, m as writeInstanceLaunch, n as buildLaunchCommand, o as isParkedOnUserInput, r as continueAndReportText, s as pendingRestartRecord, t as acknowledgeRestartRecord, v as writeSkillRegistration, w as readCutoverReceipt } from "./restart-context-DUyExi9O.js";
+import { _ as processIdentity, g as listeningPortsForPid, v as processIdentityMatches } from "./test-seam-dwvaKjRp.js";
+import { f as stateFile, i as setCheckpoint, n as loadState, r as recordCredential, s as verifyCredential, t as clearCredential, u as liveWatchdogPid } from "./state-CZMypGkB.js";
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { chmodSync, existsSync, linkSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { connect } from "node:net";
-import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import z from "@deepseek-ai/schemastery";
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
-import { resolveSessionPreset } from "@deepseek-ai/dsh-agent-presets";
+import * as agentPresetsHost from "@deepseek-ai/dsh-agent-presets";
+//#region lib/types/browser-handoff.js
+/**
+* Browser handoff bridge for launch cutovers.
+*
+* Old authenticated pages register random per-tab capabilities while the
+* previous process is still the proven listener. Only SHA-256 digests are
+* durable. After the successor proves one stable listener and passes canary,
+* every registered tab may ask the final process for either a plain reload
+* (its cookie is still valid) or that process's authenticated URL. The URL
+* exists only in the response object and the browser's location.replace call:
+* it never enters a state file, receipt, or log.
+*
+* Alongside the cutover channel, a boot-generation channel covers ordinary
+* restarts (unsupervised `restart`/`schedule-exit`, watchdog crash respawns):
+* the serving process's own pid + start token is its boot id, a polling tab
+* carries the boot id it last saw, and a stale id with no active cutover
+* means the process it knew is gone — answer ready/reload. A cutover receipt
+* always wins over the generation check: during a cutover the old tab's known
+* id is already stale, and the receipt protocol owns the pacing.
+*/
+const BROWSER_HANDOFF_ROUTE = "/_ankh-guard/browser-handoff";
+const CAPABILITY_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+const MAX_BODY_BYTES = 4096;
+const MAX_REGISTRATIONS = 64;
+const DEFAULT_LONG_POLL_MS = 25e3;
+const DEFAULT_LONG_POLL_INTERVAL_MS = 200;
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isCapability(value) {
+	return typeof value === "string" && CAPABILITY_PATTERN.test(value);
+}
+function capabilitySha256(capability) {
+	return createHash("sha256").update(capability).digest("hex");
+}
+function parseMessage(value) {
+	if (!isObject(value) || value.version !== 1) return null;
+	if (value.operation === "poll" && isCapability(value.capability)) {
+		const knownBootId = typeof value.knownBootId === "string" && value.knownBootId.length <= 256 ? value.knownBootId : void 0;
+		return {
+			version: 1,
+			operation: "poll",
+			capability: value.capability,
+			...knownBootId === void 0 ? {} : { knownBootId }
+		};
+	}
+	if (value.operation !== "ack" || typeof value.cutoverId !== "string" || value.cutoverId === "") return null;
+	if (value.channel !== "original-tab" && value.channel !== "fallback-tab") return null;
+	if (value.authentication !== "existing-cookie" && value.authentication !== "launch-url") return null;
+	if (value.channel === "original-tab" && !isCapability(value.capability)) return null;
+	return {
+		version: 1,
+		operation: "ack",
+		cutoverId: value.cutoverId,
+		channel: value.channel,
+		authentication: value.authentication,
+		...typeof value.capability === "string" ? { capability: value.capability } : {}
+	};
+}
+function readJson(file) {
+	try {
+		return JSON.parse(readFileSync(file, "utf8"));
+	} catch {
+		return null;
+	}
+}
+function createJsonOnce(file, value) {
+	mkdirSync(dirname(file), { recursive: true });
+	const tmp = `${file}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+	writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, {
+		mode: 384,
+		flag: "wx"
+	});
+	try {
+		linkSync(tmp, file);
+		try {
+			chmodSync(file, 384);
+		} catch {}
+		return true;
+	} catch (error) {
+		if (error.code === "EEXIST") return false;
+		throw error;
+	} finally {
+		unlinkSync(tmp);
+	}
+}
+function writeJsonAtomic(file, value) {
+	mkdirSync(dirname(file), { recursive: true });
+	const tmp = `${file}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+	writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, {
+		mode: 384,
+		flag: "wx"
+	});
+	try {
+		renameSync(tmp, file);
+		try {
+			chmodSync(file, 384);
+		} catch {}
+	} finally {
+		try {
+			unlinkSync(tmp);
+		} catch {}
+	}
+}
+function validRegistration(value) {
+	return isObject(value) && typeof value.authority === "string" && value.authority !== "" && typeof value.capabilitySha256 === "string" && /^[a-f0-9]{64}$/.test(value.capabilitySha256) && typeof value.armedAt === "number" && Number.isFinite(value.armedAt) && (value.acknowledgedAt === void 0 || typeof value.acknowledgedAt === "number" && Number.isFinite(value.acknowledgedAt));
+}
+function readBrowserHandoffRequest(stateDir) {
+	const request = readJson(stateFile(stateDir, "browserHandoffRequest"));
+	if (request?.version !== 2 || typeof request.cutoverId !== "string" || !Array.isArray(request.registrations) || request.registrations.length === 0 || request.registrations.length > MAX_REGISTRATIONS || !request.registrations.every(validRegistration)) return null;
+	return request;
+}
+function registerBrowserTab(stateDir, cutoverId, registration) {
+	const existing = readBrowserHandoffRequest(stateDir);
+	const registrations = existing?.cutoverId === cutoverId ? [...existing.registrations] : [];
+	if (!registrations.some((item) => item.authority === registration.authority && item.capabilitySha256 === registration.capabilitySha256)) {
+		if (registrations.length >= MAX_REGISTRATIONS) return null;
+		registrations.push(registration);
+	}
+	const request = {
+		version: 2,
+		cutoverId,
+		registrations
+	};
+	writeJsonAtomic(stateFile(stateDir, "browserHandoffRequest"), request);
+	return request;
+}
+function registrationMatches(request, cutoverId, authority, digest) {
+	return request?.cutoverId === cutoverId && request.registrations.some((item) => item.authority === authority && item.capabilitySha256 === digest);
+}
+function matchingRegistration(request, cutoverId, authority, digest) {
+	if (request?.cutoverId !== cutoverId) return void 0;
+	return request.registrations.find((item) => item.authority === authority && item.capabilitySha256 === digest);
+}
+function acknowledgeBrowserTab(stateDir, cutoverId, authority, digest, acknowledgedAt) {
+	const request = readBrowserHandoffRequest(stateDir);
+	const registration = matchingRegistration(request, cutoverId, authority, digest);
+	if (request === null || registration === void 0) return false;
+	registration.acknowledgedAt = acknowledgedAt;
+	writeJsonAtomic(stateFile(stateDir, "browserHandoffRequest"), request);
+	return true;
+}
+function readBrowserHandoffAcknowledgement(stateDir) {
+	const ack = readJson(stateFile(stateDir, "browserHandoffAck"));
+	if (ack?.version !== 1 || typeof ack.cutoverId !== "string" || ack.role !== "target" && ack.role !== "previous" || typeof ack.authority !== "string" || ack.authority === "" || !Number.isInteger(ack.listenerPid) || (ack.listenerPid ?? 0) <= 0 || typeof ack.listenerStartToken !== "string" || ack.listenerStartToken === "" || ack.channel !== "original-tab" && ack.channel !== "fallback-tab" || ack.authentication !== "existing-cookie" && ack.authentication !== "launch-url" || typeof ack.acknowledgedAt !== "number") return null;
+	return ack;
+}
+function authorityOf(req) {
+	const host = req.headers.host;
+	const origin = req.headers.origin;
+	if (typeof host !== "string" || typeof origin !== "string") return null;
+	try {
+		const parsed = new URL(origin);
+		if (parsed.protocol !== "http:" && parsed.protocol !== "https:" || parsed.host !== host || parsed.origin !== origin) return null;
+		return {
+			authority: parsed.host,
+			origin: parsed.origin
+		};
+	} catch {
+		return null;
+	}
+}
+function ownershipMatches(ownership, pid, identityMatches) {
+	return ownership !== void 0 && ownership.listenerPid === pid && identityMatches({
+		pid,
+		startToken: ownership.listenerStartToken
+	});
+}
+function json(res, status, body) {
+	res.writeHead(status, {
+		"cache-control": "no-store",
+		"content-type": "application/json; charset=utf-8",
+		"referrer-policy": "no-referrer",
+		"x-content-type-options": "nosniff"
+	});
+	res.end(`${JSON.stringify(body)}\n`);
+}
+async function bodyOf(req) {
+	let size = 0;
+	const chunks = [];
+	for await (const chunk of req) {
+		const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+		size += bytes.byteLength;
+		if (size > MAX_BODY_BYTES) throw new Error("body too large");
+		chunks.push(bytes);
+	}
+	return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+function currentReadyOwnership(stateDir, pid, identityMatches) {
+	const receipt = readCutoverReceipt(stateDir);
+	if (receipt === null || receipt.phase === "awaiting-user" || receipt.readiness?.retryCount !== 0) return null;
+	const role = receipt.readiness.role;
+	const ownership = role === "target" ? receipt.ownership.target : receipt.ownership.restored;
+	const canarySettled = role === "target" ? receipt.targetValidation?.canary?.outcome === "pass" : receipt.recovery.validation?.canary !== void 0;
+	if (!ownershipMatches(ownership, pid, identityMatches) || !canarySettled || receipt.readiness.listenerPid !== ownership.listenerPid || receipt.readiness.childPid !== ownership.childPid) return null;
+	return {
+		cutoverId: receipt.id,
+		role,
+		ownership,
+		protected: receipt.authentication.launchUrlObserved === true
+	};
+}
+function delay(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function waitForPollState(ready, waitMs, intervalMs) {
+	if (ready() || waitMs <= 0) return;
+	const deadline = Date.now() + waitMs;
+	while (Date.now() < deadline) {
+		await delay(Math.min(intervalMs, Math.max(1, deadline - Date.now())));
+		if (ready()) return;
+	}
+}
+function authenticationState(connection, req) {
+	if (connection?.requestRejection === void 0) return "legacy-public";
+	const rejection = connection.requestRejection(req);
+	if (rejection === void 0) return "authenticated";
+	return rejection === 403 ? "forbidden" : "unauthenticated";
+}
+/** Create the exact HTTP handler; dependencies are injectable for deterministic protocol tests. */
+function createBrowserHandoffHandler(dependencies) {
+	const pid = dependencies.pid ?? process.pid;
+	const now = dependencies.now ?? Date.now;
+	const identityMatches = dependencies.identityMatches ?? processIdentityMatches;
+	const identityProvider = dependencies.identityProvider ?? processIdentity;
+	const longPollMs = dependencies.longPollMs ?? DEFAULT_LONG_POLL_MS;
+	const longPollIntervalMs = dependencies.longPollIntervalMs ?? DEFAULT_LONG_POLL_INTERVAL_MS;
+	let bootIdCache;
+	const thisBootId = () => {
+		if (bootIdCache === void 0) {
+			const identity = identityProvider(pid);
+			bootIdCache = identity === null ? null : `${String(identity.pid)}:${identity.startToken}`;
+		}
+		return bootIdCache ?? void 0;
+	};
+	return async (req, res) => {
+		const connection = dependencies.connectionProvider?.() ?? dependencies.connection;
+		if (req.method !== "POST" || req.headers["content-type"]?.split(";", 1)[0]?.trim().toLowerCase() !== "application/json") {
+			json(res, 404, { state: "unavailable" });
+			return;
+		}
+		const requestAuthority = authorityOf(req);
+		if (requestAuthority === null) {
+			json(res, 403, { state: "forbidden" });
+			return;
+		}
+		let message;
+		try {
+			message = parseMessage(await bodyOf(req));
+		} catch {
+			message = null;
+		}
+		if (message === null) {
+			json(res, 400, { state: "invalid" });
+			return;
+		}
+		if (message.operation === "poll") {
+			const digest = capabilitySha256(message.capability);
+			const bootId = thisBootId();
+			const respond = (status, body) => {
+				json(res, status, bootId === void 0 ? body : {
+					...body,
+					bootId
+				});
+			};
+			if (bootId !== void 0 && message.knownBootId !== void 0 && message.knownBootId !== bootId && activeCutover(dependencies.stateDir) === null) {
+				respond(200, {
+					state: "ready",
+					action: "reload",
+					authentication: "existing-cookie"
+				});
+				return;
+			}
+			const pollHasState = () => {
+				const active = activeCutover(dependencies.stateDir);
+				if (active !== null) {
+					if (active.receipt.phase === "awaiting-user" || active.receipt.browserHandoff.status === "off") return true;
+					if (ownershipMatches(active.receipt.ownership.previous, pid, identityMatches)) return !registrationMatches(readBrowserHandoffRequest(dependencies.stateDir), active.receipt.id, requestAuthority.authority, digest);
+					return currentReadyOwnership(dependencies.stateDir, pid, identityMatches) !== null;
+				}
+				const ready = currentReadyOwnership(dependencies.stateDir, pid, identityMatches);
+				const registration = readBrowserHandoffRequest(dependencies.stateDir);
+				return ready !== null && matchingRegistration(registration, ready.cutoverId, requestAuthority.authority, digest)?.acknowledgedAt === void 0;
+			};
+			await waitForPollState(pollHasState, longPollMs, longPollIntervalMs);
+			const active = activeCutover(dependencies.stateDir);
+			const ready = currentReadyOwnership(dependencies.stateDir, pid, identityMatches);
+			const registration = readBrowserHandoffRequest(dependencies.stateDir);
+			const registered = ready === null ? void 0 : matchingRegistration(registration, ready.cutoverId, requestAuthority.authority, digest);
+			if (registered?.acknowledgedAt !== void 0 || active === null && (ready === null || registered === void 0) || active?.receipt.phase === "awaiting-user" || active?.receipt.browserHandoff.status === "off") {
+				respond(200, { state: "idle" });
+				return;
+			}
+			const previous = active?.receipt.ownership.previous;
+			if (active !== null && ownershipMatches(previous, pid, identityMatches)) {
+				const oldAuthentication = authenticationState(connection, req);
+				if (oldAuthentication === "unauthenticated" || oldAuthentication === "forbidden") {
+					json(res, 401, { state: "unauthorized" });
+					return;
+				}
+				const registration = {
+					authority: requestAuthority.authority,
+					capabilitySha256: digest,
+					armedAt: now()
+				};
+				respond(200, registrationMatches(registerBrowserTab(dependencies.stateDir, active.receipt.id, registration), active.receipt.id, requestAuthority.authority, digest) ? {
+					state: "waiting",
+					cutoverId: active.receipt.id
+				} : {
+					state: "standby",
+					cutoverId: active.receipt.id
+				});
+				return;
+			}
+			if (ready === null || active !== null && ready.cutoverId !== active.receipt.id || !registrationMatches(registration, ready?.cutoverId ?? "", requestAuthority.authority, digest)) {
+				respond(200, active === null ? { state: "idle" } : {
+					state: "waiting",
+					cutoverId: active.receipt.id
+				});
+				return;
+			}
+			if (ready.protected && connection?.requestRejection === void 0) {
+				respond(200, {
+					state: "waiting",
+					cutoverId: ready.cutoverId
+				});
+				return;
+			}
+			const cookieState = authenticationState(connection, req);
+			if (cookieState === "forbidden") {
+				json(res, 403, { state: "forbidden" });
+				return;
+			}
+			if (cookieState !== "unauthenticated") {
+				respond(200, {
+					state: "ready",
+					action: "reload",
+					cutoverId: ready.cutoverId,
+					role: ready.role,
+					authentication: "existing-cookie"
+				});
+				return;
+			}
+			if (connection?.authenticatedUrl === void 0) {
+				respond(200, {
+					state: "waiting",
+					cutoverId: ready.cutoverId
+				});
+				return;
+			}
+			let launchUrl;
+			try {
+				launchUrl = connection.authenticatedUrl(requestAuthority.origin);
+			} catch {
+				json(res, 500, { state: "unavailable" });
+				return;
+			}
+			let safe = false;
+			try {
+				const parsed = new URL(launchUrl);
+				safe = parsed.origin === requestAuthority.origin && parsed.pathname === "/" && parsed.username === "" && parsed.password === "" && parsed.search !== "" && parsed.hash === "";
+			} catch {}
+			if (!safe) {
+				json(res, 500, { state: "unavailable" });
+				return;
+			}
+			respond(200, {
+				state: "ready",
+				action: "replace",
+				cutoverId: ready.cutoverId,
+				role: ready.role,
+				authentication: "launch-url",
+				launchUrl
+			});
+			return;
+		}
+		const receipt = readCutoverReceipt(dependencies.stateDir);
+		if (receipt === null || receipt.id !== message.cutoverId) {
+			json(res, 409, { state: "stale" });
+			return;
+		}
+		const ready = currentReadyOwnership(dependencies.stateDir, pid, identityMatches);
+		if (ready === null || ready.cutoverId !== message.cutoverId) {
+			json(res, 409, { state: "waiting" });
+			return;
+		}
+		if (ready.protected && connection?.requestRejection === void 0) {
+			json(res, 409, { state: "waiting" });
+			return;
+		}
+		const ackAuthentication = authenticationState(connection, req);
+		if (ackAuthentication === "unauthenticated" || ackAuthentication === "forbidden") {
+			json(res, ackAuthentication === "forbidden" ? 403 : 401, { state: ackAuthentication === "forbidden" ? "forbidden" : "unauthorized" });
+			return;
+		}
+		const acknowledgedAt = now();
+		if (message.channel === "original-tab") {
+			const registration = readBrowserHandoffRequest(dependencies.stateDir);
+			if (message.capability === void 0 || !registrationMatches(registration, message.cutoverId, requestAuthority.authority, capabilitySha256(message.capability))) {
+				json(res, 403, { state: "forbidden" });
+				return;
+			}
+			if (!acknowledgeBrowserTab(dependencies.stateDir, message.cutoverId, requestAuthority.authority, capabilitySha256(message.capability), acknowledgedAt)) {
+				json(res, 409, { state: "conflict" });
+				return;
+			}
+		}
+		const acknowledgement = {
+			version: 1,
+			cutoverId: message.cutoverId,
+			role: ready.role,
+			authority: requestAuthority.authority,
+			listenerPid: ready.ownership.listenerPid,
+			listenerStartToken: ready.ownership.listenerStartToken,
+			channel: message.channel,
+			authentication: message.authentication,
+			acknowledgedAt
+		};
+		if (!createJsonOnce(stateFile(dependencies.stateDir, "browserHandoffAck"), acknowledgement)) {
+			const existing = readBrowserHandoffAcknowledgement(dependencies.stateDir);
+			if (existing?.cutoverId !== acknowledgement.cutoverId || existing.listenerPid !== acknowledgement.listenerPid || existing.listenerStartToken !== acknowledgement.listenerStartToken) {
+				json(res, 409, { state: "conflict" });
+				return;
+			}
+		}
+		res.writeHead(204, { "cache-control": "no-store" });
+		res.end();
+	};
+}
+/** Register the optional Web-profile bridge; headless/TUI compositions simply never activate it. */
+function registerBrowserHandoff(ctx, stateDir) {
+	ctx.inject(["webServer"], (webCtx) => {
+		const webServer = webCtx.get("webServer");
+		if (webServer === void 0) return;
+		const handler = createBrowserHandoffHandler({
+			stateDir,
+			connectionProvider: () => webCtx.get("connection")
+		});
+		webCtx.effect(() => webServer.register({
+			kind: "exact",
+			path: BROWSER_HANDOFF_ROUTE,
+			handler
+		}), "ankh-guard: browser handoff route");
+	});
+}
+//#endregion
+//#region lib/types/restart-request.js
+/**
+* In-process guarded-restart trigger for UI-grade callers (the mode
+* switcher's host half). Dispatches on supervision — no live watchdog: the
+* `restart` verb's self-contained stop→start→canary; supervised:
+* `reconfigure`'s transactional cutover, the only safe way to change the
+* launch command under a live watchdog (its respawn would otherwise fight
+* the new command). The trigger shells out to this package's own CLI, so
+* the gate chain (credential → preflight → marker/lock) keeps exactly one
+* behavior source and the detached driver keeps its proven lifetime rules;
+* the structured verdict returns through DSH_ANKH_VERDICT_FILE, never
+* scraped from the human stderr text.
+*
+* Never import the CLI module from the plugin graph: a runtime edge pulls
+* cli.ts into a shared tsdown chunk, evicting its code from lib/cli.js so
+* the direct-invocation guard never fires and the built CLI silently exits
+* 0 on every call (observed 2026-09-09; type-only imports are erased and
+* stay safe).
+*/
+/** Bounded human detail carried alongside the structured verdict, for display. */
+const DETAIL_CAP = 4096;
+/**
+* argv (after process.execPath) that runs this package's CLI with the given
+* args — the same source/built split as the CLI's own cliInvocation, resolved
+* from this module's directory (src/ and lib/ keep their entries side by
+* side). The two copies must not be unified through an import: see the module
+* doc for what a runtime edge into the CLI module does to the built bundle.
+*/
+function cliEntryArgs(args) {
+	const modulePath = fileURLToPath(import.meta.url);
+	const here = dirname(modulePath);
+	if (modulePath.includes(`${sep}src${sep}`)) {
+		const tsx = join(resolve(here, "../../../node_modules"), "tsx", "dist", "esm", "index.mjs");
+		if (existsSync(tsx)) return [
+			"--import",
+			tsx,
+			join(here, "cli.ts"),
+			...args
+		];
+		return [join(here, "cli.ts"), ...args];
+	}
+	return [join(here, "cli.js"), ...args];
+}
+/** Read the caller-side verdict file, or null when the CLI never wrote one. */
+function readVerdict(file) {
+	try {
+		const value = JSON.parse(readFileSync(file, "utf8"));
+		return typeof value.stage === "string" && typeof value.reason === "string" ? {
+			stage: value.stage,
+			reason: value.reason
+		} : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Validate and dispatch one restart request through the guard's own gate
+* chain. A refusal never stops the running instance.
+* @param request - the successor command, target profile, and owning session.
+* @param context - the guard's resolved state dir and credential repo.
+* @returns the structured verdict with bounded human detail for display.
+*/
+async function requestRestart(request, context) {
+	if (request.start.trim() === "") return {
+		accepted: false,
+		stage: "usage",
+		reason: "start (the successor launch command) is required",
+		detail: ""
+	};
+	if (request.profile.trim() === "") return {
+		accepted: false,
+		stage: "usage",
+		reason: "profile (the dsh profile to preflight) is required",
+		detail: ""
+	};
+	if (request.initiator.trim() === "") return {
+		accepted: false,
+		stage: "usage",
+		reason: "initiator (the session id the restart report returns to) is required — never invent one",
+		detail: ""
+	};
+	const port = readInstanceLaunch(context.stateDir)?.port;
+	if (port === void 0) return {
+		accepted: false,
+		stage: "usage",
+		reason: "no instance launch record in the state dir — the guard does not know this instance's port",
+		detail: ""
+	};
+	const via = liveWatchdogPid(context.stateDir) === null ? "restart" : "reconfigure";
+	const argv = via === "restart" ? [
+		"restart",
+		"--port",
+		String(port),
+		"--start",
+		request.start,
+		"--profile",
+		request.profile,
+		"--initiator",
+		request.initiator,
+		"--state-dir",
+		context.stateDir,
+		"--repo",
+		context.repoDir
+	] : [
+		"reconfigure",
+		"--start",
+		request.start,
+		"--profile",
+		request.profile,
+		"--on-failure",
+		"restore-previous",
+		"--initiator",
+		request.initiator,
+		"--state-dir",
+		context.stateDir
+	];
+	const verdictDir = mkdtempSync(join(tmpdir(), "ankh-restart-request-"));
+	const verdictFile = join(verdictDir, "verdict.json");
+	const env = {
+		...process.env,
+		DSH_ANKH_VERDICT_FILE: verdictFile
+	};
+	delete env.DSH_ANKH_RESTART_DRIVER;
+	for (const key of Object.keys(env)) if (key.startsWith("WD_")) delete env[key];
+	try {
+		const { code, output } = await new Promise((resolvePromise, rejectPromise) => {
+			let captured = "";
+			const child = spawn(process.execPath, cliEntryArgs(argv), {
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				],
+				env
+			});
+			const append = (chunk) => {
+				if (captured.length < DETAIL_CAP) captured += chunk.toString("utf8");
+			};
+			child.stdout.on("data", append);
+			child.stderr.on("data", append);
+			child.once("error", rejectPromise);
+			child.once("exit", (exitCode) => {
+				resolvePromise({
+					code: exitCode,
+					output: captured
+				});
+			});
+		});
+		const detail = output.trim();
+		if (code === 0) return {
+			accepted: true,
+			via,
+			detail
+		};
+		const verdict = readVerdict(verdictFile);
+		return {
+			accepted: false,
+			stage: verdict?.stage ?? "unknown",
+			reason: verdict?.reason ?? detail.split("\n", 1)[0] ?? `guard CLI exited ${code ?? "signal"}`,
+			detail
+		};
+	} finally {
+		rmSync(verdictDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+//#endregion
 //#region lib/types/index.js
+/**
+* Which preset a session actually runs, newest selection winning. The rc host
+* exports `resolveSessionPreset` for exactly this fold; the 0.1.2 host
+* replaced it with `agentPresetProjectionDefinition` (init from the header,
+* fold `agent-preset/selected` events) — same semantics, so the derivation
+* feature-detects either surface and never touches the version string. A host
+* with neither yields undefined: the resume falls back to the deployment's
+* default preset, the same outcome a preset-less session had before.
+* @param host - the agent-presets module namespace, structurally probed.
+* @param session - the session's header and event log.
+* @returns the preset id, or `undefined` when the session names none.
+*/
+function deriveSessionPreset(host, session) {
+	if (host.agentPresetProjectionDefinition !== void 0) {
+		const projection = host.agentPresetProjectionDefinition;
+		let state = projection.init(session.header);
+		for (const event of session.events) state = projection.apply(state, event);
+		return state ?? void 0;
+	}
+	return host.resolveSessionPreset?.(session);
+}
 const Config = z.object({
 	maxAgeMinutes: z.natural().min(1).default(10),
 	stateDir: z.string().default(""),
@@ -68,7 +707,9 @@ function registerRestartSkill(ctx, stateDir) {
 		ctx.effect(() => skills.register({
 			name,
 			description,
-			content
+			content,
+			source: "runtime",
+			provider: "ankh-guard"
 		}));
 		writeSkillRegistration(stateDir, {
 			registered: true,
@@ -120,6 +761,7 @@ function apply(ctx, config) {
 	const resumeMaxSnapshotAgeMs = config.resumeMaxSnapshotAgeMs ?? 6e5;
 	const followupReport = reportMode === "followup";
 	registerRestartSkill(ctx, stateDir);
+	registerBrowserHandoff(ctx, stateDir);
 	if (followupReport || resumeInterrupted) {
 		const pluginMessage = (text) => createUserMessage({
 			content: [{
@@ -141,6 +783,24 @@ function apply(ctx, config) {
 		ctx.effect(() => () => {
 			disposed = true;
 		});
+		const parkedMemo = /* @__PURE__ */ new Map();
+		const checkParked = (id) => {
+			let probe = parkedMemo.get(id);
+			if (probe === void 0) {
+				probe = (async () => {
+					try {
+						const persistence = ctx.get("sessionPersistence");
+						if (persistence === void 0) return false;
+						const { events } = await persistence.inspect(id);
+						return isParkedOnUserInput(events);
+					} catch {
+						return false;
+					}
+				})();
+				parkedMemo.set(id, probe);
+			}
+			return probe;
+		};
 		const claim = (agent, record) => {
 			const canaryPending = existsSync(stateFile(stateDir, "restartRequested"));
 			const text = restartContextText(record, canaryPending);
@@ -149,22 +809,39 @@ function apply(ctx, config) {
 			acknowledgeRestartRecord(stateDir, record, Date.now());
 		};
 		const deliver = (agent) => {
+			if (cutoverBlocksWake(stateDir)) return;
 			const id = agent.id;
 			const exitAt = pendingContinue.get(id);
 			const record = followupReport ? pendingRestartRecord(stateDir) : null;
-			if (exitAt !== void 0 && record !== null && (record.initiator === void 0 || id === record.initiator)) {
-				const canaryPending = existsSync(stateFile(stateDir, "restartRequested"));
-				const text = continueAndReportText(record, canaryPending);
-				if (text !== "") {
-					agent.followup(pluginMessage(text));
-					pendingContinue.delete(id);
-					acknowledgeRestartRecord(stateDir, record, Date.now());
-					return;
-				}
-			}
+			const owesReport = record !== null && (record.initiator === void 0 || id === record.initiator);
 			if (exitAt !== void 0) {
-				agent.followup(pluginMessage(continueInterruptedText(exitAt)));
-				pendingContinue.delete(id);
+				(async () => {
+					const parked = await checkParked(id);
+					if (disposed || pendingContinue.get(id) !== exitAt) return;
+					pendingContinue.delete(id);
+					if (parked) {
+						if (owesReport && record !== null) claim(agent, record);
+						return;
+					}
+					if (owesReport && record !== null) {
+						const canaryPending = existsSync(stateFile(stateDir, "restartRequested"));
+						const text = continueAndReportText(record, canaryPending);
+						if (text !== "") try {
+							agent.followup(pluginMessage(text));
+							acknowledgeRestartRecord(stateDir, record, Date.now());
+							return;
+						} catch {
+							pendingContinue.set(id, exitAt);
+							return;
+						}
+					}
+					try {
+						agent.followup(pluginMessage(continueInterruptedText(exitAt)));
+					} catch {
+						pendingContinue.set(id, exitAt);
+					}
+				})();
+				return;
 			}
 			if (record === null) return;
 			if (record.initiator !== void 0 && id !== record.initiator) return;
@@ -202,7 +879,7 @@ function apply(ctx, config) {
 			const persistence = ctx.get("sessionPersistence");
 			if (presets !== void 0 && persistence !== void 0) {
 				const inspected = await persistence.inspect(id);
-				const presetId = resolveSessionPreset({
+				const presetId = deriveSessionPreset(agentPresetsHost, {
 					header: inspected.meta,
 					events: inspected.events
 				});
@@ -221,10 +898,16 @@ function apply(ctx, config) {
 			if (snapshot !== null && Date.now() - snapshot.exitAt <= resumeMaxSnapshotAgeMs) for (const id of snapshot.interrupted) pendingContinue.set(id, snapshot.exitAt);
 		}
 		const resumePass = async () => {
+			while (!disposed && cutoverBlocksWake(stateDir)) await new Promise((resolve) => setTimeout(resolve, 250));
+			if (disposed) return;
 			const snapshot = readInterruptedSnapshot(stateDir);
 			if (snapshot === null) return;
 			if (Date.now() - snapshot.exitAt <= resumeMaxSnapshotAgeMs) for (const id of [.../* @__PURE__ */ new Set([...snapshot.resume, ...snapshot.interrupted])]) {
 				if (disposed) return;
+				if (await checkParked(id)) {
+					pendingContinue.delete(id);
+					continue;
+				}
 				const live = ctx.agents.list().find((agent) => agent.id === id);
 				if (live !== void 0) {
 					deliver(live);
@@ -249,6 +932,16 @@ function apply(ctx, config) {
 				clearTimeout(timer);
 			});
 		}
+		if (cutoverBlocksWake(stateDir)) {
+			const releaseTimer = setInterval(() => {
+				if (disposed || cutoverBlocksWake(stateDir)) return;
+				clearInterval(releaseTimer);
+				for (const agent of ctx.agents.roots()) deliver(agent);
+			}, 250);
+			ctx.effect(() => () => {
+				clearInterval(releaseTimer);
+			});
+		}
 		ctx.on("agent/created", ({ agent }) => {
 			if (!ctx.agents.roots().includes(agent)) return;
 			deliver(agent);
@@ -259,6 +952,7 @@ function apply(ctx, config) {
 		if (decision.kind === "reject" || signal.aborted) return decision;
 		const record = pendingRestartRecord(stateDir);
 		if (record === null) return decision;
+		if (cutoverBlocksWake(stateDir)) return decision;
 		const canaryPending = existsSync(stateFile(stateDir, "restartRequested"));
 		const text = restartContextText(record, canaryPending);
 		if (text === "") return decision;
@@ -283,10 +977,11 @@ function apply(ctx, config) {
 		};
 	}, { prepend: true });
 	const service = {
-		verify: () => verifyCredential(loadState(stateDir), currentHead(repoDir), Date.now(), maxAgeMinutes),
+		verify: () => verifyCredential(loadState(stateDir), currentHead(repoDir), Date.now(), maxAgeMinutes, isWorkingTreeClean(repoDir)),
 		record: (scope, options) => {
 			const head = currentHead(repoDir);
 			if (head === null) throw new Error("ankh-guard: cannot record a credential outside a git repository");
+			if (!isWorkingTreeClean(repoDir)) throw new Error("ankh-guard: cannot record a credential while the working tree is dirty");
 			return recordCredential(stateDir, {
 				scope,
 				revision: head,
@@ -305,6 +1000,10 @@ function apply(ctx, config) {
 			return result;
 		},
 		reset: (sha) => resetToCheckpoint(repoDir, sha),
+		requestRestart: (request) => requestRestart(request, {
+			stateDir,
+			repoDir
+		}),
 		canary: async (options) => {
 			const checks = [];
 			const verdict = service.verify();
@@ -332,22 +1031,7 @@ function apply(ctx, config) {
 		try {
 			const env = {};
 			for (const [key, value] of Object.entries(process.env)) if (key.startsWith("DSH_") && value !== void 0) env[key] = value;
-			let port;
-			try {
-				const out = execFileSync("lsof", [
-					"-a",
-					"-p",
-					String(process.pid),
-					"-iTCP",
-					"-sTCP:LISTEN",
-					"-P"
-				], {
-					encoding: "utf8",
-					stdio: "pipe"
-				});
-				const match = /:(\d+) \(LISTEN\)/.exec(out);
-				if (match !== null) port = Number(match[1]);
-			} catch {}
+			const port = listeningPortsForPid(process.pid)[0];
 			writeInstanceLaunch(stateDir, {
 				command: buildLaunchCommand(process.execPath, process.execArgv, process.argv.slice(1), process.cwd(), env),
 				source: "instance",
@@ -359,4 +1043,4 @@ function apply(ctx, config) {
 	})();
 }
 //#endregion
-export { Config, apply, inject, name };
+export { Config, apply, deriveSessionPreset, inject, name };