← Back to PRs

#11868: control-ui: pairing required guided flow (Clairephone V2 Candidate A)

by shojikumaru open 2026-02-08 13:07 View on GitHub →
docs app: web-ui stale
## Summary\nImplements Clairephone Rebuild V2 Candidate A: detect pairing-required WebSocket closes and show a guided, blocking recovery flow in the OpenClaw Control UI.\n\n## Key points\n- Strict detection to avoid false positives: WS close code 1008 + safe sentinel ("pairing required" / "PAIRING_REQUIRED" JSON)\n- Full-screen overlay UX with: Open Tailscale (best-effort), QR, Copy link, Manual steps, Diagnostics\n- Reconnect backoff: 1→2→4→8→15s + jitter; iOS lifecycle throttling when backgrounded; reconnect on resume\n- Safe telemetry/logging: logs close code + mapped category; avoids leaking close reasons\n\n## Tests\n- lint/format\n- UI tests (pnpm -C ui test)\n\n## Notes\nThis is intended for tailnet-only deployments using Tailscale Serve + allowTailscale.\n <!-- greptile_comment --> <h2>Greptile Overview</h2> <h3>Greptile Summary</h3> This PR adds a “connection gate” state to the Control UI so the app can detect a pairing-required WebSocket close (1008 + strict sentinel), display a full-screen blocking overlay with recovery actions (open Tailscale, QR/copy link/manual steps/diagnostics), and improve reconnection behavior with backoff+jitter and iOS lifecycle handling (throttle when hidden, reconnect on resume / online). Core changes are in `ui/src/ui/gateway.ts` (new reconnect controls + `onReconnectScheduled` callback) and `ui/src/ui/app-gateway.ts` / `ui/src/ui/app.ts` (parsing close reasons, surfacing `connectionGate` into view state, and user actions for retry/stop/QR/copy). <h3>Confidence Score: 3/5</h3> - This PR is close to mergeable, but has a couple of lifecycle/reconnect issues that can cause incorrect behavior and lingering event listeners. - Main logic is sound and tests cover the close-reason parsing, but the new global event listeners are not cleaned up on teardown and reconnect scheduling currently doesn’t align with the caller’s special-casing of WS close code 1012, which can lead to unintended reconnect/telemetry behavior. - ui/src/ui/app-gateway.ts, ui/src/ui/gateway.ts <!-- greptile_other_comments_section --> <sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub> <!-- /greptile_comment -->

Most Similar PRs