@totalreclaw/totalreclaw 3.2.3 → 3.3.0-rc.1

package/README.md

@@ -96,7 +96,36 @@ openclaw plugins install @totalreclaw/totalreclaw
 
 ### 2. Configure
 
-Set one environment variable:
+You have three ways to set up TotalReclaw, depending on where your OpenClaw gateway runs.
+
+**Local gateway (laptop / workstation):** run the CLI wizard on the same machine:
+
+```bash
+openclaw totalreclaw onboard
+```
+
+The wizard generates or accepts a 12-word BIP-39 TotalReclaw account key directly on your terminal. The phrase never touches the LLM, the chat transcript, or the network -- it's written straight to `~/.totalreclaw/credentials.json` (mode 0600).
+
+**Remote gateway (VPS, home server, shared / team):** use QR-pairing (new in v3.3.0).
+
+On the gateway host:
+
+```bash
+openclaw totalreclaw pair           # generate a new account key
+openclaw totalreclaw pair import    # import an existing TotalReclaw key
+```
+
+You'll see a QR code, a 6-digit secondary code, and a URL. Scan the QR with your phone's camera or open the URL on any modern browser. The browser page:
+
+1. Asks you to enter the 6-digit code (prevents a bystander from hijacking the session).
+2. Generates or accepts your 12-word account key in-page.
+3. Encrypts it end-to-end (x25519 + ChaCha20-Poly1305, key derived from a DH shared secret the relay never sees) and delivers it to your gateway.
+
+The phrase never enters the LLM, the chat transcript, or the relay server in plaintext. The pairing URL embeds the gateway's ephemeral public key in the URL fragment -- this is TLS-MITM resistant and invisible to any server on the path. See `CHANGELOG.md` §3.3.0 for the full threat model.
+
+Browser support: Safari 17+, Chrome 123+, Firefox 130+ (these ship WebCrypto x25519 + ChaCha20-Poly1305).
+
+**Legacy / self-hosted:** set the env var directly (useful for containers / CI):
 
 ```bash
 export TOTALRECLAW_RECOVERY_PHRASE="your twelve word recovery phrase here"
@@ -104,7 +133,7 @@ export TOTALRECLAW_RECOVERY_PHRASE="your twelve word recovery phrase here"
 
 **That's it.** v1 is the default extraction and write path. Extraction cadence, importance floor, candidate pool size, and dedup thresholds are all server-tuned via the relay's billing response -- no client env vars to set. See [env vars reference](../../docs/guides/env-vars-reference.md).
 
-For self-hosted deployments:
+For self-hosted relays:
 
 ```bash
 export TOTALRECLAW_SERVER_URL="http://your-totalreclaw-server:8080"

package/config.ts

@@ -99,6 +99,11 @@ export const CONFIG = {
   // never contains secrets. Loaded on every plugin init + on every
   // before_tool_call gate check.
   onboardingStatePath: process.env.TOTALRECLAW_STATE_PATH || path.join(home, '.totalreclaw', 'state.json'),
+  // 3.3.0 QR-pairing session store. Separate file from both credentials.json
+  // and state.json so the session-store module does not have to touch either
+  // (keeps scanner surface isolated). Contains ephemeral x25519 secret keys
+  // for 15-min TTL windows; 0600 mode.
+  pairSessionsPath: process.env.TOTALRECLAW_PAIR_SESSIONS_PATH || path.join(home, '.totalreclaw', 'pair-sessions.json'),
 
   // Chain — chainId is no longer user-configurable. It is auto-detected from
   // the relay billing response (free = Base Sepolia / 84532, Pro = Gnosis /

package/index.ts

@@ -204,6 +204,16 @@ interface OpenClawPluginApi {
       config?: unknown;
     }) => { text: string } | Promise<{ text: string }>;
   }): void;
+  /**
+   * 3.3.0 — register an HTTP route on the gateway's HTTP server.
+   * Used by the QR-pairing flow to serve the pairing page + the
+   * encrypted-payload respond endpoint. Path is exact-match against
+   * `new URL(req.url, ...).pathname`; no params supported.
+   */
+  registerHttpRoute?(params: {
+    path: string;
+    handler: (req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => Promise<void> | void;
+  }): void;
 }
 
 // ---------------------------------------------------------------------------
