@modusensus/dsh-mneme 0.8.16 → 0.9.1

package/test/security-doc.test.js

@@ -0,0 +1,139 @@
+// SECURITY.md 的两处声明会随时间变成谎话，而且没人会注意到：
+// 一是「Supported Versions」表——0.9.0 发了两个月它还在写 0.8.x 活跃开发中（#SECURITY 审计实测）；
+// 二是文件里的相对链接——docs/DAEMON.md 实际在 dsh-mneme/docs/ 下，链接指错了也没人点。
+// 这里把两件事都锁住：版本行必须等于 package.json 的 major.minor，链接必须真的能 stat 到。
+// 不锁「正文里出现的版本号」——历史审计节记录的是过去的事实，写死版本号在那里是对的。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createSettings } from "../src/settings.js";
+import { createApi } from "../src/api.js";
+
+const pkgRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const repoRoot = path.dirname(pkgRoot);
+const docPath = path.join(repoRoot, "SECURITY.md");
+const doc = readFileSync(docPath, "utf8");
+
+// package.json 的 version → 支持表里应当出现的那一行（"0.9.0" → "0.9.x"）。
+const { version } = JSON.parse(readFileSync(path.join(pkgRoot, "package.json"), "utf8"));
+const [major, minor] = version.split(".");
+const expectedVersionRow = `${major}.${minor}.x`;
+
+// 取某一节（到下一个同级 ## 标题为止）。用节而不是全文 grep：
+// 历史审计节里也有 "v0.x.y" 字样，全文匹配会假绿。
+function section(heading) {
+  const start = doc.indexOf(heading);
+  assert.ok(start >= 0, `SECURITY.md 里应有「${heading}」一节`);
+  const rest = doc.slice(start + heading.length);
+  const end = rest.search(/\r?\n## /);
+  return end >= 0 ? rest.slice(0, end) : rest;
+}
+
+test("SECURITY.md 的支持版本表跟着 package.json 走（中英各一份）", () => {
+  for (const heading of ["## Supported Versions", "## 支持版本"]) {
+    const body = section(heading);
+    // 表第一行就是「当前支持」的那一行；锁它，别锁整表（历史版本行本来就该在）。
+    const rows = body.split(/\r?\n/).filter((l) => /^\|\s*[\d<]/.test(l));
+    assert.ok(rows.length >= 2, `${heading} 的版本表应至少两行，实际 ${rows.length} 行`);
+    const current = rows[0].split("|")[1].trim();
+    assert.equal(current, expectedVersionRow,
+      `${heading} 的首行应写 ${expectedVersionRow}（package.json 为 ${version}），实际写了 ${current}`);
+  }
+});
+
+test("SECURITY.md 的版本表在两种语言之间是同一张表", () => {
+  const versions = (heading) => section(heading)
+    .split(/\r?\n/)
+    .filter((l) => /^\|\s*[\d<]/.test(l))
+    .map((l) => l.split("|")[1].trim());
+  assert.deepEqual(versions("## 支持版本"), versions("## Supported Versions"),
+    "中文表与英文表的版本行必须逐行一致，否则读者会看到两个不同的支持范围");
+});
+
+test("SECURITY.md 里的相对链接都能落到真实文件", () => {
+  // 链接从仓库根解析（README 与 SECURITY.md 都在根上）。
+  // 只查相对路径：外链、锚点、mailto 不归这里管。
+  const links = [...doc.matchAll(/\[[^\]]*\]\(([^)\s]+)\)/g)]
+    .map((m) => m[1])
+    .filter((href) => !/^(?:[a-z][a-z0-9+.-]*:|#)/i.test(href))
+    .map((href) => href.split("#")[0])
+    .filter(Boolean);
+  assert.ok(links.length >= 2, `应解析出至少 2 条相对链接，实际 ${links.length}——正则失配会让这个用例变成永真`);
+  const broken = links.filter((href) => !existsSync(path.resolve(repoRoot, href)));
+  assert.deepEqual(broken, [], "这些相对链接指向了不存在的文件：" + broken.join(", "));
+});
+
+test("SECURITY.md 不再把供应商写成已停用的那家", () => {
+  // 依赖扫描的实况是 gitleaks + dependency-review + OSV-Scanner + Dependabot，
+  // 文档里曾长期写着第三方商业扫描平台（该平台并不在 CI 里跑）。
+  assert.ok(!/OrbisAI/i.test(doc), "依赖扫描工具应写 CI 里真实在跑的那几个，不能留旧供应商名");
+});
+
+// 安全模型节那两张路由清单是「从代码抄出来的」，抄错了没人会发现：
+// 实测就漏过 /persona（token-write，GET 开放）与 /conflicts（token，只读也要 token）。
+// 这里不重跑鉴权逻辑（那是 route-policy.test.js 的事），只锁「文档清单 == 代码里的 policy 声明」：
+// 以真实装配出来的路由为准，双向比对——文档少写、多写、写错边，都红。
+function declaredRoutes() {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const settings = createSettings(store.db);
+  const mounted = [];
+  createApi(
+    { webServer: { register(route) { mounted.push(route); return () => {}; } } },
+    service, settings, { add() {}, remove() {}, list: () => [] }, null, undefined, "secret-token"
+  );
+  // 路由名去掉公共前缀，文档里写的是 /export 而不是 /api/dsh-mneme/export。
+  return mounted.map((route) => ({
+    name: route.path.replace("/api/dsh-mneme", "") || "/",
+    policy: route.policy
+  }));
+}
+
+// 从清单行里抠出反引号包着的路由。只认「可选方法 + 斜杠开头」的形状，
+// 这样 `GET`/`HEAD` 这种纯方法名不会被当成路径。
+function routesInBullet(line) {
+  const out = [];
+  for (const m of line.matchAll(/`([^`]+)`/g)) {
+    const hit = m[1].trim().match(/^(?:GET|HEAD|POST|PUT|PATCH|DELETE)?\s*(\/\S*)$/);
+    if (hit) out.push(hit[1]);
+  }
+  return out;
+}
+
+function bullet(prefix) {
+  const line = doc.split(/\r?\n/).find((l) => l.startsWith(prefix));
+  assert.ok(line, `SECURITY.md 里应有以「${prefix}」开头的清单行`);
+  return routesInBullet(line);
+}
+
+// 文档里的 /semantic/graph/* 覆盖代码里的 /semantic/graph/ego 与 /semantic/graph/entity-attrs。
+function covers(docEntry, name) {
+  if (docEntry === name) return true;
+  return docEntry.endsWith("/*") && name.startsWith(docEntry.slice(0, -1));
+}
+
+test("SECURITY.md 的开放读清单与代码里的 policy 声明一致", () => {
+  const open = declaredRoutes().filter((r) => r.policy === "open" || r.policy === "token-write");
+  for (const prefix of ["- **Open reads", "- **开放读"]) {
+    const listed = bullet(prefix);
+    const missing = open.filter((r) => !listed.some((e) => covers(e, r.name))).map((r) => r.name);
+    assert.deepEqual(missing, [], `${prefix} 漏了这些实际开放的路由：${missing.join(", ")}`);
+    const stale = listed.filter((e) => !open.some((r) => covers(e, r.name)));
+    assert.deepEqual(stale, [], `${prefix} 写了代码里并不开放的路由：${stale.join(", ")}`);
+  }
+});
+
+test("SECURITY.md 的受门控清单与代码里的 policy 声明一致", () => {
+  const gated = declaredRoutes().filter((r) => r.policy === "token" || r.policy === "token-write");
+  for (const prefix of ["- **Gated routes", "- **受门控的路由"]) {
+    const listed = bullet(prefix);
+    const missing = gated.filter((r) => !listed.some((e) => covers(e, r.name))).map((r) => r.name);
+    assert.deepEqual(missing, [], `${prefix} 漏了这些实际受门控的路由：${missing.join(", ")}`);
+    const stale = listed.filter((e) => !gated.some((r) => covers(e, r.name)));
+    assert.deepEqual(stale, [], `${prefix} 写了代码里并不受门控的路由：${stale.join(", ")}`);
+  }
+});

package/test/sensitive-scan.test.js

@@ -205,3 +205,47 @@ test("长文本上的回溯有上界：写阻塞类回归的计时护栏", () =>
     assert.ok(ms < 2000, `${text.length} 字符耗时 ${ms.toFixed(1)}ms，超 2000ms 预算（回溯上界被破坏？）`);
   }
 });
+
+// 仓库文本守卫：语料里的凭据值必须以拼接形式存在，仓库里不得留下完整形状。
+// 触发这件事的是 GitHub secret scanning 的 alert #1——write-admission-samples.js 里
+// openai-key 那条曾经是整串字面量（同文件其它四条都已是 assemble 拼接），被报成
+// openai_api_key 的 open=true 告警。它本身不是泄露（正文是 a-z、0-9 的顺序串），
+// 但扫描器只看形状；而这条漏网说明「逐条记得改」靠不住，所以用一条测试把它钉住：
+// 以后谁再往语料里加字面量，这里先红，不用等 GitHub 来通知。
+test("语料里不留完整形状的凭据字面量（secret scanning alert #1 的回归锁）", async () => {
+  const { readFile, readdir } = await import("node:fs/promises");
+  const helpersDir = new URL("./helpers/", import.meta.url);
+  const files = (await readdir(helpersDir)).filter((f) => f.endsWith(".js"));
+  // 前缀集合与长度都对齐 src/sensitive-scan.js 的 github_token / slack_token /
+  // openai_key 三条规则——只有形状一致才谈得上「扫描器会认」，前缀写窄了等于给
+  // gho_ / ghs_ / xoxp- 这些同族凭据开后门。改那三条规则时这里要跟着改。
+  // 唯一放宽的是 sk- 的下限：生产规则是 24，这里用 20，宁可多报——漏报的代价是
+  // GitHub 再报一次告警，多报的代价只是有人来把这行改成拼接。
+  const rules = [
+    // kind 与生产判据对齐，下面的断言拿它反查 scanSensitive 是不是真认这个形状。
+    { re: /\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}\b/, what: "OpenAI key", kind: "openai_key", probe: `sk-${"a1".repeat(13)}` },
+    { re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36}\b/, what: "GitHub token", kind: "github_token", probe: `ghs_${"a1".repeat(18)}` },
+    { re: /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/, what: "Slack token", kind: "slack_token", probe: `xoxp-${"a1".repeat(8)}` }
+  ];
+  // 「与生产规则同源」不能只是注释：CodeRabbit 在 #465 指出前一版把前缀写窄了
+  // （只认 ghp_ / xoxb-，漏了 gho_/ghs_/xoxp-），注释却写着同源。所以这里反查
+  // scanSensitive——守卫的每条规则必须真的被生产判据认成同一个 kind，否则这条红。
+  // 生产规则收窄前缀时，这条测试会先于「GitHub 又报一次告警」发现不一致。
+  // 两段合起来才叫同源：探针要同时被**守卫的规则**和**生产判据**认下，且 kind 一致。
+  // 只查一边的话，任一侧收窄前缀都不会红——那正是 CodeRabbit 指出的失效模式。
+  for (const { re, what, kind, probe } of rules) {
+    assert.match(probe, re, `守卫自己的 ${what} 规则认不出 ${probe}，前缀写窄了？`);
+    assert.equal(scanSensitive(probe)?.kind, kind, `生产判据不认 ${probe} 为 ${kind}，守卫与它不同源`);
+  }
+  for (const file of files) {
+    const text = await readFile(new URL(file, helpersDir), "utf8");
+    for (const { re, what } of rules) {
+      const hit = text.match(re);
+      assert.equal(
+        hit,
+        null,
+        `${file} 里出现了完整的 ${what} 字面量（${hit?.[0]?.slice(0, 12)}…）：按 assemble 拼接，别整串写`
+      );
+    }
+  }
+});

package/test/serve.test.js

@@ -83,7 +83,7 @@ test("serve: save → search 走通;token 持久化 kv;二次启动复用同一
   // token 持久化在 kv external_api(与 DSH 面板/CLI 共用同一凭证通道)
   assert.equal(rt.settings.getExternalApi().token, rt.api.token);
 
-  // 检索回执:recorder 已接(index.js:294-309 同款),recall_runs 不缺数 —— #363 回帖
+  // 检索回执:recorder 已接(index.js 的 setRecallRecorder,2026-10-14 在 :339-350),recall_runs 不缺数 —— #363 回帖
   // 向 bridge 承诺过「第三方检索的复用统计不受影响」,这条就是该承诺的回归锁。
   const recallRows = rt.store.db.prepare("SELECT COUNT(*) AS n FROM recall_runs").get();
   assert.ok(recallRows.n >= 1, "recall_runs should record the search above");

package/test/session-usage.test.js

@@ -0,0 +1,308 @@
+/**
+ * 会话日志使用证据（src/session-usage.js）的回归测试。
+ *
+ * 本文件锁的重点是**两类「静默少一大截」的坑**（都真踩过）：
+ *   ① **zstd 多帧**：`zlib.zstdDecompressSync(buf)` 只解**第一帧**且不报错——实测一个
+ *      1.5 MB 的会话文件只解出 291 字节，于是扫描得出「零命中」的假结论。所以这里用
+ *      **两帧拼接的夹具**钉死「两帧都要解出来」。
+ *   ② **参数在 `arguments` 且是 JSON 字符串**：取 `parameters` 会得到 null，看着像
+ *      「调用了但没记参数」。夹具按真实形态写。
+ *
+ * 另外钉住状态推导的语义边界：`candidate` 是「现存日志里没记录」，不是「从未使用」。
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, symlinkSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import zlib from "node:zlib";
+
+import {
+  forEachFrame,
+  toolCallsInLine,
+  identifyCapability,
+  deriveUsageState,
+  collectUsage,
+  summarizeUsage,
+  resolveSessionDir,
+  findSessionFiles,
+  STALE_AFTER_DAYS
+} from "../src/session-usage.js";
+
+const ZSTD_MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd]);
+
+/** 把若干段文本各压成一帧再拼起来，模拟真实的多帧文件。 */
+function multiFrameBuffer(chunks) {
+  return Buffer.concat(chunks.map((c) => zlib.zstdCompressSync(Buffer.from(c, "utf8"))));
+}
+
+/** 造一行真实的 tool-call 记录（参数是 JSON 字符串，不是对象）。 */
+function toolCallLine({ name, args, turn = 1, time = 1700000000000 }) {
+  const item = { type: "tool-call", id: `call_${Math.random().toString(36).slice(2)}`, name };
+  if (args !== undefined) item.arguments = JSON.stringify(args);
+  return JSON.stringify({
+    type: "assistant/message",
+    time,
+    data: { turn, step: 1, message: { role: "assistant", content: [item] } }
+  });
+}
+
+/** 造一个会话目录，内容按给定数组写进一个文件。 */
+function makeSessionDir(lines) {
+  const base = mkdtempSync(join(tmpdir(), "mneme-usage-"));
+  const sessionId = "session-test-0001";
+  const dir = join(base, "sessions", `--work-${sessionId.slice(0, 8)}--`, sessionId);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "session.v4.jsonl.zstd"), multiFrameBuffer(lines), "utf8");
+  return { base, dir: join(base, "sessions"), cleanup: () => rmSync(base, { recursive: true, force: true }) };
+}
+
+test("多帧 zstd：**每一帧**都要解出来（只解第一帧是踩过的坑）", () => {
+  const buf = multiFrameBuffer(["第一帧的内容", "第二帧的内容", "第三帧的内容"]);
+  const seen = [];
+  const stat = forEachFrame(buf, (text) => seen.push(text));
+  assert.deepEqual(seen, ["第一帧的内容", "第二帧的内容", "第三帧的内容"], "三帧都要被回调到");
+  assert.equal(stat.frames, 3);
+  assert.equal(stat.failed, 0);
+  // 反证：证明这个夹具真能暴露「只解第一帧」——直接 zstdDecompressSync 只能拿到第一段
+  assert.equal(zlib.zstdDecompressSync(buf).toString("utf8"), "第一帧的内容");
+});
+
+test("多帧 zstd：每帧都解；截断产生的**半行**由 jsonl 层丢掉（宁可少一条，不要错一条）", () => {
+  // 真实的「坏帧」不是帧头损坏，而是**文件正在写**：末帧被截断。
+  // 实测结论（写这条时验过）：zstd 是流式格式，截断帧会**解出部分文本而不抛错**，
+  // 且 Node 的绑定不暴露「还有多少输入未消费」，所以帧层的完整性判不了。
+  // 兜底放在**行层**：半行 JSON 解析失败会被丢弃——代价是少一条记录，收益是绝不误用。
+  const good = zlib.zstdCompressSync(Buffer.from("完整帧的内容", "utf8"));
+
+  // 帧层：两帧都要回调到（这是最初踩的坑——只解第一帧）
+  const seen = [];
+  const stat = forEachFrame(Buffer.concat([good, good]), (t) => seen.push(t));
+  assert.equal(stat.frames, 2);
+  assert.equal(seen.length, 2);
+
+  // 行层兜底：一个被截断的 tool-call 行不能被当完整记录用
+  const fullLine = toolCallLine({ name: "skill", args: { name: "agent-reach" } });
+  assert.equal(toolCallsInLine(fullLine).length, 1, "完整行要解析出来");
+  const halfLine = fullLine.slice(0, Math.floor(fullLine.length / 2));
+  assert.deepEqual(toolCallsInLine(halfLine), [], "半行必须被丢掉，不能猜出一个不完整的调用");
+
+  // 真实截断文件：整帧 + 半帧 → 完整的那些记录照常统计，半行被丢
+  const base = mkdtempSync(join(tmpdir(), "mneme-usage-trunc-"));
+  try {
+    const sessionId = "session-trunc-0001";
+    const dir = join(base, "sessions", "work", sessionId);
+    mkdirSync(dir, { recursive: true });
+    const truncated = zlib.zstdCompressSync(Buffer.from(fullLine, "utf8")).subarray(0, 12);
+    writeFileSync(join(dir, "session.v4.jsonl.zstd"), Buffer.concat([good, truncated]));
+    const c = collectUsage({ sessionDir: join(base, "sessions") });
+    assert.equal(c.scannedFiles, 1);
+    // 好帧里没有 tool-call，截断帧里的调用不完整 → 一条都不该被记
+    assert.equal(c.skillCalls, 0, "截断的半行不能被算成一次调用");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("tool-call 解析：参数在 arguments 且是 JSON 字符串", () => {
+  // 真实形态：{"type":"tool-call","name":"skill","arguments":"{\"name\":\"agent-reach\"}"}
+  const line = toolCallLine({ name: "skill", args: { name: "agent-reach" }, turn: 7, time: 1792000000000 });
+  const calls = toolCallsInLine(line);
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].name, "skill");
+  assert.equal(calls[0].args.name, "agent-reach", "arguments 要二次解析成对象");
+  assert.equal(calls[0].turn, 7);
+  assert.equal(calls[0].time, 1792000000000);
+});
+
+test("tool-call 解析：坏 JSON、非 tool-call 行、参数缺失都要能分清", () => {
+  assert.deepEqual(toolCallsInLine("{ 这不是 JSON"), []);
+  assert.deepEqual(toolCallsInLine(JSON.stringify({ type: "user/message" })), []);
+  // 参数缺失：**调用本身要保留**（它确实发生过），只是 args 为 null
+  const noArgs = toolCallLine({ name: "skill" });
+  const calls = toolCallsInLine(noArgs);
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].args, null);
+});
+
+test("能力识别：skill 取 arguments.name；MCP 取 mcp__<server>__<tool> 的 server 段", () => {
+  assert.deepEqual(identifyCapability({ name: "skill", args: { name: "agent-reach" } }), {
+    kind: "skill",
+    name: "agent-reach"
+  });
+  const mcp = identifyCapability({ name: "mcp__github__get_file_contents", args: {} });
+  assert.equal(mcp.kind, "mcp");
+  assert.equal(mcp.name, "github", "MCP 按 server 聚合（清单里的条目是 server 粒度）");
+  assert.equal(mcp.tool, "get_file_contents");
+  // 内置工具不是能力清单里的东西 → null（丢掉，不计 unmatched）
+  assert.equal(identifyCapability({ name: "read", args: {} }), null);
+  assert.equal(identifyCapability({ name: "pwsh", args: {} }), null);
+  // skill 没记 name → 返回 name:null，让上层计入 unmatched（如实报，不硬凑）
+  assert.deepEqual(identifyCapability({ name: "skill", args: {} }), { kind: "skill", name: null });
+  // mcp__ 后面 server 段为空同理
+  assert.equal(identifyCapability({ name: "mcp____x", args: {} }).name, null);
+});
+
+test("状态推导：没记录=candidate、用过=trusted、久未用=stale", () => {
+  const now = Date.parse("2026-10-16T00:00:00Z");
+  assert.equal(deriveUsageState(null, { now }), "candidate");
+  assert.equal(deriveUsageState({ uses: 0, lastUsedAt: null }, { now }), "candidate", "0 次也算没记录");
+  // 30 天前用过 → trusted
+  assert.equal(deriveUsageState({ uses: 3, lastUsedAt: now - 30 * 86400000 }, { now }), "trusted");
+  // 超过阈值 → stale
+  assert.equal(deriveUsageState({ uses: 3, lastUsedAt: now - (STALE_AFTER_DAYS + 1) * 86400000 }, { now }), "stale");
+  // 恰好在阈值上不算 stale（边界）
+  assert.equal(deriveUsageState({ uses: 3, lastUsedAt: now - STALE_AFTER_DAYS * 86400000 }, { now }), "trusted");
+  // 没有时间戳但有次数 → 不能判 stale，保守给 trusted
+  assert.equal(deriveUsageState({ uses: 1, lastUsedAt: null }, { now }), "trusted");
+});
+
+test("整条链路：从会话文件聚合出技能与 MCP 计数", () => {
+  const ctx = makeSessionDir([
+    toolCallLine({ name: "skill", args: { name: "agent-reach" }, turn: 1, time: 1792000000000 }),
+    toolCallLine({ name: "mcp__github__get_file_contents", args: {}, turn: 1 }),
+    toolCallLine({ name: "skill", args: { name: "agent-reach" }, turn: 2, time: 1792050000000 }),
+    toolCallLine({ name: "skill", args: { name: "euthyna" }, turn: 3 }),
+    toolCallLine({ name: "read", args: { path: "x" }, turn: 3 }), // 内置，忽略
+    toolCallLine({ name: "skill", args: {}, turn: 4 }) // 缺 name → unmatched
+  ]);
+  try {
+    const c = collectUsage({ sessionDir: ctx.dir });
+    assert.equal(c.present, true);
+    assert.equal(c.scannedFiles, 1);
+    assert.equal(c.skillCalls, 3, "两次 agent-reach + 一次 euthyna");
+    assert.equal(c.mcpCalls, 1);
+    assert.equal(c.unmatched, 1, "缺 name 的那次要对不上，不能静默丢");
+    assert.equal(c.skills.get("agent-reach").uses, 2);
+    // 最近一次使用要取最大的那个时间戳
+    assert.equal(c.skills.get("agent-reach").lastUsedAt, 1792050000000);
+    assert.equal(c.mcp.get("github").uses, 1);
+  } finally {
+    ctx.cleanup();
+  }
+});
+
+test("降级：会话目录不存在时如实报 present=false，不抛错不编造", () => {
+  const base = mkdtempSync(join(tmpdir(), "mneme-usage-none-"));
+  try {
+    const c = collectUsage({ sessionDir: join(base, "no-such-dir") });
+    assert.equal(c.present, false);
+    assert.equal(c.scannedFiles, 0);
+    assert.equal(c.skillCalls, 0);
+    assert.deepEqual([...c.skills.keys()], []);
+    const s = summarizeUsage(c);
+    assert.deepEqual(s.skills, []);
+    assert.deepEqual(s.mcp, []);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("会话目录默认值由 dshHome 推导，不写死本机路径", () => {
+  const dir = resolveSessionDir({ dshHome: "/custom/dsh" });
+  assert.ok(dir.includes("sessions"), "默认落在 sessions 子目录");
+  assert.ok(!/[A-Za-z]:\\Users/i.test(dir), "不得出现本机盘符路径");
+  // 环境变量优先
+  assert.ok(resolveSessionDir({ dshHome: join(tmpdir(), "x") }).includes("x"));
+});
+
+test("文件发现：**所有版本**的会话文件都要收（只认 v4 会漏掉一半历史）", () => {
+  // 实测回归：本机同一会话树下并存三种格式——v4（219）、v3（218）、无版本号（72）。
+  // 早期版本只认 `session.v4`，静默漏掉 50 次技能调用（euthyna 44 次），
+  // 导致三个明明用过的技能被报成 candidate。所以只要求「以 session 开头」。
+  const base = mkdtempSync(join(tmpdir(), "mneme-usage-find-"));
+  try {
+    const sessions = join(base, "sessions");
+    mkdirSync(join(sessions, "a", "id1"), { recursive: true });
+    mkdirSync(join(sessions, "b", "id2"), { recursive: true });
+    writeFileSync(join(sessions, "a", "id1", "session.v4.jsonl.zstd"), multiFrameBuffer(["x"]));
+    writeFileSync(join(sessions, "b", "id2", "session.v3.jsonl.zstd"), multiFrameBuffer(["y"]));
+    writeFileSync(join(sessions, "b", "id2", "session.jsonl.zstd"), multiFrameBuffer(["z"]));
+    writeFileSync(join(sessions, "a", "id1", "other.jsonl"), "不该被收");
+    const found = findSessionFiles(sessions);
+    assert.equal(found.files.length, 3, "v4 / v3 / 无版本号三种都要找到，other.jsonl 不要");
+    assert.equal(found.unreadable.length, 0);
+    assert.equal(found.present, true);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("文件上限可注入，且截断要留痕（CodeRabbit 抓到的静默截断）", () => {
+  // 实测回归：早期版本把上限写死在遍历里（MAX_SESSION_FILES=2000），于是
+  //   · 调用方传 maxFiles: 5000 也只拿到 2000 个——参数无效，无从察觉；
+  //   · 截断发生在内层，外层算不出 truncated（`found.files.length > maxFiles` 永假）。
+  // 结果就是「只扫了一部分」却看起来像扫全了——本仓库反复防的那类静默错。
+  const base = mkdtempSync(join(tmpdir(), "mneme-usage-cap-"));
+  try {
+    const sessions = join(base, "sessions");
+    // 造 12 个会话文件，限 5 个：应拿到 5 个 + truncated=true
+    for (let i = 0; i < 12; i++) {
+      const d = join(sessions, `s${String(i).padStart(2, "0")}`);
+      mkdirSync(d, { recursive: true });
+      writeFileSync(join(d, "session.v4.jsonl.zstd"), multiFrameBuffer([`line${i}`]));
+    }
+
+    // ① limit 真的生效（不是被内层写死的上限压住）
+    const capped = findSessionFiles(sessions, { limit: 5 });
+    assert.equal(capped.files.length, 5, "limit=5 就该只拿 5 个");
+    assert.equal(capped.truncated, true, "被截断必须留痕");
+
+    // ② 不设限时全拿到，且不报截断
+    const all = findSessionFiles(sessions);
+    assert.equal(all.files.length, 12);
+    assert.equal(all.truncated, false, "没截断就不该报截断");
+
+    // ③ collectUsage 透传：maxFiles 生效，且 truncated 透出来
+    const c = collectUsage({ sessionDir: sessions, maxFiles: 5 });
+    assert.equal(c.scannedFiles, 5);
+    assert.equal(c.truncated, true, "collectUsage 要把截断标记透出来");
+    assert.equal(c.totalFiles, 5, "totalFiles 是被限制后的数量（不是磁盘总数）");
+
+    // ④ 给足够大的 maxFiles 时能扫全（旧实现这里会失败：内层卡 2000）
+    const c2 = collectUsage({ sessionDir: sessions, maxFiles: 9999 });
+    assert.equal(c2.scannedFiles, 12);
+    assert.equal(c2.truncated, false);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("目录不可读要与「空目录」**可分辨**（不许同形）", () => {
+  // 实测回归：早期版本用 existsSync 定 present、readdirSync 失败直接 return，
+  // 于是 ACL 拒绝的目录产出与「可读空目录」逐字段相同的读数
+  // （present=true, scannedFiles=0, unreadable=[]），清单侧 175 条全 candidate。
+  // 这正是本仓库反复防的那类错：读不到被显示成「读到但没有」。
+  const base = mkdtempSync(join(tmpdir(), "mneme-usage-unreadable-"));
+  try {
+    // ① 不存在的目录：present=false
+    const missing = findSessionFiles(join(base, "nope"));
+    assert.equal(missing.present, false);
+    assert.equal(missing.files.length, 0);
+
+    // ② 存在的空目录：present=true、无 unreadable
+    const empty = join(base, "empty");
+    mkdirSync(empty, { recursive: true });
+    const emptyRes = findSessionFiles(empty);
+    assert.equal(emptyRes.present, true);
+    assert.equal(emptyRes.files.length, 0);
+    assert.equal(emptyRes.unreadable.length, 0, "空目录不该有 unreadable");
+
+    // ③ 悬空符号链接：present=true，但**必须有 unreadable**，与空目录不同形
+    try {
+      symlinkSync(join(base, "no-such-target"), join(empty, "session.dangling.jsonl.zstd"), "junction");
+    } catch (error) {
+      if (error.code === "EPERM" || error.code === "EACCES") return; // 无权限则跳过本断言
+      throw error;
+    }
+    const dangling = findSessionFiles(empty);
+    assert.ok(dangling.unreadable.length > 0, "读不到的项必须留痕，否则与空目录同形");
+    // 而且上层能区分：collectUsage 的 readable 会变 false
+    const c = collectUsage({ sessionDir: empty });
+    assert.equal(c.present, true);
+    assert.equal(c.readable, false, "有读不动的项时 readable 必须为 false");
+    assert.ok(c.unreadable.length > 0, "unreadable 要透到 collectUsage");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});