@totalreclaw/totalreclaw 3.3.12-rc.13 → 3.3.12-rc.15

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: totalreclaw
-description: "End-to-end encrypted, decentralized memory for OpenClaw. Set up an account once, then call totalreclaw_remember / totalreclaw_recall (or the tr CLI under hybrid-primary) instead of writing to MEMORY.md / USER.md / local files. Trigger on 'install TotalReclaw', 'set up TotalReclaw', 'restore my recovery phrase', any remember / recall request, AND any user statement that contains a preference / fact / decision / commitment about themselves."
-version: 3.3.12-rc.13
+description: "End-to-end encrypted, decentralized memory for OpenClaw. A native kind:memory provider — recall is automatic via memory_search/memory_get, and facts are captured in the background. Trigger on 'install TotalReclaw', 'set up TotalReclaw', 'restore my recovery phrase', any recall request ('what do you remember about me', 'what's my X'), AND any explicit remember request ('remember X', 'save X')."
+version: 3.3.12-rc.15
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -22,19 +22,17 @@ metadata:
       - persistent-context
 ---
 
-# TotalReclaw — OpenClaw plugin
+# TotalReclaw — OpenClaw native memory provider
 
-End-to-end encrypted memory stored across a decentralized network (not on a single company server). The plugin handles install + account-setup autonomously; this skill tells the agent what to call and when.
+End-to-end encrypted memory stored across a decentralized network (not on a single company server). TotalReclaw is OpenClaw's **native `kind:"memory"` provider**: recall runs through the conventional `memory_search` / `memory_get` tools (the same surface `active-memory` uses), and **facts are captured automatically in the background** — you do not call a tool to remember each fact. This skill tells you the install + account-setup flow and when to drive recall explicitly.
 
-## TOP RULE — MEMORY STORAGE
+## How memory works here (read first)
 
-When the user states ANYTHING about themselves — preferences, decisions, identity, work, location, plans, tools, commitments — call `totalreclaw_remember` (or `tr remember --json "<fact>"` under hybrid-primary). NEVER write user facts to `MEMORY.md`, `USER.md`, or any local file. Those are agent-persona configuration; user memories live encrypted on-chain.
+- **Recall is native.** `memory_search` and `memory_get` are the memory tools. OpenClaw's `active-memory` sub-agent routes recall through them and the plugin injects guidance telling you when to search. When the user asks about themselves ("what's my X?", "do I X?", "what do you remember?"), call `memory_search`. If 0 results, say so plainly — don't guess from session history.
+- **Capture is automatic.** The plugin extracts facts from the conversation in the background (trajectory poller). You do **not** call a tool on every preference/fact the user states — that happens for you. Never write user facts to `MEMORY.md`, `USER.md`, or any local file; those are agent-persona config, user memories live encrypted on-chain.
+- **Explicit remember only on request.** If the user explicitly says "remember X" / "save X" / "note X" / "don't forget X", use the CLI: `tr remember --json "X"`. One call per distinct fact.
 
-**Trigger immediately, no "should I?":** "I prefer / like / love / hate X", "my favorite is X", "I'm X", "my name is X", "I live / work at X", "I use X", "I decided X", "I'm going to X", "from now on X", "we agreed X", "I'll X by Y", "remind me to X", "remember that X", "save X", "note X". If a message contains MULTIPLE facts, call `totalreclaw_remember` once per fact — never blob.
-
-When the user asks about themselves ("what's my X?", "do I X?", "what do you remember?"), call `totalreclaw_recall` FIRST. If 0 results, say so plainly — don't guess from session history.
-
-Do not describe storage as `"local"`, `"local-only"`, `"stored locally"`, `"on disk"`, `"local memory"`, `"local storage"`, or `"without an account"` — memories are decentralized on-chain (not on any single company server) and an account is required to derive the encryption key.
+Do not describe storage as `"local"`, `"local-only"`, `"stored locally"`, `"on disk"`, or `"without an account"` — memories are decentralized on-chain (not on any single company server) and an account is required to derive the encryption key.
 
 ## Phrase safety (HARD)
 
@@ -43,34 +41,40 @@ The 12-word recovery phrase MUST NEVER enter chat or the agent's LLM context. Th
 ## Install
 
 ```
-openclaw plugins install @totalreclaw/totalreclaw@rc
+openclaw plugins install @totalreclaw/totalreclaw
 openclaw skills install totalreclaw
 ```
 
-Plugin is published on npm + ClawHub (`p-diogo`, GitHub-verified). Stable: drop `@rc`. Under hybrid-primary, the `tr` CLI is the primary path; native `totalreclaw_*` tools are also bound when OpenClaw exposes them — use whichever your runtime binds.
-
-## Setup (plugin-driven)
+Published on npm + ClawHub (`p-diogo`, GitHub-verified). For a release candidate, pin with `@rc`; stable resolves from `latest`. The plugin self-applies any gateway config it needs on load and auto-reloads (see Restart below) — no manual gateway restart.
 
-The plugin auto-creates a pair session on first load when no credentials exist, writes `{url, pin, sid, expires_at_ms}` to `~/.totalreclaw/.pair-pending.json`, and injects a `before_agent_start` context block to you. **When you see that block, surface the URL and PIN to the user VERBATIM — read from the injected context; never invent values.** Confirm on pair completion: `✓ TotalReclaw set up.` (If credentials already exist: `✓ TotalReclaw is already set up.`)
+## Setup (pair — user-initiated QR)
 
-If a restart is needed (rare — plugin self-handles via gateway config-watcher), issue the literal slash command `/totalreclaw-restart`. Never `kill`, `docker restart`, or prompt the user to restart.
+Pairing is a deliberate, user-initiated QR flow (the plugin does **not** auto-pair on load). When credentials don't exist:
 
