@totalreclaw/totalreclaw 3.3.3-rc.1 → 3.3.4-rc.2

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.3-rc.1
+version: 3.3.4-rc.2
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -30,16 +30,28 @@ metadata:
 
 If `totalreclaw_*` tools are already bound to your toolset, SKIP install and jump to step 4. Otherwise run all steps in order.
 
-1. **Install skill + plugin.** Run via your shell tool, in this order:
+1. **Install plugin first, skill second.** Run via your shell tool, in this exact order:
    ```
-   openclaw skills install totalreclaw
    openclaw plugins install @totalreclaw/totalreclaw
+   openclaw skills install totalreclaw
    ```
-   For RC: replace the second command with `openclaw plugins install @totalreclaw/totalreclaw@rc`. If either shell call fails with `command not found` / ENOENT / "not authorized" (managed-service or shell-restricted environment), tell the user verbatim *"Your environment doesn't expose the OpenClaw CLI to me. Please install `totalreclaw` from your service's plugins / skills UI, then reply `done`."* Wait for `done` and skip to step 3.
+   For RC: replace the first command with `openclaw plugins install @totalreclaw/totalreclaw@rc`. **Plugin BEFORE skill is deliberate** (3.3.4-rc.1 — issue from Pedro's QA on rc.3): the skill install triggers a config-driven SIGUSR1 gateway reload that can race a concurrent plugin install. Plugin-first lets the plugin land cleanly, then the skill's reload picks it up on the next gateway loop. If you accidentally do skill-first and the plugin install dies mid-flight, just retry `openclaw plugins install @totalreclaw/totalreclaw` once — it's idempotent.
+
+   If either shell call fails with `command not found` / ENOENT / "not authorized" (managed-service or shell-restricted environment), tell the user verbatim *"Your environment doesn't expose the OpenClaw CLI to me. Please install `totalreclaw` from your service's plugins / skills UI, then reply `done`."* Wait for `done` and skip to step 3.
+
+2. **Wait for auto-reload — then issue `/restart` autonomously if needed.** OpenClaw's default config (`gateway.reload.mode = "hybrid"`) auto-restarts the gateway via a file-watcher within 1-3 seconds. Wait ~5s, then run `openclaw plugins list | grep totalreclaw` and confirm `totalreclaw_pair` is in your toolset.
+
+   **If `totalreclaw_pair` is NOT visible after 10s:** issue OpenClaw's built-in `/restart` slash-command immediately and silently. **DO NOT ask the user "should I restart" / "do you want me to restart" / "let me check if the tool is bound" — just issue `/restart` and announce "Reloading gateway..." once.** This is in-process and drains active runs cleanly; your shell is NOT shelling out to `docker restart` or `openclaw gateway restart` (which would suicide the host). After `/restart`, wait ~3s and re-run `openclaw plugins list`.
+
+   **If `/restart` returns "You are not authorized to use this command":** the gateway's `channels.<your-channel>.allowFrom` allowlist is empty. **Do NOT keep retrying.** Surface this one-line user-facing fix and stop:
+
+   > Your channel needs to be allowlisted for slash commands. Run on the gateway host: `jq '.channels.<channel>.allowFrom = ["<your-id>"]' ~/.openclaw/openclaw.json | sponge ~/.openclaw/openclaw.json && docker restart <your-container-name>` (Docker self-host) — substitute `<channel>` with your channel name (e.g. `telegram`, `slack`), `<your-id>` with your user ID for that channel (Telegram: `@username` or numeric `chat_id`; Slack: workspace member ID), and `<your-container-name>` with your gateway container name (`docker ps` shows it). On a managed service, ask the service's support to enable slash commands for your channel. Reply `done` once it's back up.
+
+   For non-Docker / native deployments substitute `openclaw gateway restart` for the `docker restart` portion. As a session-level fallback while restart is gated, try `/new` (starts a fresh session within the same gateway process, may pick up freshly-bound tools without a full restart).
 
-2. **Wait for auto-reload — do NOT restart the gateway yourself.** OpenClaw's default config (`gateway.reload.mode = "hybrid"`) auto-restarts the gateway via a file-watcher within 1-3 seconds. Wait ~5s, then run `openclaw plugins list | grep totalreclaw` and confirm `totalreclaw_pair` is in your toolset. If it does NOT appear within 10s, the user has `gateway.reload.mode = off` — fall back: tell the user verbatim *"Auto-reload didn't fire. Please restart your OpenClaw gateway: `openclaw gateway restart` (native), `docker restart <your-container-name>` (Docker self-host — substitute the actual name; `docker ps` shows it), or your managed service's restart control. Reply `done` once it's back up."* Do NOT invoke the restart yourself — your shell is running inside the gateway you'd be restarting (catch-22). Wait for the user's `done`.
+   **Forbidden vocabulary** (these are anti-patterns when a tool is missing post-install): "Should I /restart", "Do you have a public URL", "Want me to restart", "Let me check if the tool is bound", "I need permission to restart". Just issue `/restart` immediately and announce.
 
-3. **Verify `totalreclaw_pair` is bound.** If still missing after the user said `done`, tell them the restart didn't take effect and to retry. Do not loop the install.
+3. **Verify `totalreclaw_pair` is bound.** If still missing after `/restart` (or after the user fixed allowFrom and said `done`), tell them the restart didn't take effect and ask them to retry. Do not loop the install.
 
 4. **Check for existing credentials.** Run `test -s ~/.totalreclaw/credentials.json`. If it exists and is non-empty, confirm *"TotalReclaw is already set up."* and stop.
 

package/dist/embedding.js

@@ -53,10 +53,26 @@ export function configureEmbedder(cfg) {
 function defaultCacheRoot() {
     return path.join(os.homedir(), '.totalreclaw', 'embedder');
 }
+/**
+ * Last-known-good embedder bundle tag. Used ONLY as a hard-fallback when
+ * `configureEmbedder()` is never called by the orchestrator (defensive
+ * path — production code always wires it via index.ts register()).
+ *
+ * 3.3.4-rc.1 — pinned to v3.3.3-rc.1 because that is the most recent
+ * release at fix-time with a published `embedder-v1.tar.gz` asset. Earlier
+ * fallback `'0.0.0-dev'` (rc.22 → 3.3.3-rc.1) hard-coded a placeholder
+ * that resolved to a 404 GitHub Release URL; QA on 3.3.3-rc.1 (Pedro
+ * 2026-04-30) caught it because the cascade-cause (broken
+ * `readPluginVersion()` resolution) made the fallback fire on every cold
+ * start. Bumping this constant per RC is fine — the publish workflow auto-
+ * publishes the bundle for every RC tag (see scripts/build-embedder-
+ * bundle.mjs in the public repo).
+ */
+const LAST_KNOWN_GOOD_RC_TAG = '3.3.3-rc.1';
 function activeRuntimeConfig() {
     if (runtimeConfig)
         return runtimeConfig;
-    return { cacheRoot: defaultCacheRoot(), rcTag: '0.0.0-dev' };
+    return { cacheRoot: defaultCacheRoot(), rcTag: LAST_KNOWN_GOOD_RC_TAG };
 }
 /**
  * 3.3.3-rc.1 (issue #187 — ONNX decouple): prefetch the embedder bundle

package/dist/fs-helpers.js

@@ -74,9 +74,17 @@ export function ensureMemoryHeaderFile(workspace, header, markerSubstring = 'Tot
  * Read the plugin's own version string from `package.json`.
  *
  * Behaviour:
- *   - Resolves `package.json` next to the caller-provided directory
+ *   - Tries `package.json` next to the caller-provided directory first
  *     (typically `path.dirname(fileURLToPath(import.meta.url))` from the
- *     caller).
+ *     caller — i.e., the directory of the running ESM module).
+ *   - If that misses, walks up to 5 parent directories looking for a
+ *     `package.json` whose `name` is `@totalreclaw/totalreclaw`. This
+ *     covers the OpenClaw plugin sandbox case where the loaded module
+ *     lives at `<pluginRoot>/dist/index.js` while `package.json` lives
+ *     at `<pluginRoot>/package.json` (3.3.4-rc.1 fix — without this
+ *     walk-up, the `.loaded.json` manifest gets `version=unknown` and
+ *     all RC-gated logic that depends on the version string fails
+ *     silently in production OpenClaw deployments).
  *   - Returns the `version` field, or `null` on any I/O / parse error.
  *
  * Used by the RC-gated `totalreclaw_report_qa_bug` tool registration in
@@ -87,13 +95,51 @@ export function ensureMemoryHeaderFile(workspace, header, markerSubstring = 'Tot
  * helper — see the file-header guardrail.
  */
 export function readPluginVersion(packageJsonDir) {
+    // Direct hit (source-tree dev path; tests).
+    const direct = tryReadPluginPackageJson(path.join(packageJsonDir, 'package.json'));
+    if (direct)
+        return direct;
+    // Walk up — the running ESM module typically lives at
+    // `<pluginRoot>/dist/index.js`, so `packageJsonDir` is `<pluginRoot>/dist`
+    // and `package.json` is one level up. Bound the walk so a misconfigured
+    // path doesn't traverse the entire filesystem; 5 levels is more than
+    // enough for any realistic plugin layout (dist/, dist/cjs/, build/lib/).
+    let current = packageJsonDir;
+    for (let depth = 0; depth < 5; depth++) {
+        const parent = path.dirname(current);
+        if (parent === current)
+            break; // root reached
+        const candidate = path.join(parent, 'package.json');
+        const version = tryReadPluginPackageJson(candidate);
+        if (version)
+            return version;
+        current = parent;
+    }
+    return null;
+}
+/**
+ * Try to read `package.json` at `pkgPath`. Returns the `version` only if
+ * the file's `name` field matches `@totalreclaw/totalreclaw` — guards
+ * against accidentally returning the version of an outer host-package
+ * (e.g. when the plugin is bundled inside a parent app's tree).
+ *
+ * If `name` is absent (legacy / minimal package.json), accept the version
+ * anyway as a fallback — this is the existing behaviour preserved for
+ * anyone who manually trimmed their package.json.
+ */
+function tryReadPluginPackageJson(pkgPath) {
     try {
-        const pkgPath = path.join(packageJsonDir, 'package.json');
         if (!fs.existsSync(pkgPath))
             return null;
         const raw = fs.readFileSync(pkgPath, 'utf-8');
         const parsed = JSON.parse(raw);
-        return typeof parsed.version === 'string' ? parsed.version : null;
+        if (typeof parsed.version !== 'string')
+            return null;
+        if (typeof parsed.name === 'string' && parsed.name !== '@totalreclaw/totalreclaw') {
+            // Wrong package — keep walking.
+            return null;
+        }
+        return parsed.version;
     }
     catch {
         return null;

package/dist/index.js

@@ -511,10 +511,26 @@ let firstRunWelcomeShown = false;
  *
  * 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.
+ * One-shot at the first `before_agent_start` whose `prependContext` actually
+ * lands on the LLM (3.3.4-rc.1 — see fix below). A fresh gateway restart
+ * re-fires it once.
+ *
+ * 3.3.4-rc.1 fix: through 3.3.3-rc.1 this flag was set to true as soon as
+ * the banner BLOCK was built — but multiple hook return paths returned
+ * `undefined` (zero-match cases), so the banner block was silently dropped
+ * AND the flag was flipped, suppressing all subsequent attempts. Now the
+ * flag flips ONLY when a return path actually includes the block in its
+ * `prependContext`, via the `markBannerDelivered()` closure.
  */
 let stagingBannerShown = false;
+/**
+ * 3.3.4-rc.1 — operator-facing "this is an RC build" log fires once per
+ * gateway process, independent of whether the user-facing banner has
+ * been delivered yet. Without this split, the warn-log was tied to the
+ * same flag as the user-facing banner and got dropped together when
+ * the hook returned `undefined`.
+ */
+let stagingBannerLogged = false;
 /**
  * Derive keys from the recovery phrase, load credentials, and register with
  * the server if this is the first run.
@@ -2410,18 +2426,32 @@ const plugin = {
                 }
                 // 3.3.1-rc.22 — wire the lazy-embedder runtime config so the first
                 // `generateEmbedding()` call knows where to cache the bundle and
-                // which RC's GitHub Release to fetch from. `pluginVersion` may be
-                // `null` if package.json is unreadable; the embedder defaults to
-                // a "0.0.0-dev" tag in that case.
-                try {
-                    configureEmbedder({
-                        cacheRoot: CONFIG.embedderCachePath,
-                        rcTag: pluginVersion ?? '0.0.0-dev',
-                    });
+                // which RC's GitHub Release to fetch from.
+                //
+                // 3.3.4-rc.1 — when readPluginVersion() returns null (rare, but
+                // possible if package.json is unreadable inside the OpenClaw
+                // sandbox), we previously passed the literal `'0.0.0-dev'` which
+                // resolves to a 404 GitHub Release URL. Now we let `embedding.ts`
+                // fall back to its `LAST_KNOWN_GOOD_RC_TAG` constant by SKIPPING
+                // the configure call entirely in the null case — the
+                // `activeRuntimeConfig()` helper picks the constant up. This way
+                // the constant lives in one place (embedding.ts) and the orch-
+                // estrator just doesn't fight it.
+                if (pluginVersion) {
+                    try {
+                        configureEmbedder({
+                            cacheRoot: CONFIG.embedderCachePath,
+                            rcTag: pluginVersion,
+                        });
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        api.logger.warn(`TotalReclaw: configureEmbedder failed (will use defaults): ${msg}`);
+                    }
                 }
-                catch (err) {
-                    const msg = err instanceof Error ? err.message : String(err);
-                    api.logger.warn(`TotalReclaw: configureEmbedder failed (will use defaults): ${msg}`);
+                else {
+                    api.logger.warn('TotalReclaw: pluginVersion unresolved — embedder will fall back to LAST_KNOWN_GOOD_RC_TAG. ' +
+                        'Investigate package.json resolution; see fs-helpers.readPluginVersion docs.');
                 }
                 // 3.3.3-rc.1 (issue #187 — ONNX decouple): kick off a non-blocking
                 // bundle prefetch so the ~700 MB embedder tarball starts streaming
@@ -2576,11 +2606,36 @@ const plugin = {
                     });
                     // 3.3.0 — `openclaw totalreclaw pair [generate|import]` attaches
                     // alongside the existing `onboard` + `status` subcommands.
+                    //
+                    // 3.3.4-rc.1 — wire `runRelayPairCli` so the CLI defaults to the
+                    // same relay-brokered URL surface the agent tool uses. The local
+                    // (gateway-loopback) flow is still available via `--local`. See
+                    // pair-cli.ts header for the rationale.
                     const { registerPairCli } = await import('./pair-cli.js');
                     registerPairCli(program, {
                         sessionsPath: CONFIG.pairSessionsPath,
                         renderPairingUrl: (session) => buildPairingUrl(api, session),
                         logger: api.logger,
+                        runRelayPairCli: async (cliMode, runOpts) => {
+                            const { runRelayPairCli } = await import('./pair-cli-relay.js');
+                            return runRelayPairCli(cliMode, {
+                                relayBaseUrl: CONFIG.pairRelayUrl,
+                                credentialsPath: CREDENTIALS_PATH,
+                                onboardingStatePath: CONFIG.onboardingStatePath,
+                                logger: api.logger,
+                                pluginVersion: pluginVersion ?? '3.3.4-rc.1',
+                                deriveScopeAddress: async (mnemonic) => {
+                                    try {
+                                        return await deriveSmartAccountAddress(mnemonic, CONFIG.chainId);
+                                    }
+                                    catch (err) {
+                                        api.logger.warn(`relay pair-cli: scope-address derivation failed (will retry lazily): ${err instanceof Error ? err.message : String(err)}`);
+                                        return undefined;
+                                    }
+                                },
+                                ...runOpts,
+                            });
+                        },
                     });
                 }, { commands: ['totalreclaw'] });
             }
@@ -4631,9 +4686,23 @@ const plugin = {
                             // Background task — writes credentials.json + flips state when
                             // the browser completes the flow. Tool handler returns
                             // immediately so the agent can tell the user the URL + PIN.
+                            //
+                            // 3.3.4-rc.2 (Pedro QA — pair flow stuck-session) — wrap the
+                            // WS-await in a 60s hard timeout. The relay drops sessions on
+                            // `ws_close` (separately patched relay-side); without this
+                            // bound the background task hangs in `waitNextMessage` for the
+                            // full 5-minute session TTL before resolving, and downstream
+                            // tooling that polls the gateway for completion sees stale
+                            // `processing` state at 129s/159s/189s. 60s is the user-side
+                            // deadline we surface in chat: long enough for a slow scan-
+                            // and-paste, short enough that a fresh URL request is the
+                            // obvious next step. Structured `timed_out` error in the log
+                            // lets ops grep for the failure mode independently of generic
+                            // ws-close errors.
+                            const PAIR_TOOL_HARD_TIMEOUT_MS = 60_000;
                             void (async () => {
                                 try {
-                                    await awaitPhraseUpload(remoteSession, {
+                                    const phraseUploadPromise = awaitPhraseUpload(remoteSession, {
                                         phraseValidator: (p) => validateMnemonic(p, wordlist),
                                         completePairing: async ({ mnemonic }) => {
                                             try {
@@ -4673,7 +4742,37 @@ const plugin = {
                                                 return { state: 'error', error: msg };
                                             }
                                         },
+                                        // 3.3.4-rc.2 — also pass through to awaitPhraseUpload so its
+                                        // internal `waitNextMessage` timer matches the outer race.
+                                        timeoutMs: PAIR_TOOL_HARD_TIMEOUT_MS,
+                                    });
+                                    // 3.3.4-rc.2 — outer Promise.race guard. Resolves to a
+                                    // sentinel ({ status: 'timed_out', ... }) so the catch
+                                    // handler can distinguish a hard-timeout from a generic
+                                    // ws-close error and surface it explicitly.
+                                    const TIMEOUT_SENTINEL = {
+                                        status: 'timed_out',
+                                        message: `Pair flow timed out (${PAIR_TOOL_HARD_TIMEOUT_MS / 1000}s) — generate a new URL with totalreclaw_pair.`,
+                                    };
+                                    let hardTimer;
+                                    const hardTimeoutPromise = new Promise((resolve) => {
+                                        hardTimer = setTimeout(() => resolve(TIMEOUT_SENTINEL), PAIR_TOOL_HARD_TIMEOUT_MS);
                                     });
+                                    try {
+                                        const raced = await Promise.race([
+                                            phraseUploadPromise,
+                                            hardTimeoutPromise,
+                                        ]);
+                                        if (raced &&
+                                            typeof raced === 'object' &&
+                                            raced.status === 'timed_out') {
+                                            api.logger.warn(`totalreclaw_pair(relay): hard timeout — ${raced.message} (token=${remoteSession.token.slice(0, 8)}…)`);
+                                        }
+                                    }
+                                    finally {
+                                        if (hardTimer)
+                                            clearTimeout(hardTimer);
+                                    }
                                 }
                                 catch (bgErr) {
                                     // Expected on TTL expiry / user-aborts — log at warn, not error.
@@ -4991,7 +5090,24 @@ const plugin = {
                     // 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.
+                    //
+                    // 3.3.4-rc.1 — fix: previously `stagingBannerShown` was set to
+                    // `true` AS SOON AS the block was built. If the rest of the hook
+                    // then returned `undefined` (e.g. zero memory matches on the first
+                    // turn — multiple paths around lines 6103-6325 do this), the
+                    // banner block was silently discarded AND the flag was already
+                    // flipped, so subsequent before_agent_start invocations never
+                    // reconstructed it. Net effect: QA on 3.3.3-rc.1 (Pedro
+                    // 2026-04-30) saw NO banner emitted across an entire conversation
+                    // even though the build was bound to staging.
+                    //
+                    // Fix: build the block on every call until it is actually
+                    // delivered (i.e., until at least one return path included it
+                    // in `prependContext`). The flag flips at the bottom of this
+                    // hook in `markBannerDelivered()` once we know the prependContext
+                    // path was taken.
                     let stagingBannerBlock = '';
+                    let stagingBannerSuppressed = false;
                     if (!stagingBannerShown) {
                         try {
                             const usingStagingDefault = CONFIG.serverUrl.includes('api-staging.totalreclaw.xyz');
@@ -5004,9 +5120,11 @@ const plugin = {
                                         '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.');
+                                // Do NOT set stagingBannerShown=true here — see comment above.
+                                // Logger emits once per gateway process; this is fine to
+                                // gate on the same flag because the logger is operator-
+                                // facing, not user-facing.
+                                stagingBannerSuppressed = true;
                             }
                             else {
                                 // Non-RC artifact OR user override — never fire the banner this
@@ -5019,6 +5137,33 @@ const plugin = {
                             stagingBannerShown = true;
                         }
                     }
+                    // Operator-facing log: once per process, when we DETECT the
+                    // staging build (banner-shown semantics are about user
+                    // delivery; this log is independent).
+                    if (stagingBannerSuppressed && !stagingBannerLogged) {
+                        stagingBannerLogged = 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.');
+                    }
+                    /**
+                     * Helper — invoked inline at any `prependContext` site that
+                     * wants to lead with the staging banner. Returns the banner
+                     * string AND atomically marks the banner as delivered, so
+                     * subsequent hook calls in the same gateway-process lifetime
+                     * skip re-emission. Returns '' (empty) when no banner is due
+                     * (stable build, user override, or already delivered).
+                     *
+                     * Use this at every prependContext callsite that takes the
+                     * banner; do NOT inline `stagingBannerBlock` on its own — the
+                     * 3.3.4-rc.1 bug fix requires the marker flip to be coupled
+                     * to the actual delivery.
+                     */
+                    const consumeBannerForPrepend = () => {
+                        if (stagingBannerBlock === '')
+                            return '';
+                        stagingBannerShown = true;
+                        return stagingBannerBlock;
+                    };
                     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.
@@ -5047,7 +5192,7 @@ const plugin = {
                             api.logger.warn(`First-run welcome check failed: ${msg}`);
                         }
                         return {
-                            prependContext: stagingBannerBlock +
+                            prependContext: consumeBannerForPrepend() +
                                 welcomeBlock +
                                 '## TotalReclaw setup pending\n\n' +
                                 'TotalReclaw encrypted memory is installed but not yet set up on this machine. ' +
@@ -5146,7 +5291,7 @@ const plugin = {
                                 if (injectResult.promptText) {
                                     api.logger.info(`Digest injection: state=${injectResult.state}`);
                                     return {
-                                        prependContext: stagingBannerBlock +
+                                        prependContext: consumeBannerForPrepend() +
                                             `## Your Memory\n\n${injectResult.promptText}` + welcomeBack + billingWarning,
                                     };
                                 }
@@ -5188,7 +5333,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: stagingBannerBlock + `## Relevant Memories\n\n${lines.join('\n')}` + welcomeBack + billingWarning };
+                                return { prependContext: consumeBannerForPrepend() + `## Relevant Memories\n\n${lines.join('\n')}` + welcomeBack + billingWarning };
                             }
                         }
                         // 3. Merge trapdoors — always include word trapdoors for small-dataset coverage.
@@ -5197,7 +5342,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: stagingBannerBlock + `## Relevant Memories\n\n${lines.join('\n')}` + welcomeBack + billingWarning };
+                            return { prependContext: consumeBannerForPrepend() + `## Relevant Memories\n\n${lines.join('\n')}` + welcomeBack + billingWarning };
                         }
                         if (allTrapdoors.length === 0)
                             return undefined;
@@ -5212,7 +5357,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: stagingBannerBlock + `## Relevant Memories\n\n${lines.join('\n')}` + welcomeBack + billingWarning };
+                                return { prependContext: consumeBannerForPrepend() + `## Relevant Memories\n\n${lines.join('\n')}` + welcomeBack + billingWarning };
                             }
                             return undefined;
                         }
