sage-mem 2.1.2 → 2.1.4

package/README.md

@@ -12,7 +12,7 @@
 
 **Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.**
 
-**Current release: `2.1.2`** — the npm badge above is the dynamic source of truth. **Contract baseline: `1.0.0`** — the first stable release, whose public commitments, the capability boundaries and the list of things it explicitly cannot do are frozen in the
+**Current release: `2.1.4`** — the npm badge above is the dynamic source of truth. **Contract baseline: `1.0.0`** — the first stable release, whose public commitments, the capability boundaries and the list of things it explicitly cannot do are frozen in the
 [frozen contract](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md).
 
 If it is useful to you, a Star is the most direct feedback.

package/README.zh.md

@@ -14,7 +14,7 @@
 
 > File-based cross-session memory for DeepSeek Harness — every memory is a plain markdown file you can open, edit and delete. No database, no worker, no port.
 
-**当前发布版本：`2.1.2`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
+**当前发布版本：`2.1.4`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
 [契约冻结](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md)。
 
 如果它对你有用，给个 Star 是最直接的反馈。

package/lib/autodream/tools.js

@@ -36,7 +36,7 @@ import { writeFileAtomic, warnLog } from '../memory/util.js'
 import { buildConflict, listConflicts, readConflict, sameConflict, writeConflict } from '../memory/conflicts.js'
 import { memoryPathOf } from '../memory/paths.js'
 import { decideWriteIntent } from '../memory/write-gate.js'
-import { inspectMemoryEntry, reservedIdentitySet } from '../memory/scan.js'
+import { inspectMemoryEntry, readVerified, reservedIdentitySet } from '../memory/scan.js'
 
 /** 单次 read_memory 返回的正文上限（字符）。超过就截断并明确告诉模型。 */
 const READ_LIMIT = 20000
