@totalreclaw/totalreclaw 3.3.0-rc.4 → 3.3.0-rc.5

package/CHANGELOG.md

@@ -4,6 +4,104 @@ 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.0-rc.5] — 2026-04-20
+
+Fifth release candidate for 3.3.0. Single ship-stopper fix for rc.4's
+QR-pairing flow, root-caused by the auto-QA run against rc.4 artifacts
+(report: `docs/notes/QA-plugin-3.3.0-rc.4-20260420-1517.md` in
+`totalreclaw-internal`, thread at `totalreclaw-internal#21` comment
+4281568050). rc.2 (scanner), rc.3 (auth literal path), and rc.4 (auth
+`'plugin'` literal + `ensureSessionsFileDir` mkdir before lock) fixes are
+all preserved. No protocol / on-chain changes vs 3.3.0.
+
+### Fixed
+
+- **`skill/plugin/index.ts` — register pair HTTP routes synchronously
+  (remove async IIFE)**. rc.2–rc.4 wrapped the 4 `api.registerHttpRoute`
+  calls in a fire-and-forget `(async () => { ... })()` block whose three
+  `await import(...)` calls (`./pair-http.js`, `@scure/bip39`, and
+  `@scure/bip39/wordlists/english.js`) settled one microtask AFTER the
+  SDK loader had already called `register()` and frozen the plugin's
+  HTTP-route registry. The 4 post-activation pushes landed on the
+  dispatcher's "inactive" copy and never reached the live router;
+  `openclaw plugins inspect totalreclaw --json | jq .httpRouteCount`
+  returned `0` on rc.4 despite both the `auth: 'plugin'` literal (rc.4)
+  and the `ensureSessionsFileDir` mkdir (rc.4) being correct. rc.5:
+
+  1. `buildPairRoutes`, `validateMnemonic`, and `wordlist` are now
+     **static top-of-file imports** (alongside the existing
+     `onboarding-cli.ts` / `generate-mnemonic.ts` static imports of the
+     same modules — no new deps, no circular-dep risk).
+  2. `writeOnboardingState` is added to the existing static
+     `./fs-helpers.js` import (it was the only dynamic import inside
+     the `completePairing` callback).
+  3. The async IIFE is deleted. `buildPairRoutes(...)` and the 4
+     `api.registerHttpRoute({...})` calls are now in the synchronous
+     body of `register(api)`, inside the existing
+     `if (typeof api.registerHttpRoute === 'function')` guard. The
+     `else` branch and warning are unchanged. The post-registration
+     info log now reads `'registered 4 QR-pairing HTTP routes
+     synchronously'` for clearer debug output.
+  4. `completePairing` remains `async` (it does disk I/O) — that is
+     fine because `registerHttpRoute` accepts async handlers. Only the
+     REGISTRATION had to be synchronous; the handler itself can
+     defer-to-microtask freely at runtime.
+
+  Scanner: static imports don't trigger any rule that dynamic imports
+  don't already trigger (verified via `node skill/scripts/check-scanner.mjs`,
+  0 flags, 72 files scanned).
+
+  **Before (rc.4):**
+  ```ts
+  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({ /* ... */ });
+        api.registerHttpRoute!({ path: bundle.finishPath, /*...*/, auth: 'plugin' });
+        api.registerHttpRoute!({ path: bundle.startPath,  /*...*/, auth: 'plugin' });
+        api.registerHttpRoute!({ path: bundle.respondPath,/*...*/, auth: 'plugin' });
+        api.registerHttpRoute!({ path: bundle.statusPath, /*...*/, auth: 'plugin' });
+        // ^^ these 4 pushes happen AFTER register() has returned + the
+        //    SDK loader has already activated the (empty) route registry.
+      } catch (err) { /* ... */ }
+    })();
+  }
+  ```
+
+  **After (rc.5):**
+  ```ts
+  // top of file
+  import { buildPairRoutes } from './pair-http.js';
+  import { validateMnemonic } from '@scure/bip39';
+  import { wordlist } from '@scure/bip39/wordlists/english.js';
+  // ... fs-helpers import now also includes writeOnboardingState
+
+  // inside register(api)
+  if (typeof api.registerHttpRoute === 'function') {
+    const bundle = buildPairRoutes({ /* ... */ });
+    api.registerHttpRoute!({ path: bundle.finishPath,  /*...*/, auth: 'plugin' });
+    api.registerHttpRoute!({ path: bundle.startPath,   /*...*/, auth: 'plugin' });
+    api.registerHttpRoute!({ path: bundle.respondPath, /*...*/, auth: 'plugin' });
+    api.registerHttpRoute!({ path: bundle.statusPath,  /*...*/, auth: 'plugin' });
+    // ^^ these 4 pushes happen synchronously BEFORE register() returns,
+    //    i.e. BEFORE the SDK loader activates the registry.
+    api.logger.info('TotalReclaw: registered 4 QR-pairing HTTP routes synchronously');
+  }
+  ```
+
+- **`skill/plugin/pair-http-route-registration.test.ts` — rc.5 regression
+  guard**. The existing SIMULATION suite (27 assertions covering the 4
+  routes' `auth` literal, path shape, handler type) is preserved. Added
+  a new SYNCHRONY suite (14 assertions) that invokes `plugin.register(mockApi)`
+  with a minimal mocked OpenClaw API and asserts `mockApi.registerHttpRoute`
+  has been called 4 times IMMEDIATELY after `register()` returns — no
+  `await`, no tick wait. This assertion would fail under the rc.4 async-IIFE
+  implementation and guards against any future refactor that re-introduces
+  an async boundary at the registration site. Total: 41/41 passing.
+
 ## [3.3.0-rc.4] — 2026-04-20
 
 Fourth release candidate for 3.3.0. Two independent ship-stopper fixes for

package/index.ts

@@ -133,10 +133,14 @@ import {
   isRunningInDocker,
   deleteFileIfExists,
   resolveOnboardingState,
+  writeOnboardingState,
   type OnboardingState,
 } from './fs-helpers.js';
 import { decideToolGate, isGatedToolName } from './tool-gating.js';
 import { detectFirstRun, buildWelcomePrepend, type GatewayMode } from './first-run.js';
+import { buildPairRoutes } from './pair-http.js';
+import { validateMnemonic } from '@scure/bip39';
+import { wordlist } from '@scure/bip39/wordlists/english.js';
 import crypto from 'node:crypto';
 
 // ---------------------------------------------------------------------------
@@ -2711,62 +2715,64 @@ const plugin = {
     // 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' };
-            },
+      // rc.5 — the 4 `registerHttpRoute` calls MUST happen synchronously inside
+      // `register(api)` because the SDK loader freezes the plugin's HTTP-route
+      // registry as soon as `register()` returns. In rc.2–rc.4 this block was
+      // wrapped in a fire-and-forget async IIFE whose `await import(...)`
+      // settled one microtask AFTER the loader had already activated the
+      // (empty) route list — the post-activation pushes landed on the
+      // dispatcher's "inactive" copy and `openclaw plugins inspect
+      // totalreclaw --json | jq .httpRouteCount` returned 0. See
+      // `docs/notes/QA-plugin-3.3.0-rc.4-20260420-1517.md` (internal#21).
+      // Moving `buildPairRoutes`, `@scure/bip39`, and `fs-helpers`
+      // `writeOnboardingState` to static top-of-file imports keeps the
+      // registration site synchronous and makes the call order deterministic.
+      // `completePairing` remains async (it does disk I/O) — that is fine,
+      // since `registerHttpRoute` accepts async handlers; only the
+      // REGISTRATION must be synchronous.
+      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(CONFIG.onboardingStatePath, {
+            onboardingState: 'active',
+            createdBy: 'generate',
+            credentialsCreatedAt: new Date().toISOString(),
+            version: '3.3.0',
           });
-          // auth: 'plugin' — the 4 pair routes are reached from the operator's
-          // phone/laptop browser, which has no gateway bearer token. The plugin
-          // authenticates each request itself via (a) the in-memory pair session
-          // (sid + secondaryCode + single-use consumption), (b) ECDH + AEAD for
-          // the encrypted mnemonic payload. See gateway-cli dist
-          // `matchedPluginRoutesRequireGatewayAuth` / `enforcePluginRouteGatewayAuth`
-          // — routes with `auth: 'gateway'` require a bearer token and 401 any
-          // browser caller, which is the wrong semantic for QR-pair. rc.3
-          // shipped `auth: 'gateway'` and the QA agent confirmed the routes
-          // were unreachable from a browser (QA-plugin-3.3.0-rc.3 report).
-          api.registerHttpRoute!({ path: bundle.finishPath, handler: bundle.handlers.finish, auth: 'plugin' });
-          api.registerHttpRoute!({ path: bundle.startPath, handler: bundle.handlers.start, auth: 'plugin' });
-          api.registerHttpRoute!({ path: bundle.respondPath, handler: bundle.handlers.respond, auth: 'plugin' });
-          api.registerHttpRoute!({ path: bundle.statusPath, handler: bundle.handlers.status, auth: 'plugin' });
-          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}`);
-        }
-      })();
+          return { state: 'active' };
+        },
+      });
+      // auth: 'plugin' — the 4 pair routes are reached from the operator's
+      // phone/laptop browser, which has no gateway bearer token. The plugin
+      // authenticates each request itself via (a) the in-memory pair session
+      // (sid + secondaryCode + single-use consumption), (b) ECDH + AEAD for
+      // the encrypted mnemonic payload. See gateway-cli dist
+      // `matchedPluginRoutesRequireGatewayAuth` / `enforcePluginRouteGatewayAuth`
+      // — routes with `auth: 'gateway'` require a bearer token and 401 any
+      // browser caller, which is the wrong semantic for QR-pair. rc.3
+      // shipped `auth: 'gateway'` and the QA agent confirmed the routes
+      // were unreachable from a browser (QA-plugin-3.3.0-rc.3 report).
+      api.registerHttpRoute!({ path: bundle.finishPath, handler: bundle.handlers.finish, auth: 'plugin' });
+      api.registerHttpRoute!({ path: bundle.startPath, handler: bundle.handlers.start, auth: 'plugin' });
+      api.registerHttpRoute!({ path: bundle.respondPath, handler: bundle.handlers.respond, auth: 'plugin' });
+      api.registerHttpRoute!({ path: bundle.statusPath, handler: bundle.handlers.status, auth: 'plugin' });
+      api.logger.info('TotalReclaw: registered 4 QR-pairing HTTP routes synchronously');
     } else {
       api.logger.warn(
         'api.registerHttpRoute is unavailable on this OpenClaw version — /totalreclaw pair will not work. ' +

package/package.json

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