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

package/CHANGELOG.md

@@ -4,9 +4,85 @@ 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.12] — 2026-04-23
+
+**Ship-stopper fix for rc.11.** The relay-served pair page's submit
+button threw `NotSupportedError: Failed to execute 'importKey' on
+'SubtleCrypto': Algorithm: Unrecognized name` when the user clicked
+"Seal key and finish". Root cause: `ChaCha20-Poly1305` is NOT
+implemented in the Web Crypto API of Chrome / Safari / Edge — the
+spec exposes `AES-GCM` as the only AEAD. rc.10/rc.11 never worked
+end-to-end for any user; every pair attempt failed silently and the
+token expired without logging a failure — GH issue #79.
+
+rc.12 swaps the cipher suite from ChaCha20-Poly1305 to AES-256-GCM on
+both sides (browser + gateway). Wire shape unchanged — still 12-byte
+nonce, 16-byte tag, sid-bound AAD, base64url encoding. HKDF info bumped
+from `totalreclaw-pair-v1` to `totalreclaw-pair-v2` so rc.11 ciphertexts
+cannot collide with rc.12 keys (fail-closed on any version skew).
+
+### Changed
+- `skill/plugin/pair-crypto.ts`: `aeadDecrypt` / `aeadEncryptWithSessionKey`
+  switched from `chacha20-poly1305` to `aes-256-gcm`. `HKDF_INFO` bumped
+  to `totalreclaw-pair-v2`.
+- `skill/plugin/pair-page.ts` (local-mode pair page): WebCrypto
+  `ChaCha20-Poly1305` calls swapped to `AES-GCM`. Capability probe
+  function renamed `chaChaSupported` → `aesGcmSupported`.
+
+### Observability
+- The relay's `pair-html.ts` (user-facing page) now reports phase-labelled
+  error messages so a network / encrypt / submit failure no longer masks
+  as a silent "stuck on acknowledge screen". Relay PR (fix/pair-aes-gcm-rc12)
+  is the canonical fix for the issue reported in #79.
+
+## [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.12",
   "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"
   },