@@ -245,6 +255,70 @@ function humanizeError(rawMessage: string): string {
 /** Path where we persist userId + salt across restarts. */
 const CREDENTIALS_PATH = CONFIG.credentialsPath;
 
+// ---------------------------------------------------------------------------
+// 3.3.0 — pairing URL resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the full pairing URL (including `#pk=` fragment) for a fresh
+ * pairing session. Pulls gateway config from `api.config.gateway`.
+ *
+ * Resolution order (mirrors the device-pair extension):
+ *   1. pluginConfig.publicUrl (if the operator set it explicitly)
+ *   2. gateway.remote.url (if the gateway is marked remote)
+ *   3. gateway.bind=custom + customBindHost + port
+ *   4. gateway.bind=tailnet/lan is acknowledged but we do NOT probe
+ *      the host here (network calls); we fall back to localhost with
+ *      a warning log.
+ *   5. gateway.port default = 18789 + localhost.
+ *
+ * Always returns a working URL string; never throws. The caller can
+ * log a warning if the URL is localhost and the gateway is remote,
+ * but the CLI always prints whatever we give it.
+ */
+function buildPairingUrl(
+  api: Pick<OpenClawPluginApi, 'config' | 'pluginConfig' | 'logger'>,
+  session: { sid: string; pkGatewayB64: string },
+): string {
+  const cfg = api.config as {
+    gateway?: {
+      port?: number;
+      bind?: string;
+      customBindHost?: string;
+      tls?: { enabled?: boolean };
+      remote?: { url?: string };
+    };
+  } | undefined;
+  const pluginCfg = (api.pluginConfig ?? {}) as { publicUrl?: string };
+
+  const tlsEnabled = cfg?.gateway?.tls?.enabled === true;
+  const scheme = tlsEnabled ? 'https' : 'http';
+  const port = cfg?.gateway?.port ?? 18789;
+
+  let base: string;
+  if (typeof pluginCfg.publicUrl === 'string' && pluginCfg.publicUrl.trim()) {
+    base = pluginCfg.publicUrl.replace(/\/+$/, '');
+    // If the user gave us a ws:// URL, rewrite to http(s)://
+    base = base.replace(/^wss:\/\//i, 'https://').replace(/^ws:\/\//i, 'http://');
+  } else if (typeof cfg?.gateway?.remote?.url === 'string' && cfg.gateway.remote.url.trim()) {
+    base = cfg.gateway.remote.url.trim().replace(/\/+$/, '');
+    base = base.replace(/^wss:\/\//i, 'https://').replace(/^ws:\/\//i, 'http://');
+  } else if (cfg?.gateway?.bind === 'custom' && cfg.gateway.customBindHost) {
+    base = `${scheme}://${cfg.gateway.customBindHost}:${port}`;
+  } else {
+    const bind = cfg?.gateway?.bind;
+    if (bind === 'lan' || bind === 'tailnet') {
+      api.logger.warn(
+        `TotalReclaw: pairing URL is falling back to localhost because gateway.bind=${bind} without explicit host probe. ` +
+          'Set plugins.entries.totalreclaw.config.publicUrl to override.',
+      );
+    }
+    base = `${scheme}://localhost:${port}`;
+  }
+
+  return `${base}/plugin/totalreclaw/pair/finish?sid=${encodeURIComponent(session.sid)}#pk=${encodeURIComponent(session.pkGatewayB64)}`;
+}
+
 // ---------------------------------------------------------------------------
 // Cosine similarity threshold — skip injection when top result is below this
 // ---------------------------------------------------------------------------
@@ -2557,6 +2631,14 @@ const plugin = {
             statePath: CONFIG.onboardingStatePath,
             logger: api.logger,
           });
+          // 3.3.0 — `openclaw totalreclaw pair [generate|import]` attaches
+          // alongside the existing `onboard` + `status` subcommands.
+          const { registerPairCli } = await import('./pair-cli.js');
+          registerPairCli(program as import('commander').Command, {
+            sessionsPath: CONFIG.pairSessionsPath,
+            renderPairingUrl: (session) => buildPairingUrl(api, session),
+            logger: api.logger,
+          });
         },
         { commands: ['totalreclaw'] },
       );
