@totalreclaw/totalreclaw 3.3.9-rc.3 → 3.3.9-rc.4

package/CHANGELOG.md

@@ -4,6 +4,22 @@ 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.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.9-rc.4
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz

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.9-rc.4",
   "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.9-rc.4",
   "description": "End-to-end encrypted memory for AI agents — portable, yours forever. XChaCha20-Poly1305 E2EE: server never sees plaintext.",
   "author": "TotalReclaw Team",
   "license": "MIT",