@totalreclaw/totalreclaw 3.3.1-rc.10 → 3.3.1-rc.11

package/CHANGELOG.md

@@ -4,9 +4,54 @@ All notable changes to `@totalreclaw/totalreclaw` (the OpenClaw plugin) are docu
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.3.1-rc.11] — 2026-04-23
+
+OpenClaw-side universal pair reachability — the plugin's `totalreclaw_pair` tool now routes through the relay WebSocket by default, mirroring the Python `2.3.1rc10` pivot on the Hermes side. The URL returned to the user is `https://api-staging.totalreclaw.xyz/pair/p/<token>#pk=<gateway_pubkey>` instead of the previous `http://<gateway-host>:<port>/plugin/totalreclaw/pair/finish?sid=<sid>#pk=…`. Managed hosts, Docker-in-cloud setups, phone-scan-QR flows, and split-network operators can now complete pairing without the browser needing loopback or LAN access to the gateway.
+
+Paired with Hermes Python `2.3.1rc11` — both clients now reach for the relay by default, and `TOTALRECLAW_PAIR_MODE=local` on either side restores the rc.4–rc.10 loopback flow for air-gapped / self-hosted deployments.
+
+### Added
+
+- **`skill/plugin/pair-remote-client.ts`** — new. TypeScript mirror of `python/src/totalreclaw/pair/remote_client.py` (rc.10 Hermes):
+  - `openRemotePairSession({ relayBaseUrl?, pin?, clientId?, mode? })` — generates an ephemeral x25519 keypair via the existing `pair-crypto.ts` module, opens a WebSocket to `/pair/session/open`, sends `{type:"open", gateway_pubkey, pin, client_id, mode}`, and returns a `RemotePairSession` handle containing the user-facing URL (with `#pk=` fragment), PIN, token, expiry, and the live WebSocket.
+  - `awaitPhraseUpload(session, { completePairing, phraseValidator?, timeoutMs? })` — blocks on the kept-open WebSocket until the relay pushes `{type:"forward", client_pubkey, nonce, ciphertext}`. Decrypts locally via `decryptPairingPayload` using the gateway's private key (same ECDH + HKDF + ChaCha20-Poly1305 primitives as rc.10's loopback flow — byte-compatible with Python's `pair.crypto`). Runs the caller-supplied `completePairing` handler and sends `{type:"ack"}` back on success or `{type:"nack", error}` on validator / decrypt / completion failure.
+  - `pairViaRelay(...)` — one-shot convenience wrapper for tests and simple callers.
+- **`ws` runtime dep** (`^8.18.3`) + **`@types/ws`** — pure-JS WebSocket client. Transitive already via `@totalreclaw/core`; rc.11 promotes it to a direct dep so the plugin's own import graph is explicit.
+- **`TOTALRECLAW_PAIR_MODE`** env (plugin side) — mirrors the Python env. Unset or any non-`local` value routes through the relay; `local` preserves the rc.4–rc.10 loopback HTTP server served by `pair-http.ts` (`/plugin/totalreclaw/pair/{finish,start,respond,status}`).
+- **`TOTALRECLAW_PAIR_RELAY_URL`** env (plugin side) — self-hosters can point at their own relay. Defaults to `wss://api-staging.totalreclaw.xyz`.
+- **`skill/plugin/pair-remote-client.test.ts`** — 20 assertions across 5 scenarios: happy-path round-trip, invalid-phrase nack, relay open error, decrypt failure, https-to-wss scheme conversion. Runs against a local `ws` server stub — no network dependency.
+
+### Changed
+
+- **`totalreclaw_pair` tool** now branches on `CONFIG.pairMode`. In relay mode it returns the URL + PIN immediately and schedules a background task that blocks on the WebSocket until the browser completes (or the TTL lapses). Credentials-write happens in that background task via the same `loadCredentialsJson` / `writeCredentialsJson` / `setRecoveryPhraseOverride` / `writeOnboardingState` side-effect chain that the loopback `pair-http.respond` handler uses — so the onboarding-state flip remains identical. Tool payload shape unchanged (`{url, pin, expires_at_ms, qr_ascii, qr_png_b64, qr_unicode, mode}`) except for a new `transport: 'relay' | 'local'` field that tooling (QA harness, telemetry) can use to confirm which path served a given URL.
+
+### Phrase-safety invariants (preserved)
+
+- Relay is blind: the gateway's ephemeral x25519 private key never leaves the plugin host. The relay forwards opaque ciphertext; it cannot derive the symmetric key.
+- PIN is out-of-band: the user reads the PIN from agent chat and types it into the browser. The relay stores the PIN in memory only; logs carry no PIN, no ciphertext, no pubkey, no phrase.
+- Session state is in-memory on the relay with a 5-minute TTL. Redis deferred to Phase 2 per the design blueprint.
+- Backwards-compat: `TOTALRECLAW_PAIR_MODE=local` preserves every bit of the rc.4–rc.10 flow — same loopback HTTP server, same session store, same browser page, same decrypt handler.
+
+### Mechanism / byte-compat
+
+The crypto is a literal TypeScript binding against the same `pair-crypto.ts` module `pair-http.ts` already imports. No new cipher suite, no new wire format — only the transport (WebSocket to relay + relay-served HTML page) differs from the loopback path. A ciphertext produced by the relay-served `pair-html.ts` page decrypts under the same gateway private key using the same `decryptPairingPayload(...)` call path. This is deliberate: `pair-crypto.ts` is the byte-compat anchor shared with Python's `pair.crypto`, and rc.11 extends that anchor to the relay wire.
+
 ## [3.3.1-rc.10] — 2026-04-23
 
-Coordinated version bump with Hermes Python `2.3.1rc10`. rc.10 ships the relay-brokered pair flow — see `python/CHANGELOG.md` (the `2.3.1rc10` entry) for the full design. Plugin code in this release is unchanged from rc.9; the `totalreclaw_pair` pair URL on the OpenClaw plugin side still uses the gateway-loopback HTTP server (the OpenClaw plugin runs in-process alongside a browser on the same host for most deployments, so the loopback URL actually reaches the user). The relay-brokered path is currently Hermes-side only — the OpenClaw plugin can pick it up in a later RC if the same universal-reachability problem starts biting OpenClaw users.
+Coordinated version bump with Hermes Python `2.3.1rc10`. rc.10 ships the relay-brokered pair flow — see `python/CHANGELOG.md` (the `2.3.1rc10` entry) for the full design. The `totalreclaw_pair` pair URL on the OpenClaw plugin side still uses the gateway-loopback HTTP server (the OpenClaw plugin runs in-process alongside a browser on the same host for most deployments, so the loopback URL actually reaches the user). The relay-brokered path is currently Hermes-side only — the OpenClaw plugin can pick it up in a later RC if the same universal-reachability problem starts biting OpenClaw users.
+
+Bundled into rc.10: the previously-parked rc.5 QR display layer from PR #76 (`pair-qr.ts` + `pair-qr.test.ts`, tool-payload `qr_png_b64` + `qr_unicode` fields, `totalreclaw_setup` / `totalreclaw_onboarding_start` stub removal). All rebased onto main via the chore/rc.10-qr-rebase-pr76 branch.
+
+### Added (rebased from PR #76)
+
+- **`skill/plugin/pair-qr.ts`** — new. QR encoder module wrapping `qrcode` (PNG) + `qrcode-terminal` (Unicode block). Same contract as the Python side (`totalreclaw.pair.qr`).
+- **`totalreclaw_pair` tool payload** — the `details` block now carries `qr_png_b64` (base64 PNG for image transports) and `qr_unicode` (terminal block-char string) alongside the existing `qr_ascii`. URL + PIN unchanged.
+- **SKILL.md "Rendering the QR on your transport" section** — per-transport agent rendering guidance (Telegram attachment, terminal inline, web chat `<img>` embed).
+- **`qrcode` + `@types/qrcode`** runtime deps.
+
+### Removed (rc.5 phrase-safety carve-out closure, rebased)
+
+- **`totalreclaw_setup` + `totalreclaw_onboarding_start`** agent tools — both were neutered pointer stubs in rc.4; rc.5 auto-QA flagged them as future-regression surface and their mere presence signalled to agents that "phrase handling happens here". Deleted outright in rc.5, preserved through rc.10. `skill/plugin/phrase-safety-registry.test.ts` now asserts neither name is registered.
 
 Version bump reason: rc cadence keeps Python + plugin aligned so the release-pipeline tracker carries them through QA as one artifact set.
 

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: totalreclaw
 description: "Install + set up TotalReclaw encrypted memory for OpenClaw, then use totalreclaw_remember / totalreclaw_recall. Trigger on 'install TotalReclaw', 'set up TotalReclaw', 'restore my recovery phrase', or any remember / recall request."
