@modusensus/dsh-mneme 0.8.16 → 0.9.1

package/src/scope.js

@@ -48,9 +48,17 @@ export function createScopeResolver({ ctx, config, logger } = {}) {
       header = null;
     }
 
+    // header 字段的读取要各自护住：session.header 本身取得回来，不代表它的字段
+    // 取得回来——宿主可以给出会抛错的 accessor（sessionOf / sessionKeyOf 就是为
+    // 同一类宿主写的）。漏在这里的异常会穿出解析器，把调用方的整段写入拖挂：
+    // 蒸馏路径上是一个窗口的记忆与游标一起丢，工具路径上是一次 memory_save 直接失败。
     let agentScope = null;
-    const preset = header?.agentPreset;
-    if (typeof preset === "string" && preset.trim()) agentScope = preset.trim();
+    try {
+      const preset = header?.agentPreset;
+      if (typeof preset === "string" && preset.trim()) agentScope = preset.trim();
+    } catch (e) {
+      warnOnce(`[dsh-mneme] session header agentPreset lookup failed: ${String(e)}`);
+    }
 
     // workspace：registry 反查优先（成员资格 = id 命中 + header canonical cwd
     // 校验过，path 已 realpath 归一），失败回退 header.cwd，再失败留 NULL。
@@ -70,8 +78,12 @@ export function createScopeResolver({ ctx, config, logger } = {}) {
       );
     }
     if (!workspaceScope) {
-      const cwd = header?.cwd;
-      if (typeof cwd === "string" && cwd.trim()) workspaceScope = cwd.trim();
+      try {
+        const cwd = header?.cwd;
+        if (typeof cwd === "string" && cwd.trim()) workspaceScope = cwd.trim();
+      } catch (e) {
+        warnOnce(`[dsh-mneme] session header cwd lookup failed: ${String(e)}`);
+      }
     }
 
     return { agent_scope: agentScope, workspace_scope: workspaceScope };

package/src/semantic.js

