sage-mem 2.1.3 → 2.1.5

package/README.md

@@ -12,7 +12,7 @@
 
 **Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.**
 
-**Current release: `2.1.3`** — 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.5`** — 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.3`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
+**当前发布版本：`2.1.5`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
 [契约冻结](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md)。
 
 如果它对你有用，给个 Star 是最直接的反馈。

package/lib/autodream/audit.js

@@ -33,15 +33,18 @@ import { warnLog } from '../memory/util.js'
 const INDEX_FILE = 'MEMORY.md'
 
 /**
- * 归档 / 恢复中途崩溃留下的**私有名残留**：`a.md.archiving-<hex>`。
+ * 归档 / 恢复中途崩溃留下的**私有名残留**：`a.md.archiving-<hex>` / `a.md.restoring-<hex>`。
  *
  * 为什么单列一类（2026-10-12 复审复核点出）：`memory/archive.js` 把源 `rename` 到这个
  * 私有名之后、复核完成之前若进程死掉，这份内容就留在了记忆目录里。它**不是** `.md`，
  * 所以扫描 / 注入 / 星图 / 快照 / 列表都不认它（这本来是对的，免得半成品被当成一条记忆）——
  * 但连体检也不认，就等于「可能装着用户唯一一份内容的东西」在界面上完全隐形，
  * 而它躺在用户会同步、会备份的记忆根目录里。审计负责把它报出来（纯只读，只报不删）。
+ *
+ * 2026-10-31 外部审查 Q06：恢复也改用同一套「接管到私有名」的事务原语，所以残留后缀
+ * 多了一个 `.restoring-` —— 两种都必须报，只加新不留旧（归档残留照样报）。
  */
-const STRAY_RE = /\.archiving-[0-9a-f]+$/i
+const STRAY_RE = /\.(?:archiving|restoring)-[0-9a-f]+$/i
 
 /**
  * 审计**整个跳过**的文件（不读、不当被审对象）。

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)
@@ -538,9 +539,16 @@ export function createToolRunner(opts) {
     const before = await hostStat()
     let content
     try {
-      content = await readFile(full, 'utf8')
+      /**
+       * 内容走**公共句柄读取入口**（外部审查 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
     }
@@ -982,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/lib/memory/archive.js

@@ -17,10 +17,10 @@
 
 import { ARCHIVE_DIR_NAME, addArchiveMeta, inspectDir, inspectMemoryEntry, localStamp, readArchivedMeta, stripArchiveMeta } from './scan.js'
 import { isReserved, nameKey, safeName } from './naming.js'
-import { writeFileAtomic, writeFileExclusive } from './util.js'
+import { retireTaken, returnSource, takeOverSource, writeFileAtomic, writeFileExclusive } from './util.js'
 import { isLocked } from './lock.js'
 import { ensureIndexEntry, dropIndexEntry } from './index-file.js'
-import { link, mkdir, readFile, rename, rm, stat, unlink } from 'node:fs/promises'
+import { link, mkdir, readFile, rename, rm, stat } from 'node:fs/promises'
 import { basename, join } from 'node:path'
 import { randomUUID } from 'node:crypto'
 
@@ -107,7 +107,9 @@ export async function archiveMemory(memoryDir, name, reason, at = localStamp())
     throw err
   }
   /**
-   * ⚠️ 收走原件这一步用 **`rename` 到私有名 + 复核内容**，不是 `unlink`（复审 R06 场景①）。
+   * ⚠️ 收走原件这一步交给 **`takeOverSource`**（`rename` 到私有名 → 逐字节复核 → 还回 /
+   * 退役），不是 `unlink`（复审 R06 场景①；2026-10-31 外部审查 Q06 起归档与恢复共用
+   * 同一份事务移动原语，见 `memory/util.js`）。
    *
    * 从上面那次 `inspectMemoryEntry(src)` 到现在，中间隔着读文件 + 写归档副本两次 IO；
    * 这期间若有人（面板保存、另一个进程、模型工具）把 `a.md` 写成了新版本，
@@ -125,18 +127,14 @@ export async function archiveMemory(memoryDir, name, reason, at = localStamp())
    * 于是**新版本被当成旧版本收走**，顶层与归档件里都不再有它。`ino` 在拿不到 inode 的卷上
    * 还会退化成 `null === null` 恒真，把判据进一步削弱成「体积 + 时间」。
    * 内容比对是精确判据，而且成本可忽略（归档本来就要把这份内容读进内存）。
-   *   · 与读到的字节完全相同 → 就是当初那一份，归档完成，删掉私有名；
-   *   · 不同（或读不回来）→ 是别人的新版本，用 `link()` 还回原名，放弃本次归档。
+   *   · 与读到的字节完全相同 → 就是当初那一份，归档完成，退役私有名；
+   *   · 不同（或读不回来）→ 是别人的新版本，原语用 `link()` 还回原名，放弃本次归档。
    *
    * 崩在中途的代价说清楚：私有名文件会留在记忆目录里（不是 `.md`，扫描与注入都不认它），
-   * 而归档副本已经写好 —— 不会出现「一份都没有」。
+   * 而归档副本已经写好 —— 不会出现「一份都没有」；体检会把 `.archiving-` 残留报出来。
    */
