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

package/CHANGELOG.md

@@ -4,6 +4,213 @@ 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
+rc.3's QR-pairing flow, both surfaced by the auto-QA run against rc.3
+artifacts (report: `docs/notes/QA-plugin-3.3.0-rc.3-20260420-1440.md` in
+`totalreclaw-internal`, thread at `totalreclaw-internal#21`). No protocol /
+on-chain changes vs 3.3.0. Bundled into a single RC because shipping them
+separately would require two more QA loops for what are, individually,
+one-line fixes.
+
+### Fixed
+
+- **`skill/plugin/index.ts` — pair HTTP routes must use `auth: 'plugin'`, not
+  `'gateway'`** (lines 2750–2753, now 2760–2763 after added comment). rc.3
+  added `auth: 'gateway'` to the 4 `api.registerHttpRoute` calls, which the
+  SDK loader accepted as a legal value but whose runtime semantics are
+  "requires gateway bearer token" (see
+  `matchedPluginRoutesRequireGatewayAuth` at
+  `gateway-cli-CWpalJNJ.js:23186`). For the 4 pair routes — reached from a
+  phone/laptop browser with no bearer token — that means `/pair/*` is 401'd
+  at the plugin-auth stage before the handler ever runs. The second valid
+  literal, `auth: 'plugin'` (verified as the only other accepted value at
+  `loader-BkOjign1.js:662`), lets the plugin's handler run directly and
+  authenticate itself via the in-session sid + 6-digit secondaryCode +
+  single-use consumption + ECDH AEAD payload, which is the correct model
+  for QR-pair. QA observed `httpRouteCount: 0` in rc.3 via `plugins inspect`
+  and confirmed all 4 `/plugin/totalreclaw/pair/*` paths returned 404 / SPA
+  fallthrough. rc.4 switches all 4 to `auth: 'plugin'`.
+
+  **Before (rc.3):**
+  ```ts
+  api.registerHttpRoute!({ path: bundle.finishPath,  handler: bundle.handlers.finish,  auth: 'gateway' });
+  api.registerHttpRoute!({ path: bundle.startPath,   handler: bundle.handlers.start,   auth: 'gateway' });
+  api.registerHttpRoute!({ path: bundle.respondPath, handler: bundle.handlers.respond, auth: 'gateway' });
+  api.registerHttpRoute!({ path: bundle.statusPath,  handler: bundle.handlers.status,  auth: 'gateway' });
+  ```
+
+  **After (rc.4):**
+  ```ts
+  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' });
+  ```
+
+- **`skill/plugin/pair-session-store.ts::acquireSessionsFileLock` — mkdir
+  parent before `openSync(wx)`**. On a fresh install with no
+  `~/.totalreclaw/` directory, the lock's `openSync(path, 'wx')` returned
+  `ENOENT (No such file or directory)` and the retry loop misinterpreted
+  that as "lock already held", spinning at 50 ms intervals for the full
+  10 s `LOCK_WAIT_MS` before throwing `could not acquire lock`. The CLI
+  surfaced this as a hung `openclaw totalreclaw pair generate` with no QR,
+  URL, or secondary code ever rendered. `writePairSessionsFileSync`
+  already had a mkdir, but it was never reached because the lock never
+  acquired. rc.4 extracts a shared `ensureSessionsFileDir(sessionsPath)`
+  helper (mkdir `-p` with mode 0700) and calls it at the TOP of both
+  `acquireSessionsFileLock` AND `writePairSessionsFileSync` so the two
+  code paths can't drift. QA strace evidence in
+  `totalreclaw-internal#21`.
+
+  **Before (rc.3):**
+  ```ts
+  async function acquireSessionsFileLock(sessionsPath) {
+    const lockPath = `${sessionsPath}.lock`;
+    // ...
+    while (true) {
+      try {
+        const fd = fs.openSync(lockPath, 'wx');  // ENOENT here on fresh install
+        // ...
+  ```
+
+  **After (rc.4):**
+  ```ts
+  function ensureSessionsFileDir(sessionsPath) {
+    const dir = path.dirname(sessionsPath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+
+  async function acquireSessionsFileLock(sessionsPath) {
+    ensureSessionsFileDir(sessionsPath);   // NEW — guarantees parent dir
+    const lockPath = `${sessionsPath}.lock`;
+    // ...
+  ```
+
+### Added
+
+- `skill/plugin/pair-session-store.test.ts` — two new blocks (§17, §18)
+  covering the fresh-install regression: `createPairSession` against a
+  path whose parent directory does NOT exist completes in < 2 s (was
+  10 s hang), materializes the missing dir with the correct mode, writes
+  the sessions file at 0600, and leaves no lock sentinel. Plus read-path
+  defensive tests: `getPairSession` / `listActivePairSessions` against
+  a missing dir return null / `[]` without throwing (previously would
+  have hit the same ENOENT hang).
+- `skill/plugin/pair-http-route-registration.test.ts` — assertions
+  updated from `'gateway'` to `'plugin'`, plus a per-call regression
+  guard asserting `auth !== 'gateway'` so rc.3's value cannot sneak back
+  in. Test count: 23 → 27 assertions.
+
+### Unchanged
+
+No changes to: scanner-sim rules (still 0 flags), tarball contents (same
+44 files; diff is content of 3 `.ts` files + `package.json` bump +
+`CHANGELOG.md`), UX copy, terminology (`recovery phrase` throughout),
+protobuf schema, Memory Taxonomy v1, on-chain contract surface, MCP
+wiring, client integration, Hermes / NanoClaw / core (plugin-only RC).
+
+---
+
 ## [3.3.0-rc.3] — 2026-04-20
 
 Third release candidate for 3.3.0. Sole change vs rc.2: adds the mandatory

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,52 +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',
           });
