Summary

• Problem: After rolling back from v2026.5.12 to v2026.5.7 on macOS, a stale CLI-mode client (cli v2026.5.12) continuously reconnects to the gateway producing ~1/sec protocol mismatch spam that persists across gateway restarts and killing visible helper processes
• Why it matters: The log spam makes deep status/audit/probe behavior noisy and confusing; the retrying incompatible client wastes CPU and connection resources; users have no automated way to clean up stale updater processes left behind by update/rollback
• What changed: (1) GatewayClient pauses reconnect on protocol mismatch instead of retrying forever; (2) doctor --fix auto-removes stale ai.openclaw.update.* launchd jobs; (3) server rate-limits repeated protocol mismatches per source IP
• What did NOT change: No changes to gateway protocol negotiation logic, update/rollback mechanism, launchd lifecycle, or existing stale-updater detection surface

Change Type

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes Protocol mismatch spam after rollback: local client still identifies as cli v2026.5.12 against 2026.5.7 gateway #82841
• Related fix(codex): time out silent app-server turns #82142 (user's prior Codex timeout fix)
• This PR fixes a bug or regression

Real behavior proof

• Behavior or issue addressed: Stale client protocol mismatch reconnect loop after rollback
• Real environment tested: Linux (gateway protocol test suite); macOS-specific launchd remediation passes unit tests (launchd stubs)
• Exact steps or command run after this patch:
  • pnpm test src/gateway/reconnect-gating.test.ts — 13/13 pass including PROTOCOL_MISMATCH block
  • pnpm test src/daemon/launchd.test.ts — 59/59 pass
  • pnpm test src/commands/doctor-platform-notes.launchctl-env-overrides.test.ts — 6/6 pass
  • pnpm test src/flows/doctor-health-contributions.test.ts — 16/16 pass
  • pnpm test src/cli/daemon-cli/status.gather.test.ts src/cli/daemon-cli/status.print.test.ts — 27/27 pass
  • pnpm test src/gateway/protocol/ — 87/87 pass
• Evidence after fix: All 140+ relevant tests pass
• Observed result after fix: GatewayClient pauses reconnect on PROTOCOL_MISMATCH instead of looping; doctor --fix removes stale updater launchd jobs; server suppresses logs after 5 identical mismatches per IP per minute
• What was not tested: Live macOS rollback reproduction (requires macOS host with launchd)

Root Cause

• Root cause: GatewayClient.shouldPauseReconnectAfterAuthFailure() did not list PROTOCOL_MISMATCH as a pause-eligible detail code, so any client receiving a protocol mismatch error would retry indefinitely (exponential backoff 1s→30s, never stopping)
• Missing detection / guardrail: No auto-remediation path in doctor for stale ai.openclaw.update.* launchd jobs — only detection/reporting existed
• Contributing context: The stale client process from v2026.5.12 survived rollback; without the pause-on-mismatch fix, it kept reconnecting and producing log spam

Regression Test Plan

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/gateway/reconnect-gating.test.ts — isNonRecoverableAuthError block test for PROTOCOL_MISMATCH
• Scenario the test should lock in: A protocol mismatch error causes the client to pause reconnection (non-recoverable auth error)
• Why this is the smallest reliable guardrail: Single pure function test covering the gateway-client decision point
• Existing test that already covers this (if any): Similar tests exist for all other auth error detail codes
• If no new test is added, why not: N/A — test was added

User-visible / Behavior Changes

• Gateway clients from incompatible versions stop retrying after one protocol mismatch (no more endless log spam)
• openclaw doctor --fix on macOS now auto-removes stale ai.openclaw.update.* launchd jobs instead of only reporting them
• Gateway suppresses repeated protocol mismatch log lines from the same IP after 5 occurrences per minute (silent close)

Diagram

Before:
client v2026.5.12 → connect → server v2026.5.7 → protocol mismatch → close(1002)
                                                                    → client scheduleReconnect() → connect → (loop forever)
After (Phase 1):
client v2026.5.12 → connect → server v2026.5.7 → protocol mismatch → close(1002, code:PROTOCOL_MISMATCH)
                                                                    → client shouldPauseReconnect=true → STOP
After (Phase 3):
... → protocol mismatch x5 from same IP/60s → silent close (no log, no error frame)
Security Impact
- 
New permissions/capabilities? No
- 
Secrets/tokens handling changed? No
- 
New/changed network calls? No
- 
Command/tool execution surface changed? No
- 
Data access scope changed? No
Compatibility / Migration
- 
Backward compatible? Yes
- 
Config/env changes? No
- 
Migration needed? No
Risks and Mitigations
- 
Risk: doctor --fix removes a running updater job mid-update
- 
Mitigation: The function only runs during doctor --fix with explicit user opt-in; updater jobs are short-lived by design and removal is safe once the user has confirmed no update is running (already documented in existing guidance)
- 
Risk: Rate limiter could suppress legitimate rapid reconnects from different clients behind the same NAT IP
- 
Mitigation: Threshold is 5/60s — legitimate clients would succeed on first attempt and never hit the protocol mismatch path