@totalreclaw/totalreclaw 3.3.9-rc.4 → 3.3.10-rc.3

package/CHANGELOG.md

@@ -4,6 +4,42 @@ 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.
+
+### Fixed
+
+- **`tr pair` invocation now uses shell-side `setsid -f` for session detachment.** SKILL.md and the public OpenClaw setup guide instruct the agent to spawn `tr pair --json` via `setsid -f` so the WS-holding subprocess is in its own POSIX session, untethered from the agent shell-tool's process group. The pair process survives any subsequent gateway SIGUSR1 reload, and the URL+PIN payload is captured to a tmp file the moment the WS handshake completes (~100-500ms typical). Verified live on pop-os 2026-05-05: `setsid -f node tr-cli.js pair --json > /tmp/...` returned exit 0 immediately, the detached `node tr-cli pair --json` process kept running across a `kill -USR1 1` to PID 1 in the container, and the URL+PIN was readable from the tmp file at +2s.
+
+  This needs no plugin-code change — it's a shell-side mechanism the agent uses when invoking the existing CLI. The plugin tree stays free of `child_process` imports (which would trip OpenClaw's runtime scanner same as the 3.3.2-era `postinstall.mjs` block).
+
+- **CLI install path corrected for OpenClaw 2026.5.x.** SKILL.md and `docs/guides/openclaw-setup.md` previously referenced `~/.openclaw/extensions/totalreclaw/dist/tr-cli.js` exclusively. Modern OpenClaw 2026.5.x npm-managed plugins install under `~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/...` (verified via `openclaw plugins inspect totalreclaw` → "Install path: ~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw"). Both paths now appear in the recommended `TR_CLI` resolver:
+  ```bash
+  TR_CLI="$(ls -d ~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cli.js ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js 2>/dev/null | head -1)"
+  ```
+  Resolver picks the first existing path, so the agent works on both modern and legacy installs without per-version branching.
+
+### Reverted
+
+- **3.3.10-rc.1 plugin-side `child_process` detach** — scanner-sim blocked the publish on `import { spawn } from 'node:child_process'` in `tr-cli.ts`. OpenClaw's runtime scanner (which inspects the full tarball regardless of file role — same rule that killed `postinstall.mjs` in 3.3.2) would have blocked install at the user's gateway even if the publish had been bypassed. rc.10-rc.2 takes the equivalent detach via shell-side `setsid -f`, which OpenClaw's exec subsystem treats as a normal shell command.
+
 ## [3.3.9-rc.4] — 2026-05-05
 
 Defensive patch hardening `patchOpenClawConfig()` Fix #1 against a startup crash loop observed on Pedro's pop-os QA host on 2026-05-05.

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.9-rc.4
+version: 3.3.10-rc.3
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -46,12 +46,45 @@ 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.
 
-**The `tr` binary is installed at:** `~/.openclaw/extensions/totalreclaw/dist/tr-cli.js`
-**Always invoke via:** `node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js <cmd> [--json]`
+**The `tr` binary is installed at one of two paths depending on OpenClaw version:**
+- Modern (2026.5.x npm-managed): `~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cli.js`
+- Legacy (extensions tree): `~/.openclaw/extensions/totalreclaw/dist/tr-cli.js`
+
+**Resolve the path once at the top of your shell session and reuse:**
+```bash
+TR_CLI="$(ls -d ~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cli.js ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js 2>/dev/null | head -1)"
+```
+Then invoke as `node "$TR_CLI" <cmd> [--json]`.
+
 **Never rely on `totalreclaw_*` tool binding** — it may not be available due to issue #223.
 
 ## User-visible line set (THIS IS ALL YOU SAY)