@@ -2567,6 +2649,69 @@ const plugin = {
       );
     }
 
+    // ---------------------------------------------------------------
+    // 3.3.0 — HTTP routes for QR-pairing (pair-http)
+    // ---------------------------------------------------------------
+    //
+    // Four endpoints under /plugin/totalreclaw/pair/ are registered on
+    // the gateway's HTTP server. Collectively they serve the browser
+    // pairing page, verify the 6-digit secondary code, accept the
+    // encrypted mnemonic payload, and expose a status polled by the
+    // CLI. See pair-http.ts and the 2026-04-20 design doc.
+    if (typeof api.registerHttpRoute === 'function') {
+      (async () => {
+        try {
+          const { buildPairRoutes } = await import('./pair-http.js');
+          const { validateMnemonic } = await import('@scure/bip39');
+          const { wordlist } = await import('@scure/bip39/wordlists/english.js');
+          const bundle = buildPairRoutes({
+            sessionsPath: CONFIG.pairSessionsPath,
+            apiBase: '/plugin/totalreclaw/pair',
+            logger: api.logger,
+            validateMnemonic: (p) => validateMnemonic(p, wordlist),
+            completePairing: async ({ mnemonic }) => {
+              // Write credentials.json + flip state to 'active' via
+              // fs-helpers. This centralizes disk I/O off the
+              // pair-http surface (scanner isolation).
+              const creds = loadCredentialsJson(CREDENTIALS_PATH) ?? {};
+              const next = { ...creds, mnemonic };
+              if (!writeCredentialsJson(CREDENTIALS_PATH, next)) {
+                return { state: 'error', error: 'credentials_write_failed' };
+              }
+              // Hot-reload: update the runtime override so existing
+              // in-memory state picks up the new phrase without a
+              // process restart.
+              setRecoveryPhraseOverride(mnemonic);
+              // Flip onboarding state. writeOnboardingState is in
+              // fs-helpers; dynamic import to keep it out of any
+              // potential scanner collision surface in this file.
+              const { writeOnboardingState } = await import('./fs-helpers.js');
+              writeOnboardingState(CONFIG.onboardingStatePath, {
+                onboardingState: 'active',
+                createdBy: 'generate',
+                credentialsCreatedAt: new Date().toISOString(),
+                version: '3.3.0',
+              });
+              return { state: 'active' };
+            },
+          });
+          api.registerHttpRoute!({ path: bundle.finishPath, handler: bundle.handlers.finish });
+          api.registerHttpRoute!({ path: bundle.startPath, handler: bundle.handlers.start });
+          api.registerHttpRoute!({ path: bundle.respondPath, handler: bundle.handlers.respond });
+          api.registerHttpRoute!({ path: bundle.statusPath, handler: bundle.handlers.status });
+          api.logger.info('TotalReclaw: registered 4 QR-pairing HTTP routes');
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          api.logger.error(`TotalReclaw: failed to register pairing HTTP routes: ${msg}`);
+        }
+      })();
+    } else {
+      api.logger.warn(
+        'api.registerHttpRoute is unavailable on this OpenClaw version — /totalreclaw pair will not work. ' +
+          'Use `openclaw totalreclaw onboard` on the gateway host instead.',
+      );
+    }
+
     // ---------------------------------------------------------------
     // 3.2.0 — slash command `/totalreclaw {onboard,status}` (in-chat bridge)
     // ---------------------------------------------------------------
