@totalreclaw/totalreclaw 3.3.1-rc.20 → 3.3.1-rc.22

package/CHANGELOG.md

@@ -4,6 +4,53 @@ 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).
 
+## [Unreleased]
+
+### Install / runtime hygiene (issues #126, #128)
+
+Two narrow fixes from the rc.20 user-QA findings — both around install /
+boot-time output cleanliness, no behavior change to the steady-state plugin.
+
+- **#126 — clean up `.openclaw-install-stage-*` siblings.** When
+  `openclaw plugins install @totalreclaw/totalreclaw` is interrupted mid-
+  extract (e.g. by an auto-gateway-restart triggered by the same install),
+  the npm staging directory `<extensionsDir>/.openclaw-install-stage-XXXXXX/`
+  survives. On the next gateway start, OpenClaw's plugin loader auto-
+  discovers BOTH `.../totalreclaw/` AND the orphan staging dir, registers
+  duplicate plugins, fires hooks twice, and prints a "duplicate-plugin-id"
+  warning every cycle. A user running `openclaw plugins list` sees two
+  `totalreclaw` rows.
+
+  Fix: `cleanupInstallStagingDirs(pluginDir)` runs at plugin register time
+  (one tick after the loader resolves our entrypoint). It scans the
+  extensions directory for `.openclaw-install-stage-*` siblings and
+  recursively removes each one. Best-effort — never crashes plugin init
+  on permission / race failures.
+
+  Regression: `install-staging-cleanup.test.ts` (16 assertions) covers
+  fresh install, idempotent re-run, package-root vs `dist/` invocation,
+  unrelated-dotfile preservation (`.git`, `.openclaw-cache`), and stray-
+  file (non-directory) skipping.
+
+- **#128 — registerTool breadcrumbs no longer bleed into `--json` stdout.**
+  The rc.20 breadcrumb logs (`registerTool(totalreclaw_pair) returned. ...`
+  and the RC-only `totalreclaw_report_qa_bug registered ...`) were emitted
+  via `api.logger.info`, which OpenClaw routes to stdout decorated with
+  `[plugins] `. When a user invoked `openclaw agent --message "..." --json`
+  for programmatic parsing, the breadcrumb appeared on stdout alongside
+  the JSON-RPC body, breaking any naive `JSON.parse(stdout)`.
+
+  Fix: gate both breadcrumbs behind `CONFIG.verboseRegister`, OFF by
+  default. Ops can opt back in with `TOTALRECLAW_VERBOSE_REGISTER=1` (or
+  the general `TOTALRECLAW_DEBUG=1` toggle) when chasing a tool-injection
+  regression. Default-off keeps `openclaw agent --json` stdout clean.
+
+  Regression: `json-stdout-cleanliness.test.ts` (11 assertions) confirms
+  both breadcrumbs are wrapped in `if (CONFIG.verboseRegister)` blocks,
+  simulates the gated `--json` stdout path and `JSON.parse`s the result,
+  and exercises the env-var resolution (`TOTALRECLAW_VERBOSE_REGISTER`
+  -> `TOTALRECLAW_DEBUG` -> default false).
+
 ## [3.3.1-rc.16] — 2026-04-24
 
 Fixes #92 — slow-host install times out during ONNX-runtime / embedding-model
@@ -446,7 +493,8 @@ See: `plans/2026-04-22-plugin-3.3.1-provider-agnostic-llm.md` (internal).
     - `--json` — emits a structured payload (requires `--non-interactive`).
     - `--mode <generate|restore>` — skip the menu prompt.
     - `--phrase <12-or-24>` — required for `--mode restore`; `-` reads stdin.
-    - `--emit-phrase` — opt-in path that includes the plaintext phrase in the
+    - `--emit-phrase` — historic opt-in flag (do not invoke via agent shell:
+      forbidden by the phrase-safety rule); included plaintext phrase in the
       JSON payload. Default omits the phrase; the agent should direct the
       user to read `~/.totalreclaw/credentials.json` in their terminal.
 

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: totalreclaw
 description: "Install + set up TotalReclaw encrypted memory for OpenClaw, then use totalreclaw_remember / totalreclaw_recall. Trigger on 'install TotalReclaw', 'set up TotalReclaw', 'restore my recovery phrase', or any remember / recall request."
-version: 3.3.1-rc.11
+version: 3.3.1-rc.22
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz

package/api-client.ts

@@ -8,8 +8,15 @@
  *   Authorization: Bearer <hex-encoded-auth-key>
  *
  * The server hashes the auth key with SHA-256 to look up the user.
+ *
+ * Every outbound request goes through `buildRelayHeaders()` so the
+ * `X-TotalReclaw-Client` tag is set + the optional QA-tracing
+ * `X-TotalReclaw-Session` tag is forwarded when `TOTALRECLAW_SESSION_ID`
+ * is set. See `relay-headers.ts` and internal#127.
  */
 
+import { buildRelayHeaders } from './relay-headers.js';
+
 // ---------------------------------------------------------------------------
 // Request / Response Types
 // ---------------------------------------------------------------------------
@@ -126,7 +133,7 @@ export function createApiClient(serverUrl: string) {
     ): Promise<{ user_id: string }> {
       const res = await fetch(`${baseUrl}/v1/register`, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json', 'X-TotalReclaw-Client': 'openclaw-plugin' },
+        headers: buildRelayHeaders({ 'Content-Type': 'application/json' }),
         body: JSON.stringify({ auth_key_hash: authKeyHash, salt: saltHex }),
       });
       await assertOk(res, 'register');
@@ -160,10 +167,10 @@ export function createApiClient(serverUrl: string) {
     ): Promise<{ ids: string[]; duplicate_ids?: string[] }> {
       const res = await fetch(`${baseUrl}/v1/store`, {
         method: 'POST',
-        headers: {
+        headers: buildRelayHeaders({
           'Content-Type': 'application/json',
           Authorization: `Bearer ${authKeyHex}`,
-        },
+        }),
         body: JSON.stringify({ user_id: userId, facts }),
       });
       await assertOk(res, 'store');
@@ -198,10 +205,10 @@ export function createApiClient(serverUrl: string) {
     ): Promise<SearchCandidate[]> {
       const res = await fetch(`${baseUrl}/v1/search`, {
         method: 'POST',
-        headers: {
+        headers: buildRelayHeaders({
           'Content-Type': 'application/json',
           Authorization: `Bearer ${authKeyHex}`,
-        },
+        }),
         body: JSON.stringify({
           user_id: userId,
           trapdoors,
@@ -229,9 +236,9 @@ export function createApiClient(serverUrl: string) {
     async deleteFact(factId: string, authKeyHex: string): Promise<void> {
       const res = await fetch(`${baseUrl}/v1/facts/${encodeURIComponent(factId)}`, {
         method: 'DELETE',
-        headers: {
+        headers: buildRelayHeaders({
           Authorization: `Bearer ${authKeyHex}`,
-        },
+        }),
       });
       await assertOk(res, 'deleteFact');
       const json = (await res.json()) as Record<string, unknown>;
@@ -254,10 +261,10 @@ export function createApiClient(serverUrl: string) {
     async batchDelete(factIds: string[], authKeyHex: string): Promise<number> {
       const res = await fetch(`${baseUrl}/v1/facts/batch-delete`, {
         method: 'POST',
-        headers: {
+        headers: buildRelayHeaders({
           'Content-Type': 'application/json',
           Authorization: `Bearer ${authKeyHex}`,
-        },
+        }),
         body: JSON.stringify({ fact_ids: factIds }),
       });
       await assertOk(res, 'batchDelete');
@@ -290,9 +297,9 @@ export function createApiClient(serverUrl: string) {
 
       const res = await fetch(`${baseUrl}/v1/export?${params.toString()}`, {
         method: 'GET',
-        headers: {
+        headers: buildRelayHeaders({
           Authorization: `Bearer ${authKeyHex}`,
-        },
+        }),
       });
       await assertOk(res, 'exportFacts');
       const json = (await res.json()) as Record<string, unknown>;

package/claims-helper.ts

@@ -96,6 +96,14 @@ export interface BuildClaimInput {
   sourceAgent: string;
   /** Creation timestamp. Defaults to now. */
   extractedAt?: string;
+  /**
+   * 3.3.1-rc.22 — optional embedding-model id stamped on the claim for
+   * forward-compat. Defaults to omitted (callers that already know the
+   * active embedder pass it in; legacy paths leave it unset). The field
+   * is plugin-scoped — it survives the core validator's strip pass via
+   * the same re-attach path used for `schema_version` / `volatility`.
+   */
+  embeddingModelId?: string;
 }
 
 /**
@@ -112,7 +120,7 @@ export interface BuildClaimInput {
  * payload (see `subgraph-store.ts::encodeFactProtobuf`).
  */
 export function buildCanonicalClaim(input: BuildClaimInput): string {
-  const { fact, importance, extractedAt } = input;
+  const { fact, importance, extractedAt, embeddingModelId } = input;
 
   // Defensive: ensure fact.source is always populated before v1 validation.
   // `applyProvenanceFilterLax` should have set this upstream; this is the
@@ -125,6 +133,7 @@ export function buildCanonicalClaim(input: BuildClaimInput): string {
     fact: factWithSource,
     importance,
     createdAt: extractedAt,
+    embeddingModelId,
   });
 }
 
@@ -173,6 +182,14 @@ export interface BuildClaimV1Input {
    * when provided.
    */
   pinStatus?: PinStatus;
+  /**
+   * 3.3.1-rc.22 — optional embedding-model id stamped on the claim for
+   * distillation forward-compat. Survives the core validator strip pass
+   * via the same re-attach path used for `schema_version` / `volatility`.
+   * When omitted the field is not emitted (legacy claims remain untagged
+   * and are read back as "unspecified").
+   */
+  embeddingModelId?: string;
 }
 
 /**
@@ -257,6 +274,13 @@ export function buildCanonicalClaimV1(input: BuildClaimV1Input): string {
   if (fact.volatility && (VALID_MEMORY_VOLATILITIES as readonly string[]).includes(fact.volatility)) {
     canonical.volatility = fact.volatility;
   }
+  // 3.3.1-rc.22 — forward-compat embedder marker. Plugin-only field;
+  // survives the core validator via re-attach. Future distillation
+  // detects this on read to re-embed selectively without forcing a
+  // vault-wide rebuild.
+  if (typeof input.embeddingModelId === 'string' && input.embeddingModelId.length > 0) {
+    canonical.embedding_model_id = input.embeddingModelId;
+  }
 
   return JSON.stringify(canonical);
 }
@@ -313,6 +337,11 @@ export interface BuildV1ClaimBlobInput {
    * non-pin write.
    */
   pinStatus?: PinStatus;
+  /**
+   * 3.3.1-rc.22 — optional embedding-model id stamped on the claim for
+   * distillation forward-compat. See `BuildClaimV1Input.embeddingModelId`.
+   */
+  embeddingModelId?: string;
 }
 
 /**
@@ -374,6 +403,10 @@ export function buildV1ClaimBlob(input: BuildV1ClaimBlobInput): string {
   if (input.volatility && (VALID_MEMORY_VOLATILITIES as readonly string[]).includes(input.volatility)) {
     canonical.volatility = input.volatility;
   }
+  // 3.3.1-rc.22 — see `buildCanonicalClaimV1` comment.
+  if (typeof input.embeddingModelId === 'string' && input.embeddingModelId.length > 0) {
+    canonical.embedding_model_id = input.embeddingModelId;
+  }
   return JSON.stringify(canonical);
 }
 
@@ -431,6 +464,13 @@ export interface V1BlobReadResult {
    * when the writer explicitly omitted the field (treated as `"unpinned"`).
    */
   pinStatus?: PinStatus;
+  /**
+   * 3.3.1-rc.22 — embedder identity tag. Absent on claims written by
+   * older plugin versions. Forward-compat marker; consumers MAY use it
+   * to decide whether a claim's stored embedding matches the active
+   * embedder before letting cosine similarity make a relevance call.
+   */
+  embeddingModelId?: string;
 }
 
 export function readV1Blob(decrypted: string): V1BlobReadResult | null {
@@ -497,6 +537,12 @@ export function readV1Blob(decrypted: string): V1BlobReadResult | null {
         result.pinStatus = ps;
       }
     }
+    // 3.3.1-rc.22 — pull the embedder identity tag through. Plugin-only
+    // field added by `buildCanonicalClaimV1` / `buildV1ClaimBlob` after
+    // core validation.
+    if (typeof obj.embedding_model_id === 'string' && obj.embedding_model_id.length > 0) {
+      result.embeddingModelId = obj.embedding_model_id;
+    }
 
     return result;
   } catch {

package/config.ts

@@ -9,8 +9,15 @@
  *
  * v1 env var cleanup — see `docs/guides/env-vars-reference.md`.
  * Removed user-facing vars: TOTALRECLAW_CHAIN_ID, TOTALRECLAW_EMBEDDING_MODEL,
- * TOTALRECLAW_STORE_DEDUP, TOTALRECLAW_LLM_MODEL, TOTALRECLAW_SESSION_ID,
- * TOTALRECLAW_TAXONOMY_VERSION.
+ * TOTALRECLAW_STORE_DEDUP, TOTALRECLAW_LLM_MODEL, TOTALRECLAW_TAXONOMY_VERSION.
+ *
+ * NOTE: ``TOTALRECLAW_SESSION_ID`` was in the removed list during the v1
+ * cleanup and silently rejected with a warning. That broke Axiom log tracing
+ * for QA — the qa-totalreclaw skill prescribes setting the var so relay logs
+ * are searchable by ``X-TotalReclaw-Session``. Restored as a SUPPORTED
+ * variable: read here, forwarded as the ``X-TotalReclaw-Session`` header on
+ * every outbound relay call. Mirrors the Python-side fix
+ * (`python/src/totalreclaw/agent/state.py`, v2.0.2). See internal#127.
  * Removed legacy gates: TOTALRECLAW_CLAIM_FORMAT, TOTALRECLAW_DIGEST_MODE,
  * TOTALRECLAW_AUTO_RESOLVE_MODE (the last one moved to an internal debug
  * module; see `contradiction-sync.ts`).
@@ -33,18 +40,27 @@ const REMOVED_ENV_VARS = [
   'TOTALRECLAW_EMBEDDING_MODEL',
   'TOTALRECLAW_STORE_DEDUP',
   'TOTALRECLAW_LLM_MODEL',
-  'TOTALRECLAW_SESSION_ID',
+  // NOTE: TOTALRECLAW_SESSION_ID was here before; restored as SUPPORTED
+  // (forwarded as X-TotalReclaw-Session header). Do NOT add it back to this
+  // list — see file header + internal#127.
   'TOTALRECLAW_TAXONOMY_VERSION',
   'TOTALRECLAW_CLAIM_FORMAT',
   'TOTALRECLAW_DIGEST_MODE',
 ] as const;
 
+// Migration guide URL — kept as a constant so the regression test can assert
+// the exact link text in the warning. Pointing at GitHub raw-blob is more
+// useful than the relative repo path: operators copying the warning out of
+// stderr usually do not have the repo cloned. rc.22 finding #4.
+export const ENV_VARS_REFERENCE_URL =
+  'https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/env-vars-reference.md';
+
 function warnRemovedEnvVars(warn: (msg: string) => void = console.warn): void {
   const set = REMOVED_ENV_VARS.filter((name) => process.env[name] !== undefined);
   if (set.length === 0) return;
   warn(
     `TotalReclaw: ignoring removed env var(s): ${set.join(', ')}. ` +
-      `See docs/guides/env-vars-reference.md for the v1 env var surface.`,
+      `Migration guide: ${ENV_VARS_REFERENCE_URL}`,
   );
 }
 
@@ -63,6 +79,27 @@ export function getRecoveryPhrase(): string {
   return _recoveryPhraseOverride ?? process.env.TOTALRECLAW_RECOVERY_PHRASE ?? '';
 }
 
+/**
+ * Read the QA / observability session tag from the environment.
+ *
+ * When set, every outbound relay call adds the ``X-TotalReclaw-Session``
+ * header so relay logs (and Axiom queries) can be filtered by this tag —
+ * this is what the qa-totalreclaw skill relies on to scope log searches per
+ * QA run. When unset, returns ``null`` and the header is omitted.
+ *
+ * Read via getter (not snapshotted) so operators / test harnesses can flip
+ * the var between calls without reloading the module.
+ *
+ * Mirrors the Python-side ``RelayClient._session_id`` resolution priority.
+ * See internal#127 / `docs/guides/env-vars-reference.md`.
+ */
+export function getSessionId(): string | null {
+  const raw = process.env.TOTALRECLAW_SESSION_ID;
+  if (raw === undefined) return null;
+  const trimmed = raw.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
 /**
  * Runtime override for chain ID, set after the relay billing response is
  * read. Free tier stays on 84532 (Base Sepolia); Pro tier flips to 100
@@ -92,6 +129,15 @@ export const CONFIG = {
   get recoveryPhrase(): string {
     return getRecoveryPhrase();
   },
+  /**
+   * Optional QA / observability session tag forwarded to the relay as
+   * ``X-TotalReclaw-Session``. See `getSessionId()` above. Getter form so
+   * tests + harnesses can flip the env between calls. ``null`` when unset
+   * (header omitted).
+   */
+  get sessionId(): string | null {
+    return getSessionId();
+  },
   serverUrl: (process.env.TOTALRECLAW_SERVER_URL || 'https://api.totalreclaw.xyz').replace(/\/+$/, ''),
   selfHosted: process.env.TOTALRECLAW_SELF_HOSTED === 'true',
   credentialsPath: process.env.TOTALRECLAW_CREDENTIALS_PATH || path.join(home, '.totalreclaw', 'credentials.json'),
@@ -214,11 +260,43 @@ export const CONFIG = {
     return process.env.TOTALRECLAW_QA_REPO || '';
   },
 
+  // 3.3.1-rc.21 (issue #128): verbose-register flag. When enabled, the
+  // plugin emits opt-in `info`-level breadcrumbs after sensitive
+  // registerTool calls (currently `totalreclaw_pair`) to help ops/QA
+  // grep gateway logs for definitive proof the tool was declared.
+  // Default OFF — the breadcrumb is debug-grade and was bleeding into
+  // `openclaw agent --json` stdout, breaking programmatic parsers.
+  // Enable with either:
+  //   TOTALRECLAW_VERBOSE_REGISTER=1   (specific opt-in)
+  //   TOTALRECLAW_DEBUG=1              (general debug toggle)
+  // Read via getter so flipping the env at runtime takes effect on the
+  // next gateway start without a rebuild.
+  get verboseRegister(): boolean {
+    const specific = (process.env.TOTALRECLAW_VERBOSE_REGISTER ?? '').trim().toLowerCase();
+    if (specific === '1' || specific === 'true' || specific === 'yes') return true;
+    const general = (process.env.TOTALRECLAW_DEBUG ?? '').trim().toLowerCase();
+    return general === '1' || general === 'true' || general === 'yes';
+  },
+
   // Paths
   home,
   billingCachePath: path.join(home, '.totalreclaw', 'billing-cache.json'),
   cachePath: process.env.TOTALRECLAW_CACHE_PATH || path.join(home, '.totalreclaw', 'cache.enc'),
   openclawWorkspace: path.join(home, '.openclaw', 'workspace'),
+
+  // 3.3.1-rc.22 — lazy embedder bundle cache. The embedder
+  // (`@huggingface/transformers` + `onnxruntime-node` + the q4 ONNX
+  // model) is no longer shipped inside the plugin tarball; it is fetched
+  // on first `embed()` call from a versioned GitHub Release and cached
+  // here. Separate path from `cachePath` (encrypted vault cache) so the
+  // two never collide. See `embedder-loader.ts`.
+  embedderCachePath: process.env.TOTALRECLAW_EMBEDDER_CACHE_PATH || path.join(home, '.totalreclaw', 'embedder'),
+
+  // 3.3.1-rc.22 — override the GitHub-Releases URL templates. Only useful
+  // for air-gapped / mirror deployments and self-hosted CI. Empty string
+  // falls back to the static defaults baked into the embedder code path.
+  embedderBundleUrlTemplate: process.env.TOTALRECLAW_EMBEDDER_BUNDLE_URL || '',
+  embedderManifestUrlTemplate: process.env.TOTALRECLAW_EMBEDDER_MANIFEST_URL || '',
 } as const;
 
 // ---------------------------------------------------------------------------

package/confirm-indexed.ts

@@ -0,0 +1,191 @@
+/**
+ * Read-after-write primitive — confirm a fact id has been indexed by the
+ * subgraph after an on-chain mutation (retype / set_scope / pin / unpin /
+ * forget).
+ *
+ * Wraps the pure-compute halves exported by `@totalreclaw/core`
+ * (`wasmConfirmIndexedQuery`, `wasmConfirmIndexedParse`) in a host-side
+ * polling loop. Subgraph indexer lag on Gnosis production runs 5-30s; this
+ * helper polls every `pollIntervalMs` (default 1000ms) up to `timeoutMs`
+ * (default 30000ms).
+ *
+ * Why this exists
+ * ---------------
+ * Pre-fix, mutation tools returned `{success: true}` based on the bundler
+ * ack alone. A user who immediately ran `totalreclaw_export` would see the
+ * pre-mutation state, because the subgraph indexer hadn't yet observed the
+ * L1 inclusion. Confusing UX, root cause of rc.18 finding #117.
+ *
+ * Post-fix, mutation tools call `confirmIndexed(newFactId)` after submitting
+ * the batched UserOp; on success they return normally, on timeout they
+ * return `{success: true, partial: true, ...}` with the chain write
+ * acknowledged but the indexer-level confirmation withheld.
+ *
+ * Mnemonic isolation: this helper never touches the mnemonic, encryption
+ * key, or any decrypted blob. Only reads the public {id, isActive,
+ * blockNumber} of a fact.
+ */
+
+import { createRequire } from 'node:module';
+import { getSubgraphConfig } from './subgraph-store.js';
+import { buildRelayHeaders } from './relay-headers.js';
+
+/**
+ * The four `wasmConfirmIndexed*` exports below ship in `@totalreclaw/core@2.3.x`
+ * (the `confirm` module added in 2.2.x). Older type declarations don't list
+ * them — we use a structural cast so the plugin's `--noCheck` build is
+ * unblocked and runtime resolution is via dynamic require.
+ */
+type ConfirmIndexedCore = typeof import('@totalreclaw/core') & {
+  wasmConfirmIndexedQuery(): string;
+  wasmConfirmIndexedParse(responseJson: string): boolean;
+  wasmConfirmIndexedDefaultPollMs(): number;
+  wasmConfirmIndexedDefaultTimeoutMs(): number;
+};
+
+const requireWasm = createRequire(import.meta.url);
+let _wasm: ConfirmIndexedCore | null = null;
+function getWasm(): ConfirmIndexedCore {
+  if (!_wasm) _wasm = requireWasm('@totalreclaw/core') as unknown as ConfirmIndexedCore;
+  return _wasm!;
+}
+
+/** Result of a confirm-indexed poll loop. */
+export interface ConfirmIndexedResult {
+  /** True if the fact was found and `isActive == true` before the timeout. */
+  indexed: boolean;
+  /** Number of poll attempts before resolution (or timeout). */
+  attempts: number;
+  /** Total wall-clock ms spent polling. */
+  elapsedMs: number;
+  /** Last error message from the GraphQL adapter, if any. */
+  lastError?: string;
+}
+
+export interface ConfirmIndexedOptions {
+  /** Override the default 1s poll interval. */
+  pollIntervalMs?: number;
+  /** Override the default 30s total timeout. */
+  timeoutMs?: number;
+  /** Override `${relayUrl}/v1/subgraph` (test injection point). */
+  subgraphUrl?: string;
+  /** Override the auth-key-hex header (defaults to none). */
+  authKeyHex?: string;
+  /**
+   * Direction of the read-after-write check.
+   *   - `"active"` (default) — wait until fact is found AND `isActive == true`.
+   *     Use after pin/unpin/retype/set_scope (we're confirming the *new* fact
+   *     id has appeared).
+   *   - `"inactive"` — wait until fact either disappears OR `isActive ==
+   *     false`. Use after `forget`, where the *original* fact id is being
+   *     tombstoned and a confirm-indexed wait should resolve once the
+   *     subgraph has flipped it.
+   */
+  expect?: 'active' | 'inactive';
+  /**
+   * Test injection — caller-provided `fetch`-compatible POST. Defaults to
+   * the global `fetch`. Letting tests stub this out avoids a network mock
+   * dependency.
+   */
+  poster?: (url: string, body: string, headers: Record<string, string>) => Promise<{
+    ok: boolean;
+    status: number;
+    text: () => Promise<string>;
+  }>;
+}
+
+/**
+ * Poll the subgraph until the new fact id is indexed-and-active, or the
+ * timeout elapses. Returns a result object describing the outcome — never
+ * throws on indexer-level transient errors; the caller decides whether to
+ * surface a `partial: true` flag based on `result.indexed`.
+ *
+ * The host's submitBatch already returned a tx hash before this is called,
+ * so on `indexed: false` the on-chain write is still acknowledged — just not
+ * yet visible in the read API.
+ */
+export async function confirmIndexed(
+  factId: string,
+  options: ConfirmIndexedOptions = {},
+): Promise<ConfirmIndexedResult> {
+  // WASM bindings may be unavailable (e.g. core@<2.3.0 not yet published).
+  // In that case the chain write has still succeeded — confirm step is
+  // observational only. Return `indexed: false` so callers surface
+  // `partial: true` rather than fail the whole tool invocation.
+  let wasm: ConfirmIndexedCore;
+  let query: string;
+  let pollIntervalMs: number;
+  let timeoutMs: number;
+  try {
+    wasm = getWasm();
+    pollIntervalMs = options.pollIntervalMs ?? Number(wasm.wasmConfirmIndexedDefaultPollMs?.() ?? 1000);
+    timeoutMs = options.timeoutMs ?? Number(wasm.wasmConfirmIndexedDefaultTimeoutMs?.() ?? 30000);
+    query = wasm.wasmConfirmIndexedQuery();
+  } catch (err) {
+    return {
+      indexed: false,
+      attempts: 0,
+      elapsedMs: 0,
+      lastError: `confirm-indexed wasm bindings unavailable: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+  const subgraphUrl =
+    options.subgraphUrl ?? `${getSubgraphConfig().relayUrl}/v1/subgraph`;
+
+  const overrides: Record<string, string> = {
+    'Content-Type': 'application/json',
+  };
+  if (options.authKeyHex) overrides['Authorization'] = `Bearer ${options.authKeyHex}`;
+  const headers = buildRelayHeaders(overrides);
+
+  const body = JSON.stringify({ query, variables: { id: factId } });
+
+  const poster =
+    options.poster ??
+    (async (url, b, h) => {
+      const r = await fetch(url, { method: 'POST', headers: h, body: b });
+      return { ok: r.ok, status: r.status, text: () => r.text() };
+    });
+
+  const expect = options.expect ?? 'active';
+  const start = Date.now();
+  let attempts = 0;
+  let lastError: string | undefined;
+
+  while (Date.now() - start < timeoutMs) {
+    attempts++;
+    try {
+      const r = await poster(subgraphUrl, body, headers);
+      if (r.ok) {
+        const txt = await r.text();
+        try {
+          // wasmConfirmIndexedParse returns `true` when fact is present AND
+          // isActive==true. For `expect: 'inactive'` we invert: a `false`
+          // (fact missing OR present-but-inactive) is the resolution signal.
+          const isActive = wasm.wasmConfirmIndexedParse(txt);
+          const resolved = expect === 'active' ? isActive : !isActive;
+          if (resolved) {
+            return { indexed: true, attempts, elapsedMs: Date.now() - start };
+          }
+        } catch (parseErr) {
+          lastError = parseErr instanceof Error ? parseErr.message : String(parseErr);
+        }
+      } else {
+        lastError = `HTTP ${r.status}`;
+      }
+    } catch (err) {
+      lastError = err instanceof Error ? err.message : String(err);
+    }
+    // Sleep before the next attempt — but only if there's still budget.
+    const remaining = timeoutMs - (Date.now() - start);
+    if (remaining <= 0) break;
+    await new Promise((res) => setTimeout(res, Math.min(pollIntervalMs, remaining)));
+  }
+
+  return {
+    indexed: false,
+    attempts,
+    elapsedMs: Date.now() - start,
+    lastError,
+  };
+}

package/crypto.ts

@@ -15,10 +15,18 @@
  *     -> HKDF-SHA256(seed, salt, "openmemory-dedup-v1",           32) -> dedupKey
  */
 
-// Lazy-load WASM to avoid crash when npm install hasn't finished yet.
+// Lazy-load WASM. Uses createRequire so this module loads cleanly under bare
+// Node ESM — the shipped `dist/index.js` declares `"type":"module"`, where
+// the CJS `require` global is undefined at runtime. Prior to the rc.21 fix
+// this file called bare `require('@totalreclaw/core')` and every consumer
+// died with `require is not defined`. Matches the pattern already used by
+// claims-helper / consolidation / contradiction-sync / digest-sync / pin /
+// retype-setscope. See issue #124.
+import { createRequire } from 'node:module';
+const requireWasm = createRequire(import.meta.url);
 let _wasm: typeof import('@totalreclaw/core') | null = null;
 function getWasm() {
-  if (!_wasm) _wasm = require('@totalreclaw/core');
+  if (!_wasm) _wasm = requireWasm('@totalreclaw/core');
   return _wasm;
 }