@@ -5236,7 +5381,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: stagingBannerBlock + `## Relevant Memories\n\n${lines.join('\n')}` + welcomeBack + billingWarning };
+                            return { prependContext: consumeBannerForPrepend() + `## Relevant Memories\n\n${lines.join('\n')}` + welcomeBack + billingWarning };
                         }
                         // 5. Decrypt subgraph results and build reranker input.
                         const rerankerCandidates = [];
@@ -5311,7 +5456,7 @@ const plugin = {
                             return `${i + 1}. ${typeTag}${m.text} (importance: ${importance}/10, ${age})`;
                         });
                         const contextString = `## Relevant Memories\n\n${lines.join('\n')}`;
-                        return { prependContext: stagingBannerBlock + contextString + welcomeBack + billingWarning };
+                        return { prependContext: consumeBannerForPrepend() + contextString + welcomeBack + billingWarning };
                     }
                     // --- Server mode (existing behavior) ---
                     // 1. Generate word trapdoors from the user prompt.
@@ -5393,7 +5538,7 @@ const plugin = {
                         return `${i + 1}. ${m.text} (importance: ${importance}/10, ${age})`;
                     });
                     const contextString = `## Relevant Memories\n\n${lines.join('\n')}`;
-                    return { prependContext: stagingBannerBlock + contextString + welcomeBack + billingWarning };
+                    return { prependContext: consumeBannerForPrepend() + contextString + welcomeBack + billingWarning };
                 }
                 catch (err) {
                     // The hook must NEVER throw -- log and return undefined.