@gajae-code/coding-agent 0.10.1 → 0.11.0

package/src/config/model-profiles.ts

@@ -1,5 +1,6 @@
 import { sanitizeText } from "@gajae-code/utils";
 import type { GjcModelAssignmentTargetId } from "./model-registry";
+import { type ModelSelectorValue, normalizeModelSelectorValue } from "./model-selector-value";
 import type { ModelsConfig } from "./models-config-schema";
 
 export type ModelProfileRole = GjcModelAssignmentTargetId;
@@ -18,14 +19,14 @@ export interface ModelProfileDefinition {
 	 * means any single xiaomi credential satisfies the group.
 	 */
 	alternativeProviderGroups?: readonly (readonly string[])[];
-	modelMapping: Partial<Record<ModelProfileRole, string>>;
+	modelMapping: Partial<Record<ModelProfileRole, ModelSelectorValue>>;
 	source: "builtin" | "user";
 }
 
 export interface ResolvedProfileBinding {
-	defaultSelector?: string;
-	modelRoles: Record<string, string>;
-	agentModelOverrides: Partial<Record<Exclude<ModelProfileRole, "default">, string>>;
+	defaultSelector?: ModelSelectorValue;
+	modelRoles: Record<string, ModelSelectorValue>;
+	agentModelOverrides: Partial<Record<Exclude<ModelProfileRole, "default">, ModelSelectorValue>>;
 }
 
 function parseModelSelectorProvider(selector: string): string | undefined {
@@ -36,29 +37,31 @@ function parseModelSelectorProvider(selector: string): string | undefined {
 
 export function deriveModelProfileMappedProviders(definition: Pick<ModelProfileDefinition, "modelMapping">): string[] {
 	const providers = new Set<string>();
-	for (const selector of Object.values(definition.modelMapping)) {
-		if (!selector) continue;
-		const provider = parseModelSelectorProvider(selector);
-		if (provider) providers.add(provider);
+	for (const selectorValue of Object.values(definition.modelMapping)) {
+		for (const selector of normalizeModelSelectorValue(selectorValue)) {
+			const provider = parseModelSelectorProvider(selector);
+			if (provider) providers.add(provider);
+		}
 	}
 	return [...providers].sort((a, b) => a.localeCompare(b));
 }
 
+/**
+ * Return the providers explicitly declared as hard prerequisites.
+ * Model mappings may reference fallback providers, but those references are
+ * resolution-time candidates rather than activation requirements.
+ */
 export function aggregateModelProfileRequiredProviders(
 	requiredProviders: readonly string[],
-	definition: Pick<ModelProfileDefinition, "modelMapping">,
+	_definition: Pick<ModelProfileDefinition, "modelMapping">,
 ): string[] {
-	const providers = new Set(requiredProviders);
-	for (const provider of deriveModelProfileMappedProviders(definition)) {
-		providers.add(provider);
-	}
-	return [...providers];
+	return [...new Set(requiredProviders)];
 }
 
 const profile = (
 	name: string,
 	requiredProviders: string[],
-	modelMapping: Partial<Record<ModelProfileRole, string>>,
+	modelMapping: Partial<Record<ModelProfileRole, ModelSelectorValue>>,
 	alternativeProviderGroups?: readonly (readonly string[])[],
 ): ModelProfileDefinition => ({
 	name,
@@ -70,25 +73,25 @@ const profile = (
 
 export const BUILTIN_MODEL_PROFILES: readonly ModelProfileDefinition[] = [
 	profile("codex-eco", ["openai-codex"], {
-		default: "openai-codex/gpt-5.6-terra:high",
-		executor: "openai-codex/gpt-5.6-luna:high",
-		planner: "openai-codex/gpt-5.6-terra:medium",
-		critic: "openai-codex/gpt-5.6-terra:high",
-		architect: "openai-codex/gpt-5.6-sol:medium",
+		default: "openai-codex/gpt-5.6-terra:low",
+		executor: "openai-codex/gpt-5.6-luna:low",
+		planner: "openai-codex/gpt-5.6-luna:high",
+		critic: "openai-codex/gpt-5.6-terra:xhigh",
+		architect: "openai-codex/gpt-5.6-terra:high",
 	}),
 	profile("codex-medium", ["openai-codex"], {
-		default: "openai-codex/gpt-5.6-sol:medium",
-		executor: "openai-codex/gpt-5.6-terra:xhigh",
+		default: "openai-codex/gpt-5.6-sol:low",
+		executor: "openai-codex/gpt-5.6-terra:low",
 		planner: "openai-codex/gpt-5.6-terra:high",
-		critic: "openai-codex/gpt-5.6-terra:xhigh",
+		critic: "openai-codex/gpt-5.6-sol:xhigh",
 		architect: "openai-codex/gpt-5.6-sol:high",
 	}),
 	profile("codex-pro", ["openai-codex"], {
-		default: "openai-codex/gpt-5.6-sol:xhigh",
-		executor: "openai-codex/gpt-5.6-terra:xhigh",
+		default: "openai-codex/gpt-5.6-sol:medium",
+		executor: "openai-codex/gpt-5.6-terra:medium",
 		planner: "openai-codex/gpt-5.6-sol:high",
-		critic: "openai-codex/gpt-5.6-sol:xhigh",
-		architect: "openai-codex/gpt-5.6-sol:max",
+		critic: "openai-codex/gpt-5.6-sol:max",
+		architect: "openai-codex/gpt-5.6-sol:xhigh",
 	}),
 	profile("opencodego", ["opencode-go"], {
 		default: "opencode-go/kimi-k2.6",
@@ -256,21 +259,21 @@ export const BUILTIN_MODEL_PROFILES: readonly ModelProfileDefinition[] = [
 	}),
 	profile("opus-codex", ["anthropic", "openai-codex"], {
 		default: "anthropic/claude-opus-4-8:xhigh",
-		executor: "openai-codex/gpt-5.6-terra:xhigh",
-		planner: "openai-codex/gpt-5.6-terra:high",
-		critic: "openai-codex/gpt-5.6-terra:xhigh",
-		architect: "openai-codex/gpt-5.6-sol:xhigh",
+		executor: "openai-codex/gpt-5.6-terra:low",
+		planner: "anthropic/claude-sonnet-5",
+		critic: "openai-codex/gpt-5.6-sol:xhigh",
+		architect: "openai-codex/gpt-5.6-sol:high",
 	}),
 	profile("codex-opencodego", ["openai-codex", "opencode-go"], {
-		default: "openai-codex/gpt-5.6-terra:xhigh",
+		default: "openai-codex/gpt-5.6-sol:low",
 		executor: "opencode-go/deepseek-v4-pro",
 		planner: "opencode-go/kimi-k2.6",
 		critic: "opencode-go/mimo-v2.5-pro",
-		architect: "openai-codex/gpt-5.6-sol:xhigh",
+		architect: "openai-codex/gpt-5.6-sol:high",
 	}),
 	profile("fable-opus-codex", ["anthropic", "openai-codex"], {
 		default: "anthropic/claude-fable-5:high",
-		executor: "openai-codex/gpt-5.6-terra:xhigh",
+		executor: "openai-codex/gpt-5.6-terra:medium",
 		planner: "anthropic/claude-opus-4-8:medium",
 		critic: "anthropic/claude-opus-4-8:high",
 		architect: "openai-codex/gpt-5.6-sol:xhigh",

package/src/config/model-registry.ts

@@ -4,6 +4,7 @@ import {
 	type Api,
 	type AssistantMessageEventStream,
 	type AuthCredentialSelector,
+	applyFinalCodexGpt56ContextCap,
 	type CacheRetention,
 	type Context,
 	createModelManager,
@@ -52,6 +53,7 @@ import {
 	type ModelProfileDefinition,
 	mergeModelProfiles,
 } from "./model-profiles";
+import { type ModelSelectorValue, normalizeModelSelectorValue } from "./model-selector-value";
 import {
 	type ModelOverride,
 	type ModelProfileConfig,
@@ -1019,10 +1021,10 @@ export class ModelRegistry {
 	#modelBindingsTargetSettings: Settings | undefined;
 	#appliedModelBindingRoles = new Set<string>();
 	#appliedAgentModelBindingOverrides = new Set<string>();
-	#modelBindingRoleBaselines = new Map<string, string | undefined>();
-	#agentModelBindingBaselines = new Map<string, string | undefined>();
-	#lastAppliedModelBindingRoles = new Map<string, string>();
-	#lastAppliedAgentModelBindingOverrides = new Map<string, string>();
+	#modelBindingRoleBaselines = new Map<string, ModelSelectorValue | undefined>();
+	#agentModelBindingBaselines = new Map<string, ModelSelectorValue | undefined>();
+	#lastAppliedModelBindingRoles = new Map<string, ModelSelectorValue>();
+	#lastAppliedAgentModelBindingOverrides = new Map<string, ModelSelectorValue>();
 	#configError: ConfigError | undefined = undefined;
 	#modelsConfigFile: ConfigFile<ModelsConfig>;
 	#lastStaticLoadMtime: number | null = null;
@@ -1181,7 +1183,7 @@ export class ModelRegistry {
 		// Merge runtime extension models so they survive refresh() cycles
 		const combined = this.#mergeCustomModels(withConfigModels, this.#runtimeModelOverlays);
 		const withModelOverrides = this.#applyModelOverrides(combined, this.#modelOverrides);
-		this.#models = this.#applyRuntimeProviderOverrides(withModelOverrides);
+		this.#models = applyFinalCodexGpt56ContextCap(this.#applyRuntimeProviderOverrides(withModelOverrides));
 		this.#rebuildCanonicalIndex();
 		this.#lastStaticLoadMtime = this.#modelsConfigFile.getMtimeMs();
 	}
@@ -1698,6 +1700,19 @@ export class ModelRegistry {
 		this.#applyConfiguredModelBindingsToTarget();
 	}
 
+	#cloneModelSelectorValue(value: ModelSelectorValue | undefined): ModelSelectorValue | undefined {
+		return Array.isArray(value) ? [...value] : value;
+	}
+
+	#modelSelectorValuesEqual(left: ModelSelectorValue | undefined, right: ModelSelectorValue | undefined): boolean {
+		const leftSelectors = normalizeModelSelectorValue(left);
+		const rightSelectors = normalizeModelSelectorValue(right);
+		return (
+			leftSelectors.length === rightSelectors.length &&
+			leftSelectors.every((selector, index) => selector === rightSelectors[index])
+		);
+	}
+
 	#applyConfiguredModelBindingsToTarget(): void {
 		const targetSettings = this.#modelBindingsTargetSettings;
 		if (!targetSettings) return;
@@ -1708,26 +1723,25 @@ export class ModelRegistry {
 		for (const role of this.#appliedModelBindingRoles) {
 			if (configuredModelRoleKeys.has(role)) continue;
 			const lastApplied = this.#lastAppliedModelBindingRoles.get(role);
-			if (lastApplied !== undefined && nextModelRoles[role] === lastApplied) {
+			if (lastApplied !== undefined && this.#modelSelectorValuesEqual(nextModelRoles[role], lastApplied)) {
 				const baseline = this.#modelBindingRoleBaselines.get(role);
 				if (baseline === undefined) {
 					delete nextModelRoles[role];
 				} else {
-					nextModelRoles[role] = baseline;
+					nextModelRoles[role] = this.#cloneModelSelectorValue(baseline)!;
 				}
 			}
 			this.#modelBindingRoleBaselines.delete(role);
 			this.#lastAppliedModelBindingRoles.delete(role);
 		}
-		for (const [role, modelId] of Object.entries(configuredModelRoles)) {
-			if (!modelId) continue;
+		for (const [role, selector] of Object.entries(configuredModelRoles)) {
 			const previousApplied = this.#lastAppliedModelBindingRoles.get(role);
 			if (!this.#modelBindingRoleBaselines.has(role)) {
-				this.#modelBindingRoleBaselines.set(role, nextModelRoles[role]);
+				this.#modelBindingRoleBaselines.set(role, this.#cloneModelSelectorValue(nextModelRoles[role]));
 			}
-			if (previousApplied === undefined || nextModelRoles[role] === previousApplied) {
-				nextModelRoles[role] = modelId;
-				this.#lastAppliedModelBindingRoles.set(role, modelId);
+			if (previousApplied === undefined || this.#modelSelectorValuesEqual(nextModelRoles[role], previousApplied)) {
+				nextModelRoles[role] = this.#cloneModelSelectorValue(selector)!;
+				this.#lastAppliedModelBindingRoles.set(role, this.#cloneModelSelectorValue(selector)!);
 			}
 		}
 		targetSettings.override("modelRoles", nextModelRoles);
@@ -1739,26 +1753,34 @@ export class ModelRegistry {
 		for (const agentName of this.#appliedAgentModelBindingOverrides) {
 			if (configuredAgentModelOverrideKeys.has(agentName)) continue;
 			const lastApplied = this.#lastAppliedAgentModelBindingOverrides.get(agentName);
-			if (lastApplied !== undefined && nextAgentModelOverrides[agentName] === lastApplied) {
+			if (
+				lastApplied !== undefined &&
+				this.#modelSelectorValuesEqual(nextAgentModelOverrides[agentName], lastApplied)
+			) {
 				const baseline = this.#agentModelBindingBaselines.get(agentName);
 				if (baseline === undefined) {
 					delete nextAgentModelOverrides[agentName];
 				} else {
-					nextAgentModelOverrides[agentName] = baseline;
+					nextAgentModelOverrides[agentName] = this.#cloneModelSelectorValue(baseline)!;
 				}
 			}
 			this.#agentModelBindingBaselines.delete(agentName);
 			this.#lastAppliedAgentModelBindingOverrides.delete(agentName);
 		}
-		for (const [agentName, modelId] of Object.entries(configuredAgentModelOverrides)) {
-			if (!modelId) continue;
+		for (const [agentName, selector] of Object.entries(configuredAgentModelOverrides)) {
 			const previousApplied = this.#lastAppliedAgentModelBindingOverrides.get(agentName);
 			if (!this.#agentModelBindingBaselines.has(agentName)) {
-				this.#agentModelBindingBaselines.set(agentName, nextAgentModelOverrides[agentName]);
+				this.#agentModelBindingBaselines.set(
+					agentName,
+					this.#cloneModelSelectorValue(nextAgentModelOverrides[agentName]),
+				);
 			}
-			if (previousApplied === undefined || nextAgentModelOverrides[agentName] === previousApplied) {
-				nextAgentModelOverrides[agentName] = modelId;
-				this.#lastAppliedAgentModelBindingOverrides.set(agentName, modelId);
+			if (
+				previousApplied === undefined ||
+				this.#modelSelectorValuesEqual(nextAgentModelOverrides[agentName], previousApplied)
+			) {
+				nextAgentModelOverrides[agentName] = this.#cloneModelSelectorValue(selector)!;
+				this.#lastAppliedAgentModelBindingOverrides.set(agentName, this.#cloneModelSelectorValue(selector)!);
 			}
 		}
 		targetSettings.override("task.agentModelOverrides", nextAgentModelOverrides);
@@ -1803,7 +1825,7 @@ export class ModelRegistry {
 		// Merge runtime extension models so they survive online discovery completion
 		const combined = this.#mergeCustomModels(withConfigModels, this.#runtimeModelOverlays);
 		const withModelOverrides = this.#applyModelOverrides(combined, this.#modelOverrides);
-		this.#models = this.#applyRuntimeProviderOverrides(withModelOverrides);
+		this.#models = applyFinalCodexGpt56ContextCap(this.#applyRuntimeProviderOverrides(withModelOverrides));
 		this.#rebuildCanonicalIndex();
 	}
 
@@ -1812,6 +1834,7 @@ export class ModelRegistry {
 		strategy: ModelRefreshStrategy,
 	): Promise<Model<Api>[]> {
 		const cached = readModelCache<Api>(providerConfig.provider, 24 * 60 * 60 * 1000, Date.now, this.#cacheDbPath);
+		const cachedModels = applyFinalCodexGpt56ContextCap(cached?.models ?? []);
 		const requiresAuth = !this.#keylessProviders.has(providerConfig.provider);
 		if (requiresAuth) {
 			const apiKey = await this.#peekApiKeyForProvider(providerConfig.provider);
@@ -1822,10 +1845,10 @@ export class ModelRegistry {
 					optional: providerConfig.optional ?? false,
 					stale: cached !== null,
 					fetchedAt: cached?.updatedAt,
-					models: cached?.models.map(model => model.id) ?? [],
+					models: cachedModels.map(model => model.id),
 				});
 				this.#lastDiscoveryWarnings.delete(providerConfig.provider);
-				return cached?.models ?? [];
+				return cachedModels;
 			}
 		}
 
@@ -2878,13 +2901,15 @@ export class ModelRegistry {
 			if (config.oauth?.modifyModels) {
 				const credential = this.authStorage.getOAuthCredential(providerName);
 				if (credential) {
-					this.#models = config.oauth.modifyModels(withRuntimeTransportOverride, credential);
+					this.#models = applyFinalCodexGpt56ContextCap(
+						config.oauth.modifyModels(withRuntimeTransportOverride, credential),
+					);
 					this.#rebuildCanonicalIndex();
 					return;
 				}
 			}
 
-			this.#models = withRuntimeTransportOverride;
+			this.#models = applyFinalCodexGpt56ContextCap(withRuntimeTransportOverride);
 			this.#rebuildCanonicalIndex();
 			return;
 		}

package/src/config/model-resolver.ts

@@ -9,11 +9,22 @@ import { logger } from "@gajae-code/utils";
 import chalk from "chalk";
 import { parseThinkingLevel, resolveThinkingLevelForModel } from "../thinking";
 import { isAuthenticated, kNoAuth, MODEL_ROLE_IDS, type ModelRegistry, type ModelRole } from "./model-registry";
+import { type ModelSelectorValue, normalizeModelSelectorValue } from "./model-selector-value";
 import type { Settings } from "./settings";
 
 /** Default model IDs for each known provider */
 export const defaultModelPerProvider: Record<KnownProvider, string> = DEFAULT_MODEL_PER_PROVIDER;
 
+/**
+ * Cursor's current RPC transport executes its exec protocol while streaming and
+ * has no client-side tool-call mode. Managed fallback attempts must not enable
+ * that irreversible path.
+ */
+export function managedCursorFallbackUnavailableReason(model: Model<Api>, selector: string): string | undefined {
+	if (model.api !== "cursor-agent") return undefined;
+	return `Cursor model ${selector} requires provider-side tool execution and cannot be used in a retryable fallback chain`;
+}
+
 export interface ScopedModelSelection {
 	model: Model<Api>;
 	thinkingLevel?: ThinkingLevel;
@@ -524,10 +535,8 @@ function getModelRoleAlias(value: string): ModelRole | undefined {
 	return undefined;
 }
 
-function normalizeModelPatternList(value: string | string[] | undefined): string[] {
-	if (!value) return [];
-	const patterns = Array.isArray(value) ? value : value.split(",");
-	return patterns.map(pattern => pattern.trim()).filter(Boolean);
+function normalizeModelPatternList(value: ModelSelectorValue | undefined): string[] {
+	return normalizeModelSelectorValue(value);
 }
 
 function isSessionInheritedAgentPattern(value: string): boolean {
@@ -545,7 +554,7 @@ function resolveConfiguredRolePattern(value: string, settings?: Settings): strin
 	const role = getModelRoleAlias(aliasCandidate);
 	if (!role) return [normalized];
 
-	const configured = settings?.getModelRole(role)?.trim();
+	const configured = settings?.getModelRole(role);
 	const resolved = configured ? normalizeModelPatternList(configured) : undefined;
 	if (!resolved || resolved.length === 0) {
 		return undefined;
@@ -560,14 +569,14 @@ function resolveConfiguredRolePattern(value: string, settings?: Settings): strin
 export function expandRoleAlias(value: string, settings?: Settings): string {
 	const normalized = value.trim();
 	if (normalized === DEFAULT_MODEL_ROLE) {
-		return settings?.getModelRole("default") ?? value;
+		return normalizeModelPatternList(settings?.getModelRole("default"))[0] ?? value;
 	}
 
 	const resolved = resolveConfiguredRolePattern(value, settings)?.[0];
 	return resolved ?? value;
 }
 
-export function resolveConfiguredModelPatterns(value: string | string[] | undefined, settings?: Settings): string[] {
+export function resolveConfiguredModelPatterns(value: ModelSelectorValue | undefined, settings?: Settings): string[] {
 	const patterns = normalizeModelPatternList(value);
 	return patterns.flatMap(pattern => {
 		const resolved = resolveConfiguredRolePattern(pattern, settings);
@@ -575,8 +584,8 @@ export function resolveConfiguredModelPatterns(value: string | string[] | undefi
 	});
 }
 export interface AgentModelPatternResolutionOptions {
-	settingsOverride?: string | string[];
-	agentModel?: string | string[];
+	settingsOverride?: ModelSelectorValue;
+	agentModel?: ModelSelectorValue;
 	settings?: Settings;
 	activeModelPattern?: string;
 	fallbackModelPattern?: string;
@@ -597,7 +606,10 @@ export function resolveAgentModelPatterns(options: AgentModelPatternResolutionOp
 	}
 
 	const fallback =
-		activeModelPattern?.trim() || fallbackModelPattern?.trim() || settings?.getModelRole("default")?.trim() || "";
+		activeModelPattern?.trim() ||
+		fallbackModelPattern?.trim() ||
+		normalizeModelPatternList(settings?.getModelRole("default"))[0] ||
+		"";
 	return resolveConfiguredModelPatterns(fallback, settings);
 }
 
@@ -612,21 +624,14 @@ export interface ResolvedModelRoleValue {
 }
 
 export function resolveModelRoleValue(
-	roleValue: string | undefined,
+	roleValue: ModelSelectorValue | undefined,
 	availableModels: Model<Api>[],
 	options?: { settings?: Settings; matchPreferences?: ModelMatchPreferences; modelRegistry?: CanonicalModelRegistry },
 ): ResolvedModelRoleValue {
-	if (!roleValue) {
-		return { model: undefined, thinkingLevel: undefined, explicitThinkingLevel: false, warning: undefined };
-	}
-
-	const normalized = roleValue.trim();
-	if (!normalized || normalized === DEFAULT_MODEL_ROLE) {
-		return { model: undefined, thinkingLevel: undefined, explicitThinkingLevel: false, warning: undefined };
-	}
-
-	const effectivePatterns = resolveConfiguredRolePattern(normalized, options?.settings);
-	if (!effectivePatterns || effectivePatterns.length === 0) {
+	const effectivePatterns = normalizeModelPatternList(roleValue).flatMap(
+		pattern => resolveConfiguredRolePattern(pattern, options?.settings) ?? [],
+	);
+	if (effectivePatterns.length === 0) {
 		return { model: undefined, thinkingLevel: undefined, explicitThinkingLevel: false, warning: undefined };
 	}
 
@@ -654,11 +659,10 @@ export function resolveModelRoleValue(
 }
 
 export function extractExplicitThinkingSelector(
-	value: string | undefined,
+	value: ModelSelectorValue | undefined,
 	settings?: Settings,
 ): ThinkingLevel | undefined {
-	if (!value) return undefined;
-	const normalized = value.trim();
+	const normalized = normalizeModelPatternList(value)[0];
 	if (!normalized || normalized === DEFAULT_MODEL_ROLE) return undefined;
 
 	const visited = new Set<string>();
@@ -712,12 +716,13 @@ export function resolveModelFromSettings(options: {
 	let sawConfiguredProviderQualifiedRole = false;
 	for (const role of roles) {
 		const configured = settings.getModelRole(role);
-		if (!configured) continue;
-		const expanded = expandRoleAlias(configured, settings).trim();
+		const expanded = normalizeModelPatternList(configured)[0];
+		if (!expanded) continue;
+		const resolvedValue = expandRoleAlias(expanded, settings).trim();
 		if (expanded.includes("/")) {
 			sawConfiguredProviderQualifiedRole = true;
 		}
-		const resolved = resolveModelFromString(expanded, availableModels, matchPreferences, modelRegistry);
+		const resolved = resolveModelFromString(resolvedValue, availableModels, matchPreferences, modelRegistry);
 		if (resolved) return resolved;
 	}
 	return sawConfiguredProviderQualifiedRole ? undefined : availableModels[0];
@@ -747,6 +752,56 @@ export function resolveModelOverride(
 	return { explicitThinkingLevel: false };
 }
 
+/**
+ * Resolve a configured fallback chain to its first callable entry without
+ * charging requests. For retryable chains, consumers MUST pass
+ * `{ managedFallback: true }` so unsuitable entries (including Cursor's
+ * provider-side tool mode) fail closed during resolution before any request
+ * is attempted. Single-entry chains remain non-managed selections.
+ */
+export interface ModelChainResolutionOptions {
+	managedFallback?: boolean;
+}
+
+export async function resolveModelChainWithAuth(
+	modelPatterns: readonly string[],
+	modelRegistry: ModelLookupRegistry & Pick<ModelRegistry, "getApiKey">,
+	settings?: Settings,
+	sessionId?: string,
+	options?: ModelChainResolutionOptions,
+): Promise<{
+	model?: Model<Api>;
+	thinkingLevel?: ThinkingLevel;
+	explicitThinkingLevel: boolean;
+	activeIndex: number;
+	skips: Array<{ selector: string; reason: string }>;
+}> {
+	const availableModels = modelRegistry.getAvailable();
+	const matchPreferences = { usageOrder: settings?.getStorage()?.getModelUsageOrder() };
+	const skips: Array<{ selector: string; reason: string }> = [];
+	for (let activeIndex = 0; activeIndex < modelPatterns.length; activeIndex += 1) {
+		const selector = modelPatterns[activeIndex];
+		const candidate = resolveModelRoleValue(selector, availableModels, { settings, matchPreferences, modelRegistry });
+		if (!candidate.model) {
+			skips.push({ selector, reason: "unknown_model" });
+			continue;
+		}
+		if (options?.managedFallback && modelPatterns.length > 1) {
+			const cursorReason = managedCursorFallbackUnavailableReason(candidate.model, selector);
+			if (cursorReason) {
+				skips.push({ selector, reason: cursorReason });
+				continue;
+			}
+		}
+		const key = await modelRegistry.getApiKey(candidate.model, sessionId);
+		if (key === kNoAuth || isAuthenticated(key)) {
+			return { ...candidate, activeIndex, skips };
+		}
+		skips.push({ selector, reason: "unauthenticated" });
+	}
+	return { explicitThinkingLevel: false, activeIndex: modelPatterns.length, skips };
+}
+
 /**
  * Resolve a list of override patterns to the first matching model, with an
  * auth-aware fallback to the parent session's active model.
@@ -774,6 +829,7 @@ export async function resolveModelOverrideWithAuthFallback(
 	modelRegistry: ModelLookupRegistry & Pick<ModelRegistry, "getApiKey">,
 	settings?: Settings,
 	sessionId?: string,
+	options?: ModelChainResolutionOptions,
 ): Promise<{
 	model?: Model<Api>;
 	thinkingLevel?: ThinkingLevel;
@@ -781,31 +837,62 @@ export async function resolveModelOverrideWithAuthFallback(
 	authFallbackUsed: boolean;
 	requestedModel?: Model<Api>;
 	fallbackReason?: "auth_unavailable";
+	activeIndex?: number;
+	parentFallbackSelector?: string;
+	skips: Array<{ selector: string; reason: string }>;
 }> {
-	const primary = resolveModelOverride(modelPatterns, modelRegistry, settings);
-	const unchanged = { ...primary, requestedModel: primary.model, authFallbackUsed: false };
-	if (!primary.model || !parentActiveModelPattern) {
-		return unchanged;
-	}
-
-	const primaryKey = await modelRegistry.getApiKey(primary.model, sessionId);
-	if (primaryKey === kNoAuth || isAuthenticated(primaryKey)) {
-		return unchanged;
-	}
-
-	const fallback = resolveModelOverride([parentActiveModelPattern], modelRegistry, settings);
-	if (!fallback.model) {
-		return unchanged;
-	}
-	if (modelsAreEqual(fallback.model, primary.model)) {
-		return unchanged;
-	}
-	const fallbackKey = await modelRegistry.getApiKey(fallback.model, sessionId);
-	if (!isAuthenticated(fallbackKey)) {
-		return unchanged;
+	const availableModels = modelRegistry.getAvailable();
+	const matchPreferences = { usageOrder: settings?.getStorage()?.getModelUsageOrder() };
+	let requestedModel: Model<Api> | undefined;
+	let requestedResolution: ResolvedModelRoleValue | undefined;
+	const skips: Array<{ selector: string; reason: string }> = [];
+	let activeIndex = 0;
+	for (const pattern of modelPatterns) {
+		const candidate = resolveModelRoleValue(pattern, availableModels, { settings, matchPreferences, modelRegistry });
+		if (!requestedModel && candidate.model) {
+			requestedModel = candidate.model;
+			requestedResolution = candidate;
+		}
+		if (!candidate.model) {
+			skips.push({ selector: pattern, reason: "unknown_model" });
+			activeIndex += 1;
+			continue;
+		}
+		if (options?.managedFallback && modelPatterns.length > 1) {
+			const cursorReason = managedCursorFallbackUnavailableReason(candidate.model, pattern);
+			if (cursorReason) {
+				skips.push({ selector: pattern, reason: cursorReason });
+				activeIndex += 1;
+				continue;
+			}
+		}
+		const key = await modelRegistry.getApiKey(candidate.model, sessionId);
+		if (key === kNoAuth || isAuthenticated(key)) {
+			return { ...candidate, requestedModel: candidate.model, authFallbackUsed: false, activeIndex, skips };
+		}
+		skips.push({ selector: pattern, reason: "unauthenticated" });
+		activeIndex += 1;
+	}
+	const fallback = parentActiveModelPattern
+		? resolveModelOverride([parentActiveModelPattern], modelRegistry, settings)
+		: { explicitThinkingLevel: false };
+	if (fallback.model) {
+		const fallbackKey = await modelRegistry.getApiKey(fallback.model, sessionId);
+		if (fallbackKey === kNoAuth || isAuthenticated(fallbackKey)) {
+			const isParentSubstitution = requestedModel === undefined || !modelsAreEqual(fallback.model, requestedModel);
+			return {
+				...fallback,
+				requestedModel,
+				authFallbackUsed: requestedModel !== undefined && isParentSubstitution,
+				fallbackReason: requestedModel && isParentSubstitution ? "auth_unavailable" : undefined,
+				parentFallbackSelector: isParentSubstitution ? formatModelString(fallback.model) : undefined,
+				skips,
+			};
+		}
 	}
-
-	return { ...fallback, requestedModel: primary.model, authFallbackUsed: true, fallbackReason: "auth_unavailable" };
+	return requestedResolution
+		? { ...requestedResolution, requestedModel, authFallbackUsed: false, activeIndex, skips }
+		: { explicitThinkingLevel: false, requestedModel, authFallbackUsed: false, activeIndex, skips };
 }
 
 /**

package/src/config/model-selector-value.ts

@@ -0,0 +1,50 @@
+import * as z from "zod/v4";
+
+/** A model selector or an ordered fallback chain of selectors. */
+export type ModelSelectorValue = string | readonly string[];
+
+/**
+ * Accept one validated selector or a non-empty ordered chain of validated selectors.
+ * Element schemas own each configuration surface's selector grammar.
+ */
+export function stringOrNonEmptyArray<T extends z.ZodType<string>>(elementSchema: T) {
+	return z.union([elementSchema, z.array(elementSchema).min(1)]);
+}
+
+/** Return whether a value is a non-blank selector or a non-empty selector chain. */
+export function isModelSelectorValue(value: unknown): value is ModelSelectorValue {
+	return (
+		(typeof value === "string" && value.trim().length > 0) ||
+		(Array.isArray(value) &&
+			value.length > 0 &&
+			value.every(item => typeof item === "string" && item.trim().length > 0))
+	);
+}
+
+/**
+ * Preserve compatibility with comma-delimited selector strings while flattening
+ * configured chains in their declared order.
+ */
+export function normalizeModelSelectorValue(value: ModelSelectorValue | undefined): string[] {
+	if (value === undefined) return [];
+	if (typeof value === "string") {
+		return value
+			.split(",")
+			.map(part => part.trim())
+			.filter(Boolean);
+	}
+	if (!Array.isArray(value)) return [];
+	return value
+		.filter((selector): selector is string => typeof selector === "string")
+		.flatMap(selector =>
+			selector
+				.split(",")
+				.map(part => part.trim())
+				.filter(Boolean),
+		);
+}
+
+/** Return the first configured selector for consumers that need one selector. */
+export function selectorHead(value: ModelSelectorValue | undefined): string | undefined {
+	return normalizeModelSelectorValue(value)[0];
+}