@totalreclaw/totalreclaw 3.3.2 → 3.3.3-rc.1

package/CHANGELOG.md

@@ -4,6 +4,155 @@ 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).
 
+## [3.3.3-rc.1] — 2026-04-30
+
+Combined RC bundle:
+
+- Fix the OpenClaw runtime-scanner regression that blocked `openclaw plugins
+  install @totalreclaw/totalreclaw` on stable 3.3.2 (Telegram QA, OpenClaw
+  2026.4.22).
+- Implement the codified RC=staging / stable=production environment-binding
+  rule from PR #165.
+- Add a one-shot RC/staging banner so QA testers can't accidentally use an
+  RC build for real data.
+- Decouple the ~700 MB embedder bundle download from the pair-completion
+  gate (issue [#187](https://github.com/p-diogo/totalreclaw-internal/issues/187)).
+- Document the direct-node fallback for inside-gateway agents that hit
+  CLI deadlock (issue [#184](https://github.com/p-diogo/totalreclaw-internal/issues/184)).
+
+### Fixed — OpenClaw scanner blocking install on `child_process` import
+
+User chat QA on stable 3.3.2 hit:
+
+> The plugin install was blocked — OpenClaw flagged it because the plugin's
+> `postinstall.mjs` uses `child_process` (shell execution), which triggers
+> the dangerous-code-pattern safety gate.
+
+Workaround was `--allow-dangerous`. Real fix (this RC): drop `postinstall.mjs`
+entirely. The runtime `register(api)` path already (since 3.3.1-rc.21 / 22)
+sweeps `.openclaw-install-stage-*` siblings AND clears the
+`.tr-partial-install` marker, so the postinstall script was redundant.
+
+- `skill/plugin/postinstall.mjs` deleted.
+- `skill/plugin/postinstall-validation.test.ts` deleted (the script it
+  exercised no longer exists; the runtime equivalents are still covered by
+  `install-staging-cleanup.test.ts` + `partial-install-detection.test.ts` +
+  `install-reload-idempotency.test.ts`).
+- `package.json` no longer declares `scripts.postinstall` and no longer
+  ships `postinstall.mjs` in the `files` array.
+
+Behavior preserved:
+- `preinstall` still writes `.tr-partial-install` (uses `node -e` only — no
+  `child_process` import).
+- The `.tr-partial-install` marker is now cleared exclusively at plugin
+  load time by `register(api)`.
+- `.openclaw-install-stage-*` orphan sweep happens at register() time via
+  `cleanupInstallStagingDirs(pluginDir)`.
+- Critical deps (`@scure/bip39`, `@scure/bip39/wordlists/english.js`,
+  `@totalreclaw/core`, `@totalreclaw/client`, etc.) are imported at module
+  top of `index.ts` — if any is missing, the SDK loader surfaces the
+  import error directly AND the existing `.error.json` write path drops a
+  structured marker (issue #186 in 3.3.2-rc.1). The retry-by-respawn was
+  nice-to-have, not load-bearing.
+
+OpenClaw's runtime scanner (different code path from the plugin's local
+`check-scanner.mjs`) does NOT honor the `// scanner-sim: allow` comment.
+The local scanner's previous guidance ("Moving the subprocess call into a
+separate post-install helper that OpenClaw sandboxes") turned out to be
+incorrect — the runtime scanner inspects the full tarball and flags any
+`child_process` import regardless of file role. The local scanner now has
+nothing to flag because `child_process` no longer appears anywhere in the
+shipped tarball.
+
+### Added — ENV binding implementation (PR #165 codified rule)
+
+| `release-type` | Default `TOTALRECLAW_SERVER_URL` | Audience |
+|---|---|---|
+| `rc` | `https://api-staging.totalreclaw.xyz` | QA only — never point real users here |
+| `stable` | `https://api.totalreclaw.xyz` | Production users |
+
+User env override (`TOTALRECLAW_SERVER_URL=...`) always wins.
+
+Implementation:
+
+- Source-of-truth in `config.ts` / `index.ts` / `subgraph-store.ts` /
+  `skill.json` now references `api-staging.totalreclaw.xyz` everywhere.
+  RC tarballs ship the staging URL by design.
+- Stable publish workflows (`npm-publish.yml` + `publish-clawhub.yml`)
+  add a "Bind stable artifacts to production URLs" step that
+  sed-replaces `api-staging.totalreclaw.xyz` → `api.totalreclaw.xyz`
+  across `dist/**.js`, `skill.json`, and the SKILL.md / CLAWHUB.md /
+  CHANGELOG.md / README.md prose, before pack/publish.
+- New `skill/scripts/check-url-binding.mjs` guard runs at
+  `prepublishOnly` time + as a workflow step. It asserts the right
+  invariant for the resolved release type (RC artifact MUST contain
+  `api-staging.totalreclaw.xyz`; stable artifact MUST contain
+  `api.totalreclaw.xyz` AND ZERO staging references). Misconfigured
+  artifacts fail the publish before reaching the registry.
+- `prepublishOnly` reads `TOTALRECLAW_RELEASE_TYPE=stable|rc` (default
+  `rc` for safety) so local `npm publish` invocations also assert the
+  invariant.
+- New `url-binding.test.ts` regression covers both modes against a
+  synthetic artifact tree.
+
+### Added — RC/staging banner (one-shot per gateway process)
+
+When the bundled `serverUrl` resolves to `api-staging.totalreclaw.xyz`
+AND the user has not overridden via env, the plugin emits a prominent
+prependContext banner on the first non-trivial `before_agent_start`:
+
+> ⚠️ TotalReclaw is running in RC / staging mode
+>
+> 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.
+>
+> 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.
+
+Stable artifacts (where the workflow seded the URL to production) never
+fire the banner. Per-process one-shot semantics — restart re-fires once.
+
+### Added — `totalreclaw_preload_embedder` tool + non-blocking prefetch (issue #187)
+
+- New tool: `totalreclaw_preload_embedder` lets the agent download the
+  embedder bundle ahead of `totalreclaw_pair`. Includes a 500 MB
+  disk-space pre-flight (refuses if the cache mount is below threshold)
+  and surfaces a structured `{ status: cache_hit | fetched | failed }`
+  response.
+- Register-time non-blocking prefetch: `register(api)` now fires
+  `prefetchEmbedderBundle()` as a fire-and-forget Promise immediately
+  after `configureEmbedder()`. The bundle download starts on gateway
+  boot, BEFORE the user completes pair — closing the catch-22 where the
+  bundle was only fetched on the first `generateEmbedding()` call (which
+  is gated behind `requireFullSetup()`).
+- Toggle: `TOTALRECLAW_DISABLE_EMBEDDER_PREFETCH=1` skips the auto-prefetch
+  (CI / sandboxed-network environments). The next `generateEmbedding()`
+  call still triggers the download via the same idempotent path.
+
+### Documentation — direct-node fallback for CLI deadlock (issue #184)
+
+- `docs/guides/openclaw-setup.md` Troubleshooting now documents the
+  filesystem-manifest probe (`.loaded.json` / `.error.json`) and the
+  `node ~/.openclaw/extensions/totalreclaw/dist/pair-cli.js
+  --url-pin-only` direct-node fallback for when the `openclaw` CLI
+  deadlocks (exit 124) inside gateway-internal agent shells.
+- `skill/SKILL.md` mirrors the same fallbacks for the agent's own
+  instructions: prefer reading the `.loaded.json` manifest over
+  re-running `openclaw plugins list`; switch to direct-node `pair-cli.js`
+  when `totalreclaw_pair` itself hangs.
+
+### Known issues filed during this RC
+
+Five new observation issues filed via the QA pipeline (severity:minor,
+not blockers for 3.3.3-rc.1 promote):
+- [#208](https://github.com/p-diogo/totalreclaw-internal/issues/208) — Hermes auto-extraction burst pattern can trip per-model rate limits
+- [#209](https://github.com/p-diogo/totalreclaw-internal/issues/209) — `HERMES_MODEL` env swap doesn't propagate to running daemon
+- [#210](https://github.com/p-diogo/totalreclaw-internal/issues/210) — Hermes Docker venv ships without pip
+- [#211](https://github.com/p-diogo/totalreclaw-internal/issues/211) — ClawHub artifact's `package.json` retains rc-version label after stable promote
+- [#212](https://github.com/p-diogo/totalreclaw-internal/issues/212) — `wipe-qa.sh` model-pin step appends duplicate `HERMES_MODEL` lines
+
 ## [3.3.2-rc.1] — 2026-04-27
 
 Hotfix bundle for the inside-gateway agent-flow ship-stoppers caught by the

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: totalreclaw
 description: "Install + set up TotalReclaw encrypted memory for OpenClaw, then use totalreclaw_remember / totalreclaw_recall. Trigger on 'install TotalReclaw', 'set up TotalReclaw', 'restore my recovery phrase', or any remember / recall request."
-version: 3.3.2-rc.4
+version: 3.3.3-rc.1
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz

package/config.ts

@@ -138,7 +138,15 @@ export const CONFIG = {
   get sessionId(): string | null {
     return getSessionId();
   },
-  serverUrl: (process.env.TOTALRECLAW_SERVER_URL || 'https://api.totalreclaw.xyz').replace(/\/+$/, ''),
+  // 3.3.3-rc.1: source default is `api-staging.totalreclaw.xyz` per the
+  // codified RC=staging / stable=production rule (PR #165). The workflow
+  // step "Bind stable to production URLs" in `npm-publish.yml` /
+  // `publish-clawhub.yml` sed-replaces `api-staging.totalreclaw.xyz` ->
+  // `api.totalreclaw.xyz` across the built `dist/` tree (and skill.json /
+  // SKILL.md / CHANGELOG / CLAWHUB.md / package.json) when
+  // `release-type=stable`. RC publishes leave the staging URL untouched.
+  // User overrides via `TOTALRECLAW_SERVER_URL=...` always win.
+  serverUrl: (process.env.TOTALRECLAW_SERVER_URL || 'https://api-staging.totalreclaw.xyz').replace(/\/+$/, ''),
   selfHosted: process.env.TOTALRECLAW_SELF_HOSTED === 'true',
   credentialsPath: process.env.TOTALRECLAW_CREDENTIALS_PATH || path.join(home, '.totalreclaw', 'credentials.json'),
   // 3.2.0 onboarding state file — separate from credentials.json so it
@@ -184,6 +192,21 @@ export const CONFIG = {
   entryPointAddress: process.env.TOTALRECLAW_ENTRYPOINT_ADDRESS || '',
   rpcUrl: process.env.TOTALRECLAW_RPC_URL || '',
 
+  // 3.3.3-rc.1 (issue #187 — ONNX decouple): kill switch for the
+  // non-blocking embedder bundle prefetch fired from register(). Set to
+  // `1` in CI / sandboxed environments where the GitHub-Releases CDN is
+  // unreachable. The next call to generateEmbedding() still triggers the
+  // download via the same idempotent path.
+  embedderPrefetchDisabled: process.env.TOTALRECLAW_DISABLE_EMBEDDER_PREFETCH === '1',
+
+  // 3.3.3-rc.1 (PR #165 implementation): observable form of "did the user
+  // explicitly override the bundled-default server URL via env?". Used
+  // by the RC-staging banner check in index.ts so the banner suppresses
+  // when the user has pinned a custom URL (production or self-hosted).
+  // Lives here so index.ts stays free of process.env reads (scanner
+  // env-harvesting rule).
+  serverUrlEnvOverridden: !!process.env.TOTALRECLAW_SERVER_URL,
+
   // Tuning knobs — default values used only as local fallback for
   // self-hosted mode. Managed-service clients override these from the relay
   // billing response via `resolveTuning(...)`.

package/dist/config.js

@@ -123,7 +123,15 @@ export const CONFIG = {
     get sessionId() {
         return getSessionId();
     },
-    serverUrl: (process.env.TOTALRECLAW_SERVER_URL || 'https://api.totalreclaw.xyz').replace(/\/+$/, ''),
+    // 3.3.3-rc.1: source default is `api-staging.totalreclaw.xyz` per the
+    // codified RC=staging / stable=production rule (PR #165). The workflow
+    // step "Bind stable to production URLs" in `npm-publish.yml` /
+    // `publish-clawhub.yml` sed-replaces `api-staging.totalreclaw.xyz` ->
+    // `api.totalreclaw.xyz` across the built `dist/` tree (and skill.json /
+    // SKILL.md / CHANGELOG / CLAWHUB.md / package.json) when
+    // `release-type=stable`. RC publishes leave the staging URL untouched.
+    // User overrides via `TOTALRECLAW_SERVER_URL=...` always win.
+    serverUrl: (process.env.TOTALRECLAW_SERVER_URL || 'https://api-staging.totalreclaw.xyz').replace(/\/+$/, ''),
     selfHosted: process.env.TOTALRECLAW_SELF_HOSTED === 'true',
     credentialsPath: process.env.TOTALRECLAW_CREDENTIALS_PATH || path.join(home, '.totalreclaw', 'credentials.json'),
     // 3.2.0 onboarding state file — separate from credentials.json so it
@@ -166,6 +174,19 @@ export const CONFIG = {
     dataEdgeAddress: process.env.TOTALRECLAW_DATA_EDGE_ADDRESS || '',
     entryPointAddress: process.env.TOTALRECLAW_ENTRYPOINT_ADDRESS || '',
     rpcUrl: process.env.TOTALRECLAW_RPC_URL || '',
+    // 3.3.3-rc.1 (issue #187 — ONNX decouple): kill switch for the
+    // non-blocking embedder bundle prefetch fired from register(). Set to
+    // `1` in CI / sandboxed environments where the GitHub-Releases CDN is
+    // unreachable. The next call to generateEmbedding() still triggers the
+    // download via the same idempotent path.
+    embedderPrefetchDisabled: process.env.TOTALRECLAW_DISABLE_EMBEDDER_PREFETCH === '1',
+    // 3.3.3-rc.1 (PR #165 implementation): observable form of "did the user
+    // explicitly override the bundled-default server URL via env?". Used
+    // by the RC-staging banner check in index.ts so the banner suppresses
+    // when the user has pinned a custom URL (production or self-hosted).
+    // Lives here so index.ts stays free of process.env reads (scanner
+    // env-harvesting rule).
+    serverUrlEnvOverridden: !!process.env.TOTALRECLAW_SERVER_URL,
     // Tuning knobs — default values used only as local fallback for
     // self-hosted mode. Managed-service clients override these from the relay
     // billing response via `resolveTuning(...)`.

package/dist/embedding.js

@@ -58,6 +58,30 @@ function activeRuntimeConfig() {
         return runtimeConfig;
     return { cacheRoot: defaultCacheRoot(), rcTag: '0.0.0-dev' };
 }
+/**
+ * 3.3.3-rc.1 (issue #187 — ONNX decouple): prefetch the embedder bundle
+ * WITHOUT loading the model into memory. Used to download the
+ * ~700 MB tarball pre-pair so the user does not hit the network round-trip
+ * mid-conversation. Idempotent — subsequent calls are cache-hit no-ops.
+ *
+ * Returns:
+ *   - `'cache_hit'` if the bundle was already extracted + verified.
+ *   - `'fetched'` if the bundle was downloaded this call.
+ *   - throws on transport / extraction failure.
+ *
+ * Pre-flight is the caller's job (disk-space, network reachability) — this
+ * function focuses on the cache-resolve + fetch-on-miss path so it can also
+ * be reused as a fast cache-validation probe.
+ */
+export async function prefetchEmbedderBundle(opts) {
+    const cfg = activeRuntimeConfig();
+    const loaded = await loadEmbedder({
+        cacheRoot: cfg.cacheRoot,
+        rcTag: cfg.rcTag,
+        log: opts?.log,
+    });
+    return loaded.wasFetched ? 'fetched' : 'cache_hit';
+}
 /** Lazily initialized state. */
 let pipelineExtractor = null;
 let autoTokenizer = null;

package/dist/index.js

@@ -48,7 +48,7 @@
 import { deriveKeys, deriveLshSeed, computeAuthKeyHash, encrypt, decrypt, generateBlindIndices, generateContentFingerprint, } from './crypto.js';
 import { createApiClient } from './api-client.js';
 import { extractFacts, extractDebrief, isValidMemoryType, parseEntity, VALID_MEMORY_TYPES, LEGACY_V0_MEMORY_TYPES, VALID_MEMORY_SOURCES, VALID_MEMORY_SCOPES, EXTRACTION_SYSTEM_PROMPT, extractFactsForCompaction, } from './extractor.js';
-import { initLLMClient, resolveLLMConfig, chatCompletion, generateEmbedding, getEmbeddingDims, getEmbeddingModelId, configureEmbedder, } from './llm-client.js';
+import { initLLMClient, resolveLLMConfig, chatCompletion, generateEmbedding, getEmbeddingDims, getEmbeddingModelId, configureEmbedder, prefetchEmbedderBundle, } from './llm-client.js';
 import { defaultAuthProfilesRoot, readAllProfileKeys, dedupeByProvider, } from './llm-profile-reader.js';
 import { LSHHasher } from './lsh.js';
 import { rerank, cosineSimilarity, detectQueryIntent, INTENT_WEIGHTS } from './reranker.js';
@@ -501,6 +501,20 @@ let firstRunAfterInit = true;
  * skips. A fresh gateway restart resets it back to `false`.
  */
 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.
@@ -514,7 +528,9 @@ let firstRunWelcomeShown = false;
  * directs the caller to `openclaw totalreclaw onboard`.
  */
 async function initialize(logger) {
-    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
     // pre-existing mnemonic (written either by the CLI wizard on this machine
@@ -2407,13 +2423,36 @@ const plugin = {
                     const msg = err instanceof Error ? err.message : String(err);
                     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) => {
+                        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
@@ -3509,6 +3548,114 @@ 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.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) {
+                        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
             // ---------------------------------------------------------------
             api.registerTool({
@@ -4840,6 +4987,38 @@ const plugin = {
                     if (!evt?.prompt || evt.prompt.length < 5) {
                         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
                     // the LLM knows how to respond when the user asks about setup.
@@ -4868,7 +5047,8 @@ const plugin = {
                             api.logger.warn(`First-run welcome check failed: ${msg}`);
                         }
                         return {
-                            prependContext: welcomeBlock +
+                            prependContext: stagingBannerBlock +
+                                welcomeBlock +
                                 '## TotalReclaw setup pending\n\n' +
                                 'TotalReclaw encrypted memory is installed but not yet set up on this machine. ' +
                                 'If the user asks about memory features or wants to configure TotalReclaw, ' +
@@ -4966,7 +5146,8 @@ const plugin = {
                                 if (injectResult.promptText) {
                                     api.logger.info(`Digest injection: state=${injectResult.state}`);
                                     return {
-                                        prependContext: `## Your Memory\n\n${injectResult.promptText}` + welcomeBack + billingWarning,
+                                        prependContext: stagingBannerBlock +
+                                            `## Your Memory\n\n${injectResult.promptText}` + welcomeBack + billingWarning,
                                     };
                                 }
                             }
@@ -5007,7 +5188,7 @@ const plugin = {
                             const querySimilarity = cosineSimilarity(queryEmbedding, lastQueryEmbedding);
                             if (querySimilarity > SEMANTIC_SKIP_THRESHOLD) {
                                 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 };
                             }
                         }
                         // 3. Merge trapdoors — always include word trapdoors for small-dataset coverage.
@@ -5016,7 +5197,7 @@ const plugin = {
                         // If we have cached facts and no trapdoors, return cached facts.
                         if (allTrapdoors.length === 0 && cachedFacts.length > 0) {
                             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;
@@ -5031,7 +5212,7 @@ const plugin = {
                             // Subgraph query failed -- fall back to cached facts if available.
                             if (cachedFacts.length > 0) {
                                 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;
                         }
@@ -5055,7 +5236,7 @@ const plugin = {
                         // If subgraph returned no results but we have cache, use cache.
                         if (subgraphResults.length === 0) {
                             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.
                         const rerankerCandidates = [];
@@ -5130,7 +5311,7 @@ const plugin = {
                             return `${i + 1}. ${typeTag}${m.text} (importance: ${importance}/10, ${age})`;
                         });
                         const contextString = `## Relevant Memories\n\n${lines.join('\n')}`;
-                        return { prependContext: contextString + welcomeBack + billingWarning };
+                        return { prependContext: stagingBannerBlock + contextString + welcomeBack + billingWarning };
                     }
                     // --- Server mode (existing behavior) ---
                     // 1. Generate word trapdoors from the user prompt.
@@ -5212,7 +5393,7 @@ const plugin = {
                         return `${i + 1}. ${m.text} (importance: ${importance}/10, ${age})`;
                     });
                     const contextString = `## Relevant Memories\n\n${lines.join('\n')}`;
-                    return { prependContext: contextString + welcomeBack + billingWarning };
+                    return { prependContext: stagingBannerBlock + contextString + welcomeBack + billingWarning };
                 }
                 catch (err) {
                     // The hook must NEVER throw -- log and return undefined.

package/dist/llm-client.js

@@ -684,4 +684,6 @@ async function chatCompletionAnthropic(config, messages, maxTokens, temperature,
 // (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/dist/subgraph-store.js

@@ -675,7 +675,7 @@ export function isSubgraphMode() {
  *
  * 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
@@ -683,7 +683,8 @@ export function isSubgraphMode() {
  */
 export function getSubgraphConfig() {
     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/embedding.ts

@@ -91,6 +91,31 @@ function activeRuntimeConfig(): EmbedderRuntimeConfig {
   return { cacheRoot: defaultCacheRoot(), rcTag: '0.0.0-dev' };
 }
 
+/**
+ * 3.3.3-rc.1 (issue #187 — ONNX decouple): prefetch the embedder bundle
+ * WITHOUT loading the model into memory. Used to download the
+ * ~700 MB tarball pre-pair so the user does not hit the network round-trip
+ * mid-conversation. Idempotent — subsequent calls are cache-hit no-ops.
+ *
+ * Returns:
+ *   - `'cache_hit'` if the bundle was already extracted + verified.
+ *   - `'fetched'` if the bundle was downloaded this call.
+ *   - throws on transport / extraction failure.
+ *
+ * Pre-flight is the caller's job (disk-space, network reachability) — this
+ * function focuses on the cache-resolve + fetch-on-miss path so it can also
+ * be reused as a fast cache-validation probe.
+ */
+export async function prefetchEmbedderBundle(opts?: { log?: (msg: string) => void }): Promise<'cache_hit' | 'fetched'> {
+  const cfg = activeRuntimeConfig();
+  const loaded = await loadEmbedder({
+    cacheRoot: cfg.cacheRoot,
+    rcTag: cfg.rcTag,
+    log: opts?.log,
+  });
+  return loaded.wasFetched ? 'fetched' : 'cache_hit';
+}
+
 /** Lazily initialized state. */
 let pipelineExtractor: any = null;
 let autoTokenizer: any = null;