@co-engram/core 0.1.2 → 0.1.4

package/dist/storage/repository.js

@@ -19,11 +19,14 @@ import { join, relative, sep } from "node:path";
 import { ulid } from "ulid";
 import { isStableEngramId } from "../types/repository-types.js";
 import { slugify, inferDomainTagsFromPath } from "../types/slugify.js";
+import { safeEmit } from "../prompt-signals/event-bus.js";
+import { safeJoinWithinRoot, isPathWithinRoot, } from "./path.js";
 import { computeContentHash, computeContentSize } from "./hash.js";
 import { DEFAULT_LANGUAGE } from "../i18n/index.js";
 import { readEngramFile, writeEngramFile, deleteEngramFile, renameEngramFile, parseEngramFile, detectEngramFileLanguage, } from "./engram-store.js";
 import { SYNAPSES_DIR, collectAllSynapses, upsertSynapse, readSynapseByEndpoints, readSynapseById, listSynapsesForEngram, deleteSynapsesTouching, synapseRelativePath, deleteSynapseFile, writeSynapseFile, parseSynapseFile, } from "./synapse-store.js";
 import { buildIndexEntryFromFrontmatter, engramIndexPath, readEngramIndex, rebuildEngramIndex, removeEngramIndexEntry, upsertEngramIndexEntry, writeEngramIndex, } from "./engram-index.js";
