fix(fallback): suppress stale active toasts

Author: blazejpawlak

AGENTS.md

@@ -9,7 +9,7 @@ OpenCode plugin that adds ordered model fallback chains with a health state mach
 ## Commands
 
 ```bash
-bun test              # Run all unit tests (163 tests across 16 files)
+bun test              # Run all unit tests (166 tests across 16 files)
 bunx tsc --noEmit     # Type check
 bun run build         # Build to dist/
 ```
@@ -133,7 +133,7 @@ Unit tests live in `test/`. Run with `bun test`.
 
 Integration tests for the replay orchestrator and full fallback flow exist in `test/orchestrator.test.ts`, using the mock client helper in `test/helpers/mock-client.ts`. Preemptive redirect tests are in `test/preemptive.test.ts`.
 
-Plugin event-handler hardening tests are in `test/plugin.test.ts`. `/fallback-status` tool output tests are in `test/fallback-status.test.ts`.
+Plugin event-handler hardening tests are in `test/plugin.test.ts`, including fallback-active and recovery notification guard behavior. `/fallback-status` tool output tests are in `test/fallback-status.test.ts`.
 
 Additional coverage includes startup command bootstrap (`test/plugin-create.test.ts`), logger redaction/fault-tolerance (`test/logger.test.ts`), fallback usage aggregation (`test/usage.test.ts`), and health-store timer lifecycle (`test/model-health-lifecycle.test.ts`).
 

Implementation.plan.md

@@ -107,12 +107,15 @@ interface ModelHealth {
 interface SessionFallbackState {
   sessionId: string;
   agentName: string | null; // resolved lazily from messages API
+  agentFile: string | null;
   originalModel: ModelKey | null;
   currentModel: ModelKey | null;
   fallbackDepth: number;
   isProcessing: boolean; // mutex for replay operations
   lastFallbackAt: number | null; // deduplication window
   fallbackHistory: FallbackEvent[]; // for /fallback-status reporting
+  recoveryNotifiedForModel: ModelKey | null;
+  fallbackActiveNotifiedKey: string | null; // dedupe repeated "Fallback Active" toasts
 }
 ```
 
@@ -127,8 +130,9 @@ chat.message hook fires (new user message)
   ├─ Check model health: is target model rate_limited?
   │   └─ No → return (message proceeds normally)
   │
-  ├─ Resolve fallback chain → pick healthy model
+  ├─ Resolve fallback chain (exact or normalized agent name) → pick healthy model
   ├─ Mutate output.message.model → redirect to fallback
+  ├─ Notify once per (original,current) fallback pair while fallback remains active
   └─ Message goes directly to fallback model (no 429 round-trip)
 ```
 
@@ -145,7 +149,7 @@ session.status event (type: "retry", message: "Rate limited...")
   ├─ Check deduplication window (3s since lastFallbackAt)
   │
   ├─ Resolve agent name (from cache or client.session.messages())
-  ├─ Look up fallback chain: config.agents[agentName] ?? config.agents["*"]
+  ├─ Look up fallback chain: exact agent match → normalized agent match → config.agents["*"]
   │
   ├─ Fetch messages → sync currentModel (detect TUI revert → reset fallbackDepth)
   ├─ Check maxFallbackDepth not exceeded (after sync so reset takes effect)
@@ -322,7 +326,7 @@ Addresses two problems: wasted 429 round-trips per message after a successful fa
 
 ## Verification Plan
 
-1. **Unit tests** (per module): config validation, pattern matching, classification, health transitions, chain resolution, message conversion, agent loader, preemptive redirect, plugin events, plugin startup bootstrap, logger redaction/fault tolerance, usage aggregation, fallback-status tool, tick recovery transitions, health timer lifecycle, path traversal security, YAML schema enforcement — **163/163 passing**
+1. **Unit tests** (per module): config validation, pattern matching, classification, health transitions, chain resolution, message conversion, agent loader, preemptive redirect, plugin events, plugin startup bootstrap, logger redaction/fault tolerance, usage aggregation, fallback-status tool, tick recovery transitions, health timer lifecycle, path traversal security, YAML schema enforcement — **166/166 passing**
 2. **Integration tests** (mock client): full fallback flow, cascading, max depth, concurrent events, session deletion — **complete**
 3. **Manual E2E test**: Install as local plugin, configure fallback chains, trigger rate limit, verify:
    - Detection logged correctly

src/plugin.ts

@@ -109,11 +109,13 @@ export const createPlugin: Plugin = async ({ client, directory }) => {
         });
       }
 
