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

package/CHANGELOG.md

@@ -4,6 +4,289 @@ 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.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.
+
+### 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.6 documented on the Python side only; a later plugin bug would then have to skip to rc.7 to catch up. Much simpler to bump both in lockstep.
+
+### Skipped
+
+- **`3.3.1-rc.5`** — PR #76 (branch `fix/plugin-3.3.1-rc.5-qr-display`) remained unmerged when the rc.4 Hermes regression was escalated. rc.5's QR-display work rebases onto rc.6 as a follow-up.
+
+## [3.3.1-rc.4] — 2026-04-22
+
+Phrase-safety hardening: `totalreclaw_onboard` agent tool removed. Paired with Hermes Python `2.3.1rc4` (which ports the QR-pair flow to Python so Hermes users gain a phrase-safe agent setup path too).
+
+### Removed (phrase-safety enforcement — BREAKING for agent tool callers)
+
+- **`totalreclaw_onboard` agent tool — REMOVED.** rc.3 shipped a `totalreclaw_onboard` tool that generated a fresh BIP-39 mnemonic in-process, wrote it to `credentials.json`, and returned `{scope_address, credentials_path}`. `emitPhrase: false` kept the mnemonic out of the tool's return payload, but NOTHING ARCHITECTURALLY PREVENTED leakage — a future patch could regress the flag, a different code path could echo the mnemonic in a log/error, or the mere existence of the tool signalled to agents that phrase generation inside chat is fine (it isn't). Per `project_phrase_safety_rule.md`: "recovery phrase MUST NEVER cross the LLM context in ANY form." rc.4 removes the registration. The underlying `runNonInteractiveOnboard` code path stays reachable via the CLI `openclaw totalreclaw onboard` — that path runs in the user's own terminal, OUTSIDE any agent shell, so phrase stdout never feeds back into LLM context.
+
+### Changed
+
+- **`SKILL.md` — setup section rewritten.** `totalreclaw_pair` is now the canonical setup surface for all users (local or remote). The CLI wizard (`openclaw totalreclaw onboard`) is explicitly documented as user-terminal-only — agents MUST NOT invoke it via their shell tool. Tool surface table updated: `totalreclaw_onboard` removed, `totalreclaw_pair` promoted to canonical. `totalreclaw_onboarding_start` remains as a pointer-only tool for users who explicitly prefer local-terminal setup.
+- **`index.ts` — `totalreclaw_pair` tool description updated.** Removed backref to `totalreclaw_onboard`; now instructs agents to always prefer pair, with `totalreclaw_onboarding_start` as the fallback pointer for local-terminal-only users.
+- **`docs/guides/openclaw-setup.md` — QR pairing is now documented as the default setup flow.** CLI wizard moved to a user-terminal-only subsection with a prominent "do NOT run this through an agent shell" warning.
+
+### Tests
+
+- **`phrase-safety-registry.test.ts`** — new. Text-scans `index.ts` for `api.registerTool({ name: '...' })` literals and asserts: (a) `totalreclaw_onboard` is NOT in the list; (b) `totalreclaw_pair` IS in the list; (c) no name contains phrase-adjacent tokens (`onboard_generate`, `generate_phrase`, `generate_mnemonic`, `restore_phrase`, `restore_mnemonic`, `mnemonic`). Runs as part of `npm test`.
+
+## [3.3.1-rc.3] — 2026-04-22
+
+Patch RC bundling two stability fixes, one new RC-gated tool, two SKILL.md addendums, and a configurable LLM retry budget. All prior rc.1 + rc.2 fixes are preserved.
+
+### Changed
+
+- **`llm-client.ts` — configurable `ZAI_BASE_URL` + auto-fallback on "Insufficient balance" 429.** rc.2 QA surfaced that GLM Coding Plan keys hitting the STANDARD zai endpoint (and PAYG keys hitting CODING) return HTTP 429 with body `"Insufficient balance or no resource package. Please recharge."` — misleading because the key itself is valid. rc.3: (a) accepts `ZAI_BASE_URL` env override via `config.ts` / `getZaiBaseUrl()`; (b) auto-detects the error signature and flips CODING ↔ STANDARD once per call (logged at INFO). SKILL.md now documents "GLM Coding Plan → leave unset; PAYG → set `ZAI_BASE_URL=https://api.z.ai/api/paas/v4`."
+- **`llm-client.ts` — retry budget 7s → ~62s (configurable).** rc.1/rc.2 QA: 5–9 of 10 extraction windows returned 0 facts against multi-minute upstream 429 storms. The 3-attempt 1s/2s/4s backoff couldn't outlast a 9-minute outage. rc.3: 5 attempts, 2s/4s/8s/16s/32s backoff, total ~62s. Configurable via `TOTALRECLAW_LLM_RETRY_BUDGET_MS` env (default 60_000). First retry logs at INFO, rest at DEBUG (debounced — no spam during long outages). On exhaustion throws `LLMUpstreamOutageError` (structured, `attempts` + `lastStatus`) so extraction callers can recognise vs bail silently. Non-retryable errors (401/403/404/parse) still propagate as plain `Error`.
+- **`subgraph-store.ts` — per-account submission mutex.** rc.2 logged 16 AA25 `invalid account nonce` events from concurrent `submitFactBatchOnChain` / `submitFactOnChain` calls racing at the `eth_call getNonce(sender, 0)` step. rc.3 wraps both submission entry points in a per-`sender` `Map<scopeAddress, Promise>` chain so only one UserOp is in flight per Smart Account at a time. The existing AA25-retry-with-fresh-nonce path is unchanged and still catches relay-side zombie UserOps.
+
+### Added
+
+- **`totalreclaw_report_qa_bug`** (RC-gated tool) — lets agents file structured QA-bug issues to `p-diogo/totalreclaw-internal` without the maintainer opening a fresh issue per RC finding. Only registered when the plugin version matches the `-rc.` token (via `readPluginVersion` in `fs-helpers.ts` + `isRcBuild` in the new `qa-bug-report.ts`). Handler POSTs to `https://api.github.com/repos/.../issues` with `Authorization: Bearer <token>` where `token = CONFIG.qaGithubToken` (reads `TOTALRECLAW_QA_GITHUB_TOKEN` or `GITHUB_TOKEN`). Secrets (BIP-39 phrases, `sk-*`, `AIzaSy*`, Telegram bot tokens, bearer tokens, 64+ char hex blobs, 0x-private-keys, `token=`/`secret=` qualifiers) are redacted fail-close in `redactSecrets()` before POST. Stable builds never expose this tool. See SKILL.md "Filing QA bugs (RC builds only)" for trigger rules — always ask user before filing, never the same bug twice.
+- **`skill/plugin/qa-bug-report.ts`** — new pure-logic + HTTP module. Exports `isRcBuild`, `redactSecrets`, `validateQaBugArgs`, `buildIssueBody`, `postQaBugIssue`. Unit-tested in `qa-bug-report.test.ts`.
+- **`skill/plugin/nonce-serialization.test.ts`** — exercises the per-`sender` mutex primitive: same-sender serializes, different-sender runs in parallel, case-insensitive keying, first-call failure releases the lock for the next.
+- **`fs-helpers.ts` — `readPluginVersion(packageJsonDir)`** — scanner-safe helper used by the RC gate. Resolves via `path.dirname(fileURLToPath(import.meta.url))` in `index.ts` and returns the `version` field from `package.json` next to the module.
+
+### SKILL.md
+
+- **First-person recall rule.** rc.2 debug found agents skipped `totalreclaw_recall` in 5/5 attempts on "Where do I live?". SKILL.md now hard-rules it: any first-person factual query ("where do I live/work", "what do I prefer", "my [noun]", etc.) MUST call recall first. If recall returns 0, say "I don't have anything about that yet" rather than invent.
+- **QA bug triggers.** New "Filing QA bugs (RC builds only)" section with the four triggers (repeated tool failure, user friction signals, setup errors, docs-vs-reality mismatch). Offer to file, never auto-file, never same bug twice.
+- **zai endpoint + retry budget** documented in a new "zai provider configuration" section.
+
+### Tests
+
+- `llm-client-retry.test.ts` extended from 29 → 59 assertions. Covers: balance-error detection, CODING↔STANDARD fallback URL helper, `ZAI_BASE_URL` env override, full fallback happy/sad paths, `LLMUpstreamOutageError` surfacing, budget short-circuit.
+- `qa-bug-report.test.ts` — 57 assertions covering isRcBuild, redactSecrets (BIP-39 / sk- / AIza / Telegram / Bearer / hex / private-key / preservation of UUIDs+SHAs+addresses), validateQaBugArgs, buildIssueBody, postQaBugIssue success + all failure paths.
+- `nonce-serialization.test.ts` — 9 assertions.
+- All existing tests (`llm-client.test.ts`, `manifest-shape.test.ts`, etc.) unchanged and green.
+
+### Scanner
+
+- `check-scanner.mjs` still passes (0 flags). The `TOTALRECLAW_QA_GITHUB_TOKEN` + `ZAI_BASE_URL` + `TOTALRECLAW_LLM_RETRY_BUDGET_MS` env reads live in `config.ts` (the env-harvesting-free house). `llm-client.ts`, `index.ts`, and `qa-bug-report.ts` all stay off `process.env`.
+
 ## [3.3.1-rc.2] — 2026-04-22
 
 Follow-up RC for the 3.3.1-rc.1 QA NO-GO

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: totalreclaw
-description: "End-to-end encrypted memory for AI agents — portable, yours forever. XChaCha20-Poly1305 E2EE: server never sees plaintext."
-version: 3.3.1-rc.2
+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.11
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -22,95 +22,62 @@ metadata:
       - persistent-context
 ---
 
