@iloveagents/foundry-agent 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @iloveagents/foundry-agent
 
+## 0.1.3
+
+### Patch Changes
+
+- d9b0460: fix(agent): escalate to loginRedirect after second 401
+
+  Follow-up to the auth-stale-token-401-retry fix in 0.1.2. The first version retried with `forceRefresh: true` and bounced to `loginRedirect` only when MSAL itself reported `InteractionRequiredAuthError`. But there's a more common production failure mode the silent path can't recover: the resource server rejects the **freshly-refreshed** token too — server-side policy drift, audience mismatch, conditional-access re-evaluation, claims challenge, tenant-policy change. MSAL has no way to know about any of this; it produces a clean refreshed token and calls it a day. The user is left in an endless silent 401 loop because nothing kicks them to `loginRedirect`.
+
+  Adds `recoverFromHardAuthFailure(reason)` on `authStore`. The fetch interceptor calls it when a SECOND consecutive 401 fires (i.e. even the force-refresh retry didn't help). It clears the MSAL cache and starts `loginRedirect` so a brand-new session mints a token bound to current server policy.
+
+  `createServiceFetch` now accepts an optional `recoverFromHardAuthFailure` callback. The default consumer (`@iloveagents/foundry-web-shell`) wires it to the new method on `authStore`. Same pattern in `tokenFetch`.
+
+  Pair: `lastspace#TBD` (forwards the new option through `spacesFetch`).
+
+## 0.1.2
+
+### Patch Changes
+
+- 30a4346: fix(agent): retry protected fetch with `forceRefresh` on 401
+
+  Closes the long-lived-tab 401 loop where the only recovery the user had was logging out or clearing localStorage.
+
+  The token-fetch wrapper used to ask MSAL for a cached token and never retry. If the resource server rejected that token (claims challenge, conditional-access re-eval, audience drift, or staleness MSAL's clock-offset check missed), every subsequent request kept re-sending the same token.
+
+  Fix: on 401 from a protected API, retry once with `acquireTokenSilent({ forceRefresh: true })`. If that also fails, the existing `InteractionRequiredAuthError` path bounces the user through Entra ID. Single-retry cap so we never loop. Request bodies are cloned per-attempt (ReadableStream is single-consume) so POST/PUT payloads survive the retry intact.
+
+  The `acquireToken` callback type now accepts an optional `{ forceRefresh? }` argument — non-breaking; existing callbacks continue to work, but they should forward the option to their token source so the retry path actually reaches the auth backend.
+
+  Pair: `lastspace#205` (forwards the option through `spacesFetch.acquireToken`).
+
 ## 0.1.1
 
 ### Patch Changes

package/package.json

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

package/src/__tests__/agui-runner.test.ts

@@ -6,7 +6,7 @@ import type { AgentSubscriber } from "@ag-ui/client";
 // runAgent fires them in order, synchronously yielding the loop between
 // each one so the runner's queue can drain.
 
-type ScriptedRun = (subscriber: AgentSubscriber) => Promise<void>;
+type ScriptedRun = (subscriber: AgentSubscriber, agent: { messages: unknown[] }) => Promise<void>;
 
 let nextScript: ScriptedRun[] = [];
 let runCount = 0;
@@ -38,7 +38,7 @@ vi.mock("@ag-ui/client", () => {
       const turnIdx = runCount;
       runCount++;
       const script = nextScript[turnIdx];
-      if (script) await script(subscriber);
+      if (script) await script(subscriber, this);
     }
 
     abortRun() {
@@ -52,7 +52,10 @@ import { AGUIRunner } from "../client/agui-runner.ts";
 import { clientToolRegistry } from "../tools/registry.ts";
 import type { RunnerEvent } from "../client/runner-events.ts";
 
-function makeRegistry(client: { isRegistered: (name: string) => boolean; executeTool?: (name: string, args: string) => Promise<string> }) {
+function makeRegistry(client: {
+  isRegistered: (name: string) => boolean;
+  executeTool?: (name: string, args: string) => Promise<string>;
+}) {
   return {
     isRegistered: client.isRegistered,
     executeTool: client.executeTool ?? (async () => JSON.stringify({})),
@@ -60,7 +63,10 @@ function makeRegistry(client: { isRegistered: (name: string) => boolean; execute
   };
 }
 
-async function collect(runner: AGUIRunner, registry: ReturnType<typeof makeRegistry>): Promise<RunnerEvent[]> {
+async function collect(
+  runner: AGUIRunner,
+  registry: ReturnType<typeof makeRegistry>,
+): Promise<RunnerEvent[]> {
   const out: RunnerEvent[] = [];
   for await (const evt of runner.run({ messages: [], registry })) {
     out.push(evt);
@@ -68,6 +74,18 @@ async function collect(runner: AGUIRunner, registry: ReturnType<typeof makeRegis
   return out;
 }
 
+async function collectWithMessages(
+  runner: AGUIRunner,
+  messages: Parameters<AGUIRunner["run"]>[0]["messages"],
+  registry: ReturnType<typeof makeRegistry>,
+): Promise<RunnerEvent[]> {
+  const out: RunnerEvent[] = [];
+  for await (const evt of runner.run({ messages, registry })) {
+    out.push(evt);
+  }
+  return out;
+}
+
 describe("AGUIRunner", () => {
   beforeEach(() => {
     nextScript = [];
@@ -103,8 +121,8 @@ describe("AGUIRunner", () => {
     expect(types).toContain("text-message-end");
     expect(types).toContain("run-finished");
 
-    const deltas = events.filter((e): e is Extract<RunnerEvent, { type: "text-delta" }> =>
-      e.type === "text-delta",
+    const deltas = events.filter(
+      (e): e is Extract<RunnerEvent, { type: "text-delta" }> => e.type === "text-delta",
     );
     expect(deltas.map((d) => d.delta).join("")).toBe("Hello world");
   });
@@ -121,7 +139,7 @@ describe("AGUIRunner", () => {
           } as never,
         } as never);
         await s.onToolCallArgsEvent?.({
-          event: { type: "TOOL_CALL_ARGS", toolCallId: "tc-1", delta: "{\"q\":\"x\"}" } as never,
+          event: { type: "TOOL_CALL_ARGS", toolCallId: "tc-1", delta: '{"q":"x"}' } as never,
         } as never);
         await s.onToolCallEndEvent?.({
           event: { type: "TOOL_CALL_END", toolCallId: "tc-1" } as never,
@@ -140,8 +158,8 @@ describe("AGUIRunner", () => {
     const runner = new AGUIRunner();
     const events = await collect(runner, makeRegistry({ isRegistered: () => false }));
 
-    const start = events.find((e): e is Extract<RunnerEvent, { type: "tool-call-start" }> =>
-      e.type === "tool-call-start",
+    const start = events.find(
+      (e): e is Extract<RunnerEvent, { type: "tool-call-start" }> => e.type === "tool-call-start",
     );
     expect(start).toBeDefined();
     expect(start!.isClientSide).toBe(false);
@@ -212,8 +230,8 @@ describe("AGUIRunner", () => {
     expect(lastAssistantMsg?.toolCalls?.[0]?.id).toBe("tc-1");
 
     // tool-call-start should have isClientSide=true
-    const start = events.find((e): e is Extract<RunnerEvent, { type: "tool-call-start" }> =>
-      e.type === "tool-call-start",
+    const start = events.find(
+      (e): e is Extract<RunnerEvent, { type: "tool-call-start" }> => e.type === "tool-call-start",
     );
     expect(start!.isClientSide).toBe(true);
   });
@@ -276,6 +294,63 @@ describe("AGUIRunner", () => {
     expect(lastAssistant?.content).toBe("Navigating...");
   });
 
+  it("preserves hidden protocol messages from AG-UI snapshots across visible UI turns", async () => {
+    const registry = makeRegistry({ isRegistered: () => false });
+    const runner = new AGUIRunner();
+
+    nextScript = [
+      async (s, agent) => {
+        agent.messages = [
+          {
+            id: "spaces-global-guidance:abc",
+            role: "system",
+            content: "Tenant guidance",
+          },
+          { id: "u-1", role: "user", content: "What is your name?" },
+          { id: "a-1", role: "assistant", content: "Magic Luna." },
+        ];
+        await s.onRunFinishedEvent?.({ event: { type: "RUN_FINISHED" } } as never);
+      },
+    ];
+
+    await collectWithMessages(
+      runner,
+      [{ id: "u-1", role: "user", content: "What is your name?" }],
+      registry,
+    );
+
+    nextScript = [
+      async (s) => {
+        await s.onRunFinishedEvent?.({ event: { type: "RUN_FINISHED" } } as never);
+      },
+    ];
+
+    const events = await collectWithMessages(
+      runner,
+      [
+        { id: "u-1", role: "user", content: "What is your name?" },
+        { id: "a-1", role: "assistant", content: "Magic Luna." },
+        { id: "u-2", role: "user", content: "Say your name again." },
+      ],
+      registry,
+    );
+
+    const request = events.find(
+      (event): event is Extract<RunnerEvent, { type: "request-sent" }> =>
+        event.type === "request-sent",
+    );
+    expect(request?.input.messages).toEqual([
+      {
+        id: "spaces-global-guidance:abc",
+        role: "system",
+        content: "Tenant guidance",
+      },
+      { id: "u-1", role: "user", content: "What is your name?" },
+      { id: "a-1", role: "assistant", content: "Magic Luna." },
+      { id: "u-2", role: "user", content: "Say your name again." },
+    ]);
+  });
+
   it("yields turn-started exactly once per run iteration", async () => {
     nextScript = [
       async (s) => {
@@ -320,8 +395,8 @@ describe("AGUIRunner", () => {
     const runner = new AGUIRunner();
     const events = await collect(runner, makeRegistry({ isRegistered: () => false }));
 
-    const err = events.find((e): e is Extract<RunnerEvent, { type: "run-error" }> =>
-      e.type === "run-error",
+    const err = events.find(
+      (e): e is Extract<RunnerEvent, { type: "run-error" }> => e.type === "run-error",
     );
     expect(err).toBeDefined();
     expect(err!.message).toBe("boom");

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

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { authStore } from "../msal/auth-store.ts";
+import { AuthInteractionRequiredError, authStore } from "../msal/auth-store.ts";
 import * as authConfig from "../msal/auth-config.ts";
 
 const store = () => authStore.getState();
@@ -51,6 +51,7 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
     const mock = {
       initialize: vi.fn().mockResolvedValue(undefined),
       handleRedirectPromise: vi.fn().mockResolvedValue(null),
+      clearCache: vi.fn().mockResolvedValue(undefined),
       getAllAccounts: vi.fn().mockReturnValue([account]),
       loginRedirect: vi.fn().mockResolvedValue(undefined),
       logoutRedirect: vi.fn().mockResolvedValue(undefined),
@@ -65,6 +66,30 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
     return mock;
   }
 
+  async function expectInteractiveRecoveryError(
+    promise: Promise<unknown>,
+    expected: {
+      code?: string;
+      cause: unknown;
+      messageIncludes: string[];
+    },
+  ) {
+    let thrown: unknown;
+    try {
+      await promise;
+    } catch (err) {
+      thrown = err;
+    }
+
+    expect(thrown).toBeInstanceOf(AuthInteractionRequiredError);
+    const authError = thrown as AuthInteractionRequiredError;
+    expect(authError.code).toBe(expected.code);
+    expect(authError.cause).toBe(expected.cause);
+    for (const value of expected.messageIncludes) {
+      expect(authError.message).toContain(value);
+    }
+  }
+
   afterEach(() => {
     vi.restoreAllMocks();
   });
@@ -79,10 +104,47 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
     const msal = mockMsal();
     expect(await store().getAccessToken()).toBe("fresh-token");
     expect(msal.acquireTokenSilent).toHaveBeenCalledOnce();
+    expect(msal.acquireTokenSilent).toHaveBeenCalledWith(
+      expect.objectContaining({ forceRefresh: false }),
+    );
     expect(msal.acquireTokenRedirect).not.toHaveBeenCalled();
     expect(msal.loginRedirect).not.toHaveBeenCalled();
   });
 
+  it("forwards forceRefresh to acquireTokenSilent on the 401-retry path", async () => {
+    // The fetch interceptor passes ``{ forceRefresh: true }`` after a
+    // protected API returns 401. MSAL must skip its local cache and round-
+    // trip the token endpoint so we stop sending the same stale-but-cached
+    // access token.
+    const msal = mockMsal();
+    expect(await store().getAccessToken("api", { forceRefresh: true })).toBe(
+      "fresh-token",
+    );
+    expect(msal.acquireTokenSilent).toHaveBeenCalledWith(
+      expect.objectContaining({ forceRefresh: true }),
+    );
+  });
+
+  it("recoverFromHardAuthFailure clears cache + starts loginRedirect", 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.
+    const msal = mockMsal();
+    const reason = new Error("API returned 401 after force-refresh retry");
+    await expectInteractiveRecoveryError(
+      store().recoverFromHardAuthFailure(reason),
+      {
+        code: undefined,
+        cause: reason,
+        messageIncludes: ["interaction required"],
+      },
+    );
+    expect(msal.clearCache).toHaveBeenCalled();
+    expect(msal.loginRedirect).toHaveBeenCalledOnce();
+  });
+
   it("returns null without redirecting when no account is cached", async () => {
     // AuthGuard calls loginRedirect when accounts.length === 0; double-
     // redirecting from getAccessToken would race with AuthGuard.
@@ -93,31 +155,48 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
     expect(msal.loginRedirect).not.toHaveBeenCalled();
   });
 
-  it("triggers acquireTokenRedirect on InteractionRequiredAuthError (canonical pattern)", async () => {
+  it("clears stale cache and redirects on InteractionRequiredAuthError", async () => {
     const err = Object.assign(new Error("MFA required"), {
       name: "InteractionRequiredAuthError",
       errorCode: "interaction_required",
     });
     const msal = mockMsal({ acquireTokenSilent: vi.fn().mockRejectedValue(err) });
-    expect(await store().getAccessToken()).toBeNull();
-    expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
-    expect(msal.acquireTokenRedirect).toHaveBeenCalledWith({
-      scopes: [config.apiScope],
+    await expectInteractiveRecoveryError(store().getAccessToken(), {
+      code: "interaction_required",
+      cause: err,
+      messageIncludes: [
+        "Authentication interaction required",
+        "InteractionRequiredAuthError",
+        "interaction_required",
+        "MFA required",
+      ],
+    });
+    expect(msal.clearCache).toHaveBeenCalledWith({
       account: { username: "alice@example.com", localAccountId: "alice-oid" },
     });
+    expect(msal.loginRedirect).toHaveBeenCalledOnce();
+    expect(msal.loginRedirect).toHaveBeenCalledWith({
+      scopes: [config.apiScope],
+    });
+    expect(msal.acquireTokenRedirect).not.toHaveBeenCalled();
   });
 
-  it("triggers acquireTokenRedirect on consent_required", async () => {
+  it("clears stale cache and redirects on consent_required", async () => {
     const err = Object.assign(new Error("consent required"), {
       name: "InteractionRequiredAuthError",
       errorCode: "consent_required",
     });
     const msal = mockMsal({ acquireTokenSilent: vi.fn().mockRejectedValue(err) });
-    expect(await store().getAccessToken()).toBeNull();
-    expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
+    await expectInteractiveRecoveryError(store().getAccessToken(), {
+      code: "consent_required",
+      cause: err,
+      messageIncludes: ["Authentication interaction required", "consent_required"],
+    });
+    expect(msal.clearCache).toHaveBeenCalledOnce();
+    expect(msal.loginRedirect).toHaveBeenCalledOnce();
   });
 
-  it("triggers acquireTokenRedirect on monitor_window_timeout (third-party-iframe block)", async () => {
+  it("clears stale cache and redirects on monitor_window_timeout", 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"), {
@@ -125,8 +204,13 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
       errorCode: "monitor_window_timeout",
     });
     const msal = mockMsal({ acquireTokenSilent: vi.fn().mockRejectedValue(err) });
-    expect(await store().getAccessToken()).toBeNull();
-    expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
+    await expectInteractiveRecoveryError(store().getAccessToken(), {
+      code: "monitor_window_timeout",
+      cause: err,
+      messageIncludes: ["Authentication interaction required", "monitor_window_timeout"],
+    });
+    expect(msal.clearCache).toHaveBeenCalledOnce();
+    expect(msal.loginRedirect).toHaveBeenCalledOnce();
   });
 
   it("does NOT redirect on interaction_in_progress (would race with another flow)", async () => {
@@ -163,7 +247,40 @@ describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
       name: "InteractionRequiredAuthError",
     });
     const msal = mockMsal({ acquireTokenSilent: vi.fn().mockRejectedValue(err) });
-    expect(await store().getAccessToken()).toBeNull();
-    expect(msal.acquireTokenRedirect).toHaveBeenCalledOnce();
+    await expectInteractiveRecoveryError(store().getAccessToken(), {
+      cause: err,
+      messageIncludes: ["Authentication interaction required", "InteractionRequiredAuthError"],
+    });
+    expect(msal.clearCache).toHaveBeenCalledOnce();
+    expect(msal.loginRedirect).toHaveBeenCalledOnce();
+  });
+
+  it("preserves redirect failure details when interactive recovery cannot start", async () => {
+    const tokenErr = Object.assign(new Error("MFA required"), {
+      name: "InteractionRequiredAuthError",
+      errorCode: "interaction_required",
+    });
+    const redirectErr = Object.assign(new Error("redirect blocked"), {
+      name: "BrowserAuthError",
+      errorCode: "redirect_failed",
+    });
+    const msal = mockMsal({
+      acquireTokenSilent: vi.fn().mockRejectedValue(tokenErr),
+      loginRedirect: vi.fn().mockRejectedValue(redirectErr),
+    });
+
+    await expectInteractiveRecoveryError(store().getAccessToken(), {
+      code: "redirect_failed",
+      cause: redirectErr,
+      messageIncludes: [
+        "Authentication interaction required",
+        "login redirect failed",
+        "redirect_failed",
+        "Original token error",
+        "interaction_required",
+      ],
+    });
+    expect(msal.clearCache).toHaveBeenCalledOnce();
+    expect(msal.loginRedirect).toHaveBeenCalledOnce();
   });
 });

package/src/__tests__/service-fetch.test.ts

@@ -172,15 +172,207 @@ describe("createServiceFetch", () => {
     expect(merged.get("X-Init-Only")).toBe("init");
   });
 
-  it("recovers when acquireToken throws", async () => {
+  it("does not downgrade token failures to anonymous protected calls", async () => {
     const acquireToken = vi.fn().mockRejectedValue(new Error("token boom"));
     const serviceFetch = createServiceFetch({ acquireToken });
 
-    await serviceFetch("/api/spaces/entities");
+    await expect(serviceFetch("/api/spaces/entities")).rejects.toThrow("token boom");
 
-    expect(fetchSpy).toHaveBeenCalledTimes(1);
-    const [, init] = fetchSpy.mock.calls[0]!;
-    const headers = new Headers(init?.headers);
-    expect(headers.get("Authorization")).toBeNull();
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  describe("401 retry with forceRefresh", () => {
+    it("retries once with forceRefresh when first attempt returns 401", async () => {
+      // Resource server rejects the first (stale-cached) token, then accepts
+      // the freshly-acquired one. This is the long-lived-tab recovery path.
+      fetchSpy.mockReset();
+      fetchSpy
+        .mockResolvedValueOnce(new Response(null, { status: 401 }))
+        .mockResolvedValueOnce(new Response(null, { status: 200 }));
+      const acquireToken = vi
+        .fn()
+        .mockResolvedValueOnce("stale-token")
+        .mockResolvedValueOnce("fresh-token");
+      const serviceFetch = createServiceFetch({ acquireToken });
+
+      const res = await serviceFetch("/api/spaces/entities");
+
+      expect(res.status).toBe(200);
+      expect(fetchSpy).toHaveBeenCalledTimes(2);
+      expect(acquireToken).toHaveBeenCalledTimes(2);
+      // First call: no forceRefresh (use cached token)
+      expect(acquireToken).toHaveBeenNthCalledWith(1, undefined);
+      // Second call: forceRefresh: true (skip MSAL cache, hit token endpoint)
+      expect(acquireToken).toHaveBeenNthCalledWith(2, { forceRefresh: true });
+
+      const firstAuth = new Headers(fetchSpy.mock.calls[0]![1]?.headers).get(
+        "Authorization",
+      );
+      const secondAuth = new Headers(fetchSpy.mock.calls[1]![1]?.headers).get(
+        "Authorization",
+      );
+      expect(firstAuth).toBe("Bearer stale-token");
+      expect(secondAuth).toBe("Bearer fresh-token");
+    });
+
+    it("does not retry on non-401 responses", async () => {
+      fetchSpy.mockReset();
+      fetchSpy.mockResolvedValueOnce(new Response(null, { status: 500 }));
+      const acquireToken = vi.fn().mockResolvedValue("token");
+      const serviceFetch = createServiceFetch({ acquireToken });
+
+      const res = await serviceFetch("/api/spaces/entities");
+
+      expect(res.status).toBe(500);
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+      expect(acquireToken).toHaveBeenCalledTimes(1);
+    });
+
+    it("does not retry when caller supplied their own Authorization header", async () => {
+      // The caller owns the token in this case; retrying would let our auth
+      // layer overwrite their explicit header on the second attempt.
+      fetchSpy.mockReset();
+      fetchSpy.mockResolvedValueOnce(new Response(null, { status: 401 }));
+      const acquireToken = vi.fn();
+      const serviceFetch = createServiceFetch({ acquireToken });
+
+      const res = await serviceFetch("/api/spaces/entities", {
+        headers: { Authorization: "Bearer caller-supplied" },
+      });
+
+      expect(res.status).toBe(401);
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+      expect(acquireToken).not.toHaveBeenCalled();
+    });
+
+    it("preserves a POST body across the 401 retry", async () => {
+      // Regression for the body-stream-consumed bug: ReadableStream bodies
+      // are single-consume, so the retry would otherwise see an empty body
+      // and a server-side validation failure that masks the real auth
+      // recovery. We assert the second attempt receives the same body.
+      fetchSpy.mockReset();
+      fetchSpy
+        .mockResolvedValueOnce(new Response(null, { status: 401 }))
+        .mockResolvedValueOnce(new Response(null, { status: 200 }));
+      const acquireToken = vi
+        .fn()
+        .mockResolvedValueOnce("stale-token")
+        .mockResolvedValueOnce("fresh-token");
+      const serviceFetch = createServiceFetch({ acquireToken });
+
+      const payload = JSON.stringify({ name: "create-this", id: 42 });
+      const request = new Request("https://example.com/api/items", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: payload,
+      });
+
+      const res = await serviceFetch(request);
+
+      expect(res.status).toBe(200);
+      expect(fetchSpy).toHaveBeenCalledTimes(2);
+
+      // Each fetch call's body must be readable and equal to the original.
+      // Awaiting both confirms neither call's body stream was already
+      // drained by the time fetch received it.
+      const firstAttempt = fetchSpy.mock.calls[0]![1];
+      const secondAttempt = fetchSpy.mock.calls[1]![1];
+      const firstBody = await new Response(firstAttempt?.body as BodyInit).text();
+      const secondBody = await new Response(secondAttempt?.body as BodyInit).text();
+      expect(firstBody).toBe(payload);
+      expect(secondBody).toBe(payload);
+    });
+
+    it("only retries once even if the second attempt also returns 401", async () => {
+      // Hard auth failure (refresh token expired). With no
+      // ``recoverFromHardAuthFailure`` configured, the second 401
+      // propagates to the caller. (Tests cover the recovery path
+      // separately below.)
+      fetchSpy.mockReset();
+      fetchSpy
+        .mockResolvedValueOnce(new Response(null, { status: 401 }))
+        .mockResolvedValueOnce(new Response(null, { status: 401 }));
+      const acquireToken = vi.fn().mockResolvedValue("token");
+      const serviceFetch = createServiceFetch({ acquireToken });
+
+      const res = await serviceFetch("/api/spaces/entities");
+
+      expect(res.status).toBe(401);
+      expect(fetchSpy).toHaveBeenCalledTimes(2);
+      expect(acquireToken).toHaveBeenCalledTimes(2);
+    });
+
+    it("kicks off interactive recovery after a second 401", async () => {
+      // Server-policy drift: even the force-refreshed token is rejected.
+      // The fetch interceptor must escalate to loginRedirect via the
+      // recoverFromHardAuthFailure callback — without it the user is
+      // stuck in a silent 401 loop forever (the bug this fix exists for).
+      fetchSpy.mockReset();
+      fetchSpy
+        .mockResolvedValueOnce(new Response(null, { status: 401 }))
+        .mockResolvedValueOnce(new Response(null, { status: 401 }));
+      const acquireToken = vi
+        .fn()
+        .mockResolvedValueOnce("stale-token")
+        .mockResolvedValueOnce("force-refreshed-but-still-bad-token");
+      const recoverFromHardAuthFailure = vi
+        .fn()
+        .mockRejectedValue(new Error("loginRedirect in flight"));
+      const serviceFetch = createServiceFetch({
+        acquireToken,
+        recoverFromHardAuthFailure,
+      });
+
+      await expect(serviceFetch("/api/spaces/entities")).rejects.toThrow(
+        "loginRedirect in flight",
+      );
+      expect(fetchSpy).toHaveBeenCalledTimes(2);
+      expect(acquireToken).toHaveBeenCalledTimes(2);
+      expect(recoverFromHardAuthFailure).toHaveBeenCalledTimes(1);
+      // Reason carries enough context to log/alert without leaking tokens.
+      const reason = recoverFromHardAuthFailure.mock.calls[0]![0];
+      expect(reason).toBeInstanceOf(Error);
+      expect((reason as Error).message).toMatch(/401/);
+    });
+
+    it("does NOT call recoverFromHardAuthFailure on first-attempt success", async () => {
+      // Sanity: when the first request succeeds, recovery callback must
+      // never fire.
+      fetchSpy.mockReset();
+      fetchSpy.mockResolvedValueOnce(new Response(null, { status: 200 }));
+      const acquireToken = vi.fn().mockResolvedValue("good-token");
+      const recoverFromHardAuthFailure = vi.fn();
+      const serviceFetch = createServiceFetch({
+        acquireToken,
+        recoverFromHardAuthFailure,
+      });
+
+      const res = await serviceFetch("/api/spaces/entities");
+      expect(res.status).toBe(200);
+      expect(recoverFromHardAuthFailure).not.toHaveBeenCalled();
+    });
+
+    it("does NOT call recoverFromHardAuthFailure when the retry recovers", async () => {
+      // Standard recovery — first 401, retry with forceRefresh succeeds.
+      // Recovery callback must not fire (would needlessly bounce the user
+      // through loginRedirect).
+      fetchSpy.mockReset();
+      fetchSpy
+        .mockResolvedValueOnce(new Response(null, { status: 401 }))
+        .mockResolvedValueOnce(new Response(null, { status: 200 }));
+      const acquireToken = vi
+        .fn()
+        .mockResolvedValueOnce("stale")
+        .mockResolvedValueOnce("fresh");
+      const recoverFromHardAuthFailure = vi.fn();
+      const serviceFetch = createServiceFetch({
+        acquireToken,
+        recoverFromHardAuthFailure,
+      });
+
+      const res = await serviceFetch("/api/spaces/entities");
+      expect(res.status).toBe(200);
+      expect(recoverFromHardAuthFailure).not.toHaveBeenCalled();
+    });
   });
 });

package/src/__tests__/token-fetch.test.ts

@@ -1,11 +1,13 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const getAccessToken = vi.fn();
+const recoverFromHardAuthFailure = vi.fn();
 
 vi.mock("../msal/auth-store.ts", () => ({
   authStore: {
     getState: () => ({
       getAccessToken,
+      recoverFromHardAuthFailure,
     }),
   },
 }));
@@ -15,6 +17,7 @@ import { tokenFetch } from "../msal/token-fetch.ts";
 describe("tokenFetch", () => {
   beforeEach(() => {
     getAccessToken.mockReset();
+    recoverFromHardAuthFailure.mockReset();
     vi.restoreAllMocks();
   });
 
@@ -62,4 +65,70 @@ describe("tokenFetch", () => {
     const [, init] = fetchSpy.mock.calls[0]!;
     expect(init).toBeUndefined();
   });
+
+  it("retries once with forceRefresh when first attempt returns 401", async () => {
+    // Long-lived tab path: cached token is rejected by the API → MSAL is
+    // asked to round-trip the token endpoint with the refresh token.
+    getAccessToken
+      .mockResolvedValueOnce("stale-token")
+      .mockResolvedValueOnce("fresh-token");
+    const fetchSpy = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValueOnce(new Response(null, { status: 401 }))
+      .mockResolvedValueOnce(new Response(null, { status: 200 }));
+
+    const res = await tokenFetch("https://example.com/api/items");
+
+    expect(res.status).toBe(200);
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+    expect(getAccessToken).toHaveBeenCalledTimes(2);
+    expect(getAccessToken).toHaveBeenNthCalledWith(1, "api", undefined);
+    expect(getAccessToken).toHaveBeenNthCalledWith(2, "api", { forceRefresh: true });
+
+    const firstAuth = new Headers(fetchSpy.mock.calls[0]![1]?.headers).get(
+      "Authorization",
+    );
+    const secondAuth = new Headers(fetchSpy.mock.calls[1]![1]?.headers).get(
+      "Authorization",
+    );
+    expect(firstAuth).toBe("Bearer stale-token");
+    expect(secondAuth).toBe("Bearer fresh-token");
+  });
+
+  it("does not retry on non-401 responses", async () => {
+    getAccessToken.mockResolvedValue("token");
+    const fetchSpy = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValueOnce(new Response(null, { status: 500 }));
+
+    const res = await tokenFetch("https://example.com/api/items");
+
+    expect(res.status).toBe(500);
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    expect(getAccessToken).toHaveBeenCalledTimes(1);
+  });
+
+  it("escalates to interactive recovery on a hard 401-then-401 path", async () => {
+    // Server-policy drift: even the force-refreshed token is rejected.
+    // The fetch interceptor must call ``recoverFromHardAuthFailure`` so
+    // the auth layer can kick off ``loginRedirect``. The recovery
+    // throws once the redirect is in flight; the throw stops the
+    // calling pipeline.
+    getAccessToken.mockResolvedValue("token");
+    recoverFromHardAuthFailure.mockRejectedValue(
+      new Error("loginRedirect in flight"),
+    );
+    const fetchSpy = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValueOnce(new Response(null, { status: 401 }))
+      .mockResolvedValueOnce(new Response(null, { status: 401 }));
+
+    await expect(tokenFetch("https://example.com/api/items")).rejects.toThrow(
+      "loginRedirect in flight",
+    );
+
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+    expect(getAccessToken).toHaveBeenCalledTimes(2);
+    expect(recoverFromHardAuthFailure).toHaveBeenCalledTimes(1);
+  });
 });

package/src/client/agui-runner.ts

@@ -48,6 +48,51 @@ export interface AGUIRunInput {
   context?: Context[];
 }
 
+function shouldPreserveAcrossVisibleHistory(message: Message): boolean {
+  return message.role === "system" || message.role === "developer" || message.role === "reasoning";
+}
+
+function mergeProtocolMessagesFromSnapshot(
+  previousMessages: Message[],
+  visibleMessages: Message[],
+): Message[] {
+  if (previousMessages.length === 0) return [...visibleMessages];
+
+  const visibleById = new Map(visibleMessages.map((message) => [message.id, message]));
+  const previousVisibleIds = new Set(
+    previousMessages
+      .filter((message) => !shouldPreserveAcrossVisibleHistory(message))
+      .map((message) => message.id),
+  );
+  const isSameVisibleThread = visibleMessages.some((message) => previousVisibleIds.has(message.id));
+  if (!isSameVisibleThread) return [...visibleMessages];
+
+  const merged: Message[] = [];
+  const emitted = new Set<string>();
+
+  for (const previous of previousMessages) {
+    const currentVisible = visibleById.get(previous.id);
+    if (currentVisible) {
+      merged.push(currentVisible);
+      emitted.add(currentVisible.id);
+      continue;
+    }
+
+    if (shouldPreserveAcrossVisibleHistory(previous)) {
+      merged.push(previous);
+      emitted.add(previous.id);
+    }
+  }
+
+  for (const message of visibleMessages) {
+    if (!emitted.has(message.id)) {
+      merged.push(message);
+    }
+  }
+
+  return merged;
+}
+
 /**
  * Bridges callback-driven `AgentSubscriber` events into an async-iterable
  * queue the runner's generator drains. Single-producer / single-consumer.
@@ -126,10 +171,17 @@ export class AGUIRunner {
   async *run(input: AGUIRunInput): AsyncGenerator<RunnerEvent> {
     const { messages, state, registry, abortSignal, context } = input;
     const toolCalls = new Map<string, ToolCallState>();
-    let currentMessages: Message[] = [...messages];
+    let currentMessages: Message[] = mergeProtocolMessagesFromSnapshot(
+      this.httpAgent.messages,
+      messages,
+    );
 
-    // Replace once at the top: subsequent turns append to currentMessages
-    // (per AG-UI convention — see footgun in apps/web AGENTS.md cross-link).
+    // Replace once at the top with the reconciled AG-UI history. assistant-ui
+    // stores only visible chat turns, while AG-UI snapshots may contain
+    // model-visible but UI-hidden protocol messages such as system/developer
+    // guidance. Preserve those messages across turns when the visible history
+    // belongs to the same thread so the next request remains a complete AG-UI
+    // conversation without leaking system messages into the rendered chat.
     this.httpAgent.setMessages(currentMessages);
     if (state) this.httpAgent.setState(state);
 

package/src/client/service-fetch.ts

@@ -17,8 +17,35 @@ export interface ServiceFetchOptions {
    * Acquire an access token for outgoing requests. Return `null` to skip
    * token attachment (callers without auth — e.g. local dev — pass through
    * to native fetch).
+   *
+   * The optional ``{ forceRefresh: true }`` argument is passed by the
+   * fetch interceptor on a 401 retry — the auth layer should bypass
+   * its local token cache and round-trip the token endpoint so we
+   * stop re-sending an access token the resource server has already
+   * rejected (canonical MSAL.js fix for tab-open-overnight 401 loops).
    */
-  acquireToken: () => Promise<string | null>;
+  acquireToken: (options?: { forceRefresh?: boolean }) => Promise<string | null>;
+
+  /**
+   * Force interactive recovery (e.g. ``loginRedirect``) when even a
+   * force-refreshed access token gets rejected by the resource server.
+   * The fetch interceptor calls this after a SECOND consecutive 401 —
+   * at that point we know the silent refresh produced a token the
+   * server still won't accept (audience drift, conditional-access
+   * re-eval, tenant-policy change), and the only correct UX is to
+   * mint a fresh session.
+   *
+   * Implementations should clear cached auth state and start a redirect
+   * to the IdP. They MUST throw rather than return so the fetch caller
+   * can stop processing the in-flight request — when this resolves
+   * normally the redirect is in flight and the page is about to
+   * navigate away.
+   *
+   * Optional: when omitted, the fetch interceptor lets the second 401
+   * propagate as-is. Hosts without an interactive recovery path (e.g.
+   * tests, embedded apps) should leave it unset.
+   */
+  recoverFromHardAuthFailure?: (reason: unknown) => Promise<never>;
 
   /**
    * Router FQDN for production (e.g. `https://lastspace-prod.eastus2.example.com`).
@@ -66,47 +93,105 @@ export function createServiceFetch(options: ServiceFetchOptions): ServiceFetch {
     // Request-input branch must preserve method / body / credentials /
     // signal / etc. — silently dropping them by reading only `.url` would
     // turn POST/PUT into GET and drop required headers.
-    const headers = new Headers(input instanceof Request ? input.headers : undefined);
+    const baseHeaders = new Headers(input instanceof Request ? input.headers : undefined);
     if (init?.headers) {
-      new Headers(init.headers).forEach((value, key) => headers.set(key, value));
-    }
-    if (!headers.has("Authorization")) {
-      try {
-        const token = await options.acquireToken();
-        if (token) {
-          headers.set("Authorization", `Bearer ${token}`);
-        }
-      } catch {
-        // Token acquisition failed — proceed without
-      }
+      new Headers(init.headers).forEach((value, key) => baseHeaders.set(key, value));
     }
+    const callerSuppliedAuth = baseHeaders.has("Authorization");
 
-    if (input instanceof Request) {
-      // Build a fresh Request against the rewritten URL, copying every
-      // field the runtime exposes on the original — explicit field copy
-      // is more portable than `new Request(url, originalRequest)`, which
-      // some runtimes (older undici/JSDOM in particular) do not honor
-      // for method/body. `init` then overrides anything the caller passed.
-      const cloned = input.clone();
-      const requestInit: RequestInit = {
-        method: cloned.method,
-        body:
-          cloned.method === "GET" || cloned.method === "HEAD" ? undefined : cloned.body,
-        headers,
-        credentials: cloned.credentials,
-        mode: cloned.mode,
-        cache: cloned.cache,
-        redirect: cloned.redirect,
-        referrer: cloned.referrer,
-        integrity: cloned.integrity,
-        signal: cloned.signal,
+    function buildRequestInitFrom(req: Request): RequestInit {
+      // ReadableStream bodies are single-consume. ``req.clone()`` returns a
+      // fresh Request whose body stream is independent — call it once per
+      // dispatch attempt so the 401 retry can replay POST/PUT bodies
+      // intact.
+      const fresh = req.clone();
+      const ri: RequestInit = {
+        method: fresh.method,
+        body: fresh.method === "GET" || fresh.method === "HEAD" ? undefined : fresh.body,
+        credentials: fresh.credentials,
+        mode: fresh.mode,
+        cache: fresh.cache,
+        redirect: fresh.redirect,
+        referrer: fresh.referrer,
+        integrity: fresh.integrity,
+        signal: fresh.signal,
       };
       // Streaming bodies need duplex: "half"; harmless when there's no body.
-      if (cloned.body !== null) {
-        (requestInit as RequestInit & { duplex?: string }).duplex = "half";
+      if (fresh.body !== null) {
+        (ri as RequestInit & { duplex?: string }).duplex = "half";
+      }
+      return ri;
+    }
+
+    async function dispatch(forceRefreshToken: boolean): Promise<Response> {
+      const headers = new Headers(baseHeaders);
+      if (!callerSuppliedAuth) {
+        try {
+          const token = await options.acquireToken(
+            forceRefreshToken ? { forceRefresh: true } : undefined,
+          );
+          if (token) {
+            headers.set("Authorization", `Bearer ${token}`);
+          }
+        } catch (error) {
+          // A thrown token acquisition error usually means the auth layer
+          // is starting an interactive recovery. Do not downgrade protected
+          // API calls to anonymous requests; that creates noisy 401s and
+          // stale UI.
+          throw error;
+        }
       }
-      return fetch(resolvedUrl, { ...requestInit, ...init, headers });
+      if (input instanceof Request) {
+        // Re-clone for THIS attempt — the body stream of the original is
+        // either still pristine (first attempt) or already consumed
+        // (second attempt); ``clone()`` always returns a fresh, replayable
+        // copy.
+        const requestInit = buildRequestInitFrom(input);
+        return fetch(resolvedUrl, { ...requestInit, ...init, headers });
+      }
+      return fetch(resolvedUrl, { ...init, headers });
+    }
+
+    const response = await dispatch(false);
+
+    // Long-lived tab recovery: when the resource server returns 401 the
+    // local MSAL cache may still hold a token MSAL itself thinks is valid
+    // (claims challenge, conditional-access re-eval, audience drift, or
+    // the user simply left the tab open past the cached access token's
+    // server-side validity). Force-refresh the token via the refresh
+    // token grant and replay the request once. If the refresh-token is
+    // also gone (24h SPA cap), ``acquireToken`` will throw an
+    // interaction-required error and the auth layer kicks off
+    // ``loginRedirect`` — that's the only correct UX for a hard expiry.
+    //
+    // Conditions for retry: 401, no caller-supplied auth header (we own
+    // the token), and the server didn't already see a fresh token (we
+    // only retry once).
+    if (response.status !== 401 || callerSuppliedAuth) {
+      return response;
+    }
+    // Drain the failed response body — letting it sit unread keeps the
+    // underlying connection occupied on some runtimes.
+    response.body?.cancel().catch(() => undefined);
+    const retried = await dispatch(true);
+
+    // Hard auth failure: even the force-refreshed token got rejected.
+    // The silent path can't recover this — a token minted from the
+    // cached refresh token carries the same identity claims as the
+    // original, so it'll keep getting rejected for the same reason
+    // (audience drift, conditional-access re-eval, claims challenge,
+    // tenant-policy change). Only a brand-new ``loginRedirect`` produces
+    // a token bound to the current server policy. Without this branch
+    // the user sees an endless 401 loop until they manually log out.
+    if (retried.status === 401 && options.recoverFromHardAuthFailure) {
+      retried.body?.cancel().catch(() => undefined);
+      // ``recoverFromHardAuthFailure`` throws once the redirect is in
+      // flight; the throw stops the calling pipeline so we don't
+      // return a stale 401 the caller might handle as a real failure.
+      await options.recoverFromHardAuthFailure(
+        new Error("API returned 401 after force-refresh retry"),
+      );
     }
-    return fetch(resolvedUrl, { ...init, headers });
+    return retried;
   };
 }

package/src/msal/auth-config.ts

@@ -25,6 +25,7 @@ export interface MsalAccountInfo {
 export interface MsalClientApplication {
   initialize(): Promise<void>;
   handleRedirectPromise(): Promise<unknown>;
+  clearCache(request?: { account?: MsalAccountInfo }): Promise<void>;
   getAllAccounts(): MsalAccountInfo[];
   loginRedirect(request: { scopes: string[]; prompt?: string }): Promise<void>;
   logoutRedirect(): Promise<void>;
@@ -32,6 +33,16 @@ export interface MsalClientApplication {
   acquireTokenSilent(request: {
     scopes: string[];
     account: MsalAccountInfo;
+    /**
+     * Skip MSAL's local cache and force a round-trip to the token
+     * endpoint using the cached refresh token. The fetch interceptor
+     * uses this on a 401 retry — the first attempt may have served a
+     * cached access token MSAL still thought valid (within
+     * ``tokenRenewalOffsetSeconds``) that the resource server has
+     * since rejected (claims challenge, conditional access re-eval,
+     * audience drift).
+     */
+    forceRefresh?: boolean;
   }): Promise<{ accessToken: string }>;
   acquireTokenRedirect(request: {
     scopes: string[];

package/src/msal/auth-store.ts

@@ -1,5 +1,6 @@
 import { createStore } from "zustand/vanilla";
 import { getMsalInstance, getMsalConfig } from "./auth-config.ts";
+import type { MsalAccountInfo, MsalClientApplication } from "./auth-config.ts";
 
 export interface AuthUser {
   name: string;
@@ -8,6 +9,18 @@ export interface AuthUser {
   oid?: string;
 }
 
+export class AuthInteractionRequiredError extends Error {
+  readonly code?: string;
+  readonly cause?: unknown;
+
+  constructor(message: string, options: { code?: string; cause?: unknown } = {}) {
+    super(message);
+    this.name = "AuthInteractionRequiredError";
+    this.code = options.code;
+    this.cause = options.cause;
+  }
+}
+
 interface AuthState {
   user: AuthUser | null;
   isAuthenticated: boolean;
@@ -25,13 +38,8 @@ interface AuthState {
    * Recovery semantics — follows the canonical MSAL.js pattern documented
    * at https://learn.microsoft.com/entra/msal/javascript/browser/errors:
    *
-   *   try {
-   *     await msal.acquireTokenSilent(req);
-   *   } catch (error) {
-   *     if (error instanceof InteractionRequiredAuthError) {
-   *       await msal.acquireTokenRedirect(req);
-   *     }
-   *   }
+   *   Try acquireTokenSilent first, then use an interactive redirect when
+   *   MSAL reports that user interaction is required.
    *
    * Plus one extra recoverable case explicitly called out in those docs:
    * `BrowserAuthError: monitor_window_timeout`. Microsoft's recommendation
@@ -41,6 +49,16 @@ interface AuthState {
    * blocking on Chrome 120+ / Edge / Safari (the silent iframe times
    * out because the cross-site cookie is partitioned).
    *
+   * 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`.
+   *
+   * 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
@@ -54,8 +72,29 @@ interface AuthState {
    * 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
+   * 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
+   * challenge, conditional-access re-eval, audience drift, etc.) that
+   * MSAL still considered valid against its own clock.
+   */
+  getAccessToken: (
+    audience?: "api" | "spaces",
+    options?: { forceRefresh?: boolean },
+  ) => 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.
    */
-  getAccessToken: (audience?: "api" | "spaces") => Promise<string | null>;
+  recoverFromHardAuthFailure: (reason: unknown) => Promise<never>;
 }
 
 /** Recoverable error codes per MSAL.js docs — every one of these has the
@@ -77,6 +116,8 @@ 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;
+
 function isRecoverableAuthError(err: unknown): boolean {
   if (!err || typeof err !== "object") return false;
   const name = (err as { name?: string }).name ?? "";
@@ -84,6 +125,81 @@ function isRecoverableAuthError(err: unknown): boolean {
   return name === INTERACTION_REQUIRED_NAME || RECOVERABLE_ERROR_CODES.has(code);
 }
 
+function authErrorName(err: unknown): string | undefined {
+  return err && typeof err === "object" ? (err as { name?: string }).name : undefined;
+}
+
+function authErrorCode(err: unknown): string | undefined {
+  return err && typeof err === "object" ? (err as { errorCode?: string }).errorCode : undefined;
+}
+
+function authErrorMessage(err: unknown): string | undefined {
+  if (err instanceof Error) return err.message;
+  return err && typeof err === "object" ? (err as { message?: string }).message : undefined;
+}
+
+function describeAuthError(err: unknown): string {
+  const parts = [
+    authErrorName(err) ? `name=${authErrorName(err)}` : undefined,
+    authErrorCode(err) ? `code=${authErrorCode(err)}` : undefined,
+    authErrorMessage(err) ? `message=${authErrorMessage(err)}` : undefined,
+  ].filter(Boolean);
+  return parts.join(", ");
+}
+
+function createInteractionRequiredError(
+  tokenError: unknown,
+  redirectError?: unknown,
+): AuthInteractionRequiredError {
+  const tokenDetail = describeAuthError(tokenError) || "unknown token acquisition error";
+  const redirectDetail = redirectError ? describeAuthError(redirectError) : "";
+
+  if (redirectError) {
+    return new AuthInteractionRequiredError(
+      `Authentication interaction required, but login redirect failed (${redirectDetail}). Original token error: ${tokenDetail}.`,
+      {
+        code: authErrorCode(redirectError) ?? authErrorCode(tokenError),
+        cause: redirectError,
+      },
+    );
+  }
+
+  return new AuthInteractionRequiredError(
+    `Authentication interaction required after token acquisition failed (${tokenDetail}).`,
+    {
+      code: authErrorCode(tokenError),
+      cause: tokenError,
+    },
+  );
+}
+
+async function startInteractiveRecovery(
+  msal: MsalClientApplication,
+  account: MsalAccountInfo,
+  scope: string,
+  reason: unknown,
+): Promise<never> {
+  let redirectError: unknown;
+  if (!interactiveRecoveryStarted) {
+    interactiveRecoveryStarted = true;
+    authStore.setState({ user: null, isAuthenticated: false });
+    msal.setActiveAccount(null);
+    await msal.clearCache({ account }).catch(() => undefined);
+    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);
+}
+
 export const authStore = createStore<AuthState>((set) => ({
   user: null,
   isAuthenticated: false,
@@ -98,7 +214,7 @@ export const authStore = createStore<AuthState>((set) => ({
     }
   },
 
-  getAccessToken: async (_audience = "api") => {
+  getAccessToken: async (_audience = "api", options) => {
     const msal = getMsalInstance();
     const config = getMsalConfig();
     if (!msal || !config) return null;
@@ -112,25 +228,45 @@ export const authStore = createStore<AuthState>((set) => ({
 
     // Single API-scoped token — Spaces accepts both audiences (multi-audience JWT).
     const scope = config.apiScope;
+    const forceRefresh = options?.forceRefresh === true;
 
     try {
       const result = await msal.acquireTokenSilent({
         scopes: [scope],
         account: accounts[0],
+        forceRefresh,
       });
       return result.accessToken;
     } catch (err) {
       if (isRecoverableAuthError(err)) {
-        try {
-          await msal.acquireTokenRedirect({
-            scopes: [scope],
-            account: accounts[0],
-          });
-        } catch {
-          // Redirect navigates away; nothing to return.
-        }
+        return startInteractiveRecovery(msal, accounts[0], scope, err);
       }
       return null;
     }
   },
+
+  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.
+    const msal = getMsalInstance();
+    const config = getMsalConfig();
+    if (!msal || !config) {
+      throw new AuthInteractionRequiredError(
+        "Authentication interaction required (no MSAL instance configured).",
+        { cause: reason },
+      );
+    }
+    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);
+  },
 }));

package/src/msal/index.ts

@@ -1,4 +1,8 @@
-export { authStore, type AuthUser } from "./auth-store.ts";
+export {
+  AuthInteractionRequiredError,
+  authStore,
+  type AuthUser,
+} from "./auth-store.ts";
 export {
   type MsalAuthConfig,
   type MsalAccountInfo,

package/src/msal/token-fetch.ts

@@ -7,6 +7,11 @@
  * downstream services (e.g., Spaces).
  *
  * When MSAL is not configured, behaves identically to native `fetch()`.
+ *
+ * Long-lived tab recovery: on 401 the wrapper retries once with
+ * ``forceRefresh: true`` so the resource server doesn't keep seeing a
+ * stale-but-cached access token. See ``service-fetch.ts`` for the same
+ * pattern with URL rewriting + the deeper rationale.
  */
 
 import { authStore } from "./auth-store.ts";
@@ -15,16 +20,49 @@ export async function tokenFetch(
   input: string | URL | Request,
   init?: RequestInit,
 ): Promise<Response> {
-  const token = await authStore.getState().getAccessToken("api");
+  async function dispatch(forceRefreshToken: boolean): Promise<Response> {
+    const token = await authStore
+      .getState()
+      .getAccessToken("api", forceRefreshToken ? { forceRefresh: true } : undefined);
+
+    // Clone Request inputs per-attempt: ReadableStream bodies are single-
+    // consume, so the 401 retry would otherwise see an empty body.
+    // ``input.clone()`` returns a fresh Request whose body stream is
+    // independent of the original.
+    const target = input instanceof Request ? input.clone() : input;
 
-  if (!token) {
-    return fetch(input, init);
+    if (!token) {
+      return fetch(target, init);
+    }
+
+    const headers = new Headers(input instanceof Request ? input.headers : undefined);
+    if (init?.headers) {
+      new Headers(init.headers).forEach((value, key) => headers.set(key, value));
+    }
+    headers.set("Authorization", `Bearer ${token}`);
+    return fetch(target, { ...init, headers });
   }
 
-  const headers = new Headers(input instanceof Request ? input.headers : undefined);
-  if (init?.headers) {
-    new Headers(init.headers).forEach((value, key) => headers.set(key, value));
+  const response = await dispatch(false);
+  if (response.status !== 401) {
+    return response;
+  }
+  response.body?.cancel().catch(() => undefined);
+  const retried = await dispatch(true);
+  if (retried.status === 401) {
+    // Second 401 after a force-refresh retry — the silent token path
+    // can't recover this (refresh-token grant produces the same
+    // identity claims that just got rejected). Kick off interactive
+    // recovery so a fresh ``loginRedirect`` mints a token bound to
+    // current server policy. ``recoverFromHardAuthFailure`` throws
+    // once the redirect is in flight so we don't return a stale 401
+    // the caller might handle as a real failure.
+    retried.body?.cancel().catch(() => undefined);
+    await authStore
+      .getState()
+      .recoverFromHardAuthFailure(
+        new Error("API returned 401 after force-refresh retry"),
+      );
   }
-  headers.set("Authorization", `Bearer ${token}`);
-  return fetch(input, { ...init, headers });
+  return retried;
 }