@remnic/core 10.0.52 → 10.0.54

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

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -232,3 +232,77 @@ test("Orama rebuild gate inspects every indexed string field, not only content (
     await rm(root, { recursive: true, force: true });
   }
 });
+
+test("Orama updateCompleted reports a finished refresh, and false for an aborted one (issue #3286)", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-orama-completed-"));
+  try {
+    await writeMemoryFact(root, "fact.md", "---\nid: mem-completed\n---\nAn indexed fact about completion.");
+    const backend = await createBackend(root, path.join(root, "orama-db"), undefined, { update: false });
+
+    assert.equal(await backend.updateCompleted({ signal: AbortSignal.abort() }), false, "an aborted refresh did not finish");
+    assert.equal((await backend.bm25Search("completion")).length, 0, "precondition: nothing was indexed");
+
+    assert.equal(await backend.updateCompleted(), true);
+    assert.equal((await backend.bm25Search("completion")).some((r) => r.docid === "mem-completed"), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+/** A signal that reports aborted from its Nth read on: lets a test abort a refresh at each of its checkpoints. */
+function abortingFromRead(read: number): AbortSignal {
+  const signal = new AbortController().signal;
+  let reads = 0;
+  Object.defineProperty(signal, "aborted", { get: () => ++reads >= read });
+  return signal;
+}
+
+test("Orama updateCompleted is false for a refresh aborted at any checkpoint, and true only once it persisted (issue #3286)", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-orama-abort-sweep-"));
+  try {
+    await writeMemoryFact(root, "kept.md", "---\nid: mem-kept\n---\nA fact that stays indexed.");
+    await writeMemoryFact(root, "second.md", "---\nid: mem-second\n---\nA second fact so the diff loops iterate.");
+    const dbPath = path.join(root, "orama-db");
+    // An existing, persisted index makes the refresh walk the stored hits as well as the corpus.
+    await createBackend(root, dbPath);
+    const persistedFile = resolveOramaCollectionDbFilePath(dbPath, "openclaw-engram");
+    const before = await readFile(persistedFile);
+    await rm(path.join(root, "facts", "second.md"));
+
+    // Every abort checkpoint must report false and leave the persisted index alone;
+    // the first run that reports true must be the one that persisted the change.
+    let completedAt = 0;
+    for (let read = 1; read < 200 && completedAt === 0; read += 1) {
+      // A fresh backend per attempt: an aborted refresh leaves its in-memory edits behind,
+      // which would shift the checkpoints of the next attempt.
+      const backend = await createBackend(root, dbPath, undefined, { update: false });
+      const completed = await backend.updateCompleted({ signal: abortingFromRead(read) });
+      const persisted = await readFile(persistedFile);
+      if (completed) {
+        completedAt = read;
+        assert.notDeepEqual(persisted, before, "a refresh reporting completion persisted the index");
+      } else {
+        assert.deepEqual(persisted, before, `aborted at read ${read}: nothing may be persisted`);
+      }
+    }
+    assert.ok(completedAt > 4, `the refresh checks for abort at several points (completed only at read ${completedAt})`);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("Orama updateCompleted reports false, not a rejection, when the refresh throws (issue #3286)", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-orama-throws-"));
+  try {
+    await writeMemoryFact(root, "fact.md", "---\nid: mem-throws\n---\nA fact.");
+    const backend = await createBackend(root, path.join(root, "orama-db"), undefined, { update: false });
+    Object.defineProperty(backend, "persistDbForCollection", {
+      value: async () => {
+        throw new Error("disk full");
+      },
+    });
+    assert.equal(await backend.updateCompleted(), false);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/src/search/orama-backend.ts

@@ -178,14 +178,28 @@ export class OramaBackend 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(`OramaBackend 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;
     const db = await this.ensureDbForCollection(collection);
-    if (isSearchAborted(execution)) return;
-    if (!db) return;
+    if (isSearchAborted(execution)) return false;
+    if (!db) return false;
     const { search: oramaSearch, insert, remove, count, getByID } = this.oramaModule;
 
     const docs = await scanMemoryDir(memoryDir);
-    if (isSearchAborted(execution)) return;
+    if (isSearchAborted(execution)) return false;
     const docMap = new Map(docs.map((d) => [d.docid, d]));
     const { update: oramaUpdate } = this.oramaModule;
 
@@ -204,7 +218,7 @@ export class OramaBackend implements SearchBackend {
         limit: existingCount + 100,
       });
       for (const hit of allHits.hits) {
-        if (isSearchAborted(execution)) return;
+        if (isSearchAborted(execution)) return false;
         const storedDocument =
           typeof getByID === "function"
             ? await getByID(db, hit.id)
@@ -227,7 +241,7 @@ export class OramaBackend implements SearchBackend {
 
     // Insert new docs, update existing ones (preserving vectors since update is remove+insert)
     for (const doc of docs) {
-      if (isSearchAborted(execution)) return;
+      if (isSearchAborted(execution)) return false;
       const existing = existingDocs.get(doc.docid);
       if (existing) {
         const payload: Record<string, unknown> = {
@@ -281,13 +295,14 @@ export class OramaBackend implements SearchBackend {
       }
     }
 
-    if (isSearchAborted(execution)) return;
+    if (isSearchAborted(execution)) return false;
     await this.persistDbForCollection(db, collection);
     this.rememberVectorProviderCompatibility(
       db,
       embeddingProviderIdentity,
       allRowsCompatible,
     );
+    return true;
   }
 
   async embed(): Promise<void> {

package/src/search/port.ts

@@ -182,6 +182,13 @@ export interface SearchBackend {
    * calls remain fail-open for migration/maintenance resilience.
    */
   updateStrict?(execution?: SearchExecutionOptions): Promise<void>;
+  /**
+   * Fail-open like update(), but reports whether the index was actually brought
+   * up to date: false when it returned early (aborted, unavailable, suppressed
+   * or skipped) or failed. It never rejects for an update failure. For backends with no strict variant, so a caller
+   * that must not lose a re-index (the entity-migration pending marker) can tell.
+   */
+  updateCompleted?(execution?: SearchExecutionOptions): Promise<boolean>;
   updateCollection(collection: string, execution?: SearchExecutionOptions): Promise<void>;
   updateCollectionFromDir?(collection: string, memoryDir: string, execution?: SearchExecutionOptions): Promise<void>;
   /**

package/src/search/remote-backend.ts

@@ -84,6 +84,10 @@ export class RemoteSearchBackend implements SearchBackend {
   }
 
   async update(_execution?: SearchExecutionOptions): Promise<void> {}
+  /** The remote service owns its own indexing, so there is no local re-index that could be left incomplete. */
+  async updateCompleted(_execution?: SearchExecutionOptions): Promise<boolean> {
+    return true;
+  }
   async updateCollection(_collection: string, _execution?: SearchExecutionOptions): Promise<void> {}
   async embed(): Promise<void> {}
   async embedCollection(_collection: string): Promise<void> {}

package/src/storage/entity-canonical-id-migration-adapter.ts

@@ -10,6 +10,12 @@ import {
   rewriteProjectedEntityReferences,
   rewriteProjectedMemoryEntityReference,
 } from "../memory-projection-mutations.js";
+import {
+  listMaintenancePending,
+  settleMaintenancePending,
+  trackMaintenanceSettlement,
+  writeMaintenancePending,
+} from "./entity-migration-maintenance-pending.js";
 
 export interface EntityCanonicalIdMigrationHost {
   readonly baseDir: string;
@@ -31,7 +37,13 @@ export interface EntityCanonicalIdMigrationHost {
   invalidateColdMemoriesCache(): void;
   bumpMemoryStatusVersion(): void;
   getEntityMutationVersion(): number;
-  onEntityMigrationComplete?: () => void;
+  /**
+   * Ask search maintenance to re-index. `false` means the request was refused
+   * (e.g. the host is shutting down) and a promise settling to `false` means no
+   * pass served it: the pending markers stay so the next start retries. A
+   * promise is awaited off the startup path; `true` or nothing clears them.
+   */
+  onEntityMigrationComplete?: () => boolean | Promise<boolean> | void;
 }
 
 export async function runLegacyEntityCanonicalIdMigration(
@@ -43,15 +55,26 @@ export async function runLegacyEntityCanonicalIdMigration(
   const readMigrationFingerprint = () =>
     getFingerprint(host.baseDir, host.entitiesDir, () => String(host.getEntityMutationVersion()));
   // The migration bumps the status version only after a pass that rewrote
-  // references; a no-op replay must not ask search maintenance to run.
+  // references; a no-op replay must not ask search maintenance to run unless a
+  // previous run died owing it (issue #3286 pending marker).
   let rewroteReferences = false;
+  // Markers an earlier run left behind: this run owes (and may clear) exactly
+  // these plus its own, never a marker a concurrent run arms meanwhile.
+  const owed = await listMaintenancePending(host.stateDir);
+  // Arm the marker before this run rewrites anything, so a crash between the
+  // rewrite and the hook leaves it behind. Idempotent per run.
+  let armed: Promise<string> | undefined;
+  const armPending = (): Promise<string> => (armed ??= writeMaintenancePending(host.stateDir));
   const completionFingerprint = await migrateLegacyEntityCanonicalIds({
     stateDir: host.stateDir,
     entitiesDir: host.entitiesDir,
     normalizeEntityName: host.normalizeEntityName.bind(host),
     resolveEntityFilePath: host.resolveEntityFilePath.bind(host),
     readStorageSecureFile: host.readStorageSecureFile.bind(host),
-    writeStorageSecureFile: host.writeStorageSecureFile.bind(host),
+    writeStorageSecureFile: async (filePath, content, forceEncrypt) => {
+      await armPending();
+      return host.writeStorageSecureFile(filePath, content, forceEncrypt);
+    },
     isEncryptedStorageFile: host.isEncryptedFileHeader.bind(host),
     snapshotBeforeWrite: host.snapshotBeforeWrite.bind(host),
     parseEntityFile,
@@ -63,10 +86,14 @@ export async function runLegacyEntityCanonicalIdMigration(
     readArchivedMemories: host.readArchivedMemories.bind(host),
     validateMemoryScanRoots: () =>
       validateRoots(host.baseDir, host.entitiesDir, host.stateDir, host.archiveDir),
-    rewriteProjectedEntityReferences: (mappings) =>
-      rewriteProjectedEntityReferences(host.baseDir, mappings),
-    rewriteProjectedMemoryEntityReference: (memoryId, previousEntityRef, nextEntityRef) =>
-      rewriteProjectedMemoryEntityReference(host.baseDir, memoryId, previousEntityRef, nextEntityRef),
+    rewriteProjectedEntityReferences: async (mappings) => {
+      await armPending();
+      return rewriteProjectedEntityReferences(host.baseDir, mappings);
+    },
+    rewriteProjectedMemoryEntityReference: async (memoryId, previousEntityRef, nextEntityRef) => {
+      await armPending();
+      return rewriteProjectedMemoryEntityReference(host.baseDir, memoryId, previousEntityRef, nextEntityRef);
+    },
     invalidateKnowledgeIndexCache: host.invalidateKnowledgeIndexCache.bind(host),
     invalidateAllMemoriesCache: host.invalidateAllMemoriesCache.bind(host),
     invalidateColdMemoriesCache: host.invalidateColdMemoriesCache.bind(host),
@@ -76,9 +103,17 @@ export async function runLegacyEntityCanonicalIdMigration(
     },
     readMigrationFingerprint,
   } satisfies EntityCanonicalIdMigrationDependencies);
-  if (completionFingerprint !== undefined && rewroteReferences) {
+  if (completionFingerprint !== undefined && (rewroteReferences || owed.length > 0) && host.onEntityMigrationComplete) {
+    // No hook wired (e.g. a CLI-only process) skips this block, keeping the markers too.
+    const held = armed ? [...owed, await armed] : owed;
     try {
-      host.onEntityMigrationComplete?.();
+      const outcome = host.onEntityMigrationComplete();
+      const settling = settleMaintenancePending(host.stateDir, held, outcome).catch(() => {
+        log.warn("entity migration: search maintenance scheduling failed");
+      });
+      // An async hook is served after a debounce: never hold startup for it.
+      if (outcome instanceof Promise) trackMaintenanceSettlement(host.stateDir, settling);
+      else await settling;
     } catch {
       log.warn("entity migration: search maintenance scheduling failed");
     }

package/src/storage/entity-migration-maintenance-pending-helpers.test.ts

@@ -0,0 +1,87 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import {
+  clearMaintenancePending,
+  drainMaintenanceSettlements,
+  ENTITY_MIGRATION_MAINTENANCE_PENDING_PREFIX,
+  listMaintenancePending,
+  settleMaintenancePending,
+  trackMaintenanceSettlement,
+  writeMaintenancePending,
+} from "./entity-migration-maintenance-pending.js";
+
+async function withStateDir(run: (stateDir: string) => Promise<void>): Promise<void> {
+  const stateDir = await mkdtemp(path.join(os.tmpdir(), "remnic-3286-marker-unit-"));
+  try {
+    await run(stateDir);
+  } finally {
+    await rm(stateDir, { recursive: true, force: true });
+  }
+}
+
+test("each arm writes its own marker, and listing ignores in-progress temp files", async () => {
+  await withStateDir(async (stateDir) => {
+    assert.deepEqual(await listMaintenancePending(path.join(stateDir, "missing")), [], "an absent state dir owes nothing");
+    const first = await writeMaintenancePending(stateDir);
+    const second = await writeMaintenancePending(stateDir);
+    assert.notEqual(first, second, "concurrent arms never share a file");
+    await writeFile(path.join(stateDir, `${ENTITY_MIGRATION_MAINTENANCE_PENDING_PREFIX}.crashed.tmp`), "partial");
+    await writeFile(path.join(stateDir, "entity-canonical-id-migration-v1.json"), "{}");
+    assert.deepEqual((await listMaintenancePending(stateDir)).sort(), [first, second].sort());
+  });
+});
+
+test("clearing named markers never deletes one armed by another run, and tolerates an already-gone name", async () => {
+  await withStateDir(async (stateDir) => {
+    const mine = await writeMaintenancePending(stateDir);
+    const concurrent = await writeMaintenancePending(stateDir);
+    await clearMaintenancePending(stateDir, [mine, "entity-canonical-id-maintenance.pending.already-gone"]);
+    assert.deepEqual(await listMaintenancePending(stateDir), [concurrent], "the concurrent run's marker survives");
+    await clearMaintenancePending(stateDir, [concurrent]);
+    assert.deepEqual(await readdir(stateDir), []);
+  });
+});
+
+test("settling clears on served or no answer, keeps on a refusal or a not-served promise, and propagates a rejection", async () => {
+  await withStateDir(async (stateDir) => {
+    const cases: Array<[string, boolean | Promise<boolean> | void, boolean]> = [
+      ["true", true, true],
+      ["nothing", undefined, true],
+      ["resolved true", Promise.resolve(true), true],
+      ["false", false, false],
+      ["resolved false", Promise.resolve(false), false],
+    ];
+    for (const [label, outcome, clears] of cases) {
+      const marker = await writeMaintenancePending(stateDir);
+      await settleMaintenancePending(stateDir, [marker], outcome);
+      assert.equal((await listMaintenancePending(stateDir)).length, clears ? 0 : 1, label);
+      await clearMaintenancePending(stateDir, await listMaintenancePending(stateDir));
+    }
+    const marker = await writeMaintenancePending(stateDir);
+    await assert.rejects(settleMaintenancePending(stateDir, [marker], Promise.reject(new Error("pass failed"))), /pass failed/);
+    assert.deepEqual(await listMaintenancePending(stateDir), [marker], "a rejected request keeps the marker");
+  });
+});
+
+test("tracked settlements can be drained and forgotten once done", async () => {
+  await withStateDir(async (stateDir) => {
+    const release = Promise.withResolvers<void>();
+    let finished = false;
+    trackMaintenanceSettlement(
+      stateDir,
+      release.promise.then(() => {
+        finished = true;
+      }),
+    );
+    const drained = drainMaintenanceSettlements(stateDir);
+    assert.equal(finished, false);
+    release.resolve();
+    await drained;
+    assert.equal(finished, true);
+    await drainMaintenanceSettlements(stateDir);
+  });
+});

package/src/storage/entity-migration-maintenance-pending.test.ts

@@ -0,0 +1,242 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { StorageManager, normalizeEntityName } from "../storage.js";
+import { drainMaintenanceSettlements, writeMaintenancePending } from "./entity-migration-maintenance-pending.js";
+
+// Issue #3286: a crash between the reference rewrite and the completion hook
+// must not leave the QMD index stale. A "maintenance pending" marker beside the
+// migration journal makes the next startup's no-op replay fire the hook once.
+const MAINTENANCE_PENDING_PREFIX = "entity-canonical-id-maintenance.pending";
+
+/** Pending-marker files currently on disk (temp files excluded). */
+async function pendingMarkers(dir: string): Promise<string[]> {
+  return (await readdir(path.join(dir, "state")))
+    .filter((name) => name.startsWith(MAINTENANCE_PENDING_PREFIX) && !name.endsWith(".tmp"));
+}
+
+interface SeededCorpus {
+  dir: string;
+  legacy: string;
+  canonical: string;
+}
+
+/**
+ * Seed a corpus with one legacy-typed entity file and one memory referencing
+ * it by the legacy id, so a later run has a real rewrite to perform. The
+ * legacy file keeps its old id as the filename while its `Type:` was retyped —
+ * the production legacy shape (see entity-canonical-id-collision.test.ts).
+ */
+async function seedLegacyCorpus(): Promise<SeededCorpus> {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-3286-pending-"));
+  // Create the directory skeleton (facts/ is date-partitioned on write, so
+  // the raw file below lands in a directory ensureDirectories has made).
+  await new StorageManager(dir).ensureDirectories();
+  const name = "Nightly Ingest";
+  const legacy = normalizeEntityName(name, "automation");
+  const canonical = normalizeEntityName(name, "automation-cron-job");
+  assert.notEqual(legacy, canonical, "fixture must actually straddle the rename");
+  await writeFile(
+    path.join(dir, "entities", `${legacy}.md`),
+    `---\nid: ${legacy}\ncreated: 2026-03-01T00:00:00.000Z\nupdated: 2026-03-01T00:00:00.000Z\n---\n\n`
+    + `# ${name}\n\n**Type:** automation-cron-job\n\nRuns at 02:00.\n`,
+    "utf8",
+  );
+  // Seed the memory file fully raw with the legacy entityRef: writeMemoryFrontmatter
+  // would canonicalize the ref through the journal this pass is about to build,
+  // and a raw edit after a cached read would serve the stale parse (the corpus
+  // version only moves on managed writes).
+  const memoryPath = path.join(dir, "facts", new Date().toISOString().slice(0, 10), "note-3286.md");
+  await writeFile(
+    memoryPath,
+    [
+      "---",
+      "id: fact-3286-note",
+      "category: fact",
+      "created: 2026-03-01T00:00:00.000Z",
+      "updated: 2026-03-01T00:00:00.000Z",
+      "source: extraction",
+      "confidence: 0.8",
+      "confidenceTier: implied",
+      "tags: []",
+      `entityRef: ${legacy}`,
+      "---",
+      "",
+      `References [[${legacy}]].`,
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+  return { dir, legacy, canonical };
+}
+
+function countHook(storage: StorageManager, counter: { calls: number }, throwFirstTime = false): void {
+  storage.onEntityMigrationComplete = () => {
+    counter.calls += 1;
+    if (throwFirstTime && counter.calls === 1) throw new Error("simulated crash before maintenance was requested");
+  };
+}
+
+test("a crash after the rewrite but before the hook fires the hook once on the next no-op startup", async () => {
+  const { dir } = await seedLegacyCorpus();
+  const hook = { calls: 0 };
+  try {
+    // Pass 1: the migration rewrites; the hook throws to emulate the crash
+    // between the rewrite and maintenance being requested.
+    const first = new StorageManager(dir);
+    countHook(first, hook, true);
+    await first.ensureDirectories();
+    await first.drainEntityCanonicalIdMigration();
+    assert.equal(hook.calls, 1, "precondition: the rewriting pass reached the hook");
+
+    // Pass 2: a fresh manager replays a no-op journal; the pending marker
+    // must fire the hook exactly once, then clear itself.
+    const second = new StorageManager(dir);
+    countHook(second, hook);
+    await second.ensureDirectories();
+    await second.drainEntityCanonicalIdMigration();
+    assert.equal(hook.calls, 2, "the no-op replay must fire the hook once via the pending marker");
+    assert.equal((await pendingMarkers(dir)).length, 0, "the marker must clear after the hook");
+
+    // Pass 3: ordinary no-op startup stays quiet.
+    const third = new StorageManager(dir);
+    countHook(third, hook);
+    await third.ensureDirectories();
+    await third.drainEntityCanonicalIdMigration();
+    assert.equal(hook.calls, 2, "a no-op startup after the marker is cleared must not fire the hook");
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("a rewriting pass with a healthy hook leaves no pending marker", async () => {
+  const { dir, legacy, canonical } = await seedLegacyCorpus();
+  const hook = { calls: 0 };
+  try {
+    const storage = new StorageManager(dir);
+    countHook(storage, hook);
+    await storage.ensureDirectories();
+    await storage.drainEntityCanonicalIdMigration();
+    assert.equal(hook.calls, 1);
+    assert.equal((await pendingMarkers(dir)).length, 0);
+    const journal = JSON.parse(
+      await readFile(path.join(dir, "state", "entity-canonical-id-migration-v1.json"), "utf8"),
+    );
+    assert.equal(journal.complete, true, "precondition: the journal completed");
+    await assert.rejects(() => readFile(path.join(dir, "entities", `${legacy}.md`), "utf8"));
+    await readFile(path.join(dir, "entities", `${canonical}.md`), "utf8");
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+test("a process with no hook wired keeps the marker so a later wired start fires once", async () => {
+  const { dir } = await seedLegacyCorpus();
+  const hook = { calls: 0 };
+  try {
+    // A CLI-only process runs the rewrite with nothing to request maintenance.
+    const bare = new StorageManager(dir);
+    await bare.ensureDirectories();
+    await bare.drainEntityCanonicalIdMigration();
+    assert.equal((await pendingMarkers(dir)).length, 1, "no hook: the owed re-index must persist");
+
+    const wired = new StorageManager(dir);
+    countHook(wired, hook);
+    await wired.ensureDirectories();
+    await wired.drainEntityCanonicalIdMigration();
+    assert.equal(hook.calls, 1);
+    assert.equal((await pendingMarkers(dir)).length, 0);
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("a hook that refuses the request (shutdown) keeps the marker for the next start", async () => {
+  const { dir } = await seedLegacyCorpus();
+  const hook = { calls: 0 };
+  try {
+    const stopping = new StorageManager(dir);
+    stopping.onEntityMigrationComplete = () => {
+      hook.calls += 1;
+      return false;
+    };
+    await stopping.ensureDirectories();
+    await stopping.drainEntityCanonicalIdMigration();
+    assert.equal(hook.calls, 1);
+    assert.equal((await pendingMarkers(dir)).length, 1, "a refused request must stay owed");
+
+    const next = new StorageManager(dir);
+    countHook(next, hook);
+    await next.ensureDirectories();
+    await next.drainEntityCanonicalIdMigration();
+    assert.equal(hook.calls, 2);
+    assert.equal((await pendingMarkers(dir)).length, 0);
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("an async hook keeps the marker until its maintenance pass is served, and keeps it when that fails", async () => {
+  const { dir } = await seedLegacyCorpus();
+  try {
+    // The real hook only ARMS a debounced timer; its promise settles when the
+    // pass has run. Clearing at request time would lose the re-index to a crash
+    // or destroy() inside the debounce window (review finding on #3287).
+    const served = Promise.withResolvers<boolean>();
+    const first = new StorageManager(dir);
+    first.onEntityMigrationComplete = () => served.promise;
+    await first.ensureDirectories();
+    await first.drainEntityCanonicalIdMigration();
+    assert.equal((await pendingMarkers(dir)).length, 1, "the marker must outlive the unserved request");
+
+    served.resolve(false);
+    await drainMaintenanceSettlements(path.join(dir, "state"));
+    assert.equal((await pendingMarkers(dir)).length, 1, "a pass that did not serve the request keeps the marker");
+
+    // A later start still owes it; this time the pass is served.
+    const retry = Promise.withResolvers<boolean>();
+    const second = new StorageManager(dir);
+    second.onEntityMigrationComplete = () => retry.promise;
+    await second.ensureDirectories();
+    await second.drainEntityCanonicalIdMigration();
+    assert.equal((await pendingMarkers(dir)).length, 1);
+    retry.resolve(true);
+    await drainMaintenanceSettlements(path.join(dir, "state"));
+    assert.equal((await pendingMarkers(dir)).length, 0, "a served pass clears the marker");
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("clearing one run's marker never deletes a marker a concurrent run armed meanwhile", async () => {
+  const { dir } = await seedLegacyCorpus();
+  try {
+    const stateDir = path.join(dir, "state");
+    const first = new StorageManager(dir);
+    // Another process takes the migration lock after this run released it and
+    // arms its own marker before this run's hook returns and its clear starts.
+    let concurrentArm: Promise<string> | undefined;
+    first.onEntityMigrationComplete = () => {
+      concurrentArm = writeMaintenancePending(stateDir);
+    };
+    await first.ensureDirectories();
+    await first.drainEntityCanonicalIdMigration();
+    await drainMaintenanceSettlements(stateDir);
+    await concurrentArm;
+    assert.equal(
+      (await pendingMarkers(dir)).length,
+      1,
+      "the concurrent run's marker must survive this run's clear (it is the only owed re-index if that run crashes)",
+    );
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});