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

package/CHANGELOG.md

@@ -4,6 +4,163 @@ 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.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
+`auth` field to the 4 `registerHttpRoute` calls that were silently dropped by
+the OpenClaw 2026.4.2 loader. QR-pairing was end-to-end dead in rc.2 despite
+the scanner and all other gates passing. See internal QA report at
+`totalreclaw-internal#21`.
+
+### Fixed
+
+- `skill/plugin/index.ts` — added `auth: 'gateway'` to all 4
+  `api.registerHttpRoute!({...})` calls (lines 2750–2753). OpenClaw 2026.4.2
+  introduced a mandatory `auth` field; registrations without it are silently
+  dropped at load time. Affected routes: `/pair/finish`, `/pair/start`,
+  `/pair/respond`, `/pair/status`. The plugin's `logger.info('registered 4
+  QR-pairing HTTP routes')` still fired in rc.2, masking the failure — only
+  surfaced when `GET /plugin/totalreclaw/pair/finish` fell through to the SPA
+  and `POST /pair/respond` returned 404.
+- `skill/plugin/index.ts` `PluginApi` interface — `registerHttpRoute` param
+  type updated to include `auth: 'gateway' | 'plugin'` so TypeScript enforces
+  the field going forward.
+
+**Before:**
+```ts
+api.registerHttpRoute!({ path: bundle.finishPath, handler: bundle.handlers.finish });
+api.registerHttpRoute!({ path: bundle.startPath, handler: bundle.handlers.start });
+api.registerHttpRoute!({ path: bundle.respondPath, handler: bundle.handlers.respond });
+api.registerHttpRoute!({ path: bundle.statusPath, handler: bundle.handlers.status });
+```
+
+**After:**
+```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' });
+```
+
+### Added
+
+- `skill/plugin/pair-http-route-registration.test.ts` — new unit test (23
+  assertions) covering: 4 calls made, `auth` field present on every call,
+  `auth === 'gateway'`, paths contain `/pair/`, handlers are functions, all 4
+  endpoint segments covered (finish/start/respond/status), and no-throw when
+  `registerHttpRoute` is absent.
+
+---
+
 ## [3.3.0-rc.2] — 2026-04-20
 
 Second release candidate for 3.3.0. Bundles the scanner false-positive

package/index.ts

@@ -214,6 +214,8 @@ interface OpenClawPluginApi {
   registerHttpRoute?(params: {
     path: string;
     handler: (req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => Promise<void> | void;
+    /** OpenClaw 2026.4.2+ — required; loader silently drops the route if absent. */
+    auth: 'gateway' | 'plugin';
   }): void;
 }
 
@@ -2745,10 +2747,20 @@ const plugin = {
               return { state: 'active' };
             },
           });
-          api.registerHttpRoute!({ path: bundle.finishPath, handler: bundle.handlers.finish });
-          api.registerHttpRoute!({ path: bundle.startPath, handler: bundle.handlers.start });
-          api.registerHttpRoute!({ path: bundle.respondPath, handler: bundle.handlers.respond });
-          api.registerHttpRoute!({ path: bundle.statusPath, handler: bundle.handlers.status });
+          // 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);

package/package.json

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