-## Hybrid-primary CLI
+1. Run `tr pair --json` → returns `{"url":"https://…/pair/p/<id>#pk=…","pin":"123456","expires_at_ms":…}`.
+2. Surface the **url** and **pin** to the user verbatim (read from the JSON; never invent values): "Open `<url>` in your browser, enter PIN `<pin>`, and generate or paste your 12-word recovery phrase. Reply done once it's sealed."
+3. The user completes in the browser (phrase is generated/imported browser-side, encrypted, posted to the relay — never touches this chat). On completion `~/.totalreclaw/credentials.json` is written.
+4. Confirm: `✓ TotalReclaw set up.` (If credentials already exist when first asked: `✓ TotalReclaw is already set up.`)
 
-OpenClaw 2026.5.x may strip non-bundled tool bindings (issue #223). Never rely on `totalreclaw_*` tool binding alone. Fall back via shell:
+Pair is UNCONDITIONAL when no credentials — the user installing/requesting setup IS the consent; do not add a second consent gate. `tr --help` lists every subcommand.
 
 ```bash
 TR_CLI="$(ls -d ~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cli.js ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js 2>/dev/null | head -1)"
-node "$TR_CLI" status --json     # {"version":"...","hybrid_mode":true,"tool_count":17}
-node "$TR_CLI" remember --json "I work at Graph Foundation"
-node "$TR_CLI" recall --json "where does the user work" --limit 5   # {"results":[{"text":"...","score":0.8}]}
-node "$TR_CLI" pair --json       # {"url":"...","pin":"123456","expires_at_ms":...} — plugin's auto-pair is preferred; only use this for re-pair
+node "$TR_CLI" pair --json        # start/re-pair
+node "$TR_CLI" status --json      # {"version":"…","paired":true,…}
 ```
 
-Pair is UNCONDITIONAL when no credentials — pasting the install URL IS the consent. `tr --help` lists every subcommand.
+## Restart (agent-driven, never user-manual)
+
+The plugin self-reloads: after install it writes the gateway config it needs and signals `SIGUSR1` to its own PID so the gateway picks it up without a manual restart. **If `memory_search`/`memory_get` are not bound** (tools didn't take effect on first load), issue the literal slash command `/totalreclaw-restart` **autonomously** — announce it in one line, never ask the user to authorize it, never stall, never `kill` / `docker restart` / prompt the user to restart. This mirrors the autonomous-restart pattern other runtimes use; the user should never perform a manual restart.
+
+## Tools + CLI surface
+
+**Recall (native memory contract — agent-facing):** `memory_search`, `memory_get`.
 
-## Tools (16 native; same surface via `tr`)
+**Explicit capture + curation (CLI — `tr`, i.e. `node "$TR_CLI" …`):**
+`tr remember` (explicit write) · `tr pin` / `tr unpin` · `tr retype` · `tr set_scope` · `tr status` · `tr export` · `tr pair`. Import + plan upgrade run via the gateway subcommand: `openclaw totalreclaw import from <source> --file <path> [--json]`, `openclaw totalreclaw upgrade [--json]`, `openclaw totalreclaw import status|abort`.
 
-`totalreclaw_remember` · `totalreclaw_recall` · `totalreclaw_forget` · `totalreclaw_pair` · `totalreclaw_pin` · `totalreclaw_unpin` · `totalreclaw_retype` · `totalreclaw_set_scope` · `totalreclaw_export` · `totalreclaw_import_from` · `totalreclaw_import_batch` · `totalreclaw_consolidate` · `totalreclaw_status` · `totalreclaw_upgrade` · `totalreclaw_onboarding_start` · `totalreclaw_report_qa_bug` (RC only).
+The legacy `totalreclaw_*` agent tools and the `tr recall` CLI are retired — recall is `memory_search`, explicit capture is `tr remember`. If a stale guide references them, follow this SKILL instead.
 
-Full guides: <https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/openclaw-setup.md>
+Full guide: <https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/openclaw-setup.md>

package/config.ts

@@ -102,10 +102,10 @@ export function getSessionId(): string | null {
 
 /**
  * Runtime override for chain ID, set after the relay billing response is
- * read. Free tier stays on 84532 (Base Sepolia); Pro tier flips to 100
- * (Gnosis mainnet). The relay routes Pro writes to Gnosis, so Pro-tier
- * UserOps MUST be signed against chain 100 — otherwise the bundler rejects
- * the signature with AA23.
+ * read. After the ops-1 single-chain migration (2026-05), ALL tiers (free
+ * + Pro) are on Gnosis mainnet (chain 100). The default below is 100.
+ * The relay routes all writes to Gnosis, so UserOps MUST be signed against
+ * chain 100 — otherwise the bundler rejects the signature with AA24.
  *
  * See index.ts: after the billing lookup completes, call
  * `setChainIdOverride(100)` for Pro users. Free users can leave the
@@ -221,9 +221,8 @@ export const CONFIG = {
       : 'wss://api.totalreclaw.xyz')
   ).replace(/\/+$/, ''),
 
-  // Chain — chainId is no longer user-configurable. It is auto-detected from
-  // the relay billing response (free = Base Sepolia / 84532, Pro = Gnosis /
-  // 100). The default here is used only before the first billing lookup
+  // Chain — chainId is no longer user-configurable. After the ops-1 single-
+  // chain migration, ALL tiers are on Gnosis (100). The default here is 100.
   // completes. Self-hosted users can still point at a custom DataEdge via
   // TOTALRECLAW_DATA_EDGE_ADDRESS / TOTALRECLAW_ENTRYPOINT_ADDRESS /
   // TOTALRECLAW_RPC_URL (undocumented; internal knobs).
@@ -233,7 +232,7 @@ export const CONFIG = {
   // not a literal — a literal would freeze all Pro-tier UserOps to the
   // wrong chainId and AA23 at the bundler.
   get chainId(): number {
-    return _chainIdOverride ?? 84532;
+    return _chainIdOverride ?? 100;
   },
   dataEdgeAddress: process.env.TOTALRECLAW_DATA_EDGE_ADDRESS || '',
   entryPointAddress: process.env.TOTALRECLAW_ENTRYPOINT_ADDRESS || '',

package/dist/config.js

@@ -90,10 +90,10 @@ export function getSessionId() {
 }
 /**
  * Runtime override for chain ID, set after the relay billing response is
- * read. Free tier stays on 84532 (Base Sepolia); Pro tier flips to 100
- * (Gnosis mainnet). The relay routes Pro writes to Gnosis, so Pro-tier
- * UserOps MUST be signed against chain 100 — otherwise the bundler rejects
- * the signature with AA23.
+ * read. After the ops-1 single-chain migration (2026-05), ALL tiers (free
+ * + Pro) are on Gnosis mainnet (chain 100). The default below is 100.
+ * The relay routes all writes to Gnosis, so UserOps MUST be signed against
+ * chain 100 — otherwise the bundler rejects the signature with AA24.
  *
  * See index.ts: after the billing lookup completes, call
  * `setChainIdOverride(100)` for Pro users. Free users can leave the
@@ -202,9 +202,8 @@ export const CONFIG = {
         || (process.env.TOTALRECLAW_SERVER_URL
             ? process.env.TOTALRECLAW_SERVER_URL.replace(/^https?:\/\//, 'wss://').replace(/^http:/, 'ws:')
             : 'wss://api.totalreclaw.xyz')).replace(/\/+$/, ''),
-    // Chain — chainId is no longer user-configurable. It is auto-detected from
-    // the relay billing response (free = Base Sepolia / 84532, Pro = Gnosis /
-    // 100). The default here is used only before the first billing lookup
+    // Chain — chainId is no longer user-configurable. After the ops-1 single-
+    // chain migration, ALL tiers are on Gnosis (100). The default here is 100.
     // completes. Self-hosted users can still point at a custom DataEdge via
     // TOTALRECLAW_DATA_EDGE_ADDRESS / TOTALRECLAW_ENTRYPOINT_ADDRESS /
     // TOTALRECLAW_RPC_URL (undocumented; internal knobs).
@@ -214,7 +213,7 @@ export const CONFIG = {
     // not a literal — a literal would freeze all Pro-tier UserOps to the
     // wrong chainId and AA23 at the bundler.
     get chainId() {
-        return _chainIdOverride ?? 84532;
+        return _chainIdOverride ?? 100;
     },
     dataEdgeAddress: process.env.TOTALRECLAW_DATA_EDGE_ADDRESS || '',
     entryPointAddress: process.env.TOTALRECLAW_ENTRYPOINT_ADDRESS || '',

package/dist/index.js

@@ -3524,6 +3524,17 @@ const plugin = {
                     sessionsPath: CONFIG.pairSessionsPath,
                     apiBase: '/plugin/totalreclaw/pair',
                     logger: api.logger,
+                    // 3.3.14 — wire the relay URL so buildPairRoutes exposes the
+                    // in-process `/pair/init` route. The gateway process opens the
+                    // relay WebSocket directly (via openRemotePairSession from
+                    // pair-remote-client.ts), eliminating the 30s-subprocess-kill
+                    // 502 that the CLI path (tr pair) hit when OpenClaw's shell
+                    // tool killed the subprocess mid-pair. relayBaseUrl is sourced
+                    // from CONFIG.pairRelayUrl (config.ts reads it from the env
+                    // once, centrally) — never read from the environment inside
+                    // pair-http.ts (scanner-surface rule).
+                    relayBaseUrl: CONFIG.pairRelayUrl,
+                    initPairMode: 'either',
                     validateMnemonic: (p) => validateMnemonic(p, wordlist),
                     completePairing: async ({ mnemonic }) => {
                         // Write credentials.json + flip state to 'active' via
@@ -3584,7 +3595,20 @@ const plugin = {
                 api.registerHttpRoute({ path: bundle.startPath, handler: bundle.handlers.start, auth: 'plugin' });
                 api.registerHttpRoute({ path: bundle.respondPath, handler: bundle.handlers.respond, auth: 'plugin' });
                 api.registerHttpRoute({ path: bundle.statusPath, handler: bundle.handlers.status, auth: 'plugin' });
-                api.logger.info('TotalReclaw: registered 4 QR-pairing HTTP routes synchronously');
+                // 3.3.14 — in-process pair trigger. The bundle exposes initPath +
+                // handlers.init ONLY when relayBaseUrl is wired (always true here,
+                // since CONFIG.pairRelayUrl has a built-in default). Registered
+                // with auth: 'plugin' (same as the other pair routes) so the
+                // agent's localhost curl reaches it without a gateway bearer
+                // token. The route opens the relay WS in the gateway process →
+                // survives shell-tool timeouts, retries, SIGUSR1 reloads.
+                if (bundle.initPath && bundle.handlers.init) {
+                    api.registerHttpRoute({ path: bundle.initPath, handler: bundle.handlers.init, auth: 'plugin' });
+                    api.logger.info('TotalReclaw: registered 5 QR-pairing HTTP routes synchronously (incl. in-process /pair/init)');
+                }
+                else {
+                    api.logger.info('TotalReclaw: registered 4 QR-pairing HTTP routes synchronously (in-process /pair/init not wired — no relay URL)');
+                }
             }
             else {
                 api.logger.warn('api.registerHttpRoute is unavailable on this OpenClaw version — /totalreclaw pair will not work. ' +

package/dist/pair-http.js

@@ -2,7 +2,23 @@
  * pair-http — gateway-side HTTP route handlers for the v3.3.0 QR-pairing
  * flow. Registered via `api.registerHttpRoute` from `index.ts`.
  *
- * Three endpoints (all under /plugin/totalreclaw/pair/):
+ * Five endpoints (all under /plugin/totalreclaw/pair/):
+ *
+ *   GET  /plugin/totalreclaw/pair/init
+ *        → IN-PROCESS pair trigger (3.3.14). Opens the relay WebSocket
+ *          directly in the gateway process via `openRemotePairSession`
+ *          (from pair-remote-client.ts), returns `{url, pin, sid,
+ *          expires_at_ms}` immediately so the agent can surface URL+PIN
+ *          to the user, and starts a BACKGROUND `awaitPhraseUpload` that
+ *          blocks on the WS for the browser's encrypted phrase, decrypts
+ *          locally, and invokes the injected `completePairing` callback
+ *          (writes credentials.json + flips onboarding state). The WS
+ *          lives in the gateway process — immune to the shell-tool's
+ *          30s subprocess timeout that killed the `tr pair` CLI path
+ *          (relay returned 502 on /pair/respond when the subprocess
+ *          died). This is the primary agent-facilitated pair path; the
+ *          CLI `tr pair --json` remains as a fallback for non-agent
+ *          scenarios.
  *
  *   GET  /plugin/totalreclaw/pair/finish?sid=<sid>
  *        → returns the browser pairing page (HTML + inline JS + CSS).
@@ -37,6 +53,12 @@
  *   - NO environment-variable reads. All config values flow in via
  *     `PairHttpConfig`; callers read from `CONFIG` in `config.ts`.
  *
+ * Adding `openRemotePairSession` (which dials an outbound WebSocket to
+ * the relay) keeps this file env=N, net=Y → the env-harvesting rule
+ * requires BOTH an env read AND a request trigger in the same file;
+ * the relay base URL arrives via `PairHttpConfig.relayBaseUrl` (caller-
+ * injected), never read from the environment here.
+ *
  * Logging: NEVER logs the secondary code, the mnemonic, the gateway
  * private key, or raw request bodies. Session ids and status
  * transitions are logged at info/warn levels for diagnostics.
@@ -44,9 +66,11 @@
 import { consumePairSession, getPairSession, registerFailedSecondaryCode, rejectPairSession, transitionPairSession, MAX_SECONDARY_CODE_ATTEMPTS, } from './pair-session-store.js';
 import { compareSecondaryCodesCT, decryptPairingPayload } from './pair-crypto.js';
 import { renderPairPage } from './pair-page.js';
+import { awaitPhraseUpload, openRemotePairSession, } from './pair-remote-client.js';
 /**
- * Build the four handlers. The caller registers each with
- * `api.registerHttpRoute({ path, handler })`.
+ * Build the route handlers. The caller registers each with
+ * `api.registerHttpRoute({ path, handler })`. When `cfg.relayBaseUrl` is
+ * set, the bundle also carries the in-process `/pair/init` handler.
  */
 export function buildPairRoutes(cfg) {
     const apiBase = cfg.apiBase.replace(/\/+$/, '');
@@ -283,7 +307,117 @@ export function buildPairRoutes(cfg) {
             mode: session.mode,
         });
     }
-    return {
+    // ---------------------------------------------------------------
+    // 3.3.14 — In-process pair trigger (the 30s-subprocess-kill 502 fix)
+    // ---------------------------------------------------------------
+    //
+    // Defined unconditionally so the handler identity is stable for the
+    // lifetime of the bundle; it short-circuits with 503 when no relay
+    // URL was wired. Only attached to the returned bundle + registered
+    // as a route when `cfg.relayBaseUrl` is set (see the return below).
+    async function handleInit(req, res) {
+        if (!methodAllowed(req, ['GET'])) {
+            sendJson(res, 405, { error: 'method_not_allowed' });
+            return;
+        }
+        const relay = cfg.relayBaseUrl;
+        if (!relay) {
+            // Caller did not wire a relay URL — the in-process route is inert.
+            sendJson(res, 503, { error: 'init_not_configured' });
+            return;
+        }
+        // 1. Open the relay WebSocket IN-PROCESS (the gateway process owns the
+        //    socket). This is the fix: the WS is no longer held by a CLI
+        //    subprocess, so OpenClaw's 30s shell-tool timeout cannot kill it
+        //    and the relay never sees a mid-pair disconnect → no more 502 on
+        //    /pair/respond.
+        let session;
+        try {
+            const openOpts = {
+                relayBaseUrl: relay,
+                mode: cfg.initPairMode ?? 'either',
+            };
+            if (cfg.initWebSocketImpl) {
+                openOpts.webSocketImpl = cfg.initWebSocketImpl;
+            }
+            session = await openRemotePairSession(openOpts);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            cfg.logger.warn(`pair-http /init: relay session open failed: ${msg}`);
+            sendJson(res, 502, { error: 'relay_open_failed', detail: msg });
+            return;
+        }
+        const parsedExpiresMs = Date.parse(session.expiresAt);
+        const expiresAtMs = Number.isFinite(parsedExpiresMs)
+            ? parsedExpiresMs
+            : now() + 5 * 60_000;
+        // 2. Respond IMMEDIATELY with the URL + PIN + sid (relay token) +
+        //    expiry. The agent reads this and surfaces the URL+PIN to the
+        //    user. The relay token here plays the `sid` role for agent-side
+        //    correlation (parity with the CLI JSON payload shape).
+        sendJson(res, 200, {
+            v: 1,
+            sid: session.token,
+            url: session.url,
+            pin: session.pin,
+            mode: session.mode,
+            expires_at_ms: expiresAtMs,
+        });
+        // 3. Start the background wait IN THE GATEWAY PROCESS. We do NOT
+        //    await this from the request handler — the HTTP response has
+        //    already been sent. The promise resolves when the browser
+        //    uploads the encrypted phrase (the relay pushes a `forward`
+        //    frame), the gateway decrypts locally, and `completePairing`
+        //    writes credentials.json + flips onboarding state. Errors are
+        //    logged but never reach the HTTP response (it's already gone).
+        //
+        //    The injected `completePairing` callback receives the mnemonic
+        //    + a session-shaped object. We adapt the relay session to the
+        //    `PairSession`-like shape the existing handler signature
+        //    expects; only the fields completePairing actually reads are
+        //    populated, the rest default. The mnemonic is the load-bearing
+        //    field (it writes credentials.json); the session shape carries
+        //    sid/mode for log correlation.
+        void (async () => {
+            try {
+                const result = await awaitPhraseUpload(session, {
+                    phraseValidator: validate,
+                    timeoutMs: cfg.initAwaitTimeoutMs,
+                    completePairing: async ({ mnemonic }) => {
+                        // Adapt the relay session to the PairSession-like shape the
+                        // existing CompletePairingHandler signature expects. Only
+                        // sid + mode are load-bearing for log correlation; the
+                        // crypto fields are unused (decryption already happened).
+                        const sessionLike = {
+                            sid: session.token,
+                            mode: session.mode === 'generate' ? 'generate' : 'import',
+                        };
+                        return cfg.completePairing({ mnemonic, session: sessionLike });
+                    },
+                });
+                if (result.state === 'active') {
+                    cfg.logger.info(`pair-http /init: session ${redactSid(session.token)} completed in-process; onboarding active`);
+                }
+                else {
+                    cfg.logger.warn(`pair-http /init: session ${redactSid(session.token)} completion non-active: ${result.error ?? 'unknown'}`);
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                // Timeouts are expected when the user closes the browser without
+                // completing; log at info so a benign expire doesn't look like an
+                // error in the gateway log.
+                if (msg.includes('timeout') || msg.includes('closed')) {
+                    cfg.logger.info(`pair-http /init: session ${redactSid(session.token)} expired/closed before completion`);
+                }
+                else {
+                    cfg.logger.warn(`pair-http /init: session ${redactSid(session.token)} failed: ${msg}`);
+                }
+            }
+        })();
+    }
+    const bundle = {
         finishPath: `${apiBase}/finish`,
         startPath: `${apiBase}/start`,
         respondPath: `${apiBase}/respond`,
@@ -295,6 +429,15 @@ export function buildPairRoutes(cfg) {
             status: handleStatus,
         },
     };
+    // Only surface the in-process /init route when a relay URL is wired.
+    // Older callers that construct the bundle without `relayBaseUrl` get
+    // the original four-route shape (back-compat for tests + any external
+    // consumers of buildPairRoutes).
+    if (cfg.relayBaseUrl) {
+        bundle.initPath = `${apiBase}/init`;
+        bundle.handlers.init = handleInit;
+    }
+    return bundle;
 }
 // ---------------------------------------------------------------------------
 // Internals: body reading, response helpers, validation

package/dist/tr-cli.js

@@ -51,7 +51,7 @@ const STATE_PATH = CONFIG.onboardingStatePath;
 // Auto-synced by skill/scripts/sync-version.mjs from skill/plugin/package.json::version.
 // Do not edit by hand — running tests will catch drift but the publish workflow
 // rewrites this constant at the start of every npm/ClawHub publish.
-const PLUGIN_VERSION = '3.3.12-rc.13';
+const PLUGIN_VERSION = '3.3.12-rc.15';
 function die(msg, code = 1) {
     process.stderr.write(`tr: ${msg}\n`);
     process.exit(code);

package/index.ts

@@ -4192,6 +4192,17 @@ const plugin = {
         sessionsPath: CONFIG.pairSessionsPath,
         apiBase: '/plugin/totalreclaw/pair',
         logger: api.logger,
+        // 3.3.14 — wire the relay URL so buildPairRoutes exposes the
+        // in-process `/pair/init` route. The gateway process opens the
+        // relay WebSocket directly (via openRemotePairSession from
+        // pair-remote-client.ts), eliminating the 30s-subprocess-kill
+        // 502 that the CLI path (tr pair) hit when OpenClaw's shell
+        // tool killed the subprocess mid-pair. relayBaseUrl is sourced
+        // from CONFIG.pairRelayUrl (config.ts reads it from the env
+        // once, centrally) — never read from the environment inside
+        // pair-http.ts (scanner-surface rule).
+        relayBaseUrl: CONFIG.pairRelayUrl,
+        initPairMode: 'either',
         validateMnemonic: (p) => validateMnemonic(p, wordlist),
         completePairing: async ({ mnemonic }) => {
           // Write credentials.json + flip state to 'active' via
@@ -4252,7 +4263,19 @@ const plugin = {
       api.registerHttpRoute!({ path: bundle.startPath, handler: bundle.handlers.start, auth: 'plugin' });
       api.registerHttpRoute!({ path: bundle.respondPath, handler: bundle.handlers.respond, auth: 'plugin' });
       api.registerHttpRoute!({ path: bundle.statusPath, handler: bundle.handlers.status, auth: 'plugin' });
-      api.logger.info('TotalReclaw: registered 4 QR-pairing HTTP routes synchronously');
+      // 3.3.14 — in-process pair trigger. The bundle exposes initPath +
+      // handlers.init ONLY when relayBaseUrl is wired (always true here,
+      // since CONFIG.pairRelayUrl has a built-in default). Registered
+      // with auth: 'plugin' (same as the other pair routes) so the
+      // agent's localhost curl reaches it without a gateway bearer
+      // token. The route opens the relay WS in the gateway process →
+      // survives shell-tool timeouts, retries, SIGUSR1 reloads.
+      if (bundle.initPath && bundle.handlers.init) {
+        api.registerHttpRoute!({ path: bundle.initPath, handler: bundle.handlers.init, auth: 'plugin' });
+        api.logger.info('TotalReclaw: registered 5 QR-pairing HTTP routes synchronously (incl. in-process /pair/init)');
+      } else {
+        api.logger.info('TotalReclaw: registered 4 QR-pairing HTTP routes synchronously (in-process /pair/init not wired — no relay URL)');
+      }
     } else {
       api.logger.warn(
         'api.registerHttpRoute is unavailable on this OpenClaw version — /totalreclaw pair will not work. ' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.12-rc.13",
+  "version": "3.3.12-rc.15",
   "description": "End-to-end encrypted, agent-portable memory for OpenClaw and any LLM-agent runtime. XChaCha20-Poly1305 with protobuf v4 + on-chain Memory Taxonomy v1 (claim / preference / directive / commitment / episode / summary).",
   "type": "module",
   "keywords": [
@@ -68,7 +68,7 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json --noCheck",
     "verify-tarball": "node ../scripts/verify-tarball.mjs",
-    "test": "npx tsx batch-gate.test.ts && npx tsx manifest-shape.test.ts && npx tsx config-schema.test.ts && npx tsx config.test.ts && npx tsx relay-headers.test.ts && npx tsx scope-address-visible.test.ts && npx tsx llm-profile-reader.test.ts && npx tsx llm-client.test.ts && npx tsx llm-client-retry.test.ts && npx tsx llm-client-json-mode.test.ts && npx tsx gateway-url.test.ts && npx tsx retype-setscope.test.ts && npx tsx tool-gating.test.ts && npx tsx onboarding-noninteractive.test.ts && npx tsx pair-cli-json.test.ts && npx tsx pair-qr.test.ts && npx tsx pair-remote-client.test.ts && npx tsx qa-bug-report.test.ts && npx tsx nonce-serialization.test.ts && npx tsx phrase-safety-registry.test.ts && npx tsx test_issue_92_onnx_download_ux.test.ts && npx tsx onboard-pair-only.test.ts && npx tsx import-state.test.ts && npx tsx import-time-smoke.test.ts && npx tsx install-staging-cleanup.test.ts && npx tsx partial-install-detection.test.ts && npx tsx install-reload-idempotency.test.ts && npx tsx json-stdout-cleanliness.test.ts && npx tsx url-binding.test.ts && npx tsx fs-helpers.test.ts && npx tsx pair-cli-default-mode.test.ts && npx tsx embedding-fallback-tag.test.ts && npx tsx staging-banner-gate.test.ts && npx tsx restart-auth.test.ts && npx tsx inbound-user-tracker.test.ts && npx tsx register-command-name.test.ts && npx tsx skill-md-hybrid-primary.test.ts && npx tsx tr-cli-json-output.test.ts && npx tsx import-upgrade-cli.test.ts && npx tsx postinstall-validate.test.ts && npx tsx credential-provider.test.ts && npx tsx memory-runtime.test.ts && npx tsx tools.test.ts && npx tsx register-native.test.ts && npx tsx relay.test.ts && npx tsx vault-crypto.test.ts && npx tsx entry-env.test.ts && npx tsx trajectory-poller.test.ts",
+    "test": "npx tsx batch-gate.test.ts && npx tsx manifest-shape.test.ts && npx tsx config-schema.test.ts && npx tsx config.test.ts && npx tsx relay-headers.test.ts && npx tsx scope-address-visible.test.ts && npx tsx llm-profile-reader.test.ts && npx tsx llm-client.test.ts && npx tsx llm-client-retry.test.ts && npx tsx llm-client-json-mode.test.ts && npx tsx gateway-url.test.ts && npx tsx retype-setscope.test.ts && npx tsx tool-gating.test.ts && npx tsx onboarding-noninteractive.test.ts && npx tsx pair-cli-json.test.ts && npx tsx pair-qr.test.ts && npx tsx pair-remote-client.test.ts && npx tsx pair-http.test.ts && npx tsx pair-http-route-registration.test.ts && npx tsx pair-http-init.test.ts && npx tsx qa-bug-report.test.ts && npx tsx nonce-serialization.test.ts && npx tsx phrase-safety-registry.test.ts && npx tsx test_issue_92_onnx_download_ux.test.ts && npx tsx onboard-pair-only.test.ts && npx tsx import-state.test.ts && npx tsx import-time-smoke.test.ts && npx tsx install-staging-cleanup.test.ts && npx tsx partial-install-detection.test.ts && npx tsx install-reload-idempotency.test.ts && npx tsx json-stdout-cleanliness.test.ts && npx tsx url-binding.test.ts && npx tsx fs-helpers.test.ts && npx tsx pair-cli-default-mode.test.ts && npx tsx embedding-fallback-tag.test.ts && npx tsx staging-banner-gate.test.ts && npx tsx restart-auth.test.ts && npx tsx inbound-user-tracker.test.ts && npx tsx register-command-name.test.ts && npx tsx skill-md-native.test.ts &&npx tsx tr-cli-json-output.test.ts && npx tsx import-upgrade-cli.test.ts && npx tsx postinstall-validate.test.ts && npx tsx credential-provider.test.ts && npx tsx memory-runtime.test.ts && npx tsx tools.test.ts && npx tsx register-native.test.ts && npx tsx relay.test.ts && npx tsx vault-crypto.test.ts && npx tsx entry-env.test.ts && npx tsx trajectory-poller.test.ts",
     "smoke:dist": "npx tsx dist-esm-smoke.test.ts",
     "check-scanner": "node ../scripts/check-scanner.mjs",
     "check-version-drift": "node ../scripts/check-version-drift.mjs",

package/pair-http.ts

@@ -2,7 +2,23 @@
  * pair-http — gateway-side HTTP route handlers for the v3.3.0 QR-pairing
  * flow. Registered via `api.registerHttpRoute` from `index.ts`.
  *
- * Three endpoints (all under /plugin/totalreclaw/pair/):
+ * Five endpoints (all under /plugin/totalreclaw/pair/):
+ *
+ *   GET  /plugin/totalreclaw/pair/init
+ *        → IN-PROCESS pair trigger (3.3.14). Opens the relay WebSocket
+ *          directly in the gateway process via `openRemotePairSession`
+ *          (from pair-remote-client.ts), returns `{url, pin, sid,
+ *          expires_at_ms}` immediately so the agent can surface URL+PIN
+ *          to the user, and starts a BACKGROUND `awaitPhraseUpload` that
+ *          blocks on the WS for the browser's encrypted phrase, decrypts
+ *          locally, and invokes the injected `completePairing` callback
+ *          (writes credentials.json + flips onboarding state). The WS
+ *          lives in the gateway process — immune to the shell-tool's
+ *          30s subprocess timeout that killed the `tr pair` CLI path
+ *          (relay returned 502 on /pair/respond when the subprocess
+ *          died). This is the primary agent-facilitated pair path; the
+ *          CLI `tr pair --json` remains as a fallback for non-agent
+ *          scenarios.
  *
  *   GET  /plugin/totalreclaw/pair/finish?sid=<sid>
  *        → returns the browser pairing page (HTML + inline JS + CSS).
@@ -37,6 +53,12 @@
  *   - NO environment-variable reads. All config values flow in via
  *     `PairHttpConfig`; callers read from `CONFIG` in `config.ts`.
  *
+ * Adding `openRemotePairSession` (which dials an outbound WebSocket to
+ * the relay) keeps this file env=N, net=Y → the env-harvesting rule
+ * requires BOTH an env read AND a request trigger in the same file;
+ * the relay base URL arrives via `PairHttpConfig.relayBaseUrl` (caller-
+ * injected), never read from the environment here.
+ *
  * Logging: NEVER logs the secondary code, the mnemonic, the gateway
  * private key, or raw request bodies. Session ids and status
  * transitions are logged at info/warn levels for diagnostics.
@@ -56,6 +78,11 @@ import {
 } from './pair-session-store.js';
 import { compareSecondaryCodesCT, decryptPairingPayload } from './pair-crypto.js';
 import { renderPairPage } from './pair-page.js';
+import {
+  awaitPhraseUpload,
+  openRemotePairSession,
+  type RemotePairSession,
+} from './pair-remote-client.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -99,7 +126,7 @@ export type CompletePairingHandler = (inputs: {
 export interface PairHttpConfig {
   /** Absolute path to pair-sessions.json. */
   sessionsPath: string;
-  /** Pathname prefix the three routes live under. */
+  /** Pathname prefix the routes live under. */
   apiBase: string;
   /** Writes credentials + flips state. Injected from index.ts. */
   completePairing: CompletePairingHandler;
@@ -111,6 +138,33 @@ export interface PairHttpConfig {
   maxBodyBytes?: number;
   /** If set, override BIP-39 validator for tests. Default does a word-count + wordlist check. */
   validateMnemonic?: (phrase: string) => boolean;
+  /**
+   * Relay base URL for the in-process `/pair/init` route (3.3.14). When
+   * set, `buildPairRoutes` exposes an `init` handler that opens the relay
+   * WebSocket directly in the gateway process (via `openRemotePairSession`).
+   * When omitted, the `init` handler is omitted from the bundle — older
+   * callers that haven't been updated still get the original 4 routes.
+   * Caller sources this from `CONFIG.pairRelayUrl`; NEVER read from the
+   * environment here (scanner-surface rule).
+   */
+  relayBaseUrl?: string;
+  /**
+   * Pair mode advertised in the relay open-frame for `/pair/init`.
+   * Defaults to 'either' (the relay will render both generate + import
+   * panels). Callers can pin 'generate' or 'import'.
+   */
+  initPairMode?: 'generate' | 'import' | 'either';
+  /**
+   * Override the WebSocket constructor used by `openRemotePairSession`
+   * for the `/pair/init` route. Tests inject a stub; production leaves
+   * this unset so the real `ws` client is used.
+   */
+  initWebSocketImpl?: typeof import('ws').WebSocket;
+  /**
+   * Override the forward-frame await timeout (ms) for the in-process
+   * background await. Defaults to the 5-minute relay TTL.
+   */
+  initAwaitTimeoutMs?: number;
 }
 
 /**
@@ -133,23 +187,32 @@ interface PairRespondBody {
  * Shape returned so the plugin wiring can invoke each handler directly.
  * Callers normally pass each one to `api.registerHttpRoute` — but we
  * also expose them in an object for tests.
+ *
+ * `initPath` / `handlers.init` are present ONLY when `PairHttpConfig`
+ * supplied a `relayBaseUrl` (3.3.14 in-process pair route). Older
+ * callers that omit it get back the original four-route bundle.
  */
 export interface PairRouteBundle {
   finishPath: string;
   startPath: string;
   respondPath: string;
   statusPath: string;
+  /** Present only when `cfg.relayBaseUrl` is set (in-process pair route). */
+  initPath?: string;
   handlers: {
     finish: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
     start: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
     respond: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
     status: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+    /** Present only when `cfg.relayBaseUrl` is set (in-process pair route). */
+    init?: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
   };
 }
 
 /**
- * Build the four handlers. The caller registers each with
- * `api.registerHttpRoute({ path, handler })`.
+ * Build the route handlers. The caller registers each with
+ * `api.registerHttpRoute({ path, handler })`. When `cfg.relayBaseUrl` is
+ * set, the bundle also carries the in-process `/pair/init` handler.
  */
 export function buildPairRoutes(cfg: PairHttpConfig): PairRouteBundle {
   const apiBase = cfg.apiBase.replace(/\/+$/, '');
@@ -402,7 +465,124 @@ export function buildPairRoutes(cfg: PairHttpConfig): PairRouteBundle {
     });
   }
 
-  return {
+  // ---------------------------------------------------------------
+  // 3.3.14 — In-process pair trigger (the 30s-subprocess-kill 502 fix)
+  // ---------------------------------------------------------------
+  //
+  // Defined unconditionally so the handler identity is stable for the
+  // lifetime of the bundle; it short-circuits with 503 when no relay
+  // URL was wired. Only attached to the returned bundle + registered
+  // as a route when `cfg.relayBaseUrl` is set (see the return below).
+  async function handleInit(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    if (!methodAllowed(req, ['GET'])) {
+      sendJson(res, 405, { error: 'method_not_allowed' });
+      return;
+    }
+    const relay = cfg.relayBaseUrl;
+    if (!relay) {
+      // Caller did not wire a relay URL — the in-process route is inert.
+      sendJson(res, 503, { error: 'init_not_configured' });
+      return;
+    }
+
+    // 1. Open the relay WebSocket IN-PROCESS (the gateway process owns the
+    //    socket). This is the fix: the WS is no longer held by a CLI
+    //    subprocess, so OpenClaw's 30s shell-tool timeout cannot kill it
+    //    and the relay never sees a mid-pair disconnect → no more 502 on
+    //    /pair/respond.
+    let session: RemotePairSession;
+    try {
+      const openOpts: Parameters<typeof openRemotePairSession>[0] = {
+        relayBaseUrl: relay,
+        mode: cfg.initPairMode ?? 'either',
+      };
+      if (cfg.initWebSocketImpl) {
+        openOpts.webSocketImpl = cfg.initWebSocketImpl;
+      }
+      session = await openRemotePairSession(openOpts);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      cfg.logger.warn(`pair-http /init: relay session open failed: ${msg}`);
+      sendJson(res, 502, { error: 'relay_open_failed', detail: msg });
+      return;
+    }
+
+    const parsedExpiresMs = Date.parse(session.expiresAt);
+    const expiresAtMs = Number.isFinite(parsedExpiresMs)
+      ? parsedExpiresMs
+      : now() + 5 * 60_000;
+
+    // 2. Respond IMMEDIATELY with the URL + PIN + sid (relay token) +
+    //    expiry. The agent reads this and surfaces the URL+PIN to the
+    //    user. The relay token here plays the `sid` role for agent-side
+    //    correlation (parity with the CLI JSON payload shape).
+    sendJson(res, 200, {
+      v: 1,
+      sid: session.token,
+      url: session.url,
+      pin: session.pin,
+      mode: session.mode,
+      expires_at_ms: expiresAtMs,
+    });
+
+    // 3. Start the background wait IN THE GATEWAY PROCESS. We do NOT
+    //    await this from the request handler — the HTTP response has
+    //    already been sent. The promise resolves when the browser
+    //    uploads the encrypted phrase (the relay pushes a `forward`
+    //    frame), the gateway decrypts locally, and `completePairing`
+    //    writes credentials.json + flips onboarding state. Errors are
+    //    logged but never reach the HTTP response (it's already gone).
+    //
+    //    The injected `completePairing` callback receives the mnemonic
+    //    + a session-shaped object. We adapt the relay session to the
+    //    `PairSession`-like shape the existing handler signature
+    //    expects; only the fields completePairing actually reads are
+    //    populated, the rest default. The mnemonic is the load-bearing
+    //    field (it writes credentials.json); the session shape carries
+    //    sid/mode for log correlation.
+    void (async (): Promise<void> => {
+      try {
+        const result = await awaitPhraseUpload(session, {
+          phraseValidator: validate,
+          timeoutMs: cfg.initAwaitTimeoutMs,
+          completePairing: async ({ mnemonic }) => {
+            // Adapt the relay session to the PairSession-like shape the
+            // existing CompletePairingHandler signature expects. Only
+            // sid + mode are load-bearing for log correlation; the
+            // crypto fields are unused (decryption already happened).
+            const sessionLike = {
+              sid: session.token,
+              mode: session.mode === 'generate' ? 'generate' : 'import',
+            } as PairSession;
+            return cfg.completePairing({ mnemonic, session: sessionLike });
+          },
+        });
+        if (result.state === 'active') {
+          cfg.logger.info(
+            `pair-http /init: session ${redactSid(session.token)} completed in-process; onboarding active`,
+          );
+        } else {
+          cfg.logger.warn(
+            `pair-http /init: session ${redactSid(session.token)} completion non-active: ${result.error ?? 'unknown'}`,
+          );
+        }
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // Timeouts are expected when the user closes the browser without
+        // completing; log at info so a benign expire doesn't look like an
+        // error in the gateway log.
+        if (msg.includes('timeout') || msg.includes('closed')) {
+          cfg.logger.info(
+            `pair-http /init: session ${redactSid(session.token)} expired/closed before completion`,
+          );
+        } else {
+          cfg.logger.warn(`pair-http /init: session ${redactSid(session.token)} failed: ${msg}`);
+        }
+      }
+    })();
+  }
+
+  const bundle: PairRouteBundle = {
     finishPath: `${apiBase}/finish`,
     startPath: `${apiBase}/start`,
     respondPath: `${apiBase}/respond`,
@@ -414,6 +594,15 @@ export function buildPairRoutes(cfg: PairHttpConfig): PairRouteBundle {
       status: handleStatus,
     },
   };
+  // Only surface the in-process /init route when a relay URL is wired.
+  // Older callers that construct the bundle without `relayBaseUrl` get
+  // the original four-route shape (back-compat for tests + any external
+  // consumers of buildPairRoutes).
+  if (cfg.relayBaseUrl) {
+    bundle.initPath = `${apiBase}/init`;
+    bundle.handlers.init = handleInit;
+  }
+  return bundle;
 }
 
 // ---------------------------------------------------------------------------

package/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "totalreclaw",
-  "version": "3.3.12-rc.13",
+  "version": "3.3.12-rc.15",
   "description": "End-to-end encrypted memory for AI agents — portable, yours forever. XChaCha20-Poly1305 E2EE: server never sees plaintext.",
   "author": "TotalReclaw Team",
   "license": "MIT",

package/tr-cli.ts

@@ -68,7 +68,7 @@ const STATE_PATH = CONFIG.onboardingStatePath;
 // Auto-synced by skill/scripts/sync-version.mjs from skill/plugin/package.json::version.
 // Do not edit by hand — running tests will catch drift but the publish workflow
 // rewrites this constant at the start of every npm/ClawHub publish.
-const PLUGIN_VERSION = '3.3.12-rc.13';
+const PLUGIN_VERSION = '3.3.12-rc.15';
 
 function die(msg: string, code = 1): never {
   process.stderr.write(`tr: ${msg}\n`);