@oh-my-pi/pi-coding-agent 17.0.0 → 17.0.2

package/src/config/settings-schema.ts

@@ -67,6 +67,8 @@ import {
 // Schema Definition Types
 // ═══════════════════════════════════════════════════════════════════════════
 
+export type ModelRoleStorage = "global" | "project";
+
 export type SettingTab =
 	| "appearance"
 	| "model"
@@ -509,6 +511,30 @@ export const SETTINGS_SCHEMA = {
 
 	disabledExtensions: { type: "array", default: EMPTY_STRING_ARRAY },
 
+	modelRoleStorage: {
+		type: "enum",
+		values: ["global", "project"] as const,
+		default: "global",
+		ui: {
+			tab: "model",
+			group: "Prompt",
+			label: "Model Role Storage",
+			description: "Where model selector role assignments are saved",
+			options: [
+				{
+					value: "global",
+					label: "Global",
+					description: "Save role models in the active profile config (current behavior)",
+				},
+				{
+					value: "project",
+					label: "Per-project",
+					description: "Save project role models in .omp/config.yml; missing project roles use global defaults",
+				},
+			],
+		},
+	},
+
 	modelRoles: { type: "record", default: EMPTY_STRING_RECORD },
 
 	modelTags: { type: "record", default: EMPTY_MODEL_TAGS_RECORD },
@@ -1439,7 +1465,7 @@ export const SETTINGS_SCHEMA = {
 			group: "Retry & Fallback",
 			label: "Retry Fallback Chains",
 			description:
-				'JSON object mapping model roles, model selectors ("provider/model-id"), or provider wildcards ("provider/*") to ordered fallback selectors, e.g. {"default":["openai/gpt-4o-mini"],"google-antigravity/*":["google/*","google-vertex/*"]}. Model-oriented keys apply whenever that model/provider is active, regardless of role; a "provider/*" entry keeps the failing model\'s id and swaps the provider.',
+				'JSON object mapping model roles, model selectors ("provider/model-id"), or provider wildcards ("provider/*") to ordered fallback selectors, e.g. {"default":["openai/gpt-4o-mini"],"google-antigravity/*":["google/*","google-vertex/*"]}. Model-oriented keys apply whenever that model/provider is active, regardless of role; a "provider/*" entry keeps the failing model\'s id and swaps the provider. An id-prefixed wildcard ("openrouter/google/*") re-prefixes the failing model\'s bare id (google-antigravity/gemini-x -> openrouter/google/gemini-x) and, used as a key, matches only that provider\'s ids under the prefix.',
 		},
 	},
 	"retry.fallbackRevertPolicy": {
@@ -2466,7 +2492,7 @@ export const SETTINGS_SCHEMA = {
 			group: "Auto-Learn",
 			label: "Auto-run capture at stop",
 			description:
-				"When on, auto-run one capture turn at stop (uses extra tokens). Off = passive reminder on your next turn.",
+				"When on, auto-run one private capture turn at stop (uses extra tokens). When off, only standing auto-learn guidance remains.",
 			condition: "autolearnActive",
 		},
 	},
@@ -3616,7 +3642,7 @@ export const SETTINGS_SCHEMA = {
 	},
 	"generate_image.enabled": {
 		type: "boolean",
-		default: true,
+		default: false,
 		ui: {
 			tab: "tools",
 			group: "Available Tools",
@@ -4468,7 +4494,7 @@ export const SETTINGS_SCHEMA = {
 	},
 	"providers.image": {
 		type: "enum",
-		values: ["auto", "openai", "antigravity", "xai", "gemini", "openrouter"] as const,
+		values: ["auto", "openai", "openai-codex", "antigravity", "xai", "gemini", "openrouter"] as const,
 		default: "auto",
 		ui: {
 			tab: "providers",
@@ -4479,9 +4505,20 @@ export const SETTINGS_SCHEMA = {
 				{
 					value: "auto",
 					label: "Auto",
-					description: "Priority: GPT model image tool > Antigravity > xAI > OpenRouter > Gemini",
+					description:
+						"Priority: per-request provider > configured provider > active session provider > GPT model image tool > Codex subscription > Antigravity > xAI > OpenRouter > Gemini",
+				},
+				{
+					value: "openai",
+					label: "OpenAI",
+					description:
+						"OPENAI_API_KEY (gpt-image-2) or active GPT model; falls back to a connected Codex subscription",
+				},
+				{
+					value: "openai-codex",
+					label: "OpenAI Codex (ChatGPT)",
+					description: "Uses a connected Codex / ChatGPT subscription — no OPENAI_API_KEY needed",
 				},
-				{ value: "openai", label: "OpenAI", description: "Uses the active GPT Responses/Codex model" },
 				{
 					value: "antigravity",
 					label: "Antigravity",

package/src/config/settings.ts

@@ -27,6 +27,7 @@ import {
 	setWorktreesDir,
 } from "@oh-my-pi/pi-utils";
 import { JSONC, YAML } from "bun";
+import { invalidate as invalidateCapabilityFsCache } from "../capability/fs";
 import { type Settings as SettingsCapabilityItem, settingsCapability } from "../capability/settings";
 import type { ModelRole } from "../config/model-roles";
 import { loadCapability } from "../discovery";
@@ -172,6 +173,83 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 	return !!value && typeof value === "object" && !Array.isArray(value);
 }
 
+/**
+ * Migrate a v17 leaf rename that used to nest under a boolean parent path
+ * (`dev.autoqa.consent` → `dev.autoqaConsent`, `todo.reminders.max` →
+ * `todo.remindersMax`). Pre-rename configs left the leaf beneath the parent,
+ * so the parent path resolved to an object and truthy checks like
+ * `isAutoQaEnabled` treated a consent-only container as "enabled".
+ *
+ * Handles nested (`{ parent: { leaf } }`) and quoted-dotted (`"parent.leaf"`)
+ * legacy sources. An explicit new key always wins; a separately configured
+ * boolean parent is preserved; an irrecoverable object-valued parent (only ever
+ * a container for the old leaf) is dropped so the schema default applies.
+ */
+function migrateNestedLeafRename(
+	raw: RawSettings,
+	root: string,
+	parent: string,
+	oldLeaf: string,
+	newLeaf: string,
+	isLeafValue: (value: unknown) => boolean,
+): void {
+	const rootObj = isRecord(raw[root]) ? (raw[root] as Record<string, unknown>) : undefined;
+	const nestedParent = rootObj?.[parent];
+	const flatParent = raw[`${root}.${parent}`];
+	const oldParentPath = `${root}.${parent}`;
+
+	const candidates = [
+		rootObj?.[newLeaf],
+		raw[`${root}.${newLeaf}`],
+		isRecord(nestedParent) ? nestedParent[oldLeaf] : undefined,
+		raw[`${oldParentPath}.${oldLeaf}`],
+	];
+	const resolvedLeaf = candidates.find(isLeafValue);
+
+	const recoveredParent =
+		typeof nestedParent === "boolean" ? nestedParent : typeof flatParent === "boolean" ? flatParent : undefined;
+
+	const ensureRoot = (): Record<string, unknown> => {
+		const current = raw[root];
+		if (isRecord(current)) return current;
+		const created: Record<string, unknown> = {};
+		raw[root] = created;
+		return created;
+	};
+
+	if (resolvedLeaf !== undefined) {
+		const target = ensureRoot();
+		if (!isLeafValue(target[newLeaf])) {
+			target[newLeaf] = resolvedLeaf;
+		}
+	}
+
+	// Strip legacy leaf sources (nested + flat dotted).
+	delete raw[`${oldParentPath}.${oldLeaf}`];
+	delete raw[`${root}.${newLeaf}`];
+	if (isRecord(raw[root]) && isRecord((raw[root] as Record<string, unknown>)[parent])) {
+		const parentObj = (raw[root] as Record<string, unknown>)[parent] as Record<string, unknown>;
+		delete parentObj[oldLeaf];
+		if (Object.keys(parentObj).length === 0) {
+			delete (raw[root] as Record<string, unknown>)[parent];
+		}
+	}
+
+	// The parent path must be a boolean or absent — never a leftover object.
+	if (recoveredParent !== undefined) {
+		const target = ensureRoot();
+		if (typeof target[parent] !== "boolean") {
+			target[parent] = recoveredParent;
+		}
+	} else if (isRecord(raw[root]) && isRecord((raw[root] as Record<string, unknown>)[parent])) {
+		delete (raw[root] as Record<string, unknown>)[parent];
+	}
+	delete raw[oldParentPath];
+	if (isRecord(raw[root]) && Object.keys(raw[root] as Record<string, unknown>).length === 0) {
+		delete raw[root];
+	}
+}
+
 function modelRoleValueFromUnknown(value: unknown): string | undefined {
 	if (typeof value === "string") return value;
 	if (!Array.isArray(value)) return undefined;
@@ -250,6 +328,16 @@ export class Settings {
 
 	/** Paths modified during this session (for partial save) */
 	#modified = new Set<string>();
+	/** Individual project model roles modified during this session */
+	#modifiedProjectModelRoles = new Set<string>();
+	/**
+	 * Original process-wide model-role overrides captured before a project edit
+	 * temporarily replaced them via `#updateRuntimeModelRoleOverride`. Restored
+	 * on `reloadForCwd` / `cloneForCwd` so destination projects never inherit the
+	 * source-project value. Maps role → original override value (`undefined`
+	 * when the role had no runtime override).
+	 */
+	#savedRuntimeModelRoleOverrides = new Map<string, string | undefined>();
 
 	/** Legacy `lastChangelogVersion` captured from config.yml during migration (now a marker file). */
 	#legacyLastChangelogVersion?: string;
@@ -257,6 +345,8 @@ export class Settings {
 	/** Pending save (debounced) */
 	#saveTimer?: NodeJS.Timeout;
 	#savePromise?: Promise<void>;
+	#projectSaveTimer?: NodeJS.Timeout;
+	#projectSavePromise?: Promise<void>;
 
 	/** Whether to persist changes */
 	#persist: boolean;
@@ -400,6 +490,9 @@ export class Settings {
 	 * Apply runtime overrides (not persisted).
 	 */
 	override<P extends SettingPath>(path: P, value: SettingValue<P>): void {
+		if (path === "modelRoles") {
+			this.#savedRuntimeModelRoleOverrides.clear();
+		}
 		const prev = this.get(path);
 		const segments = path.split(".");
 		setByPath(this.#overrides, segments, value);
@@ -411,6 +504,9 @@ export class Settings {
 	 * Clear a runtime override.
 	 */
 	clearOverride(path: SettingPath): void {
+		if (path === "modelRoles") {
+			this.#savedRuntimeModelRoleOverrides.clear();
+		}
 		const prev = this.get(path);
 		const segments = path.split(".");
 		let current = this.#overrides;
@@ -443,12 +539,22 @@ export class Settings {
 			clearTimeout(this.#saveTimer);
 			this.#saveTimer = undefined;
 		}
+		if (this.#projectSaveTimer) {
+			clearTimeout(this.#projectSaveTimer);
+			this.#projectSaveTimer = undefined;
+		}
 		if (this.#savePromise) {
 			await this.#savePromise;
 		}
+		if (this.#projectSavePromise) {
+			await this.#projectSavePromise;
+		}
 		if (this.#modified.size > 0) {
 			await this.#saveNow();
 		}
+		if (this.#modifiedProjectModelRoles.size > 0) {
+			await this.#saveProjectNow();
+		}
 	}
 
 	async cloneForCwd(cwd: string): Promise<Settings> {
@@ -463,7 +569,7 @@ export class Settings {
 		cloned.#project = this.#persist ? await cloned.#loadProjectSettings() : structuredClone(this.#project);
 		cloned.#configFiles = [...this.#configFiles];
 		cloned.#configOverlay = structuredClone(this.#configOverlay);
-		cloned.#overrides = structuredClone(this.#overrides);
+		cloned.#overrides = this.#buildOriginalOverrides();
 		cloned.#rebuildMerged();
 		cloned.#fireAllHooks();
 		return cloned;
@@ -484,6 +590,8 @@ export class Settings {
 	async reloadForCwd(cwd: string): Promise<void> {
 		const normalized = path.normalize(cwd);
 		if (normalized === this.#cwd) return;
+		await this.flush();
+		this.#restoreRuntimeModelRoleOverrides();
 		const prevModelRoles = this.get("modelRoles");
 		this.#cwd = normalized;
 		if (this.#persist) {
@@ -602,35 +710,168 @@ export class Settings {
 		return roles;
 	}
 
+	#modelRoleLayerOwns(layer: RawSettings, role: ModelRole | string): boolean {
+		const value = getByPath(layer, ["modelRoles"]);
+		if (!isRecord(value)) return false;
+		return Object.hasOwn(value, role);
+	}
+
+	/**
+	 * Set the full `modelRoles` map on the runtime override layer without
+	 * routing through the public {@link override} method. Internal callers
+	 * (project edits, global fallback updates) use this so they can control
+	 * capture invalidation independently of the whole-map replacement
+	 * semantics that `override("modelRoles", …)` carries.
+	 */
+	#setRuntimeModelRoleOverrides(next: Record<string, string>): void {
+		const prev = this.get("modelRoles");
+		setByPath(this.#overrides, ["modelRoles"], next);
+		this.#rebuildMerged();
+		this.#fireEffectiveSettingChanged("modelRoles", this.get("modelRoles"), prev);
+	}
+
+	#updateRuntimeModelRoleOverride(role: ModelRole | string, modelId: string | undefined): void {
+		const runtimeOverrides = getByPath(this.#overrides, ["modelRoles"]);
+		if (!isRecord(runtimeOverrides) || !Object.hasOwn(runtimeOverrides, role)) return;
+
+		const nextRuntimeOverride = this.#modelRolesFromLayer(this.#overrides);
+		if (modelId === undefined) {
+			delete nextRuntimeOverride[role];
+		} else {
+			nextRuntimeOverride[role] = modelId;
+		}
+		this.#setRuntimeModelRoleOverrides(nextRuntimeOverride);
+	}
+
+	/**
+	 * Capture the original process-wide override for `role` the first time a
+	 * project edit temporarily replaces it, so the original can be restored on
+	 * cwd changes. Subsequent edits in the same cwd must not overwrite the
+	 * first captured value.
+	 */
+	#captureRuntimeModelRoleOverride(role: ModelRole | string): void {
+		if (this.#savedRuntimeModelRoleOverrides.has(role)) return;
+		const runtimeOverrides = getByPath(this.#overrides, ["modelRoles"]);
+		if (!isRecord(runtimeOverrides) || !Object.hasOwn(runtimeOverrides, role)) return;
+		this.#savedRuntimeModelRoleOverrides.set(role, this.#modelRolesFromLayer(this.#overrides)[role]);
+	}
+
+	/**
+	 * Restore original process-wide model-role overrides that were temporarily
+	 * replaced by project edits, mutating `#overrides` in place without
+	 * rebuilding. All remaining captures are valid because superseding
+	 * operations (late `overrideModelRoles`, global-mode `setModelRole`,
+	 * whole-map `override`/`clearOverride`) invalidate the affected captures
+	 * at the point of supersession. Caller is responsible for `#rebuildMerged()`.
+	 */
+	#restoreRuntimeModelRoleOverrides(): void {
+		if (this.#savedRuntimeModelRoleOverrides.size === 0) return;
+		const runtimeRoles = getByPath(this.#overrides, ["modelRoles"]);
+		if (!isRecord(runtimeRoles)) {
+			this.#savedRuntimeModelRoleOverrides.clear();
+			return;
+		}
+		for (const [role, originalValue] of this.#savedRuntimeModelRoleOverrides) {
+			if (originalValue === undefined) {
+				delete runtimeRoles[role];
+			} else {
+				runtimeRoles[role] = originalValue;
+			}
+		}
+		this.#savedRuntimeModelRoleOverrides.clear();
+	}
+
+	/**
+	 * Produce a deep copy of `#overrides` with original process-wide model-role
+	 * overrides restored, for use by {@link cloneForCwd}. All remaining
+	 * captures are valid (see {@link #restoreRuntimeModelRoleOverrides}).
+	 * Does not mutate the current instance's `#overrides`.
+	 */
+	#buildOriginalOverrides(): RawSettings {
+		if (this.#savedRuntimeModelRoleOverrides.size === 0) {
+			return structuredClone(this.#overrides);
+		}
+		const overrides = structuredClone(this.#overrides);
+		const runtimeRoles = getByPath(overrides, ["modelRoles"]);
+		if (!isRecord(runtimeRoles)) return overrides;
+		for (const [role, originalValue] of this.#savedRuntimeModelRoleOverrides) {
+			if (originalValue === undefined) {
+				delete runtimeRoles[role];
+			} else {
+				runtimeRoles[role] = originalValue;
+			}
+		}
+		return overrides;
+	}
+
+	#setProjectModelRoleValue(role: ModelRole | string, modelId: string | null): void {
+		const prev = this.get("modelRoles");
+		const projectRoles = getByPath(this.#project, ["modelRoles"]);
+		const current: Record<string, unknown> = isRecord(projectRoles) ? { ...projectRoles } : {};
+		current[role] = modelId;
+		setByPath(this.#project, ["modelRoles"], current);
+		this.#modifiedProjectModelRoles.add(role);
+		this.#rebuildMerged();
+		this.#fireEffectiveSettingChanged("modelRoles", this.get("modelRoles"), prev);
+		this.#queueProjectSave();
+	}
+
 	/**
 	 * Set a model role (helper for modelRoles record). Passing `undefined`
 	 * clears the role from the persisted record and any runtime override.
+	 *
+	 * In project storage mode, when a project edit has temporarily replaced
+	 * the process-wide runtime override for `role` and that override is still
+	 * active (the runtime slot currently matches the project value), the
+	 * global-layer write must not rewrite that runtime slot — otherwise the
+	 * global fallback would immediately shadow the still-configured project
+	 * role. The global layer is still persisted; only the runtime override is
+	 * left untouched. The guard is precise so that a later clear, a late
+	 * `overrideModelRoles`, or a storage-mode transition does not leave a
+	 * stale skip in place.
 	 */
 	setModelRole(role: ModelRole | string, modelId: string | undefined): void {
 		const current = this.#modelRolesFromLayer(this.#global);
-		const runtimeOverrides = getByPath(this.#overrides, ["modelRoles"]);
-		const updateRuntimeOverride =
-			!!runtimeOverrides &&
-			typeof runtimeOverrides === "object" &&
-			!Array.isArray(runtimeOverrides) &&
-			Object.hasOwn(runtimeOverrides, role);
-
 		if (modelId === undefined) {
 			delete current[role];
 		} else {
 			current[role] = modelId;
 		}
 		this.set("modelRoles", current);
-
-		if (updateRuntimeOverride) {
-			const nextRuntimeOverride = this.#modelRolesFromLayer(this.#overrides);
-			if (modelId === undefined) {
-				delete nextRuntimeOverride[role];
-			} else {
-				nextRuntimeOverride[role] = modelId;
-			}
-			this.override("modelRoles", nextRuntimeOverride);
+		if (this.isProjectModelRoleRuntimeOverrideActive(role)) {
+			return;
 		}
+		this.#savedRuntimeModelRoleOverrides.delete(role);
+		this.#updateRuntimeModelRoleOverride(role, modelId);
+	}
+
+	/**
+	 * Whether `role`'s runtime override slot currently holds the temporary
+	 * project-scoped value installed by a prior `setProjectModelRole`. Returns
+	 * `false` when storage is not project-mode, no capture exists, or the
+	 * project role was cleared. With explicit provenance invalidation, a
+	 * surviving capture implies no external supersession occurred.
+	 */
+	isProjectModelRoleRuntimeOverrideActive(role: ModelRole | string): boolean {
+		if (this.get("modelRoleStorage") !== "project") return false;
+		if (!this.#savedRuntimeModelRoleOverrides.has(role)) return false;
+		return !!this.getProjectModelRole(role);
+	}
+	/**
+	 * Set a model role in the current project's settings layer.
+	 */
+	setProjectModelRole(role: ModelRole | string, modelId: string): void {
+		this.#setProjectModelRoleValue(role, modelId);
+		this.#captureRuntimeModelRoleOverride(role);
+		this.#updateRuntimeModelRoleOverride(role, modelId);
+	}
+	/**
+	 * Clear a model role from the current project's settings layer.
+	 */
+	clearProjectModelRole(role: ModelRole | string): void {
+		this.#setProjectModelRoleValue(role, null);
+		this.#captureRuntimeModelRoleOverride(role);
+		this.#updateRuntimeModelRoleOverride(role, undefined);
 	}
 
 	/**
@@ -641,6 +882,49 @@ export class Settings {
 		if (!isRecord(roles)) return undefined;
 		return modelRoleValueFromUnknown(roles[role]);
 	}
+	/**
+	 * Get a model role from only the global settings layer.
+	 */
+	getGlobalModelRole(role: ModelRole | string): string | undefined {
+		const modelId = this.#modelRolesFromLayer(this.#global)[role];
+		return modelId || undefined;
+	}
+
+	/**
+	 * Get a model role from only the current project settings layer.
+	 */
+	getProjectModelRole(role: ModelRole | string): string | undefined {
+		const modelId = this.#modelRolesFromLayer(this.#project)[role];
+		return modelId || undefined;
+	}
+
+	/**
+	 * Report which layer actually supplies the effective model role across
+	 * full merge precedence (runtime override → config overlay → project →
+	 * global → default). Unlike {@link getModelRoleSource}, this accounts
+	 * for runtime and config-overlay layers and detects ownership by key
+	 * presence rather than normalized value, so a `null` tombstone in the
+	 * overlay or runtime layer correctly blocks lower layers. The project
+	 * layer is checked through {@link #projectSettingsForMerge} because a
+	 * project null is a cleared value (falls back to global), not a
+	 * tombstone.
+	 */
+	getModelRoleProvenance(role: ModelRole | string): "runtime" | "overlay" | "project" | "global" | "default" {
+		if (this.#modelRoleLayerOwns(this.#overrides, role)) return "runtime";
+		if (this.#modelRoleLayerOwns(this.#configOverlay, role)) return "overlay";
+		if (this.#modelRoleLayerOwns(this.#projectSettingsForMerge(), role)) return "project";
+		if (this.#modelRoleLayerOwns(this.#global, role)) return "global";
+		return "default";
+	}
+
+	/**
+	 * Get the persisted layer supplying a model role (project/global/default only).
+	 */
+	getModelRoleSource(role: ModelRole | string): "project" | "global" | "default" {
+		if (this.getProjectModelRole(role)) return "project";
+		if (this.getGlobalModelRole(role)) return "global";
+		return "default";
+	}
 
 	/**
 	 * Get all model roles (helper for modelRoles record).
@@ -668,9 +952,10 @@ export class Settings {
 		for (const [role, modelId] of Object.entries(roles)) {
 			if (modelId) {
 				next[role] = modelId;
+				this.#savedRuntimeModelRoleOverrides.delete(role);
 			}
 		}
-		this.override("modelRoles", next);
+		this.#setRuntimeModelRoleOverrides(next);
 	}
 
 	/**
@@ -778,6 +1063,11 @@ export class Settings {
 					merged = this.#deepMerge(merged, item.data as RawSettings);
 				}
 			}
+			const nativeProject = await this.#loadYaml(path.join(this.#cwd, ".omp", "config.yml"));
+			const nativeModelRoles = getByPath(nativeProject, ["modelRoles"]);
+			if (nativeModelRoles !== undefined) {
+				merged = this.#deepMerge(merged, { modelRoles: nativeModelRoles });
+			}
 			return this.#migrateRawSettings(merged);
 		} catch {
 			return {};
@@ -1253,6 +1543,26 @@ export class Settings {
 		if (tierTouched) raw.tier = tierObj;
 		delete raw.fastModeScope;
 
+		// v17 renames that used to nest under a boolean parent path:
+		//   dev.autoqa.consent -> dev.autoqaConsent
+		//   todo.reminders.max -> todo.remindersMax
+		migrateNestedLeafRename(
+			raw,
+			"dev",
+			"autoqa",
+			"consent",
+			"autoqaConsent",
+			value => value === "unset" || value === "granted" || value === "denied",
+		);
+		migrateNestedLeafRename(
+			raw,
+			"todo",
+			"reminders",
+			"max",
+			"remindersMax",
+			value => typeof value === "number" && Number.isFinite(value),
+		);
+
 		// BM25 tool discovery removal: tools.discoveryMode / tools.essentialOverride /
 		// mcp.discoveryMode / mcp.discoveryDefaultServers are gone with no
 		// replacement (`tools.xdev` stays at its own default). Dead keys are
@@ -1304,14 +1614,20 @@ export class Settings {
 		if (!this.#persist || !this.#configPath) return;
 
 		// Debounce: wait 100ms for more changes
-		if (this.#saveTimer) {
-			clearTimeout(this.#saveTimer);
-		}
+		clearTimeout(this.#saveTimer);
 		this.#saveTimer = setTimeout(() => {
 			this.#saveTimer = undefined;
-			this.#saveNow().catch(err => {
-				logger.warn("Settings: background save failed", { error: String(err) });
-			});
+			const savePromise = this.#saveNow();
+			this.#savePromise = savePromise;
+			savePromise
+				.catch(err => {
+					logger.warn("Settings: background save failed", { error: String(err) });
+				})
+				.finally(() => {
+					if (this.#savePromise === savePromise) {
+						this.#savePromise = undefined;
+					}
+				});
 		}, 100);
 	}
 
@@ -1348,13 +1664,77 @@ export class Settings {
 
 		this.#rebuildMerged();
 	}
+	#queueProjectSave(): void {
+		if (!this.#persist) return;
+
+		clearTimeout(this.#projectSaveTimer);
+		this.#projectSaveTimer = setTimeout(() => {
+			this.#projectSaveTimer = undefined;
+			const savePromise = this.#saveProjectNow();
+			this.#projectSavePromise = savePromise;
+			savePromise
+				.catch(err => {
+					logger.warn("Settings: background project save failed", { error: String(err) });
+				})
+				.finally(() => {
+					if (this.#projectSavePromise === savePromise) {
+						this.#projectSavePromise = undefined;
+					}
+				});
+		}, 100);
+	}
+
+	async #saveProjectNow(): Promise<void> {
+		if (!this.#persist || this.#modifiedProjectModelRoles.size === 0) return;
+
+		const projectConfigPath = path.join(this.#cwd, ".omp", "config.yml");
+		const modifiedModelRoles = [...this.#modifiedProjectModelRoles];
+		this.#modifiedProjectModelRoles.clear();
+
+		try {
+			await fs.promises.mkdir(path.dirname(projectConfigPath), { recursive: true });
+			await withFileLock(projectConfigPath, async () => {
+				const projectSettings = await this.#loadYaml(projectConfigPath);
+
+				const projectRoles = getByPath(this.#project, ["modelRoles"]);
+				for (const role of modifiedModelRoles) {
+					const value = isRecord(projectRoles) ? projectRoles[role] : undefined;
+					setByPath(projectSettings, ["modelRoles", role], value);
+				}
+
+				await Bun.write(projectConfigPath, YAML.stringify(projectSettings, null, 2));
+			});
+			invalidateCapabilityFsCache(projectConfigPath);
+		} catch (error) {
+			for (const role of modifiedModelRoles) {
+				this.#modifiedProjectModelRoles.add(role);
+			}
+			throw error;
+		}
+
+		this.#rebuildMerged();
+	}
 
 	// ─────────────────────────────────────────────────────────────────────────
 	// Utilities
 	// ─────────────────────────────────────────────────────────────────────────
 
+	#projectSettingsForMerge(): RawSettings {
+		const projectRoles = getByPath(this.#project, ["modelRoles"]);
+		if (!isRecord(projectRoles)) return this.#project;
+
+		let filteredRoles: Record<string, unknown> | undefined;
+		for (const role in projectRoles) {
+			if (!Object.hasOwn(projectRoles, role) || modelRoleValueFromUnknown(projectRoles[role]) !== undefined)
+				continue;
+			filteredRoles ??= { ...projectRoles };
+			delete filteredRoles[role];
+		}
+		return filteredRoles ? { ...this.#project, modelRoles: filteredRoles } : this.#project;
+	}
+
 	#rebuildMerged(): void {
-		this.#merged = this.#deepMerge(this.#deepMerge({}, this.#global), this.#project);
+		this.#merged = this.#deepMerge(this.#deepMerge({}, this.#global), this.#projectSettingsForMerge());
 		this.#merged = this.#deepMerge(this.#merged, this.#configOverlay);
 		this.#merged = this.#deepMerge(this.#merged, this.#overrides);
 		this.#resolvedCache.clear();