@@ -28,29 +28,59 @@ import { LocalReranker } from "./reranker.js";
  */
 export async function backfillMissingEmbeddings({
   store, embedder, vectorIndex, logger,
+  // maxTotal: 0 = no cap (drain the whole backlog this run). The default stays
+  // modest so a boot never floods a provider, but the cap is a caller choice
+  // now instead of a hardcoded one — the fixed 500 meant a 4k-row backlog
+  // needed nine restarts to clear, and nothing reported that it had been cut.
   maxTotal = 500, batchSize = 10, rateLimitMs = 200
 }) {
+  const startedAt = new Date().toISOString();
+  // Model-aware selector: rows whose vector came from another model (or
+  // predate per-row provenance) must be re-embedded too, otherwise a model
+  // switch leaves uncomparable vectors in the index forever.
+  const model = embedder.modelHash;
+  const pick = (n) => (typeof store.needsEmbeddingFor === "function"
+    ? store.needsEmbeddingFor(model, n)
+    : store.needsEmbedding(n));
+  const unlimited = !(maxTotal > 0);
   let indexed = 0;
-  for (let done = 0; done < maxTotal;) {
-    const rows = store.needsEmbedding(batchSize);
+  let processed = 0;
+  let failed = 0;
+  for (let done = 0; unlimited || done < maxTotal;) {
+    const rows = pick(batchSize);
     if (!rows.length) break;
     for (const row of rows) {
       try {
         const text = [row.title, row.content].filter(Boolean).join("\n");
         const vector = await embedder.embedSingle(text);
         if (vector?.length) {
-          store.setEmbedding(row.id, vector);
+          store.setEmbedding(row.id, vector, model);
           indexed++;
+        } else {
+          failed++;
         }
-      } catch { /* skip the bad row */ }
+      } catch { failed++; /* skip the bad row, but count it */ }
     }
     done += rows.length;
+    processed += rows.length;
     // Rate limit: space out batches so the provider is not hammered.
-    if (store.needsEmbedding(1).length) await new Promise((r) => setTimeout(r, rateLimitMs));
+    if (pick(1).length) await new Promise((r) => setTimeout(r, rateLimitMs));
   }
-  if (indexed > 0 && embedder.modelHash) vectorIndex.markModel?.(embedder.modelHash, embedder.dimension);
-  logger?.info?.(`[dsh-mneme] auto-reindex backfilled ${indexed} embeddings on boot`);
-  return indexed;
+  if (indexed > 0 && model) vectorIndex.markModel?.(model, embedder.dimension);
+  // stillStale answers "did it actually finish?". The old return value was a
+  // bare indexed count, so a run that hit the cap looked exactly like a run
+  // that drained the backlog.
+  const stillStale = pick(1).length > 0;
+  const finishReason = stillStale ? "capped" : (failed > 0 && indexed === 0 ? "all-failed" : "drained");
+  logger?.info?.(
+    `[dsh-mneme] auto-reindex backfilled ${indexed} embeddings (processed=${processed}, failed=${failed}, finish=${finishReason})`
+  );
+  return {
+    indexed, processed, failed, finishReason, stillStale,
+    startedAt,
+    finishedAt: new Date().toISOString(),
+    model: model ?? null
+  };
 }
 
 /**
@@ -74,6 +104,9 @@ export function createSemantic({ store, service, settings, cfg, logger, vectorIn
   // boot 回填首查计时器。搬移前在 index.js 是裸 setTimeout(不参与卸载清理);
   // 纳入 dispose 是修悬挂,不改变启动行为。
   let reindexTimer = null;
+  // Last boot-backfill summary, exposed via backfillStatus() so "did it
+  // finish?" has an answer other than a log line.
+  let lastBackfill = null;
 
   if (lightMode) {
     // Light mode: the whole vector pipeline stays off — no embedder (nothing
@@ -202,12 +235,31 @@ export function createSemantic({ store, service, settings, cfg, logger, vectorIn
           if (tries > 0) reindexTimer = setTimeout(() => attempt(tries - 1), 2000);
           return;
         }
-        if (!store.needsEmbedding(1).length) return; // nothing to backfill
+        const model = embedder.modelHash;
+        const stale = typeof store.hasStaleEmbedding === "function"
+          ? store.hasStaleEmbedding(model)
+          : store.needsEmbedding(1).length > 0;
+        if (!stale) return; // nothing missing and nothing from another model
         // Issue #128: no fingerprint gate here anymore — a matching fingerprint
         // used to return early and permanently orphan rows whose embed failed
         // at write time. See backfillMissingEmbeddings().
-        backfillMissingEmbeddings({ store, embedder, vectorIndex, logger })
+        // Cap and pacing are configuration now (reindexMaxPerBoot /
+        // reindexBatchSize / reindexRateLimitMs) instead of hardcoded 500/10/200.
+        lastBackfill = {
+          state: "running", startedAt: new Date().toISOString(),
+          maxTotal: cfg.reindexMaxPerBoot, batchSize: cfg.reindexBatchSize
+        };
+        backfillMissingEmbeddings({
+          store, embedder, vectorIndex, logger,
+          maxTotal: cfg.reindexMaxPerBoot,
+          batchSize: cfg.reindexBatchSize,
+          rateLimitMs: cfg.reindexRateLimitMs
+        })
+          .then((summary) => {
+            lastBackfill = { ...summary, state: "finished" };
+          })
           .catch((error) => {
+            lastBackfill = { state: "error", error: String(error), startedAt: lastBackfill?.startedAt };
             logger?.warn?.(`[dsh-mneme] auto-reindex failed: ${String(error)}`);
           });
       } catch (error) {
@@ -221,6 +273,10 @@ export function createSemantic({ store, service, settings, cfg, logger, vectorIn
   return {
     embedder,
     reranker,
+    /** Last backfill run: { state, indexed, failed, finishReason, stillStale, ... }. */
+    backfillStatus() {
+      return lastBackfill;
+    },
     dispose() {
       if (embedRetryTimer !== null) { clearTimeout(embedRetryTimer); embedRetryTimer = null; }
       if (reindexTimer !== null) { clearTimeout(reindexTimer); reindexTimer = null; }

package/src/serve.js

@@ -112,7 +112,7 @@ export async function createServeRuntime({
     }
   }
 
-  // index.js:294-309:检索回执落 recall_runs(searchMemories 的 recordRecall 默认开,
+  // index.js 的 setRecallRecorder（2026-10-14 在 :339-350）：检索回执落 recall_runs(searchMemories 的 recordRecall 默认开,
   // 第三方检索统计因此不缺数)。best-effort:回执写失败绝不影响检索本身。
   service.setRecallRecorder((recall) => {
     try {

package/src/service.js

@@ -18,9 +18,14 @@ import { anchorSeeds, normalizePath, cascadeDepths, HOP_QUOTA } from "./graph/an
 // 的 recall_runs `auto` 模式里被按需检索过 328 次：不是垃圾数据，只是进不了注入池。
 // 收编后候选池 1362 → 1713（+25.8%），按 top_k=5 粗算约多占 1 席；重要度闸门对
 // history 一视同仁（见 injectCandidates 的 importance >= threshold），低于闸门照旧出局。
-// pattern 一并收编：它只由手工写入（实测 40 条全 source=manual），却已被 dreamMergeGuard
-// 列为长保留受保护类型（docs/CONFIGURATION.md）——巩固层当资产护住、注入面一次不给看，
-// 是同一条口径的两头不一致。
+// pattern 一并收编：它一度被当成「只由手工写入（实测 40 条全 source=manual）」——那个
+// 判据是错的。机器一直在 mint：2026-10-14 按 dream_runs 的 patterns.applied 逐轮求和，
+// 得 144，与表内 pattern 行数 144 相等（72 轮 sleep 里 48 轮 ok，auto 轮 0），来源是
+// src/dream/sleep.js 的 phasePatterns；当时的 source=manual 只是 saveWithDedupe 没拿到
+// source 时的兜底值，不是「人写的」的意思（现在 mint 会带 source=sleep/dream）。
+// 但它确实已被 dreamMergeGuard 列为长保留受保护类型（docs/CONFIGURATION.md）——巩固层
+// 当资产护住、注入面一次不给看，是同一条口径的两头不一致。这一点与作者是谁无关，
+// 收编的结论不变，错的只是当初用来支持它的那句前提。
 const INJECT_TYPES = new Set(["preference", "project", "decision", "summary", "rejected_solution", "pitfall", "constraint", "history", "pattern"]);
 
 // document 摘要行（#230）：仅 documentMemoryEnabled 开启时进注入候选。独立
@@ -1293,7 +1298,10 @@ export function createService({ store, mirror, config, onWrite, logger, document
     let quality = null;
     if (qf?.enabled === true) {
       try {
-        const recentContents = store.all().slice(0, 20).map((m) => m.content ?? "");
+        // #430：近重复判定只要最近 20 条正文，别再为了 slice(0,20) 先物化整库
+        // （all() + 逐行 toRow，5k 行实测 100ms 级；本查询 0.06ms 级）。口径与
+        // all().slice(0, 20) 一致：不加 WHERE、updated_at DESC、同刻顺序未定义。
+        const recentContents = store.recentContents(20);
         quality = evaluateMemoryQuality(memory, {
           minContentLength: qf.minContentLength ?? 10,
           recentContents
@@ -1837,9 +1845,15 @@ export function createService({ store, mirror, config, onWrite, logger, document
     if ((config?.recallRecordDefault ?? true) && recallRecorder && injected.length > 0) {
       try {
         recallRecorder({
-          // recall_runs.query 是 NOT NULL（store.js:61）：注入是主动曝光、
-          // 没有查询词，用空串而非 null——SQLite 改列约束需重建表，不值得。
-          query: "",
+          // recall_runs.query 是 NOT NULL（store.js 的 recall_runs 建表语句，
+          // 2026-10-14 在 :75）—— 注入是主动曝光，
+          // 没有查询词时用空串而非 null——SQLite 改列约束需重建表，不值得。
+          // v0.9.0：调用方（inject.js 的 lastUserQuery，2026-10-14 在 :343）本来就带着本轮的
+          // 用户原话传进来，这里丢掉等于把「当时想干什么」从审计里抹掉
+          // （2026-10-13 快照：18,231/18,231 注入行 query 全空，全空比例
+          // 100%——这个比率才是要记的，绝对行数随表长，引用要带时刻）。
+          // 有就记，真没有才空串。
+          query: q,
           mode: "inject",
           topK: maxItems,
           threshold: null,
@@ -1944,6 +1958,9 @@ export function createService({ store, mirror, config, onWrite, logger, document
         setArchived: (mid, v) => archiveMemory(mid, v),
         transaction: (fn) => transaction(fn)
       };
+      // 不传 mintSource——本路径由人在面板上点确认，即便日后有人在这里加
+      // create，落 saveWithDedupe 的 manual 兜底恰好就是对的语义（人触发的写入）。
+      // 这是刻意的，不是漏传。
       const { committed, failures } = applyDecisions(
         [{ action: "conflict", winner: winnerId, loser: loserId, reason: row.reason ?? "" }],
         applyService,
@@ -2150,18 +2167,22 @@ export function createService({ store, mirror, config, onWrite, logger, document
     try {
       // 预先取本次要覆盖的全部活跃行（只读一次）。这里曾经是
       // store.list({ limit: 500 })——活跃集超过 500 时镜像会静默少掉尾部记忆，
-      // 而文件本身没有任何提示（#278 第一批）。store.list 的 limit 默认值只有
-      // 50，比原来显式传的 500 更小，所以改用 all() 并在这里做同一套过滤
-      // （forgotten/archived 都不进镜像，与 includeForgotten:false + 默认
-      // includeArchived:false 等价）。
-      // 代价是全表读，且落在每次业务写后的最热路径上（#202 自记 all() 5k 行
-      // 231ms → ~135ms）。要压这一层得换按 type 分页取，属另一批的事；
-      // 在这里退回任何截断都不行——「宣称覆盖活跃集」与静默截断不能共存。
-      const list = store.all().filter((m) => !m.forgotten && !m.archived
+      // 而文件本身没有任何提示（#278 第一批）。在这里退回任何截断都不行——
+      // 「宣称覆盖活跃集」与静默截断不能共存（这一条不变）。
+      // #430：改成 list 的无界档（limit: null）+ SQL 侧过滤，替掉 all() + 逐行
+      // filter——list 的默认 includeForgotten:false / includeArchived:false 与旧
+      // filter 的 !forgotten && !archived 完全同口径（store.js 里就是这两条
+      // clause），document 闸改由 excludeTypes 在 LIMIT 之前排除。旧写法先物化
+      // 整库（embedding 列 + 逐行 27 字段 toRow）再逐行丢弃：被丢掉的行连带它们
+      // 的物化一起省下了。要再压一层得换按 type 分页取，属另一批的事。
+      const list = store.list({
+        limit: null,
+        order: "chrono",
         // #296 第二批：镜像里的 documents.md 与 index.md 共用 documentMemoryEnabled
         // 闸。关掉时把 document 行也从渲染集里去掉——sync 对「空 type」的既有处理
         // 会把陈旧的 documents.md 删掉，不留一个「看着还在、其实已关」的视图。
-        && (m.type !== "document" || config?.documentMemoryEnabled === true));
+        excludeTypes: config?.documentMemoryEnabled === true ? null : ["document"]
+      });
       for (const memory of list) {
         if (memory?.type && TYPE_FILE[memory.type]) {
           coveredTypes.add(memory.type);
@@ -2524,11 +2545,31 @@ export function createService({ store, mirror, config, onWrite, logger, document
       // Async-initializing embedder: poll `ready` until it flips, then flush.
       if ("ready" in emb && embedReadyTimer === null) {
         let attempts = 0;
+        let readyReadFailed = false;
+        // 读 `ready` 必须先兜住异常再算天花板，否则天花板形同不存在：`ready` 是
+        // getter（embedding.js 的 OpenAI embedder 直接读库），getter 一抛错，整条
+        // `||` 的求值当场中断，右侧的 `attempts >= EMBED_READY_POLL_LIMIT` 永远轮
+        // 不到 —— stopEmbedReadyPolling() 不执行，定时器就活过 3s 上限，并以未捕获
+        // 异常的形式每 100ms 抛一次。实测（2026-10-14）：卸载路径 store.close() 之后
+        // 每次读 ready 都抛 "database is not open"，5s 内读 46 次，天花板 31 被直接
+        // 打穿，宿主事件循环因此永不排空。读不出来按「没就绪」处理，但上限照算。
+        const readReady = () => {
+          try {
+            return emb.ready === true;
+          } catch (err) {
+            if (!readyReadFailed) {
+              readyReadFailed = true; // 只报一次，别让 3s 上限变成 30 条刷屏
+              logger?.warn?.("embedder ready probe failed, treating it as not-ready:", err);
+            }
+            return false;
+          }
+        };
         embedReadyTimer = setInterval(() => {
           attempts++;
-          if (emb.ready === true || attempts >= EMBED_READY_POLL_LIMIT) {
+          const ready = readReady();
+          if (ready || attempts >= EMBED_READY_POLL_LIMIT) {
             stopEmbedReadyPolling();
-            if (emb.ready === true) flushEmbedPending();
+            if (ready) flushEmbedPending();
             else embedPending = []; // init never landed: drop the queue
           }
         }, EMBED_READY_POLL_MS);

package/src/session-usage.js

@@ -0,0 +1,350 @@
+/**
+ * 能力使用证据的**读侧**：从 DSH 会话日志里解析「哪个能力在什么时候被调用过」。
+ *
+ * 为什么单独一个文件：这份解析有两个已经踩过的坑，都属「静默少一大截」型——
+ *   · **zstd 是多帧的**：`zlib.zstdDecompressSync(buf)` 只返回**第一帧**，不报错、不警告。
+ *     实测一个 1.5 MB 的会话文件只解出 291 字节，99% 的内容没被扫到，于是得出
+ *     「零命中」的假结论。必须自己按 magic `28 b5 2f fd` 切帧逐帧解。
+ *   · **tool-call 的参数在 `arguments`，值是 JSON 字符串**（不是对象，也不是
+ *     `parameters`）：形如 `{"type":"tool-call","name":"skill","arguments":"{\"name\":\"agent-reach\"}"}`。
+ *     取错字段会得到 null，看着像「调用了但没记参数」。
+ * 把它们关在一个模块里，是为了让 `capabilities.js` 只负责「调用 + 投影」，不碰这些细节。
+ *
+ * **只读**：不解压到磁盘、不写任何文件、不改库。
+ *
+ * 与 `src/pipeline.js` 的 `deriveState` 同一套语汇：使用状态由**运行记录**推出来，
+ * 不由人写死——没记录就是 `candidate`（实话：不知道用过没有），有记录是 `trusted`，
+ * 久未用是 `stale`。
+ */
+import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import zlib from "node:zlib";
+
+/** zstd 帧头 magic。多帧文件里每帧都以此开头，切帧就靠它。 */
+const ZSTD_MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd]);
+
+/**
+ * 会话日志文件名前缀。
+ *
+ * **不是只认 `session.v4`** —— 本机实测同一会话树下并存三种格式：
+ *   · `session.v4.jsonl.zstd`（219 个）
+ *   · `session.v3.jsonl.zstd`（218 个）
+ *   · `session.jsonl.zstd`（72 个，无版本号的最早期形态）
+ * 只认 v4 会**静默漏掉一半以上的历史**（实测漏掉 50 次技能调用，其中 `euthyna` 44 次；
+ * `brainstorming` / `writing-plans` / `subagent-driven-development` 三个技能明明用过
+ * 却被报成 `candidate`）。所以这里只要求「文件名以 `session` 开头」——宁可多读几个
+ * 非会话文件（解析时自然会被 `tool-call` 过滤掉），也不要漏掉真实记录。
+ */
+const SESSION_FILE_PREFIX = "session";
+
+/** 单次扫描最多读多少个文件——目录膨胀时宁可报错，也不要把一次面板刷新变成全盘扫描。 */
+const MAX_SESSION_FILES = 2000;
+
+/** 判定 `stale` 的默认天数。与 pipeline.js 的 90 天同源：都是「久未使用」的经验阈值。 */
+export const STALE_AFTER_DAYS = 90;
+
+/**
+ * 使用状态**三值**。
+ *
+ * **这是对 `pipeline.js` 四态（`candidate`/`trusted`/`stale`/`refuted`）的有意收敛，
+ * 不是遗漏**：`refuted` 在工作流里的含义是「这一步被运行记录判定为不成立」，而能力
+ * 的「被使用」记录**推不出**任何等价结论——一个能力被调用过，只能说「用过」，不能
+ * 因此说它「已被推翻」。能力的弃用要另立判据（比如「用它之后任务失败了」），那是
+ * 另一件事，**不能从调用次数硬凑**。所以这里只保留能从运行记录直接推出的三态；
+ * 少了的那一态宁可不做，也不拿 `candidate` 或 `stale` 冒充。
+ */
+export const USAGE_STATES = ["candidate", "trusted", "stale"];
+
+/**
+ * 会话根目录。默认由 `DSH_HOME` 推导，**不写死本机路径**——仓库里出现盘符是红线。
+ * 传 `dshHome` 可覆盖（测试用临时目录，生产用环境变量）。
+ */
+export function resolveSessionDir({ dshHome = process.env.DSH_HOME || join(homedir(), ".dsh") } = {}) {
+  return join(String(dshHome), "sessions");
+}
+
+/**
+ * 逐帧解一个多帧 zstd buffer，**边解边回调**，不把全文拼成一个字符串。
+ *
+ * 用回调而不是返回字符串：实测一次读上百个会话文件会 OOM（`FATAL ERROR: Reached
+ * heap limit`）。逐帧交给回调，内存只保留一帧。
+ */
+/**
+ * 多帧 zstd 逐帧解压，**边解边回调**。
+ *
+ * 返回 `{ frames, failed, bytes }`——`failed` 是**解不出来**的帧数。
+ *
+ * **关于「残缺帧」的一个实测结论**：zstd 是流式格式，**尾部被截断的帧会解出「部分
+ * 文本」而不抛错**（实测截断到一半的帧解出 `"这一帧会被截"`）。我试过两种完整性判据
+ * 都不可靠：①「截掉末字节再解、比对是否相同」——对短截断失效；②流式 API 的
+ * `end` 事件——截断帧照样正常结束、不报错。Node 的 zstd 绑定没有暴露「还有多少输入
+ * 未被消费」。
+ *
+ * 所以**不猜帧的完整性**，改在**行这一层**兜底：残缺帧解出来的尾部一定是半行，而
+ * jsonl 的解析器本来就要求整行是合法 JSON —— 半行会 `JSON.parse` 失败被丢掉。
+ * 代价是：**一条调用记录若正好被截在中间，会被丢弃**（而不是被当成完整记录误用）。
+ * 这个取舍是明确的：**宁可少一条，不要错一条**。
+ *
+ * 另外，**只有最后一帧可能被截断**（中间帧的边界由下一个 magic 保证），所以
+ * `failed` 只在真的解不出来时增长，不把「末帧可能是半行」计进去——那样会天天报警。
+ */
+export function forEachFrame(buf, onText) {
+  let offset = 0;
+  let frames = 0;
+  let failed = 0;
+  while (offset < buf.length) {
+    const start = buf.indexOf(ZSTD_MAGIC, offset);
+    if (start === -1) break;
+    let end = buf.indexOf(ZSTD_MAGIC, start + 4);
+    if (end === -1) end = buf.length;
+    try {
+      onText(zlib.zstdDecompressSync(buf.subarray(start, end)).toString("utf8"));
+      frames += 1;
+    } catch {
+      // 帧头都坏了：计入 failed，继续后面的帧。
+      failed += 1;
+    }
+    offset = end;
+  }
+  return { frames, failed };
+}
+
+/**
+ * 递归找出所有会话日志文件。
+ *
+ * 返回 `{ files, unreadable, truncated }`——**目录读不动时必须留痕**。
+ *
+ * 为什么这是关键：早期版本用 `existsSync` 定 `present`、`readdirSync` 失败直接 `return`，
+ * 于是「目录存在但不可读（ACL 拒绝、权限不足）」与「目录存在且为空」产出**逐字段相同**
+ * 的读数（`present=true, scannedFiles=0, unreadable=[]`），清单上 175 条技能全 `candidate`。
+ * 那正是本仓库反复防的那类错：**读不到被显示成「读到但没有」**。所以 readdir 失败要
+ * 记进 `unreadable`，让上层能把它与「空目录」分辨开。
+ *
+ * `limit` 可注入（默认 `MAX_SESSION_FILES`）。**早期版本把上限写死在遍历里**，于是
+ * 调用方传 `maxFiles: 5000` 也只拿到 2000 个——上限在内层生效、外层无从知道，
+ * 又是「静默截断」。现在上限只在这里生效，且**超限时 `truncated` 为 true**。
+ */
+export function findSessionFiles(dir, { limit = MAX_SESSION_FILES } = {}) {
+  const cap = Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : MAX_SESSION_FILES;
+  const result = { files: [], unreadable: [], present: false, truncated: false };
+  if (!existsSync(dir)) return result;
+  result.present = true;
+  const walk = (current) => {
+    if (result.files.length >= cap) {
+      result.truncated = true;
+      return;
+    }
+    let entries;
+    try {
+      entries = readdirSync(current, { withFileTypes: true });
+    } catch (error) {
+      // 读不动就说出来——不静默 return（那会与「空目录」同形）。
+      result.unreadable.push({ dir: current, detail: `目录读失败：${error.message}` });
+      return;
+    }
+    for (const entry of entries) {
+      if (result.files.length >= cap) {
+        result.truncated = true;
+        return;
+      }
+      const full = join(current, entry.name);
+      // 符号链接要单独认：Dirent 对 symlink 的 isDirectory() 返回 false（踩过一次）。
+      let isDir = entry.isDirectory();
+      if (entry.isSymbolicLink()) {
+        try {
+          isDir = statSync(full).isDirectory();
+        } catch {
+          // 悬空链接：计入 unreadable（目标不可达也是「读不到」的一种）。
+          result.unreadable.push({ dir: full, detail: "符号链接目标不可达" });
+          continue;
+        }
+      }
+      if (isDir) walk(full);
+      else if (entry.name.startsWith(SESSION_FILE_PREFIX)) result.files.push(full);
+    }
+  };
+  walk(dir);
+  result.files.sort();
+  return result;
+}
+
+/**
+ * 从一行 jsonl 里抽出所有 tool-call。
+ *
+ * 返回 `{ name, args, turn, time }`——`args` 是**二次解析后的对象**，取不到就是 null
+ * （调用记录本身仍保留，只是参数缺失，这种要能看出来而不是丢掉整条）。
+ */
+export function toolCallsInLine(line) {
+  if (typeof line !== "string" || !line.includes('"tool-call"')) return [];
+  let obj;
+  try {
+    obj = JSON.parse(line);
+  } catch {
+    return [];
+  }
+  const content = obj?.data?.message?.content;
+  if (!Array.isArray(content)) return [];
+  const out = [];
+  for (const item of content) {
+    if (item?.type !== "tool-call" || typeof item.name !== "string") continue;
+    let args = null;
+    if (typeof item.arguments === "string") {
+      try {
+        args = JSON.parse(item.arguments);
+      } catch {
+        args = null;
+      }
+    } else if (item.arguments && typeof item.arguments === "object") {
+      args = item.arguments;
+    }
+    out.push({
+      name: item.name,
+      args,
+      turn: obj?.data?.turn ?? null,
+      time: Number.isFinite(obj?.time) ? obj.time : null
+    });
+  }
+  return out;
+}
+
+/**
+ * 一次调用对应哪个能力。三类能力的判定方式**故意不同**：
+ *   · `skill` 工具 → 参数里的 `name` 就是技能名（照宿主 `skill` 工具的契约）；
+ *   · MCP 工具 → 公共名形如 `mcp__<serverName>__<rawName>`，取中间那段为 server；
+ *   · 其余内置工具（read / pwsh 等）**不是能力清单里的东西**，返回 null 丢掉。
+ *
+ * 拿不到名字时返回 `{ kind, name: null }`，让上层能统计「对不上的条数」——
+ * 对不上是要报出来的事实，不是可以静默丢弃的噪音。
+ */
+export function identifyCapability(call) {
+  if (!call || typeof call.name !== "string") return null;
+  if (call.name === "skill") {
+    const name = call.args && typeof call.args.name === "string" ? call.args.name.trim() : "";
+    return { kind: "skill", name: name === "" ? null : name };
+  }
+  if (call.name.startsWith("mcp__")) {
+    const parts = call.name.split("__");
+    // mcp__<server>__<tool>：server 为空也算 MCP 调用，只是名字不可用。
+    const server = typeof parts[1] === "string" ? parts[1].trim() : "";
+    return { kind: "mcp", name: server === "" ? null : server, tool: parts.slice(2).join("__") || null };
+  }
+  return null;
+}
+
+/**
+ * 扫全部会话日志，产出「按能力聚合的使用记录」。
+ *
+ * 返回结构里的 `skills` / `mcp` 是 Map（能力名 → { uses, lastUsedAt, sessions }），
+ * 由上层投影成清单字段。`unmatched` 记对不上名字的调用数——如实报，不硬凑。
+ *
+ * `maxFiles` 现在**真的管用**（透传给 `findSessionFiles` 的 `limit`）：早期版本把上限
+ * 写死在遍历里，传 5000 也只拿到 2000 个且不报截断——调用方以为扫全了。
+ */
+export function collectUsage({ sessionDir = resolveSessionDir(), maxFiles = MAX_SESSION_FILES } = {}) {
+  const found = findSessionFiles(sessionDir, { limit: maxFiles });
+  // 透传后 found.files 已按上限截好，slice 只是防御（limit 非法时）。
+  const files = found.files.slice(0, maxFiles);
+  const result = {
+    dir: sessionDir,
+    // `present` = 目录在；`readable` = 目录真能列出来。**两者必须分开报**，
+    // 否则「不可读」与「空目录」在读数上同形（那正是本仓库反复防的那类错）。
+    present: found.present,
+    readable: found.present && found.unreadable.length === 0,
+    // 文件数被上限截断时要说出来，否则「只扫了一部分」看不出来。
+    // 两个来源：内层遍历到上限（found.truncated），或调用方给的 maxFiles 更小。
+    truncated: found.truncated === true || found.files.length > files.length,
+    totalFiles: found.files.length,
+    scannedFiles: 0,
+    frames: 0,
+    failedFrames: 0,
+    skillCalls: 0,
+    mcpCalls: 0,
+    unmatched: 0,
+    skills: new Map(),
+    mcp: new Map(),
+    // 目录读不动、悬空链接、单文件读失败都记在这里——**读不到要有痕**。
+    unreadable: [...found.unreadable]
+  };
+
+  const record = (map, name, time, sessionId) => {
+    const entry = map.get(name) || { uses: 0, lastUsedAt: null, sessions: new Set() };
+    entry.uses += 1;
+    if (Number.isFinite(time) && (entry.lastUsedAt === null || time > entry.lastUsedAt)) entry.lastUsedAt = time;
+    if (sessionId) entry.sessions.add(sessionId);
+    map.set(name, entry);
+  };
+
+  for (const file of files) {
+    let buf;
+    try {
+      buf = readFileSync(file);
+    } catch (error) {
+      result.unreadable.push({ file, detail: `读失败：${error.message}` });
+      continue;
+    }
+    result.scannedFiles += 1;
+    const sessionId = file.split(/[\\/]/).slice(-2, -1)[0] || null;
+    const stat = forEachFrame(buf, (text) => {
+      for (const line of text.split("\n")) {
+        if (!line.trim() || !line.includes('"tool-call"')) continue;
+        // time 在行的外层，toolCallsInLine 已带上；这里从整行再取一次 session 级信息。
+        for (const call of toolCallsInLine(line)) {
+          const identified = identifyCapability(call);
+          if (!identified) continue;
+          if (identified.name === null) {
+            result.unmatched += 1;
+            continue;
+          }
+          if (identified.kind === "skill") {
+            result.skillCalls += 1;
+            record(result.skills, identified.name, call.time, sessionId);
+          } else {
+            result.mcpCalls += 1;
+            // MCP 按 **server** 聚合（清单里的 MCP 条目是 server 粒度），不是按工具。
+            record(result.mcp, identified.name, call.time, sessionId);
+          }
+        }
+      }
+    });
+    result.frames += stat.frames;
+    result.failedFrames += stat.failed;
+    buf.fill(0);
+  }
+
+  return result;
+}
+
+/**
+ * 由使用记录推使用状态。**照 `pipeline.js` 的 `deriveState` 写**：
+ *   · 没有记录 → `candidate`（不知道用过没有，这是实话）；
+ *   · 有记录、最近一次在 `staleAfterDays` 天内 → `trusted`；
+ *   · 有记录但最近一次早于阈值 → `stale`。
+ *
+ * 保留期会限制这个判定的可靠度：会话日志被清理后，久未用的能力会**退化成 candidate**
+ * （看起来像从没用过）。所以「candidate」的含义是「本机现存日志里没有记录」，
+ * 而不是「从未使用」——这句话必须由上层写进输出，否则会被读错。
+ */
+export function deriveUsageState(entry, { now = Date.now(), staleAfterDays = STALE_AFTER_DAYS } = {}) {
+  if (!entry || !Number.isFinite(entry.uses) || entry.uses === 0) return "candidate";
+  if (Number.isFinite(entry.lastUsedAt)) {
+    const ageDays = (now - entry.lastUsedAt) / 86400000;
+    if (Number.isFinite(ageDays) && ageDays > staleAfterDays) return "stale";
+  }
+  return "trusted";
+}
+
+/** 把 Map 里的聚合记录投影成清单友好的纯数组（含状态），按使用次数降序。 */
+export function summarizeUsage(collection, { now = Date.now(), staleAfterDays = STALE_AFTER_DAYS } = {}) {
+  const toRows = (map) =>
+    [...map.entries()]
+      .map(([name, entry]) => ({
+        name,
+        uses: entry.uses,
+        lastUsedAt: Number.isFinite(entry.lastUsedAt) ? new Date(entry.lastUsedAt).toISOString() : null,
+        sessions: entry.sessions.size,
+        state: deriveUsageState(entry, { now, staleAfterDays })
+      }))
+      .sort((a, b) => b.uses - a.uses || a.name.localeCompare(b.name));
+  return { skills: toRows(collection.skills), mcp: toRows(collection.mcp) };
+}