@remnic/core 10.0.52 → 10.0.54

package/src/orchestration/maintenance.ts

@@ -22,7 +22,7 @@
 import { resolveNamespaceCapabilities,
   resolveQmdCapabilities,resolveConsolidationCapabilities, resolveRecallAuxiliaryCapabilities } from "../capabilities.js";
 import { existsSync, type Dirent } from "node:fs";
-import { appendFile, lstat, mkdir, readFile, readdir, realpath, stat, writeFile } from "node:fs/promises";
+import { lstat, readdir, realpath, stat } from "node:fs/promises";
 import path from "node:path";
 
 import type { PluginConfig } from "../types.js";
@@ -57,11 +57,8 @@ import {
   maybeRebuildMemoryProjectionScheduled,
   terminateScheduledProjectionRebuilds,
 } from "./projection-rebuild-schedule.js";
-import {
-  drainPendingLifecycleLedgerIfAny,
-  pendingLifecycleLedgerDir,
-  type LifecyclePendingIo,
-} from "../storage/memory-lifecycle-ledger-access.js";
+import { drainPendingLifecycleAppendsForPath } from "./lifecycle-pending-fallback-drain.js";
+import { QmdMaintenanceCompletion } from "./qmd-maintenance-completion.js";
 import { STATE_FILE_MAX_DECRYPT_BYTES } from "../storage/secure-line-reader.js";
 import { createCompoundingWeeklyCron, type CompoundingWeeklySchedulerHandle } from "../compounding/weekly-scheduler.js";
 import { startLocationAutoSync, type LocationAutoSyncHandle } from "../location/scheduler.js";
@@ -70,7 +67,7 @@ import type { ActivitySyncRunSummary } from "../activity/runner.js";
 import { resolveHomeDir } from "../runtime/env.js";
 import { log } from "../logger.js";
 import { isErrnoCode } from "../utils/errno.js";
