@gajae-code/coding-agent 0.18.10 → 0.18.12

package/src/config/file-lock.ts

@@ -24,6 +24,8 @@ import { nativeProcessBindings } from "@gajae-code/utils/native-process";
 
 export interface FileLockOptions {
 	staleMs?: number;
+	/** Age after which an ownerless removal transition may be adopted; defaults to `staleMs`. */
+	orphanTransitionAgeMs?: number;
 	retries?: number;
 	retryDelayMs?: number;
 	signal?: AbortSignal;
@@ -91,7 +93,10 @@ export function isFileLockAcquireTimeout(error: unknown): error is FileLockAcqui
 }
 
 const DEFAULT_OPTIONS: Required<
-	Omit<FileLockOptions, "ownerHostId" | "previousOwnerHostIds" | "signal" | "onAcquired" | "onContended">
+	Omit<
+		FileLockOptions,
+		"orphanTransitionAgeMs" | "ownerHostId" | "previousOwnerHostIds" | "signal" | "onAcquired" | "onContended"
+	>
 > = {
 	staleMs: 10_000,
 	retries: 50,
@@ -104,11 +109,19 @@ const DEFAULT_OPTIONS: Required<
  * is explicitly pre-mutation in this case, so retrying the same source name cannot
  * publish twice or clean up a committed namespace change.
  */
-const PUBLICATION_SHARING_RETRY_ATTEMPTS = 3;
-const PUBLICATION_SHARING_RETRY_DELAY_MS = 10;
+const PUBLICATION_CONTENTION_RETRY_ATTEMPTS = 3;
+const PUBLICATION_CONTENTION_RETRY_DELAY_MS = 10;
 
-/** Ownerless empty residue must outlive both this grace and the acquire budget. */
+/** Grace period after which an unpublished removal transition becomes reclaimable as orphan. */
 const REMOVAL_TRANSITION_GRACE_MS = 10_000;
+/**
+ * Additional buffer beyond the grace period to ensure a retained removal transition
+ * whose owner died is reclaimed promptly, decoupled from acquisition retry budget.
+ * This bounds how long a dead owner's transition can block lock acquisition.
+ */
+const REMOVAL_TRANSITION_ADOPTION_BUFFER_MS = 5_000;
+export const FILE_LOCK_ORPHAN_TRANSITION_ADOPTION_AGE_MS =
+	REMOVAL_TRANSITION_GRACE_MS + REMOVAL_TRANSITION_ADOPTION_BUFFER_MS;
 
 /** Release retries cover transient handle denial and a competing exact-removal quarantine cleanup. */
 export const FILE_LOCK_RELEASE_RETRY_ATTEMPTS = 20;
@@ -137,6 +150,10 @@ export const FileLockTestHooks: {
 		renameNoReplacePathAsync: typeof renameNoReplacePathAsync;
 		renameDirectoryNoReplacePathAsync: typeof renameDirectoryNoReplacePathAsync;
 	};
+	stagingIdentityEvidence?: () => {
+		processIncarnation: string | null;
+		startTime: string | null;
+	};
 	nativeQuarantineBindings?: () => NativeFileLockBindings;
 	nativeExactRemovalProbe?: () => boolean | Promise<boolean>;
 } = {};
