@modusensus/dsh-mneme 0.13.0 → 0.14.0-beta.1

package/lib/wiki/t1.js

@@ -23,7 +23,11 @@ import { readFileSync, writeFileSync, existsSync, mkdtempSync, rmSync, mkdirSync
 import { join, dirname, sep, resolve } from "node:path";
 import { tmpdir } from "node:os";
 import { realpathSync } from "node:fs";
-import { extractHumanBlocks, injectHumanBlocks, T1_SECTION_START, T1_SECTION_END } from "./render.js";
+import {
+  extractHumanBlocks, injectHumanBlocks, T1_SECTION_START, T1_SECTION_END,
+  FM_VERIFIED_AT, FM_VERIFIED_BASELINE, setFrontmatterKeys,
+} from "./render.js";
+import { gitHead } from "./t0.js";
 // issue #607：拒绝文案里的 CLI 命令要给绝对路径入口（profile 装的插件没有全局
 // shim，光写 `dsh-mneme-choro` 用户照抄只会 command not found）。
 import { choroCliCommandFrom } from "./cli-hint.js";
@@ -64,9 +68,18 @@ export function isEnvironmentFailure(result) {
 // 模型路由走 --patch 临时 overlay 指池模型（bili-scroll 同款，零配置改动）。
 // exe 定位：env DSH_EXE > process.execPath（本身是 Harness exe，即已在宿主 CLI 内）>
 // 标准安装位。定位不到 → environment 失败（降级表第一行），不猜测。
-export function makeHeadlessRunner({ profile = "headless", onOverlay = null } = {}) {
+//
+// 三种定位（exe / cli.js / 失败诊断）都做成可注入的纯函数：issue #578 的病根全在
+// 「按一种安装布局写死」，而布局差异只有真机上才看得见——不能测的东西迟早会错。
+export function makeHeadlessRunner({
+  profile = "headless",
+  onOverlay = null,
+  spawn: spawnFn = spawn,
+  locateExe = locateDshExe,
+  resolveCli = resolveCliJs,
+} = {}) {
   return async function runSession({ cwd, task, model, timeoutMs, maxToolCalls, maxOutputBytes }) {
-    const exe = locateDshExe();
+    const exe = locateExe();
     if (!exe) {
       return {
         ok: false,
@@ -74,10 +87,16 @@ export function makeHeadlessRunner({ profile = "headless", onOverlay = null } =
         reason: "找不到 DeepSeek Harness 主程序（设 DSH_EXE 环境变量，或用 --dsh-exe 显式指定）",
       };
     }
-    const cliJs = locateCliJs(exe);
-    if (!cliJs) {
-      return { ok: false, kind: "environment", reason: `在 ${dirname(exe)} 下找不到 dsh-desktop-host 的 cli.js` };
+    const cli = resolveCli(exe);
+    if (!cli.path) {
+      // 显式指定（DSH_CLI_JS / --dsh-cli）但路径不存在，与「哪种布局都找不到」是两件
+      // 事：前者是人写错了一个字符，后者是布局没覆盖。分开说，否则用户会去改布局。
+      const reason = cli.explicitMissing
+        ? `DSH_CLI_JS 指定的 headless CLI 不存在：${cli.explicitMissing}（这是显式指定，不会回退到其它候选；改正它或取消指定）`
+        : `在 ${dirname(exe)} 下找不到 headless CLI。试过：${cli.candidates.join("、") || "(无候选)"}。DSH NEXT 布局可用环境变量 DSH_CLI_JS 直接指定 cli 路径`;
+      return { ok: false, kind: "environment", reason };
     }
+    const cliJs = cli.path;
     const [provider, modelName] = String(model).split("/");
     const overlayPath = writeModelOverlay(provider ?? "xdpool", modelName ?? "deepseek-v4.1-flash", onOverlay);
     let proc = null;
@@ -90,12 +109,21 @@ export function makeHeadlessRunner({ profile = "headless", onOverlay = null } =
         "headless",
         task,
       ];
-      proc = spawn(exe, args, {
+      proc = spawnFn(exe, args, {
         cwd,
         env: { ...process.env, ELECTRON_RUN_AS_NODE: "1" },
         stdio: ["ignore", "pipe", "pipe"],
       });
-      return await consumeHeadlessStream(proc, { timeoutMs, maxToolCalls, maxOutputBytes });
+      const result = await consumeHeadlessStream(proc, { timeoutMs, maxToolCalls, maxOutputBytes });
+      // 探测不可用时（普通 node 看不进 asar）走的是旧布局的老路径，这条提示只在真失败时
+      // 附上——成功时多说一句只会让人以为哪里没配好。
+      if (!result.ok && !cli.verified && result.kind === "environment") {
+        // 候选清单一起带上：只说「未经探测」等于让人重新猜一遍布局，而这轮已经把
+        // 探测过哪些路径算出来了（#578 那位用户当初只能靠读源码猜）。
+        result.reason += `（CLI 路径未经探测：当前进程看不进 asar，按旧布局 ${cliJs} 处理；`
+          + `已探测：${(cli.candidates ?? []).join("、") || "(无候选)"}。若是 DSH NEXT 请设 DSH_CLI_JS）`;
+      }
+      return result;
     } catch (err) {
       return { ok: false, kind: "environment", reason: String(err?.message ?? err) };
     } finally {
@@ -105,19 +133,60 @@ export function makeHeadlessRunner({ profile = "headless", onOverlay = null } =
   };
 }
 
-function locateDshExe() {
-  if (process.env.DSH_EXE && existsSync(process.env.DSH_EXE)) return process.env.DSH_EXE;
-  const exePath = process.execPath ?? "";
-  if (basename(exePath).toLowerCase() === "deepseek harness.exe") return exePath;
-  const standard = join(process.env["ProgramFiles"] ?? "C:\\Program Files", "DeepSeek Harness", "DeepSeek Harness.exe");
-  return existsSync(standard) ? standard : null;
+// exe 名白名单：不认「同目录任意 exe」——那只会在装了两套宿主时挑中错的那个。
+// 前两个是现行两种安装布局的名字（DSH NEXT 的 exe 就叫 DSH NEXT.exe），第三个是
+// 历史名字，留着只为不打断已经在用旧版的人。
+const DSH_EXE_NAMES = ["deepseek harness.exe", "dsh next.exe", "dsh.exe"];
+
+export function locateDshExe(env = process.env, execPath = process.execPath) {
+  if (env.DSH_EXE && existsSync(env.DSH_EXE)) return env.DSH_EXE;
+  const exePath = execPath ?? "";
+  if (DSH_EXE_NAMES.includes(basename(exePath).toLowerCase())) return exePath;
+  // 标准安装位按「两种布局 × 两种名字」逐个试。issue #578：DSH NEXT 装在别处、
+  // exe 也不叫 DeepSeek Harness.exe，旧实现两个条件同时不满足 → 直接 environment 失败。
+  const roots = [env["ProgramFiles"] ?? "C:\\Program Files", env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)"].filter(Boolean);
+  for (const root of roots) {
+    for (const name of ["DeepSeek Harness", "DSH NEXT"]) {
+      const candidate = join(root, name, `${name}.exe`);
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
 }
 
-function locateCliJs(exe) {
-  // cli.js 固定在 exe 相对路径的 app.asar 内部。**不能 existsSync 校验**：CLI 进程
-  // 是普通 node，没有 asar 支持 stat 不进包内——而 exe 自己（V1 实测）加载这个
-  // 路径没问题。位置是安装器定的，直接给出去。
-  return join(dirname(exe), "resources", "app.asar", "dsh", "node_modules", "@deepseek-ai", "dsh-desktop-host", "lib", "cli.js");
+// cli.js 在 app.asar 内部，位置随安装布局变（issue #578 的核心）：旧布局多一层
+// `dsh/`，DSH NEXT 直接放在 `lib/desktop-cli.js`。所以这里是**按优先级探测**，
+// 不再硬编码单一路径。
+//
+// 关于「不能 existsSync」那条旧注释：它对 CLI 子进程成立（普通 node 没有 asar
+// 补丁），但**探测发生在插件进程里**（Electron 主进程 / ELECTRON_RUN_AS_NODE 子
+// 进程，两者都给 fs 打了 asar 补丁）——本机实测 statSync/readFileSync 对 asar 内
+// 路径都正常工作。探测不到时（比如被测进程是裸 node）退回旧布局那条老路径并标记
+// verified:false，让失败信息自己说明「这次没探测」。
+export function resolveCliJs(exe, env = process.env) {
+  const base = dirname(exe);
+  const asar = join(base, "resources", "app.asar");
+  // DSH_CLI_JS 是**人明确指定**的答案，不是一条待排序的候选：指定了就不许再猜。
+  // 回退到别的候选会让人以为自己的设置生效了——实际跑的却是另一份 CLI，症状是
+  // 「我明明指了 NEXT 的 cli，报错里还是旧布局路径」。指定了但不存在 → 直接失败，
+  // 让错误信息如实指向他写的那个路径。
+  const explicit = typeof env.DSH_CLI_JS === "string" && env.DSH_CLI_JS !== "" ? env.DSH_CLI_JS : null;
+  const candidates = [
+    explicit,
+    join(asar, "lib", "desktop-cli.js"),
+    join(asar, "dsh", "node_modules", "@deepseek-ai", "dsh-desktop-host", "lib", "cli.js"),
+    join(asar, "node_modules", "@deepseek-ai", "dsh-desktop-host", "lib", "cli.js"),
+  ].filter((c) => typeof c === "string" && c !== "");
+  if (explicit !== null) {
+    if (existsSync(explicit)) return { path: explicit, candidates, verified: true };
+    return { path: null, candidates, verified: false, explicitMissing: explicit };
+  }
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return { path: candidate, candidates, verified: true };
+  }
+  // 全部探测失败：把**旧布局**那条老路径交出去（它曾是唯一答案，老真机上大概率还是
+  // 它），但如实带上 verified:false 与完整候选清单——猜错时失败信息里得看得见试过什么。
+  return { path: join(asar, "dsh", "node_modules", "@deepseek-ai", "dsh-desktop-host", "lib", "cli.js"), candidates, verified: false };
 }
 
 // overlay 只含 provider/model 名（红线 4：不落 key）；一次性临时目录，finally 里删。
@@ -137,6 +206,9 @@ function writeModelOverlay(provider, model, onOverlay) {
   return p;
 }
 
+// stderr 尾巴上限：够装下一条栈顶报错，又不至于把几万行 usage 全端上来。
+const STDERR_TAIL_LIMIT = 4096;
+
 // NDJSON 事件流消费：三重上限在读取循环里计数，超限 kill。headless --json 的事件
 // 形状以宿主实现为准——工具调用按「事件名含 tool_call/tool_use」的宽匹配计数，
 // 计不出就退化为只用 timeout/bytes 两道上限（如实降级，不假装第三道存在）。
@@ -147,6 +219,7 @@ function consumeHeadlessStream(proc, { timeoutMs, maxToolCalls, maxOutputBytes }
     let toolCalls = 0;
     let scannedLines = 0; // 已计过数的完整行数——每块只扫新增部分，否则事件被平方级重复计数（实测 11s 撞 40 上限的假象就是这么来的）
     let timedOut = false;
+    let stderrTail = "";
     const timer = setTimeout(() => {
       timedOut = true;
       proc.kill();
@@ -183,15 +256,22 @@ function consumeHeadlessStream(proc, { timeoutMs, maxToolCalls, maxOutputBytes }
       }
       scannedLines = complete;
     });
-    proc.stderr.on("data", () => { /* 诊断进 stderr，不影响结果 */ });
+    // stderr 必须收：headless 起不来时真正的原因（缺 credential、NO_ADAPTER、模块解析
+    // 失败、CLI 路径不存在）全在这里，而 stdout 一个字都没有——issue #578 的「(无输出)」
+    // 就是这么来的。只留尾巴（4 KiB）且不参与成败判定，纯诊断。
+    proc.stderr.on("data", (chunk) => {
+      stderrTail = (stderrTail + chunk.toString("utf8")).slice(-STDERR_TAIL_LIMIT);
+    });
     proc.on("error", (err) => finish({ ok: false, kind: "environment", reason: `spawn 失败：${String(err?.message ?? err)}` }));
     proc.on("close", (code) => {
       if (timedOut) { finish({ ok: false, kind: "module", reason: `超过 ${timeoutMs}ms 墙钟上限` }); return; }
       // 最终答案：--json 流里最后一个非事件行；流解析失败就取 stdout 去掉事件行后的文本。
       const text = extractFinalText(out);
       if (code !== 0) {
-        const envHint = /MISSING_CREDENTIAL|NO_ADAPTER|UNKNOWN_MODEL|EADDR|cannot find/i.test(out) ? "environment" : "module";
-        finish({ ok: false, kind: envHint, reason: `headless 退出码 ${code}：${(text || "").slice(0, 200) || "(无输出)"}` });
+        const envHint = /MISSING_CREDENTIAL|NO_ADAPTER|UNKNOWN_MODEL|EADDR|cannot find/i.test(out + stderrTail) ? "environment" : "module";
+        // 诊断优先取 stderr 尾巴：失败时 stdout 常常是空的，而原因都在 stderr。
+        const detail = (text || "").slice(0, 200) || stderrTail.trim().slice(-400) || "(无输出)";
+        finish({ ok: false, kind: envHint, reason: `headless 退出码 ${code}：${detail}` });
         return;
       }
       if (!text.trim()) { finish({ ok: false, kind: "module", reason: "headless 没有产出可解析的最终回答" }); return; }
@@ -286,10 +366,18 @@ export function createT1({ store, runSession = null, limits = DEFAULT_LIMITS, no
       skipped,
       t1Unavailable: null,
     };
+    // --dsh-exe 只影响这一轮：原来写进 process.env 就不还了，同一进程里后续任何一次
+    // 定位都会继承它（面板里切仓库、换个布局都还是旧值），属于会记很久的脏状态。
     const runnerWithExe = dshExe
       ? async (call) => {
+          const saved = process.env.DSH_EXE;
           process.env.DSH_EXE = dshExe;
-          return runner(call);
+          try {
+            return await runner(call);
+          } finally {
+            if (saved === undefined) delete process.env.DSH_EXE;
+            else process.env.DSH_EXE = saved;
+          }
         }
       : runner;
 
@@ -345,12 +433,18 @@ export function createT1({ store, runSession = null, limits = DEFAULT_LIMITS, no
 
       // 富化 + 双落（P19/P20）。写路径断言复用 t0 的机械面语义：只许动
       // .chorography/** 下的页面与 evidence。
+      //
+      // verifiedBaseline 必须是**这一刻**的 HEAD：claims 的行号是从这棵代码树上读出来
+      // 的，之后判失效只能从它起算。拿不到 HEAD（不是 git 仓库 / git 不在）就记 null，
+      // 面板据此说「这一页哪次验证的，不知道」——不退回全仓 git_baseline，那会把
+      // 「T1 之前就发生、claim 早已算进去」的改动误报成 touched。
       const generatedAt = now();
-      enrichPageFile(pageFile, parsed.sections);
-      writeEvidenceFile(rootPath, slug, parsed.claims, generatedAt);
+      const verifiedBaseline = gitHead(rootPath);
+      enrichPageFile(pageFile, parsed.sections, { verifiedBaseline, verifiedAt: generatedAt });
+      writeEvidenceFile(rootPath, slug, parsed.claims, generatedAt, verifiedBaseline);
       store.saveChoroPageClaims(pageRow.id, parsed.claims.map((c) => ({ ...c, createdAt: generatedAt })));
-      store.markChoroPageEnriched(pageRow.id, generatedAt);
-      receipt.enriched.push({ slug, sections: Object.keys(parsed.sections), claims: parsed.claims.length });
+      store.markChoroPageEnriched(pageRow.id, generatedAt, verifiedBaseline);
+      receipt.enriched.push({ slug, sections: Object.keys(parsed.sections), claims: parsed.claims.length, verifiedBaseline });
     }
     return receipt;
   }
@@ -430,7 +524,11 @@ function parseT1Output(text) {
 }
 
 // 富化（P19）：剥掉旧 T1 段 → 新段插在「## 生成说明」之前 → 保留区照旧页尾回填。
-function enrichPageFile(pageFile, sections) {
+//
+// 顺带把「对着哪个提交验证的」写进 frontmatter（① provenance）：这两个键**只有 T1
+// 写**，T0 渲染一个字节都不产出。因此 T0 重跑整页重建时它们随语义段一起消失，
+// 与「T0 丢弃 T1 正文」是同一件事，不新增语义，也不碰 T0 的逐字节确定性。
+function enrichPageFile(pageFile, sections, { verifiedBaseline = null, verifiedAt = null } = {}) {
   let content = readFileSync(pageFile, "utf8");
   // 剥旧 T1 段（含标记本身）
   const wrap = new RegExp(`${escapeRe(T1_SECTION_START)}[\\s\\S]*?${escapeRe(T1_SECTION_END)}\\n?`, "g");
@@ -462,7 +560,13 @@ function enrichPageFile(pageFile, sections) {
     ? `${content.replace(/\n*$/, "\n")}\n${block}`
     : content.slice(0, anchor) + block.replace(/^\n/, "") + content.slice(anchor);
   const { blocks } = extractHumanBlocks(base);
-  const finalContent = blocks.length > 0 ? injectHumanBlocks(stripHumanBlocks(base), blocks) : base;
+  const withHuman = blocks.length > 0 ? injectHumanBlocks(stripHumanBlocks(base), blocks) : base;
+  // HUMAN 块是页尾整块，frontmatter 在页首，两者互不干扰；顺序仍按「先回填保留区、
+  // 再收尾 frontmatter」，避免 fronts 里的键名与保留区正文同名时被误改。
+  const finalContent = setFrontmatterKeys(withHuman, [
+    [FM_VERIFIED_BASELINE, verifiedBaseline],
+    [FM_VERIFIED_AT, verifiedAt],
+  ]);
   writeFileSync(pageFile, finalContent, "utf8");
 }
 
@@ -472,11 +576,14 @@ function stripHumanBlocks(text) {
   return text.replace(re, "");
 }
 
-function writeEvidenceFile(repoRoot, slug, claims, generatedAt) {
+function writeEvidenceFile(repoRoot, slug, claims, generatedAt, verifiedBaseline = null) {
   const rel = `${".chorography"}/evidence/${slug}.json`;
   const abs = insideChoro(repoRoot, rel);
   mkdirp(dirname(abs));
-  writeFileSync(abs, `${JSON.stringify({ slug, generatedAt, claims }, null, 2)}\n`, "utf8");
+  // verifiedBaseline 与页面 frontmatter 同源同写：evidence 是给人核的旁证，光有 claims
+  // 没有「对着哪个提交」的，事后同样无从复核。
+  const body = { slug, generatedAt, verifiedBaseline, claims };
+  writeFileSync(abs, `${JSON.stringify(body, null, 2)}\n`, "utf8");
 }
 
 function insideChoro(rootPath, relPath) {

package/package.json

@@ -1,8 +1,22 @@
 {
   "name": "@modusensus/dsh-mneme",
   "description": "Cross-session memory plugin for DeepSeek Harness with autoDream consolidation: SQLite store, Markdown mirrors, 10 model tools, automatic injection, session summarization, user profile/rules, custom slash commands, vector (semantic) search, and a Web GUI panel",
-  "version": "0.13.0",
+  "version": "0.14.0-beta.1",
   "license": "MIT",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "deepseek",
+    "memory",
+    "agent-memory",
+    "long-term-memory",
+    "cross-session",
+    "recall",
+    "consolidation",
+    "sqlite",
+    "markdown"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/slow-stack/mneme.git"

package/scripts/release-docs.mjs

@@ -182,6 +182,12 @@ export function sectionOf(text, heading) {
 export function checkSupportTable(text, version) {
   const [major, minor] = version.split(".");
   const expected = `${major}.${minor}.x`;
+  // 预发布版（0.14.0-beta.1）不是「受支持的版本」，支持表不该跟着它挪格。
+  // 挪了等于对外宣称 0.14 已经在活跃维护——而 beta 随时可能推倒重来。
+  // 这里显式标 skipped，调用方据此换一句人话；**不静默通过**：skipped 是返回值的一部分。
+  if (version.includes("-")) {
+    return { ok: true, expected, problems: [], skipped: "prerelease" };
+  }
   const problems = [];
   for (const [heading, label] of [
     ["## Supported Versions", "英文"],
@@ -200,5 +206,5 @@ export function checkSupportTable(text, version) {
     const found = rows[0].split("|")[1].trim();
     if (found !== expected) problems.push(`${label}表首行写的是 ${found}，应为 ${expected}`);
   }
-  return { ok: problems.length === 0, expected, problems };
+  return { ok: problems.length === 0, expected, problems, skipped: null };
 }

package/scripts/release-notes.mjs

@@ -149,7 +149,10 @@ export function renderNotes(sectionText, opts = {}) {
 /** release.yml 的调用方式：node dsh-mneme/scripts/release-notes.mjs <version>（cwd 为仓库根）。 */
 function main() {
   const v = (process.argv[2] || "").replace(/^v/, "");
-  if (!/^\d+\.\d+\.\d+$/.test(v)) { console.error("usage: release-notes.mjs <version>"); process.exit(1); }
+  // 允许预发布后缀：0.14.0-beta.1 是合法发布版本，此前这条守卫把它当非法用法直接 exit 1，
+  // 于是 release job 在抽正文这步就红了——预发布版根本发不出去。语义校验交给
+  // semver 的形状（x.y.z 后可跟 -标识），不做额外白名单。
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(v)) { console.error("usage: release-notes.mjs <version>"); process.exit(1); }
   const md = readFileSync("dsh-mneme/CHANGELOG.md", "utf8");
   const sec = findSection(md, v);
   if (!sec) { console.error("changelog section not found: " + v); process.exit(1); }

package/src/api.js

@@ -1670,7 +1670,16 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
             // 少了它们，「这条边被抬过」在面板上根本看不出来。取不到时给
             // 初值形状而不是 undefined，前端不必到处判空。
             weight: e.weight ?? 1.0,
-            source: e.source ?? "manual"
+            source: e.source ?? "manual",
+            // #619 可见化 B：边上的 metadata 必须原样透传，否则情感边写进去的
+            // emotion / attribution / sessionCount / evidence 在面板上永远取不到
+            // ——数据在库里、在 store.toRelation 里（src/store.js 已 JSON.parse），
+            // 只在最后一跳被这个映射丢掉，读起来就像「这个功能不存在」。
+            // 不裁剪字段：情感边的 metadata 由 sleep 相位写入，形状本来就会随版本
+            // 演进，在 API 层挑字段等于给未来的字段再挖一个同样的坑。
+            // 无 metadata 时给 null，不伪造空对象——前端要靠 null 区分「老边（抽取器
+            // 写的，本来就没有情绪）」和「有 metadata 但没有 emotion」。
+            metadata: e.metadata ?? null
           }))
         });
       } catch {
@@ -1723,6 +1732,92 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     }
   });
 
+  // --- affective: 情绪归因一览（#619 可见化 C） ---
+  // `ego` 端点只能从某个实体往外看，回答不了「这库里一共记了哪些情绪」。
+  // 所以单开一条：按 person/target/emotion 聚合，occasion 与 trait 分开。
+  //
+  // 三处刻意的选择，都是为了让面板不撒谎：
+  // - 聚键含 attribution（occasion / trait），两类不混在一条里。同一个「焦虑」
+  //   在一件事上是 occasion，跨三件事才是 trait，合成一条会把「这次」说成「一贯」。
+  // - trait 组带 independentSessions（跨几个独立会话）。trait 的判据本来就是会话数，
+  //   面板只显示「稳定倾向」而不给数字，用户没法判断它是攒够了还是被猜测出来的。
+  // - 完全读不到时返回 500 + error，不返回空列表：空列表在面板上长得跟
+  //   「你还没记过任何情绪」一样，而这两件事对用户的含义完全相反。
+  //   前端靠 httpStatusCode 区分，不靠 items.length。
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/semantic/graph/affective",
+    policy: "open",
+    handler(req, res) {
+      try {
+        const url = new URL(req.url, "http://localhost");
+        const limit = Math.max(1, Math.min(500, Number(url.searchParams.get("limit") ?? 200) || 200));
+        if (typeof service.relationsByType !== "function") {
+          sendJson(res, 500, { error: "unavailable" });
+          return;
+        }
+        const edges = service.relationsByType("affective_context", limit) ?? [];
+        const groups = new Map();
+        for (const e of edges) {
+          const meta = e.metadata && typeof e.metadata === "object" ? e.metadata : {};
+          const emotion = String(meta.emotion ?? "").trim();
+          // 没有情绪名的边不进聚合：它是老版本或手工写的空壳，凑进「情绪一览」
+          // 会造出一个名字为空的条目。但也不能假装它不存在——计数单列。
+          const attribution = String(meta.attribution ?? "").trim() || "occasion";
+          if (!emotion) continue;
+          const key = `${e.from_entity}\u0000${e.to_entity}\u0000${emotion}\u0000${attribution}`;
+          if (!groups.has(key)) {
+            groups.set(key, {
+              person: e.from_name ?? null,
+              personId: e.from_entity,
+              target: e.to_name ?? null,
+              targetId: e.to_entity,
+              emotion,
+              attribution,
+              promotedToTrait: meta.promotedToTrait === true,
+              sessionCount: Number.isFinite(meta.sessionCount) ? meta.sessionCount : null,
+              traitSessionCount: Number.isFinite(meta.traitSessionCount) ? meta.traitSessionCount : null,
+              evidenceCount: Array.isArray(meta.evidence) ? meta.evidence.length : (e.memory_id ? 1 : 0),
+              firstSeen: e.created_at ?? null,
+              lastSeen: e.created_at ?? null,
+              edgeIds: []
+            });
+          }
+          const g = groups.get(key);
+          g.edgeIds.push(e.id);
+          if (e.created_at && (!g.lastSeen || e.created_at > g.lastSeen)) g.lastSeen = e.created_at;
+          if (e.created_at && (!g.firstSeen || e.created_at < g.firstSeen)) g.firstSeen = e.created_at;
+          if (e.from_name) g.person = e.from_name;
+          if (e.to_name) g.target = e.to_name;
+          if (Number.isFinite(meta.sessionCount)) {
+            g.sessionCount = Math.max(g.sessionCount ?? 0, meta.sessionCount);
+          }
+          if (Number.isFinite(meta.traitSessionCount)) {
+            g.traitSessionCount = Math.max(g.traitSessionCount ?? 0, meta.traitSessionCount);
+          }
+          if (meta.promotedToTrait === true) g.promotedToTrait = true;
+        }
+        const items = [...groups.values()].sort((a, b) => {
+          // trait 在前（更值得看），同类按最近一次出现倒序。
+          if ((b.attribution === "trait") !== (a.attribution === "trait")) {
+            return a.attribution === "trait" ? -1 : 1;
+          }
+          return String(b.lastSeen ?? "").localeCompare(String(a.lastSeen ?? ""));
+        });
+        sendJson(res, 200, {
+          items,
+          // 读到了多少条原始边、其中多少条因为没情绪名没进聚合。给出来是为了
+          // 让「只有 0 条」能自我解释：是库里真没有，还是有边但都不带情绪。
+          totalEdges: edges.length,
+          skippedEdges: edges.length - items.reduce((n, g) => n + g.edgeIds.length, 0),
+          truncated: edges.length >= limit
+        });
+      } catch {
+        sendJson(res, 500, { error: "internal" });
+      }
+    }
+  });
+
   // --- entity attrs: current valid attrs for one entity (graph hover panel) ---
   // Read-only; mirrors getCurrentAttrs (valid_until IS NULL). Also used as the
   // graph panel's fallback list when the ego graph is too sparse to draw.
@@ -2223,6 +2318,38 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     }
   });
 
+  // GET /conflicts/ledger（issue #641，beta 第三阶段）：矛盾分诊账本的只读面——
+  // 分诊分布（按 tier 计数）+ 最近账本行。conflict_ledger 是 bookkeeping 表，
+  // 这里的行不是待办（处置由 enforce 档自动完成），面板只回答「账本里有什么、
+  // 分布如何」。policy 与 /conflicts 同级（token）：行带标题级信息与检出时间，
+  // 不该对未持 token 的本地进程开放。
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/conflicts/ledger",
+    policy: "token",
+    handler(req, res) {
+      try {
+        if (req.method !== "GET") {
+          sendJson(res, 404, { error: "not-found" });
+          return;
+        }
+        const url = new URL(req.url, "http://localhost");
+        const limit = Math.min(200, Math.max(1, Number(url.searchParams.get("limit") ?? 50) || 50));
+        const offset = Math.max(0, Number(url.searchParams.get("offset") ?? 0) || 0);
+        const items = service.listConflictLedger({ limit, offset });
+        const counts = {
+          dup: service.countConflictLedger({ tier: "dup" }),
+          "cross-scope-dup": service.countConflictLedger({ tier: "cross-scope-dup" }),
+          evolution: service.countConflictLedger({ tier: "evolution" }),
+          conflict: service.countConflictLedger({ tier: "conflict" })
+        };
+        sendJson(res, 200, { items, counts, total: service.countConflictLedger() });
+      } catch {
+        sendJson(res, 500, { error: "internal" });
+      }
+    }
+  });
+
   register({
     kind: "exact",
     path: "/api/dsh-mneme/conflicts/resolve",
@@ -3047,18 +3174,47 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   // 为什么要 caller 指定 repo：一次面板加载若把 5 个 stale 仓库全扫一遍，用户只是
   // 打开一个页面却付了 5 次全仓扫描；列表路径只在 ?repo= 明确点名时才刷。
   function autoRefreshOne(repoId, facts) {
-    const result = { autoRefreshed: false, autoRefreshError: undefined, repo: facts };
+    const result = {
+      autoRefreshed: false,
+      autoRefreshError: undefined,
+      // autoRefreshSkipped 与 autoRefreshError 是两件事：前者是「我们主动没做」，
+      // 后者是「试了但失败了」。混成一个字段会让面板把一次正确的拒绝说成故障。
+      autoRefreshSkipped: undefined,
+      autoRefreshSkipNote: undefined,
+      repo: facts
+    };
     if (!config || config.chorographyAutoRefresh !== true) return result;
     if (!facts || facts.staleReason !== "git") return result;
     if (typeof choro.runT0Apply !== "function") return result;
+    // 有富化页时先别动手：读侧刷新只该刷新「确定性骨架」，不该在用户点开一页时
+    // 顺手把语义段（花模型调用换来的）连同 claims 一起清掉。T0 自己也会拒绝
+    // （guardT1Loss），这里提前拦一道是为了给面板一句能直接显示的人话，
+    // 并且不进 warn 日志——这不是异常。
+    if (Number(facts.enrichedPages ?? 0) > 0) {
+      result.autoRefreshSkipped = "t1-loss";
+      result.autoRefreshSkipNote =
+        `这个仓库有 ${facts.enrichedPages} 页已经富化过：自动刷新会退回骨架、清空语义段与结论，`
+        + "所以这次没有动。代码已变这件事仍然有效，需要新快照请在面板里手动点「重建骨架」。";
+      return result;
+    }
     try {
-      choro.runT0Apply({ repoRoot: facts.rootPath });
+      // guardT1Loss 必须显式传：库里的 enrichedPages 只是第一道提示（快、能生成人话），
+      // 真正读盘判断「会丢哪几页」的是 T0 自己。不传给 T0 等于把唯一的硬守卫关掉。
+      choro.runT0Apply({ repoRoot: facts.rootPath, guardT1Loss: true });
       result.autoRefreshed = true;
       // 重跑之后基线推进了，回执里的 stale 必须按新基线说话：沿用旧行的判定会让
       // 面板刚刷完就显示「代码已变」，也就是谎报一次失败。
       const fresh = typeof choro.repoFactsById === "function" ? choro.repoFactsById(repoId) : null;
       if (fresh) result.repo = fresh;
     } catch (err) {
+      // would-drop-t1 是 T0 侧的同一条判断（它读盘，比这里的库计数更准）：
+      // 到这一层说明库里的 enrichedPages 和磁盘上的实际情况对不上，仍按「主动跳过」
+      // 处理并把人话透出去，绝不报成刷新失败。
+      if (err?.code === "would-drop-t1") {
+        result.autoRefreshSkipped = "t1-loss";
+        result.autoRefreshSkipNote = String(err?.message ?? err);
+        return result;
+      }
       result.autoRefreshError = String(err?.message ?? err);
       ctx.logger?.warn?.(`dsh-mneme: choro auto refresh failed for repo ${repoId}: ${result.autoRefreshError}`);
     }
@@ -3078,6 +3234,8 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
       const repoParam = new URL(req.url, "http://localhost").searchParams.get("repo");
       let autoRefreshed = false;
       let autoRefreshError;
+      let autoRefreshSkipped;
+      let autoRefreshSkipNote;
       if (repoParam !== null && repoParam !== "") {
         const target = choro.resolveRepo(repoParam);
         if (target && !target.ambiguous) {
@@ -3086,13 +3244,15 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
             const refreshed = autoRefreshOne(target.id, repos[idx]);
             autoRefreshed = refreshed.autoRefreshed;
             autoRefreshError = refreshed.autoRefreshError;
+            autoRefreshSkipped = refreshed.autoRefreshSkipped;
+            autoRefreshSkipNote = refreshed.autoRefreshSkipNote;
             if (refreshed.repo) repos[idx] = refreshed.repo;
           }
         }
       }
       // cliCommand（#607）：面板空态直接把它贴出来，用户复制即用。推导不出
       // 入口时为 null，面板据此退回通用说法（不硬编一个假路径）。
-      sendJson(res, 200, { repos, autoRefreshed, autoRefreshError, cliCommand: CHORO_CLI });
+      sendJson(res, 200, { repos, autoRefreshed, autoRefreshError, autoRefreshSkipped, autoRefreshSkipNote, cliCommand: CHORO_CLI });
     }
   });
 
@@ -3161,10 +3321,15 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
           stale: repoNow.stale,
           staleReason: repoNow.staleReason,
           legacy: repoNow.legacy,
+          // 面板要靠它解释「为什么这次自动刷新没动」——它是主动拒绝的依据，
+          // 不是内部账本，所以随读页一起回。
+          enrichedPages: repoNow.enrichedPages ?? 0,
           lastRunAt: repoNow.lastRunAt
         } : { id: repo.id, name: repo.name },
         autoRefreshed: refreshed.autoRefreshed,
-        autoRefreshError: refreshed.autoRefreshError
+        autoRefreshError: refreshed.autoRefreshError,
+        autoRefreshSkipped: refreshed.autoRefreshSkipped,
+        autoRefreshSkipNote: refreshed.autoRefreshSkipNote
       });
     }
   });
@@ -3201,6 +3366,47 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     }
   });
 
