fix(realtime): believe a refusal only once a fresh token has been refused too

"Access ended" is terminal for the hook's lifetime, so it was being reached
by three things that are not the end of anyone's access.

A realtime token lives at most 60 seconds. A backgrounded tab has its timers
throttled and can be frozen outright, so the gap between minting one and
opening the stream with it can outlast it, and the 401 that answers is about
the token rather than the person. A 404 is what an edge answers while the
realtime service is being replaced: no route right now, not "not your site".
And access_revoked is the control frame sent whenever an epoch moves, which
a member removal, a share-settings change, a deletion start and the worker
replaying any of those from its outbox all do. The hub's own comment spells
out the client's part of that contract, "stop, re-mint, and find out why
from the API", and calls over-bumping safe precisely because of it.

So each of those now costs one more round trip with a new token, and only
the second refusal is believed. A 403 still is believed at once: the gateway
read the token and answered about the person. The allowance resets on every
stream that opens, so it is one per healthy connection, not one per page.

The status also moves into the card's header, where the live count already
sits. A caveat about every number in the card belongs beside the card's name
rather than in a strip over the rows, and a live count printed next to a
stream that is not live is the one thing that header must never say.

Author: Uaghazade1

apps/web/components/dashboard/realtime-card.tsx

@@ -146,12 +146,23 @@ export function RealtimeCard() {
   // through the shell's header slot: it is a fact about the whole card, not
   // the first row of its list. Keyed on the number so a snapshot tick with
   // the same count never re-registers.
+  //
+  // An unhealthy feed takes that same slot, and takes it from the count
+  // (2026-08-26): "Reconnecting" or "Access ended" is a caveat about every
+  // number in the card, so it belongs where the card is named rather than in
+  // a strip over the rows, and a live count printed beside a stream that is
+  // not live is the one thing the header must never say.
   const liveCount = snapshot === null ? null : snapshot.active_visitors;
   React.useEffect(() => {
-    if (setHeaderChip === null || liveCount === null) return;
+    if (setHeaderChip === null) return;
+    if (status !== "live") {
+      setHeaderChip(<RealtimeStatusChip status={status} />);
+      return () => setHeaderChip(null);
+    }
+    if (liveCount === null) return;
     setHeaderChip(<LiveBadge count={liveCount} />);
     return () => setHeaderChip(null);
-  }, [setHeaderChip, liveCount]);
+  }, [setHeaderChip, liveCount, status]);
 
   // The same number, for the "Overview" heading (see the store above). The
   // card is the screen's one realtime subscriber, so it is also the one