-version: 3.3.1-rc.6
+version: 3.3.1-rc.11
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -34,7 +34,7 @@ If the user says "install totalreclaw" (or any variant) AND no `totalreclaw_*` t
 2. Tell the user: *"Plugin installed. Restarting the gateway so the tools bind."* Then ask the user to restart the gateway: `openclaw gateway restart` (native) or `docker restart tr-openclaw` (Docker). The agent-facing shell CANNOT self-restart the gateway it's running inside of — this step has to be a user action. Wait for the user to confirm the restart is done.
 3. After restart: verify `totalreclaw_pair` is now in your toolset. If not, tell the user the restart didn't take effect and to retry the restart command. Do not loop the install.
 4. Check `~/.totalreclaw/credentials.json` (via `test -s ~/.totalreclaw/credentials.json`). If it exists, confirm *"TotalReclaw is already set up."* and stop.
-5. Call `totalreclaw_pair`. Returns `{url, pin, qr_ascii, expires_at_ms}`.
+5. Call `totalreclaw_pair`. Returns `{url, pin, qr_ascii, qr_png_b64, qr_unicode, expires_at_ms}` (see "Rendering the QR on your transport" below for the rc.5+ additions).
 6. Relay verbatim: *"Open <url> in your browser. Enter your 12-word recovery phrase (or let the browser generate one). Confirm PIN <pin>. I'll wait for you to say done."*
 7. After user says done: verify `~/.totalreclaw/credentials.json`. If missing, call `totalreclaw_pair` again (PIN likely expired) and resend.
 8. Confirm: *"TotalReclaw set up ✓. Ask me to remember or recall anything — try `totalreclaw_remember` or ask me to remember something."*
@@ -47,11 +47,23 @@ Used when the user pastes a verbose prompt describing skill install + plugin ins
 
 1. `openclaw plugins install @totalreclaw/totalreclaw` (stable). For RC: `@totalreclaw/totalreclaw@rc`.
 2. Restart gateway so plugin routes + tools bind. Docker: `docker restart tr-openclaw`. Native: `openclaw gateway restart`. Wait ~5s; confirm the gateway is back up. (If you are running inside the gateway, ask the user to run the restart command and wait for confirmation.)
-3. Call `totalreclaw_pair`. Returns `{url, pin, qr_ascii, expires_at_ms}`.
+3. Call `totalreclaw_pair`. Returns `{url, pin, qr_ascii, qr_png_b64, qr_unicode, expires_at_ms}` (see "Rendering the QR on your transport" below for the rc.5+ additions).
 4. Relay to user verbatim: *"Open <url> in your browser. Enter your 12-word recovery phrase (or let the browser generate one). Confirm PIN <pin>. I'll wait for you to say done."*
 5. After user says done: verify `~/.totalreclaw/credentials.json` exists and is non-empty. If missing, call `totalreclaw_pair` again (PIN likely expired) and resend.
 6. Confirm: *"TotalReclaw is set up. Ask me to remember or recall anything."*
 
+## Rendering the QR on your transport (rc.5+)
+
+When you call `totalreclaw_pair` and receive the payload, tell the user: *"Open the URL below or scan this QR code from your phone. PIN: <pin>."*
+
+Then render the QR based on your chat transport:
+
+- **Transport supports image attachments** (Telegram, Slack, web chat, any transport with file/image upload): decode `qr_png_b64` from base64 to bytes, save to a tempfile with a `.png` suffix, and attach the tempfile as an image in your reply. Also show the URL + PIN as text so users who prefer clicking can still do so.
+- **Terminal-only transport** (OpenClaw native CLI chat, bare SSH shell): emit the `qr_unicode` string inline in your reply. It renders as block characters that display correctly in most terminal fonts; the user scans from their phone.
+- **Web chat with inline-image support**: embed as `<img src="data:image/png;base64,<qr_png_b64>" alt="Pair QR">` if the chat client renders HTML; otherwise fall back to attachment.
+
+The QR encodes ONLY the pair URL. The 6-digit PIN is a separate out-of-band confirmation — it is deliberately NOT baked into the QR (dual-channel design: scan + type). Never log, print, or re-emit the PIN outside of the user-facing reply. The PIN is a shared secret between you and the user; it must NOT end up in any other tool call, any log file, or any memory store.
+
 ## Phrase safety (HARD — never break)
 
 NEVER echo / generate / ask the user to paste a recovery phrase in chat. NEVER invoke `openclaw totalreclaw onboard`, `totalreclaw setup`, or any phrase-touching CLI via your shell tool (stdout enters LLM context). The ONLY agent-facilitated setup path is `totalreclaw_pair`. If the user pastes a phrase anyway: tell them it is compromised, call `totalreclaw_pair` with `mode=generate` for a fresh wallet.

package/config.ts

