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

package/CHANGELOG.md

@@ -4,6 +4,53 @@ 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]
+
+### Install / runtime hygiene (issues #126, #128)
+
+Two narrow fixes from the rc.20 user-QA findings — both around install /
+boot-time output cleanliness, no behavior change to the steady-state plugin.
+
+- **#126 — clean up `.openclaw-install-stage-*` siblings.** When
+  `openclaw plugins install @totalreclaw/totalreclaw` is interrupted mid-
+  extract (e.g. by an auto-gateway-restart triggered by the same install),
+  the npm staging directory `<extensionsDir>/.openclaw-install-stage-XXXXXX/`
+  survives. On the next gateway start, OpenClaw's plugin loader auto-
+  discovers BOTH `.../totalreclaw/` AND the orphan staging dir, registers
+  duplicate plugins, fires hooks twice, and prints a "duplicate-plugin-id"
+  warning every cycle. A user running `openclaw plugins list` sees two
+  `totalreclaw` rows.
+
+  Fix: `cleanupInstallStagingDirs(pluginDir)` runs at plugin register time
+  (one tick after the loader resolves our entrypoint). It scans the
+  extensions directory for `.openclaw-install-stage-*` siblings and
+  recursively removes each one. Best-effort — never crashes plugin init
+  on permission / race failures.
+
+  Regression: `install-staging-cleanup.test.ts` (16 assertions) covers
+  fresh install, idempotent re-run, package-root vs `dist/` invocation,
+  unrelated-dotfile preservation (`.git`, `.openclaw-cache`), and stray-
+  file (non-directory) skipping.
+
+- **#128 — registerTool breadcrumbs no longer bleed into `--json` stdout.**
+  The rc.20 breadcrumb logs (`registerTool(totalreclaw_pair) returned. ...`
+  and the RC-only `totalreclaw_report_qa_bug registered ...`) were emitted
+  via `api.logger.info`, which OpenClaw routes to stdout decorated with
+  `[plugins] `. When a user invoked `openclaw agent --message "..." --json`
+  for programmatic parsing, the breadcrumb appeared on stdout alongside
+  the JSON-RPC body, breaking any naive `JSON.parse(stdout)`.
+
+  Fix: gate both breadcrumbs behind `CONFIG.verboseRegister`, OFF by
+  default. Ops can opt back in with `TOTALRECLAW_VERBOSE_REGISTER=1` (or
+  the general `TOTALRECLAW_DEBUG=1` toggle) when chasing a tool-injection
+  regression. Default-off keeps `openclaw agent --json` stdout clean.
+
+  Regression: `json-stdout-cleanliness.test.ts` (11 assertions) confirms
+  both breadcrumbs are wrapped in `if (CONFIG.verboseRegister)` blocks,
+  simulates the gated `--json` stdout path and `JSON.parse`s the result,
+  and exercises the env-var resolution (`TOTALRECLAW_VERBOSE_REGISTER`
+  -> `TOTALRECLAW_DEBUG` -> default false).
+
 ## [3.3.1-rc.16] — 2026-04-24
 
 Fixes #92 — slow-host install times out during ONNX-runtime / embedding-model

package/api-client.ts

@@ -8,8 +8,15 @@
  *   Authorization: Bearer <hex-encoded-auth-key>
  *
  * The server hashes the auth key with SHA-256 to look up the user.
+ *
+ * Every outbound request goes through `buildRelayHeaders()` so the
+ * `X-TotalReclaw-Client` tag is set + the optional QA-tracing
+ * `X-TotalReclaw-Session` tag is forwarded when `TOTALRECLAW_SESSION_ID`
+ * is set. See `relay-headers.ts` and internal#127.
  */
 
+import { buildRelayHeaders } from './relay-headers.js';
+
 // ---------------------------------------------------------------------------
 // Request / Response Types
 // ---------------------------------------------------------------------------
