@totalreclaw/totalreclaw 3.3.11-rc.4 → 3.3.11-rc.5

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.11-rc.5] — 2026-05-07
+
+Trajectory poller hardening: cap extractions per poll iteration + skip stale trajectory files. Pedro's 2026-05-07 zai 429 cascade was caused by ~5 old session files all crossing the extract threshold in the same poll → 5 back-to-back LLM calls in seconds → daily quota tripped. Today's chat memories were lost because every extraction call returned 0 facts (LLM rejected with rate-limit).
+
+### Changed
+
+- **Cap = 1 extraction per poll iteration.** When multiple session files cross the extract-interval threshold in the same 60 s poll, only the first fires the LLM call. The rest defer to subsequent polls. Their `turnsAccum` and `offset` state is preserved, so they don't lose progress — they just stagger. With the default 60 s poll interval, 5 backlogged files take 5 minutes to drain instead of 5 seconds. Free-tier LLM rate limits don't trip.
+- **Stale-trajectory skip (>7 days mtime).** A user installing TotalReclaw on a host with months of OpenClaw session log history won't get a retroactive extraction backlog. Files with mtime older than 7 days are baseline-snapshotted (offset captured) but skip the extraction path entirely. If the user later resumes an old session, the offset is current and only net-new content extracts.
+
+### Implementation notes
+
+- `MAX_EXTRACTIONS_PER_POLL = 1` constant in `trajectory-poller.ts`. Sequential `for` loop already guarantees serialization within a poll; the cap just stops issuing additional LLM calls once the first one completes.
+- `STALE_TRAJECTORY_AGE_MS = 7 * 24 * 60 * 60 * 1000`. Stale files get a one-time offset record (`state[file] = {offset: stat.size, turnsAccum: 0}`) so they're never re-stat'd repeatedly. If the user re-engages an old session (writes new content → mtime refreshes), the stale-skip check fails and normal extraction resumes from the recorded offset.
+- 4 new test cases in `trajectory-poller.test.ts`: cap=1 multi-session deferral, second-poll-no-op-after-deferred-cap, stale-file skip (>7 days), recent-file (<7 days) NOT skipped. 44/44 green.
+- 92/92 fs-helpers + 21/21 register-command-name + 37/37 skill-md + 21/21 tr-cli-json + 44/44 trajectory-poller + 10/10 manifest-shape. check-scanner: 129 files, 0 flags.
+
+### Won't fix here
+
+- Pop-os specific delayed-load anomaly (~58 min from rc.4 install to plugin first-load) — couldn't reproduce in fresh container; pop-os has accumulated state from many install/wipe cycles. Auto-QA confirmed clean fresh-install path.
+- The retroactive-backlog scenario itself remains: if a user has ACTIVE sessions (mtime < 7 days) with high turn counts, they'll still drain over multiple polls. With cap=1 and 60 s interval, 5 active-but-backlogged files = 5 minutes to drain. Acceptable.
+
 ## [3.3.11-rc.4] — 2026-05-07
 
 Fix #4 added to `patchOpenClawConfig()`: the **populated-allowlist plugin-skip bug** that broke every realistic install path.

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.11-rc.4
+version: 3.3.11-rc.5
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz

package/dist/tr-cli.js

@@ -41,7 +41,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.11-rc.4';
+const PLUGIN_VERSION = '3.3.11-rc.5';
 function die(msg, code = 1) {
     process.stderr.write(`tr: ${msg}\n`);
     process.exit(code);

package/dist/trajectory-poller.js

@@ -41,6 +41,15 @@ import os from 'node:os';
 import path from 'node:path';
 const DEFAULT_POLL_INTERVAL_MS = 60_000;
 const STATE_FILE = path.join(os.homedir(), '.totalreclaw', 'extract-state.json');
+/**
+ * Skip trajectory files older than this. A user who installs
+ * TotalReclaw on a host with months of OpenClaw session log history
+ * shouldn't get a retroactive extraction backlog — we only care about
+ * ongoing chat from now forward (3.3.11-rc.5). Files with mtime older
+ * than this threshold get a one-time offset snapshot so they're never
+ * re-scanned, and skip the extraction path entirely.
+ */
+const STALE_TRAJECTORY_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 /**
  * Start the trajectory poller. Runs an initial poll after 5 s, then
  * every `pollIntervalMs` (default 60 s). Returns a handle the caller
@@ -62,15 +71,51 @@ export function startTrajectoryPoller(deps, opts = {}) {
                 return;
             const extractInterval = deps.getExtractInterval();
             let stateChanged = false;
+            // 3.3.11-rc.5: cap extractions per poll iteration. Pedro's
+            // 2026-05-07 zai 429 cascade was caused by N session files all
+            // crossing the extract threshold in the same poll → N back-to-back
+            // LLM calls trip the rate-limiter (especially on free tiers).
+            // With cap=1, extra files defer to the next poll iteration
+            // (60 s later by default). Their turnsAccum is preserved across
+            // polls so they don't lose progress.
+            let extractionsThisPoll = 0;
+            const MAX_EXTRACTIONS_PER_POLL = 1;
             for (const file of files) {
+                // Stale-file skip: trajectory files untouched for STALE_TRAJECTORY_AGE_MS
+                // are likely abandoned sessions (old test runs, dead chats). Skip them
+                // entirely — don't burn LLM budget on extraction from stale content
+                // that the user has effectively forgotten about.
+                let mtimeMs = 0;
+                try {
+                    mtimeMs = fs.statSync(file).mtimeMs;
+                }
+                catch {
+                    continue;
+                }
+                if (Date.now() - mtimeMs > STALE_TRAJECTORY_AGE_MS) {
+                    // Lazy-record offset so we don't repeatedly re-scan stale files —
+                    // if the user later resumes this session, the offset is already
+                    // current and we'll only extract net-new content.
+                    if (!state[file]) {
+                        try {
+                            state[file] = { offset: fs.statSync(file).size, turnsAccum: 0 };
+                            stateChanged = true;
+                        }
+                        catch { /* ignore */ }
+                    }
+                    continue;
+                }
                 const lastEntry = state[file] ?? { offset: 0, turnsAccum: 0 };
                 const { messages, newOffset } = parseNewMessages(file, lastEntry.offset);
                 if (newOffset === lastEntry.offset)
                     continue; // nothing new
                 const turnsAdded = countTurns(messages);
                 const turnsAccum = lastEntry.turnsAccum + turnsAdded;
