@totalreclaw/totalreclaw 3.3.12-rc.9 → 3.3.12

package/dist/tr-cli.js

@@ -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.
@@ -31,16 +34,13 @@
  * Install: wired via package.json `bin.tr` → dist/tr-cli.js
  * 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';
 import { loadCredentialsJson } from './fs-helpers.js';
 import { printStatus } from './onboarding-cli.js';
-import { deriveKeys, computeAuthKeyHash, encrypt, decrypt, generateBlindIndices, generateContentFingerprint, } from './crypto.js';
+import { deriveKeys, computeAuthKeyHash, encrypt, generateBlindIndices, generateContentFingerprint, } from './crypto.js';
 import { createApiClient } from './api-client.js';
 import { encodeFactProtobuf, submitFactBatchOnChain, deriveSmartAccountAddress, getSubgraphConfig, PROTOBUF_VERSION_V4, } from './subgraph-store.js';
-import { searchSubgraph, searchSubgraphBroadened, } from './subgraph-search.js';
 import { exportAllFacts } from './tr-cli-export-helper.js';
 // ---------------------------------------------------------------------------
 // Helpers
@@ -51,7 +51,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, code = 1) {
     process.stderr.write(`tr: ${msg}\n`);
     process.exit(code);
@@ -66,15 +66,6 @@ function popFlag(args, flag) {
         return [false, args];
     return [true, [...args.slice(0, idx), ...args.slice(idx + 1)]];
 }
-/** Parse --limit N from args, returning [limit, cleanedArgs]. Default: defaultLimit. */
-function popLimitFlag(args, defaultLimit) {
-    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, flag, defaultValue) {
     const idx = args.indexOf(flag);
@@ -91,12 +82,6 @@ function toHexBlob(plaintext, encryptionKey) {
     const b64 = encrypt(plaintext, encryptionKey);
     return Buffer.from(b64, 'base64').toString('hex');
 }
-/** Inverse of toHexBlob — used by recall/export to decrypt subgraph blobs. */
-function fromHexBlob(hexBlob, encryptionKey) {
-    const hex = hexBlob.startsWith('0x') ? hexBlob.slice(2) : hexBlob;
-    const b64 = Buffer.from(hex, 'hex').toString('base64');
-    return decrypt(b64, encryptionKey);
-}
 async function buildContext() {
     const creds = loadCredentialsJson(CREDENTIALS_PATH);
     if (!creds) {
@@ -176,56 +161,26 @@ async function buildContext() {
 // Command: status
 // ---------------------------------------------------------------------------
 async function cmdStatus(jsonMode) {
-    // Probe plugin manifest for version/hybridMode/toolCount.
-    let pluginVersion;
-    let bootCount;
-    let hybridMode = true; // default true in 3.3.9-rc.1 (hybrid-primary)
-    let toolCount;
-    let loadedAgeSec;
-    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);
-            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 = {
-            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` +
+        process.stdout.write(`\n  plugin:      loaded (version=${PLUGIN_VERSION})\n` +
             `  hooks:       before_agent_start, agent_end, message_received, before_reset\n`);
     }
 }
@@ -337,79 +292,6 @@ async function cmdRemember(rawArgs) {
     }
 }
 // ---------------------------------------------------------------------------
-// Command: recall
-// ---------------------------------------------------------------------------
-async function cmdRecall(rawArgs) {
-    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 = [];
-        for (const c of candidates) {
-            try {
-                const docJson = fromHexBlob(c.encryptedBlob, ctx.encryptionKey);
-                const parsed = JSON.parse(docJson);
-                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;
-                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
 // ---------------------------------------------------------------------------
 async function cmdForget(rawArgs) {
@@ -418,12 +300,12 @@ async function cmdForget(rawArgs) {
     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.`);
     }
     const ctx = await buildContext();
     // Tombstone shape (pin/unpin & native forget use the same one — see
@@ -521,33 +403,60 @@ async function main() {
             await cmdRemember(args.slice(1));
             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));
             break;
         case 'export':
             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` +
+            process.stdout.write(`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/dist/trajectory-poller.js

@@ -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)
@@ -39,7 +90,24 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 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
@@ -50,16 +118,95 @@ const STATE_FILE = path.join(os.homedir(), '.totalreclaw', 'extract-state.json')
  * re-scanned, and skip the extraction path entirely.
  */
 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 = 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);
 /**
  * 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, opts = {}) {
     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 = 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;
+    let initialTimeout;
+    const stop = () => {
+        if (timer)
+            clearInterval(timer);
+        if (initialTimeout)
+            clearTimeout(initialTimeout);
+        if (activePoller === handle)
+            activePoller = null;
+    };
     const pollAndExtract = async () => {
         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 = 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;
@@ -149,24 +296,23 @@ export function startTrajectoryPoller(deps, opts = {}) {
             deps.logger.error(`extractd: poll iteration failed: ${msg}`);
         }
     };
-    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 = {
+        stop,
         pollOnce: pollAndExtract,
     };
+    activePoller = handle;
+    return handle;
 }
 // ---------------------------------------------------------------------------
 // Filesystem scan + trajectory parser