minimal-agent 0.11.0 → 0.13.0

package/src/memory/repository.ts

@@ -1,8 +1,10 @@
 import { watch, type FSWatcher } from 'node:fs';
 import { mkdir, readFile, readdir, rename, rm, stat, unlink } from 'node:fs/promises';
-import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
 
+import { pathContains } from '../utils/pathContains.js';
+
 import { parseMemoryRecord, serializeMemoryRecord, sha256 } from './codec.js';
 import { ALL_CATEGORIES, CATEGORY_DIR } from './constants.js';
 import {
@@ -30,8 +32,10 @@ interface CachedFile {
 }
 
 const fileCache = new Map<string, CachedFile>();
-const SCOPE_FALLBACK_TTL_MS = 1_000;
-const SCOPE_WATCH_AUDIT_MS = 30_000;
+/** 兜底审计的最小间隔：watcher 漏掉的变更最迟这么久后会被 stat 审计发现。 */
+const SCOPE_AUDIT_TTL_MS = 1_000;
+/** 「扫描期间被改动 → 重扫」的重试上限，防止持续写入把读拖成活锁。 */
+const MAX_SCAN_RETRIES = 3;
 const MAX_SCOPE_CACHE_ENTRIES = 128;
 
 const repositoryDiagnostics = {
@@ -52,18 +56,69 @@ export function resetMemoryRepositoryDiagnostics(): void {
   repositoryDiagnostics.fullScans = 0;
 }
 
-interface CachedScope {
+interface ScopeCacheEntry {
   snapshot: MemorySnapshot;
-  checkedAt: number;
   dirty: boolean;
-  watcherActive: boolean;
   directoryFingerprint: string;
   lastAuditAt: number;
+}
+
+interface ScopeRuntimeState {
+  cache?: ScopeCacheEntry;
+  watchers: FSWatcher[];
+  watcherComplete: boolean;
+  watcherRefreshRequired: boolean;
+  epoch: number;
   lastUsedAt: number;
+  lastDrainAt: number;
+  suppressDirtyUntil: number;
+}
+
+const scopeStates = new Map<string, ScopeRuntimeState>();
+
+function scopeState(key: string): ScopeRuntimeState {
+  let state = scopeStates.get(key);
+  if (!state) {
+    state = {
+      watchers: [],
+      watcherComplete: false,
+      watcherRefreshRequired: false,
+      epoch: 0,
+      lastUsedAt: 0,
+      lastDrainAt: 0,
+      suppressDirtyUntil: 0,
+    };
+    scopeStates.set(key, state);
+  }
+  return state;
 }
 
-const scopeCache = new Map<string, CachedScope>();
-const scopeWatchers = new Map<string, FSWatcher[]>();
+/** scope 目录下由本模块自己生成、不该被当成「用户改了记忆」的条目。 */
+const GENERATED_SCOPE_ENTRIES: ReadonlySet<string> = new Set([
+  'views',
+  '.transactions',
+  '.records.lock',
+]);
+const CATEGORY_SCOPE_ENTRIES = new Set(Object.values(CATEGORY_DIR));
+const WATCHER_SETTLE_REUSE_MS = 50;
+const WATCHER_SETTLE_WAIT_MS = 20;
+const INTERNAL_RECORD_EVENT_TTL_MS = 1_000;
+const internalRecordEvents = new Map<string, number>();
+
+function markInternalRecordEvent(path: string): void {
+  internalRecordEvents.set(path, Date.now() + INTERNAL_RECORD_EVENT_TTL_MS);
+}
+
+function consumeInternalRecordEvent(path: string): boolean {
+  const expiresAt = internalRecordEvents.get(path);
+  if (!expiresAt) return false;
+  if (expiresAt < Date.now()) {
+    internalRecordEvents.delete(path);
+    return false;
+  }
+  internalRecordEvents.delete(path);
+  return true;
+}
 
 interface MemoryTransactionItem {
   id: string;
@@ -84,9 +139,13 @@ function transactionRoot(base: string): string { return join(base, '.transaction
 function transactionManifestPath(base: string): string { return join(transactionRoot(base), 'current.json'); }
 function generationPath(base: string): string { return join(transactionRoot(base), 'generation'); }
 
+/**
+ * 「这个路径在不在那个目录里」只有一份实现：`src/utils/pathContains.ts`。
+ * 这里只负责把两边解析成绝对路径（manifest 里的路径来自 JSON，可能是相对的），
+ * 判据本身不再手写第五遍——那个 util 的头注释专门警告过手写副本会各自漂移。
+ */
 function pathInside(base: string, path: string): boolean {
-  const rel = relative(resolve(base), resolve(path));
-  return rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+  return pathContains(resolve(base), resolve(path));
 }
 
 async function readGeneration(base: string): Promise<string> {
@@ -99,7 +158,12 @@ async function readTransactionManifest(base: string): Promise<MemoryTransactionM
     throw error;
   });
   if (raw === null) return null;
-  const parsed = JSON.parse(raw) as MemoryTransactionManifest;
+  let parsed: MemoryTransactionManifest;
+  try {
+    parsed = JSON.parse(raw) as MemoryTransactionManifest;
+  } catch {
+    throw new Error('MEMORY_TRANSACTION_CORRUPT');
+  }
   if (parsed.schemaVersion !== 1 || !parsed.id || !Array.isArray(parsed.items)) {
     throw new Error('MEMORY_TRANSACTION_CORRUPT');
   }
@@ -129,6 +193,8 @@ async function rollForwardTransactionUnlocked(base: string): Promise<void> {
       throw new Error('MEMORY_TRANSACTION_CONFLICT');
     }
     await mkdir(dirname(item.nextPath), { recursive: true, mode: 0o700 });
+    markInternalRecordEvent(item.nextPath);
+    if (item.oldPath !== item.nextPath) markInternalRecordEvent(item.oldPath);
     await rename(item.stagePath, item.nextPath);
     if (item.oldPath !== item.nextPath) await unlink(item.oldPath).catch(() => {});
   }
@@ -137,91 +203,332 @@ async function rollForwardTransactionUnlocked(base: string): Promise<void> {
   await rm(join(transactionRoot(base), manifest.id), { recursive: true, force: true });
 }
 
-async function recoverScopeTransaction(base: string): Promise<boolean> {
-  const manifest = await readTransactionManifest(base);
-  if (!manifest) return false;
+const TRANSACTION_POISON_ERRORS = new Set([
+  'MEMORY_TRANSACTION_CORRUPT',
+  'MEMORY_TRANSACTION_PATH_INVALID',
+  'MEMORY_TRANSACTION_CONFLICT',
+]);
+
+interface ScopeRecovery {
+  recovered: boolean;
+}
+
+interface QuarantineMetadata {
+  schemaVersion: 1;
+  quarantinedAt: number;
+  reason: string;
+  originalManifestPath: string;
+}
+
+async function quarantineDiagnosticsFor(base: string): Promise<MemoryDiagnostic[]> {
+  const root = transactionRoot(base);
+  let names: string[];
+  try {
+    names = (await readdir(root, { withFileTypes: true }))
+      .filter((entry) => entry.isDirectory() && entry.name.startsWith('quarantine-'))
+      .map((entry) => entry.name);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+  const diagnostics: MemoryDiagnostic[] = [];
+  for (const name of names.sort()) {
+    const target = join(root, name);
+    let metadata: QuarantineMetadata | null = null;
+    try {
+      metadata = JSON.parse(await readFile(join(target, 'diagnostic.json'), 'utf8')) as QuarantineMetadata;
+    } catch {
+      // 旧版本隔离目录没有元数据时仍需告警，不能因升级让诊断沉默。
+    }
+    const reason = metadata?.reason ?? 'MEMORY_TRANSACTION_QUARANTINED';
+    diagnostics.push({
+      path: metadata?.originalManifestPath ?? join(target, 'current.json'),
+      message:
+        `记忆事务无法前滚（${reason}），已隔离到 ${target} 并继续读取现有记录；`
+        + '该批次的改动可能只应用了一部分，请复核相关记忆。',
+    });
+  }
+  return diagnostics;
+}
+
+export async function clearScopeTransactionQuarantine(
+  scope: MemoryScope,
+  workspaceId?: string,
+): Promise<void> {
+  const root = transactionRoot(scopeDirectory(scope, workspaceId));
+  let names: string[] = [];
+  try {
+    names = (await readdir(root, { withFileTypes: true }))
+      .filter((entry) => entry.isDirectory() && entry.name.startsWith('quarantine-'))
+      .map((entry) => entry.name);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+  }
+  await Promise.all(names.map(async (name) => {
+    const quarantine = join(root, name);
+    try {
+      const manifest = JSON.parse(await readFile(join(quarantine, 'current.json'), 'utf8')) as { id?: unknown };
+      if (typeof manifest.id === 'string' && /^[a-f0-9-]{16,}$/i.test(manifest.id)) {
+        await rm(join(root, manifest.id), { recursive: true, force: true });
+      }
+    } catch {
+      // 损坏清单本来就可能无法解析；清理隔离目录仍继续。
+    }
+    await rm(quarantine, { recursive: true, force: true });
+  }));
+  invalidateScope(scope, workspaceId);
+}
+
+/** 隔离操作的专用锁路径（实际锁文件是 `<它>.lock`）。 */
+function quarantineLockPath(base: string): string {
+  return join(transactionRoot(base), '.quarantine');
+}
+
+/**
+ * 把无法前滚的事务清单挪进 `.transactions/quarantine-<ts>/`，让读路径继续可用。
+ *
+ * ⚠️ 这是**读路径**独有的策略；写路径（replaceMemoryBatchVersioned）仍然照常抛错——
+ * 写入方必须看到冲突，不能替它把别人已提交的事务悄悄扔掉。
+ *
+ * ⚠️ **必须持 `.quarantine` 锁调用**（见 quarantineTransaction）。它是
+ * `mkdir + rename + unlink + 写元数据` 的多步变更，无锁并发会各建一个隔离目录。
+ */
+async function quarantineTransactionLocked(base: string, reason: string): Promise<void> {
+  const manifestPath = transactionManifestPath(base);
+  const manifestRaw = await readFile(manifestPath, 'utf8').catch(() => null);
+  // 拿到锁后清单已经不在 = 另一个读者/进程刚刚隔离过同一份。直接返回：
+  // 不重复建目录、不重复告警。这一条取代了以前那个只覆盖 ENOENT 交错的特判。
+  if (manifestRaw === null) return;
+
+  const target = join(
+    transactionRoot(base),
+    `quarantine-${Date.now()}-${randomUUID().slice(0, 8)}`,
+  );
+  await mkdir(target, { recursive: true, mode: 0o700 });
+  let claimed = true;
+  try {
+    await rename(manifestPath, join(target, 'current.json'));
+  } catch {
+    // 跨卷或某些网络盘上 rename 可能失败。必须先保存并校验副本，再移除原清单；
+    // 不能为了让读路径继续就丢掉唯一的恢复证据。
+    const preserved = join(target, 'current.json');
+    await atomicWriteFile(preserved, manifestRaw).catch(() => undefined);
+    const verified = await readFile(preserved, 'utf8')
+      .then((value) => sha256(value) === sha256(manifestRaw))
+      .catch(() => false);
+    claimed = verified
+      ? await unlink(manifestPath).then(() => true).catch(() => false)
+      : false;
+  }
+  if (!claimed) {
+    // 证据没保住就别留下空目录——它会被 quarantineDiagnosticsFor 当成一次真实隔离，
+    // 报出「已隔离到 XXX」却什么都恢复不了。
+    await rm(target, { recursive: true, force: true }).catch(() => undefined);
+    return;
+  }
+  const metadata: QuarantineMetadata = {
+    schemaVersion: 1,
+    quarantinedAt: Date.now(),
+    reason,
+    originalManifestPath: manifestPath,
+  };
+  await atomicWriteFile(join(target, 'diagnostic.json'), `${JSON.stringify(metadata, null, 2)}\n`)
+    .catch(() => undefined);
+}
+
+/**
+ * 加锁版入口。用**独立**的 `.quarantine` 锁而不是 `.records`：
+ * 需要互斥的只有「另一个隔离尝试」——合法的在飞事务其清单由 atomicWriteFile 写出，
+ * 永远是完整可解析的，不会被误隔离，所以无需与记录写入互斥。
+ * 而且 `memoryService.remember()` 是**持着 `.records` 锁**调用 scanMemoryScope 的，
+ * 这里若复用 `.records` 会自锁（文件锁不可重入）直接等到超时。
+ */
+async function quarantineTransaction(base: string, reason: string): Promise<void> {
+  const release = await acquireFileLock(quarantineLockPath(base));
+  try {
+    await quarantineTransactionLocked(base, reason);
+  } finally {
+    await release();
+  }
+}
+
+async function recoverScopeTransaction(base: string): Promise<ScopeRecovery> {
+  let manifestExists: boolean;
+  try {
+    manifestExists = (await readTransactionManifest(base)) !== null;
+  } catch (error) {
+    const reason = (error as Error).message;
+    if (!TRANSACTION_POISON_ERRORS.has(reason)) throw error;
+    // 清单读不出来（结构损坏 / JSON 语法错 / 路径越界）→ 隔离。
+    // ⚠️ 这里曾写着「锁都不必拿，直接隔离」并真的裸调 —— 那是错的：隔离是多步文件变更，
+    //    两个并发读者（典型触发者：一次 remember() 后台刷新视图的扫描 + 用户这次读）
+    //    会各建一个隔离目录，其中一个还留不下 current.json，却照样报「已隔离到 XXX」。
+    //    同一函数在下面 roll-forward 失败处本来就是持锁调用的，这个不对称就是缺陷本身。
+    await quarantineTransaction(base, reason);
+    return { recovered: true };
+  }
+  if (!manifestExists) return { recovered: false };
   const release = await acquireFileLock(join(base, '.records'));
   try {
     await rollForwardTransactionUnlocked(base);
+  } catch (error) {
+    const reason = (error as Error).message;
+    if (!TRANSACTION_POISON_ERRORS.has(reason)) throw error;
+    await quarantineTransaction(base, reason);
+    return { recovered: true };
   } finally {
     await release();
   }
-  return true;
+  return { recovered: true };
 }
 
 function scopeKey(scope: MemoryScope, workspaceId?: string): string {
   return scopeDirectory(scope, workspaceId);
 }
 
-async function withTopicView(
-  snapshot: MemorySnapshot,
+/**
+ * 重建 `views/topics.md`（人类可读视图，不是权威数据）。
+ *
+ * 只在两种时刻调用：**全量扫描之后**，以及**记忆变更之后**。读路径不再触发它——
+ * 否则每次 recall / 建上下文包都要 readFile 一次，连「缓存命中」都带磁盘 IO，
+ * 而且 read-only 会话也会写盘。
+ */
+export async function refreshTopicView(
   scope: MemoryScope,
   workspaceId?: string,
-): Promise<MemorySnapshot> {
-  await ensureTopicView(snapshot, scope, workspaceId).catch(() => undefined);
-  return snapshot;
+): Promise<void> {
+  const snapshot = await scanMemoryScope(scope, workspaceId);
+  await ensureTopicView(snapshot, scope, workspaceId);
+}
+
+function currentEpoch(key: string): number {
+  return scopeState(key).epoch;
 }
 
 function invalidateScope(scope: MemoryScope, workspaceId?: string): void {
-  const cached = scopeCache.get(scopeKey(scope, workspaceId));
-  if (cached) {
-    cached.dirty = true;
+  const key = scopeKey(scope, workspaceId);
+  const state = scopeState(key);
+  state.epoch += 1;
+  if (state.cache && !state.cache.dirty) {
+    state.cache.dirty = true;
     repositoryDiagnostics.watchInvalidations += 1;
   }
 }
 
+function closeScopeWatchers(state: ScopeRuntimeState): void {
+  for (const watcher of state.watchers) watcher.close();
+  state.watchers = [];
+  state.watcherComplete = false;
+}
+
 function ensureScopeWatcher(
   base: string,
   scope: MemoryScope,
   workspaceId?: string,
 ): boolean {
   const key = scopeKey(scope, workspaceId);
-  if (scopeWatchers.has(key)) return true;
+  const state = scopeState(key);
+  if (state.watchers.length && !state.watcherRefreshRequired) return state.watcherComplete;
+  closeScopeWatchers(state);
+  state.watcherRefreshRequired = false;
   try {
     const watchers: FSWatcher[] = [];
-    const watchPath = (path: string): void => {
-      const watcher = watch(path, () => invalidateScope(scope, workspaceId));
+    const rootWatcher = watch(base, (event, filename) => {
+      if (typeof filename !== 'string') {
+        // 根目录的无名事件无法判定来源，不直接打脏；让下次读立即做轻量审计。
+        if (state.cache) state.cache.lastAuditAt = 0;
+        return;
+      }
+      if (GENERATED_SCOPE_ENTRIES.has(filename)) return;
+      if (event !== 'rename' || !CATEGORY_SCOPE_ENTRIES.has(filename)) return;
+      state.watcherRefreshRequired = true;
+      invalidateScope(scope, workspaceId);
+    });
+    rootWatcher.unref();
+    watchers.push(rootWatcher);
+
+    const watchCategory = (path: string): void => {
+      const watcher = watch(path, (_event, filename) => {
+        if (typeof filename === 'string' && !filename.endsWith('.md')) return;
+        if (typeof filename === 'string' && consumeInternalRecordEvent(join(path, filename))) return;
+        // 全量扫描刚结束时，部分平台会延迟送达「已被该快照包含」的旧事件。
+        // 这个短窗口内不盲目打脏，而是强制下次读做版本/目录审计；因此真实外部
+        // 修改仍会被发现，而迟到的旧事件不会导致无意义全量重扫。
+        if (Date.now() < state.suppressDirtyUntil) {
+          if (state.cache) state.cache.lastAuditAt = 0;
+          return;
+        }
+        invalidateScope(scope, workspaceId);
+      });
       watcher.unref();
       watchers.push(watcher);
     };
-    watchPath(base);
+    // ★ 覆盖必须**完整**才敢自称 watcherActive，否则读路径不能享受 1 秒信任窗（见下）。
+    //   实测（Windows，`fs.watch` 非递归）：手工编辑 `<base>/profile/x.md` 只触发**分类目录**
+    //   上的 watcher（`change x.md`），base 上的 watcher 一声不吭——所以分类目录的 watcher
+    //   是「改动能不能被发现」的唯一依据。
+    //   ⚠️ 「不存在的分类目录」不算覆盖缺口：它装不下任何记录，而且它**被创建**时 base 上的
+    //   watcher 会收到 `rename <category>`（同样实测过），照样能作废缓存。只有目录确实存在
+    //   却挂不上 watcher（句柄耗尽、权限、网络盘…）才是真缺口，那时必须每次读都做审计。
+    let complete = true;
     for (const category of ALL_CATEGORIES) {
-      try { watchPath(join(base, CATEGORY_DIR[category])); } catch { /* absent category */ }
+      try {
+        watchCategory(join(base, CATEGORY_DIR[category]));
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') complete = false;
+      }
     }
     const fallback = () => {
-      for (const watcher of watchers) watcher.close();
-      scopeWatchers.delete(key);
-      const cached = scopeCache.get(key);
-      if (cached) watcherActiveFallback(cached);
+      closeScopeWatchers(state);
+      state.watcherRefreshRequired = true;
+      if (state.cache) watcherActiveFallback(state.cache);
     };
     for (const watcher of watchers) watcher.on('error', fallback);
-    scopeWatchers.set(key, watchers);
-    return true;
+    state.watchers = watchers;
+    state.watcherComplete = complete;
+    return complete;
   } catch {
+    closeScopeWatchers(state);
     return false;
   }
 }
 
-function watcherActiveFallback(cached: CachedScope): void {
-  cached.watcherActive = false;
+function watcherActiveFallback(cached: ScopeCacheEntry): void {
   cached.dirty = true;
 }
 
 function evictScopeCaches(): void {
-  if (scopeCache.size <= MAX_SCOPE_CACHE_ENTRIES) return;
-  const victims = [...scopeCache.entries()]
+  if (scopeStates.size <= MAX_SCOPE_CACHE_ENTRIES) return;
+  const victims = [...scopeStates.entries()]
     .sort((a, b) => a[1].lastUsedAt - b[1].lastUsedAt)
-    .slice(0, scopeCache.size - MAX_SCOPE_CACHE_ENTRIES);
+    .slice(0, scopeStates.size - MAX_SCOPE_CACHE_ENTRIES);
   for (const [key] of victims) {
-    scopeCache.delete(key);
-    for (const watcher of scopeWatchers.get(key) ?? []) watcher.close();
-    scopeWatchers.delete(key);
+    const state = scopeStates.get(key);
+    if (state) closeScopeWatchers(state);
+    scopeStates.delete(key);
+    // ⚠️ 不能写 `path.startsWith(`${key}/`)`：Windows 上分隔符是 `\`，该条件恒为 false，
+    //    被淘汰 scope 的文件缓存永远清不掉 → fileCache 无上限增长。
     for (const path of fileCache.keys()) {
-      if (path.startsWith(`${key}/`)) fileCache.delete(path);
+      if (pathContains(key, path)) fileCache.delete(path);
     }
   }
 }
 
+async function settleRecentWatcherEvents(state: ScopeRuntimeState): Promise<boolean> {
+  await new Promise<void>((resolvePromise) => { setImmediate(resolvePromise); });
+  if (state.cache?.dirty) return false;
+  const now = Date.now();
+  if (now - state.lastDrainAt >= WATCHER_SETTLE_REUSE_MS) {
+    await new Promise<void>((resolvePromise) => {
+      setTimeout(resolvePromise, WATCHER_SETTLE_WAIT_MS);
+    });
+    state.lastDrainAt = Date.now();
+  }
+  // 正常 watcher 在上面的 settle 窗口中会直接打脏；扫描结束后的抑制窗口只把
+  // lastAuditAt 清零，故仅这一种情况需要逐文件核验。稳定缓存不做 stat 扫描。
+  return state.cache?.lastAuditAt === 0 || Date.now() < state.suppressDirtyUntil;
+}
+
 async function cachedFilesUnchanged(snapshot: MemorySnapshot): Promise<boolean> {
   const checks = await Promise.all(snapshot.records.map(async (record) => {
     const path = memoryRecordPath(record);
@@ -282,50 +589,82 @@ async function readCached(path: string): Promise<CachedFile> {
 export async function scanMemoryScope(
   scope: MemoryScope,
   workspaceId?: string,
+  attempt = 0,
 ): Promise<MemorySnapshot> {
   const base = scopeDirectory(scope, workspaceId);
   const key = scopeKey(scope, workspaceId);
-  const recovered = await recoverScopeTransaction(base);
-  let cachedScope = scopeCache.get(key);
-  if (recovered && cachedScope) cachedScope.dirty = true;
+  const state = scopeState(key);
+  const recovery = await recoverScopeTransaction(base);
+  let cachedScope = state.cache;
+  if (recovery.recovered && cachedScope) cachedScope.dirty = true;
   const generationBefore = await readGeneration(base);
   const now = Date.now();
-  // A hand edit may complete immediately before this call while fs.watch has
-  // already queued (but not dispatched) its callback. Yield one event-loop turn
-  // so the watcher can invalidate without falling back to O(record-count) stats.
-  if (
-    cachedScope?.watcherActive
-    && !cachedScope.dirty
-    && now - cachedScope.lastUsedAt < 50
-  ) {
-    await new Promise<void>((resolvePromise) => setTimeout(resolvePromise, 20));
-    cachedScope = scopeCache.get(key);
-  }
+  // ★ 读路径保持纯读：缓存命中直接返回快照，不再顺手 readFile / 写 views/topics.md。
+  //   旧实现把 ensureTopicView 挂在**所有**返回分支上，于是「缓存命中」仍有磁盘 IO，
+  //   而且 memoryAccess:'read-only' 的会话也会写盘——仓储的读 API 不该有副作用。
+  //   视图改由「全量扫描后」与「变更后」触发（见 refreshTopicView）。
+  // ★ 新鲜度两条腿，缺一不可：
+  //
+  //   ① **排空一次事件循环**再判 dirty。`fs.watch` 的回调是排队派发的，「watcher 已挂上」
+  //      不等于「它已经把刚才那次改动告诉我了」。实测（Windows）：改完文件后只要让出
+  //      一个 setImmediate tick，事件就已送达。这一步零 IO，却把「刚改完立刻读」这个
+  //      最常见的竞态消掉了。旧代码也想干这事，但把它锁在「距上次使用 <50ms」的条件里，
+  //      两次读之间只要多做点别的（哪怕只是写一次设置）就绕过去了。
+  //
+  //   ② watcher 覆盖不全或压根没触发时，用 stat 审计兜底，节流到每秒最多一次。
+  //      审计是 O(记录数) 次 stat——实测 300 条记录约 40ms，放在每次读上太贵
+  //      （每回合 recall + buildContextBundle 各一次），所以必须节流；但 30 秒的信任窗
+  //      又太松，手编要等半分钟才生效。1 秒是两边都能接受的点。
+  //
+  //   ⚠️ 别再让读路径去写 `views/topics.md` 来「顺便」作废缓存——那是以前手编能被发现的
+  //      真实原因，纯属巧合，代价是每次读都做磁盘 IO。
+  let verifyAfterSettle = false;
   if (cachedScope && !cachedScope.dirty) {
-    cachedScope.lastUsedAt = now;
-    if (cachedScope.watcherActive && now - cachedScope.lastAuditAt < SCOPE_WATCH_AUDIT_MS) {
-      repositoryDiagnostics.snapshotHits += 1;
-      return withTopicView(cachedScope.snapshot, scope, workspaceId);
+    verifyAfterSettle = await settleRecentWatcherEvents(state);
+    cachedScope = state.cache;
+  }
+  if (cachedScope && !cachedScope.dirty && verifyAfterSettle) {
+    repositoryDiagnostics.fallbackAudits += 1;
+    if (
+      !await cachedFilesUnchanged(cachedScope.snapshot)
+      || cachedScope.directoryFingerprint !== await directoryFingerprint(base)
+    ) {
+      cachedScope.dirty = true;
+    } else {
+      cachedScope.lastAuditAt = Date.now();
     }
-    if (!cachedScope.watcherActive && now - cachedScope.checkedAt < SCOPE_FALLBACK_TTL_MS) {
+  }
+  if (cachedScope && !cachedScope.dirty) {
+    state.lastUsedAt = now;
+    // 只有 watcher 覆盖完整时才敢跳过审计——覆盖有缺口就等于没人会告诉我们变更，
+    // 那个 1 秒信任窗就失去依据，必须每次读都审计。
+    if (state.watcherComplete && now - cachedScope.lastAuditAt < SCOPE_AUDIT_TTL_MS) {
       repositoryDiagnostics.snapshotHits += 1;
-      return withTopicView(cachedScope.snapshot, scope, workspaceId);
+      return cachedScope.snapshot;
     }
     repositoryDiagnostics.fallbackAudits += 1;
     if (
       await cachedFilesUnchanged(cachedScope.snapshot)
       && cachedScope.directoryFingerprint === await directoryFingerprint(base)
     ) {
-      cachedScope.checkedAt = now;
       cachedScope.lastAuditAt = now;
       repositoryDiagnostics.snapshotHits += 1;
-      return withTopicView(cachedScope.snapshot, scope, workspaceId);
+      return cachedScope.snapshot;
     }
     cachedScope.dirty = true;
   }
   repositoryDiagnostics.fullScans += 1;
+  // ★ 先挂 watcher 再读文件，并记下代际号。
+  //   旧顺序是「先把记录全读完，最后才挂 watcher」，中间那段窗口里发生的改动**两头都漏**：
+  //   读的时候还没改，watcher 又还没挂上——扫完却把这份已经过时的快照标记为干净缓存，
+  //   于是直到下一次兜底审计（现在是 1 秒）之前，谁都发现不了。这是原设计里的 TOCTOU。
+  //   现在：先挂 watcher，扫完再比对代际号，期间有任何改动就重扫。
+  const watcherActive = ensureScopeWatcher(base, scope, workspaceId);
+  const epochBefore = currentEpoch(key);
   const records: MemoryRecordV2[] = [];
-  const diagnostics: MemoryDiagnostic[] = [];
+  // 隔离事务留下的告警要跟着本次快照走完，不能只写日志然后消失——
+  // diagnostics 是既有的、Desktop 与 diagnosticSuffix() 都会展示的通道。
+  const diagnostics: MemoryDiagnostic[] = await quarantineDiagnosticsFor(base);
   const versions: Record<string, MemoryVersion> = {};
   const seen = new Set<string>();
   for (const category of ALL_CATEGORIES) {
@@ -369,35 +708,45 @@ export async function scanMemoryScope(
     }
   }
 
+  // 同上：硬编码 `/` 在 Windows 上永不命中，已删除记录的缓存条目会永久滞留。
   for (const path of fileCache.keys()) {
-    if (
-      path.startsWith(`${base}/`) &&
-      path.endsWith('.md') &&
-      !seen.has(path)
-    ) {
+    if (path.endsWith('.md') && !seen.has(path) && pathContains(base, path)) {
       fileCache.delete(path);
     }
   }
   records.sort((a, b) => b.updatedAt - a.updatedAt);
   const snapshot = { records, versions, diagnostics, createdAt: Date.now() };
-  if (await recoverScopeTransaction(base) || generationBefore !== await readGeneration(base)) {
+  const tailRecovery = await recoverScopeTransaction(base);
+  if (
+    (tailRecovery.recovered || generationBefore !== await readGeneration(base))
+    && attempt < MAX_SCAN_RETRIES
+  ) {
     invalidateScope(scope, workspaceId);
-    return scanMemoryScope(scope, workspaceId);
+    return scanMemoryScope(scope, workspaceId, attempt + 1);
   }
-  for (const watcher of scopeWatchers.get(key) ?? []) watcher.close();
-  scopeWatchers.delete(key);
-  const watcherActive = ensureScopeWatcher(base, scope, workspaceId);
-  scopeCache.set(key, {
+  // 让排队中的 watcher 回调先送达，再判断这次扫描期间有没有人改过东西。
+  await new Promise<void>((resolvePromise) => { setImmediate(resolvePromise); });
+  // ⚠️ 重试必须有上限：持续写入的场景（cron 批量、另一个宿主导入、迁移）下每次重扫都会
+  //    看到新的代际号，无上限就是**活锁——读永远不返回**（还每轮重开 7 个 watcher）。
+  //    撞顶就照常缓存，让 1 秒兜底审计去纠正：最坏是几毫秒的陈旧快照且会自愈，
+  //    远好过一次挂死的 recall。
+  const changedDuringScan = currentEpoch(key) !== epochBefore;
+  if (changedDuringScan && attempt < MAX_SCAN_RETRIES) {
+    return scanMemoryScope(scope, workspaceId, attempt + 1);
+  }
+  state.cache = {
     snapshot,
-    checkedAt: Date.now(),
     dirty: false,
-    watcherActive,
     directoryFingerprint: await directoryFingerprint(base),
-    lastAuditAt: Date.now(),
-    lastUsedAt: Date.now(),
-  });
+    // 撞了重试上限才落库的快照是**已知可能陈旧**的，不能再送它一个完整的 1 秒信任窗——
+    // 把审计时间戳清零，下一次读立刻走 stat 审计纠正。
+    lastAuditAt: changedDuringScan ? 0 : Date.now(),
+  };
+  state.watcherComplete = watcherActive;
+  state.lastUsedAt = Date.now();
+  state.suppressDirtyUntil = Date.now() + 100;
   evictScopeCaches();
-  return withTopicView(snapshot, scope, workspaceId);
+  return snapshot;
 }
 
 export async function readVersionedMemory(
@@ -415,6 +764,7 @@ export async function writeNewMemory(
 ): Promise<MemoryVersion> {
   const path = memoryRecordPath(record);
   const content = serializeMemoryRecord(record);
+  markInternalRecordEvent(path);
   await atomicWriteFile(path, content);
   fileCache.delete(path);
   invalidateScope(record.scope, record.workspaceId);
@@ -521,6 +871,7 @@ export async function removeVersionedMemory(
         throw new Error('MEMORY_VERSION_CONFLICT');
     }
     try {
+      markInternalRecordEvent(path);
       await unlink(path);
       fileCache.delete(path);
       invalidateScope(current.record.scope, current.record.workspaceId);
@@ -536,7 +887,7 @@ export async function removeVersionedMemory(
 
 export function clearMemoryIndex(): void {
   fileCache.clear();
-  scopeCache.clear();
-  for (const watchers of scopeWatchers.values()) for (const watcher of watchers) watcher.close();
-  scopeWatchers.clear();
+  internalRecordEvents.clear();
+  for (const state of scopeStates.values()) closeScopeWatchers(state);
+  scopeStates.clear();
 }