-                const shouldExtract = turnsAccum >= extractInterval && messages.length >= 2;
+                const shouldExtract = turnsAccum >= extractInterval &&
+                    messages.length >= 2 &&
+                    extractionsThisPoll < MAX_EXTRACTIONS_PER_POLL;
                 if (shouldExtract) {
+                    extractionsThisPoll++;
                     deps.logger.info(`extractd: ${path.basename(file)} -> ${turnsAccum}/${extractInterval} turns; running extraction (${messages.length} messages)`);
                     const existing = deps.isDedupEnabled() ? await deps.getDedupCandidates(20, messages) : [];
                     const rawFacts = await deps.runExtraction(messages, 'turn', existing, undefined);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.11-rc.4",
+  "version": "3.3.11-rc.5",
   "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.11-rc.4",
+  "version": "3.3.11-rc.5",
   "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

@@ -52,7 +52,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.11-rc.4';
+const PLUGIN_VERSION = '3.3.11-rc.5';
 
 function die(msg: string, code = 1): never {
   process.stderr.write(`tr: ${msg}\n`);

package/trajectory-poller.ts

@@ -127,6 +127,15 @@ export interface TrajectoryPollerHandle {
 
 const DEFAULT_POLL_INTERVAL_MS = 60_000;
 const STATE_FILE = path.join(os.homedir(), '.totalreclaw', 'extract-state.json');
+/**
+ * Skip trajectory files older than this. A user who installs
+ * TotalReclaw on a host with months of OpenClaw session log history
+ * shouldn't get a retroactive extraction backlog — we only care about
+ * ongoing chat from now forward (3.3.11-rc.5). Files with mtime older
+ * than this threshold get a one-time offset snapshot so they're never
+ * re-scanned, and skip the extraction path entirely.
+ */
+const STALE_TRAJECTORY_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 
 /**
  * Start the trajectory poller. Runs an initial poll after 5 s, then
@@ -152,17 +161,54 @@ export function startTrajectoryPoller(
 
       const extractInterval = deps.getExtractInterval();
       let stateChanged = false;
+      // 3.3.11-rc.5: cap extractions per poll iteration. Pedro's
+      // 2026-05-07 zai 429 cascade was caused by N session files all
+      // crossing the extract threshold in the same poll → N back-to-back
+      // LLM calls trip the rate-limiter (especially on free tiers).
+      // With cap=1, extra files defer to the next poll iteration
+      // (60 s later by default). Their turnsAccum is preserved across
+      // polls so they don't lose progress.
+      let extractionsThisPoll = 0;
+      const MAX_EXTRACTIONS_PER_POLL = 1;
 
       for (const file of files) {
+        // Stale-file skip: trajectory files untouched for STALE_TRAJECTORY_AGE_MS
+        // are likely abandoned sessions (old test runs, dead chats). Skip them
+        // entirely — don't burn LLM budget on extraction from stale content
+        // that the user has effectively forgotten about.
+        let mtimeMs = 0;
+        try {
+          mtimeMs = fs.statSync(file).mtimeMs;
+        } catch {
+          continue;
+        }
+        if (Date.now() - mtimeMs > STALE_TRAJECTORY_AGE_MS) {
+          // Lazy-record offset so we don't repeatedly re-scan stale files —
+          // if the user later resumes this session, the offset is already
+          // current and we'll only extract net-new content.
+          if (!state[file]) {
+            try {
+              state[file] = { offset: fs.statSync(file).size, turnsAccum: 0 };
+              stateChanged = true;
+            } catch { /* ignore */ }
+          }
+          continue;
+        }
+
         const lastEntry = state[file] ?? { offset: 0, turnsAccum: 0 };
         const { messages, newOffset } = parseNewMessages(file, lastEntry.offset);
         if (newOffset === lastEntry.offset) continue; // nothing new
 
         const turnsAdded = countTurns(messages);
         const turnsAccum = lastEntry.turnsAccum + turnsAdded;
-        const shouldExtract = turnsAccum >= extractInterval && messages.length >= 2;
+        const shouldExtract =
+          turnsAccum >= extractInterval &&
+          messages.length >= 2 &&
+          extractionsThisPoll < MAX_EXTRACTIONS_PER_POLL;
 
         if (shouldExtract) {
+          extractionsThisPoll++;
+
           deps.logger.info(
             `extractd: ${path.basename(file)} -> ${turnsAccum}/${extractInterval} turns; running extraction (${messages.length} messages)`,
           );