@gajae-code/coding-agent 0.10.1 → 0.11.0

package/src/config/settings.ts

@@ -7,10 +7,9 @@
  *   const enabled = settings.get("compaction.enabled");  // sync read
  *   settings.set("theme.dark", "red-claw");              // sync write, saves in background
  *
- * For tests:
+ * For tests, `Settings.isolated()` seeds explicit user/global settings:
  *   const isolated = Settings.isolated({ "compaction.enabled": false });
  */
-
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -29,9 +28,20 @@ import { type Settings as SettingsCapabilityItem, settingsCapability } from "../
 import type { ModelRole } from "../config/model-registry";
 import { loadCapability } from "../discovery";
 import { isLightTheme, setAutoThemeMapping, setColorBlindMode, setSymbolPreset } from "../modes/theme/theme";
+import type { NotificationSettingsReader, NotificationSettingsSnapshot } from "../sdk/bus/config";
 import { AgentStorage } from "../session/agent-storage";
 import { type EditMode, normalizeEditMode } from "../utils/edit-mode";
-import { withFileLock } from "./file-lock";
+import {
+	type AtomicYamlPatch,
+	applyAtomicYamlPatches,
+	applyAtomicYamlPatchesWithCurrent,
+	type CasReceipt,
+	deleteByPath,
+	reserveAtomicYamlUpdateSlot,
+	setByPath,
+} from "./atomic-yaml-patch";
+import { isModelSelectorValue, type ModelSelectorValue, normalizeModelSelectorValue } from "./model-selector-value";
+
 import {
 	type BashInterceptorRule,
 	type GroupPrefix,
@@ -57,10 +67,38 @@ export interface RawSettings {
 
 type SettingsPatch = {
 	readonly path: string;
-	readonly value: unknown;
+	readonly value: unknown | undefined;
 	readonly generation: number;
+	readonly revision: number;
+	readonly modelRole?: string;
+	readonly modelRoleRevision?: number;
+	readonly configVersion?: string;
+	readonly legacyFallbackMigration?: boolean;
+};
+
+type PendingSaveSlot = {
+	captured: boolean;
+	released: boolean;
+	release: () => void;
+	wait: Promise<void>;
 };
 
+type DurableBatchRevision = {
+	patch: AtomicYamlPatch;
+	previousRevision: number | undefined;
+	revision: number;
+};
+
+export type SettingsAtomicPatch = { path: SettingPath; op: "set"; value: unknown } | { path: SettingPath; op: "unset" };
+export type SettingsAtomicReceipt = CasReceipt;
+
+export interface GlobalDefaultModelRoleCommit {
+	readonly previousDefault: ModelSelectorValue | undefined;
+	readonly previousModelRolesExisted: boolean;
+	readonly committedDefault: ModelSelectorValue | undefined;
+	readonly committedConfigVersion?: string;
+	readonly defaultRevision: number;
+}
 export interface SettingsOptions {
 	/** Current working directory for project settings discovery */
 	cwd?: string;
@@ -72,6 +110,31 @@ export interface SettingsOptions {
 	overrides?: Partial<Record<SettingPath, unknown>>;
 }
 
+/** Additional layer setup for {@link Settings.isolated}. */
+export interface IsolatedSettingsOptions {
+	/** Initial runtime overrides. Notification paths are rejected. */
+	overrides?: Partial<Record<SettingPath, unknown>>;
+}
+
+/** Raised when an ephemeral override attempts to change global-only notification settings. */
+export class NotificationSettingsOverrideError extends Error {
+	constructor(readonly path: SettingPath) {
+		super(`Runtime overrides are not allowed for global notification setting ${path}.`);
+		this.name = "NotificationSettingsOverrideError";
+	}
+}
+
+const LOCAL_NOTIFICATION_SETTING_KEYS = new Set(["terminalBell", "bellOnComplete", "bellOnApproval", "bellOnAsk"]);
+const LOCAL_NOTIFICATION_SETTING_PATHS = new Set(
+	[...LOCAL_NOTIFICATION_SETTING_KEYS].map(key => `notifications.${key}`),
+);
+
+function isNotificationSettingsPath(path: string): boolean {
+	return (
+		(path === "notifications" || path.startsWith("notifications.")) && !LOCAL_NOTIFICATION_SETTING_PATHS.has(path)
+	);
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // Path Utilities
 // ═══════════════════════════════════════════════════════════════════════════
@@ -90,22 +153,6 @@ function getByPath(obj: RawSettings, segments: string[]): unknown {
 	return current;
 }
 
-/**
- * Set a nested value in an object by path segments.
- * Creates intermediate objects as needed.
- */
-function setByPath(obj: RawSettings, segments: string[], value: unknown): void {
-	let current = obj;
-	for (let i = 0; i < segments.length - 1; i++) {
-		const segment = segments[i];
-		if (!(segment in current) || typeof current[segment] !== "object" || current[segment] === null) {
-			current[segment] = {};
-		}
-		current = current[segment] as RawSettings;
-	}
-	current[segments[segments.length - 1]] = value;
-}
-
 const PATH_SCOPED_ARRAY_SETTINGS = new Set<SettingPath>(["enabledModels", "disabledProviders"]);
 const LEGACY_THEME_NAME_REPLACEMENTS = {
 	dark: "red-claw",
@@ -144,18 +191,37 @@ function stringArrayFromUnknown(value: unknown): string[] {
 	return [];
 }
 
-function shallowStringRecord(value: unknown): Record<string, string> {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+function rawSettingsRecord(value: unknown): RawSettings | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	return value as RawSettings;
+}
+
+function shallowModelSelectorRecord(value: unknown): Record<string, ModelSelectorValue> {
+	const record = rawSettingsRecord(value);
+	if (!record) return {};
 
-	const result: Record<string, string> = {};
-	for (const [key, item] of Object.entries(value)) {
-		if (typeof item === "string") {
-			result[key] = item;
-		}
+	const result: Record<string, ModelSelectorValue> = {};
+	for (const [key, item] of Object.entries(record)) {
+		if (isModelSelectorValue(item)) result[key] = Array.isArray(item) ? [...item] : item;
 	}
 	return result;
 }
 
+function legacyFallbackChains(value: unknown): Record<string, unknown> {
+	return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+}
+
+function hasOwnModelRole(source: RawSettings, role: string): boolean {
+	const roles = getByPath(source, ["modelRoles"]);
+	return !!roles && typeof roles === "object" && !Array.isArray(roles) && Object.hasOwn(roles, role);
+}
+
+function selectorChain(value: unknown): string[] {
+	if (typeof value === "string") return normalizeModelSelectorValue(value);
+	if (!Array.isArray(value) || !value.every(item => typeof item === "string")) return [];
+	return normalizeModelSelectorValue(value);
+}
+
 function resolvePathScopedStringArray(settingPath: SettingPath, value: unknown, cwd: string): string[] | undefined {
 	if (!PATH_SCOPED_ARRAY_SETTINGS.has(settingPath) || !Array.isArray(value)) return undefined;
 
@@ -193,12 +259,79 @@ function resolvePathScopedStringArray(settingPath: SettingPath, value: unknown,
 
 	return resolved;
 }
+type DefaultModelRoleOwnership = {
+	generation: number;
+	configVersion?: string;
+	defaultConfigVersion?: string;
+	defaultLineageKnown: boolean;
+};
+
+function readConfigVersion(filePath: string): string | undefined {
+	try {
+		const stat = fs.statSync(filePath, { bigint: true });
+		return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}`;
+	} catch (error) {
+		if (isEnoent(error)) return undefined;
+		throw error;
+	}
+}
+
+function defaultModelRoleFrom(raw: RawSettings): ModelSelectorValue | undefined {
+	const value = rawSettingsRecord(raw.modelRoles)?.default;
+	return isModelSelectorValue(value) ? (Array.isArray(value) ? [...value] : value) : undefined;
+}
+
+function setRawModelRole(
+	raw: RawSettings,
+	role: string,
+	modelId: ModelSelectorValue | undefined,
+	removeContainerWhenEmpty = false,
+): void {
+	const roles = { ...rawSettingsRecord(raw.modelRoles) };
+	if (modelId === undefined) {
+		delete roles[role];
+		if (removeContainerWhenEmpty && Object.keys(roles).length === 0) {
+			delete raw.modelRoles;
+		} else {
+			raw.modelRoles = roles;
+		}
+		return;
+	}
+	raw.modelRoles = { ...roles, [role]: modelId };
+}
+
+function updateModelRolesPatch(
+	patch: SettingsPatch,
+	role: string,
+	modelId: ModelSelectorValue | undefined,
+	removeContainerWhenEmpty = false,
+): SettingsPatch {
+	const raw: RawSettings = { modelRoles: structuredClone(patch.value) };
+	setRawModelRole(raw, role, modelId, removeContainerWhenEmpty);
+	return { ...patch, value: raw.modelRoles };
+}
+
+function settingsPatchKey(patch: SettingsPatch): string {
+	return patch.modelRole ? `modelRoles.${patch.modelRole}` : patch.path;
+}
+
+function applySettingsPatch(raw: RawSettings, patch: SettingsPatch): void {
+	if (patch.modelRole) {
+		setRawModelRole(raw, patch.modelRole, patch.value as ModelSelectorValue | undefined);
+		return;
+	}
+	if (patch.value === undefined) {
+		deleteByPath(raw, patch.path.split("."));
+		return;
+	}
+	setByPath(raw, patch.path.split("."), patch.value);
+}
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Settings Class
 // ═══════════════════════════════════════════════════════════════════════════
 
-export class Settings {
+export class Settings implements NotificationSettingsReader {
 	#configPath: string | null;
 	#cwd: string;
 	#agentDir: string;
@@ -216,12 +349,19 @@ export class Settings {
 	/** Latest dirty patch for each path, owned by its generation. */
 	#modified = new Map<string, SettingsPatch>();
 	#nextGeneration = 0;
-
-	/** Pending save (debounced) */
+	#pathRevisions = new Map<string, number>();
+	#nextRevision = 0;
+	#defaultModelRoleOwnership: DefaultModelRoleOwnership = { generation: 0, defaultLineageKnown: true };
+	/** Pending debounced ordinary save; its queue slot is reserved immediately. */
 	#saveTimer?: NodeJS.Timeout;
-	#saveTail: Promise<void> = Promise.resolve();
+	#savePromise?: Promise<void>;
+	#pendingSaveSlot?: PendingSaveSlot;
 	#globalModelRoleTail: Promise<void> = Promise.resolve();
 
+	/** Legacy fallback migration warnings emitted once per settings instance. */
+	#legacyFallbackMigrationWarnings = 0;
+	#legacyFallbackMigrationGlobalFingerprint: string | undefined;
+
 	/** Whether to persist changes */
 	#persist: boolean;
 
@@ -233,7 +373,8 @@ export class Settings {
 
 		if (options.overrides) {
 			for (const [key, value] of Object.entries(options.overrides)) {
-				setByPath(this.#overrides, key.split("."), value);
+				if (isNotificationSettingsPath(key)) throw new NotificationSettingsOverrideError(key as SettingPath);
+				setByPath(this.#overrides, key.split("."), structuredClone(value));
 			}
 		}
 	}
@@ -267,11 +408,18 @@ export class Settings {
 	}
 
 	/**
-	 * Create an isolated instance for testing.
+	 * Create an isolated instance for testing with explicit user/global settings.
 	 * Does not affect the global singleton.
 	 */
-	static isolated(overrides: Partial<Record<SettingPath, unknown>> = {}): Settings {
-		const instance = new Settings({ inMemory: true, overrides });
+	static isolated(
+		globalSettings: Partial<Record<SettingPath, unknown>> = {},
+		options: IsolatedSettingsOptions = {},
+	): Settings {
+		const instance = new Settings({ inMemory: true, overrides: options.overrides });
+		for (const [key, value] of Object.entries(globalSettings)) {
+			setByPath(instance.#global, key.split("."), structuredClone(value));
+		}
+
 		instance.#rebuildMerged();
 		return instance;
 	}
@@ -316,6 +464,113 @@ export class Settings {
 		return value === undefined ? undefined : (value as SettingValue<P>);
 	}
 
+	/**
+	 * Read the remote-notification settings from the user/global layer only.
+	 * Schema defaults are applied per path; project settings and runtime overrides
+	 * are deliberately excluded from this trust boundary.
+	 */
+	getNotificationSettingsSnapshot(): NotificationSettingsSnapshot {
+		const enabled = this.#getGlobalResolved("notifications.enabled");
+		const botToken = this.#getGlobalResolved("notifications.telegram.botToken");
+		const chatId = this.#getGlobalResolved("notifications.telegram.chatId");
+		const activation = this.#getGlobalResolved("notifications.telegram.activation");
+		const activationSnapshot =
+			activation && Object.keys(activation).length > 0 ? structuredClone(activation) : undefined;
+		const richEnabled = this.#getGlobalResolved("notifications.telegram.rich.enabled");
+		const richDraftEnabled = this.#getGlobalResolved("notifications.telegram.richDraft.enabled");
+		const nameTemplate = this.#getGlobalResolved("notifications.telegram.topics.nameTemplate");
+		const discordBotToken = this.#getGlobalResolved("notifications.discord.botToken");
+		const discordApplicationId = this.#getGlobalResolved("notifications.discord.applicationId");
+		const discordGuildId = this.#getGlobalResolved("notifications.discord.guildId");
+		const discordParentChannelId = this.#getGlobalResolved("notifications.discord.parentChannelId");
+		const slackBotToken = this.#getGlobalResolved("notifications.slack.botToken");
+		const slackAppToken = this.#getGlobalResolved("notifications.slack.appToken");
+		const slackWorkspaceId = this.#getGlobalResolved("notifications.slack.workspaceId");
+		const slackChannelId = this.#getGlobalResolved("notifications.slack.channelId");
+		const slackAuthorizedUserId = this.#getGlobalResolved("notifications.slack.authorizedUserId");
+		const redact = this.#getGlobalResolved("notifications.redact");
+		const verbosity = this.#getGlobalResolved("notifications.verbosity");
+		const sessionScope = this.#getGlobalResolved("notifications.sessionScope");
+		const idleTimeoutMs = this.#getGlobalResolved("notifications.daemon.idleTimeoutMs");
+
+		return {
+			enabled: typeof enabled === "boolean" ? enabled : getDefault("notifications.enabled"),
+			telegram: {
+				botToken:
+					typeof botToken === "string" && botToken.length > 0
+						? botToken
+						: getDefault("notifications.telegram.botToken"),
+				chatId:
+					typeof chatId === "string" && chatId.length > 0 ? chatId : getDefault("notifications.telegram.chatId"),
+				...(activationSnapshot === undefined ? {} : { activation: activationSnapshot }),
+				rich: {
+					enabled:
+						typeof richEnabled === "boolean" ? richEnabled : getDefault("notifications.telegram.rich.enabled"),
+				},
+				richDraft: {
+					enabled:
+						typeof richDraftEnabled === "boolean"
+							? richDraftEnabled
+							: getDefault("notifications.telegram.richDraft.enabled"),
+				},
+				topics: {
+					nameTemplate:
+						typeof nameTemplate === "string" && nameTemplate.length > 0
+							? nameTemplate
+							: getDefault("notifications.telegram.topics.nameTemplate"),
+				},
+			},
+			discord: {
+				botToken:
+					typeof discordBotToken === "string" && discordBotToken.length > 0
+						? discordBotToken
+						: getDefault("notifications.discord.botToken"),
+				applicationId:
+					typeof discordApplicationId === "string" && discordApplicationId.length > 0
+						? discordApplicationId
+						: getDefault("notifications.discord.applicationId"),
+				guildId:
+					typeof discordGuildId === "string" && discordGuildId.length > 0
+						? discordGuildId
+						: getDefault("notifications.discord.guildId"),
+				parentChannelId:
+					typeof discordParentChannelId === "string" && discordParentChannelId.length > 0
+						? discordParentChannelId
+						: getDefault("notifications.discord.parentChannelId"),
+			},
+			slack: {
+				botToken:
+					typeof slackBotToken === "string" && slackBotToken.length > 0
+						? slackBotToken
+						: getDefault("notifications.slack.botToken"),
+				appToken:
+					typeof slackAppToken === "string" && slackAppToken.length > 0
+						? slackAppToken
+						: getDefault("notifications.slack.appToken"),
+				workspaceId:
+					typeof slackWorkspaceId === "string" && slackWorkspaceId.length > 0
+						? slackWorkspaceId
+						: getDefault("notifications.slack.workspaceId"),
+				channelId:
+					typeof slackChannelId === "string" && slackChannelId.length > 0
+						? slackChannelId
+						: getDefault("notifications.slack.channelId"),
+				authorizedUserId:
+					typeof slackAuthorizedUserId === "string" && slackAuthorizedUserId.length > 0
+						? slackAuthorizedUserId
+						: getDefault("notifications.slack.authorizedUserId"),
+			},
+			redact: typeof redact === "boolean" ? redact : getDefault("notifications.redact"),
+			verbosity: verbosity === "verbose" || getDefault("notifications.verbosity") === "verbose" ? "verbose" : "lean",
+			sessionScope:
+				sessionScope === "primary" || getDefault("notifications.sessionScope") === "primary" ? "primary" : "all",
+			idleTimeoutMs:
+				typeof idleTimeoutMs === "number" && Number.isFinite(idleTimeoutMs) && idleTimeoutMs > 0
+					? idleTimeoutMs
+					: getDefault("notifications.daemon.idleTimeoutMs"),
+		};
+	}
+
 	/** Check whether a setting is present in loaded settings/overrides rather than coming from schema defaults. */
 	has(path: SettingPath): boolean {
 		return getByPath(this.#merged, path.split(".")) !== undefined;
@@ -323,25 +578,175 @@ export class Settings {
 
 	/**
 	 * Set a setting value (sync).
-	 * Updates global settings and queues a background save.
-	 * Triggers hooks for settings that have side effects.
+	 * Updates global settings and reserves its background persistence slot before
+	 * returning, so later durable batches cannot overtake this mutation.
 	 */
-	set<P extends SettingPath>(path: P, value: SettingValue<P>): void {
+	set<P extends SettingPath>(path: P, value: SettingValue<P> | undefined): void {
+		if (value === undefined) {
+			this.unset(path);
+			return;
+		}
+		this.#set(path, value, true);
+	}
+
+	#set<P extends SettingPath>(path: P, value: SettingValue<P>, defaultModelRoleMayHaveChanged: boolean): void {
 		const prev = this.get(path);
+		const clonedValue = structuredClone(value);
+		let modelRoleRevision: number | undefined;
+		if (path === "modelRoles" && defaultModelRoleMayHaveChanged) {
+			this.#defaultModelRoleOwnership.generation += 1;
+			modelRoleRevision = this.#defaultModelRoleOwnership.generation;
+		}
 		const patch: SettingsPatch = {
 			path,
-			value: structuredClone(value),
+			value: clonedValue,
 			generation: ++this.#nextGeneration,
+			revision: ++this.#nextRevision,
+			modelRoleRevision,
+			configVersion: this.#defaultModelRoleOwnership.configVersion,
 		};
-		setByPath(this.#global, path.split("."), structuredClone(patch.value));
+		setByPath(this.#global, path.split("."), structuredClone(clonedValue));
+		this.#pathRevisions.set(path, patch.revision);
 		this.#modified.set(path, patch);
+
 		this.#rebuildMerged();
 		this.#queueSave();
 
-		// Trigger hook if exists
 		const hook = SETTING_HOOKS[path];
-		if (hook) {
-			hook(value, prev);
+		if (hook) hook(value, prev);
+	}
+
+	/**
+	 * Delete a global setting (sync), rather than serializing an ambiguous YAML
+	 * `undefined` value. Defaults/project settings become visible immediately.
+	 */
+	unset<P extends SettingPath>(path: P): void {
+		const prev = this.get(path);
+		let modelRoleRevision: number | undefined;
+		if (path === "modelRoles") {
+			this.#defaultModelRoleOwnership.generation += 1;
+			modelRoleRevision = this.#defaultModelRoleOwnership.generation;
+		}
+		const patch: SettingsPatch = {
+			path,
+			value: undefined,
+			generation: ++this.#nextGeneration,
+			revision: ++this.#nextRevision,
+			modelRoleRevision,
+			configVersion: this.#defaultModelRoleOwnership.configVersion,
+		};
+		deleteByPath(this.#global, path.split("."));
+		this.#pathRevisions.set(path, patch.revision);
+		this.#modified.set(path, patch);
+		this.#rebuildMerged();
+		this.#queueSave();
+
+		const hook = SETTING_HOOKS[path];
+		if (hook) hook(this.get(path), prev);
+	}
+
+	/**
+	 * Persist a tagged batch as one atomic YAML replacement. Unlike ordinary
+	 * {@link set}, canonical state and hooks change only after the rename succeeds.
+	 */
+	async commitAtomicBatch(patches: readonly SettingsAtomicPatch[]): Promise<CasReceipt> {
+		if (!this.#persist || !this.#configPath) {
+			throw new Error("commitAtomicBatch requires persistent Settings with a config.yml path.");
+		}
+
+		const durablePatches: AtomicYamlPatch[] = patches.map(patch => {
+			if (!Object.hasOwn(SETTINGS_SCHEMA, patch.path)) {
+				throw new Error(`Unknown setting path for atomic batch: ${patch.path}`);
+			}
+			if (patch.op === "unset") return { path: patch.path, op: "unset" };
+			if (patch.value === undefined) {
+				throw new TypeError(`Settings set patch for ${patch.path} cannot carry undefined; use unset instead.`);
+			}
+			return { path: patch.path, op: "set", value: structuredClone(patch.value) };
+		});
+
+		// A durable batch is a causal barrier: close the earlier ordinary debounce
+		// inside its already-reserved slot before queueing this batch.
+		this.#releasePendingSaveSlot();
+
+		const revisions = durablePatches.map(patch => ({
+			patch,
+			revision: ++this.#nextRevision,
+			previousRevision: this.#pathRevisions.get(patch.path),
+		}));
+		for (const entry of revisions) this.#pathRevisions.set(entry.patch.path, entry.revision);
+
+		try {
+			const receipt = await applyAtomicYamlPatches(this.#configPath, durablePatches, {
+				onRestored: restoredPatches => this.#applyRestoredDurableBatch(revisions, restoredPatches),
+			});
+			this.#applyDurableBatch(revisions);
+			return receipt;
+		} catch (error) {
+			for (const entry of revisions) {
+				if (this.#pathRevisions.get(entry.patch.path) === entry.revision) {
+					if (entry.previousRevision === undefined) this.#pathRevisions.delete(entry.patch.path);
+					else this.#pathRevisions.set(entry.patch.path, entry.previousRevision);
+				}
+			}
+			if (this.#modified.size > 0 && !this.#pendingSaveSlot) this.#queueSave();
+			throw error;
+		}
+	}
+
+	/** Build a durable batch from the current on-disk YAML under the shared queue and file lock. */
+	async commitAtomicBatchWithCurrent(
+		buildPatches: (
+			current: Readonly<RawSettings>,
+		) => Promise<readonly SettingsAtomicPatch[]> | readonly SettingsAtomicPatch[],
+	): Promise<CasReceipt> {
+		if (!this.#persist || !this.#configPath) {
+			const patches = await buildPatches(structuredClone(this.#global));
+			return this.commitAtomicBatch(patches);
+		}
+
+		this.#releasePendingSaveSlot();
+		let revisions: DurableBatchRevision[] = [];
+		try {
+			const receipt = await applyAtomicYamlPatchesWithCurrent(
+				this.#configPath,
+				async current => {
+					const patches = await buildPatches(structuredClone(current));
+					const durablePatches: AtomicYamlPatch[] = patches.map(patch => {
+						if (!Object.hasOwn(SETTINGS_SCHEMA, patch.path)) {
+							throw new Error(`Unknown setting path for atomic batch: ${patch.path}`);
+						}
+						if (patch.op === "unset") return { path: patch.path, op: "unset" };
+						if (patch.value === undefined) {
+							throw new TypeError(
+								`Settings set patch for ${patch.path} cannot carry undefined; use unset instead.`,
+							);
+						}
+						return { path: patch.path, op: "set", value: structuredClone(patch.value) };
+					});
+					revisions = durablePatches.map(patch => ({
+						patch,
+						revision: ++this.#nextRevision,
+						previousRevision: this.#pathRevisions.get(patch.path),
+					}));
+					for (const entry of revisions) this.#pathRevisions.set(entry.patch.path, entry.revision);
+					return durablePatches;
+				},
+				{
+					onRestored: restoredPatches => this.#applyRestoredDurableBatch(revisions, restoredPatches),
+				},
+			);
+			this.#applyDurableBatch(revisions);
+			return receipt;
+		} catch (error) {
+			for (const entry of revisions) {
+				if (this.#pathRevisions.get(entry.patch.path) === entry.revision) {
+					if (entry.previousRevision === undefined) this.#pathRevisions.delete(entry.patch.path);
+					else this.#pathRevisions.set(entry.patch.path, entry.previousRevision);
+				}
+			}
+			if (this.#modified.size > 0 && !this.#pendingSaveSlot) this.#queueSave();
+			throw error;
 		}
 	}
 
@@ -349,8 +754,9 @@ export class Settings {
 	 * Apply runtime overrides (not persisted).
 	 */
 	override<P extends SettingPath>(path: P, value: SettingValue<P>): void {
-		const segments = path.split(".");
-		setByPath(this.#overrides, segments, value);
+		if (isNotificationSettingsPath(path)) throw new NotificationSettingsOverrideError(path);
+		const clonedValue = structuredClone(value);
+		setByPath(this.#overrides, path.split("."), clonedValue);
 		this.#rebuildMerged();
 	}
 
@@ -369,45 +775,58 @@ export class Settings {
 		this.#rebuildMerged();
 	}
 
-	/**
-	 * Flush any pending saves to disk.
-	 * Call before exit to ensure all changes are persisted.
-	 */
+	/** Flush a reserved debounced save without allowing it to be overtaken. */
 	async flush(): Promise<void> {
-		if (this.#saveTimer) {
-			clearTimeout(this.#saveTimer);
-			this.#saveTimer = undefined;
+		this.#releasePendingSaveSlot();
+		if (this.#modified.size > 0 && !this.#pendingSaveSlot) this.#queueSave();
+		this.#releasePendingSaveSlot();
+		const observedSave = this.#savePromise;
+		try {
+			await observedSave;
+		} catch {
+			// Historical flush() behavior logs background failures but does not reject.
+		}
+		// A failed predecessor may settle just before a new mutation observes its
+		// still-reserved slot. Explicit flush owns one fresh attempt for remaining
+		// dirty patches instead of leaving them stranded or retrying forever.
+		if (this.#modified.size > 0 && this.#savePromise === observedSave) {
+			if (!this.#pendingSaveSlot) this.#queueSave();
+			this.#releasePendingSaveSlot();
+			try {
+				await this.#savePromise;
+			} catch {
+				// Keep dirty state for a later explicit flush or mutation.
+			}
 		}
-		const save = this.#modified.size > 0 ? this.#saveNow() : this.#saveTail;
-		await save;
+		await this.#refreshDurableSettings();
 	}
 
-	/**
-	 * Like {@link flush}, but rejects if the durable save fails instead of
-	 * swallowing the error. Use where the caller must confirm persistence before
-	 * reporting success (e.g. the Telegram `/rich` toggle). In-memory instances
-	 * ({@link isolated}) short-circuit in {@link #saveNow} and never throw.
-	 */
+	/** Like {@link flush}, but reports a durable save failure to the caller. */
 	async flushOrThrow(): Promise<void> {
-		if (this.#saveTimer) {
-			clearTimeout(this.#saveTimer);
-			this.#saveTimer = undefined;
-		}
-		const save = this.#modified.size > 0 ? this.#saveNow({ throwOnError: true }) : this.#saveTail;
-		await save;
+		this.#releasePendingSaveSlot();
+		if (this.#modified.size > 0 && !this.#pendingSaveSlot) this.#queueSave();
+		this.#releasePendingSaveSlot();
+		await this.#savePromise;
+		await this.#refreshDurableSettings();
 	}
 
 	async cloneForCwd(cwd: string): Promise<Settings> {
+		// A clone shares the same config queue. Settle an already-reserved local
+		// debounce before the clone can enqueue a durable selector, preventing it
+		// from waiting behind a slot only this instance can open.
+		await this.flush();
 		const cloned = new Settings({
 			cwd,
 			agentDir: this.#agentDir,
 			inMemory: !this.#persist,
 		});
 		cloned.#storage = this.#storage;
+		cloned.#defaultModelRoleOwnership = this.#defaultModelRoleOwnership;
+
 		cloned.#global = structuredClone(this.#global);
 		cloned.#project = this.#persist ? await cloned.#loadProjectSettings() : structuredClone(this.#project);
 		cloned.#overrides = structuredClone(this.#overrides);
-		cloned.#rebuildMerged();
+		await cloned.#normalizeAfterLoad();
 		cloned.#fireAllHooks();
 		return cloned;
 	}
@@ -483,7 +902,7 @@ export class Settings {
 	/**
 	 * Set a model role (helper for modelRoles record).
 	 */
-	setModelRole(role: ModelRole | string, modelId: string): void {
+	setModelRole(role: ModelRole | string, modelId: ModelSelectorValue): void {
 		const runtimeOverrides = getByPath(this.#overrides, ["modelRoles"]);
 		const updateRuntimeOverride =
 			!!runtimeOverrides &&
@@ -494,52 +913,210 @@ export class Settings {
 		this.setGlobalModelRole(role, modelId);
 
 		if (updateRuntimeOverride) {
-			this.override("modelRoles", { ...shallowStringRecord(runtimeOverrides), [role]: modelId });
+			this.override("modelRoles", { ...shallowModelSelectorRecord(runtimeOverrides), [role]: modelId });
 		}
 	}
 
-	setGlobalModelRole(role: ModelRole | string, modelId: string | undefined): void {
-		const current = shallowStringRecord(getByPath(this.#global, ["modelRoles"]));
-		if (modelId === undefined) {
-			const { [role]: _removed, ...remaining } = current;
-			this.set("modelRoles", remaining);
-			return;
+	setGlobalModelRole(role: ModelRole | string, modelId: ModelSelectorValue | undefined): void {
+		let modelRoleRevision: number | undefined;
+		if (role === "default") {
+			this.#defaultModelRoleOwnership.generation += 1;
+			modelRoleRevision = this.#defaultModelRoleOwnership.generation;
 		}
-		this.set("modelRoles", { ...current, [role]: modelId });
+		const revision = ++this.#nextRevision;
+		const patch: SettingsPatch = {
+			path: "modelRoles",
+			value: modelId,
+			generation: ++this.#nextGeneration,
+			revision,
+			modelRole: role,
+			modelRoleRevision,
+			configVersion: this.#defaultModelRoleOwnership.configVersion,
+		};
+		setRawModelRole(this.#global, role, modelId);
+		this.#pathRevisions.set("modelRoles", revision);
+		this.#modified.set(settingsPatchKey(patch), patch);
+		this.#rebuildMerged();
+		this.#queueSave();
 	}
 
-	setGlobalModelRoleAndFlush(role: ModelRole | string, modelId: string | undefined): Promise<void> {
-		const transaction = this.#globalModelRoleTail.then(async () => {
-			const hadModelRoles = Object.hasOwn(this.#global, "modelRoles");
-			const previousModelRoles = structuredClone(this.#global.modelRoles);
-			const previousPatch = this.#modified.get("modelRoles");
-			this.setGlobalModelRole(role, modelId);
-			const generation = this.#modified.get("modelRoles")?.generation;
-			if (this.#saveTimer) {
-				clearTimeout(this.#saveTimer);
-				this.#saveTimer = undefined;
-			}
-			const save = this.#saveNow({ throwOnError: true });
-			try {
-				await save;
-			} catch (error) {
-				const currentPatch = this.#modified.get("modelRoles");
-				if (currentPatch?.generation === generation) {
-					if (hadModelRoles) this.#global.modelRoles = previousModelRoles;
-					else delete this.#global.modelRoles;
-					if (previousPatch) this.#modified.set("modelRoles", previousPatch);
-					else this.#modified.delete("modelRoles");
-					this.#rebuildMerged();
-				}
-				throw error;
-			}
-		});
+	setGlobalModelRoleAndFlush(
+		role: ModelRole | string,
+		modelId: ModelSelectorValue | undefined,
+	): Promise<GlobalDefaultModelRoleCommit> {
+		const transaction = this.#globalModelRoleTail.then(() => this.#commitGlobalModelRoleAndFlush(role, modelId));
 		this.#globalModelRoleTail = transaction.then(
 			() => undefined,
 			() => undefined,
 		);
 		return transaction;
 	}
+
+	restoreGlobalDefaultModelRoleIfCurrent(commit: GlobalDefaultModelRoleCommit): Promise<boolean> {
+		const transaction = this.#globalModelRoleTail.then(() => this.#restoreGlobalDefaultModelRoleIfCurrent(commit));
+		this.#globalModelRoleTail = transaction.then(
+			() => undefined,
+			() => undefined,
+		);
+		return transaction;
+	}
+
+	async #commitGlobalModelRoleAndFlush(
+		role: ModelRole | string,
+		modelId: ModelSelectorValue | undefined,
+	): Promise<GlobalDefaultModelRoleCommit> {
+		if (this.#persist) await this.flushOrThrow();
+		const previousDefault = defaultModelRoleFrom(this.#global);
+		const previousModelRolesExisted = Object.hasOwn(this.#global, "modelRoles");
+		const previousDefaultRevision = this.#defaultModelRoleOwnership.generation;
+		let defaultRevision = previousDefaultRevision;
+		if (role === "default") {
+			defaultRevision += 1;
+			this.#defaultModelRoleOwnership.generation = defaultRevision;
+		}
+		this.#setGlobalModelRoleInMemory(role, modelId, false, true);
+
+		if (!this.#persist || !this.#configPath) {
+			return {
+				previousDefault,
+				previousModelRolesExisted,
+				committedDefault: defaultModelRoleFrom(this.#global),
+				defaultRevision,
+				committedConfigVersion: undefined,
+			};
+		}
+
+		let durableBeforeWrite: RawSettings | undefined;
+		let durableVersionBeforeWrite: string | undefined;
+		try {
+			const result = await reserveAtomicYamlUpdateSlot(this.#configPath, () => ({
+				apply: current => {
+					durableBeforeWrite = structuredClone(current);
+					durableVersionBeforeWrite = readConfigVersion(this.#configPath!);
+					const durablePreviousDefault = defaultModelRoleFrom(current);
+					const durablePreviousModelRolesExisted = Object.hasOwn(current, "modelRoles");
+					setRawModelRole(current, role, modelId);
+					return {
+						durablePreviousDefault,
+						durablePreviousModelRolesExisted,
+						committedDefault: defaultModelRoleFrom(current),
+						committedConfigVersion: undefined as string | undefined,
+						defaultRevision,
+					};
+				},
+				committed: (current, result) => {
+					const committedConfigVersion = readConfigVersion(this.#configPath!);
+					this.#replaceGlobalWithDurable(
+						current,
+						committedConfigVersion,
+						role === "default",
+						durableVersionBeforeWrite,
+					);
+					result.committedConfigVersion = committedConfigVersion;
+				},
+			}));
+			return {
+				previousDefault: result.durablePreviousDefault,
+				previousModelRolesExisted: result.durablePreviousModelRolesExisted,
+				committedDefault: result.committedDefault,
+				committedConfigVersion: result.committedConfigVersion,
+				defaultRevision: result.defaultRevision,
+			};
+		} catch (error) {
+			if (role === "default" && this.#defaultModelRoleOwnership.generation === defaultRevision) {
+				if (durableBeforeWrite) {
+					this.#replaceGlobalWithDurable(durableBeforeWrite, durableVersionBeforeWrite, false);
+				} else {
+					this.#setGlobalModelRoleInMemory("default", previousDefault, !previousModelRolesExisted, true);
+				}
+				this.#defaultModelRoleOwnership.generation = previousDefaultRevision;
+			}
+			throw error;
+		}
+	}
+
+	async #restoreGlobalDefaultModelRoleIfCurrent(commit: GlobalDefaultModelRoleCommit): Promise<boolean> {
+		if (this.#defaultModelRoleOwnership.generation !== commit.defaultRevision) return false;
+
+		if (!this.#persist || !this.#configPath) {
+			if (defaultModelRoleFrom(this.#global) !== commit.committedDefault) return false;
+			this.#setGlobalModelRoleInMemory("default", commit.previousDefault, !commit.previousModelRolesExisted);
+			this.#defaultModelRoleOwnership.generation += 1;
+			return true;
+		}
+
+		const restored = await reserveAtomicYamlUpdateSlot(this.#configPath, () => ({
+			apply: current => {
+				if (this.#defaultModelRoleOwnership.generation !== commit.defaultRevision) return false;
+				const currentConfigVersion = readConfigVersion(this.#configPath!);
+				if (defaultModelRoleFrom(current) !== commit.committedDefault) return false;
+				if (
+					commit.committedConfigVersion !== undefined &&
+					currentConfigVersion !== commit.committedConfigVersion &&
+					!(
+						this.#defaultModelRoleOwnership.defaultConfigVersion === commit.committedConfigVersion &&
+						this.#defaultModelRoleOwnership.defaultLineageKnown &&
+						this.#defaultModelRoleOwnership.configVersion === currentConfigVersion
+					)
+				) {
+					return false;
+				}
+				setRawModelRole(current, "default", commit.previousDefault, !commit.previousModelRolesExisted);
+				return { currentConfigVersion };
+			},
+			shouldWrite: result => result !== false,
+			committed: (current, result) => {
+				if (result === false) return;
+				const restoredConfigVersion = readConfigVersion(this.#configPath!);
+				this.#replaceGlobalWithDurable(current, restoredConfigVersion, true, result.currentConfigVersion);
+				this.#defaultModelRoleOwnership.generation += 1;
+			},
+		}));
+		if (!restored) return false;
+		await this.flushOrThrow();
+		return true;
+	}
+
+	#setGlobalModelRoleInMemory(
+		role: string,
+		modelId: ModelSelectorValue | undefined,
+		removeContainerWhenEmpty: boolean,
+		updatePendingPatch = false,
+	): void {
+		setRawModelRole(this.#global, role, modelId, removeContainerWhenEmpty);
+		if (updatePendingPatch) {
+			const rootPatch = this.#modified.get("modelRoles");
+			if (rootPatch) {
+				this.#modified.set("modelRoles", updateModelRolesPatch(rootPatch, role, modelId, removeContainerWhenEmpty));
+			}
+			const rolePatch = this.#modified.get(`modelRoles.${role}`);
+			if (rolePatch) {
+				this.#modified.set(`modelRoles.${role}`, { ...rolePatch, value: modelId });
+			}
+		}
+		this.#rebuildMerged();
+	}
+
+	#replaceGlobalWithDurable(
+		current: RawSettings,
+		configVersion?: string,
+		defaultChanged = false,
+		predecessorConfigVersion = configVersion,
+	): void {
+		this.#global = current;
+		for (const patch of this.#pendingPatchesInGenerationOrder()) {
+			this.#applyPatchWithDefaultOwnership(this.#global, { ...patch, value: structuredClone(patch.value) });
+		}
+		const externalLineageBreak = predecessorConfigVersion !== this.#defaultModelRoleOwnership.configVersion;
+		this.#defaultModelRoleOwnership.configVersion = configVersion;
+		if (defaultChanged) {
+			this.#defaultModelRoleOwnership.defaultConfigVersion = configVersion;
+			this.#defaultModelRoleOwnership.defaultLineageKnown = true;
+		} else if (externalLineageBreak) {
+			this.#defaultModelRoleOwnership.defaultLineageKnown = false;
+		}
+		this.#rebuildMerged();
+	}
 	/**
 	 * Set an agent model override while keeping any live runtime override aligned.
 	 *
@@ -547,8 +1124,8 @@ export class Settings {
 	 * session. A user-selected role assignment must win immediately in that same
 	 * session, but only the explicit agent change should be persisted.
 	 */
-	setAgentModelOverride(agentName: string, modelId: string): void {
-		const current = shallowStringRecord(getByPath(this.#global, ["task", "agentModelOverrides"]));
+	setAgentModelOverride(agentName: string, modelId: ModelSelectorValue): void {
+		const current = shallowModelSelectorRecord(getByPath(this.#global, ["task", "agentModelOverrides"]));
 		const runtimeOverrides = getByPath(this.#overrides, ["task", "agentModelOverrides"]);
 		const updateRuntimeOverride =
 			!!runtimeOverrides && typeof runtimeOverrides === "object" && !Array.isArray(runtimeOverrides);
@@ -557,7 +1134,7 @@ export class Settings {
 
 		if (updateRuntimeOverride) {
 			this.override("task.agentModelOverrides", {
-				...shallowStringRecord(runtimeOverrides),
+				...shallowModelSelectorRecord(runtimeOverrides),
 				[agentName]: modelId,
 			});
 		}
@@ -566,7 +1143,7 @@ export class Settings {
 	/**
 	 * Get a model role (helper for modelRoles record).
 	 */
-	getModelRole(role: ModelRole | string): string | undefined {
+	getModelRole(role: ModelRole | string): ModelSelectorValue | undefined {
 		const roles = this.get("modelRoles");
 		return roles[role];
 	}
@@ -574,19 +1151,17 @@ export class Settings {
 	/**
 	 * Get all model roles (helper for modelRoles record).
 	 */
-	getModelRoles(): ReadOnlyDict<string> {
+	getModelRoles(): Readonly<Record<string, ModelSelectorValue>> {
 		return { ...this.get("modelRoles") };
 	}
 
 	/*
 	 * Override model roles (helper for modelRoles record).
 	 */
-	overrideModelRoles(roles: ReadOnlyDict<string>): void {
-		const next = shallowStringRecord(getByPath(this.#overrides, ["modelRoles"]));
+	overrideModelRoles(roles: Readonly<Record<string, ModelSelectorValue>>): void {
+		const next = shallowModelSelectorRecord(getByPath(this.#overrides, ["modelRoles"]));
 		for (const [role, modelId] of Object.entries(roles)) {
-			if (modelId) {
-				next[role] = modelId;
-			}
+			if (modelId) next[role] = Array.isArray(modelId) ? [...modelId] : modelId;
 		}
 		this.override("modelRoles", next);
 	}
@@ -614,13 +1189,14 @@ export class Settings {
 			this.#storage = await AgentStorage.open(getAgentDbPath(this.#agentDir));
 			await this.#migrateFromLegacy();
 			this.#global = await this.#loadYaml(this.#configPath!);
+			const configVersion = readConfigVersion(this.#configPath!);
+			this.#defaultModelRoleOwnership.configVersion = configVersion;
+			this.#defaultModelRoleOwnership.defaultConfigVersion = configVersion;
 		}
 
 		this.#project = await projectPromise;
 
-		// Build merged view (global → project → overrides; project wins over global)
-		this.#rebuildMerged();
-		this.#fireAllHooks();
+		await this.#normalizeAfterLoad();
 		return this;
 	}
 
@@ -644,9 +1220,14 @@ export class Settings {
 			const result = await loadCapability(settingsCapability.id, { cwd: this.#cwd });
 			let merged: RawSettings = {};
 			for (const item of result.items as SettingsCapabilityItem[]) {
-				if (item.level === "project") {
-					merged = this.#deepMerge(merged, item.data as RawSettings);
+				if (item.level !== "project") continue;
+				const { settings, rejectedNotifications } = this.#stripProjectNotificationSettings(
+					item.data as RawSettings,
+				);
+				if (rejectedNotifications) {
+					logger.warn("Settings: ignoring project notification settings", { path: item.path });
 				}
+				merged = this.#deepMerge(merged, settings);
 			}
 			return this.#migrateRawSettings(merged);
 		} catch {
@@ -654,6 +1235,149 @@ export class Settings {
 		}
 	}
 
+	async #normalizeAfterLoad(): Promise<void> {
+		this.#sanitizeModelSelectorRecords();
+		this.#rebuildMerged();
+		this.#legacyFallbackMigrationGlobalFingerprint = YAML.stringify(this.#global, null, 2);
+		this.#migrateRetryFallbackChains();
+		if (
+			!this.#modified.has("modelRoles") &&
+			![...this.#modified.keys()].some(path => path.startsWith("retry.fallback"))
+		) {
+			this.#legacyFallbackMigrationGlobalFingerprint = undefined;
+		}
+		await this.flush();
+		this.#sanitizeModelSelectorRecords();
+		this.#rebuildMerged();
+		this.#fireAllHooks();
+	}
+
+	#sanitizeModelSelectorRecords(): void {
+		for (const source of [this.#global, this.#project, this.#overrides]) {
+			for (const pathSegments of [["modelRoles"], ["task", "agentModelOverrides"]]) {
+				const raw = getByPath(source, pathSegments);
+				if (raw === undefined) continue;
+				if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+					logger.warn("Settings: replaced malformed model selector record", { path: pathSegments.join(".") });
+					setByPath(source, pathSegments, {});
+					continue;
+				}
+				const sanitized = shallowModelSelectorRecord(raw);
+				if (Object.keys(sanitized).length !== Object.keys(raw).length) {
+					logger.warn("Settings: dropped invalid model selector values", {
+						path: pathSegments.join("."),
+						dropped: Object.keys(raw).filter(key => !(key in sanitized)),
+					});
+				}
+				setByPath(source, pathSegments, sanitized);
+			}
+		}
+	}
+
+	#migrateRetryFallbackChains(): void {
+		const globalChains = legacyFallbackChains(getByPath(this.#global, ["retry", "fallbackChains"]));
+		const projectChains = legacyFallbackChains(getByPath(this.#project, ["retry", "fallbackChains"]));
+		const overrideChains = legacyFallbackChains(getByPath(this.#overrides, ["retry", "fallbackChains"]));
+		const roles = new Set([
+			...Object.keys(globalChains),
+			...Object.keys(projectChains),
+			...Object.keys(overrideChains),
+		]);
+		const retainedGlobalChains: Record<string, unknown> = {};
+		const effectiveRoles = shallowModelSelectorRecord(getByPath(this.#merged, ["modelRoles"]));
+		for (const role of roles) {
+			const source = Object.hasOwn(overrideChains, role)
+				? "override"
+				: Object.hasOwn(projectChains, role)
+					? "project"
+					: "global";
+			const tailValue =
+				source === "override"
+					? overrideChains[role]
+					: source === "project"
+						? projectChains[role]
+						: globalChains[role];
+			const primary = selectorChain(effectiveRoles[role]);
+			const tail = selectorChain(tailValue);
+			const chain = [...new Set([...primary, ...tail])];
+			if (primary.length === 0 || tail.length === 0) {
+				this.#warnLegacyFallbackMigration(
+					`retry.fallbackChains.${role} could not be migrated because it lacks a valid primary selector or tail.`,
+				);
+				continue;
+			}
+			const target =
+				source === "override" || hasOwnModelRole(this.#overrides, role)
+					? this.#overrides
+					: source === "project" || hasOwnModelRole(this.#project, role)
+						? this.#project
+						: this.#global;
+			const targetRoles = shallowModelSelectorRecord(getByPath(target, ["modelRoles"]));
+			setByPath(target, ["modelRoles"], { ...targetRoles, [role]: chain });
+			if (target === this.#global) {
+				this.#recordLegacyFallbackMigrationPatch("modelRoles", getByPath(this.#global, ["modelRoles"]));
+			}
+			if (target !== this.#global && Object.hasOwn(globalChains, role))
+				retainedGlobalChains[role] = globalChains[role];
+			if (source === "project") {
+				this.#warnLegacyFallbackMigration(
+					`retry.fallbackChains.${role} is project-owned and was migrated in memory only.`,
+				);
+			}
+		}
+		for (const source of [this.#project, this.#overrides]) {
+			deleteByPath(source, ["retry", "fallbackChains"]);
+			deleteByPath(source, ["retry", "fallbackRevertPolicy"]);
+		}
+		if (Object.keys(retainedGlobalChains).length > 0) {
+			setByPath(this.#global, ["retry", "fallbackChains"], retainedGlobalChains);
+			this.#recordLegacyFallbackMigrationPatch("retry.fallbackChains", retainedGlobalChains);
+		} else if (getByPath(this.#global, ["retry", "fallbackChains"]) !== undefined) {
+			deleteByPath(this.#global, ["retry", "fallbackChains"]);
+			this.#recordLegacyFallbackMigrationPatch("retry.fallbackChains", undefined);
+		}
+		if (
+			Object.keys(retainedGlobalChains).length === 0 &&
+			getByPath(this.#global, ["retry", "fallbackRevertPolicy"]) !== undefined
+		) {
+			deleteByPath(this.#global, ["retry", "fallbackRevertPolicy"]);
+			this.#recordLegacyFallbackMigrationPatch("retry.fallbackRevertPolicy", undefined);
+		}
+		if (
+			Object.keys(retainedGlobalChains).length === 0 &&
+			this.#global.retry !== undefined &&
+			Object.keys(rawSettingsRecord(this.#global.retry) ?? {}).length === 0
+		) {
+			delete this.#global.retry;
+			this.#recordLegacyFallbackMigrationPatch("retry", undefined);
+		}
+		this.#rebuildMerged();
+	}
+
+	#recordLegacyFallbackMigrationPatch(path: string, value: unknown): void {
+		const existing = this.#modified.get(path);
+		if (existing && !existing.legacyFallbackMigration) {
+			this.#modified.set(path, { ...existing, value: structuredClone(value) });
+			return;
+		}
+		const revision = ++this.#nextRevision;
+		this.#pathRevisions.set(path, revision);
+		this.#modified.set(path, {
+			path,
+			value: structuredClone(value),
+			generation: ++this.#nextGeneration,
+			revision,
+			configVersion: this.#defaultModelRoleOwnership.configVersion,
+			legacyFallbackMigration: true,
+		});
+	}
+
+	#warnLegacyFallbackMigration(message: string): void {
+		if (this.#legacyFallbackMigrationWarnings >= 10) return;
+		this.#legacyFallbackMigrationWarnings++;
+		logger.warn(`Settings: ${message}`);
+	}
+
 	async #migrateFromLegacy(): Promise<void> {
 		if (!this.#configPath) return;
 
@@ -690,10 +1414,17 @@ export class Settings {
 			}
 		} catch {}
 
-		// 3. Write merged settings
+		// 3. Write merged settings through the shared atomic YAML pipeline.
 		if (migrated && Object.keys(settings).length > 0) {
 			try {
-				await Bun.write(this.#configPath, YAML.stringify(settings, null, 2));
+				await applyAtomicYamlPatches(
+					this.#configPath,
+					Object.entries(settings).map(([settingPath, value]) => ({
+						path: settingPath,
+						op: "set" as const,
+						value,
+					})),
+				);
 				logger.debug("Settings: migrated to config.yml", { path: this.#configPath });
 			} catch {}
 		}
@@ -870,59 +1601,257 @@ export class Settings {
 	#queueSave(): void {
 		if (!this.#persist || !this.#configPath) return;
 
+		const currentSlot = this.#pendingSaveSlot;
+		if (currentSlot && !currentSlot.captured && !currentSlot.released) {
+			this.#armSaveTimer(currentSlot);
+			return;
+		}
+
+		let release!: () => void;
+		const slot: PendingSaveSlot = {
+			captured: false,
+			released: false,
+			release: () => release(),
+			wait: new Promise<void>(resolve => {
+				release = resolve;
+			}),
+		};
+		this.#pendingSaveSlot = slot;
+
+		let captured: SettingsPatch[] = [];
+		let durableBeforeWrite: RawSettings | undefined;
+		let durableVersionBeforeWrite: string | undefined;
+		const save = reserveAtomicYamlUpdateSlot(this.#configPath, async () => {
+			await slot.wait;
+			slot.captured = true;
+			if (this.#pendingSaveSlot === slot) this.#pendingSaveSlot = undefined;
+			captured = this.#pendingPatchesInGenerationOrder();
+			return {
+				apply: current => {
+					this.#migrateRawSettings(current);
+					const migrationFingerprint = this.#legacyFallbackMigrationGlobalFingerprint;
+					this.#legacyFallbackMigrationGlobalFingerprint = undefined;
+					if (migrationFingerprint !== undefined && YAML.stringify(current, null, 2) !== migrationFingerprint) {
+						this.#global = structuredClone(current);
+						this.#rebuildMerged();
+						if (getByPath(current, ["retry", "fallbackChains"]) !== undefined) {
+							this.#defaultModelRoleOwnership.configVersion = readConfigVersion(this.#configPath!);
+							this.#defaultModelRoleOwnership.defaultLineageKnown = false;
+							this.#migrateRetryFallbackChains();
+							captured = this.#pendingPatchesInGenerationOrder();
+						} else {
+							for (const patch of captured) {
+								if (!patch.legacyFallbackMigration) continue;
+								const key = settingsPatchKey(patch);
+								if (this.#modified.get(key)?.generation === patch.generation) this.#modified.delete(key);
+							}
+							captured = captured.filter(patch => !patch.legacyFallbackMigration);
+						}
+					}
+					const currentConfigVersion = readConfigVersion(this.#configPath!);
+					durableBeforeWrite = structuredClone(current);
+					durableVersionBeforeWrite = currentConfigVersion;
+					const externalLineageBreak = currentConfigVersion !== this.#defaultModelRoleOwnership.configVersion;
+					const applicablePatches = captured.filter(
+						patch =>
+							!this.#isStaleDefaultModelRolePatch(patch, currentConfigVersion) || patch.modelRole !== "default",
+					);
+					const appliesDefault = applicablePatches.some(
+						patch =>
+							!this.#isStaleDefaultModelRolePatch(patch, currentConfigVersion) &&
+							(patch.modelRole === "default" || (patch.path === "modelRoles" && !patch.modelRole)),
+					);
+					for (const patch of applicablePatches) {
+						this.#applyPatchWithDefaultOwnership(current, patch, currentConfigVersion);
+					}
+					return { appliesDefault, externalLineageBreak, shouldWrite: applicablePatches.length > 0 };
+				},
+				shouldWrite: result => result.shouldWrite,
+				committed: (current, result) => {
+					const savedConfigVersion = readConfigVersion(this.#configPath!);
+					this.#defaultModelRoleOwnership.configVersion = savedConfigVersion;
+					if (result.appliesDefault) {
+						this.#defaultModelRoleOwnership.defaultConfigVersion = savedConfigVersion;
+						this.#defaultModelRoleOwnership.defaultLineageKnown = true;
+					} else if (result.externalLineageBreak) {
+						this.#defaultModelRoleOwnership.defaultLineageKnown = false;
+					}
+					for (const patch of captured) {
+						const key = settingsPatchKey(patch);
+						if (this.#modified.get(key)?.generation === patch.generation) {
+							this.#modified.delete(key);
+						}
+					}
+					this.#global = current;
+					for (const [key, patch] of [...this.#modified].sort(
+						(left, right) => left[1].generation - right[1].generation,
+					)) {
+						if (this.#isStaleDefaultModelRolePatch(patch, savedConfigVersion) && patch.modelRole === "default") {
+							this.#modified.delete(key);
+							continue;
+						}
+						this.#applyPatchWithDefaultOwnership(
+							this.#global,
+							{ ...patch, value: structuredClone(patch.value) },
+							savedConfigVersion,
+						);
+					}
+					this.#rebuildMerged();
+				},
+			};
+		}).then(() => undefined);
+		this.#savePromise = save;
+		void save.catch(error => {
+			logger.warn("Settings: background save failed", { error: String(error) });
+			let droppedStaleDefault = false;
+			for (const patch of captured) {
+				const key = settingsPatchKey(patch);
+				const currentPatch = this.#modified.get(key);
+				if (currentPatch?.generation !== patch.generation) continue;
+				if (
+					this.#isStaleDefaultModelRolePatch(patch, readConfigVersion(this.#configPath!)) &&
+					patch.modelRole === "default"
+				) {
+					this.#modified.delete(key);
+					droppedStaleDefault = true;
+				} else {
+					this.#modified.set(key, patch);
+				}
+			}
+			if (droppedStaleDefault && durableBeforeWrite) {
+				setRawModelRole(
+					this.#global,
+					"default",
+					defaultModelRoleFrom(durableBeforeWrite),
+					!Object.hasOwn(durableBeforeWrite, "modelRoles"),
+				);
+				this.#defaultModelRoleOwnership.configVersion = durableVersionBeforeWrite;
+				this.#defaultModelRoleOwnership.defaultLineageKnown = false;
+				this.#rebuildMerged();
+			}
+		});
+		this.#armSaveTimer(slot);
+	}
+
+	#armSaveTimer(slot: PendingSaveSlot): void {
 		if (this.#saveTimer) clearTimeout(this.#saveTimer);
 		this.#saveTimer = setTimeout(() => {
 			this.#saveTimer = undefined;
-			void this.#saveNow();
+			if (slot.released) return;
+			slot.released = true;
+			slot.release();
 		}, 100);
 	}
 
-	async #saveNow(options: { throwOnError?: boolean } = {}): Promise<void> {
-		if (!this.#persist || !this.#configPath || this.#modified.size === 0) return;
+	#isStaleDefaultModelRolePatch(
+		patch: SettingsPatch,
+		currentConfigVersion = this.#defaultModelRoleOwnership.configVersion,
+	): boolean {
+		const changesDefault = patch.modelRole === "default" || (patch.path === "modelRoles" && !patch.modelRole);
+		const generationChanged =
+			patch.modelRoleRevision !== undefined &&
+			patch.modelRoleRevision !== this.#defaultModelRoleOwnership.generation;
+		const externalConfigChanged =
+			patch.configVersion !== currentConfigVersion &&
+			(this.#defaultModelRoleOwnership.configVersion !== currentConfigVersion ||
+				!this.#defaultModelRoleOwnership.defaultLineageKnown);
+		return changesDefault && (generationChanged || externalConfigChanged);
+	}
 
-		const configPath = this.#configPath;
-		const patches = [...this.#modified.values()];
+	#pendingPatchesInGenerationOrder(): SettingsPatch[] {
+		return [...this.#modified.values()].sort((left, right) => left.generation - right.generation);
+	}
 
-		const save = this.#saveTail.then(() =>
-			withFileLock(configPath, async () => {
-				const current = await this.#loadYaml(configPath);
-				for (const patch of patches) {
-					setByPath(current, patch.path.split("."), patch.value);
-				}
-				await Bun.write(configPath, YAML.stringify(current, null, 2));
-				for (const patch of patches) {
-					if (this.#modified.get(patch.path)?.generation === patch.generation) {
-						this.#modified.delete(patch.path);
-					}
-				}
-				this.#global = current;
-				for (const patch of this.#modified.values()) {
-					setByPath(this.#global, patch.path.split("."), structuredClone(patch.value));
-				}
-			}),
-		);
-		this.#saveTail = save.then(
-			() => undefined,
-			() => undefined,
+	#applyPatchWithDefaultOwnership(
+		raw: RawSettings,
+		patch: SettingsPatch,
+		currentConfigVersion = this.#defaultModelRoleOwnership.configVersion,
+	): boolean {
+		if (!this.#isStaleDefaultModelRolePatch(patch, currentConfigVersion)) {
+			applySettingsPatch(raw, patch);
+			return true;
+		}
+		if (patch.modelRole === "default") return false;
+
+		const durableDefault = defaultModelRoleFrom(raw);
+		const roles = shallowModelSelectorRecord(patch.value);
+		if (durableDefault === undefined) delete roles.default;
+		else roles.default = durableDefault;
+		setByPath(raw, ["modelRoles"], roles);
+		return true;
+	}
+
+	#releasePendingSaveSlot(): void {
+		if (this.#saveTimer) {
+			clearTimeout(this.#saveTimer);
+			this.#saveTimer = undefined;
+		}
+		const slot = this.#pendingSaveSlot;
+		if (!slot || slot.released) return;
+		slot.released = true;
+		slot.release();
+	}
+
+	#applyDurableBatch(revisions: readonly DurableBatchRevision[]): void {
+		this.#applyDurablePatches(
+			revisions,
+			revisions.map(entry => entry.patch),
+			true,
 		);
+	}
 
-		try {
-			await save;
-		} catch (error) {
-			logger.warn("Settings: save failed", { error: String(error) });
-			for (const patch of patches) {
-				const currentPatch = this.#modified.get(patch.path);
-				if (currentPatch?.generation === patch.generation) {
-					this.#modified.set(patch.path, patch);
-				}
+	#applyRestoredDurableBatch(
+		revisions: readonly DurableBatchRevision[],
+		restoredPatches: readonly AtomicYamlPatch[],
+	): void {
+		this.#applyDurablePatches(revisions, restoredPatches, false);
+	}
+
+	#applyDurablePatches(
+		revisions: readonly DurableBatchRevision[],
+		patches: readonly AtomicYamlPatch[],
+		clearStagedMutations: boolean,
+	): void {
+		const revisionsByPath = new Map<string, DurableBatchRevision>();
+		for (const entry of revisions) revisionsByPath.set(entry.patch.path, entry);
+		const finalPatches = new Map<string, AtomicYamlPatch>();
+		for (const patch of patches) finalPatches.set(patch.path, patch);
+		const applicable = [...finalPatches.values()].filter(patch => {
+			const revision = revisionsByPath.get(patch.path);
+			return revision !== undefined && this.#pathRevisions.get(patch.path) === revision.revision;
+		});
+		if (applicable.length === 0) return;
+
+		const previous = new Map<SettingPath, SettingValue<SettingPath>>();
+		for (const patch of applicable) {
+			const settingPath = patch.path as SettingPath;
+			const revision = revisionsByPath.get(patch.path)!;
+			previous.set(settingPath, this.get(settingPath));
+			if (patch.op === "set") {
+				setByPath(this.#global, settingPath.split("."), structuredClone(patch.value));
+			} else {
+				deleteByPath(this.#global, settingPath.split("."));
 			}
-			if (options.throwOnError) {
-				this.#rebuildMerged();
-				throw error;
+			if (clearStagedMutations) {
+				for (const [key, staged] of this.#modified) {
+					if (staged.path === settingPath && staged.revision <= revision.revision) {
+						this.#modified.delete(key);
+					}
+				}
 			}
 		}
-
 		this.#rebuildMerged();
+		for (const patch of applicable) {
+			const settingPath = patch.path as SettingPath;
+			const hook = SETTING_HOOKS[settingPath];
+			if (hook) hook(this.get(settingPath), previous.get(settingPath)!);
+		}
+	}
+
+	async #refreshDurableSettings(): Promise<void> {
+		if (!this.#persist || !this.#configPath) return;
+		const current = await this.#loadYaml(this.#configPath);
+		this.#replaceGlobalWithDurable(current, readConfigVersion(this.#configPath), false);
 	}
 
 	// ─────────────────────────────────────────────────────────────────────────
@@ -944,6 +1873,39 @@ export class Settings {
 		}
 	}
 
+	#getGlobalResolved<P extends SettingPath>(path: P): SettingValue<P> {
+		const value = getByPath(this.#global, path.split("."));
+		return value === undefined ? getDefault(path) : (value as SettingValue<P>);
+	}
+
+	#stripProjectNotificationSettings(settings: RawSettings): {
+		settings: RawSettings;
+		rejectedNotifications: boolean;
+	} {
+		let rejectedNotifications = false;
+		const sanitized: RawSettings = {};
+		for (const [key, value] of Object.entries(settings)) {
+			if (key === "notifications" && value && typeof value === "object" && !Array.isArray(value)) {
+				const localNotifications: Record<string, unknown> = {};
+				for (const [notificationKey, notificationValue] of Object.entries(value)) {
+					if (LOCAL_NOTIFICATION_SETTING_KEYS.has(notificationKey)) {
+						localNotifications[notificationKey] = notificationValue;
+					} else {
+						rejectedNotifications = true;
+					}
+				}
+				if (Object.keys(localNotifications).length > 0) sanitized[key] = localNotifications;
+				continue;
+			}
+			if (isNotificationSettingsPath(key)) {
+				rejectedNotifications = true;
+				continue;
+			}
+			sanitized[key] = value;
+		}
+		return { settings: sanitized, rejectedNotifications };
+	}
+
 	#deepMerge(base: RawSettings, overrides: RawSettings): RawSettings {
 		const result = { ...base };
 		for (const key of Object.keys(overrides)) {