@totalreclaw/totalreclaw 3.3.12-rc.2 → 3.3.12-rc.20

package/CHANGELOG.md

@@ -4,6 +4,32 @@ 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.12-rc.5] — 2026-05-09
+
+Final RC for the 3.3.12 stable promote. Behavioral fix: Pedro's Pop-OS Telegram QA (zai/glm-5-turbo) on rc.4 found the agent storing user statements in `MEMORY.md` / `USER.md` via `write` tool calls instead of calling `totalreclaw_remember`. 28 `write` calls observed in one session, 0 TotalReclaw tool calls — facts never reached the chain. Root cause: SKILL.md trigger language was permissive ("call when the user asks") and the agent's default file-write reflex won out. rc.5 makes the memory-storage rule the TOP RULE of SKILL.md with an explicit prohibition on `write`/`edit` against `MEMORY.md`/`USER.md`, an exhaustive trigger-phrase list (preference / identity / decision / commitment / possessive-assertion patterns), and a multi-fact-per-message instruction so blob-style packing does not happen.
+
+### Changed
+
+- **SKILL.md TOP RULE rewrite — aggressive triggers, no MEMORY.md fallback.** Memory storage section moved to the very top of SKILL.md (before architecture, vocabulary, install flow). Adds: (1) absolute prohibition on `write`/`edit` against `MEMORY.md` / `USER.md` / `~/.claude/memory/*.md`; (2) trigger-phrase list covering preferences, identity, tools, decisions, commitments, explicit asks, possessive assertions; (3) multi-fact-per-message rule (split into one `totalreclaw_remember` call per atomic fact); (4) full 17-tool reference table with canonical use cases; (5) restart policy reaffirmed (gateway self-restarts via SIGUSR1; agent NEVER prompts user to manually restart); (6) phrase-safety hard rail (no phrase in chat / no phrase as tool input / browser-side only).
+- **Public quickstart guide audit** (`docs/guides/openclaw-setup-quickstart.md`) — already prose-style + clean from rc.6 revert. No edits required.
+- **Long-form setup guide cleanup** (`docs/guides/openclaw-setup.md`) — F-flip default URL corrected (`api.totalreclaw.xyz` for free tier, staging via env override; previous text said the relay was `api-staging.*`); line 1 wording aligned with SKILL.md (`Setting up TotalReclaw — this takes about a minute…`); legacy `qr_png_b64` / `qr_unicode` references replaced with `qr_ascii` (the only QR field in the current pair payload); manual restart fallback (`openclaw gateway restart` / `docker restart`) deemphasized — the plugin self-restarts via SIGUSR1; RC pin examples bumped from `3.3.11-rc.5` to `3.3.12-rc.5`.
+- **Version sync** — package.json, skill.json, SKILL.md frontmatter, tr-cli.ts PLUGIN_VERSION all aligned to 3.3.12-rc.5 via `sync-version.mjs`. `check-version-drift` green.
+
+### Verified
+
+- All 38 test suites pass (manifest-shape, config-schema, config, relay-headers, scope-address-visible, llm-profile-reader, llm-client (×2), gateway-url, retype-setscope, tool-gating, onboarding-noninteractive, pair-cli-json, pair-qr, pair-remote-client, qa-bug-report, nonce-serialization, phrase-safety-registry, onnx-download-ux, onboard-pair-only, import-time-smoke, install-staging-cleanup, partial-install-detection, install-reload-idempotency, json-stdout-cleanliness, load-manifest, url-binding, fs-helpers, pair-cli-default-mode, embedding-fallback-tag, staging-banner-gate, restart-auth, inbound-user-tracker, register-command-name, skill-md-hybrid-primary, tr-cli-json-output).
+- `check-scanner` green (0 flags).
+- `check-version-drift` green (3 sites + tr-cli.ts all = 3.3.12-rc.5).
+- E2E on clean OpenClaw 2026.5.7 container — agent given `"Hi, I'm Pedro. I live in Porto. I prefer PostgreSQL over MySQL."` calls `totalreclaw_remember` ≥1 time, with 0 `write`/`edit` calls against `MEMORY.md` / `USER.md`. (See PR description for the captured `toolSummary` JSON.)
+
+### Out of scope (unchanged from rc.4)
+
+- Plugin install lifecycle on OpenClaw 2026.5.7 (auto-QA PASS — plugin loads, SIGUSR1 self-restart works, in-process restart, managed-service-friendly).
+- `tr` CLI on-chain memory ops (rc.4 fix verified).
+- Pair flow (browser-side phrase, no leakage).
+- Trajectory poller (auto-extraction backup).
+- F flip (RC + stable both default to prod URL; staging via env override).
+
 ## [3.3.12-rc.2] — 2026-05-08
 
 Hot-fix on rc.1's F flip. Pair flow regression: rc.1 set `pairRelayUrl`'s default to `wss://api.totalreclaw.xyz` (production) independently of `serverUrl`. RC users who set `TOTALRECLAW_SERVER_URL=https://api-staging.totalreclaw.xyz` (per the staging-opt-in flow) had pair WS go to **prod**, which pre-dates the pair feature → 404 on WS upgrade → `totalreclaw_pair failed: Unexpected server response: 404`. End-to-end blocker: pair never completed → no credentials → no memories.

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.12-rc.2
+description: "End-to-end encrypted, decentralized memory for OpenClaw. A native kind:memory provider — recall is automatic via memory_search/memory_get, and facts are captured in the background. Trigger on 'install TotalReclaw', 'set up TotalReclaw', 'restore my recovery phrase', any recall request ('what do you remember about me', 'what's my X'), AND any explicit remember request ('remember X', 'save X')."
+version: 3.3.12-rc.20
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -22,276 +22,61 @@ metadata:
       - persistent-context
 ---
 