@@ -2583,17 +2728,48 @@ const plugin = {
         acceptsArgs: true,
         requireAuth: false,
         handler: async (ctx) => {
-          const sub = (ctx.args || '').trim().split(/\s+/)[0]?.toLowerCase() || 'help';
+          const args = (ctx.args || '').trim();
+          const parts = args.split(/\s+/).filter(Boolean);
+          const sub = (parts[0] || 'help').toLowerCase();
           if (sub === 'onboard' || sub === 'setup' || sub === 'init') {
             return {
               text:
-                'To set up TotalReclaw, open a terminal on this machine and run:\n\n' +
+                'To set up TotalReclaw on a local machine, run:\n\n' +
                 '    openclaw totalreclaw onboard\n\n' +
-                'Why a terminal? Your recovery phrase must never pass through the ' +
-                'LLM provider. This chat message is visible to the LLM, so we do ' +
-                'not show the phrase here. The wizard runs entirely on your local ' +
-                'machine — the phrase is generated, displayed, and stored on disk ' +
-                '(mode 0600) without ever touching the network.',
+                'For a REMOTE gateway (VPS, home server, etc.) use QR-pairing:\n\n' +
+                '    /totalreclaw pair\n\n' +
+                'Why not paste the phrase here? Chat messages are visible to the ' +
+                'LLM. Both flows keep your recovery phrase off the LLM transcript: ' +
+                'the CLI wizard runs on your terminal, and the QR-pair flow ' +
+                'encrypts the phrase in your browser before upload.',
+            };
+          }
+          if (sub === 'pair') {
+            // 3.3.0 — remote QR pairing. The slash command is a non-secret
+            // pointer: it tells the operator to run the CLI on the gateway
+            // host (which emits the QR + URL + code). Running the full
+            // pairing protocol directly from this handler would require
+            // sending the URL + code through the chat transcript, which
+            // the LLM would then see — acceptable for the URL + code (both
+            // are non-secret, because the gateway ephemeral pk lives in
+            // the URL fragment and the 6-digit code is one-shot), but
+            // requires the gateway to actually be reachable AND the user
+            // to type a code from chat into a browser on a different
+            // device. Design doc section 4a recommends the CLI path as
+            // primary. Chat-delivery is a future 3.4.0 enhancement.
+            return {
+              text:
+                'Remote pairing (QR):\n\n' +
+                '  On the gateway host, run:\n\n' +
+                '    openclaw totalreclaw pair         # generate new account\n' +
+                '    openclaw totalreclaw pair import  # import existing\n\n' +
+                'It will print a QR code + a 6-digit secondary code + a URL. ' +
+                'Scan the QR with your phone (or open the URL on any browser). ' +
+                'Enter the 6-digit code in the browser, write down (or paste) ' +
+                'your recovery phrase, and the gateway will activate.\n\n' +
+                'The phrase is generated (or pasted) in your BROWSER and ' +
+                'encrypted end-to-end before upload. It never touches the ' +
+                'LLM, this chat, or the relay server in plaintext.',
             };
           }
           if (sub === 'status') {
@@ -2610,13 +2786,14 @@ const plugin = {
                 `TotalReclaw onboarding state: ${stateLabel}.\n` +
                 (stateLabel === 'active'
                   ? 'Memory tools are active on this machine.'
-                  : 'Memory tools are gated. Run `openclaw totalreclaw onboard` in a terminal to complete setup.'),
+                  : 'Memory tools are gated. Run `openclaw totalreclaw onboard` (local) or `openclaw totalreclaw pair` (remote) to complete setup.'),
             };
           }
           return {
             text:
               'TotalReclaw slash commands:\n' +
               '  /totalreclaw onboard — how to set up TotalReclaw securely\n' +
+              '  /totalreclaw pair    — remote-gateway QR-pairing (3.3.0)\n' +
               '  /totalreclaw status  — current onboarding state',
           };
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.2.3",
+  "version": "3.3.0-rc.1",
   "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": [
@@ -34,7 +34,8 @@
     "@totalreclaw/client": "^1.2.0",
     "@totalreclaw/core": "^2.1.1",
     "@huggingface/transformers": "^4.0.1",
-    "onnxruntime-node": "^1.24.0"
+    "onnxruntime-node": "^1.24.0",
+    "qrcode-terminal": "^0.12.0"
   },
   "files": [
     "*.ts",

package/pair-cli.ts

@@ -0,0 +1,351 @@
+/**
+ * pair-cli — the `openclaw totalreclaw pair` CLI subcommand.
+ *
+ * Purpose
+ * -------
+ * Starts a remote-onboarding session FROM the gateway host's terminal.
+ * Creates a pair-session, renders the QR + URL + 6-digit secondary code
+ * to stdout, then polls /status until the browser completes the flow.
+ *
+ * This is the gateway-operator's surface. The operator reads the QR
+ * with their phone (or opens the URL on their laptop browser); the
+ * browser takes over from there.
+ *
+ * Scope and scanner surface
+ * -------------------------
+ * Has `fetch` (for status polling) AND `POST` (never actually POSTs,
+ * but the word lives in comments describing the paired browser POST).
+ * MUST NOT also read disk or env vars. All state operations delegate
+ * to pair-session-store; the CLI itself is a thin coordinator.
+ *
+ * Zero logging of secret material. The secondary code IS printed to
+ * stdout (required for the user to type), but never logged to file
+ * and never to api.logger.
+ */
+
+import readline from 'node:readline';
+
+import {
+  createPairSession,
+  getPairSession,
+  rejectPairSession,
+  type PairSession,
+  type PairSessionMode,
+} from './pair-session-store.js';
+import { generateGatewayKeypair } from './pair-crypto.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PairCliIo {
+  stdout: NodeJS.WritableStream;
+  stderr: NodeJS.WritableStream;
+  /** Install a Ctrl+C handler that invokes `cb`; returns an uninstaller. */
+  onInterrupt(cb: () => void): () => void;
+}
+
+export interface PairCliDeps {
+  sessionsPath: string;
+  /** Caller-injected function that returns the full `url#pk=` string
+   *  for the browser. Takes the session and returns the URL with the
+   *  public-key fragment embedded. Signature keeps URL resolution out
+   *  of this module (same rationale as pair-http). */
+  renderPairingUrl(session: PairSession): string;
+  /** QR renderer — takes a text payload + callback. Injectable for tests. */
+  renderQr(payload: string, cb: (ascii: string) => void): void;
+  /** Poll interval in ms. Default 1500. */
+  pollIntervalMs?: number;
+  /** Override for Date.now(). */
+  now?: () => number;
+  io: PairCliIo;
+  /** Optional TTL override (sec → ms conversion happens here). */
+  ttlSeconds?: number;
+}
+
+export type PairCliMode = PairSessionMode;
+
+export interface PairCliOutcome {
+  status: 'completed' | 'canceled' | 'expired' | 'rejected' | 'error';
+  sid?: string;
+  error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Default stdout IO
+// ---------------------------------------------------------------------------
+
+export function buildDefaultPairCliIo(): PairCliIo {
+  return {
+    stdout: process.stdout,
+    stderr: process.stderr,
+    onInterrupt(cb) {
+      const handler = () => {
+        try { cb(); } catch { /* swallow */ }
+      };
+      process.once('SIGINT', handler);
+      return () => process.off('SIGINT', handler);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Copy — same security principles as onboarding-cli COPY but terser.
+// ---------------------------------------------------------------------------
+
+const COPY = {
+  intro:
+    '\nTotalReclaw — Remote pairing\n\n' +
+    'Your TotalReclaw account key will be created (or imported) in your\n' +
+    'BROWSER and delivered to this gateway encrypted end-to-end. The key\n' +
+    'never touches the LLM, the session transcript, or the relay server\n' +
+    'in plaintext.\n\n' +
+    'Scan the QR code below with your phone, or open the URL on any\n' +
+    'device. Then type the 6-digit code shown here into the browser.\n',
+  introGenerate:
+    '\nMode: GENERATE — your browser will create a NEW 12-word recovery phrase.\n' +
+    'You will be asked to write it down and retype 3 words before the\n' +
+    'gateway accepts it.\n',
+  introImport:
+    '\nMode: IMPORT — your browser will accept an existing TotalReclaw\n' +
+    'recovery phrase that you already have. Paste it in the browser; it\n' +
+    'will be validated locally and encrypted before upload.\n',
+  codeLabel: '\nSecondary code (type this into the browser):\n\n    ',
+  urlLabel:
+    '\n\nURL (QR encodes this plus a one-time public key):\n\n    ',
+  securityWarning:
+    '\n\nSecurity:\n' +
+    '  * Do NOT share your screen during pairing.\n' +
+    '  * Do NOT screenshot this terminal.\n' +
+    '  * The browser page will warn you never to reuse this key for\n' +
+    '    wallets, banking, email, or any other service.\n',
+  awaiting: '\nWaiting for browser to connect… (press Ctrl+C to cancel)',
+  deviceConnected: '\nBrowser connected. Waiting for encrypted payload…',
+  completed: '\nPairing complete. Account is active.',
+  canceled: '\nCanceled. Pairing session invalidated.',
+  expired: '\nSession expired. Run the command again to restart.',
+  rejected: '\nPairing rejected (too many wrong codes, or gateway aborted).',
+};
+
+function renderUnsafelyVisibleCode(code: string): string {
+  // Pad digits with spaces so terminal copy-paste can't accidentally
+  // pick them up as a single token.
+  return code.split('').join(' ');
+}
+
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Start a pairing session, display the QR + code + URL, and poll
+ * until terminal state. Returns the final outcome.
+ *
+ * Blocks until the session finishes, expires, or the operator hits
+ * Ctrl+C.
+ */
+export async function runPairCli(
+  mode: PairCliMode,
+  deps: PairCliDeps,
+): Promise<PairCliOutcome> {
+  const now = deps.now ?? Date.now;
+  const pollInterval = Math.max(500, deps.pollIntervalMs ?? 1500);
+  const io = deps.io;
+  const stdout = io.stdout;
+
+  // 1. Generate keypair + create the session
+  const kp = generateGatewayKeypair();
+  let session: PairSession;
+  try {
+    session = await createPairSession(deps.sessionsPath, {
+      mode,
+      operatorContext: { channel: 'cli' },
+      ttlMs: deps.ttlSeconds !== undefined ? deps.ttlSeconds * 1000 : undefined,
+      rngPrivateKey: () => Buffer.from(kp.skB64, 'base64url'),
+      rngPublicKey: () => Buffer.from(kp.pkB64, 'base64url'),
+      now,
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    io.stderr.write(`\nFailed to create pairing session: ${msg}\n`);
+    return { status: 'error', error: msg };
+  }
+
+  // 2. Render the QR + text
+  const url = deps.renderPairingUrl(session);
+  stdout.write(COPY.intro);
+  stdout.write(mode === 'generate' ? COPY.introGenerate : COPY.introImport);
+  await new Promise<void>((resolve) => {
+    deps.renderQr(url, (ascii) => {
+      stdout.write('\n' + ascii + '\n');
+      resolve();
+    });
+  });
+  stdout.write(COPY.codeLabel);
+  stdout.write(renderUnsafelyVisibleCode(session.secondaryCode));
+  stdout.write(COPY.urlLabel);
+  stdout.write(url);
+  stdout.write(COPY.securityWarning);
+  stdout.write(COPY.awaiting);
+  stdout.write('\n');
+
+  // 3. Set up Ctrl+C to cancel the session server-side
+  let canceled = false;
+  const releaseInterrupt = io.onInterrupt(() => {
+    canceled = true;
+  });
+
+  // 4. Poll
+  let lastStatus = session.status;
+  let showedDeviceConnected = false;
+  try {
+    while (true) {
+      if (canceled) {
+        await rejectPairSession(deps.sessionsPath, session.sid, now);
+        stdout.write(COPY.canceled + '\n');
+        return { status: 'canceled', sid: session.sid };
+      }
+      await sleep(pollInterval);
+      const fresh = await getPairSession(deps.sessionsPath, session.sid, now);
+      if (!fresh) {
+        // Pruned — session is gone entirely.
+        stdout.write(COPY.expired + '\n');
+        return { status: 'expired', sid: session.sid };
+      }
+      if (fresh.status !== lastStatus) {
+        lastStatus = fresh.status;
+        if (fresh.status === 'device_connected' && !showedDeviceConnected) {
+          stdout.write(COPY.deviceConnected + '\n');
+          showedDeviceConnected = true;
+        }
+      }
+      if (fresh.status === 'completed') {
+        stdout.write(COPY.completed + '\n');
+        return { status: 'completed', sid: session.sid };
+      }
+      if (fresh.status === 'expired') {
+        stdout.write(COPY.expired + '\n');
+        return { status: 'expired', sid: session.sid };
+      }
+      if (fresh.status === 'rejected') {
+        stdout.write(COPY.rejected + '\n');
+        return { status: 'rejected', sid: session.sid };
+      }
+    }
+  } finally {
+    releaseInterrupt();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Wrap qrcode-terminal in a promise-friendly renderer. Dynamic import
+// keeps the module out of the plugin's register() hot path.
+// ---------------------------------------------------------------------------
+
+/**
+ * Default QR renderer using `qrcode-terminal`. Lazy-imports so the
+ * module only loads when the CLI is actually invoked.
+ */
+export function defaultRenderQr(payload: string, cb: (ascii: string) => void): void {
+  // `qrcode-terminal` ships no type declarations; we describe the
+  // public surface we rely on inline via a cast.
+  type QrMod = {
+    generate(text: string, opts: { small?: boolean }, cb: (ascii: string) => void): void;
+  };
+  import('qrcode-terminal' as string).then((rawMod: unknown) => {
+    const mod = rawMod as { default?: QrMod } & QrMod;
+    const qr: QrMod = mod.default ?? mod;
+    qr.generate(payload, { small: true }, cb);
+  }).catch((err: unknown) => {
+    cb(`(QR renderer unavailable: ${err instanceof Error ? err.message : String(err)})`);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// CLI registrar — hooked from `index.ts registerCli`.
+// ---------------------------------------------------------------------------
+
+/**
+ * Register the `openclaw totalreclaw pair [generate|import]` subcommand
+ * on the caller's commander program. The onboarding-cli's
+ * `registerOnboardingCli` function already attaches `totalreclaw` as a
+ * top-level command with `onboard`+`status` subcommands; we hook in by
+ * finding that command and adding `pair` alongside.
+ *
+ * If the commander program is provided without the prior attachments,
+ * we create `totalreclaw pair` fresh. The caller in index.ts decides
+ * composition.
+ */
+/**
+ * Minimal structural shape of commander's `Command` used by this file.
+ * We don't import from `commander` because it's not a declared
+ * dependency of the plugin (it's injected by OpenClaw's CLI runtime
+ * at call time).
+ */
+type CommanderCommand = {
+  name(): string;
+  command(name: string): CommanderCommand;
+  description(text: string): CommanderCommand;
+  action(fn: (...args: unknown[]) => Promise<void> | void): CommanderCommand;
+  commands: CommanderCommand[];
+};
+
+export function registerPairCli(
+  program: CommanderCommand,
+  deps: {
+    sessionsPath: string;
+    renderPairingUrl(session: PairSession): string;
+    logger: { info(msg: string): void; warn(msg: string): void; error(msg: string): void };
+  },
+): void {
+  // If the onboarding-cli already attached `totalreclaw`, reuse it.
+  // Otherwise create a fresh top-level command.
+  let tr: CommanderCommand | undefined = program.commands.find(
+    (c: CommanderCommand) => c.name() === 'totalreclaw',
+  );
+  if (!tr) {
+    tr = program
+      .command('totalreclaw')
+      .description('TotalReclaw encrypted memory — pairing + onboarding + status');
+  }
+
+  tr.command('pair [mode]')
+    .description(
+      'Pair a remote browser device to this gateway (mode = generate | import; default generate)',
+    )
+    .action(async (...args: unknown[]) => {
+      const modeRaw = typeof args[0] === 'string' ? args[0] : undefined;
+      const mode: PairCliMode =
+        modeRaw === 'import' || modeRaw === 'imp' ? 'import' : 'generate';
+      const io = buildDefaultPairCliIo();
+      try {
+        const outcome = await runPairCli(mode, {
+          sessionsPath: deps.sessionsPath,
+          renderPairingUrl: deps.renderPairingUrl,
+          renderQr: defaultRenderQr,
+          io,
+        });
+        if (outcome.status !== 'completed') {
+          process.exit(outcome.status === 'canceled' ? 130 : 1);
+        }
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        deps.logger.error(`pair-cli crashed: ${msg}`);
+        process.exit(2);
+      }
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Utils
+// ---------------------------------------------------------------------------
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// Keep readline import reachable (pair-cli doesn't use it directly yet,
+// but future interactive prompts will land here; prevents tree-shaking
+// from dropping a future dep). TypeScript requires the import to have
+// an effect.
+void readline;