@@ -181,26 +192,21 @@ export function RealtimeCard() {
   );
 
   if (snapshot === null) {
-    // No data yet: connecting, first reconnect, or access already lost.
+    // No data yet: connecting, first reconnect, or access already lost. The
+    // state itself is named in the header now, so what is left here is the
+    // sentence that explains it, and while connecting there is none to give.
     return (
-      <div className="flex h-full flex-col items-center justify-center gap-2 px-6 text-center">
-        <RealtimeStatusChip status={status} />
+      <div className="flex h-full flex-col items-center justify-center px-6 text-center">
         <RealtimeStatusNote status={status} />
       </div>
     );
   }
 
   return (
     <div className="flex h-full flex-col">
-      {/* No green "Live" badge row: a populated card is its own live signal,
-          and the count now sits beside the title. The chip returns only when
-          the feed is NOT healthy, because "Live paused" or "Reconnecting" is
-          a caveat about every number below it. */}
-      {status !== "live" && (
-        <div className="flex items-center justify-end px-5 pb-1 pt-0.5">
-          <RealtimeStatusChip status={status} />
-        </div>
-      )}
+      {/* Nothing above the rows any more, in either direction: the count and
+          the caveat both live in the header, and a strip here only ever
+          pushed the list down by a row. */}
       {latest.length === 0 ? (
         <p className="flex flex-1 items-center justify-center px-6 pb-4 text-center text-sm leading-6 text-muted-foreground">
           No one is browsing right now.

apps/web/hooks/use-realtime.ts

@@ -29,8 +29,28 @@ import {
  *
  * Reconnects mint a fresh token (the old one has expired by then) and resume
  * with `Last-Event-ID`, backing off around the stream's own `retry:` hint.
- * `access_lost` is terminal for the hook's lifetime: the server said this
- * user no longer sees this site, and only a remount re-arbitrates that.
+ *
+ * `access_lost` is terminal for the hook's lifetime, and for that reason it is
+ * only reached by a refusal that **survives a fresh token** (2026-08-26).
+ * Every path into it used to be believed on the spot, which painted a red
+ * "Access ended" over three ordinary things:
+ *
+ * - A token is good for at most 60 seconds. A backgrounded tab has its timers
+ *   throttled and can be frozen outright, so the gap between minting one and
+ *   opening the stream with it can outlast it. The `401` that answers is about
+ *   the token, not the person.
+ * - A `404` is what an edge answers while the realtime service is being
+ *   replaced. It means "no route right now", not "not your site".
+ * - `access_revoked` is the control frame the server sends when an epoch moves
+ *   (a member removed, share settings changed, a deletion started, or the
+ *   worker replaying that bump from its outbox). The realtime hub's own
+ *   comment states the client's part: "stop, re-mint, and find out why from
+ *   the API" is the contract, and over-bumping is called safe precisely
+ *   because of it.
+ *
+ * So each of those costs one more round trip with a new token, and only the
+ * second refusal is believed. A `403` still is: the gateway read the token and
+ * said this person may not have this site.
  */
 export function useRealtime(slug: string): {
   status: RealtimeStatus;
@@ -68,6 +88,12 @@ export function useRealtime(slug: string): {
       let attempt = 0;
       let lastId: string | null = null;
       let retryHintMs = DEFAULT_RETRY_MS;
+      /**
+       * Whether a refusal is already standing, unanswered by a fresh token.
+       * Cleared by any stream that opens, so the allowance is one per healthy
+       * connection rather than one per page.
+       */
+      let refusedOnce = false;
 
       while (!abort.signal.aborted) {
         try {
@@ -82,43 +108,68 @@ export function useRealtime(slug: string): {
             signal: abort.signal,
           });
 
-          if ([401, 403, 404].includes(response.status)) {
-            // The token minted a moment ago no longer opens the stream —
-            // the gateway is the arbiter, and it said no.
+          // 403 is the gateway having read the token and answered about the
+          // person. 401 and 404 are answers about the token and the route,
+          // which a new token settles, so they are worth exactly one more.
+          if (response.status === 403) {
             setStatus("access_lost");
             return;
           }
-          if (!response.ok || !response.body) {
-            throw new Error(`stream answered ${response.status}`);
-          }
+          if (response.status === 401 || response.status === 404) {
+            if (refusedOnce) {
+              setStatus("access_lost");
+              return;
+            }
+            refusedOnce = true;
+            setStatus("reconnecting");
+          } else {
+            if (!response.ok || !response.body) {
+              throw new Error(`stream answered ${response.status}`);
+            }
 
-          attempt = 0;
-          setStatus("live");
+            attempt = 0;
+            refusedOnce = false;
+            setStatus("live");
 
-          for await (const record of readSseRecords(
-            response.body,
-            abort.signal
-          )) {
-            if (record.retry !== undefined) retryHintMs = record.retry;
-            const frame = toFrame(record, "private");
-            if (!frame) continue;
-            if (frame.type === "retry") continue;
-            if (frame.type === "snapshot") {
-              if (frame.id) lastId = frame.id;
-              setSnapshot(frame.data as RealtimeSnapshot);
-              setStatus("live");
-              continue;
+            for await (const record of readSseRecords(
+              response.body,
+              abort.signal
+            )) {
+              if (record.retry !== undefined) retryHintMs = record.retry;
+              const frame = toFrame(record, "private");
+              if (!frame) continue;
+              if (frame.type === "retry") continue;
+              if (frame.type === "snapshot") {
+                if (frame.id) lastId = frame.id;
+                setSnapshot(frame.data as RealtimeSnapshot);
+                setStatus("live");
+                continue;
+              }
+              const next = statusAfterControl(frame.data);
+              if (frame.data.action === "disconnect") {
+                // A revocation is a claim about access that a fresh token can
+                // check. Believed the second time it is made, answered the
+                // first time by reconnecting.
+                if (next === "access_lost") {
+                  if (refusedOnce) {
+                    setStatus("access_lost");
+                    return;
+                  }
+                  refusedOnce = true;
+                  setStatus("reconnecting");
+                } else {
+                  setStatus(next);
+                }
+                break;
+              }
+              setStatus(next);
             }
-            const next = statusAfterControl(frame.data);
-            setStatus(next);
-            if (frame.data.action === "disconnect") {
-              if (next === "access_lost") return;
-              break; // polite server disconnect — reconnect with a new token
+            // Stream ended (network drop or server break), so fall through
+            // to the backoff and reconnect.
+            if (!abort.signal.aborted && !refusedOnce) {
+              setStatus("reconnecting");
             }
           }
-          // Stream ended (network drop or server break) — fall through to
-          // the backoff and reconnect.
-          if (!abort.signal.aborted) setStatus("reconnecting");
         } catch (raised: unknown) {
           if (abort.signal.aborted) return;
           if (isUnauthenticated(raised)) {