@totalreclaw/totalreclaw 3.3.1 → 3.3.2-rc.1

package/CHANGELOG.md

@@ -6,6 +6,31 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+### 3.3.2-rc.1 — preinstall orphan-stage cleanup (umbrella #182 F6 / issue #190)
+
+The rc.21 fix (#126) added `cleanupInstallStagingDirs` called at plugin
+register time. That helper is too late for the re-install scenario: with
+an orphan `.openclaw-install-stage-*` sibling already present in
+`~/.openclaw/extensions/`, OpenClaw's config validator fires
+`duplicate plugin id detected; global plugin will be overridden by global
+plugin` BEFORE plugin register runs, so registration is blocked entirely
+and the helper never gets a chance to clean up. The user observes the
+warning and a plugin that silently fails to load.
+
+Fix: a new `preinstall.mjs` script runs at npm preinstall time (before
+the new install is renamed into place). It removes orphan
+`.openclaw-install-stage-*` siblings from `~/.openclaw/extensions/`
+(and `$OPENCLAW_STATE_DIR/extensions/` when set), skipping the script's
+own cwd basename so older OpenClaw versions that stage inside extensions/
+don't delete their own in-flight install. Also keeps the existing
+`.tr-partial-install` marker drop. Best-effort throughout — never throws
+or exits non-zero.
+
+Regression: `test_issue_190_preinstall_orphan_cleanup.test.ts`
+(19 assertions) covers newer-OpenClaw flow (cwd in /tmp), older-OpenClaw
+flow (cwd inside extensions/), `OPENCLAW_STATE_DIR` env override,
+no-extensions-dir fallback, and unrelated-sibling preservation.
+
 ### Install / runtime hygiene (issues #126, #128)
 
 Two narrow fixes from the rc.20 user-QA findings — both around install /

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.1
 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/index.js

@@ -4377,18 +4377,23 @@ const plugin = {
         // ---------------------------------------------------------------
         api.registerTool({
             name: 'totalreclaw_pair',
-            label: 'QR pair — start remote pairing session',
-            description: 'Start a remote pairing session so the user can create or import a TotalReclaw ' +
-                'recovery phrase from their phone or another browser. Returns a pairing URL, a ' +
-                '6-digit PIN, and an ASCII QR code that the agent relays to the user. The recovery ' +
-                'phrase itself is generated/entered in the BROWSER and uploaded end-to-end encrypted ' +
-                'to this gateway — it NEVER touches the LLM provider or the chat transcript.\n\n' +
-                'This is the CANONICAL agent-facilitated setup surface — use it whenever the user ' +
-                'asks you to set up TotalReclaw, regardless of whether they have terminal access. ' +
-                'Browser-side crypto keeps the recovery phrase out of the LLM context entirely. ' +
-                'If a user explicitly prefers local-terminal setup with no browser, point them at ' +
-                '`totalreclaw_onboarding_start` (a pointer to the CLI wizard they run on their own ' +
-                'terminal, NOT through your shell tool).',
+            label: 'Set up the user\'s TotalReclaw account (encrypted, browser-side)',
+            description: 'Set up the user\'s TotalReclaw account (encrypted, browser-side recovery-phrase ' +
+                'generation or import). Starts a brief remote session so the user can create or ' +
+                'import a TotalReclaw recovery phrase from their phone or another browser. ' +
+                'Returns an account-setup URL, a 6-digit PIN, and an ASCII QR code that the agent ' +
+                'relays to the user. The recovery phrase itself is generated/entered in the ' +
+                'BROWSER and uploaded end-to-end encrypted to this gateway — it NEVER touches ' +
+                'the LLM provider or the chat transcript.\n\n' +
+                'This is the CANONICAL agent-facilitated account-setup surface — use it whenever ' +
+                'the user asks you to set up TotalReclaw, regardless of whether they have ' +
+                'terminal access. Narrate it to the user as "setting up your TotalReclaw ' +
+                'account". Browser-side crypto keeps the recovery phrase out of the LLM context ' +
+                'entirely. If a user explicitly prefers local-terminal account setup with no ' +
+                'browser, point them at `totalreclaw_onboarding_start` (a pointer to the CLI ' +
+                'wizard they run on their own terminal, NOT through your shell tool).\n\n' +
+                'Tool name `totalreclaw_pair` is kept for backward compatibility — function-wise ' +
+                'this is the account-setup tool.',
             parameters: {
                 type: 'object',
                 properties: {

package/index.ts

@@ -5162,19 +5162,24 @@ const plugin = {
     api.registerTool(
       {
         name: 'totalreclaw_pair',
-        label: 'QR pair — start remote pairing session',
+        label: 'Set up the user\'s TotalReclaw account (encrypted, browser-side)',
         description:
-          'Start a remote pairing session so the user can create or import a TotalReclaw ' +
-          'recovery phrase from their phone or another browser. Returns a pairing URL, a ' +
-          '6-digit PIN, and an ASCII QR code that the agent relays to the user. The recovery ' +
-          'phrase itself is generated/entered in the BROWSER and uploaded end-to-end encrypted ' +
-          'to this gateway — it NEVER touches the LLM provider or the chat transcript.\n\n' +
-          'This is the CANONICAL agent-facilitated setup surface — use it whenever the user ' +
-          'asks you to set up TotalReclaw, regardless of whether they have terminal access. ' +
-          'Browser-side crypto keeps the recovery phrase out of the LLM context entirely. ' +
-          'If a user explicitly prefers local-terminal setup with no browser, point them at ' +
-          '`totalreclaw_onboarding_start` (a pointer to the CLI wizard they run on their own ' +
-          'terminal, NOT through your shell tool).',
+          'Set up the user\'s TotalReclaw account (encrypted, browser-side recovery-phrase ' +
+          'generation or import). Starts a brief remote session so the user can create or ' +
+          'import a TotalReclaw recovery phrase from their phone or another browser. ' +
+          'Returns an account-setup URL, a 6-digit PIN, and an ASCII QR code that the agent ' +
+          'relays to the user. The recovery phrase itself is generated/entered in the ' +
+          'BROWSER and uploaded end-to-end encrypted to this gateway — it NEVER touches ' +
+          'the LLM provider or the chat transcript.\n\n' +
+          'This is the CANONICAL agent-facilitated account-setup surface — use it whenever ' +
+          'the user asks you to set up TotalReclaw, regardless of whether they have ' +
+          'terminal access. Narrate it to the user as "setting up your TotalReclaw ' +
+          'account". Browser-side crypto keeps the recovery phrase out of the LLM context ' +
+          'entirely. If a user explicitly prefers local-terminal account setup with no ' +
+          'browser, point them at `totalreclaw_onboarding_start` (a pointer to the CLI ' +
+          'wizard they run on their own terminal, NOT through your shell tool).\n\n' +
+          'Tool name `totalreclaw_pair` is kept for backward compatibility — function-wise ' +
+          'this is the account-setup tool.',
         parameters: {
           type: 'object',
           properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.1",
+  "version": "3.3.2-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": [
@@ -54,6 +54,7 @@
     "!**/*.test.ts",
     "!pocv2-e2e-test.ts",
     "openclaw.plugin.json",
+    "preinstall.mjs",
     "SKILL.md",
     "README.md",
     "CHANGELOG.md",
@@ -63,12 +64,12 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json --noCheck",
     "verify-tarball": "node ../scripts/verify-tarball.mjs",
-    "test": "npx tsx manifest-shape.test.ts && npx tsx config-schema.test.ts && npx tsx config.test.ts && npx tsx relay-headers.test.ts && npx tsx scope-address-visible.test.ts && npx tsx llm-profile-reader.test.ts && npx tsx llm-client.test.ts && npx tsx llm-client-retry.test.ts && npx tsx gateway-url.test.ts && npx tsx retype-setscope.test.ts && npx tsx tool-gating.test.ts && npx tsx onboarding-noninteractive.test.ts && npx tsx pair-cli-json.test.ts && npx tsx pair-qr.test.ts && npx tsx pair-remote-client.test.ts && npx tsx qa-bug-report.test.ts && npx tsx nonce-serialization.test.ts && npx tsx phrase-safety-registry.test.ts && npx tsx test_issue_92_onnx_download_ux.test.ts && npx tsx onboard-pair-only.test.ts && npx tsx import-time-smoke.test.ts && npx tsx install-staging-cleanup.test.ts && npx tsx partial-install-detection.test.ts && npx tsx install-reload-idempotency.test.ts && npx tsx json-stdout-cleanliness.test.ts",
+    "test": "npx tsx manifest-shape.test.ts && npx tsx config-schema.test.ts && npx tsx config.test.ts && npx tsx relay-headers.test.ts && npx tsx scope-address-visible.test.ts && npx tsx llm-profile-reader.test.ts && npx tsx llm-client.test.ts && npx tsx llm-client-retry.test.ts && npx tsx gateway-url.test.ts && npx tsx retype-setscope.test.ts && npx tsx tool-gating.test.ts && npx tsx onboarding-noninteractive.test.ts && npx tsx pair-cli-json.test.ts && npx tsx pair-qr.test.ts && npx tsx pair-remote-client.test.ts && npx tsx qa-bug-report.test.ts && npx tsx nonce-serialization.test.ts && npx tsx phrase-safety-registry.test.ts && npx tsx test_issue_92_onnx_download_ux.test.ts && npx tsx onboard-pair-only.test.ts && npx tsx import-time-smoke.test.ts && npx tsx install-staging-cleanup.test.ts && npx tsx partial-install-detection.test.ts && npx tsx install-reload-idempotency.test.ts && npx tsx json-stdout-cleanliness.test.ts && npx tsx test_issue_190_preinstall_orphan_cleanup.test.ts",
     "smoke:dist": "npx tsx dist-esm-smoke.test.ts",
     "check-scanner": "node ../scripts/check-scanner.mjs",
     "check-version-drift": "node ../scripts/check-version-drift.mjs",
     "sync-version": "node ../scripts/sync-version.mjs",
-    "preinstall": "node -e \"try{require('fs').writeFileSync('.tr-partial-install','');}catch{}\"",
+    "preinstall": "node ./preinstall.mjs",
     "postinstall": "node -e \"try{require('fs').unlinkSync('.tr-partial-install');}catch{}\"",
     "prepack": "npm run build",
     "prepublishOnly": "node ../scripts/check-scanner.mjs && node ../scripts/check-version-drift.mjs"

package/preinstall.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+// Runs at npm preinstall during `openclaw plugins install @totalreclaw/totalreclaw`.
+//
+// Two responsibilities:
+//   1. Drop the `.tr-partial-install` marker. detectPartialInstall (rc.22)
+//      uses it to identify installs that didn't reach postinstall.
+//   2. Remove orphan `.openclaw-install-stage-*` siblings from
+//      `~/.openclaw/extensions/` (and `$OPENCLAW_STATE_DIR/extensions/` when set).
+//      An interrupted prior install leaves a stage dir behind; on next gateway
+//      start, OpenClaw's config validator finds two manifests with the same
+//      plugin id, fires `duplicate plugin id detected; global plugin will be
+//      overridden by global plugin`, and refuses to register either copy.
+//      The register-time `cleanupInstallStagingDirs` helper from rc.21 (#126)
+//      cannot recover this: registration is blocked before our code runs.
+//
+// Best-effort throughout. Never throws or exits non-zero.
+//
+// Background: issue #190 (umbrella #182 finding F6).
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const STAGE_PREFIX = '.openclaw-install-stage-';
+
+try {
+  fs.writeFileSync('.tr-partial-install', '');
+} catch { /* swallow */ }
+
+function cleanExtensionsDir(extensionsDir, selfName) {
+  const removed = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(extensionsDir);
+  } catch { return removed; }
+  for (const name of entries) {
+    if (!name.startsWith(STAGE_PREFIX)) continue;
+    if (name === selfName) continue;
+    const target = path.join(extensionsDir, name);
+    try {
+      if (!fs.lstatSync(target).isDirectory()) continue;
+      fs.rmSync(target, { recursive: true, force: true });
+      removed.push(target);
+    } catch { /* skip racy / unreadable */ }
+  }
+  return removed;
+}
+
+const cwd = process.cwd();
+const cwdName = path.basename(cwd);
+
+const candidates = new Set();
+if (cwdName.startsWith(STAGE_PREFIX)) {
+  candidates.add(path.dirname(cwd));
+}
+candidates.add(path.join(os.homedir(), '.openclaw', 'extensions'));
+if (process.env.OPENCLAW_STATE_DIR) {
+  candidates.add(path.join(process.env.OPENCLAW_STATE_DIR, 'extensions'));
+}
+
+for (const dir of candidates) {
+  for (const removedPath of cleanExtensionsDir(dir, cwdName)) {
+    process.stdout.write(`[totalreclaw preinstall] removed orphan install-stage dir: ${removedPath}\n`);
+  }
+}

package/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "totalreclaw",
-  "version": "3.3.1-rc.22",
+  "version": "3.3.2-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",