+  // Claim 粒度失效清单（借 openwiki 的 Grounded Claims）。只读、policy open，
+  // 与其余 choro 读路由同级。
+  //
+  // 为什么不落库：判据是 git diff × claims 三列证据的纯机械比对，一次几十毫秒。
+  // 落库就多一份要失效的缓存，而它唯一的消费者（面板）本来就是打开时现读。
+  // 写路径一条不加，spec §4 的红线（生成只走 CLI）不动。
+  //
+  // 响应三态刻意分开，别让面板把「算不出来」说成「没事」：
+  //   200 clean:true             基线 == HEAD，确实没变
+  //   200 anchorStale:true       基线认不出 / git 不可读（附 reason）
+  //   200 clean:false 且有 pages  正常算出来了，逐页看 atRisk
+  // 仓库不存在 → 404；chorography 关闭 → 409；queries 未装配 → 503（由 choroGate 给）。
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/choro/claims",
+    policy: "open",
+    handler(req, res) {
+      if (!choroGate(req, res)) return;
+      const repo = choroResolveOr4xx(req, res);
+      if (!repo) return;
+      if (typeof choro.claimDrift !== "function") {
+        sendJson(res, 503, { error: "unavailable", reason: "choro-claims-unavailable" });
+        return;
+      }
+      let drift;
+      try {
+        drift = choro.claimDrift(repo.id);
+      } catch (err) {
+        // 读盘（页面正文判 hasT1）可能撞上权限/占用：说清是哪一步炸的，
+        // 不要假装「没有 claim」。
+        sendJson(res, 500, { error: "claims-failed", detail: String(err?.message ?? err) });
+        return;
+      }
+      if (!drift) {
+        sendJson(res, 404, { error: "repo-not-found" });
+        return;
+      }
+      sendJson(res, 200, drift);
+    }
+  });
+
   // 面板重建入口（收尾档 P34）：T0 apply 秒级同步回执。
   // policy token-write：写的是仓库磁盘的 .chorography/**，属数据面写。
   //