@@ -806,8 +823,18 @@ async function exactRemoveLockTree(
 	const transitionPath = fileLockRemovalTransitionPath(lockPath);
 	const recordPath = `${transitionPath}.owner`;
 	const prior = await readRemovalTransitionOwnerRecord(transitionPath);
-	if (prior?.owner.owner_host_id !== undefined && lockRecordIsForeignHost(prior.owner, ownerHostId, []))
+	if (prior?.owner.owner_host_id !== undefined && lockRecordIsForeignHost(prior.owner, ownerHostId, [])) {
+		// A foreign transition remains untouchable. Once its tree is gone, only
+		// the remover's final record clear is pending: wait without probing its
+		// PID or deleting its record, even for an unqualified successor.
+		try {
+			await fs.lstat(transitionPath);
+		} catch (error) {
+			if (!isEnoent(error)) throw error;
+			return { ok: false, code: "removal_record_busy" };
+		}
 		return { ok: false, code: "identity_mismatch" };
+	}
 	if (prior && !ownerIsAlive(prior.owner) && ownerLiveness(prior.owner.pid) !== "unknown") {
 		try {
 			await fs.lstat(transitionPath);
@@ -818,8 +845,12 @@ async function exactRemoveLockTree(
 		if (!(await removeRemovalRecord(recordPath, JSON.stringify(prior))))
 			return { ok: false, code: "identity_mismatch" };
 	}
+	// A live remover still owns the sibling record, usually the previous lock
+	// generation whose tree is gone but whose record clear is still in flight.
+	// That is contention, not a changed owner: identity_mismatch makes a release
+	// final and strands this live owner's lock for every other process.
 	if (!(await publishRemovalRecord(transitionPath, snapshot, ownerHostId)))
-		return { ok: false, code: "identity_mismatch" };
+		return { ok: false, code: "removal_record_busy" };
 	try {
 		return nativeFileLockBindings().exactRemoveDirectoryTree(lockPath, snapshot, parentIdentity, detachOnly);
 	} finally {
@@ -1192,6 +1223,7 @@ function isValidNativeNoReplaceResult(value: unknown): value is NativeNoReplaceR
 				"identity_violation",
 				"durability_not_provable",
 				"sharing_violation",
+				"access_denied",
 				"unknown",
 			] as const
 		).includes(value.reason as never) ||
@@ -1302,19 +1334,19 @@ function isPreMutationUnsupportedRenameResult(value: unknown): value is NativeNo
 	return true;
 }
 
-function isPreMutationSharingViolation(value: unknown): value is NativeNoReplaceResult {
+function isPreMutationPublicationContention(value: unknown): boolean {
 	return (
 		isValidNativeNoReplaceResult(value) &&
 		!value.ok &&
 		value.code === "sharing_violation" &&
 		value.mutationState === "not_committed" &&
 		value.durabilityState === "not_attempted" &&
-		value.reason === "sharing_violation" &&
+		value.reason === value.code &&
 		value.phase === "rename"
 	);
 }
 
-async function publishNoReplaceWithSharingRetry(
+async function publishNoReplaceWithContentionRetry(
 	publish: (sourcePath: string, destinationPath: string) => Promise<NativeNoReplaceResult>,
 	sourcePath: string,
 	destinationPath: string,
@@ -1322,10 +1354,10 @@ async function publishNoReplaceWithSharingRetry(
 	let result = await publish(sourcePath, destinationPath);
 	for (
 		let attempt = 1;
-		attempt < PUBLICATION_SHARING_RETRY_ATTEMPTS && isPreMutationSharingViolation(result);
+		attempt < PUBLICATION_CONTENTION_RETRY_ATTEMPTS && isPreMutationPublicationContention(result);
 		attempt++
 	) {
-		await Bun.sleep(PUBLICATION_SHARING_RETRY_DELAY_MS * attempt);
+		await Bun.sleep(PUBLICATION_CONTENTION_RETRY_DELAY_MS * attempt);
 		result = await publish(sourcePath, destinationPath);
 	}
 	return result;
@@ -2003,7 +2035,10 @@ async function tryAcquireLock(
 	await ensureLockParent(path.dirname(lockPath));
 	const afterParentMkdir = FileLockTestHooks.afterParentMkdir;
 	if (afterParentMkdir) await afterParentMkdir(lockPath);
-	const pendingPath = `${lockPath}.pending.${process.pid}.${crypto.randomUUID()}`;
+	const stagingIdentity = currentFileLockStagingIdentity();
+	const pendingPath = stagingIdentity
+		? `${lockPath}.pending.${process.pid}.${stagingIdentity}.${crypto.randomBytes(12).toString("base64url")}`
+		: `${lockPath}.pending.${process.pid}.${crypto.randomUUID()}`;
 	const owner = lockInfo(ownerHostId, ownerToken);
 	let removePending = false;
 	try {
@@ -2083,7 +2118,7 @@ async function tryAcquireLock(
 			renameNoReplacePathAsync,
 			renameDirectoryNoReplacePathAsync,
 		};
-		const published = await publishNoReplaceWithSharingRetry(
+		const published = await publishNoReplaceWithContentionRetry(
 			publication.renameNoReplacePathAsync,
 			canonicalPendingPath,
 			destinationPath,
@@ -2092,7 +2127,7 @@ async function tryAcquireLock(
 		if (published.ok && !publishedSuccessfully)
 			throw new Error("Failed to publish file lock: invalid primary success receipt.");
 		if (!published.ok && isPreMutationUnsupportedRenameResult(published)) {
-			const fallback = await publishNoReplaceWithSharingRetry(
+			const fallback = await publishNoReplaceWithContentionRetry(
 				publication.renameDirectoryNoReplacePathAsync,
 				canonicalPendingPath,
 				destinationPath,
@@ -2117,6 +2152,8 @@ async function tryAcquireLock(
 			}
 			if (fallbackSuccessfully || verifiedCommittedPublication) {
 				publishedSuccessfully = true;
+			} else if (isPreMutationPublicationContention(fallback)) {
+				return null;
 			} else if (fallback.reason === "destination_exists") {
 				return null;
 			} else {
@@ -2128,7 +2165,7 @@ async function tryAcquireLock(
 			}
 		}
 		if (!publishedSuccessfully) {
-			if (published.reason === "destination_exists") {
+			if (isPreMutationPublicationContention(published) || published.reason === "destination_exists") {
 				return null;
 			}
 			const failure = new Error(
@@ -2308,14 +2345,23 @@ async function quarantineReleasedLock(
 	return false;
 }
 
-async function releaseOwnedLock(lockPath: string, owner: FileLockOwnerToken): Promise<void> {
+async function releaseOwnedLock(
+	lockPath: string,
+	owner: FileLockOwnerToken,
+	captureInitialIdentity = false,
+): Promise<void> {
 	if (await finishDetachedLockCleanup(owner)) return;
-	let preVerdictIdentity: GenericFileLockDirIdentity | undefined;
-	try {
-		preVerdictIdentity = (await captureFileLockDirIdentity(lockPath)) ?? undefined;
-		if (preVerdictIdentity) fileLockDirIdentities.set(owner, preVerdictIdentity);
-	} catch (error) {
-		if (!isTransientReleaseError(error)) throw error;
+	// Only the initial release may establish removal authority. Pending retries
+	// must retain that evidence, even if a replacement carries identical info.
+	// If the initial capture failed, a later pathname cannot supply authority.
+	let preVerdictIdentity = fileLockDirIdentities.get(owner);
+	if (captureInitialIdentity && !preVerdictIdentity) {
+		try {
+			preVerdictIdentity = (await captureFileLockDirIdentity(lockPath)) ?? undefined;
+			if (preVerdictIdentity) fileLockDirIdentities.set(owner, preVerdictIdentity);
+		} catch (error) {
+			if (!isTransientReleaseError(error)) throw error;
+		}
 	}
 	let lastTransientError: unknown;
 	for (let attempt = 0; attempt < FILE_LOCK_RELEASE_RETRY_ATTEMPTS; attempt++) {
@@ -2392,18 +2438,41 @@ async function releaseLock(lockPath: string, owner: FileLockOwnerToken, knownKey
 		return;
 	}
 	state.status = "releasing";
-	const releasePromise = releaseOwnedLock(lockPath, owner);
+	const releasePromise = releaseOwnedLock(lockPath, owner, true);
 	state.releasePromise = releasePromise;
 	try {
 		await releasePromise;
 		if (localLockStates.get(key) === state) localLockStates.delete(key);
 	} catch (error) {
 		state.status = "release_pending";
+		scheduleReleasePendingRetry(lockPath, key, state);
 		throw error;
 	} finally {
 		if (state.releasePromise === releasePromise) state.releasePromise = undefined;
 	}
 }
+
+const RELEASE_PENDING_RETRY_DELAYS_MS = [250, 1_000, 5_000, 15_000, 60_000];
+
+/**
+ * A failed release otherwise waits for this process's next acquisition of the
+ * same path. An idle process may never acquire again and other processes never
+ * displace a live owner, so retry in the background. Each retry re-runs the full
+ * guarded release and can only remove this owner generation.
+ */
+function scheduleReleasePendingRetry(lockPath: string, key: string, state: LocalLockState, attempt = 0): void {
+	const delay = RELEASE_PENDING_RETRY_DELAYS_MS[attempt];
+	if (delay === undefined) {
+		logger.warn("File lock release is still pending after background retries", { lockPath });
+		return;
+	}
+	const timer = setTimeout(async () => {
+		if (localLockStates.get(key) !== state) return;
+		await retryPendingLocalRelease(lockPath, key).catch(() => undefined);
+		if (localLockStates.get(key) === state) scheduleReleasePendingRetry(lockPath, key, state, attempt + 1);
+	}, delay);
+	timer.unref?.();
+}
 /**
  * Bounded, actionable description of who holds `lockPath` at exhaustion time.
  * Never a stealing authority: purely diagnostic, read once after the last retry.
@@ -2482,6 +2551,16 @@ async function lockHolderDescription(
 		} catch (error) {
 			if (!isEnoent(error)) throw error;
 		}
+		try {
+			if ((await fs.readdir(lockPath)).length === 0) {
+				return (
+					"held by an ownerless empty lock directory; inspect and remove this exact directory manually only after " +
+					`confirming no publisher remains: ${manualLockCleanupCommand(lockPath)}`
+				);
+			}
+		} catch (error) {
+			if (!isEnoent(error)) throw error;
+		}
 		return "held by an unrecognized owner record";
 	} catch (error) {
 		return `held by an unreadable owner (${(error as Error).message})`;
@@ -2497,7 +2576,9 @@ export async function acquireFileLock(filePath: string, options: FileLockOptions
 	if (options.previousOwnerHostIds?.some(hostId => !hostId))
 		throw new Error("previousOwnerHostIds must contain only non-empty identities");
 	const opts = { ...DEFAULT_OPTIONS, ...options };
-	const orphanTransitionAgeMs = Math.max(REMOVAL_TRANSITION_GRACE_MS, opts.retries * opts.retryDelayMs);
+	const orphanTransitionAgeMs = options.orphanTransitionAgeMs ?? options.staleMs ?? DEFAULT_OPTIONS.staleMs;
+	if (!Number.isFinite(orphanTransitionAgeMs) || orphanTransitionAgeMs < 0)
+		throw new RangeError("orphanTransitionAgeMs must be a finite, non-negative number");
 
 	if (opts.signal?.aborted) throw opts.signal.reason ?? new Error("File lock acquisition aborted");
 	const lockPath = getLockPath(filePath);
@@ -2527,16 +2608,20 @@ export async function acquireFileLock(filePath: string, options: FileLockOptions
 			ownerToken,
 			opts.onAcquired,
 		);
-		if (isFileLockOrphanTransition(result))
-			throw new FileLockAcquireError(
-				filePath,
-				lockPath,
-				attempt + 1,
-				`orphan transition retained at ${result.path}`,
-				"orphan_transition",
-				result.path,
-			);
-		if (result) {
+		if (isFileLockOrphanTransition(result)) {
+			// Adoption is identity-bound and can be refused by a transient cleanup race.
+			// Keep using the caller's bounded contention budget; the same generation is
+			// revalidated before every later adoption attempt.
+			if (attempt + 1 === opts.retries)
+				throw new FileLockAcquireError(
+					filePath,
+					lockPath,
+					opts.retries,
+					`orphan transition retained at ${result.path}`,
+					"orphan_transition",
+					result.path,
+				);
+		} else if (result) {
 			localLockStates.set(localKey, { owner: result, status: "held" });
 			return () => releaseLock(lockPath, result, localKey);
 		}
@@ -2585,20 +2670,26 @@ export async function acquireFileLock(filePath: string, options: FileLockOptions
 			opts.signal.removeEventListener("abort", onAbort);
 		}
 	}
+	const holder = await lockHolderDescription(
+		lockPath,
+		orphanTransitionAgeMs,
+		opts.ownerHostId,
+		opts.previousOwnerHostIds ?? [],
+	);
+	const transitionState = await classifyFileLockRemovalTransition(
+		lockPath,
+		orphanTransitionAgeMs,
+		opts.ownerHostId,
+		opts.previousOwnerHostIds ?? [],
+	);
+	const transitionPath = transitionState ? fileLockRemovalTransitionPath(lockPath) : undefined;
 	throw new FileLockAcquireError(
 		filePath,
 		lockPath,
 		opts.retries,
-		await lockHolderDescription(lockPath, orphanTransitionAgeMs, opts.ownerHostId, opts.previousOwnerHostIds ?? []),
-		"acquire_timeout",
-		(await classifyFileLockRemovalTransition(
-			lockPath,
-			orphanTransitionAgeMs,
-			opts.ownerHostId,
-			opts.previousOwnerHostIds ?? [],
-		))
-			? fileLockRemovalTransitionPath(lockPath)
-			: undefined,
+		holder,
+		transitionState === "orphan_transition" ? "orphan_transition" : "acquire_timeout",
+		transitionPath,
 		await staleRemovalFailureForCurrentGeneration(lockPath, staleRemovalFailure),
 	);
 }
@@ -2630,14 +2721,54 @@ export async function withFileLock<T>(
 	return result;
 }
 
-/** Strictly recognize the staging names emitted by tryAcquireLock. */
-export function fileLockStagingOwnerPid(name: string): number | null {
-	const match = /^.+\.lock\.pending\.([1-9]\d*)\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.exec(
-		name,
-	);
+type FileLockStagingIdentity = { kind: "process_incarnation" | "start_time"; value: string };
+type FileLockStagingOwner = { pid: number; identity?: FileLockStagingIdentity };
+
+const FILE_LOCK_STAGING_UUID = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+const FILE_LOCK_STAGING_NAME_WITH_IDENTITY =
+	/^.+\.lock\.pending\.([1-9]\d*)\.([is][A-Za-z0-9_-]{16})\.([A-Za-z0-9_-]{16})$/;
+const LEGACY_FILE_LOCK_STAGING_NAME = new RegExp(`^.+\\.lock\\.pending\\.([1-9]\\d*)\\.${FILE_LOCK_STAGING_UUID}$`);
+
+function fileLockStagingOwner(name: string): FileLockStagingOwner | null {
+	const current = FILE_LOCK_STAGING_NAME_WITH_IDENTITY.exec(name);
+	const legacy = current ? null : LEGACY_FILE_LOCK_STAGING_NAME.exec(name);
+	const match = current ?? legacy;
 	if (!match) return null;
 	const pid = Number(match[1]);
-	return Number.isSafeInteger(pid) ? pid : null;
+	if (!Number.isSafeInteger(pid)) return null;
+	if (!current) return { pid };
+	const encodedIdentity = current[2] ?? "";
+	return {
+		pid,
+		identity: {
+			kind: encodedIdentity.startsWith("i") ? "process_incarnation" : "start_time",
+			value: encodedIdentity.slice(1),
+		},
+	};
+}
+
+function fileLockStagingIdentityHash(identity: string): string {
+	// Ninety-six bits are sufficient to disambiguate process generations while
+	// keeping the sibling name within the old component-length envelope.
+	return crypto.createHash("sha256").update(identity, "utf8").digest("base64url").slice(0, 16);
+}
+
+/**
+ * A missing generation is represented by a legacy UUID name that forces a
+ * liveness probe; never hash a synthetic "unknown" as if it were identity evidence.
+ */
+function currentFileLockStagingIdentity(): string | null {
+	const evidence = FileLockTestHooks.stagingIdentityEvidence?.();
+	const incarnation = evidence ? evidence.processIncarnation : currentProcessIncarnation();
+	if (incarnation) return `i${fileLockStagingIdentityHash(incarnation)}`;
+	const startTime = evidence ? evidence.startTime : currentProcessStartTime();
+	if (!startTime || startTime === "unknown") return null;
+	return `s${fileLockStagingIdentityHash(startTime)}`;
+}
+
+/** Return a name-encoded staging PID for GC discovery. */
+export function fileLockStagingOwnerPid(name: string): number | null {
+	return fileLockStagingOwner(name)?.pid ?? null;
 }
 
 export interface FileLockStagingResult {
@@ -2660,8 +2791,9 @@ export async function inspectFileLockStagingDir(
 		removed: false,
 		reason: "unverified_staging_directory",
 	};
-	const namePid = fileLockStagingOwnerPid(path.basename(stagingPath));
-	if (namePid === null) return kept;
+	const nameOwner = fileLockStagingOwner(path.basename(stagingPath));
+	if (!nameOwner) return kept;
+	const namePid = nameOwner.pid;
 	const canonical = await canonicalLockPathPreservingFinal(stagingPath);
 	// A winning acquirer publishes (renames) its staging directory concurrently, so the
 	// candidate can disappear between the caller's readdir and this observation.
@@ -2673,6 +2805,36 @@ export async function inspectFileLockStagingDir(
 		return { ...kept, reason: "enoent_already_gone" };
 	}
 	if (!root.isDirectory() || root.isSymbolicLink()) return kept;
+	let namePidStatus: OwnerLiveness;
+	if (nameOwner.identity) {
+		const currentIdentity =
+			nameOwner.identity.kind === "process_incarnation" ? processIncarnation(namePid) : processStartTime(namePid);
+		if (currentIdentity !== null && fileLockStagingIdentityHash(currentIdentity) === nameOwner.identity.value) {
+			return { ...kept, pid: namePid, status: "alive", reason: "live_staging_name_owner" };
+		}
+		const syntheticStartTimeFallback =
+			nameOwner.identity.kind === "start_time" &&
+			(nameOwner.identity.value === fileLockStagingIdentityHash(`${namePid}:unknown`) ||
+				(currentIdentity !== null &&
+					nameOwner.identity.value === fileLockStagingIdentityHash(`${namePid}:${currentIdentity}`)));
+		// Older publishers hashed `${pid}:${startTime}` or `${pid}:unknown` when
+		// start-time evidence was unavailable. A later raw start-time mismatch is
+		// not proof those already-running staging owners are dead.
+		namePidStatus = currentIdentity === null || syntheticStartTimeFallback ? probe(namePid) : "dead";
+	} else {
+		namePidStatus = probe(namePid);
+	}
+	if (namePidStatus !== "dead") {
+		// Do not open the publication source while its owner may be live. On Windows an
+		// info-file handle can prevent the owner's atomic directory rename. Legacy names
+		// without generation evidence and unknown liveness fail closed.
+		return {
+			...kept,
+			pid: namePid,
+			status: namePidStatus,
+			reason: namePidStatus === "alive" ? "live_staging_name_owner" : "staging_name_owner_liveness_unknown",
+		};
+	}
 	const captured = nativeFileLockBindings().snapshotDirectoryTree(canonical);
 	if (
 		!captured.ok ||
@@ -2702,10 +2864,8 @@ export async function inspectFileLockStagingDir(
 		if (captured.snapshot.entries.some(entry => entry.relativePath !== "")) return kept;
 		pid = namePid;
 	}
-	if (pid === process.pid || namePid === process.pid) {
-		return { ...kept, pid, status: "alive", reason: "in_process_staging_owner" };
-	}
-	let status = probe(pid);
+	let status = pid === namePid ? namePidStatus : probe(pid);
+	if (pid === process.pid && observation && !ownerIncarnationChanged(observation.info)) status = "alive";
 	if (status === "alive" && observation && ownerIncarnationChanged(observation.info)) status = "dead";
 	const result: FileLockStagingResult = {
 		path: stagingPath,

package/src/config/model-bindings-applier.ts

@@ -10,12 +10,14 @@ export interface ConfiguredModelBindings {
 export class ModelBindingsApplier {
 	#targetSettings: Settings | undefined;
 	#bindings: ConfiguredModelBindings | undefined;
+	#lastAppliedRoles = new Map<string, ModelSelectorValue>();
+	#lastAppliedAgentOverrides = new Map<string, ModelSelectorValue>();
+	#manualRoles = new Map<string, ModelSelectorValue | undefined>();
+	#manualAgentOverrides = new Map<string, ModelSelectorValue | undefined>();
 	#appliedRoles = new Set<string>();
 	#appliedAgentOverrides = new Set<string>();
 	#roleBaselines = new Map<string, ModelSelectorValue | undefined>();
 	#agentBaselines = new Map<string, ModelSelectorValue | undefined>();
-	#lastAppliedRoles = new Map<string, ModelSelectorValue>();
-	#lastAppliedAgentOverrides = new Map<string, ModelSelectorValue>();
 
 	/** The currently configured bindings (as installed at startup), for baseline lookup. */
 	getBindings(): ConfiguredModelBindings | undefined {
@@ -71,6 +73,8 @@ export class ModelBindingsApplier {
 		this.#targetSettings = targetSettings;
 		const bindings = this.#bindings;
 		if (!targetSettings) return;
+		for (const role of Object.keys(bindings?.modelRoles ?? {})) this.#manualRoles.delete(role);
+		for (const role of Object.keys(bindings?.agentModelOverrides ?? {})) this.#manualAgentOverrides.delete(role);
 		const modelRoles = { ...(targetSettings.get("modelRoles") ?? {}) };
 		this.#forceSync(
 			modelRoles,
@@ -98,6 +102,13 @@ export class ModelBindingsApplier {
 		baselines: Map<string, ModelSelectorValue | undefined>,
 		lastApplied: Map<string, ModelSelectorValue>,
 	): void {
+		const configuredKeys = new Set(Object.keys(configured));
+		for (const key of applied) {
+			if (configuredKeys.has(key)) continue;
+			const baseline = baselines.get(key);
+			if (baseline === undefined) delete target[key];
+			else target[key] = this.#clone(baseline)!;
+		}
 		for (const [key, value] of Object.entries(configured)) {
 			if (!baselines.has(key)) baselines.set(key, this.#clone(target[key]));
 			target[key] = this.#clone(value)!;
@@ -111,82 +122,109 @@ export class ModelBindingsApplier {
 		const targetSettings = this.#targetSettings;
 		if (!targetSettings) return;
 		const bindings = this.#bindings;
-		const nextModelRoles = { ...(targetSettings.get("modelRoles") ?? {}) };
 		this.#sync(
-			nextModelRoles,
+			targetSettings,
+			"modelRoles",
 			bindings?.modelRoles ?? {},
-			this.#appliedRoles,
-			this.#roleBaselines,
 			this.#lastAppliedRoles,
+			this.#manualRoles,
+			this.#roleBaselines,
 		);
-		targetSettings.override("modelRoles", nextModelRoles);
-
-		const nextAgentOverrides = { ...(targetSettings.get("task.agentModelOverrides") ?? {}) };
 		this.#sync(
-			nextAgentOverrides,
+			targetSettings,
+			"task.agentModelOverrides",
 			bindings?.agentModelOverrides ?? {},
-			this.#appliedAgentOverrides,
-			this.#agentBaselines,
 			this.#lastAppliedAgentOverrides,
+			this.#manualAgentOverrides,
+			this.#agentBaselines,
 		);
-		targetSettings.override("task.agentModelOverrides", nextAgentOverrides);
 	}
 
 	#restoreTarget(targetSettings: Settings): void {
-		const modelRoles = { ...(targetSettings.get("modelRoles") ?? {}) };
-		this.#sync(modelRoles, {}, this.#appliedRoles, this.#roleBaselines, this.#lastAppliedRoles);
-		targetSettings.override("modelRoles", modelRoles);
-
-		const agentOverrides = { ...(targetSettings.get("task.agentModelOverrides") ?? {}) };
 		this.#sync(
-			agentOverrides,
+			targetSettings,
+			"task.agentModelOverrides",
 			{},
-			this.#appliedAgentOverrides,
-			this.#agentBaselines,
 			this.#lastAppliedAgentOverrides,
+			this.#manualAgentOverrides,
+			this.#agentBaselines,
 		);
-		targetSettings.override("task.agentModelOverrides", agentOverrides);
+		this.#sync(targetSettings, "modelRoles", {}, this.#lastAppliedRoles, this.#manualRoles, this.#roleBaselines);
 	}
 
 	#clearTargetLifecycle(): void {
-		this.#appliedRoles.clear();
-		this.#appliedAgentOverrides.clear();
-		this.#roleBaselines.clear();
-		this.#agentBaselines.clear();
 		this.#lastAppliedRoles.clear();
 		this.#lastAppliedAgentOverrides.clear();
+		this.#manualRoles.clear();
+		this.#manualAgentOverrides.clear();
+		this.#roleBaselines.clear();
+		this.#agentBaselines.clear();
 	}
 
 	#sync(
-		target: Record<string, ModelSelectorValue>,
+		targetSettings: Settings,
+		settingPath: "modelRoles" | "task.agentModelOverrides",
 		configured: Record<string, ModelSelectorValue>,
-		applied: Set<string>,
-		baselines: Map<string, ModelSelectorValue | undefined>,
 		lastApplied: Map<string, ModelSelectorValue>,
+		manualOverrides: Map<string, ModelSelectorValue | undefined>,
+		baselines: Map<string, ModelSelectorValue | undefined>,
 	): void {
 		const configuredKeys = new Set(Object.keys(configured));
-		for (const key of applied) {
-			if (configuredKeys.has(key)) continue;
-			const previous = lastApplied.get(key);
-			if (previous !== undefined && this.#equal(target[key], previous)) {
-				const baseline = baselines.get(key);
-				if (baseline === undefined) delete target[key];
-				else target[key] = this.#clone(baseline)!;
+		const current = (targetSettings.get(settingPath) ?? {}) as Record<string, ModelSelectorValue>;
+		const global = (targetSettings.getGlobal(settingPath) ?? {}) as Record<string, ModelSelectorValue>;
+		const runtime = targetSettings.getOverride(settingPath) ?? {};
+		for (const key of configuredKeys) {
+			if (!lastApplied.has(key) && !baselines.has(key)) baselines.set(key, this.#clone(runtime[key]));
+		}
+
+		// Manual bindings remain authoritative, but their cached values must follow
+		// later edits and removals from the runtime override slots.
+		for (const key of manualOverrides.keys()) {
+			manualOverrides.set(key, this.#clone(runtime[key]));
+		}
+
+		// Keep existing non-global values that belong to another runtime layer.
+		for (const [key, value] of Object.entries(current)) {
+			if (configuredKeys.has(key) || lastApplied.has(key) || manualOverrides.has(key)) continue;
+			if (!this.#equal(value, global[key])) manualOverrides.set(key, this.#clone(value)!);
+		}
+
+		// A value changed while our previous overlay was active is a manual edit.
+		for (const [key, previous] of lastApplied) {
+			const currentValue = current[key];
+			if (!Object.hasOwn(runtime, key) || !Object.hasOwn(current, key)) {
+				manualOverrides.set(key, undefined);
+			} else if (!this.#equal(runtime[key], previous)) {
+				manualOverrides.set(key, this.#clone(runtime[key])!);
+			} else if (!this.#equal(currentValue, previous)) {
+				manualOverrides.set(key, this.#clone(currentValue)!);
 			}
-			baselines.delete(key);
-			lastApplied.delete(key);
 		}
-		for (const [key, value] of Object.entries(configured)) {
-			const previous = lastApplied.get(key);
-			if (!baselines.has(key)) baselines.set(key, this.#clone(target[key]));
-			if (previous === undefined || this.#equal(target[key], previous)) {
-				const appliedValue = this.#clone(value)!;
-				target[key] = appliedValue;
-				lastApplied.set(key, this.#clone(appliedValue)!);
+
+		const nextOverrides: Record<string, ModelSelectorValue> = {};
+		for (const [key, value] of Object.entries(runtime)) {
+			if (!lastApplied.has(key) && !configuredKeys.has(key)) nextOverrides[key] = this.#clone(value)!;
+		}
+		for (const [key, baseline] of baselines) {
+			if (!configuredKeys.has(key)) {
+				if (baseline !== undefined) nextOverrides[key] = this.#clone(baseline)!;
+				baselines.delete(key);
 			}
 		}
-		applied.clear();
-		for (const key of configuredKeys) applied.add(key);
+		for (const [key, value] of manualOverrides) {
+			if (value === undefined) delete nextOverrides[key];
+			else nextOverrides[key] = this.#clone(value)!;
+		}
+		lastApplied.clear();
+		for (const [key, value] of Object.entries(configured)) {
+			if (manualOverrides.has(key)) continue;
+			const appliedValue = this.#clone(value)!;
+			nextOverrides[key] = appliedValue;
+			lastApplied.set(key, this.#clone(appliedValue)!);
+		}
+
+		if (Object.keys(nextOverrides).length === 0) targetSettings.clearOverride(settingPath);
+		else targetSettings.override(settingPath, nextOverrides);
 	}
 
 	#cloneBindings(