From 8fcfa8bacb6995acc23243bdcf13f79321b4f373 Mon Sep 17 00:00:00 2001
From: "Builder.io" <builder-bot@builder.io>
Date: Tue, 4 Aug 2026 19:59:48 +0000
Subject: [PATCH 1/3] Fix session loading spinner stalling with bounded retries

---
 .changeset/hungry-donkeys-repeat.md           | 20 ++++++
 packages/core/src/client/DefaultSpinner.tsx   | 21 ++++--
 .../core/src/client/require-session.spec.tsx  | 64 +++++++++++++++++--
 packages/core/src/client/require-session.tsx  | 39 ++++++++++-
 packages/core/src/client/use-session.spec.tsx | 26 ++++++++
 packages/core/src/client/use-session.ts       | 50 +++++++++++++--
 6 files changed, 199 insertions(+), 21 deletions(-)
 create mode 100644 .changeset/hungry-donkeys-repeat.md

diff --git a/.changeset/hungry-donkeys-repeat.md b/.changeset/hungry-donkeys-repeat.md
new file mode 100644
index 0000000000..dcdeaeac24
--- /dev/null
+++ b/.changeset/hungry-donkeys-repeat.md
@@ -0,0 +1,20 @@
+---
+"@agent-native/core": patch
+---
+
+Stop stranding users on the loading spinner when the session endpoint is
+unreadable. `useSession` retried a failed `/_agent-native/auth/session` every
+second forever while holding `isLoading` true, so a transient 5xx, network
+failure, or timeout produced a spinner that never resolved and carried no error
+anywhere. It now retries a bounded number of times with backoff and then reports
+a distinct `status: "unavailable"` alongside the existing `session`/`isLoading`
+fields.
+
+`RequireSession` keys off that status: unreadable is no longer collapsed into
+signed-out (which would bounce a signed-in user to the sign-in page over a blip)
+nor into loading (which stranded them). It renders a notice with Try again and
+Reload actions instead.
+
+The `DefaultSpinner` stall hint is also environment-aware now. It previously
+told every visitor — including on hosted deployments — to "check the terminal
+running the dev server", which is meaningless outside local development.
diff --git a/packages/core/src/client/DefaultSpinner.tsx b/packages/core/src/client/DefaultSpinner.tsx
index 3d5d24d5b9..cecb201abb 100644
--- a/packages/core/src/client/DefaultSpinner.tsx
+++ b/packages/core/src/client/DefaultSpinner.tsx
@@ -10,6 +10,21 @@
  * is indistinguishable from a blank screen, and reads as "the app is broken"
  * rather than "look at the terminal" — that mis-read is what this text buys.
  */
