@totalreclaw/totalreclaw 3.3.4-rc.1 → 3.3.5-rc.1

package/CHANGELOG.md

@@ -4,6 +4,37 @@ 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.5-rc.1] — 2026-04-30
+
+UX bundle from Pedro's QA on 3.3.4-rc.2:
+
+- **Drop the "yes/no" consent gate before pair setup.** The yes-gate was added
+  in PR #160's safety-tone rewrite to give safety-trained agents an explicit
+  green light before account creation. In practice the user already consents
+  by pasting "Install TotalReclaw" + the canonical URL, and the URL+PIN handed
+  back from `totalreclaw_pair` is the real consent moment (the user has to
+  open the page in their browser to proceed). The extra gate added friction
+  for zero security benefit. Removed from `skill/plugin/SKILL.md`,
+  `skill/SKILL.md`, and `docs/guides/openclaw-setup.md`. The Hermes guide
+  retains its own gate (handled separately).
+- **Tighten silence rules to suppress chat-channel mid-edit churn.** OpenClaw's
+  Telegram channel edits the bot's messages live as the agent's tool calls
+  progress, so every "Let me check…" / "Plugin loaded. Let me verify…" /
+  "I'll now…" line shows up to the user as visible edit churn even if the
+  transport later "deletes" or rewrites it. Added a top-level rule at the
+  start of SKILL.md: "Emit ONLY the user-visible lines. Do not narrate tool
+  calls. Do not describe what you're doing or about to do." Strengthened the
+  forbidden-vocabulary deny-list with the exact patterns Pedro saw in his
+  QA today. Re-stated the canonical user-visible line set as 5–6 lines
+  TOTAL.
+- **Strengthen `/restart` instructions.** Pedro's chat agent on rc.4-rc.2
+  again said "I need permission to restart" instead of issuing the slash
+  command — same anti-pattern that PR #163 / #173 / #174 tried to suppress.
+  Made the SKILL.md instruction more imperative and concrete: "Your IMMEDIATE
+  next message must be the literal slash command `/restart` — nothing else."
+  Added explicit "Do not propose alternatives" guidance for the unauthorized
+  fallback path. Mirrored in `docs/guides/openclaw-setup.md`.
+
 ## [3.3.3-rc.1] — 2026-04-30
 
 Combined RC bundle:

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.4-rc.1
+version: 3.3.5-rc.1
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -26,11 +26,35 @@ metadata:
 
 > 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.
 
