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

package/dist/index.js

@@ -63,8 +63,9 @@ import { executePinOperation, validatePinArgs, } from './pin.js';
 import { executeRetype, executeSetScope, validateRetypeArgs, validateSetScopeArgs, } from './retype-setscope.js';
 import { PluginHotCache } from './hot-cache-wrapper.js';
 import { CONFIG, setRecoveryPhraseOverride } from './config.js';
+import { buildRelayHeaders } from './relay-headers.js';
 import { readBillingCache, writeBillingCache, BILLING_CACHE_PATH, } from './billing-cache.js';
-import { ensureMemoryHeaderFile, loadCredentialsJson, writeCredentialsJson, deleteCredentialsFile, isRunningInDocker, deleteFileIfExists, resolveOnboardingState, writeOnboardingState, readPluginVersion, } from './fs-helpers.js';
+import { ensureMemoryHeaderFile, loadCredentialsJson, writeCredentialsJson, deleteCredentialsFile, isRunningInDocker, deleteFileIfExists, resolveOnboardingState, writeOnboardingState, readPluginVersion, cleanupInstallStagingDirs, } from './fs-helpers.js';
 import { isRcBuild } from './qa-bug-report.js';
 import { decideToolGate, isGatedToolName } from './tool-gating.js';
 import { detectFirstRun, buildWelcomePrepend } from './first-run.js';
@@ -73,6 +74,18 @@ import { detectGatewayHost } from './gateway-url.js';
 import { validateMnemonic } from '@scure/bip39';
 import { wordlist } from '@scure/bip39/wordlists/english.js';
 import crypto from 'node:crypto';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import * as nodePath from 'node:path';
+// CJS-style require for the @totalreclaw/core WASM module. We keep this
+// load path lazy (only inside getSmartImportWasm() below) so a partial
+// install of the dependency tree doesn't crash module init. Bare
+// `require()` is a CommonJS global and is undefined under bare Node ESM —
+// the shipped `dist/index.js` declares `"type":"module"`, so calling the
+// global directly emits "require is not defined" at runtime (issue #124).
+// createRequire bridges the gap. Same shape as crypto.ts / lsh.ts /
+// subgraph-store.ts / claims-helper.ts.
+const __cjsRequire = createRequire(import.meta.url);
 // ---------------------------------------------------------------------------
 // Human-friendly error messages
 // ---------------------------------------------------------------------------
