fix(core): dynamic fallback routing for exhausted quota models

packages/core/src/config/config.test.ts

@@ -863,6 +863,16 @@ describe('Server Config (config.ts)', () => {
       expect(GeminiClient).toHaveBeenCalledWith(config);
     });
 
+    it('should clear fallback overrides when refreshing auth', async () => {
+      const config = new Config(baseParams);
+      config.activateFallbackMode('fallback-model', 'failed-model');
+      expect(config.getFallbackOverride('failed-model')).toBe('fallback-model');
+
+      await config.refreshAuth(AuthType.USE_GEMINI);
+
+      expect(config.getFallbackOverride('failed-model')).toBeUndefined();
+    });
+
     it('should pass Vertex AI routing settings when refreshing auth', async () => {
       const vertexAiRouting = {
         requestType: 'shared' as const,
@@ -1902,6 +1912,21 @@ describe('Server Config (config.ts)', () => {
     );
   });
 
+  it('clears fallback overrides when session changes', async () => {
+    const config = new Config({
+      ...baseParams,
+      sessionId: 'session-one',
+    });
+    await config.initialize();
+
+    config.activateFallbackMode('fallback-model', 'failed-model');
+    expect(config.getFallbackOverride('failed-model')).toBe('fallback-model');
+
+    config.setSessionId('session-two');
+
+    expect(config.getFallbackOverride('failed-model')).toBeUndefined();
+  });
+
   it('does not throw when changing sessions before the previous plans dir exists', async () => {
     const config = new Config({
       ...baseParams,
@@ -2715,6 +2740,16 @@ describe('Config getHooks', () => {
       expect(spy).toHaveBeenCalled();
     });
 
+    it('should clear fallback overrides when setting a model', () => {
+      const config = new Config(baseParams);
+      config.activateFallbackMode('fallback-model', 'failed-model');
+      expect(config.getFallbackOverride('failed-model')).toBe('fallback-model');
+
+      config.setModel('new-model');
+
+      expect(config.getFallbackOverride('failed-model')).toBeUndefined();
+    });
+
     it('should allow setting auto model from auto model and reset availability', () => {
       const config = new Config({
         cwd: '/tmp',

packages/core/src/config/config.ts

@@ -833,6 +833,7 @@ export class Config implements McpContext, AgentLoopContext {
   private ideMode: boolean;
 
   private _activeModel: string;
+  private fallbackOverrides = new Map<string, string>();
   private readonly maxSessionTurns: number;
   private readonly listSessions: boolean;
   private readonly deleteSession: string | undefined;
@@ -1567,6 +1568,8 @@ export class Config implements McpContext, AgentLoopContext {
   ) {
     // Reset availability service when switching auth
     this.modelAvailabilityService.reset();
+    this.fallbackOverrides.clear();
+    this.modelConfigService.clearRuntimeOverrides();
 
     // Vertex and Genai have incompatible encryption and sending history with
     // thoughtSignature from Genai to Vertex will fail, we need to strip them
@@ -1828,6 +1831,8 @@ export class Config implements McpContext, AgentLoopContext {
     this._sessionId = sessionId;
     this.storage.setSessionId(sessionId);
     this.trackerService = undefined;
+    this.fallbackOverrides.clear();
+    this.modelConfigService.clearRuntimeOverrides();
     this.approvedPlanPath = undefined;
     this.topicState.reset();
     this.skillManager.reset();
@@ -1921,16 +1926,29 @@ export class Config implements McpContext, AgentLoopContext {
       this.onModelChange(newModel);
     }
     this.modelAvailabilityService.reset();
+    this.fallbackOverrides.clear();
+    this.modelConfigService.clearRuntimeOverrides();
   }
 
-  activateFallbackMode(model: string): void {
+  activateFallbackMode(model: string, failedModel?: string): void {
     this.setModel(model, true);
+    if (failedModel) {
+      this.fallbackOverrides.set(failedModel, model);
+      this.modelConfigService.registerRuntimeModelOverride({
+        match: { model: failedModel },
+        modelConfig: { model },
+      });
+    }
     const authType = this.getContentGeneratorConfig()?.authType;
     if (authType) {
       logFlashFallback(this, new FlashFallbackEvent(authType));
     }
   }
 
+  getFallbackOverride(model: string): string | undefined {
+    return this.fallbackOverrides.get(model);
+  }
+
   getActiveModel(): string {
     return this._activeModel ?? this.model;
   }

packages/core/src/config/flashFallback.test.ts

@@ -73,5 +73,23 @@ describe('Flash Model Fallback Configuration', () => {
         expect.any(FlashFallbackEvent),
       );
     });
+
+    it('should set fallback override when failedModel is provided and register runtime override', () => {
+      config.activateFallbackMode(
+        DEFAULT_GEMINI_FLASH_MODEL,
+        DEFAULT_GEMINI_MODEL,
+      );
+      expect(config.getModel()).toBe(DEFAULT_GEMINI_FLASH_MODEL);
+      expect(config.getFallbackOverride(DEFAULT_GEMINI_MODEL)).toBe(
+        DEFAULT_GEMINI_FLASH_MODEL,
+      );
+
+      // Verify it registers the runtime model override with ModelConfigService
+      expect(
+        config
+          .getModelConfigService()
+          .getResolvedConfig({ model: DEFAULT_GEMINI_MODEL }).model,
+      ).toBe(DEFAULT_GEMINI_FLASH_MODEL);
+    });
   });
 });

packages/core/src/fallback/handler.test.ts

@@ -191,6 +191,7 @@ describe('handleFallback', () => {
         expect(policyConfig.getFallbackModelHandler).not.toHaveBeenCalled();
         expect(policyConfig.activateFallbackMode).toHaveBeenCalledWith(
           DEFAULT_GEMINI_FLASH_MODEL,
+          MOCK_PRO_MODEL,
         );
       } finally {
         chainSpy.mockRestore();
@@ -383,6 +384,7 @@ describe('handleFallback', () => {
       expect(result).toBe(true);
       expect(policyConfig.activateFallbackMode).toHaveBeenCalledWith(
         FALLBACK_MODEL,
+        MOCK_PRO_MODEL,
       );
       // TODO: add logging expect statement
     });

packages/core/src/fallback/handler.ts

@@ -42,8 +42,14 @@ export async function handleFallback(
     return { service: availability, policy: failedPolicy };
   };
 
+  const activeModel = config.getActiveModel();
   let fallbackModel: string;
+
   if (!candidates.length) {
+    if (failedModel !== activeModel) {
+      applyAvailabilityTransition(getAvailabilityContext, failureKind);
+      return processIntent(config, 'retry_always', activeModel, failedModel);
+    }
     fallbackModel = failedModel;
   } else {
     const selection = availability.selectFirstAvailable(
@@ -69,10 +75,11 @@ export async function handleFallback(
 
     // failureKind is already declared and calculated above
     const action = resolvePolicyAction(failureKind, selectedPolicy);
+    const activeModel = config.getActiveModel();
 
-    if (action === 'silent') {
+    if (action === 'silent' || fallbackModel === activeModel) {
       applyAvailabilityTransition(getAvailabilityContext, failureKind);
-      return processIntent(config, 'retry_always', fallbackModel);
+      return processIntent(config, 'retry_always', fallbackModel, failedModel);
     }
 
     // This will be used in the future when FallbackRecommendation is passed through UI
@@ -103,7 +110,7 @@ export async function handleFallback(
       applyAvailabilityTransition(getAvailabilityContext, failureKind);
     }
 
-    return await processIntent(config, intent, fallbackModel);
+    return await processIntent(config, intent, fallbackModel, failedModel);
   } catch (handlerError) {
     debugLogger.error('Fallback handler failed:', handlerError);
     return null;
@@ -131,12 +138,13 @@ async function processIntent(
   config: Config,
   intent: FallbackIntent | null,
   fallbackModel: string,
+  failedModel?: string,
 ): Promise<boolean> {
   switch (intent) {
     case 'retry_always':
       // TODO(telemetry): Implement generic fallback event logging. Existing
       // logFlashFallback is specific to a single Model.
-      config.activateFallbackMode(fallbackModel);
+      config.activateFallbackMode(fallbackModel, failedModel);
       return true;
 
     case 'retry_once':

packages/core/src/services/modelConfigService.test.ts

@@ -668,6 +668,31 @@ describe('ModelConfigService', () => {
       // Specificity should win over order
       expect(resolved.generateContentConfig.temperature).toBe(0.1);
     });
+
+    it('should clear runtime overrides', () => {
+      const config: ModelConfigServiceConfig = {
+        aliases: {},
+        overrides: [],
+      };
+      const service = new ModelConfigService(config);
+
+      service.registerRuntimeModelOverride({
+        match: { model: 'gemini-pro' },
+        modelConfig: { generateContentConfig: { temperature: 0.99 } },
+      });
+
+      expect(
+        service.getResolvedConfig({ model: 'gemini-pro' }).generateContentConfig
+          .temperature,
+      ).toBe(0.99);
+
+      service.clearRuntimeOverrides();
+
+      expect(
+        service.getResolvedConfig({ model: 'gemini-pro' }).generateContentConfig
+          .temperature,
+      ).toBeUndefined();
+    });
   });
 
   describe('custom aliases', () => {

packages/core/src/services/modelConfigService.ts

@@ -65,7 +65,7 @@
 export interface ModelDefinition {
   displayName?: string;
   tier?: string; // 'pro' | 'flash' | 'flash-lite' | 'custom' | 'auto'
   family?: string; // The gemini family, e.g. 'gemini-3' | 'gemini-2'
   isPreview?: boolean;
   // Specifies whether the model should be visible in the dialog.
   isVisible?: boolean;
@@ -344,6 +344,10 @@
     this.runtimeOverrides.push(override);
   }
 
+  clearRuntimeOverrides(): void {
+    this.runtimeOverrides.length = 0;
+  }
+
   /**
    * Resolves a model configuration by merging settings from aliases and applying overrides.
    *