@totalreclaw/totalreclaw 3.3.2 → 3.3.4-rc.1

package/pair-cli-relay.ts

@@ -0,0 +1,336 @@
+/**
+ * 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';
+import type {
+  PairCliIo,
+  PairCliJsonPayload,
+  PairCliMode,
+  PairCliOutcome,
+  PairCliOutputMode,
+  PairCliPairOnlyPayload,
+  PairCliUrlPinPayload,
+} from './pair-cli.js';
+
+export interface RelayPairCliRunnerOpts {
+  /** Relay base URL (`wss://api-staging.totalreclaw.xyz` for RC, `wss://api.…` for stable). */
+  relayBaseUrl: string;
+  /** Where credentials.json lives — written by completePairing. */
+  credentialsPath: string;
+  /** Where onboarding-state.json lives — flipped to `active` on success. */
+  onboardingStatePath: string;
+  /** Plugin version stamped into onboarding-state.json. */
+  pluginVersion: string;
+  /** Scope-address derivation. Best-effort — null on failure. */
+  deriveScopeAddress: (mnemonic: string) => Promise<string | undefined>;
+  /** Logger — never receives PIN / phrase / token-tail material. */
+  logger: { info(msg: string): void; warn(msg: string): void; error(msg: string): void };
+  /** QR ASCII renderer — same callback shape as `qrcode-terminal`. */
+  renderQr: (payload: string, cb: (ascii: string) => void) => void;
+  /** stdio surface for stdout / stderr / Ctrl+C. */
+  io: PairCliIo;
+  /** Output mode — defaults to `'human'`. */
+  outputMode?: PairCliOutputMode;
+  /**
+   * 3.3.4-rc.1 — currently informational. The relay-side TTL is set by the
+   * relay; this runner accepts the option for surface parity with the local
+   * runner. We do not extend it past the relay default because the relay is
+   * authoritative for session expiry.
+   */
+  ttlSeconds?: number;
+}
+
+/**
+ * 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: PairCliMode,
+  opts: RelayPairCliRunnerOpts,
+): Promise<PairCliOutcome> {
+  const outputMode: PairCliOutputMode = 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: Awaited<ReturnType<typeof openRemotePairSession>>;
+  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<string>((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: PairCliUrlPinPayload = {
+      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: PairCliPairOnlyPayload = {
+      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: PairCliJsonPayload = {
+      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: string): void => {
+    if (outputMode === 'human') stdout.write(text);
+  };
+
+  try {
+    const result = await awaitPhraseUpload(session, {
+      phraseValidator: (p: string) => validateMnemonic(p, wordlist),
+      completePairing: async ({ mnemonic }) => {
+        try {
+          let scopeAddress: string | undefined;
+          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: typeof creds = { ...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: unknown) {
+          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/pair-cli.ts

@@ -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
@@ -444,6 +458,15 @@ export function registerPairCli(
     sessionsPath: string;
     renderPairingUrl(session: PairSession): string;
     logger: { info(msg: string): void; warn(msg: string): void; error(msg: string): void };
+    /**
+     * 3.3.4-rc.1 — relay-mode runner. When supplied, the CLI defaults to
+     * relay-mode (relay-brokered URL via `api-staging.totalreclaw.xyz` /
+     * `api.totalreclaw.xyz`). The runner is responsible for opening the
+     * WS session and polling the relay, mirroring `runPairCli`'s exit
+     * codes. If absent (very old plugin loader), the CLI silently falls
+     * back to local-mode and warns.
+     */
+    runRelayPairCli?: (mode: PairCliMode, opts: RelayPairCliOpts) => Promise<PairCliOutcome>;
   },
 ): void {
   // If the onboarding-cli already attached `totalreclaw`, reuse it.
@@ -459,15 +482,23 @@ export function registerPairCli(
 
   tr.command('pair [mode]')
     .description(
-      'Pair a remote browser device to this gateway (mode = generate | import; default generate)',
+      '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/sid/qr_ascii) instead of the human-readable banner. Enables agent-driven pairing.')
+    .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: unknown[]) => {
       // commander passes: [modeArg, options, cmd]
       const modeRaw = typeof args[0] === 'string' ? args[0] : undefined;
-      const opts = (args[1] ?? {}) as { json?: boolean; urlPinOnly?: boolean; timeout?: string | number };
+      const opts = (args[1] ?? {}) as {
+        json?: boolean;
+        urlPinOnly?: boolean;
+        local?: boolean;
+        timeout?: string | number;
+      };
       const mode: PairCliMode =
         modeRaw === 'import' || modeRaw === 'imp' ? 'import' : 'generate';
       // --url-pin-only wins over --json when both are passed, since it is
@@ -483,15 +514,57 @@ export function registerPairCli(
         if (Number.isFinite(parsed) && parsed > 0) 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: PairCliOutcome;
+        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);
         }
@@ -503,6 +576,33 @@ export function registerPairCli(
     });
 }
 
+/**
+ * 3.3.4-rc.1 — options for the relay-mode CLI runner. Mirrors the human
+ * surface of `runPairCli` (output mode, QR renderer, IO, TTL) but does
+ * NOT take `sessionsPath` / `renderPairingUrl` because the relay flow
+ * mints its own URL via the relay's `opened` frame.
+ */
+export interface RelayPairCliOpts {
+  renderQr: (payload: string, cb: (ascii: string) => void) => void;
+  io: PairCliIo;
+  outputMode?: PairCliOutputMode;
+  ttlSeconds?: number;
+}
+
+/**
+ * 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: {
+  local?: boolean;
+  hasRelayRunner: boolean;
+}): boolean {
+  if (opts.local) return false;
+  return opts.hasRelayRunner;
+}
+
 // ---------------------------------------------------------------------------
 // Utils
 // ---------------------------------------------------------------------------

package/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "totalreclaw",
-  "version": "3.3.2-rc.4",
+  "version": "3.3.4-rc.1",
   "description": "End-to-end encrypted memory for AI agents — portable, yours forever. XChaCha20-Poly1305 E2EE: server never sees plaintext.",
   "author": "TotalReclaw Team",
   "license": "MIT",
@@ -193,8 +193,8 @@
     "config": {
       "serverUrl": {
         "type": "string",
-        "default": "https://api.totalreclaw.xyz",
-        "description": "TotalReclaw server URL (only change for self-hosted mode)"
+        "default": "https://api-staging.totalreclaw.xyz",
+        "description": "TotalReclaw server URL (only change for self-hosted mode). Source default points at staging; stable releases swap to https://api.totalreclaw.xyz at publish time per PR #165."
       },
       "autoExtractEveryTurns": {
         "type": "number",

package/subgraph-store.ts

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