-  const taken = `${src}.archiving-${randomUUID().replace(/-/g, '')}`
-  const moveErr = await rename(src, taken).then(
-    () => null,
-    (err) => err,
-  )
-  if (moveErr) {
+  const takenRes = await takeOverSource(src, sourceBytes, 'archiving')
+  if (!takenRes.ok) {
     /**
      * ⚠️ `rename` 失败**不等于**「源不见了」（复审复核实测，真机 Windows）：
      * 另一进程只读占用（编辑器 / 杀软 / 同步工具）时 `rename` 报 **EBUSY** 而不是 ENOENT，
@@ -144,45 +142,37 @@ export async function archiveMemory(memoryDir, name, reason, at = localStamp())
      * 「错误：没有这个文件」—— 诊断是错的，人会去别处找。按真实错误码分流。
      */
     await rm(dst, { force: true }).catch(() => {})
-    if (moveErr?.code === 'ENOENT') {
+    if (takenRes.code === 'not-found') {
       return { ok: false, code: 'not-found', error: `sage-mem: file not found: ${safe}（归档途中源文件消失了）` }
     }
-    return {
-      ok: false,
-      code: 'move-failed',
-      error: `sage-mem: 归档 ${safe} 时移不动它（${moveErr?.code ?? moveErr}：${moveErr?.message ?? moveErr}）。文件仍在原处、一个字节没动，本次归档未完成 —— 可稍后重试（若是被其它程序占用，关掉它再来）。`,
+    if (takenRes.code === 'move-failed') {
+      const moveErr = takenRes.cause
+      return {
+        ok: false,
+        code: 'move-failed',
+        error: `sage-mem: 归档 ${safe} 时移不动它（${moveErr?.code ?? moveErr}：${moveErr?.message ?? moveErr}）。文件仍在原处、一个字节没动，本次归档未完成 —— 可稍后重试（若是被其它程序占用，关掉它再来）。`,
+      }
     }
-  }
-  const currentBytes = await readFile(taken).catch(() => null)
-  const sameOne = currentBytes !== null && Buffer.compare(currentBytes, sourceBytes) === 0
-  if (!sameOne) {
-    // 移走的是**别人**的新版本：还回去，一个字节都不动。
-    const restored = await link(taken, src).then(
-      () => true,
-      () => false,
-    )
-    await rm(dst, { force: true }).catch(() => {})
-    if (!restored) {
+    if (takenRes.keptAt) {
       /**
        * ⚠️ 归还失败时**绝不能删 `taken`**：它是这份新版本**唯一**的落身处
        * （原名此刻已被别人占着，link 才报的 EEXIST）。删掉它就是真的丢数据。
-       * 这里把它原样留下，并把路径如实写进错误里让人去捞 —— 名字带 `.archiving-`
-       * 后缀，不是 `.md`，扫描 / 注入 / 星图都不会把它当成一条记忆。
+       * 原语把它原样留下，这里把路径如实写进错误里让人去捞 —— 名字带 `.archiving-`
+       * 后缀，不是 `.md`，扫描 / 注入 / 星图都不会把它当成一条记忆，体检会报出来。
        */
       return {
         ok: false,
         code: 'changed',
-        error: `sage-mem: ${safe} 在归档过程中被改写，已放弃本次归档；归还时原名已被占用，**内容仍保留在 ${basename(taken)}**，请手工改回 ${safe}`,
+        error: `sage-mem: ${safe} 在归档过程中被改写，已放弃本次归档；归还时原名已被占用，**内容仍保留在 ${basename(takenRes.keptAt)}**，请手工改回 ${safe}`,
       }
     }
-    await rm(taken, { force: true }).catch(() => {})
     return {
       ok: false,
       code: 'changed',
       error: `sage-mem: ${safe} 在归档过程中被改写，已放弃本次归档（新版本保留在原处，请重试）`,
     }
   }
-  await rm(taken, { force: true }).catch(() => {})
+  await retireTaken(takenRes.taken)
   /**
    * **从索引里摘掉**（与恢复时补索引对称）：索引是「活动记忆的清单」，
    * 记忆归档了就该从清单里退出 —— 不摘的话审计会报「索引悬空」。
@@ -245,7 +235,54 @@ export async function restoreMemory(memoryDir, name) {
   if (dstGate.code !== 'missing') {
     return { ok: false, code: dstGate.code, error: `sage-mem: refusing to restore over ${safe}: ${dstGate.error}` }
   }
-  const content = await readFile(src, 'utf8')
+  const sourceBytes = await readFile(src)
+  const content = sourceBytes.toString('utf8')
+  /**
+   * **事务接管源 + 目标排他落位**（2026-10-31 外部审查 Q06）。
+   *
+   * 旧写法是「先把 A 排他落位到顶层，再 `unlink(归档源)`」：落位确实保护了目标
+   * （复审 R06 场景②），但最后那步按名删除**没有绑定读取时的源版本** —— 落位与 unlink
+   * 之间另一路把归档源改写成 B，`unlink(名字)` 删的就是 B，新版本从两个位置一起消失，
+   * 而函数报 `ok:true`。
+   *
+   * 现在顺序反过来，用与归档同一份原语（`memory/util.js` 的 `takeOverSource`）：
+   *   ① 先把源原子 `rename` 成私有名，并逐字节核对它仍是当初读到的那一份；
+   *   ② 内容对不上 → 原语把 B 还回原名，本次放弃（一个字节都不丢）；
+   *   ③ 排他落位目标（`writeFileExclusive`：目标冒出来就 EEXIST，绝不覆盖）；
+   *   ④ 落位失败 → 把接管的那份**原样还回**归档区；还不动时留在私有名上并点名；
+   *   ⑤ 落位成功后才退役**私有副本** —— 不碰「当前叫 archive/a.md 的那个文件」，
+   *      所以落位之后被写进来的 B 会老老实实留在归档区。
+   *
+   * 崩在中途的代价：`.restoring-` 私有副本会留在归档区（不是 `.md`，扫描 / 注入都不认），
+   * 体检会把它报出来 —— 至少有一份可定位、可恢复的原文。
+   */
+  const takenRes = await takeOverSource(src, sourceBytes, 'restoring')
+  if (!takenRes.ok) {
+    if (takenRes.code === 'not-found') {
+      return { ok: false, code: 'not-archived', error: `sage-mem: not archived: ${safe}（恢复途中源文件消失了）` }
+    }
+    if (takenRes.code === 'move-failed') {
+      const moveErr = takenRes.cause
+      return {
+        ok: false,
+        code: 'move-failed',
+        error: `sage-mem: 恢复 ${safe} 时移不动它（${moveErr?.code ?? moveErr}：${moveErr?.message ?? moveErr}）。文件仍在 archive/ 里、一个字节没动 —— 可稍后重试（若是被其它程序占用，关掉它再来）。`,
+      }
+    }
+    if (takenRes.keptAt) {
+      // 核对时发现是别人的新版本，而原名已被再次占住 —— 新版本留在私有名上，点名给人捞。
+      return {
+        ok: false,
+        code: 'changed',
+        error: `sage-mem: ${safe} 在恢复过程中被改写，已放弃本次恢复；归还时原名已被占用，**内容（新版本）仍保留在 archive/${basename(takenRes.keptAt)}**，请手工改回 ${safe} 再试。`,
+      }
+    }
+    return {
+      ok: false,
+      code: 'changed',
+      error: `sage-mem: ${safe} 在恢复过程中被改写，已放弃本次恢复（新版本保留在归档区原处，请重试）`,
+    }
+  }
   /**
    * **排他落位**（复审 R06 场景②）：上面那句 `dstGate` 检查通过 ≠ 目标此刻仍不存在 ——
    * 检查与写入之间，用户完全可能在顶层新建一条同名记忆（实测用 IPC 固定交错即可复现）。
@@ -256,12 +293,21 @@ export async function restoreMemory(memoryDir, name) {
   try {
     await writeFileExclusive(dst, stripArchiveMeta(content))
   } catch (err) {
+    // 落位没成：接管的归档件必须先还回去 —— 它此刻是这个名字下唯一的一份内容。
+    const back = await returnSource(takenRes.taken, src)
+    if (!back.ok) {
+      return {
+        ok: false,
+        code: 'restore-failed',
+        error: `sage-mem: 恢复 ${safe} 落位失败（${err?.code ?? err}），且归还归档区原名时被占用 —— **内容仍保留在 archive/${basename(back.keptAt)}**，请手工改回 ${safe} 再试。`,
+      }
+    }
     if (err?.code === 'EEXIST') {
       return { ok: false, code: 'target-exists', error: `sage-mem: already exists, refusing to overwrite: ${safe}` }
     }
     throw err
   }
-  await unlink(src)
+  await retireTaken(takenRes.taken)
   /**
    * **注册回索引**：移回文件不等于这条记忆又存在了 —— 索引里没有它，
    * 面板与检索都看不见，体检会报「漏索引」（真实事故见 lib/memory/index-file.js 的头注）。

package/lib/memory/util.js

@@ -2,7 +2,8 @@
  * sage-mem 记忆层 —— 通用小工具：统一日志出口与原子写。
  */
 
-import { link, open, rename, unlink, writeFile } from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
+import { link, open, readFile, rename, rm, unlink, writeFile } from 'node:fs/promises'
 
 /**
  * 统一告警出口。所有非 ENOENT 的失败都必须落到日志，绝不静默
@@ -124,6 +125,77 @@ export async function writeFileExclusive(target, content) {
   return { exclusive }
 }
 
+/**
+ * **事务式接管源文件**：把源 `rename` 到只有本次调用知道的私有名，再逐字节核对
+ * 它是不是调用方读到的那些字节。
+ *
+ * 为什么需要它（2026-10-31 外部审查 Q06 / 复审 R06）：`unlink(名字)` / `rm(名字)`
+ * 只认名字 —— 从「读到内容」到「动手删」之间隔着若干次 IO，别人完全可能在这段时间里
+ * 把那个名字换成新版本，按名删除就会把**从未被收走过的新版本**从唯一的位置抹掉。
+ * `rename` 是原子的：先把源移到私有名上，再对**移走的那份实物**核对内容，
+ * 「名字」与「身份」就解耦了（与 `autodream/gate.js`「抢占过期锁 + 复核 + 还回」同一套手法）。
+ *
+ * ⚠️ 判据必须是**内容**，不能是 `dev:ino + size + mtime`（复审复核实测：原地截断改写 +
+ * 体积刚好相同 + 回写 mtime 会让三元组全部命中，新版本被当成旧版本收走）。内容比对
+ * 成本可忽略 —— 归档 / 恢复本来就要把这份内容读进内存。
+ *
+ * 失败时**绝不直接丢掉**这份内容：
+ *   - 内容对不上 → 用 `link()` 还回原名；原名已被别人占住时，把它留在私有名上并带回路径；
+ *   - 移不动 → 源还在原处、一个字节没动（按真实错误码分流，别谎称「源不存在」）。
+ *
+ * @param {string} from — 源路径
+ * @param {Buffer} expected — 调用方读到的字节
+ * @param {string} tag — 私有名后缀（`archiving` / `restoring`）；体检按它认崩溃残留
+ * @returns {Promise<
+ *   {ok:true, taken:string} |
+ *   {ok:false, code:'not-found'|'move-failed'|'changed', cause?:Error, keptAt?:string}
+ * >}
+ */
+export async function takeOverSource(from, expected, tag) {
+  const taken = `${from}.${tag}-${randomUUID().replace(/-/g, '')}`
+  const moveErr = await rename(from, taken).then(
+    () => null,
+    (err) => err,
+  )
+  if (moveErr) {
+    return { ok: false, code: moveErr?.code === 'ENOENT' ? 'not-found' : 'move-failed', cause: moveErr }
+  }
+  const current = await readFile(taken).catch(() => null)
+  if (current !== null && Buffer.compare(current, expected) === 0) return { ok: true, taken }
+  // 移走的是**别人**的新版本：还回去，一个字节都不动。
+  const back = await returnSource(taken, from)
+  return { ok: false, code: 'changed', ...(back.ok ? {} : { keptAt: back.keptAt }) }
+}
+
+/**
+ * 把 `takeOverSource` 接管的那份**原样**还回原名。
+ *
+ * 还成功时删掉私有副本；原名已被别人占住（`link` 报 EEXIST）或其它原因还不动时，
+ * **绝不删它** —— 它是这份内容唯一的落身处，留在私有名上让人去捞。
+ *
+ * @returns {Promise<{ok:true}|{ok:false,keptAt:string}>}
+ */
+export async function returnSource(taken, to) {
+  const linked = await link(taken, to).then(
+    () => true,
+    () => false,
+  )
+  if (!linked) return { ok: false, keptAt: taken }
+  await rm(taken, { force: true }).catch(() => {})
+  return { ok: true }
+}
+
+/**
+ * 退役一份已经被**成功接管并落位**的私有副本。
+ *
+ * 调用者必须已经确认落位目标拿到了同一份内容：这里删的是私有名，不是任何可能
+ * 已经被别人改过的公开名字 —— 「目标落位后归档源又被写成 B」时，B 住在公开名上，
+ * 这里一个字节都碰不到它。
+ */
+export async function retireTaken(taken) {
+  await rm(taken, { force: true }).catch(() => {})
+}
+
 /**
  * 造一个**进程内串行队列**：同一个队列上的任务一个接一个跑，绝不并发。
  *

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.3",
+  "version": "2.1.5",
   "type": "module",
   "main": "lib/index.js",
   "icon": "./icon.png",