Chat can wait forever for the initial history frame (no deadline, no retry)

[clemenshelm]

Symptom

Reported on the production PWA, 2026-07-28. On mobile, several agents were opened one after another; each stayed on the loading indicator indefinitely — no error, no timeout, no retry offered. A reload of the PWA on the desktop was followed immediately by the agents appearing on mobile.

The defect that holds regardless of root cause

The client's wait for initial history has no deadline.

hasInitialContent (use-ws-runtime.ts:498) is what takes the chat out of "starting", and it flips only when a history frame arrives — either with messages or with the authoritative sessionKnown: true empty signal added for #197. Nothing in use-ws-runtime.ts arms a timer for that frame; the timers present (delayTimerRef, ack timers, reconnect backoff) all cover sending, not the initial load.

So if the frame is lost for any reason, the UI parks on the loading indicator forever: no error state, no automatic retry, no user-visible way out except a manual reload. That is a real gap independent of which cause dropped the frame, and it is what turned a transient fault into an indefinite dead end here.

Why "the server just didn't answer" is unlikely

ClientRouter's history path (client-router.ts:956-1058) sends a history frame on every branch:

• messages found → history with messages
• empty but session known → history with sessionKnown: true
• waitForConnection() rejects (10 s, CONNECTION_TIMEOUT_MS) → catch → retry once → history either way
• OpenClaw not connected and session unknown → history with messages: []
• otherwise → greeting

There is no path that returns without answering. So the likelier reading is that the frame never reached the device, or the request never reached the server — not that the server declined to send one.

Candidate causes — none confirmed

1. Dead-but-unreported WebSocket after PWA resume. A backgrounded PWA socket can be torn down by the OS without a close event reaching the page. The client believes it is connected, sends the history request into a void, and — with no deadline — waits forever. The extensive lifecycle handling (visibilitychange, pageshow, freeze, resume, use-ws-runtime.ts:1518-1522) exists precisely for this, so if this is it, the gap is in detection, not in intent.

2. Shared server-side OpenClaw client down. getOpenClawClient() (server/openclaw-client.ts) is a single process-wide instance on globalThis, shared by every user and connection. While it is disconnected, every history request degrades — and when it reconnects, all sessions recover simultaneously. That would explain the "fixed everywhere at once" shape, but not why the desktop reload would be the trigger.

3. Coincidence. The desktop reload may simply have happened around the time the underlying link recovered on its own. Worth stating explicitly: one observation of "I did X, then Y happened" is not causation, and this one has an obvious confound.

Observation 2 vs 3 is decidable from production logs (Pinchy's OpenClaw client connect/disconnect timestamps vs the recovery moment); observation 1 shows up as a browser-side socket with no matching server-side connection. Production has deliberately not been inspected for this report.

Suggested work

• Arm a deadline on the initial history wait and surface a real state when it expires: an error with a Retry, reusing the existing retry affordances rather than inventing a new one. This is the part worth doing whatever the root cause turns out to be.
• Consider an application-level ping/pong or a "history requested but unanswered" watchdog that forces a reconnect, so a silently dead socket self-heals instead of waiting on the user.
• Add an E2E case for "history frame never arrives" — today nothing covers it, since every test's server answers.

Impact

User-visible and confusing: the app looks broken with no explanation and no path forward except knowing to reload. Not a blocker for 0.9.0 — it needs a transient fault to trigger, and reloading recovers it.

Found during 0.9.0 Flow-5 testing.

[clemenshelm]

Root cause confirmed from production logs — it was none of the three candidates above

Read-only inspection of production, 2026-07-28. All 19 Pinchy log lines in the preceding three hours were the same message:

2026-07-28T17:49:35.019Z [ws] rate-limited WebSocket connection for user=… (max concurrent reached)
…
2026-07-28T17:51:04.122Z [ws] rate-limited WebSocket connection for user=… (max concurrent reached)

19 rejections across ~90 seconds (19:49–19:51 local), matching the reported incident exactly, then silence.

The chain

1. ChatSessionMounts (chat-session-mounts.tsx:17) renders every visited session, each as a ChatSessionInstance with its own useWsRuntime — so its own WebSocket. Sockets accumulate per device with each agent or chat visited, not one for the active chat.
2. WsRateLimiter (server/ws-rate-limit.ts:40) allows maxConnectionsPerUser = 10, counted per user across all devices, not per device or per tab.
3. Desktop PWA (several visited agents) plus mobile PWA (several more) crossed 10.
4. Pinchy rejected the mobile upgrades. A rejected connection delivers no history frame.
5. With no deadline on the initial history wait — the defect this issue is about — the mobile UI parked on the loading indicator indefinitely, showing no error.
6. Reloading the desktop PWA tore down its sockets; releaseConnection (server.ts:262, wired via once() to both close and error) freed the slots; the mobile client's next reconnect attempt succeeded and the agents appeared at once.

Corrections to the original report

• The desktop reload really was the cause, not a coincidence. The "worth stating explicitly: one observation is not causation" caveat in the issue body was wrong here — the mechanism is direct, and freeing slots is exactly what a reload does. The reporter's own hypothesis ("does some request not go out?") was right in substance: the request was refused before it could be made.
• Candidates 1 (dead socket after resume), 2 (shared OpenClaw client down) and 3 (coincidence) are all ruled out. The OpenClaw client was never the problem; there were no connect/disconnect events at all in the window.
• The limiter is not leaking connections: release is wired to both close and error through once(), and the rejections stopping on their own confirms slots were returned.

What this issue keeps

The deadline is still the right fix, and this makes the case stronger: the server behaved as designed and rejected an upgrade, yet the user saw an indefinite spinner rather than "too many open connections". Whatever prevents a history frame from arriving, the client must not wait forever — and here it should surface a specific, actionable message.

The limiter sizing itself is tracked separately.