@@ -121,7 +121,8 @@ async function scanEntries(memoryDir, ctx) {
       continue
     }
     try {
-      const content = await readFile(full, 'utf8')
+      // 同上：清单也要从闸门检查过的那个句柄读（N03 —— 检查后换文件不能把外部标题带进来）。
+      const content = await readVerified(full, gate, 'utf8')
       const meta = parseFrontmatterLite(content)
       const body = content.replace(/^---\r?\n[\s\S]*?\r?\n---/, '')
       const h1 = body.match(/^#\s+(.+)$/m)
@@ -489,24 +490,72 @@ export function createToolRunner(opts) {
   const readVersions = new Map()
 
   /**
-   * 记下一次读取对应的版本。取不到可信版本就**什么都不记**（宁可让写入走「拒绝」，
-   * 也不要拿一个来路不明的版本假装有守卫）。
+   * 把「这份内容对应磁盘上的哪个版本」记下来（写回时当守卫）。
    *
-   * 一致性：宿主 fs 可用时用 `stat → 读 → stat`，**两次版本相同**才认这份内容是那个版本的快照。
-   * 中间被人改过就不记 —— 分开读拿不到原子快照，那就诚实地说「不知道」。
+   * 取不到可信版本（`version` 为 null）就**什么都不记** —— 宁可让写入走「拒绝」，
+   * 也不要拿一个来路不明的版本假装有守卫。
+   *
+   * ⚠️ 这里只登记、**自己不 stat**。版本由 `readEntryWithVersion` 在**实际读取的前后**
+   * 各取一次得到；以前是在 `readFile` **之后**才 stat 两次，读 A、盘上已是 B 时两次 stat
+   * 都是 B，于是 A 的正文被绑到 B 的版本上（外部审查 2026-10-31，Q01）。
+   */
+  function rememberReadVersion(fullPath, version, truncated) {
+    if (!version) return
+    const where = memoryPathOf(fullPath, memoryDir)
+    if (where.ok) readVersions.set(where.canon, { version, truncated: truncated === true })
+  }
+
+  /**
+   * 「读内容」与「取版本」共用的**唯一入口**（外部审查 2026-10-31，Q01）。
+   *
+   * 为什么必须是入口、不是两段调用：写回守卫要回答的是「**这份正文**对应哪一个版本」。
+   * 分开写时，调用方手里是 `readFile` 的返回值和两次 `stat` 的结果，把三者拼起来那一步最容易错
+   * —— 真实代码曾是 `readFile → stat → stat`：读的是 A，两次 stat 都读到 B，
+   * 于是 A 的正文被绑到 B 的版本，宿主的 CAS 即使完全正确也救不了这个错配。
+   *
+   * 顺序固定 **stat → read → stat**，两次版本**相同**才认这份内容就是那个版本的快照；
+   * 任何一次取不到（没有宿主 fs 服务 / stat 抛错 / 版本字段缺失）都按「版本未知」处理，
+   * 不拿当前版本补票 —— 补票等于替调用方担保一份它没读过的内容。
+   *
+   * 宿主 `fs` 契约里目前**没有**「原子 read-with-version」这一原语（`readText` 只回正文），
+   * 所以退到两次 stat 夹住实际读取。将来宿主提供这个原语，应当优先在 open 句柄上一次性拿到。
+   *
+   * @returns {Promise<{ok:false, gate:object}|{ok:true, gate:object, content:string, version:string|null}>}
+   *   `gate` 是 `inspectMemoryEntry` 的结果（2.1.4 起内容读还用它做身份核对）
    */
-  async function rememberReadVersion(fullPath, content, truncated) {
+  async function readEntryWithVersion(full) {
+    const gate = await inspectMemoryEntry(full)
+    if (!gate.ok) return { ok: false, gate }
+    const fs = hostFs()
+    const hostStat = async () => {
+      if (!fs || typeof fs.stat !== 'function') return null
+      try {
+        const info = await fs.stat(await fs.resolve(full))
+        return info?.version ?? null
+      } catch {
+        return null // 取不到就是未知：不要拿「现在」的版本顶替
+      }
+    }
+    const before = await hostStat()
+    let content
     try {
-      const fs = hostFs()
-      if (!fs || typeof fs.stat !== 'function') return
-      const target = await fs.resolve(fullPath)
-      const before = await fs.stat(target)
-      if (!before?.version) return
-      const after = await fs.stat(target)
-      if (!after?.version || after.version !== before.version) return
-      const where = memoryPathOf(fullPath, memoryDir)
-      if (where.ok) readVersions.set(where.canon, { version: before.version, truncated: truncated === true })
-    } catch { /* 记不下就不记：调用方会按「未知版本」处理 */ }
+      /**
+       * 内容走**公共句柄读取入口**（外部审查 2026-10-31，N03）：`inspectMemoryEntry` 是按路径
+       * `lstat`，`readFile(路径)` 是另一次按路径打开 —— 两次之间把普通文件换成符号链接 / 另一份
+       * 文件，读的就是没检查过的东西（审查用真符号链接复现出目录外内容）。`readVerified`
+       * 改成 open 句柄 + fstat 比对 `dev:ino` / 大小，只从那个句柄读；体积上限也在全文读入
+       * **之前**生效，不会先整份读进内存再判。
+       */
+      content = await readVerified(full, gate, 'utf8')
+    } catch (err) {
+      // 扫到读之间被删是正常状态；其余读失败（含「检查后被换掉」）照旧抛给上层。
+      if (err?.code === 'ENOENT') return { ok: false, gate: { ok: false, code: 'missing' } }
+      throw err
+    }
+    const after = await hostStat()
+    // 两次版本相同才认「内容 = 版本」；只要中间可能被动过就当作未知。
+    const version = before && after && before === after ? before : null
+    return { ok: true, gate, content, version }
   }
 
   /**
@@ -800,22 +849,21 @@ export function createToolRunner(opts) {
              * 过闸门再读：**名字在记忆目录里不等于内容住在记忆目录里**。
              * 注入与面板两条腿都挡住了，这条腿（模型工具）也必须挡 ——
              * 否则外部文件的内容照样会被读进来、送进模型上下文。
+             *
+             * 内容与版本一起取（`readEntryWithVersion`）：守卫要的是「这份正文对应哪个版本」，
+             * 分开取会把 A 的正文绑到 B 的版本上（Q01）。
              */
-            const gate = await inspectMemoryEntry(full)
-            if (!gate.ok) {
-              return gate.code === 'missing'
+            const seen = await readEntryWithVersion(full)
+            if (!seen.ok) {
+              return seen.gate.code === 'missing'
                 ? `错误：没有这个文件：${basename(full)}`
-                : `错误：拒绝读取 ${basename(full)}：${gate.error}`
+                : `错误：拒绝读取 ${basename(full)}：${seen.gate.error}`
             }
-            const content = await readFile(full, 'utf8').catch((err) => {
-              if (err?.code === 'ENOENT') return null
-              throw err
-            })
-            if (content === null) return `错误：没有这个文件：${basename(full)}`
-            // 记下「这份内容对应磁盘上的哪个版本」——写回时用它当守卫（外部复审 R01）。
+            const content = seen.content
+            // 记下「这份内容对应磁盘上的哪个版本」——写回时用它当守卫（外部复审 R01 / Q01）。
             // 截断的读也要标出来：截断内容不足以作为整份覆盖的依据。
             const truncated = content.length > READ_LIMIT
-            await rememberReadVersion(full, content, truncated)
+            rememberReadVersion(full, seen.version, truncated)
             if (truncated) {
               return `${content.slice(0, READ_LIMIT)}\n\n…（已截断，全文 ${content.length} 字符。注意：截断的读不能作为整份覆盖的依据）`
             }
@@ -942,10 +990,11 @@ export function createToolRunner(opts) {
               return '错误：report_contradiction 必须给 note —— 一句话说明这两条到底哪里互斥。'
             }
             // 两份正文都存进记录：面板上人要对照着判，只留一边等于没得判。
+            // 同样走句柄读取入口（N03）：记录里的正文会被人和模型看到，不能来自目录外。
             const readBody = async (full) => {
               const gate = await inspectMemoryEntry(full)
               if (!gate.ok) return null
-              return await readFile(full, 'utf8').catch(() => null)
+              return await readVerified(full, gate, 'utf8').catch(() => null)
             }
             const onDisk = await readBody(oldFull)
             const incoming = await readBody(newFull)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sage-mem",
   "description": "Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.",
-  "version": "2.1.2",
+  "version": "2.1.4",
   "type": "module",
   "main": "lib/index.js",
   "icon": "./icon.png",