#11868: control-ui: pairing required guided flow (Clairephone V2 Candidate A)
docs
app: web-ui
stale
Cluster:
Device Pairing and Gateway Fixes
## 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
#23678: fix(ui): Control UI shows no guidance on 1008 pairing required (#23...
by yinghaosang · 2026-02-22
80.3%
#9218: Fix Control UI chat resync on gaps and terminal events
by figitaki · 2026-02-05
79.1%
#20456: fix(control-ui): show device pairing approval prompt when a new dev...
by mmaghsoodnia · 2026-02-18
77.9%
#13321: android/gateway: harden manual connect identity and A2UI UX
by m888m · 2026-02-10
76.4%
#13902: fix: auto-recover on event gap instead of showing error
by nikogamulin · 2026-02-11
75.5%
#21148: fix(gateway): add request-aware pairing recovery hints and docs
by cluster2600 · 2026-02-19
75.2%
#6846: fix: bridge node.pair.* tools to device pairing store
by cortexuvula · 2026-02-02
75.0%
#12168: feat: integrate Mission Control dashboard into Control UI
by riftagent-git · 2026-02-08
74.8%
#20089: fix(gateway): preserve control-ui scopes when dangerouslyDisableDev...
by vashkartik · 2026-02-18
74.6%
#11527: feat(control-ui): UX improvements — Enter key, thinking icon, auto-...
by Annaxiebot · 2026-02-07
74.3%