sage-mem 0.9.17 → 0.9.18

package/README.md

@@ -182,6 +182,32 @@ SAGE_MEM_DIR=/path/to/your/memory
 
 - **摘要侧也有相关性门槛**：中文里「怎么」「什么」这类词元在大量 `description` 里都有，一句无关的「今天天气怎么样」曾靠一个「怎么」命中十几份记忆。门槛按**语料自身的 IDF 尺度**归一，实测真实目录里无关问题的候选数降到约七分之一；离线评测集上还不只是没退化、而是更好了（Recall@5 84%→87%、误注入 14%→5.6%）—— 被清掉的弱摘要候选原先在挤占名额
 - **意图识别绝不在四类显式请求上抑制重复**：「上次决定用 A 对吧」（核实）、「不用 A 了」（更正）、「之前为什么没选 A」（问依据）必须给原文；判不出来就不判，不猜
+
+### 长任务的接力棒：任务检查点
+
+宿主什么时候压缩上下文，插件控制不了 —— 所以**不承诺「压缩前保存」**。能做的是：如果
+`<状态根>/tasks/<任务 id>/WORKING.md` 存在，注入末尾会给一条短句柄，说清任务、revision
+与去哪读。**压缩后账本归零会连去重一起清掉**，句柄因此重新出现 —— 这就是恢复路径。
+
+任务 id 取 `SAGE_MEM_TASK_ID`（给跨会话的同一条任务用），否则用会话 id。**绝不用你的问题
+原文去决定读哪个目录。** 检查点里「已完成」的条目如果没有任何证据标记（路径、命令、测试结果），
+解析时会如实报出来 —— 格式完美、内容错误的交接材料仍然是错的。
+
+### 访问台账：三种「用过」分开记
+
+`<状态根>/access.json` 记三件事：
+
+| 字段 | 含义 |
+|---|---|
+| `injected` | 插件**被动**注入了这份记忆 |
+| `read` | 模型**主动**读了它（用内置 `read` / `grep` 翻记忆目录时会记上） |
+| `use` | 明确被采用的次数（自报） |
+
+分开记是因为这三件事的含义完全不同：**被注入**只说明插件觉得相关，**被主动读**只说明模型
+选了它，都不等于内容有用、更不等于内容正确。混成一个「热度」就再也分不开了。
+
+**这张台账目前只用于诊断与自动归档阈值，不参与检索排序。** 观测有已知盲区：`pwsh` 里
+`cat 某记忆` 认不出来，那就不认 —— 我们不会把「看不到」说成「没读过」。
 - **每条记忆的标题带新鲜度**：`（保存于 N 天前）`，**优先读 frontmatter 的 `updated:`，缺失才回落文件 mtime** —— 手写的时间戳是权威，文件系统时间会被复制 / 备份还原 / checkout 整批改掉。理由是陈旧记忆被当事实引用时，「引用」这个动作本身会让它显得更权威而不是更可疑，所以注入文本开头还带一节**引用纪律**（提到路径先确认存在、提到函数先 grep、要动手先核实）。它**独立成节**而不是一条 bullet：Claude Code 实测同一句话埋成 bullet 命中 0/3、独立成节 3/3
 - **`baseline: true` 的记忆每场会话第一步无条件注入**，最多 8 条——给「你是谁」「待办清单」这类每次开场都该在场的记忆用。多条 baseline 之间的先后由 `baselinePriority` 决定（数字越大越前，缺省 0），**不按文件名排**
 - 记忆目录读不到、权限错、frontmatter 格式坏，这些都**降级为不注入并写日志**，不会静默失效

package/lib/autodream/engine.js

@@ -37,7 +37,7 @@ import { auditMemoryDir } from '../autodream-audit.js'
 import { autodreamToolSchemas, createToolRunner } from '../autodream-tools.js'
 import { CONFIG_VERSION, DEFAULT_CONFIG, DEFAULT_TOKEN_BUDGET, FAILURE_BACKOFF_MS, FEATURE_DIR, LEGACY_SNAPSHOT_DIR, LEGACY_STATE_FILE, SCHEDULE_INTERVAL_MS, STARTUP_CHECK_DELAY_MS, STATE_DIR } from './config.js'
 import { countSessionsSince, newRunId, stampHuman } from './util.js'
-import { flushAccess, pickArchiveCandidates, readAccessLedger } from '../memory/access.js'
+import { flushAccess, ledgerFileFor, pickArchiveCandidates, readAccessLedger } from '../memory/access.js'
 import { archiveMemory } from '../memory/archive.js'
 import { scanMemoryFiles } from '../memory/scan.js'
 import { dirname, join } from 'node:path'
