minimal-agent 0.11.0 → 0.12.0

package/src/memory/repository.js

@@ -1,14 +1,17 @@
 import { watch } 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 { acquireFileLock, atomicWriteFile, memoryRecordPath, scopeDirectory, } from './fileStore.js';
 import { ensureTopicView } from './topicView.js';
 const fileCache = new Map();
-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 = {
     snapshotHits: 0,
@@ -25,14 +28,58 @@ export function resetMemoryRepositoryDiagnostics() {
     repositoryDiagnostics.fallbackAudits = 0;
     repositoryDiagnostics.fullScans = 0;
 }
-const scopeCache = new Map();
-const scopeWatchers = new Map();
+const scopeStates = new Map();
+function scopeState(key) {
+    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;
+}
+/** scope 目录下由本模块自己生成、不该被当成「用户改了记忆」的条目。 */
+const GENERATED_SCOPE_ENTRIES = 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();
+function markInternalRecordEvent(path) {
+    internalRecordEvents.set(path, Date.now() + INTERNAL_RECORD_EVENT_TTL_MS);
+}
+function consumeInternalRecordEvent(path) {
+    const expiresAt = internalRecordEvents.get(path);
+    if (!expiresAt)
+        return false;
+    if (expiresAt < Date.now()) {
+        internalRecordEvents.delete(path);
+        return false;
+    }
+    internalRecordEvents.delete(path);
+    return true;
+}
 function transactionRoot(base) { return join(base, '.transactions'); }
 function transactionManifestPath(base) { return join(transactionRoot(base), 'current.json'); }
 function generationPath(base) { return join(transactionRoot(base), 'generation'); }
+/**
+ * 「这个路径在不在那个目录里」只有一份实现：`src/utils/pathContains.ts`。
+ * 这里只负责把两边解析成绝对路径（manifest 里的路径来自 JSON，可能是相对的），
+ * 判据本身不再手写第五遍——那个 util 的头注释专门警告过手写副本会各自漂移。
+ */
 function pathInside(base, path) {
-    const rel = relative(resolve(base), resolve(path));
-    return rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+    return pathContains(resolve(base), resolve(path));
 }
 async function readGeneration(base) {
     return readFile(generationPath(base), 'utf8').catch(() => '');
@@ -45,7 +92,13 @@ async function readTransactionManifest(base) {
     });
     if (raw === null)
         return null;
-    const parsed = JSON.parse(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('MEMORY_TRANSACTION_CORRUPT');
+    }
     if (parsed.schemaVersion !== 1 || !parsed.id || !Array.isArray(parsed.items)) {
         throw new Error('MEMORY_TRANSACTION_CORRUPT');
     }
@@ -75,6 +128,9 @@ async function rollForwardTransactionUnlocked(base) {
             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(() => { });
@@ -83,89 +139,321 @@ async function rollForwardTransactionUnlocked(base) {
     await unlink(transactionManifestPath(base)).catch(() => { });
     await rm(join(transactionRoot(base), manifest.id), { recursive: true, force: true });
 }
+const TRANSACTION_POISON_ERRORS = new Set([
+    'MEMORY_TRANSACTION_CORRUPT',
+    'MEMORY_TRANSACTION_PATH_INVALID',
+    'MEMORY_TRANSACTION_CONFLICT',
+]);
+async function quarantineDiagnosticsFor(base) {
+    const root = transactionRoot(base);
+    let names;
+    try {
+        names = (await readdir(root, { withFileTypes: true }))
+            .filter((entry) => entry.isDirectory() && entry.name.startsWith('quarantine-'))
+            .map((entry) => entry.name);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const diagnostics = [];
+    for (const name of names.sort()) {
+        const target = join(root, name);
+        let metadata = null;
+        try {
+            metadata = JSON.parse(await readFile(join(target, 'diagnostic.json'), 'utf8'));
+        }
+        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, workspaceId) {
+    const root = transactionRoot(scopeDirectory(scope, workspaceId));
+    let names = [];
+    try {
+        names = (await readdir(root, { withFileTypes: true }))
+            .filter((entry) => entry.isDirectory() && entry.name.startsWith('quarantine-'))
+            .map((entry) => entry.name);
+    }
+    catch (error) {
+        if (error.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'));
+            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) {
+    return join(transactionRoot(base), '.quarantine');
+}
+/**
+ * 把无法前滚的事务清单挪进 `.transactions/quarantine-<ts>/`，让读路径继续可用。
+ *
+ * ⚠️ 这是**读路径**独有的策略；写路径（replaceMemoryBatchVersioned）仍然照常抛错——
+ * 写入方必须看到冲突，不能替它把别人已提交的事务悄悄扔掉。
+ *
+ * ⚠️ **必须持 `.quarantine` 锁调用**（见 quarantineTransaction）。它是
+ * `mkdir + rename + unlink + 写元数据` 的多步变更，无锁并发会各建一个隔离目录。
+ */
+async function quarantineTransactionLocked(base, reason) {
+    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 = {
+        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, reason) {
+    const release = await acquireFileLock(quarantineLockPath(base));
+    try {
+        await quarantineTransactionLocked(base, reason);
+    }
+    finally {
+        await release();
+    }
+}
 async function recoverScopeTransaction(base) {
-    const manifest = await readTransactionManifest(base);
-    if (!manifest)
-        return false;
+    let manifestExists;
+    try {
+        manifestExists = (await readTransactionManifest(base)) !== null;
+    }
+    catch (error) {
+        const reason = 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.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, workspaceId) {
     return scopeDirectory(scope, workspaceId);
 }
-async function withTopicView(snapshot, scope, workspaceId) {
-    await ensureTopicView(snapshot, scope, workspaceId).catch(() => undefined);
-    return snapshot;
+/**
+ * 重建 `views/topics.md`（人类可读视图，不是权威数据）。
+ *
+ * 只在两种时刻调用：**全量扫描之后**，以及**记忆变更之后**。读路径不再触发它——
+ * 否则每次 recall / 建上下文包都要 readFile 一次，连「缓存命中」都带磁盘 IO，
+ * 而且 read-only 会话也会写盘。
+ */
+export async function refreshTopicView(scope, workspaceId) {
+    const snapshot = await scanMemoryScope(scope, workspaceId);
+    await ensureTopicView(snapshot, scope, workspaceId);
+}
+function currentEpoch(key) {
+    return scopeState(key).epoch;
 }
 function invalidateScope(scope, workspaceId) {
-    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) {
+    for (const watcher of state.watchers)
+        watcher.close();
+    state.watchers = [];
+    state.watcherComplete = false;
+}
 function ensureScopeWatcher(base, scope, workspaceId) {
     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 = [];
-        const watchPath = (path) => {
-            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) => {
+            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]));
+                watchCategory(join(base, CATEGORY_DIR[category]));
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    complete = false;
             }
-            catch { /* absent category */ }
         }
         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) {
-    cached.watcherActive = false;
     cached.dirty = true;
 }
 function evictScopeCaches() {
-    if (scopeCache.size <= MAX_SCOPE_CACHE_ENTRIES)
+    if (scopeStates.size <= MAX_SCOPE_CACHE_ENTRIES)
         return;
-    const victims = [...scopeCache.entries()]
+    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}/`))
+            if (pathContains(key, path))
                 fileCache.delete(path);
         }
     }
 }
+async function settleRecentWatcherEvents(state) {
+    await new Promise((resolvePromise) => { setImmediate(resolvePromise); });
+    if (state.cache?.dirty)
+        return false;
+    const now = Date.now();
+    if (now - state.lastDrainAt >= WATCHER_SETTLE_REUSE_MS) {
+        await new Promise((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) {
     const checks = await Promise.all(snapshot.records.map(async (record) => {
         const path = memoryRecordPath(record);
@@ -225,47 +513,79 @@ async function readCached(path) {
         return next;
     }
 }
-export async function scanMemoryScope(scope, workspaceId) {
+export async function scanMemoryScope(scope, workspaceId, attempt = 0) {
     const base = scopeDirectory(scope, workspaceId);
     const key = scopeKey(scope, workspaceId);
-    const recovered = await recoverScopeTransaction(base);
-    let cachedScope = scopeCache.get(key);
-    if (recovered && cachedScope)
+    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((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 = [];
-    const diagnostics = [];
+    // 隔离事务留下的告警要跟着本次快照走完，不能只写日志然后消失——
+    // diagnostics 是既有的、Desktop 与 diagnosticSuffix() 都会展示的通道。
+    const diagnostics = await quarantineDiagnosticsFor(base);
     const versions = {};
     const seen = new Set();
     for (const category of ALL_CATEGORIES) {
@@ -308,34 +628,43 @@ export async function scanMemoryScope(scope, workspaceId) {
             }
         }
     }
+    // 同上：硬编码 `/` 在 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((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(id, scope, workspaceId) {
     const snapshot = await scanMemoryScope(scope, workspaceId);
@@ -345,6 +674,7 @@ export async function readVersionedMemory(id, scope, workspaceId) {
 export async function writeNewMemory(record) {
     const path = memoryRecordPath(record);
     const content = serializeMemoryRecord(record);
+    markInternalRecordEvent(path);
     await atomicWriteFile(path, content);
     fileCache.delete(path);
     invalidateScope(record.scope, record.workspaceId);
@@ -434,6 +764,7 @@ export async function removeVersionedMemory(current, expectedVersion) {
                 throw new Error('MEMORY_VERSION_CONFLICT');
         }
         try {
+            markInternalRecordEvent(path);
             await unlink(path);
             fileCache.delete(path);
             invalidateScope(current.record.scope, current.record.workspaceId);
@@ -451,9 +782,8 @@ export async function removeVersionedMemory(current, expectedVersion) {
 }
 export function clearMemoryIndex() {
     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();
 }