+import { regenerateObsidianLinks, checkObsidianView, } from "./obsidian-links.js";
 const DEFAULT_IMPORTANCE = 0.5;
 const DEFAULT_CONFIDENCE_BY_SOURCE = {
     firsthand: 0.85,
@@ -64,6 +67,21 @@ function deriveAutoSummary(content, title) {
         return cleaned;
     return cleaned.slice(0, 197) + "...";
 }
+/**
+ * Synapse visibility 继承规则:取两端 engram 的最严。
+ *
+ * 严格度排序:`private` > `restricted` > `team` > `public`。
+ * 任一端是 private,synapse 整条就按 private 处理(保守策略)。
+ */
+const VIS_STRICTNESS = {
+    public: 0,
+    team: 1,
+    restricted: 2,
+    private: 3,
+};
+function maxVisibility(a, b) {
+    return VIS_STRICTNESS[a] >= VIS_STRICTNESS[b] ? a : b;
+}
 /**
  * EngramRepository — per-edge synapse + ULID stable id + 单文件 engram
  *
@@ -90,6 +108,18 @@ export class EngramRepository {
      * 会立即触发缓存失效,无需等下次 getIndex 的 mtime 兜底检查。
      */
     indexWatcher;
+    /**
+     * 递归 fs.watch 句柄,监听 dataRoot 下所有 .md 文件变化(可选)。
+     *
+     * 触发场景(关键):git pull / git checkout / 手动编辑 / rsync 等任何外部
+     * 写入 .md 的途径,startWatching() 单独监听 index.json 看不到这些变化。
+     * dataWatcher 触发后 debounce 调用 rebuildIndex,把磁盘 .md 真相重新
+     * 投影到 engram-index.json,避免"git pull 拉到新文件但 engram_search
+     * 找不到"的 fail-silent(架构缺陷 index-no-truth 的具体表现)。
+     */
+    dataWatcher;
+    /** dataWatcher debounce 定时器。git pull 一次性触发大量事件,合并为一次重建。 */
+    dataRebuildTimer;
     language;
     constructor(config) {
         this.config = config;
@@ -180,17 +210,43 @@ export class EngramRepository {
         removeEngramIndexEntry(index, id);
         this.persistIndex(index);
     }
+    /**
+     * 清理索引中所有指向 relativePath 的孤儿 entry,返回清理数量。
+     *
+     * 触发场景:外部(用户 rm / git 操作 / 进程异常)删除 engram 文件后,
+     * engram-index.json 仍保留旧 ULID 的 entry。下一次 createEngram 写入
+     * 同 path 的新 ULID 会留下永不消失的孤儿,导致 listEngrams / viewer
+     * 显示"重影"(同一文件被两个 ULID 引用)。
+     *
+     * 同 path 出现多条 entry 本身就是不变量破坏 —— 此处发现即清。多数调用
+     * 不会命中,N=0 时是 O(|index|) 扫一次,可接受。
+     */
+    purgeStaleIndexEntriesForPath(relativePath) {
+        const index = this.getIndex();
+        const stale = [];
+        for (const [id, entry] of index.entries) {
+            if (entry.path === relativePath)
+                stale.push(id);
+        }
+        for (const id of stale) {
+            this.deleteIndexEntry(id);
+        }
+        return stale.length;
+    }
     // ─── Cross-process watcher ─────────────────────────────────────────────
     /**
-     * 启动对 engram-index.json 的 fs.watch 监听。
+     * 启动对 engram-index.json 的 fs.watch 监听 + dataRoot .md 递归监听。
      *
-     * 启动后,外部进程修改 index(创建/更新/删除 engram)会触发 watcher,
-     * 主动失效 indexCache。下次 getIndex 调用时从磁盘重读。
+     * 启动后:
+     *   - index.json watcher:外部进程修改 index(创建/更新/删除 engram)→ 失效 cache
+     *   - dataRoot .md watcher:任何途径(git pull / checkout / 手动编辑)写入 .md
+     *     → debounce 后调 rebuildIndex,把磁盘真相重新投影到 index.json
      *
      * 幂等:多次调用安全,只创建一个 watcher。
      *
      * 适用场景:多个 host adapter(MCP server / OpenClaw plugin)共享同一
-     * dataRoot 时,确保各进程的缓存相互一致。
+     * dataRoot 时,确保各进程的缓存相互一致;同时覆盖 git pull 后索引漏更新
+     * 的 fail-silent 场景。
      *
      * 不需要显式停止 — 进程退出时 OS 自动回收 fd。stopWatching() 仅用于
      * 测试 / 显式资源管理场景。
@@ -216,6 +272,76 @@ export class EngramRepository {
             // persistIndex 写盘后会 lazy 重试 startWatching,覆盖首次空 dataRoot 场景。
             this.indexWatcher = undefined;
         }
+        this.startDataRootWatcher();
+    }
+    /**
+     * 启动 dataRoot 下 .md 文件的递归 fs.watch。
+     *
+     * Node 22+ 在 Linux/macOS/Windows 都支持 `recursive: true`(Linux 通过 inotify)。
+     * 不支持的平台(NFS / 老 Node)→ catch 后 noop,startWatching 的 index.json
+     * watcher + getIndex 的 mtime 兜底仍然有效,只是 .md 变化需要等下次主动 getIndex。
+     *
+     * 触发后通过 scheduleDataRebuild debounce 合并,避免 git pull 一次性大量事件
+     * 触发多次 rebuildIndex。
+     */
+    startDataRootWatcher() {
+        if (this.dataWatcher)
+            return;
+        try {
+            this.dataWatcher = watch(this.config.rootPath, { recursive: true, persistent: false }, (_eventType, filename) => {
+                if (process.env["CO_ENGRAM_WATCHER_DEBUG"]) {
+                    process.stderr.write(`[co-engram-watcher] event=${_eventType} filename=${filename ?? "null"}\n`);
+                }
+                // 只关心 .md 变化(.yaml / .json / .co-engram/ 内部状态由 index.json
+                // watcher 或 persistIndex 路径覆盖)。filename 跨平台可能为 null,
+                // 不可靠时宁可多触发一次 rebuildIndex 也不要漏事件。
+                if (typeof filename === "string" && !filename.endsWith(".md"))
+                    return;
+                this.scheduleDataRebuild();
+            });
+            this.dataWatcher.on("error", () => {
+                this.dataWatcher = undefined;
+            });
+        }
+        catch {
+            // 平台不支持 recursive fs.watch → 降级,功能不阻塞
+            this.dataWatcher = undefined;
+        }
+    }
+    /**
+     * Debounce 调用 rebuildIndex,合并短时间内的多次 .md 变化事件。
+     *
+     * git pull / rsync 等批量操作会一次性产生几十~几百个事件,逐个触发
+     * rebuildIndex(全量扫盘)会卡死。1000ms debounce 把它们合并成一次重建。
+     */
+    scheduleDataRebuild() {
+        if (this.dataRebuildTimer)
+            clearTimeout(this.dataRebuildTimer);
+        this.dataRebuildTimer = setTimeout(() => {
+            this.dataRebuildTimer = undefined;
+            try {
+                if (process.env["CO_ENGRAM_WATCHER_DEBUG"]) {
+                    process.stderr.write(`[co-engram-watcher] rebuildIndex triggered\n`);
+                }
+                // rebuildIndex 全量扫盘重读所有 .md,更新 engram-index.json。
+                // 之后 persistIndex 写 index.json → 触发 indexWatcher → invalidateIndexCache
+                // → searchOrchestrator 重建 ftsIndex,完成全链路同步。
+                const result = this.rebuildIndex();
+                this.invalidateIndexCache();
+                if (process.env["CO_ENGRAM_WATCHER_DEBUG"]) {
+                    const count = result.entries
+                        ? Object.keys(result.entries).length
+                        : "?";
+                    process.stderr.write(`[co-engram-watcher] rebuildIndex done, entries=${count}\n`);
+                }
+            }
+            catch (e) {
+                if (process.env["CO_ENGRAM_WATCHER_DEBUG"]) {
+                    process.stderr.write(`[co-engram-watcher] rebuildIndex failed: ${e instanceof Error ? e.message : String(e)}\n`);
+                }
+                // 重建失败不能阻塞 watcher 后续触发,静默吞掉(下次事件再次尝试)
+            }
+        }, 1000);
     }
     /** 停止 watcher(主要用于测试隔离) */
     stopWatching() {
@@ -228,6 +354,19 @@ export class EngramRepository {
             }
             this.indexWatcher = undefined;
         }
+        if (this.dataWatcher) {
+            try {
+                this.dataWatcher.close();
+            }
+            catch {
+                // ignore
+            }
+            this.dataWatcher = undefined;
+        }
+        if (this.dataRebuildTimer) {
+            clearTimeout(this.dataRebuildTimer);
+            this.dataRebuildTimer = undefined;
+        }
     }
     /** 失效缓存 — 下次 getIndex 从磁盘重读。同时通知 invalidate listeners。 */
     invalidateIndexCache() {
@@ -262,17 +401,26 @@ export class EngramRepository {
     /** 解析 stableId → 相对路径 */
     resolvePath(stableId) {
         if (!isStableEngramId(stableId)) {
-            // 兼容:可能是相对路径,直接当 path 用
+            // 兼容:可能是相对路径,直接当 path 用。
+            // 但必须先校验路径在 root 内(防 `..` 逃逸,path traversal 防御)
+            if (!isPathWithinRoot(this.config.rootPath, stableId))
+                return undefined;
             if (this.existsAtPath(stableId))
                 return stableId;
             return undefined;
         }
         const entry = this.getIndex().entries.get(stableId);
+        // 防御:索引中的 path 也校验(理论上是 trusted,但 doctor 自愈后可能含异常)
+        if (entry?.path && !isPathWithinRoot(this.config.rootPath, entry.path)) {
+            return undefined;
+        }
         return entry?.path;
     }
     /** 检查相对路径是否存在 engram 文件 */
     existsAtPath(relativePath) {
-        return existsSync(join(this.config.rootPath, relativePath));
+        if (!isPathWithinRoot(this.config.rootPath, relativePath))
+            return false;
+        return existsSync(safeJoinWithinRoot(this.config.rootPath, relativePath));
     }
     // ─── Engram CRUD ───────────────────────────────────────────────────────
     /**
@@ -290,11 +438,18 @@ export class EngramRepository {
         const sourceType = input.sourceType ?? "firsthand";
         const contentHash = computeContentHash(input.content);
         const contentSize = computeContentSize(input.content);
+        // pathHint 优先;否则用 deriveDefaultPath(slugify title + raw domainTags + .md)
+        // safeJoinWithinRoot 拦截 `..` 逃逸与绝对路径(path traversal 防御)
         const relativePath = input.pathHint ?? this.deriveDefaultPath(input);
-        const absolutePath = join(this.config.rootPath, relativePath);
+        const absolutePath = safeJoinWithinRoot(this.config.rootPath, relativePath);
         if (existsSync(absolutePath)) {
             throw new Error(`Engram already exists at ${relativePath}`);
         }
+        // 自愈:外部 rm / git 操作可能让 engram-index.json 残留指向同 path
+        // 但磁盘已无文件的孤儿 entry。新 ULID 写入后会留下永不消失的"重影"
+        // (listEngrams / viewer 显示重复节点)。在写入前清理。engram_doctor
+        // 是手动巡检版本,此处是写入路径的自动防线。
+        this.purgeStaleIndexEntriesForPath(relativePath);
         const hasExplicitDomainTags = input.domainTags.length > 0;
         const frontmatter = {
             id: stableId,
@@ -344,14 +499,29 @@ export class EngramRepository {
             contentHash,
         });
         this.updateIndexEntry(entry);
+        // Task 3.4 Phase B:engram 创建后 emit,让 prompt-signals cache 失效并 debounced rebuild
+        safeEmit({
+            type: "engram_created",
+            engramId: stableId,
+            at: new Date().toISOString(),
+        });
         return this.readEngram(stableId);
     }
-    /** 默认路径:{domainTags.join('/')/}{slug}.md */
+    /**
+     * 默认路径:{domainTags.join('/')/}{slug}.md
+     *
+     * private engram 自动落 `private/` 子目录(被 .gitignore 隔离出团队仓库)。
+     * 注意:本函数只用于「无 pathHint」场景;调用方传 pathHint 时直接尊重用户路径,
+     * 不会自动加 private 前缀(避免 `private/private/...` 双前缀)。
+     */
     deriveDefaultPath(input) {
         const slug = slugify(input.title);
         const domains = input.domainTags.length > 0 ? input.domainTags : [];
         const parts = [...domains, `${slug}.md`];
-        return parts.join("/");
+        const basePath = parts.join("/");
+        return input.visibility === "private"
+            ? `private/${basePath}`
+            : basePath;
     }
     /**
      * 读取完整 Engram(单文件 + 统计)
@@ -361,7 +531,8 @@ export class EngramRepository {
         if (!relativePath) {
             throw new Error(`Engram not found: ${stableId}`);
         }
-        const absolutePath = join(this.config.rootPath, relativePath);
+        // resolvePath 已校验路径在 root 内,这里再防御一次
+        const absolutePath = safeJoinWithinRoot(this.config.rootPath, relativePath);
         const file = readEngramFile(absolutePath);
         return this.assembleEngram(file, relativePath);
     }
@@ -371,7 +542,8 @@ export class EngramRepository {
     exists(stableId) {
         const relativePath = this.resolvePath(stableId);
         return (relativePath !== undefined &&
-            existsSync(join(this.config.rootPath, relativePath)));
+            isPathWithinRoot(this.config.rootPath, relativePath) &&
+            existsSync(safeJoinWithinRoot(this.config.rootPath, relativePath)));
     }
     /**
      * 更新 Engram(content/frontmatter 双写)
@@ -454,9 +626,18 @@ export class EngramRepository {
         const newSlugUnlocked = oldFrontmatter.slug === undefined
             ? slugify(newTitle)
             : oldFrontmatter.slug;
-        const newPath = newSlugUnlocked !== oldSlug
-            ? this.rebuildPath(relativePath, newSlugUnlocked)
-            : relativePath;
+        // 处理 visibility 变化:public/team/restricted ↔ private → 路径前缀调整
+        // (private engram 落 `private/` 子目录,变更 visibility 时同步迁移路径)
+        const oldVisibility = oldFrontmatter.visibility ?? "public";
+        const visibilityChanged = newVisibility !== oldVisibility;
+        // slug + visibility 都可能触发 rename,正交串联应用
+        let newPath = relativePath;
+        if (newSlugUnlocked !== oldSlug) {
+            newPath = this.rebuildPath(newPath, newSlugUnlocked);
+        }
+        if (visibilityChanged) {
+            newPath = this.rebuildPathForVisibility(newPath, newVisibility);
+        }
         const newFile = {
             frontmatter: newFrontmatter,
             content: newContent,
@@ -464,10 +645,15 @@ export class EngramRepository {
         if (newPath !== relativePath) {
             const newAbsolutePath = join(this.config.rootPath, newPath);
             if (existsSync(newAbsolutePath)) {
-                throw new Error(`Slug rename conflict: ${newPath} already exists`);
+                // 原子性保证:目标已存在就报错,不动旧文件
+                throw new Error(`Rename conflict: ${newPath} already exists`);
             }
             writeEngramFile(newAbsolutePath, newFile, this.language);
             rmSync(absolutePath);
+            // 旧路径孤儿 index entry 清理(原 updateEngram 漏了这一步):
+            // rename 后旧 path 的反向 entry(path → stableId)若不清理,会留下
+            // 「磁盘无文件但 index 有记录」的孤儿,listEngrams / viewer 会显示重影。
+            this.purgeStaleIndexEntriesForPath(relativePath);
         }
         else {
             writeEngramFile(absolutePath, newFile, this.language);
@@ -488,8 +674,28 @@ export class EngramRepository {
         parts[parts.length - 1] = `${newSlug}.md`;
         return parts.join("/");
     }
+    /**
+     * 调整路径的 visibility 前缀(不改动 basename):
+     * - `'private'` → 加 `private/` 前缀(若已含则幂等返回原值)
+     * - 其他(`'public'`/`'team'`/`'restricted'`) → 移除 `private/` 前缀(若不含则幂等返回)
+     *
+     * 用于 updateEngram 中 visibility 变更时的路径迁移。
+     * 注意:仅处理前缀,basename 由 rebuildPath 负责,两者正交可串联应用。
+     */
+    rebuildPathForVisibility(path, visibility) {
+        const PRIVATE_PREFIX = "private/";
+        if (visibility === "private") {
+            return path.startsWith(PRIVATE_PREFIX) ? path : `${PRIVATE_PREFIX}${path}`;
+        }
+        return path.startsWith(PRIVATE_PREFIX)
+            ? path.slice(PRIVATE_PREFIX.length)
+            : path;
+    }
     /**
      * 删除 Engram + 级联删除触及的 synapses + 清理 index
+     *
+     * 走 `this.deleteSynapsesTouching` 方法版而非模块函数,以触发
+     * 邻居派生段( Obsidian wikilinks)的 cascade refresh。
      */
     deleteEngram(stableId) {
         const relativePath = this.resolvePath(stableId);
@@ -497,7 +703,7 @@ export class EngramRepository {
             return;
         const absolutePath = join(this.config.rootPath, relativePath);
         deleteEngramFile(absolutePath);
-        deleteSynapsesTouching(this.config.rootPath, stableId);
+        this.deleteSynapsesTouching(stableId);
         if (isStableEngramId(stableId)) {
             this.deleteIndexEntry(stableId);
         }
@@ -613,9 +819,40 @@ export class EngramRepository {
     readSynapseById(synapseId) {
         return readSynapseById(this.config.rootPath, synapseId);
     }
+    /**
+     * 触发 Obsidian 派生段重建(多条 engram 一次性刷新,去重)。
+     *
+     * 永不抛(regenerateObsidianLinks 内部已吞错)。调用方无需 try/catch。
+     */
+    refreshObsidianLinks(...ids) {
+        const seen = new Set();
+        for (const id of ids) {
+            if (!id || seen.has(id))
+                continue;
+            seen.add(id);
+            regenerateObsidianLinks(this.config.rootPath, id, this.language);
+        }
+    }
     /** 创建 synapse(idempotent) */
     createSynapse(input) {
-        return upsertSynapse(this.config.rootPath, {
+        // 继承最严 visibility:取 from/to 两端 engram 的 max(private > restricted > team > public)
+        // 端点查不到(已删/无效 id)时降级 'public',不阻塞 synapse 创建
+        let fromVis = "public";
+        let toVis = "public";
+        try {
+            fromVis = this.readEngram(input.from).visibility ?? "public";
+        }
+        catch {
+            // from engram 不存在或不可读,降级 public
+        }
+        try {
+            toVis = this.readEngram(input.to).visibility ?? "public";
+        }
+        catch {
+            // to engram 不存在或不可读,降级 public
+        }
+        const inheritedVisibility = maxVisibility(fromVis, toVis);
+        const result = upsertSynapse(this.config.rootPath, {
             from: input.from,
             to: input.to,
             kind: input.kind,
@@ -625,8 +862,17 @@ export class EngramRepository {
             createdBy: input.createdBy,
             sourceSemantic: input.sourceSemantic,
             targetSemantic: input.targetSemantic,
+            visibility: inheritedVisibility,
             language: this.language,
         });
+        this.refreshObsidianLinks(input.from, input.to);
+        // Task 3.4 Phase B:synapse 创建影响 graph 结构,触发 prompt-signals rebuild
+        safeEmit({
+            type: "synapse_created",
+            engramId: input.from,
+            at: new Date().toISOString(),
+        });
+        return result;
     }
     /**
      * 更新 synapse(走 upsert,合并 evidence)。
@@ -648,7 +894,7 @@ export class EngramRepository {
             const oldPath = join(this.config.rootPath, synapseRelativePath(target.id, target.kind));
             deleteSynapseFile(oldPath);
         }
-        return upsertSynapse(this.config.rootPath, {
+        const result = upsertSynapse(this.config.rootPath, {
             from: target.from,
             to: target.to,
             kind: nextKind,
@@ -659,8 +905,13 @@ export class EngramRepository {
             sourceSemantic: target.sourceSemantic,
             targetSemantic: target.targetSemantic,
             resolutionState: target.resolutionState,
+            // 保守策略:不因端点 visibility 提升而自动调整 synapse visibility,
+            // 保留原值。Phase 1.5 可加 recomputeSynapseVisibility(engramId)。
+            visibility: target.visibility ?? "public",
             language: this.language,
         });
+        this.refreshObsidianLinks(target.from, target.to);
+        return result;
     }
     /** 删除某条 synapse */
     deleteSynapse(synapseId) {
@@ -669,10 +920,26 @@ export class EngramRepository {
             return;
         const path = join(this.config.rootPath, synapseRelativePath(syn.id, syn.kind));
         deleteSynapseFile(path);
+        this.refreshObsidianLinks(syn.from, syn.to);
     }
     /** 级联删除触及 engram 的所有 synapse */
     deleteSynapsesTouching(engramId) {
-        return deleteSynapsesTouching(this.config.rootPath, engramId);
+        // 先抓所有邻居 endpoint — 删除后这些 synapse 就找不到了,
+        // 邻居 engram.md 的派生段还引用着 engramId,需要重建。
+        const touching = listSynapsesForEngram(this.config.rootPath, engramId);
+        const neighbors = new Set();
+        for (const s of touching.outgoing) {
+            if (s.to !== engramId)
+                neighbors.add(s.to);
+        }
+        for (const s of touching.incoming) {
+            if (s.from !== engramId)
+                neighbors.add(s.from);
+        }
+        const count = deleteSynapsesTouching(this.config.rootPath, engramId);
+        if (neighbors.size > 0)
+            this.refreshObsidianLinks(...neighbors);
+        return count;
     }
     /**
      * 添加 outgoing synapse。
@@ -683,7 +950,7 @@ export class EngramRepository {
      * @returns 实际落盘的 synapse(其 id 是计算值)
      */
     addOutgoingSynapse(fromId, synapse) {
-        return upsertSynapse(this.config.rootPath, {
+        const result = upsertSynapse(this.config.rootPath, {
             from: fromId,
             to: synapse.to,
             kind: synapse.kind,
@@ -701,6 +968,8 @@ export class EngramRepository {
             resolutionState: synapse.resolutionState,
             language: this.language,
         });
+        this.refreshObsidianLinks(fromId, synapse.to);
+        return result;
     }
     /**
      * 删除 outgoing synapse。
@@ -714,6 +983,7 @@ export class EngramRepository {
             return;
         const path = join(this.config.rootPath, synapseRelativePath(target.id, target.kind));
         deleteSynapseFile(path);
+        this.refreshObsidianLinks(target.from, target.to);
     }
     /**
      * 更新 synapse 的 resolutionState(contradicts 专用)。
@@ -822,6 +1092,12 @@ export class EngramRepository {
      */
     updateVerificationStatus(id, status) {
         this.mutateFrontmatter(id, (fm) => ({ ...fm, verificationStatus: status }));
+        // Task 3.4 Phase B:验证状态变化影响 prompt 的 lowConfidenceTopics
+        safeEmit({
+            type: "engram_verified",
+            engramId: id,
+            at: new Date().toISOString(),
+        });
     }
     /**
      * 低层 frontmatter 修改:不触发 version++,不改 slug,不改 path。
@@ -876,6 +1152,11 @@ export class EngramRepository {
                 path: orphanPath,
                 message: `Markdown file without frontmatter: ${orphanPath} (either delete it or add frontmatter with a stable id)`,
                 autoFixed: false,
+                nextAction: {
+                    tool: "engram_create",
+                    argsHint: `{ title, content, kind, domainTags, createdBy }  // 直接读取这个 markdown 的内容作为 engram body`,
+                    explanation: "Markdown 文件没有 frontmatter,所以不在 engram 索引里。如果是新记忆,用 engram_create 注册(把现有正文粘到 content);如果是废弃草稿,直接 rm 即可。",
+                },
             });
             pendingManualReview.push(issues[issues.length - 1]);
         });
@@ -913,11 +1194,17 @@ export class EngramRepository {
                     // 标记相关 synapse dangling
                     const touching = listSynapsesForEngram(this.config.rootPath, oldId);
                     if (touching.outgoing.length + touching.incoming.length > 0) {
+                        const danglingCount = touching.outgoing.length + touching.incoming.length;
                         pendingManualReview.push({
                             kind: "dangling_synapse",
                             stableId: oldId,
-                            message: `Engram ${oldId} was deleted but ${touching.outgoing.length + touching.incoming.length} synapse(s) still reference it (clean up manually or restore the engram)`,
+                            message: `Engram ${oldId} was deleted but ${danglingCount} synapse(s) still reference it (clean up manually or restore the engram)`,
                             autoFixed: false,
+                            nextAction: {
+                                tool: "synapse_delete",
+                                argsHint: `{ id: "<synapseId>" }  // synapseId 在每个 synapse 的 yaml id 字段,逐条删`,
+                                explanation: `被删 engram 还有 ${danglingCount} 条 synapse 指向它,这些 synapse 现在是悬空的。去 synapses/ 目录找出涉及该 engram 的 synapse,用 synapse_delete 逐条清理;或者用 engram_create 重建该 engram(让 synapse 重新有目标)。`,
+                            },
                         });
                     }
                 }
@@ -988,6 +1275,35 @@ export class EngramRepository {
                 });
             }
         }
+        // 5. Obsidian 视图一致性(派生段 wikilinks)
+        // 对每条 engram:checkObsidianView 检测派生段与权威源(synapse yaml)不一致,
+        // 不一致 → regenerateObsidianLinks 重写派生段(wikilink target=文件名)。
+        for (const [id, entry] of freshIndex.entries) {
+            const absPath = join(this.config.rootPath, entry.path);
+            if (!existsSync(absPath))
+                continue;
+            let file;
+            try {
+                file = readEngramFile(absPath);
+            }
+            catch {
+                continue; // parse 错误由别处报告(或phan_markdown 路径)
+            }
+            const touching = listSynapsesForEngram(this.config.rootPath, id);
+            const status = checkObsidianView(file, touching, freshIndex);
+            if (!status.stale)
+                continue;
+            regenerateObsidianLinks(this.config.rootPath, id, this.language);
+            fixes.push({
+                kind: "obsidian_view_stale",
+                stableId: id,
+                path: entry.path,
+                message: `Obsidian derived wikilinks regenerated (target=filename, display=title·kind)`,
+                autoFixed: true,
+            });
+        }
+        // Task 3.4 Phase B:doctor 完成后 emit(doctor 可能 sweep/forget,engram 集合变化)
+        safeEmit({ type: "doctor_completed", at: new Date().toISOString() });
         return {
             startedAt,
             finishedAt: now(),