@totalreclaw/totalreclaw 3.3.1 → 3.3.2-rc.2

package/CHANGELOG.md

@@ -4,7 +4,83 @@ 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]
+## [3.3.2-rc.1] — 2026-04-27
+
+Hotfix bundle for the inside-gateway agent-flow ship-stoppers caught by the
+2026-04-27 user QA against stable 3.3.1 (umbrella issue #182). The four fixes
+combined unblock the agent-driven canonical install path.
+
+### Added — filesystem load manifest (issue #186)
+
+The plugin now writes `.loaded.json` and `.error.json` into its own
+extension directory at register-time. The agent has no working CLI inside
+the gateway (issue #182 finding F1 — `openclaw plugins list` hangs in
+some Docker setups), so the manifests are the canonical filesystem signal
+that register() ran to completion AND which tools the SDK saw.
+
+- `~/.openclaw/extensions/totalreclaw/.loaded.json` —
+  `{loadedAt: <ms>, tools: [<name>...], version: <semver>}`. Written
+  synchronously at the end of `register(api)`. Captures every tool name
+  passed to `api.registerTool` during the call.
+- `~/.openclaw/extensions/totalreclaw/.error.json` —
+  `{loadedAt, error, stack?, version?}`. Written from the try/catch
+  surrounding the register() body when register() throws. Successful
+  boots clear any stale `.error.json`; failed boots preserve any prior
+  `.loaded.json` so the agent can compare timestamps.
+
+Synchronous writes only (same constraint as `registerHttpRoute` — the SDK
+freezes plugin registries the moment register() returns; an async write
+would race that freeze and the manifest could miss late tool
+registrations).
+
+Regression: `load-manifest.test.ts` (22 assertions).
+
+### Added — `totalreclaw_pair` declared in skill manifest (issue #185)
+
+The `totalreclaw_pair` tool is now advertised in `skill.json` alongside
+`totalreclaw_remember`/`recall`/`forget`/`export`/`status`/`consolidate`/
+`upgrade`/`import_from`. Previously plugin-only — if the plugin runtime
+load failed silently (e.g. dep race in #188), the tool never appeared
+in the agent's toolset and the canonical setup flow was unreachable.
+
+The skill-side declaration ensures the tool name is visible in the
+skill registry advertisement even when plugin runtime issues prevent
+binding. The implementation remains in the plugin (browser-side
+e2e-encrypted recovery-phrase flow); only the declaration moves up.
+
+### Added — atomic dependency validation in postinstall (issue #188)
+
+`postinstall.mjs` is now a real lifecycle script (replacing the inline
+`node -e` shim). After `npm install`, it require()s every critical dep
+(`@scure/bip39`, `@scure/bip39/wordlists/english.js`, `@totalreclaw/core`,
+`@totalreclaw/client`, `qrcode`, `ws`). On first-attempt failure: clears
+`node_modules`, re-runs `npm install --ignore-scripts` once, re-validates.
+If retry also fails, exits non-zero so the install surfaces the failure
+instead of writing `enabled: true` over a broken half-state.
+
+The retry loop can be skipped with `TOTALRECLAW_SKIP_POSTINSTALL_RETRY=1`
+for sandboxed CI / restricted-network environments.
+
+Phrase-safety: the script does NOT touch credentials.json, mnemonics,
+or any phrase code path. Only validates module loading and cleans
+staging directories.
+
+### Added — install-stage cleanup at install-time (issue #190)
+
+`postinstall.mjs` extends the rc.21 staging-cleanup behavior (which ran
+at register-time) to ALSO sweep `<extensions>/.openclaw-install-stage-*`
+siblings during the post-install step itself. Goal: a re-install starts
+from a clean parent dir, eliminating the
+"duplicate plugin id detected; global plugin will be overridden by global
+plugin" warning during the install. Safety: skipped when the plugin's
+parent dir is not an `extensions/` directory (dev checkouts) so no random
+siblings are deleted.
+
+Regression: `postinstall-validation.test.ts` (17 assertions) covers
+happy path, marker clearing, staging sweep, idempotent re-runs,
+unrelated-dotfile preservation, and dev-checkout safety.
+
+
 
 ### Install / runtime hygiene (issues #126, #128)
 

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.22
+version: 3.3.2-rc.2
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -43,10 +43,10 @@ If `totalreclaw_*` tools are already bound to your toolset, SKIP install and jum
 
 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.
 
-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:
+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.*
 
-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."*
+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."*
 
 ## Rendering the QR on your transport (rc.5+)
 
@@ -54,13 +54,13 @@ When you receive the `totalreclaw_pair` payload, render the QR based on your cha
 
 - **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.
+- **Web chat with inline-image support**: embed as `<img src="data:image/png;base64,<qr_png_b64>" alt="TotalReclaw account-setup QR">` if the chat client renders HTML; otherwise fall back to attachment.
 
-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.
+The QR encodes ONLY the account-setup URL. The 6-digit PIN is a separate out-of-band confirmation — deliberately NOT baked into the QR (dual-channel design: scan + type). Never log, print, or re-emit the PIN outside the user-facing reply. The PIN must NOT end up in any other tool call, log file, or memory store.
 
 ## 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.
+NEVER echo / generate / ask the user to paste a recovery phrase in chat. NEVER invoke `openclaw totalreclaw onboard` (bare interactive form), `totalreclaw setup`, or any phrase-touching CLI via your shell tool (stdout enters LLM context). The ONLY agent-facilitated account-setup paths are (in order of preference): (1) the `totalreclaw_pair` account-setup 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 account-setup flow, `pair_url` key naming). Both have zero phrase material on stdout (account-setup crypto is x25519-only, not BIP-39). If the user pastes a phrase anyway: tell them it is compromised, call `totalreclaw_pair` with `mode=generate` for a fresh wallet.
 
 ## Usage (post-setup)
 
@@ -74,10 +74,10 @@ NEVER echo / generate / ask the user to paste a recovery phrase in chat. NEVER i
 
 - `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.
+- `onboarding required` → credentials missing; redo from the account-setup 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
 
-`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).
+`totalreclaw_pair` (ONLY account-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/dist/fs-helpers.js

@@ -420,6 +420,107 @@ export function wipePartialInstall(pluginRootDir) {
         return false;
     }
 }
