@totalreclaw/totalreclaw 3.3.2 → 3.3.3-rc.1

package/index.ts

@@ -81,6 +81,7 @@ import {
   getEmbeddingDims,
   getEmbeddingModelId,
   configureEmbedder,
+  prefetchEmbedderBundle,
 } from './llm-client.js';
 import {
   defaultAuthProfilesRoot,
@@ -748,6 +749,21 @@ let firstRunAfterInit = true;
  */
 let firstRunWelcomeShown = false;
 
+/**
+ * 3.3.3-rc.1 — RC-mode staging-only banner (PR #165 implementation).
+ *
+ * Fires ONCE per gateway process when:
+ *   - the bundled-default `serverUrl` resolves to `api-staging.totalreclaw.xyz`
+ *     (RC artifact, not stable), AND
+ *   - the user has NOT overridden via `TOTALRECLAW_SERVER_URL=...` env.
+ *
+ * Goal: a fresh QA tester can't accidentally use an RC build for real data
+ * without seeing a clear "RC = staging, no SLA, may be wiped" warning.
+ * One-shot at the first `before_agent_start` after register(); never spams
+ * per-turn. A fresh gateway restart re-fires it once.
+ */
+let stagingBannerShown = false;
+
 /**
  * Derive keys from the recovery phrase, load credentials, and register with
  * the server if this is the first run.
@@ -761,7 +777,9 @@ let firstRunWelcomeShown = false;
  * directs the caller to `openclaw totalreclaw onboard`.
  */
 async function initialize(logger: OpenClawPluginApi['logger']): Promise<void> {
-  const serverUrl = CONFIG.serverUrl || 'https://api.totalreclaw.xyz';
+  // 3.3.3-rc.1: staging is the source default per #165. Stable build-time
+  // sed-replace flips `api-staging` -> `api` in dist/.
+  const serverUrl = CONFIG.serverUrl || 'https://api-staging.totalreclaw.xyz';
   let masterPassword = CONFIG.recoveryPhrase;
 
   // 3.2.0: if the env var is unset, probe credentials.json for a
@@ -2967,13 +2985,39 @@ const plugin = {
         api.logger.warn(`TotalReclaw: configureEmbedder failed (will use defaults): ${msg}`);
       }
 
+      // 3.3.3-rc.1 (issue #187 — ONNX decouple): kick off a non-blocking
+      // bundle prefetch so the ~700 MB embedder tarball starts streaming
+      // as soon as the gateway boots, BEFORE the user completes
+      // `totalreclaw_pair`. Decouples the model download from the
+      // pair-completion gate the previous flow imposed via
+      // `requireFullSetup()` -> first `generateEmbedding()` call.
+      // Fire-and-forget — never awaits, never throws on failure (the next
+      // `generateEmbedding()` call retries via the same idempotent path).
+      // Disabled when `TOTALRECLAW_DISABLE_EMBEDDER_PREFETCH=1` (CI / tests
+      // where the network is sandboxed away). The env read lives in
+      // config.ts; we read the resolved CONFIG flag here so this file
+      // stays scanner-clean (no env lookups in index.ts).
+      if (!CONFIG.embedderPrefetchDisabled) {
+        prefetchEmbedderBundle({ log: (msg) => api.logger.info(msg) })
+          .then((result) => {
+            api.logger.info(`TotalReclaw: embedder prefetch ${result === 'fetched' ? 'completed (downloaded bundle)' : 'cache hit'}`);
+          })
+          .catch((err: unknown) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            api.logger.warn(
+              `TotalReclaw: embedder prefetch failed (non-fatal — will retry on first generateEmbedding): ${msg}`,
+            );
+          });
+      }
+
       // 3.3.1-rc.22 (rc.21 finding #5): self-heal partial-install marker.
-      // The `preinstall` npm script writes `.tr-partial-install`; the
-      // `postinstall` script removes it on a successful install. If we
-      // have gotten this far the loader did register us — meaning the
-      // install succeeded enough to be useful — so any lingering marker
-      // (e.g. npm ran preinstall but postinstall misfired) is stale.
-      // Clear it so the next retry's detector does not see a false positive.
+      // The `preinstall` npm script writes `.tr-partial-install`; clearing
+      // it has been the runtime's job since 3.3.3-rc.1 dropped postinstall.mjs
+      // (OpenClaw scanner blocked the install on the subprocess-spawn import
+      // — see 3.3.3-rc.1 PR). If we have gotten this far the loader did
+      // register us — meaning the install succeeded enough to be useful —
+      // so any lingering marker is stale. Clear it so the next retry's
+      // detector does not see a false positive.
       //
       // 3.3.1-rc.22 (rc.21 finding #6) — gateway/reload upstream caveat:
       // OpenClaw's config-watcher fires `gateway/reload` when
@@ -4202,6 +4246,120 @@ const plugin = {
       { name: 'totalreclaw_status' },
     );
 
+    // ---------------------------------------------------------------
+    // Tool: totalreclaw_preload_embedder (3.3.3-rc.1 — issue #187)
+    // ---------------------------------------------------------------
+    //
+    // Decouples the ~700 MB embedder bundle download from the pair-
+    // completion gate. The agent can call this BEFORE
+    // `totalreclaw_pair` to pre-flight disk space, kick off the
+    // download, and surface the completion state. The non-blocking
+    // prefetch in `register()` already starts the download
+    // unconditionally; this tool is an explicit on-demand hook for
+    // agents that want to confirm completion (or trigger a retry on
+    // network failure) without first completing pair.
+    //
+    // Behavior:
+    //   - Disk-space pre-flight: refuses if free disk < 500 MB on the
+    //     embedder cache mount. Surfaces the path + free bytes so the
+    //     user can clear space.
+    //   - Triggers `prefetchEmbedderBundle()` (idempotent — cache hit
+    //     returns immediately).
+    //   - Returns a structured success message with status:
+    //     `cache_hit | fetched | failed`.
+    //
+    // Phrase-safety: this tool does NOT touch credentials.json,
+    // mnemonics, or keys. It only touches `~/.totalreclaw/embedder/`
+    // and the GitHub Releases CDN.
+
+    api.registerTool(
+      {
+        name: 'totalreclaw_preload_embedder',
+        label: 'Preload Embedder',
+        description:
+          'Download the local-embedding model bundle ahead of pair completion. Use this when the user wants to set up TotalReclaw on a slow connection or run an offline-after-setup workflow. Returns success once the ~700 MB bundle is cached at ~/.totalreclaw/embedder/.',
+        parameters: {
+          type: 'object',
+          properties: {},
+          additionalProperties: false,
+        },
+        async execute() {
+          try {
+            // Disk-space pre-flight: refuse if < 500 MB free on the
+            // embedder cache mount. Best-effort — if statfs fails, we
+            // proceed without the pre-flight rather than blocking.
+            const fsModule = await import('node:fs');
+            const cacheRoot = CONFIG.embedderCachePath;
+            const REQUIRED_BYTES = 500 * 1024 * 1024;
+            try {
+              // Find the deepest existing parent so statfs has a real
+              // mount to measure (loadEmbedder will mkdir under it
+              // anyway).
+              let probeDir = cacheRoot;
+              while (true) {
+                try {
+                  fsModule.statSync(probeDir);
+                  break;
+                } catch {
+                  const parent = nodePath.dirname(probeDir);
+                  if (parent === probeDir) break;
+                  probeDir = parent;
+                }
+              }
+              const stats = (fsModule as unknown as {
+                statfsSync?: (p: string) => { bavail: bigint | number; bsize: bigint | number };
+              }).statfsSync?.(probeDir);
+              if (stats) {
+                const bavail = typeof stats.bavail === 'bigint' ? Number(stats.bavail) : stats.bavail;
+                const bsize = typeof stats.bsize === 'bigint' ? Number(stats.bsize) : stats.bsize;
+                const freeBytes = bavail * bsize;
+                if (freeBytes > 0 && freeBytes < REQUIRED_BYTES) {
+                  const freeMb = Math.round(freeBytes / (1024 * 1024));
+                  return {
+                    content: [{
+                      type: 'text',
+                      text: `Insufficient free disk space for embedder bundle. Required: 500 MB. Available at ${probeDir}: ${freeMb} MB. Free up space and retry.`,
+                    }],
+                    details: { status: 'failed', reason: 'disk_space', free_mb: freeMb, required_mb: 500, cache_root: cacheRoot },
+                  };
+                }
+              }
+            } catch {
+              // statfs probe failed — surface a soft warning in logs
+              // but proceed with the download anyway.
+              api.logger.info('totalreclaw_preload_embedder: disk-space probe unavailable, proceeding without pre-flight');
+            }
+
+            // Trigger the prefetch. This is idempotent (cache hit returns
+            // immediately) so it's safe to invoke even when the
+            // background prefetch from register() already completed.
+            const result = await prefetchEmbedderBundle({
+              log: (msg) => api.logger.info(msg),
+            });
+            const human =
+              result === 'fetched'
+                ? `Embedder bundle downloaded and cached at ${cacheRoot}. Subsequent embedding calls run in-memory.`
+                : `Embedder bundle already cached at ${cacheRoot} — no download needed.`;
+            return {
+              content: [{ type: 'text', text: human }],
+              details: { status: result, cache_root: cacheRoot },
+            };
+          } catch (err: unknown) {
+            const message = err instanceof Error ? err.message : String(err);
+            api.logger.error(`totalreclaw_preload_embedder failed: ${message}`);
+            return {
+              content: [{
+                type: 'text',
+                text: `Embedder bundle preload failed: ${humanizeError(message)}. The plugin will retry on first embedding call.`,
+              }],
+              details: { status: 'failed', reason: 'fetch_error', message },
+            };
+          }
+        },
+      },
+      { name: 'totalreclaw_preload_embedder' },
+    );
+
     // ---------------------------------------------------------------
     // Tool: totalreclaw_consolidate
     // ---------------------------------------------------------------
@@ -5672,6 +5830,39 @@ const plugin = {
             return undefined;
           }
 
+          // 3.3.3-rc.1 — RC-staging banner (PR #165 implementation).
+          // Build a one-shot prefix when the bundled default points at staging
+          // AND the user hasn't overridden via env. This prefix is prepended
+          // to whichever context block the rest of the hook produces.
+          let stagingBannerBlock = '';
+          if (!stagingBannerShown) {
+            try {
+              const usingStagingDefault = CONFIG.serverUrl.includes('api-staging.totalreclaw.xyz');
+              const userOverrode = CONFIG.serverUrlEnvOverridden;
+              if (usingStagingDefault && !userOverrode) {
+                stagingBannerBlock =
+                  '## ⚠️ TotalReclaw is running in RC / staging mode\n\n' +
+                  'This build is bound to `api-staging.totalreclaw.xyz`. Staging has **no SLA** ' +
+                  'and may be wiped between QA cycles. Do **NOT** use this build for real data.\n\n' +
+                  'For production, install the stable release: `openclaw plugins install ' +
+                  '@totalreclaw/totalreclaw` (no `@rc` suffix). To pin a custom server, set ' +
+                  '`TOTALRECLAW_SERVER_URL=https://api.totalreclaw.xyz` in your env.\n\n';
+                stagingBannerShown = true;
+                api.logger.warn(
+                  'TotalReclaw: RC/staging build active (api-staging.totalreclaw.xyz). ' +
+                  'See docs/guides/release-process.md for the RC=staging / stable=production rule.',
+                );
+              } else {
+                // Non-RC artifact OR user override — never fire the banner this
+                // gateway-process lifetime.
+                stagingBannerShown = true;
+              }
+            } catch {
+              // Best-effort; never block session start on banner derivation.
+              stagingBannerShown = true;
+            }
+          }
+
           await ensureInitialized(api.logger);
 
           // 3.2.0 onboarding pending: emit a non-secret guidance banner so
@@ -5701,6 +5892,7 @@ const plugin = {
             }
             return {
               prependContext:
+                stagingBannerBlock +
                 welcomeBlock +
                 '## TotalReclaw setup pending\n\n' +
                 'TotalReclaw encrypted memory is installed but not yet set up on this machine. ' +
@@ -5802,6 +5994,7 @@ const plugin = {
                   api.logger.info(`Digest injection: state=${injectResult.state}`);
                   return {
                     prependContext:
+                      stagingBannerBlock +
                       `## Your Memory\n\n${injectResult.promptText}` + welcomeBack + billingWarning,
                   };
                 }
@@ -5848,7 +6041,7 @@ const plugin = {
                 const lines = cachedFacts.slice(0, 8).map((f, i) =>
                   `${i + 1}. ${f.text} (importance: ${f.importance}/10, cached)`,
                 );
-                return { prependContext: `## Relevant Memories\n\n${lines.join('\n')}` + welcomeBack + billingWarning };
+                return { prependContext: stagingBannerBlock + `## Relevant Memories\n\n${lines.join('\n')}` + welcomeBack + billingWarning };
               }
             }
 
@@ -5861,7 +6054,7 @@ const plugin = {
               const lines = cachedFacts.slice(0, 8).map((f, i) =>
                 `${i + 1}. ${f.text} (importance: ${f.importance}/10, cached)`,
               );
-              return { prependContext: `## Relevant Memories\n\n${lines.join('\n')}` + welcomeBack + billingWarning };
+              return { prependContext: stagingBannerBlock + `## Relevant Memories\n\n${lines.join('\n')}` + welcomeBack + billingWarning };
             }
 
             if (allTrapdoors.length === 0) return undefined;
@@ -5878,7 +6071,7 @@ const plugin = {
                 const lines = cachedFacts.slice(0, 8).map((f, i) =>
                   `${i + 1}. ${f.text} (importance: ${f.importance}/10, cached)`,
                 );
-                return { prependContext: `## Relevant Memories\n\n${lines.join('\n')}` + welcomeBack + billingWarning };
+                return { prependContext: stagingBannerBlock + `## Relevant Memories\n\n${lines.join('\n')}` + welcomeBack + billingWarning };
               }
               return undefined;
             }
