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

package/CHANGELOG.md

@@ -4,6 +4,26 @@ 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:

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.2
+version: 3.3.11-rc.3
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz

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.2';
+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.2",
+  "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.2",
+  "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.2';
+const PLUGIN_VERSION = '3.3.11-rc.3';
 
 function die(msg: string, code = 1): never {
   process.stderr.write(`tr: ${msg}\n`);