@@ -436,7 +436,7 @@ export class AutodreamEngine {
   async archivePolicyPass(cfg) {
     const requested = cfg.autoArchive === 'auto' ? 'auto' : cfg.autoArchive === 'off' ? 'off' : 'report'
     if (requested === 'off') return { mode: 'off', requested, candidates: [], archived: [], degraded: '' }
-    const [ledger, memoryFiles] = await Promise.all([readAccessLedger(), scanMemoryFiles(this.ctx, '')])
+    const [ledger, memoryFiles] = await Promise.all([readAccessLedger(ledgerFileFor(this.memoryDir)), scanMemoryFiles(this.ctx, '')])
     const candidates = pickArchiveCandidates(memoryFiles, ledger, {
       thresholds: {
         project: cfg.archiveAfterDaysProject,

package/lib/index.js

@@ -27,9 +27,11 @@ import { rankChunks } from './memory/search.js'
 import { renderStatusCard } from './memory/status.js'
 import { detectIntent } from './memory/intent.js'
 import { decideDelivery } from './memory/deliver.js'
+import { classifyToolExecution, accessEventKey, createDeduper } from './memory/observe.js'
+import { readCheckpoint } from './memory/checkpoint.js'
 import { createMemoryTools } from './tools/memory-tools.js'
 import { archiveMemory, restoreMemory } from './memory/archive.js'
-import { flushAccess, pickArchiveCandidates, readAccessLedger, recordAccess } from './memory/access.js'
+import { flushAccess, pickArchiveCandidates, readAccessLedger, recordAccess, recordRead } from './memory/access.js'
 import { warnLog, writeFileAtomic } from './memory/util.js'
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
 import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises'
@@ -238,6 +240,37 @@ export class MemoryGateway extends TypertRemoteService {
       warnLog(ctx, `检索工具挂载失败（记忆注入不受影响）：${err?.message ?? err}`)
     }
 
+    // ── 观测：模型自己翻了记忆目录 ──
+    //
+    // 宿主的 `tools/result` 把**每一次**工具调用的 `exec`（含 name / arguments）交给我们，
+    // 于是「模型用内置 read/grep 读了哪份记忆」第一次变得可观测 —— 此前台账只记得下
+    // 「插件注入了什么」，记不下「模型主动翻了什么」。
+    //
+    // 三条纪律：
+    //   1. **只记能可靠判定的**（`observe.js` 认 read/grep/glob 的路径参数；`pwsh` 一律不认，
+    //      那是**已知观测盲区** —— 不许把「看不到」说成「没读」）。
+    //   2. **按 session × 文件去重**：翻页（read 的 offset 不同）不刷计数，那是同一个动作。
+    //   3. **失败绝不影响任何东西**：观测是副产品，它的问题不许冒泡到工具调用链上。
+    const observedReads = createDeduper()
+    try {
+      ctx.on('tools/result', (exec) => {
+        try {
+          const cls = classifyToolExecution(exec?.name, exec?.arguments, MEMORY_DIR)
+          if (cls.kind !== 'active_read' || !cls.file) return
+          const key = accessEventKey({
+            sessionId: exec?.agent?.id ?? '',
+            file: cls.file,
+            // revision 要读盘才算得出，这里拿不到 —— 所以去重粒度是「session × 文件」。
+            // 写明这条口径，免得以后有人以为它按内容去重。
+            revision: '',
+            kind: cls.kind,
+          })
+          if (!key || !observedReads.shouldCount(key)) return
+          recordRead(cls.file, '')
+        } catch { /* 观测失败静默：它不该有任何存在感 */ }
+      })
+    } catch { /* 老宿主没有这个事件：不影响注入 */ }
+
     // 同一轮对话里问题不变、注入内容也不变，但 DSH 每一步都会往 session 追加
     // 一条 context 消息——不去重的话同一份记忆会被反复追加，撑爆上下文。
     const recallCache = new Map()
@@ -340,6 +373,11 @@ export class MemoryGateway extends TypertRemoteService {
         // 检索由这份签名保证同一问题不重复追加，两条线互不干扰。
         const relevant = text && text.length >= 2 ? selectRelevant(text, files) : []
 
+        // ── 意图：先判，因为它要影响下面正文检索的**门槛松紧** ──
+        // 用户是不是在问自己的历史（上次 / 之前 / 更正 / 问依据 / 继续）。
+        // 判不出来就是 `none`，不猜 —— 误判的代价是把不该抑制的正文抑制掉。
+        const intentInfo = text ? detectIntent(text) : { intent: 'none', historyDependent: false, suppressible: true }
+
         // ── 正文检索 ──
         // 摘要（description + aliases + 文件名）是最省的检索面，代价是**正文里的东西天生检索不到**。
         // 这里用它做两件事：
@@ -349,8 +387,17 @@ export class MemoryGateway extends TypertRemoteService {
         //
         // query 短于 4 个字符不做正文匹配：`继续` 这种两个字的问题拿去匹配正文，
         // 命中的全是「继续」这个词本身，与用户问什么毫无关系。
+        //
+        // **门槛按意图放宽**：默认要求「连续命中 ≥ 2 个词元」（那条防的是跨词边界的假词元，
+        // 见 search.js）。代价是整句只对上一个两字专名时会被拦下 —— 那是 0.9.16 有意付的。
+        // 但用户**明确在问自己的历史**时，宁可多给一条也不该让他拿不到依据：这类问题的
+        // 代价不对称（少给 = 答错，多给 = 多花一点上下文）。所以这时把 `minRun` 放到 1。
         const bodyRanked = typeof text === 'string' && text.length >= 4
-          ? rankChunks(text, files, { limit: MAX_RESULTS, perFile: 1 })
+          ? rankChunks(text, files, {
+              limit: MAX_RESULTS,
+              perFile: 1,
+              ...(intentInfo.historyDependent ? { minEvidence: { minRun: 1 } } : {}),
+            })
           : []
         const bestChunk = new Map()
         for (const h of bodyRanked) if (!bestChunk.has(h.file)) bestChunk.set(h.file, h.chunk)
@@ -403,9 +450,6 @@ export class MemoryGateway extends TypertRemoteService {
         let cardSig = carried?.cardSig ?? ''
         const nowMs = Date.now()
 
-        // 用户这句话是不是在问自己的历史 —— 展示层与状态卡都要用它，所以在两处之前算一次。
-        const intentInfo = text ? detectIntent(text) : { intent: 'none', historyDependent: false, suppressible: true }
-
         // ── 渲染候选，然后交给展示层决定「给正文 / 给指针 / 不给」──
         // 两件事分开做：这一段只负责「每条候选长什么样」，`decideDelivery` 负责
         // 「在预算内该给哪几条、为什么」。混在一起写就是上一版的样子 —— 预算、渲染、
@@ -491,8 +535,23 @@ export class MemoryGateway extends TypertRemoteService {
         // 后者是计划里点名的一条：没有历史依赖时不要插「你可能遗漏记忆」，否则提示
         // 每轮都出现，等真有缺口时它已经被当噪音忽略了。
         const gapExists = unread > 0 || skippedForBudget > 0
-        const wantCard = gapExists || intentInfo.historyDependent
-        const cardText = wantCard
+
+        // ── 任务检查点：压缩后的恢复入口 ──
+        // 宿主**什么时候**压缩上下文，插件控制不了 —— 所以这里**不承诺「压缩前保存」**，
+        // 只保证「存在检查点就给一条短句柄」。压缩后两本账与卡的签名会一起归零，
+        // 句柄因此会重新出现，这就是恢复路径（而不是靠某个压缩前钩子）。
+        //
+        // 任务 id：`SAGE_MEM_TASK_ID` 优先（给「跨会话的同一条任务」用），否则用 session id。
+        // **绝不用查询文本自定作用域** —— 那句话是模型或用户写的，不该决定去读哪个目录。
+        const taskId = process.env.SAGE_MEM_TASK_ID || session.id || ''
+        let checkpointLine = ''
+        try {
+          const cp = taskId ? await readCheckpoint(taskId, { stateRoot: STATE_ROOT }) : null
+          if (cp?.ok && cp.handle) checkpointLine = cp.handle
+        } catch { /* 读不到检查点就当没有：它是可选的接力棒，不是必需件 */ }
+
+        const wantCard = gapExists || intentInfo.historyDependent || !!checkpointLine
+        const cardBody = wantCard
           ? renderStatusCard({
               scope: bodySearched ? 'all' : 'summary',
               scanned: files.length,
@@ -505,6 +564,8 @@ export class MemoryGateway extends TypertRemoteService {
               memoryDir: MEMORY_DIR,
             })
           : ''
+        // 句柄与卡**共用卡池**：它是同一个通道里的另一句提示，不该另开一份额度。
+        const cardText = [cardBody, checkpointLine].filter(Boolean).join('\n')
         let cardPart = ''
         // 卡按**内容签名**去重：签名没变就不重复发。否则每一步都追加一张一模一样的卡，
         // 而每张卡都是落到会话里的持久消息 —— 那不叫提示，那叫刷屏。

package/lib/memory/access.js

@@ -21,9 +21,58 @@ import { mkdir, readFile, readdir } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { nameKey } from './naming.js'
 
-/** 台账文件：状态根下，与记忆文件分开。 */
+/** 台账文件：状态根下，与记忆文件分开。**用默认记忆目录时**就是它。 */
 export const ACCESS_LEDGER_FILE = join(STATE_ROOT, 'access.json')
 
+/**
+ * 某个记忆目录**对应**的台账文件路径。
+ *
+ * ⚠️ 为什么不能写死成模块常量：`flushAccess(memoryDir)` 是「一边按那个目录回收死键、
+ * 一边把结果写回台账」。若台账路径固定，就会出现**扫描 A 目录、把结果写进 B 台账** ——
+ * A 里不存在的名字在 B 台账里全被判成死键删掉。
+ *
+ * 这不是假想：2026-10-15 实测到一个用**临时**记忆目录跑的测试，因此把用户的**真实**台账
+ * 冲成了它的夹具文件名（`access.json` 从百来条真实记忆变成两条 `a.md` / `b.md`），
+ * 而自动归档阈值唯一的数据来源就是这份台账。
+ *
+ * 用默认目录时仍走 `STATE_ROOT`（尊重 `SAGE_MEM_STATE_DIR` 覆写）；传了别的目录，
+ * 台账就跟着那个目录走（`<它的上一层>/.sage-mem/access.json`）。
+ */
+export function ledgerFileFor(memoryDir = MEMORY_DIR) {
+  if (!memoryDir || memoryDir === MEMORY_DIR) return ACCESS_LEDGER_FILE
+  return join(dirname(memoryDir), '.sage-mem', 'access.json')
+}
+
+/** 落盘格式版本。v1 是 `{ "文件.md": 时间戳 }`；v2 是 `{ v:2, files: { "文件.md": {...} } }`。 */
+export const ACCESS_SCHEMA_VERSION = 2
+
+/**
+ * 台账条目归一：**v1 的裸数字与 v2 的对象都要吃**。
+ *
+ * 为什么读端必须兼容两代：台账是磁盘上的既有数据，用户升级插件时它就在那儿。
+ * 「只认新格式」等于把老用户的台账当成损坏数据丢掉 —— 而它是自动归档阈值唯一的数据源。
+ * 旧格式的裸数字语义是「最近一次被注入」，正好对应 v2 的 `injected`。
+ */
+export function ledgerEntry(value) {
+  if (Number.isFinite(value)) return { injected: value, read: 0, use: 0, readRev: '' }
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return {
+      injected: Number.isFinite(value.injected) ? value.injected : 0,
+      // `read` / `use` / `readRev` 是 0.9.18 才有的字段：**只记不参与排序**（决定 D3）。
+      read: Number.isFinite(value.read) ? value.read : 0,
+      use: Number.isFinite(value.use) ? value.use : 0,
+      readRev: typeof value.readRev === 'string' ? value.readRev : '',
+    }
+  }
+  return { injected: 0, read: 0, use: 0, readRev: '' }
+}
+
+/** 条目里「最近一次被注入」的时间戳（0 = 没有）。`idleDays` 与归档候选都走它。 */
+export function injectedAt(value) {
+  const e = ledgerEntry(value)
+  return e.injected > 0 ? e.injected : null
+}
+
 /** 落盘节流：内存先累计，最多每 30 秒写一次盘。 */
 export const ACCESS_FLUSH_INTERVAL_MS = 30 * 1000
 
@@ -46,11 +95,35 @@ export const NEVER_ARCHIVE_TYPES = new Set(['feedback'])
  */
 const enqueueFlush = createWriteQueue()
 
-/** 内存累计（尚未落盘）：文件名 → 时间戳，同名取最新。 */
+/** 内存累计（尚未落盘）：文件名 → 各字段的增量（见 `record` 的合并语义）。 */
 let pending = new Map()
 let flushTimer = null
 let lastFlushAt = 0
 
+/**
+ * 把一次观测并进内存增量表。
+ *
+ * 为什么是「增量」而不是「整条时间戳」：v2 有四个字段，同一批里可能先记注入、再记读取。
+ * 直接 `set(name, at)` 会让后写的把先写的**冲掉** —— 那正是旧版台账丢计时的那类问题。
+ *
+ * 各字段的合并语义**不一样**，写错就会丢数据：
+ *   - `injected` / `read`：取**较晚**的（它们是「最近一次」）；
+ *   - `use`：**累加**（它是「采用了几次」，不是时间戳）；
+ *   - `readRev`：跟着 `read` 走（谁把 `read` 推新，就用谁那份 revision）。
+ */
+function record(name, patch) {
+  if (typeof name !== 'string' || !name) return
+  const cur = pending.get(name) ?? {}
+  const read = Math.max(cur.read ?? 0, patch.read ?? 0)
+  pending.set(name, {
+    injected: Math.max(cur.injected ?? 0, patch.injected ?? 0),
+    read,
+    readRev: read > 0 && read === (patch.read ?? 0) && patch.readRev ? patch.readRev : (cur.readRev ?? ''),
+    use: (cur.use ?? 0) + (patch.use ?? 0),
+  })
+  scheduleFlush()
+}
+
 /**
  * 记一次「这些文件真的被注入了」。
  *
@@ -58,10 +131,22 @@ let lastFlushAt = 0
  * **同步、绝不抛**：台账是观测数据，它的问题不许升级成「记忆不再注入」。
  */
 export function recordAccess(names, at = Date.now()) {
-  for (const n of names ?? []) {
-    if (typeof n === 'string' && n) pending.set(n, at)
-  }
-  scheduleFlush()
+  for (const n of names ?? []) record(n, { injected: at })
+}
+
+/**
+ * 记一次「模型**主动**读了这份记忆」。
+ *
+ * 与 `recordAccess`（被动注入）**分开记**，是这个版本的重点：主动读取只说明模型**选了**它，
+ * 不等于内容有用、更不等于内容正确。两者混成一个「热度」就再也分不开了（决定 D3 的另一半）。
+ */
+export function recordRead(name, revision, at = Date.now()) {
+  record(name, { read: at, readRev: typeof revision === 'string' ? revision : '' })
+}
+
+/** 记一次「明确采用」的增量。自报数据，**只记不参与排序**。 */
+export function recordUse(name) {
+  record(name, { use: 1 })
 }
 
 function scheduleFlush() {
@@ -75,14 +160,26 @@ function scheduleFlush() {
   if (typeof flushTimer.unref === 'function') flushTimer.unref()
 }
 
-/** 读盘上的台账。读不到 / JSON 坏 / 不是对象 / 值不是有限数 → 一律当空台账。 */
-export async function readAccessLedger() {
+/**
+ * 读盘上的台账，**归一成一种形状**：`{ 文件名 → {injected, read, use, readRev} }`。
+ *
+ * 读不到 / JSON 坏 / 不是对象 / 两代格式都不是 → 一律当空台账（降级成「不知道」，
+ * 而不是把已有数据判成损坏丢掉 —— 它是自动归档阈值唯一的数据源）。
+ * v1 的裸数字（= 被注入时间）由 `ledgerEntry` 升成 v2 条目，调用方不必分代。
+ */
+export async function readAccessLedger(file = ACCESS_LEDGER_FILE) {
   try {
-    const parsed = JSON.parse(await readFile(ACCESS_LEDGER_FILE, 'utf8'))
+    const parsed = JSON.parse(await readFile(file, 'utf8'))
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {}
+    // v2 = `{ v:2, files:{…} }`；v1 = 裸映射 `{ "文件.md": 时间戳 }`。
+    const src = parsed.v === ACCESS_SCHEMA_VERSION && parsed.files && typeof parsed.files === 'object' && !Array.isArray(parsed.files)
+      ? parsed.files
+      : parsed
     const out = {}
-    for (const [k, v] of Object.entries(parsed)) {
-      if (typeof k === 'string' && Number.isFinite(v)) out[k] = v
+    for (const [k, v] of Object.entries(src)) {
+      if (typeof k !== 'string' || !k) continue
+      if (!Number.isFinite(v) && !(v && typeof v === 'object' && !Array.isArray(v))) continue
+      out[k] = ledgerEntry(v)
     }
     return out
   } catch {
@@ -154,9 +251,20 @@ async function flushAccessLocked(memoryDir) {
   const batch = pending
   pending = new Map()
   try {
-    const onDisk = await readAccessLedger()
-    for (const [name, at] of batch) {
-      if (!Number.isFinite(onDisk[name]) || at > onDisk[name]) onDisk[name] = at
+    // 台账必须与**这次回收所依据的那个目录**配套（见 ledgerFileFor 的注释）。
+    const file = ledgerFileFor(memoryDir)
+    const onDisk = await readAccessLedger(file)
+    // 逐字段合并（`readAccessLedger` 已经归一成 v2 条目，不用再分代）。
+    // 语义与内存里的 `record` 一致：时间戳取较晚、`use` 累加、`readRev` 跟 `read` 走。
+    for (const [name, patch] of batch) {
+      const cur = onDisk[name] ?? { injected: 0, read: 0, use: 0, readRev: '' }
+      const read = Math.max(cur.read ?? 0, patch.read ?? 0)
+      onDisk[name] = {
+        injected: Math.max(cur.injected ?? 0, patch.injected ?? 0),
+        read,
+        readRev: read > 0 && read === (patch.read ?? 0) && patch.readRev ? patch.readRev : (cur.readRev ?? ''),
+        use: (cur.use ?? 0) + (patch.use ?? 0),
+      }
     }
     const alive = await currentMemoryNames(memoryDir)
     if (alive) {
@@ -166,12 +274,23 @@ async function flushAccessLocked(memoryDir) {
     }
     // 状态目录是插件自己的地盘，缺了可以建（autodream 的配置也存在这儿）。
     // 建不出来（只读、父路径不是目录）就走 catch 静默降级。
-    await mkdir(dirname(ACCESS_LEDGER_FILE), { recursive: true })
-    await writeFileAtomic(ACCESS_LEDGER_FILE, JSON.stringify(onDisk, null, 2))
+    await mkdir(dirname(file), { recursive: true })
+    // 落盘一律写 v2（哪怕读进来的是 v1）：老格式只在读端兼容，写端不扩散。
+    await writeFileAtomic(file, JSON.stringify({ v: ACCESS_SCHEMA_VERSION, files: onDisk }, null, 2))
     lastFlushAt = Date.now()
     return { ok: true, written: batch.size, reclaimed: alive ? true : false }
   } catch (err) {
-    for (const [name, at] of batch) if (!pending.has(name)) pending.set(name, at)
+    // 放回内存时**逐字段并回去**，不能整条覆盖 —— 否则失败重试会把期间新攒的字段冲掉。
+    for (const [name, patch] of batch) {
+      const cur = pending.get(name) ?? {}
+      const read = Math.max(cur.read ?? 0, patch.read ?? 0)
+      pending.set(name, {
+        injected: Math.max(cur.injected ?? 0, patch.injected ?? 0),
+        read,
+        readRev: read > 0 && read === (patch.read ?? 0) && patch.readRev ? patch.readRev : (cur.readRev ?? ''),
+        use: (cur.use ?? 0) + (patch.use ?? 0),
+      })
+    }
     // 静默降级：注入是插件最核心的事，台账写不进去不许把它拖下水。开了 DEBUG 才出声。
     if (DEBUG) console.warn(`[sage-mem][debug] access ledger flush failed: ${err?.message ?? err}`)
     return { ok: false, error: err?.message ?? String(err) }
@@ -199,7 +318,9 @@ export function fileType(f) {
  * 都会把它整批改掉。
  */
 export function idleDays(f, ledger = {}, now = Date.now()) {
-  const seen = ledger?.[f?.file]
+  // 走 `injectedAt` 而不是直接读值：手写的 v1 台账（裸数字）与 v2 条目都能收，
+  // 调用方不必分代 —— 归档候选的计算不该因为台账升了一代就整体失效。
+  const seen = injectedAt(ledger?.[f?.file])
   const fromMeta = Date.parse(f?.updated || '')
   const base = Number.isFinite(seen)
     ? seen

package/lib/memory/checkpoint.js

@@ -0,0 +1,546 @@
+/**
+ * sage-mem 记忆层 —— 任务检查点（`<状态根>/tasks/<taskId>/WORKING.md`）。
+ *
+ * 为什么要有这一层：宿主什么时候压缩上下文，插件说了不算 —— 所以**不能承诺
+ * 「压缩前一定保存」**。能做的只有两件事：任务走到里程碑时把状态写下来，
+ * 压缩之后再用一个短句柄把它读回来。检查点与长期记忆刻意分开：长期记忆答
+ * 「我记住的事」，检查点答「这件任务走到哪了」，两者的生命周期、检索方式、
+ * 失效条件都不一样，混在一起会让两边都不可信。
+ *
+ * 这个模块存在的理由**不是格式检查**：固定标题 + 最小长度只能验证格式，而一份格式完美、
+ * 内容错误的交接材料仍然是错的。所以 `parseCheckpoint` 除了报缺节，还报
+ * `claimsDoneWithoutEvidence` —— 「已完成」里没有任何证据标记的条目。判据的取向是刻意
+ * 严格的：**「测试过了」不是证据，「结果：12 passed, 0 failed」才是**。没有证据，
+ * 不许把「准备做」写成「已经完成」。
+ *
+ * 并发：本模块**不实现锁**。同一个 taskId 的并发写由调用方串行（进程内用 `util.js` 的
+ * `createWriteQueue`，跨进程本模块明确不管）—— 本模块只负责把每一份写原子化。
+ */
+
+import { mkdir, readFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { STATE_ROOT } from './config.js'
+import { writeFileAtomic } from './util.js'
+
+/** 检查点都放在状态根的这个子目录下，一个任务一个目录。 */
+export const TASKS_DIR_NAME = 'tasks'
+
+/** 检查点文件名。固定不变，短句柄里要引用它。 */
+export const CHECKPOINT_FILE_NAME = 'WORKING.md'
+
+/**
+ * 单份检查点的体积上限（字节）。
+ *
+ * 与记忆的 512 KB 上限分开：检查点是**要反复注入**的东西，一份 64 KB 的交接材料
+ * 等于把上下文又用掉一大块，那正好抵消了压缩腾出来的空间。到 64 KB 说明写成了流水账，
+ * 该拆成多份（或把稳定结论移进长期记忆）。
+ */
+export const CHECKPOINT_MAX_BYTES = 64 * 1024
+
+/** 必需的节标题（顺序即模板顺序）。 */
+export const CHECKPOINT_SECTIONS = Object.freeze([
+  '目标与约束',
+  '已完成与证据',
+  '未完成',
+  '关键决定',
+  '记忆引用',
+  '待核实',
+])
+
+/**
+ * 缺字段的占位文本。
+ *
+ * 为什么用占位符而不是空行：空行在 markdown 里与排版空白没有区别，「这里少东西」这件事
+ * 在渲染结果里看不见；而且 `parseCheckpoint` 需要能区分「有标题」与「有内容」——
+ * 占位符是「有标题、没内容」在文本里的可判定形态。
+ */
+const PLACEHOLDER = '（待补）'
+
+/**
+ * 任务 id 允许的字符集：单段、`[A-Za-z0-9._-]`、1..64 字符。
+ *
+ * **刻意不含** `/`、`\`、`:`：三个都是路径语义的元字符（`:` 在 NTFS 上是交替数据流的分隔符）。
+ * 判定走纯字符类、**不走 `path.basename`** —— `\` 在 Windows 是分隔符、在 Linux 只是普通字符，
+ * 用平台 API 判会得出「同一份输入在两个平台上合法性相反」的结论（本仓库刚被 Linux CI 抓过
+ * 同类缺陷）。这里的判据在两个平台上逐字一致。
+ */
+const TASK_ID_RE = /^[A-Za-z0-9._-]{1,64}$/
+
+/**
+ * Windows 保留设备名。在这个平台上 `tasks/CON` 这类目录**建不出来**（报错或行为未定义），
+ * 而 Linux 上完全正常 —— 同一份状态目录同步过去就会「在那边能写、在这边写不了」。
+ */
+const WINDOWS_RESERVED = new Set([
+  'con', 'prn', 'aux', 'nul',
+  ...Array.from({ length: 9 }, (_, i) => `com${i + 1}`),
+  ...Array.from({ length: 9 }, (_, i) => `lpt${i + 1}`),
+])
+
+/**
+ * 任务 id 归一：合法原样返回，非法返回 null。
+ *
+ * 只收字符串，也不 trim：路径两端的空格在 Windows 上会被静默裁掉、在 Linux 上不会，
+ * 「帮忙归一化」本身就会造出两个平台指向不同文件的输入 —— 那正是要防的东西。
+ */
+export function normalizeTaskId(raw) {
+  if (typeof raw !== 'string') return null
+  if (!TASK_ID_RE.test(raw)) return null
+  // `.` / `..` 单看是合法的一段字符，但 join 会把它们折掉：`..` 让路径跳出 tasks 目录、
+  // 落到状态根上（`<状态根>/WORKING.md`）。「字符合法、语义是穿越」的输入必须单独拒。
+  if (/^\.+$/.test(raw)) return null
+  // 尾随点在 Windows 上被静默吃掉（`a.` 与 `a` 是**同一个**目录项），Linux 上是两个不同目录。
+  // 「同一个 id 在两个平台指向不同文件夹」与本仓库刚修掉的那类平台差异同源，所以无条件拒。
+  if (raw.endsWith('.')) return null
+  // Windows 保留设备名同理（见上）：那个平台上建不出来，Linux 上可以。
+  if (WINDOWS_RESERVED.has(raw.split('.')[0].toLowerCase())) return null
+  return raw
+}
+
+/** stateRoot 的归一：非空字符串才用，否则回落 config.js 的 STATE_ROOT。 */
+function rootOf(stateRoot) {
+  return typeof stateRoot === 'string' && stateRoot !== '' ? stateRoot : STATE_ROOT
+}
+
+/**
+ * 检查点文件路径；taskId 非法返回 null（调用方据此在写之前就拦住，而不是等 IO 报错）。
+ */
+export function checkpointPathFor(taskId, stateRoot) {
+  const id = normalizeTaskId(taskId)
+  if (id === null) return null
+  return join(rootOf(stateRoot), TASKS_DIR_NAME, id, CHECKPOINT_FILE_NAME)
+}
+
+/** 缺的字段渲染成「（待补）」而不是空行。 */
+function orPlaceholder(value) {
+  const s = value === undefined || value === null ? '' : String(value).trim()
+  return s === '' ? PLACEHOLDER : s
+}
+
+/** 列表字段渲染成 bullet；空列表给一条占位 bullet（保证节里不是空的）。 */
+function bulletBlock(list) {
+  const items = (Array.isArray(list) ? list : list === undefined || list === null ? [] : [list])
+    .map((x) => String(x ?? '').trim())
+    .filter((x) => x !== '')
+  if (items.length === 0) return `- ${PLACEHOLDER}`
+  return items.map((x) => `- ${x}`).join('\n')
+}
+
+/**
+ * 渲染一份检查点（模板）。字段都可以缺，缺的渲染成「（待补）」。
+ *
+ * 刻意**不做校验**：渲染是给人补写的起点，格式问题由 `parseCheckpoint` 在读的那一端报出，
+ * 这样「写进去」和「读回来判它」是两条独立的路径，不会互相掩盖。
+ *
+ * @param {{taskId?, project?, revision?, goal?, constraints?, done?, todo?, decisions?, refs?, toVerify?}} input
+ */
+export function renderCheckpoint(input) {
+  const src = input && typeof input === 'object' ? input : {}
+  const taskId = orPlaceholder(src.taskId)
+  const revision = Number.isInteger(src.revision) && src.revision >= 0 ? src.revision : 0
+  const S = CHECKPOINT_SECTIONS
+  const lines = [
+    `# 任务检查点 ${taskId}`,
+    '',
+    `- 任务：${taskId}`,
+    `- 项目：${orPlaceholder(src.project)}`,
+    `- revision：${revision}`,
+    '',
+    `## ${S[0]}`,
+    '',
+    `目标：${orPlaceholder(src.goal)}`,
+    '',
+    '约束：',
+    bulletBlock(src.constraints),
+    '',
+    `## ${S[1]}`,
+    '',
+    bulletBlock(src.done),
+    '',
+    `## ${S[2]}`,
+    '',
+    bulletBlock(src.todo),
+    '',
+    `## ${S[3]}`,
+    '',
+    bulletBlock(src.decisions),
+    '',
+    `## ${S[4]}`,
+    '',
+    bulletBlock(src.refs),
+    '',
+    `## ${S[5]}`,
+    '',
+    bulletBlock(src.toVerify),
+    '',
+  ]
+  return lines.join('\n')
+}
+
+/**
+ * 「证据标记」数据表 —— **数据而不是 if 链**，因为面板与文档要能展示「凭什么算证据」，
+ * 断言也要能逐条核对它。
+ *
+ * 取证的取向：一条「已完成」条目必须**指向一个可以去核对的东西**（命令、路径、行号、
+ * 测试结果、提交哈希、外部链接、带单位的测量值）。所以刻意**不**把「测试过了」「已验证」
+ * 这类**关于测试的说法**当证据 —— 那正是这个模块要抓的谎报形态：它没有让任何人能去核对。
+ */
+export const EVIDENCE_MARKERS = Object.freeze([
+  Object.freeze({
+    id: 'code_span',
+    label: '反引号包裹的命令 / 路径 / 标识符',
+    pattern: /`[^`\n]+`/,
+  }),
+  Object.freeze({
+    id: 'path_with_dir',
+    label: '带目录成分且带扩展名的路径',
+    pattern: /\b[\w-]+(?:\/[\w.-]+)+\.[A-Za-z]{1,6}\b/,
+  }),
+  Object.freeze({
+    id: 'file_with_ext',
+    label: '带扩展名的文件名（可去核对的东西）',
+    pattern: /[\w-]+\.(?:md|mjs|cjs|js|json|jsonl|yml|yaml|toml|ts|py|ps1|sh|txt|log)\b/i,
+  }),
+  Object.freeze({
+    id: 'line_ref',
+    label: '文件:行号（精确到行的定位）',
+    pattern: /(?:[\w-]+\/[\w./-]*|\b[\w-]+\.[A-Za-z0-9]+):\d+(?:-\d+)?/,
+  }),
+  Object.freeze({
+    id: 'test_result',
+    label: '测试 / 断言的具体结果（带数字、PASS/FAIL 或退出码）',
+    pattern:
+      /\b\d+\s*(?:passed|failed)\b|\b(?:PASS|FAIL)\b|\bexit\s*code\s*[:：]?\s*\d|\d+\s*(?:个|项|条)?(?:断言|用例|测试)?\s*通过|退出码\s*[:：]?\s*\d|结果\s*[:：]\s*\d/,
+  }),
+  Object.freeze({
+    id: 'commit_ref',
+    label: 'commit / revision / sha256 后跟具体值',
+    pattern: /(?:\bcommit\b|\brevision\b|\bsha256\b)[\s:：]*[0-9a-z]/i,
+  }),
+  Object.freeze({
+    id: 'hex_ref',
+    label: '看起来是提交哈希的十六进制串（含字母、至少 7 位）',
+    pattern: /\b(?=[0-9a-f]*[a-f])[0-9a-f]{7,40}\b/i,
+  }),
+  Object.freeze({
+    id: 'link',
+    label: '可核对的外部链接',
+    pattern: /https?:\/\/\S+/,
+  }),
+  Object.freeze({
+    id: 'measurement',
+    label: '带单位的具体测量值',
+    pattern: /[：:]\s*\d+(?:\.\d+)?\s*(?:字节|KB|MB|GB|ms|毫秒|秒|条|项|处|个)/,
+  }),
+])
+
+/** 一条条目里有没有**可以去核对**的东西。任一标记命中即算有。 */
+export function hasEvidence(item) {
+  const s = String(item ?? '')
+  return EVIDENCE_MARKERS.some((m) => m.pattern.test(s))
+}
+
+/** 子标签行（`目标：` / `约束：`）：它们只是排版，不是内容。 */
+const SUB_LABEL_RE = /^(?:目标|约束|限制|备注)\s*[:：]?\s*$/
+
+/**
+ * 两个有语义的节名：解析时按**名字**取，不用数组下标 —— 顺序虽然冻结，名字更经得起改。
+ * 下标只在渲染模板（顺序即模板顺序）里用。
+ */
+const DONE_SECTION = '已完成与证据'
+const TODO_SECTION = '未完成'
+
+/**
+ * 节内容的「实义行」：剥掉列表标记与子标签，再滤掉空行与占位符。
+ *
+ * 这是「有标题 ≠ 有内容」的落点：一个节只要还有一条实义行才算存在；只有一个标题、
+ * 或者标题下全是「（待补）」，都算缺。
+ */
+function significantLines(text) {
+  return String(text ?? '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .map((line) => line.replace(/^[-*+]\s+/, '').replace(/^\d+[.)]\s+/, '').trim())
+    .map((line) => line.replace(/^(?:目标|约束|限制|备注)\s*[:：]\s*/, '').trim())
+    .filter((line) => line !== '' && line !== PLACEHOLDER && !SUB_LABEL_RE.test(line))
+}
+
+/**
+ * 把节内容切成条目：bullet（`-` / `*` / `1.`）各算一条，**不以 bullet 开头的行并入上一条**
+ * （同一件事的证据常常写在换行的续行里，切开会把证据判丢）。节内的小标题不算条目。
+ */
+function itemsOf(text) {
+  const items = []
+  for (const raw of String(text ?? '').split(/\r?\n/)) {
+    const line = raw.trim()
+    if (line === '' || /^#{1,6}\s/.test(line)) continue
+    const bullet = line.match(/^(?:[-*+]|\d+[.)])\s+(.*)$/)
+    if (bullet) {
+      items.push(bullet[1].trim())
+      continue
+    }
+    if (items.length === 0) items.push(line)
+    else items[items.length - 1] = `${items[items.length - 1]} ${line}`.trim()
+  }
+  return items.filter((item) => item !== '' && item !== PLACEHOLDER)
+}
+
+/** 「没有剩余工作」的声明：它不是下一件事。只认这几种明确的收尾说法，不猜别的。 */
+function isNoWork(item) {
+  const s = String(item ?? '').replace(/[\s。.!！,，;；:：、]/g, '')
+  if (/^(?:无|没有|暂无|尚无|无剩余|无待办|无未完成|均已?完成|全部完成|none|nothing|n\/?a)$/i.test(s)) return true
+  return /^(?:无|没有|暂无|尚无)/.test(s) && s.length <= 8
+}
+
+/**
+ * 解析检查点。
+ *
+ * 三件事分开报，因为它们对应三种不同的错：
+ *   · `missing` —— 缺节，或**只有标题没有内容**（占位符不算内容）；
+ *   · `claimsDoneWithoutEvidence` —— 声称完成却没有任何证据标记（本模块的主要理由）；
+ *   · `malformedReason` —— 连检查点的骨架都读不出来（不是文本 / 空 / 没有任务标记 /
+ *     revision 不是非负整数）。**缺节不算坏文件**：那是不完整，不是不可读。
+ *
+ * 绝不抛：任何输入都返回同一形状的对象。
+ *
+ * @returns {{taskId: string, project: string, revision: number, sections: Object,
+ *            missing: string[], claimsDoneWithoutEvidence: string[],
+ *            hasNextStep: boolean, malformedReason: string}}
+ */
+export function parseCheckpoint(text) {
+  const out = {
+    taskId: '',
+    project: '',
+    revision: 0,
+    sections: {},
+    missing: [],
+    claimsDoneWithoutEvidence: [],
+    hasNextStep: false,
+    malformedReason: '',
+  }
+  // 六个键先铺满：调用方不必自己判 undefined，`missing` 才是「哪几节没内容」的答案。
+  for (const name of CHECKPOINT_SECTIONS) out.sections[name] = ''
+
+  if (typeof text !== 'string') {
+    out.malformedReason = '内容不是文本'
+    out.missing = [...CHECKPOINT_SECTIONS]
+    return out
+  }
+
+  const lines = text.split(/\r?\n/)
+
+  // 元信息只认**第一个二级及更深标题之前**的行：一级标题是本模板的文档标题（`# 任务检查点 x`），
+  // 而节正文里的 `- 任务：…` 是内容、不是元信息 —— 用「二级标题」当元信息区的结束，两者都不误伤。
+  let metaEnd = lines.length
+  for (let i = 0; i < lines.length; i++) {
+    if (/^\s{0,3}#{2,}\s+\S/.test(lines[i])) {
+      metaEnd = i
+      break
+    }
+  }
+
+  let revisionRaw = null
+  for (let i = 0; i < metaEnd; i++) {
+    const line = lines[i]
+    if (out.taskId === '') {
+      const m = line.match(/^[-*+]?\s*任务\s*[:：]\s*(.*)$/)
+      if (m) {
+        out.taskId = m[1].trim()
+        continue
+      }
+    }
+    if (out.project === '') {
+      const m = line.match(/^[-*+]?\s*项目\s*[:：]\s*(.*)$/)
+      if (m) {
+        out.project = m[1].trim()
+        continue
+      }
+    }
+    if (revisionRaw === null) {
+      const m = line.match(/^[-*+]?\s*revision\s*[:：]\s*(\S*)\s*$/i)
+      if (m) revisionRaw = m[1]
+    }
+  }
+  // 渲染出的占位符不是值 —— 回了占位符等于没写。
+  if (out.taskId === PLACEHOLDER) out.taskId = ''
+  if (out.project === PLACEHOLDER) out.project = ''
+
+  let revReason = ''
+  if (revisionRaw !== null) {
+    if (!/^\d+$/.test(revisionRaw)) {
+      revReason = `revision 不是非负整数：${revisionRaw}`
+    } else {
+      const n = Number(revisionRaw)
+      if (!Number.isSafeInteger(n)) revReason = `revision 超出安全整数范围：${revisionRaw}`
+      else out.revision = n
+    }
+  }
+
+  const bodies = new Map(CHECKPOINT_SECTIONS.map((name) => [name, []]))
+  let current = null
+  for (const line of lines) {
+    const heading = line.match(/^\s{0,3}(#{1,6})\s+(.*?)\s*#*\s*$/)
+    if (heading) {
+      const level = heading[1].length
+      const title = heading[2].replace(/\s*[：:]\s*$/, '').trim()
+      if (CHECKPOINT_SECTIONS.includes(title)) {
+        current = title
+        continue
+      }
+      // 六节固定是二级标题：别的二级及更浅标题是节边界；`###` 更深的是节内小标题，
+      // 落到下面照样进正文（它是一个节的排版结构，不是新节）。
+      if (level <= 2) {
+        current = null
+        continue
+      }
+    }
+    if (current !== null) bodies.get(current).push(line)
+  }
+  for (const name of CHECKPOINT_SECTIONS) out.sections[name] = bodies.get(name).join('\n').trim()
+
+  out.missing = CHECKPOINT_SECTIONS.filter((name) => significantLines(out.sections[name]).length === 0)
+  out.claimsDoneWithoutEvidence = itemsOf(out.sections[DONE_SECTION]).filter((item) => !hasEvidence(item))
+  out.hasNextStep = itemsOf(out.sections[TODO_SECTION]).some((item) => !isNoWork(item))
+
+  if (out.taskId === '') out.malformedReason = '缺少任务标记（- 任务：…）'
+  else if (revReason !== '') out.malformedReason = revReason
+
+  return out
+}
+
+/**
+ * 读一份检查点。**所有失败都返回对象，绝不抛**（注入链上不许因为一次读失败炸掉）。
+ *
+ * @param {string} taskId
+ * @param {{stateRoot?: string}} [opts]
+ * @returns {Promise<{ok:true, path, bytes, text, taskId, project, revision, sections, missing,
+ *   claimsDoneWithoutEvidence, hasNextStep, malformedReason, declaredTaskId, warnings, handle}
+ *   | {ok:false, code:'invalid'|'missing'|'io_error'|'malformed', path?, error, revision?}>}
+ */
+export async function readCheckpoint(taskId, opts) {
+  const id = normalizeTaskId(taskId)
+  if (id === null) return { ok: false, code: 'invalid', error: `任务 id 非法：${JSON.stringify(taskId)}` }
+
+  const path = checkpointPathFor(id, opts && typeof opts === 'object' ? opts.stateRoot : undefined)
+  let text
+  try {
+    text = await readFile(path, 'utf8')
+  } catch (err) {
+    if (err?.code === 'ENOENT') return { ok: false, code: 'missing', path, error: '检查点文件不存在' }
+    return { ok: false, code: 'io_error', path, error: String(err?.message ?? err) }
+  }
+
+  const parsed = parseCheckpoint(text)
+  if (parsed.malformedReason !== '') {
+    // 坏文件**不把正文交出去**：一份读不出来的东西被当成检查点用，比读不到更危险。
+    return { ok: false, code: 'malformed', path, error: parsed.malformedReason, revision: parsed.revision }
+  }
+
+  // 目录名才是我们请求的身份；文件里写的 id 只当**声明**核对，不一致要说出来而不是静默采信。
+  const warnings = []
+  if (parsed.taskId !== id) warnings.push(`文件内声明的任务 id（${parsed.taskId}）与所在目录（${id}）不一致`)
+
+  return {
+    ok: true,
+    path,
+    bytes: Buffer.byteLength(text, 'utf8'),
+    text,
+    ...parsed,
+    taskId: id,
+    declaredTaskId: parsed.taskId,
+    warnings,
+    handle: checkpointHandleText({ taskId: id, revision: parsed.revision, project: parsed.project }),
+  }
+}
+
+/**
+ * 写一份检查点（原子写，覆盖旧版本）。
+ *
+ * 复用 `util.js` 的 `writeFileAtomic`：直写崩在中途会留下半截检查点 —— 而半截的交接材料
+ * 比没有更糟（它看起来像一份状态，实际是错的）。这里**不校验内容**：校验的落点在读/解析
+ * 那一端，写路径只守体积与原子性。写进去的东西至少是完整的一份，能被读出来判它坏。
+ *
+ * ⚠️ 本模块不实现锁：并发写同一个 taskId 由**调用方串行**（进程内用 createWriteQueue）。
+ *
+ * @param {string} taskId
+ * @param {string} text
+ * @param {{stateRoot?: string}} [opts]
+ * @returns {Promise<{ok:true, bytes:number, path:string} | {ok:false, code:'invalid'|'too_big'|'io_error', ...}>}
+ */
+export async function writeCheckpoint(taskId, text, opts) {
+  const id = normalizeTaskId(taskId)
+  if (id === null) return { ok: false, code: 'invalid', error: `任务 id 非法：${JSON.stringify(taskId)}` }
+  if (typeof text !== 'string') return { ok: false, code: 'invalid', error: '检查点正文必须是字符串' }
+
+  // 按 UTF-8 字节算，不是字符数 —— 一份中文检查点的字符数只有字节数的三分之一，
+  // 用字符数当闸门等于把上限放大三倍。
+  const bytes = Buffer.byteLength(text, 'utf8')
+  if (bytes > CHECKPOINT_MAX_BYTES) {
+    return {
+      ok: false,
+      code: 'too_big',
+      bytes,
+      limit: CHECKPOINT_MAX_BYTES,
+      error: `检查点 ${bytes} 字节，超过上限 ${CHECKPOINT_MAX_BYTES} 字节`,
+    }
+  }
+
+  const path = checkpointPathFor(id, opts && typeof opts === 'object' ? opts.stateRoot : undefined)
+  try {
+    await mkdir(dirname(path), { recursive: true })
+    await writeFileAtomic(path, text)
+  } catch (err) {
+    return { ok: false, code: 'io_error', path, error: String(err?.message ?? err) }
+  }
+  return { ok: true, bytes, path }
+}
+
+/** 注入用的短句柄硬上限（字节）。它要跟正文抢上下文，不能自己长起来。 */
+const HANDLE_MAX_BYTES = 160
+
+/** 按**码点**截断到不超过 maxBytes 字节：不许把一个字符切成半个（注入文本里会变 U+FFFD）。 */
+function truncateByBytes(s, maxBytes) {
+  if (Buffer.byteLength(s, 'utf8') <= maxBytes) return s
+  let out = ''
+  let used = 0
+  for (const ch of s) {
+    const b = Buffer.byteLength(ch, 'utf8')
+    if (used + b > maxBytes) break
+    out += ch
+    used += b
+  }
+  return out
+}
+
+/**
+ * 注入用的短句柄（一行，≤ 160 字节）：说清「有这个检查点、revision 几、怎么读」。
+ *
+ * 预算是硬的，所以按优先级退化：**id 与 revision 不可丢**（它们才是身份），项目是可选线索
+ * （放不下就截短或整个丢掉），最后连「重复一次 id 的完整相对路径」放不下时（64 字符的
+ * 极端 id），退成不含重复路径的说法。绝不把多字节字符截半个。taskId 非法返回 ''。
+ *
+ * revision 缺省按 0（与 renderCheckpoint 的缺省一致）。
+ */
+export function checkpointHandleText({ taskId, revision, project } = {}) {
+  const id = normalizeTaskId(taskId)
+  if (id === null) return ''
+  const rev = Number.isInteger(revision) && revision >= 0 ? revision : 0
+  const proj = String(project ?? '').replace(/\s+/g, ' ').trim()
+
+  const head = `检查点 ${id}（revision ${rev}）：`
+  const detail = `读 tasks/${id}/WORKING.md`
+  const tail = '，续做前先读'
+  const build = (p) => `${head}${p === '' ? '' : `项目 ${p}，`}${detail}${tail}`
+
+  let line = build(proj)
+  if (Buffer.byteLength(line, 'utf8') > HANDLE_MAX_BYTES) {
+    // 项目放不下：按剩余预算截断它，截不下就整个丢掉。
+    const fixed = Buffer.byteLength(build(''), 'utf8')
+    const room = HANDLE_MAX_BYTES - fixed - Buffer.byteLength('项目 ，', 'utf8')
+    line = build(room > 0 ? truncateByBytes(proj, room) : '')
+  }
+  if (Buffer.byteLength(line, 'utf8') > HANDLE_MAX_BYTES) {
+    // 到这儿只剩「id 太长」一种可能：完整相对路径（id 出现两次）放不下，退成不重复的写法。
+    line = `${head}读 ${TASKS_DIR_NAME}/${CHECKPOINT_FILE_NAME}`
+  }
+  return line
+}

package/lib/memory/observe.js

@@ -0,0 +1,304 @@
+/**
+ * sage-mem 记忆层 —— 工具调用观测：这一次调用是不是在读记忆目录。
+ *
+ * 宿主的 `tools/result` 会把**每一次**工具调用的 `exec`（含 `name` 与 `arguments`）交给我们，
+ * 于是「模型自己用内置工具翻了记忆」这件事第一次能被记进台账（0.9.16 之前只能记「注入过什么」）。
+ * 本模块只做**判定**：写台账是 access.js 的事 —— 这里不落盘、不看时钟、不 stat。
+ *
+ * ## 三条边界（都是「宁可漏记，绝不误记」）
+ *
+ * 1. **只认能可靠判定的形状。**
+ *    `read` 的 `file_path`、`grep` / `glob` 的 `path` 是结构化参数，能可靠判定；而 `pwsh` 的
+ *    `command` 是一段程序 —— `cat 某记忆`、`Get-Content`、`type`、`Select-String`、变量拼接、
+ *    管道、重定向……认不全。认一半的代价是把「读的是别的东西」记成「读了记忆」，所以执行类
+ *    工具一律 `kind:'unobservable'`：**这是已知观测盲区，不是「这一步没有读取」**。
+ *    同理不猜的还有：`grep` / `glob` 缺 `path` 时不拿 `pattern` 反推目录（pattern 里可以有
+ *    `*` / `{a,b}` / `**`）；`read` 拿到相对路径时不猜 cwd（cwd 是运行时状态，纯函数看不到）。
+ *
+ * 2. **`atime` 永远不许当证据。** 索引器、备份程序、挂载选项都会改它，它既不等于「模型读过」，
+ *    也不等于「用户用过」。本模块只用传进来的参数判定，一个文件系统调用都不发。
+ *
+ * 3. **路径判定与平台无关。** `\` 在 Windows 是分隔符、在 Linux 只是普通字符：同一份输入在
+ *    两个平台上会被 `path` 的默认语义解析成不同目录（`naming.js` 的 `safeName` 刚被 Linux CI
+ *    用同一类缺陷抓过一次）。所以这里**不用** `path.resolve` / `path.relative` / `path.sep`，
+ *    按下面这套固定规则自己归一 —— 语义只由规则决定，不由运行平台决定。
+ *
+ * ## 归一规则（两个平台完全一致，实现见 canonicalPathOf）
+ *
+ * - 只接受**绝对路径**（`/…`、`//server/share…`、`X:/…`）；相对路径不认。
+ * - `\` 与 `/` **一律**当分隔符（显式同时处理两者，而不是交给 `path.sep`）。
+ * - 折叠 `.`、连续分隔符，逐段回退 `..`（绝对路径在根上的 `..` 是空操作）。
+ * - 盘符统一小写；其余部分**大小写敏感**。NTFS 不敏感、ext4 敏感 —— 取交集（敏感）只会漏记，
+ *   取并集（不敏感）会误记，观测层宁可漏记。
+ * - 包含关系按**段边界**判定（父目录 + 分隔符），所以 `记忆目录-evil/x.md` 不会被当成
+ *   `记忆目录/x.md` —— 字符串前缀比较的经典错。
+ *
+ * ## 已知残留边界（写清楚，不假装没有）
+ *
+ * - POSIX 上 `\` 可以是文件名里的普通字符，本模块把它当分隔符：那种畸形名字可能被归到隔壁。
+ *   方向只会是**漏记**（或把一个本来就在目录内的名字算成目录内的另一个名字），且 `safeName`
+ *   本来就禁止记忆条目名里出现 `\`。
+ * - 符号链接 / 8.3 短名 / 目录联接不做解析（纯函数不读盘）。路径里先有指向外部的链接时，
+ *   `link/../x` 这类写法按字面归一 —— 这是观测层能做到的上限，宁可少记。
+ *
+ * ## 字段口径
+ *
+ * - `file` = **记忆文件名**，不是路径。与 `scanMemoryFiles` / `hits[].file` / 台账
+ *   `access.json` 的键同一口径：调用方拿到就能直接进 `accessEventKey` 与 `recordAccess`，
+ *   不必再 basename 一次 —— 每多一次转换就多一个「键域搞错」的机会（D18 就是这么来的）。
+ * - `dir` = **规范化后的绝对路径**，只在「值指向记忆目录里的一个目录（含记忆目录本身）」时给出。
+ */
+
+/** 认得的读工具 → 取路径的参数名。表是**数据**：调用方与测试都直接读它，不写第二份分支。 */
+export const READ_TOOLS = Object.freeze({ read: 'file_path', grep: 'path', glob: 'path' })
+
+/** 判为「写」的工具。列出来是为了可解释：它们改记忆，不是读记忆。 */
+export const WRITE_TOOLS = Object.freeze(['write', 'edit'])
+
+/**
+ * 判为「看不见」的工具。
+ *
+ * 单列出来就是为了可解释：台账里出现 `unobservable` 才说明「这一步**可能**有读取但我们没记」，
+ * 而不是「这一步没有读取」。两者的区别决定了排查方向。
+ */
+export const UNOBSERVABLE_TOOLS = Object.freeze(['pwsh', 'bash', 'shell'])
+
+/**
+ * 记忆条目一律是 `.md`（`naming.js` 的唯一判据）。这里**不** import `isMemoryEntry`：
+ * 观测层判的是「这次调用碰的是不是记忆文件」，不该跟着扫描层的排除名单（索引 / 流水）一起变
+ * —— 读 `MEMORY.md` 同样是读了记忆目录，该不该记进台账由调用方决定。
+ */
+const MEMORY_FILE_RE = /\.md$/i
+
+/** 写工具取路径的参数名（读工具的对应项在 READ_TOOLS 里）。 */
+const WRITE_PATH_ARG = 'file_path'
+
+/** 只有这两种事件有「哪个文件」这个键，才进得了以文件名为键的台账。 */
+const RECORDABLE_KINDS = new Set(['active_read', 'write'])
+
+/**
+ * 把路径归一成规范形式；**不是绝对路径就返回 null**（调用方一律按「不认」处理）。
+ *
+ * 为什么自己写而不用 `path.resolve`：`path.resolve` 在 Windows 上把 `\` 当分隔符、在 Linux 上
+ * 不当，于是同一份输入两个平台给出不同结果 —— 而记忆目录会被同步 / 拷贝 / 备份还原，判据必须
+ * 跨平台一致。这里的规则只依赖输入的**形状**，不依赖 `path.sep`。
+ *
+ * `..` 到根为止（绝对路径在根上的 `..` 是空操作，POSIX 与 Windows 同义）；不作磁盘解析，
+ * 所以符号链接意义上的「真实位置」不保证被还原 —— 见文件头的残留边界。
+ */
+function canonicalPathOf(raw) {
+  if (typeof raw !== 'string' || raw === '') return null
+  const isDrive = /^[A-Za-z]:[\\/]/.test(raw)
+  // UNC（`\\server\share…` / `//server/share…`）保留双斜杠前缀：它和「根下的同名目录」不是
+  // 一回事，合并成一个前缀会把两个不同的位置判成同一个（那才是误记）。
+  const isUnc = !isDrive && (raw.startsWith('//') || raw.startsWith('\\\\'))
+  let prefix
+  let rest
+  if (isDrive) {
+    // 盘符统一小写：Windows 上 `C:` 与 `c:` 必然同义；POSIX 上这种形状不是绝对路径，到不了这里。
+    prefix = `${raw[0].toLowerCase()}:`
+    rest = raw.slice(2)
+  } else if (isUnc) {
+    prefix = '//'
+    rest = raw.slice(2)
+  } else if (raw.startsWith('/')) {
+    prefix = '/'
+    rest = raw.slice(1)
+  } else {
+    // `\x`（Windows 当前盘的根）、`a/b`（相对 cwd）、`C:foo`（盘符相对）都在这里被拒：
+    // 它们的真实落点取决于运行时状态，纯函数看不到，猜一个基准就是误记。
+    return null
+  }
+  const segs = []
+  for (const seg of rest.split(/[\\/]+/)) {
+    if (seg === '' || seg === '.') continue
+    if (seg === '..') {
+      if (segs.length) segs.pop()
+      continue
+    }
+    segs.push(seg)
+  }
+  if (prefix === '/') return segs.length ? `/${segs.join('/')}` : '/'
+  if (prefix === '//') return segs.length ? `//${segs.join('/')}` : '//'
+  return segs.length ? `${prefix}/${segs.join('/')}` : `${prefix}/`
+}
+
+/**
+ * 段边界包含：`/mem` 含 `/mem/x.md` 与它自己，**不含** `/memories/x.md`。
+ *
+ * 判据是「父目录 + 分隔符」，不是裸字符串前缀 —— 裸前缀正是那个经典陷阱。
+ */
+function isSameOrInside(parent, child) {
+  if (parent === child) return true
+  const boundary = parent.endsWith('/') ? parent : `${parent}/`
+  return child.startsWith(boundary)
+}
+
+/** 规范路径的最后一段（`file` 字段要的是记忆文件名，不是路径）。 */
+function fileNameOf(canon) {
+  const cut = canon.lastIndexOf('/')
+  return cut < 0 ? canon : canon.slice(cut + 1)
+}
+
+/**
+ * 根目录不算记忆目录。
+ *
+ * 拿根（`/`、`//`、`X:/`）做包含判定，等于把整块盘都算成记忆 —— 一条配置写错就能把台账
+ * 灌满「读了别处」的记录。宁可不判。
+ */
+function isRootLike(canon) {
+  return canon === '/' || canon === '//' || /^[a-z]:\/$/.test(canon)
+}
+
+/** 结果工厂：保证四个字段恒在，调用方不必到处判 undefined。 */
+function verdict(kind, why) {
+  return { kind, file: null, dir: null, why }
+}
+
+/** 安全取参：参数不是对象就当作没给；getter 抛错由 classifyToolExecution 的外层兜住。 */
+function argOf(args, key) {
+  if (!args || typeof args !== 'object') return undefined
+  return args[key]
+}
+
+/** 写工具：是写就不是读，但仍要如实说出「写的是不是记忆文件」。 */
+function classifyWrite(args, memoryDir) {
+  const canon = canonicalPathOf(argOf(args, WRITE_PATH_ARG))
+  if (!memoryDir) return verdict('write', '写操作；记忆目录不可判定，不判断是否落在记忆里')
+  if (!canon) return verdict('write', '写操作；没有可判定的绝对文件路径')
+  if (!isSameOrInside(memoryDir, canon)) return verdict('write', '写操作，但目标不在记忆目录内')
+  if (!MEMORY_FILE_RE.test(canon)) return verdict('write', '写操作，目标在记忆目录内但不是 .md 记忆条目')
+  return { kind: 'write', file: fileNameOf(canon), dir: null, why: '写记忆文件（不是读取）' }
+}
+
+/**
+ * 读工具（`read` / `grep` / `glob`）。
+ *
+ * `grep` / `glob` 的 `path` 既可能是目录也可能是文件，纯函数不 stat，所以按**值的形状**分：
+ * `.md` 结尾当文件（仓库里记忆条目一律 `.md`），否则当目录。`read` 按语义必须落在文件上，
+ * 非 `.md` 一律不认。
+ */
+function classifyRead(toolName, args, memoryDir) {
+  const argName = READ_TOOLS[toolName]
+  const raw = argOf(args, argName)
+  if (typeof raw !== 'string' || raw === '') {
+    return verdict('other', `没有可用的 ${argName} 字符串，不猜这次读的是哪`)
+  }
+  const canon = canonicalPathOf(raw)
+  if (!canon) {
+    return verdict('other', '不是绝对路径（相对路径的基准是运行时的 cwd，纯函数看不到），不猜')
+  }
+  if (!isSameOrInside(memoryDir, canon)) return verdict('other', '路径不在记忆目录内')
+
+  if (toolName === 'read') {
+    if (!MEMORY_FILE_RE.test(canon)) return verdict('other', '在记忆目录内，但不是 .md 记忆条目')
+    return { kind: 'active_read', file: fileNameOf(canon), dir: null, why: '读了记忆目录里的记忆文件' }
+  }
+  // glob 只列清单（不算读正文）；grep 会读正文，所以是 active_read。两者都不刷「读了多少」，
+  // 交给台账按文件名去重。
+  const kind = toolName === 'glob' ? 'list_only' : 'active_read'
+  if (MEMORY_FILE_RE.test(canon)) {
+    return {
+      kind,
+      file: fileNameOf(canon),
+      dir: null,
+      why: toolName === 'glob' ? '列了记忆目录里的一个文件（只列清单，不算读正文）' : '在记忆目录里按模式检索这个文件',
+    }
+  }
+  return {
+    kind,
+    file: null,
+    dir: canon,
+    why: toolName === 'glob' ? '列了记忆目录（只列清单，不算读正文）' : '在记忆目录里按模式检索（读的是记忆正文）',
+  }
+}
+
+/**
+ * 判定一次工具调用。**纯函数**：不读盘、不看时钟、不抛。
+ *
+ * @param {string} toolName
+ * @param {object} args — 原始 arguments
+ * @param {string} memoryDir — 记忆根目录（绝对路径）
+ * @returns {{kind:'active_read'|'list_only'|'write'|'unobservable'|'other',
+ *            file:string|null, dir:string|null, why:string}}
+ *   `file`（记忆文件名）只在确实指向记忆目录里的一个记忆文件时给出；`dir`（规范绝对路径）只在
+ *   其值指向记忆目录里的一个目录（含记忆目录本身）时给出。**指向别处的路径一律不认**
+ *   （`kind:'other'`）—— 观测层不许把「读了别的东西」记成「读了记忆」。
+ */
+export function classifyToolExecution(toolName, args, memoryDir) {
+  try {
+    const name = typeof toolName === 'string' ? toolName : ''
+    if (!name) return verdict('other', '工具名缺失或不合法，不猜')
+
+    // 看不见的工具先判：它和参数能不能解析无关 —— 「我们看不见」本身就是结论。
+    if (UNOBSERVABLE_TOOLS.includes(name)) {
+      return verdict('unobservable', `${name} 的命令行无法可靠认出读了哪个文件 —— 已知观测盲区，不是「没有读取」`)
+    }
+
+    const dir = canonicalPathOf(memoryDir)
+    // 相对 / 空的记忆目录不猜（猜了就是拿一个不知道的基准做包含判定）；根目录拒掉的原因见 isRootLike。
+    const usableDir = dir && !isRootLike(dir) ? dir : null
+
+    if (WRITE_TOOLS.includes(name)) return classifyWrite(args, usableDir)
+
+    if (Object.prototype.hasOwnProperty.call(READ_TOOLS, name)) {
+      if (!usableDir) {
+        return verdict('other', dir ? '记忆目录是根目录，用它判定会把整块盘算成记忆，不判' : '记忆目录不可判定（不是绝对路径），不判')
+      }
+      return classifyRead(name, args, usableDir)
+    }
+
+    return verdict('other', `不认得的工具（${name}），不猜它的参数形状`)
+  } catch {
+    // 观测层是**顺带**记一笔，绝不许有能力把调用方拖下水：任何意外都退化成「没看见」。
+    return verdict('other', '判定过程出错，按不认处理')
+  }
+}
+
+/**
+ * 去重键：同一 session × 文件 × revision × kind 只算一次。
+ *
+ * 翻页（`read` 的 `offset` / `limit` 不同）不在这里出现 —— 它们根本不在入参里，所以
+ * 「翻页不刷计数」是**结构上**成立的，不靠调用方自觉。换了 revision 就是另一份内容，
+ * 要重新计一次。
+ *
+ * ⚠️ **它不是台账键**：台账 `access.json` 的键是文件名，这个键是四元组。别混用。
+ *
+ * @returns {string|null} null = 不该记（没有文件，或者不是一次访问事件）
+ */
+export function accessEventKey(input = {}) {
+  const a = input && typeof input === 'object' ? input : {}
+  const file = typeof a.file === 'string' ? a.file : ''
+  if (file === '') return null
+  if (!RECORDABLE_KINDS.has(a.kind)) return null
+  // 缺 session 时退化成「整个进程一个会话」的去重域：宁可少记重复的，也不因为拿不到 session
+  // 就一条都不记。revision 缺失同理（空串），它有值时自然与空串区分开。
+  const session = typeof a.sessionId === 'string' ? a.sessionId : ''
+  const revision = typeof a.revision === 'string' ? a.revision : ''
+  return `${session}\u0000${file}\u0000${revision}\u0000${a.kind}`
+}
+
+/**
+ * 已经记过的键的容器（纯内存，调用方持有）。
+ *
+ * 为什么由调用方持有而不是模块级单例：模块级单例会在热加载 / 测试之间串味，而这个集合的
+ * 生命周期本来就该等于「一场会话」。调用方拿同一份实例跑完会话，`clear()` 就能重来。
+ */
+export function createDeduper() {
+  const seen = new Set()
+  return {
+    /** @returns {boolean} true = 这次该记（第一次见到这个键） */
+    shouldCount(key) {
+      if (typeof key !== 'string' || key === '') return false
+      if (seen.has(key)) return false
+      seen.add(key)
+      return true
+    },
+    get size() {
+      return seen.size
+    },
+    clear() {
+      seen.clear()
+    },
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sage-mem",
   "description": "File-based memory plugin for DeepSeek Harness (DSH) — cross-session memory in plain markdown files, with a memory star-map view, type/tag filtering, retrieval aliases, and an optional autodream pass that consolidates memories on demand or on a schedule — with per-run rollback points, a per-file change declaration (what changed and why), and a separately selectable model for the consolidation pass",
-  "version": "0.9.17",
+  "version": "0.9.18",
   "type": "module",
   "main": "lib/index.js",
   "exports": {