-import { assertPathInsideRoot, listContainedSpillFiles } from "../utils/path-containment.js";
+import { assertPathInsideRoot } from "../utils/path-containment.js";
 import {
   probeEncryptedRegularFileHeader,
   SECURE_STORE_ENVELOPE_OVERHEAD_BYTES,
@@ -137,6 +134,9 @@ export class MaintenanceScheduler {
   private qmdMaintenanceTimer: NodeJS.Timeout | null = null;
   private qmdMaintenancePending = false;
   private qmdMaintenanceInFlight = false;
+  private readonly qmdCompletion = new QmdMaintenanceCompletion();
+  /** Namespaces that ran in passes of the request still waiting for full coverage. */
+  private readonly qmdCoveredNamespaces = new Set<string>();
   private lastQmdEmbedAtMs = 0;
   private lastQmdEmbedAtMsByNamespace = new Map<string, number>();
 
@@ -476,13 +476,13 @@ export class MaintenanceScheduler {
   // QMD maintenance scheduling (debounced + singleflight)
   // ───────────────────────────────────────────────────────────────────────
 
-  /** Internal: queue a debounced QMD maintenance pass. */
-  private requestQmdMaintenance(): void {
-    if (!this.deps.getQmd().isAvailable()) return;
-    if (!resolveQmdCapabilities(this.deps.config).qmdMaintenance) return;
+  /** Internal: queue a debounced QMD maintenance pass; false when nothing could be armed. */
+  private requestQmdMaintenance(): boolean {
+    if (!this.deps.getQmd().isAvailable()) return false;
+    if (!resolveQmdCapabilities(this.deps.config).qmdMaintenance) return false;
 
     this.qmdMaintenancePending = true;
-    if (this.qmdMaintenanceTimer) return;
+    if (this.qmdMaintenanceTimer) return true;
 
     this.qmdMaintenanceTimer = setTimeout(() => {
       this.qmdMaintenanceTimer = null;
@@ -490,6 +490,18 @@ export class MaintenanceScheduler {
         log.debug(`background qmd maintenance failed: ${err}`),
       );
     }, this.deps.config.qmdMaintenanceDebounceMs);
+    return true;
+  }
+
+  /**
+   * Like a maintenance request, but resolves true only once a pass that started
+   * after it completed successfully. False when nothing could be armed (QMD
+   * unavailable or maintenance off), the pass failed, or dispose() abandoned it,
+   * so a caller that must not lose the re-index keeps owing it.
+   */
+  requestQmdMaintenanceCompletion(namespace?: string): Promise<boolean> {
+    if (this.disposed || !this.requestQmdMaintenance()) return Promise.resolve(false);
+    return this.qmdCompletion.wait(namespace);
   }
 
   /**
@@ -530,6 +542,12 @@ export class MaintenanceScheduler {
     if (!this.qmdMaintenancePending) return;
     this.qmdMaintenanceInFlight = true;
     this.qmdMaintenancePending = false;
+    // Waiters claimed here are served by THIS pass; later requests wait for the next.
+    const settle = this.qmdCompletion.claim();
+    let served = false;
+    let deferred = false;
+    // Set only by the namespace-aware branch; absent means the pass outcome applies to every waiter.
+    let ranNamespaces: Set<string> | undefined;
 
     try {
       if (resolveNamespaceCapabilities(this.deps.config).namespaces) {
@@ -555,7 +573,7 @@ export class MaintenanceScheduler {
           }
           this.lastQmdEmbedAtMs = now;
         };
-        await runNamespaceMaintenanceBatchPlan(
+        const summary = await runNamespaceMaintenanceBatchPlan(
           this.deps.config,
           plan,
           async (candidates) => {
@@ -605,8 +623,53 @@ export class MaintenanceScheduler {
             skipReasonForError: qmdMaintenanceSkipReasonForError,
           },
         );
+        // Namespaces skipped for a TRANSIENT reason (budget_exhausted, lock_held) were not covered
+        // by this pass. They are covered once they ran in this or an earlier pass of the same
+        // request, so a deployment with more namespaces than the cycle budget still converges.
+        // Permanent skip reasons describe namespaces this deployment never re-indexes.
+        const covered = this.qmdCoveredNamespaces;
+        const ran = new Set<string>();
+        ranNamespaces = ran;
+        const before = covered.size;
+        for (const status of summary.statuses) {
+          if (status.state !== "ran") continue;
+          covered.add(status.namespace);
+          ran.add(status.namespace);
+        }
+        const uncovered = summary.statuses.some(
+          (status) =>
+            status.state === "skipped" &&
+            (status.reason === "budget_exhausted" || status.reason === "lock_held") &&
+            !covered.has(status.namespace),
+        );
+        // The batch runner drops namespace "*" skips from the statuses, so a failed catalog read
+        // is only visible on the plan: cataloged namespaces were never discovered this pass.
+        const catalogReadFailed = plan.skipped.some((skip) => skip.reason === "catalog_read_failed");
+        served = summary.ran > 0 && summary.failed === 0 && !uncovered && !catalogReadFailed;
+        // Partial progress keeps the waiters for another pass; no progress, a failure or a failed
+        // catalog read ends the request unserved so the next start asks again.
+        deferred = !served && summary.failed === 0 && !catalogReadFailed && covered.size > before && !this.disposed;
       } else {
-        await this.deps.getQmd().update();
+        const qmd = this.deps.getQmd();
+        // Plain update() is fail-open on every backend: it resolves when the min-interval gate,
+        // failure backoff or an early exit suppressed it, and when it errored. Only the variants
+        // that report whether an update ran count (updateCompleted, else QMD's updateStrict).
+        if (qmd.updateCompleted) {
+          try {
+            served = await qmd.updateCompleted();
+          } catch (err) {
+            log.debug(`qmd maintenance update did not run: ${err}`);
+          }
+        } else if (qmd.updateStrict) {
+          try {
+            await qmd.updateStrict();
+            served = true;
+          } catch (err) {
+            log.debug(`qmd maintenance update did not run: ${err}`);
+          }
+        } else {
+          await qmd.update();
+        }
         const now = Date.now();
         if (
           resolveQmdCapabilities(this.deps.config).qmdAutoEmbed &&
@@ -624,7 +687,10 @@ export class MaintenanceScheduler {
       // backoff) does not advance lastUpdateRanAtMs, so it leaves caches warm
       // (#1904, Codex/Cursor).
     } finally {
+      settle(served, deferred, ranNamespaces);
+      if (!deferred) this.qmdCoveredNamespaces.clear();
       this.qmdMaintenanceInFlight = false;
+      if (deferred) this.qmdMaintenancePending = true;
       if (this.qmdMaintenancePending) {
         this.requestQmdMaintenance();
       }
@@ -772,7 +838,7 @@ export class MaintenanceScheduler {
     if (target.storage) {
       await this.drainPendingLifecycleAppends(target.storage);
     } else {
-      await this.drainPendingLifecycleAppendsForPath(target.memoryDir);
+      await drainPendingLifecycleAppendsForPath(target.memoryDir);
     }
   }
 
@@ -787,86 +853,6 @@ export class MaintenanceScheduler {
     }
   }
 
-  /**
-   * Drain a filesystem-fallback target's pending lifecycle-append spill when no
-   * secure StorageManager is available (catalog-disabled namespace; issue
-   * #2033). Uses the safe path-scoped PLAINTEXT context this fallback already
-   * operates in: a keyless drain can only fold plaintext spills into a plaintext
-   * ledger, so it refuses when the ledger or ANY spill is encrypted at rest,
-   * leaving those pending for a keyed (catalog-path) drain — exactly mirroring
-   * the fallback compaction's encrypted-ledger deferral. Non-fatal; a fast
-   * no-op when nothing is pending. The shared spill lister enforces the symlink/
-   * containment guard on every spill file it reads or deletes.
-   */
-  private async drainPendingLifecycleAppendsForPath(memoryDir: string): Promise<void> {
-    const ledgerPath = path.join(memoryDir, "state", "memory-lifecycle-ledger.jsonl");
-    const spillDir = pendingLifecycleLedgerDir(ledgerPath);
-    // Enumerate spills through the SAME guarded lister the actual drain uses
-    // (listContainedSpillFiles): it rejects a symlinked/non-directory spill dir
-    // and skips any symlink/FIFO/device/escaping entry, returning only regular
-    // files contained in the dir. Never raw-readdir + open() an untrusted name:
-    // opening a FIFO would block until a writer appears and a symlink would
-    // redirect the probe outside the dir (#2033). Enumerate BOTH live `*.jsonl`
-    // spills and crash-orphaned `*.jsonl.claimed` files: a drain that died
-    // between claiming a spill (rename to `.claimed`) and committing it leaves
-    // the ONLY copy of those rows as a claimed orphan. Gating solely on live
-    // spills would early-return here whenever the pending dir holds nothing but
-    // orphans, stranding those rows forever; proceeding lets
-    // drainPendingLifecycleLedgerIfAny -> recoverOrphanedClaims restore and
-    // re-commit them under the ledger lock (#2033).
-    let spillFiles: string[];
-    let claimedOrphans: string[];
-    try {
-      spillFiles = await listContainedSpillFiles(spillDir);
-      claimedOrphans = await listContainedSpillFiles(spillDir, ".jsonl.claimed");
-    } catch (err) {
-      log.debug(`fallback lifecycle pending scan failed (non-fatal) for ${memoryDir}: ${err}`);
-      return;
-    }
-    if (spillFiles.length === 0 && claimedOrphans.length === 0) return;
-    // The pending encryption state is authoritative only UNDER the ledger lock:
-    // drainPendingLifecycleLedgerIfAny waits for the lock and re-enumerates the
-    // pending dir, so a secure-store writer that spills an encrypted file — or a
-    // keyed compaction that rewrites the ledger encrypted — while this fallback
-    // waits would defeat any pre-lock probe (#2033). Probe each file at the
-    // moment of use inside the held lock instead: readSecure refuses an
-    // encrypted spill (the fold reads each spill lazily and propagates the throw
-    // BEFORE claiming that spill, leaving it intact) and the append refuses a
-    // ledger that became encrypted (the fold rolls the claims back). Either way
-    // the plaintext IO
-    // never reads or writes ciphertext; the keyed catalog-path drain handles the
-    // deferred rows.
-    const io: LifecyclePendingIo = {
-      writeSecure: async (filePath, payload) => {
-        await mkdir(path.dirname(filePath), { recursive: true });
-        await writeFile(filePath, payload, "utf-8");
-      },
-      readSecure: async (filePath) => {
-        if (await probeEncryptedRegularFileHeader(filePath)) {
-          throw new Error(`fallback lifecycle drain deferred: encrypted spill at ${filePath}`);
-        }
-        return readFile(filePath, "utf-8");
-      },
-    };
-    try {
-      await drainPendingLifecycleLedgerIfAny(
-        ledgerPath,
-        io,
-        async (payload) => {
-          if (await probeEncryptedRegularFileHeader(ledgerPath)) {
-            throw new Error(`fallback lifecycle drain deferred: ledger became encrypted at ${ledgerPath}`);
-          }
-          await appendFile(ledgerPath, payload, "utf-8");
-        },
-        async () => {
-          await mkdir(path.dirname(ledgerPath), { recursive: true });
-        },
-      );
-    } catch (err) {
-      log.debug(`fallback lifecycle pending drain failed (non-fatal) for ${memoryDir}: ${err}`);
-    }
-  }
-
   /**
    * Enumerate the lifecycle ledgers to consider for compaction: the root
    * (through the secure-configured root storage when available) plus every
@@ -1186,6 +1172,7 @@ export class MaintenanceScheduler {
       this.qmdMaintenanceTimer = null;
     }
     this.qmdMaintenancePending = false;
+    this.qmdCompletion.abandon();
     await activityDrain;
     await locationDrain; await weeklyDrain;
     // Belt-and-suspenders: clear anything a late tick armed before the latch.

package/src/orchestration/qmd-maintenance-completion.ts

@@ -0,0 +1,44 @@
+/**
+ * Callers that must know the re-index actually ran (the entity-migration
+ * pending marker, issue #3286) cannot rely on arming the debounced timer: a
+ * crash or dispose() inside the debounce window would lose the request. They
+ * wait here instead; the scheduler claims the waiters when a pass starts and
+ * settles them with the pass outcome, and abandons them on dispose().
+ */
+export class QmdMaintenanceCompletion {
+  private waiters: Array<{ resolve: (served: boolean) => void; namespace?: string }> = [];
+
+  /**
+   * Resolves true when a pass that started after this call completed successfully. With a
+   * `namespace` the request is served as soon as a pass ran that namespace, whatever else it skipped.
+   */
+  wait(namespace?: string): Promise<boolean> {
+    return new Promise((resolve) => this.waiters.push({ resolve, namespace }));
+  }
+
+  /**
+   * A pass is starting: take every waiter it will serve and return their settle function.
+   * `ran` lists the namespaces a namespace-aware pass ran (absent when namespaces are disabled:
+   * one corpus is maintained and the pass outcome applies to every waiter); `defer` keeps the
+   * waiters it did not serve waiting for a later pass (a pass that covered only part of the selection).
+   */
+  claim(): (served: boolean, defer?: boolean, ran?: ReadonlySet<string>) => void {
+    const claimed = this.waiters.splice(0);
+    return (served, defer = false, ran) => {
+      const requeue: typeof claimed = [];
+      for (const waiter of claimed) {
+        // A scoped waiter needs its own namespace to have run; the pass outcome alone is not enough.
+        const own = waiter.namespace !== undefined && ran !== undefined ? ran.has(waiter.namespace) : served;
+        if (own) waiter.resolve(true);
+        else if (defer) requeue.push(waiter);
+        else waiter.resolve(false);
+      }
+      this.waiters.unshift(...requeue);
+    };
+  }
+
+  /** The scheduler stopped: nothing will serve the waiters. */
+  abandon(): void {
+    this.claim()(false);
+  }
+}

package/src/orchestrator.ts

@@ -1512,7 +1512,14 @@ export class Orchestrator {
       onActivitySynced: (summary) => { if (!this.config.meetings.enabled) return; void this.getMeetingsService().then((s) => s.requestBuildForActivitySync(summary.ranAt, this.config.activity.timezone, summary.touchedDates)).catch((err) => log.warn(`meetings: activity tail-step build failed to schedule: ${err instanceof Error ? err.message : String(err)}`)); },
     });
     const bindStorage = (storage: StorageManager, namespace: string) => {
-      storage.onEntityMigrationComplete = () => { if (this.acceptingEntityMigrationMaintenance) this.requestQmdMaintenance(); };
+      storage.onEntityMigrationComplete = () => {
+        if (!this.acceptingEntityMigrationMaintenance) return false;
+        // Settles once a QMD pass covering this request ran; the migration keeps its pending marker until then.
+        const served = this.maintenanceScheduler.requestQmdMaintenanceCompletion(namespace);
+        // Same side effects as before: projection rebuild and ledger-compaction checks, independent of QMD.
+        this.requestQmdMaintenance();
+        return served;
+      };
       if (this.prioritizedEmbedding) storage.onMemoryWrite = (filePath) => this.prioritizedEmbedding?.enqueue(filePath, namespace);
     };
     bindStorage(this.storage, this.config.defaultNamespace);

package/src/search/lancedb-backend.ts

@@ -139,23 +139,38 @@ export class LanceDbBackend implements SearchBackend {
   }
 
   async updateCollectionFromDir(collection: string, memoryDir: string, execution?: SearchExecutionOptions): Promise<void> {
-    if (isSearchAborted(execution)) return;
+    await this.refreshCollection(collection, memoryDir, execution);
+  }
+
+  async updateCompleted(execution?: SearchExecutionOptions): Promise<boolean> {
+    try {
+      return await this.refreshCollection(this.collection, this.memoryDir, execution);
+    } catch (err) {
+      log.debug(`LanceDbBackend update did not complete: ${err}`);
+      return false;
+    }
+  }
+
+  /** Brings the collection up to date; true only when it ran to completion (false: aborted, unavailable, skipped or failed). */
+  private async refreshCollection(collection: string, memoryDir: string, execution?: SearchExecutionOptions): Promise<boolean> {
+    if (isSearchAborted(execution)) return false;
     let table = await this.ensureTableForCollection(collection);
-    if (isSearchAborted(execution)) return;
-    if (!table) return;
+    if (isSearchAborted(execution)) return false;
+    if (!table) return false;
 
     const docs = await scanMemoryDir(memoryDir);
-    if (isSearchAborted(execution)) return;
+    if (isSearchAborted(execution)) return false;
     if (docs.length === 0) {
       // Clear stale data when no docs remain
       try {
         const db = await this.ensureDb();
         await db.dropTable(collection).catch(() => {});
         if (collection === this.collection) this.table = null;
+        return true;
       } catch {
         // Best-effort cleanup
       }
-      return;
+      return false;
     }
 
     const embeddingProviderIdentity = this.embedHelper.getProviderIdentity();
@@ -166,13 +181,13 @@ export class LanceDbBackend implements SearchBackend {
     const vectorProviderColumnState = await this.tableVectorProviderColumnState(table);
     if (vectorProviderColumnState === "missing") {
       table = await this.recreateTableForCollection(collection);
-      if (isSearchAborted(execution)) return;
-      if (!table) return;
+      if (isSearchAborted(execution)) return false;
+      if (!table) return false;
     } else if (vectorProviderColumnState === "present") {
       try {
         const existingRows = await table.query().select(["docid", "vector", "vectorProvider"]).toArray();
         for (const row of existingRows ?? []) {
-          if (isSearchAborted(execution)) return;
+          if (isSearchAborted(execution)) return false;
           const docid = row.docid;
           if (typeof docid !== "string") continue;
           const vector = row.vector;
@@ -184,11 +199,11 @@ export class LanceDbBackend implements SearchBackend {
         }
       } catch {
         log.debug("LanceDbBackend skipped refresh after vector preservation failed");
-        return;
+        return false;
       }
     } else {
       log.debug("LanceDbBackend skipped vector preservation after vectorProvider probe failed");
-      return;
+      return false;
     }
 
     const rows = docs.map((d) => {
@@ -213,19 +228,21 @@ export class LanceDbBackend implements SearchBackend {
     });
 
     try {
-      if (isSearchAborted(execution)) return;
+      if (isSearchAborted(execution)) return false;
       await table.add(rows, { mode: "overwrite" });
       this.rememberVectorProviderCompatibility(
         table,
         embeddingProviderIdentity,
         rows.length > 0 && rows.every((row) => row.vectorProvider === embeddingProviderIdentity),
       );
-      if (isSearchAborted(execution)) return;
+      if (isSearchAborted(execution)) return false;
       // FTS index on the content column.
       await this.createFtsIndex(table);
       if (collection === this.collection) this.table = table;
+      return true;
     } catch (err) {
       log.debug(`LanceDbBackend update failed: ${err}`);
+      return false;
     }
   }
 

package/src/search/meilisearch-backend.test.ts

@@ -0,0 +1,148 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { MeilisearchBackend } from "./meilisearch-backend.js";
+
+// Issue #3286: update() is fail-open on every backend, so the entity-migration
+// pending marker asks updateCompleted() whether the re-index actually ran.
+test("Meilisearch updateCompleted is false whenever an enabled refresh returned early", async () => {
+  const base = { host: "http://127.0.0.1:1", collection: "openclaw-engram", memoryDir: "/nonexistent" };
+  assert.equal(await new MeilisearchBackend({ ...base, autoIndex: true }).updateCompleted(), false, "never probed: unavailable");
+  assert.equal(await new MeilisearchBackend({ host: base.host, collection: base.collection, autoIndex: true }).updateCompleted(), false, "no memory dir");
+});
+
+test("Meilisearch updateCompleted is true when autoIndex is off: nothing is pushed by configuration (issue #3286)", async () => {
+  // autoIndex defaults to off (the server is managed outside Remnic). Reporting false would
+  // make every strict namespace update fail and leave the pending marker stuck.
+  const base = { host: "http://127.0.0.1:1", collection: "openclaw-engram", memoryDir: "/nonexistent" };
+  assert.equal(await new MeilisearchBackend({ ...base, autoIndex: false }).updateCompleted(), true);
+  assert.equal(await new MeilisearchBackend({ host: base.host, collection: base.collection }).updateCompleted(), true, "default config, no memory dir, never probed");
+});
+
+/** A Meilisearch client double: waitForTask resolves with the task status, as the real 0.46 SDK does. */
+function stubClient(status: string) {
+  return {
+    async health() {},
+    async getIndex() {},
+    index: () => ({
+      async addDocuments() {
+        return { taskUid: 1 };
+      },
+      async getDocuments() {
+        return { results: [] };
+      },
+      async deleteDocuments() {
+        return { taskUid: 2 };
+      },
+    }),
+    // Resolves for failed and canceled tasks too; only a timeout rejects.
+    async waitForTask() {
+      return { status };
+    },
+  };
+}
+
+function reachableBackend(memoryDir: string, status: string): MeilisearchBackend {
+  const backend = new MeilisearchBackend({ host: "http://127.0.0.1:1", collection: "openclaw-engram", autoIndex: true, memoryDir });
+  Object.defineProperty(backend, "available", { value: true });
+  Object.defineProperty(backend, "client", { value: stubClient(status) });
+  return backend;
+}
+
+test("Meilisearch updateCompleted is true only when the add task succeeded (issue #3286)", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-meili-completed-"));
+  try {
+    await mkdir(path.join(root, "facts"), { recursive: true });
+    await writeFile(path.join(root, "facts", "fact.md"), "---\nid: mem-meili\n---\nA fact to index.");
+    assert.equal(await reachableBackend(root, "succeeded").updateCompleted(), true);
+    for (const status of ["failed", "canceled", "enqueued", "processing"]) {
+      assert.equal(await reachableBackend(root, status).updateCompleted(), false, `a ${status} task did not index anything`);
+    }
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("Meilisearch updateCompleted is false for a reachable backend with no memory dir to index (issue #3286)", async () => {
+  const backend = new MeilisearchBackend({ host: "http://127.0.0.1:1", collection: "openclaw-engram", autoIndex: true });
+  Object.defineProperty(backend, "available", { value: true });
+  Object.defineProperty(backend, "client", { value: stubClient("succeeded") });
+  assert.equal(await backend.updateCompleted(), false);
+});
+
+test("Meilisearch updateCompleted is false when a stale-document deletion fails (issue #3286)", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-meili-deletion-"));
+  try {
+    await mkdir(path.join(root, "facts"), { recursive: true });
+    // One live fact plus one stale server-side doc: the add succeeds, the deletion must too.
+    await writeFile(path.join(root, "facts", "fact.md"), "---\nid: mem-meili\n---\nA fact to index.");
+    const backend = new MeilisearchBackend({ host: "http://127.0.0.1:1", collection: "openclaw-engram", autoIndex: true, memoryDir: root });
+    Object.defineProperty(backend, "available", { value: true });
+    let waitForTaskCalls = 0;
+    Object.defineProperty(backend, "client", {
+      value: {
+        async health() {},
+        async getIndex() {},
+        index: () => ({
+          async addDocuments() {
+            return { taskUid: 1 };
+          },
+          async getDocuments() {
+            return { results: [{ id: "mem-meili" }, { id: "mem-stale" }] };
+          },
+          async deleteDocuments() {
+            return { taskUid: 2 };
+          },
+        }),
+        // First wait is the add (succeeded); second is the stale-doc deletion.
+        async waitForTask() {
+          waitForTaskCalls += 1;
+          return { status: waitForTaskCalls === 1 ? "succeeded" : "failed" };
+        },
+      },
+    });
+    assert.equal(await backend.updateCompleted(), false, "a failed deletion leaves a stale document searchable");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("Meilisearch updateCompleted is false when waiting on the stale-document deletion throws (issue #3286)", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-meili-deletion-throw-"));
+  try {
+    await mkdir(path.join(root, "facts"), { recursive: true });
+    await writeFile(path.join(root, "facts", "fact.md"), "---\nid: mem-meili\n---\nA fact to index.");
+    const backend = new MeilisearchBackend({ host: "http://127.0.0.1:1", collection: "openclaw-engram", autoIndex: true, memoryDir: root });
+    Object.defineProperty(backend, "available", { value: true });
+    let waitForTaskCalls = 0;
+    Object.defineProperty(backend, "client", {
+      value: {
+        async health() {},
+        async getIndex() {},
+        index: () => ({
+          async addDocuments() {
+            return { taskUid: 1 };
+          },
+          async getDocuments() {
+            return { results: [{ id: "mem-meili" }, { id: "mem-stale" }] };
+          },
+          async deleteDocuments() {
+            return { taskUid: 2 };
+          },
+        }),
+        // The add succeeds; waiting on the deletion rejects (a timeout in the real SDK).
+        async waitForTask() {
+          waitForTaskCalls += 1;
+          if (waitForTaskCalls > 1) throw new Error("timed out waiting for the deletion task");
+          return { status: "succeeded" };
+        },
+      },
+    });
+    assert.equal(await backend.updateCompleted(), false);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/src/search/meilisearch-backend.ts

@@ -136,17 +136,30 @@ export class MeilisearchBackend implements SearchBackend {
   }
 
   async updateCollectionFromDir(collection: string, memoryDir: string, execution?: SearchExecutionOptions): Promise<void> {
-    if (!this.autoIndex) return;
-    if (!this.available) return;
-    if (isSearchAborted(execution)) return;
+    await this.refreshCollection(collection, memoryDir, execution);
+  }
+
+  async updateCompleted(execution?: SearchExecutionOptions): Promise<boolean> {
+    // autoIndex is off by default: the Meilisearch server is managed outside Remnic and
+    // nothing is pushed by configuration, so there is no re-index that could be left incomplete.
+    if (!this.autoIndex) return true;
+    if (!this.memoryDir) return false;
+    return this.refreshCollection(this.collection, this.memoryDir, execution);
+  }
+
+  /** Brings the collection up to date; true only when it ran to completion (false: aborted, unavailable, skipped or failed). */
+  private async refreshCollection(collection: string, memoryDir: string, execution?: SearchExecutionOptions): Promise<boolean> {
+    if (!this.autoIndex) return false;
+    if (!this.available) return false;
+    if (isSearchAborted(execution)) return false;
 
     try {
       const ensured = await this.ensureCollection(memoryDir, collection, execution);
-      if (ensured === "skipped" || ensured === "missing") return;
+      if (ensured === "skipped" || ensured === "missing") return false;
       const client = await this.ensureClient();
-      if (isSearchAborted(execution)) return;
+      if (isSearchAborted(execution)) return false;
       const docs = await scanMemoryDir(memoryDir);
-      if (isSearchAborted(execution)) return;
+      if (isSearchAborted(execution)) return false;
       const index = client.index(collection);
 
       const meilDocs = docs.map((d) => ({
@@ -157,10 +170,15 @@ export class MeilisearchBackend implements SearchBackend {
       }));
 
       // Upsert current docs and wait for the task to complete
-      if (isSearchAborted(execution)) return;
+      if (isSearchAborted(execution)) return false;
       const addTask = await index.addDocuments(meilDocs, { primaryKey: "id" });
-      await client.waitForTask(addTask.taskUid, { timeOutMs: this.timeoutMs });
-      if (isSearchAborted(execution)) return;
+      // waitForTask resolves with a failed or canceled task and rejects only on timeout.
+      const added = await client.waitForTask(addTask.taskUid, { timeOutMs: this.timeoutMs });
+      if (added.status !== "succeeded") {
+        log.debug(`MeilisearchBackend add task finished with status ${added.status}`);
+        return false;
+      }
+      if (isSearchAborted(execution)) return false;
 
       // Remove docs that no longer exist on disk (paginated to handle large indexes)
       const currentIds = new Set(docs.map((d) => d.docid));
@@ -170,7 +188,7 @@ export class MeilisearchBackend implements SearchBackend {
         let staleIds: string[] = [];
         let hasMore = true;
         while (hasMore) {
-          if (isSearchAborted(execution)) return;
+          if (isSearchAborted(execution)) return false;
           const page = await index.getDocuments({ limit: PAGE_SIZE, offset, fields: ["id"] });
           const results = page.results ?? [];
           for (const doc of results) {
@@ -181,15 +199,24 @@ export class MeilisearchBackend implements SearchBackend {
           hasMore = results.length === PAGE_SIZE;
         }
         if (staleIds.length > 0) {
-          if (isSearchAborted(execution)) return;
+          if (isSearchAborted(execution)) return false;
           const delTask = await index.deleteDocuments(staleIds);
-          await client.waitForTask(delTask.taskUid, { timeOutMs: this.timeoutMs });
+          // The deletion is part of completion: a stale document left searchable is not an
+          // up-to-date index, and waitForTask resolves failed/canceled tasks without throwing.
+          const deleted = await client.waitForTask(delTask.taskUid, { timeOutMs: this.timeoutMs });
+          if (deleted.status !== "succeeded") {
+            log.debug(`MeilisearchBackend stale-document deletion finished with status ${deleted.status}`);
+            return false;
+          }
         }
-      } catch {
-        // Deletion cleanup is best-effort
+      } catch (err) {
+        log.debug(`MeilisearchBackend stale-document deletion failed: ${err}`);
+        return false;
       }
+      return true;
     } catch (err) {
       log.debug(`MeilisearchBackend update failed: ${err}`);
+      return false;
     }
   }