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

package/CHANGELOG.md

@@ -4,6 +4,44 @@ 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.6] — 2026-05-07
+
+UX fix: mandatory ack-before-first-tool-call on install. Pedro's rc.5 user QA found the agent went silent for ~60 s while running `openclaw plugins install` before emitting the first user-visible line. From the user's POV the prompt looked unanswered. This RC strengthens SKILL.md + the quickstart guide to require line 1 BEFORE the first shell tool call, with reassuring wait-time copy.
+
+### Changed
+
+- **SKILL.md user-visible line 1 reworded** from `Installing TotalReclaw…` to `Setting up TotalReclaw — this takes about a minute…` — adds explicit wait-time signal so the user knows to wait rather than resend.
+- **New "MANDATORY ACK BEFORE FIRST TOOL CALL" section** in SKILL.md top-level rules. Calls out forbidden vs required ordering: line 1 must precede any shell tool call (no `openclaw plugins install` → 60 s silent → emit line 1).
+- **Silence rules updated**: skipping line 1 entirely is now explicitly forbidden (previously the rule only forbade extra narration between lines, not omission of line 1).
+- **`docs/guides/openclaw-setup-quickstart.md` mirrors the change** with the same wait-time copy and an explicit "Line 1 fires BEFORE the first shell tool call — not after" sub-section.
+
+### Implementation notes
+
+- 4 new assertions in `skill-md-hybrid-primary.test.ts`: MANDATORY ACK section present, line 1 wait-time wording, Forbidden vs Required order documented, "Skipping line 1 entirely" listed as forbidden. 41/41 green.
+- All other test suites unchanged: 92/92 fs-helpers + 21/21 register-command-name + 21/21 tr-cli-json + 44/44 trajectory-poller + 10/10 manifest-shape. check-scanner: 129 files, 0 flags.
+- Pure documentation + spec change. No runtime code modified. Same poller behavior as rc.5.
+
+## [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.6
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -61,6 +61,15 @@ The word "pair" is internal jargon — never use it in user-visible prose. The u
 
 **Emit ONLY the user-visible lines listed below. Do not narrate tool calls. Do not describe what you're doing or about to do. Errors are the only allowed deviation, and only as a single tight line.** The expected user-facing transcript for a healthy install is **4–5 short lines TOTAL**. Anything more is a SKILL violation. Telegram and similar transports edit the bot's messages live as your tool calls progress — every interim "Let me check…" / "Plugin loaded. Let me verify…" line shows up to the user as awkward edit churn, even if you "delete" it. The fix is to never emit it in the first place.
 
+### ⚡ MANDATORY ACK BEFORE FIRST TOOL CALL
+
+**User-visible line 1 MUST be your FIRST output — emitted BEFORE you run any shell tool, plugin install, or `tr` command.** Install + setup takes 1–2 minutes of silent tool-execution; without an immediate ack the user assumes the request didn't register and may resend or abandon. The ack tells them work is happening.
+
+The ack is unconditional. It fires the moment you decide to install / set up TotalReclaw — even before you've resolved `TR_CLI`, even before you've checked whether the plugin is already installed, even before the first `openclaw plugins install` shell call. Send line 1, THEN start the work.
+
+Forbidden order (silent-then-narrate): ❌ run `openclaw plugins install` → wait 60s → emit line 1.
+Required order (ack-then-work): ✅ emit line 1 → run `openclaw plugins install` silently → emit line 2 when `tr status` returns.
+
 ## ⛔ FORBIDDEN ACTIONS (4 hard rules from 2026-05-05 QA)
 
 These specific actions break the pair flow. Everything else is governed by the "emit only the numbered user-visible lines" rule above.
@@ -93,8 +102,8 @@ Then invoke as `node "$TR_CLI" <cmd> [--json]`.
 
 Speak only these lines, in order. Substitute the bracketed placeholders with the real values. No prefaces. No suffixes. No narration.
 
-1. (start of install)
-   > Installing TotalReclaw…
+1. (FIRST output, emitted BEFORE any shell tool call — see "MANDATORY ACK" rule above)
+   > Setting up TotalReclaw — this takes about a minute…
 2. (after install + CLI verify — `tr status` works)
    > ✓ Installed (totalreclaw &lt;version&gt;, hybrid mode)
 3. (account-setup URL + PIN, IMMEDIATELY after `tr pair --json` returns — no consent gate)
@@ -114,8 +123,9 @@ Do NOT emit transitional / narrative lines between any of the four user-visible
 - ❌ "Need to pair. Let me kick that off:" → silent. Just run the `setsid -f` block. Emit line 3 when URL+PIN returns. ALSO never use the word "pair" in user-facing text — see vocabulary table above.
 - ❌ "Standing by." → silent. Acknowledgements between lines are noise.
 - ❌ Any "Let me X" / "Now I'll Y" / "Just give me a second" prelude.
+- ❌ **Skipping line 1 entirely and going straight to shell tool calls.** Line 1 ack must precede the first tool call. Silent install = user thinks the prompt didn't register.
 
-The transcript Pedro should see is exactly four messages — the four numbered lines, nothing in between.
+The transcript Pedro should see is exactly four messages — the four numbered lines, nothing in between. Line 1 fires immediately. Lines 2–4 fire as work completes. No prose between.
 
 ## How does TotalReclaw work? (canonical answer for user questions)
 

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.6';
 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.6",
   "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.6",
   "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.6';
 
 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)`,
           );