@iloveagents/foundry-agent 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @iloveagents/foundry-agent
 
+## 0.1.4
+
+### Patch Changes
+
+- 07ace7e: fix(agent): canonical MSAL.js recovery — acquireTokenRedirect-first, orphaned-state cleanup, dedup
+
+  Closes the production "stuck on 401 forever" bug observed on andritz-dev after the 0.1.2 / 0.1.3 fixes. Diagnostic on the live tab showed `getAllAccounts() === []` despite localStorage holding 3 access tokens + 1 refresh token — the orphaned-state signature.
+
+  **Root cause:** The previous recovery code did `setActiveAccount(null) + clearCache({account}) + loginRedirect()`. When `loginRedirect()` silently failed to navigate (caught by our try/catch — popup blocker, browser policy, async race), the account record was already gone but the tokens lingered. Every subsequent API call hit `getAllAccounts() === []` and silently returned `null` — no Bearer header, endless 401s, only manual `localStorage.clear()` recovered.
+
+  **Canonical 2026 fix per Microsoft Learn `entra/msal/javascript/browser/errors`** + linked GitHub issues + msal-react samples:
+  1. **`acquireTokenRedirect` first, not `loginRedirect`.** It's the documented primitive for refreshing a known account's tokens — preserves the account record across the navigation. `loginRedirect` is only the fallback when `acquireTokenRedirect` itself fails to navigate.
+  2. **Never `clearCache` before redirect.** The redirect navigation IS the recovery signal; if it succeeds, MSAL handles state cleanup; if it fails, leave state intact for the next attempt rather than orphaning the cache.
+  3. **Detect + repair orphaned state.** When `getAllAccounts() === []` but localStorage has MSAL token entries, nuke ALL `msal.*` keys (localStorage + sessionStorage) and force a fresh `loginRedirect`. Without this, the SPA renders authenticated UI but every API call goes anonymous.
+  4. **Module-level recovery deduplication.** Multiple parallel API calls all hitting the recovery path simultaneously now share a single in-flight redirect promise instead of each issuing their own (which would cascade `interaction_in_progress` errors).
+
+  The previous `recoverFromHardAuthFailure` callback now uses the same primitive — single recovery path for both "MSAL silent failed" and "API rejected refreshed token".
+
+  68/68 agent tests pass (was 65) — the new tests assert the no-clearCache invariant, the acquireTokenRedirect-first ordering, the loginRedirect fallback path, and the orphaned-state nuke + redirect. Pair: lastspace bump to ^0.1.4.
+
 ## 0.1.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iloveagents/foundry-agent",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "types": "./src/index.ts",

package/src/__tests__/auth-store.test.ts

@@ -125,12 +125,13 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
     );
   });
 
