@remnic/core 10.0.49 → 10.0.51

package/src/briefing-window.ts

@@ -1,11 +1,12 @@
 import { log } from "./logger.js";
-import type { MemoryFile } from "./types.js";
+import type { EntityFile, MemoryFile } from "./types.js";
 import { isAbortError } from "./abort-error.js";
 import type { CorpusReadOptions } from "./corpus-read-cancellation.js";
 import type { ParsedBriefingWindow } from "./briefing.js";
+import type { WindowedMemoryReadOptions } from "./storage/windowed-memory-read.js";
 
 type BriefingMemoryReader = {
-  readMemoriesWindow?: (options: { updatedAfter?: Date }) => Promise<{ memories: MemoryFile[] }>;
+  readMemoriesWindow?: (options: WindowedMemoryReadOptions) => Promise<{ memories: MemoryFile[] }>;
   readAllMemories: ((options?: CorpusReadOptions) => Promise<MemoryFile[]>) & {
     supportsAbortSignal?: boolean;
   };
@@ -30,6 +31,12 @@ export const BRIEFING_FULL_READ_FALLBACK_MS = 30_000;
 export interface SafeReadMemoriesOptions {
   /** Test seam overriding {@link BRIEFING_FULL_READ_FALLBACK_MS}. */
   fallbackDeadlineMs?: number;
+  /**
+   * Caller cancellation. The signal reaches the storage read so it stops at
+   * its next boundary, and a cancelled read is rethrown rather than degraded
+   * into an empty corpus (issue #3139).
+   */
+  signal?: AbortSignal;
 }
 
 type BriefingReadMode = "windowed" | "full-read-fallback";
@@ -138,6 +145,12 @@ export async function safeReadMemories(
     resultCount = memories.length;
     return memories;
   } catch (err) {
+    if (isAbortError(err) && options.signal?.aborted) {
+      // Caller cancellation is not a read failure: rethrow it so the briefing
+      // rejects instead of degrading into an empty corpus (issue #3139). The
+      // own fallback deadline is reported as BriefingReadTimedOut below.
+      throw err;
+    }
     if (err instanceof BriefingReadTimedOut) {
       outcome = "timeout";
       bestEffortLog(
@@ -174,7 +187,9 @@ async function readBriefingMemories(
   // the full corpus on cache misses; keep the full-read fallback for custom
   // StorageManager-compatible callers that predate readMemoriesWindow().
   if (mode === "windowed") {
-    const result = await storage.readMemoriesWindow!({ updatedAfter: window.from });
+    const readOptions: WindowedMemoryReadOptions = { updatedAfter: window.from };
+    if (options.signal) readOptions.abortSignal = options.signal;
+    const result = await storage.readMemoriesWindow!(readOptions);
     return result.memories;
   }
   // Refuse legacy adapters that do not explicitly declare cancellation support (#2827).
@@ -195,12 +210,13 @@ async function readBriefingMemories(
     deadlineFired = true;
     controller.abort();
   }, deadlineMs);
+  const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
   try {
     // Direct await, no Promise.race: the signal IS the deadline. A
     // signal-aware read settles on abort (AbortError at its next scan
     // boundary, #2307), so nothing is left scanning in the background once
     // this function returns.
-    const memories = await storage.readAllMemories({ abortSignal: controller.signal });
+    const memories = await storage.readAllMemories({ abortSignal: signal });
     if (deadlineFired) {
       // A double that resolves partial rows instead of rejecting on abort
       // must not have them served as a complete corpus.
@@ -214,3 +230,16 @@ async function readBriefingMemories(
     clearTimeout(timer);
   }
 }
+
+export async function safeReadEntities(
+  storage: { readAllEntityFiles(options?: CorpusReadOptions): Promise<EntityFile[]> },
+  signal: AbortSignal,
+): Promise<EntityFile[]> {
+  try {
+    return await storage.readAllEntityFiles({ abortSignal: signal });
+  } catch (err) {
+    if (isAbortError(err) && signal.aborted) throw err;
+    log.warn(`briefing: readAllEntityFiles failed: ${err}`);
+    return [];
+  }
+}

package/src/briefing.ts

@@ -19,12 +19,14 @@ import { readFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { log } from "./logger.js";
+import { isAbortError, throwIfAborted } from "./abort-error.js";
+import { withBriefingDeadline } from "./briefing-deadline.js";
 import { withBriefingFollowupTimeout } from "./briefing-followup-timeout.js";
 import { extractJsonCandidates } from "./json-extract.js";
 import { drainPassiveCorrectionNotifications } from "./correction/passive-correction-notifications.js";
 import { excludeSupportPassportPrivateMemories } from "./support-passport/card-projection.js";
 import { normalizeEntityName, StorageManager } from "./storage.js";
-import { safeReadMemories } from "./briefing-window.js";
+import { safeReadEntities, safeReadMemories } from "./briefing-window.js";
 import { readEnvVar, resolveHomeDir } from "./runtime/env.js";
 import type {
   BriefingActiveThread,
@@ -817,6 +819,8 @@ export interface BuildBriefingOptions {
   followupGenerator?: BriefingFollowupGenerator;
   /** Injected "now" — makes tests deterministic. */
   now?: Date;
+  /** Caller cancellation must not consume correction notifications. */
+  abortSignal?: AbortSignal;
 }
 
 const MAX_ACTIVE_THREADS = 8;
@@ -830,15 +834,23 @@ const MAX_OPEN_COMMITMENTS = 8;
  * omitted and `followupsUnavailableReason` is set.
  */
 export async function buildBriefing(options: BuildBriefingOptions): Promise<BriefingResult> {
+  return withBriefingDeadline(
+    (signal) => buildBriefingWithSignal(options, signal),
+    options.abortSignal,
+  );
+}
+
+async function buildBriefingWithSignal(options: BuildBriefingOptions, signal: AbortSignal): Promise<BriefingResult> {
   const now = options.now ?? new Date();
   const window = options.window ?? defaultWindow(now);
   const maxFollowups = clampFollowups(options.maxFollowups);
   const focus = options.focus ?? null;
 
   const [allMemories, allEntities] = await Promise.all([
-    safeReadMemories(options.storage, window).then(excludeSupportPassportPrivateMemories),
-    safeReadEntities(options.storage),
+    safeReadMemories(options.storage, window, { signal }).then(excludeSupportPassportPrivateMemories),
+    safeReadEntities(options.storage, signal),
   ]);
+  throwIfAborted(signal, "briefing aborted");
 
   const memoriesInWindow = filterMemoriesByWindow(allMemories, window);
   const focusedMemories = focus
@@ -852,6 +864,7 @@ export async function buildBriefing(options: BuildBriefingOptions): Promise<Brie
   const calendarLoadResult = options.calendarSource
     ? await loadTodayCalendar(options.calendarSource, now)
     : undefined;
+  throwIfAborted(signal, "briefing aborted");
 
   const calendarSourceErrors: BriefingCalendarSourceError[] =
     calendarLoadResult?.error ? [calendarLoadResult.error] : [];
@@ -904,18 +917,20 @@ export async function buildBriefing(options: BuildBriefingOptions): Promise<Brie
       log.warn(`briefing: ${followupsUnavailableReason}`);
     }
   }
+  throwIfAborted(signal, "briefing aborted");
 
   const sections: BriefingSections = {
     ...sectionsBase,
     suggestedFollowups: followups,
   };
 
-  // Drain auto-applied passive-correction notifications (issue #1581). The
-  // queue is cleared on read, so each notification surfaces in exactly one
-  // briefing. Fail-open: a drain error never blocks the briefing.
+  // Drain auto-applied passive-correction notifications (issue #1581): cleared on read,
+  // so each surfaces in exactly one briefing. Fail-open except cancellation, which must
+  // not consume notifications nobody receives.
+  throwIfAborted(signal, "briefing aborted");
   let correctionNotifications: BriefingResult["correctionNotifications"];
   try {
-    const drained = await drainPassiveCorrectionNotifications(options.storage.dir);
+    const drained = await drainPassiveCorrectionNotifications(options.storage.dir, signal);
     if (drained.length > 0) {
       correctionNotifications = drained.map((n) => ({
         planId: n.planId,
@@ -925,6 +940,7 @@ export async function buildBriefing(options: BuildBriefingOptions): Promise<Brie
       }));
     }
   } catch (err) {
+    if (isAbortError(err)) throw err;
     log.debug(`briefing: correction notification drain failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
   }
 
@@ -977,15 +993,6 @@ function defaultWindow(now: Date): ParsedBriefingWindow {
   return { from: new Date(now.getTime() - DAY_MS), to: now, label: "yesterday" };
 }
 
-async function safeReadEntities(storage: StorageManager): Promise<EntityFile[]> {
-  try {
-    return await storage.readAllEntityFiles();
-  } catch (err) {
-    log.warn(`briefing: readAllEntityFiles failed: ${err}`);
-    return [];
-  }
-}
-
 function memoryTimestamp(memory: MemoryFile): number {
   const raw = memory.frontmatter.updated || memory.frontmatter.created;
   if (!raw) return 0;

package/src/correction/passive-correction-notifications-abort.test.ts

@@ -0,0 +1,42 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import { syncBuiltinESMExports } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import {
+  drainPassiveCorrectionNotifications,
+  enqueuePassiveCorrectionNotification,
+} from "./passive-correction-notifications.js";
+
+// Issue #3139 review: a briefing cancelled mid-drain must leave the queue
+// intact, because the caller never receives what the drain consumed.
+test("a drain cancelled after reading keeps the notification queue", async (t) => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "remnic-3139-drain-"));
+  t.after(() => fs.rm(dir, { recursive: true, force: true }));
+  await enqueuePassiveCorrectionNotification(dir, {
+    planId: "plan-1",
+    summary: "kept",
+    undoCommand: "undo",
+    createdAt: new Date(0).toISOString(),
+  });
+  const controller = new AbortController();
+  const read: (file: string, encoding: "utf-8") => Promise<string> = fs.readFile;
+  t.mock.method(fs, "readFile", async (file: string) => {
+    const content = await read(file, "utf-8");
+    controller.abort(new Error("deadline"));
+    return content;
+  });
+  syncBuiltinESMExports();
+  t.after(() => {
+    t.mock.restoreAll();
+    syncBuiltinESMExports();
+  });
+
+  await assert.rejects(drainPassiveCorrectionNotifications(dir, controller.signal), { name: "AbortError" });
+
+  t.mock.restoreAll();
+  syncBuiltinESMExports();
+  const kept = await drainPassiveCorrectionNotifications(dir);
+  assert.equal(kept.length, 1, "the cancelled drain must not consume the queue");
+});

package/src/correction/passive-correction-notifications.ts

@@ -14,6 +14,7 @@
 
 import { mkdir, readFile, rename, writeFile, unlink } from "node:fs/promises";
 import path from "node:path";
+import { throwIfAborted } from "../abort-error.js";
 import { serializeMutations } from "../utils/serialize-mutations.js";
 
 // ---------------------------------------------------------------------------
@@ -84,6 +85,7 @@ export async function enqueuePassiveCorrectionNotification(
  */
 export async function drainPassiveCorrectionNotifications(
   storageDir: string,
+  signal?: AbortSignal,
 ): Promise<PassiveCorrectionNotification[]> {
   const filePath = notificationsPath(storageDir);
   return serializeMutations(`passive-notification:${filePath}`, async () => {
@@ -96,6 +98,8 @@ export async function drainPassiveCorrectionNotifications(
       throw err;
     }
 
+    // Cancellation after the read must keep the queue: the caller never receives these.
+    throwIfAborted(signal, "briefing aborted");
     const notifications: PassiveCorrectionNotification[] = [];
     for (const line of raw.split("\n")) {
       const trimmed = line.trim();

package/src/entity-lazy-compatibility.test.ts

@@ -0,0 +1,229 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { StorageManager, parseEntityFile } from "./storage.js";
+import { sleep } from "./utils/sleep.js";
+
+async function legacyStore() {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-lazy-compat-"));
+  const seed = new StorageManager(dir);
+  const id = await seed.writeEntity("Legacy Person", "person", ["Keeps a synthetic task."]);
+  await rename(path.join(dir, "entities", `${id}.md`), path.join(dir, "entities", "legacy-person.md"));
+  const journal = path.join(dir, "state", "entity-canonical-id-migration-v1.json");
+  await rm(journal, { force: true });
+  const lock = path.join(dir, "state", "entity-canonical-id-migration.lock");
+  await writeFile(lock, `${process.pid} test-holder ${new Date().toISOString()}\n`);
+  const storage = new StorageManager(dir);
+  await storage.ensureDirectories({ waitForEntityMigration: false });
+  return { dir, id, journal, lock, storage };
+}
+
+test("canonical reads find a legacy file without a journal or migration", async () => {
+  const fixture = await legacyStore();
+  try {
+    assert.match(await fixture.storage.readEntity(fixture.id), /Keeps a synthetic task/);
+    await assert.rejects(() => readFile(fixture.journal), { code: "ENOENT" });
+    assert.ok(await readFile(fixture.lock));
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(fixture.dir, { recursive: true, force: true });
+  }
+});
+
+test("ambiguous legacy canonical matches are refused rather than picking a claimant", async () => {
+  const fixture = await legacyStore();
+  try {
+    const raw = await readFile(path.join(fixture.dir, "entities", "legacy-person.md"));
+    await writeFile(path.join(fixture.dir, "entities", "other-legacy-person.md"), raw);
+    await assert.rejects(() => fixture.storage.readEntity(fixture.id), /ambiguous/i);
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(fixture.dir, { recursive: true, force: true });
+  }
+});
+
+test("completed migration skips corpus reads on repeated misses in a fresh read-only store", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-completed-miss-"));
+  try {
+    const seed = new StorageManager(dir);
+    await seed.writeEntity("Existing Person", "person", ["Synthetic fact."]);
+    await seed.ensureDirectories();
+    const reader = new StorageManager(dir);
+    await reader.ensureDirectories({ waitForEntityMigration: false });
+    // Bracket access is TypeScript's typed escape hatch for the private reader.
+    const originalRead = reader["readStorageSecureFile"].bind(reader);
+    const reads: string[] = [];
+    reader["readStorageSecureFile"] = async (filePath: string) => {
+      reads.push(path.basename(filePath));
+      return originalRead(filePath);
+    };
+    assert.equal(await reader.readEntity("person-missing"), "");
+    assert.equal(await reader.readEntity("person-missing"), "");
+    assert.deepEqual(reads, ["person-missing.md", "person-missing.md"], "completed-store misses must not scan entity contents");
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("an external entities change invalidates the amortized completion verdict on the same reader", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-completed-cache-"));
+  try {
+    const seed = new StorageManager(dir);
+    const id = await seed.writeEntity("Café", "project", ["Synthetic legacy fact."]);
+    await seed.ensureDirectories();
+    const reader = new StorageManager(dir);
+    await reader.ensureDirectories({ waitForEntityMigration: false });
+    const canonical = reader.normalizeEntityName("Café", "project");
+    // First miss computes and caches the completion verdict.
+    assert.equal(await reader.readEntity("project-missing"), "");
+    // An external rename changes the entities directory; the cached verdict
+    // must not keep hiding the now-legacy file from the same reader.
+    await rename(path.join(dir, "entities", `${id}.md`), path.join(dir, "entities", "legacy-cafe.md"));
+    assert.match(await reader.readEntity(canonical), /Synthetic legacy fact/);
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("an external aliases change invalidates the amortized completion verdict on the same reader", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-completed-alias-cache-"));
+  try {
+    const seed = new StorageManager(dir);
+    const previousId = await seed.writeEntity("Café", "project", ["Synthetic legacy fact."]);
+    await seed.ensureDirectories();
+    const journalPath = path.join(dir, "state", "entity-canonical-id-migration-v1.json");
+    const journal = await readFile(journalPath, "utf8");
+    assert.equal(JSON.parse(journal).complete, true);
+
+    const reader = new StorageManager(dir);
+    await reader.ensureDirectories({ waitForEntityMigration: false });
+    // Warm amortized completion (and any same-reader completion memo) on a miss.
+    assert.equal(await reader.readEntity("project-missing"), "");
+
+    // Block migration repair so fingerprint drift stays visible to reads.
+    const lock = path.join(dir, "state", "entity-canonical-id-migration.lock");
+    await writeFile(lock, `${process.pid} test-holder ${new Date().toISOString()}\n`);
+
+    // External aliases.json is a getFingerprint input. It must invalidate a
+    // warm completed verdict without entities membership or mutation-version change.
+    // The entity file stays at previousId; only the alias-derived canonical id moves.
+    await mkdir(path.join(dir, "config"), { recursive: true });
+    await writeFile(path.join(dir, "config", "aliases.json"), JSON.stringify({ café: "coffee" }));
+    await reader.loadAliases();
+    const canonical = reader.normalizeEntityName("Café", "project");
+    assert.notEqual(canonical, previousId);
+
+    assert.match(await reader.readEntity(canonical), /Synthetic legacy fact/);
+    assert.equal(await readFile(journalPath, "utf8"), journal, "read compatibility must not replay migration");
+    assert.ok(await readFile(lock));
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+
+for (const change of ["aliases", "raw legacy write"]) {
+  test(`stale completed journals do not hide canonical reads after ${change}`, async () => {
+    const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-stale-completion-"));
+    try {
+      const seed = new StorageManager(dir);
+      const previousId = await seed.writeEntity("Café", "project", ["Synthetic legacy fact."]);
+      await seed.ensureDirectories();
+      const journalPath = path.join(dir, "state", "entity-canonical-id-migration-v1.json");
+      const journal = await readFile(journalPath, "utf8");
+      assert.equal(JSON.parse(journal).complete, true);
+      if (change === "aliases") {
+        await mkdir(path.join(dir, "config"), { recursive: true });
+        await writeFile(path.join(dir, "config", "aliases.json"), JSON.stringify({ café: "coffee" }));
+      } else {
+        await rename(path.join(dir, "entities", `${previousId}.md`), path.join(dir, "entities", "legacy-cafe.md"));
+        await writeFile(path.join(dir, "state", "entity-canonical-id-reconcile.pending"), "synthetic raw writer\n");
+      }
+      const lock = path.join(dir, "state", "entity-canonical-id-migration.lock");
+      await writeFile(lock, `${process.pid} test-holder ${new Date().toISOString()}\n`);
+      const reader = new StorageManager(dir);
+      await reader.ensureDirectories({ waitForEntityMigration: false });
+      const canonical = reader.normalizeEntityName("Café", "project");
+      if (change === "aliases") assert.notEqual(canonical, previousId);
+      assert.match(await reader.readEntity(canonical), /Synthetic legacy fact/);
+      assert.equal(await readFile(journalPath, "utf8"), journal, "read compatibility must not replay migration");
+      assert.ok(await readFile(lock));
+    } finally {
+      StorageManager.clearAllStaticCaches();
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+}
+
+const mutations = [
+  {
+    name: "relationship",
+    run: (s: StorageManager, id: string) => s.addEntityRelationship(id, { target: "person-peer", label: "knows" }),
+    check: (raw: string) => assert.ok(parseEntityFile(raw).relationships.some((r) => r.label === "knows")),
+  },
+  {
+    name: "activity",
+    run: (s: StorageManager, id: string) => s.addEntityActivity(id, { date: "2026-01-01", note: "Synthetic activity" }, 10),
+    check: (raw: string) => assert.ok(parseEntityFile(raw).activity.some((a) => a.note === "Synthetic activity")),
+  },
+  {
+    name: "alias",
+    run: (s: StorageManager, id: string) => s.addEntityAlias(id, "synthetic-alias"),
+    check: (raw: string) => assert.ok(parseEntityFile(raw).aliases.includes("synthetic-alias")),
+  },
+  {
+    name: "synthesis",
+    run: (s: StorageManager, id: string) => s.updateEntitySynthesis(id, "Synthetic synthesis"),
+    check: (raw: string) => assert.equal(parseEntityFile(raw).synthesis, "Synthetic synthesis"),
+  },
+  {
+    name: "fragment merge",
+    run: (s: StorageManager) => s.mergeFragmentedEntities(),
+    check: (raw: string) => assert.match(raw, /Keeps a synthetic task/),
+  },
+  {
+    name: "timeline migration",
+    run: (s: StorageManager) => s.migrateEntityFilesToCompiledTruthTimeline(),
+    check: (raw: string) => assert.match(raw, /Keeps a synthetic task/),
+  },
+];
+
+for (const caller of ["canonical", "legacy"]) {
+for (const mutation of mutations) {
+  test(`${mutation.name} awaits migration for a ${caller} caller`, async () => {
+    const fixture = await legacyStore();
+    let settled = false;
+    let failure: Error | undefined;
+    const operation = mutation.run(fixture.storage, caller === "legacy" ? "legacy-person" : fixture.id).then(
+      () => { settled = true; },
+      (error: Error) => { failure = error; settled = true; },
+    );
+    let probeFailure: unknown;
+    try {
+      await sleep(100);
+      assert.equal(settled, false, "a public entity mutation must wait behind the migration lock");
+    } catch (error) {
+      probeFailure = error;
+    } finally {
+      await rm(fixture.lock, { force: true });
+    }
+    try {
+      await operation;
+      if (probeFailure) throw probeFailure;
+      assert.equal(failure, undefined);
+      const raw = await readFile(path.join(fixture.dir, "entities", `${fixture.id}.md`), "utf8");
+      mutation.check(raw);
+      const journal = JSON.parse(await readFile(fixture.journal, "utf8"));
+      assert.equal(journal.complete, true);
+    } finally {
+      StorageManager.clearAllStaticCaches();
+      await rm(fixture.dir, { recursive: true, force: true });
+    }
+  });
+}
+}

package/src/entity-migration-completion-notification.test.ts

@@ -0,0 +1,148 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rename, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { parseConfig } from "./config.js";
+import { Orchestrator } from "./orchestrator.js";
+import { StorageManager } from "./storage.js";
+
+// #3240 follow-up: the host's onEntityMigrationComplete slot must fire once
+// per migration pass that rewrote entities (never on no-op replays or ensure() no-ops), fail open on a
+// throwing hook, reach router-created storages independent of auto-embed, and
+// be inert after Orchestrator.destroy(). No direct QMD calls; the re-arm is
+// observed through a requestQmdMaintenance spy.
+
+async function legacyEntityStore(prefix: string): Promise<string> {
+  const dir = await mkdtemp(path.join(os.tmpdir(), prefix));
+  const seed = new StorageManager(dir);
+  const id = await seed.writeEntity("Legacy Person", "person", ["Keeps a synthetic task."]);
+  await rename(path.join(dir, "entities", `${id}.md`), path.join(dir, "entities", "legacy-person.md"));
+  await rm(path.join(dir, "state", "entity-canonical-id-migration-v1.json"), { force: true });
+  return dir;
+}
+
+test("real storage fires the completion slot only for a pass that rewrote entities, and fails open on a throwing hook", async () => {
+  const dir = await legacyEntityStore("remnic-migration-complete-");
+  const emptyDir = await mkdtemp(path.join(os.tmpdir(), "remnic-migration-noop-"));
+  const throwingDir = await legacyEntityStore("remnic-migration-throwing-");
+  try {
+    const storage = new StorageManager(dir);
+    let completions = 0;
+    storage.onEntityMigrationComplete = () => {
+      completions += 1;
+    };
+    await storage.ensureDirectories();
+    assert.equal(completions, 1, "a migration pass that renamed a legacy entity must fire the completion slot");
+    await storage.ensureDirectories();
+    assert.equal(completions, 1, "a second ensureDirectories must not re-fire the slot");
+
+    const noop = new StorageManager(emptyDir);
+    let noopCompletions = 0;
+    noop.onEntityMigrationComplete = () => {
+      noopCompletions += 1;
+    };
+    await noop.ensureDirectories();
+    assert.equal(noopCompletions, 0, "a no-op replay must not ask search maintenance to run");
+
+    const throwing = new StorageManager(throwingDir);
+    let hookCalls = 0;
+    throwing.onEntityMigrationComplete = () => {
+      hookCalls += 1;
+      throw new Error("consumer hook exploded");
+    };
+    await throwing.ensureDirectories();
+    assert.equal(hookCalls, 1, "the throwing hook must still be invoked");
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+    await rm(emptyDir, { recursive: true, force: true });
+    await rm(throwingDir, { recursive: true, force: true });
+  }
+});
+
+test("orchestrator wires completion with auto-embed off and blocks it from teardown admission", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-migration-complete-orch-"));
+  const orchestrator = new Orchestrator(
+    parseConfig({
+      memoryDir: dir,
+      workspaceDir: path.join(dir, "workspace"),
+      qmdEnabled: false,
+      qmdAutoEmbedEnabled: false,
+      namespacesEnabled: true,
+      namespaceCatalogEnabled: true,
+      defaultNamespace: "default",
+      sharedNamespace: "shared",
+      namespacePolicies: [],
+      embeddingFallbackEnabled: false,
+      identityContinuityEnabled: false,
+      transcriptEnabled: false,
+      hourlySummariesEnabled: false,
+      compoundingEnabled: false,
+      knowledgeIndexEnabled: false,
+    }),
+  );
+  // Test-only access to the Orchestrator's private wiring fields: bracket access
+  // is TypeScript's typed escape hatch for private members, so no assertion.
+  const internals = {
+    get storage() { return orchestrator["storage"]; },
+    get storageRouter() { return orchestrator["storageRouter"]; },
+    get maintenanceScheduler() { return orchestrator["maintenanceScheduler"]; },
+    set requestQmdMaintenance(fn: () => void) { orchestrator["requestQmdMaintenance"] = fn; },
+  };
+  try {
+    // Wiring must exist independent of auto-embed.
+    const onMigrationComplete = internals.storage.onEntityMigrationComplete;
+    assert.ok(
+      onMigrationComplete instanceof Function,
+      "the default storage must carry the migration completion slot without auto-embed",
+    );
+    const namespaceStorage = await internals.storageRouter.storageFor("proj-a");
+    const onNamespaceMigrationComplete = namespaceStorage.onEntityMigrationComplete;
+    assert.ok(
+      onNamespaceMigrationComplete instanceof Function,
+      "a router-created namespace storage must carry the slot without auto-embed",
+    );
+
+    const rearmRequests: string[] = [];
+    internals.requestQmdMaintenance = () => {
+      rearmRequests.push("rearm");
+    };
+    assert.ok(onMigrationComplete);
+    onMigrationComplete();
+    assert.ok(onNamespaceMigrationComplete);
+    onNamespaceMigrationComplete();
+    assert.deepEqual(rearmRequests, ["rearm", "rearm"], "a completion must re-arm QMD maintenance");
+
+    const { promise: disposeGate, resolve: releaseDispose } = Promise.withResolvers<void>();
+    const { promise: disposing, resolve: signalDispose } = Promise.withResolvers<void>();
+    const originalDispose = internals.maintenanceScheduler.dispose.bind(internals.maintenanceScheduler);
+    internals.maintenanceScheduler.dispose = async () => {
+      signalDispose();
+      await disposeGate;
+      await originalDispose();
+    };
+    const teardown = orchestrator.destroy();
+    try {
+      await disposing;
+      onMigrationComplete();
+      onNamespaceMigrationComplete();
+      assert.deepEqual(rearmRequests, ["rearm", "rearm"], "teardown admission must stop completion re-arms before drains");
+    } finally {
+      releaseDispose();
+      await teardown;
+    }
+    onMigrationComplete();
+    onNamespaceMigrationComplete();
+    assert.deepEqual(
+      rearmRequests,
+      ["rearm", "rearm"],
+      "a completion after destroy must not re-arm maintenance",
+    );
+  } finally {
+    await orchestrator.destroy().catch(() => undefined);
+    StorageManager.clearAllStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/extraction-scope-source-agent.test.ts

@@ -92,13 +92,13 @@ test("scope prompt qualifies tool knowledge as project, requires naming the agen
   assert.match(captured.system, /"`git status --short` emits compact output" -> "global"/);
 });
 
-// ExtractedFactSchema is z.object(...).superRefine(...); unwrap the ZodEffects
-// to reach the scope field's describe text (named const, not an inline cast).
+// zod 4: superRefine attaches checks to the object itself — the schema stays
+// a ZodObject, so the scope field's describe text is on `.shape` directly.
 function scopeDescribe(): string {
-  const unwrapped = ExtractedFactSchema as unknown as {
-    innerType(): { shape: Record<string, { description?: string }> };
-  };
-  return unwrapped.innerType().shape.scope?.description ?? "";
+  // SAFETY: ExtractedFactSchema is a ZodObject in zod 4 (superRefine attaches
+  // checks in place); its `.shape` maps field names to schema nodes.
+  const schema = ExtractedFactSchema as { shape: Record<string, { description?: string }> };
+  return schema.shape.scope?.description ?? "";
 }
 
 test("scope field schema describe no longer lists tool configs and qualifies by agent", () => {