@@ -105,6 +105,21 @@ export const CONFIG = {
   // for 15-min TTL windows; 0600 mode.
   pairSessionsPath: process.env.TOTALRECLAW_PAIR_SESSIONS_PATH || path.join(home, '.totalreclaw', 'pair-sessions.json'),
 
+  // 3.3.1-rc.11 — pair-flow transport selector. Mirrors the Python-side
+  // `TOTALRECLAW_PAIR_MODE` env (rc.10). `'relay'` (default) routes
+  // `totalreclaw_pair` through the universal-reachability WebSocket relay at
+  // `TOTALRECLAW_PAIR_RELAY_URL`. `'local'` preserves the rc.4–rc.10 loopback
+  // HTTP flow (the plugin serves `/plugin/totalreclaw/pair/*` via
+  // `pair-http.ts`). Air-gapped / self-hosted users can pin `'local'` here.
+  pairMode: (() => {
+    const v = (process.env.TOTALRECLAW_PAIR_MODE ?? '').trim().toLowerCase();
+    return v === 'local' ? 'local' : 'relay';
+  })() as 'relay' | 'local',
+  // 3.3.1-rc.11 — relay base URL for the WebSocket-brokered pair flow.
+  // `wss://` preferred; `https://` is rewritten in the remote-client.
+  pairRelayUrl: (process.env.TOTALRECLAW_PAIR_RELAY_URL
+    || 'wss://api-staging.totalreclaw.xyz').replace(/\/+$/, ''),
+
   // Chain — chainId is no longer user-configurable. It is auto-detected from
   // the relay billing response (free = Base Sepolia / 84532, Pro = Gnosis /
   // 100). The default here is used only before the first billing lookup

package/index.ts

@@ -4891,162 +4891,36 @@ const plugin = {
     );
 
     // ---------------------------------------------------------------
-    // Tool: totalreclaw_setup (DEPRECATED in 3.2.0)
+    // Tools: totalreclaw_setup + totalreclaw_onboarding_start —
+    //   REMOVED in 3.3.1-rc.5 (phrase-safety carve-out closure).
     // ---------------------------------------------------------------
     //
-    // Pre-3.2.0 behaviour: auto-generate a mnemonic + return it in the tool
-    // response body so the LLM surfaces it to the user. That path shipped
-    // the recovery phrase to the LLM provider's logs — incompatible with
-    // TotalReclaw's "server cannot read your memories" pitch. 3.2.0
-    // replaces it with a pointer-only stub.
+    // rc.4 left these two registrations in place as *neutered* stubs —
+    // ``totalreclaw_setup`` rejected any ``recovery_phrase`` argument
+    // and returned a CLI-pointer message; ``totalreclaw_onboarding_start``
+    // was already pointer-only. Neither path could leak a phrase in
+    // rc.4, but the rc.4 auto-QA (2026-04-22) flagged them as future-
+    // regression surface: any future patch that re-enables phrase
+    // acceptance (e.g. a flag-driven "power-user" path) would silently
+    // re-open the leak, and their mere presence in the tool registry
+    // keeps signalling to agents that "phrase handling happens here".
     //
-    // Kept registered (rather than deleted) for back-compat — LLMs that
-    // learned the old tool name from training data won't silently succeed
-    // if the user asks them to set up memory. They'll call this tool,
-    // receive a pointer to `openclaw totalreclaw onboard`, and the flow
-    // continues on the user's TTY.
+    // Per ``project_phrase_safety_rule.md`` the ONLY approved agent-
+    // facilitated setup surface is ``totalreclaw_pair`` (browser-side
+    // crypto keeps the phrase out of the LLM round-trip by construction).
+    // rc.5 deletes both registrations outright. The underlying CLI
+    // wizard (``openclaw totalreclaw onboard``) is unchanged — users
+    // run it in their own terminal, outside any agent shell.
     //
-    // The `recovery_phrase` param is kept in the schema so existing tool
-    // calls parse — but ANY phrase the caller passes is rejected, and the
-    // tool NEVER writes credentials.json. All real setup happens in the
-    // CLI wizard.
-    api.registerTool(
-      {
-        name: 'totalreclaw_setup',
-        label: 'TotalReclaw setup (deprecated — redirect to CLI)',
-        description:
-          'DEPRECATED in 3.2.0. This tool no longer accepts recovery phrases or performs ' +
-          'setup. It returns a pointer to `openclaw totalreclaw onboard` — the secure CLI ' +
-          'wizard that runs on the user\'s terminal so the phrase never touches the LLM ' +
-          'provider. Prefer calling `totalreclaw_onboarding_start` for the same pointer.',
-        parameters: {
-          type: 'object',
-          properties: {
-            recovery_phrase: {
-              type: 'string',
-              description:
-                'Legacy parameter — IGNORED in 3.2.0. If provided, the tool returns a ' +
-                'security warning explaining that phrases must never be pasted through ' +
-                'chat. Use the `openclaw totalreclaw onboard` CLI wizard to import an ' +
-                'existing phrase safely.',
-            },
-          },
-          additionalProperties: false,
-        },
-        async execute(_toolCallId: string, params: { recovery_phrase?: string }) {
-          // Phrase-passing is a security boundary violation in 3.2.0. Reject
-          // with a message that explains WHY — the LLM might try again with
-          // a different shape otherwise.
-          if (typeof params?.recovery_phrase === 'string' && params.recovery_phrase.trim().length > 0) {
-            api.logger.warn(
-              'totalreclaw_setup: rejected phrase-passing call (3.2.0 deprecation).',
-            );
-            return {
-              content: [{
-                type: 'text',
-                text:
-                  'For security, TotalReclaw no longer accepts a recovery phrase through ' +
-                  'chat. Pasting a phrase into this tool would ship it to the LLM provider, ' +
-                  'which defeats the whole point of end-to-end encryption.\n\n' +
-                  'Ask the user to open a terminal on their machine and run:\n\n' +
-                  '    openclaw totalreclaw onboard\n\n' +
-                  'The wizard imports an existing phrase via a hidden stdin prompt that ' +
-                  'never touches the LLM, the transcript, or the network.',
-              }],
-            };
-          }
-
-          // No-arg call against an already-active state: confirm + move on.
-          const state = resolveOnboardingState(CREDENTIALS_PATH, CONFIG.onboardingStatePath);
-          if (state.onboardingState === 'active') {
-            return {
-              content: [{
-                type: 'text',
-                text:
-                  'TotalReclaw is already set up and active on this machine. Memory tools ' +
-                  'are unblocked — you can call `totalreclaw_remember` and `totalreclaw_recall` ' +
-                  'directly. If the user wants to rotate phrases, have them delete ' +
-                  '`~/.totalreclaw/credentials.json` and run `openclaw totalreclaw onboard` again.',
-              }],
-            };
-          }
-
-          // Fresh state, no phrase: redirect to the CLI wizard.
-          return {
-            content: [{
-              type: 'text',
-              text:
-                'TotalReclaw setup must run on the user\'s local terminal so the recovery ' +
-                'phrase never touches the LLM. Ask the user to open a terminal and run:\n\n' +
-                '    openclaw totalreclaw onboard\n\n' +
-                'The wizard walks through generate-new-phrase or import-existing-phrase. ' +
-                'After it completes, memory tools become available automatically. See the ' +
-                '`totalreclaw_onboarding_start` tool for the same pointer in a more ' +
-                'discoverable shape.',
-            }],
-          };
-        },
-      },
-      { name: 'totalreclaw_setup' },
-    );
-
-    // ---------------------------------------------------------------
-    // Tool: totalreclaw_onboarding_start (3.2.0 pointer-only tool)
-    // ---------------------------------------------------------------
+    // Audit assertion: ``phrase-safety-registry.test.ts`` asserts
+    // neither name is present in the ``api.registerTool`` call list.
+    // Re-adding either fails CI.
     //
-    // When the user asks the LLM to set up TotalReclaw, this tool directs
-    // them to the CLI wizard. The response body is a non-secret pointer —
-    // it NEVER contains a recovery phrase — so it can safely flow through
-    // the LLM provider and the transcript.
-    api.registerTool(
-      {
-        name: 'totalreclaw_onboarding_start',
-        label: 'TotalReclaw — start onboarding',
-        description:
-          'Call this when the user wants to set up TotalReclaw memory or asks about ' +
-          'enabling memory features. This tool does NOT generate, display, or accept ' +
-          'a recovery phrase — it returns a short pointer that tells the user to run ' +
-          'the onboarding wizard in their local terminal. All phrase handling happens ' +
-          'outside the LLM. If TotalReclaw is already active, the tool returns a ' +
-          'confirmation.',
-        parameters: {
-          type: 'object',
-          properties: {},
-          additionalProperties: false,
-        },
-        async execute() {
-          const state = resolveOnboardingState(CREDENTIALS_PATH, CONFIG.onboardingStatePath);
-          if (state.onboardingState === 'active') {
-            return {
-              content: [{
-                type: 'text',
-                text:
-                  'TotalReclaw is already set up on this machine. Your encryption keys are ' +
-                  'ready — `totalreclaw_remember`, `totalreclaw_recall`, and the other memory ' +
-                  'tools are unblocked. Run `openclaw totalreclaw status` in a terminal for ' +
-                  'more detail.',
-              }],
-            };
-          }
-          return {
-            content: [{
-              type: 'text',
-              text:
-                'TotalReclaw onboarding requires a local terminal so your recovery phrase ' +
-                'never touches the LLM provider. On the same machine as your OpenClaw ' +
-                'gateway, open a terminal and run:\n\n' +
-                '    openclaw totalreclaw onboard\n\n' +
-                'The wizard will ask whether you want to generate a new phrase or import an ' +
-                'existing TotalReclaw phrase. Both paths display/accept the phrase only on ' +
-                'your terminal — nothing crosses the network. After the wizard completes, ' +
-                'come back here and I\'ll be able to use `totalreclaw_remember` and ' +
-                '`totalreclaw_recall`.',
-            }],
-          };
-        },
-      },
-      { name: 'totalreclaw_onboarding_start' },
-    );
+    // Historical tombstone (so LLM-assisted contributors don't re-add
+    // the former shape from training-data memory): rc.4 registered two
+    // tools by the names "totalreclaw_setup" and
+    // "totalreclaw_onboarding_start" as pointer-only stubs. Both were
+    // deleted in rc.5. Do not re-introduce.
 
     // ---------------------------------------------------------------
     // Tool: totalreclaw_onboard — REMOVED in 3.3.1-rc.4 (phrase-safety).
@@ -5122,18 +4996,99 @@ const plugin = {
           const rawMode = params?.mode;
           const mode: 'generate' | 'import' =
             rawMode === 'import' ? 'import' : 'generate';
+          const pairMode = CONFIG.pairMode;
           try {
-            const { createPairSession } = await import('./pair-session-store.js');
-            const { generateGatewayKeypair } = await import('./pair-crypto.js');
+            // 3.3.1-rc.11 — relay-brokered pair by default (universal reachability).
+            // `TOTALRECLAW_PAIR_MODE=local` preserves the rc.4–rc.10 loopback flow
+            // for air-gapped / self-hosted setups. Both paths return the same
+            // tool payload (`{url, pin, expires_at_ms, qr_*, mode, instructions}`);
+            // only the URL origin differs.
+            let url: string;
+            let pin: string;
+            let sidOrToken: string;
+            let expiresAtMs: number;
+            let localSession: import('./pair-session-store.js').PairSession | undefined;
+
+            if (pairMode === 'relay') {
+              const { openRemotePairSession, awaitPhraseUpload } = await import(
+                './pair-remote-client.js'
+              );
+              const remoteSession = await openRemotePairSession({
+                relayBaseUrl: CONFIG.pairRelayUrl,
+                mode: mode === 'generate' ? 'generate' : 'import',
+              });
+              url = remoteSession.url;
+              pin = remoteSession.pin;
+              sidOrToken = remoteSession.token;
+              // Relay sends ISO-8601; convert to ms for tool payload parity.
+              const parsed = Date.parse(remoteSession.expiresAt);
+              expiresAtMs = Number.isFinite(parsed)
+                ? parsed
+                : Date.now() + 5 * 60_000;
+              // Background task — writes credentials.json + flips state when
+              // the browser completes the flow. Tool handler returns
+              // immediately so the agent can tell the user the URL + PIN.
+              void (async () => {
+                try {
+                  await awaitPhraseUpload(remoteSession, {
+                    phraseValidator: (p: string) =>
+                      validateMnemonic(p, wordlist),
+                    completePairing: async ({ mnemonic }) => {
+                      try {
+                        const creds =
+                          loadCredentialsJson(CREDENTIALS_PATH) ?? {};
+                        const next = { ...creds, mnemonic };
+                        if (!writeCredentialsJson(CREDENTIALS_PATH, next)) {
+                          return { state: 'error', error: 'credentials_write_failed' };
+                        }
+                        setRecoveryPhraseOverride(mnemonic);
+                        writeOnboardingState(CONFIG.onboardingStatePath, {
+                          onboardingState: 'active',
+                          createdBy: mode === 'generate' ? 'generate' : 'import',
+                          credentialsCreatedAt: new Date().toISOString(),
+                          version: '3.3.1-rc.11',
+                        });
+                        api.logger.info(
+                          `totalreclaw_pair(relay): session ${remoteSession.token.slice(0, 8)}… completed; credentials written`,
+                        );
+                        return { state: 'active' };
+                      } catch (err: unknown) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        api.logger.error(
+                          `totalreclaw_pair(relay): completePairing failed: ${msg}`,
+                        );
+                        return { state: 'error', error: msg };
+                      }
+                    },
+                  });
+                } catch (bgErr: unknown) {
+                  // Expected on TTL expiry / user-aborts — log at warn, not error.
+                  const bgMsg = bgErr instanceof Error ? bgErr.message : String(bgErr);
+                  api.logger.warn(
+                    `totalreclaw_pair(relay): background task ended for token=${remoteSession.token.slice(0, 8)}…: ${bgMsg}`,
+                  );
+                }
+              })();
+            } else {
+              // Local loopback path (rc.10 behaviour).
+              const { createPairSession } = await import('./pair-session-store.js');
+              const { generateGatewayKeypair } = await import('./pair-crypto.js');
+              const kp = generateGatewayKeypair();
+              const session = await createPairSession(CONFIG.pairSessionsPath, {
+                mode,
+                operatorContext: { channel: 'agent' },
+                rngPrivateKey: () => Buffer.from(kp.skB64, 'base64url'),
+                rngPublicKey: () => Buffer.from(kp.pkB64, 'base64url'),
+              });
+              url = buildPairingUrl(api, session);
+              pin = session.secondaryCode;
+              sidOrToken = session.sid;
+              expiresAtMs = session.expiresAtMs;
+              localSession = session;
+            }
+
+            // QR renderers — same for both modes; input is the URL string.
             const { defaultRenderQr } = await import('./pair-cli.js');
-            const kp = generateGatewayKeypair();
-            const session = await createPairSession(CONFIG.pairSessionsPath, {
-              mode,
-              operatorContext: { channel: 'agent' },
-              rngPrivateKey: () => Buffer.from(kp.skB64, 'base64url'),
-              rngPublicKey: () => Buffer.from(kp.pkB64, 'base64url'),
-            });
-            const url = buildPairingUrl(api, session);
             const qrAscii = await new Promise<string>((resolve) => {
               let settled = false;
               const t = setTimeout(() => {
@@ -5156,16 +5111,40 @@ const plugin = {
                 resolve('');
               }
             });
+
+            // 3.3.1-rc.5 — PNG + Unicode QR for multi-transport rendering.
+            let qrPngB64 = '';
+            let qrUnicode = '';
+            try {
+              const { encodePng, encodeUnicode } = await import('./pair-qr.js');
+              const [pngBuf, uni] = await Promise.all([
+                encodePng(url),
+                encodeUnicode(url),
+              ]);
+              qrPngB64 = pngBuf.toString('base64');
+              qrUnicode = uni;
+            } catch (qrErr: unknown) {
+              api.logger.warn(
+                `totalreclaw_pair: QR encode failed (non-fatal): ${
+                  qrErr instanceof Error ? qrErr.message : String(qrErr)
+                }`,
+              );
+            }
+
             api.logger.info(
-              `totalreclaw_pair: session ${session.sid.slice(0, 8)}… mode=${mode} url=${url}`,
+              `totalreclaw_pair: session ${sidOrToken.slice(0, 8)}… mode=${mode} transport=${pairMode} url=${url} qr_png=${qrPngB64.length} qr_unicode=${qrUnicode.length}`,
             );
+            // Voidly reference localSession so TS does not flag the unused
+            // local-branch binding. Future rc.12 diagnostics can expose
+            // `session.mode` / `session.status` separately.
+            void localSession;
             return {
               content: [{
                 type: 'text',
                 text:
                   `Pairing session started.\n\n` +
                   `URL: ${url}\n\n` +
-                  `PIN (type this into the browser): ${session.secondaryCode}\n\n` +
+                  `PIN (type this into the browser): ${pin}\n\n` +
                   (qrAscii ? `QR code:\n\n${qrAscii}\n\n` : '') +
                   `Instructions for the user:\n` +
                   `1. Open the URL above on their phone or another browser (scan the QR or copy-paste).\n` +
@@ -5179,12 +5158,18 @@ const plugin = {
                   `This session expires in ~5 minutes. Run this tool again if you need a fresh URL.`,
               }],
               details: {
-                sid: session.sid,
+                sid: sidOrToken,
                 url,
-                pin: session.secondaryCode,
+                pin,
                 mode,
-                expires_at_ms: session.expiresAtMs,
+                expires_at_ms: expiresAtMs,
                 qr_ascii: qrAscii,
+                qr_png_b64: qrPngB64,
+                qr_unicode: qrUnicode,
+                // rc.11 — surface the transport so downstream tooling (QA
+                // harness asserters, telemetry) can confirm which path
+                // served the URL. Either 'relay' or 'local'.
+                transport: pairMode,
               },
             };
           } catch (err: unknown) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.1-rc.10",
+  "version": "3.3.1-rc.11",
   "description": "End-to-end encrypted, agent-portable memory for OpenClaw and any LLM-agent runtime. XChaCha20-Poly1305 with protobuf v4 + on-chain Memory Taxonomy v1 (claim / preference / directive / commitment / episode / summary).",
   "type": "module",
   "keywords": [
@@ -31,11 +31,15 @@
   "author": "TotalReclaw Team",
   "license": "MIT",
   "dependencies": {
+    "@huggingface/transformers": "^4.0.1",
     "@totalreclaw/client": "^1.2.0",
     "@totalreclaw/core": "^2.1.1",
-    "@huggingface/transformers": "^4.0.1",
+    "@types/qrcode": "^1.5.6",
+    "@types/ws": "^8.5.12",
     "onnxruntime-node": "^1.24.0",
-    "qrcode-terminal": "^0.12.0"
+    "qrcode": "^1.5.4",
+    "qrcode-terminal": "^0.12.0",
+    "ws": "^8.18.3"
   },
   "files": [
     "*.ts",
@@ -50,7 +54,7 @@
     "skill.json"
   ],
   "scripts": {
-    "test": "npx tsx manifest-shape.test.ts && npx tsx config-schema.test.ts && npx tsx llm-profile-reader.test.ts && npx tsx llm-client.test.ts && npx tsx llm-client-retry.test.ts && npx tsx gateway-url.test.ts && npx tsx retype-setscope.test.ts && npx tsx tool-gating.test.ts && npx tsx onboarding-noninteractive.test.ts && npx tsx pair-cli-json.test.ts && npx tsx qa-bug-report.test.ts && npx tsx nonce-serialization.test.ts && npx tsx phrase-safety-registry.test.ts",
+    "test": "npx tsx manifest-shape.test.ts && npx tsx config-schema.test.ts && npx tsx llm-profile-reader.test.ts && npx tsx llm-client.test.ts && npx tsx llm-client-retry.test.ts && npx tsx gateway-url.test.ts && npx tsx retype-setscope.test.ts && npx tsx tool-gating.test.ts && npx tsx onboarding-noninteractive.test.ts && npx tsx pair-cli-json.test.ts && npx tsx pair-qr.test.ts && npx tsx pair-remote-client.test.ts && npx tsx qa-bug-report.test.ts && npx tsx nonce-serialization.test.ts && npx tsx phrase-safety-registry.test.ts",
     "check-scanner": "node ../scripts/check-scanner.mjs",
     "prepublishOnly": "node ../scripts/check-scanner.mjs"
   },

package/pair-qr.ts

@@ -0,0 +1,152 @@
+/**
+ * pair-qr — QR encoders for the rc.5 pair-tool payload.
+ *
+ * Two helpers that render the pair URL as either a PNG (for
+ * image-capable chat transports like Telegram) or a Unicode block
+ * string (for terminal-only transports like the OpenClaw native CLI).
+ *
+ * Phrase-safety invariant (see
+ * `project_phrase_safety_rule.md` in the internal repo):
+ *   The QR payload is ONLY the pair URL. The 6-digit PIN is a separate
+ *   out-of-band confirmation — it is NEVER baked into the QR. The URL
+ *   itself carries only the session token + gateway ephemeral pubkey
+ *   (fragment-encoded).
+ *
+ * Size profile for a typical ~110-char pair URL:
+ *   - `encodePng` defaults (scale=10, margin=4): ~4 KiB PNG, ~5.5 KiB
+ *     base64. Fits comfortably in a tool-call response.
+ *   - `encodeUnicode` (margin=2): ~1.1 KiB, 23 lines.
+ *
+ * We wrap the `qrcode` npm package (~50 KiB, pure TS, no native
+ * bindings) so neither tsx dev runs nor the published plugin depend on
+ * the bundler understanding CJS vs ESM subpath imports. All we use is
+ * the high-level `toBuffer` / `toString` surface.
+ */
+
+// Lazy import shape — avoids pulling `qrcode` into module load when the
+// tool is never invoked. The `qrcode` types ship with the package but
+// we describe the tiny surface we use here so a future type-drift in
+// upstream doesn't break the build.
+type QrCodeModule = {
+  toBuffer(
+    text: string,
+    options?: { errorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H'; scale?: number; margin?: number },
+  ): Promise<Buffer>;
+  toString(
+    text: string,
+    options?: { type?: 'utf8'; errorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H'; margin?: number },
+  ): Promise<string>;
+};
+
+/**
+ * Error class raised by the rc.5 QR encoders.
+ *
+ * Extends the built-in `Error` so `instanceof Error` checks in callers
+ * keep working.
+ */
+export class QREncodeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'QREncodeError';
+  }
+}
+
+// QR v40 maxes out at ~2953 alphanumeric bytes at ECC-L. We reject
+// payloads over 2 KiB — the pair URL should never approach this. This
+// is defence-in-depth against a caller accidentally feeding a
+// phrase-length blob.
+const MAX_PAYLOAD_BYTES = 2048;
+
+function validatePayload(url: unknown): asserts url is string {
+  if (typeof url !== 'string') {
+    throw new QREncodeError(`url must be a string, got ${typeof url}`);
+  }
+  if (url.length === 0) {
+    throw new QREncodeError('url must not be empty');
+  }
+  const bytes = Buffer.byteLength(url, 'utf-8');
+  if (bytes > MAX_PAYLOAD_BYTES) {
+    throw new QREncodeError(
+      `url too large for QR encoding: ${bytes} bytes (max ${MAX_PAYLOAD_BYTES}). ` +
+        'This limit prevents accidentally encoding phrase-length blobs; a pair ' +
+        'URL should be ~80-150 bytes.',
+    );
+  }
+}
+
+async function loadQrCodeModule(): Promise<QrCodeModule> {
+  const raw = (await import('qrcode' as string)) as unknown as
+    | (QrCodeModule & { default?: QrCodeModule })
+    | { default: QrCodeModule };
+  // qrcode ships CJS; the `default` export contains the surface under
+  // both Node's ESM interop and tsx's loader.
+  const mod = (raw as { default?: QrCodeModule }).default ?? (raw as QrCodeModule);
+  return mod;
+}
+
+export interface EncodePngOptions {
+  /** Error-correction level. Defaults to `'M'` (15%). */
+  ecc?: 'L' | 'M' | 'Q' | 'H';
+  /** Pixels per module. Defaults to 10 → ~300x300 px image. */
+  boxSize?: number;
+  /** Quiet-zone width in modules. Defaults to 4 (QR standard minimum). */
+  border?: number;
+}
+
+export interface EncodeUnicodeOptions {
+  /** Error-correction level. Defaults to `'M'`. */
+  ecc?: 'L' | 'M' | 'Q' | 'H';
+  /** Quiet-zone width in modules. Defaults to 2. */
+  border?: number;
+}
+
+/**
+ * Render `url` as a PNG QR code.
+ *
+ * @throws {QREncodeError} if the URL is empty, non-string, or exceeds
+ *   the 2 KiB safety cap.
+ */
+export async function encodePng(
+  url: string,
+  options: EncodePngOptions = {},
+): Promise<Buffer> {
+  validatePayload(url);
+  const qr = await loadQrCodeModule();
+  try {
+    return await qr.toBuffer(url, {
+      errorCorrectionLevel: options.ecc ?? 'M',
+      scale: Math.max(1, options.boxSize ?? 10),
+      margin: Math.max(0, options.border ?? 4),
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new QREncodeError(`QR encoding failed: ${msg}`);
+  }
+}
+
+/**
+ * Render `url` as a Unicode block QR string (for terminal output).
+ *
+ * Uses half-block glyphs so each character represents two vertical
+ * pixels — the resulting string renders square-ish in terminals with
+ * ~2:1 line-height. Emitted as a single newline-delimited string.
+ *
+ * @throws {QREncodeError} on invalid input.
+ */
+export async function encodeUnicode(
+  url: string,
+  options: EncodeUnicodeOptions = {},
+): Promise<string> {
+  validatePayload(url);
+  const qr = await loadQrCodeModule();
+  try {
+    return await qr.toString(url, {
+      type: 'utf8',
+      errorCorrectionLevel: options.ecc ?? 'M',
+      margin: Math.max(0, options.border ?? 2),
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new QREncodeError(`QR encoding failed: ${msg}`);
+  }
+}

package/pair-remote-client.ts

@@ -0,0 +1,540 @@
+/**
+ * pair-remote-client — gateway-side WebSocket client for the relay-brokered
+ * pair flow (plugin rc.11).
+ *
+ * TypeScript mirror of ``python/src/totalreclaw/pair/remote_client.py``. Wire
+ * formats (WebSocket frame shapes, URL layout, base64url encoding) match the
+ * Python implementation byte-for-byte so either side can open a session that
+ * the relay (`totalreclaw-relay`) + browser page (`pair-html.ts`) already
+ * understand. Crypto primitives come from the shared ``pair-crypto.ts``
+ * module — the same ECDH + HKDF + ChaCha20-Poly1305 stack the loopback HTTP
+ * server uses.
+ *
+ * Flow (this file implements the gateway half):
+ *
+ *   1. Generate an ephemeral x25519 keypair (`generateGatewayKeypair`).
+ *   2. Open a short-lived WebSocket to `wss://<relay>/pair/session/open`.
+ *   3. Send `{type: "open", gateway_pubkey, pin, client_id, mode?}`.
+ *   4. Receive `{type: "opened", token, short_url, expires_at}` — use these
+ *      to build the user-facing pair URL (token + `#pk=<gateway_pubkey>`).
+ *   5. Block on the WebSocket until the relay pushes
+ *      `{type: "forward", client_pubkey, nonce, ciphertext}`.
+ *   6. Decrypt locally via `decryptPairingPayload` using the gateway private
+ *      key. If decrypt succeeds and phrase is valid, call the caller's
+ *      `completePairing` handler (writes credentials.json).
+ *   7. Send `{type: "ack"}` back; close the WebSocket.
+ *
+ * Phrase-safety invariants preserved:
+ *   - Relay sees only ciphertext; it cannot derive the symmetric key without
+ *     the gateway's private key.
+ *   - The gateway pubkey transits the relay as a label in the open frame so
+ *     the relay can display the session, but is ALSO bound into the URL
+ *     fragment the user opens — the fragment never hits the relay.
+ *   - Phrase NEVER enters any logs. PIN is never logged.
+ *   - No relay credentials are required — auth is the single-use PIN +
+ *     5-minute TTL + gateway ECDH private key.
+ *
+ * Scope / scanner surface:
+ *   - NO `fs.*` primitives (delegates credentials writes to the caller via
+ *     `completePairing`). Safe for the check-scanner cross-rule guard.
+ *   - NO env-var reads. Caller passes `relayBaseUrl` explicitly; the plugin
+ *     sources it from the `TOTALRECLAW_PAIR_RELAY_URL` env (via `config.ts`)
+ *     or falls back to the staging default.
+ */
+
+import { randomBytes, randomInt } from 'node:crypto';
+
+import WebSocket from 'ws';
+
+import {
+  decryptPairingPayload,
+  generateGatewayKeypair,
+  type GatewayKeypair,
+} from './pair-crypto.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Default relay endpoint. Caller passes `TOTALRECLAW_PAIR_RELAY_URL` via config. */
+export const DEFAULT_RELAY_URL = 'wss://api-staging.totalreclaw.xyz';
+
+/** WebSocket connect + handshake timeout (ms). */
+const OPEN_TIMEOUT_MS = 10_000;
+
+/** Default blocking-await-for-forward timeout (5 minutes — matches relay TTL). */
+const DEFAULT_AWAIT_TIMEOUT_MS = 5 * 60_000;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Pair mode forwarded in the open frame. Relay uses it to pick the HTML panel. */
+export type PairRelayMode = 'generate' | 'import' | 'either';
+
+/**
+ * Handle returned by `openRemotePairSession`. Carries the user-facing URL
+ * + PIN + keypair + a live WebSocket. The caller normally hands the URL /
+ * PIN to the user via chat, then calls `awaitPhraseUpload(session, ...)` to
+ * block until the browser completes.
+ */
+export interface RemotePairSession {
+  /** User-facing pair URL (https://… plus `#pk=` fragment). */
+  url: string;
+  /** 6-digit PIN the user types into the browser. */
+  pin: string;
+  /** Opaque session token issued by the relay. */
+  token: string;
+  /** ISO-8601 timestamp when the relay will drop the session. */
+  expiresAt: string;
+  /** Ephemeral gateway keypair for this session. `skB64` stays in-process. */
+  keypair: GatewayKeypair;
+  /** Relay mode forwarded in the open frame. */
+  mode: PairRelayMode;
+  /** Live WebSocket. Internal — the caller does not interact with it. */
+  _ws: WebSocket;
+}
+
+/** Outcome of the caller-supplied completion handler. */
+export interface RelayCompletionResult {
+  state: 'active' | 'error';
+  accountId?: string;
+  error?: string;
+}
+
+/**
+ * Completion handler signature. Receives the decrypted recovery phrase as a
+ * plain string + the live session. Expected to write credentials.json + flip
+ * onboarding state. MUST NOT log or return the phrase. The returned
+ * `RelayCompletionResult` decides whether the relay sees `ack` or `nack`.
+ */
+export type RelayCompletePairingHandler = (inputs: {
+  mnemonic: string;
+  session: RemotePairSession;
+}) => Promise<RelayCompletionResult>;
+
+/** Optional phrase validator — caller can pass `validateMnemonic` from `@scure/bip39`. */
+export type PhraseValidator = (phrase: string) => boolean;
+
+/** Default validator — 12 or 24 lowercase ASCII words. Matches pair-http default. */
+function defaultBip39CountValidator(phrase: string): boolean {
+  const words = phrase.split(' ');
+  if (words.length !== 12 && words.length !== 24) return false;
+  return words.every((w) => /^[a-z]+$/.test(w));
+}
+
+/** 6-digit uniform PIN. Uses `node:crypto.randomInt` (cryptographically random). */
+function defaultPin(): string {
+  const n = randomInt(0, 1_000_000);
+  return n.toString(10).padStart(6, '0');
+}
+
+/** Random hex client id. Opaque to the relay. */
+function defaultClientId(): string {
+  return 'gw-' + randomBytes(8).toString('hex');
+}
+
+/**
+ * Assemble the user-facing pair URL. Converts `wss://` → `https://` and
+ * `ws://` → `http://` for the URL the user opens in a browser. The gateway
+ * pubkey lives in the URL fragment so it never hits relay logs.
+ */
+function buildUserUrl(relayBase: string, token: string, pkB64: string): string {
+  let httpBase = relayBase;
+  if (httpBase.startsWith('wss://')) {
+    httpBase = 'https://' + httpBase.slice('wss://'.length);
+  } else if (httpBase.startsWith('ws://')) {
+    httpBase = 'http://' + httpBase.slice('ws://'.length);
+  }
+  return `${httpBase}/pair/p/${token}#pk=${pkB64}`;
+}
+
+/**
+ * Normalise the relay base URL for the WebSocket connect. We always hit
+ * `wss://` for the open-frame WS even if the caller passed an `https://`
+ * browser-facing URL in the config (most self-hosters will pass one URL for
+ * both). Strips trailing slashes.
+ */
+function wsConnectBase(relayBase: string): string {
+  let base = relayBase.replace(/\/+$/, '');
+  if (base.startsWith('https://')) {
+    base = 'wss://' + base.slice('https://'.length);
+  } else if (base.startsWith('http://')) {
+    base = 'ws://' + base.slice('http://'.length);
+  }
+  return base;
+}
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+export interface OpenRemotePairOptions {
+  /** Relay base URL. Defaults to `DEFAULT_RELAY_URL`. */
+  relayBaseUrl?: string;
+  /** Override the auto-generated PIN (tests). */
+  pin?: string;
+  /** Override the auto-generated client id (tests). */
+  clientId?: string;
+  /** Pair mode advertised in the open frame. Defaults to 'either'. */
+  mode?: PairRelayMode;
+  /** Override the random keypair generator (tests). */
+  keypair?: GatewayKeypair;
+  /** Override the WebSocket constructor (tests inject a stub). */
+  webSocketImpl?: typeof WebSocket;
+  /** Override `Date.now` for deterministic expiry strings (tests). */
+  now?: () => number;
+}
+
+export interface AwaitPhraseUploadOptions {
+  /** Completion handler — writes credentials and returns state. */
+  completePairing: RelayCompletePairingHandler;
+  /** Optional phrase validator. Defaults to 12/24-word lowercase-ASCII. */
+  phraseValidator?: PhraseValidator;
+  /** Timeout for the forward frame arrival (ms). Default 5 min. */
+  timeoutMs?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Open
+// ---------------------------------------------------------------------------
+
+/**
+ * Open a pair session on the relay. Returns a handle with the user-facing
+ * URL, 6-digit PIN, expiry, keypair, and a live WebSocket the caller holds
+ * until `awaitPhraseUpload` resolves.
+ *
+ * Throws if the relay responds with `{type: "error"}` or an unexpected frame.
+ */
+export async function openRemotePairSession(
+  opts: OpenRemotePairOptions = {},
+): Promise<RemotePairSession> {
+  const relayBase = (opts.relayBaseUrl ?? DEFAULT_RELAY_URL).replace(/\/+$/, '');
+  const wsBase = wsConnectBase(relayBase);
+  const wsUrl = `${wsBase}/pair/session/open`;
+  const WebSocketImpl = opts.webSocketImpl ?? WebSocket;
+  const keypair = opts.keypair ?? generateGatewayKeypair();
+  const pin = opts.pin ?? defaultPin();
+  const clientId = opts.clientId ?? defaultClientId();
+  const mode: PairRelayMode = opts.mode ?? 'either';
+
+  const ws: WebSocket = new WebSocketImpl(wsUrl, {
+    handshakeTimeout: OPEN_TIMEOUT_MS,
+  });
+
+  // Wait for the WS to open (so `send` doesn't race the handshake).
+  try {
+    await waitOpen(ws, OPEN_TIMEOUT_MS);
+  } catch (err) {
+    safeClose(ws);
+    throw err;
+  }
+
+  // Send the open frame.
+  try {
+    ws.send(
+      JSON.stringify({
+        type: 'open',
+        gateway_pubkey: keypair.pkB64,
+        pin,
+        client_id: clientId,
+        mode,
+      }),
+    );
+  } catch (err) {
+    safeClose(ws);
+    throw err instanceof Error ? err : new Error(String(err));
+  }
+
+  // Wait for the opened frame.
+  let raw: Buffer | ArrayBuffer | string;
+  try {
+    raw = await waitNextMessage(ws, OPEN_TIMEOUT_MS);
+  } catch (err) {
+    safeClose(ws);
+    throw err;
+  }
+
+  let msg: { type?: string; [k: string]: unknown };
+  try {
+    const text = typeof raw === 'string' ? raw : Buffer.from(raw as ArrayBuffer).toString('utf-8');
+    msg = JSON.parse(text);
+  } catch {
+    safeClose(ws);
+    throw new Error('pair-remote-client: opened frame not valid JSON');
+  }
+
+  if (msg.type === 'error') {
+    const errStr = typeof msg.error === 'string' ? msg.error : 'relay_error';
+    safeClose(ws);
+    throw new Error(`pair-remote-client: session/open failed: ${errStr}`);
+  }
+
+  if (msg.type !== 'opened') {
+    safeClose(ws);
+    throw new Error(`pair-remote-client: unexpected response type '${String(msg.type)}'`);
+  }
+
+  const token = typeof msg.token === 'string' ? msg.token : '';
+  const expiresAt = typeof msg.expires_at === 'string' ? msg.expires_at : '';
+  if (!token || !expiresAt) {
+    safeClose(ws);
+    throw new Error('pair-remote-client: opened frame missing token or expires_at');
+  }
+
+  const url = buildUserUrl(relayBase, token, keypair.pkB64);
+
+  return {
+    url,
+    pin,
+    token,
+    expiresAt,
+    keypair,
+    mode,
+    _ws: ws,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Await + decrypt + ack
+// ---------------------------------------------------------------------------
+
+/**
+ * Block on the WebSocket until the relay pushes the encrypted phrase, then
+ * decrypt and invoke `completePairing`. Sends `{type: "ack"}` on success or
+ * `{type: "nack", error: "..."}` on failure, then closes the WebSocket.
+ *
+ * Returns the `RelayCompletionResult` produced by the caller's handler.
+ *
+ * Caller semantics: most plugin callers schedule this as a background task so
+ * the `totalreclaw_pair` tool handler can return the URL + PIN to the agent
+ * immediately, and the phrase-upload wait happens asynchronously while the
+ * agent chats with the user.
+ */
+export async function awaitPhraseUpload(
+  session: RemotePairSession,
+  opts: AwaitPhraseUploadOptions,
+): Promise<RelayCompletionResult> {
+  const validate = opts.phraseValidator ?? defaultBip39CountValidator;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_AWAIT_TIMEOUT_MS;
+  const ws = session._ws;
+
+  let raw: Buffer | ArrayBuffer | string;
+  try {
+    raw = await waitNextMessage(ws, timeoutMs);
+  } catch (err) {
+    safeClose(ws);
+    throw err;
+  }
+
+  let msg: { type?: string; [k: string]: unknown };
+  try {
+    const text = typeof raw === 'string' ? raw : Buffer.from(raw as ArrayBuffer).toString('utf-8');
+    msg = JSON.parse(text);
+  } catch {
+    safeSend(ws, { type: 'nack', error: 'bad_json' });
+    safeClose(ws);
+    throw new Error('pair-remote-client: forward frame not valid JSON');
+  }
+
+  if (msg.type !== 'forward') {
+    safeSend(ws, { type: 'nack', error: 'expected_forward' });
+    safeClose(ws);
+    throw new Error(`pair-remote-client: unexpected frame '${String(msg.type)}'`);
+  }
+
+  const clientPubkey = typeof msg.client_pubkey === 'string' ? msg.client_pubkey : '';
+  const nonce = typeof msg.nonce === 'string' ? msg.nonce : '';
+  const ciphertext = typeof msg.ciphertext === 'string' ? msg.ciphertext : '';
+  if (!clientPubkey || !nonce || !ciphertext) {
+    safeSend(ws, { type: 'nack', error: 'bad_forward_body' });
+    safeClose(ws);
+    throw new Error('pair-remote-client: forward frame missing required fields');
+  }
+
+  // Decrypt locally (ciphertext + shared-secret derivation never leave this host).
+  let plaintext: Buffer;
+  try {
+    plaintext = decryptPairingPayload({
+      skGatewayB64: session.keypair.skB64,
+      pkDeviceB64: clientPubkey,
+      sid: session.token,
+      nonceB64: nonce,
+      ciphertextB64: ciphertext,
+    });
+  } catch (err) {
+    safeSend(ws, { type: 'nack', error: 'decrypt_failed' });
+    safeClose(ws);
+    throw err instanceof Error ? err : new Error(String(err));
+  }
+
+  // Decode + normalize. Match pair-http's BIP-39 norm: NFKC → lowercase → trim → single-space.
+  let mnemonic: string;
+  try {
+    mnemonic = plaintext
+      .toString('utf-8')
+      .normalize('NFKC')
+      .toLowerCase()
+      .trim()
+      .split(/\s+/)
+      .join(' ');
+  } catch (err) {
+    safeSend(ws, { type: 'nack', error: 'bad_utf8' });
+    safeClose(ws);
+    throw err instanceof Error ? err : new Error(String(err));
+  } finally {
+    // Best-effort: scrub the raw plaintext buffer.
+    plaintext.fill(0);
+  }
+
+  if (!validate(mnemonic)) {
+    safeSend(ws, { type: 'nack', error: 'invalid_mnemonic' });
+    safeClose(ws);
+    throw new Error('pair-remote-client: phrase failed BIP-39 validation');
+  }
+
+  // Hand off to the caller-supplied completion handler. Wrapped in try/finally
+  // so we always drop our own reference to the mnemonic.
+  let result: RelayCompletionResult;
+  try {
+    result = await opts.completePairing({ mnemonic, session });
+  } catch (err) {
+    safeSend(ws, { type: 'nack', error: 'completion_failed' });
+    safeClose(ws);
+    throw err instanceof Error ? err : new Error(String(err));
+  } finally {
+    // Drop our reference. JS strings are immutable so we can't zero them;
+    // rebinding at least drops the reference from this closure.
+    mnemonic = '';
+  }
+
+  if (result.state !== 'active') {
+    safeSend(ws, { type: 'nack', error: result.error ?? 'completion_failed' });
+    safeClose(ws);
+    return result;
+  }
+
+  safeSend(ws, { type: 'ack' });
+  safeClose(ws);
+  return result;
+}
+
+/**
+ * One-shot convenience: open session + await phrase upload + run completion.
+ * Tool handlers normally split this into two calls so the agent can tell the
+ * user the URL + PIN before blocking. This helper exists for tests and for
+ * simpler callers.
+ */
+export async function pairViaRelay(opts: {
+  completePairing: RelayCompletePairingHandler;
+  relayBaseUrl?: string;
+  pin?: string;
+  mode?: PairRelayMode;
+  phraseValidator?: PhraseValidator;
+  timeoutMs?: number;
+}): Promise<RelayCompletionResult> {
+  const session = await openRemotePairSession({
+    relayBaseUrl: opts.relayBaseUrl,
+    pin: opts.pin,
+    mode: opts.mode,
+  });
+  return awaitPhraseUpload(session, {
+    completePairing: opts.completePairing,
+    phraseValidator: opts.phraseValidator,
+    timeoutMs: opts.timeoutMs,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// WS helpers
+// ---------------------------------------------------------------------------
+
+function waitOpen(ws: WebSocket, timeoutMs: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (ws.readyState === WebSocket.OPEN) {
+      resolve();
+      return;
+    }
+    const onOpen = (): void => {
+      cleanup();
+      resolve();
+    };
+    const onError = (err: Error): void => {
+      cleanup();
+      reject(err instanceof Error ? err : new Error(String(err)));
+    };
+    const onClose = (code: number): void => {
+      cleanup();
+      reject(new Error(`pair-remote-client: ws closed before open (${code})`));
+    };
+    const timer = setTimeout(() => {
+      cleanup();
+      reject(new Error('pair-remote-client: ws open timeout'));
+    }, timeoutMs);
+    const cleanup = (): void => {
+      clearTimeout(timer);
+      ws.off('open', onOpen);
+      ws.off('error', onError);
+      ws.off('close', onClose);
+    };
+    ws.on('open', onOpen);
+    ws.on('error', onError);
+    ws.on('close', onClose);
+  });
+}
+
+function waitNextMessage(
+  ws: WebSocket,
+  timeoutMs: number,
+): Promise<Buffer | ArrayBuffer | string> {
+  return new Promise((resolve, reject) => {
+    const onMessage = (data: Buffer | ArrayBuffer | string): void => {
+      cleanup();
+      resolve(data);
+    };
+    const onError = (err: Error): void => {
+      cleanup();
+      reject(err instanceof Error ? err : new Error(String(err)));
+    };
+    const onClose = (code: number): void => {
+      cleanup();
+      reject(new Error(`pair-remote-client: ws closed before message (${code})`));
+    };
+    const timer = setTimeout(() => {
+      cleanup();
+      reject(new Error('pair-remote-client: ws message timeout'));
+    }, timeoutMs);
+    const cleanup = (): void => {
+      clearTimeout(timer);
+      ws.off('message', onMessage);
+      ws.off('error', onError);
+      ws.off('close', onClose);
+    };
+    ws.on('message', onMessage);
+    ws.on('error', onError);
+    ws.on('close', onClose);
+  });
+}
+
+function safeSend(ws: WebSocket, msg: unknown): void {
+  try {
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(msg));
+    }
+  } catch {
+    /* swallow */
+  }
+}
+
+function safeClose(ws: WebSocket): void {
+  try {
+    if (
+      ws.readyState === WebSocket.OPEN ||
+      ws.readyState === WebSocket.CONNECTING
+    ) {
+      ws.close();
+    }
+  } catch {
+    /* swallow */
+  }
+}