fix(web): keep offline recovery out of session gate

Author: pallyoung

packages/web/src/app/providers.lifecycle.test.tsx

@@ -68,6 +68,13 @@ function createWsSendCommandMock(
   handler?: (op: string, args: unknown) => Promise<unknown> | unknown
 ) {
   return vi.fn().mockImplementation(async (op: string, args: unknown) => {
+    if (handler) {
+      const handled = await handler(op, args);
+      if (handled !== undefined) {
+        return handled;
+      }
+    }
+
     if (op === "activation.claim") {
       return {
         active: true,
@@ -80,10 +87,6 @@ function createWsSendCommandMock(
       return { ok: true };
     }
 
-    if (handler) {
-      return await handler(op, args);
-    }
-
     return undefined;
   });
 }
@@ -562,6 +565,96 @@ describe("AppProviders lifecycle recovery", () => {
     ).toHaveLength(0);
   });
 
+  it("does not gate activation when websocket reconnect fails", async () => {
+    const store = createStore();
+    wsState.client!.connect = vi.fn().mockRejectedValue(new Error("connect failed"));
+
+    renderProviders(store);
+
+    await vi.waitFor(() => {
+      expect(wsState.client?.connect).toHaveBeenCalled();
+    });
+
+    await vi.waitFor(() => {
+      expect(store.get(activationStatusAtom)).not.toBe("gated");
+      expect(store.get(activationReasonAtom)).toBeNull();
+    });
+  });
+
+  it("does not gate activation when activation.claim fails", async () => {
+    const store = createStore();
+    wsState.client!.sendCommand = createWsSendCommandMock(async (op: string) => {
+      if (op === "activation.claim") {
+        throw new Error("claim failed");
+      }
+
+      return undefined;
+    });
+
+    renderProviders(store);
+
+    await vi.waitFor(() => {
+      expect(wsState.client?.connect).toHaveBeenCalled();
+    });
+
+    act(() => {
+      wsState.client?.statusHandler?.("connected");
+    });
+
+    await vi.waitFor(() => {
+      expect(store.get(activationStatusAtom)).not.toBe("gated");
+      expect(store.get(activationReasonAtom)).toBeNull();
+    });
+  });
+
+  it("retries activation.claim after a transient failure while connected", async () => {
+    const store = createStore();
+    let claimAttempts = 0;
+    vi.useFakeTimers();
+    wsState.client!.sendCommand = createWsSendCommandMock(async (op: string) => {
+      if (op === "activation.claim") {
+        claimAttempts += 1;
+        if (claimAttempts === 1) {
+          throw new Error("claim failed");
+        }
+
+        return {
+          active: true,
+          generation: 2,
+          recoveryMode: "grace_recover",
+        };
+      }
+
+      return undefined;
+    });
+
+    renderProviders(store);
+
+    await vi.waitFor(() => {
+      expect(wsState.client?.connect).toHaveBeenCalled();
+    });
+
+    act(() => {
+      wsState.client?.statusHandler?.("connected");
+    });
+
+    await vi.waitFor(() => {
+      expect(claimAttempts).toBe(1);
+      expect(store.get(activationStatusAtom)).toBe("idle");
+    });
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1_000);
+    });
+
+    await vi.waitFor(() => {
+      expect(claimAttempts).toBe(2);
+      expect(store.get(activationStatusAtom)).toBe("active");
+      expect(store.get(activationGenerationAtom)).toBe(2);
+      expect(store.get(activationReasonAtom)).toBeNull();
+    });
+  });
+
   it("disconnects and gates when activation.revoked is received", async () => {
     const store = createStore();
     seedWorkspaces(store, ["ws-1"], "ws-1");

packages/web/src/app/providers.tsx

@@ -463,7 +463,7 @@ export function AppProviders({ children }: AppProvidersProps) {
       // Track reconnect attempts
       if (status === "reconnecting") {
         setReconnectCount((count) => count + 1);
-        setLastReconnect(Date.now());
+        setLastReconnect((previous) => previous ?? Date.now());
       }
 
       // Reset writer status on disconnect
@@ -472,6 +472,8 @@ export function AppProviders({ children }: AppProvidersProps) {
       }
 
       if (status === "connected") {
+        setReconnectCount(0);
+        setLastReconnect(null);
         syncWorkspaceActivity(true);
       }
     };

packages/web/src/hooks/use-activation.ts

@@ -14,6 +14,8 @@ interface ActivationClaimPayload {
   recoveryMode: "fresh" | "grace_recover" | "takeover";
 }
 
+const CLAIM_RETRY_DELAY_MS = 1_000;
+
 export function useActivation() {
   const wsClient = useAtomValue(wsClientAtom);
   const connectionStatus = useAtomValue(connectionStatusAtom);
@@ -22,6 +24,7 @@ export function useActivation() {
   const [generation, setGeneration] = useAtom(activationGenerationAtom);
   const setReason = useSetAtom(activationReasonAtom);
   const claimInFlightRef = useRef<Promise<boolean> | null>(null);
+  const claimRetryTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   const claim = useCallback(async (): Promise<boolean> => {
     if (!wsClient) {
@@ -32,8 +35,8 @@ export function useActivation() {
       try {
         await wsClient.connect();
       } catch {
-        setStatus("gated");
-        setReason("reconnect_failed");
+        setReason(null);
+        setStatus((current) => (current === "gated" ? current : "idle"));
         return false;
       }
     }
@@ -54,9 +57,9 @@ export function useActivation() {
         setStatus("active");
         return true;
       })
-      .catch((error) => {
-        setStatus("gated");
-        setReason(error instanceof Error ? error.message : "claim_failed");
+      .catch(() => {
+        setReason(null);
+        setStatus((current) => (current === "gated" ? current : "idle"));
         return false;
       })
       .finally(() => {
@@ -67,8 +70,38 @@ export function useActivation() {
     return pending;
   }, [clientInstanceId, connectionStatus, setGeneration, setReason, setStatus, wsClient]);
 
+  useEffect(() => {
+    if (claimRetryTimerRef.current !== null) {
+      clearTimeout(claimRetryTimerRef.current);
+      claimRetryTimerRef.current = null;
+    }
+
+    if (!wsClient || connectionStatus !== "connected" || status !== "idle") {
+      return;
+    }
+
+    claimRetryTimerRef.current = setTimeout(() => {
+      claimRetryTimerRef.current = null;
+      if (!claimInFlightRef.current) {
+        void claim();
+      }
+    }, CLAIM_RETRY_DELAY_MS);
+
+    return () => {
+      if (claimRetryTimerRef.current !== null) {
+        clearTimeout(claimRetryTimerRef.current);
+        claimRetryTimerRef.current = null;
+      }
+    };
+  }, [claim, connectionStatus, status, wsClient]);
+
   useEffect(() => {
     return () => {
+      if (claimRetryTimerRef.current !== null) {
+        clearTimeout(claimRetryTimerRef.current);
+        claimRetryTimerRef.current = null;
+      }
+
       if (!wsClient || generation === null) {
         return;
       }

packages/web/src/shells/desktop-shell.test.tsx

@@ -2,7 +2,7 @@ import { render, screen, waitFor } from "@testing-library/react";
 import { createStore, Provider } from "jotai";
 import { BrowserRouter } from "react-router-dom";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { activationStatusAtom } from "../atoms/activation";
+import { activationReasonAtom, activationStatusAtom } from "../atoms/activation";
 import { authenticatedAtom, localeAtom } from "../atoms/app-ui";
 import { authEnabledAtom, connectionStatusAtom, wsClientAtom } from "../atoms/connection";
 import {
@@ -313,7 +313,21 @@ describe("DesktopShell auth gating", () => {
 
     renderShell(store);
 
-    expect(screen.getByText("正在重新连接...")).toBeInTheDocument();
+    expect(screen.getByText("连接已断开，正在重新连接...")).toBeInTheDocument();
+  });
+
+  it("shows the displaced-session banner on desktop when activation is gated", () => {
+    const store = createStore();
+    store.set(connectionStatusAtom, "disconnected");
+    store.set(authEnabledAtom, false);
+    store.set(authenticatedAtom, true);
+    store.set(activationStatusAtom, "gated");
+    store.set(activationReasonAtom, "displaced");
+
+    renderShell(store);
+
+    expect(screen.getByText("另一个标签页已激活")).toBeInTheDocument();
+    expect(screen.queryByText("连接已断开，正在重新连接...")).not.toBeInTheDocument();
   });
 
   it("renders SessionGatePage on /session-gate", () => {

packages/web/src/shells/shared/connection-status-banner.test.tsx

@@ -0,0 +1,104 @@
+import { act, render, screen } from "@testing-library/react";
+import { createStore, Provider } from "jotai";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { activationReasonAtom, activationStatusAtom } from "../../atoms/activation";
+import { connectionStatusAtom, lastReconnectAttemptAtom } from "../../atoms/connection";
+import { ConnectionStatusBanner } from "./connection-status-banner";
+
+function renderBanner() {
+  const store = createStore();
+
+  render(
+    <Provider store={store}>
+      <ConnectionStatusBanner />
+    </Provider>
+  );
+
+  return store;
+}
+
+describe("ConnectionStatusBanner", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("renders the unified reconnect message while reconnecting", () => {
+    const store = renderBanner();
+
+    act(() => {
+      store.set(connectionStatusAtom, "reconnecting");
+    });
+
+    expect(screen.getByText("连接已断开，正在重新连接...")).toBeInTheDocument();
+  });
+
+  it("shows the displaced-session message instead of reconnecting when activation is gated", () => {
+    const store = renderBanner();
+
+    act(() => {
+      store.set(activationStatusAtom, "gated");
+      store.set(activationReasonAtom, "displaced");
+      store.set(connectionStatusAtom, "disconnected");
+    });
+
+    expect(screen.getByText("另一个标签页已激活")).toBeInTheDocument();
+    expect(screen.queryByText("连接已断开，正在重新连接...")).not.toBeInTheDocument();
+  });
+
+  it("shows the slow recovery hint after 25 seconds", () => {
+    const startedAt = new Date("2026-05-14T00:00:00.000Z").getTime();
+    vi.setSystemTime(startedAt + 25_000);
+    const store = renderBanner();
+
+    act(() => {
+      store.set(connectionStatusAtom, "reconnecting");
+      store.set(lastReconnectAttemptAtom, startedAt);
+    });
+
+    expect(
+      screen.getByText("连接恢复较慢，可能是网络问题。如果长时间没有恢复，可以刷新页面。")
+    ).toBeInTheDocument();
+  });
+
+  it("reveals the slow recovery hint after time passes without another status update", () => {
+    const startedAt = new Date("2026-05-14T00:00:00.000Z").getTime();
+    vi.setSystemTime(startedAt);
+    const store = renderBanner();
+
+    act(() => {
+      store.set(connectionStatusAtom, "reconnecting");
+      store.set(lastReconnectAttemptAtom, startedAt);
+    });
+
+    expect(
+      screen.queryByText("连接恢复较慢，可能是网络问题。如果长时间没有恢复，可以刷新页面。")
+    ).not.toBeInTheDocument();
+
+    act(() => {
+      vi.advanceTimersByTime(25_000);
+    });
+
+    expect(
+      screen.getByText("连接恢复较慢，可能是网络问题。如果长时间没有恢复，可以刷新页面。")
+    ).toBeInTheDocument();
+  });
+
+  it("does not show the slow recovery hint before the threshold", () => {
+    const startedAt = new Date("2026-05-14T00:00:00.000Z").getTime();
+    vi.setSystemTime(startedAt + 24_000);
+    const store = renderBanner();
+
+    act(() => {
+      store.set(connectionStatusAtom, "reconnecting");
+      store.set(lastReconnectAttemptAtom, startedAt);
+    });
+
+    expect(
+      screen.queryByText("连接恢复较慢，可能是网络问题。如果长时间没有恢复，可以刷新页面。")
+    ).not.toBeInTheDocument();
+  });
+});