@totalreclaw/totalreclaw 3.3.2 → 3.3.4-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.4-rc.1
 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/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

@@ -53,10 +53,50 @@ 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
+ * 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;

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;