@totalreclaw/totalreclaw 3.3.1-rc.8 → 3.3.1

package/CHANGELOG.md

@@ -4,6 +4,272 @@ 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).
 
+## [Unreleased]
+
+### Install / runtime hygiene (issues #126, #128)
+
+Two narrow fixes from the rc.20 user-QA findings — both around install /
+boot-time output cleanliness, no behavior change to the steady-state plugin.
+
+- **#126 — clean up `.openclaw-install-stage-*` siblings.** When
+  `openclaw plugins install @totalreclaw/totalreclaw` is interrupted mid-
+  extract (e.g. by an auto-gateway-restart triggered by the same install),
+  the npm staging directory `<extensionsDir>/.openclaw-install-stage-XXXXXX/`
+  survives. On the next gateway start, OpenClaw's plugin loader auto-
+  discovers BOTH `.../totalreclaw/` AND the orphan staging dir, registers
+  duplicate plugins, fires hooks twice, and prints a "duplicate-plugin-id"
+  warning every cycle. A user running `openclaw plugins list` sees two
+  `totalreclaw` rows.
+
+  Fix: `cleanupInstallStagingDirs(pluginDir)` runs at plugin register time
+  (one tick after the loader resolves our entrypoint). It scans the
+  extensions directory for `.openclaw-install-stage-*` siblings and
+  recursively removes each one. Best-effort — never crashes plugin init
+  on permission / race failures.
+
+  Regression: `install-staging-cleanup.test.ts` (16 assertions) covers
+  fresh install, idempotent re-run, package-root vs `dist/` invocation,
+  unrelated-dotfile preservation (`.git`, `.openclaw-cache`), and stray-
+  file (non-directory) skipping.
+
+- **#128 — registerTool breadcrumbs no longer bleed into `--json` stdout.**
+  The rc.20 breadcrumb logs (`registerTool(totalreclaw_pair) returned. ...`
+  and the RC-only `totalreclaw_report_qa_bug registered ...`) were emitted
+  via `api.logger.info`, which OpenClaw routes to stdout decorated with
+  `[plugins] `. When a user invoked `openclaw agent --message "..." --json`
+  for programmatic parsing, the breadcrumb appeared on stdout alongside
+  the JSON-RPC body, breaking any naive `JSON.parse(stdout)`.
+
+  Fix: gate both breadcrumbs behind `CONFIG.verboseRegister`, OFF by
+  default. Ops can opt back in with `TOTALRECLAW_VERBOSE_REGISTER=1` (or
+  the general `TOTALRECLAW_DEBUG=1` toggle) when chasing a tool-injection
+  regression. Default-off keeps `openclaw agent --json` stdout clean.
+
+  Regression: `json-stdout-cleanliness.test.ts` (11 assertions) confirms
+  both breadcrumbs are wrapped in `if (CONFIG.verboseRegister)` blocks,
+  simulates the gated `--json` stdout path and `JSON.parse`s the result,
+  and exercises the env-var resolution (`TOTALRECLAW_VERBOSE_REGISTER`
+  -> `TOTALRECLAW_DEBUG` -> default false).
+
+## [3.3.1-rc.16] — 2026-04-24
+
+Fixes #92 — slow-host install times out during ONNX-runtime / embedding-model
+download. ONNX stays mandatory (no opt-in flag); first-call download is now
+wrapped with timeout, progress, and retry UX so slow connections succeed
+instead of silently hanging until OpenClaw SIGTERMs.
+
+### Embedding-model download UX
+
+- New `download-ux.ts` module — pure stdlib, no third-party imports — exposes
+  `downloadWithUX(label, fn, opts)`. Wraps a download promise with:
+  - **Per-attempt timeout**, default 600s (covers ~290 KB/s for the 344 MB
+    Harrier model). Configurable via env `TOTALRECLAW_ONNX_INSTALL_TIMEOUT`
+    (in seconds). Per-attempt timeout grows 1x/2x/4x across retries.
+  - **60s keep-alive log** during long downloads so users on slow networks
+    see "still downloading… (Ns elapsed)" rather than a frozen prompt.
+  - **3-attempt exponential-backoff retry** (5s/10s backoff between attempts)
+    to absorb transient network blips.
+  - **Loud actionable error** on exhaustion: names the env var to extend the
+    timeout and the exact `openclaw plugins install totalreclaw` command to
+    rerun.
+- `embedding.ts` now wraps `AutoTokenizer.from_pretrained`,
+  `AutoModel.from_pretrained`, and the `pipeline()` call with
+  `downloadWithUX`. Prints a user-visible "Downloading embedding model
+  (~344MB) — this may take a few minutes on slower connections. Please wait."
+  message before the first download starts.
+- ONNX remains a mandatory hard `dependency` (no `[embedding]`-style opt-in
+  extra). Recall accuracy is unchanged.
+- Regression: `test_issue_92_onnx_download_ux.test.ts` exercises happy path,
+  transient failure → retry, full exhaustion, per-attempt timeout, and
+  keep-alive cadence. Wired into the plugin `npm test` chain.
+
+## [3.3.1-rc.14] — 2026-04-24
+
+Coordinated version bump with Python `2.3.1rc14`. Two narrow bug fixes
+found during rc.13 user QA on 2026-04-24:
+
+### RC-gated QA bug tool — target-repo hardening
+
+`totalreclaw_report_qa_bug` now refuses to file to any repo that isn't
+internal. rc.13 user QA surfaced agent-filed bug reports leaking to the
+public `p-diogo/totalreclaw` tracker despite the tool's default target
+being `p-diogo/totalreclaw-internal`.
+
+- New env var: `TOTALRECLAW_QA_REPO` lets operators point the tool at a
+  private fork. The default stays `p-diogo/totalreclaw-internal`.
+- New `resolveQaRepo(...)` guard: rejects any slug that is on the
+  public-repo denylist (includes `p-diogo/totalreclaw`,
+  `...-website`, `...-relay`, `...-plugin`, `...-hermes`) OR does not
+  end in `-internal`. The check runs before the HTTP POST is
+  constructed, so rejection never leaves the client.
+- `CONFIG.qaRepoOverride` surfaces the env var through `config.ts`
+  (keeps scanner-sensitive `process.env` reads centralized).
+- Regression test in `qa-bug-report.test.ts` mocks the public slug
+  and asserts `fetch` is NEVER called.
+
+Labels on filing unchanged — still emits `qa-bug`, `pending-triage`,
+`severity:<...>`, `component:<...>`, `rc:<...>`.
+
+### Relay pair page — PIN paste button UX
+
+The paste button on the step-1 PIN screen was silently failing under
+certain browser states. rc.14 rewrites the handler with a proper
+error taxonomy:
+
+- Capability probe up front — `navigator.clipboard.readText` missing →
+  clear "Paste unavailable on this browser" toast.
+- `NotAllowedError` → "Clipboard access denied — type the 6 digits
+  manually" (covers iOS Safari permission denial).
+- Empty clipboard → "Clipboard is empty — copy the PIN from your chat
+  first".
+- Non-digit content → "Clipboard has no digits — copy the 6-digit PIN
+  first".
+- Every failure path focuses the first PIN cell so the user can fall
+  through to manual typing without another click.
+- Errors log to `console.warn` with name + message so future failures
+  are diagnosable from browser devtools.
+
+The mockup at `docs/mockups/rc13-pair-wizard/wizard.js` gets the same
+rewrite for parity — the relay's `scripts/sync-pair-preview.mjs`
+regenerates `/pair-preview/` from this source.
+
+Fix also applies to the "Paste all 12 words" import-grid button on the
+relay production page (same taxonomy, same focus-fallback).
+
+## [3.3.1-rc.13] — 2026-04-24
+
+Coordinated version bump with Python `2.3.1rc13`. No substantive
+changes to the plugin's own TypeScript — the rc.13 fix lands on the
+Hermes-side (`python/src/totalreclaw/hermes/pair_tool.py`) where the
+asyncio lifecycle regression lived. We keep plugin + Python RC
+numbers in lockstep so the release-pipeline tracker and
+`qa-totalreclaw` skill carry both artifacts through QA as one
+bundle.
+
+See the corresponding entry in `python/CHANGELOG.md` for the full
+design: the relay-pair WebSocket is now owned by a dedicated worker
+thread (with its own event loop) so it survives the Hermes
+tool-invocation loop teardown that destroyed the rc.10–rc.12 waiter
+mid-recv and caused every pair attempt to 502.
+
+The relay-served production pair page is also replaced with the
+rc.13 wizard UX — a typeform-style 3-step flow (PIN → phrase → done)
+mirroring the `docs/mockups/rc13-pair-wizard/` design. This lands in
+the `totalreclaw-relay` repo PR, not here, but surfaces to every
+OpenClaw user via the default relay pair flow.
+
+### Plugin local-mode pair page
+
+`skill/plugin/pair-page.ts` (the local-mode fallback served when a
+user sets `TOTALRECLAW_PAIR_MODE=local`) retains its rc.10–rc.12 UX
+shape. The wizard UX port for this file is deferred to rc.14 pending
+a design decision on whether to share a single CSS+JS asset across
+all three pair pages (relay / Python local / plugin local) or keep
+them independently inlined. Local-mode is rarely exercised — the
+plugin defaults to the relay flow via the Hermes Python sidecar and
+only falls back here for air-gapped setups.
+
+## [3.3.1-rc.12] — 2026-04-23
+
+**Ship-stopper fix for rc.11.** The relay-served pair page's submit
+button threw `NotSupportedError: Failed to execute 'importKey' on
+'SubtleCrypto': Algorithm: Unrecognized name` when the user clicked
+"Seal key and finish". Root cause: `ChaCha20-Poly1305` is NOT
+implemented in the Web Crypto API of Chrome / Safari / Edge — the
+spec exposes `AES-GCM` as the only AEAD. rc.10/rc.11 never worked
+end-to-end for any user; every pair attempt failed silently and the
+token expired without logging a failure — GH issue #79.
+
+rc.12 swaps the cipher suite from ChaCha20-Poly1305 to AES-256-GCM on
+both sides (browser + gateway). Wire shape unchanged — still 12-byte
+nonce, 16-byte tag, sid-bound AAD, base64url encoding. HKDF info bumped
+from `totalreclaw-pair-v1` to `totalreclaw-pair-v2` so rc.11 ciphertexts
+cannot collide with rc.12 keys (fail-closed on any version skew).
+
+### Changed
+- `skill/plugin/pair-crypto.ts`: `aeadDecrypt` / `aeadEncryptWithSessionKey`
+  switched from `chacha20-poly1305` to `aes-256-gcm`. `HKDF_INFO` bumped
+  to `totalreclaw-pair-v2`.
+- `skill/plugin/pair-page.ts` (local-mode pair page): WebCrypto
+  `ChaCha20-Poly1305` calls swapped to `AES-GCM`. Capability probe
+  function renamed `chaChaSupported` → `aesGcmSupported`.
+
+### Observability
+- The relay's `pair-html.ts` (user-facing page) now reports phase-labelled
+  error messages so a network / encrypt / submit failure no longer masks
+  as a silent "stuck on acknowledge screen". Relay PR (fix/pair-aes-gcm-rc12)
+  is the canonical fix for the issue reported in #79.
+
+## [3.3.1-rc.11] — 2026-04-23
+
+OpenClaw-side universal pair reachability — the plugin's `totalreclaw_pair` tool now routes through the relay WebSocket by default, mirroring the Python `2.3.1rc10` pivot on the Hermes side. The URL returned to the user is `https://api-staging.totalreclaw.xyz/pair/p/<token>#pk=<gateway_pubkey>` instead of the previous `http://<gateway-host>:<port>/plugin/totalreclaw/pair/finish?sid=<sid>#pk=…`. Managed hosts, Docker-in-cloud setups, phone-scan-QR flows, and split-network operators can now complete pairing without the browser needing loopback or LAN access to the gateway.
+
+Paired with Hermes Python `2.3.1rc11` — both clients now reach for the relay by default, and `TOTALRECLAW_PAIR_MODE=local` on either side restores the rc.4–rc.10 loopback flow for air-gapped / self-hosted deployments.
+
+### Added
+
+- **`skill/plugin/pair-remote-client.ts`** — new. TypeScript mirror of `python/src/totalreclaw/pair/remote_client.py` (rc.10 Hermes):
+  - `openRemotePairSession({ relayBaseUrl?, pin?, clientId?, mode? })` — generates an ephemeral x25519 keypair via the existing `pair-crypto.ts` module, opens a WebSocket to `/pair/session/open`, sends `{type:"open", gateway_pubkey, pin, client_id, mode}`, and returns a `RemotePairSession` handle containing the user-facing URL (with `#pk=` fragment), PIN, token, expiry, and the live WebSocket.
+  - `awaitPhraseUpload(session, { completePairing, phraseValidator?, timeoutMs? })` — blocks on the kept-open WebSocket until the relay pushes `{type:"forward", client_pubkey, nonce, ciphertext}`. Decrypts locally via `decryptPairingPayload` using the gateway's private key (same ECDH + HKDF + ChaCha20-Poly1305 primitives as rc.10's loopback flow — byte-compatible with Python's `pair.crypto`). Runs the caller-supplied `completePairing` handler and sends `{type:"ack"}` back on success or `{type:"nack", error}` on validator / decrypt / completion failure.
+  - `pairViaRelay(...)` — one-shot convenience wrapper for tests and simple callers.
+- **`ws` runtime dep** (`^8.18.3`) + **`@types/ws`** — pure-JS WebSocket client. Transitive already via `@totalreclaw/core`; rc.11 promotes it to a direct dep so the plugin's own import graph is explicit.
+- **`TOTALRECLAW_PAIR_MODE`** env (plugin side) — mirrors the Python env. Unset or any non-`local` value routes through the relay; `local` preserves the rc.4–rc.10 loopback HTTP server served by `pair-http.ts` (`/plugin/totalreclaw/pair/{finish,start,respond,status}`).
+- **`TOTALRECLAW_PAIR_RELAY_URL`** env (plugin side) — self-hosters can point at their own relay. Defaults to `wss://api-staging.totalreclaw.xyz`.
+- **`skill/plugin/pair-remote-client.test.ts`** — 20 assertions across 5 scenarios: happy-path round-trip, invalid-phrase nack, relay open error, decrypt failure, https-to-wss scheme conversion. Runs against a local `ws` server stub — no network dependency.
+
+### Changed
+
+- **`totalreclaw_pair` tool** now branches on `CONFIG.pairMode`. In relay mode it returns the URL + PIN immediately and schedules a background task that blocks on the WebSocket until the browser completes (or the TTL lapses). Credentials-write happens in that background task via the same `loadCredentialsJson` / `writeCredentialsJson` / `setRecoveryPhraseOverride` / `writeOnboardingState` side-effect chain that the loopback `pair-http.respond` handler uses — so the onboarding-state flip remains identical. Tool payload shape unchanged (`{url, pin, expires_at_ms, qr_ascii, qr_png_b64, qr_unicode, mode}`) except for a new `transport: 'relay' | 'local'` field that tooling (QA harness, telemetry) can use to confirm which path served a given URL.
+
+### Phrase-safety invariants (preserved)
+
+- Relay is blind: the gateway's ephemeral x25519 private key never leaves the plugin host. The relay forwards opaque ciphertext; it cannot derive the symmetric key.
+- PIN is out-of-band: the user reads the PIN from agent chat and types it into the browser. The relay stores the PIN in memory only; logs carry no PIN, no ciphertext, no pubkey, no phrase.
+- Session state is in-memory on the relay with a 5-minute TTL. Redis deferred to Phase 2 per the design blueprint.
+- Backwards-compat: `TOTALRECLAW_PAIR_MODE=local` preserves every bit of the rc.4–rc.10 flow — same loopback HTTP server, same session store, same browser page, same decrypt handler.
+
+### Mechanism / byte-compat
+
+The crypto is a literal TypeScript binding against the same `pair-crypto.ts` module `pair-http.ts` already imports. No new cipher suite, no new wire format — only the transport (WebSocket to relay + relay-served HTML page) differs from the loopback path. A ciphertext produced by the relay-served `pair-html.ts` page decrypts under the same gateway private key using the same `decryptPairingPayload(...)` call path. This is deliberate: `pair-crypto.ts` is the byte-compat anchor shared with Python's `pair.crypto`, and rc.11 extends that anchor to the relay wire.
+
+## [3.3.1-rc.10] — 2026-04-23
+
+Coordinated version bump with Hermes Python `2.3.1rc10`. rc.10 ships the relay-brokered pair flow — see `python/CHANGELOG.md` (the `2.3.1rc10` entry) for the full design. The `totalreclaw_pair` pair URL on the OpenClaw plugin side still uses the gateway-loopback HTTP server (the OpenClaw plugin runs in-process alongside a browser on the same host for most deployments, so the loopback URL actually reaches the user). The relay-brokered path is currently Hermes-side only — the OpenClaw plugin can pick it up in a later RC if the same universal-reachability problem starts biting OpenClaw users.
+
+Bundled into rc.10: the previously-parked rc.5 QR display layer from PR #76 (`pair-qr.ts` + `pair-qr.test.ts`, tool-payload `qr_png_b64` + `qr_unicode` fields, `totalreclaw_setup` / `totalreclaw_onboarding_start` stub removal). All rebased onto main via the chore/rc.10-qr-rebase-pr76 branch.
+
+### Added (rebased from PR #76)
+
+- **`skill/plugin/pair-qr.ts`** — new. QR encoder module wrapping `qrcode` (PNG) + `qrcode-terminal` (Unicode block). Same contract as the Python side (`totalreclaw.pair.qr`).
+- **`totalreclaw_pair` tool payload** — the `details` block now carries `qr_png_b64` (base64 PNG for image transports) and `qr_unicode` (terminal block-char string) alongside the existing `qr_ascii`. URL + PIN unchanged.
+- **SKILL.md "Rendering the QR on your transport" section** — per-transport agent rendering guidance (Telegram attachment, terminal inline, web chat `<img>` embed).
+- **`qrcode` + `@types/qrcode`** runtime deps.
+
+### Removed (rc.5 phrase-safety carve-out closure, rebased)
+
+- **`totalreclaw_setup` + `totalreclaw_onboarding_start`** agent tools — both were neutered pointer stubs in rc.4; rc.5 auto-QA flagged them as future-regression surface and their mere presence signalled to agents that "phrase handling happens here". Deleted outright in rc.5, preserved through rc.10. `skill/plugin/phrase-safety-registry.test.ts` now asserts neither name is registered.
+
+Version bump reason: rc cadence keeps Python + plugin aligned so the release-pipeline tracker carries them through QA as one artifact set.
+
+## [3.3.1-rc.9] — 2026-04-23
+
+Coordinated version bump with Hermes Python `2.3.1rc9`. Plugin code itself is unchanged from `3.3.1-rc.6` (the first-run banner fix lives entirely on the Python side — `totalreclaw.onboarding.maybe_emit_welcome`). The rc.9 bundle ships the Hermes-side banner suppression and keeps plugin + Python versions aligned so the release-pipeline tracker can carry them through QA as one artifact set.
+
+### Why a plugin bump when only Python changed
+
+Our RC cadence publishes both registries from the same bundle. Out-of-sync version tags cause downstream confusion (the `qa-totalreclaw` skill and the release-pipeline tracker both key on a single RC-number per wave). Skipping the plugin bump would leave rc.9 documented on the Python side only; a later plugin bug would then have to skip to rc.10 to catch up. Much simpler to bump both in lockstep.
+
+See `python/CHANGELOG.md` (the `2.3.1rc9` entry) for the underlying fix: suppress the first-run welcome banner emitted by `totalreclaw.onboarding.maybe_emit_welcome`. Two problems surfaced during the rc.8 Hermes auto-QA run:
+
+1. **Chat-breaker.** The banner dominated `hermes chat -q` stdout when credentials were absent, breaking the QA harness's `session_id` parsing on every fresh install.
+2. **Phrase-safety violation.** The banner told users to `Run: totalreclaw setup` — a CLI that emits the recovery phrase to stdout. In an agent-driven context, stdout is echoed back into LLM context, so the phrase would cross the LLM boundary in violation of `project_phrase_safety_rule.md`.
+
+Agent-driven setup now routes through the `totalreclaw_pair` tool (browser-side crypto, phrase-safe) per SKILL.md. User-in-terminal setup still runs through `totalreclaw setup` / `openclaw totalreclaw onboard` OUTSIDE any agent context.
+
+### Skipped
+
+- **`3.3.1-rc.7`** and **`3.3.1-rc.8`** — registry-only bumps from 2026-04-22 workflow dispatches; the git repo on `main` carried rc.6 code unchanged through both publishes.
+
 ## [3.3.1-rc.6] — 2026-04-22
 
 Coordinated version bump with Hermes Python `2.3.1rc6`. Plugin code itself is unchanged from `3.3.1-rc.4` (the OpenClaw plugin's `register()` path already wired every tool advertised in `skill.yaml`). The rc.6 bundle ships the Hermes-side tool-registration fix and keeps plugin + Python versions aligned so the release-pipeline tracker can carry them through QA as one artifact set.
@@ -227,7 +493,8 @@ See: `plans/2026-04-22-plugin-3.3.1-provider-agnostic-llm.md` (internal).
     - `--json` — emits a structured payload (requires `--non-interactive`).
     - `--mode <generate|restore>` — skip the menu prompt.
     - `--phrase <12-or-24>` — required for `--mode restore`; `-` reads stdin.
-    - `--emit-phrase` — opt-in path that includes the plaintext phrase in the
+    - `--emit-phrase` — historic opt-in flag (do not invoke via agent shell:
+      forbidden by the phrase-safety rule); included plaintext phrase in the
       JSON payload. Default omits the phrase; the agent should direct the
       user to read `~/.totalreclaw/credentials.json` in their terminal.
 

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: totalreclaw
 description: "Install + set up TotalReclaw encrypted memory for OpenClaw, then use totalreclaw_remember / totalreclaw_recall. Trigger on 'install TotalReclaw', 'set up TotalReclaw', 'restore my recovery phrase', or any remember / recall request."
-version: 3.3.1-rc.6
+version: 3.3.1-rc.22
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -24,37 +24,43 @@ metadata:
 
 # TotalReclaw — OpenClaw
 
-## Fast path — "install totalreclaw" (Approach A, preferred)
+> 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.
 
-ClawHub classifies TotalReclaw as a skill. `openclaw skills install totalreclaw` registers this SKILL.md into your agent context BEFORE the plugin is installed (so you may be reading this with no `totalreclaw_*` tools yet).
+## Setup flow
 
-If the user says "install totalreclaw" (or any variant) AND no `totalreclaw_*` tools are in your toolset:
+If `totalreclaw_*` tools are already bound to your toolset, SKIP install and jump to step 4. Otherwise run all steps in order.
 
-1. Run via your shell tool: `openclaw plugins install totalreclaw`. (For RC candidates: `openclaw plugins install @totalreclaw/totalreclaw@rc` — the `rc` dist-tag on npm is the latest candidate.)
-2. Tell the user: *"Plugin installed. Restarting the gateway so the tools bind."* Then ask the user to restart the gateway: `openclaw gateway restart` (native) or `docker restart tr-openclaw` (Docker). The agent-facing shell CANNOT self-restart the gateway it's running inside of — this step has to be a user action. Wait for the user to confirm the restart is done.
-3. After restart: verify `totalreclaw_pair` is now in your toolset. If not, tell the user the restart didn't take effect and to retry the restart command. Do not loop the install.
-4. Check `~/.totalreclaw/credentials.json` (via `test -s ~/.totalreclaw/credentials.json`). If it exists, confirm *"TotalReclaw is already set up."* and stop.
-5. Call `totalreclaw_pair`. Returns `{url, pin, qr_ascii, expires_at_ms}`.
-6. Relay verbatim: *"Open <url> in your browser. Enter your 12-word recovery phrase (or let the browser generate one). Confirm PIN <pin>. I'll wait for you to say done."*
-7. After user says done: verify `~/.totalreclaw/credentials.json`. If missing, call `totalreclaw_pair` again (PIN likely expired) and resend.
-8. Confirm: *"TotalReclaw set up ✓. Ask me to remember or recall anything — try `totalreclaw_remember` or ask me to remember something."*
+1. **Install skill + plugin.** Run via your shell tool, in this order:
+   ```
+   openclaw skills install totalreclaw
+   openclaw plugins install @totalreclaw/totalreclaw
+   ```
+   For RC: replace the second command with `openclaw plugins install @totalreclaw/totalreclaw@rc`. 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.
 
-If `totalreclaw_*` tools ARE already in your toolset when the user asks, SKIP the install step and jump to step 4.
+2. **Wait for auto-reload — do NOT restart the gateway yourself.** OpenClaw's default config (`gateway.reload.mode = "hybrid"`) auto-restarts the gateway via a file-watcher within 1-3 seconds. Wait ~5s, then run `openclaw plugins list | grep totalreclaw` and confirm `totalreclaw_pair` is in your toolset. If it does NOT appear within 10s, the user has `gateway.reload.mode = off` — fall back: tell the user verbatim *"Auto-reload didn't fire. Please restart your OpenClaw gateway: `openclaw gateway restart` (native), `docker restart <your-container-name>` (Docker self-host — substitute the actual name; `docker ps` shows it), or your managed service's restart control. Reply `done` once it's back up."* Do NOT invoke the restart yourself — your shell is running inside the gateway you'd be restarting (catch-22). Wait for the user's `done`.
 
-## Explicit two-step setup flow (Approach B, fallback)
+3. **Verify `totalreclaw_pair` is bound.** If still missing after the user said `done`, tell them the restart didn't take effect and to retry. Do not loop the install.
 
-Used when the user pastes a verbose prompt describing skill install + plugin install + restart + pair (e.g. *"TotalReclaw is a skill at 'totalreclaw' on ClawHub. Install it, then install the plugin, restart the gateway, and walk me through the QR pairing flow"*) OR when a tool returns `onboarding required`.
+4. **Check for existing credentials.** Run `test -s ~/.totalreclaw/credentials.json`. If it exists and is non-empty, confirm *"TotalReclaw is already set up."* and stop.
 
-1. `openclaw plugins install @totalreclaw/totalreclaw` (stable). For RC: `@totalreclaw/totalreclaw@rc`.
-2. Restart gateway so plugin routes + tools bind. Docker: `docker restart tr-openclaw`. Native: `openclaw gateway restart`. Wait ~5s; confirm the gateway is back up. (If you are running inside the gateway, ask the user to run the restart command and wait for confirmation.)
-3. Call `totalreclaw_pair`. Returns `{url, pin, qr_ascii, expires_at_ms}`.
-4. Relay to user verbatim: *"Open <url> in your browser. Enter your 12-word recovery phrase (or let the browser generate one). Confirm PIN <pin>. I'll wait for you to say done."*
-5. After user says done: verify `~/.totalreclaw/credentials.json` exists and is non-empty. If missing, call `totalreclaw_pair` again (PIN likely expired) and resend.
-6. Confirm: *"TotalReclaw is set up. Ask me to remember or recall anything."*
+5. **Pair.** Call `totalreclaw_pair`. Returns `{url, pin, qr_ascii, qr_png_b64, qr_unicode, expires_at_ms}` (see "Rendering the QR" below). Relay verbatim:
+   > *Open <url> in your browser. Generate a new 12-word recovery phrase there or paste an existing one — the phrase stays in your browser, the relay only sees ciphertext. Confirm PIN <pin>. Reply `done` once the page says it's sealed.*
+
+6. **Verify and confirm.** After user says `done`, re-run `test -s ~/.totalreclaw/credentials.json`. If missing, the PIN expired — call `totalreclaw_pair` again and resend. If present, confirm *"TotalReclaw is set up. Ask me to remember or recall anything."*
+
+## Rendering the QR on your transport (rc.5+)
+
+When you receive the `totalreclaw_pair` payload, render the QR based on your chat transport:
+
+- **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="Pair QR">` if the chat client renders HTML; otherwise fall back to attachment.
+
+The QR encodes ONLY the pair 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.
 
 ## Phrase safety (HARD — never break)
 
-NEVER echo / generate / ask the user to paste a recovery phrase in chat. NEVER invoke `openclaw totalreclaw onboard`, `totalreclaw setup`, or any phrase-touching CLI via your shell tool (stdout enters LLM context). The ONLY agent-facilitated setup path is `totalreclaw_pair`. If the user pastes a phrase anyway: tell them it is compromised, call `totalreclaw_pair` with `mode=generate` for a fresh wallet.
+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 setup paths are (in order of preference): (1) `totalreclaw_pair` tool; (2) if the tool is missing from your tool list — a known gap for some container-based agents, issue #87 — 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}`, issue #95 — same pair flow, `pair_url` key naming). Both have zero phrase material on stdout (pair-crypto is x25519-only, not BIP-39). If the user pastes a phrase anyway: tell them it is compromised, call `totalreclaw_pair` with `mode=generate` for a fresh wallet.
 
 ## Usage (post-setup)
 
@@ -66,7 +72,7 @@ NEVER echo / generate / ask the user to paste a recovery phrase in chat. NEVER i
 
 ## Diagnostics
 
-- `totalreclaw_*` tools not visible → plugin not installed or gateway not restarted. Verify via `openclaw plugins list | grep totalreclaw`. If listed, ask the user to restart the gateway.
+- `totalreclaw_*` tools not visible → plugin not installed or auto-reload didn't fire. Verify via `openclaw plugins list | grep totalreclaw` (or, on a managed service that doesn't expose the CLI, ask the user to confirm via their service's plugins UI). If `totalreclaw` is listed but tools are still absent, the gateway probably hasn't completed its auto-restart yet (give it 5-10s) OR `gateway.reload.mode = off` is set — instruct manual restart as fallback: `openclaw gateway restart` (native), `docker restart <your-container-name>` (Docker self-host), or the managed service's restart control. If the plugin is listed and the gateway has been restarted but tools are still missing (container-agent gap, issue #87), shell out to `openclaw totalreclaw pair generate --url-pin-only` on the gateway host and hand the user the `url` + `pin` from the JSON payload — OR `openclaw totalreclaw onboard --pair-only` (same flow, returns `pair_url` instead of `url`, issue #95). If your shell doesn't reach the gateway host (managed service), tell the user to install/enable the plugin via their service's plugins UI and restart the gateway via the service's restart control. Do NOT suggest the bare `openclaw totalreclaw onboard` (leaks phrase on stdout — deprecated in rc.18, removed next RC).
 - User says done but `credentials.json` missing → PIN expired or entered wrong phrase; call `totalreclaw_pair` again.
 - `onboarding required` → credentials missing; redo from the pair step.
 - `quota exceeded` → `totalreclaw_status`, then offer `totalreclaw_upgrade`.

package/api-client.ts

@@ -8,8 +8,15 @@
  *   Authorization: Bearer <hex-encoded-auth-key>
  *
  * The server hashes the auth key with SHA-256 to look up the user.
+ *
+ * Every outbound request goes through `buildRelayHeaders()` so the
+ * `X-TotalReclaw-Client` tag is set + the optional QA-tracing
+ * `X-TotalReclaw-Session` tag is forwarded when `TOTALRECLAW_SESSION_ID`
+ * is set. See `relay-headers.ts` and internal#127.
  */
 
+import { buildRelayHeaders } from './relay-headers.js';
+
 // ---------------------------------------------------------------------------
 // Request / Response Types
 // ---------------------------------------------------------------------------
@@ -126,7 +133,7 @@ export function createApiClient(serverUrl: string) {
     ): Promise<{ user_id: string }> {
       const res = await fetch(`${baseUrl}/v1/register`, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json', 'X-TotalReclaw-Client': 'openclaw-plugin' },
+        headers: buildRelayHeaders({ 'Content-Type': 'application/json' }),
         body: JSON.stringify({ auth_key_hash: authKeyHash, salt: saltHex }),
       });
       await assertOk(res, 'register');
@@ -160,10 +167,10 @@ export function createApiClient(serverUrl: string) {
     ): Promise<{ ids: string[]; duplicate_ids?: string[] }> {
       const res = await fetch(`${baseUrl}/v1/store`, {
         method: 'POST',
-        headers: {
+        headers: buildRelayHeaders({
           'Content-Type': 'application/json',
           Authorization: `Bearer ${authKeyHex}`,
-        },
+        }),
         body: JSON.stringify({ user_id: userId, facts }),
       });
       await assertOk(res, 'store');
@@ -198,10 +205,10 @@ export function createApiClient(serverUrl: string) {
     ): Promise<SearchCandidate[]> {
       const res = await fetch(`${baseUrl}/v1/search`, {
         method: 'POST',
-        headers: {
+        headers: buildRelayHeaders({
           'Content-Type': 'application/json',
           Authorization: `Bearer ${authKeyHex}`,
-        },
+        }),
         body: JSON.stringify({
           user_id: userId,
           trapdoors,
@@ -229,9 +236,9 @@ export function createApiClient(serverUrl: string) {
     async deleteFact(factId: string, authKeyHex: string): Promise<void> {
       const res = await fetch(`${baseUrl}/v1/facts/${encodeURIComponent(factId)}`, {
         method: 'DELETE',
-        headers: {
+        headers: buildRelayHeaders({
           Authorization: `Bearer ${authKeyHex}`,
-        },
+        }),
       });
       await assertOk(res, 'deleteFact');
       const json = (await res.json()) as Record<string, unknown>;
@@ -254,10 +261,10 @@ export function createApiClient(serverUrl: string) {
     async batchDelete(factIds: string[], authKeyHex: string): Promise<number> {
       const res = await fetch(`${baseUrl}/v1/facts/batch-delete`, {
         method: 'POST',
-        headers: {
+        headers: buildRelayHeaders({
           'Content-Type': 'application/json',
           Authorization: `Bearer ${authKeyHex}`,
-        },
+        }),
         body: JSON.stringify({ fact_ids: factIds }),
       });
       await assertOk(res, 'batchDelete');
@@ -290,9 +297,9 @@ export function createApiClient(serverUrl: string) {
 
       const res = await fetch(`${baseUrl}/v1/export?${params.toString()}`, {
         method: 'GET',
-        headers: {
+        headers: buildRelayHeaders({
           Authorization: `Bearer ${authKeyHex}`,
-        },
+        }),
       });
       await assertOk(res, 'exportFacts');
       const json = (await res.json()) as Record<string, unknown>;

package/claims-helper.ts

@@ -96,6 +96,14 @@ export interface BuildClaimInput {
   sourceAgent: string;
   /** Creation timestamp. Defaults to now. */
   extractedAt?: string;
+  /**
+   * 3.3.1-rc.22 — optional embedding-model id stamped on the claim for
+   * forward-compat. Defaults to omitted (callers that already know the
+   * active embedder pass it in; legacy paths leave it unset). The field
+   * is plugin-scoped — it survives the core validator's strip pass via
+   * the same re-attach path used for `schema_version` / `volatility`.
+   */
+  embeddingModelId?: string;
 }
 
 /**
@@ -112,7 +120,7 @@ export interface BuildClaimInput {
  * payload (see `subgraph-store.ts::encodeFactProtobuf`).
  */
 export function buildCanonicalClaim(input: BuildClaimInput): string {
-  const { fact, importance, extractedAt } = input;
+  const { fact, importance, extractedAt, embeddingModelId } = input;
 
   // Defensive: ensure fact.source is always populated before v1 validation.
   // `applyProvenanceFilterLax` should have set this upstream; this is the
@@ -125,6 +133,7 @@ export function buildCanonicalClaim(input: BuildClaimInput): string {
     fact: factWithSource,
     importance,
     createdAt: extractedAt,
+    embeddingModelId,
   });
 }
 
@@ -173,6 +182,14 @@ export interface BuildClaimV1Input {
    * when provided.
    */
   pinStatus?: PinStatus;
+  /**
+   * 3.3.1-rc.22 — optional embedding-model id stamped on the claim for
+   * distillation forward-compat. Survives the core validator strip pass
+   * via the same re-attach path used for `schema_version` / `volatility`.
+   * When omitted the field is not emitted (legacy claims remain untagged
+   * and are read back as "unspecified").
+   */
+  embeddingModelId?: string;
 }
 
 /**
@@ -257,6 +274,13 @@ export function buildCanonicalClaimV1(input: BuildClaimV1Input): string {
   if (fact.volatility && (VALID_MEMORY_VOLATILITIES as readonly string[]).includes(fact.volatility)) {
     canonical.volatility = fact.volatility;
   }
+  // 3.3.1-rc.22 — forward-compat embedder marker. Plugin-only field;
+  // survives the core validator via re-attach. Future distillation
+  // detects this on read to re-embed selectively without forcing a
+  // vault-wide rebuild.
+  if (typeof input.embeddingModelId === 'string' && input.embeddingModelId.length > 0) {
+    canonical.embedding_model_id = input.embeddingModelId;
+  }
 
   return JSON.stringify(canonical);
 }
@@ -313,6 +337,11 @@ export interface BuildV1ClaimBlobInput {
    * non-pin write.
    */
   pinStatus?: PinStatus;
+  /**
+   * 3.3.1-rc.22 — optional embedding-model id stamped on the claim for
+   * distillation forward-compat. See `BuildClaimV1Input.embeddingModelId`.
+   */
+  embeddingModelId?: string;
 }
 
 /**
@@ -374,6 +403,10 @@ export function buildV1ClaimBlob(input: BuildV1ClaimBlobInput): string {
   if (input.volatility && (VALID_MEMORY_VOLATILITIES as readonly string[]).includes(input.volatility)) {
     canonical.volatility = input.volatility;
   }
+  // 3.3.1-rc.22 — see `buildCanonicalClaimV1` comment.
+  if (typeof input.embeddingModelId === 'string' && input.embeddingModelId.length > 0) {
+    canonical.embedding_model_id = input.embeddingModelId;
+  }
   return JSON.stringify(canonical);
 }
 
@@ -431,6 +464,13 @@ export interface V1BlobReadResult {
    * when the writer explicitly omitted the field (treated as `"unpinned"`).
    */
   pinStatus?: PinStatus;
+  /**
+   * 3.3.1-rc.22 — embedder identity tag. Absent on claims written by
+   * older plugin versions. Forward-compat marker; consumers MAY use it
+   * to decide whether a claim's stored embedding matches the active
+   * embedder before letting cosine similarity make a relevance call.
+   */
+  embeddingModelId?: string;
 }
 
 export function readV1Blob(decrypted: string): V1BlobReadResult | null {
@@ -497,6 +537,12 @@ export function readV1Blob(decrypted: string): V1BlobReadResult | null {
         result.pinStatus = ps;
       }
     }
+    // 3.3.1-rc.22 — pull the embedder identity tag through. Plugin-only
+    // field added by `buildCanonicalClaimV1` / `buildV1ClaimBlob` after
+    // core validation.
+    if (typeof obj.embedding_model_id === 'string' && obj.embedding_model_id.length > 0) {
+      result.embeddingModelId = obj.embedding_model_id;
+    }
 
     return result;
   } catch {