Multi-Agent Collaboration for Team and Friends
TypeScript agent-automationagent-orchestrationagent-workflowai-agentsai-collaborationai-memoryai-workforceautonomous-agentsclaude-codeclaude-code-skillscodexcoding-agentmulti-agentmultiple-agentone-person-businessone-person-companyone-person-teamopencodesolopreneur
fix(web): harden WebSocket reconnect lifecycle (#742)
Gener996493a0ff43
diff --git a/src/web/src/lib/analytics.test.ts b/src/web/src/lib/analytics.test.tsindex ee136869e..e669b4505 100644--- a/src/web/src/lib/analytics.test.ts+++ b/src/web/src/lib/analytics.test.ts@@ -31,9 +31,13 @@ import {trackSettingsUpdated,trackCanvasLayoutChanged,trackCommunityWsFrameDropped,+ trackCommunityWsAuthFailure,+ trackCommunityWsLifecycleClose,trackCommunityWsLifecycleRecovery,+ trackCommunityWsLifecycleStage,trackCommunityWsReconcileComplete,trackCommunityWsReconcileFailure,+ trackCommunityWsRetryScheduled,} from "./analytics"describe("analytics utility", () => {@@ -313,5 +317,59 @@ describe("analytics utility", () => {suspensionDuration: "over-2m",})})++ it("reports normalized close metadata without raw reasons or identities", () => {+ trackCommunityWsLifecycleClose({+ initiator: "validation-timeout",+ code: 1006,+ wasClean: false,+ reasonBucket: "abnormal",+ reason: "token=secret",+ userId: "user-1",+ url: "wss://example.test/?token=secret",+ } as never)+ expect(mockSendGTMEvent).toHaveBeenCalledWith({+ event: "community_ws_lifecycle_close",+ initiator: "validation-timeout",+ code: 1006,+ wasClean: false,+ reasonBucket: "abnormal",+ })+ })++ it("reports bounded auth, stage, and retry fields only", () => {+ trackCommunityWsAuthFailure({+ failureClass: "credentials",+ token: "secret",+ } as never)+ trackCommunityWsLifecycleStage({+ stage: "auth",+ result: "timeout",+ durationMs: Number.POSITIVE_INFINITY,+ nonce: "private",+ } as never)+ trackCommunityWsRetryScheduled({+ attempt: 3_000,+ delayMs: -1,+ windowMs: 900_000,+ rawReason: "private",+ } as never)++ expect(mockSendGTMEvent.mock.calls).toEqual([+ [{ event: "community_ws_auth_failure", failureClass: "credentials" }],+ [{+ event: "community_ws_lifecycle_stage",+ stage: "auth",+ result: "timeout",+ durationMs: 0,+ }],+ [{+ event: "community_ws_retry_scheduled",+ attempt: 1_000,+ delayMs: 0,+ windowMs: 600_000,+ }],+ ])+ })})})diff --git a/src/web/src/lib/analytics.ts b/src/web/src/lib/analytics.tsindex c37f7c08a..6b68153f6 100644--- a/src/web/src/lib/analytics.ts+++ b/src/web/src/lib/analytics.ts@@ -207,6 +207,47 @@ export type CommunityWsSuspensionDurationBucket =| "under-30s"| "unknown"+export type CommunityWsCloseInitiator =+ | "auth-failure"+ | "connect-timeout"+ | "freeze"+ | "heartbeat-timeout"+ | "local-retire"+ | "manual-retry"+ | "offline"+ | "remote"+ | "validation-failure"+ | "validation-timeout"++export type CommunityWsCloseReasonBucket =+ | "abnormal"+ | "going-away"+ | "normal"+ | "other"+ | "policy"+ | "server-error"+ | "unknown"++export type CommunityWsAuthFailureClass =+ | "credentials"+ | "network"+ | "server"+ | "timeout"+ | "unknown"++export type CommunityWsLifecycleStage = "auth" | "open" | "token" | "validation"++export type CommunityWsLifecycleStageResult =+ | "aborted"+ | "failure"+ | "success"+ | "timeout"++function boundedCommunityWsInteger(value: number, maximum: number): number {+ if (!Number.isFinite(value)) return 0+ return Math.min(Math.max(0, Math.round(value)), maximum)+}+function sendCommunityWsGTMEvent(payload: Record<string, unknown>) {try {sendGTMEvent(payload)@@ -271,6 +312,56 @@ export function trackCommunityWsLifecycleRecovery(params: {});}+export function trackCommunityWsLifecycleClose(params: {+ initiator: CommunityWsCloseInitiator+ code: number+ wasClean: boolean+ reasonBucket: CommunityWsCloseReasonBucket+}) {+ sendCommunityWsGTMEvent({+ event: "community_ws_lifecycle_close",+ initiator: params.initiator,+ code: boundedCommunityWsInteger(params.code, 4999),+ wasClean: params.wasClean === true,+ reasonBucket: params.reasonBucket,+ });+}++export function trackCommunityWsAuthFailure(params: {+ failureClass: CommunityWsAuthFailureClass+}) {+ sendCommunityWsGTMEvent({+ event: "community_ws_auth_failure",+ failureClass: params.failureClass,+ });+}++export function trackCommunityWsLifecycleStage(params: {+ stage: CommunityWsLifecycleStage+ result: CommunityWsLifecycleStageResult+ durationMs: number+}) {+ sendCommunityWsGTMEvent({+ event: "community_ws_lifecycle_stage",+ stage: params.stage,+ result: params.result,+ durationMs: boundedCommunityWsInteger(params.durationMs, 600_000),+ });+}++export function trackCommunityWsRetryScheduled(params: {+ attempt: number+ delayMs: number+ windowMs: number+}) {+ sendCommunityWsGTMEvent({+ event: "community_ws_retry_scheduled",+ attempt: boundedCommunityWsInteger(params.attempt, 1_000),+ delayMs: boundedCommunityWsInteger(params.delayMs, 600_000),+ windowMs: boundedCommunityWsInteger(params.windowMs, 600_000),+ });+}+// ─── P3 — Page-Level Behavior ───────────────────────────────────────────────export function trackLandingCtaClicked(params: { cta_name: string }) {diff --git a/src/web/src/lib/use-user-ws.test.ts b/src/web/src/lib/use-user-ws.test.tsindex b2ee46949..90fab095f 100644--- a/src/web/src/lib/use-user-ws.test.ts+++ b/src/web/src/lib/use-user-ws.test.ts@@ -6,9 +6,17 @@ import {import type { UseUserWsOptions } from "./use-user-ws"const mockTrackCommunityWsLifecycleRecovery = vi.hoisted(() => vi.fn())+const mockTrackCommunityWsAuthFailure = vi.hoisted(() => vi.fn())+const mockTrackCommunityWsLifecycleClose = vi.hoisted(() => vi.fn())+const mockTrackCommunityWsLifecycleStage = vi.hoisted(() => vi.fn())+const mockTrackCommunityWsRetryScheduled = vi.hoisted(() => vi.fn())vi.mock("@/lib/analytics", async (importOriginal) => ({...await importOriginal<typeof import("@/lib/analytics")>(),+ trackCommunityWsAuthFailure: mockTrackCommunityWsAuthFailure,+ trackCommunityWsLifecycleClose: mockTrackCommunityWsLifecycleClose,trackCommunityWsLifecycleRecovery: mockTrackCommunityWsLifecycleRecovery,+ trackCommunityWsLifecycleStage: mockTrackCommunityWsLifecycleStage,+ trackCommunityWsRetryScheduled: mockTrackCommunityWsRetryScheduled,}))// --- Mock WebSocket ---@@ -23,7 +31,7 @@ class MockWebSocket {onopen: (() => void) | null = nullonmessage: ((e: { data: string }) => void) | null = nullonerror: (() => void) | null = null- onclose: (() => void) | null = null+ onclose: ((event?: { code: number; reason: string; wasClean: boolean }) => void) | null = nullclosed = falsesent: string[] = []@@ -32,14 +40,23 @@ class MockWebSocket {MockWebSocket.instances.push(this)}send(data: string) { this.sent.push(data) }- close() { this.closed = true; this.readyState = MockWebSocket.CLOSED; this.onclose?.() }+ close() {+ if (this.readyState === MockWebSocket.CLOSING || this.readyState === MockWebSocket.CLOSED) return+ this.closed = true+ this.readyState = MockWebSocket.CLOSED+ this.onclose?.({ code: 1000, reason: "local detail", wasClean: true })+ }// Helpers for testssimulateOpen() { this.readyState = MockWebSocket.OPEN; this.onopen?.() }simulateMessage(data: unknown) { this.onmessage?.({ data: JSON.stringify(data) }) }simulateRawMessage(data: string) { this.onmessage?.({ data }) }simulateError() { this.onerror?.() }- simulateClose() { this.readyState = MockWebSocket.CLOSED; this.onclose?.() }+ simulateClose(code = 1006, reason = "remote detail", wasClean = false) {+ this.closed = true+ this.readyState = MockWebSocket.CLOSED+ this.onclose?.({ code, reason, wasClean })+ }}vi.stubGlobal("WebSocket", MockWebSocket)@@ -79,8 +96,10 @@ const mockDocument = Object.assign(new MockEventTarget(), {wasDiscarded: false,})const mockWindow = Object.assign(new MockEventTarget(), { location: { origin: "http://localhost:3000" } })+const mockNavigator = { onLine: true }vi.stubGlobal("document", mockDocument)vi.stubGlobal("window", mockWindow)+vi.stubGlobal("navigator", mockNavigator)// Mock fetch for /api/ws/tokenconst mockFetch = vi.fn()@@ -198,6 +217,7 @@ function dispatchWindowFocus() {}function resetMockState() {+ vi.stubGlobal("WebSocket", MockWebSocket)MockWebSocket.instances = []mockFetch.mockReset()effectCleanup = null@@ -209,7 +229,12 @@ function resetMockState() {effectCounter = 0latestHookResult = nullmockTrackCommunityWsLifecycleRecovery.mockReset()+ mockTrackCommunityWsAuthFailure.mockReset()+ mockTrackCommunityWsLifecycleClose.mockReset()+ mockTrackCommunityWsLifecycleStage.mockReset()+ mockTrackCommunityWsRetryScheduled.mockReset()mockDocument.visibilityState = "visible"+ mockNavigator.onLine = truemockDocument.reset()mockWindow.reset()}@@ -490,6 +515,38 @@ describe("useUserWs", () => {expect(MockWebSocket.instances).toHaveLength(1)})+ it("keeps a hidden socketless page suspended when it goes offline", async () => {+ setupTokenFetch()+ mockDocument.visibilityState = "hidden"+ const onConnectionStateChange = vi.fn()++ await mountHook(vi.fn(), {+ onConnectionStateChange,+ requestDaemonStatusOnAuth: false,+ })+ mockNavigator.onLine = false+ mockWindow.dispatch("offline")++ expect(onConnectionStateChange).toHaveBeenLastCalledWith("suspended")+ expect(mockFetch).not.toHaveBeenCalled()+ expect(MockWebSocket.instances).toEqual([])+ })++ it("publishes reconnecting without fetching during a visible offline cold start", async () => {+ setupTokenFetch()+ mockNavigator.onLine = false+ const onConnectionStateChange = vi.fn()++ await mountHook(vi.fn(), {+ onConnectionStateChange,+ requestDaemonStatusOnAuth: false,+ })++ expect(onConnectionStateChange).toHaveBeenLastCalledWith("reconnecting")+ expect(mockFetch).not.toHaveBeenCalled()+ expect(MockWebSocket.instances).toEqual([])+ })+it("manual reconnect retires the current socket and starts exactly one fresh generation", async () => {setupTokenFetch()const onAuthenticated = vi.fn()@@ -518,6 +575,57 @@ describe("useUserWs", () => {expect(MockWebSocket.instances).toHaveLength(2)})+ it("reports local retirement and remote close exactly once per socket", async () => {+ setupTokenFetch()+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })+ const first = MockWebSocket.instances[0]!+ first.simulateOpen()+ first.simulateMessage({ type: "auth.ok" })++ latestHookResult!.reconnectNow()+ await flushPromises()+ first.simulateClose(1000, "duplicate local detail", true)++ expect(mockTrackCommunityWsLifecycleClose.mock.calls+ .filter(([event]) => event.initiator === "manual-retry"))+ .toHaveLength(1)++ const replacement = MockWebSocket.instances[1]!+ replacement.simulateOpen()+ replacement.simulateMessage({ type: "auth.ok" })+ replacement.simulateClose(1006, "private remote detail", false)+ replacement.simulateClose(1006, "duplicate private detail", false)++ expect(mockTrackCommunityWsLifecycleClose.mock.calls+ .filter(([event]) => event.initiator === "remote"))+ .toHaveLength(1)+ expect(JSON.stringify(mockTrackCommunityWsLifecycleClose.mock.calls))+ .not.toContain("private remote detail")+ })++ it.each([+ [1001, "going-away"],+ [1011, "server-error"],+ [4321, "other"],+ ] as const)("normalizes remote close code %i to %s", async (code, reasonBucket) => {+ setupTokenFetch()+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })+ const ws = MockWebSocket.instances[0]!+ ws.simulateOpen()+ ws.simulateMessage({ type: "auth.ok" })++ ws.simulateClose(code, "private raw reason", false)++ expect(mockTrackCommunityWsLifecycleClose).toHaveBeenCalledWith({+ initiator: "remote",+ code,+ wasClean: false,+ reasonBucket,+ })+ expect(JSON.stringify(mockTrackCommunityWsLifecycleClose.mock.calls))+ .not.toContain("private raw reason")+ })+it("manual reconnect invalidates an older pending token before it can create a socket", async () => {const firstTokenResponse = deferred<{ok: boolean@@ -611,6 +719,362 @@ describe("useUserWs", () => {effectCleanup?.()})+ it("classifies HTTP auth failures without recording token or close reason content", async () => {+ mockFetch.mockResolvedValueOnce({ ok: false, status: 403 })+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })++ expect(mockTrackCommunityWsAuthFailure).toHaveBeenCalledWith({+ failureClass: "credentials",+ })+ expect(mockTrackCommunityWsLifecycleStage).toHaveBeenCalledWith(expect.objectContaining({+ stage: "token",+ result: "failure",+ }))++ mockFetch.mockResolvedValueOnce({ ok: false, status: 503 })+ latestHookResult!.reconnectNow()+ await flushPromises()+ expect(mockTrackCommunityWsAuthFailure).toHaveBeenCalledWith({+ failureClass: "server",+ })++ mockFetch.mockResolvedValueOnce({ ok: false, status: 429 })+ latestHookResult!.reconnectNow()+ await flushPromises()+ expect(mockTrackCommunityWsAuthFailure).toHaveBeenCalledWith({+ failureClass: "unknown",+ })++ setupTokenFetch()+ latestHookResult!.reconnectNow()+ await flushPromises()+ const ws = MockWebSocket.instances[0]!+ ws.simulateOpen()+ ws.simulateClose(1008, "token=private", false)++ expect(mockTrackCommunityWsLifecycleClose).toHaveBeenCalledWith({+ initiator: "auth-failure",+ code: 1008,+ wasClean: false,+ reasonBucket: "policy",+ })+ expect(JSON.stringify(mockTrackCommunityWsLifecycleClose.mock.calls))+ .not.toContain("token=private")+ })++ it("rechecks offline state before foreground validation after telemetry", async () => {+ setupTokenFetch()+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })+ const ws = MockWebSocket.instances[0]!+ ws.simulateOpen()+ ws.simulateMessage({ type: "auth.ok" })+ mockTrackCommunityWsLifecycleRecovery.mockImplementationOnce(() => {+ mockNavigator.onLine = false+ mockWindow.dispatch("offline")+ })++ dispatchWindowFocus()++ expect(connectionPings(ws)).toEqual([])+ expect(ws.closed).toBe(false)+ })++ it("rechecks offline state after the reconnecting lifecycle callback", async () => {+ setupTokenFetch()+ const onConnectionStateChange = vi.fn((phase: string) => {+ if (phase === "reconnecting") mockNavigator.onLine = false+ })++ await mountHook(vi.fn(), {+ onConnectionStateChange,+ requestDaemonStatusOnAuth: false,+ })++ expect(onConnectionStateChange).toHaveBeenCalledWith("reconnecting")+ expect(mockFetch).not.toHaveBeenCalled()+ expect(MockWebSocket.instances).toEqual([])+ })++ it("drops a token body that resolves after navigator becomes offline", async () => {+ const body = deferred<{ userId: string; token: string }>()+ mockFetch.mockResolvedValue({+ ok: true,+ json: () => body.promise,+ } as Response)+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })+ expect(mockFetch).toHaveBeenCalledOnce()++ mockNavigator.onLine = false+ body.resolve({ userId: "stale-user", token: "stale-token" })+ await flushPromises()++ expect(MockWebSocket.instances).toEqual([])+ })++ it("does not run a scheduled retry if navigator becomes offline before it fires", async () => {+ mockFetch.mockRejectedValueOnce(new Error("network unavailable"))+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })+ expect(mockTrackCommunityWsRetryScheduled).toHaveBeenCalledOnce()++ mockNavigator.onLine = false+ await vi.advanceTimersByTimeAsync(1_000)++ expect(mockFetch).toHaveBeenCalledOnce()+ expect(MockWebSocket.instances).toEqual([])+ })++ it("reports WebSocket constructor failures and schedules a retry", async () => {+ class ThrowingWebSocket {+ static CONNECTING = 0+ static OPEN = 1+ static CLOSING = 2+ static CLOSED = 3+ constructor(_url: string) {+ throw new Error("constructor failed")+ }+ }+ vi.stubGlobal("WebSocket", ThrowingWebSocket)+ setupTokenFetch()++ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })++ expect(mockTrackCommunityWsLifecycleStage).toHaveBeenCalledWith(expect.objectContaining({+ stage: "open",+ result: "failure",+ }))+ expect(mockTrackCommunityWsRetryScheduled).toHaveBeenCalledOnce()+ })++ it("closes without authenticating if navigator becomes offline before open", async () => {+ setupTokenFetch()+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })+ const ws = MockWebSocket.instances[0]!++ mockNavigator.onLine = false+ ws.simulateOpen()++ expect(ws.closed).toBe(true)+ expect(ws.sent).toEqual([])+ expect(mockTrackCommunityWsLifecycleClose).toHaveBeenCalledWith(expect.objectContaining({+ initiator: "offline",+ }))+ })++ it("reports an auth transport failure when the auth frame send throws", async () => {+ setupTokenFetch()+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })+ const ws = MockWebSocket.instances[0]!+ ws.send = vi.fn(() => { throw new Error("auth send failed") })++ ws.simulateOpen()++ expect(ws.closed).toBe(true)+ expect(mockTrackCommunityWsLifecycleStage).toHaveBeenCalledWith(expect.objectContaining({+ stage: "auth",+ result: "failure",+ }))+ expect(mockTrackCommunityWsAuthFailure).toHaveBeenCalledWith({+ failureClass: "network",+ })+ expect(mockTrackCommunityWsLifecycleClose).toHaveBeenCalledWith(expect.objectContaining({+ initiator: "auth-failure",+ }))+ })++ it("retires and retries when the post-auth status frame send throws", async () => {+ setupTokenFetch()+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: true })+ const ws = MockWebSocket.instances[0]!+ const send = ws.send.bind(ws)+ ws.send = vi.fn((data: string) => {+ if (data === JSON.stringify({ type: "check_daemon_status" })) {+ throw new Error("status send failed")+ }+ send(data)+ })+ ws.simulateOpen()++ ws.simulateMessage({ type: "auth.ok" })++ expect(ws.closed).toBe(true)+ expect(mockTrackCommunityWsLifecycleClose).toHaveBeenCalledWith(expect.objectContaining({+ initiator: "local-retire",+ }))+ expect(mockTrackCommunityWsRetryScheduled).toHaveBeenCalledOnce()+ })++ it("uses offline as a hard gate for pending tokens, retries, and manual recovery", async () => {+ const firstTokenResponse = deferred<Response>()+ mockFetch+ .mockReturnValueOnce(firstTokenResponse.promise)+ .mockResolvedValue({+ ok: true,+ json: () => Promise.resolve({ userId: "online-user", token: "online-token" }),+ })++ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })+ const firstSignal = (mockFetch.mock.calls[0]?.[1] as RequestInit).signal++ mockNavigator.onLine = false+ mockWindow.dispatch("offline")+ latestHookResult!.reconnectNow()+ dispatchWindowFocus()+ mockDocument.dispatch("resume")+ await vi.advanceTimersByTimeAsync(60_000)++ expect(firstSignal?.aborted).toBe(true)+ expect(mockFetch).toHaveBeenCalledOnce()+ expect(MockWebSocket.instances).toEqual([])++ firstTokenResponse.resolve({+ ok: true,+ json: () => Promise.resolve({ userId: "stale-user", token: "stale-token" }),+ } as Response)+ await flushPromises()+ expect(MockWebSocket.instances).toEqual([])++ mockNavigator.onLine = true+ mockWindow.dispatch("online")+ mockWindow.dispatch("online")+ await flushPromises()++ expect(mockFetch).toHaveBeenCalledTimes(2)+ expect(MockWebSocket.instances).toHaveLength(1)+ expect(MockWebSocket.instances[0]?.url).toContain("online-user")+ })++ it("keeps an authenticated socket silent offline and validates it once online", async () => {+ setupTokenFetch()+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })+ const ws = MockWebSocket.instances[0]!+ ws.simulateOpen()+ ws.simulateMessage({ type: "auth.ok" })+ const fetchCount = mockFetch.mock.calls.length++ mockNavigator.onLine = false+ mockWindow.dispatch("offline")+ const offlineFrameCount = ws.sent.length+ latestHookResult!.send({ type: "check_daemon_status" })+ latestHookResult!.reconnectNow()+ dispatchWindowFocus()+ mockDocument.dispatch("resume")+ dispatchPageShow(true)+ await vi.advanceTimersByTimeAsync(60_000)++ expect(ws.closed).toBe(false)+ expect(ws.sent).toHaveLength(offlineFrameCount)+ expect(mockFetch).toHaveBeenCalledTimes(fetchCount)++ mockNavigator.onLine = true+ mockWindow.dispatch("online")+ mockWindow.dispatch("online")+ dispatchWindowFocus()++ expect(connectionPings(ws)).toHaveLength(1)+ expect(MockWebSocket.instances).toEqual([ws])+ expect(mockFetch).toHaveBeenCalledTimes(fetchCount)+ })++ it("applies offline cleanup after send observes the browser offline before the event", async () => {+ setupTokenFetch()+ const onConnectionStateChange = vi.fn()+ await mountHook(vi.fn(), {+ onConnectionStateChange,+ requestDaemonStatusOnAuth: false,+ })+ const ws = MockWebSocket.instances[0]!+ ws.simulateOpen()+ ws.simulateMessage({ type: "auth.ok" })+ const authenticatedTimerCount = vi.getTimerCount()+ const sentCount = ws.sent.length++ mockNavigator.onLine = false+ latestHookResult!.send({ type: "check_daemon_status" })+ expect(ws.sent).toHaveLength(sentCount)+ expect(vi.getTimerCount()).toBe(authenticatedTimerCount)++ mockWindow.dispatch("offline")++ expect(ws.closed).toBe(false)+ expect(onConnectionStateChange).toHaveBeenLastCalledWith("suspended")+ expect(vi.getTimerCount()).toBeLessThan(authenticatedTimerCount)++ await vi.advanceTimersByTimeAsync(60_000)+ expect(ws.sent).toHaveLength(sentCount)+ })++ it("publishes reconnecting if a retained authenticated socket closes while offline", async () => {+ setupTokenFetch()+ const onConnectionStateChange = vi.fn()+ await mountHook(vi.fn(), {+ onConnectionStateChange,+ requestDaemonStatusOnAuth: false,+ })+ const ws = MockWebSocket.instances[0]!+ ws.simulateOpen()+ ws.simulateMessage({ type: "auth.ok" })+ const fetchCount = mockFetch.mock.calls.length++ mockNavigator.onLine = false+ mockWindow.dispatch("offline")+ expect(onConnectionStateChange).toHaveBeenLastCalledWith("suspended")++ ws.simulateClose(1012, "offline remote close", false)+ expect(onConnectionStateChange).toHaveBeenLastCalledWith("reconnecting")+ await vi.advanceTimersByTimeAsync(60_000)++ expect(mockFetch).toHaveBeenCalledTimes(fetchCount)+ expect(MockWebSocket.instances).toEqual([ws])+ })++ it("retires an open pre-auth socket offline and ignores every late frame", async () => {+ setupTokenFetch()+ const onAuthenticated = vi.fn()+ await mountHook(vi.fn(), { onAuthenticated, requestDaemonStatusOnAuth: false })+ const first = MockWebSocket.instances[0]!+ first.simulateOpen()+ expect(first.sent).toContain(JSON.stringify({ type: "auth", token: "tok-123" }))++ mockNavigator.onLine = false+ mockWindow.dispatch("offline")+ first.simulateMessage({ type: "auth.ok" })+ first.simulateMessage({ type: "task.updated", taskId: "stale" })+ await vi.advanceTimersByTimeAsync(60_000)++ expect(first.closed).toBe(true)+ expect(onAuthenticated).not.toHaveBeenCalled()+ expect(mockFetch).toHaveBeenCalledOnce()++ mockNavigator.onLine = true+ mockWindow.dispatch("online")+ mockWindow.dispatch("online")+ await flushPromises()+ expect(mockFetch).toHaveBeenCalledTimes(2)+ expect(MockWebSocket.instances).toHaveLength(2)+ })++ it("cancels a scheduled retry offline and starts one replacement online", async () => {+ mockFetch.mockRejectedValueOnce(new Error("network unavailable"))+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })+ expect(mockTrackCommunityWsRetryScheduled).toHaveBeenCalledOnce()++ mockNavigator.onLine = false+ mockWindow.dispatch("offline")+ latestHookResult!.reconnectNow()+ dispatchWindowFocus()+ await vi.advanceTimersByTimeAsync(60_000)+ expect(mockFetch).toHaveBeenCalledOnce()++ setupTokenFetch()+ mockNavigator.onLine = true+ mockWindow.dispatch("online")+ mockWindow.dispatch("online")+ await flushPromises()++ expect(mockFetch).toHaveBeenCalledTimes(2)+ expect(MockWebSocket.instances).toHaveLength(1)+ })+it("suppresses reconnect while hidden and reconnects immediately when visible", async () => {setupTokenFetch()await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })@@ -738,7 +1202,7 @@ describe("useUserWs", () => {dispatchWindowFocus()await flushPromises()- expect(closing.closed).toBe(true)+ expect(closing.closed).toBe(false)expect(MockWebSocket.instances).toHaveLength(3)expect(mockTrackCommunityWsLifecycleRecovery).toHaveBeenLastCalledWith({trigger: "focus",@@ -748,6 +1212,32 @@ describe("useUserWs", () => {})})+ it("preserves a remote initiator when recovery races a remote closing handshake", async () => {+ setupTokenFetch()+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })+ const ws = MockWebSocket.instances[0]!+ ws.simulateOpen()+ ws.simulateMessage({ type: "auth.ok" })++ ws.readyState = MockWebSocket.CLOSING+ dispatchWindowFocus()+ await flushPromises()+ expect(mockTrackCommunityWsLifecycleClose).not.toHaveBeenCalled()+ expect(MockWebSocket.instances).toHaveLength(2)++ ws.simulateClose(1006, "private remote detail", false)++ expect(mockTrackCommunityWsLifecycleClose).toHaveBeenCalledOnce()+ expect(mockTrackCommunityWsLifecycleClose).toHaveBeenCalledWith({+ initiator: "remote",+ code: 1006,+ wasClean: false,+ reasonBucket: "abnormal",+ })+ expect(JSON.stringify(mockTrackCommunityWsLifecycleClose.mock.calls))+ .not.toContain("private remote detail")+ })+it("clears a pending reconnect when the page becomes hidden", async () => {setupTokenFetch()await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })@@ -1081,7 +1571,8 @@ describe("useUserWs", () => {mockWindow.dispatch("offline")mockWindow.dispatch("online")- expect(connectionPings(ws)).toHaveLength(1)+ expect(connectionPings(ws)).toHaveLength(2)+ expect(connectionPings(ws)[1]?.nonce).not.toBe(connectionPings(ws)[0]?.nonce)})it("keeps a cleared foreground validation timer inert", async () => {@@ -1310,6 +1801,36 @@ describe("useUserWs", () => {expect(mockFetch).toHaveBeenCalledTimes(2)})+ it("recovers once online after validation observes offline before the offline event", async () => {+ setupTokenFetch()+ const onConnectionStateChange = vi.fn()+ const mod = await mountHook(vi.fn(), {+ onConnectionStateChange,+ requestDaemonStatusOnAuth: false,+ })+ const ws = MockWebSocket.instances[0]!+ ws.simulateOpen()+ ws.simulateMessage({ type: "auth.ok" })+ dispatchWindowFocus()+ expect(connectionPings(ws)).toHaveLength(1)++ mockNavigator.onLine = false+ await vi.advanceTimersByTimeAsync(mod.WS_CONNECTION_VALIDATION_TIMEOUT_MS)++ expect(ws.closed).toBe(true)+ expect(onConnectionStateChange).toHaveBeenLastCalledWith("reconnecting")+ expect(mockFetch).toHaveBeenCalledOnce()++ setupTokenFetch()+ mockNavigator.onLine = true+ mockWindow.dispatch("online")+ mockWindow.dispatch("online")+ await flushPromises()++ expect(mockFetch).toHaveBeenCalledTimes(2)+ expect(MockWebSocket.instances).toHaveLength(2)+ })+it("treats error as non-authoritative and lets current close start one validation failure chain", async () => {setupTokenFetch()const onConnectionStateChange = vi.fn()@@ -1343,6 +1864,44 @@ describe("useUserWs", () => {expect(mockFetch).toHaveBeenCalledTimes(2)})+ it("uses full jitter, preserves the failure window across manual retries, and resets on auth.ok", async () => {+ const random = vi.spyOn(Math, "random").mockReturnValue(0.5)+ mockFetch.mockRejectedValue(new Error("network error"))+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })++ expect(mockTrackCommunityWsAuthFailure).toHaveBeenCalledWith({+ failureClass: "network",+ })+ expect(mockTrackCommunityWsRetryScheduled).toHaveBeenLastCalledWith({+ attempt: 1,+ delayMs: 500,+ windowMs: 1_000,+ })++ latestHookResult!.reconnectNow()+ await flushPromises()+ expect(mockTrackCommunityWsRetryScheduled).toHaveBeenLastCalledWith({+ attempt: 2,+ delayMs: 1_000,+ windowMs: 2_000,+ })++ setupTokenFetch()+ latestHookResult!.reconnectNow()+ await flushPromises()+ const ws = MockWebSocket.instances[0]!+ ws.simulateOpen()+ ws.simulateMessage({ type: "auth.ok" })+ ws.simulateClose()++ expect(mockTrackCommunityWsRetryScheduled).toHaveBeenLastCalledWith({+ attempt: 1,+ delayMs: 500,+ windowMs: 1_000,+ })+ random.mockRestore()+ })+it("failed connect (fetch rejects) retries with backoff and cleanup prevents further reconnects", async () => {// All connects will failmockFetch.mockRejectedValue(new Error("network error"))@@ -1659,6 +2218,47 @@ describe("useUserWs", () => {expect(trace).toEqual(["authenticated", "reconnect", "status", "message"])})+ it("does not send or start heartbeat after onAuthenticated synchronously reconnects", async () => {+ setupTokenFetch()+ let reconnectDuringCallback = true+ const onAuthenticated = vi.fn(() => {+ if (!reconnectDuringCallback) return+ reconnectDuringCallback = false+ latestHookResult!.reconnectNow()+ })+ await mountHook(vi.fn(), { onAuthenticated, requestDaemonStatusOnAuth: true })+ const first = MockWebSocket.instances[0]!+ first.simulateOpen()+ first.simulateMessage({ type: "auth.ok" })+ await flushPromises()++ expect(first.closed).toBe(true)+ expect(first.sent).not.toContain(JSON.stringify({ type: "check_daemon_status" }))+ expect(MockWebSocket.instances).toHaveLength(2)+ await vi.advanceTimersByTimeAsync(25_000)+ expect(first.sent).not.toContain("ping")+ })++ it("does not continue an old auth.ok after onReconnect synchronously replaces it", async () => {+ setupTokenFetch()+ const onReconnect = vi.fn(() => latestHookResult!.reconnectNow())+ await mountHook(vi.fn(), { onReconnect, requestDaemonStatusOnAuth: true })+ const first = MockWebSocket.instances[0]!+ first.simulateOpen()+ first.simulateMessage({ type: "auth.ok" })+ first.simulateClose()+ await vi.advanceTimersByTimeAsync(2_000)++ const replacement = MockWebSocket.instances.at(-1)!+ replacement.simulateOpen()+ replacement.simulateMessage({ type: "auth.ok" })+ await flushPromises()++ expect(replacement.closed).toBe(true)+ expect(replacement.sent).not.toContain(JSON.stringify({ type: "check_daemon_status" }))+ expect(MockWebSocket.instances).toHaveLength(3)+ })+it("isolates synchronous throws and asynchronous rejections from lifecycle callbacks", async () => {setupTokenFetch()const warn = vi.spyOn(console, "warn").mockImplementation(() => {})diff --git a/src/web/src/lib/use-user-ws.ts b/src/web/src/lib/use-user-ws.tsindex 4156cf118..e18d0bc7d 100644--- a/src/web/src/lib/use-user-ws.ts+++ b/src/web/src/lib/use-user-ws.ts@@ -10,9 +10,17 @@ import {type WsMessage,} from "@alook/shared"import {+ trackCommunityWsAuthFailure,trackCommunityWsFrameDropped,+ trackCommunityWsLifecycleClose,trackCommunityWsLifecycleRecovery,+ trackCommunityWsLifecycleStage,+ trackCommunityWsRetryScheduled,+ type CommunityWsAuthFailureClass,+ type CommunityWsCloseInitiator,+ type CommunityWsCloseReasonBucket,type CommunityWsFrameDropReason,+ type CommunityWsLifecycleStageResult,type CommunityWsLifecycleRecoveryStrategy,type CommunityWsLifecycleRecoveryTrigger,type CommunityWsSocketReadyState,@@ -33,13 +41,50 @@ type PendingConnectionValidation = {ws: WebSocketgeneration: numbernonce: string+ startedAt: numbertimeout: ReturnType<typeof setTimeout>}+type PendingTokenAttempt = {+ controller: AbortController+ generation: number+ startedAt: number+ reported: boolean+}+function isPageHidden(): boolean {return typeof document !== "undefined" && document.visibilityState === "hidden"}+function isBrowserOffline(): boolean {+ return typeof navigator !== "undefined" && navigator.onLine === false+}++function boundedDurationMs(startedAt: number): number {+ return Math.min(Math.max(0, Date.now() - startedAt), 600_000)+}++function normalizedCloseCode(code: number | undefined): number {+ if (code === undefined || !Number.isInteger(code) || code < 0 || code > 4999) return 0+ return code+}++function closeReasonBucket(code: number): CommunityWsCloseReasonBucket {+ if (code === 1000) return "normal"+ if (code === 1001) return "going-away"+ if (code === 1005 || code === 1006) return "abnormal"+ if (code === 1008) return "policy"+ if (code === 1011) return "server-error"+ if (code === 0) return "unknown"+ return "other"+}++function tokenFailureClass(status: number): CommunityWsAuthFailureClass {+ if (status === 401 || status === 403) return "credentials"+ if (status >= 500) return "server"+ return "unknown"+}+function socketReadyState(ws: WebSocket | null): CommunityWsSocketReadyState {if (!ws) return "none"switch (ws.readyState) {@@ -125,6 +170,7 @@ export function useUserWs(): { send: (msg: object) => void; reconnectNow: () => void } {const wsRef = useRef<WebSocket | null>(null)const reconnectDelay = useRef(WS_RECONNECT_INIT)+ const reconnectAttemptRef = useRef(0)const onMessageRef = useRef(onMessage)const onReconnectRef = useRef(options?.onReconnect)const onDisconnectRef = useRef(options?.onDisconnect)@@ -133,7 +179,7 @@ export function useUserWs(const lastConnectionPhaseRef = useRef<UserWsConnectionPhase | null>(null)const requestDaemonStatusOnAuthRef = useRef(options?.requestDaemonStatusOnAuth ?? true)const reconnectTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)- const tokenAbortRef = useRef<AbortController | null>(null)+ const pendingTokenRef = useRef<PendingTokenAttempt | null>(null)const tokenTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)const connectTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)const connectStartedAtRef = useRef(0)@@ -150,6 +196,16 @@ export function useUserWs(const suspendedAtRef = useRef<number | null>(null)const sentinelIntervalRef = useRef<ReturnType<typeof setInterval> | null>(null)const lastSentinelTickAtRef = useRef(0)+ const offlineRef = useRef(isBrowserOffline())+ const offlineCleanupAppliedRef = useRef(false)+ const localCloseInitiatorRef = useRef(new WeakMap<WebSocket, CommunityWsCloseInitiator>())+ const reportedCloseSocketsRef = useRef(new WeakSet<WebSocket>())+ const isOffline = useCallback(() => {+ if (offlineRef.current) return true+ if (!isBrowserOffline()) return false+ offlineRef.current = true+ return true+ }, [])useEffect(() => {onMessageRef.current = onMessage@@ -182,19 +238,89 @@ export function useUserWs(onConnectionStateChangeRef.current?.(phase))}, [])- const clearConnectionValidation = useCallback(() => {+ const ownsConnection = useCallback((ws: WebSocket, generation: number) => (+ ws === wsRef.current && generation === connectionGenerationRef.current+ ), [])++ const ownsAuthenticatedConnection = useCallback((ws: WebSocket, generation: number) => (+ ownsConnection(ws, generation)+ && authenticatedGenerationRef.current === generation+ && ws.readyState === WebSocket.OPEN+ ), [ownsConnection])++ const clearConnectionValidation = useCallback((+ result?: CommunityWsLifecycleStageResult,+ ) => {const pending = connectionValidationRef.currentconnectionValidationRef.current = nullif (pending) clearTimeout(pending.timeout)+ if (pending && result) {+ trackCommunityWsLifecycleStage({+ stage: "validation",+ result,+ durationMs: boundedDurationMs(pending.startedAt),+ })+ }+ }, [])++ const reportTokenAttempt = useCallback((+ attempt: PendingTokenAttempt,+ result: CommunityWsLifecycleStageResult,+ ) => {+ if (attempt.reported) return+ attempt.reported = true+ trackCommunityWsLifecycleStage({+ stage: "token",+ result,+ durationMs: boundedDurationMs(attempt.startedAt),+ })}, [])const abortPendingToken = useCallback(() => {- tokenAbortRef.current?.abort()- tokenAbortRef.current = null+ const attempt = pendingTokenRef.current+ pendingTokenRef.current = null+ if (attempt) {+ reportTokenAttempt(attempt, "aborted")+ attempt.controller.abort()+ }if (tokenTimeoutRef.current !== null) {clearTimeout(tokenTimeoutRef.current)tokenTimeoutRef.current = null}+ }, [reportTokenAttempt])++ const closeSocket = useCallback((ws: WebSocket, initiator: CommunityWsCloseInitiator) => {+ if (+ !localCloseInitiatorRef.current.has(ws)+ && ws.readyState !== WebSocket.CLOSING+ && ws.readyState !== WebSocket.CLOSED+ ) {+ localCloseInitiatorRef.current.set(ws, initiator)+ }+ ws.close()+ }, [])++ const reportSocketClose = useCallback((+ ws: WebSocket,+ event?: Pick<CloseEvent, "code" | "wasClean">,+ ): CommunityWsCloseInitiator => {+ const localInitiator = localCloseInitiatorRef.current.get(ws)+ localCloseInitiatorRef.current.delete(ws)+ const code = normalizedCloseCode(event?.code)+ const initiator = localInitiator+ ?? (authenticatedGenerationRef.current === null && code === 1008+ ? "auth-failure"+ : "remote")+ if (!reportedCloseSocketsRef.current.has(ws)) {+ reportedCloseSocketsRef.current.add(ws)+ trackCommunityWsLifecycleClose({+ initiator,+ code,+ wasClean: event?.wasClean === true,+ reasonBucket: closeReasonBucket(code),+ })+ }+ return initiator}, [])const stopHeartbeat = useCallback(() => {@@ -206,25 +332,36 @@ export function useUserWs(stopHeartbeat()if (isPageHidden()+ || isOffline()|| frozenRef.current- || ws !== wsRef.current- || generation !== connectionGenerationRef.current- || authenticatedGenerationRef.current !== generation- || ws.readyState !== WebSocket.OPEN+ || !ownsAuthenticatedConnection(ws, generation)) returnlastMessageAtRef.current = Date.now()pingIntervalRef.current = setInterval(() => {- if (ws.readyState === WebSocket.OPEN) ws.send("ping")+ if (+ !isOffline()+ && !isPageHidden()+ && !frozenRef.current+ && ownsAuthenticatedConnection(ws, generation)+ ) ws.send("ping")}, 25_000)livenessIntervalRef.current = setInterval(() => {- if (Date.now() - lastMessageAtRef.current > 30_000) ws.close()+ if (+ !isOffline()+ && ownsAuthenticatedConnection(ws, generation)+ && Date.now() - lastMessageAtRef.current > 30_000+ ) closeSocket(ws, "heartbeat-timeout")}, 5_000)- }, [stopHeartbeat])+ }, [closeSocket, isOffline, ownsAuthenticatedConnection, stopHeartbeat])- const retireSocket = useCallback((reportDisconnect = true) => {+ const retireSocket = useCallback((+ reportDisconnect: boolean,+ initiator: CommunityWsCloseInitiator,+ validationResult: CommunityWsLifecycleStageResult = "aborted",+ ) => {const ws = wsRef.currentwsRef.current = null- clearConnectionValidation()+ clearConnectionValidation(validationResult)if (reportDisconnect && authenticatedGenerationRef.current !== null) {authenticatedGenerationRef.current = nulldisconnectedAtRef.current ??= Date.now()@@ -232,13 +369,14 @@ export function useUserWs(}stopHeartbeat()if (connectTimeoutRef.current !== null) { clearTimeout(connectTimeoutRef.current); connectTimeoutRef.current = null }- ws?.close()- }, [clearConnectionValidation, stopHeartbeat])+ if (ws) closeSocket(ws, initiator)+ }, [clearConnectionValidation, closeSocket, stopHeartbeat])const failConnectionValidation = useCallback((ws: WebSocket,generation: number,nonce: string,+ result: "failure" | "timeout",) => {const pending = connectionValidationRef.currentif (@@ -249,14 +387,23 @@ export function useUserWs(|| ws !== wsRef.current|| generation !== connectionGenerationRef.current) return- clearConnectionValidation()- retireSocket()- const suspended = isPageHidden() || frozenRef.current- publishConnectionPhase(suspended ? "suspended" : "reconnecting")- if (!suspended) void connectRef.current?.()- }, [clearConnectionValidation, publishConnectionPhase, retireSocket])+ const initiator = result === "timeout" ? "validation-timeout" : "validation-failure"+ clearConnectionValidation(result)+ retireSocket(true, initiator, result)+ if (generation !== connectionGenerationRef.current) return+ const parked = isPageHidden() || frozenRef.current+ publishConnectionPhase(parked ? "suspended" : "reconnecting")+ if (generation !== connectionGenerationRef.current) return+ if (!parked && !isOffline()) void connectRef.current?.()+ }, [clearConnectionValidation, isOffline, publishConnectionPhase, retireSocket])const validateCurrentConnection = useCallback((ws: WebSocket, generation: number) => {+ if (+ isOffline()+ || isPageHidden()+ || frozenRef.current+ || !ownsAuthenticatedConnection(ws, generation)+ ) returnconst current = connectionValidationRef.currentif (current?.ws === ws@@ -264,104 +411,197 @@ export function useUserWs(&& ws === wsRef.current&& generation === connectionGenerationRef.current) return- clearConnectionValidation()+ clearConnectionValidation("aborted")stopHeartbeat()const nonce = crypto.randomUUID()const pending: PendingConnectionValidation = {ws,generation,nonce,+ startedAt: Date.now(),timeout: setTimeout(() => {- failConnectionValidation(ws, generation, nonce)+ failConnectionValidation(ws, generation, nonce, "timeout")}, WS_CONNECTION_VALIDATION_TIMEOUT_MS),}connectionValidationRef.current = pendingtry {ws.send(JSON.stringify({ type: "connection.ping", nonce }))} catch {- failConnectionValidation(ws, generation, nonce)+ failConnectionValidation(ws, generation, nonce, "failure")}- }, [clearConnectionValidation, failConnectionValidation, stopHeartbeat])+ }, [+ clearConnectionValidation,+ failConnectionValidation,+ isOffline,+ ownsAuthenticatedConnection,+ stopHeartbeat,+ ])const scheduleReconnect = useCallback((generation: number) => {if (generation !== connectionGenerationRef.current) return- if (isPageHidden() || frozenRef.current) return+ if (isPageHidden() || isOffline() || frozenRef.current) returnif (reconnectTimerRef.current !== null) {clearTimeout(reconnectTimerRef.current)reconnectTimerRef.current = null}- const delay = Math.min(reconnectDelay.current, WS_RECONNECT_MAX)- reconnectDelay.current = Math.min(delay * 2, WS_RECONNECT_MAX)+ const windowMs = Math.min(reconnectDelay.current, WS_RECONNECT_MAX)+ const delayMs = Math.floor(Math.random() * windowMs)+ const attempt = reconnectAttemptRef.current + 1+ reconnectAttemptRef.current = attempt+ reconnectDelay.current = Math.min(windowMs * 2, WS_RECONNECT_MAX)+ trackCommunityWsRetryScheduled({ attempt, delayMs, windowMs })reconnectTimerRef.current = setTimeout(() => {- if (generation !== connectionGenerationRef.current) return+ reconnectTimerRef.current = null+ if (+ generation !== connectionGenerationRef.current+ || isPageHidden()+ || isOffline()+ || frozenRef.current+ ) returnvoid connectRef.current?.()- }, delay + Math.random() * 500)- }, [])+ }, delayMs)+ }, [isOffline])const connect = useCallback(async () => {- if (isPageHidden() || frozenRef.current) {- publishConnectionPhase("suspended")+ if (isPageHidden() || isOffline() || frozenRef.current) {+ publishConnectionPhase(+ isPageHidden() || frozenRef.current ? "suspended" : "reconnecting",+ )return}+ if (pendingTokenRef.current) return+ const previousGeneration = connectionGenerationRef.currentpublishConnectionPhase("reconnecting")- const generation = connectionGenerationRef.current + 1+ if (+ pendingTokenRef.current+ || previousGeneration !== connectionGenerationRef.current+ || isPageHidden()+ || isOffline()+ || frozenRef.current+ ) return+ const generation = previousGeneration + 1connectionGenerationRef.current = generationif (reconnectTimerRef.current !== null) {clearTimeout(reconnectTimerRef.current)reconnectTimerRef.current = null}- tokenAbortRef.current?.abort()const tokenController = new AbortController()- tokenAbortRef.current = tokenController+ const tokenAttempt: PendingTokenAttempt = {+ controller: tokenController,+ generation,+ startedAt: Date.now(),+ reported: false,+ }+ pendingTokenRef.current = tokenAttemptlet tokenTimedOut = falsetokenTimeoutRef.current = setTimeout(() => {+ if (pendingTokenRef.current !== tokenAttempt) returntokenTimedOut = true+ pendingTokenRef.current = null+ tokenTimeoutRef.current = null+ reportTokenAttempt(tokenAttempt, "timeout")+ trackCommunityWsAuthFailure({ failureClass: "timeout" })tokenController.abort()+ scheduleReconnect(generation)}, WS_TOKEN_TIMEOUT_MS)let userId: stringlet authToken: stringlet wsPort: number = WS_DO_PORT_DEFAULT+ let tokenResponseReceived = falsetry {const res = await fetch("/api/ws/token", { signal: tokenController.signal })+ tokenResponseReceived = true+ if (+ pendingTokenRef.current !== tokenAttempt+ || generation !== connectionGenerationRef.current+ || isOffline()+ ) returnif (!res.ok) {- if (generation !== connectionGenerationRef.current) return+ reportTokenAttempt(tokenAttempt, "failure")+ trackCommunityWsAuthFailure({ failureClass: tokenFailureClass(res.status) })console.warn("[ws] token fetch failed:", res.status)scheduleReconnect(generation)return}const body = await res.json() as { userId: string; token: string; wsPort?: number }- if (generation !== connectionGenerationRef.current) return+ if (+ pendingTokenRef.current !== tokenAttempt+ || generation !== connectionGenerationRef.current+ || isOffline()+ ) return+ reportTokenAttempt(tokenAttempt, "success")userId = body.userIdauthToken = body.tokenif (body.wsPort) wsPort = body.wsPort} catch (err) {- if (generation !== connectionGenerationRef.current) return- if (tokenController.signal.aborted && !tokenTimedOut) return+ if (+ pendingTokenRef.current !== tokenAttempt+ || generation !== connectionGenerationRef.current+ || isOffline()+ ) return+ if (tokenController.signal.aborted || tokenTimedOut) return+ reportTokenAttempt(tokenAttempt, "failure")+ trackCommunityWsAuthFailure({+ failureClass: tokenResponseReceived ? "unknown" : "network",+ })console.warn("[ws] token fetch error:", err)scheduleReconnect(generation)return} finally {- if (tokenAbortRef.current === tokenController) {+ if (pendingTokenRef.current === tokenAttempt) {if (tokenTimeoutRef.current !== null) {clearTimeout(tokenTimeoutRef.current)tokenTimeoutRef.current = null}- tokenAbortRef.current = null+ pendingTokenRef.current = null}}+ if (generation !== connectionGenerationRef.current || isOffline()) return+const wsBaseUrl = useLocalServices? websocketUrl("user", { local: true, port: wsPort }): websocketUrl("user", { local: false, origin: location.origin })const url = `${wsBaseUrl}?userId=${userId}`+ const socketStartedAt = Date.now()+ let openedAt = 0+ let openStageReported = false+ let authStageReported = false+ let authFailureReported = false+ const reportOpenStage = (result: CommunityWsLifecycleStageResult) => {+ if (openStageReported) return+ openStageReported = true+ trackCommunityWsLifecycleStage({+ stage: "open",+ result,+ durationMs: boundedDurationMs(socketStartedAt),+ })+ }+ const reportAuthStage = (result: CommunityWsLifecycleStageResult) => {+ if (authStageReported || openedAt === 0) return+ authStageReported = true+ trackCommunityWsLifecycleStage({+ stage: "auth",+ result,+ durationMs: boundedDurationMs(openedAt),+ })+ }+ const reportAuthFailure = (failureClass: CommunityWsAuthFailureClass) => {+ if (authFailureReported) return+ authFailureReported = true+ trackCommunityWsAuthFailure({ failureClass })+ }+let ws: WebSockettry {- if (generation !== connectionGenerationRef.current) return- retireSocket()+ if (generation !== connectionGenerationRef.current || isOffline()) return+ retireSocket(true, "local-retire")+ if (generation !== connectionGenerationRef.current || isOffline()) returnws = new WebSocket(url)} catch (err) {if (generation !== connectionGenerationRef.current) return+ reportOpenStage("failure")console.warn("[ws] WebSocket creation failed:", err)scheduleReconnect(generation)return@@ -369,18 +609,35 @@ export function useUserWs(wsRef.current = wsconnectStartedAtRef.current = Date.now()connectTimeoutRef.current = setTimeout(() => {- if (ws !== wsRef.current || generation !== connectionGenerationRef.current) return- ws.close()+ if (!ownsConnection(ws, generation)) return+ if (openedAt === 0) {+ reportOpenStage("timeout")+ } else {+ reportAuthStage("timeout")+ reportAuthFailure("timeout")+ }+ closeSocket(ws, "connect-timeout")}, WS_CONNECTION_VALIDATION_TIMEOUT_MS)ws.onopen = () => {- if (ws !== wsRef.current || generation !== connectionGenerationRef.current) return- reconnectDelay.current = WS_RECONNECT_INIT- ws.send(JSON.stringify({ type: "auth", token: authToken }))+ if (!ownsConnection(ws, generation)) return+ if (isOffline()) {+ closeSocket(ws, "offline")+ return+ }+ openedAt = Date.now()+ reportOpenStage("success")+ try {+ ws.send(JSON.stringify({ type: "auth", token: authToken }))+ } catch {+ reportAuthStage("failure")+ reportAuthFailure("network")+ closeSocket(ws, "auth-failure")+ }}ws.onmessage = (e) => {- if (ws !== wsRef.current || generation !== connectionGenerationRef.current) return+ if (!ownsConnection(ws, generation) || isOffline()) returnlastMessageAtRef.current = Date.now()if (typeof e.data !== "string") {reportDroppedFrame("invalid-json")@@ -412,8 +669,12 @@ export function useUserWs(&& pending.nonce === msg.nonce&& authenticatedGenerationRef.current === generation) {- clearConnectionValidation()+ clearConnectionValidation("success")publishConnectionPhase("authenticated")+ if (+ isOffline()+ || !ownsAuthenticatedConnection(ws, generation)+ ) returnstartHeartbeat(ws, generation)}return@@ -423,6 +684,7 @@ export function useUserWs(reportDroppedFrame("duplicate-auth-ok", msg)return}+ reportAuthStage("success")authenticatedGenerationRef.current = generationif (connectTimeoutRef.current !== null) {clearTimeout(connectTimeoutRef.current)@@ -435,14 +697,28 @@ export function useUserWs(: Math.max(0, Date.now() - disconnectedAtRef.current)disconnectedAtRef.current = nullpublishConnectionPhase("authenticated")+ if (!ownsAuthenticatedConnection(ws, generation) || isOffline()) returnrunLifecycleCallback("authenticated", onAuthenticatedRef.current)+ if (!ownsAuthenticatedConnection(ws, generation) || isOffline()) returnif (isReconnect) {runLifecycleCallback("reconnect", () =>onReconnectRef.current?.({ reconnectDurationMs }))+ if (!ownsAuthenticatedConnection(ws, generation) || isOffline()) return}+ reconnectDelay.current = WS_RECONNECT_INIT+ reconnectAttemptRef.current = 0if (requestDaemonStatusOnAuthRef.current) {- ws.send(JSON.stringify({ type: "check_daemon_status" }))+ try {+ ws.send(JSON.stringify({ type: "check_daemon_status" }))+ } catch {+ retireSocket(true, "local-retire")+ if (generation === connectionGenerationRef.current) {+ scheduleReconnect(generation)+ }+ return+ }}+ if (!ownsAuthenticatedConnection(ws, generation) || isOffline()) returnstartHeartbeat(ws, generation)return}@@ -472,28 +748,67 @@ export function useUserWs(ws.onerror = () => {}- ws.onclose = () => {- if (ws !== wsRef.current) return+ ws.onclose = (event) => {+ const initiator = reportSocketClose(ws, event)+ const timeout = initiator === "connect-timeout"+ const aborted = initiator === "freeze"+ || initiator === "local-retire"+ || initiator === "manual-retry"+ || initiator === "offline"+ if (!openStageReported) reportOpenStage(timeout ? "timeout" : aborted ? "aborted" : "failure")+ if (openedAt !== 0 && !authStageReported) {+ reportAuthStage(timeout ? "timeout" : aborted ? "aborted" : "failure")+ if (initiator === "auth-failure") {+ const code = normalizedCloseCode(event?.code)+ reportAuthFailure(code === 1008 ? "credentials" : "network")+ } else if (initiator === "remote") {+ const code = normalizedCloseCode(event?.code)+ reportAuthFailure(code === 1008 ? "credentials" : code === 1011 ? "server" : "network")+ }+ }+ if (!ownsConnection(ws, generation)) returnconst validation = connectionValidationRef.current- if (+ const failedValidation = Boolean(validation?.ws === ws&& validation.generation === generation- ) {- failConnectionValidation(ws, generation, validation.nonce)- return+ )+ if (failedValidation) {+ clearConnectionValidation("failure")}const wasAuthenticated = authenticatedGenerationRef.current === generation+ wsRef.current = nullif (wasAuthenticated) {authenticatedGenerationRef.current = nulldisconnectedAtRef.current ??= Date.now()runLifecycleCallback("disconnect", onDisconnectRef.current)+ if (generation !== connectionGenerationRef.current) return}stopHeartbeat()if (connectTimeoutRef.current !== null) { clearTimeout(connectTimeoutRef.current); connectTimeoutRef.current = null }- publishConnectionPhase(isPageHidden() || frozenRef.current ? "suspended" : "reconnecting")- scheduleReconnect(generation)+ publishConnectionPhase(+ isPageHidden() || frozenRef.current ? "suspended" : "reconnecting",+ )+ if (generation !== connectionGenerationRef.current) return+ if (failedValidation && !isPageHidden() && !isOffline() && !frozenRef.current) {+ void connectRef.current?.()+ } else {+ scheduleReconnect(generation)+ }}- }, [clearConnectionValidation, failConnectionValidation, publishConnectionPhase, retireSocket, scheduleReconnect, startHeartbeat, stopHeartbeat])+ }, [+ clearConnectionValidation,+ closeSocket,+ isOffline,+ ownsAuthenticatedConnection,+ ownsConnection,+ publishConnectionPhase,+ reportSocketClose,+ reportTokenAttempt,+ retireSocket,+ scheduleReconnect,+ startHeartbeat,+ stopHeartbeat,+ ])useEffect(() => {connectRef.current = connect@@ -502,7 +817,7 @@ export function useUserWs(const suspendConnection = useCallback((retireAuthenticatedSocket: boolean) => {connectionValidationNeededRef.current = truesuspendedAtRef.current ??= Date.now()- clearConnectionValidation()+ clearConnectionValidation("aborted")stopHeartbeat()publishConnectionPhase("suspended")if (reconnectTimerRef.current !== null) {@@ -511,21 +826,59 @@ export function useUserWs(}const generation = connectionGenerationRef.current+ const ws = wsRef.currentconst authenticated = authenticatedGenerationRef.current === generation- if (!retireAuthenticatedSocket && authenticated) return+ if (!retireAuthenticatedSocket && authenticated && ws?.readyState === WebSocket.OPEN) returnconnectionGenerationRef.current += 1abortPendingToken()- retireSocket(retireAuthenticatedSocket)+ retireSocket(+ retireAuthenticatedSocket,+ retireAuthenticatedSocket ? "freeze" : "local-retire",+ )}, [abortPendingToken, clearConnectionValidation, publishConnectionPhase, retireSocket, stopHeartbeat])+ const suspendForOffline = useCallback(() => {+ offlineRef.current = true+ if (offlineCleanupAppliedRef.current) return+ offlineCleanupAppliedRef.current = true+ connectionValidationNeededRef.current = true+ suspendedAtRef.current ??= Date.now()+ clearConnectionValidation("aborted")+ stopHeartbeat()+ if (reconnectTimerRef.current !== null) {+ clearTimeout(reconnectTimerRef.current)+ reconnectTimerRef.current = null+ }+ abortPendingToken()++ const ws = wsRef.current+ const generation = connectionGenerationRef.current+ const retainAuthenticatedSocket = ws+ ? ownsAuthenticatedConnection(ws, generation)+ : false+ if (!retainAuthenticatedSocket) {+ connectionGenerationRef.current += 1+ retireSocket(true, "offline")+ }+ const parked = retainAuthenticatedSocket || isPageHidden() || frozenRef.current+ publishConnectionPhase(parked ? "suspended" : "reconnecting")+ }, [+ abortPendingToken,+ clearConnectionValidation,+ ownsAuthenticatedConnection,+ publishConnectionPhase,+ retireSocket,+ stopHeartbeat,+ ])+const trackLifecycleRecovery = useCallback((trigger: CommunityWsLifecycleRecoveryTrigger,strategy: CommunityWsLifecycleRecoveryStrategy,readyState: CommunityWsSocketReadyState,now: number,) => {- if (isPageHidden() || frozenRef.current) return+ if (isPageHidden() || isOffline() || frozenRef.current) returntrackCommunityWsLifecycleRecovery({trigger,strategy,@@ -533,12 +886,21 @@ export function useUserWs(suspensionDuration: suspensionDurationBucket(suspendedAtRef.current, now),})suspendedAtRef.current = null- }, [])+ }, [isOffline])const requestForegroundRecovery = useCallback((trigger: CommunityWsLifecycleRecoveryTrigger,forceValidation: boolean,) => {+ if (isOffline()) {+ connectionValidationNeededRef.current = true+ const ws = wsRef.current+ const generation = connectionGenerationRef.current+ if (!ws || !ownsAuthenticatedConnection(ws, generation)) {+ publishConnectionPhase("reconnecting")+ }+ return+ }if (isPageHidden()) {suspendConnection(false)return@@ -548,8 +910,7 @@ export function useUserWs(const recoveryNeeded = forceValidation || connectionValidationNeededRef.currentif (!recoveryNeeded) return- reconnectDelay.current = WS_RECONNECT_INIT- if (tokenAbortRef.current) return+ if (pendingTokenRef.current) returnconst ws = wsRef.currentconst generation = connectionGenerationRef.current@@ -575,14 +936,23 @@ export function useUserWs(reconnectTimerRef.current = null}const readyState = socketReadyState(ws)- retireSocket()+ retireSocket(true, "local-retire")+ if (generation !== connectionGenerationRef.current || isOffline()) returntrackLifecycleRecovery(trigger, "replace", readyState, Date.now())void connectRef.current?.()- }, [retireSocket, suspendConnection, trackLifecycleRecovery, validateCurrentConnection])+ }, [+ isOffline,+ ownsAuthenticatedConnection,+ publishConnectionPhase,+ retireSocket,+ suspendConnection,+ trackLifecycleRecovery,+ validateCurrentConnection,+ ])useEffect(() => {const mountedAt = Date.now()- if (isPageHidden()) suspendedAtRef.current = mountedAt+ if (isPageHidden() || isOffline()) suspendedAtRef.current = mountedAtlastSentinelTickAtRef.current = mountedAtvoid connect()const onVisibilityChange = () => {@@ -604,8 +974,14 @@ export function useUserWs(if (event.target !== window) returnrequestForegroundRecovery("focus", true)}- const onOnline = () => requestForegroundRecovery("online", false)- const onOffline = () => { connectionValidationNeededRef.current = true }+ const onOnline = () => {+ if (!offlineRef.current) return+ offlineRef.current = false+ offlineCleanupAppliedRef.current = false+ connectionValidationNeededRef.current = true+ requestForegroundRecovery("online", true)+ }+ const onOffline = () => suspendForOffline()if (typeof document !== "undefined") {document.addEventListener("visibilitychange", onVisibilityChange)document.addEventListener("freeze", onFreeze)@@ -623,6 +999,7 @@ export function useUserWs(lastSentinelTickAtRef.current = nowif (isPageHidden()+ || isOffline()|| elapsedMs < WS_FOREGROUND_SUSPENSION_GAP_MS) returnrequestForegroundRecovery("sentinel", true)@@ -644,7 +1021,7 @@ export function useUserWs(sentinelIntervalRef.current = null}connectionGenerationRef.current += 1- clearConnectionValidation()+ clearConnectionValidation("aborted")abortPendingToken()if (reconnectTimerRef.current !== null) {clearTimeout(reconnectTimerRef.current)@@ -652,41 +1029,60 @@ export function useUserWs(}if (connectTimeoutRef.current !== null) { clearTimeout(connectTimeoutRef.current); connectTimeoutRef.current = null }stopHeartbeat()- retireSocket(false)+ retireSocket(false, "local-retire")}}, [abortPendingToken,clearConnectionValidation,connect,+ isOffline,requestForegroundRecovery,retireSocket,stopHeartbeat,suspendConnection,+ suspendForOffline,])const send = useCallback((msg: object) => {const ws = wsRef.current- if (ws && ws.readyState === WebSocket.OPEN) {+ if (!isOffline() && ws?.readyState === WebSocket.OPEN) {ws.send(JSON.stringify(msg))}- }, [])+ }, [isOffline])const reconnectNow = useCallback(() => {- clearConnectionValidation()+ clearConnectionValidation("aborted")if (reconnectTimerRef.current !== null) {clearTimeout(reconnectTimerRef.current)reconnectTimerRef.current = null}abortPendingToken()- reconnectDelay.current = WS_RECONNECT_INIT- retireSocket()+ if (isOffline()) {+ connectionValidationNeededRef.current = true+ stopHeartbeat()+ const ws = wsRef.current+ const generation = connectionGenerationRef.current+ publishConnectionPhase(+ ws && ownsAuthenticatedConnection(ws, generation) ? "suspended" : "reconnecting",+ )+ return+ }+ retireSocket(true, "manual-retry")if (isPageHidden() || frozenRef.current) {connectionGenerationRef.current += 1publishConnectionPhase("suspended")return}void connectRef.current?.()- }, [abortPendingToken, clearConnectionValidation, publishConnectionPhase, retireSocket])+ }, [+ abortPendingToken,+ clearConnectionValidation,+ isOffline,+ ownsAuthenticatedConnection,+ publishConnectionPhase,+ retireSocket,+ stopHeartbeat,+ ])return { send, reconnectNow }}diff --git a/src/web/src/test/e2e/ws.test.ts b/src/web/src/test/e2e/ws.test.tsindex 29b3a430a..8640f97fe 100644--- a/src/web/src/test/e2e/ws.test.ts+++ b/src/web/src/test/e2e/ws.test.ts@@ -117,6 +117,24 @@ describe("ws (dev direct to ws-do)", () => {ws.close()})+ it("echoes the exact authenticated connection-validation nonce", async () => {+ if (!available) return++ const ws = await openWs(userId)+ ws.send(JSON.stringify({ type: "auth", token }))+ await waitForMessage<{ type: string }>(ws, (message) => message.type === "auth.ok")++ const nonce = randomUUID()+ const pong = waitForMessage<{ type: string; nonce?: string }>(+ ws,+ (message) => message.type === "connection.pong",+ )+ ws.send(JSON.stringify({ type: "connection.ping", nonce }))++ await expect(pong).resolves.toEqual({ type: "connection.pong", nonce })+ ws.close()+ })+it("closes with 1008 on invalid token", async () => {if (!available) return