@@ -126,7 +133,7 @@ export function createApiClient(serverUrl: string) {
     ): Promise<{ user_id: string }> {
       const res = await fetch(`${baseUrl}/v1/register`, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json', 'X-TotalReclaw-Client': 'openclaw-plugin' },
+        headers: buildRelayHeaders({ 'Content-Type': 'application/json' }),
         body: JSON.stringify({ auth_key_hash: authKeyHash, salt: saltHex }),
       });
       await assertOk(res, 'register');
@@ -160,10 +167,10 @@ export function createApiClient(serverUrl: string) {
     ): Promise<{ ids: string[]; duplicate_ids?: string[] }> {
       const res = await fetch(`${baseUrl}/v1/store`, {
         method: 'POST',
-        headers: {
+        headers: buildRelayHeaders({
           'Content-Type': 'application/json',
           Authorization: `Bearer ${authKeyHex}`,
-        },
+        }),
         body: JSON.stringify({ user_id: userId, facts }),
       });
       await assertOk(res, 'store');
@@ -198,10 +205,10 @@ export function createApiClient(serverUrl: string) {
     ): Promise<SearchCandidate[]> {
       const res = await fetch(`${baseUrl}/v1/search`, {
         method: 'POST',
-        headers: {
+        headers: buildRelayHeaders({
           'Content-Type': 'application/json',
           Authorization: `Bearer ${authKeyHex}`,
-        },
+        }),
         body: JSON.stringify({
           user_id: userId,
           trapdoors,
@@ -229,9 +236,9 @@ export function createApiClient(serverUrl: string) {
     async deleteFact(factId: string, authKeyHex: string): Promise<void> {
       const res = await fetch(`${baseUrl}/v1/facts/${encodeURIComponent(factId)}`, {
         method: 'DELETE',
-        headers: {
+        headers: buildRelayHeaders({
           Authorization: `Bearer ${authKeyHex}`,
-        },
+        }),
       });
       await assertOk(res, 'deleteFact');
       const json = (await res.json()) as Record<string, unknown>;
@@ -254,10 +261,10 @@ export function createApiClient(serverUrl: string) {
     async batchDelete(factIds: string[], authKeyHex: string): Promise<number> {
       const res = await fetch(`${baseUrl}/v1/facts/batch-delete`, {
         method: 'POST',
-        headers: {
+        headers: buildRelayHeaders({
           'Content-Type': 'application/json',
           Authorization: `Bearer ${authKeyHex}`,
-        },
+        }),
         body: JSON.stringify({ fact_ids: factIds }),
       });
       await assertOk(res, 'batchDelete');
@@ -290,9 +297,9 @@ export function createApiClient(serverUrl: string) {
 
       const res = await fetch(`${baseUrl}/v1/export?${params.toString()}`, {
         method: 'GET',
-        headers: {
+        headers: buildRelayHeaders({
           Authorization: `Bearer ${authKeyHex}`,
-        },
+        }),
       });
       await assertOk(res, 'exportFacts');
       const json = (await res.json()) as Record<string, unknown>;

package/config.ts

@@ -9,8 +9,15 @@
  *
  * v1 env var cleanup — see `docs/guides/env-vars-reference.md`.
  * Removed user-facing vars: TOTALRECLAW_CHAIN_ID, TOTALRECLAW_EMBEDDING_MODEL,
- * TOTALRECLAW_STORE_DEDUP, TOTALRECLAW_LLM_MODEL, TOTALRECLAW_SESSION_ID,
- * TOTALRECLAW_TAXONOMY_VERSION.
+ * TOTALRECLAW_STORE_DEDUP, TOTALRECLAW_LLM_MODEL, TOTALRECLAW_TAXONOMY_VERSION.
+ *
+ * NOTE: ``TOTALRECLAW_SESSION_ID`` was in the removed list during the v1
+ * cleanup and silently rejected with a warning. That broke Axiom log tracing
+ * for QA — the qa-totalreclaw skill prescribes setting the var so relay logs
+ * are searchable by ``X-TotalReclaw-Session``. Restored as a SUPPORTED
+ * variable: read here, forwarded as the ``X-TotalReclaw-Session`` header on
+ * every outbound relay call. Mirrors the Python-side fix
+ * (`python/src/totalreclaw/agent/state.py`, v2.0.2). See internal#127.
  * Removed legacy gates: TOTALRECLAW_CLAIM_FORMAT, TOTALRECLAW_DIGEST_MODE,
  * TOTALRECLAW_AUTO_RESOLVE_MODE (the last one moved to an internal debug
  * module; see `contradiction-sync.ts`).
@@ -33,7 +40,9 @@ const REMOVED_ENV_VARS = [
   'TOTALRECLAW_EMBEDDING_MODEL',
   'TOTALRECLAW_STORE_DEDUP',
   'TOTALRECLAW_LLM_MODEL',
-  'TOTALRECLAW_SESSION_ID',
+  // NOTE: TOTALRECLAW_SESSION_ID was here before; restored as SUPPORTED
+  // (forwarded as X-TotalReclaw-Session header). Do NOT add it back to this
+  // list — see file header + internal#127.
   'TOTALRECLAW_TAXONOMY_VERSION',
   'TOTALRECLAW_CLAIM_FORMAT',
   'TOTALRECLAW_DIGEST_MODE',
@@ -63,6 +72,27 @@ export function getRecoveryPhrase(): string {
   return _recoveryPhraseOverride ?? process.env.TOTALRECLAW_RECOVERY_PHRASE ?? '';
 }
 
+/**
+ * Read the QA / observability session tag from the environment.
+ *
+ * When set, every outbound relay call adds the ``X-TotalReclaw-Session``
+ * header so relay logs (and Axiom queries) can be filtered by this tag —
+ * this is what the qa-totalreclaw skill relies on to scope log searches per
+ * QA run. When unset, returns ``null`` and the header is omitted.
+ *
+ * Read via getter (not snapshotted) so operators / test harnesses can flip
+ * the var between calls without reloading the module.
+ *
+ * Mirrors the Python-side ``RelayClient._session_id`` resolution priority.
+ * See internal#127 / `docs/guides/env-vars-reference.md`.
+ */
+export function getSessionId(): string | null {
+  const raw = process.env.TOTALRECLAW_SESSION_ID;
+  if (raw === undefined) return null;
+  const trimmed = raw.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
 /**
  * Runtime override for chain ID, set after the relay billing response is
  * read. Free tier stays on 84532 (Base Sepolia); Pro tier flips to 100
@@ -92,6 +122,15 @@ export const CONFIG = {
   get recoveryPhrase(): string {
     return getRecoveryPhrase();
   },
+  /**
+   * Optional QA / observability session tag forwarded to the relay as
+   * ``X-TotalReclaw-Session``. See `getSessionId()` above. Getter form so
+   * tests + harnesses can flip the env between calls. ``null`` when unset
+   * (header omitted).
+   */
+  get sessionId(): string | null {
+    return getSessionId();
+  },
   serverUrl: (process.env.TOTALRECLAW_SERVER_URL || 'https://api.totalreclaw.xyz').replace(/\/+$/, ''),
   selfHosted: process.env.TOTALRECLAW_SELF_HOSTED === 'true',
   credentialsPath: process.env.TOTALRECLAW_CREDENTIALS_PATH || path.join(home, '.totalreclaw', 'credentials.json'),
@@ -214,6 +253,24 @@ export const CONFIG = {
     return process.env.TOTALRECLAW_QA_REPO || '';
   },
 
+  // 3.3.1-rc.21 (issue #128): verbose-register flag. When enabled, the
+  // plugin emits opt-in `info`-level breadcrumbs after sensitive
+  // registerTool calls (currently `totalreclaw_pair`) to help ops/QA
+  // grep gateway logs for definitive proof the tool was declared.
+  // Default OFF — the breadcrumb is debug-grade and was bleeding into
+  // `openclaw agent --json` stdout, breaking programmatic parsers.
+  // Enable with either:
+  //   TOTALRECLAW_VERBOSE_REGISTER=1   (specific opt-in)
+  //   TOTALRECLAW_DEBUG=1              (general debug toggle)
+  // Read via getter so flipping the env at runtime takes effect on the
+  // next gateway start without a rebuild.
+  get verboseRegister(): boolean {
+    const specific = (process.env.TOTALRECLAW_VERBOSE_REGISTER ?? '').trim().toLowerCase();
+    if (specific === '1' || specific === 'true' || specific === 'yes') return true;
+    const general = (process.env.TOTALRECLAW_DEBUG ?? '').trim().toLowerCase();
+    return general === '1' || general === 'true' || general === 'yes';
+  },
+
   // Paths
   home,
   billingCachePath: path.join(home, '.totalreclaw', 'billing-cache.json'),

package/crypto.ts

@@ -15,10 +15,18 @@
  *     -> HKDF-SHA256(seed, salt, "openmemory-dedup-v1",           32) -> dedupKey
  */
 
-// Lazy-load WASM to avoid crash when npm install hasn't finished yet.
+// Lazy-load WASM. Uses createRequire so this module loads cleanly under bare
+// Node ESM — the shipped `dist/index.js` declares `"type":"module"`, where
+// the CJS `require` global is undefined at runtime. Prior to the rc.21 fix
+// this file called bare `require('@totalreclaw/core')` and every consumer
+// died with `require is not defined`. Matches the pattern already used by
+// claims-helper / consolidation / contradiction-sync / digest-sync / pin /
+// retype-setscope. See issue #124.
+import { createRequire } from 'node:module';
+const requireWasm = createRequire(import.meta.url);
 let _wasm: typeof import('@totalreclaw/core') | null = null;
 function getWasm() {
-  if (!_wasm) _wasm = require('@totalreclaw/core');
+  if (!_wasm) _wasm = requireWasm('@totalreclaw/core');
   return _wasm;
 }
 

package/dist/api-client.js

@@ -8,7 +8,13 @@
  *   Authorization: Bearer <hex-encoded-auth-key>
  *
  * The server hashes the auth key with SHA-256 to look up the user.
+ *
+ * Every outbound request goes through `buildRelayHeaders()` so the
+ * `X-TotalReclaw-Client` tag is set + the optional QA-tracing
+ * `X-TotalReclaw-Session` tag is forwarded when `TOTALRECLAW_SESSION_ID`
+ * is set. See `relay-headers.ts` and internal#127.
  */
+import { buildRelayHeaders } from './relay-headers.js';
 // ---------------------------------------------------------------------------
 // API Client Factory
 // ---------------------------------------------------------------------------
@@ -56,7 +62,7 @@ export function createApiClient(serverUrl) {
         async register(authKeyHash, saltHex) {
             const res = await fetch(`${baseUrl}/v1/register`, {
                 method: 'POST',
-                headers: { 'Content-Type': 'application/json', 'X-TotalReclaw-Client': 'openclaw-plugin' },
+                headers: buildRelayHeaders({ 'Content-Type': 'application/json' }),
                 body: JSON.stringify({ auth_key_hash: authKeyHash, salt: saltHex }),
             });
             await assertOk(res, 'register');
@@ -80,10 +86,10 @@ export function createApiClient(serverUrl) {
         async store(userId, facts, authKeyHex) {
             const res = await fetch(`${baseUrl}/v1/store`, {
                 method: 'POST',
-                headers: {
+                headers: buildRelayHeaders({
                     'Content-Type': 'application/json',
                     Authorization: `Bearer ${authKeyHex}`,
-                },
+                }),
                 body: JSON.stringify({ user_id: userId, facts }),
             });
             await assertOk(res, 'store');
@@ -109,10 +115,10 @@ export function createApiClient(serverUrl) {
         async search(userId, trapdoors, maxCandidates, authKeyHex) {
             const res = await fetch(`${baseUrl}/v1/search`, {
                 method: 'POST',
-                headers: {
+                headers: buildRelayHeaders({
                     'Content-Type': 'application/json',
                     Authorization: `Bearer ${authKeyHex}`,
-                },
+                }),
                 body: JSON.stringify({
                     user_id: userId,
                     trapdoors,
@@ -136,9 +142,9 @@ export function createApiClient(serverUrl) {
         async deleteFact(factId, authKeyHex) {
             const res = await fetch(`${baseUrl}/v1/facts/${encodeURIComponent(factId)}`, {
                 method: 'DELETE',
-                headers: {
+                headers: buildRelayHeaders({
                     Authorization: `Bearer ${authKeyHex}`,
-                },
+                }),
             });
             await assertOk(res, 'deleteFact');
             const json = (await res.json());
@@ -157,10 +163,10 @@ export function createApiClient(serverUrl) {
         async batchDelete(factIds, authKeyHex) {
             const res = await fetch(`${baseUrl}/v1/facts/batch-delete`, {
                 method: 'POST',
-                headers: {
+                headers: buildRelayHeaders({
                     'Content-Type': 'application/json',
                     Authorization: `Bearer ${authKeyHex}`,
-                },
+                }),
                 body: JSON.stringify({ fact_ids: factIds }),
             });
             await assertOk(res, 'batchDelete');
@@ -185,9 +191,9 @@ export function createApiClient(serverUrl) {
                 params.set('cursor', cursor);
             const res = await fetch(`${baseUrl}/v1/export?${params.toString()}`, {
                 method: 'GET',
-                headers: {
+                headers: buildRelayHeaders({
                     Authorization: `Bearer ${authKeyHex}`,
-                },
+                }),
             });
             await assertOk(res, 'exportFacts');
             const json = (await res.json());

package/dist/config.js

@@ -9,8 +9,15 @@
  *
  * v1 env var cleanup — see `docs/guides/env-vars-reference.md`.
  * Removed user-facing vars: TOTALRECLAW_CHAIN_ID, TOTALRECLAW_EMBEDDING_MODEL,
- * TOTALRECLAW_STORE_DEDUP, TOTALRECLAW_LLM_MODEL, TOTALRECLAW_SESSION_ID,
- * TOTALRECLAW_TAXONOMY_VERSION.
+ * TOTALRECLAW_STORE_DEDUP, TOTALRECLAW_LLM_MODEL, TOTALRECLAW_TAXONOMY_VERSION.
+ *
+ * NOTE: ``TOTALRECLAW_SESSION_ID`` was in the removed list during the v1
+ * cleanup and silently rejected with a warning. That broke Axiom log tracing
+ * for QA — the qa-totalreclaw skill prescribes setting the var so relay logs
+ * are searchable by ``X-TotalReclaw-Session``. Restored as a SUPPORTED
+ * variable: read here, forwarded as the ``X-TotalReclaw-Session`` header on
+ * every outbound relay call. Mirrors the Python-side fix
+ * (`python/src/totalreclaw/agent/state.py`, v2.0.2). See internal#127.
  * Removed legacy gates: TOTALRECLAW_CLAIM_FORMAT, TOTALRECLAW_DIGEST_MODE,
  * TOTALRECLAW_AUTO_RESOLVE_MODE (the last one moved to an internal debug
  * module; see `contradiction-sync.ts`).
@@ -30,7 +37,9 @@ const REMOVED_ENV_VARS = [
     'TOTALRECLAW_EMBEDDING_MODEL',
     'TOTALRECLAW_STORE_DEDUP',
     'TOTALRECLAW_LLM_MODEL',
-    'TOTALRECLAW_SESSION_ID',
+    // NOTE: TOTALRECLAW_SESSION_ID was here before; restored as SUPPORTED
+    // (forwarded as X-TotalReclaw-Session header). Do NOT add it back to this
+    // list — see file header + internal#127.
     'TOTALRECLAW_TAXONOMY_VERSION',
     'TOTALRECLAW_CLAIM_FORMAT',
     'TOTALRECLAW_DIGEST_MODE',
@@ -53,6 +62,27 @@ export function setRecoveryPhraseOverride(phrase) {
 export function getRecoveryPhrase() {
     return _recoveryPhraseOverride ?? process.env.TOTALRECLAW_RECOVERY_PHRASE ?? '';
 }
+/**
+ * Read the QA / observability session tag from the environment.
+ *
+ * When set, every outbound relay call adds the ``X-TotalReclaw-Session``
+ * header so relay logs (and Axiom queries) can be filtered by this tag —
+ * this is what the qa-totalreclaw skill relies on to scope log searches per
+ * QA run. When unset, returns ``null`` and the header is omitted.
+ *
+ * Read via getter (not snapshotted) so operators / test harnesses can flip
+ * the var between calls without reloading the module.
+ *
+ * Mirrors the Python-side ``RelayClient._session_id`` resolution priority.
+ * See internal#127 / `docs/guides/env-vars-reference.md`.
+ */
+export function getSessionId() {
+    const raw = process.env.TOTALRECLAW_SESSION_ID;
+    if (raw === undefined)
+        return null;
+    const trimmed = raw.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
 /**
  * Runtime override for chain ID, set after the relay billing response is
  * read. Free tier stays on 84532 (Base Sepolia); Pro tier flips to 100
@@ -79,6 +109,15 @@ export const CONFIG = {
     get recoveryPhrase() {
         return getRecoveryPhrase();
     },
+    /**
+     * Optional QA / observability session tag forwarded to the relay as
+     * ``X-TotalReclaw-Session``. See `getSessionId()` above. Getter form so
+     * tests + harnesses can flip the env between calls. ``null`` when unset
+     * (header omitted).
+     */
+    get sessionId() {
+        return getSessionId();
+    },
     serverUrl: (process.env.TOTALRECLAW_SERVER_URL || 'https://api.totalreclaw.xyz').replace(/\/+$/, ''),
     selfHosted: process.env.TOTALRECLAW_SELF_HOSTED === 'true',
     credentialsPath: process.env.TOTALRECLAW_CREDENTIALS_PATH || path.join(home, '.totalreclaw', 'credentials.json'),
@@ -192,6 +231,24 @@ export const CONFIG = {
     get qaRepoOverride() {
         return process.env.TOTALRECLAW_QA_REPO || '';
     },
+    // 3.3.1-rc.21 (issue #128): verbose-register flag. When enabled, the
+    // plugin emits opt-in `info`-level breadcrumbs after sensitive
+    // registerTool calls (currently `totalreclaw_pair`) to help ops/QA
+    // grep gateway logs for definitive proof the tool was declared.
+    // Default OFF — the breadcrumb is debug-grade and was bleeding into
+    // `openclaw agent --json` stdout, breaking programmatic parsers.
+    // Enable with either:
+    //   TOTALRECLAW_VERBOSE_REGISTER=1   (specific opt-in)
+    //   TOTALRECLAW_DEBUG=1              (general debug toggle)
+    // Read via getter so flipping the env at runtime takes effect on the
+    // next gateway start without a rebuild.
+    get verboseRegister() {
+        const specific = (process.env.TOTALRECLAW_VERBOSE_REGISTER ?? '').trim().toLowerCase();
+        if (specific === '1' || specific === 'true' || specific === 'yes')
+            return true;
+        const general = (process.env.TOTALRECLAW_DEBUG ?? '').trim().toLowerCase();
+        return general === '1' || general === 'true' || general === 'yes';
+    },
     // Paths
     home,
     billingCachePath: path.join(home, '.totalreclaw', 'billing-cache.json'),

package/dist/crypto.js

@@ -14,11 +14,19 @@
  *     -> HKDF-SHA256(seed, salt, "totalreclaw-encryption-key-v1", 32) -> encryptionKey
  *     -> HKDF-SHA256(seed, salt, "openmemory-dedup-v1",           32) -> dedupKey
  */
-// Lazy-load WASM to avoid crash when npm install hasn't finished yet.
+// Lazy-load WASM. Uses createRequire so this module loads cleanly under bare
+// Node ESM — the shipped `dist/index.js` declares `"type":"module"`, where
+// the CJS `require` global is undefined at runtime. Prior to the rc.21 fix
+// this file called bare `require('@totalreclaw/core')` and every consumer
+// died with `require is not defined`. Matches the pattern already used by
+// claims-helper / consolidation / contradiction-sync / digest-sync / pin /
+// retype-setscope. See issue #124.
+import { createRequire } from 'node:module';
+const requireWasm = createRequire(import.meta.url);
 let _wasm = null;
 function getWasm() {
     if (!_wasm)
-        _wasm = require('@totalreclaw/core');
+        _wasm = requireWasm('@totalreclaw/core');
     return _wasm;
 }
 // ---------------------------------------------------------------------------

package/dist/fs-helpers.js

@@ -213,6 +213,88 @@ export function deleteFileIfExists(filePath) {
     }
 }
 // ---------------------------------------------------------------------------
+// Install-staging cleanup (issue #126 — rc.20 finding F3)
+// ---------------------------------------------------------------------------
+/**
+ * Clean up `.openclaw-install-stage-*` sibling directories left behind by
+ * an interrupted `openclaw plugins install` run.
+ *
+ * Background
+ * ----------
+ * `openclaw plugins install @totalreclaw/totalreclaw` extracts the npm
+ * tarball into a staging directory named
+ * `<extensionsDir>/.openclaw-install-stage-XXXXXX/` and then renames it
+ * to `<extensionsDir>/totalreclaw/` on success. If the install is
+ * interrupted partway through (e.g. an auto-gateway-restart triggered by
+ * the same install kills the process — see rc.20 QA finding F3), the
+ * staging dir survives. On the next gateway start, OpenClaw's plugin
+ * loader auto-discovers BOTH directories — the real `totalreclaw/` and
+ * the orphaned `.openclaw-install-stage-XXXXXX/` — and registers two
+ * copies of the plugin. Hooks fire twice, the user sees a duplicate
+ * `totalreclaw` row in `openclaw plugins list`, and the gateway log
+ * spams a duplicate-plugin-id warning every cycle.
+ *
+ * Fix scope: best-effort cleanup driven by the plugin itself at register
+ * time. We resolve the extensions dir as the parent of the loaded
+ * plugin's own directory, scan for `.openclaw-install-stage-*` siblings,
+ * and recursively remove each one. If anything fails (permission,
+ * race with a concurrent install), we swallow the error — the existing
+ * loader-warning behavior is no worse than before.
+ *
+ * Returns the list of staging-dir paths that were successfully removed.
+ * Callers may log this for ops visibility. Empty list on a clean install.
+ *
+ * Parameters
+ * ----------
+ * @param pluginDir  Absolute path to the loaded plugin's directory
+ *                   (typically `<extensionsDir>/totalreclaw/dist`). The
+ *                   helper walks up to the parent that holds sibling
+ *                   plugin directories (the `extensions/` root).
+ * @param _now       Optional clock injector for testing — defaults to
+ *                   Date.now().
+ */
+export function cleanupInstallStagingDirs(pluginDir, _now = Date.now) {
+    const removed = [];
+    try {
+        // pluginDir is `<extensionsDir>/totalreclaw/dist` after build, so the
+        // siblings live two levels up. Resolve both candidates so the helper
+        // works regardless of whether the caller passes the package root or
+        // its `dist/` subdir.
+        const candidates = [
+            path.resolve(pluginDir, '..'), // <extensionsDir>/totalreclaw → siblings dir if pluginDir is `dist`
+            path.resolve(pluginDir, '..', '..'), // <extensionsDir>/             → siblings dir if pluginDir is package root
+        ];
+        for (const extensionsDir of candidates) {
+            let entries;
+            try {
+                entries = fs.readdirSync(extensionsDir);
+            }
+            catch {
+                continue;
+            }
+            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.push(target);
+                }
+                catch {
+                    // Best-effort — skip unreadable / racy entries.
+                }
+            }
+        }
+    }
+    catch {
+        // Best-effort — never crash plugin init on cleanup failure.
+    }
+    return removed;
+}
+// ---------------------------------------------------------------------------
 // Auto-bootstrap of credentials.json (3.1.0 first-run UX)
 // ---------------------------------------------------------------------------
 /**