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

package/CHANGELOG.md

@@ -4,6 +4,22 @@ 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.10-rc.3] — 2026-05-06
+
+Pedro's 2026-05-05 manual QA on rc.10-rc.2 confirmed that even with the `setsid -f` instruction in SKILL.md, the agent freelances during install + pair: it restarted the gateway unprompted, re-rendered the QR to `/tmp/` (which OpenClaw's media-access policy blocks → `LocalMediaAccessError` on Telegram), wrote extra config that triggered another deferred SIGUSR1 reload, and ran `tr pair` in the foreground — all of which killed the pair WS and produced the 502 on browser respond. Plus the CLI binary's hard-coded `PLUGIN_VERSION` constant lagged the package version (CLI reported `3.3.9-rc.1` while the install record was `3.3.10-rc.2`).
+
+### Fixed
+
+- **`PLUGIN_VERSION` constant in `tr-cli.ts` is now auto-synced** from `package.json::version` by `skill/scripts/sync-version.mjs` (extended to cover this third site alongside the existing `SKILL.md` frontmatter and `skill.json` mirrors). The constant is the fallback the CLI returns from `tr status --json` when the on-disk `.loaded.json` manifest is missing — without sync, fresh-install boots before the manifest write report stale versions and break operator-side version checks.
+
+- **SKILL.md and `docs/guides/openclaw-setup.md` now have an explicit ⛔ FORBIDDEN section** listing every freelancing pattern from Pedro's QA, with the exact bad agent prose verbatim. The section is positioned BEFORE the setup flow so the agent reads it first. Forbidden actions: gateway restart (`/totalreclaw-restart`, SIGUSR1, `docker restart`), config writes to `~/.openclaw/openclaw.json` after install, QR re-render to `/tmp/totalreclaw-pair-qr.png`, foreground `tr pair --json` invocation (must use `setsid -f` verbatim), and narrative prose about CLI internals / version-lag / path resolution.
+
+### Implementation notes
+
+- `sync-version.mjs` now updates 3 sites: `SKILL.md` frontmatter, `skill.json::version`, `tr-cli.ts::PLUGIN_VERSION`. Idempotent — running twice on aligned tree is a no-op. Already wired into the publish workflows.
+- The FORBIDDEN section in SKILL.md and the setup-guide are mostly text duplicates by design — the guide is the agent's primary surface (URL prompt) but SKILL.md is loaded into context when `openclaw skills install totalreclaw` ran. Both must carry the rules so neither path is a bypass.
+- This RC does NOT yet ship the proper architectural fix for the 502 (HTTP-poll pair flow that doesn't require a persistent WS at all, planned for 3.3.11). It instead hardens the agent-side instructions so the existing `setsid -f` mechanism actually gets used.
+
 ## [3.3.10-rc.2] — 2026-05-05
 
 Critical 502 fix via shell-side detach (rc.10-rc.1's plugin-side `child_process` approach was reverted — scanner blocks `child_process` imports anywhere in the plugin tree). Pedro's manual QA on rc.4 confirmed the persistent 502 `gateway_disconnected` was NOT caused by relay idle close (PR #14's 5s+immediate WS keepalive was deployed and verified at sha `0ff812a`). Real cause: each `openclaw plugins install` writes `plugins.installs.totalreclaw.*` to the gateway config, triggering a deferred SIGUSR1 reload that eventually fires and kills any in-flight foreground subprocess — including the agent shell-tool's `node tr-cli pair --json` which holds the relay WS until the browser uploads the encrypted phrase.

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.10-rc.2
+version: 3.3.10-rc.3
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -46,6 +46,31 @@ If you find yourself about to say any of these, STOP. The correct statement is:
 
 **Emit ONLY the user-visible lines listed below. Do not narrate tool calls. Do not describe what you're doing or about to do. Errors are the only allowed deviation, and only as a single tight line.** The expected user-facing transcript for a healthy install is **4–5 short lines TOTAL**. Anything more is a SKILL violation. Telegram and similar transports edit the bot's messages live as your tool calls progress — every interim "Let me check…" / "Plugin loaded. Let me verify…" line shows up to the user as awkward edit churn, even if you "delete" it. The fix is to never emit it in the first place.
 
+## ⛔ FORBIDDEN — do NOT do these (3.3.10-rc.3, hard rules from Pedro's 2026-05-05 QA)
+
+These are the freelancing patterns that have broken pair flows and made transcripts noisy. They are FORBIDDEN, full stop:
+
+1. **Do NOT issue `/totalreclaw-restart`.** Do NOT send `kill -USR1`. Do NOT call `openclaw gateway restart`. Do NOT `docker restart`. The plugin auto-patches the gateway config and emits a single restart-required warn IF (and only if) the gateway needs one. The gateway will restart itself when its reload pipeline decides to. **You restarting it KILLS the in-flight `setsid -f` pair subprocess and surfaces as a 502 on the browser respond.**
+
+2. **Do NOT write to `~/.openclaw/openclaw.json`.** The plugin's `patchOpenClawConfig()` already wrote `plugins.slots.memory`, `plugins.entries.totalreclaw.hooks.allowConversationAccess`, and `channels.telegram.streaming.mode` for you. Any further config write triggers a fresh deferred reload that eventually fires SIGUSR1 and kills the pair subprocess. Forbidden tool calls: `openclaw config set …`, `jq … > openclaw.json`, any `cat > openclaw.json`, any `sed -i openclaw.json`.
+
+3. **Do NOT re-render the QR.** `tr pair --json` already returns the QR as `qr_ascii` (Unicode block chars) AND the pair page itself renders a real PNG QR. Do NOT save the QR to `/tmp/totalreclaw-pair-qr.png` — OpenClaw's media-access policy blocks `/tmp/` paths and Telegram delivery fails with `LocalMediaAccessError: Local media path is not under an allowed directory`. The agent's only QR responsibility is to copy the URL+PIN into user-visible line 3. The transport (Telegram/web/CLI) renders the QR from the URL the user can already click.
+
+4. **Do NOT invoke `tr pair --json` in the foreground.** A foreground pair subprocess is killed when your shell-tool exec returns (the agent runtime cleans up child PIDs). The pair WS dies → relay returns 502 on the browser respond. **The setup-flow Step 4 below uses `setsid -f` for exactly this reason — copy that block VERBATIM. Do not "simplify" it. Do not drop the `setsid -f`. Do not redirect stdout differently. Do not omit `< /dev/null`.**
+
+5. **Do NOT narrate.** Examples of narration that have appeared in past QAs and MUST NEVER appear again:
+   - "Now let me verify the CLI and check for existing credentials." → silent.
+   - "Gateway needs a restart to load the plugin. Let me restart it." → DO NOT RESTART.
+   - "The gateway is running but as a container process, not via systemd. Let me find and signal the gateway process to reload." → DO NOT SIGNAL.
+   - "The CLI is at the npm path, not the extensions path. Let me use the correct path." → silent (the `TR_CLI` resolver below already handles both paths).
+   - "Plugin is X.Y.Z, CLI reports itself as A.B.C (version string lag in the CLI binary)." → silent (don't reveal CLI internals).
+   - "Now let me also add the required post-install config and render the QR as an image." → DO NOT WRITE CONFIG. DO NOT RE-RENDER QR.
+   - "The pair response already has the QR data. Let me save the QR as a PNG using the existing skill's pair-qr module." → DO NOT SAVE QR ANYWHERE.
+
+If `tr status --json` returns version that disagrees with `openclaw plugins inspect totalreclaw`, **that is fine — do not narrate it**. The plugin's CLI reports its own packaged version which may lag the install record by one RC during a publish cycle. Both work.
+
+If you find yourself about to do anything in this list, STOP. Re-read this section. Then run the literal commands in the setup flow below — exactly as written.
+
 ## Hybrid-primary architecture (3.3.9-rc.1)
 
 OpenClaw 2026.5.2 has a tool-policy-pipeline bug (issue #223) that strips non-bundled plugin tools before they reach the agent toolset. **3.3.9-rc.1 makes the `tr` CLI the PRIMARY path for all memory operations.** Native tools (`totalreclaw_*`) are kept for back-compat with older OpenClaw versions where they work, but the agent MUST NOT depend on them. Use `tr` from your shell tool for everything.

package/dist/tr-cli.js

@@ -38,7 +38,10 @@ import { createApiClient } from './api-client.js';
 const CREDENTIALS_PATH = CONFIG.credentialsPath;
 const SERVER_URL = CONFIG.serverUrl;
 const STATE_PATH = CONFIG.onboardingStatePath;
-const PLUGIN_VERSION = '3.3.9-rc.1';
+// 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.10-rc.3';
 function die(msg, code = 1) {
     process.stderr.write(`tr: ${msg}\n`);
     process.exit(code);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.10-rc.2",
+  "version": "3.3.10-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/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "totalreclaw",
-  "version": "3.3.10-rc.2",
+  "version": "3.3.10-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

@@ -49,7 +49,10 @@ import { createApiClient } from './api-client.js';
 const CREDENTIALS_PATH = CONFIG.credentialsPath;
 const SERVER_URL = CONFIG.serverUrl;
 const STATE_PATH = CONFIG.onboardingStatePath;
-const PLUGIN_VERSION = '3.3.9-rc.1';
+// 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.10-rc.3';
 
 function die(msg: string, code = 1): never {
   process.stderr.write(`tr: ${msg}\n`);