@@ -632,11 +645,10 @@ async function initialize(logger) {
                 const billingUrl = CONFIG.serverUrl;
                 const resp = await fetch(`${billingUrl}/v1/billing/status?wallet_address=${encodeURIComponent(walletAddr)}`, {
                     method: 'GET',
-                    headers: {
+                    headers: buildRelayHeaders({
                         'Authorization': `Bearer ${authKeyHex}`,
                         'Accept': 'application/json',
-                        'X-TotalReclaw-Client': 'openclaw-plugin',
-                    },
+                    }),
                 });
                 if (resp.ok) {
                     const billingData = await resp.json();
@@ -1121,12 +1133,12 @@ const MIGRATION_PAGE_SIZE = 1000;
 /** Execute a GraphQL query against a subgraph endpoint. Returns null on error. */
 async function migrationGqlQuery(endpoint, query, variables, authKey) {
     try {
-        const headers = {
+        const overrides = {
             'Content-Type': 'application/json',
-            'X-TotalReclaw-Client': 'openclaw-plugin',
         };
         if (authKey)
-            headers['Authorization'] = `Bearer ${authKey}`;
+            overrides['Authorization'] = `Bearer ${authKey}`;
+        const headers = buildRelayHeaders(overrides);
         const response = await fetch(endpoint, {
             method: 'POST',
             headers,
@@ -1867,11 +1879,14 @@ async function handlePluginImportFrom(params, logger) {
 // ---------------------------------------------------------------------------
 // Smart Import — Two-Pass Pipeline (Profile + Triage)
 // ---------------------------------------------------------------------------
-// Lazy-load WASM for smart import functions (same pattern as crypto.ts / subgraph-store.ts).
+// Lazy-load WASM for smart import functions (same pattern as crypto.ts /
+// subgraph-store.ts). Goes through __cjsRequire (createRequire(import.meta.url))
+// declared at the top of the file — bare `require()` is undefined under
+// pure-ESM Node, see issue #124.
 let _smartImportWasm = null;
 function getSmartImportWasm() {
     if (!_smartImportWasm)
-        _smartImportWasm = require('@totalreclaw/core');
+        _smartImportWasm = __cjsRequire('@totalreclaw/core');
     return _smartImportWasm;
 }
 /**
@@ -2298,17 +2313,35 @@ const plugin = {
         // the loopback callsite if package.json read fails.
         let pluginVersion = null;
         try {
-            // `import.meta.url` is ESM-only; fallback to `__dirname` for the CJS
-            // build path. `require` comes from Node core and is available in both
-            // module formats. `fileURLToPath` / `path.dirname` are pure-sync.
-            const url = require('node:url');
-            const nodePath = require('node:path');
-            const pluginDir = nodePath.dirname(url.fileURLToPath(import.meta.url));
+            // Resolve our own dist/ directory so `readPluginVersion` can locate
+            // package.json. We use `import.meta.url` + ESM-static stdlib imports
+            // (`fileURLToPath` from `node:url`, `nodePath.dirname` from `node:path`,
+            // both imported at the top of this file). Earlier shape used inline
+            // `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));
             pluginVersion = readPluginVersion(pluginDir);
             rcMode = isRcBuild(pluginVersion);
             if (rcMode) {
                 api.logger.info(`TotalReclaw: RC build detected (version=${pluginVersion}). RC-gated tools will be registered.`);
             }
+            // 3.3.1-rc.21 (issue #126 — rc.20 finding F3): clean up
+            // `.openclaw-install-stage-*` siblings left behind by an interrupted
+            // `openclaw plugins install` run. Without cleanup, OpenClaw's plugin
+            // loader auto-discovers the orphan directory on the next gateway
+            // start and registers a duplicate `totalreclaw` plugin (duplicate
+            // hooks, duplicate tools, "duplicate-plugin-id" warning every cycle).
+            // Best-effort — never throws on permission / race failures.
+            try {
+                const removed = cleanupInstallStagingDirs(pluginDir);
+                if (removed.length > 0) {
+                    api.logger.info(`TotalReclaw: removed ${removed.length} stale install-staging dir(s) from prior interrupted install: ${removed.join(', ')}`);
+                }
+            }
+            catch {
+                // Best-effort — already swallowed inside the helper, but keep this
+                // outer try as belt-and-braces against future helper changes.
+            }
         }
         catch {
             rcMode = false;
@@ -2459,8 +2492,30 @@ const plugin = {
                     // Write credentials.json + flip state to 'active' via
                     // fs-helpers. This centralizes disk I/O off the
                     // pair-http surface (scanner isolation).
+                    //
+                    // 3.3.1 (internal#130) — derive + persist the Smart Account
+                    // address right here so the user can see their scope address
+                    // immediately after pair, without waiting for a first chain
+                    // write. SA derivation runs locally (WASM deriveEoa + factory
+                    // getAddress eth_call); the mnemonic NEVER crosses any new
+                    // boundary — it's already on disk in credentials.json and is
+                    // consumed by the same `deriveSmartAccountAddress` call the
+                    // store/search paths use. Only the derived public address is
+                    // persisted to credentials.json (`scope_address`).
+                    let scopeAddress;
+                    try {
+                        scopeAddress = await deriveSmartAccountAddress(mnemonic, CONFIG.chainId);
+                    }
+                    catch (err) {
+                        // Best-effort. If chain RPC is unreachable at pair time, the
+                        // status tool re-tries derivation lazily on next call —
+                        // fall through and write credentials.json without it.
+                        api.logger.warn(`pair: scope_address derivation failed (will retry lazily): ${err instanceof Error ? err.message : String(err)}`);
+                    }
                     const creds = loadCredentialsJson(CREDENTIALS_PATH) ?? {};
                     const next = { ...creds, mnemonic };
+                    if (scopeAddress)
+                        next.scope_address = scopeAddress;
                     if (!writeCredentialsJson(CREDENTIALS_PATH, next)) {
                         return { state: 'error', error: 'credentials_write_failed' };
                     }
@@ -3145,11 +3200,10 @@ const plugin = {
                                 : { owner, first: PAGE_SIZE };
                             const res = await fetch(`${relayUrl}/v1/subgraph`, {
                                 method: 'POST',
-                                headers: {
+                                headers: buildRelayHeaders({
                                     'Content-Type': 'application/json',
-                                    'X-TotalReclaw-Client': 'openclaw-plugin',
                                     ...(authKeyHex ? { Authorization: `Bearer ${authKeyHex}` } : {}),
-                                },
+                                }),
                                 body: JSON.stringify({ query, variables }),
                             });
                             const json = (await res.json());
@@ -3275,11 +3329,10 @@ const plugin = {
                     const walletAddr = subgraphOwner || userId || '';
                     const response = await fetch(`${serverUrl}/v1/billing/status?wallet_address=${encodeURIComponent(walletAddr)}`, {
                         method: 'GET',
-                        headers: {
+                        headers: buildRelayHeaders({
                             'Authorization': `Bearer ${authKeyHex}`,
                             'Accept': 'application/json',
-                            'X-TotalReclaw-Client': 'openclaw-plugin',
-                        },
+                        }),
                     });
                     if (!response.ok) {
                         const body = await response.text().catch(() => '');
@@ -3300,6 +3353,32 @@ const plugin = {
                         features: data.features,
                         checked_at: Date.now(),
                     });
+                    // 3.3.1 (internal#130) — surface the Smart Account / scope
+                    // address so the user can do subgraph queries, BaseScan
+                    // lookups, and cross-client portability checks BEFORE any
+                    // chain write completes. Resolution priority:
+                    //   1. In-memory `subgraphOwner` (already derived earlier).
+                    //   2. credentials.json `scope_address` (persisted at pair).
+                    //   3. Lazy derive now from the loaded mnemonic + cache it
+                    //      back to credentials.json so the next call is free.
+                    let scopeAddress = subgraphOwner ?? undefined;
+                    if (!scopeAddress) {
+                        try {
+                            const credsCache = loadCredentialsJson(CREDENTIALS_PATH);
+                            if (credsCache?.scope_address && typeof credsCache.scope_address === 'string') {
+                                scopeAddress = credsCache.scope_address;
+                            }
+                            else if (credsCache?.mnemonic && typeof credsCache.mnemonic === 'string') {
+                                scopeAddress = await deriveSmartAccountAddress(credsCache.mnemonic, CONFIG.chainId);
+                                if (scopeAddress) {
+                                    writeCredentialsJson(CREDENTIALS_PATH, { ...credsCache, scope_address: scopeAddress });
+                                }
+                            }
+                        }
+                        catch (deriveErr) {
+                            api.logger.warn(`totalreclaw_status: scope_address lookup failed: ${deriveErr instanceof Error ? deriveErr.message : String(deriveErr)}`);
+                        }
+                    }
                     const tierLabel = tier === 'pro' ? 'Pro' : 'Free';
                     const lines = [
                         `Tier: ${tierLabel}`,
@@ -3308,12 +3387,20 @@ const plugin = {
                     if (freeWritesResetAt) {
                         lines.push(`Resets: ${new Date(freeWritesResetAt).toLocaleDateString()}`);
                     }
+                    if (scopeAddress) {
+                        lines.push(`Smart Account: ${scopeAddress}`);
+                    }
                     if (tier !== 'pro') {
                         lines.push(`Pricing: https://totalreclaw.xyz/pricing`);
                     }
                     return {
                         content: [{ type: 'text', text: lines.join('\n') }],
-                        details: { tier, free_writes_used: freeWritesUsed, free_writes_limit: freeWritesLimit },
+                        details: {
+                            tier,
+                            free_writes_used: freeWritesUsed,
+                            free_writes_limit: freeWritesLimit,
+                            scope_address: scopeAddress,
+                        },
                     };
                 }
                 catch (err) {
@@ -3972,11 +4059,10 @@ const plugin = {
                     }
                     const response = await fetch(`${serverUrl}/v1/billing/checkout`, {
                         method: 'POST',
-                        headers: {
+                        headers: buildRelayHeaders({
                             'Authorization': `Bearer ${authKeyHex}`,
                             'Content-Type': 'application/json',
-                            'X-TotalReclaw-Client': 'openclaw-plugin',
-                        },
+                        }),
                         body: JSON.stringify({
                             wallet_address: walletAddr,
                             tier: 'pro',
@@ -4045,11 +4131,10 @@ const plugin = {
                     // 1. Check billing tier
                     const billingResp = await fetch(`${serverUrl}/v1/billing/status?wallet_address=${encodeURIComponent(subgraphOwner)}`, {
                         method: 'GET',
-                        headers: {
+                        headers: buildRelayHeaders({
                             'Authorization': `Bearer ${authKeyHex}`,
                             'Content-Type': 'application/json',
-                            'X-TotalReclaw-Client': 'openclaw-plugin',
-                        },
+                        }),
                     });
                     if (!billingResp.ok) {
                         return { content: [{ type: 'text', text: `Failed to check billing tier (HTTP ${billingResp.status}).` }] };
@@ -4304,8 +4389,23 @@ const plugin = {
                                     phraseValidator: (p) => validateMnemonic(p, wordlist),
                                     completePairing: async ({ mnemonic }) => {
                                         try {
+                                            // 3.3.1 (internal#130) — derive + persist the
+                                            // Smart Account address now so the user can see
+                                            // it immediately after pair, before any chain
+                                            // write. Mnemonic stays in this scope (already
+                                            // on disk in credentials.json); only the
+                                            // derived public scope_address is added.
+                                            let scopeAddress;
+                                            try {
+                                                scopeAddress = await deriveSmartAccountAddress(mnemonic, CONFIG.chainId);
+                                            }
+                                            catch (deriveErr) {
+                                                api.logger.warn(`totalreclaw_pair(relay): scope_address derivation failed (will retry lazily): ${deriveErr instanceof Error ? deriveErr.message : String(deriveErr)}`);
+                                            }
                                             const creds = loadCredentialsJson(CREDENTIALS_PATH) ?? {};
                                             const next = { ...creds, mnemonic };
+                                            if (scopeAddress)
+                                                next.scope_address = scopeAddress;
                                             if (!writeCredentialsJson(CREDENTIALS_PATH, next)) {
                                                 return { state: 'error', error: 'credentials_write_failed' };
                                             }
@@ -4316,7 +4416,7 @@ const plugin = {
                                                 credentialsCreatedAt: new Date().toISOString(),
                                                 version: pluginVersion ?? '3.3.0',
                                             });
-                                            api.logger.info(`totalreclaw_pair(relay): session ${remoteSession.token.slice(0, 8)}… completed; credentials written`);
+                                            api.logger.info(`totalreclaw_pair(relay): session ${remoteSession.token.slice(0, 8)}… completed; credentials written${scopeAddress ? ` (scope_address=${scopeAddress})` : ''}`);
                                             return { state: 'active' };
                                         }
                                         catch (err) {
@@ -4447,9 +4547,18 @@ const plugin = {
         // declared. If the agent then reports the tool is missing from its
         // tool list, the gap is upstream OpenClaw tool propagation, not our
         // plugin — see issue #110 fix 3 + PR #102 (CLI fallback).
-        api.logger.info('TotalReclaw: registerTool(totalreclaw_pair) returned. If the agent does not see it in its tool list ' +
-            'after gateway restart, the issue is upstream tool injection (containerized agents) — fall back to ' +
-            '`openclaw totalreclaw pair generate --url-pin-only` (PR #102) or `openclaw totalreclaw onboard --pair-only`.');
+        //
+        // 3.3.1-rc.21 (issue #128): the breadcrumb is debug-grade — it was
+        // bleeding into `openclaw agent --json` stdout, breaking programmatic
+        // parsers that expect the JSON-RPC body to be the only thing on the
+        // wire. Gated behind `TOTALRECLAW_VERBOSE_REGISTER` (or the general
+        // `TOTALRECLAW_DEBUG` toggle) so ops can opt back in when chasing
+        // a tool-injection regression. Default OFF — clean stdout for users.
+        if (CONFIG.verboseRegister) {
+            api.logger.info('TotalReclaw: registerTool(totalreclaw_pair) returned. If the agent does not see it in its tool list ' +
+                'after gateway restart, the issue is upstream tool injection (containerized agents) — fall back to ' +
+                '`openclaw totalreclaw pair generate --url-pin-only` (PR #102) or `openclaw totalreclaw onboard --pair-only`.');
+        }
         // ---------------------------------------------------------------
         // Tool: totalreclaw_report_qa_bug (3.3.1-rc.3 — RC-gated)
         //
@@ -4573,7 +4682,13 @@ const plugin = {
                     }
                 },
             }, { name: 'totalreclaw_report_qa_bug' });
-            api.logger.info('totalreclaw_report_qa_bug registered (RC build — this tool is hidden in stable releases).');
+            // 3.3.1-rc.21 (issue #128): demote the registration-confirmation
+            // breadcrumb to verbose-only. Same `--json` stdout pollution risk
+            // as the totalreclaw_pair breadcrumb above; ops can opt back in
+            // via TOTALRECLAW_VERBOSE_REGISTER / TOTALRECLAW_DEBUG.
+            if (CONFIG.verboseRegister) {
+                api.logger.info('totalreclaw_report_qa_bug registered (RC build — this tool is hidden in stable releases).');
+            }
         }
         // ---------------------------------------------------------------
         // Hook: before_tool_call (3.2.0 memory-tool gate)
@@ -4696,7 +4811,7 @@ const plugin = {
                         const walletParam = encodeURIComponent(subgraphOwner || userId || '');
                         const billingResp = await fetch(`${billingUrl}/v1/billing/status?wallet_address=${walletParam}`, {
                             method: 'GET',
-                            headers: { 'Authorization': `Bearer ${authKeyHex}`, 'Accept': 'application/json', 'X-TotalReclaw-Client': 'openclaw-plugin' },
+                            headers: buildRelayHeaders({ 'Authorization': `Bearer ${authKeyHex}`, 'Accept': 'application/json' }),
                         });
                         if (billingResp.ok) {
                             const billingData = await billingResp.json();

package/dist/lsh.js

@@ -6,11 +6,16 @@
  *
  * Default parameters: 32 bits per table, 20 tables.
  */
-// Lazy-load WASM to avoid crash when npm install hasn't finished yet.
+// Lazy-load WASM via createRequire. The shipped `dist/index.js` is ESM-only
+// (`"type":"module"`) so the bare `require` global is undefined at runtime.
+// See issue #124 for the bug this avoids; matches the pattern in
+// claims-helper / consolidation / digest-sync / pin / retype-setscope.
+import { createRequire } from 'node:module';
+const requireWasm = createRequire(import.meta.url);
 let _WasmLshHasher = null;
 function getWasmLshHasher() {
     if (!_WasmLshHasher)
-        _WasmLshHasher = require('@totalreclaw/core').WasmLshHasher;
+        _WasmLshHasher = requireWasm('@totalreclaw/core').WasmLshHasher;
     return _WasmLshHasher;
 }
 /**

package/dist/relay-headers.js

@@ -0,0 +1,44 @@
+/**
+ * Shared outbound-header helper for relay calls.
+ *
+ * Centralizes the common `X-TotalReclaw-*` headers so every fetch site
+ * consistently tags requests with:
+ *   - `X-TotalReclaw-Client`  — caller identity (defaults to `openclaw-plugin`).
+ *   - `X-TotalReclaw-Session` — optional QA / observability tag from
+ *     `TOTALRECLAW_SESSION_ID`. Used by Axiom log filters and the
+ *     `qa-totalreclaw` skill to scope log searches per QA run.
+ *
+ * Pure function — no I/O, no network. Reads `getSessionId()` (which reads the
+ * env var via getter so harnesses that flip the env between calls pick up
+ * the new value).
+ *
+ * The session-id env var was accidentally placed in the v1 REMOVED_ENV_VARS
+ * list and silently warned-and-dropped, breaking Axiom traceability for QA
+ * runs (see internal#127). This helper is the canonical re-entry point for
+ * the variable.
+ */
+import { getSessionId } from './config.js';
+/** Default `X-TotalReclaw-Client` value. */
+export const DEFAULT_CLIENT_ID = 'openclaw-plugin';
+/**
+ * Build the standard outbound header set.
+ *
+ * @param overrides - merge-in additional headers (`Authorization`,
+ *   `Content-Type`, etc.); these win over the defaults.
+ * @param clientId - override the `X-TotalReclaw-Client` value.
+ *
+ * Always includes `X-TotalReclaw-Client`. Includes `X-TotalReclaw-Session`
+ * only when `TOTALRECLAW_SESSION_ID` is set + non-empty.
+ */
+export function buildRelayHeaders(overrides = {}, clientId = DEFAULT_CLIENT_ID) {
+    const headers = {
+        'X-TotalReclaw-Client': clientId,
+    };
+    const sessionId = getSessionId();
+    if (sessionId) {
+        headers['X-TotalReclaw-Session'] = sessionId;
+    }
+    // Caller-supplied headers (Authorization, Content-Type, Accept, etc.) take
+    // precedence over the defaults but should generally not stomp the X-* tags.
+    return { ...headers, ...overrides };
+}

package/dist/subgraph-search.js

@@ -21,6 +21,7 @@
  */
 import { getSubgraphConfig } from './subgraph-store.js';
 import { CONFIG } from './config.js';
+import { buildRelayHeaders } from './relay-headers.js';
 /** Batch size for Phase 2 split queries. */
 const TRAPDOOR_BATCH_SIZE = CONFIG.trapdoorBatchSize;
 /** Graph Studio / Graph Network hard limit on `first` argument. */
@@ -31,13 +32,13 @@ const PAGE_SIZE = CONFIG.pageSize;
  */
 async function gqlQuery(endpoint, query, variables, authKeyHex) {
     try {
-        const headers = {
+        const overrides = {
             'Content-Type': 'application/json',
-            'X-TotalReclaw-Client': 'openclaw-plugin',
         };
         if (authKeyHex) {
-            headers['Authorization'] = `Bearer ${authKeyHex}`;
+            overrides['Authorization'] = `Bearer ${authKeyHex}`;
         }
+        const headers = buildRelayHeaders(overrides);
         const response = await fetch(endpoint, {
             method: 'POST',
             headers,

package/dist/subgraph-store.js

@@ -9,14 +9,19 @@
  * ECDSA signing. Raw fetch() for all JSON-RPC calls to the relay bundler
  * and chain RPCs. No viem, no permissionless.
  */
-// Lazy-load WASM to avoid crash when npm install hasn't finished yet.
+// Lazy-load WASM via createRequire — the shipped bundle is ESM-only and
+// the bare `require` global is undefined there (issue #124). Same pattern
+// as crypto / lsh / claims-helper / consolidation / digest-sync.
+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;
 }
 import { CONFIG } from './config.js';
+import { buildRelayHeaders } from './relay-headers.js';
 // ---------------------------------------------------------------------------
 // Pimlico 429 retry helper
 // ---------------------------------------------------------------------------
@@ -294,14 +299,14 @@ export async function submitFactOnChain(protobufPayload, config) {
 }
 async function submitFactOnChainLocked(protobufPayload, config, eoa, sender) {
     const bundlerUrl = `${config.relayUrl}/v1/bundler`;
-    const headers = {
+    const overrides = {
         'Content-Type': 'application/json',
-        'X-TotalReclaw-Client': 'openclaw-plugin',
     };
     if (config.authKeyHex)
-        headers['Authorization'] = `Bearer ${config.authKeyHex}`;
+        overrides['Authorization'] = `Bearer ${config.authKeyHex}`;
     if (config.walletAddress)
-        headers['X-Wallet-Address'] = config.walletAddress;
+        overrides['X-Wallet-Address'] = config.walletAddress;
+    const headers = buildRelayHeaders(overrides);
     // Helper for JSON-RPC calls to relay bundler (with 429 retry)
     async function rpc(method, params) {
         return rpcWithRetry(bundlerUrl, headers, method, params);
@@ -482,14 +487,14 @@ export async function submitFactBatchOnChain(protobufPayloads, config) {
 }
 async function submitFactBatchOnChainLocked(protobufPayloads, config, eoa, sender) {
     const bundlerUrl = `${config.relayUrl}/v1/bundler`;
-    const headers = {
+    const overrides = {
         'Content-Type': 'application/json',
-        'X-TotalReclaw-Client': 'openclaw-plugin',
     };
     if (config.authKeyHex)
-        headers['Authorization'] = `Bearer ${config.authKeyHex}`;
+        overrides['Authorization'] = `Bearer ${config.authKeyHex}`;
     if (config.walletAddress)
-        headers['X-Wallet-Address'] = config.walletAddress;
+        overrides['X-Wallet-Address'] = config.walletAddress;
+    const headers = buildRelayHeaders(overrides);
     // Helper for JSON-RPC calls to relay bundler (with 429 retry)
     async function rpc(method, params) {
         return rpcWithRetry(bundlerUrl, headers, method, params);

package/fs-helpers.ts

@@ -56,6 +56,15 @@ export interface CredentialsFile {
   mnemonic?: string;
   /** Alias for `mnemonic`, accepted on read only. */
   recovery_phrase?: string;
+  /**
+   * Smart Account (scope) address derived from the mnemonic. Persisted at
+   * pair-finish so users + tools (`totalreclaw_status`) can read it before
+   * any on-chain write. Internal#130 — lazy SA derivation previously left
+   * the user blind to their scope address until first-write.
+   *
+   * Format: lowercase 0x-prefixed 40-hex-char address. Public, non-secret.
+   */
+  scope_address?: string;
   firstRunAnnouncementShown?: boolean;
   [extra: string]: unknown;
 }
@@ -252,6 +261,89 @@ export function deleteFileIfExists(filePath: string): void {
   }
 }
 
+// ---------------------------------------------------------------------------
+// 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: string,
+  _now: () => number = Date.now,
+): string[] {
+  const removed: string[] = [];
+  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: string[];
+      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)
 // ---------------------------------------------------------------------------