From e1532b31932418ed3126f3a606b205c072161d51 Mon Sep 17 00:00:00 2001
From: Cascade Bot <bot@cascade.dev>
Date: Wed, 5 Aug 2026 14:47:57 +0000
Subject: [PATCH] fix(backends): honor inherited model label + warn on
 engine/model incompatibility

---
 docs/adding-engines.md                        | 21 ++++-
 src/backends/catalog.ts                       | 28 +++++-
 src/backends/claude-code/index.ts             | 13 ++-
 src/backends/claude-code/models.ts            |  8 ++
 src/backends/codex/index.ts                   |  4 +-
 src/backends/codex/models.ts                  | 11 +++
 src/backends/types.ts                         |  8 ++
 tests/unit/backends/catalog.test.ts           | 60 +++++++++++++
 tests/unit/web/agent-config-utils.test.ts     | 86 +++++++++++++++++++
 tests/unit/web/model-field.test.ts            | 29 +++++++
 .../projects/agent-config-detail.tsx          | 25 +++++-
 .../components/projects/agent-config-types.ts | 10 +++
 .../components/projects/agent-config-utils.ts | 23 +++++
 .../projects/project-harness-form.tsx         |  2 +-
 web/src/components/settings/model-field.tsx   | 25 +++++-
 15 files changed, 340 insertions(+), 13 deletions(-)

diff --git a/docs/adding-engines.md b/docs/adding-engines.md
index f7a872f65..2e8929954 100644
--- a/docs/adding-engines.md
+++ b/docs/adding-engines.md
@@ -72,14 +72,33 @@ export const MY_ENGINE_DEFINITION: AgentEngineDefinition = {
   ],
   modelSelection: {
     type: 'select',                      // or 'free-text' for open-ended model strings
-    defaultValueLabel: 'Default (v1.0)',
+    // Derive the label from your DEFAULT_*_MODEL constant + catalog lookup instead
+    // of hardcoding it, so the displayed default can never drift from the actually
+    // resolved default on the next model bump (MNG-1772). See catalog.ts's
+    // `defaultModelLabel(models, defaultId)` helper.
+    defaultValueLabel: defaultModelLabel(MY_ENGINE_MODELS, DEFAULT_MY_ENGINE_MODEL),
     options: MY_ENGINE_MODELS,           // Imported from ./my-engine/models.ts
+    // Optional: model-ID prefixes your engine accepts in addition to catalog IDs.
+    // Single-source these next to your model list (e.g. MY_ENGINE_ACCEPTED_PREFIXES)
+    // and consume them in your resolveModel() so the runtime acceptance rules and
+    // the dashboard's config-time incompatibility warning share one definition.
+    // Must be a plain string[] — it serializes across the agentConfigs.engines tRPC
+    // query and is mirrored by the frontend's isModelCompatibleWithEngine().
+    acceptedModelPrefixes: MY_ENGINE_ACCEPTED_PREFIXES,
   },
   logLabel: 'My Engine Log',
   // Optional: add 'settings' if your engine has configurable fields
 };
 ```
 
+> **Anti-drift + config-time warning contract (MNG-1772).** For `select`-type
+> engines, deriving `defaultValueLabel` from the default-model constant keeps the
+> UI honest, and exposing `acceptedModelPrefixes` lets the agent-config detail
+> panel warn *before* dispatch when an inherited model is incompatible with the
+> engine (instead of crashing mid-run). A guard test in
+> `tests/unit/backends/catalog.test.ts` asserts the displayed default always
+> matches the resolved default for every `select` engine.
+
 Add it to `DEFAULT_ENGINE_CATALOG` at the bottom of the same file:
 
 ```typescript
