fix: recover Control UI access after device-auth upgrades (#118231)

* fix: recover Control UI pairing from dashboard

* test: prove dashboard credential rotation

* test: complete gateway auth generation fixture

* test: restore QR device token verifier

* fix: preserve headless dashboard recovery

docs/cli/dashboard.md

@@ -1,14 +1,16 @@
 ---
-summary: "CLI reference for `openclaw dashboard` (open the Control UI)"
+summary: "CLI reference for `openclaw dashboard` (securely open the Control UI)"
 read_when:
-  - You want to open the Control UI with your current token
+  - You want to open or re-pair the Control UI from the Gateway host
   - You want to print the URL without launching a browser
 title: "Dashboard"
 ---
 
 # `openclaw dashboard`
 
-Open the Control UI using your current auth.
+Open the Control UI with a short-lived, one-time browser pairing link. A successful handoff leaves
+that browser with its own durable device credential, so reopening the dashboard does not depend on
+the shared Gateway token.
 
 ```bash
 openclaw dashboard
@@ -29,17 +31,28 @@ Use `--json` for desktop integrations and scripts that need the resolved Control
 openclaw dashboard --json
 ```
 
-The response includes `url`, `httpUrl`, `wsUrl`, `port`, and `tokenIncluded`. If the Gateway is not ready, the command returns `{"ok":false,"reason":"..."}` and exits non-zero. SecretRef-managed tokens are never included in `url`.
+The response includes the backward-compatible shared-auth `url`, plus `browserUrl`,
+`browserBootstrapExpiresAtMs`, `httpUrl`, `wsUrl`, `port`, and `tokenIncluded`. Browser integrations
+should open `browserUrl`; native RPC clients that need the shared Gateway credential can continue to
+use `url`. If the Gateway is not ready or a browser handoff cannot be issued, the command returns
+`{"ok":false,"reason":"..."}` and exits non-zero. SecretRef-managed shared tokens are never included
+in `url`.
 
 Notes:
 
 - Resolves configured `gateway.auth.token` SecretRefs when possible.
+- `browserUrl` carries a single-use, ten-minute bootstrap in the URL fragment. The Control UI strips
+  it immediately, binds it to the browser's signed device identity, and stores only the resulting
+  per-device credential.
 - Follows `gateway.tls.enabled`: TLS-enabled gateways print/open `https://` Control UI URLs and connect over `wss://`.
 - For `lan` or a wildcard `custom` bind, same-host launches always use loopback because a wildcard is not a browser destination. Plaintext `tailnet` and `custom` binds also use `127.0.0.1` so the browser has a secure context; TLS-enabled specific hosts keep the configured address so certificate names match.
 - Before delivering an authenticated loopback URL for a specific-interface bind, the command probes the configured interface and verifies that it and `127.0.0.1` are owned by the same Gateway process. Ambiguous listener ownership fails closed with status guidance.
-- For SecretRef-managed tokens (resolved or unresolved), the printed/copied/opened URL never includes the token, so external secrets do not leak into terminal output, clipboard history, or browser-launch arguments.
-- If `gateway.auth.token` is SecretRef-managed but unresolved, the command prints a non-tokenized URL and remediation guidance instead of an invalid token placeholder.
+- The interactive command prints only the clean base URL; the clipboard/browser launch receives the
+  one-time `browserUrl`, never the shared token. SecretRef-managed shared tokens therefore do not leak
+  into terminal output, clipboard history, or browser-launch arguments.
 - If clipboard/browser delivery fails for a token-authenticated URL, the command logs a safe manual-auth hint naming `OPENCLAW_GATEWAY_TOKEN`, `gateway.auth.token`, and the URL fragment key `token`, without printing the token value.
+- If the shared token cannot be placed in a URL and clipboard/browser delivery fails, run
+  `openclaw dashboard --json` and open its short-lived `browserUrl` within ten minutes.
 
 ## Related