@totalreclaw/totalreclaw 3.3.12-rc.9 → 3.3.12

package/tr-cli.ts

@@ -1,12 +1,17 @@
 #!/usr/bin/env node
 /**
- * tr — TotalReclaw hybrid CLI (3.3.9-rc.1 primary architecture)
+ * tr — TotalReclaw CLI (explicit-write + curation surface)
  *
- * OpenClaw 2026.5.2 has a tool-policy-pipeline bug (issue #223) that strips non-bundled plugin
- * tools before they reach the agent toolset. In 3.3.9-rc.1, this CLI is the PRIMARY path for
- * all agent memory operations (not a fallback). The agent runs `tr <cmd> --json` from shell;
- * hooks (before_agent_start, agent_end, message_received, before_reset) continue via the
- * unbroken hook code path.
+ * Scope (Phase 3.3 — OpenClaw native integration): recall is now NATIVE.
+ * The agent reads memories via OpenClaw's bundled `memory_search` /
+ * `memory_get` tools (backed by the MemoryPluginCapability + TrMemorySearchManager
+ * adapter registered in `index.ts`). This CLI no longer ships a recall path.
+ *
+ * What's still CLI-only (no native agent-facing surface):
+ *   - explicit write (`tr remember`) — the conventional memory contract has no
+ *     agent-facing write tool; auto-extraction stores facts via hooks.
+ *   - curation / lifecycle (`tr forget`, `tr export`).
+ *   - onboarding + pairing (`tr status`, `tr pair`).
  *
  * Phrase-safety: this CLI reads credentials.json (mnemonic at rest) but NEVER
  * prints the mnemonic to stdout, stderr, or any log. Phrase only enters via QR-pair
@@ -16,14 +21,12 @@
  *   tr status [--json]          — print onboarding + credentials state
  *   tr pair [--json]            — start a relay pairing session, print URL+PIN+QR
  *   tr remember [--json] <text> — store a memory in the encrypted vault (on-chain)
- *   tr recall [--json] [--limit N] <query> — search the encrypted vault (subgraph)
- *   tr forget [--json] <factId> — tombstone a memory on-chain
+ *   tr forget [--json] <factId> — tombstone a memory on-chain (find the id via memory_search)
  *   tr export [--json] [--format json|markdown] — dump all memories from the subgraph
  *
- * 3.3.12-rc.4 — switched remember/recall/forget/export from `/v1/store` and
+ * 3.3.12-rc.4 — switched remember/forget/export from `/v1/store` and
  * `/v1/search` (those endpoints were removed during the on-chain pivot —
- * relay returns 404) to the on-chain UserOp + subgraph paths used by the
- * native MCP tools (`totalreclaw_remember`, `totalreclaw_recall`, etc).
+ * relay returns 404) to the on-chain UserOp + subgraph paths.
  *
  * --json flag: all agent-facing CLI calls MUST use --json for clean machine-parseable output.
  *              Plain text mode is for direct user CLI use only.
@@ -32,8 +35,6 @@
  * Usage from container: `docker exec tr-openclaw node ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js status --json`
  */
 
-import path from 'node:path';
-import os from 'node:os';
 import { randomUUID } from 'node:crypto';
 
 import { CONFIG, setRecoveryPhraseOverride } from './config.js';
@@ -43,7 +44,6 @@ import {
   deriveKeys,
   computeAuthKeyHash,
   encrypt,
-  decrypt,
   generateBlindIndices,
   generateContentFingerprint,
 } from './crypto.js';
@@ -56,10 +56,6 @@ import {
   PROTOBUF_VERSION_V4,
   type FactPayload,
 } from './subgraph-store.js';
-import {
-  searchSubgraph,
-  searchSubgraphBroadened,
-} from './subgraph-search.js';
 import { exportAllFacts } from './tr-cli-export-helper.js';
 
 // ---------------------------------------------------------------------------