diff --git a/src/backends/catalog.ts b/src/backends/catalog.ts
index 8a68516dc..59db6e77c 100644
--- a/src/backends/catalog.ts
+++ b/src/backends/catalog.ts
@@ -1,7 +1,25 @@
-import { CLAUDE_CODE_MODELS } from './claude-code/models.js';
-import { CODEX_MODELS } from './codex/models.js';
+import {
+	CLAUDE_CODE_ACCEPTED_PREFIXES,
+	CLAUDE_CODE_MODELS,
+	DEFAULT_CLAUDE_CODE_MODEL,
+} from './claude-code/models.js';
+import { CODEX_ACCEPTED_PREFIXES, CODEX_MODELS, DEFAULT_CODEX_MODEL } from './codex/models.js';
 import type { AgentEngineDefinition } from './types.js';
 
+/**
+ * Derive the `select`-engine empty-option label from the engine's default model
+ * constant, looking the display label up in the model catalog. This kills the
+ * hand-synced-literal drift class (MNG-1772/MNG-1770): the displayed default
+ * always matches the actually-resolved `DEFAULT_*_MODEL` on the next model bump.
+ */
+export function defaultModelLabel(
+	models: ReadonlyArray<{ value: string; label: string }>,
+	defaultId: string,
+): string {
+	const match = models.find((m) => m.value === defaultId);
+	return `Default (${match?.label ?? defaultId})`;
+}
+
 export const LLMIST_ENGINE_DEFINITION: AgentEngineDefinition = {
 	id: 'llmist',
 	label: 'LLMist',
@@ -35,8 +53,9 @@ export const CLAUDE_CODE_ENGINE_DEFINITION: AgentEngineDefinition = {
 	],
 	modelSelection: {
 		type: 'select',
-		defaultValueLabel: 'Default (Sonnet 5)',
+		defaultValueLabel: defaultModelLabel(CLAUDE_CODE_MODELS, DEFAULT_CLAUDE_CODE_MODEL),
 		options: CLAUDE_CODE_MODELS,
+		acceptedModelPrefixes: CLAUDE_CODE_ACCEPTED_PREFIXES,
 	},
 	logLabel: 'Claude Code Log',
 	settings: {
@@ -94,8 +113,9 @@ export const CODEX_ENGINE_DEFINITION: AgentEngineDefinition = {
 	],
 	modelSelection: {
 		type: 'select',
-		defaultValueLabel: 'Default (GPT-5.4)',
+		defaultValueLabel: defaultModelLabel(CODEX_MODELS, DEFAULT_CODEX_MODEL),
 		options: CODEX_MODELS,
+		acceptedModelPrefixes: CODEX_ACCEPTED_PREFIXES,
 	},
 	logLabel: 'Codex Log',
 	settings: {
diff --git a/src/backends/claude-code/index.ts b/src/backends/claude-code/index.ts
index 83c3b128c..d4cc29e26 100644
--- a/src/backends/claude-code/index.ts
+++ b/src/backends/claude-code/index.ts
@@ -21,7 +21,11 @@ import {
 	consumeStream,
 	filterContextImages,
 } from './messageProcessing.js';
-import { CLAUDE_CODE_MODEL_IDS, DEFAULT_CLAUDE_CODE_MODEL } from './models.js';
+import {
+	CLAUDE_CODE_ACCEPTED_PREFIXES,
+	CLAUDE_CODE_MODEL_IDS,
+	DEFAULT_CLAUDE_CODE_MODEL,
+} from './models.js';
 import { ClaudeCodeSettingsSchema, resolveClaudeCodeSettings } from './settings.js';
 
 export {
@@ -40,8 +44,11 @@ export { buildPromptWithImages, formatErrorMessage } from './messageProcessing.j
  */
 export function resolveClaudeModel(cascadeModel: string): string {
 	if (CLAUDE_CODE_MODEL_IDS.includes(cascadeModel)) return cascadeModel;
-	if (cascadeModel.startsWith('claude-')) return cascadeModel;
-	if (cascadeModel.startsWith('anthropic:')) return cascadeModel.replace('anthropic:', '');
+	if (CLAUDE_CODE_ACCEPTED_PREFIXES.some((prefix) => cascadeModel.startsWith(prefix))) {
+		return cascadeModel.startsWith('anthropic:')
+			? cascadeModel.replace('anthropic:', '')
+			: cascadeModel;
+	}
 
 	throw new Error(
 		`Model "${cascadeModel}" is not compatible with the Claude Code engine. Configure a Claude-compatible model (e.g. "${DEFAULT_CLAUDE_CODE_MODEL}") or switch to a different engine.`,
diff --git a/src/backends/claude-code/models.ts b/src/backends/claude-code/models.ts
index 0d34b424b..8ba84189d 100644
--- a/src/backends/claude-code/models.ts
+++ b/src/backends/claude-code/models.ts
@@ -20,3 +20,11 @@ export const CLAUDE_CODE_MODELS = [
 export const CLAUDE_CODE_MODEL_IDS: string[] = CLAUDE_CODE_MODELS.map((m) => m.value);
 
 export const DEFAULT_CLAUDE_CODE_MODEL = 'claude-sonnet-5';
+
+/**
+ * Model-ID prefixes the Claude Code engine accepts in addition to catalog IDs.
+ * Single source of truth consumed by `resolveClaudeModel` (runtime acceptance)
+ * and surfaced on the engine definition as `acceptedModelPrefixes` so the
+ * dashboard can mirror the compatibility check without duplicating logic.
+ */
+export const CLAUDE_CODE_ACCEPTED_PREFIXES = ['claude-', 'anthropic:'] as const;
diff --git a/src/backends/codex/index.ts b/src/backends/codex/index.ts
index 9004b3cbb..6ff1dcb01 100644
--- a/src/backends/codex/index.ts
+++ b/src/backends/codex/index.ts
@@ -19,7 +19,7 @@ import { buildSystemPrompt, buildTaskPrompt } from '../shared/nativeToolPrompts.
 import type { AgentEngineResult, AgentExecutionPlan, LogWriter } from '../types.js';
 import type { UsageSummary } from './jsonlParser.js';
 import { extractUsage, parseCodexEvent } from './jsonlParser.js';
-import { CODEX_MODEL_IDS, DEFAULT_CODEX_MODEL } from './models.js';
+import { CODEX_ACCEPTED_PREFIXES, CODEX_MODEL_IDS, DEFAULT_CODEX_MODEL } from './models.js';
 import { CODEX_COMPLETION_OUTPUT_SCHEMA, parseCodexCompletionReport } from './outputSchema.js';
 import {
 	assertHeadlessCodexSettings,
@@ -508,7 +508,7 @@ function resolveCodexModel(cascadeModel: string): string {
 	// and would silently persist zero cost. Add new models to CODEX_MODEL_IDS in
 	// src/backends/codex/models.ts AND add a pricing row to MODEL_PRICING in
 	// src/utils/llmMetrics.ts before accepting them here.
-	if (cascadeModel.startsWith('openai:')) {
+	if (CODEX_ACCEPTED_PREFIXES.some((prefix) => cascadeModel.startsWith(prefix))) {
 		const bareId = cascadeModel.replace('openai:', '');
 		if (CODEX_MODEL_IDS.includes(bareId)) return bareId;
 	}
diff --git a/src/backends/codex/models.ts b/src/backends/codex/models.ts
index beab7fcee..84e306cd5 100644
--- a/src/backends/codex/models.ts
+++ b/src/backends/codex/models.ts
@@ -13,3 +13,14 @@ export const CODEX_MODELS = [
 export const CODEX_MODEL_IDS: string[] = CODEX_MODELS.map((model) => model.value);
 
 export const DEFAULT_CODEX_MODEL = 'gpt-5.4';
+
+/**
+ * Model-ID prefixes the Codex engine accepts in addition to catalog IDs.
+ * Single source of truth consumed by `resolveCodexModel` (runtime acceptance)
+ * and surfaced on the engine definition as `acceptedModelPrefixes` so the
+ * dashboard can mirror the compatibility check without duplicating logic.
+ *
+ * Note: an `openai:`-prefixed model still only resolves when its bare ID is a
+ * known catalog ID (see `resolveCodexModel`); the prefix alone is not enough.
+ */
+export const CODEX_ACCEPTED_PREFIXES = ['openai:'] as const;
diff --git a/src/backends/types.ts b/src/backends/types.ts
index 744d93871..b382b7619 100644
--- a/src/backends/types.ts
+++ b/src/backends/types.ts
@@ -156,6 +156,14 @@ export interface AgentEngineDefinition {
 				type: 'select';
 				defaultValueLabel: string;
 				options: ReadonlyArray<{ value: string; label: string }>;
+				/**
+				 * Model-ID prefixes this engine accepts in addition to its catalog
+				 * options (e.g. `['claude-', 'anthropic:']`). Must be a plain
+				 * `string[]` so it serializes across the `agentConfigs.engines` tRPC
+				 * query — the frontend mirrors the runtime compatibility check via
+				 * `isModelCompatibleWithEngine` without duplicating logic.
+				 */
+				acceptedModelPrefixes?: readonly string[];
 		  };
 	readonly logLabel: string;
 	readonly settings?: AgentEngineSettingsDefinition;
diff --git a/tests/unit/backends/catalog.test.ts b/tests/unit/backends/catalog.test.ts
index b929389b1..f9308e1ea 100644
--- a/tests/unit/backends/catalog.test.ts
+++ b/tests/unit/backends/catalog.test.ts
@@ -3,9 +3,15 @@ import {
 	CLAUDE_CODE_ENGINE_DEFINITION,
 	CODEX_ENGINE_DEFINITION,
 	DEFAULT_ENGINE_CATALOG,
+	defaultModelLabel,
 	LLMIST_ENGINE_DEFINITION,
 	OPENCODE_ENGINE_DEFINITION,
 } from '../../../src/backends/catalog.js';
+import {
+	CLAUDE_CODE_MODELS,
+	DEFAULT_CLAUDE_CODE_MODEL,
+} from '../../../src/backends/claude-code/models.js';
+import { CODEX_MODELS, DEFAULT_CODEX_MODEL } from '../../../src/backends/codex/models.js';
 import type { AgentEngineDefinition } from '../../../src/backends/types.js';
 
 describe('DEFAULT_ENGINE_CATALOG', () => {
@@ -50,6 +56,60 @@ describe('DEFAULT_ENGINE_CATALOG', () => {
 	});
 });
 
+// ─── defaultModelLabel + displayed-default==resolved-default guard ────────────
+describe('defaultModelLabel', () => {
+	it('renders "Default (<label>)" using the catalog label lookup', () => {
+		const models = [
+			{ value: 'claude-sonnet-5', label: 'Claude Sonnet 5' },
+			{ value: 'gpt-5.4', label: 'GPT-5.4' },
+		];
+		expect(defaultModelLabel(models, 'claude-sonnet-5')).toBe('Default (Claude Sonnet 5)');
+		expect(defaultModelLabel(models, 'gpt-5.4')).toBe('Default (GPT-5.4)');
+	});
+
+	it('falls back to the raw id when the id is not in the catalog', () => {
+		expect(defaultModelLabel([{ value: 'a', label: 'A' }], 'missing')).toBe('Default (missing)');
+	});
+});
+
+/**
+ * Anti-drift guard (MNG-1772): the label displayed for the empty option of each
+ * `select` engine must be derived from that engine's DEFAULT_*_MODEL. If someone
+ * bumps the default model without touching the label (or vice versa), this fails
+ * loudly — the "displayed default != resolved default" defect class this issue
+ * was about cannot silently reappear.
+ */
+describe('select engines: displayed default == resolved default', () => {
+	it('claude-code defaultValueLabel matches DEFAULT_CLAUDE_CODE_MODEL catalog label', () => {
+		const label = CLAUDE_CODE_MODELS.find((m) => m.value === DEFAULT_CLAUDE_CODE_MODEL)?.label;
+		expect(label).toBeDefined();
+		if (CLAUDE_CODE_ENGINE_DEFINITION.modelSelection.type === 'select') {
+			expect(CLAUDE_CODE_ENGINE_DEFINITION.modelSelection.defaultValueLabel).toBe(
+				`Default (${label})`,
+			);
+		}
+	});
+
+	it('codex defaultValueLabel matches DEFAULT_CODEX_MODEL catalog label', () => {
+		const label = CODEX_MODELS.find((m) => m.value === DEFAULT_CODEX_MODEL)?.label;
+		expect(label).toBeDefined();
+		if (CODEX_ENGINE_DEFINITION.modelSelection.type === 'select') {
+			expect(CODEX_ENGINE_DEFINITION.modelSelection.defaultValueLabel).toBe(`Default (${label})`);
+		}
+	});
+
+	it('select engines expose acceptedModelPrefixes as a plain string[]', () => {
+		for (const engine of DEFAULT_ENGINE_CATALOG) {
+			if (engine.modelSelection.type !== 'select') continue;
+			const prefixes = engine.modelSelection.acceptedModelPrefixes;
+			expect(Array.isArray(prefixes)).toBe(true);
+			for (const prefix of prefixes ?? []) {
+				expect(typeof prefix).toBe('string');
+			}
+		}
+	});
+});
+
 // ─── Individual engine definitions ────────────────────────────────────────────
 describe('LLMIST_ENGINE_DEFINITION', () => {
 	it('has correct id and label', () => {
diff --git a/tests/unit/web/agent-config-utils.test.ts b/tests/unit/web/agent-config-utils.test.ts
index 138d3680f..2588eda93 100644
--- a/tests/unit/web/agent-config-utils.test.ts
+++ b/tests/unit/web/agent-config-utils.test.ts
@@ -1,8 +1,10 @@
 import { describe, expect, it } from 'vitest';
 import type { ResolvedTrigger } from '../../../src/api/routers/_shared/triggerTypes.js';
+import type { Engine } from '../../../web/src/components/projects/agent-config-types.js';
 import {
 	countActiveTriggers,
 	engineHasCredentials,
+	isModelCompatibleWithEngine,
 } from '../../../web/src/components/projects/agent-config-utils.js';
 
 // ============================================================================
@@ -76,6 +78,90 @@ describe('engineHasCredentials', () => {
 	});
 });
 
+// ============================================================================
+// isModelCompatibleWithEngine
+// ============================================================================
+
+describe('isModelCompatibleWithEngine', () => {
+	const claudeCode: Engine = {
+		id: 'claude-code',
+		label: 'Claude Code',
+		modelSelection: {
+			type: 'select',
+			defaultValueLabel: 'Default (Claude Sonnet 5)',
+			options: [
+				{ value: 'claude-sonnet-5', label: 'Claude Sonnet 5' },
+				{ value: 'claude-opus-5', label: 'Claude Opus 5' },
+			],
+			acceptedModelPrefixes: ['claude-', 'anthropic:'],
+		},
+	};
+
+	const codex: Engine = {
+		id: 'codex',
+		label: 'Codex',
+		modelSelection: {
+			type: 'select',
+			defaultValueLabel: 'Default (GPT-5.4)',
+			options: [{ value: 'gpt-5.4', label: 'GPT-5.4' }],
+			acceptedModelPrefixes: ['openai:'],
+		},
+	};
+
+	const freeText: Engine = {
+		id: 'llmist',
+		label: 'LLMist',
+		modelSelection: { type: 'free-text' },
+	};
+
+	it('flags an openrouter model as incompatible with claude-code', () => {
+		expect(
+			isModelCompatibleWithEngine('openrouter:google/gemini-3-flash-preview', claudeCode),
+		).toBe(false);
+	});
+
+	it('accepts a catalog id for claude-code', () => {
+		expect(isModelCompatibleWithEngine('claude-sonnet-5', claudeCode)).toBe(true);
+	});
+
+	it('accepts a non-catalog claude- prefixed model for claude-code', () => {
+		expect(isModelCompatibleWithEngine('claude-opus-5', claudeCode)).toBe(true);
+	});
+
+	it('accepts an anthropic: prefixed model for claude-code', () => {
+		expect(isModelCompatibleWithEngine('anthropic:claude-sonnet-4-5', claudeCode)).toBe(true);
+	});
+
+	it('flags an openai model as incompatible with claude-code', () => {
+		expect(isModelCompatibleWithEngine('openai:gpt-5.4', claudeCode)).toBe(false);
+	});
+
+	it('accepts catalog ids and openai: prefixes for codex', () => {
+		expect(isModelCompatibleWithEngine('gpt-5.4', codex)).toBe(true);
+		expect(isModelCompatibleWithEngine('openai:gpt-5.4', codex)).toBe(true);
+	});
+
+	it('flags an openrouter model as incompatible with codex', () => {
+		expect(isModelCompatibleWithEngine('openrouter:google/gemini-3-flash-preview', codex)).toBe(
+			false,
+		);
+	});
+
+	it('treats every model as compatible with a free-text engine', () => {
+		expect(isModelCompatibleWithEngine('openrouter:google/gemini-3-flash-preview', freeText)).toBe(
+			true,
+		);
+	});
+
+	it('treats an empty model (inherit) as compatible', () => {
+		expect(isModelCompatibleWithEngine('', claudeCode)).toBe(true);
+	});
+
+	it('treats an engine without modelSelection as compatible', () => {
+		expect(isModelCompatibleWithEngine('anything', { id: 'x', label: 'X' })).toBe(true);
+	});
+});
+
 // ============================================================================
 // countActiveTriggers
 // ============================================================================
diff --git a/tests/unit/web/model-field.test.ts b/tests/unit/web/model-field.test.ts
index efdcddc65..f4205bf0c 100644
--- a/tests/unit/web/model-field.test.ts
+++ b/tests/unit/web/model-field.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest';
+import { resolveSelectEmptyLabel } from '../../../web/src/components/settings/model-field.js';
 import {
 	addPrefix,
 	formatContext,
@@ -7,6 +8,34 @@ import {
 	stripPrefix,
 } from '../../../web/src/lib/openrouter-utils.js';
 
+// ────────────────────────────────────────────────────────────────────────────
+// resolveSelectEmptyLabel — honors the caller's inheritance-aware defaultLabel
+// on the ModelField `select` branch (MNG-1772). The runtime chain is
+// override → per-agent → project.model with no engine-default step, so the
+// empty option must describe inheritance, not a fictional engine default.
+// ────────────────────────────────────────────────────────────────────────────
+describe('resolveSelectEmptyLabel', () => {
+	it('returns the caller defaultLabel when provided', () => {
+		expect(
+			resolveSelectEmptyLabel(
+				'Inherit from project (openrouter:google/gemini-3-flash-preview)',
+				'Default (Claude Sonnet 5)',
+			),
+		).toBe('Inherit from project (openrouter:google/gemini-3-flash-preview)');
+	});
+
+	it('falls back to the engine defaultValueLabel when defaultLabel is undefined', () => {
+		expect(resolveSelectEmptyLabel(undefined, 'Default (Claude Sonnet 5)')).toBe(
+			'Default (Claude Sonnet 5)',
+		);
+	});
+
+	it('prefers an empty-string defaultLabel only when it is nullish (uses ?? semantics)', () => {
+		// Empty string is a real value under ?? — kept for callers that pass ''.
+		expect(resolveSelectEmptyLabel('', 'Default (GPT-5.4)')).toBe('');
+	});
+});
+
 // Tests import directly from the shared utility module used by the production
 // component, so implementation drift between tests and production is impossible.
 
diff --git a/web/src/components/projects/agent-config-detail.tsx b/web/src/components/projects/agent-config-detail.tsx
index 9e192bb9b..17b5ca793 100644
--- a/web/src/components/projects/agent-config-detail.tsx
+++ b/web/src/components/projects/agent-config-detail.tsx
@@ -2,7 +2,7 @@
  * Agent detail view components: DefinitionAgentSection and AgentDetailView.
  * Renders the tabbed detail panel (Engine / Prompts / Triggers) for a single agent.
  */
-import { ArrowLeft } from 'lucide-react';
+import { AlertTriangle, ArrowLeft } from 'lucide-react';
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { EngineSettingsFields } from '@/components/settings/engine-settings-fields.js';
 import { ModelField } from '@/components/settings/model-field.js';
@@ -22,6 +22,7 @@ import {
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs.js';
 import { AGENT_LABELS, CATEGORY_LABELS } from '@/lib/trigger-agent-mapping.js';
 import type { AgentDetailViewProps, DefinitionAgentSectionProps } from './agent-config-types.js';
+import { isModelCompatibleWithEngine } from './agent-config-utils.js';
 import { AgentPromptOverrides } from './agent-prompt-overrides.js';
 
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: tabbed detail panel managing Engine/Prompts/Triggers tabs with per-tab state, mutations, and trigger category grouping
@@ -84,6 +85,18 @@ function DefinitionAgentSection({
 	const inheritedModel = projectModel ?? systemDefaults?.model;
 	const inheritedMaxIterations = projectMaxIterations ?? systemDefaults?.maxIterations;
 
+	// Effective engine + model for the compatibility check (walk inheritance).
+	// The runtime resolves model as override → per-agent → project.model with no
+	// engine-default step, so a `select`-type engine inheriting an incompatible
+	// model (e.g. claude-code + openrouter:...) crashes mid-run. Surface it here.
+	const effectiveModelEngineId = agentEngine || inheritedEngine;
+	const effectiveModelEngine = engines.find((engine) => engine.id === effectiveModelEngineId);
+	const effectiveModel = model || inheritedModel || '';
+	const showModelIncompatibilityWarning =
+		effectiveModelEngine?.modelSelection?.type === 'select' &&
+		effectiveModel.length > 0 &&
+		!isModelCompatibleWithEngine(effectiveModel, effectiveModelEngine);
+
 	// Sync form state when config changes (e.g. after invalidateQueries refetch)
 	// Skip clearing "Saved" if we just saved — the nonce effect will handle the timer
 	useEffect(() => {
@@ -232,6 +245,16 @@ function DefinitionAgentSection({
 							defaultLabel={inheritedModel ? `Inherit from project (${inheritedModel})` : undefined}
 							projectId={projectId}
 						/>
+						{showModelIncompatibilityWarning && (
+							<p className="flex items-start gap-1.5 text-xs text-amber-600 dark:text-amber-400">
+								<AlertTriangle className="mt-0.5 h-3.5 w-3.5 shrink-0" aria-hidden="true" />
+								<span>
+									Inherited model <strong>{effectiveModel}</strong> will fail on the{' '}
+									{effectiveModelEngine?.label ?? effectiveModelEngineId} engine — pick a compatible
+									model.
+								</span>
+							</p>
+						)}
 					</div>
 					{effectiveEngine && (
 						<EngineSettingsFields
diff --git a/web/src/components/projects/agent-config-types.ts b/web/src/components/projects/agent-config-types.ts
index c70877e00..93f7922ef 100644
--- a/web/src/components/projects/agent-config-types.ts
+++ b/web/src/components/projects/agent-config-types.ts
@@ -48,9 +48,19 @@ export type EngineSettingField =
 			step?: number;
 	  };
 
+export type EngineModelSelection =
+	| { type: 'free-text' }
+	| {
+			type: 'select';
+			defaultValueLabel: string;
+			options: { value: string; label: string }[];
+			acceptedModelPrefixes?: string[];
+	  };
+
 export interface Engine {
 	id: string;
 	label: string;
+	modelSelection?: EngineModelSelection;
 	settings?: {
 		title?: string;
 		description?: string;
diff --git a/web/src/components/projects/agent-config-utils.ts b/web/src/components/projects/agent-config-utils.ts
index 80296d2c0..ef082d1b5 100644
--- a/web/src/components/projects/agent-config-utils.ts
+++ b/web/src/components/projects/agent-config-utils.ts
@@ -4,8 +4,31 @@
  */
 
 import type { ResolvedTrigger } from '../shared/definition-trigger-toggles.js';
+import type { Engine } from './agent-config-types.js';
 import { engineCredentialKeys } from './engine-secrets.js';
 
+/**
+ * Returns true when `model` is compatible with a `select`-type engine — i.e. it
+ * is one of the engine's catalog options OR matches one of the engine's accepted
+ * model prefixes (`acceptedModelPrefixes`). Mirrors the runtime acceptance rules
+ * enforced by `resolveClaudeModel` / `resolveCodexModel` so the dashboard can
+ * warn at configuration time instead of crashing the run mid-flight (MNG-1772).
+ *
+ * `free-text` engines (and engines whose selection shape is unknown) accept any
+ * model string, so this always returns true for them — avoids false positives.
+ */
+export function isModelCompatibleWithEngine(model: string, engine: Engine): boolean {
+	const selection = engine.modelSelection;
+	// Only select-type engines constrain the model set.
+	if (!selection || selection.type !== 'select') return true;
+	// An empty model means "inherit"; compatibility is judged on the resolved
+	// value by the caller — treat empty as compatible here.
+	if (!model) return true;
+	if (selection.options.some((option) => option.value === model)) return true;
+	const prefixes = selection.acceptedModelPrefixes ?? [];
+	return prefixes.some((prefix) => model.startsWith(prefix));
+}
+
 /**
  * Returns true when the given engine has at least one credential key configured.
  * Derived from ENGINE_SECRETS in engine-secrets.ts — no separate mapping to maintain.
diff --git a/web/src/components/projects/project-harness-form.tsx b/web/src/components/projects/project-harness-form.tsx
index abf65152c..89e538773 100644
--- a/web/src/components/projects/project-harness-form.tsx
+++ b/web/src/components/projects/project-harness-form.tsx
@@ -226,7 +226,7 @@ export function ProjectHarnessForm({ project }: { project: Project }) {
 															value={model}
 															onChange={setModel}
 															engine={engine.id}
-															defaultLabel={defaults ? defaults.model : undefined}
+															defaultLabel={defaults ? `Default (${defaults.model})` : undefined}
 															projectId={project.id}
 														/>
 														<p className="text-xs text-muted-foreground">
diff --git a/web/src/components/settings/model-field.tsx b/web/src/components/settings/model-field.tsx
index 5af512dc1..627dc516e 100644
--- a/web/src/components/settings/model-field.tsx
+++ b/web/src/components/settings/model-field.tsx
@@ -26,6 +26,24 @@ interface ModelFieldProps {
 	projectId?: string;
 }
 
+/**
+ * Resolve the label rendered for the empty ("_none") option of a `select`-type
+ * engine's model picker.
+ *
+ * The runtime resolution chain is `override → per-agent → project.model` with no
+ * engine-default step (see `src/agents/shared/modelResolution.ts`), so when a
+ * caller supplies an inheritance-aware `defaultLabel` (e.g. "Inherit from project
+ * (X)") it must win over the engine catalog's hardcoded `defaultValueLabel`
+ * (e.g. "Default (Sonnet 5)"). Only when no caller label is provided do we fall
+ * back to the engine default. Exported so it can be unit-tested directly.
+ */
+export function resolveSelectEmptyLabel(
+	defaultLabel: string | undefined,
+	engineDefaultValueLabel: string,
+): string {
+	return defaultLabel ?? engineDefaultValueLabel;
+}
+
 export function ModelField({
 	value,
 	onChange,
@@ -44,7 +62,12 @@ export function ModelField({
 					<SelectValue placeholder="Select model" />
 				</SelectTrigger>
 				<SelectContent>
-					<SelectItem value="_none">{engineDefinition.modelSelection.defaultValueLabel}</SelectItem>
+					<SelectItem value="_none">
+						{resolveSelectEmptyLabel(
+							defaultLabel,
+							engineDefinition.modelSelection.defaultValueLabel,
+						)}
+					</SelectItem>
 					{engineDefinition.modelSelection.options.map((m) => (
 						<SelectItem key={m.value} value={m.value}>
 							{m.label}