@totalreclaw/totalreclaw 3.3.2 → 3.3.4-rc.1

package/dist/pair-cli-relay.js

@@ -0,0 +1,278 @@
+/**
+ * pair-cli-relay — relay-mode runner for the `openclaw totalreclaw pair`
+ * CLI subcommand (3.3.4-rc.1).
+ *
+ * Background
+ * ----------
+ * The CLI default through 3.3.3-rc.1 was the loopback / LAN URL flow
+ * (`pair-cli.ts` `runPairCli` + `pair-session-store`). On Docker
+ * deployments — i.e. the rc.6+ default — that emits `http://localhost:18789/…`
+ * which is unreachable from the user's browser. QA on 3.3.3-rc.1 (Pedro
+ * 2026-04-30) confirmed this is the *primary* CLI-fallback failure mode:
+ * agent loses the `totalreclaw_pair` tool binding, falls back to
+ * `openclaw totalreclaw pair generate --url-pin-only`, gets a localhost
+ * URL, user can't open it.
+ *
+ * 3.3.4-rc.1 flips the CLI default to relay-mode. This file implements
+ * the runner. It mirrors the relay flow already used by the agent tool
+ * (`index.ts` `totalreclaw_pair` handler) so the CLI and the tool emit
+ * URLs from the same relay (`api-staging.totalreclaw.xyz` / `api.…`).
+ *
+ * Output formats
+ * --------------
+ * Same `PairCliOutputMode` surface as the local flow:
+ *   - `human` — multi-line banner + QR ASCII + URL + PIN (default)
+ *   - `json` — single-line `{v:1,sid,url,pin,mode,expires_at_ms,qr_ascii}`
+ *   - `url-pin` — single-line `{v:1,url,pin,expires_at_ms}` (no QR)
+ *   - `pair-only` — single-line `{v:1,pair_url,pin,expires_at_ms}` (no QR)
+ *
+ * The `sid` field in JSON mode carries the relay token (relay-issued
+ * opaque session id) so the agent can correlate emit + completion.
+ *
+ * Phrase safety
+ * -------------
+ * The same invariant the agent-tool path enforces: relay sees only
+ * ciphertext, gateway decrypts locally via x25519 ECDH + AES-GCM, the
+ * mnemonic is written to credentials.json by `completePairing` and never
+ * crosses any logger / stdout. PIN is on stdout (required) but never
+ * logged.
+ *
+ * Scanner / scope
+ * ---------------
+ * Touches `fs` indirectly via the credential-write completion handler
+ * passed in. No env-var reads here — caller resolves URL / paths from
+ * `CONFIG`. See `index.ts` wire-up.
+ */
+import { validateMnemonic } from '@scure/bip39';
+import { wordlist } from '@scure/bip39/wordlists/english';
+import { loadCredentialsJson, writeCredentialsJson, writeOnboardingState, } from './fs-helpers.js';
+import { awaitPhraseUpload, openRemotePairSession, } from './pair-remote-client.js';
+import { setRecoveryPhraseOverride } from './config.js';
+import { encodePng, encodeUnicode } from './pair-qr.js';
+/**
+ * Run the relay-mode pair CLI. Mirrors `runPairCli`'s exit-code semantics:
+ *   - `completed` (status 0)
+ *   - `canceled` (Ctrl+C — status 130)
+ *   - `expired` / `rejected` / `error` (status 1)
+ *
+ * Resolves with the outcome; the caller (`registerPairCli` action) maps
+ * the outcome to `process.exit(...)`.
+ */
+export async function runRelayPairCli(mode, opts) {
+    const outputMode = opts.outputMode ?? 'human';
+    const stdout = opts.io.stdout;
+    // 1. Open the relay session. The relay returns the user-facing URL +
+    //    PIN + token + expiresAt. The keypair stays in-process.
+    let session;
+    try {
+        session = await openRemotePairSession({
+            relayBaseUrl: opts.relayBaseUrl,
+            mode: mode === 'generate' ? 'generate' : 'import',
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        opts.io.stderr.write(`\nFailed to open relay pairing session: ${msg}\n` +
+            `If the relay is unreachable from this gateway, retry with --local for the loopback URL flow.\n`);
+        return { status: 'error', error: msg };
+    }
+    // ISO-8601 → ms for tool-payload parity with the agent tool.
+    const parsedExpiresMs = Date.parse(session.expiresAt);
+    const expiresAtMs = Number.isFinite(parsedExpiresMs)
+        ? parsedExpiresMs
+        : Date.now() + 5 * 60_000;
+    // 2. Render the QR ASCII (skipped in url-pin / pair-only modes — the
+    //    same as `runPairCli`). 10s timeout guard against a renderer that
+    //    never fires its callback.
+    const skipsQr = outputMode === 'url-pin' || outputMode === 'pair-only';
+    const qrAscii = skipsQr
+        ? ''
+        : await new Promise((resolve) => {
+            let settled = false;
+            const t = setTimeout(() => {
+                if (!settled) {
+                    settled = true;
+                    resolve('');
+                }
+            }, 10_000);
+            try {
+                opts.renderQr(session.url, (ascii) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(t);
+                    resolve(ascii);
+                });
+            }
+            catch (err) {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(t);
+                resolve(`(QR renderer crashed: ${err instanceof Error ? err.message : String(err)})`);
+            }
+        });
+    // 3. Emit the visible surface — single JSON line for non-human modes,
+    //    multi-line banner + QR for human mode. Identical layout to the
+    //    local-mode runner so callers can swap transparently.
+    if (outputMode === 'url-pin') {
+        const payload = {
+            v: 1,
+            url: session.url,
+            pin: session.pin,
+            expires_at_ms: expiresAtMs,
+        };
+        stdout.write(JSON.stringify(payload) + '\n');
+    }
+    else if (outputMode === 'pair-only') {
+        const payload = {
+            v: 1,
+            pair_url: session.url,
+            pin: session.pin,
+            expires_at_ms: expiresAtMs,
+        };
+        stdout.write(JSON.stringify(payload) + '\n');
+    }
+    else if (outputMode === 'json') {
+        const payload = {
+            v: 1,
+            sid: session.token,
+            url: session.url,
+            pin: session.pin,
+            mode,
+            expires_at_ms: expiresAtMs,
+            qr_ascii: qrAscii,
+        };
+        stdout.write(JSON.stringify(payload) + '\n');
+    }
+    else {
+        // Human-mode banner. Mirror `pair-cli.ts` COPY surface, but tweak the
+        // header so operators see "Relay" not "Local" (so it's obvious the
+        // URL is universal-reachable, not gateway-loopback).
+        stdout.write('\nTotalReclaw — Relay pairing\n\n' +
+            'Your TotalReclaw recovery phrase will be created (or imported) in your\n' +
+            'BROWSER and delivered to this gateway encrypted end-to-end via the\n' +
+            'relay (the relay only sees ciphertext). The phrase never touches the\n' +
+            'LLM, the session transcript, or the relay server in plaintext.\n\n' +
+            'Scan the QR code below with your phone, or open the URL on any device\n' +
+            '(no LAN / Tailscale / port-forward required). Then type the 6-digit\n' +
+            'code shown here into the browser.\n');
+        stdout.write(mode === 'generate'
+            ? '\nMode: GENERATE — your browser will create a NEW 12-word recovery phrase.\n' +
+                'You will be asked to write it down and retype 3 words before the\n' +
+                'gateway accepts it.\n'
+            : '\nMode: IMPORT — your browser will accept an existing TotalReclaw\n' +
+                'recovery phrase that you already have. Paste it in the browser; it\n' +
+                'will be validated locally and encrypted before upload.\n');
+        if (qrAscii) {
+            stdout.write('\n' + qrAscii + '\n');
+        }
+        else {
+            stdout.write('\n(QR not rendered — use the URL below)\n');
+        }
+        stdout.write('\nSecondary code (type this into the browser):\n\n    ' +
+            session.pin.split('').join(' ') +
+            '\n\nURL (QR encodes this plus a one-time public key):\n\n    ' +
+            session.url +
+            '\n\nSecurity:\n' +
+            '  * Do NOT share your screen during pairing.\n' +
+            '  * Do NOT screenshot this terminal.\n' +
+            '  * The browser page will warn you never to reuse this recovery\n' +
+            '    phrase for wallets, banking, email, or any other service.\n' +
+            '\nWaiting for browser to connect… (press Ctrl+C to cancel)\n');
+    }
+    // 4. Optional PNG / Unicode QR for richer transports — same as the
+    //    agent tool. Best-effort; non-fatal on encode failure.
+    if (!skipsQr && outputMode !== 'human') {
+        // JSON consumers already have qr_ascii; PNG/Unicode would belong in
+        // a separate response shape. Keeping the runner surface in-band with
+        // the local runner means we don't add fields here. Skip silently.
+        void encodePng;
+        void encodeUnicode;
+    }
+    // 5. Set up Ctrl+C cancellation. The relay session can't be
+    //    server-side rejected from the client (no rejectPairSession-equivalent
+    //    over the WS), but closing the WebSocket terminates the session.
+    let canceled = false;
+    const releaseInterrupt = opts.io.onInterrupt(() => {
+        canceled = true;
+        try {
+            session._ws.close();
+        }
+        catch {
+            /* ignore */
+        }
+    });
+    // 6. Block on the relay until the browser uploads the encrypted
+    //    phrase, then write credentials + flip onboarding-state. Mirrors
+    //    the agent-tool's `awaitPhraseUpload` callback inline so we have a
+    //    single source of truth for credential persistence.
+    const emitStatus = (text) => {
+        if (outputMode === 'human')
+            stdout.write(text);
+    };
+    try {
+        const result = await awaitPhraseUpload(session, {
+            phraseValidator: (p) => validateMnemonic(p, wordlist),
+            completePairing: async ({ mnemonic }) => {
+                try {
+                    let scopeAddress;
+                    try {
+                        scopeAddress = await opts.deriveScopeAddress(mnemonic);
+                    }
+                    catch (deriveErr) {
+                        opts.logger.warn(`pair-cli (relay): scope_address derivation failed (will retry lazily): ${deriveErr instanceof Error ? deriveErr.message : String(deriveErr)}`);
+                    }
+                    const creds = loadCredentialsJson(opts.credentialsPath) ?? {};
+                    const next = { ...creds, mnemonic };
+                    if (scopeAddress)
+                        next.scope_address = scopeAddress;
+                    if (!writeCredentialsJson(opts.credentialsPath, next)) {
+                        return { state: 'error', error: 'credentials_write_failed' };
+                    }
+                    setRecoveryPhraseOverride(mnemonic);
+                    writeOnboardingState(opts.onboardingStatePath, {
+                        onboardingState: 'active',
+                        createdBy: mode === 'generate' ? 'generate' : 'import',
+                        credentialsCreatedAt: new Date().toISOString(),
+                        version: opts.pluginVersion,
+                    });
+                    opts.logger.info(`pair-cli (relay): session ${session.token.slice(0, 8)}… completed; credentials written` +
+                        (scopeAddress ? ` (scope_address=${scopeAddress})` : ''));
+                    return { state: 'active' };
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    opts.logger.error(`pair-cli (relay): completePairing failed: ${msg}`);
+                    return { state: 'error', error: msg };
+                }
+            },
+        });
+        if (canceled) {
+            emitStatus('\nCanceled. Pairing session invalidated.\n');
+            return { status: 'canceled', sid: session.token };
+        }
+        if (result.state === 'active') {
+            emitStatus('\nPairing complete. Account is active.\n');
+            return { status: 'completed', sid: session.token };
+        }
+        emitStatus(`\nPairing failed: ${result.error ?? 'unknown_error'}\n`);
+        return { status: 'error', sid: session.token, error: result.error ?? 'unknown_error' };
+    }
+    catch (err) {
+        if (canceled) {
+            emitStatus('\nCanceled. Pairing session invalidated.\n');
+            return { status: 'canceled', sid: session.token };
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('timeout')) {
+            emitStatus('\nSession expired. Run the command again to restart.\n');
+            return { status: 'expired', sid: session.token };
+        }
+        emitStatus(`\nPairing error: ${msg}\n`);
+        return { status: 'error', sid: session.token, error: msg };
+    }
+    finally {
+        releaseInterrupt();
+    }
+}

package/dist/pair-cli.js

@@ -3,20 +3,34 @@
  *
  * Purpose
  * -------
- * Starts a remote-onboarding session FROM the gateway host's terminal.
- * Creates a pair-session, renders the QR + URL + 6-digit secondary code
- * to stdout, then polls /status until the browser completes the flow.
+ * Starts a pairing session from the gateway host's terminal and renders
+ * the URL + 6-digit PIN + ASCII QR. The user opens the URL in a browser
+ * (on phone or laptop), confirms the PIN, and uploads their recovery
+ * phrase end-to-end-encrypted.
  *
- * This is the gateway-operator's surface. The operator reads the QR
- * with their phone (or opens the URL on their laptop browser); the
- * browser takes over from there.
+ * Two URL flavours
+ * ----------------
+ * * **Relay mode (3.3.4-rc.1 default).** The CLI opens a WebSocket against
+ *   the relay (`api-staging.totalreclaw.xyz` for RC, `api.totalreclaw.xyz`
+ *   for stable) and gets back a `https://<relay>/pair/p/<token>#pk=…` URL
+ *   the user can reach from any device on any network. This is the same
+ *   surface the agent-tool `totalreclaw_pair` uses. It works behind NAT,
+ *   in Docker, on managed services — anywhere outbound HTTPS works.
+ *
+ * * **Local mode (`--local`).** The legacy loopback flow: a session lands
+ *   in `pair-session-store` and the URL points at the gateway's own
+ *   bound interface (`http://localhost:18789/...`, or LAN/Tailscale IP
+ *   if autodetected). Required for fully-air-gapped operators who want
+ *   the relay out of the loop. Browser must be on a network that can
+ *   reach the gateway.
  *
  * Scope and scanner surface
  * -------------------------
  * Has `fetch` (for status polling) AND `POST` (never actually POSTs,
  * but the word lives in comments describing the paired browser POST).
  * MUST NOT also read disk or env vars. All state operations delegate
- * to pair-session-store; the CLI itself is a thin coordinator.
+ * to pair-session-store / pair-remote-client; the CLI itself is a thin
+ * coordinator.
  *
  * Zero logging of secret material. The secondary code IS printed to
  * stdout (required for the user to type), but never logged to file
@@ -287,9 +301,12 @@ export function registerPairCli(program, deps) {
             .description('TotalReclaw encrypted memory — pairing + onboarding + status');
     }
     tr.command('pair [mode]')
-        .description('Pair a remote browser device to this gateway (mode = generate | import; default generate)')
-        .option('--json', 'Emit a single JSON payload (url/pin/sid/qr_ascii) instead of the human-readable banner. Enables agent-driven pairing.')
+        .description('Pair a remote browser device to this gateway via the relay (default; ' +
+        'works through NAT and inside Docker). Use --local to fall back to ' +
+        'gateway-loopback URLs for air-gapped setups.')
+        .option('--json', 'Emit a single JSON payload (url/pin/qr_ascii) instead of the human-readable banner. Enables agent-driven pairing.')
         .option('--url-pin-only', 'Emit ONLY {v,url,pin,expires_at_ms} — no QR ASCII, no SID, no mode echo. Headless fallback for container-based agents where the totalreclaw_pair tool is not injected (issue #87). Zero phrase exposure on stdout.')
+        .option('--local', '(3.3.4-rc.1) Use the loopback / LAN URL flow instead of the relay. URLs point at this gateway\'s bound interface (e.g. http://localhost:18789/…) and require the user\'s browser to be on a reachable network. Default since rc.6 was relay; this flag preserves the air-gapped path.')
         .option('--timeout <sec>', 'Session TTL in seconds (default: 900 = 15 min, matches pair-session-store default)')
         .action(async (...args) => {
         // commander passes: [modeArg, options, cmd]
@@ -311,15 +328,55 @@ export function registerPairCli(program, deps) {
                 ttlSeconds = parsed;
         }
         const io = buildDefaultPairCliIo();
+        // 3.3.4-rc.1 — flip the default to relay-mode. The agent tool
+        // `totalreclaw_pair` has used the relay since rc.11; the CLI was
+        // the last surface still defaulting to gateway-loopback URLs,
+        // which are unreachable from a remote browser when the gateway
+        // runs in Docker (the rc.6+ default deployment). `--local`
+        // restores the legacy flow for air-gapped operators.
+        const useRelay = shouldUseRelayMode({
+            local: opts.local,
+            hasRelayRunner: typeof deps.runRelayPairCli === 'function',
+        });
         try {
-            const outcome = await runPairCli(mode, {
-                sessionsPath: deps.sessionsPath,
-                renderPairingUrl: deps.renderPairingUrl,
-                renderQr: defaultRenderQr,
-                io,
-                outputMode,
-                ttlSeconds,
-            });
+            let outcome;
+            if (useRelay) {
+                outcome = await deps.runRelayPairCli(mode, {
+                    renderQr: defaultRenderQr,
+                    io,
+                    outputMode,
+                    ttlSeconds,
+                });
+            }
+            else {
+                if (opts.local) {
+                    // Tell the operator they explicitly opted in. Suppress in
+                    // JSON modes — the JSON contract must stay stdout-clean.
+                    if (outputMode === 'human') {
+                        io.stderr.write('\n[--local] Using gateway-loopback URL flow. The user\'s browser ' +
+                            'must be reachable from this gateway\'s bound interface (LAN, Tailscale, ' +
+                            'or localhost on the same machine).\n');
+                    }
+                }
+                else if (!deps.runRelayPairCli) {
+                    // No relay runner wired — older composition. Warn once on
+                    // stderr in human mode so the operator knows why URLs may
+                    // be unreachable from a remote browser.
+                    if (outputMode === 'human') {
+                        io.stderr.write('\n[pair-cli] relay-mode runner not available — falling back to local-mode. ' +
+                            'Pair URLs will use this gateway\'s bound interface. Upgrade the plugin ' +
+                            'or pass --local to silence this warning.\n');
+                    }
+                }
+                outcome = await runPairCli(mode, {
+                    sessionsPath: deps.sessionsPath,
+                    renderPairingUrl: deps.renderPairingUrl,
+                    renderQr: defaultRenderQr,
+                    io,
+                    outputMode,
+                    ttlSeconds,
+                });
+            }
             if (outcome.status !== 'completed') {
                 process.exit(outcome.status === 'canceled' ? 130 : 1);
             }
@@ -331,6 +388,17 @@ export function registerPairCli(program, deps) {
         }
     });
 }
+/**
+ * 3.3.4-rc.1 — pure decision function: given the parsed action flags
+ * and whether a relay runner is wired, return whether the relay path
+ * should be taken. Exported for unit-testing the default-mode flip
+ * without invoking either runner.
+ */
+export function shouldUseRelayMode(opts) {
+    if (opts.local)
+        return false;
+    return opts.hasRelayRunner;
+}
 // ---------------------------------------------------------------------------
 // Utils
 // ---------------------------------------------------------------------------

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

@@ -86,9 +86,51 @@ function defaultCacheRoot(): string {
   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(): EmbedderRuntimeConfig {
   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?: { 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. */

package/fs-helpers.ts

@@ -124,9 +124,17 @@ export function ensureMemoryHeaderFile(
  * 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
@@ -137,12 +145,48 @@ export function ensureMemoryHeaderFile(
  * helper — see the file-header guardrail.
  */
 export function readPluginVersion(packageJsonDir: string): string | null {
+  // 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: string): string | null {
   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) as { version?: string };
-    return typeof parsed.version === 'string' ? parsed.version : null;
+    const parsed = JSON.parse(raw) as { version?: string; name?: string };
+    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;
   }