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

package/CHANGELOG.md

@@ -4,6 +4,166 @@ 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.6] — 2026-04-20
+
+Sixth release candidate for 3.3.0. Single manifest-only fix for the
+root cause of every rc.2–rc.5 HTTP-route failure: the gateway's startup
+registry pin silently excluded our plugin because the manifest declared
+`kind: "memory"`. All prior fixes (scanner, auth literal, sync
+registration) are preserved. No code changes in `index.ts` or any other
+source file. No protocol / on-chain changes vs 3.3.0.
+
+See research report: `docs/notes/RESEARCH-openclaw-http-route-plumbing-20260420-1608.md`
+in `totalreclaw-internal`, and `totalreclaw-internal#21` comment 4282038854.
+
+### Fixed
+
+- **`skill/plugin/openclaw.plugin.json` — drop `"kind": "memory"`**.
+  `resolveGatewayStartupPluginIds` (channel-plugin-ids-*.js) excludes
+  plugins with `kind: "memory"` from the gateway's startup set unless
+  they also declare a configured channel. Because TotalReclaw has no
+  channel, `loadGatewayPlugins` (gateway-cli-*.js:19807–19813) took an
+  empty-list early return, passed an empty HTTP route registry to
+  `createGatewayRuntimeState`, and `pinActivePluginHttpRouteRegistry`
+  locked that empty registry. The plugin still loaded later via the
+  memory-backend path and pushed its 4 routes into a NEW registry, but
+  `setActivePluginRegistry`'s `syncTrackedSurface` early-returns when
+  `surface.pinned === true` (runtime-*.js:60–67). Net: every `/pair/*`
+  HTTP route returned 404/SPA-fallthrough at runtime despite
+  `httpRouteCount: 4` in `openclaw plugins inspect`.
+
+  Removing `"kind": "memory"` from the manifest restores startup
+  inclusion via the sidecar path (`hasRuntimeContractSurface` becomes
+  false), so the gateway pins a registry that already contains the 4
+  routes.
+
+  **The JS plugin definition (`index.ts` line ~2626) still returns
+  `kind: 'memory' as const`.** The OpenClaw loader re-merges the JS
+  definition into `record.kind` at line 2090, so memory-slot matching
+  via `config.slots.memory === "totalreclaw"` still works and all
+  memory-gated behavior is unchanged.
+
+  This is a workaround for an upstream OpenClaw bug — see "Upstream
+  OpenClaw bug" section in the linked PR for the bug report draft and
+  proposed proper fixes.
+
+### Added
+
+- **`skill/plugin/manifest-shape.test.ts`** — dual-assertion regression
+  guard documenting the intentional manifest/JS asymmetry:
+  1. `openclaw.plugin.json` does NOT contain `"kind": "memory"` (guard
+     against accidentally re-adding).
+  2. The exported plugin definition in `index.ts` DOES have
+     `kind: 'memory' as const` (guard against accidental removal from
+     JS, which would break memory-slot matching).
+
+### Unchanged
+
+No changes to: `index.ts`, `pair-http.ts`, or any other source file.
+Scanner-sim: 0 flags. Tarball contents: same files; diff is
+`openclaw.plugin.json` (1 line removed) + `package.json` version bump +
+`CHANGELOG.md`.
+
+---
+
+## [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/openclaw.plugin.json

@@ -1,7 +1,6 @@
 {
   "id": "totalreclaw",
   "name": "TotalReclaw",
-  "kind": "memory",
   "description": "End-to-end encrypted memory vault for AI agents",
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.0-rc.4",
+  "version": "3.3.0-rc.6",
   "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": [
@@ -50,6 +50,7 @@
     "skill.json"
   ],
   "scripts": {
+    "test": "npx tsx manifest-shape.test.ts",
     "check-scanner": "node ../scripts/check-scanner.mjs",
     "prepublishOnly": "node ../scripts/check-scanner.mjs"
   },