@@ -81,41 +114,49 @@ If existing credentials are detected (step "Check for existing credentials" belo
 
    If either shell call fails with `command not found` / ENOENT / "not authorized" (managed-service or shell-restricted environment), tell the user verbatim *"Your environment doesn't expose the OpenClaw CLI to me. Please install `totalreclaw` from your service's plugins / skills UI, then reply `done`."* Wait for `done` and skip to step 3.
 
-2. **Verify CLI works — emit user-visible line 2 when successful.** Run:
-   ```
-   node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js status --json
+2. **Verify CLI works — emit user-visible line 2 when successful.** Resolve `TR_CLI` and run:
+   ```bash
+   TR_CLI="$(ls -d ~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cli.js ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js 2>/dev/null | head -1)"
+   node "$TR_CLI" status --json
    ```
    Parse the JSON. When you get `{"version": "...", "hybrid_mode": true, ...}`, emit user-visible line 2 with the version substituted. **Do NOT wait for tool binding. Do NOT issue `/totalreclaw-restart`. Do NOT check whether `totalreclaw_pair` is in your toolset.** The CLI works independently of tool binding. If `tr status` exits non-zero or the file doesn't exist, wait 5s and retry once — it may still be installing.
 
 3. **Check for existing credentials (silent unless found).** Run `test -s ~/.totalreclaw/credentials.json`. If it exists and is non-empty, emit *"✓ TotalReclaw is already set up."* and stop.
 
-4. **Set up the user's TotalReclaw account IMMEDIATELY — no consent gate.** As soon as `tr status --json` returns and credentials are not present, run:
+4. **Set up the user's TotalReclaw account IMMEDIATELY — no consent gate.** As soon as `tr status --json` returns and credentials are not present, run pair in DETACHED mode. CRITICAL: a foreground `node tr-cli pair` is killed when the gateway fires its post-install SIGUSR1 reload (3.3.10 finding from Pedro's 2026-05-05 QA — relay logs `gateway_disconnected` 502 on `/respond`). Use `setsid -f` so the pair process is in its own session and survives any subsequent gateway SIGUSR1 reload. The handshake URL+PIN is written to a tmp file the moment the WS opens (~100-500ms typical):
+   ```bash
+   PAIR_OUT="/tmp/tr-pair-out-$(date +%s).json"
+   setsid -f node "$TR_CLI" pair --json > "$PAIR_OUT" 2>&1 < /dev/null
+   sleep 2
+   cat "$PAIR_OUT"
    ```
-   node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js pair --json
-   ```
-   This is UNCONDITIONAL. Do NOT ask "Would you like to set up an account?" or "Want me to pair now?". The user installed TotalReclaw — setup is the expected next step. The URL + PIN itself is the consent moment (the user can simply not open the page to opt out). Parse the JSON response `{"url": "...", "pin": "...", "expires_at": "..."}` and emit user-visible line 3. If `tr pair --json` is not available (old install), fall back to `totalreclaw_pair` tool or `openclaw totalreclaw pair generate --url-pin-only`.
+   This is UNCONDITIONAL. Do NOT ask "Would you like to set up an account?" or "Want me to pair now?". The user installed TotalReclaw — setup is the expected next step. The URL + PIN itself is the consent moment (the user can simply not open the page to opt out). Parse the JSON response `{"url": "...", "pin": "...", "expires_at_ms": ...}` and emit user-visible line 3. If the cat output is empty after 2s, sleep 2 more seconds and try again (relay handshake can take up to 4s on a cold network). If `tr pair --json` is not available (old install), fall back to `totalreclaw_pair` tool or `openclaw totalreclaw pair generate --url-pin-only`.
 
-5. **Verify and confirm (silent until line 4).** After the user says `done`, re-run `test -s ~/.totalreclaw/credentials.json`. If missing, the PIN expired — run `tr pair --json` again and resend line 3 once. If present, emit user-visible line 4 and stop.
+5. **Verify and confirm (silent until line 4).** After the user says `done`, re-run `test -s ~/.totalreclaw/credentials.json`. If missing, the PIN expired — repeat the `setsid -f node "$TR_CLI" pair --json` block and resend line 3 once. If present, emit user-visible line 4 and stop.
 
 ## `tr` CLI reference (hybrid-primary commands)
 
 Always use `--json` flag when running from shell for machine-parseable output. Plain text mode is for direct user invocation only.
 
 ```bash
+# (Resolve TR_CLI once at the top of your session)
+TR_CLI="$(ls -d ~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cli.js ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js 2>/dev/null | head -1)"
+
 # Status check (parse JSON to confirm install + onboarding state)
-node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js status --json
-# Returns: {"version":"3.3.9-rc.1","onboarded":false,"next_step":"pair","tool_count":17,"hybrid_mode":true}
+node "$TR_CLI" status --json
+# Returns: {"version":"3.3.10-rc.2","onboarded":false,"next_step":"pair","tool_count":17,"hybrid_mode":true}
 
-# Pair / account setup
-node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js pair --json
-# Returns: {"url":"https://...","pin":"123456","expires_at":"2026-05-05T..."}
+# Pair / account setup — ALWAYS run via setsid -f to survive gateway restarts
+PAIR_OUT="/tmp/tr-pair-out-$(date +%s).json"
+setsid -f node "$TR_CLI" pair --json > "$PAIR_OUT" 2>&1 < /dev/null && sleep 2 && cat "$PAIR_OUT"
+# Returns: {"v":1,"sid":"...","url":"https://...","pin":"123456","mode":"generate","expires_at_ms":...,"qr_ascii":"..."}
 
-# Remember a fact
-node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js remember --json "I work at Graph Foundation"
+# Remember a fact (foreground OK — non-blocking single-shot HTTP call)
+node "$TR_CLI" remember --json "I work at Graph Foundation"
 # Returns: {"ok":true,"id":"...","claim_count":N}
 
 # Recall memories
-node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js recall --json "where does the user work" --limit 5
+node "$TR_CLI" recall --json "where does the user work" --limit 5
 # Returns: {"results":[{"text":"...","score":0.8},...]}
 ```
 
@@ -138,12 +179,12 @@ NEVER echo / generate / ask the user to paste a recovery phrase in chat. NEVER i
 ## Usage (post-setup)
 
 - Stable user facts / preferences / identity / "remember X":
-  ```
-  node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js remember --json "<fact>"
+  ```bash
+  node "$TR_CLI" remember --json "<fact>"
   ```
 - First-person factual query ("do I / what's my / where do I…"):
-  ```
-  node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js recall --json "<query>" --limit 5
+  ```bash
+  node "$TR_CLI" recall --json "<query>" --limit 5
   ```
   Recall FIRST, then answer from returned facts. If 0 results, say so.
 - For forget / pin / unpin / retype / set_scope — use native tools if available, or ask user to run `openclaw totalreclaw` subcommand.

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.9-rc.4",
+  "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.9-rc.4",
+  "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`);