-# TotalReclaw — OpenClaw
+# TotalReclaw — OpenClaw native memory provider
 
-> **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.
+End-to-end encrypted memory stored across a decentralized network (not on a single company server). TotalReclaw is OpenClaw's **native `kind:"memory"` provider**: recall runs through the conventional `memory_search` / `memory_get` tools (the same surface `active-memory` uses), and **facts are captured automatically in the background** — you do not call a tool to remember each fact. This skill tells you the install + account-setup flow and when to drive recall explicitly.
 
-## CRITICAL: How TotalReclaw actually stores memories (read before anything else)
+## How memory works here (read first)
 
-**TotalReclaw is end-to-end encrypted memory stored across a DECENTRALIZED NETWORK — not on a single company server.** Memories are encrypted with keys derived from the user's 12-word recovery phrase, submitted as Account Abstraction UserOps, and persisted on a public blockchain (Base / Gnosis depending on tier). The Graph subgraph indexes them. The TotalReclaw relay only forwards encrypted bundles to the bundler and proxies subgraph reads — it never sees plaintext, can't read memories, and could be replaced by any compatible relay without losing data. No single company controls or can read user memories.
+- **Recall is native.** `memory_search` and `memory_get` are the memory tools. OpenClaw's `active-memory` sub-agent routes recall through them and the plugin injects guidance telling you when to search. When the user asks about themselves ("what's my X?", "do I X?", "what do you remember?"), call `memory_search`. If 0 results, say so plainly — don't guess from session history.
+- **Capture is automatic.** The plugin extracts facts from the conversation in the background (trajectory poller). You do **not** call a tool on every preference/fact the user states — that happens for you. Never write user facts to `MEMORY.md`, `USER.md`, or any local file; those are agent-persona config, user memories live encrypted on-chain.
+- **Explicit remember only on request.** If the user explicitly says "remember X" / "save X" / "note X" / "don't forget X", use the CLI: `tr remember --json "X"`. One call per distinct fact.
 
-Forbidden vocabulary — these claims are WRONG (some imply local-only storage; some imply a single-company server):
-- "local", "local-only", "stored locally", "on disk", "local memory", "local storage" — wrong direction (implies local-only). Memories require an account; they're encrypted and submitted on-chain.
-- "stored on a relay server", "stored on TotalReclaw's server", "single server owned by", "TotalReclaw stores your", "company server" — wrong direction (implies centralized custody). The relay forwards ciphertext; storage is decentralized on-chain.
-- "without an account" — wrong (an account is required to derive the encryption key).
+Do not describe storage as `"local"`, `"local-only"`, `"stored locally"`, `"on disk"`, or `"without an account"` — memories are decentralized on-chain (not on any single company server) and an account is required to derive the encryption key.
 
-If you need to describe how it works, the canonical line is: **"Memories are encrypted with a key derived from your recovery phrase, submitted on-chain via Account Abstraction, and stored across a decentralized network. The relay only forwards encrypted bundles — it never sees plaintext. Only you can decrypt them, and only with your recovery phrase."**
+## Phrase safety (HARD)
 
-## User-facing vocabulary (substitute internal jargon for plain words)
+The 12-word recovery phrase MUST NEVER enter chat or the agent's LLM context. The plugin's browser-based pair flow handles phrase generation and import. Never echo it, never ask the user to paste it, never pass it to any tool. If the user pastes one anyway, tell them it's compromised and re-pair for a fresh wallet.
 
-Internal terms that the user does NOT know — translate when you must speak:
+**HARD guardrail — install/reinstall/upgrade flows:** During install, reinstall, upgrade, or any verification steps, the agent MUST NOT read, list, cat, show, display, or inspect `credentials.json`, `~/.totalreclaw/credentials.json`, `~/.totalreclaw*/credentials.json`, `~/.openclaw/plugins/totalreclaw/credentials.json`, or ANY credentials/phrase/key/secrets file — for ANY reason, including "verifying the install." These files contain encryption key material and Smart Account addresses that MUST NOT enter the LLM context. Never run `ls`, `find`, `cat`, `show`, or similar commands against plugin directories to "check files."
 