-          api.registerHttpRoute!({ path: bundle.finishPath, handler: bundle.handlers.finish, auth: 'gateway' });
-          api.registerHttpRoute!({ path: bundle.startPath, handler: bundle.handlers.start, auth: 'gateway' });
-          api.registerHttpRoute!({ path: bundle.respondPath, handler: bundle.handlers.respond, auth: 'gateway' });
-          api.registerHttpRoute!({ path: bundle.statusPath, handler: bundle.handlers.status, auth: 'gateway' });
-          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.3",
+  "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": [

package/pair-session-store.ts

@@ -238,6 +238,25 @@ export const LOCK_WAIT_MS = 10_000;
 /** Between-retry sleep. Short enough to feel responsive, long enough not to spin. */
 export const LOCK_RETRY_MS = 50;
 
+/**
+ * Ensure the parent directory of `sessionsPath` exists, creating it
+ * (and any missing intermediates) with 0700 mode. This is called from
+ * BOTH the lock-acquisition and the write paths — if we only create
+ * the dir on write, a fresh install hits ENOENT on the lock's
+ * `openSync(path, 'wx')` and spins the retry loop until deadline (rc.3
+ * regression: QA-plugin-3.3.0-rc.3 report).
+ *
+ * Best-effort: a mkdir failure is re-thrown to the caller, which will
+ * surface it via the lock-acquisition error path (for lock) or the
+ * try/catch in `writePairSessionsFileSync` (for write). 0700 mode
+ * matches the privacy posture of the sessions file (0600) — if the
+ * user can read the directory they can already read the file.
+ */
+function ensureSessionsFileDir(sessionsPath: string): void {
+  const dir = path.dirname(sessionsPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+
 /**
  * Acquire an exclusive lock on the given sessions-file path by
  * atomically creating `<path>.lock` with `wx` mode. Retries up to
@@ -251,6 +270,16 @@ export const LOCK_RETRY_MS = 50;
  * and self-contained is safer than fighting the scanner.
  */
 async function acquireSessionsFileLock(sessionsPath: string): Promise<() => void> {
+  // Guarantee the parent directory exists BEFORE the first openSync(wx).
+  // Without this, a fresh install where `~/.totalreclaw/` doesn't yet
+  // exist gets ENOENT on every attempt, tight-loops until deadline, and
+  // throws "could not acquire lock" — which the CLI surfaces as a hung
+  // pair command with no QR / code / URL ever rendered (rc.3 blocker;
+  // QA-plugin-3.3.0-rc.3 strace evidence in totalreclaw-internal#21).
+  // `writePairSessionsFileSync` already creates the dir, but that path
+  // is never reached because the lock never acquires.
+  ensureSessionsFileDir(sessionsPath);
+
   const lockPath = `${sessionsPath}.lock`;
   const deadline = Date.now() + LOCK_WAIT_MS;
 
@@ -349,8 +378,9 @@ export function writePairSessionsFileSync(
   file: PairSessionFile,
 ): boolean {
   try {
-    const dir = path.dirname(sessionsPath);
-    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    // Same ensureSessionsFileDir used by acquireSessionsFileLock so the
+    // two paths can't drift.
+    ensureSessionsFileDir(sessionsPath);
     const tmp = `${sessionsPath}.tmp-${process.pid}-${Date.now()}`;
     fs.writeFileSync(tmp, JSON.stringify(file), { mode: 0o600 });
     fs.renameSync(tmp, sessionsPath);