-  it("recoverFromHardAuthFailure clears cache + starts loginRedirect", async () => {
+  it("recoverFromHardAuthFailure starts acquireTokenRedirect (preserves account)", async () => {
     // When the fetch interceptor's force-refresh retry STILL gets 401,
-    // the only correct UX is a fresh ``loginRedirect`` (server policy
-    // drift, audience mismatch, etc.). Same recovery primitive used by
-    // the silent path, but invoked from the resource-server signal
-    // rather than an MSAL exception.
+    // server-side drift (audience / claims / conditional-access) means
+    // we need a fresh interactive auth. Same recovery primitive as the
+    // silent-failure path: ``acquireTokenRedirect`` first (preserves
+    // the account record), ``loginRedirect`` only as fallback. Cache
+    // is NOT cleared before redirect.
     const msal = mockMsal();
     const reason = new Error("API returned 401 after force-refresh retry");
     await expectInteractiveRecoveryError(
@@ -141,8 +142,8 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
         messageIncludes: ["interaction required"],
       },
     );
-    expect(msal.clearCache).toHaveBeenCalled();
-    expect(msal.loginRedirect).toHaveBeenCalledOnce();
+    expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
+    expect(msal.clearCache).not.toHaveBeenCalled();
   });
 
   it("returns null without redirecting when no account is cached", async () => {
@@ -155,7 +156,12 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
     expect(msal.loginRedirect).not.toHaveBeenCalled();
   });
 
-  it("clears stale cache and redirects on InteractionRequiredAuthError", async () => {
+  it("uses acquireTokenRedirect on InteractionRequiredAuthError (preserves account)", async () => {
+    // Canonical 2026 MSAL.js pattern: ``acquireTokenRedirect`` is the
+    // documented primitive for refreshing a known account's tokens
+    // without a full ``loginRedirect``. Critically, the cache is NOT
+    // cleared before the redirect — that was the orphaned-state bug
+    // (account record gone + tokens lingering when redirect fails).
     const err = Object.assign(new Error("MFA required"), {
       name: "InteractionRequiredAuthError",
       errorCode: "interaction_required",
@@ -171,17 +177,41 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
         "MFA required",
       ],
     });
-    expect(msal.clearCache).toHaveBeenCalledWith({
+    expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
+    expect(msal.acquireTokenRedirect).toHaveBeenCalledWith({
+      scopes: [config.apiScope],
       account: { username: "alice@example.com", localAccountId: "alice-oid" },
     });
-    expect(msal.loginRedirect).toHaveBeenCalledOnce();
-    expect(msal.loginRedirect).toHaveBeenCalledWith({
-      scopes: [config.apiScope],
+    // Cache MUST NOT be cleared before redirect — see
+    // AzureAD/microsoft-authentication-library-for-js#7551 and the
+    // orphaned-state production bug this fix exists to address.
+    expect(msal.clearCache).not.toHaveBeenCalled();
+    expect(msal.setActiveAccount).not.toHaveBeenCalled();
+  });
+
+  it("falls back to loginRedirect when acquireTokenRedirect returns without navigating", async () => {
+    // ``acquireTokenRedirect`` resolves before navigation in some
+    // environments (test runners, blocked redirects). When it settles
+    // without throwing AND without navigating, fall through to a full
+    // ``loginRedirect`` so the user still gets through the auth flow.
+    const err = Object.assign(new Error("interaction"), {
+      name: "InteractionRequiredAuthError",
+      errorCode: "interaction_required",
     });
-    expect(msal.acquireTokenRedirect).not.toHaveBeenCalled();
+    const msal = mockMsal({
+      acquireTokenSilent: vi.fn().mockRejectedValue(err),
+      acquireTokenRedirect: vi.fn().mockResolvedValue(undefined),
+    });
+    await expectInteractiveRecoveryError(store().getAccessToken(), {
+      code: "interaction_required",
+      cause: err,
+      messageIncludes: ["Authentication interaction required"],
+    });
+    expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
+    expect(msal.loginRedirect).toHaveBeenCalledOnce();
   });
 
-  it("clears stale cache and redirects on consent_required", async () => {
+  it("recovers on consent_required without clearing cache before redirect", async () => {
     const err = Object.assign(new Error("consent required"), {
       name: "InteractionRequiredAuthError",
       errorCode: "consent_required",
@@ -192,11 +222,11 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
       cause: err,
       messageIncludes: ["Authentication interaction required", "consent_required"],
     });
-    expect(msal.clearCache).toHaveBeenCalledOnce();
-    expect(msal.loginRedirect).toHaveBeenCalledOnce();
+    expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
+    expect(msal.clearCache).not.toHaveBeenCalled();
   });
 
-  it("clears stale cache and redirects on monitor_window_timeout", async () => {
+  it("recovers on monitor_window_timeout without clearing cache before redirect", async () => {
     // Microsoft Learn → "Common errors in MSAL JS" → monitor_window_timeout
     // → documented remedy includes "Invoke an interactive API".
     const err = Object.assign(new Error("monitor_window_timeout"), {
@@ -209,8 +239,8 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
       cause: err,
       messageIncludes: ["Authentication interaction required", "monitor_window_timeout"],
     });
-    expect(msal.clearCache).toHaveBeenCalledOnce();
-    expect(msal.loginRedirect).toHaveBeenCalledOnce();
+    expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
+    expect(msal.clearCache).not.toHaveBeenCalled();
   });
 
   it("does NOT redirect on interaction_in_progress (would race with another flow)", async () => {
@@ -251,36 +281,148 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
       cause: err,
       messageIncludes: ["Authentication interaction required", "InteractionRequiredAuthError"],
     });
-    expect(msal.clearCache).toHaveBeenCalledOnce();
-    expect(msal.loginRedirect).toHaveBeenCalledOnce();
+    expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
+    expect(msal.clearCache).not.toHaveBeenCalled();
   });
 
-  it("preserves redirect failure details when interactive recovery cannot start", async () => {
+  it("preserves redirect failure details when both redirect attempts fail", async () => {
     const tokenErr = Object.assign(new Error("MFA required"), {
       name: "InteractionRequiredAuthError",
       errorCode: "interaction_required",
     });
-    const redirectErr = Object.assign(new Error("redirect blocked"), {
+    const acquireErr = Object.assign(new Error("acquireToken redirect blocked"), {
       name: "BrowserAuthError",
       errorCode: "redirect_failed",
     });
+    const loginErr = Object.assign(new Error("login redirect blocked"), {
+      name: "BrowserAuthError",
+      errorCode: "redirect_failed_login",
+    });
     const msal = mockMsal({
       acquireTokenSilent: vi.fn().mockRejectedValue(tokenErr),
-      loginRedirect: vi.fn().mockRejectedValue(redirectErr),
+      acquireTokenRedirect: vi.fn().mockRejectedValue(acquireErr),
+      loginRedirect: vi.fn().mockRejectedValue(loginErr),
     });
 
     await expectInteractiveRecoveryError(store().getAccessToken(), {
-      code: "redirect_failed",
-      cause: redirectErr,
+      code: "redirect_failed_login",
+      cause: loginErr,
       messageIncludes: [
         "Authentication interaction required",
-        "login redirect failed",
-        "redirect_failed",
+        "redirect failed",
+        "redirect_failed_login",
         "Original token error",
         "interaction_required",
       ],
     });
-    expect(msal.clearCache).toHaveBeenCalledOnce();
+    expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
     expect(msal.loginRedirect).toHaveBeenCalledOnce();
+    // Even on full failure, cache is NOT touched — leaves state intact
+    // for the next attempt rather than creating an orphaned cache.
+    expect(msal.clearCache).not.toHaveBeenCalled();
+  });
+});
+
+describe("authStore — orphaned-state recovery", () => {
+  // Production bug: a previous recovery cleared the account record but
+  // its redirect didn't navigate (browser policy, popup blocker, etc.).
+  // localStorage is left with token entries but ``getAllAccounts()``
+  // returns []. Every subsequent API call gets null token + 401 forever
+  // until manual ``localStorage.clear()``.
+
+  const config = {
+    clientId: "test-client",
+    authority: "https://login.microsoftonline.com/test-tenant",
+    redirectUri: "http://localhost:8010",
+    apiScope: "api://test-api/access_as_user",
+  };
+
+  beforeEach(() => {
+    if (typeof localStorage !== "undefined") {
+      localStorage.clear();
+    }
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    if (typeof localStorage !== "undefined") {
+      localStorage.clear();
+    }
+  });
+
+  it("detects orphaned state, nukes localStorage, and triggers fresh login", async () => {
+    // Seed the orphan: token-shaped MSAL keys but no account record.
+    localStorage.setItem(
+      "msal.3|home-id.tenant|login.windows.net|accesstoken|client|tenant|scope|",
+      JSON.stringify({ id: "x", nonce: "n", data: "encrypted-blob", lastUpdatedAt: "0" }),
+    );
+    localStorage.setItem(
+      "msal.3|home-id.tenant|login.windows.net|refreshtoken|client|||",
+      JSON.stringify({ id: "x", nonce: "n", data: "encrypted-blob", lastUpdatedAt: "0" }),
+    );
+    localStorage.setItem(
+      "msal.client.active-account-filters",
+      JSON.stringify({ homeAccountId: "home-id.tenant" }),
+    );
+
+    const msal = {
+      initialize: vi.fn().mockResolvedValue(undefined),
+      handleRedirectPromise: vi.fn().mockResolvedValue(null),
+      clearCache: vi.fn().mockResolvedValue(undefined),
+      // CRITICAL: the orphaned-state — empty accounts despite localStorage entries.
+      getAllAccounts: vi.fn().mockReturnValue([]),
+      loginRedirect: vi.fn().mockResolvedValue(undefined),
+      logoutRedirect: vi.fn().mockResolvedValue(undefined),
+      setActiveAccount: vi.fn(),
+      acquireTokenSilent: vi.fn(),
+      acquireTokenRedirect: vi.fn().mockResolvedValue(undefined),
+      acquireTokenPopup: vi.fn(),
+    };
+    vi.spyOn(authConfig, "getMsalInstance").mockReturnValue(msal);
+    vi.spyOn(authConfig, "getMsalConfig").mockReturnValue(config);
+
+    let thrown: unknown;
+    try {
+      await authStore.getState().getAccessToken();
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(AuthInteractionRequiredError);
+    expect((thrown as AuthInteractionRequiredError).message).toMatch(/orphaned/i);
+
+    // localStorage should have been nuked of all msal.* keys.
+    const remainingMsalKeys = Object.keys(localStorage).filter((k) =>
+      k.startsWith("msal."),
+    );
+    expect(remainingMsalKeys).toEqual([]);
+
+    // No account → recovery skips acquireTokenRedirect and goes
+    // straight to loginRedirect.
+    expect(msal.acquireTokenRedirect).not.toHaveBeenCalled();
+    expect(msal.loginRedirect).toHaveBeenCalledOnce();
+  });
+
+  it("returns null on truly clean no-account state (no orphan)", async () => {
+    // No MSAL keys in localStorage and no accounts — user genuinely
+    // hasn't logged in yet. AuthGuard handles ``loginRedirect`` on
+    // its render; we don't double-redirect from here.
+    const msal = {
+      initialize: vi.fn().mockResolvedValue(undefined),
+      handleRedirectPromise: vi.fn().mockResolvedValue(null),
+      clearCache: vi.fn().mockResolvedValue(undefined),
+      getAllAccounts: vi.fn().mockReturnValue([]),
+      loginRedirect: vi.fn().mockResolvedValue(undefined),
+      logoutRedirect: vi.fn().mockResolvedValue(undefined),
+      setActiveAccount: vi.fn(),
+      acquireTokenSilent: vi.fn(),
+      acquireTokenRedirect: vi.fn(),
+      acquireTokenPopup: vi.fn(),
+    };
+    vi.spyOn(authConfig, "getMsalInstance").mockReturnValue(msal);
+    vi.spyOn(authConfig, "getMsalConfig").mockReturnValue(config);
+
+    expect(await authStore.getState().getAccessToken()).toBeNull();
+    expect(msal.acquireTokenRedirect).not.toHaveBeenCalled();
+    expect(msal.loginRedirect).not.toHaveBeenCalled();
   });
 });

package/src/msal/auth-store.ts

@@ -38,42 +38,50 @@ interface AuthState {
    * Recovery semantics — follows the canonical MSAL.js pattern documented
    * at https://learn.microsoft.com/entra/msal/javascript/browser/errors:
    *
-   *   Try acquireTokenSilent first, then use an interactive redirect when
-   *   MSAL reports that user interaction is required.
+   * 1. ``acquireTokenSilent`` first. Pass-through on success.
+   * 2. On a recoverable error (``InteractionRequiredAuthError``,
+   *    ``monitor_window_timeout`` from blocked silent-SSO iframes,
+   *    ``login_required`` / ``consent_required``), call
+   *    :func:`startInteractiveRecovery` to navigate the user through a
+   *    fresh interactive auth.
    *
-   * Plus one extra recoverable case explicitly called out in those docs:
-   * `BrowserAuthError: monitor_window_timeout`. Microsoft's recommendation
-   * is to either backoff, fix the redirectUri page, or "invoke an
-   * interactive API such as acquireTokenPopup or acquireTokenRedirect" —
-   * we take the last option, which matches third-party-iframe storage
-   * blocking on Chrome 120+ / Edge / Safari (the silent iframe times
-   * out because the cross-site cookie is partitioned).
+   * Recovery uses ``acquireTokenRedirect`` (NOT ``loginRedirect``) as
+   * the first step — that's the documented primitive for refreshing a
+   * known account's tokens without forcing a full re-login. Falls back
+   * to ``loginRedirect`` only when ``acquireTokenRedirect`` itself
+   * fails to navigate (browser policy, popup blocker, etc.).
    *
-   * Before starting that redirect, clear the stale local account/token
-   * cache. This avoids the broken half-authenticated state where the SPA
-   * still renders an account but every API call goes out without a bearer
-   * token after MSAL returned `interaction_required`.
+   * Critically: cache is NEVER cleared before the redirect. The
+   * previous version cleared the account record before calling
+   * ``loginRedirect``; when the redirect failed silently (browser
+   * blocking the navigation), the account record was gone but the
+   * tokens lingered, leaving every subsequent API call to find
+   * ``getAllAccounts() === []``, return null, and ship anonymously
+   * to the API — endless 401s, only manual ``localStorage.clear()``
+   * recovers. This bug is documented in
+   * AzureAD/microsoft-authentication-library-for-js#7551.
    *
-   * Recoverable auth failures reject with `AuthInteractionRequiredError`
-   * after recovery has been started. The error exposes `code` and `cause`
-   * so callers can distinguish a normal interaction-required redirect from
-   * a blocked/failed redirect attempt.
+   * Recoverable auth failures reject with ``AuthInteractionRequiredError``
+   * after recovery has been started. The error exposes ``code`` and
+   * ``cause`` so callers can distinguish a normal interaction-required
+   * redirect from a blocked/failed redirect attempt.
    *
-   * Other `BrowserAuthError` codes (`interaction_in_progress`,
-   * `hash_empty_error`, `hash_does_not_contain_known_properties`,
-   * `block_iframe_reload`) are config / race-condition bugs that another
-   * redirect won't fix — propagate them as null without navigating.
+   * Other ``BrowserAuthError`` codes (``hash_empty_error``,
+   * ``hash_does_not_contain_known_properties``, ``block_iframe_reload``)
+   * are config / race-condition bugs that another redirect won't fix —
+   * propagate them as null without navigating.
    *
-   * The "no account in cache" case is handled at boot by `AuthGuard`,
-   * which calls `loginRedirect` when `accounts.length === 0`. If we
-   * still reach this method without an account, it's an unusual state;
-   * return null and let the next AuthGuard render recover.
+   * The "no account in cache" case is handled by detecting ORPHANED
+   * STATE (no accounts but localStorage has MSAL token entries) and
+   * cleaning the half-corrupted cache before redirecting. Without this,
+   * the page renders authenticated UI but every API call goes anonymous.
    *
-   * Errors are matched by `name` / `errorCode` rather than `instanceof`
-   * because `@azure/msal-browser` is loaded via dynamic import; the
-   * error class identity isn't shared across module boundaries.
+   * Errors are matched by ``name`` / ``errorCode`` rather than
+   * ``instanceof`` because ``@azure/msal-browser`` is loaded via
+   * dynamic import; the error class identity isn't shared across
+   * module boundaries.
    *
-   * `forceRefresh: true` skips MSAL's local cache and goes back to the
+   * ``forceRefresh: true`` skips MSAL's local cache and goes back to the
    * token endpoint with the cached refresh token. Use it from the
    * fetch interceptor when a protected API returns 401 — the first
    * attempt may have used a stale cached access token (claims
@@ -86,13 +94,14 @@ interface AuthState {
   ) => Promise<string | null>;
 
   /**
-   * Force interactive recovery: clear MSAL's cache for the active account
-   * and start a ``loginRedirect``. Use this from the fetch interceptor
-   * when even a force-refreshed access token still gets rejected by the
-   * resource server (the silent path can't tell us "this is fundamentally
-   * the wrong token" — it has to come from the protected API saying 401
-   * after we already retried). Throws ``AuthInteractionRequiredError``
-   * once the redirect has been kicked off so the caller can stop processing.
+   * Force interactive recovery: start an ``acquireTokenRedirect`` (or
+   * ``loginRedirect`` fallback). Use this from the fetch interceptor
+   * when even a force-refreshed access token still gets rejected by
+   * the resource server (the silent path can't tell us "this is
+   * fundamentally the wrong token" — it has to come from the protected
+   * API saying 401 after we already retried). Throws
+   * ``AuthInteractionRequiredError`` once the redirect has been kicked
+   * off so the caller can stop processing.
    */
   recoverFromHardAuthFailure: (reason: unknown) => Promise<never>;
 }
@@ -116,7 +125,14 @@ const RECOVERABLE_ERROR_CODES = new Set([
  * class name as a fallback when the error code isn't set. */
 const INTERACTION_REQUIRED_NAME = "InteractionRequiredAuthError";
 
-let interactiveRecoveryStarted = false;
+/** Module-level deduplication: when N parallel API calls all trip the
+ * recovery path simultaneously, the second-onwards must reuse the first
+ * one's promise rather than each issuing their own redirect. Without
+ * this, MSAL throws ``interaction_in_progress`` on N-1 of them and the
+ * cascading errors mask the actual recovery state. Mirrors the pattern
+ * in the msal-react ``useMsalAuthentication`` hook + the production
+ * patterns linked from Microsoft Learn's "Common errors" guide. */
+let activeRecoveryPromise: Promise<never> | null = null;
 
 function isRecoverableAuthError(err: unknown): boolean {
   if (!err || typeof err !== "object") return false;
@@ -156,7 +172,7 @@ function createInteractionRequiredError(
 
   if (redirectError) {
     return new AuthInteractionRequiredError(
-      `Authentication interaction required, but login redirect failed (${redirectDetail}). Original token error: ${tokenDetail}.`,
+      `Authentication interaction required, but redirect failed (${redirectDetail}). Original token error: ${tokenDetail}.`,
       {
         code: authErrorCode(redirectError) ?? authErrorCode(tokenError),
         cause: redirectError,
@@ -173,31 +189,98 @@ function createInteractionRequiredError(
   );
 }
 
+/** Storage probe: does the browser have orphaned MSAL token entries with
+ * no matching account record? That state is the "stuck on 401 forever"
+ * signature — getAllAccounts() returns [] but the SPA still has tokens
+ * lingering from a previous session that recovery half-cleaned. Returns
+ * the list of MSAL keys to nuke; empty array means cache is coherent. */
+function findOrphanedMsalKeys(): string[] {
+  if (typeof window === "undefined" || !window.localStorage) return [];
+  const allKeys: string[] = [];
+  for (let i = 0; i < window.localStorage.length; i++) {
+    const k = window.localStorage.key(i);
+    if (k && k.startsWith("msal.")) allKeys.push(k);
+  }
+  const tokenKeys = allKeys.filter((k) =>
+    /\|(?:access|refresh|id)token\|/.test(k),
+  );
+  // No tokens = clean (or never logged in). Tokens AND empty
+  // getAllAccounts means orphaned — caller is the only one who knows
+  // the accounts state, so caller decides whether to nuke.
+  return tokenKeys.length > 0 ? allKeys : [];
+}
+
+function nukeMsalLocalStorage(): void {
+  if (typeof window === "undefined") return;
+  for (const store of [window.localStorage, window.sessionStorage]) {
+    if (!store) continue;
+    const toRemove: string[] = [];
+    for (let i = 0; i < store.length; i++) {
+      const k = store.key(i);
+      if (k && k.startsWith("msal.")) toRemove.push(k);
+    }
+    toRemove.forEach((k) => store.removeItem(k));
+  }
+}
+
 async function startInteractiveRecovery(
   msal: MsalClientApplication,
-  account: MsalAccountInfo,
+  account: MsalAccountInfo | null,
   scope: string,
   reason: unknown,
 ): Promise<never> {
-  let redirectError: unknown;
-  if (!interactiveRecoveryStarted) {
-    interactiveRecoveryStarted = true;
+  // Deduplicate concurrent recovery attempts. Multiple in-flight API
+  // calls can simultaneously detect a stale token and trip recovery;
+  // without this, MSAL throws ``interaction_in_progress`` on every
+  // call after the first.
+  if (activeRecoveryPromise) {
+    return activeRecoveryPromise;
+  }
+
+  activeRecoveryPromise = (async () => {
+    let redirectError: unknown;
     authStore.setState({ user: null, isAuthenticated: false });
-    msal.setActiveAccount(null);
-    await msal.clearCache({ account }).catch(() => undefined);
+
+    // Step 1: ``acquireTokenRedirect`` — the documented primitive for
+    // refreshing a known account's tokens without forcing full
+    // re-auth. Preserves the account record across the navigation,
+    // which is critical: ``loginRedirect`` + pre-redirect
+    // ``clearCache`` (the previous design) caused the orphaned-state
+    // bug we just hit in production (account record gone, tokens
+    // linger, every API call returns null token + 401 forever).
+    if (account) {
+      try {
+        await msal.acquireTokenRedirect({ scopes: [scope], account });
+        // If we reach here without navigating, MSAL settled the promise
+        // before the browser navigation kicked in (test environments,
+        // blocked redirects, etc.). Fall through to loginRedirect.
+      } catch (err) {
+        redirectError = err;
+      }
+    }
+
+    // Step 2: full ``loginRedirect`` fallback. Used when:
+    //   * No account was passed (orphaned-state caller)
+    //   * acquireTokenRedirect threw a non-navigation error
+    //   * acquireTokenRedirect settled without navigating
+    // Still NO ``clearCache`` before this — let MSAL handle its own
+    // state across the navigation. Only nuke localStorage if BOTH
+    // redirect attempts fail (the orphaned-state caller does this
+    // up-front because their state is already corrupt).
     try {
       await msal.loginRedirect({ scopes: [scope] });
     } catch (err) {
-      // The redirect is expected to navigate away; if it settles by throwing,
-      // keep that failure attached so logs/UI can show what blocked recovery.
       redirectError = err;
-    } finally {
-      // In tests or blocked-popup environments the promise can settle without
-      // navigation. Allow a later user action/retry to start recovery again.
-      interactiveRecoveryStarted = false;
     }
+
+    throw createInteractionRequiredError(reason, redirectError);
+  })();
+
+  try {
+    return await activeRecoveryPromise;
+  } finally {
+    activeRecoveryPromise = null;
   }
-  throw createInteractionRequiredError(reason, redirectError);
 }
 
 export const authStore = createStore<AuthState>((set) => ({
@@ -220,14 +303,33 @@ export const authStore = createStore<AuthState>((set) => ({
     if (!msal || !config) return null;
 
     const accounts = msal.getAllAccounts();
+    const scope = config.apiScope;
+
+    // Orphaned-state recovery: ``getAllAccounts()`` returns [] BUT
+    // localStorage still holds MSAL token entries. That happens when a
+    // previous recovery attempt cleared the account record but its
+    // redirect didn't navigate (browser policy, popup blocker, async
+    // race). The SPA renders "logged in" but every API call goes
+    // anonymous. Nuke the orphans + force a fresh redirect so the
+    // user gets unstuck without manually clearing browser storage.
     if (accounts.length === 0) {
-      // No cached account — `AuthGuard` will call `loginRedirect` on
+      const orphans = findOrphanedMsalKeys();
+      if (orphans.length > 0) {
+        nukeMsalLocalStorage();
+        return startInteractiveRecovery(
+          msal,
+          null,
+          scope,
+          new Error(
+            `Detected orphaned MSAL state (${orphans.length} cache entries with no account record); cleaned up + redirecting`,
+          ),
+        );
+      }
+      // Truly logged out — ``AuthGuard`` will call ``loginRedirect`` on
       // its next render. Don't double-redirect from here.
       return null;
     }
 
-    // Single API-scoped token — Spaces accepts both audiences (multi-audience JWT).
-    const scope = config.apiScope;
     const forceRefresh = options?.forceRefresh === true;
 
     try {
@@ -246,12 +348,12 @@ export const authStore = createStore<AuthState>((set) => ({
   },
 
   recoverFromHardAuthFailure: async (reason) => {
-    // The silent path produced a token but the resource server rejected
-    // it (audience drift, conditional-access re-eval, claims challenge,
-    // tenant-policy change, etc.). The cached refresh token can't help
-    // — a token minted from it would carry the same identity claims —
-    // so the only correct UX is a full ``loginRedirect`` that produces
-    // a fresh token bound to the current server policy.
+    // Fetch interceptor's escape hatch: silent path produced a token
+    // but the resource server rejected it (audience drift, conditional-
+    // access re-eval, claims challenge, tenant-policy change, etc.).
+    // Same recovery primitive as the silent-failure path —
+    // acquireTokenRedirect → loginRedirect — invoked from the
+    // resource-server signal rather than an MSAL exception.
     const msal = getMsalInstance();
     const config = getMsalConfig();
     if (!msal || !config) {
@@ -261,12 +363,11 @@ export const authStore = createStore<AuthState>((set) => ({
       );
     }
     const accounts = msal.getAllAccounts();
-    if (accounts.length === 0) {
-      throw new AuthInteractionRequiredError(
-        "Authentication interaction required (no cached account).",
-        { cause: reason },
-      );
-    }
-    return startInteractiveRecovery(msal, accounts[0], config.apiScope, reason);
+    return startInteractiveRecovery(
+      msal,
+      accounts[0] ?? null,
+      config.apiScope,
+      reason,
+    );
   },
 }));