+// ---------------------------------------------------------------------------
+// Plugin load manifest (.loaded.json / .error.json) — 3.3.2-rc.1 #186
+// ---------------------------------------------------------------------------
+/**
+ * Filenames written into the plugin root dir at the end of register() and
+ * (on failure) from the surrounding try/catch. The presence of `.loaded.json`
+ * is the canonical filesystem signal that the plugin's register() body ran
+ * to completion AND the SDK tool/route/hook registries received calls.
+ *
+ * Acceptance criteria (issue #186):
+ *   - `cat ~/.openclaw/extensions/totalreclaw/.loaded.json` shows
+ *     `{loadedAt, tools, version}` after every successful gateway start.
+ *   - `cat ~/.openclaw/extensions/totalreclaw/.error.json` shows
+ *     `{loadedAt, error, stack}` if register() threw.
+ *   - Both are overwritten on each register() call so the agent can rely
+ *     on the timestamp matching the most recent gateway start.
+ *
+ * Why these MUST be synchronous writes (same constraint as
+ * `registerHttpRoute` per the comment in index.ts around the route
+ * registration site): the SDK loader treats register() returning as the
+ * signal to freeze the registries. An async `fs.promises.writeFile` would
+ * settle one microtask AFTER the loader has moved on, so the manifest
+ * could miss tools that registered late OR drop entirely if the gateway
+ * exits before the microtask runs. `writeFileSync` is the only safe choice.
+ */
+export const PLUGIN_LOADED_MANIFEST = '.loaded.json';
+export const PLUGIN_ERROR_MANIFEST = '.error.json';
+/**
+ * Resolve the plugin root dir from the loaded module's directory. The plugin
+ * is shipped with `dist/index.js` as the entry, so `import.meta.url` resolves
+ * to `<root>/dist/`. We walk up one level to put the manifests next to
+ * `package.json`. Defensive: if the caller already passed the root (no
+ * trailing `dist`), we still return a sensible path.
+ */
+function resolvePluginRootForManifest(pluginDir) {
+    const base = path.basename(pluginDir);
+    return base === 'dist' ? path.resolve(pluginDir, '..') : pluginDir;
+}
+/**
+ * Write the success manifest. SYNCHRONOUS — the SDK freezes the plugin
+ * registries the moment register() returns; `fs.promises.writeFile` would
+ * race that freeze and the manifest could miss late tool registrations or
+ * never land at all if the process exits before the microtask runs.
+ *
+ * Best-effort: returns `true` on success, `false` on any I/O error. Never
+ * throws — failing to write the manifest is a diagnostic loss, not a
+ * correctness loss, so we don't propagate.
+ *
+ * The manifest is written at mode 0644 (world-readable). It contains no
+ * secrets — only a timestamp, the (publicly known) tool names, and the
+ * plugin version. Cleared first so a stale `.error.json` from a previous
+ * failed boot doesn't survive a successful boot.
+ */
+export function writePluginManifest(pluginDir, manifest) {
+    try {
+        const root = resolvePluginRootForManifest(pluginDir);
+        if (!fs.existsSync(root))
+            return false;
+        const loadedPath = path.join(root, PLUGIN_LOADED_MANIFEST);
+        const errorPath = path.join(root, PLUGIN_ERROR_MANIFEST);
+        // Best-effort error-file cleanup — a successful boot supersedes any
+        // prior failure marker. If the unlink fails (e.g. permission), the
+        // .loaded.json timestamp still tells the agent which is current.
+        try {
+            if (fs.existsSync(errorPath))
+                fs.unlinkSync(errorPath);
+        }
+        catch {
+            // Swallow — best-effort.
+        }
+        fs.writeFileSync(loadedPath, JSON.stringify(manifest, null, 2));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Write the error manifest. SYNCHRONOUS for the same reason as
+ * `writePluginManifest`. Called from the try/catch surrounding the
+ * register() body so the agent has a filesystem signal that the plugin
+ * registered AT LEAST attempted to load and failed in a specific way.
+ *
+ * Does NOT clear `.loaded.json` from a prior successful boot — keeping
+ * the older success marker around lets the agent see "last good boot was
+ * X, current boot failed at Y" without spelunking logs. The newer
+ * `.error.json` timestamp wins as "current state".
+ */
+export function writePluginError(pluginDir, error) {
+    try {
+        const root = resolvePluginRootForManifest(pluginDir);
+        if (!fs.existsSync(root))
+            return false;
+        const errorPath = path.join(root, PLUGIN_ERROR_MANIFEST);
+        fs.writeFileSync(errorPath, JSON.stringify(error, null, 2));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Drop the `.tr-partial-install` marker into `pluginRootDir`. Idempotent
  * (overwrites any existing marker) and best-effort — returns `true` on