@totalreclaw/totalreclaw 3.3.9-rc.3 → 3.3.10-rc.2

package/CHANGELOG.md

@@ -4,6 +4,42 @@ All notable changes to `@totalreclaw/totalreclaw` (the OpenClaw plugin) are docu
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.3.10-rc.2] — 2026-05-05
+
+Critical 502 fix via shell-side detach (rc.10-rc.1's plugin-side `child_process` approach was reverted — scanner blocks `child_process` imports anywhere in the plugin tree). Pedro's manual QA on rc.4 confirmed the persistent 502 `gateway_disconnected` was NOT caused by relay idle close (PR #14's 5s+immediate WS keepalive was deployed and verified at sha `0ff812a`). Real cause: each `openclaw plugins install` writes `plugins.installs.totalreclaw.*` to the gateway config, triggering a deferred SIGUSR1 reload that eventually fires and kills any in-flight foreground subprocess — including the agent shell-tool's `node tr-cli pair --json` which holds the relay WS until the browser uploads the encrypted phrase.
+
+### Fixed
+
+- **`tr pair` invocation now uses shell-side `setsid -f` for session detachment.** SKILL.md and the public OpenClaw setup guide instruct the agent to spawn `tr pair --json` via `setsid -f` so the WS-holding subprocess is in its own POSIX session, untethered from the agent shell-tool's process group. The pair process survives any subsequent gateway SIGUSR1 reload, and the URL+PIN payload is captured to a tmp file the moment the WS handshake completes (~100-500ms typical). Verified live on pop-os 2026-05-05: `setsid -f node tr-cli.js pair --json > /tmp/...` returned exit 0 immediately, the detached `node tr-cli pair --json` process kept running across a `kill -USR1 1` to PID 1 in the container, and the URL+PIN was readable from the tmp file at +2s.
+
+  This needs no plugin-code change — it's a shell-side mechanism the agent uses when invoking the existing CLI. The plugin tree stays free of `child_process` imports (which would trip OpenClaw's runtime scanner same as the 3.3.2-era `postinstall.mjs` block).
+
+- **CLI install path corrected for OpenClaw 2026.5.x.** SKILL.md and `docs/guides/openclaw-setup.md` previously referenced `~/.openclaw/extensions/totalreclaw/dist/tr-cli.js` exclusively. Modern OpenClaw 2026.5.x npm-managed plugins install under `~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/...` (verified via `openclaw plugins inspect totalreclaw` → "Install path: ~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw"). Both paths now appear in the recommended `TR_CLI` resolver:
+  ```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)"
+  ```
+  Resolver picks the first existing path, so the agent works on both modern and legacy installs without per-version branching.
+
+### Reverted
+
+- **3.3.10-rc.1 plugin-side `child_process` detach** — scanner-sim blocked the publish on `import { spawn } from 'node:child_process'` in `tr-cli.ts`. OpenClaw's runtime scanner (which inspects the full tarball regardless of file role — same rule that killed `postinstall.mjs` in 3.3.2) would have blocked install at the user's gateway even if the publish had been bypassed. rc.10-rc.2 takes the equivalent detach via shell-side `setsid -f`, which OpenClaw's exec subsystem treats as a normal shell command.
+
+## [3.3.9-rc.4] — 2026-05-05
+
+Defensive patch hardening `patchOpenClawConfig()` Fix #1 against a startup crash loop observed on Pedro's pop-os QA host on 2026-05-05.
+
+### Fixed
+
+- **Slot patch crash-loop guard:** `patchOpenClawConfig()` previously wrote `plugins.slots.memory = "totalreclaw"` whenever the slot was unset. On 2026-05-05 pop-os crashed in a restart loop (~13 attempts, 12:10–12:23 UTC) with `Gateway failed to start: Error: Invalid config at openclaw.json. plugins.slots.memory: plugin not found: totalreclaw. Run "openclaw doctor --fix" to repair, then retry.` Root cause: a previous register() invocation had written the slot, but a later config reset / migration wiped `plugins.installs.totalreclaw` while leaving `plugins.slots.memory` behind. OpenClaw's startup validator hard-fails when `slots.memory` points to a name with no install record. The crash self-resolved at 12:24 once the user re-ran `openclaw plugins install`.
+
+  **Fix:** Slot patch is now gated on `cfg.plugins.installs?.totalreclaw?.version` being a non-empty string. Without an install record we leave `slots.memory` alone — neither writing it (preventing future crash loops) nor cleaning it up (not our responsibility). The hooks (Fix #2) and Telegram streaming (Fix #3) patches are unchanged — they write under `plugins.entries` and `channels` which are inert without an install record and cannot trip the validator.
+
+### Implementation notes
+
+- `cfg.plugins.installs.totalreclaw.version` is the install pipeline's authoritative signal that the plugin is on disk and registered with the gateway. It's populated by `openclaw plugins install` and survives gateway restarts; a config reset that drops it indicates the plugin install record is no longer valid and slot should not point to it.
+- 7 new tests in `fs-helpers.test.ts`: empty-config-no-installs (slot NOT written), empty-config-with-installs (slot WRITTEN), installs-without-version (slot still gated), stale-slot-no-install (we don't auto-clean), plus updated fixtures across the existing 4 cases. 81/81 green.
+- Pre-existing tests for the hooks and Telegram streaming patches continue to pass unchanged — those code paths are not gated.
+
 ## [3.3.9-rc.3] — 2026-05-05
 
 Patch release silencing the verbose Telegram streaming output Pedro reported during 3.3.9-rc.2 manual QA ("Krilling… 🔧 Exec: run openclaw skills" repeated 3-4× per shell command in the same chat bubble).

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: totalreclaw
 description: "Install + set up TotalReclaw encrypted memory for OpenClaw, then use tr CLI for remember / recall. Trigger on 'install TotalReclaw', 'set up TotalReclaw', 'restore my recovery phrase', or any remember / recall request."
-version: 3.3.9-rc.3
+version: 3.3.10-rc.2
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -50,8 +50,16 @@ If you find yourself about to say any of these, STOP. The correct statement is:
 
 OpenClaw 2026.5.2 has a tool-policy-pipeline bug (issue #223) that strips non-bundled plugin tools before they reach the agent toolset. **3.3.9-rc.1 makes the `tr` CLI the PRIMARY path for all memory operations.** Native tools (`totalreclaw_*`) are kept for back-compat with older OpenClaw versions where they work, but the agent MUST NOT depend on them. Use `tr` from your shell tool for everything.
 
-**The `tr` binary is installed at:** `~/.openclaw/extensions/totalreclaw/dist/tr-cli.js`
-**Always invoke via:** `node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js <cmd> [--json]`
+**The `tr` binary is installed at one of two paths depending on OpenClaw version:**
+- Modern (2026.5.x npm-managed): `~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cli.js`
+- Legacy (extensions tree): `~/.openclaw/extensions/totalreclaw/dist/tr-cli.js`
+
+**Resolve the path once at the top of your shell session and reuse:**
+```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)"
+```
+Then invoke as `node "$TR_CLI" <cmd> [--json]`.
+
 **Never rely on `totalreclaw_*` tool binding** — it may not be available due to issue #223.
 
 ## User-visible line set (THIS IS ALL YOU SAY)
@@ -81,41 +89,49 @@ If existing credentials are detected (step "Check for existing credentials" belo
 
    If either shell call fails with `command not found` / ENOENT / "not authorized" (managed-service or shell-restricted environment), tell the user verbatim *"Your environment doesn't expose the OpenClaw CLI to me. Please install `totalreclaw` from your service's plugins / skills UI, then reply `done`."* Wait for `done` and skip to step 3.
 
-2. **Verify CLI works — emit user-visible line 2 when successful.** Run:
-   ```
-   node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js status --json
+2. **Verify CLI works — emit user-visible line 2 when successful.** Resolve `TR_CLI` and run:
+   ```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
    ```
    Parse the JSON. When you get `{"version": "...", "hybrid_mode": true, ...}`, emit user-visible line 2 with the version substituted. **Do NOT wait for tool binding. Do NOT issue `/totalreclaw-restart`. Do NOT check whether `totalreclaw_pair` is in your toolset.** The CLI works independently of tool binding. If `tr status` exits non-zero or the file doesn't exist, wait 5s and retry once — it may still be installing.
 
 3. **Check for existing credentials (silent unless found).** Run `test -s ~/.totalreclaw/credentials.json`. If it exists and is non-empty, emit *"✓ TotalReclaw is already set up."* and stop.
 
-4. **Set up the user's TotalReclaw account IMMEDIATELY — no consent gate.** As soon as `tr status --json` returns and credentials are not present, run:
+4. **Set up the user's TotalReclaw account IMMEDIATELY — no consent gate.** As soon as `tr status --json` returns and credentials are not present, run pair in DETACHED mode. CRITICAL: a foreground `node tr-cli pair` is killed when the gateway fires its post-install SIGUSR1 reload (3.3.10 finding from Pedro's 2026-05-05 QA — relay logs `gateway_disconnected` 502 on `/respond`). Use `setsid -f` so the pair process is in its own session and survives any subsequent gateway SIGUSR1 reload. The handshake URL+PIN is written to a tmp file the moment the WS opens (~100-500ms typical):
+   ```bash
+   PAIR_OUT="/tmp/tr-pair-out-$(date +%s).json"
+   setsid -f node "$TR_CLI" pair --json > "$PAIR_OUT" 2>&1 < /dev/null
+   sleep 2
+   cat "$PAIR_OUT"
    ```
-   node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js pair --json
-   ```
-   This is UNCONDITIONAL. Do NOT ask "Would you like to set up an account?" or "Want me to pair now?". The user installed TotalReclaw — setup is the expected next step. The URL + PIN itself is the consent moment (the user can simply not open the page to opt out). Parse the JSON response `{"url": "...", "pin": "...", "expires_at": "..."}` and emit user-visible line 3. If `tr pair --json` is not available (old install), fall back to `totalreclaw_pair` tool or `openclaw totalreclaw pair generate --url-pin-only`.
+   This is UNCONDITIONAL. Do NOT ask "Would you like to set up an account?" or "Want me to pair now?". The user installed TotalReclaw — setup is the expected next step. The URL + PIN itself is the consent moment (the user can simply not open the page to opt out). Parse the JSON response `{"url": "...", "pin": "...", "expires_at_ms": ...}` and emit user-visible line 3. If the cat output is empty after 2s, sleep 2 more seconds and try again (relay handshake can take up to 4s on a cold network). If `tr pair --json` is not available (old install), fall back to `totalreclaw_pair` tool or `openclaw totalreclaw pair generate --url-pin-only`.
 
-5. **Verify and confirm (silent until line 4).** After the user says `done`, re-run `test -s ~/.totalreclaw/credentials.json`. If missing, the PIN expired — run `tr pair --json` again and resend line 3 once. If present, emit user-visible line 4 and stop.
+5. **Verify and confirm (silent until line 4).** After the user says `done`, re-run `test -s ~/.totalreclaw/credentials.json`. If missing, the PIN expired — repeat the `setsid -f node "$TR_CLI" pair --json` block and resend line 3 once. If present, emit user-visible line 4 and stop.
 
 ## `tr` CLI reference (hybrid-primary commands)
 
 Always use `--json` flag when running from shell for machine-parseable output. Plain text mode is for direct user invocation only.
 
 ```bash
+# (Resolve TR_CLI once at the top of your session)
+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)"
+
 # Status check (parse JSON to confirm install + onboarding state)
-node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js status --json
-# Returns: {"version":"3.3.9-rc.1","onboarded":false,"next_step":"pair","tool_count":17,"hybrid_mode":true}
+node "$TR_CLI" status --json
+# Returns: {"version":"3.3.10-rc.2","onboarded":false,"next_step":"pair","tool_count":17,"hybrid_mode":true}
 
-# Pair / account setup
-node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js pair --json
-# Returns: {"url":"https://...","pin":"123456","expires_at":"2026-05-05T..."}
+# Pair / account setup — ALWAYS run via setsid -f to survive gateway restarts
+PAIR_OUT="/tmp/tr-pair-out-$(date +%s).json"
+setsid -f node "$TR_CLI" pair --json > "$PAIR_OUT" 2>&1 < /dev/null && sleep 2 && cat "$PAIR_OUT"
+# Returns: {"v":1,"sid":"...","url":"https://...","pin":"123456","mode":"generate","expires_at_ms":...,"qr_ascii":"..."}
 
-# Remember a fact
-node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js remember --json "I work at Graph Foundation"
+# Remember a fact (foreground OK — non-blocking single-shot HTTP call)
+node "$TR_CLI" remember --json "I work at Graph Foundation"
 # Returns: {"ok":true,"id":"...","claim_count":N}
 
 # Recall memories
-node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js recall --json "where does the user work" --limit 5
+node "$TR_CLI" recall --json "where does the user work" --limit 5
 # Returns: {"results":[{"text":"...","score":0.8},...]}
 ```
 
@@ -138,12 +154,12 @@ NEVER echo / generate / ask the user to paste a recovery phrase in chat. NEVER i
 ## Usage (post-setup)
 
 - Stable user facts / preferences / identity / "remember X":
-  ```
-  node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js remember --json "<fact>"
+  ```bash
+  node "$TR_CLI" remember --json "<fact>"
   ```
 - First-person factual query ("do I / what's my / where do I…"):
-  ```
-  node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js recall --json "<query>" --limit 5
+  ```bash
+  node "$TR_CLI" recall --json "<query>" --limit 5
   ```
   Recall FIRST, then answer from returned facts. If 0 results, say so.
 - For forget / pin / unpin / retype / set_scope — use native tools if available, or ask user to run `openclaw totalreclaw` subcommand.

package/dist/fs-helpers.js

@@ -933,9 +933,14 @@ export function resolveOnboardingState(credentialsPath, statePath) {
  * Auto-patch `~/.openclaw/openclaw.json` with the entries required by
  * OpenClaw 2026.5.x for clean operation (issues #225 + #226 + verbosity):
  *
- *   1. `plugins.slots.memory = "totalreclaw"`
+ *   1. `plugins.slots.memory = "totalreclaw"` (gated on install record)
  *      Claim the memory slot so the plugin loads instead of deferring to
- *      the built-in `memory-core` tenant.
+ *      the built-in `memory-core` tenant. As of 3.3.9-rc.4 this fix is
+ *      gated on `plugins.installs.totalreclaw.version` being present —
+ *      writing the slot without an install record produces a startup
+ *      crash loop ("plugins.slots.memory: plugin not found: totalreclaw")
+ *      that survives container restarts until `openclaw plugins install`
+ *      repopulates the install record.
  *
  *   2. `plugins.entries.totalreclaw.hooks.allowConversationAccess = true`
  *      Grant the plugin access to `agent_end` and `before_agent_start`
@@ -985,13 +990,49 @@ export function patchOpenClawConfig(configPath) {
             cfg.plugins = {};
         }
         let mutated = false;
-        // --- Fix #1: plugins.slots.memory = "totalreclaw" ---
-        if (typeof cfg.plugins.slots !== 'object' || cfg.plugins.slots === null) {
-            cfg.plugins.slots = {};
-        }
-        if (cfg.plugins.slots.memory !== 'totalreclaw') {
-            cfg.plugins.slots.memory = 'totalreclaw';
-            mutated = true;
+        // --- Fix #1: plugins.slots.memory = "totalreclaw" (gated on install) ---
+        //
+        // DEFENSIVE GATE (3.3.9-rc.4 — 2026-05-05): only write the slot when
+        // the plugin is genuinely INSTALLED (`plugins.installs.totalreclaw`
+        // present with a `version`). Writing the slot unconditionally
+        // produced a startup crash loop on Pedro's pop-os QA host on
+        // 2026-05-05 — after a config reset, `plugins.installs.totalreclaw`
+        // was missing but a previously-written `slots.memory = "totalreclaw"`
+        // had survived. OpenClaw's startup validator refuses to start with
+        //
+        //   Gateway failed to start: Error: Invalid config at openclaw.json.
+        //   plugins.slots.memory: plugin not found: totalreclaw
+        //   Run "openclaw doctor --fix" to repair, then retry.
+        //
+        // The container restart-loop drained ~13 attempts (12:10-12:23 UTC)
+        // until `openclaw plugins install` was re-run and re-populated
+        // `plugins.installs.totalreclaw`. With this gate, future installs
+        // that wipe `plugins.installs` (config reset, `doctor --fix`,
+        // migration tools) cannot regress into the same boot loop — slot is
+        // only ever written when the install record exists, and the install
+        // record is the install pipeline's authoritative signal that the
+        // plugin is on disk and registered with the gateway.
+        //
+        // The hooks patch (Fix #2) and Telegram streaming patch (Fix #3) are
+        // not gated this way — they write under `plugins.entries` and
+        // `channels` which are inert without an install record, so they can
+        // never trip the validator.
+        const installsRoot = cfg.plugins.installs;
+        const installEntry = typeof installsRoot === 'object' && installsRoot !== null
+            ? installsRoot.totalreclaw
+            : undefined;
+        const pluginIsInstalled = typeof installEntry === 'object'
+            && installEntry !== null
+            && typeof installEntry.version === 'string'
+            && installEntry.version.length > 0;
+        if (pluginIsInstalled) {
+            if (typeof cfg.plugins.slots !== 'object' || cfg.plugins.slots === null) {
+                cfg.plugins.slots = {};
+            }
+            if (cfg.plugins.slots.memory !== 'totalreclaw') {
+                cfg.plugins.slots.memory = 'totalreclaw';
+                mutated = true;
+            }
         }
         // --- Fix #2: plugins.entries.totalreclaw.hooks.allowConversationAccess = true ---
         if (typeof cfg.plugins.entries !== 'object' || cfg.plugins.entries === null) {

package/fs-helpers.ts

@@ -1149,9 +1149,14 @@ export type OpenClawConfigPatchResult = 'patched' | 'unchanged' | 'skipped' | 'e
  * Auto-patch `~/.openclaw/openclaw.json` with the entries required by
  * OpenClaw 2026.5.x for clean operation (issues #225 + #226 + verbosity):
  *
- *   1. `plugins.slots.memory = "totalreclaw"`
+ *   1. `plugins.slots.memory = "totalreclaw"` (gated on install record)
  *      Claim the memory slot so the plugin loads instead of deferring to
- *      the built-in `memory-core` tenant.
+ *      the built-in `memory-core` tenant. As of 3.3.9-rc.4 this fix is
+ *      gated on `plugins.installs.totalreclaw.version` being present —
+ *      writing the slot without an install record produces a startup
+ *      crash loop ("plugins.slots.memory: plugin not found: totalreclaw")
+ *      that survives container restarts until `openclaw plugins install`
+ *      repopulates the install record.
  *
  *   2. `plugins.entries.totalreclaw.hooks.allowConversationAccess = true`
  *      Grant the plugin access to `agent_end` and `before_agent_start`
@@ -1207,13 +1212,50 @@ export function patchOpenClawConfig(
 
     let mutated = false;
 
-    // --- Fix #1: plugins.slots.memory = "totalreclaw" ---
-    if (typeof cfg.plugins.slots !== 'object' || cfg.plugins.slots === null) {
-      cfg.plugins.slots = {};
-    }
-    if (cfg.plugins.slots.memory !== 'totalreclaw') {
-      cfg.plugins.slots.memory = 'totalreclaw';
-      mutated = true;
+    // --- Fix #1: plugins.slots.memory = "totalreclaw" (gated on install) ---
+    //
+    // DEFENSIVE GATE (3.3.9-rc.4 — 2026-05-05): only write the slot when
+    // the plugin is genuinely INSTALLED (`plugins.installs.totalreclaw`
+    // present with a `version`). Writing the slot unconditionally
+    // produced a startup crash loop on Pedro's pop-os QA host on
+    // 2026-05-05 — after a config reset, `plugins.installs.totalreclaw`
+    // was missing but a previously-written `slots.memory = "totalreclaw"`
+    // had survived. OpenClaw's startup validator refuses to start with
+    //
+    //   Gateway failed to start: Error: Invalid config at openclaw.json.
+    //   plugins.slots.memory: plugin not found: totalreclaw
+    //   Run "openclaw doctor --fix" to repair, then retry.
+    //
+    // The container restart-loop drained ~13 attempts (12:10-12:23 UTC)
+    // until `openclaw plugins install` was re-run and re-populated
+    // `plugins.installs.totalreclaw`. With this gate, future installs
+    // that wipe `plugins.installs` (config reset, `doctor --fix`,
+    // migration tools) cannot regress into the same boot loop — slot is
+    // only ever written when the install record exists, and the install
+    // record is the install pipeline's authoritative signal that the
+    // plugin is on disk and registered with the gateway.
+    //
+    // The hooks patch (Fix #2) and Telegram streaming patch (Fix #3) are
+    // not gated this way — they write under `plugins.entries` and
+    // `channels` which are inert without an install record, so they can
+    // never trip the validator.
+    const installsRoot = cfg.plugins.installs;
+    const installEntry = typeof installsRoot === 'object' && installsRoot !== null
+      ? installsRoot.totalreclaw
+      : undefined;
+    const pluginIsInstalled = typeof installEntry === 'object'
+      && installEntry !== null
+      && typeof installEntry.version === 'string'
+      && installEntry.version.length > 0;
+
+    if (pluginIsInstalled) {
+      if (typeof cfg.plugins.slots !== 'object' || cfg.plugins.slots === null) {
+        cfg.plugins.slots = {};
+      }
+      if (cfg.plugins.slots.memory !== 'totalreclaw') {
+        cfg.plugins.slots.memory = 'totalreclaw';
+        mutated = true;
+      }
     }
 
     // --- Fix #2: plugins.entries.totalreclaw.hooks.allowConversationAccess = true ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.9-rc.3",
+  "version": "3.3.10-rc.2",
   "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": [

package/skill.json

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