fix(gateway): stop flagging RPC timeouts while gateway is starting/restarting

[hazeone]

Problem

On Windows + ClawX 0.3.10, many users see a persistent red banner on the Channels page:

网关状态异常 · 最近的网关 RPC 调用发生超时

This analysis of user-submitted logs (captured spawnToReadyMs of 50–130 seconds on Windows) showed the banner is not a single bug, but the product of several Windows-specific lifecycle choices combining against a UI judgement with no cooldown:

1. Cold-start dwarfs RPC timeouts. On Windows, Gateway bootstrap (uv python download, Defender scans, bonjour probing, model-pricing fetch, plugin init) routinely takes 30 s to 2 min. The first channels.status (5–8 s timeout) and chat.history (30–35 s timeout) fire long before the gateway is actually ready, rejecting with Gateway not connected / Gateway stopped / RPC timeout.
2. Windows reload is forced into restart. SIGUSR1 is not supported, so every provider + channel save triggers a full cold-start, cascading the previous problem.
3. Windows heartbeat recovery was disabled outright. Once the Gateway deadlocked (Defender / plugin / IO stall), the manager logged Gateway heartbeat recovery skipped (platform=win32) and did nothing until the user manually clicked "重启网关".
4. Handshake / challenge ceilings were platform-agnostic (10 s / 20 s). On Windows those were shorter than real cold-starts, producing a false Connect handshake timeout, which startup-orchestrator treated as a transient error and retried up to 3× — stacking another >1 min of delay.
5. Health judgement was too hot. consecutiveRpcFailures > 0 → rpc_timeout reason without any cooldown. A single transport failure while the gateway was still booting stuck the banner until the next successful RPC.
6. Channels page re-fired 5 refresh ticks on page load (1.2 / 2.6 / 4.5 / 7 / 10.5 s), compounding the counter during cold-start.

Log evidence (abridged, from attached session transcripts):

[metric] gateway.startup { spawnToReadyMs: 128245, totalMs: 128866 }
[channels.accounts] channels.status probe=0 failed after 8013ms
[gateway:rpc] chat.history failed (timeoutMs=35000): Error: Gateway stopped
[ERROR] Gateway connect handshake timed out
[WARN ] Transient start error: Error: Connect handshake timeout. Retrying... (1/3)
Gateway heartbeat: 5 consecutive pong misses … autoReconnect=true
Gateway heartbeat recovery skipped (platform=win32)

Fix

electron/gateway/manager.ts

• isTransportRpcFailure() narrowed to only "RPC timeout:". Gateway not connected / Gateway stopped / send failures are expected during lifecycle transitions and are already surfaced via status.state (gateway_not_running / gateway_error reasons).
• recordRpcFailure() gates incrementing consecutiveRpcFailures on status.state === 'running', gatewayReady === true, AND 45 s elapsed since connectedAt — matching the renderer-side chat.history startup retry window.
• recordRpcSuccess() now infers gatewayReady = true on the first successful RPC, so builds that never emit (or emit too-early) gateway.ready no longer wait on the 30 s fallback.
• Windows heartbeat recovery is re-enabled but behind a 5-minute silence guard (WINDOWS_RECOVERY_SILENCE_MS). Short Defender-induced blips (which emit another message within a minute or two) keep the existing deferral; genuine deadlocks now self-heal after 5 min.

electron/gateway/ws-client.ts

• New GATEWAY_CHALLENGE_TIMEOUT_MS_WIN = 30_000 and GATEWAY_CONNECT_HANDSHAKE_TIMEOUT_MS_WIN = 45_000, selected automatically via getPlatformChallenge/ConnectHandshakeTimeoutMs() based on the caller's platform. Linux / macOS retain the stricter 10 s / 20 s defaults.
• Prevents the retry loop that previously stacked three 20 s handshake-timeout failures on top of a legitimate Windows cold-start.

electron/api/routes/channels.ts

• buildChannelAccountsView() short-circuits the runtime channels.status RPC unless the gateway is truly running && gatewayReady. Startup renders now rely on the config view (already fully populated) instead of firing requests that are guaranteed to fail.
• Channel save debounce raised from 150 ms → 2000 ms (CHANNEL_SAVE_RESTART_DEBOUNCE_MS). A typical provider + channel setup flow (which can trigger 3–5 saves within 1 s of each other) now coalesces into a single Gateway restart instead of stacking several cold-starts on Windows.

electron/main/ipc-handlers.ts

• Same 2000 ms debounce applied to the legacy IPC code path that also drives channel-save refreshes.

src/pages/Channels/index.tsx

• scheduleConvergenceRefresh() timers re-read the live gateway status before firing. Ticks are skipped (with a clear info log) while the gateway is not yet running + gatewayReady.
• Added a second trigger so that when gatewayReady flips true while status.state is already 'running', the page re-fetches runtime data and re-schedules convergence. This covers the case where a page loaded during 'starting' and transitioned via gateway.ready without ever changing status.state.

Non-fix decisions documented

• UtilityProcess IPC reload (PLAN item Dev #4): declined after code audit of node_modules/openclaw/dist. OpenClaw only handles reload via in-process SIGUSR1 (process.listenerCount('SIGUSR1') > 0 ? emit : kill) and does not listen for parent process.on('message') IPC. There is no gateway.reload / admin.reload RPC; secrets.reload and config.apply both funnel back into the same SIGUSR1 path. Even if implemented, the SIGUSR1 in-process reload re-runs the same plugin/bonjour/model-pricing init that causes the cost we see anyway. The debounce bump from 150 ms → 2 s (above) captures the much larger win — one restart per typical setup flow instead of 3-5.

Tests

• tests/unit/gateway-manager-diagnostics.test.ts (now 6 tests):
  • new: RPC timeout during state: 'starting' does NOT pollute consecutiveRpcFailures / rpc_timeout reason.
  • new: RPC timeout within the 45 s post-connect grace window does NOT count.
  • new: First successful RPC flips gatewayReady = true.
  • Existing cases updated to set connectedAt / gatewayReady so recordRpcFailure still fires where intended.
• tests/unit/gateway-manager-heartbeat.test.ts (now 5 tests):
  • Windows case split into "deferred while <5 min silence guard" + "fires after prolonged silence".
• tests/unit/gateway-ws-client.test.ts (now 12 tests):
  • new: getPlatformChallenge/ConnectHandshakeTimeoutMs returns the Windows constants on win32 and defaults elsewhere.
  • new: A win32 handshake still succeeds after advancing past the non-windows default (+5 s) because the Windows ceiling is in effect.
• tests/unit/channel-routes.test.ts:
  • 25 getStatus mocks extended with gatewayReady: true so channels.status still dispatches in tests.

Verification

Check	Result
pnpm test	84 files, 542 tests passed
pnpm typecheck	clean
pnpm run lint	clean
pnpm run comms:replay + comms:compare	all metrics PASS (rpc_timeout_rate, duplicate_event_rate, event_fanout_ratio, history_inflight_max, rpc_p95_ms 0% delta vs baseline)

Notes for reviewers

• No change to the banner UI itself or to user-facing copy.
• The startup-grace change intentionally keeps lastRpcFailureAt / lastRpcFailureMethod diagnostics populated for debugging — only the health summary is gated.
• No renderer-side change needed for history path: src/stores/chat/history-startup-retry.ts already classifies these failures and retries for up to ~45 s, so timeouts that used to poison the banner now retry transparently.