@gajae-code/coding-agent 0.11.0 → 0.11.2

package/src/commands/mcp-serve.ts

@@ -1,3 +1,4 @@
+import { getAgentDir } from "@gajae-code/utils";
 import { Args, Command, Flags } from "@gajae-code/utils/cli";
 import {
 	COORDINATOR_MCP_PROTOCOL_VERSION,
@@ -5,12 +6,88 @@ import {
 	COORDINATOR_MCP_TOOL_NAMES,
 } from "../coordinator/contract";
 import { runCoordinatorMcpStdio } from "../coordinator-mcp/server";
+import { type BrokerDiscovery, readBrokerDiscovery } from "../sdk/broker/discovery";
+import { UnsupportedStateVersionError } from "../sdk/broker/state-version";
 import { runSdkMcpStdio, SDK_MCP_TOOL_NAMES } from "../sdk/mcp/server";
 
 function writeJson(value: unknown): void {
 	process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
 
+export type CoordinatorBrokerDiscoveryStatus = "ready" | "unavailable" | "error";
+export type CoordinatorBrokerDiscoveryReason =
+	| null
+	| "absent_or_invalid"
+	| "unsupported_state_version"
+	| "discovery_access_denied"
+	| "discovery_read_failed";
+
+export interface CoordinatorBrokerObservation {
+	discovery_status: CoordinatorBrokerDiscoveryStatus;
+	reason: CoordinatorBrokerDiscoveryReason;
+}
+
+export interface CoordinatorCheckProbe {
+	agentDir?: string;
+	readBrokerDiscovery?: (agentDir: string) => Promise<BrokerDiscovery | null>;
+}
+
+export interface CoordinatorCheckPayload {
+	ok: true;
+	server: { name: typeof COORDINATOR_MCP_SERVER_NAME; protocolVersion: typeof COORDINATOR_MCP_PROTOCOL_VERSION };
+	readOnly: true;
+	tools: readonly string[];
+	catalog: { ready: true; reason: null };
+	broker: CoordinatorBrokerObservation & {
+		operational_ready: null;
+		bootstrap_supported: true;
+		bootstrap_attempted: false;
+	};
+}
+
+function discoveryErrorCode(error: unknown): unknown {
+	if (typeof error !== "object" || error === null || !("code" in error)) return undefined;
+	return error.code;
+}
+
+export async function probeCoordinatorBrokerCheck(
+	probe: CoordinatorCheckProbe = {},
+): Promise<CoordinatorBrokerObservation> {
+	try {
+		const discovery = await (probe.readBrokerDiscovery ?? readBrokerDiscovery)(probe.agentDir ?? getAgentDir());
+		return discovery
+			? { discovery_status: "ready", reason: null }
+			: { discovery_status: "unavailable", reason: "absent_or_invalid" };
+	} catch (error) {
+		if (error instanceof UnsupportedStateVersionError)
+			return { discovery_status: "error", reason: "unsupported_state_version" };
+		const code = discoveryErrorCode(error);
+		if (code === "EACCES" || code === "EPERM")
+			return { discovery_status: "error", reason: "discovery_access_denied" };
+		return { discovery_status: "error", reason: "discovery_read_failed" };
+	}
+}
+
+export function formatCoordinatorCheckPayload(observation: CoordinatorBrokerObservation): CoordinatorCheckPayload {
+	return {
+		ok: true,
+		server: { name: COORDINATOR_MCP_SERVER_NAME, protocolVersion: COORDINATOR_MCP_PROTOCOL_VERSION },
+		readOnly: true,
+		tools: [...COORDINATOR_MCP_TOOL_NAMES],
+		catalog: { ready: true, reason: null },
+		broker: {
+			...observation,
+			operational_ready: null,
+			bootstrap_supported: true,
+			bootstrap_attempted: false,
+		},
+	};
+}
+
+export async function buildCoordinatorCheckPayload(probe?: CoordinatorCheckProbe): Promise<CoordinatorCheckPayload> {
+	return formatCoordinatorCheckPayload(await probeCoordinatorBrokerCheck(probe));
+}
+
 export function validateMcpServeSubcommandForTest(server: string | undefined): void {
 	if (server !== "coordinator" && server !== "hermes" && server !== "sdk")
 		throw new Error(`unknown_mcp_serve_subcommand:${server ?? ""}`);
@@ -46,17 +123,17 @@ export default class McpServe extends Command {
 		}
 
 		if (flags.check) {
+			if (!flags.json) {
+				const serverName = server === "sdk" ? "gjc-sdk-mcp" : COORDINATOR_MCP_SERVER_NAME;
+				const toolCount = server === "sdk" ? SDK_MCP_TOOL_NAMES.length : COORDINATOR_MCP_TOOL_NAMES.length;
+				process.stdout.write(`server: ${serverName}\ntools: ${toolCount}\n`);
+				return;
+			}
 			const payload =
 				server === "sdk"
 					? { ok: true, server: { name: "gjc-sdk-mcp" }, readOnly: false, tools: [...SDK_MCP_TOOL_NAMES] }
-					: {
-							ok: true,
-							server: { name: COORDINATOR_MCP_SERVER_NAME, protocolVersion: COORDINATOR_MCP_PROTOCOL_VERSION },
-							readOnly: true,
-							tools: [...COORDINATOR_MCP_TOOL_NAMES],
-						};
-			if (flags.json) writeJson(payload);
-			else process.stdout.write(`server: ${payload.server.name}\ntools: ${payload.tools.length}\n`);
+					: await buildCoordinatorCheckPayload();
+			writeJson(payload);
 			return;
 		}
 

package/src/commands/mcp.ts

@@ -53,7 +53,7 @@ export default class MCP extends Command {
 
 	async run(): Promise<void> {
 		if (this.argv.includes("--help") || this.argv.includes("-h")) {
-			this.printHelp();
+			this.#printHelp();
 			return;
 		}
 
@@ -80,7 +80,7 @@ export default class MCP extends Command {
 		await runMCPCommand(cmd);
 	}
 
-	private printHelp(): void {
+	#printHelp(): void {
 		process.stdout.write(`Store standalone MCP server definitions in GJC config without loading them at runtime
 
 USAGE

package/src/commands/notify.ts

@@ -12,9 +12,8 @@ export default class Notify extends Command {
 
 	static args = {
 		action: Args.string({
-			description: "Notify action",
+			description: "Notify action (setup|status|health|test|recovery|daemon-internal)",
 			required: false,
-			options: ACTIONS,
 		}),
 		extra: Args.string({
 			description: "Provider or additional internal args",
@@ -49,7 +48,12 @@ export default class Notify extends Command {
 
 	async run(): Promise<void> {
 		const { args, flags } = await this.parse(Notify);
-		const action = (args.action ?? "status") as NotifyAction;
+		const action = args.action ?? "status";
+		if (!ACTIONS.includes(action as NotifyAction)) {
+			console.error(`Unknown notify action: ${action}`);
+			console.error(`Valid actions: ${ACTIONS.join(", ")}`);
+			process.exit(1);
+		}
 		const extra = Array.isArray(args.extra) ? args.extra : args.extra ? [args.extra] : [];
 		const flagRec = flags as Record<string, unknown>;
 		const ownerId = flagRec["owner-id"] as string | undefined;
@@ -72,7 +76,7 @@ export default class Notify extends Command {
 		}
 
 		const cmd: NotifyCommandArgs = {
-			action,
+			action: action as NotifyAction,
 			smoke: flags.smoke,
 			rawArgs,
 			provider: provider === "telegram" || provider === "discord" || provider === "slack" ? provider : undefined,

package/src/commands/sdk.ts

@@ -3,6 +3,7 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { Args, Command, Flags } from "@gajae-code/utils/cli";
 import type { Args as ParsedArgs } from "../cli/args";
+import { Settings } from "../config/settings";
 import { applyStartupModelProfiles, createSessionManager } from "../main";
 import { initializeExtensions } from "../modes/runtime-init";
 import { Broker } from "../sdk/broker/broker";
@@ -16,20 +17,28 @@ import {
 } from "../sdk/broker/lifecycle";
 import { processIncarnation } from "../sdk/broker/process-incarnation";
 import { type CreateLifecycleAgentSessionResult, createLifecycleAgentSession } from "../sdk/lifecycle-session";
+import { listManagedSessionCandidates, resolveManagedSessionScope } from "../sdk/session-directory";
 import {
 	normalizeSdkStartupFailure,
 	type SdkStartupFailure,
 	type SdkStartupRollbackResult,
 	SdkStartupRollbackTracker,
 } from "../sdk/startup-capability";
-
 import {
 	type CapturedSessionTranscriptSnapshot,
 	type ResumeSessionIdentity,
 	SessionManager,
 } from "../session/session-manager";
 
-export function lifecycleArgs(request: SessionLifecycleLaunchRequest, cwd: string, agentDir: string): ParsedArgs {
+export async function lifecycleArgs(
+	request: SessionLifecycleLaunchRequest,
+	cwd: string,
+	agentDir: string,
+): Promise<ParsedArgs> {
+	const targetScope = await resolveManagedSessionScope({ cwd, agentDir });
+	if (targetScope.kind !== "resolved") throw new Error(`Lifecycle session scope is invalid: ${targetScope.message}`);
+	const forkSessionDir =
+		request.operation === "session.fork" ? SessionManager.getDefaultSessionDir(cwd, agentDir) : undefined;
 	return {
 		messages: [],
 		fileArgs: [],
@@ -39,7 +48,7 @@ export function lifecycleArgs(request: SessionLifecycleLaunchRequest, cwd: strin
 		...(request.operation === "session.fork"
 			? {
 					fork: request.sourceSessionPath ?? request.sourceSessionId,
-					sessionDir: SessionManager.getDefaultSessionDirReadOnly(cwd, agentDir),
+					sessionDir: forkSessionDir,
 				}
 			: {}),
 	};
@@ -53,7 +62,7 @@ type LifecycleTranscriptSource = {
 };
 
 function sameTranscriptIdentity(
-	actual: { dev: bigint; ino: bigint; size: number; mtimeMs: number; mtimeNs: bigint },
+	actual: { dev: bigint; ino: bigint; size: number; mtimeMs: number; mtimeNs: bigint; sha256: string },
 	expected: SessionLifecycleTranscriptIdentity,
 ): boolean {
 	return (
@@ -61,7 +70,8 @@ function sameTranscriptIdentity(
 		actual.ino.toString() === expected.ino &&
 		actual.size === expected.size &&
 		actual.mtimeMs === expected.mtimeMs &&
-		actual.mtimeNs.toString() === expected.mtimeNs
+		actual.mtimeNs.toString() === expected.mtimeNs &&
+		actual.sha256 === expected.sha256
 	);
 }
 
@@ -85,26 +95,38 @@ function lifecycleTranscriptSource(request: SessionLifecycleLaunchRequest, cwd:
 	throw new Error("A new lifecycle session has no persisted transcript authority.");
 }
 
-function verifyLifecycleTranscript(
+async function captureLifecycleTranscript(
 	request: SessionLifecycleLaunchRequest,
 	cwd: string,
 	agentDir: string,
-): LifecycleTranscriptSource {
+	migrationPolicy: "copy-retain" | "disabled",
+): Promise<CapturedSessionTranscriptSnapshot> {
 	const source = lifecycleTranscriptSource(request, cwd);
-	const inventory = SessionManager.inventorySessionsStrict(source.cwd, {
-		sessionDir: SessionManager.getDefaultSessionDir(source.cwd, agentDir),
-	});
+	const scope = await resolveManagedSessionScope({ cwd: source.cwd, agentDir });
+	if (scope.kind !== "resolved")
+		throw new Error("Lifecycle saved session storage could not be verified for the requested workspace.");
+	const inventory = await listManagedSessionCandidates({ scope: scope.scope });
 	if (inventory.kind !== "complete")
 		throw new Error("Lifecycle saved session storage could not be verified for the requested workspace.");
-	const matches = inventory.candidates.filter(
+	const captured = SessionManager.captureTranscriptStrict(source.path);
+	if (
+		captured.kind !== "captured" ||
+		captured.snapshot.sourcePath !== path.resolve(source.path) ||
+		captured.snapshot.identity.sessionId !== source.id ||
+		!sameTranscriptIdentity(captured.snapshot.identity, source.identity)
+	)
+		throw new Error("Lifecycle saved session authority changed before the session host consumed it.");
+	const matches = inventory.owned.filter(
 		candidate =>
-			candidate.path === path.resolve(source.path) &&
-			candidate.id === source.id &&
-			sameTranscriptIdentity(candidate.identity, source.identity),
+			candidate.path === captured.snapshot.sourcePath &&
+			candidate.sessionId === source.id &&
+			sameLifecycleTranscriptSnapshot(candidate.identity, captured.snapshot.identity),
 	);
 	if (matches.length !== 1)
 		throw new Error("Lifecycle saved session authority changed before the session host started.");
-	return source;
+	if (matches[0]!.provenance === "legacy" && migrationPolicy === "disabled")
+		throw new Error("Lifecycle legacy session migration is disabled by policy.");
+	return captured.snapshot;
 }
 
 function sameLifecycleTranscriptSnapshot(left: ResumeSessionIdentity, right: ResumeSessionIdentity): boolean {
@@ -120,23 +142,6 @@ function sameLifecycleTranscriptSnapshot(left: ResumeSessionIdentity, right: Res
 	);
 }
 
-function captureLifecycleTranscript(
-	request: SessionLifecycleLaunchRequest,
-	cwd: string,
-	agentDir: string,
-): CapturedSessionTranscriptSnapshot {
-	const source = verifyLifecycleTranscript(request, cwd, agentDir);
-	const captured = SessionManager.captureTranscriptStrict(source.path);
-	if (
-		captured.kind !== "captured" ||
-		captured.snapshot.sourcePath !== path.resolve(source.path) ||
-		captured.snapshot.identity.sessionId !== source.id ||
-		!sameTranscriptIdentity(captured.snapshot.identity, source.identity)
-	)
-		throw new Error("Lifecycle saved session authority changed before the session host consumed it.");
-	return captured.snapshot;
-}
-
 async function revalidateLifecycleTranscript(snapshot: ResumeSessionIdentity): Promise<void> {
 	const inspected = await SessionManager.inspectSessionTailReadOnly(snapshot.canonicalPath);
 	if (inspected.kind === "error" || !sameLifecycleTranscriptSnapshot(snapshot, inspected.identity))
@@ -149,14 +154,22 @@ export async function openLifecycleSessionManager(
 	cwd: string,
 	agentDir: string,
 ): Promise<{ parsed: ParsedArgs; sessionManager: SessionManager | undefined }> {
-	const parsed = lifecycleArgs(request, cwd, agentDir);
+	const parsed = await lifecycleArgs(request, cwd, agentDir);
+	const lifecycleSettings = await Settings.loadForScope({ cwd, agentDir });
+	const migrationPolicy =
+		lifecycleSettings.get("session.directoryMigration") === "disabled" ? "disabled" : "copy-retain";
 	if (request.operation === "session.create") {
-		return { parsed, sessionManager: await createSessionManager(parsed, cwd) };
+		return { parsed, sessionManager: await createSessionManager(parsed, cwd, lifecycleSettings) };
 	}
-	const snapshot = captureLifecycleTranscript(request, cwd, agentDir);
+	const snapshot = await captureLifecycleTranscript(request, cwd, agentDir, migrationPolicy);
 	let sessionManager: SessionManager | undefined;
 	if (request.operation === "session.resume") {
-		const opened = await SessionManager.openExistingStrict(snapshot.identity, parsed.sessionDir);
+		const opened = await SessionManager.openExistingStrict(
+			snapshot.identity,
+			parsed.sessionDir,
+			undefined,
+			migrationPolicy,
+		);
 		if (opened.kind === "error")
 			throw new Error("Lifecycle saved session authority changed while the session host opened it.");
 		sessionManager = opened.manager;
@@ -167,7 +180,7 @@ export async function openLifecycleSessionManager(
 			throw error;
 		}
 	} else {
-		const forked = await SessionManager.forkFromCaptured(snapshot, cwd, parsed.sessionDir);
+		const forked = await SessionManager.forkFromCaptured(snapshot, cwd, parsed.sessionDir, migrationPolicy);
 		if (forked.kind === "error")
 			throw new Error("Lifecycle saved session authority changed while the session host forked it.");
 		sessionManager = forked.manager;
@@ -302,21 +315,23 @@ export async function runSessionHost(
 					fs.readFile(transcriptPath),
 					fs.stat(transcriptPath, { bigint: true }),
 				]);
+				const digest = createHash("sha256").update(bytes).digest("hex");
 				return {
-					digest: createHash("sha256").update(bytes).digest("hex"),
+					digest,
 					identity: {
 						dev: stat.dev.toString(),
 						ino: stat.ino.toString(),
 						size: Number(stat.size),
 						mtimeMs: Number(stat.mtimeMs),
 						mtimeNs: stat.mtimeNs.toString(),
+						sha256: digest,
 					},
 				};
 			} catch {
 				return undefined;
 			}
 		})();
-		return disposal;
+		return disposal ?? Promise.resolve(undefined);
 	};
 	let failureRollback: Promise<void> | undefined;
 	const failAfterRollback = (failure: SdkStartupFailure): Promise<void> => {
@@ -415,7 +430,13 @@ export default class Sdk extends Command {
 		}
 		const agentDir = flags["agent-dir"] as string | undefined;
 		if (!agentDir) throw new Error("--agent-dir is required for sdk broker-internal.");
-		const broker = new Broker({ agentDir });
+		const broker = new Broker({
+			agentDir,
+			resolveDirectoryMigration: async cwd => {
+				const policy = (await Settings.loadForScope({ cwd, agentDir })).get("session.directoryMigration");
+				return policy === "disabled" ? "disabled" : "copy-retain";
+			},
+		});
 		await broker.start();
 		if (!broker.ownsDiscovery) return;
 		const stop = () => void broker.stop().finally(() => process.exit(0));

package/src/commands/ultragoal.ts

@@ -26,15 +26,18 @@ export default class Ultragoal extends Command {
 		if (isReviewStart && !result.createdReviewPlan && (result.reviewBlockerGoalIds?.length ?? 0) === 0) return;
 
 		const cwd = process.cwd();
-		const { objective, goalsPath } = await readUltragoalGjcObjective(cwd);
+		const { objective, goalsPath, provenance } = await readUltragoalGjcObjective(cwd);
+
 		await writeCurrentSessionGoalModeState({
 			sessionFile: process.env[GJC_SESSION_FILE_ENV],
 			objective,
+			provenance,
 		});
 		await writePendingGoalModeRequest({
 			cwd,
 			objective,
 			goalsPath,
+			provenance,
 			sessionId: process.env[GJC_SESSION_ID_ENV],
 		});
 	}

package/src/config/atomic-yaml-patch.ts

@@ -4,19 +4,40 @@ import * as path from "node:path";
 import { YAML } from "bun";
 import { withFileLock } from "./file-lock";
 
+export interface AtomicYamlExpectedPrecondition {
+	path: string;
+	hash: string;
+}
+
 export interface AtomicYamlSetPatch {
 	path: string;
 	op: "set";
 	value: unknown;
+	expected?: AtomicYamlExpectedPrecondition;
 }
 
 export interface AtomicYamlUnsetPatch {
 	path: string;
 	op: "unset";
+	expected?: AtomicYamlExpectedPrecondition;
 }
 
 export type AtomicYamlPatch = AtomicYamlSetPatch | AtomicYamlUnsetPatch;
 
+/** Raised when a compare-and-swap precondition no longer matches durable YAML. */
+export class AtomicYamlConflictError extends Error {
+	readonly code = "ATOMIC_YAML_CONFLICT";
+
+	constructor(
+		readonly path: string,
+		readonly expectedHash: string,
+		readonly actualHash: string,
+	) {
+		super(`Atomic YAML precondition failed for ${path}.`);
+		this.name = "AtomicYamlConflictError";
+	}
+}
+
 export interface AtomicYamlPatchRevision {
 	path: string;
 	beforeHash: string;
@@ -53,6 +74,8 @@ export interface AtomicYamlPatchOptions {
 	sleep?: (ms: number) => Promise<void>;
 	/** Test seam for Windows rename retry behavior. */
 	platform?: NodeJS.Platform;
+	/** Called under the config lock before patches are applied. */
+	validateRoot?: (root: unknown, patches: readonly AtomicYamlPatch[]) => void | Promise<void>;
 	/** Called under the config lock after a successful CAS restore. */
 	onRestored?: (patches: readonly AtomicYamlPatch[]) => void | Promise<void>;
 }
@@ -98,6 +121,16 @@ function assertPatch(patch: AtomicYamlPatch): void {
 	) {
 		throw new Error("Atomic YAML patches require a non-empty dotted path.");
 	}
+	if (
+		patch.expected &&
+		(typeof patch.expected.path !== "string" ||
+			patch.expected.path.length === 0 ||
+			patch.expected.path.split(".").some(part => !part) ||
+			typeof patch.expected.hash !== "string" ||
+			patch.expected.hash.length === 0)
+	) {
+		throw new Error("Atomic YAML patch preconditions require a non-empty dotted path and hash.");
+	}
 	if (patch.op === "set") {
 		if (patch.value === undefined) {
 			throw new TypeError(`Atomic YAML set patch for ${patch.path} cannot carry undefined; use unset instead.`);
@@ -148,6 +181,12 @@ export function deleteByPath(value: Record<string, unknown>, segments: readonly
 }
 
 function stableValue(value: unknown): string {
+	if (typeof value === "number") {
+		if (Number.isNaN(value)) return "NaN";
+		if (value === Infinity) return "Infinity";
+		if (value === -Infinity) return "-Infinity";
+		if (Object.is(value, -0)) return "-0";
+	}
 	if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "undefined";
 	if (Array.isArray(value)) return `[${value.map(stableValue).join(",")}]`;
 	const object = value as Record<string, unknown>;
@@ -167,12 +206,22 @@ function cloneState(state: PathState): PathState {
 	return state.exists ? { exists: true, value: structuredClone(state.value) } : state;
 }
 
-async function readYaml(configPath: string): Promise<Record<string, unknown>> {
+/** Hash a dotted YAML path state for an expected-hash patch precondition. */
+export function atomicYamlPathHash(value: Record<string, unknown>, path: string): string {
+	return stateHash(stateAtPath(value, path.split(".")));
+}
+
+type YamlReadResult = {
+	current: Record<string, unknown>;
+	root: unknown;
+};
+
+async function readYaml(configPath: string): Promise<YamlReadResult> {
 	try {
-		const parsed = YAML.parse(await fs.readFile(configPath, "utf8"));
-		return record(parsed) ?? {};
+		const root = YAML.parse(await fs.readFile(configPath, "utf8"));
+		return { current: record(root) ?? {}, root };
 	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return { current: {}, root: undefined };
 		throw error;
 	}
 }
@@ -254,8 +303,9 @@ function createReceipt(
 		async restore(): Promise<CasRestoreResult> {
 			if (discarded) return { status: "discarded" };
 			return await enqueueAtomicYamlOperation(configPath, async canonicalPath => {
+				if (discarded) return { status: "discarded" };
 				return await withFileLock(canonicalPath, async () => {
-					const current = await readYaml(canonicalPath);
+					const { current, root } = await readYaml(canonicalPath);
 					const conflicts = changes
 						.filter(
 							change =>
@@ -269,6 +319,7 @@ function createReceipt(
 							? { path: change.path, op: "set", value: structuredClone(change.before.value) }
 							: { path: change.path, op: "unset" },
 					);
+					await options.validateRoot?.(root, restorePatches);
 					const receipt = await applyPatchesUnderLock(canonicalPath, current, restorePatches, options);
 					await options.onRestored?.(restorePatches);
 					return { status: "restored", receipt };
@@ -286,6 +337,14 @@ async function applyPatchesUnderLock(
 ): Promise<CasReceipt> {
 	if (patches.length === 0) return createReceipt(configPath, [], options);
 
+	for (const patch of patches) {
+		if (!patch.expected) continue;
+		const actualHash = stateHash(stateAtPath(current, patch.expected.path.split(".")));
+		if (actualHash !== patch.expected.hash) {
+			throw new AtomicYamlConflictError(patch.expected.path, patch.expected.hash, actualHash);
+		}
+	}
+
 	const changesByPath = new Map<string, ReceiptChange>();
 	for (const patch of patches) {
 		const segments = patch.path.split(".");
@@ -329,9 +388,10 @@ export function applyAtomicYamlPatchesWithCurrent(
 	return enqueueAtomicYamlOperation(configPath, async canonicalPath => {
 		await fs.mkdir(path.dirname(canonicalPath), { recursive: true, mode: 0o700 });
 		return await withFileLock(canonicalPath, async () => {
-			const current = await readYaml(canonicalPath);
+			const { current, root } = await readYaml(canonicalPath);
 			const patches = await buildPatches(current);
 			for (const patch of patches) assertPatch(patch);
+			await options.validateRoot?.(root, patches);
 			return await applyPatchesUnderLock(canonicalPath, current, patches, options);
 		});
 	});
@@ -374,7 +434,8 @@ export function reserveAtomicYamlPatchSlot(
 		for (const patch of nextPatches) assertPatch(patch);
 		await fs.mkdir(path.dirname(canonicalPath), { recursive: true, mode: 0o700 });
 		return await withFileLock(canonicalPath, async () => {
-			const current = await readYaml(canonicalPath);
+			const { current, root } = await readYaml(canonicalPath);
+			await options.validateRoot?.(root, nextPatches);
 			return await applyPatchesUnderLock(canonicalPath, current, nextPatches, options);
 		});
 	});
@@ -393,7 +454,7 @@ export function reserveAtomicYamlUpdateSlot<T>(
 		const atomicUpdate = await update();
 		await fs.mkdir(path.dirname(canonicalPath), { recursive: true, mode: 0o700 });
 		return await withFileLock(canonicalPath, async () => {
-			const current = await readYaml(canonicalPath);
+			const { current } = await readYaml(canonicalPath);
 			const result = await atomicUpdate.apply(current);
 			if (atomicUpdate.shouldWrite?.(result) !== false) {
 				await writeAtomicYaml(canonicalPath, current, options);
@@ -414,10 +475,16 @@ export function applyAtomicYamlPatches(
 	options: AtomicYamlPatchOptions = {},
 ): Promise<CasReceipt> {
 	for (const patch of patches) assertPatch(patch);
-	const immutablePatches = patches.map(patch =>
-		patch.op === "set"
-			? ({ path: patch.path, op: "set", value: structuredClone(patch.value) } as const)
-			: ({ path: patch.path, op: "unset" } as const),
-	);
+	const immutablePatches = patches.map(patch => {
+		const expected = patch.expected ? { ...patch.expected } : undefined;
+		return patch.op === "set"
+			? ({
+					path: patch.path,
+					op: "set",
+					value: structuredClone(patch.value),
+					...(expected ? { expected } : {}),
+				} as const)
+			: ({ path: patch.path, op: "unset", ...(expected ? { expected } : {}) } as const);
+	});
 	return reserveAtomicYamlPatchSlot(configPath, () => immutablePatches, options);
 }