@totalreclaw/totalreclaw 3.3.1 → 3.3.2-rc.2

package/fs-helpers.ts

@@ -495,6 +495,130 @@ export function wipePartialInstall(pluginRootDir: string): boolean {
   }
 }
 
+// ---------------------------------------------------------------------------
+// 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';
+
+/** Schema written to `.loaded.json` — see PLUGIN_LOADED_MANIFEST. */
+export interface PluginLoadManifest {
+  /** Unix epoch milliseconds when register() finished. */
+  loadedAt: number;
+  /** Tool names passed to api.registerTool() during register(). */
+  tools: string[];
+  /** Plugin version string from package.json (or "unknown"). */
+  version: string;
+}
+
+/** Schema written to `.error.json` when register() throws. */
+export interface PluginLoadError {
+  loadedAt: number;
+  error: string;
+  stack?: string;
+  version?: string;
+}
+
+/**
+ * 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: string): string {
+  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: string,
+  manifest: PluginLoadManifest,
+): boolean {
+  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: string,
+  error: PluginLoadError,
+): boolean {
+  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

package/index.ts

@@ -164,6 +164,8 @@ import {
   cleanupInstallStagingDirs,
   detectPartialInstall,
   clearPartialInstallMarker,
+  writePluginManifest,
+  writePluginError,
   type OnboardingState,
 } from './fs-helpers.js';
 import { isRcBuild } from './qa-bug-report.js';
@@ -2856,6 +2858,50 @@ const plugin = {
   },
 
   register(api: OpenClawPluginApi) {
+    // ---------------------------------------------------------------
+    // 3.3.2-rc.1 (issue #186) — load manifest instrumentation
+    // ---------------------------------------------------------------
+    //
+    // Capture every `api.registerTool({name, ...})` call so we can write
+    // a `.loaded.json` manifest at the end of register(). Wrap the body
+    // in try/catch so a register-time throw produces `.error.json` for
+    // agent-side filesystem verification (the CLI hangs in some Docker
+    // setups — issue #182 — so the manifest is the canonical "did the
+    // plugin load?" probe).
+    //
+    // Implementation: we intercept the api.registerTool method by
+    // wrapping it on the api object passed in. The wrapper inspects the
+    // `name` field (every TR registerTool call sets it) and forwards
+    // verbatim. NO behavior change to the SDK call — the original method
+    // is invoked with original args and `this` binding.
+    //
+    // Synchronous writes ONLY (see writePluginManifest doc): the SDK
+    // freezes plugin registries the moment register() returns; an async
+    // write would race that freeze.
+    const _registeredToolNames: string[] = [];
+    const _originalRegisterTool = api.registerTool.bind(api);
+    api.registerTool = (tool: unknown, opts?: { name?: string; names?: string[] }) => {
+      try {
+        const t = tool as { name?: unknown } | null | undefined;
+        if (t && typeof t === 'object' && typeof t.name === 'string' && t.name.length > 0) {
+          _registeredToolNames.push(t.name);
+        }
+      } catch {
+        // Manifest is diagnostic; never let bookkeeping break tool registration.
+      }
+      _originalRegisterTool(tool, opts);
+    };
+
+    // Lazily resolved inside the try below — needed by both the manifest
+    // write and the error path. `dist/` after build, package root in tests.
+    let _pluginDirForManifest: string | null = null;
+
+    // NOTE: the body of register() below is intentionally NOT re-indented
+    // under this `try` block — re-indenting would touch every line in a
+    // 3,500-line function and obscure the actual hotfix diff. The closing
+    // `} catch (registerErr: unknown) { ... }` is at the very end of
+    // register() (search for "register() threw").
+    try {
     // ---------------------------------------------------------------
     // RC-build detection (3.3.1-rc.3)
     // ---------------------------------------------------------------
@@ -2880,6 +2926,7 @@ const plugin = {
       // `require('node:url')` — undefined under bare-ESM Node, broke the
       // before_agent_start hook in the published rc.20 bundle (issue #124).
       const pluginDir = nodePath.dirname(fileURLToPath(import.meta.url));
+      _pluginDirForManifest = pluginDir; // captured for #186 .loaded.json/.error.json
       pluginVersion = readPluginVersion(pluginDir);
       rcMode = isRcBuild(pluginVersion);
       if (rcMode) {
@@ -5162,19 +5209,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: {
@@ -6291,6 +6343,60 @@ const plugin = {
       },
       { priority: 5 },
     );
+
+    // ---------------------------------------------------------------
+    // 3.3.2-rc.1 (issue #186) — write `.loaded.json` manifest
+    // ---------------------------------------------------------------
+    //
+    // Final step of register(): drop the success manifest so the agent
+    // can `cat ~/.openclaw/extensions/totalreclaw/.loaded.json` to
+    // verify which tools bound. Synchronous (see writePluginManifest doc).
+    // Never throws — diagnostic loss only on I/O failure.
+    if (_pluginDirForManifest) {
+      try {
+        const ok = writePluginManifest(_pluginDirForManifest, {
+          loadedAt: Date.now(),
+          tools: _registeredToolNames.slice(),
+          version: pluginVersion ?? 'unknown',
+        });
+        if (ok) {
+          api.logger.info(
+            `TotalReclaw: wrote .loaded.json manifest (${_registeredToolNames.length} tools, version=${pluginVersion ?? 'unknown'})`,
+          );
+        }
+      } catch {
+        // Best-effort; helper swallows internally too.
+      }
+    }
+    } catch (registerErr: unknown) {
+      // ---------------------------------------------------------------
+      // 3.3.2-rc.1 (issue #186) — write `.error.json` on register() throw
+      // ---------------------------------------------------------------
+      //
+      // Some surface threw out of register(). Drop a structured error
+      // marker the agent can grep. Best-effort logging then re-throw so
+      // the SDK sees the original failure.
+      const errMsg = registerErr instanceof Error ? registerErr.message : String(registerErr);
+      const errStack = registerErr instanceof Error ? registerErr.stack : undefined;
+      try {
+        api.logger.error(`TotalReclaw: register() threw: ${errMsg}`);
+      } catch {
+        // Logger may be unavailable (very early failure path).
+      }
+      if (_pluginDirForManifest) {
+        try {
+          writePluginError(_pluginDirForManifest, {
+            loadedAt: Date.now(),
+            error: errMsg,
+            stack: errStack,
+            version: 'unknown',
+          });
+        } catch {
+          // Best-effort.
+        }
+      }
+      throw registerErr;
+    }
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.1",
+  "version": "3.3.2-rc.2",
   "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": [
@@ -58,24 +58,31 @@
     "README.md",
     "CHANGELOG.md",
     "CLAWHUB.md",
-    "skill.json"
+    "skill.json",
+    "postinstall.mjs"
   ],
   "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 load-manifest.test.ts && npx tsx postinstall-validation.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{}\"",
-    "postinstall": "node -e \"try{require('fs').unlinkSync('.tr-partial-install');}catch{}\"",
+    "postinstall": "node ./postinstall.mjs",
     "prepack": "npm run build",
     "prepublishOnly": "node ../scripts/check-scanner.mjs && node ../scripts/check-version-drift.mjs"
   },
   "openclaw": {
     "extensions": [
       "./dist/index.js"
-    ]
+    ],
+    "compat": {
+      "pluginApi": ">=2026.3.22"
+    },
+    "build": {
+      "openclawVersion": "2026.4.24"
+    }
   }
 }

package/postinstall.mjs

@@ -0,0 +1,260 @@
+// scanner-sim: allow — postinstall scripts run during `npm install`, NOT inside the OpenClaw runtime sandbox. Per check-scanner.mjs guidance ("Moving the subprocess call into a separate post-install helper that OpenClaw sandboxes (NOT covered by this scanner)"), this file is the intended home for child_process usage. The plugin's runtime code (index.ts, etc.) stays scanner-clean; this file only runs once at install-time.
+/**
+ * postinstall.mjs — TotalReclaw plugin post-install lifecycle script.
+ *
+ * Runs after `npm install` finishes inside the plugin extension dir
+ * (`~/.openclaw/extensions/totalreclaw/`). Three jobs, in order:
+ *
+ *   1. Clean the partial-install marker (`.tr-partial-install`) that
+ *      `preinstall` dropped. Mirrors the inline shim that shipped in
+ *      pre-3.3.2 releases.
+ *   2. (3.3.2-rc.1 / issue #188) Smoke-check critical deps. After `npm
+ *      install` claims success we require() the modules whose absence
+ *      bricked rc.22 first-attempt installs (`@scure/bip39`,
+ *      `@scure/bip39/wordlists/english.js`, `@totalreclaw/core`,
+ *      `@totalreclaw/client`, `qrcode`, `ws`). If any throws, the
+ *      post-install fails LOUDLY — better than the rc.21 silent
+ *      half-install where `enabled: true` shipped with a missing dep.
+ *   3. (3.3.2-rc.1 / issue #190) Sweep `<extensions>/.openclaw-install-stage-*`
+ *      siblings. The runtime register() helper handles this on plugin
+ *      load too, but doing it here means a re-install starts from a
+ *      clean parent dir — no "duplicate plugin id detected; global
+ *      plugin will be overridden by global plugin" warning during the
+ *      install itself.
+ *
+ * Constraints:
+ *   - Must be idempotent: re-running on a clean tree is a no-op.
+ *   - Must not import any production module that itself runs `register()`
+ *     or makes outbound calls. We use only Node stdlib + dynamic require()
+ *     of the smoke-check deps.
+ *   - Must run in CommonJS-compatible Node ESM (the plugin's package.json
+ *     declares `"type": "module"`, so this file uses `.mjs` and
+ *     `createRequire` to call require() against the plugin's node_modules).
+ *
+ * Phrase-safety note: this file does NOT touch credentials.json, mnemonics,
+ * keys, or any phrase code path. It only validates module loading and
+ * cleans staging directories.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { execSync } from 'node:child_process';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+
+const PARTIAL_INSTALL_MARKER = '.tr-partial-install';
+
+// Order matters: light, fast modules first so a failure surfaces quickly.
+// `@scure/bip39/wordlists/english.js` is the EXACT path that bricked rc.21
+// (issue #188 — `Cannot find module '@scure/bip39/wordlists/english.js'`).
+const CRITICAL_DEPS = [
+  '@scure/bip39',
+  '@scure/bip39/wordlists/english.js',
+  '@totalreclaw/core',
+  '@totalreclaw/client',
+  'qrcode',
+  'ws',
+];
+
+function log(msg) {
+  process.stdout.write(`[totalreclaw postinstall] ${msg}\n`);
+}
+
+function warn(msg) {
+  process.stderr.write(`[totalreclaw postinstall] WARN: ${msg}\n`);
+}
+
+// ---------------------------------------------------------------------------
+// Step 1 — clear .tr-partial-install marker
+// ---------------------------------------------------------------------------
+
+function clearPartialInstallMarker() {
+  try {
+    const markerPath = path.join(here, PARTIAL_INSTALL_MARKER);
+    if (fs.existsSync(markerPath)) {
+      fs.unlinkSync(markerPath);
+      log('cleared .tr-partial-install marker');
+    }
+  } catch (err) {
+    // Best-effort. The runtime register() also clears this defensively.
+    warn(`could not clear .tr-partial-install marker: ${err.message}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Step 2 — atomic critical-dep validation (issue #188)
+// ---------------------------------------------------------------------------
+
+/**
+ * Try to require() each critical dep. Returns the list of names that
+ * failed; an empty array means everything resolved.
+ */
+function smokeCheckDeps() {
+  const missing = [];
+  for (const dep of CRITICAL_DEPS) {
+    try {
+      require(dep);
+    } catch (err) {
+      missing.push({ dep, message: err.message });
+    }
+  }
+  return missing;
+}
+
+/**
+ * Recovery path: if smoke-check fails, blow away the local node_modules
+ * tree the parent install populated and re-run `npm install --no-audit
+ * --no-fund --no-save --offline=false` once. This is meant to recover
+ * from race-condition partial-fetches (issue #188), NOT from a missing
+ * dep in package.json.
+ *
+ * If the second attempt also fails, exit non-zero so `openclaw plugins
+ * install` surfaces the failure to the agent rather than writing
+ * `enabled: true` over a broken install.
+ *
+ * Skipped if `TOTALRECLAW_SKIP_POSTINSTALL_RETRY=1` (CI / sandboxes that
+ * cannot reach the registry from inside the postinstall hook).
+ */
+function retryNpmInstall() {
+  if (process.env.TOTALRECLAW_SKIP_POSTINSTALL_RETRY === '1') {
+    warn('TOTALRECLAW_SKIP_POSTINSTALL_RETRY=1 — skipping retry');
+    return false;
+  }
+  try {
+    log('first-attempt smoke check failed — clearing node_modules and retrying npm install once...');
+    const nm = path.join(here, 'node_modules');
+    if (fs.existsSync(nm)) {
+      fs.rmSync(nm, { recursive: true, force: true });
+    }
+    // Note: we deliberately re-invoke npm install here. The `--ignore-scripts`
+    // flag is critical — without it we'd re-trigger this same postinstall
+    // and recurse forever.
+    execSync('npm install --no-audit --no-fund --ignore-scripts', {
+      cwd: here,
+      stdio: 'inherit',
+    });
+    log('retry npm install completed; re-validating deps');
+    return true;
+  } catch (err) {
+    warn(`retry npm install failed: ${err.message}`);
+    return false;
+  }
+}
+
+function validateDepsOrFail() {
+  const firstMiss = smokeCheckDeps();
+  if (firstMiss.length === 0) {
+    log(`smoke check OK (${CRITICAL_DEPS.length} critical deps resolved)`);
+    return;
+  }
+
+  warn(`smoke check failed on first attempt:`);
+  for (const m of firstMiss) {
+    warn(`  - ${m.dep}: ${m.message}`);
+  }
+
+  const retried = retryNpmInstall();
+  if (!retried) {
+    process.exitCode = 1;
+    throw new Error(
+      `TotalReclaw postinstall: critical deps missing after npm install — ` +
+        `[${firstMiss.map((m) => m.dep).join(', ')}]. ` +
+        `Re-run \`openclaw plugins install @totalreclaw/totalreclaw\` to retry, ` +
+        `or set TOTALRECLAW_SKIP_POSTINSTALL_RETRY=1 to bypass and surface the ` +
+        `original error.`,
+    );
+  }
+
+  const secondMiss = smokeCheckDeps();
+  if (secondMiss.length === 0) {
+    log(`smoke check OK after retry (${CRITICAL_DEPS.length} deps resolved)`);
+    return;
+  }
+
+  process.exitCode = 1;
+  throw new Error(
+    `TotalReclaw postinstall: deps still missing after retry — ` +
+      `[${secondMiss.map((m) => m.dep).join(', ')}]. ` +
+      `This is likely a permanent breakage (registry outage, package rename, ` +
+      `or corrupted node_modules). The plugin will not load. Original errors:\n` +
+      secondMiss.map((m) => `  - ${m.dep}: ${m.message}`).join('\n'),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Step 3 — sweep `.openclaw-install-stage-*` siblings (issue #190)
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the OpenClaw extensions dir from the plugin's own location.
+ * The plugin lives at `<extensions>/totalreclaw/` so the parent is the
+ * extensions root. Returns null if the layout is not what we expect
+ * (npm tarball linked outside an `<extensions>/` parent — e.g. dev
+ * checkout) so we never delete random siblings.
+ */
+function resolveExtensionsDir() {
+  // `here` is the plugin root (this file is at the package root, NOT in dist/).
+  // The parent should be the OpenClaw extensions directory.
+  const parent = path.resolve(here, '..');
+  // Heuristic check: only sweep if we look like we're inside an OpenClaw
+  // install dir. We accept (a) the well-known `extensions` dirname, OR
+  // (b) the presence of any sibling `.openclaw-install-stage-*` (which is
+  // proof we're inside an extensions dir).
+  if (path.basename(parent) === 'extensions') return parent;
+  try {
+    const entries = fs.readdirSync(parent);
+    if (entries.some((n) => n.startsWith('.openclaw-install-stage-'))) {
+      return parent;
+    }
+  } catch {
+    // Parent unreadable — bail safely.
+  }
+  return null;
+}
+
+function sweepStagingSiblings() {
+  const extensionsDir = resolveExtensionsDir();
+  if (!extensionsDir) {
+    log('no extensions parent detected (dev checkout?) — skipping staging sweep');
+    return;
+  }
+  let removed = 0;
+  let entries;
+  try {
+    entries = fs.readdirSync(extensionsDir);
+  } catch (err) {
+    warn(`could not list ${extensionsDir}: ${err.message}`);
+    return;
+  }
+  for (const name of entries) {
+    if (!name.startsWith('.openclaw-install-stage-')) continue;
+    const target = path.join(extensionsDir, name);
+    try {
+      const st = fs.lstatSync(target);
+      if (!st.isDirectory()) continue;
+      fs.rmSync(target, { recursive: true, force: true });
+      removed++;
+      log(`removed stale staging dir: ${name}`);
+    } catch (err) {
+      warn(`could not remove ${name}: ${err.message}`);
+    }
+  }
+  if (removed === 0) {
+    log('no stale staging dirs to sweep');
+  } else {
+    log(`swept ${removed} stale staging dir(s)`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+clearPartialInstallMarker();
+sweepStagingSiblings();
+validateDepsOrFail();
+
+log('postinstall complete');

package/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "totalreclaw",
-  "version": "3.3.1-rc.22",
+  "version": "3.3.2-rc.2",
   "description": "End-to-end encrypted memory for AI agents — portable, yours forever. XChaCha20-Poly1305 E2EE: server never sees plaintext.",
   "author": "TotalReclaw Team",
   "license": "MIT",
@@ -175,6 +175,19 @@
             "description": "Preview consolidation without deleting"
           }
         }
+      },
+      {
+        "name": "totalreclaw_pair",
+        "description": "Set up the user's TotalReclaw account (encrypted, browser-side recovery-phrase generation or import). Returns an account-setup URL, a 6-digit PIN, and an ASCII QR code that the agent relays to the user. The recovery phrase 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. This is the canonical agent-facilitated account-setup surface. Tool name kept for backward compatibility — function-wise this is the account-setup tool.",
+        "parameters": {
+          "mode": {
+            "type": "string",
+            "required": false,
+            "enum": ["generate", "import"],
+            "default": "generate",
+            "description": "\"generate\" = browser will create a NEW recovery phrase. \"import\" = browser will accept an EXISTING phrase pasted by the user in their browser (never through chat)."
+          }
+        }
       }
     ],
     "config": {