@@ -72,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.9';
+const PLUGIN_VERSION = '3.3.12-rc.23';
 
 function die(msg: string, code = 1): never {
   process.stderr.write(`tr: ${msg}\n`);
@@ -90,15 +86,6 @@ function popFlag(args: string[], flag: string): [boolean, string[]] {
   return [true, [...args.slice(0, idx), ...args.slice(idx + 1)]];
 }
 
-/** Parse --limit N from args, returning [limit, cleanedArgs]. Default: defaultLimit. */
-function popLimitFlag(args: string[], defaultLimit: number): [number, string[]] {
-  const idx = args.indexOf('--limit');
-  if (idx === -1 || idx + 1 >= args.length) return [defaultLimit, args];
-  const n = parseInt(args[idx + 1], 10);
-  const limit = isNaN(n) || n < 1 ? defaultLimit : n;
-  return [limit, [...args.slice(0, idx), ...args.slice(idx + 2)]];
-}
-
 /** Parse --format VALUE from args, returning [value, cleanedArgs]. */
 function popOptionFlag(
   args: string[],
@@ -120,13 +107,6 @@ function toHexBlob(plaintext: string, encryptionKey: Buffer): string {
   return Buffer.from(b64, 'base64').toString('hex');
 }
 
-/** Inverse of toHexBlob — used by recall/export to decrypt subgraph blobs. */
-function fromHexBlob(hexBlob: string, encryptionKey: Buffer): string {
-  const hex = hexBlob.startsWith('0x') ? hexBlob.slice(2) : hexBlob;
-  const b64 = Buffer.from(hex, 'hex').toString('base64');
-  return decrypt(b64, encryptionKey);
-}
-
 // ---------------------------------------------------------------------------
 // Core init — minimal version of index.ts initialize()
 // ---------------------------------------------------------------------------
@@ -228,62 +208,27 @@ async function buildContext(): Promise<CliContext> {
 // ---------------------------------------------------------------------------
 
 async function cmdStatus(jsonMode: boolean): Promise<void> {
-  // Probe plugin manifest for version/hybridMode/toolCount.
-  let pluginVersion: string | undefined;
-  let bootCount: number | undefined;
-  let hybridMode = true; // default true in 3.3.9-rc.1 (hybrid-primary)
-  let toolCount: number | undefined;
-  let loadedAgeSec: number | undefined;
-
-  try {
-    const fs = await import('node:fs');
-    const candidatePaths = [
-      path.join(os.homedir(), '.openclaw', 'extensions', 'totalreclaw', '.loaded.json'),
-      path.join(os.homedir(), '.openclaw', 'npm', 'node_modules', '@totalreclaw', 'totalreclaw', 'dist', '.loaded.json'),
-    ];
-    const resolvedPath = candidatePaths.find((p) => fs.existsSync(p));
-    if (resolvedPath) {
-      const raw = fs.readFileSync(resolvedPath, 'utf-8');
-      const manifest = JSON.parse(raw) as {
-        version?: string;
-        bootCount?: number;
-        loadedAt?: number;
-        hybridMode?: boolean;
-        tools?: string[];
-      };
-      pluginVersion = manifest.version ?? PLUGIN_VERSION;
-      bootCount = manifest.bootCount;
-      hybridMode = manifest.hybridMode !== false; // default true
-      toolCount = manifest.tools?.length;
-      const ageMs = Date.now() - (manifest.loadedAt ?? 0);
-      loadedAgeSec = Math.round(ageMs / 1000);
-    }
-  } catch {
-    // Best-effort
-  }
-
-  // Check onboarding state
+  // Phase 3.4 retired the `.loaded.json` manifest — the writer was removed
+  // in 3.1 and the reader had nothing current to read. `tr status` now
+  // reports the static plugin version (from the CLI binary's own
+  // PLUGIN_VERSION constant) plus onboarding state. For per-boot history,
+  // consult the gateway log.
   const creds = loadCredentialsJson(CREDENTIALS_PATH);
   const onboarded = !!creds;
 
   if (jsonMode) {
     // JSON-first output for agent parsing
     const out: Record<string, unknown> = {
-      version: pluginVersion ?? PLUGIN_VERSION,
+      version: PLUGIN_VERSION,
       onboarded,
       next_step: onboarded ? 'none' : 'pair',
-      tool_count: toolCount ?? 17,
-      hybrid_mode: hybridMode,
     };
-    if (bootCount !== undefined) out.boot_count = bootCount;
-    if (loadedAgeSec !== undefined) out.loaded_age_sec = loadedAgeSec;
     log(JSON.stringify(out));
   } else {
     // Human-readable plain text for direct user CLI use
     printStatus(CREDENTIALS_PATH, STATE_PATH, process.stdout);
     process.stdout.write(
-      `\n  plugin:      ${pluginVersion ? `loaded (version=${pluginVersion}` + (bootCount !== undefined ? ` bootCount=${bootCount}` : '') + (loadedAgeSec !== undefined ? ` loaded=${loadedAgeSec}s ago` : '') + ')' : 'not found in .loaded.json'}\n` +
-      `  hybrid-mode: ${hybridMode ? 'yes (primary — use tr <cmd> --json)' : 'no'}\n` +
+      `\n  plugin:      loaded (version=${PLUGIN_VERSION})\n` +
       `  hooks:       before_agent_start, agent_end, message_received, before_reset\n`,
     );
   }
@@ -413,96 +358,6 @@ async function cmdRemember(rawArgs: string[]): Promise<void> {
   }
 }
 
-// ---------------------------------------------------------------------------
-// Command: recall
-// ---------------------------------------------------------------------------
-
-async function cmdRecall(rawArgs: string[]): Promise<void> {
-  const [jsonMode, argsAfterJson] = popFlag(rawArgs, '--json');
-  const [limit, argsAfterLimit] = popLimitFlag(argsAfterJson, 5);
-  const query = argsAfterLimit.join(' ').trim();
-  if (!query) {
-    die('Usage: tr recall [--json] [--limit N] <query>');
-  }
-
-  const ctx = await buildContext();
-
-  // Generate word trapdoors for blind search. The CLI does not run the
-  // ONNX embedder (that's a 700 MB lazy bundle in the gateway) so we send
-  // word-only trapdoors. The reranker in the native MCP path would add LSH
-  // trapdoors on top — we live without them here in exchange for a much
-  // smaller CLI footprint.
-  const trapdoors = generateBlindIndices(query);
-  const pool = Math.max(limit * 4, 20);
-
-  try {
-    let candidates = await searchSubgraph(
-      ctx.walletAddress,
-      trapdoors,
-      pool,
-      ctx.authKeyHex,
-    );
-
-    // Always run broadened search and merge — ensures vocabulary mismatches
-    // (e.g., "preferences" vs "prefer") don't cause recall failures. This
-    // mirrors the native tool path in index.ts (line 3978).
-    try {
-      const broadened = await searchSubgraphBroadened(
-        ctx.walletAddress,
-        pool,
-        ctx.authKeyHex,
-      );
-      const seen = new Set(candidates.map((r) => r.id));
-      for (const br of broadened) {
-        if (!seen.has(br.id)) candidates.push(br);
-      }
-    } catch {
-      // best-effort; broadened-only failures shouldn't block trapdoor results
-    }
-
-    const results: Array<{ text: string; score: number }> = [];
-
-    for (const c of candidates) {
-      try {
-        const docJson = fromHexBlob(c.encryptedBlob, ctx.encryptionKey);
-        const parsed = JSON.parse(docJson) as {
-          text?: string;
-          importance?: number;
-          metadata?: { importance?: number };
-        };
-        if (!parsed.text) continue;
-        // The CLI is intentionally simple — score by decayScore (importance
-        // proxy) instead of running the full BM25 + cosine reranker that
-        // the native MCP path uses. Agents calling the CLI typically just
-        // want the top-N by importance.
-        const decay = typeof c.decayScore === 'string'
-          ? parseInt(c.decayScore, 10)
-          : (c.decayScore as unknown as number);
-        const score = Number.isFinite(decay) ? decay / 10 : 0.5;
-        results.push({ text: parsed.text, score });
-      } catch {
-        // Skip undecryptable / non-JSON (digest blobs, tombstones, etc.)
-      }
-    }
-
-    // Sort by score descending, then trim to limit.
-    results.sort((a, b) => b.score - a.score);
-    const trimmed = results.slice(0, limit);
-
-    if (jsonMode) {
-      log(JSON.stringify({ results: trimmed }));
-    } else {
-      log(`Found ${trimmed.length} result(s) for: ${query}`);
-      for (const r of trimmed) {
-        log(`  [score=${r.score.toFixed(2)}] ${r.text}`);
-      }
-    }
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    die(`recall failed: ${msg}`);
-  }
-}
-
 // ---------------------------------------------------------------------------
 // Command: forget
 // ---------------------------------------------------------------------------
@@ -513,13 +368,13 @@ async function cmdForget(rawArgs: string[]): Promise<void> {
   if (!factId) {
     die('Usage: tr forget [--json] <factId>');
   }
-  // UUID-v4-ish shape check — same validation as the native totalreclaw_forget
-  // tool (index.ts line 4225). Prevents fabricated / natural-language IDs
-  // from reaching the UserOp path and silently no-op'ing on-chain.
+  // UUID-v4-ish shape check — same validation the old totalreclaw_forget
+  // tool applied. Prevents fabricated / natural-language IDs from reaching
+  // the UserOp path and silently no-op'ing on-chain.
   if (!/^[0-9a-f-]{8,}$/i.test(factId)) {
     die(
       `forget failed: "${factId.slice(0, 60)}" doesn't look like a memory ID. ` +
-        `Run \`tr recall --json <query>\` first and pass a result's id.`,
+        `Ask the agent to look it up via memory_search (or tr export) and pass a result's id.`,
     );
   }
 
@@ -640,8 +495,15 @@ async function main(): Promise<void> {
       break;
 
     case 'recall':
-      await cmdRecall(args.slice(1));
-      break;
+      // Retired in Phase 3.3 — recall is now native via the bundled
+      // memory_search / memory_get tools (MemoryPluginCapability). Surface
+      // a clear pointer instead of falling through to "unknown command"
+      // so agents / users running stale prompts get actionable guidance.
+      die(
+        'tr recall was retired — recall is now native. ' +
+          'The agent reads memories via the memory_search tool automatically; ' +
+          'use `tr export` to dump every memory outside the agent.',
+      );
 
     case 'forget':
       await cmdForget(args.slice(1));
@@ -651,26 +513,51 @@ async function main(): Promise<void> {
       await cmdExport(args.slice(1));
       break;
 
+    case 'import':
+    case 'upgrade':
+      // Import + upgrade run inside the gateway process (they need the
+      // plugin runtime — extraction pipeline, smart-import WASM, module-
+      // level auth state). The standalone `tr` binary is a separate Node
+      // script that does NOT load index.ts (would pull in the entire
+      // plugin runtime). Point users at the registerCli surface instead
+      // of silently no-op'ing or falling through to "unknown command".
+      die(
+        `${cmd} is not available on the standalone \`tr\` binary. ` +
+          `Run it on the gateway host via:\n` +
+          `  openclaw totalreclaw ${cmd === 'import' ? 'import from <source>' : 'upgrade'}${cmd === 'import' ? ' [--file <path>] [--dry-run] [--json]' : ' [--json]'}\n` +
+          (cmd === 'import'
+            ? `  openclaw totalreclaw import status [--id <importId>] [--json]\n` +
+              `  openclaw totalreclaw import abort <importId> [--json]\n` +
+              `Sources: mem0 | mcp-memory | chatgpt | claude | gemini`
+            : `Returns a Stripe checkout URL for Pro upgrade.`),
+      );
+
     case undefined:
     case '--help':
     case '-h':
       process.stdout.write(
-        `TotalReclaw hybrid CLI v${PLUGIN_VERSION} (primary mode — OpenClaw 2026.5.2+)\n\n` +
+        `TotalReclaw CLI v${PLUGIN_VERSION} (recall is native — memory_search tool)\n\n` +
         'Usage:\n' +
-        '  tr status [--json]                       — onboarding + plugin load state\n' +
-        '  tr pair [--json]                         — start a relay pairing session\n' +
-        '  tr remember [--json] <text>              — store a memory (on-chain UserOp)\n' +
-        '  tr recall [--json] [--limit N] <query>   — search memories (default limit: 5)\n' +
-        '  tr forget [--json] <factId>              — tombstone a memory on-chain\n' +
+        '  tr status [--json]                          — onboarding + plugin load state\n' +
+        '  tr pair [--json]                            — start a relay pairing session\n' +
+        '  tr remember [--json] <text>                 — store a memory (on-chain UserOp)\n' +
+        '  tr forget [--json] <factId>                 — tombstone a memory on-chain\n' +
         '  tr export [--json] [--format json|markdown] — dump every memory in the vault\n\n' +
+        'Recall: NOT a CLI command. The agent recalls via the bundled memory_search tool.\n' +
+        '        To dump memories outside the agent, use `tr export`.\n\n' +
+        'Import + Upgrade: NOT on the standalone `tr` binary. They run inside the gateway\n' +
+        '        process via the `openclaw totalreclaw` subcommand chain:\n' +
+        '          openclaw totalreclaw import from <source> [--file <path>] [--dry-run] [--json]\n' +
+        '          openclaw totalreclaw import status [--id <importId>] [--json]\n' +
+        '          openclaw totalreclaw import abort <importId> [--json]\n' +
+        '          openclaw totalreclaw upgrade [--json]\n' +
+        '        Sources: mem0 | mcp-memory | chatgpt | claude | gemini\n\n' +
         'Flags:\n' +
-        '  --json    Output machine-parseable JSON (required for agent shell calls)\n' +
-        '  --limit N Limit recall results (default: 5)\n\n' +
+        '  --json    Output machine-parseable JSON (required for agent shell calls)\n\n' +
         'JSON output shapes:\n' +
         '  status:   {"version":"...","onboarded":bool,"next_step":"pair|none","tool_count":N,"hybrid_mode":bool}\n' +
         '  pair:     {"url":"...","pin":"123456","expires_at":"..."}\n' +
         '  remember: {"ok":true,"id":"...","claim_count":N}\n' +
-        '  recall:   {"results":[{"text":"...","score":0.8}]}\n' +
         '  forget:   {"ok":true,"id":"...","tx_hash":"0x..."}\n' +
         '  export:   {"count":N,"facts":[{"id":"...","text":"...","metadata":{...},"created_at":"..."}]}\n\n' +
         'Environment:\n' +

package/trajectory-poller.ts

@@ -21,8 +21,59 @@
  *   existing extraction pipeline. Per-file byte-offset is tracked in
  *   ~/.totalreclaw/extract-state.json so we never re-process lines.
  *
- *   When the upstream OpenClaw bug is fixed, the agent_end hook starts
- *   firing again — both paths can coexist with offset-based dedup.
+ * RC1 capture strategy (Phase 4, 2026-06-22):
+ *   RC1 capture = POLLER-PRIMARY, FLUSH-SHADOWED. This poller is the
+ *   capture workhorse. OpenClaw's host-facing `flushPlanResolver`
+ *   (wired in native-memory.ts via buildFlushPlan) returns TR's
+ *   extraction plan so the memory slot is "complete" and the host CAN
+ *   drive flushes — but TR's encrypt→on-chain capture does NOT depend
+ *   on the host invoking the flush. The flush-driven capture path
+ *   (host flush → read scratch file → encrypt → on-chain) is NOT
+ *   wired on TR's side today; that is H2/RC2-gated. The poller
+ *   guarantees capture works regardless of host flush cadence: even
+ *   if the host never flushes, the poller still captures on its own
+ *   60 s schedule. This is the graceful-degradation stance —
+ *   recall-native + capture-poller meets both primary bars even if
+ *   H2 (host flush cadence) fails at the RC1 QA gate.
+ *
+ *   RC2 retires this poller IF H2 confirms the host invokes
+ *   flushPlanResolver at useful cadence. If H2 fails, the poller
+ *   stays as the long-term capture mechanism.
+ *
+ * Idempotency / offset-dedup:
+ *   The poller is idempotent across poller-restart and gateway-reload.
+ *   `extract-state.json` is the single source of truth for "what's
+ *   been consumed from each trajectory file": loadState() reads it at
+ *   the start of every poll iteration, parseNewMessages() only reads
+ *   bytes past the recorded offset, and the file is rewritten (via
+ *   saveState) only when at least one file's offset advanced. A
+ *   poller that crashes mid-extraction loses at most the in-flight
+ *   pass (state was not yet saved); the next poller re-reads from the
+ *   last persisted offset and re-runs the extraction — duplicate
+ *   facts are caught downstream by the dedup pass, and re-extraction
+ *   of the same slice is bounded to one retry (state then advances).
+ *
+ *   `parseNewMessages` caps newOffset at the last full newline so a
+ *   partially-flushed trailing line is re-read on the next poll
+ *   rather than dropped or double-counted.
+ *
+ * Cross-path double-write (NOT a risk today; RC2 work):
+ *   Today the poller is the only capture path that actually fires.
+ *   The agent_end / before_compaction / before_reset hook handlers
+ *   in index.ts still REGISTER storeExtractedFacts callbacks, but on
+ *   OpenClaw 2026.5.x the host never fires those events for
+ *   non-bundled plugins (the bug that motivated this poller), so in
+ *   practice the poller is the sole capture path. If a future
+ *   OpenClaw release un-blocks the hooks (or when the RC2
+ *   flush-driven capture path is wired), BOTH the poller AND the
+ *   parallel path would capture from overlapping state with NO
+ *   shared dedup — the hooks do NOT consult `extract-state.json`.
+ *   That is acceptable for RC1 (only the poller fires) but becomes
+ *   a real double-write risk at RC2. See the TODO(RC2/H2) marker on
+ *   STATE_FILE below for where the shared last-captured-offset
+ *   resolver would live. The earlier claim that "both paths can
+ *   coexist with offset-based dedup" was aspirational; no such
+ *   shared offset exists today.
  *
  * Module boundary (scanner constraint):
  *   This file does disk I/O (fs.read* on trajectory files + state file)
@@ -40,6 +91,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 // ---------------------------------------------------------------------------
 // Public surface
@@ -126,6 +178,22 @@ export interface TrajectoryPollerHandle {
 }
 
 const DEFAULT_POLL_INTERVAL_MS = 60_000;
+// Per-file offset tracker (poller's own source of truth for what's been
+// consumed from each trajectory file). Today this is consulted ONLY by the
+// poller — the agent_end / before_compaction / before_reset hooks in
+// index.ts do NOT read or write it, so if any of those hooks ever fire
+// alongside the poller they would double-capture from overlapping state.
+//
+// TODO(RC2/H2): when the flush-driven capture path is wired (host invokes
+// flushPlanResolver → TR reads the scratch file → encrypt → on-chain) OR
+// the upstream agent_end block is lifted, ALL capture paths MUST consult
+// a shared last-captured-offset resolver before encrypting. The simplest
+// shape is to expose loadState()/saveState() (or a `consumed(file)`
+// helper) to the hook handlers and the flush callback so they skip any
+// byte range the poller already consumed, and conversely the poller must
+// skip any range the hooks/flush path recorded. Until then, this file is
+// poller-private and there is no cross-path double-write risk (only the
+// poller fires on OpenClaw 2026.5.x).
 const STATE_FILE = path.join(os.homedir(), '.totalreclaw', 'extract-state.json');
 /**
  * Skip trajectory files older than this. A user who installs
@@ -137,20 +205,105 @@ const STATE_FILE = path.join(os.homedir(), '.totalreclaw', 'extract-state.json')
  */
 const STALE_TRAJECTORY_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 
+/**
+ * Module-global handle to the currently-running poller (rc.20, #402).
+ *
+ * OpenClaw's SIGUSR1 restarts are IN-PROCESS — the module cache survives, so a
+ * same-version re-register hits THIS module instance again. Without a guard,
+ * each re-register started a fresh setInterval on top of the previous one and
+ * live pollers accumulated (a fresh container boot was observed with 2 from
+ * boot double-register). `startTrajectoryPoller` stops the previous poller
+ * from this module instance before starting a new one.
+ */
+let activePoller: TrajectoryPollerHandle | null = null;
+
+/**
+ * Path to THIS module's own file, captured once at load. Each poll tick
+ * verifies it still exists AND is the same file (same inode + mtime); if the
+ * plugin dir was removed, or the file at this path was swapped for a different
+ * one (an old version uninstalled then a new version reinstalled at the SAME
+ * path within seconds — the gateway restart is an in-process signal, so the
+ * stale module instance survives), the poller self-terminates so a zombie
+ * module instance from a stale version can't keep submitting UserOps (rc.20,
+ * #402). An existence-only check missed the same-path reinstall case (review
+ * LOW-2, observed live: OpenClaw recreates dist at the same path in ~45s, so
+ * `existsSync` stayed true and the old-version poller ran on). Tests override
+ * this path via `opts.sentinelPath`.
+ */
+const MODULE_SENTINEL = fileURLToPath(import.meta.url);
+
+/** File-identity fingerprint used to detect a same-path replacement. */
+type SentinelIdentity = { ino: number; mtimeMs: number };
+
 /**
  * Start the trajectory poller. Runs an initial poll after 5 s, then
  * every `pollIntervalMs` (default 60 s). Returns a handle the caller
  * can use to stop polling and run one-shot polls in tests.
+ *
+ * Lifecycle guards (rc.20, #402): a previously-started poller from this module
+ * instance is stopped first (singleton), and each tick self-terminates if this
+ * module's file is gone.
  */
 export function startTrajectoryPoller(
   deps: TrajectoryPollerDeps,
-  opts: { pollIntervalMs?: number; stateFile?: string } = {},
+  opts: { pollIntervalMs?: number; stateFile?: string; sentinelPath?: string } = {},
 ): TrajectoryPollerHandle {
   const pollIntervalMs = opts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
   const stateFile = opts.stateFile ?? STATE_FILE;
+  const sentinelPath = opts.sentinelPath ?? MODULE_SENTINEL;
+
+  // Capture the sentinel's file identity (inode + mtime) once at start so each
+  // tick can tell "same file still there" from "different file swapped in at
+  // the same path" (reinstall/upgrade). If the initial stat throws, fall back
+  // to existence-only semantics rather than crashing startup.
+  let sentinelIdentity: SentinelIdentity | null = null;
+  try {
+    const st = fs.statSync(sentinelPath);
+    sentinelIdentity = { ino: st.ino, mtimeMs: st.mtimeMs };
+  } catch {
+    sentinelIdentity = null;
+  }
+
+  // Singleton guard: stop any poller this module instance started earlier so a
+  // same-version re-register (in-process SIGUSR1 restart) does not stack a
+  // second live setInterval on top of the first.
+  if (activePoller) {
+    activePoller.stop();
+    deps.logger.info('extractd: previous poller stopped (re-register)');
+  }
+
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let initialTimeout: ReturnType<typeof setTimeout> | undefined;
+
+  const stop = (): void => {
+    if (timer) clearInterval(timer);
+    if (initialTimeout) clearTimeout(initialTimeout);
+    if (activePoller === handle) activePoller = null;
+  };
 
   const pollAndExtract = async (): Promise<void> => {
     try {
+      // Cross-version self-termination: if this module's own file is gone, or a
+      // DIFFERENT file was swapped in at the same path (uninstall→reinstall of a
+      // newer version), stop — a zombie poller from a stale module instance must
+      // not keep capturing.
+      let sentinelStat: fs.Stats | null = null;
+      try {
+        sentinelStat = fs.statSync(sentinelPath);
+      } catch {
+        // File gone (plugin dir removed).
+        deps.logger.warn('extractd: poller self-terminated (plugin dir removed)');
+        stop();
+        return;
+      }
+      if (
+        sentinelIdentity !== null &&
+        (sentinelStat.ino !== sentinelIdentity.ino || sentinelStat.mtimeMs !== sentinelIdentity.mtimeMs)
+      ) {
+        deps.logger.warn('extractd: poller self-terminated (plugin file replaced — reinstall/upgrade detected)');
+        stop();
+        return;
+      }
       await deps.ensureInitialized();
       if (deps.isPairingPending()) return;
       if (deps.isImportActive()) return;
@@ -244,25 +397,24 @@ export function startTrajectoryPoller(
     }
   };
 
-  const timer = setInterval(() => {
+  timer = setInterval(() => {
     void pollAndExtract();
   }, pollIntervalMs);
   if (typeof timer.unref === 'function') timer.unref();
 
-  const initialTimeout = setTimeout(() => {
+  initialTimeout = setTimeout(() => {
     void pollAndExtract();
   }, 5_000);
   if (typeof initialTimeout.unref === 'function') initialTimeout.unref();
 
   deps.logger.info(`extractd: trajectory poller started (interval=${Math.round(pollIntervalMs / 1000)}s)`);
 
-  return {
-    stop: () => {
-      clearInterval(timer);
-      clearTimeout(initialTimeout);
-    },
+  const handle: TrajectoryPollerHandle = {
+    stop,
     pollOnce: pollAndExtract,
   };
+  activePoller = handle;
+  return handle;
 }
 
 // ---------------------------------------------------------------------------