-| Internal term | Say to the user |
-|---|---|
-| pair / pairing / paired account | "set up an account" / "your TotalReclaw account" |
-| relay / relay server | (don't mention; if forced, say "the encrypted-bundle forwarder") |
-| WS / WebSocket / handshake | (don't mention) |
-| trapdoor / blind index / dedup-key | (don't mention) |
-| subgraph / bundler / UserOp / Account Abstraction | (don't mention; if forced, "submitted on-chain to a decentralized network") |
-| credentials.json / mnemonic file | "your recovery phrase" |
-| `tr pair --json` / `setsid -f` / shell exec | (don't mention; just do the work silently) |
+## Install
 
-The word "pair" is internal jargon — never use it in user-visible prose. The user-visible vocabulary is "set up an account", "your account", "your recovery phrase", "your memories".
-
-## Top-level rule (read this before anything else)
-
-**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.
-
-### ⚡ MANDATORY ACK BEFORE FIRST TOOL CALL
-
-**User-visible line 1 MUST be your FIRST output — emitted BEFORE you run any shell tool, plugin install, or `tr` command.** Install + setup takes 1–2 minutes of silent tool-execution; without an immediate ack the user assumes the request didn't register and may resend or abandon. The ack tells them work is happening.
-
-The ack is unconditional. It fires the moment you decide to install / set up TotalReclaw — even before you've resolved `TR_CLI`, even before you've checked whether the plugin is already installed, even before the first `openclaw plugins install` shell call. Send line 1, THEN start the work.
-
-Forbidden order (silent-then-narrate): ❌ run `openclaw plugins install` → wait 60s → emit line 1.
-Required order (ack-then-work): ✅ emit line 1 → run `openclaw plugins install` silently → emit line 2 when `tr status` returns.
-
-## ⛔ 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.
-
-**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)
-
-Speak only these lines, in order. Substitute the bracketed placeholders with the real values. No prefaces. No suffixes. No narration.
-
-1. (FIRST output, emitted BEFORE any shell tool call — see "MANDATORY ACK" rule above)
-   > Setting up TotalReclaw — this takes about a minute…
-2. (after install + CLI verify — `tr status` works)
-   > ✓ Installed (totalreclaw &lt;version&gt;, hybrid mode)
-3. (account-setup URL + PIN, IMMEDIATELY after `tr pair --json` returns — no consent gate)
-   > Open &lt;url&gt; in your browser. Enter PIN &lt;pin&gt;. Generate or paste a 12-word recovery phrase. Reply `done` once it's sealed.
-4. (done + free-tier confirmation)
-   > ✓ You're set up on the TotalReclaw free tier — 500 memories/month, unlimited reads. https://totalreclaw.xyz/pricing. Ask me to remember anything.
-
-If existing credentials are detected (step "Check for existing credentials" below), emit ONLY this line and stop:
-   > ✓ TotalReclaw is already set up.
-
-### Hard silence rules between numbered lines
-
-Do NOT emit transitional / narrative lines between any of the four user-visible lines above. Specifically forbidden (verbatim examples from Pedro's 2026-05-06 QA):
-
-- ❌ "Now let me verify the install:" → silent. Just run `tr status --json`. Emit line 2 when it returns.
-- ❌ "Now let me check if you already have credentials:" → silent. Just run `test -s ~/.totalreclaw/credentials.json`.
-- ❌ "Need to pair. Let me kick that off:" → silent. Just run the `setsid -f` block. Emit line 3 when URL+PIN returns. ALSO never use the word "pair" in user-facing text — see vocabulary table above.
-- ❌ "Standing by." → silent. Acknowledgements between lines are noise.
-- ❌ Any "Let me X" / "Now I'll Y" / "Just give me a second" prelude.
-- ❌ **Skipping line 1 entirely and going straight to shell tool calls.** Line 1 ack must precede the first tool call. Silent install = user thinks the prompt didn't register.
-
-The transcript Pedro should see is exactly four messages — the four numbered lines, nothing in between. Line 1 fires immediately. Lines 2–4 fire as work completes. No prose between.
-
-## How does TotalReclaw work? (canonical answer for user questions)
-
-When the user asks "how does this work?" / "where are my memories stored?" / "is this safe?" / similar — answer with this content. Do NOT say "stored on a relay server", "stored on TotalReclaw's server", or any phrasing that implies single-company custody. The actual architecture:
-
-> **End-to-end encrypted, decentralized memory.** When you tell me to remember something, I encrypt it locally with a key derived from your 12-word recovery phrase, then submit it on-chain via Account Abstraction (a UserOperation). It lives on a public blockchain (Base Sepolia for free tier, Gnosis mainnet for paid). The Graph subgraph indexes it for fast retrieval. The TotalReclaw relay server only forwards encrypted bundles between your client and the chain — it never sees plaintext, can't read your memories, and could be replaced by any compatible relay without losing data. Your recovery phrase is the only thing that can decrypt the memories. Nobody (not me, not TotalReclaw the company, not the relay operator) can read them without it.
-
-If the user asks shorter questions, reply with the relevant slice:
-
-- **"Where are memories stored?"** → "Encrypted, on-chain (Base or Gnosis depending on your tier), indexed by The Graph. Not on any single company's server."
-- **"Is the relay reading my data?"** → "No. The relay only forwards encrypted bundles. Plaintext never leaves your device. Only your recovery phrase can decrypt them."
-- **"What if TotalReclaw shuts down?"** → "Your memories survive. They're on a public blockchain. Any compatible relay (or self-hosted relay) can read them with your recovery phrase."
-
-## Setup flow (hybrid-primary)
-
-1. **Install plugin first, skill second (silent — emit user-visible line 1 once at the start, then no prose until line 2).** Run via your shell tool, in this exact order:
-   ```
-   openclaw plugins install @totalreclaw/totalreclaw
-   openclaw skills install totalreclaw
-   ```
-   For RC: replace the first command with `openclaw plugins install @totalreclaw/totalreclaw@rc`. **Plugin BEFORE skill is deliberate** (3.3.4-rc.1 — issue from Pedro's QA on rc.3): the skill install triggers a config-driven SIGUSR1 gateway reload that can race a concurrent plugin install.
-
-   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.** 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.
+openclaw plugins install @totalreclaw/totalreclaw
+openclaw skills install totalreclaw
+```
 
-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.
+Published on npm + ClawHub (`p-diogo`, GitHub-verified). For a release candidate, pin with `@rc`; stable resolves from `latest`. The plugin self-applies any gateway config it needs on load and auto-reloads (see Restart below) — no manual gateway restart.
 
-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"
-   ```
-   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`.
+## Setup (pair — user-initiated QR)
 
-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.
+Pairing is a deliberate, user-initiated QR flow (the plugin does **not** auto-pair on load). When credentials don't exist:
 
-## `tr` CLI reference (hybrid-primary commands)
+1. Run `tr pair --json` → returns `{"url":"https://…/pair/p/<id>#pk=…","pin":"123456","expires_at_ms":…}`.
+2. Surface the **url** and **pin** to the user verbatim (read from the JSON; never invent values): "Open `<url>` in your browser, enter PIN `<pin>`, and generate or paste your 12-word recovery phrase. Reply done once it's sealed."
+3. The user completes in the browser (phrase is generated/imported browser-side, encrypted, posted to the relay — never touches this chat). On completion `~/.totalreclaw/credentials.json` is written.
+4. Confirm: `✓ TotalReclaw set up.` (If credentials already exist when first asked: `✓ TotalReclaw is already set up.`)
 
-Always use `--json` flag when running from shell for machine-parseable output. Plain text mode is for direct user invocation only.
+Pair is UNCONDITIONAL when no credentials — the user installing/requesting setup IS the consent; do not add a second consent gate. `tr --help` lists every subcommand.
 
 ```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 "$TR_CLI" status --json
-# Returns: {"version":"3.3.11-rc.1","onboarded":false,"next_step":"pair","tool_count":17,"hybrid_mode":true}
-
-# 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 (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 "$TR_CLI" recall --json "where does the user work" --limit 5
-# Returns: {"results":[{"text":"...","score":0.8},...]}
+node "$TR_CLI" pair --json        # start/re-pair
+node "$TR_CLI" status --json      # {"version":"…","paired":true,…}
 ```
 
-**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 (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>
-```
+## Restart (agent-driven, never user-manual)
 
-Open <url> in your browser. Enter PIN <pin>. Generate or paste a 12-word recovery phrase. Reply `done` once it's sealed.
+The plugin self-reloads: after install it writes the gateway config it needs and signals `SIGUSR1` to its own PID so the gateway picks it up without a manual restart. **If `memory_search`/`memory_get` are not bound** (tools didn't take effect on first load), issue the literal slash command `/totalreclaw-restart` **autonomously** — announce it in one line, never ask the user to authorize it, never stall, never `kill` / `docker restart` / prompt the user to restart. This mirrors the autonomous-restart pattern other runtimes use; the user should never perform a manual restart.
 
-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.
+## Tools + CLI surface
 
-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.
-
-## Browser flow context (know it, narrate only on user question)
-
-After you emit user-visible line 3, the user opens the URL on their phone or desktop browser. They walk through a 3-step wizard before the relay forwards the encrypted phrase to the plugin. You don't narrate this proactively (silence rules). But you MUST know it so you can answer questions and recover from issues:
-
-1. **Step 1 of 3 — Enter your PIN.** Six PIN cells. The user types or pastes the 6-digit PIN you sent in line 3. "Continue" is disabled until all 6 digits match. There's a 10-minute countdown displayed in the corner.
-2. **Step 2 of 3 — Your recovery phrase.** Two tabs: **Set up** (default — generates a fresh 12-word BIP-39 phrase locally in the browser) and **Log in** (paste an existing phrase to restore on a new device). User must check **"I've written this down and stored it somewhere safe"** then click **Set up TotalReclaw**.
-3. **Step 3 of 3 — You're all set.** Confirmation screen with a "Close this page" link. The browser already POSTed the encrypted phrase by this point — the relay forwards to your gateway, the plugin decrypts, writes `~/.totalreclaw/credentials.json`, and your `awaitPhraseUpload` resolves.
-
-Common user-side issues during pair (recover gracefully — emit ONE tight line, don't pre-narrate):
-
-- **"The page won't load"** → confirm the URL host is `api.totalreclaw.xyz` (the default for both stable and RC post-3.3.12-rc.1). If a `TOTALRECLAW_SERVER_URL` env override was set, the host might be `api-staging.totalreclaw.xyz` (staging, opt-in) or a self-hosted relay. Wrong stub host → generate a fresh URL.
-- **"PIN says expired"** or countdown ran out → re-run the pair block (Step 4 above) and emit line 3 again with the fresh URL+PIN. The previous session is dead.
-- **"It says invalid phrase"** during Log in → the user pasted a phrase that isn't BIP-39 valid (typo or wrong source). Tell them to double-check and re-paste; or switch to **Set up** tab to generate a fresh one (loses existing memories).
-- **"I clicked Set up TotalReclaw but nothing happened"** / **502** → the gateway WS dropped before respond. The pair subprocess is alive (you used `setsid -f`). Wait 30s; if the user still sees the 502, re-run Step 4 (the deferred reload should have completed by then).
-- **"Where do I write down the phrase?"** → tell them: anywhere safe and durable — paper, password manager, encrypted note. NOT in this chat. NOT in a screenshot to cloud-synced photos. The phrase IS the account; losing it means losing all memories.
-
-## Phrase safety (HARD — never break)
-
-NEVER echo / generate / ask the user to paste a recovery phrase in chat. NEVER invoke `openclaw totalreclaw onboard` (bare interactive form), `totalreclaw setup`, or any phrase-touching CLI via your shell tool (stdout enters LLM context). The ONLY agent-facilitated account-setup paths are (in order of preference): (1) `tr pair --json`; (2) the `totalreclaw_pair` account-setup tool; (3) if both are missing — shell out to EITHER `openclaw totalreclaw pair generate --url-pin-only` (single-line JSON `{v,url,pin,expires_at_ms}`) OR `openclaw totalreclaw onboard --pair-only` (single-line JSON `{v,pair_url,pin,expires_at_ms}`). Both have zero phrase material on stdout (account-setup crypto is x25519-only, not BIP-39). If the user pastes a phrase anyway: tell them it is compromised, re-run `tr pair --json` for a fresh wallet.
-
-## Usage (post-setup)
-
-- Stable user facts / preferences / identity / "remember X":
-  ```bash
-  node "$TR_CLI" remember --json "<fact>"
-  ```
-- First-person factual query ("do I / what's my / where do I…"):
-  ```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.
-- "status" → `tr status --json` (parse version + onboarded + next_step).
-- "upgrade" → `totalreclaw_upgrade` native tool (paste Stripe URL verbatim). Post-upgrade testnet → mainnet: `totalreclaw_migrate` with `dry_run` first.
-- "import / export / consolidate" → `totalreclaw_import_from` · `totalreclaw_export` · `totalreclaw_consolidate` native tools.
-
-**Forbidden vocabulary** (these are anti-patterns that violate the silence rule):
-- "Let me check that…"
-- "Plugin loaded. Let me verify…"
-- "I'll now…"
-- "Quick fix…"
-- "However, I don't see…"
-- "I need to use…"
-- "Should I /totalreclaw-restart" / "Do you have a public URL" / "Want me to restart" / "Let me check if the tool is bound" / "I need permission to restart"
-- "Now installing…" / "Got it" / "In parallel…" / "Step 1a/1b/1c"
-- "local" / "local-only" / "stored locally" / "on disk" / "without an account" / "local memory" / "local storage"
-
-## Diagnostics
-
-- `tr` CLI not found → plugin not installed or install still in progress. Wait 5s, retry. If still missing, retry `openclaw plugins install @totalreclaw/totalreclaw@rc` once.
-- `totalreclaw_*` tools not visible → EXPECTED under OpenClaw 2026.5.2 (issue #223). Use `tr` CLI instead. Do not restart, do not issue `/totalreclaw-restart`, do not issue `/new`.
-- If `/totalreclaw-restart` is needed for another reason, issue the literal slash command `/totalreclaw-restart` — nothing else. Do not narrate.
-- User says done but `credentials.json` missing → PIN expired or entered wrong phrase; re-run `tr pair --json` and resend line 3 once.
-- `onboarding required` → credentials missing; redo from the account-setup step.
-- `quota exceeded` → `tr status --json` or `totalreclaw_status`, then offer `totalreclaw_upgrade`.
-- `No LLM available for auto-extraction` at startup → provider key unreachable; check `~/.openclaw/agents/<agent>/agent/auth-profiles.json` or plugin config `extraction.llm`.
-
-## Required post-install config (OpenClaw 2026.5.2+)
-
-Add to `~/.openclaw/openclaw.json` after installing:
-```json
-{
-  "plugins": {
-    "allow": ["totalreclaw"],
-    "entries": {
-      "totalreclaw": {
-        "hooks": { "allowConversationAccess": true }
-      }
-    }
-  }
-}
-```
+**Recall (native memory contract — agent-facing):** `memory_search`, `memory_get`.
 
-`plugins.allow` suppresses the "plugins.allow is empty" warning. `hooks.allowConversationAccess` unlocks typed hooks (`agent_end`, etc.) for auto-extraction.
+**Explicit capture + curation (CLI — `tr`, i.e. `node "$TR_CLI" …`):**
+`tr remember` (explicit write) · `tr pin` / `tr unpin` · `tr retype` · `tr set_scope` · `tr status` · `tr export` · `tr pair`. Import + plan upgrade run via the gateway subcommand: `openclaw totalreclaw import from <source> --file <path> [--json]`, `openclaw totalreclaw upgrade [--json]`, `openclaw totalreclaw import status|abort`.
 
-## Tool surface
+The legacy `totalreclaw_*` agent tools and the `tr recall` CLI are retired — recall is `memory_search`, explicit capture is `tr remember`. If a stale guide references them, follow this SKILL instead.
 
-Hybrid-primary: `tr remember` · `tr recall` · `tr pair` · `tr status` (primary path for all agent ops)
-Native fallback (when available): `totalreclaw_pair` · `_remember` · `_recall` · `_forget` · `_pin` · `_unpin` · `_retype` · `_set_scope` · `_export` · `_status` · `_upgrade` · `_migrate` · `_import_from` · `_import_batch` · `_consolidate` · `_onboarding_start` · `_report_qa_bug` (RC only)
+Full guide: <https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/openclaw-setup.md>

package/api-client.ts

@@ -1,8 +1,9 @@
 /**
  * TotalReclaw Plugin - HTTP API Client
  *
- * Communicates with the TotalReclaw server over JSON/HTTP. Uses Node.js
- * built-in `fetch` (available since Node 18).
+ * Communicates with the TotalReclaw server over JSON/HTTP. All wire I/O
+ * goes through `relay.ts` (the plugin's single network site); this module
+ * owns request/response shape, status-checking, and error context.
  *
  * All authenticated endpoints expect:
  *   Authorization: Bearer <hex-encoded-auth-key>
@@ -16,6 +17,7 @@
  */
 
 import { buildRelayHeaders } from './relay-headers.js';
+import { relayFetch } from './relay.js';
 
 // ---------------------------------------------------------------------------
 // Request / Response Types
@@ -131,7 +133,8 @@ export function createApiClient(serverUrl: string) {
       authKeyHash: string,
       saltHex: string,
     ): Promise<{ user_id: string }> {
-      const res = await fetch(`${baseUrl}/v1/register`, {
+      const res = await relayFetch({
+        url: `${baseUrl}/v1/register`,
         method: 'POST',
         headers: buildRelayHeaders({ 'Content-Type': 'application/json' }),
         body: JSON.stringify({ auth_key_hash: authKeyHash, salt: saltHex }),
@@ -165,7 +168,8 @@ export function createApiClient(serverUrl: string) {
       facts: StoreFactPayload[],
       authKeyHex: string,
     ): Promise<{ ids: string[]; duplicate_ids?: string[] }> {
-      const res = await fetch(`${baseUrl}/v1/store`, {
+      const res = await relayFetch({
+        url: `${baseUrl}/v1/store`,
         method: 'POST',
         headers: buildRelayHeaders({
           'Content-Type': 'application/json',
@@ -203,7 +207,8 @@ export function createApiClient(serverUrl: string) {
       maxCandidates: number,
       authKeyHex: string,
     ): Promise<SearchCandidate[]> {
-      const res = await fetch(`${baseUrl}/v1/search`, {
+      const res = await relayFetch({
+        url: `${baseUrl}/v1/search`,
         method: 'POST',
         headers: buildRelayHeaders({
           'Content-Type': 'application/json',
@@ -234,7 +239,8 @@ export function createApiClient(serverUrl: string) {
      * @param authKeyHex  Hex-encoded raw auth key for Bearer header.
      */
     async deleteFact(factId: string, authKeyHex: string): Promise<void> {
-      const res = await fetch(`${baseUrl}/v1/facts/${encodeURIComponent(factId)}`, {
+      const res = await relayFetch({
+        url: `${baseUrl}/v1/facts/${encodeURIComponent(factId)}`,
         method: 'DELETE',
         headers: buildRelayHeaders({
           Authorization: `Bearer ${authKeyHex}`,
@@ -259,7 +265,8 @@ export function createApiClient(serverUrl: string) {
      * @returns The number of facts that were actually deleted.
      */
     async batchDelete(factIds: string[], authKeyHex: string): Promise<number> {
-      const res = await fetch(`${baseUrl}/v1/facts/batch-delete`, {
+      const res = await relayFetch({
+        url: `${baseUrl}/v1/facts/batch-delete`,
         method: 'POST',
         headers: buildRelayHeaders({
           'Content-Type': 'application/json',
@@ -295,7 +302,8 @@ export function createApiClient(serverUrl: string) {
       const params = new URLSearchParams({ limit: String(limit) });
       if (cursor) params.set('cursor', cursor);
 
-      const res = await fetch(`${baseUrl}/v1/export?${params.toString()}`, {
+      const res = await relayFetch({
+        url: `${baseUrl}/v1/export?${params.toString()}`,
         method: 'GET',
         headers: buildRelayHeaders({
           Authorization: `Bearer ${authKeyHex}`,
@@ -325,7 +333,7 @@ export function createApiClient(serverUrl: string) {
      */
     async health(): Promise<boolean> {
       try {
-        const res = await fetch(`${baseUrl}/health`, { method: 'GET' });
+        const res = await relayFetch({ url: `${baseUrl}/health`, method: 'GET' });
         return res.status === 200;
       } catch {
         return false;

package/batch-gate.ts

@@ -0,0 +1,42 @@
+/**
+ * Boot-time chain-gate predicate for client-side `executeBatch` UserOp
+ * submission. Spec #281 §9 Phase 1 (item imp-16).
+ *
+ * The gate batches via `executeBatch` on Gnosis (chain 100). After ops-1
+ * (2026-06-05) BOTH tiers run on Gnosis, so both now batch — the chain==100
+ * check is retained as a safety guard (a non-100 chain, which shouldn't occur
+ * after ops-1, falls back to single-fact). The legacy Free ⇒ Base Sepolia
+ * (84532) single-fact path is gone with the retired two-tier routing (#402).
+ * The `TOTALRECLAW_GNOSIS_BATCH_ENABLED` env var is a hard kill-switch —
+ * setting it to `false` disables batching regardless of chain, so ops can
+ * revert to single-fact submission without a client redeploy. Behaviour of
+ * `shouldBatchOnChain` is unchanged by #402.
+ *
+ * Read at boot only (module-load time). Per-write reads would re-parse the
+ * env on every submission — too expensive for the auto-extraction hot path
+ * and pointless because the env doesn't change mid-process.
+ *
+ * Sibling work-leaves wire `shouldBatchOnChain` into `submitFactBatchOnChain`
+ * (TS) and `agent/lifecycle.py` (Python mirror in `batch_gate.py`); this
+ * module ships the primitive only.
+ *
+ * Env read is centralized in entry.ts (env-reading seam, Task 1.3 of the
+ * OpenClaw native integration plan, 2026-06-21).
+ */
+
+import { isGnosisBatchEnabledAtBoot } from './entry.js';
+
+const GNOSIS_CHAIN_ID = 100;
+
+export function shouldBatchOnChain(chainId: number): boolean {
+  if (!isGnosisBatchEnabledAtBoot()) return false;
+  return chainId === GNOSIS_CHAIN_ID;
+}
+
+export const __testing = {
+  readGateForTests(env: NodeJS.ProcessEnv, chainId: number): boolean {
+    const enabled = (env.TOTALRECLAW_GNOSIS_BATCH_ENABLED ?? '').toLowerCase() !== 'false';
+    if (!enabled) return false;
+    return chainId === GNOSIS_CHAIN_ID;
+  },
+};

package/billing-cache.ts

@@ -11,8 +11,9 @@
  * This module:
  *   - reads/writes `~/.totalreclaw/billing-cache.json` (path from CONFIG)
  *   - exports `BillingCache`, `BILLING_CACHE_PATH`, `BILLING_CACHE_TTL`
- *   - keeps the chain-id override in sync with the cached tier so Pro-tier
- *     UserOps sign against chain 100 and Free-tier stays on 84532
+ *   - keeps the chain-id override in sync with the relay's authoritative
+ *     `chain_id` (after ops-1 both tiers are on Gnosis 100; the client consumes
+ *     the relay value verbatim — see `syncChainIdFromBilling`)
  *   - does NOT import anything that performs outbound I/O
  *
  * Do NOT add any outbound-request call to this file — a single match for
@@ -50,6 +51,12 @@ export interface BillingCache {
     max_facts_per_extraction?: number;
     max_candidate_pool?: number;
   };
+  /**
+   * Authoritative chain id from the relay `/v1/billing/status` response.
+   * After ops-1 (2026-06-05) both tiers are on Gnosis (100); the relay is the
+   * source of truth, so the client consumes this verbatim (#402).
+   */
+  chain_id?: number;
   checked_at: number;
 }
 
@@ -58,24 +65,21 @@ export interface BillingCache {
 // ---------------------------------------------------------------------------
 
 /**
- * Apply the billing tier to the runtime chain override.
+ * Apply the relay's authoritative `chain_id` to the runtime chain override.
  *
- * Pro tier → chain 100 (Gnosis mainnet). Free tier (or unknown) stays on
- * 84532 (Base Sepolia). The relay routes Pro UserOps to Gnosis, so the
- * client MUST sign them against chain 100 — otherwise the bundler returns
- * AA23 (invalid signature). See MCP's equivalent path in mcp/src/index.ts.
+ * After ops-1 (2026-06-05) both tiers run on Gnosis (chain 100) and the relay
+ * returns an authoritative `chain_id` in `/v1/billing/status`. The client MUST
+ * consume that verbatim — the old tier→chain derivation (Free ⇒ 84532 Base
+ * Sepolia) was retired two-tier logic that mis-signed FREE-tier UserOps
+ * against the wrong chain and queried a Base-Sepolia RPC for a Gnosis-deployed
+ * sender, producing deterministic AA10 (#402).
  *
- * Called from `readBillingCache` and `writeBillingCache` so that every cache
- * read or write keeps the chain override in sync with the cached tier.
- * Idempotent — calling with the same tier is a no-op.
+ * A missing / non-finite `chain_id` (older relay, partial payload) defaults to
+ * 100 — never 84532. Called from `readBillingCache` and `writeBillingCache` so
+ * every cache read or write keeps the override in sync. Idempotent.
  */
-export function syncChainIdFromTier(tier: string | undefined): void {
-  if (tier === 'pro') {
-    setChainIdOverride(100);
-  } else {
-    // Free or unknown → reset to the default free-tier chain.
-    setChainIdOverride(84532);
-  }
+export function syncChainIdFromBilling(chainId: number | undefined): void {
+  setChainIdOverride(typeof chainId === 'number' && Number.isFinite(chainId) ? chainId : 100);
 }
 
 // ---------------------------------------------------------------------------
@@ -95,8 +99,9 @@ export function readBillingCache(): BillingCache | null {
     if (!fs.existsSync(BILLING_CACHE_PATH)) return null;
     const raw = JSON.parse(fs.readFileSync(BILLING_CACHE_PATH, 'utf-8')) as BillingCache;
     if (!raw.checked_at || Date.now() - raw.checked_at > BILLING_CACHE_TTL) return null;
-    // Keep chain override in sync with persisted tier across process restarts.
-    syncChainIdFromTier(raw.tier);
+    // Keep chain override in sync with the persisted authoritative chain_id
+    // across process restarts.
+    syncChainIdFromBilling(raw.chain_id);
     return raw;
   } catch {
     return null;
@@ -118,5 +123,5 @@ export function writeBillingCache(cache: BillingCache): void {
   }
   // Sync chain override AFTER the write so in-process UserOp signing picks
   // up the correct chain immediately, even if the disk write failed.
-  syncChainIdFromTier(cache.tier);
+  syncChainIdFromBilling(cache.chain_id);
 }

package/claims-helper.ts

@@ -30,6 +30,7 @@ import {
   VALID_MEMORY_VOLATILITIES,
   VALID_MEMORY_TYPES_V1,
 } from './extractor.js';
+import { envStringLower } from './entry.js';
 
 // Lazy-load WASM. We use createRequire so this module loads cleanly under
 // both the OpenClaw runtime (CJS-ish tsx) and bare Node ESM (used by tests).
@@ -281,6 +282,11 @@ export function buildCanonicalClaimV1(input: BuildClaimV1Input): string {
   if (typeof input.embeddingModelId === 'string' && input.embeddingModelId.length > 0) {
     canonical.embedding_model_id = input.embeddingModelId;
   }
+  // am-1: Crystal-shaped debrief structured metadata. Re-attached after
+  // validation using the same plugin-extra pattern as volatility.
+  if (fact.crystalMetadata) {
+    canonical.metadata = fact.crystalMetadata;
+  }
 
   return JSON.stringify(canonical);
 }
@@ -635,7 +641,7 @@ export type AutoResolveMode = 'active' | 'off' | 'shadow';
  * @internal Not public config — emergency kill-switch only.
  */
 export function resolveAutoResolveMode(): AutoResolveMode {
-  const raw = (process.env.TOTALRECLAW_AUTO_RESOLVE_MODE ?? '').trim().toLowerCase();
+  const raw = envStringLower('TOTALRECLAW_AUTO_RESOLVE_MODE');
   if (raw === 'off') return 'off';
   if (raw === 'shadow') return 'shadow';
   return 'active';