+## 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 **5–6 short lines TOTAL** (lines 1, 2, 5, 6 always; lines 3 and 4 only if the corresponding condition fires). 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.
+
+## 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. (start of install)
+   > Installing TotalReclaw…
+2. (after install + auto-reload + `totalreclaw_pair` is bound)
+   > ✓ Installed (totalreclaw &lt;version&gt;)
+3. (optional — only if auto-reload didn't fire and you need to issue `/restart`)
+   > Restarting OpenClaw to load the plugin…
+4. (optional — only if you successfully disabled the built-in memory tool to prevent dual-write)
+   > Disabled built-in memory tool.
+5. (account-setup URL + PIN, immediately after `totalreclaw_pair` returns)
+   > 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.
+6. (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.
+
 ## Setup flow
 
 If `totalreclaw_*` tools are already bound to your toolset, SKIP install and jump to step 4. Otherwise run all steps in order.
 
-1. **Install plugin first, skill second.** Run via your shell tool, in this exact order:
+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
@@ -39,26 +63,39 @@ If `totalreclaw_*` tools are already bound to your toolset, SKIP install and jum
 
    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. **Wait for auto-reload — then issue `/restart` autonomously if needed.** 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.
+2. **Wait for auto-reload — then issue `/restart` autonomously if needed (silent — emit user-visible line 2 on success, line 3 only if you had to restart).** 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. When bound, emit user-visible line 2 and proceed.
+
+   **If `totalreclaw_pair` is NOT visible after 10s — restart imperative (read carefully):**
+
+   > Your IMMEDIATE next message must be the literal slash command `/restart` — nothing else. Do not narrate. Do not ask permission. Do not describe what `/restart` does. Do not propose alternatives. Just send `/restart`. You may emit user-visible line 3 (`Restarting OpenClaw to load the plugin…`) ONCE in the same turn, then issue `/restart`. Nothing else.
+
+   `/restart` is in-process — it drains active runs cleanly; your shell is NOT shelling out to `docker restart` or `openclaw gateway restart` (those would suicide the host). After `/restart`, wait ~3s and re-run `openclaw plugins list`.
 
-   **If `totalreclaw_pair` is NOT visible after 10s:** issue OpenClaw's built-in `/restart` slash-command immediately and silently. **DO NOT ask the user "should I restart" / "do you want me to restart" / "let me check if the tool is bound" — just issue `/restart` and announce "Reloading gateway..." once.** This is in-process and drains active runs cleanly; your shell is NOT shelling out to `docker restart` or `openclaw gateway restart` (which would suicide the host). After `/restart`, wait ~3s and re-run `openclaw plugins list`.
+   **If `/restart` returns "You are not authorized to use this command":** surface this verbatim and stop. Do NOT loop `/restart` calls. Do NOT propose alternatives.
 
-   **If `/restart` returns "You are not authorized to use this command":** the gateway's `channels.<your-channel>.allowFrom` allowlist is empty. **Do NOT keep retrying.** Surface this one-line user-facing fix and stop:
+   > Your Telegram channel needs `allowFrom` configured. Run on your host: `jq '.channels.<channel>.allowFrom = ["<your-id>"]' ~/.openclaw/openclaw.json | sponge ~/.openclaw/openclaw.json && docker restart <your-container-name>`. Substitute `<channel>` (e.g. `telegram`, `slack`), `<your-id>` (Telegram: `@username` or numeric `chat_id`; Slack: workspace member ID), and `<your-container-name>` (`docker ps` shows it). For non-Docker installs substitute `openclaw gateway restart` for the `docker restart` portion. On a managed service, ask the service's support to enable slash commands. Reply `done` after.
 
-   > Your channel needs to be allowlisted for slash commands. Run on the gateway host: `jq '.channels.<channel>.allowFrom = ["<your-id>"]' ~/.openclaw/openclaw.json | sponge ~/.openclaw/openclaw.json && docker restart <your-container-name>` (Docker self-host) — substitute `<channel>` with your channel name (e.g. `telegram`, `slack`), `<your-id>` with your user ID for that channel (Telegram: `@username` or numeric `chat_id`; Slack: workspace member ID), and `<your-container-name>` with your gateway container name (`docker ps` shows it). On a managed service, ask the service's support to enable slash commands for your channel. Reply `done` once it's back up.
+   Then wait for `done`. Do NOT retry the install. Do NOT keep restarting. As a last-resort session-level fallback while restart is gated, try `/new` once (fresh session within the same gateway process, may pick up freshly-bound tools without a full restart).
 
-   For non-Docker / native deployments substitute `openclaw gateway restart` for the `docker restart` portion. As a session-level fallback while restart is gated, try `/new` (starts a fresh session within the same gateway process, may pick up freshly-bound tools without a full restart).
+   **Forbidden vocabulary** (these are anti-patterns — they show up to the user even if your transport edits them later, and they 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 /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"
 
-   **Forbidden vocabulary** (these are anti-patterns when a tool is missing post-install): "Should I /restart", "Do you have a public URL", "Want me to restart", "Let me check if the tool is bound", "I need permission to restart". Just issue `/restart` immediately and announce.
+   Substitute all of these with silence — the next user-visible line in the set, or nothing.
 
 3. **Verify `totalreclaw_pair` is bound.** If still missing after `/restart` (or after the user fixed allowFrom and said `done`), tell them the restart didn't take effect and ask them to retry. Do not loop the install.
 
-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.
+4. **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.
 
-5. **Set up the user's TotalReclaw account.** Tell the user: *"I'll walk you through setting up your TotalReclaw account."* Then call `totalreclaw_pair` (the account-setup tool — name kept for backward compatibility). 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.*
+5. **Set up the user's TotalReclaw account (emit user-visible line 5 once, after `totalreclaw_pair` returns).** Call `totalreclaw_pair` silently (the account-setup tool — name kept for backward compatibility). It returns `{url, pin, qr_ascii, qr_png_b64, qr_unicode, expires_at_ms}` (see "Rendering the QR" below). Then emit user-visible line 5 with `<url>` and `<pin>` substituted. Do not pre-narrate ("I'll walk you through…", "Setting up your account now…") — line 5 itself is the only thing the user needs to see. The URL + PIN itself is the real consent moment: surfacing them verbatim is what gives the user the chance to opt out by simply not opening the page.
 
-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 *"Your TotalReclaw account is set up. Ask me to remember or recall anything."*
+6. **Verify and confirm (silent until line 6).** After the user says `done`, re-run `test -s ~/.totalreclaw/credentials.json`. If missing, the PIN expired — call `totalreclaw_pair` again silently and resend line 5 once. If present, emit user-visible line 6 and stop.
 
 ## Rendering the QR on your transport (rc.5+)
 

package/dist/index.js

@@ -4686,9 +4686,23 @@ const plugin = {
                             // Background task — writes credentials.json + flips state when
                             // the browser completes the flow. Tool handler returns
                             // immediately so the agent can tell the user the URL + PIN.
+                            //
+                            // 3.3.4-rc.2 (Pedro QA — pair flow stuck-session) — wrap the
+                            // WS-await in a 60s hard timeout. The relay drops sessions on
+                            // `ws_close` (separately patched relay-side); without this
+                            // bound the background task hangs in `waitNextMessage` for the
+                            // full 5-minute session TTL before resolving, and downstream
+                            // tooling that polls the gateway for completion sees stale
+                            // `processing` state at 129s/159s/189s. 60s is the user-side
+                            // deadline we surface in chat: long enough for a slow scan-
+                            // and-paste, short enough that a fresh URL request is the
+                            // obvious next step. Structured `timed_out` error in the log
+                            // lets ops grep for the failure mode independently of generic
+                            // ws-close errors.
+                            const PAIR_TOOL_HARD_TIMEOUT_MS = 60_000;
                             void (async () => {
                                 try {
-                                    await awaitPhraseUpload(remoteSession, {
+                                    const phraseUploadPromise = awaitPhraseUpload(remoteSession, {
                                         phraseValidator: (p) => validateMnemonic(p, wordlist),
                                         completePairing: async ({ mnemonic }) => {
                                             try {
@@ -4728,7 +4742,37 @@ const plugin = {
                                                 return { state: 'error', error: msg };
                                             }
                                         },
+                                        // 3.3.4-rc.2 — also pass through to awaitPhraseUpload so its
+                                        // internal `waitNextMessage` timer matches the outer race.
+                                        timeoutMs: PAIR_TOOL_HARD_TIMEOUT_MS,
+                                    });
+                                    // 3.3.4-rc.2 — outer Promise.race guard. Resolves to a
+                                    // sentinel ({ status: 'timed_out', ... }) so the catch
+                                    // handler can distinguish a hard-timeout from a generic
+                                    // ws-close error and surface it explicitly.
+                                    const TIMEOUT_SENTINEL = {
+                                        status: 'timed_out',
+                                        message: `Pair flow timed out (${PAIR_TOOL_HARD_TIMEOUT_MS / 1000}s) — generate a new URL with totalreclaw_pair.`,
+                                    };
+                                    let hardTimer;
+                                    const hardTimeoutPromise = new Promise((resolve) => {
+                                        hardTimer = setTimeout(() => resolve(TIMEOUT_SENTINEL), PAIR_TOOL_HARD_TIMEOUT_MS);
                                     });
+                                    try {
+                                        const raced = await Promise.race([
+                                            phraseUploadPromise,
+                                            hardTimeoutPromise,
+                                        ]);
+                                        if (raced &&
+                                            typeof raced === 'object' &&
+                                            raced.status === 'timed_out') {
+                                            api.logger.warn(`totalreclaw_pair(relay): hard timeout — ${raced.message} (token=${remoteSession.token.slice(0, 8)}…)`);
+                                        }
+                                    }
+                                    finally {
+                                        if (hardTimer)
+                                            clearTimeout(hardTimer);
+                                    }
                                 }
                                 catch (bgErr) {
                                     // Expected on TTL expiry / user-aborts — log at warn, not error.

package/dist/pair-cli-relay.js

@@ -44,7 +44,7 @@
  * `CONFIG`. See `index.ts` wire-up.
  */
 import { validateMnemonic } from '@scure/bip39';
-import { wordlist } from '@scure/bip39/wordlists/english';
+import { wordlist } from '@scure/bip39/wordlists/english.js';
 import { loadCredentialsJson, writeCredentialsJson, writeOnboardingState, } from './fs-helpers.js';
 import { awaitPhraseUpload, openRemotePairSession, } from './pair-remote-client.js';
 import { setRecoveryPhraseOverride } from './config.js';

package/index.ts

@@ -5496,9 +5496,23 @@ const plugin = {
               // Background task — writes credentials.json + flips state when
               // the browser completes the flow. Tool handler returns
               // immediately so the agent can tell the user the URL + PIN.
+              //
+              // 3.3.4-rc.2 (Pedro QA — pair flow stuck-session) — wrap the
+              // WS-await in a 60s hard timeout. The relay drops sessions on
+              // `ws_close` (separately patched relay-side); without this
+              // bound the background task hangs in `waitNextMessage` for the
+              // full 5-minute session TTL before resolving, and downstream
+              // tooling that polls the gateway for completion sees stale
+              // `processing` state at 129s/159s/189s. 60s is the user-side
+              // deadline we surface in chat: long enough for a slow scan-
+              // and-paste, short enough that a fresh URL request is the
+              // obvious next step. Structured `timed_out` error in the log
+              // lets ops grep for the failure mode independently of generic
+              // ws-close errors.
+              const PAIR_TOOL_HARD_TIMEOUT_MS = 60_000;
               void (async () => {
                 try {
-                  await awaitPhraseUpload(remoteSession, {
+                  const phraseUploadPromise = awaitPhraseUpload(remoteSession, {
                     phraseValidator: (p: string) =>
                       validateMnemonic(p, wordlist),
                     completePairing: async ({ mnemonic }) => {
@@ -5546,7 +5560,48 @@ const plugin = {
                         return { state: 'error', error: msg };
                       }
                     },
+                    // 3.3.4-rc.2 — also pass through to awaitPhraseUpload so its
+                    // internal `waitNextMessage` timer matches the outer race.
+                    timeoutMs: PAIR_TOOL_HARD_TIMEOUT_MS,
                   });
+                  // 3.3.4-rc.2 — outer Promise.race guard. Resolves to a
+                  // sentinel ({ status: 'timed_out', ... }) so the catch
+                  // handler can distinguish a hard-timeout from a generic
+                  // ws-close error and surface it explicitly.
+                  const TIMEOUT_SENTINEL: {
+                    status: 'timed_out';
+                    message: string;
+                  } = {
+                    status: 'timed_out',
+                    message:
+                      `Pair flow timed out (${PAIR_TOOL_HARD_TIMEOUT_MS / 1000}s) — generate a new URL with totalreclaw_pair.`,
+                  };
+                  let hardTimer: ReturnType<typeof setTimeout> | undefined;
+                  const hardTimeoutPromise = new Promise<typeof TIMEOUT_SENTINEL>(
+                    (resolve) => {
+                      hardTimer = setTimeout(
+                        () => resolve(TIMEOUT_SENTINEL),
+                        PAIR_TOOL_HARD_TIMEOUT_MS,
+                      );
+                    },
+                  );
+                  try {
+                    const raced = await Promise.race([
+                      phraseUploadPromise,
+                      hardTimeoutPromise,
+                    ]);
+                    if (
+                      raced &&
+                      typeof raced === 'object' &&
+                      (raced as { status?: unknown }).status === 'timed_out'
+                    ) {
+                      api.logger.warn(
+                        `totalreclaw_pair(relay): hard timeout — ${(raced as typeof TIMEOUT_SENTINEL).message} (token=${remoteSession.token.slice(0, 8)}…)`,
+                      );
+                    }
+                  } finally {
+                    if (hardTimer) clearTimeout(hardTimer);
+                  }
                 } catch (bgErr: unknown) {
                   // Expected on TTL expiry / user-aborts — log at warn, not error.
                   const bgMsg = bgErr instanceof Error ? bgErr.message : String(bgErr);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.4-rc.1",
+  "version": "3.3.5-rc.1",
   "description": "End-to-end encrypted, agent-portable memory for OpenClaw and any LLM-agent runtime. XChaCha20-Poly1305 with protobuf v4 + on-chain Memory Taxonomy v1 (claim / preference / directive / commitment / episode / summary).",
   "type": "module",
   "keywords": [
@@ -31,6 +31,7 @@
   "author": "TotalReclaw Team",
   "license": "MIT",
   "dependencies": {
+    "@scure/bip39": "^2.2.0",
     "@totalreclaw/client": "^1.2.0",
     "@totalreclaw/core": "^2.1.1",
     "@types/qrcode": "^1.5.6",

package/pair-cli-relay.ts

@@ -45,7 +45,7 @@
  */
 
 import { validateMnemonic } from '@scure/bip39';
-import { wordlist } from '@scure/bip39/wordlists/english';
+import { wordlist } from '@scure/bip39/wordlists/english.js';
 
 import {
   loadCredentialsJson,

package/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "totalreclaw",
-  "version": "3.3.4-rc.1",
+  "version": "3.3.5-rc.1",
   "description": "End-to-end encrypted memory for AI agents — portable, yours forever. XChaCha20-Poly1305 E2EE: server never sees plaintext.",
   "author": "TotalReclaw Team",
   "license": "MIT",