@@ -5905,7 +6098,7 @@ const plugin = {
               const lines = cachedFacts.slice(0, 8).map((f, i) =>
                 `${i + 1}. ${f.text} (importance: ${f.importance}/10, cached)`,
               );
-              return { prependContext: `## Relevant Memories\n\n${lines.join('\n')}` + welcomeBack + billingWarning };
+              return { prependContext: stagingBannerBlock + `## Relevant Memories\n\n${lines.join('\n')}` + welcomeBack + billingWarning };
             }
 
             // 5. Decrypt subgraph results and build reranker input.
@@ -5995,7 +6188,7 @@ const plugin = {
             });
             const contextString = `## Relevant Memories\n\n${lines.join('\n')}`;
 
-            return { prependContext: contextString + welcomeBack + billingWarning };
+            return { prependContext: stagingBannerBlock + contextString + welcomeBack + billingWarning };
           }
 
           // --- Server mode (existing behavior) ---
@@ -6099,7 +6292,7 @@ const plugin = {
           });
           const contextString = `## Relevant Memories\n\n${lines.join('\n')}`;
 
-          return { prependContext: contextString + welcomeBack + billingWarning };
+          return { prependContext: stagingBannerBlock + contextString + welcomeBack + billingWarning };
         } catch (err: unknown) {
           // The hook must NEVER throw -- log and return undefined.
           const message = err instanceof Error ? err.message : String(err);

package/llm-client.ts

@@ -911,4 +911,11 @@ async function chatCompletionAnthropic(
 // (Harrier-OSS-v1-270M ONNX model). No API key needed. The native deps +
 // model are lazy-fetched from a pinned GitHub Release on first call —
 // see embedding.ts + embedder-loader.ts.
-export { generateEmbedding, getEmbeddingDims, getEmbeddingModelId, configureEmbedder } from './embedding.js';
+export {
+  generateEmbedding,
+  getEmbeddingDims,
+  getEmbeddingModelId,
+  configureEmbedder,
+  // 3.3.3-rc.1 (#187): pre-pair bundle prefetch
+  prefetchEmbedderBundle,
+} from './embedding.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.2",
+  "version": "3.3.3-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": [
@@ -58,21 +58,20 @@
     "README.md",
     "CHANGELOG.md",
     "CLAWHUB.md",
-    "skill.json",
-    "postinstall.mjs"
+    "skill.json"
   ],
   "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 && npx tsx load-manifest.test.ts && npx tsx postinstall-validation.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 url-binding.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",
+    "check-url-binding": "node ../scripts/check-url-binding.mjs",
     "sync-version": "node ../scripts/sync-version.mjs",
     "preinstall": "node -e \"try{require('fs').writeFileSync('.tr-partial-install','');}catch{}\"",
-    "postinstall": "node ./postinstall.mjs",
     "prepack": "npm run build",
-    "prepublishOnly": "node ../scripts/check-scanner.mjs && node ../scripts/check-version-drift.mjs"
+    "prepublishOnly": "node ../scripts/check-scanner.mjs && node ../scripts/check-version-drift.mjs && node ../scripts/check-url-binding.mjs --release-type=${TOTALRECLAW_RELEASE_TYPE:-rc}"
   },
   "openclaw": {
     "extensions": [

package/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "totalreclaw",
-  "version": "3.3.2-rc.4",
+  "version": "3.3.3-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",
@@ -193,8 +193,8 @@
     "config": {
       "serverUrl": {
         "type": "string",
-        "default": "https://api.totalreclaw.xyz",
-        "description": "TotalReclaw server URL (only change for self-hosted mode)"
+        "default": "https://api-staging.totalreclaw.xyz",
+        "description": "TotalReclaw server URL (only change for self-hosted mode). Source default points at staging; stable releases swap to https://api.totalreclaw.xyz at publish time per PR #165."
       },
       "autoExtractEveryTurns": {
         "type": "number",

package/subgraph-store.ts

@@ -805,7 +805,7 @@ export function isSubgraphMode(): boolean {
  *
  * After the v1 env var cleanup, clients only need:
  *   - TOTALRECLAW_RECOVERY_PHRASE -- BIP-39 mnemonic
- *   - TOTALRECLAW_SERVER_URL -- relay server URL (default: https://api.totalreclaw.xyz)
+ *   - TOTALRECLAW_SERVER_URL -- relay server URL (source default: https://api-staging.totalreclaw.xyz; stable build: https://api.totalreclaw.xyz — swapped in at publish time per PR #165)
  *   - TOTALRECLAW_SELF_HOSTED -- set "true" to use self-hosted server (default: managed service)
  *
  * Chain ID is no longer configurable via env — it is auto-detected from the
@@ -813,7 +813,8 @@ export function isSubgraphMode(): boolean {
  */
 export function getSubgraphConfig(): SubgraphStoreConfig {
   return {
-    relayUrl: CONFIG.serverUrl || 'https://api.totalreclaw.xyz',
+    // 3.3.3-rc.1: staging by default in source; stable workflow seds.
+    relayUrl: CONFIG.serverUrl || 'https://api-staging.totalreclaw.xyz',
     mnemonic: CONFIG.recoveryPhrase,
     cachePath: CONFIG.cachePath,
     chainId: CONFIG.chainId,

package/postinstall.mjs

@@ -1,260 +0,0 @@
-// 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');