-      // Remind user on each turn while running on a fallback model
-      const current = sessionState.currentModel;
-      const original = sessionState.originalModel;
-      if (current && original && current !== original) {
-        notifyFallbackActive(client, original, current).catch(() => {});
+      const activeFallback = store.sessions.consumeFallbackActiveNotification(input.sessionID);
+      if (activeFallback) {
+        notifyFallbackActive(
+          client,
+          activeFallback.originalModel,
+          activeFallback.currentModel
+        ).catch(() => {});
       }
     },
 
@@ -287,6 +289,7 @@ export async function handleIdle(
   if (!state.originalModel) return;
   if (state.currentModel === state.originalModel) {
     state.recoveryNotifiedForModel = null;
+    state.fallbackActiveNotifiedKey = null;
     return;
   }
 

src/preemptive.ts

@@ -35,6 +35,7 @@ export function tryPreemptiveRedirect(
     sessionState.currentModel = modelKey;
     if (wasOnFallback && modelKey === sessionState.originalModel) {
       sessionState.fallbackDepth = 0;
+      store.sessions.clearFallbackActiveNotification(sessionId);
       logger.debug("preemptive.depth.reset", { sessionId, modelKey });
     }
   }

src/resolution/agent-resolver.ts

@@ -3,6 +3,11 @@ import type { ModelKey, PluginConfig } from "../types.js";
 
 type Client = PluginInput["client"];
 
+function normalizeAgentName(agentName: string): string {
+  const compact = agentName.toLowerCase().replace(/[^a-z0-9]/g, "");
+  return compact.endsWith("agent") ? compact.slice(0, -5) : compact;
+}
+
 /**
  * Map a session to its agent name, then to the fallback config for that agent.
  * Falls back to wildcard "*" agent config.
@@ -34,5 +39,16 @@ export function resolveFallbackModels(config: PluginConfig, agentName: string |
   if (agentName && config.agents[agentName]) {
     return config.agents[agentName].fallbackModels;
   }
+
+  if (agentName) {
+    const normalized = normalizeAgentName(agentName);
+    const matches = Object.entries(config.agents).filter(
+      ([name]) => name !== "*" && normalizeAgentName(name) === normalized
+    );
+    if (matches.length === 1) {
+      return matches[0][1].fallbackModels;
+    }
+  }
+
   return config.agents["*"]?.fallbackModels ?? [];
 }

src/state/session-state.ts

@@ -3,6 +3,10 @@ import type { ErrorCategory, FallbackEvent, ModelKey, SessionFallbackState } fro
 export class SessionStateStore {
   private store = new Map<string, SessionFallbackState>();
 
+  private getFallbackActiveKey(originalModel: ModelKey, currentModel: ModelKey): string {
+    return `${originalModel}->${currentModel}`;
+  }
+
   get(sessionId: string): SessionFallbackState {
     let state = this.store.get(sessionId);
     if (!state) {
@@ -86,9 +90,31 @@ export class SessionStateStore {
     if (!state.originalModel) {
       state.originalModel = model;
       state.currentModel = model;
+      state.fallbackActiveNotifiedKey = null;
     }
   }
 
+  consumeFallbackActiveNotification(
+    sessionId: string
+  ): { originalModel: ModelKey; currentModel: ModelKey } | null {
+    const state = this.get(sessionId);
+    const { originalModel, currentModel } = state;
+
+    if (!originalModel || !currentModel || originalModel === currentModel) return null;
+
+    const key = this.getFallbackActiveKey(originalModel, currentModel);
+    if (state.fallbackActiveNotifiedKey === key) return null;
+
+    state.fallbackActiveNotifiedKey = key;
+    return { originalModel, currentModel };
+  }
+
+  clearFallbackActiveNotification(sessionId: string): void {
+    const state = this.store.get(sessionId);
+    if (!state) return;
+    state.fallbackActiveNotifiedKey = null;
+  }
+
   setAgentName(sessionId: string, agentName: string): void {
     const state = this.get(sessionId);
     state.agentName = agentName;
@@ -105,6 +131,7 @@ export class SessionStateStore {
     state.fallbackHistory = [];
     state.lastFallbackAt = null;
     state.isProcessing = false;
+    state.fallbackActiveNotifiedKey = null;
     // Preserves: originalModel, currentModel, agentName, fallbackDepth
   }
 
@@ -128,6 +155,7 @@ export class SessionStateStore {
       lastFallbackAt: null,
       fallbackHistory: [],
       recoveryNotifiedForModel: null,
+      fallbackActiveNotifiedKey: null,
     };
   }
 }

src/types.ts

@@ -40,6 +40,7 @@ export interface SessionFallbackState {
   lastFallbackAt: number | null;
   fallbackHistory: FallbackEvent[];
   recoveryNotifiedForModel: ModelKey | null;
+  fallbackActiveNotifiedKey: string | null;
 }
 
 export interface AgentConfig {

test/fallback.test.ts

@@ -112,6 +112,21 @@ describe("resolveFallbackModels", () => {
     expect(result).toEqual(["a/1", "a/2"]);
   });
 
+  it("matches normalized agent names like Build -> BuildAgent", () => {
+    const result = resolveFallbackModels(
+      {
+        ...config,
+        agents: {
+          BuildAgent: { fallbackModels: ["c/1", "c/2"] },
+          "*": { fallbackModels: ["b/1"] },
+        },
+      },
+      "Build"
+    );
+
+    expect(result).toEqual(["c/1", "c/2"]);
+  });
+
   it("falls back to wildcard when agent not configured", () => {
     const result = resolveFallbackModels(config, "coder");
     expect(result).toEqual(["b/1"]);
@@ -204,4 +219,32 @@ describe("SessionStateStore", () => {
     const state = store.get("s9");
     expect(state.fallbackDepth).toBe(1);
   });
+
+  it("consumes fallback-active notification only once per fallback pair", () => {
+    const store = new SessionStateStore();
+    store.setOriginalModel("s10", "a/orig");
+    store.recordPreemptiveRedirect("s10", "a/orig", "a/fallback", "coder");
+
+    expect(store.consumeFallbackActiveNotification("s10")).toEqual({
+      originalModel: "a/orig",
+      currentModel: "a/fallback",
+    });
+    expect(store.consumeFallbackActiveNotification("s10")).toBeNull();
+  });
+
+  it("clears fallback-active notification after returning to original model", () => {
+    const store = new SessionStateStore();
+    store.setOriginalModel("s11", "a/orig");
+    store.recordPreemptiveRedirect("s11", "a/orig", "a/fallback", "coder");
+
+    expect(store.consumeFallbackActiveNotification("s11")).not.toBeNull();
+    store.clearFallbackActiveNotification("s11");
+    store.get("s11").currentModel = "a/orig";
+    store.recordPreemptiveRedirect("s11", "a/orig", "a/fallback", "coder");
+
+    expect(store.consumeFallbackActiveNotification("s11")).toEqual({
+      originalModel: "a/orig",
+      currentModel: "a/fallback",
+    });
+  });
 });

test/usage.test.ts

@@ -15,6 +15,7 @@ function baseState(): SessionFallbackState {
     lastFallbackAt: null,
     fallbackHistory: [],
     recoveryNotifiedForModel: null,
+    fallbackActiveNotifiedKey: null,
   };
 }