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

package/CHANGELOG.md

@@ -4,6 +4,48 @@ 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.4] — 2026-05-06
+
+Address OpenClaw's own meta-feedback on the rc.10-rc.3 setup guide (collected during a clean retest run by Pedro). Two functional fixes alongside doc cleanup:
+
+### Fixed
+
+- **QR delivery regression on Telegram.** rc.10-rc.3's FORBIDDEN list correctly banned saving the QR PNG to `/tmp/totalreclaw-pair-qr.png` (which OpenClaw's media-policy rejected with `LocalMediaAccessError`), but the existing "Rendering the QR on your transport" SKILL.md section still pointed agents at a non-existent `qr_png_b64` field and a `qr_unicode` field — leftover from an older skill/native-tool surface. The agent skipped QR entirely rather than render the wrong field. Fix: the section is rewritten around the actual `qr_ascii` field that `tr pair --json` returns. Single recommended path: emit `qr_ascii` inside a triple-backticked code block above user-visible line 3. Renders as block-char QR in monospace font on Telegram, Slack, web, and terminal — every transport. No PNG, no save-to-disk, no media-policy interaction.
+
+- **`--force` install path.** OpenClaw QA fed back that `openclaw plugins install` fails on a re-run when the plugin is already on disk. Both the quickstart and the long setup guide now document the `--force` flag for this case.
+
+- **`tr status --json` retry-fail escalation.** Quickstart spells out a three-level escalation: 1st failure → sleep 5s + retry; 2nd → re-run install with `--force`; 3rd → emit a tight error line and stop. The previous "retry once after 5s" guidance left the agent stranded when retry also failed.
+
+### Changed
+
+- **New file `docs/guides/openclaw-setup-quickstart.md` (~5 KB)** — agent-executable contract: hard rules, four user-visible lines, copy-paste shell snippets. No rationale prose. SKILL.md's header now points agents at the quickstart first; the long `openclaw-setup.md` is the human-readable companion. The 28 KB `openclaw-setup.md` was burning context on every agent fetch — quickstart cuts that ~5×.
+
+- **SKILL.md FORBIDDEN section trimmed.** OpenClaw's feedback noted the rc.3 list was patching past failures one by one with verbatim narration examples that bloated the skill without adding rules. The list is now four crisp action-bans (no gateway restart, no config write, no QR PNG save, mandatory `setsid -f` for pair) — the narration ban is folded into the existing top-level "emit only the numbered user-visible lines" rule.
+
+- **`openclaw-setup.md` audience map at top.** Explicit three-audience map (humans, agents, QA / Pedro) with cross-link to the quickstart, so agents that fetched the long URL by accident know to switch.
+
+### Implementation notes
+
+- `qr_ascii` already exists in `pair-cli-relay.ts` `PairCliJsonPayload`. No CLI change required.
+- The legacy SKILL.md QR-rendering section referenced the older native-`totalreclaw_pair` tool's payload shape (`qr_png_b64`, `qr_unicode`). The native tool surface is unchanged for back-compat — but it's deprioritized in 3.3.9-rc.1+ (issue #223 strips it). Hybrid CLI is now the documented path, and CLI returns `qr_ascii` only.
+- This RC is doc + SKILL.md only — no code changes. Same `tr-cli.js` binary as rc.3.
+
+## [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.4
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -24,7 +24,11 @@ metadata:
 
 # TotalReclaw — OpenClaw
 
-> The canonical install flow lives at <https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/openclaw-setup.md>. If a user pastes that URL in chat, fetch it and follow its agent-instructions section. This SKILL.md mirrors the same steps so you can act even if the URL is unreachable.
+> **Agent-executable quickstart (5 KB, copy-paste-runnable)**: <https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/openclaw-setup-quickstart.md>
+>
+> **Human-readable setup guide (full rationale, troubleshooting)**: <https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/openclaw-setup.md>
+>
+> If the user pastes either URL: prefer the quickstart for execution. Fetch the full guide only if the user asks for context or troubleshooting beyond what the quickstart covers. This SKILL.md mirrors the quickstart's hard rules so you can act even if the URL is unreachable.
 
 ## CRITICAL: Relay-based architecture (read before anything else)
 
@@ -46,6 +50,18 @@ 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 ACTIONS (4 hard rules from 2026-05-05 QA)
+
+These specific actions break the pair flow. Everything else is governed by the "emit only the numbered user-visible lines" rule above.
+
+1. **Do NOT restart the gateway.** No `/totalreclaw-restart`, no `kill -USR1`, no `docker restart`, no `openclaw gateway restart`. The plugin self-patches and signals its own restart needs. You restarting it kills the in-flight `setsid -f` pair subprocess → 502 on browser respond.
+
+2. **Do NOT write to `~/.openclaw/openclaw.json`.** The plugin's `patchOpenClawConfig()` already wrote `plugins.slots.memory`, `plugins.entries.totalreclaw.hooks.allowConversationAccess`, `channels.telegram.streaming.mode`. Any further write triggers a deferred SIGUSR1 reload that kills pair. No `openclaw config set …`, no `jq …>openclaw.json`, no `sed -i openclaw.json`.
+
+3. **Do NOT save QR PNGs.** `tr pair --json` returns `qr_ascii` — emit that inline in a triple-backticked code block. No `/tmp/totalreclaw-pair-qr.png` (OpenClaw media-policy blocks it: `LocalMediaAccessError`). No PNG decode. No `qr_png_b64` (legacy field, no longer exists in payload).
+
+4. **`tr pair --json` MUST run via `setsid -f`** (exact form below). Foreground invocation is killed when your shell-tool exec returns → 502.
+
 ## 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.
@@ -137,13 +153,21 @@ node "$TR_CLI" recall --json "where does the user work" --limit 5
 
 **Note on tool names**: `totalreclaw_remember`, `totalreclaw_recall`, etc. may or may not appear in your toolset depending on OpenClaw version. Under hybrid-primary, you use the `tr` CLI instead. If native tools ARE available (older OpenClaw or future OC fix), they work too — but always prefer `tr` for reliability.
 
-## Rendering the QR on your transport (rc.5+)
+## Rendering the QR on your transport (3.3.10-rc.4 — corrected)
+
+`tr pair --json` returns a `qr_ascii` field — Unicode block-char QR (43 lines × ~43 cols). That is the ONLY QR field in the payload. The legacy `qr_png_b64` and `qr_unicode` field names referenced by older skill docs no longer exist.
+
+The simplest path that works on every transport (Telegram, Slack, web, terminal SSH): emit `qr_ascii` INLINE inside a triple-backtick code block right above user-visible line 3. Block-char QR renders correctly in monospace fonts on every modern transport — the user scans from their phone. The pair PAGE itself renders a real PNG QR alongside, so users on a desktop browser see both.
+
+Format the line-3 message as:
+
+```
+<qr_ascii contents — 43 lines of ▄▀█▄▀█ block chars>
+```
 
-When you receive the `totalreclaw_pair` payload (from tool OR `tr pair --json`), render the QR based on your chat transport:
+Open <url> in your browser. Enter PIN <pin>. Generate or paste a 12-word recovery phrase. Reply `done` once it's sealed.
 
-- **Transport supports image attachments** (Telegram, Slack, web chat, any transport with file/image upload): decode `qr_png_b64` from base64 to bytes, save to a tempfile with a `.png` suffix, and attach the tempfile as an image. Also show the URL + PIN as text so users who prefer clicking can still do so.
-- **Terminal-only transport** (OpenClaw native CLI chat, bare SSH shell): emit `qr_unicode` inline in your reply. It renders as block characters in most terminal fonts; the user scans from their phone.
-- **Web chat with inline-image support**: embed as `<img src="data:image/png;base64,<qr_png_b64>" alt="TotalReclaw account-setup QR">` if the chat client renders HTML; otherwise fall back to attachment.
+Do NOT decode `qr_png_b64` (does not exist), do NOT save a PNG to `/tmp/totalreclaw-pair-qr.png` (`LocalMediaAccessError` blocks delivery), do NOT re-render the QR through any other library. The `qr_ascii` field is the single source of truth.
 
 The QR encodes ONLY the account-setup URL. The 6-digit PIN is a separate out-of-band confirmation — deliberately NOT baked into the QR (dual-channel design: scan + type). Never log, print, or re-emit the PIN outside the user-facing reply. The PIN must NOT end up in any other tool call, log file, or memory store.
 

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.4';
 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.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/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "totalreclaw",
-  "version": "3.3.10-rc.2",
+  "version": "3.3.10-rc.4",
   "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.4';
 
 function die(msg: string, code = 1): never {
   process.stderr.write(`tr: ${msg}\n`);