@totalreclaw/totalreclaw 3.3.11-rc.1 → 3.3.11-rc.3

package/CHANGELOG.md

@@ -4,6 +4,43 @@ 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.11-rc.3] — 2026-05-06
+
+Two real-bug fixes flagged by Pedro's pop-os QA on rc.11-rc.1/rc.2: credentials.json shipped with only `{mnemonic}` (no userId, no salt), and the subgraph "Invalid character 'q' at position 0" Bytes-decode error.
+
+### Fixed
+
+- **credentials.json now persists `userId` + `salt` at pair time.** Previously, `pair-cli-relay.ts::completePairing` wrote only `{mnemonic}` and deferred `/v1/register` + the `{userId, salt}` fields to the plugin's next `register()` load. When that load failed (Pedro's pop-os SIGUSR1 plugin-skip + various other transients), credentials stayed mnemonic-only and every subsequent operation re-attempted registration but never actually wrote the result. Fix: pair-cli-relay's completePairing now derives `keys = deriveKeys(mnemonic)`, computes `authKeyHash + saltHex`, calls `apiClient.register()` against the relay's `/v1/register` (converting `wss://…` → `https://…`), and writes the full `{mnemonic, salt(base64), userId, scope_address}` object to credentials.json before resolving the WS pair flow. USER_EXISTS in subgraph mode falls back to a deterministic userId derived from the auth-key hash. Pair flow is now self-contained: a successful pair leaves the user fully registered with complete credentials, regardless of subsequent plugin-load behavior.
+
+- **Subgraph "Invalid character 'q' at position 0" eliminated.** Plugin's Smart Account derivation has a fallback: when `deriveSmartAccountAddress(mnemonic)` throws, it set `subgraphOwner = userId`. But the subgraph's `owner` field is typed `Bytes!` (0x-prefixed hex), and userIds (UUIDs from `/v1/register`) often start with non-hex chars like `q`/`r`/`y`, so every subsequent subgraph query returned `Failed to decode Bytes value: Invalid character 'q' at position 0`. Fix: never fall back to `userId` for the Bytes! field. Instead leave `subgraphOwner = null` and emit a clear error explaining that subgraph reads/writes will be skipped this session until SA derivation succeeds. This surfaces the underlying mnemonic issue (or whatever the SA-derivation failure was) rather than masking it as a downstream subgraph decoding error.
+
+### Implementation notes
+
+- `pair-cli-relay.ts` now imports `deriveKeys` + `computeAuthKeyHash` from `crypto.js` and `createApiClient` from `api-client.js`. The added `/v1/register` call is best-effort — registration failure logs a warn and continues with a mnemonic-only credentials.json (the plugin's `register()` retries on next boot). USER_EXISTS specifically derives the userId deterministically (`authKeyHash.slice(0, 32)`) so the credentials are still complete.
+- `index.ts` SA-derivation fallback removed. `subgraphOwner` stays `null` on derivation failure. Existing call-sites already check for null/undefined before issuing subgraph queries; the change just stops poisoning those checks with a wrong-format string.
+- 81/81 fs-helpers + 21/21 register-command-name + 37/37 skill-md + 21/21 tr-cli-json + 40/40 trajectory-poller. check-scanner: 129 files, 0 flags.
+
+### Likely cures
+
+The pop-os "plugin doesn't load after SIGUSR1" symptom from rc.11-rc.1/rc.2 was probably a downstream effect of these two bugs: incomplete credentials → SA derivation fails → subgraphOwner falls back to userId → first subgraph query throws → plugin's register() bails before reaching the trajectory-poller setup. With creds complete at pair time AND no garbage-fallback for the Bytes field, plugin's register() should run to completion and the poller should fire.
+
+## [3.3.11-rc.2] — 2026-05-06
+
+UX hardening on top of rc.1's trajectory-poller. Pedro's first install attempt on rc.1 surfaced two agent-prose violations the prior FORBIDDEN ACTIONS list didn't catch:
+
+1. **Inter-line narration during install.** The agent emitted "Now let me verify the install:", "Now let me check if you already have credentials:", and "Need to pair. Let me kick that off:" between the four numbered user-visible lines. Each was edit churn the user shouldn't see — and the third leaked the internal word "pair", which the user doesn't know.
+2. **"Stored on a relay server" architectural claim.** When asked "how does this work?", the agent replied that memories are stored on a relay server. WRONG. Memories are encrypted with a key derived from the recovery phrase, submitted on-chain via Account Abstraction (UserOps), persisted on a public blockchain (Base for free tier, Gnosis for paid), and indexed by The Graph. The relay only forwards encrypted bundles — it never sees plaintext, can't read memories, and could be replaced by any compatible relay without losing data.
+
+### Changed
+
+- **SKILL.md "CRITICAL" section rewritten as "How TotalReclaw actually stores memories"** — leads with the on-chain decentralized architecture, not the relay. Forbidden vocabulary list expanded with centralized-custody phrasings ("stored on a relay server", "TotalReclaw's server", "single server owned by", "company server", etc.) alongside the existing local-only ban list.
+- **New "User-facing vocabulary" translation table.** Maps internal jargon (pair, relay, WS, trapdoor, subgraph, bundler, UserOp, mnemonic file, `setsid -f`) to user-facing phrases ("set up an account", "your account", "your recovery phrase"). The word "pair" is now explicitly forbidden in user-visible prose — it's an internal CLI command, not a user concept.
+- **New "Hard silence rules between numbered lines"** subsection with verbatim bad examples from this QA: "Now let me verify the install" / "Now let me check if you already have credentials" / "Need to pair. Let me kick that off" / "Standing by." / any "Let me X" prelude. The transcript the user sees is exactly the four numbered lines, nothing in between.
+- **New "How does TotalReclaw work?" canonical answer section.** Provides the long-form explanation plus three short slices ("Where are memories stored?" / "Is the relay reading my data?" / "What if TotalReclaw shuts down?") so the agent has a paste-ready truthful answer for common user questions. Mirrored in `openclaw-setup-quickstart.md`.
+- **Quickstart rules bumped from 5 to 7** with the same "no pair word" + "no centralized-custody phrasing" hard rules.
+
+This RC is doc + SKILL.md only — same `tr-cli.js` and `trajectory-poller.js` binaries as rc.1. The trajectory poller verified end-to-end (40/40 unit tests + live container smoke) in rc.1 ships unchanged.
+
 ## [3.3.11-rc.1] — 2026-05-06
 
 Auto-extraction restored without waiting on upstream OpenClaw. Pedro's pop-os QA on rc.10-rc.5 produced 0 extraction events across 2 h of Telegram chat — root cause confirmed in fresh canonical container (OpenClaw 2026.5.4): the `agent_end` hook is silently rejected for non-bundled plugins despite `plugins.entries.totalreclaw.hooks.allowConversationAccess=true` in config. Reproduces every gateway boot + every SIGUSR1 in-process restart. Plugin's `api.on('agent_end', handler)` call returns without error but the gateway never dispatches the event.

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: totalreclaw
 description: "Install + set up TotalReclaw encrypted memory for OpenClaw, then use tr CLI for remember / recall. Trigger on 'install TotalReclaw', 'set up TotalReclaw', 'restore my recovery phrase', or any remember / recall request."
-version: 3.3.11-rc.1
+version: 3.3.11-rc.3
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -30,21 +30,32 @@ metadata:
 >
 > If the user pastes either URL: prefer the quickstart for execution. Fetch the full guide only if the user asks for context or troubleshooting beyond what the quickstart covers. This SKILL.md mirrors the quickstart's hard rules so you can act even if the URL is unreachable.
 
-## CRITICAL: Relay-based architecture (read before anything else)
+## CRITICAL: How TotalReclaw actually stores memories (read before anything else)
 
-**TotalReclaw is RELAY-BASED. All memories require a paired account on the staging or production relay (depending on RC vs stable). There is NO local-only mode. NEVER claim memories are stored locally without an account.**
+**TotalReclaw is end-to-end encrypted memory stored across a DECENTRALIZED NETWORK — not on a single company server.** Memories are encrypted with keys derived from the user's 12-word recovery phrase, submitted as Account Abstraction UserOps, and persisted on a public blockchain (Base / Gnosis depending on tier). The Graph subgraph indexes them. The TotalReclaw relay only forwards encrypted bundles to the bundler and proxies subgraph reads — it never sees plaintext, can't read memories, and could be replaced by any compatible relay without losing data. No single company controls or can read user memories.
 
-Forbidden vocabulary — these claims are FALSE and MUST NEVER appear in your responses:
-- "local"
-- "local-only"
-- "stored locally"
-- "on disk"
-- "without an account"
-- "local memory"
-- "local storage"
-- any phrasing suggesting memories can be stored without pairing a relay account
+Forbidden vocabulary — these claims are WRONG (some imply local-only storage; some imply a single-company server):
+- "local", "local-only", "stored locally", "on disk", "local memory", "local storage" — wrong direction (implies local-only). Memories require an account; they're encrypted and submitted on-chain.
+- "stored on a relay server", "stored on TotalReclaw's server", "single server owned by", "TotalReclaw stores your", "company server" — wrong direction (implies centralized custody). The relay forwards ciphertext; storage is decentralized on-chain.
+- "without an account" — wrong (an account is required to derive the encryption key).
 
-If you find yourself about to say any of these, STOP. The correct statement is: "TotalReclaw requires a paired relay account to store memories — run `tr pair` to set one up."
+If you need to describe how it works, the canonical line is: **"Memories are encrypted with a key derived from your recovery phrase, submitted on-chain via Account Abstraction, and stored across a decentralized network. The relay only forwards encrypted bundles — it never sees plaintext. Only you can decrypt them, and only with your recovery phrase."**
+
+## User-facing vocabulary (substitute internal jargon for plain words)
+
+Internal terms that the user does NOT know — translate when you must speak:
+
+| Internal term | Say to the user |
+|---|---|
+| pair / pairing / paired account | "set up an account" / "your TotalReclaw account" |
+| relay / relay server | (don't mention; if forced, say "the encrypted-bundle forwarder") |
+| WS / WebSocket / handshake | (don't mention) |
+| trapdoor / blind index / dedup-key | (don't mention) |
+| subgraph / bundler / UserOp / Account Abstraction | (don't mention; if forced, "submitted on-chain to a decentralized network") |
+| credentials.json / mnemonic file | "your recovery phrase" |
+| `tr pair --json` / `setsid -f` / shell exec | (don't mention; just do the work silently) |
+
+The word "pair" is internal jargon — never use it in user-visible prose. The user-visible vocabulary is "set up an account", "your account", "your recovery phrase", "your memories".
 
 ## Top-level rule (read this before anything else)
 
@@ -94,6 +105,30 @@ Speak only these lines, in order. Substitute the bracketed placeholders with the
 If existing credentials are detected (step "Check for existing credentials" below), emit ONLY this line and stop:
    > ✓ TotalReclaw is already set up.
 
+### Hard silence rules between numbered lines
+
+Do NOT emit transitional / narrative lines between any of the four user-visible lines above. Specifically forbidden (verbatim examples from Pedro's 2026-05-06 QA):
+
+- ❌ "Now let me verify the install:" → silent. Just run `tr status --json`. Emit line 2 when it returns.
+- ❌ "Now let me check if you already have credentials:" → silent. Just run `test -s ~/.totalreclaw/credentials.json`.
+- ❌ "Need to pair. Let me kick that off:" → silent. Just run the `setsid -f` block. Emit line 3 when URL+PIN returns. ALSO never use the word "pair" in user-facing text — see vocabulary table above.
+- ❌ "Standing by." → silent. Acknowledgements between lines are noise.
+- ❌ Any "Let me X" / "Now I'll Y" / "Just give me a second" prelude.
+
+The transcript Pedro should see is exactly four messages — the four numbered lines, nothing in between.
+
+## How does TotalReclaw work? (canonical answer for user questions)
+
+When the user asks "how does this work?" / "where are my memories stored?" / "is this safe?" / similar — answer with this content. Do NOT say "stored on a relay server", "stored on TotalReclaw's server", or any phrasing that implies single-company custody. The actual architecture:
+
+> **End-to-end encrypted, decentralized memory.** When you tell me to remember something, I encrypt it locally with a key derived from your 12-word recovery phrase, then submit it on-chain via Account Abstraction (a UserOperation). It lives on a public blockchain (Base Sepolia for free tier, Gnosis mainnet for paid). The Graph subgraph indexes it for fast retrieval. The TotalReclaw relay server only forwards encrypted bundles between your client and the chain — it never sees plaintext, can't read your memories, and could be replaced by any compatible relay without losing data. Your recovery phrase is the only thing that can decrypt the memories. Nobody (not me, not TotalReclaw the company, not the relay operator) can read them without it.
+
+If the user asks shorter questions, reply with the relevant slice:
+
+- **"Where are memories stored?"** → "Encrypted, on-chain (Base or Gnosis depending on your tier), indexed by The Graph. Not on any single company's server."
+- **"Is the relay reading my data?"** → "No. The relay only forwards encrypted bundles. Plaintext never leaves your device. Only your recovery phrase can decrypt them."
+- **"What if TotalReclaw shuts down?"** → "Your memories survive. They're on a public blockchain. Any compatible relay (or self-hosted relay) can read them with your recovery phrase."
+
 ## Setup flow (hybrid-primary)
 
 1. **Install plugin first, skill second (silent — emit user-visible line 1 once at the start, then no prose until line 2).** Run via your shell tool, in this exact order:
@@ -135,7 +170,7 @@ TR_CLI="$(ls -d ~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cl
 
 # Status check (parse JSON to confirm install + onboarding state)
 node "$TR_CLI" status --json
-# Returns: {"version":"3.3.10-rc.2","onboarded":false,"next_step":"pair","tool_count":17,"hybrid_mode":true}
+# Returns: {"version":"3.3.11-rc.1","onboarded":false,"next_step":"pair","tool_count":17,"hybrid_mode":true}
 
 # Pair / account setup — ALWAYS run via setsid -f to survive gateway restarts
 PAIR_OUT="/tmp/tr-pair-out-$(date +%s).json"

package/dist/index.js

@@ -660,6 +660,13 @@ async function initialize(logger) {
         logger.info(`Registered new user: ${userId}`);
     }
     // Derive Smart Account address for subgraph queries (on-chain owner identity).
+    // 3.3.11-rc.3: NEVER fall back to userId on derivation failure — the subgraph's
+    // `owner` field is typed `Bytes!` (0x-prefixed hex) and rejects userId UUIDs
+    // with `Failed to decode Bytes value: Invalid character 'q' at position 0`
+    // (because userIds often start with non-hex chars like q/r/y). When SA
+    // derivation fails the only safe path is to leave subgraphOwner unset and
+    // fail every subsequent on-chain operation with a clear "smart-account
+    // unavailable" error rather than spamming the subgraph with garbage Bytes.
     if (isSubgraphMode()) {
         try {
             const config = getSubgraphConfig();
@@ -667,9 +674,13 @@ async function initialize(logger) {
             logger.info(`Subgraph owner (Smart Account): ${subgraphOwner}`);
         }
         catch (err) {
-            logger.warn(`Failed to derive Smart Account address: ${err instanceof Error ? err.message : String(err)}`);
-            // Fall back to userId — won't match subgraph Bytes format, but better than null
-            subgraphOwner = userId;
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.error(`Smart Account derivation failed: ${msg} — subgraph reads/writes will be skipped this session ` +
+                '(no Bytes-format owner available). Verify mnemonic in credentials.json.');
+            // Leave subgraphOwner undefined. Code paths that read it must guard
+            // against undefined and skip the subgraph round-trip rather than
+            // sending a malformed query.
+            subgraphOwner = null;
         }
     }
     // One-time billing check for returning users (imported recovery phrase).

package/dist/pair-cli-relay.js

@@ -49,6 +49,8 @@ import { loadCredentialsJson, writeCredentialsJson, writeOnboardingState, } from
 import { awaitPhraseUpload, openRemotePairSession, } from './pair-remote-client.js';
 import { setRecoveryPhraseOverride } from './config.js';
 import { encodePng, encodeUnicode } from './pair-qr.js';
+import { deriveKeys, computeAuthKeyHash } from './crypto.js';
+import { createApiClient } from './api-client.js';
 /**
  * Run the relay-mode pair CLI. Mirrors `runPairCli`'s exit-code semantics:
  *   - `completed` (status 0)
@@ -216,6 +218,45 @@ export async function runRelayPairCli(mode, opts) {
             phraseValidator: (p) => validateMnemonic(p, wordlist),
             completePairing: async ({ mnemonic }) => {
                 try {
+                    // 3.3.11-rc.3: derive auth key + salt from mnemonic and pre-register
+                    // with the relay HERE (not deferred to the plugin's next register()
+                    // load). Pedro's 2026-05-06 QA found that pop-os was leaving
+                    // credentials.json with only `{mnemonic}` because the plugin's
+                    // post-pair register() either didn't run (post-SIGUSR1 plugin-skip
+                    // bug) or partially failed before writing userId/salt back to disk.
+                    // Doing it inline here means a successful pair is self-contained:
+                    // browser uploads phrase → completePairing derives keys → register
+                    // → write {userId, salt, mnemonic, scope_address}. Plugin's
+                    // register() on next boot just authenticates with the existing
+                    // credentials.
+                    const keys = deriveKeys(mnemonic);
+                    const authKeyHash = computeAuthKeyHash(keys.authKey);
+                    const saltHex = keys.salt.toString('hex');
+                    const saltB64 = keys.salt.toString('base64');
+                    let registeredUserId;
+                    try {
+                        // wss://… → https://… for the REST register call. The relay
+                        // serves both protocols on the same host.
+                        const httpsBase = opts.relayBaseUrl.replace(/^ws/, 'http').replace(/\/+$/, '');
+                        const apiClient = createApiClient(httpsBase);
+                        const result = await apiClient.register(authKeyHash, saltHex);
+                        registeredUserId = result.user_id;
+                        opts.logger.info(`pair-cli (relay): registered user_id=${registeredUserId} (salt + auth-key persisted)`);
+                    }
+                    catch (regErr) {
+                        const msg = regErr instanceof Error ? regErr.message : String(regErr);
+                        // USER_EXISTS in subgraph mode → derive userId deterministically
+                        // from auth-key hash so the credentials are still complete.
+                        // Other errors → continue with mnemonic-only creds; the plugin's
+                        // register() will retry on next load.
+                        if (msg.includes('USER_EXISTS')) {
+                            registeredUserId = authKeyHash.slice(0, 32);
+                            opts.logger.info(`pair-cli (relay): USER_EXISTS — using derived userId=${registeredUserId}`);
+                        }
+                        else {
+                            opts.logger.warn(`pair-cli (relay): /v1/register failed (best-effort, will retry on plugin load): ${msg}`);
+                        }
+                    }
                     let scopeAddress;
                     try {
                         scopeAddress = await opts.deriveScopeAddress(mnemonic);
@@ -224,7 +265,9 @@ export async function runRelayPairCli(mode, opts) {
                         opts.logger.warn(`pair-cli (relay): scope_address derivation failed (will retry lazily): ${deriveErr instanceof Error ? deriveErr.message : String(deriveErr)}`);
                     }
                     const creds = loadCredentialsJson(opts.credentialsPath) ?? {};
-                    const next = { ...creds, mnemonic };
+                    const next = { ...creds, mnemonic, salt: saltB64 };
+                    if (registeredUserId)
+                        next.userId = registeredUserId;
                     if (scopeAddress)
                         next.scope_address = scopeAddress;
                     if (!writeCredentialsJson(opts.credentialsPath, next)) {
@@ -238,6 +281,7 @@ export async function runRelayPairCli(mode, opts) {
                         version: opts.pluginVersion,
                     });
                     opts.logger.info(`pair-cli (relay): session ${session.token.slice(0, 8)}… completed; credentials written` +
+                        (registeredUserId ? ` (userId=${registeredUserId.slice(0, 8)}…)` : '') +
                         (scopeAddress ? ` (scope_address=${scopeAddress})` : ''));
                     return { state: 'active' };
                 }

package/dist/tr-cli.js

@@ -41,7 +41,7 @@ const STATE_PATH = CONFIG.onboardingStatePath;
 // Auto-synced by skill/scripts/sync-version.mjs from skill/plugin/package.json::version.
 // Do not edit by hand — running tests will catch drift but the publish workflow
 // rewrites this constant at the start of every npm/ClawHub publish.
-const PLUGIN_VERSION = '3.3.11-rc.1';
+const PLUGIN_VERSION = '3.3.11-rc.3';
 function die(msg, code = 1) {
     process.stderr.write(`tr: ${msg}\n`);
     process.exit(code);

package/index.ts

@@ -931,15 +931,28 @@ async function initialize(logger: OpenClawPluginApi['logger']): Promise<void> {
   }
 
   // Derive Smart Account address for subgraph queries (on-chain owner identity).
+  // 3.3.11-rc.3: NEVER fall back to userId on derivation failure — the subgraph's
+  // `owner` field is typed `Bytes!` (0x-prefixed hex) and rejects userId UUIDs
+  // with `Failed to decode Bytes value: Invalid character 'q' at position 0`
+  // (because userIds often start with non-hex chars like q/r/y). When SA
+  // derivation fails the only safe path is to leave subgraphOwner unset and
+  // fail every subsequent on-chain operation with a clear "smart-account
+  // unavailable" error rather than spamming the subgraph with garbage Bytes.
   if (isSubgraphMode()) {
     try {
       const config = getSubgraphConfig();
       subgraphOwner = await deriveSmartAccountAddress(config.mnemonic, config.chainId);
       logger.info(`Subgraph owner (Smart Account): ${subgraphOwner}`);
     } catch (err) {
-      logger.warn(`Failed to derive Smart Account address: ${err instanceof Error ? err.message : String(err)}`);
-      // Fall back to userId — won't match subgraph Bytes format, but better than null
-      subgraphOwner = userId;
+      const msg = err instanceof Error ? err.message : String(err);
+      logger.error(
+        `Smart Account derivation failed: ${msg} — subgraph reads/writes will be skipped this session ` +
+          '(no Bytes-format owner available). Verify mnemonic in credentials.json.',
+      );
+      // Leave subgraphOwner undefined. Code paths that read it must guard
+      // against undefined and skip the subgraph round-trip rather than
+      // sending a malformed query.
+      subgraphOwner = null;
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.11-rc.1",
+  "version": "3.3.11-rc.3",
   "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": [

package/pair-cli-relay.ts

@@ -58,6 +58,8 @@ import {
 } from './pair-remote-client.js';
 import { setRecoveryPhraseOverride } from './config.js';
 import { encodePng, encodeUnicode } from './pair-qr.js';
+import { deriveKeys, computeAuthKeyHash } from './crypto.js';
+import { createApiClient } from './api-client.js';
 import type {
   PairCliIo,
   PairCliJsonPayload,
@@ -272,6 +274,51 @@ export async function runRelayPairCli(
       phraseValidator: (p: string) => validateMnemonic(p, wordlist),
       completePairing: async ({ mnemonic }) => {
         try {
+          // 3.3.11-rc.3: derive auth key + salt from mnemonic and pre-register
+          // with the relay HERE (not deferred to the plugin's next register()
+          // load). Pedro's 2026-05-06 QA found that pop-os was leaving
+          // credentials.json with only `{mnemonic}` because the plugin's
+          // post-pair register() either didn't run (post-SIGUSR1 plugin-skip
+          // bug) or partially failed before writing userId/salt back to disk.
+          // Doing it inline here means a successful pair is self-contained:
+          // browser uploads phrase → completePairing derives keys → register
+          // → write {userId, salt, mnemonic, scope_address}. Plugin's
+          // register() on next boot just authenticates with the existing
+          // credentials.
+          const keys = deriveKeys(mnemonic);
+          const authKeyHash = computeAuthKeyHash(keys.authKey);
+          const saltHex = keys.salt.toString('hex');
+          const saltB64 = keys.salt.toString('base64');
+
+          let registeredUserId: string | undefined;
+          try {
+            // wss://… → https://… for the REST register call. The relay
+            // serves both protocols on the same host.
+            const httpsBase = opts.relayBaseUrl.replace(/^ws/, 'http').replace(/\/+$/, '');
+            const apiClient = createApiClient(httpsBase);
+            const result = await apiClient.register(authKeyHash, saltHex);
+            registeredUserId = result.user_id;
+            opts.logger.info(
+              `pair-cli (relay): registered user_id=${registeredUserId} (salt + auth-key persisted)`,
+            );
+          } catch (regErr) {
+            const msg = regErr instanceof Error ? regErr.message : String(regErr);
+            // USER_EXISTS in subgraph mode → derive userId deterministically
+            // from auth-key hash so the credentials are still complete.
+            // Other errors → continue with mnemonic-only creds; the plugin's
+            // register() will retry on next load.
+            if (msg.includes('USER_EXISTS')) {
+              registeredUserId = authKeyHash.slice(0, 32);
+              opts.logger.info(
+                `pair-cli (relay): USER_EXISTS — using derived userId=${registeredUserId}`,
+              );
+            } else {
+              opts.logger.warn(
+                `pair-cli (relay): /v1/register failed (best-effort, will retry on plugin load): ${msg}`,
+              );
+            }
+          }
+
           let scopeAddress: string | undefined;
           try {
             scopeAddress = await opts.deriveScopeAddress(mnemonic);
@@ -283,7 +330,8 @@ export async function runRelayPairCli(
             );
           }
           const creds = loadCredentialsJson(opts.credentialsPath) ?? {};
-          const next: typeof creds = { ...creds, mnemonic };
+          const next: typeof creds = { ...creds, mnemonic, salt: saltB64 };
+          if (registeredUserId) next.userId = registeredUserId;
           if (scopeAddress) next.scope_address = scopeAddress;
           if (!writeCredentialsJson(opts.credentialsPath, next)) {
             return { state: 'error', error: 'credentials_write_failed' };
@@ -297,6 +345,7 @@ export async function runRelayPairCli(
           });
           opts.logger.info(
             `pair-cli (relay): session ${session.token.slice(0, 8)}… completed; credentials written` +
+              (registeredUserId ? ` (userId=${registeredUserId.slice(0, 8)}…)` : '') +
               (scopeAddress ? ` (scope_address=${scopeAddress})` : ''),
           );
           return { state: 'active' };

package/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "totalreclaw",
-  "version": "3.3.11-rc.1",
+  "version": "3.3.11-rc.3",
   "description": "End-to-end encrypted memory for AI agents — portable, yours forever. XChaCha20-Poly1305 E2EE: server never sees plaintext.",
   "author": "TotalReclaw Team",
   "license": "MIT",

package/tr-cli.ts

@@ -52,7 +52,7 @@ const STATE_PATH = CONFIG.onboardingStatePath;
 // Auto-synced by skill/scripts/sync-version.mjs from skill/plugin/package.json::version.
 // Do not edit by hand — running tests will catch drift but the publish workflow
 // rewrites this constant at the start of every npm/ClawHub publish.
-const PLUGIN_VERSION = '3.3.11-rc.1';
+const PLUGIN_VERSION = '3.3.11-rc.3';
 
 function die(msg: string, code = 1): never {
   process.stderr.write(`tr: ${msg}\n`);