-# TotalReclaw — Agent Guide
+# TotalReclaw — OpenClaw
 
-You are operating inside a host that has the TotalReclaw memory plugin loaded. This file tells you WHAT to call and WHEN. Every sentence is a rule.
+> 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.
 
-## Setup state
+## Setup flow
 
-Before any memory tool, check `~/.totalreclaw/credentials.json`:
+If `totalreclaw_*` tools are already bound to your toolset, SKIP install and jump to step 4. Otherwise run all steps in order.
 
-- **Missing, empty, malformed, or no `mnemonic` key** -> NOT set up. You MUST NOT generate a phrase in chat, and you MUST NOT ask the user to paste one. Route:
-  - Local gateway: call `totalreclaw_onboarding_start` (or `totalreclaw_onboard` if available); both return a pointer to `openclaw totalreclaw onboard`.
-  - Remote gateway (VPS / Docker / no TTY): call `totalreclaw_pair` (v3.3.1+), OR instruct the user to run `openclaw totalreclaw pair generate --json`. Present the returned `{url, pin, qr_ascii}` to the user. The phrase is entered in their browser, never in this conversation.
-- **Present with a valid `mnemonic`** -> active. Use the tools below.
+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.
 
-## Core rules
+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`.
 
-1. **Phrase safety (NON-NEGOTIABLE).** The recovery phrase is a secret. Never generate one in chat, never echo one back, never log one in reasoning / tool payloads, never pass one to another tool. Direct users to `cat ~/.totalreclaw/credentials.json | jq -r .mnemonic`.
-2. **Use the tools, not inline state.** `totalreclaw_remember` stores; `totalreclaw_recall` retrieves. Don't re-ask the user for past facts; don't paraphrase memories as your own recollection.
-3. **Gateway restart is required after install.** If tools fail right after `openclaw plugins install @totalreclaw/totalreclaw`, tell the user to run `openclaw restart` or `docker restart openclaw-qa`.
+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.
 
-## Decision tree — which tool, when
+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.
 
-- **Fact-shaped content** (preferences, identity, commitments, decisions, directives, episodes): `totalreclaw_remember`. Don't ask permission for obvious user facts.
-- **Question about the past** ("what do you remember about…", "do I like…"): `totalreclaw_recall`.
-- **"Pin that" / "remember permanently"**: `totalreclaw_pin`. **"Unpin" / "can forget that"**: `totalreclaw_unpin`.
-- **"Forget X" / "delete that memory"**: `totalreclaw_forget` with the fact's id.
-- **"That's a preference, not a claim"**: `totalreclaw_retype`.
-- **"Put that under work"**: `totalreclaw_set_scope`.
-- **"Export my memories"**: `totalreclaw_export`.
-- **"What's my TotalReclaw status?"**: `totalreclaw_status`.
-- **"Set up TotalReclaw"** (no credentials): route per the Setup-state section above.
-- **"Import my Mem0 / ChatGPT / Claude / Gemini history"**: `totalreclaw_import_from` with `dry_run=true` first. Show the estimate, confirm, then run without `dry_run`. For >50 chunks, use `totalreclaw_import_batch` and report progress.
-- **"Upgrade" / "I want Pro"**: `totalreclaw_upgrade` returns a Stripe URL. After upgrade, offer `totalreclaw_migrate` (dry-run first) to move testnet memories to mainnet.
+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` (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)
+
+- Stable user facts / preferences / identity / "remember X" → `totalreclaw_remember` (don't ask permission).
+- First-person factual query ("do I / what's my / where do I …") → `totalreclaw_recall` FIRST, then answer from returned facts. If 0 results, say so.
+- "forget / pin / unpin / retype / move to <scope>" X → `totalreclaw_recall` first for `factId`, then `totalreclaw_forget` / `_pin` / `_unpin` / `_retype` / `_set_scope`.
+- "status" → `totalreclaw_status`. "upgrade" → `totalreclaw_upgrade` (paste Stripe URL verbatim). Post-upgrade testnet → mainnet: `totalreclaw_migrate` with `dry_run` first.
+- "import / export / consolidate" → `totalreclaw_import_from` (`dry_run=true` first; `_import_batch` for >50 chunks) · `totalreclaw_export` · `totalreclaw_consolidate` (`dry_run` first).
+
+## Diagnostics
+
+- `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`.
+- `No LLM available for auto-extraction` at startup → provider key unreachable; check `~/.openclaw/agents/<agent>/agent/auth-profiles.json` or plugin config `extraction.llm`.
 
 ## Tool surface
 
-Tools work only when credentials are active AND the gateway has been restarted post-install. If a tool returns "onboarding required", route back to onboarding.
-
-| Tool | Key params |
-|------|------------|
-| `totalreclaw_remember` | `text`, optional `type` (default `claim`), `importance` |
-| `totalreclaw_recall` | `query`, optional `k` (default 8, max 20) |
-| `totalreclaw_forget` | `factId` |
-| `totalreclaw_pin` / `totalreclaw_unpin` | `factId`, optional `reason` |
-| `totalreclaw_retype` | `factId`, `newType` |
-| `totalreclaw_set_scope` | `factId`, `scope` |
-| `totalreclaw_export` | optional `format` (`json` / `markdown`) |
-| `totalreclaw_status` | (none) |
-| `totalreclaw_upgrade` | (none) |
-| `totalreclaw_migrate` | optional `confirm` (dry-run by default) |
-| `totalreclaw_import_from` / `totalreclaw_import_batch` | `source`, `file_path` or `content`, `dry_run` |
-| `totalreclaw_consolidate` | optional `dry_run` |
-| `totalreclaw_onboarding_start` / `totalreclaw_onboard` | (none) — returns CLI pointer |
-| `totalreclaw_pair` | optional `mode` (`generate` / `import`) — returns `{url, pin, qr_ascii, expires_at_ms}` |
-
-## Taxonomy
-
-**Types:** `claim` (default) / `preference` / `directive` (reusable rule) / `commitment` (future intent) / `episode` (event) / `summary` (derived synthesis).
-
-**Scopes:** `work` / `personal` (default) / `health` / `family` / `creative` / `finance` / `misc`.
-
-## If a tool fails
-
-- Tell the user plainly. Don't retry blindly.
-- "onboarding required" -> route per Setup-state above.
-- "No LLM available for auto-extraction" (startup only, v3.3.1+) -> provider key not reachable. Point at `~/.openclaw/agents/<agent>/agent/auth-profiles.json` or the `plugins.entries.totalreclaw.config.extraction.llm` override.
-- Silent extraction failures -> suggest `openclaw totalreclaw status` or check `~/.totalreclaw/billing-cache.json` for rate-limit signals.
-
-## Minimum viable interaction pattern
-
-```
-User: "I live in Porto and prefer PostgreSQL."
--> totalreclaw_remember({text: "User lives in Porto", type: "claim"})
--> totalreclaw_remember({text: "User prefers PostgreSQL over MySQL", type: "preference"})
--> respond naturally, don't list what you just saved.
-
-User: "What do you remember about me?"
--> totalreclaw_recall({query: "user facts preferences identity"})
--> summarize returned facts in your reply.
-
-User: "Set me up for TotalReclaw."
--> check ~/.totalreclaw/credentials.json. If missing:
-   local:  totalreclaw_onboarding_start (or totalreclaw_onboard)
-   remote: totalreclaw_pair -> present URL + PIN + QR
--> follow the tool's instructions. Never invent a phrase.
-```
-
-## What NOT to do
-
-- Do NOT write memories to `MEMORY.md` or any cleartext file — that defeats E2EE.
-- Do NOT call `totalreclaw_remember` for transient in-session context.
-- Do NOT paste recovery phrases or API keys into chat.
-- Do NOT run `npx @totalreclaw/mcp-server setup` — deprecated path that corrupts credentials.
+`totalreclaw_pair` (ONLY setup path) · `_remember` · `_recall` · `_forget` · `_pin` · `_unpin` · `_retype` · `_set_scope` · `_export` · `_status` · `_upgrade` · `_migrate` · `_import_from` · `_import_batch` · `_consolidate` · `_onboarding_start` (pointer to local-terminal wizard, for users explicitly rejecting the browser flow) · `_report_qa_bug` (RC only).

package/config.ts

@@ -105,6 +105,21 @@ export const CONFIG = {
   // for 15-min TTL windows; 0600 mode.
   pairSessionsPath: process.env.TOTALRECLAW_PAIR_SESSIONS_PATH || path.join(home, '.totalreclaw', 'pair-sessions.json'),
 
+  // 3.3.1-rc.11 — pair-flow transport selector. Mirrors the Python-side
+  // `TOTALRECLAW_PAIR_MODE` env (rc.10). `'relay'` (default) routes
+  // `totalreclaw_pair` through the universal-reachability WebSocket relay at
+  // `TOTALRECLAW_PAIR_RELAY_URL`. `'local'` preserves the rc.4–rc.10 loopback
+  // HTTP flow (the plugin serves `/plugin/totalreclaw/pair/*` via
+  // `pair-http.ts`). Air-gapped / self-hosted users can pin `'local'` here.
+  pairMode: (() => {
+    const v = (process.env.TOTALRECLAW_PAIR_MODE ?? '').trim().toLowerCase();
+    return v === 'local' ? 'local' : 'relay';
+  })() as 'relay' | 'local',
+  // 3.3.1-rc.11 — relay base URL for the WebSocket-brokered pair flow.
+  // `wss://` preferred; `https://` is rewritten in the remote-client.
+  pairRelayUrl: (process.env.TOTALRECLAW_PAIR_RELAY_URL
+    || 'wss://api-staging.totalreclaw.xyz').replace(/\/+$/, ''),
+
   // Chain — chainId is no longer user-configurable. It is auto-detected from
   // the relay billing response (free = Base Sepolia / 84532, Pro = Gnosis /
   // 100). The default here is used only before the first billing lookup
@@ -157,6 +172,48 @@ export const CONFIG = {
     cerebras: process.env.CEREBRAS_API_KEY || '',
   } as Record<string, string>,
 
+  // 3.3.1-rc.3: zai base-URL override. Read via a getter so tests can
+  // mutate `process.env.ZAI_BASE_URL` between calls — the value is NOT
+  // frozen at module load. Default is the coding endpoint; the rc.3
+  // auto-fallback flips to the standard endpoint on an "Insufficient
+  // balance" 429.
+  get zaiBaseUrl(): string {
+    const override = process.env.ZAI_BASE_URL;
+    if (override && override.trim()) return override.trim().replace(/\/+$/, '');
+    return 'https://api.z.ai/api/coding/paas/v4';
+  },
+
+  // 3.3.1-rc.3: retry budget for chatCompletion. Default 60s covers
+  // multi-minute upstream outages. Read as a plain value (not getter)
+  // so tests that patch env need to reload the module — but the default
+  // suffices for production.
+  llmRetryBudgetMs: (() => {
+    const raw = process.env.TOTALRECLAW_LLM_RETRY_BUDGET_MS;
+    const parsed = raw ? parseInt(raw, 10) : NaN;
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 60_000;
+  })(),
+
+  // 3.3.1-rc.3: GitHub personal-access token used by the RC-gated
+  // `totalreclaw_report_qa_bug` tool. `TOTALRECLAW_QA_GITHUB_TOKEN` is
+  // the dedicated variable; `GITHUB_TOKEN` is a fallback for CI-style
+  // setups where the same token is shared across tools. Read via getter
+  // so operators can set the var after the process starts (e.g. via a
+  // dotenv reload) and the next tool call picks it up.
+  get qaGithubToken(): string {
+    return process.env.TOTALRECLAW_QA_GITHUB_TOKEN || process.env.GITHUB_TOKEN || '';
+  },
+
+  // 3.3.1-rc.14: optional target-repo override for the RC-gated QA
+  // bug-report tool. The `qa-bug-report` module enforces a
+  // "slug ends in `-internal`" rule on whatever is resolved here, so
+  // this override is only useful for forks / mirrors of the internal
+  // tracker. Leaving unset uses the production default
+  // (`p-diogo/totalreclaw-internal`). Read via getter so operators can
+  // flip the var at runtime.
+  get qaRepoOverride(): string {
+    return process.env.TOTALRECLAW_QA_REPO || '';
+  },
+
   // Paths
   home,
   billingCachePath: path.join(home, '.totalreclaw', 'billing-cache.json'),