+
+/**
+ * Production wording wins whenever the build mode is unreadable: core is often
+ * consumed as prebuilt dist, where the Vite env is absent. A hosted visitor has
+ * no dev-server terminal, so pointing them at one is worse than saying less.
+ */
+function stallHint(): string {
+  const env = import.meta.env as Record<string, unknown> | undefined;
+  const isDev = env?.DEV === true || env?.MODE === "development";
+  if (isDev) {
+    return "Still loading. A first run compiles dependencies and can take a minute — if it does not finish, check the terminal running the dev server for errors.";
+  }
+  return "Still loading. This is taking longer than usual — try reloading the page, and let us know if it keeps happening.";
+}
+
 export function DefaultSpinner() {
   return (
     <div
@@ -38,11 +53,7 @@ export function DefaultSpinner() {
       >
         <path d="M21 12a9 9 0 1 1-6.219-8.56" />
       </svg>
-      <p className="an-stall-hint">
-        Still loading. A first run compiles dependencies and can take a minute —
-        if it does not finish, check the terminal running the dev server for
-        errors.
-      </p>
+      <p className="an-stall-hint">{stallHint()}</p>
       <style>{`
         @keyframes an-spin { to { transform: rotate(360deg) } }
         @keyframes an-stall-in { to { opacity: 0.6 } }
diff --git a/packages/core/src/client/require-session.spec.tsx b/packages/core/src/client/require-session.spec.tsx
index aca313dcad..6449ede42b 100644
--- a/packages/core/src/client/require-session.spec.tsx
+++ b/packages/core/src/client/require-session.spec.tsx
@@ -82,7 +82,11 @@ const Child = () => <div data-testid="protected">inbox</div>;
 
 describe("RequireSession", () => {
   it("shows a loading fallback while the session resolves and never redirects", () => {
-    useSessionMock.mockReturnValue({ session: null, isLoading: true });
+    useSessionMock.mockReturnValue({
+      session: null,
+      isLoading: true,
+      status: "loading",
+    });
     render(
       <RequireSession>
         <Child />
@@ -97,6 +101,7 @@ describe("RequireSession", () => {
     useSessionMock.mockReturnValue({
       session: { userId: "u1", email: "a@b.com" },
       isLoading: false,
+      status: "authenticated",
     });
     render(
       <RequireSession>
@@ -108,7 +113,11 @@ describe("RequireSession", () => {
   });
 
   it("redirects to the framework sign-in page carrying an opaque continuation", () => {
-    useSessionMock.mockReturnValue({ session: null, isLoading: false });
+    useSessionMock.mockReturnValue({
+      session: null,
+      isLoading: false,
+      status: "unauthenticated",
+    });
     render(
       <RequireSession>
         <Child />
@@ -131,7 +140,11 @@ describe("RequireSession", () => {
     // here, which is the only thing left standing between this surface and a
     // same-URL replace loop — it must never gain a fallback.
     stubLocation("/_agent-native/sign-in", "?c=abc");
-    useSessionMock.mockReturnValue({ session: null, isLoading: false });
+    useSessionMock.mockReturnValue({
+      session: null,
+      isLoading: false,
+      status: "unauthenticated",
+    });
     render(
       <RequireSession>
         <Child />
@@ -146,7 +159,11 @@ describe("RequireSession", () => {
     // old marker-only base resolver returned "" and failed to recognise it as
     // an auth entry path — a live, reproducible infinite bounce.
     vi.stubEnv("VITE_APP_BASE_PATH", "/myapp");
-    useSessionMock.mockReturnValue({ session: null, isLoading: false });
+    useSessionMock.mockReturnValue({
+      session: null,
+      isLoading: false,
+      status: "unauthenticated",
+    });
     for (const path of ["/myapp/login", "/myapp/signup"]) {
       stubLocation(path);
       render(
@@ -160,7 +177,11 @@ describe("RequireSession", () => {
   });
 
   it("does not redirect twice across re-renders", () => {
-    useSessionMock.mockReturnValue({ session: null, isLoading: false });
+    useSessionMock.mockReturnValue({
+      session: null,
+      isLoading: false,
+      status: "unauthenticated",
+    });
     render(
       <RequireSession>
         <Child />
@@ -175,7 +196,11 @@ describe("RequireSession", () => {
   });
 
   it("renders `signedOut` instead of redirecting when redirect is disabled", () => {
-    useSessionMock.mockReturnValue({ session: null, isLoading: false });
+    useSessionMock.mockReturnValue({
+      session: null,
+      isLoading: false,
+      status: "unauthenticated",
+    });
     render(
       <RequireSession redirect={false} signedOut={<div>please sign in</div>}>
         <Child />
@@ -185,8 +210,33 @@ describe("RequireSession", () => {
     expect(replaceMock).not.toHaveBeenCalled();
   });
 
+  it("shows a recoverable notice when the session is unreadable", () => {
+    // A transient 5xx must read as neither "signed out" (which bounces a
+    // signed-in user to sign-in) nor "still loading" (which strands them).
+    useSessionMock.mockReturnValue({
+      session: null,
+      isLoading: false,
+      status: "unavailable",
+      error: new Error("Could not read the session after 4 attempts."),
+      retry: vi.fn(),
+    });
+    render(
+      <RequireSession>
+        <Child />
+      </RequireSession>,
+    );
+    expect(replaceMock).not.toHaveBeenCalled();
+    expect(container.querySelector('[data-testid="protected"]')).toBeNull();
+    expect(container.querySelector('[aria-label="Loading"]')).toBeNull();
+    expect(container.textContent).toContain("Try again");
+  });
+
   it("bypass renders children even with no session", () => {
-    useSessionMock.mockReturnValue({ session: null, isLoading: false });
+    useSessionMock.mockReturnValue({
+      session: null,
+      isLoading: false,
+      status: "unauthenticated",
+    });
     render(
       <RequireSession bypass>
         <Child />
diff --git a/packages/core/src/client/require-session.tsx b/packages/core/src/client/require-session.tsx
index 419b5bd023..d464488e16 100644
--- a/packages/core/src/client/require-session.tsx
+++ b/packages/core/src/client/require-session.tsx
@@ -118,13 +118,13 @@ function ResolvedSessionGate({
   redirect = true,
   signedOut,
 }: Omit<RequireSessionProps, "bypass">) {
-  const { session, isLoading } = useSession();
+  const { session, status, retry } = useSession();
   // Guard against firing the redirect more than once (effect re-runs, React
   // StrictMode double-invoke) — a second navigation while the first is in
   // flight is harmless but noisy.
   const redirectedRef = useRef(false);
 
-  const mustRedirect = !isLoading && !session && redirect;
+  const mustRedirect = status === "unauthenticated" && redirect;
 
   useEffect(() => {
     if (!mustRedirect) return;
@@ -144,10 +144,43 @@ function ResolvedSessionGate({
 
   // Still resolving, or redirect already in flight: show the loading fallback
   // rather than flashing app chrome the visitor can't use.
-  if (isLoading) return <>{fallback ?? <DefaultSpinner />}</>;
+  if (status === "loading") return <>{fallback ?? <DefaultSpinner />}</>;
+  // Unreadable is not signed-out. Redirecting here would bounce a signed-in
+  // user to the sign-in page over a transient 5xx, and rendering the spinner
+  // would strand them on a screen that never resolves.
+  if (status === "unavailable") {
+    return <SessionUnavailableNotice retry={retry} />;
+  }
   if (!session) {
     if (redirect) return <>{fallback ?? <DefaultSpinner />}</>;
     return <>{signedOut ?? null}</>;
   }
   return <>{children}</>;
 }
+
+function SessionUnavailableNotice({ retry }: { retry: () => void }) {
+  return (
+    <div className="flex h-screen w-full flex-col items-center justify-center gap-4 px-6 text-center">
+      <p className="max-w-md text-sm text-muted-foreground">
+        We couldn&apos;t reach the server to confirm you&apos;re signed in. This
+        is usually temporary.
+      </p>
+      <div className="flex gap-2">
+        <button
+          type="button"
+          onClick={retry}
+          className="rounded-md bg-primary px-3 py-1.5 text-sm font-medium text-primary-foreground"
+        >
+          Try again
+        </button>
+        <button
+          type="button"
+          onClick={() => window.location.reload()}
+          className="rounded-md border border-border px-3 py-1.5 text-sm font-medium"
+        >
+          Reload page
+        </button>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/core/src/client/use-session.spec.tsx b/packages/core/src/client/use-session.spec.tsx
index bff21465f6..fe4d1cf2ec 100644
--- a/packages/core/src/client/use-session.spec.tsx
+++ b/packages/core/src/client/use-session.spec.tsx
@@ -29,6 +29,11 @@ function SessionConsumers({ labels }: { labels: string[] }) {
   return labels.map((label) => <SessionConsumer key={label} label={label} />);
 }
 
+function StatusConsumer() {
+  const { status } = useSession();
+  return <div data-testid="status">{status}</div>;
+}
+
 async function renderConsumers(labels: string[]) {
   await act(async () => {
     root.render(<SessionConsumers labels={labels} />);
@@ -144,6 +149,27 @@ describe("useSession", () => {
     expect(analyticsMocks.trackSessionStatus).toHaveBeenCalledWith(true);
   });
 
+  it("stops retrying and reports unavailable when the endpoint keeps failing", async () => {
+    vi.useFakeTimers();
+    const failingFetch = vi.fn(async () => new Response(null, { status: 503 }));
+    vi.stubGlobal("fetch", failingFetch);
+
+    await act(async () => {
+      root.render(<StatusConsumer />);
+      await Promise.resolve();
+    });
+    expect(container.textContent).toBe("loading");
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(30_000);
+    });
+
+    expect(container.textContent).toBe("unavailable");
+    expect(failingFetch).toHaveBeenCalledTimes(4);
+    // An unreadable endpoint must never be reported as a signed-out visitor.
+    expect(analyticsMocks.trackSessionStatus).not.toHaveBeenCalled();
+  });
+
   it("caches a definitive unauthenticated response", async () => {
     const fetchMock = vi.fn(async () =>
       jsonResponse({ error: "Not authenticated" }),
diff --git a/packages/core/src/client/use-session.ts b/packages/core/src/client/use-session.ts
index c24b18aacb..e67b2a83a0 100644
--- a/packages/core/src/client/use-session.ts
+++ b/packages/core/src/client/use-session.ts
@@ -1,4 +1,4 @@
-import { useEffect, useState } from "react";
+import { useCallback, useEffect, useState } from "react";
 
 import type { AuthSession } from "../server/auth.js";
 import { setSentryUser, trackSessionStatus } from "./analytics.js";
@@ -6,13 +6,30 @@ import { fetchAuthSessionStatus } from "./client-status-requests.js";
 
 export type { AuthSession };
 
+/**
+ * `"unavailable"` is the session endpoint being unreadable — a 5xx, a network
+ * failure, or a timeout. It is NOT the visitor being signed out, and a caller
+ * that collapses the two either strands the user on a spinner forever or
+ * bounces a signed-in user to the sign-in page over a transient blip.
+ */
+export type SessionStatus =
+  | "loading"
+  | "authenticated"
+  | "unauthenticated"
+  | "unavailable";
+
 interface UseSessionResult {
   session: AuthSession | null;
   isLoading: boolean;
+  status: SessionStatus;
+  error: Error | null;
+  /** Restart the resolve loop, e.g. from a "Try again" control. */
+  retry: () => void;
 }
 
 const SESSION_CACHE_TTL_MS = 30_000;
 const SESSION_RETRY_DELAY_MS = 1_000;
+const SESSION_MAX_ATTEMPTS = 4;
 let cachedSession: AuthSession | null | undefined;
 let cachedSessionAt = 0;
 let sessionRequest: Promise<AuthSession | null | undefined> | undefined;
@@ -81,25 +98,46 @@ function fetchSharedSession(): Promise<AuthSession | null | undefined> {
 export function useSession(): UseSessionResult {
   const cached = hasFreshSessionCache() ? (cachedSession ?? null) : null;
   const [session, setSession] = useState<AuthSession | null>(cached);
-  const [isLoading, setIsLoading] = useState(!hasFreshSessionCache());
+  const [status, setStatus] = useState<SessionStatus>(() => {
+    if (!hasFreshSessionCache()) return "loading";
+    return cached ? "authenticated" : "unauthenticated";
+  });
+  const [error, setError] = useState<Error | null>(null);
+  const [retryToken, setRetryToken] = useState(0);
+
+  const retry = useCallback(() => {
+    setError(null);
+    setStatus("loading");
+    setRetryToken((token) => token + 1);
+  }, []);
 
   useEffect(() => {
     let cancelled = false;
     let retryTimer: ReturnType<typeof setTimeout> | undefined;
+    let attempts = 0;
 
     const resolveSession = async () => {
       const resolved = await fetchSharedSession();
       if (cancelled) return;
 
       if (resolved === undefined) {
+        attempts += 1;
+        if (attempts >= SESSION_MAX_ATTEMPTS) {
+          setError(
+            new Error(`Could not read the session after ${attempts} attempts.`),
+          );
+          setStatus("unavailable");
+          return;
+        }
         retryTimer = setTimeout(() => {
           void resolveSession();
-        }, SESSION_RETRY_DELAY_MS);
+        }, SESSION_RETRY_DELAY_MS * attempts);
         return;
       }
 
       setSession(resolved);
-      setIsLoading(false);
+      setError(null);
+      setStatus(resolved ? "authenticated" : "unauthenticated");
     };
 
     void resolveSession();
@@ -107,7 +145,7 @@ export function useSession(): UseSessionResult {
       cancelled = true;
       if (retryTimer) clearTimeout(retryTimer);
     };
-  }, []);
+  }, [retryToken]);
 
-  return { session, isLoading };
+  return { session, isLoading: status === "loading", status, error, retry };
 }

From 89dcb7f6b06adbe50d5c44b440f295b1eee61692 Mon Sep 17 00:00:00 2001
From: "Builder.io" <builder-bot@builder.io>
Date: Tue, 4 Aug 2026 20:15:01 +0000
Subject: [PATCH 2/3] Keep isLoading true for unavailable sessions to prevent
 sign-out misreads

---
 .../core/src/client/require-session.spec.tsx  |  4 +++-
 packages/core/src/client/use-session.spec.tsx | 20 +++++++++++++++++++
 packages/core/src/client/use-session.ts       | 10 +++++++++-
 3 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/packages/core/src/client/require-session.spec.tsx b/packages/core/src/client/require-session.spec.tsx
index 6449ede42b..1e8504dd0c 100644
--- a/packages/core/src/client/require-session.spec.tsx
+++ b/packages/core/src/client/require-session.spec.tsx
@@ -215,7 +215,9 @@ describe("RequireSession", () => {
     // signed-in user to sign-in) nor "still loading" (which strands them).
     useSessionMock.mockReturnValue({
       session: null,
-      isLoading: false,
+      // The real hook keeps isLoading true for "unavailable" so legacy
+      // isLoading-only consumers never misread it as signed-out.
+      isLoading: true,
       status: "unavailable",
       error: new Error("Could not read the session after 4 attempts."),
       retry: vi.fn(),
diff --git a/packages/core/src/client/use-session.spec.tsx b/packages/core/src/client/use-session.spec.tsx
index fe4d1cf2ec..04308385dc 100644
--- a/packages/core/src/client/use-session.spec.tsx
+++ b/packages/core/src/client/use-session.spec.tsx
@@ -170,6 +170,26 @@ describe("useSession", () => {
     expect(analyticsMocks.trackSessionStatus).not.toHaveBeenCalled();
   });
 
+  it("keeps legacy isLoading consumers from misreading unavailable as signed-out", async () => {
+    // Consumers that only read `isLoading`/`session` (not `status`) must never
+    // see a false "signed out" once retries are exhausted.
+    vi.useFakeTimers();
+    const failingFetch = vi.fn(async () => new Response(null, { status: 503 }));
+    vi.stubGlobal("fetch", failingFetch);
+
+    await act(async () => {
+      root.render(<SessionConsumers labels={["first"]} />);
+      await Promise.resolve();
+    });
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(30_000);
+    });
+
+    expect(failingFetch).toHaveBeenCalledTimes(4);
+    expect(container.textContent).toBe("loading");
+  });
+
   it("caches a definitive unauthenticated response", async () => {
     const fetchMock = vi.fn(async () =>
       jsonResponse({ error: "Not authenticated" }),
diff --git a/packages/core/src/client/use-session.ts b/packages/core/src/client/use-session.ts
index e67b2a83a0..86b23c6b83 100644
--- a/packages/core/src/client/use-session.ts
+++ b/packages/core/src/client/use-session.ts
@@ -147,5 +147,13 @@ export function useSession(): UseSessionResult {
     };
   }, [retryToken]);
 
-  return { session, isLoading: status === "loading", status, error, retry };
+  // Callers that only read `isLoading`/`session` (most of the codebase, not
+  // yet migrated to `status`) must not see "unavailable" as "signed out" —
+  // that bounces an authenticated user through sign-in-only UI over a
+  // transient blip. Keeping `isLoading` true here reproduces this hook's
+  // pre-existing behavior for those callers (an indefinite "still resolving"
+  // instead of a wrong answer); only `status`-aware callers get the distinct
+  // "unavailable" treatment with a retry affordance.
+  const isLoading = status === "loading" || status === "unavailable";
+  return { session, isLoading, status, error, retry };
 }

From f89d21b0d3e58e397967c10998111ebc27ca6e2e Mon Sep 17 00:00:00 2001
From: "Builder.io" <builder-bot@builder.io>
Date: Tue, 4 Aug 2026 20:57:24 +0000
Subject: [PATCH 3/3] Fix session mock to include status field for consistent
 gate behavior

---
 packages/core/src/client/app-providers.spec.tsx | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/packages/core/src/client/app-providers.spec.tsx b/packages/core/src/client/app-providers.spec.tsx
index 55f7484fea..8f62abfea1 100644
--- a/packages/core/src/client/app-providers.spec.tsx
+++ b/packages/core/src/client/app-providers.spec.tsx
@@ -74,9 +74,18 @@ function renderProviders(props: {
   });
 }
 
+// `RequireSession` branches on `useSession().status`, not just `isLoading` —
+// every mock here must supply a status or the gate can neither redirect nor
+// hold the fallback consistently with the real hook.
+const SIGNED_OUT_SESSION = {
+  session: null,
+  isLoading: false,
+  status: "unauthenticated" as const,
+};
+
 describe("AppProviders session gate", () => {
   it("uses Toolkit's theme-aware toaster by default", () => {
-    useSessionMock.mockReturnValue({ session: null, isLoading: false });
+    useSessionMock.mockReturnValue(SIGNED_OUT_SESSION);
 
     act(() => {
       root.render(
@@ -92,7 +101,7 @@ describe("AppProviders session gate", () => {
   });
 
   it("renders public paths directly without resolving or redirecting a session", () => {
-    useSessionMock.mockReturnValue({ session: null, isLoading: false });
+    useSessionMock.mockReturnValue(SIGNED_OUT_SESSION);
 
     renderProviders({ isPublicPath: true });
 
@@ -104,7 +113,7 @@ describe("AppProviders session gate", () => {
   });
 
   it("gates private paths and redirects signed-out visitors after hydration", () => {
-    useSessionMock.mockReturnValue({ session: null, isLoading: false });
+    useSessionMock.mockReturnValue(SIGNED_OUT_SESSION);
 
     renderProviders({});
 
@@ -116,7 +125,7 @@ describe("AppProviders session gate", () => {
   });
 
   it("allows token-authenticated private surfaces to bypass the session gate", () => {
-    useSessionMock.mockReturnValue({ session: null, isLoading: false });
+    useSessionMock.mockReturnValue(SIGNED_OUT_SESSION);
 
     renderProviders({ sessionBypass: true });