sage-mem 0.9.18 → 0.9.20

package/lib/autodream-tools.js

@@ -29,8 +29,11 @@ import { join, basename } from 'node:path'
 import { createHash } from 'node:crypto'
 import { auditMemoryDir, formatAudit, parseFrontmatterLite } from './autodream-audit.js'
 import { archiveMemory } from './memory/archive.js'
-import { MAX_FILE_BYTES } from './memory/config.js'
+import { MAX_FILE_BYTES, STATE_ROOT } from './memory/config.js'
 import { writeFileAtomic, warnLog } from './memory/util.js'
+import { buildConflict, 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'
 
 /** 单次 read_memory 返回的正文上限（字符）。超过就截断并明确告诉模型。 */
@@ -459,7 +462,112 @@ export function createToolRunner(opts) {
    * @param {'create'|'update'|'archive'} op
    * @param {'model'|'auto'} reasonSource — model = 模型自述；auto = 宿主追溯（模型没给）
    */
-  function changeRecord(op, file, reason, before, after, reasonSource = 'model') {
+  /**
+   * 取宿主的 `fs` 服务，拿不到就返回 null。
+   *
+   * ⚠️ 必须用 `ctx.get('fs')` 而不是 `ctx.fs`：后者在插件没声明 `inject: ['fs']` 时会**抛**
+   * `cannot get property "fs" without inject`（实测，见 docs/host-facts.md）。
+   * 而 sage-mem 有意不声明这个硬依赖 —— 声明了它，没有 fs 服务的宿主上整个插件会一直待机。
+   */
+  function hostFs() {
+    try {
+      const fs = typeof ctx?.get === 'function' ? ctx.get('fs') : undefined
+      return fs && typeof fs.resolve === 'function' && typeof fs.writeText === 'function' ? fs : null
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * 把一次「版本过期」落成一条**待人工判定**的冲突记录。
+   *
+   * 为什么不是「重试」也不是「放弃」：两者都是在替用户决定保留哪一边。
+   * 我们要做的是把这次失败从**一个报错**变成**一条可查询的记录** —— 盘上那份是什么、
+   * 我们想写的是什么，都留下来，让用户在面板里看到再选。
+   *
+   * ⚠️ 这里**吞掉一切异常**：它发生在「写入已经失败」的路径上，再抛一次只会把真正的原因
+   * （`FS_STALE_VERSION`）盖掉。留不下记录就只留日志，绝不改变向外抛的那个错误。
+   */
+  async function recordStaleConflict(fullPath, incoming, err) {
+    try {
+      const fs = hostFs()
+      let onDisk = null
+      // 把盘上那一版也存下来 —— 冲突记录的价值就在「两份都在」，只有一边等于没得判。
+      try {
+        if (fs && typeof fs.readText === 'function') onDisk = await fs.readText(await fs.resolve(fullPath))
+      } catch { /* 读不到就只留我们这一版：宁缺一半，也不要为它把冲突记录整条丢掉 */ }
+      const record = buildConflict({
+        kind: 'stale_version',
+        file: basename(fullPath),
+        expectedVersion: 'unknown',   // 守卫是我们自己按 stat 到的版本构造的，这里拿不到那个字符串
+        actualVersion: String(err?.code ?? ''),
+        incoming,
+        onDisk,
+        note: '自动做梦写入时版本已变化：有人在这份记忆被读入之后改过它',
+        tool: 'write_memory',
+        at: new Date().toISOString(),
+      })
+      await writeConflict(record, { stateRoot: STATE_ROOT })
+    } catch (conflictErr) {
+      warnLog(ctx, `冲突记录没写下来（写入失败的原因不受影响）：${conflictErr?.message ?? conflictErr}`)
+    }
+  }
+
+  /**
+   * 把内容写进一条记忆文件。
+   *
+   * **优先走宿主的 `fs.writeText`**，理由是它同时吃到 `fs/write-intent` 那道**写入门**
+   * （见 `lib/memory/write-gate.js`）：我们自己那套 `writeFileAtomic` **绕过它**。
+   * 绕过意味着 autodream 排在版本守卫之外 —— 而 autodream 恰恰是最可能与用户手动编辑
+   * 撞上的写入者（它在后台跑，用户看不见）。两套写入者之间还能静默互踩，就等于没修。
+   *
+   * ⚠️ **宿主写入失败时绝不回落。** 回落等于「版本守卫拒绝之后我们照样写进去」，
+   * 那把守卫整个作废了，还更糟：它会让失败看起来像成功。失败如实抛给调用方。
+   *
+   * 只有**宿主没有 fs 服务**时才回落（老宿主 / 测试里的假 ctx）——那条路径的行为与改动前
+   * 逐字一致，所以既有断言不受影响。
+   *
+   * @returns {Promise<object|null>} 宿主的 `FsWriteOutcome`；回落时返回 null
+   */
+  async function writeMemoryText(fullPath, content) {
+    const fs = hostFs()
+    if (!fs) {
+      await writeFileAtomic(fullPath, content)
+      return null
+    }
+    const target = await fs.resolve(fullPath)
+    // ⚠️ **守卫必须由我们自己传。** `fs/write-intent` 只为「工具发起」的写入派发，
+    // 插件自己调 `writeText` 时一次都不发（实测）—— 不自己传，这次写入就是**无守卫**的，
+    // 那正是 D4 要避免的漏洞，也是「两套写入者静默互踩」的入口。
+    // 判定表与写门用的是同一个（`write-gate.js`），所以两条路的语义不会漂。
+    let expected
+    if (typeof fs.stat === 'function') {
+      try {
+        const info = await fs.stat(target)
+        expected = decideWriteIntent({
+          memoryPath: memoryPathOf(fullPath, memoryDir),
+          exists: !!info,
+          version: info?.version ?? null,
+          caller: undefined,
+        }).intent
+      } catch {
+        // 探不到就不猜：不传守卫（宿主按默认语义走），也绝不退化成 createIfAbsent ——
+        // 那对**其实存在**的文件是一次误拦。
+        expected = undefined
+      }
+    }
+    try {
+      return await fs.writeText(target, content, expected)
+    } catch (err) {
+      // 版本过期不是「写失败」，是**一次待判定的冲突**：有人在我们读入之后改过这份记忆。
+      // 落一条记录（保留哪边由人决定），然后**照旧把错误抛出去** ——
+      // 静默重试或静默放弃都是在替用户做决定。
+      if (err?.code === 'FS_STALE_VERSION') await recordStaleConflict(fullPath, content, err)
+      throw err
+    }
+  }
+
+  function changeRecord(op, file, reason, before, after, reasonSource = 'model', extra = null) {
     seq += 1
     const at = Date.now()
     changes.push({
@@ -474,6 +582,9 @@ export function createToolRunner(opts) {
       before,
       after,
       deltaBytes: after.bytes - before.bytes,
+      // 这一笔是走宿主 fs 写的、还是回落到本地原子写；走宿主时带**版本**。
+      // 回落时两者都如实写 null —— 不假装知道一个我们其实拿不到的版本。
+      ...(extra && typeof extra === 'object' ? extra : {}),
     })
   }
 
@@ -572,10 +683,9 @@ export function createToolRunner(opts) {
             const reason = typeof a.reason === 'string' ? a.reason.trim() : ''
             const selfReported = reason.length >= MIN_REASON_CHARS
             const before = await fileFingerprint(full)
-            // 原子写：这是**唯一**会把模型生成的内容写进记忆目录的路径。
-            // 直写若崩在中途，留下的是半截 frontmatter —— 文件还在、列表还列得出，
-            // 但解析不出类型与标题，检索与星图同时哑掉。
-            await writeFileAtomic(full, a.content)
+            // 走宿主写入（有 fs 服务时）：原子性由宿主保证，**并且吃到写入门**（见 writeMemoryText）。
+            // 内容闸门上面已按字节判过，这里只关心「写没写进去、写成了什么版本」。
+            const outcome = await writeMemoryText(full, a.content)
             const after = await fileFingerprint(full)
             if (!selfReported) {
               // **不拒绝。** 一次改写缺了缘由，拒掉的代价是这条修正彻底丢失——而它可能
@@ -583,12 +693,17 @@ export function createToolRunner(opts) {
               // 既保住了改动，也让声明里一眼看得出哪些缘由是模型自己说的。
               notes.push(`${basename(full)} 的改动模型没有自述缘由，声明里已标「未自述」并附追溯信息`)            }
             changeRecord(
-              before.exist ? 'update' : 'create',
+              // 宿主给了 operation（create / update）就直接用 —— 它比「看写之前存不存在」更权威：
+              // 那个指纹是我们**自己**在写之前 stat 的，中间还有一道缝。回落时才由指纹推。
+              outcome?.operation === 'create' || outcome?.operation === 'update'
+                ? outcome.operation
+                : (before.exist ? 'update' : 'create'),
               basename(full),
               selfReported ? reason : '',
               before,
               after,
               selfReported ? 'model' : 'auto',
+              { via: outcome ? 'fs' : 'atomic', version: outcome?.version ?? null },
             )
             touched.push(basename(full))
             listCache = null

package/lib/index.js

@@ -29,6 +29,8 @@ 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 { memoryPathOf } from './memory/paths.js'
+import { decideWriteIntent, decideEditGuard } from './memory/write-gate.js'
 import { createMemoryTools } from './tools/memory-tools.js'
 import { archiveMemory, restoreMemory } from './memory/archive.js'
 import { flushAccess, pickArchiveCandidates, readAccessLedger, recordAccess, recordRead } from './memory/access.js'
@@ -271,6 +273,87 @@ export class MemoryGateway extends TypertRemoteService {
       })
     } catch { /* 老宿主没有这个事件：不影响注入 */ }
 
+    // ── 写入门：给记忆目录的写入补上版本守卫 ──
+    //
+    // 实测（`scripts/events-probe.mjs`，本机 headless，2026-10-15）：这两个事件**只对
+    // 「工具发起」的写入**触发 —— 模型调内置 `write` / `edit` 打到记忆文件时会走这里；
+    // 而**插件自己**调 `ctx.fs.writeText` 时一次都不发（实测 0 次），那条路由调用方自己传
+    // `expected`（见 `lib/autodream-tools.js` 的 `writeMemoryText`）。
+    // 监听器**不需要声明 inject** 也能收到，所以这里不挂子 fiber。
+    //
+    // 它买到的东西：**模型的 `write` 没法在一个记忆文件被改过之后静默覆盖它** ——
+    // 守卫过不了，宿主会以 `FS_STALE_VERSION` 明确拒绝（实测确实会被拒）。
+    // 这属于「把静默的坏结果变成显式的失败」，不是「阻止写入」：这个事件**没有拒绝动作**，
+    // 我们也不发明一个（见 write-gate.js 的头注释）。
+    //
+    // 单槽纪律：返回 `undefined` 才是「不管」。目录外**必须**返回 undefined，否则会占掉槽位、
+    // 影响整块盘的写入（write-gate.js 的 `outside_memory` 判在 `caller_wins` 之前正是为此）。
+    /**
+     * 探目标的当前版本。**区分「不存在」与「不知道」**。
+     *
+     * 这个区分不是洁癖：`!!info` 会把「拿不到 fs 服务」也写成 `exists:false`，判定表据此给
+     * `createIfAbsent` —— 而目标**其实是存在的**记忆文件时，那是一次**误拦**（写入必然失败，
+     * 模型收到一句看不懂的错误）。拿不准就不干涉，比猜一个安全。
+     */
+    // ⚠️⚠️ **这段注册必须在 `apply()` 里直接做，绝不能挪进 `ctx.inject(['fs'], …)`，也不能给
+    // 插件加 `static inject = ['fs']`。** 这不是风格偏好，是实测出来的硬约束：
+    // 这两个事件有一个**注册窗口**，窗口在 fs 服务就绪**之前**就关了。
+    //   不 inject、apply 里直接挂     → 收到 1 次 ✅
+    //   顶层 `inject:['fs']`           → **0 次**
+    //   顶层 `inject:['tokenMeter']`   → **0 次**（与 fs 无关，是时机问题）
+    //   `ctx.inject(['fs'], sub)` 子 fiber → **0 次**
+    //   不 inject、但 apply 之后 2.5 秒再挂 → **0 次**（晚挂收不到）
+    // 证据：`scripts/host-facts-probe.mjs` 的七组对照 + `docs/host-facts.md` 3.3 节。
+    // 之所以特别标注：**按 D5 的规范直觉（可选服务要用 ctx.inject 挂子 fiber）改这里，
+    // 会让写门静默失效** —— 编译得过、测试可能也过，只是永远不触发。
+    // 而我们**不需要** inject：实测不声明 inject 时，处理器**内部** `ctx.get('fs')` 照样拿得到服务
+    // （`{hasFs:true, hasStat:true}`），取版本就靠它。
+    const probeTarget = async (target) => {
+      try {
+        const fs = typeof ctx.get === 'function' ? ctx.get('fs') : undefined
+        if (!fs || typeof fs.stat !== 'function' || !target) return { known: false }
+        const info = await fs.stat(target)
+        return { known: true, exists: !!info, version: info?.version ?? null }
+      } catch {
+        return { known: false }
+      }
+    }
+    try {
+      if (typeof ctx.on === 'function') {
+        // 公共骨架：**先判位置、再决定要不要碰链子**。
+        //
+        // ⚠️ 三条纪律（都是踩出来的）：
+        //   1. **目录外连 `next()` 都不调**。宿主对**任何**工具写入都发这个事件（实测：写一个
+        //      临时文件也发），无条件调 next() + stat 等于给整个系统的每次写文件都加一次系统调用，
+        //      而我们本来就什么都不该做。直接 `return next()` 把决策权原样交出去。
+        //   2. **一旦调了 `next()`，就必须把它给的东西交回去**。`next()` 返回的是下游（或调用方
+        //      自己）已经做出的决定；此时再 `return undefined` 会把这个决定**丢掉** ——
+        //      我们本想「不干涉」，实际却比干涉还糟。
+        //   3. **探不到版本就不碰**（见 probeTarget）：把「不知道」当「不存在」会误拦真实存在的文件。
+        const gateEvent = (decide) => async (target, actor, next) => {
+          try {
+            const memoryPath = memoryPathOf(target?.displayPath, MEMORY_DIR)
+            if (!memoryPath.ok) return typeof next === 'function' ? next() : undefined
+            const caller = typeof next === 'function' ? await next() : undefined
+            const probed = await probeTarget(target)
+            if (!probed.known) return caller
+            const chosen = decide({
+              memoryPath,
+              exists: probed.exists,
+              version: probed.version,
+              caller,
+            })
+            // 我们给出决定就用我们的；决定不了（undefined）就把 `caller` 原样交回去，不吞。
+            return chosen === undefined ? caller : chosen
+          } catch {
+            return undefined /* 写门在宿主的写入链路上：抛出去会把一次正常写入炸掉 */
+          }
+        }
+        ctx.on('fs/write-intent', gateEvent((facts) => decideWriteIntent(facts).intent))
+        ctx.on('fs/edit-intent', gateEvent((facts) => decideEditGuard(facts).guard))
+      }
+    } catch { /* 老宿主没有这两个事件：写入按宿主默认语义走 */ }
+
     // 同一轮对话里问题不变、注入内容也不变，但 DSH 每一步都会往 session 追加
     // 一条 context 消息——不去重的话同一份记忆会被反复追加，撑爆上下文。
     const recallCache = new Map()

package/lib/memory/conflicts.js

@@ -0,0 +1,520 @@
+/**
+ * sage-mem 记忆层 —— 冲突队列（`<状态根>/conflicts/<id>.json`）。
+ *
+ * 为什么要有这一层：宿主的文件写入是**原子**的、而且带版本守卫 —— 版本过期会抛
+ * `FS_STALE_VERSION`。所以「冲突」不需要我们去比内容差异，宿主已经把「谁的版本旧了」
+ * 告诉调用方了。我们要做的只有一件事：**把这次失败从「一个报错」变成「一条待判定的记录」**，
+ * 这样用户能在面板上看到「有 N 条冲突等你处理」，而不是让一次静默覆盖把别人的改动吃掉。
+ *
+ * ⚠️ **本模块不做任何自动裁决**。保留磁盘那份 / 保留我的 / 手工合并 —— 由**人**决定，
+ * 插件不猜（自动合并冲突留到 1.0.0 之后）。所以这里只有五个动作：
+ * 落记录（buildConflict / writeConflict）、读一条（readConflict）、列全部（listConflicts）、
+ * 标记状态（resolveConflict）、删除（removeConflict）。**不要在这里加「聪明」的合并逻辑。**
+ *
+ * ⚠️ **冲突正文是用户的记忆内容，本模块永不把它写进日志/控制台**：进终端就等于进日志，
+ * 而这份记录里放的是两份正文。所以本模块**一处 console 都没有**，失败一律用返回值表达。
+ *
+ * 并发：同一个 id 的并发写由**调用方串行**（进程内用 `util.js` 的 `createWriteQueue`）；
+ * 不同 id 互不影响（一个 id 一个文件）。本模块自己只保证每次写是原子的。
+ */
+
+import { createHash } from 'node:crypto'
+import { mkdir, readdir, readFile, unlink } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { STATE_ROOT } from './config.js'
+import { writeFileAtomic } from './util.js'
+
+/** 冲突记录都放在状态根的这个子目录下。 */
+export const CONFLICTS_DIR_NAME = 'conflicts'
+
+/** 一条冲突一个文件。 */
+export const CONFLICT_FILE_SUFFIX = '.json'
+
+/**
+ * 冲突的种类。`stale_version` 是宿主版本守卫直接报出来的那种（最常见）；
+ * `external_change` 是文件在别处被改了；`unresolved_merge` 是人工合并到一半留下的。
+ */
+export const CONFLICT_KINDS = Object.freeze(['stale_version', 'external_change', 'unresolved_merge'])
+
+/**
+ * 记录的状态。`open` 是唯一「待处理」的状态；另外两种都是人的判断结果，
+ * 区别只在语义（`resolved` = 处理过了，`dismissed` = 看过、决定不管）。
+ */
+export const CONFLICT_STATUSES = Object.freeze(['open', 'resolved', 'dismissed'])
+
+/**
+ * 单份冲突记录的体积上限（字节）。
+ *
+ * 定 256 KB：一份记录里要放**两份**正文（我的版本 + 磁盘上的版本），所以它天生比记忆大；
+ * 但再大就不该整份塞进上下文了 —— 到量说明该人工合并，而不是把两份都留着。
+ */
+export const CONFLICT_MAX_BYTES = 256 * 1024
+
+/**
+ * 各字段的单字段字节上限（**数据表**而不是散落的魔法数：面板与文档要能展示凭什么是这个数）。
+ *
+ * 为什么要「上限之外另有一条」：整个记录的上限（256 KB）管不住**一个字段**把预算吃光 ——
+ * 一份 200 KB 的 `incoming` 能挤掉 `onDisk`，而后者恰恰是判定冲突时最需要对照的那份。
+ * 所以两个正文字段各自先卡 48 KB（两份共 96 KB，还有一半留给元信息与 JSON 转义），
+ * 小字段给到只够装下它们的量级。超了就**截断头部**并置 `truncated: true`。
+ */
+export const CONFLICT_FIELD_LIMITS = Object.freeze({
+  incoming: 48 * 1024,
+  onDisk: 48 * 1024,
+  file: 1024,
+  note: 4096,
+  tool: 256,
+  version: 256,
+})
+
+/**
+ * 状态机（**数据**，不是 if 链：面板要能显示「这一步能不能点」，断言也要能逐条核对）。
+ *
+ * `open → resolved` / `open → dismissed` / `resolved ↔ dismissed` 允许；
+ * **不许从 `resolved`/`dismissed` 回到 `open`** —— 那等于把一条已经做过判断的记录
+ * 悄悄复活成「待处理」，而判断的理由不在记录里，复活后没人知道当初为什么关掉它。
+ * 要重开就新建一条（带上新的证据）。
+ */
+export const CONFLICT_TRANSITIONS = Object.freeze({
+  open: Object.freeze(['resolved', 'dismissed']),
+  resolved: Object.freeze(['dismissed']),
+  dismissed: Object.freeze(['resolved']),
+})
+
+/**
+ * 冲突 id 允许的字符集：单段、`[A-Za-z0-9-]`、1..64 字符。
+ *
+ * 字符集里**根本没有** `.`、`/`、`\`、`:` —— 前三个是路径语义（`.` 的尾随形态还会被 Windows
+ * 静默吃掉），`:` 在 NTFS 上是交替数据流的分隔符。判定走纯字符类、**不走 `path.basename`**：
+ * `\` 在 Windows 是分隔符、在 Linux 只是普通字符，用平台 API 判会得出「同一份输入在两个平台上
+ * 合法性相反」的结论（本仓库刚被 Linux CI 抓过同类缺陷）。这里的判据两个平台逐字一致。
+ */
+const CONFLICT_ID_RE = /^[A-Za-z0-9-]{1,64}$/
+
+/**
+ * Windows 保留设备名：`conflicts/CON.json` 在这个平台上**建不出来**（设备名带扩展名同样保留），
+ * Linux 上完全正常 —— 同一份状态目录同步过去就会「在那边能写、在这边写不了」。
+ *
+ * 同一份判据 `checkpoint.js` 里也有一份：两个模块各守自己的 id 空间，为此去动 `lib/` 加一个
+ * 共享文件等于引入跨模块耦合，而表本身很小 —— 重复比耦合便宜。
+ */
+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 normalizeConflictId(raw) {
+  if (typeof raw !== 'string') return null
+  if (!CONFLICT_ID_RE.test(raw)) return null
+  // 纯点号（`.` / `..`）与尾随点在这里已经被字符集挡掉了（字符集不含 `.`），
+  // 但下面这条**设备名**判据必须在：`con` / `com1` 全是合法字符，却是 Windows 的保留名。
+  if (WINDOWS_RESERVED.has(raw.toLowerCase())) return null
+  return raw
+}
+
+/** stateRoot 的归一：非空字符串才用，否则回落 config.js 的 STATE_ROOT。 */
+function rootOf(stateRoot) {
+  return typeof stateRoot === 'string' && stateRoot !== '' ? stateRoot : STATE_ROOT
+}
+
+/** 冲突目录。 */
+function conflictsDir(stateRoot) {
+  return join(rootOf(stateRoot), CONFLICTS_DIR_NAME)
+}
+
+/** 一条冲突的文件路径；调用方必须先过 `normalizeConflictId`。 */
+function conflictPathFor(id, stateRoot) {
+  return join(conflictsDir(stateRoot), `${id}${CONFLICT_FILE_SUFFIX}`)
+}
+
+/**
+ * 按**码点**截断到不超过 maxBytes 字节。
+ *
+ * 不能按字符数截（`s.slice(0, N)`）：一个汉字 3 字节，按字符截出来的东西是预算的三倍，
+ * 闸门等于没设。也不能按字节硬切：那会把一个码点切成半个，注入 / 面板上显示成 U+FFFD。
+ */
+function truncateByBytes(s, maxBytes) {
+  const text = String(s ?? '')
+  if (Buffer.byteLength(text, 'utf8') <= maxBytes) return text
+  let out = ''
+  let used = 0
+  for (const ch of text) {
+    const b = Buffer.byteLength(ch, 'utf8')
+    if (used + b > maxBytes) break
+    out += ch
+    used += b
+  }
+  return out
+}
+
+/** 单字段限长。非字符串按「缺」处理（不去猜一个对象 / Buffer 的内容）。 */
+function clampText(value, limit) {
+  if (typeof value !== 'string') return { text: '', cut: false }
+  if (Buffer.byteLength(value, 'utf8') <= limit) return { text: value, cut: false }
+  return { text: truncateByBytes(value, limit), cut: true }
+}
+
+/** 版本号一律当字符串用（`undefined` / `null` = 没有这个版本，不是字符串 "null"）。 */
+function versionText(value) {
+  return value === undefined || value === null ? '' : String(value)
+}
+
+/** 时间戳归一：认得出才用，认不出就是空串（**不编一个时间**）。 */
+function normalizeAt(raw) {
+  if (typeof raw !== 'string' || raw === '') return ''
+  return Number.isFinite(Date.parse(raw)) ? raw : ''
+}
+
+/** 把时间戳压成 id 里能用的紧凑形态：`2026-10-15T19:47:54.000Z` → `20261015T194754Z`。 */
+function compactStamp(at) {
+  const ms = Date.parse(at)
+  if (!Number.isFinite(ms)) return ''
+  return new Date(ms).toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z')
+}
+
+/**
+ * 内容指纹（8 位十六进制）。
+ *
+ * 这里**刻意不用随机数**，虽然接口注释写的是「时间戳 + 短随机」：
+ *   1. 随机数会让「同输入两次结果一致」不成立 —— 一个从「写失败」造记录的纯函数不该读随机源；
+ *   2. 指纹还有个更好的性质：**同一条冲突被重复上报时 id 相同**，队列里不会长出重复项。
+ * 指纹取的是「这次冲突是什么」的字段（种类 / 文件 / 两个版本 / 两份正文），不含 `note` / `tool`
+ * 这类关于「谁在什么时候碰上的」的元信息 —— 换一次说明不该变成另一条冲突。
+ */
+function shortDigest(parts) {
+  const canonical = parts.map((p) => String(p ?? '')).join('\u0000')
+  return createHash('sha256').update(canonical, 'utf8').digest('hex').slice(0, 8)
+}
+
+/**
+ * 从「一次写失败」造一条记录（**纯函数**：不落盘、不读时钟、不掷随机数）。
+ *
+ * 时间与 id 从输入来：`at` 给定了就是逐字确定、可重放的结果；不给 `at` 就是空串
+ * （id 也就没有时间戳前缀）。**不自己读时钟**是刻意的 —— 时间是调用方的事实
+ * （只有它知道这次过期发生在何时），编一个「现在」会让重放与去重都失效。
+ * `id` 也可以直接传（面板要指定 id 时用），非法就按内容指纹现算。
+ *
+ * 截断：各字段按 `CONFLICT_FIELD_LIMITS` 卡字节，截过就置 `truncated: true`。
+ *
+ * @param {{kind?, file?, expectedVersion?, actualVersion?, incoming?, onDisk?, note?, tool?, at?, id?}} input
+ */
+export function buildConflict(input) {
+  const src = input && typeof input === 'object' ? input : {}
+
+  const at = normalizeAt(src.at)
+  // 不认识的 kind **原样保留**：静默换成某个已知值等于把「未知」伪装成「已知」。
+  const kind = typeof src.kind === 'string' ? src.kind : ''
+
+  const file = clampText(src.file, CONFLICT_FIELD_LIMITS.file)
+  const incoming = clampText(src.incoming, CONFLICT_FIELD_LIMITS.incoming)
+  const onDisk = clampText(src.onDisk, CONFLICT_FIELD_LIMITS.onDisk)
+  const note = clampText(src.note, CONFLICT_FIELD_LIMITS.note)
+  const tool = clampText(src.tool, CONFLICT_FIELD_LIMITS.tool)
+  const expectedVersion = clampText(versionText(src.expectedVersion), CONFLICT_FIELD_LIMITS.version)
+  const actualVersion = clampText(versionText(src.actualVersion), CONFLICT_FIELD_LIMITS.version)
+
+  const truncated =
+    file.cut || incoming.cut || onDisk.cut || note.cut || tool.cut || expectedVersion.cut || actualVersion.cut
+
+  const stamp = compactStamp(at)
+  const digest = shortDigest([kind, file.text, expectedVersion.text, actualVersion.text, incoming.text, onDisk.text])
+  const id = normalizeConflictId(src.id) ?? `${stamp === '' ? '' : `${stamp}-`}${digest}`
+
+  return {
+    v: 1,
+    id,
+    kind,
+    status: 'open',
+    file: file.text,
+    expectedVersion: expectedVersion.text,
+    actualVersion: actualVersion.text,
+    at,
+    incoming: incoming.text,
+    onDisk: onDisk.text,
+    note: note.text,
+    tool: tool.text,
+    truncated,
+  }
+}
+
+/** 记录 → 文件正文。紧凑 JSON + 一个尾换行：状态目录是给程序读的，行数少一点更好 diff。 */
+function serialize(record) {
+  try {
+    return `${JSON.stringify(record)}\n`
+  } catch {
+    // 循环引用 / BigInt 会让 JSON.stringify 抛 —— 契约要求「所有失败都返回对象」，所以在这里收住。
+    return null
+  }
+}
+
+/**
+ * 整份记录超上限时，按字节削两个正文字段（两份都保留**头部**，只削当前最大的那份）。
+ *
+ * 为什么要迭代而不是一次算准：JSON 转义会让同一段文本的落盘字节数变多（引号、反斜杠、
+ * 控制字符最多膨胀到 6 倍），所以「预算」只能边算边收。步数有界：每轮至少削 1 字节，
+ * 削到两个字段都空还放不下就放弃（返回 null，由调用方报 too_big，绝不静默写半份）。
+ */
+function fitBodies(record, limit) {
+  const bodyOf = (k) => (typeof record[k] === 'string' ? record[k] : '')
+  const originals = [bodyOf('incoming'), bodyOf('onDisk')]
+  const keep = originals.map((s) => Buffer.byteLength(s, 'utf8'))
+  for (let round = 0; round < 128; round++) {
+    const trial = {
+      ...record,
+      incoming: truncateByBytes(originals[0], keep[0]),
+      onDisk: truncateByBytes(originals[1], keep[1]),
+      truncated: true,
+    }
+    const text = serialize(trial)
+    if (text === null) return null
+    const bytes = Buffer.byteLength(text, 'utf8')
+    if (bytes <= limit) return text
+    // 每轮只削**当前最大的**那个正文字段：撑爆预算的是大的那份；两份一起削会把短的那份
+    // 先削没，而短的那份往往正是用户想保留的 `incoming`。两份都空了还放不下 = 放弃。
+    let largest = -1
+    for (let i = 0; i < keep.length; i++) {
+      if (keep[i] > 0 && (largest === -1 || keep[i] > keep[largest])) largest = i
+    }
+    if (largest === -1) return null
+    keep[largest] = Math.max(0, keep[largest] - Math.max(1, Math.ceil((bytes - limit) / 2)))
+  }
+  return null
+}
+
+/**
+ * 落盘一条冲突记录（原子写，复用 `util.js` 的 `writeFileAtomic`）。
+ *
+ * ⚠️ **并发：同一个 id 由调用方串行**（进程内 `createWriteQueue`）—— 本模块不做锁，
+ * 因为跨进程锁的成本与误伤面都不划算，而真实并发都发生在同一个插件进程里。不同 id
+ * 各写各的文件，互不影响。
+ *
+ * 超 `CONFLICT_MAX_BYTES` 时**按字节截断两个正文字段**并置 `truncated: true`（而不是拒收：
+ * 一条被截断的冲突记录仍然是人可以判定的，一份写不进去的记录才是真的丢了）。
+ * 只有「削完正文还放不下」（元信息本身畸形地大）才报 `too_big`。
+ *
+ * 本函数**不校验记录的内容**（除了 id —— 路径需要它）：校验的落点在读的那一端，
+ * 写路径只守体积与原子性。
+ *
+ * @param {object} record
+ * @param {{stateRoot?: string}} [opts]
+ * @returns {Promise<{ok:true, bytes:number, path:string, truncated:boolean}
+ *   | {ok:false, code:'invalid'|'too_big'|'io_error', ...}>}
+ */
+export async function writeConflict(record, opts) {
+  if (record === null || typeof record !== 'object' || Array.isArray(record)) {
+    return { ok: false, code: 'invalid', error: '冲突记录必须是一个对象' }
+  }
+  const id = normalizeConflictId(record.id)
+  if (id === null) return { ok: false, code: 'invalid', error: `冲突 id 非法：${JSON.stringify(record.id)}` }
+
+  const path = conflictPathFor(id, opts && typeof opts === 'object' ? opts.stateRoot : undefined)
+
+  let text = serialize(record)
+  if (text === null) return { ok: false, code: 'invalid', error: '冲突记录无法序列化（循环引用或非法值）' }
+  let truncated = record.truncated === true
+  if (Buffer.byteLength(text, 'utf8') > CONFLICT_MAX_BYTES) {
+    const fitted = fitBodies(record, CONFLICT_MAX_BYTES)
+    if (fitted === null) {
+      return {
+        ok: false,
+        code: 'too_big',
+        bytes: Buffer.byteLength(text, 'utf8'),
+        limit: CONFLICT_MAX_BYTES,
+        error: `冲突记录超过 ${CONFLICT_MAX_BYTES} 字节，且削完两个正文字段仍放不下`,
+      }
+    }
+    text = fitted
+    truncated = true
+  }
+
+  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: Buffer.byteLength(text, 'utf8'), path, truncated }
+}
+
+/**
+ * 解析一条记录的正文。形状不对就报原因 —— 判据是「读不读得出这是哪条冲突」：
+ * 必须有非空 `id`，`status` 必须是已知状态。`kind` 允许未知（老记录 / 别处写的记录照读）。
+ */
+function parseConflictText(text) {
+  let obj
+  try {
+    obj = JSON.parse(text)
+  } catch (err) {
+    return { ok: false, reason: `JSON 解析失败：${err?.message ?? err}` }
+  }
+  if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) return { ok: false, reason: '不是一个 JSON 对象' }
+  if (typeof obj.id !== 'string' || obj.id === '') return { ok: false, reason: '缺少 id' }
+  if (!CONFLICT_STATUSES.includes(obj.status)) {
+    return { ok: false, reason: `status 不是已知状态：${JSON.stringify(obj.status)}` }
+  }
+  return { ok: true, record: obj }
+}
+
+/**
+ * 读一条冲突记录。**所有失败都返回对象，绝不抛**。
+ *
+ * 文件名才是身份：文件里声明的 id 与文件名不一致时，以文件名为准并给出警告
+ * （不静默采信标签，也不把整条记录判成坏 —— 内容还在，人还能判定）。
+ *
+ * @returns {Promise<{ok:true, path, bytes, record, warnings:string[]}
+ *   | {ok:false, code:'invalid'|'missing'|'io_error'|'malformed', path?, error}>}
+ */
+export async function readConflict(id, opts) {
+  const cid = normalizeConflictId(id)
+  if (cid === null) return { ok: false, code: 'invalid', error: `冲突 id 非法：${JSON.stringify(id)}` }
+
+  const path = conflictPathFor(cid, 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 = parseConflictText(text)
+  if (!parsed.ok) return { ok: false, code: 'malformed', path, error: parsed.reason }
+
+  const record = { ...parsed.record, id: cid }
+  const warnings = []
+  if (parsed.record.id !== cid) {
+    warnings.push(`文件内声明的冲突 id（${parsed.record.id}）与文件名（${cid}）不一致，已按文件名归一`)
+  }
+  return { ok: true, path, bytes: Buffer.byteLength(text, 'utf8'), record, warnings }
+}
+
+/** 稳定比较：不用 localeCompare（它跟 ICU 走，跨环境可能给出不同顺序）。 */
+function cmp(a, b) {
+  const x = String(a ?? '')
+  const y = String(b ?? '')
+  return x < y ? -1 : x > y ? 1 : 0
+}
+
+/**
+ * 列出全部冲突（只读目录）。
+ *
+ * 一个坏文件**绝不能**让整张列表打不开 —— 那等于「有一条冲突坏了，面板上什么都看不见」。
+ * 所以坏文件只记名字进 `broken`，能读的照列；非 `.json` 的文件（编辑器临时文件、别的模块的垃圾）
+ * 进 `ignored`，一样报告出来但不当成冲突。
+ *
+ * 目录不存在**不是错误**（还没发生过冲突）：返回空列表。
+ *
+ * @returns {Promise<{ok:true, items:Array, broken:string[], ignored:string[], dir:string}
+ *   | {ok:false, code:'io_error', dir, error}>}
+ */
+export async function listConflicts(opts) {
+  const dir = conflictsDir(opts && typeof opts === 'object' ? opts.stateRoot : undefined)
+  let names
+  try {
+    names = await readdir(dir)
+  } catch (err) {
+    if (err?.code === 'ENOENT') return { ok: true, items: [], broken: [], ignored: [], dir }
+    return { ok: false, code: 'io_error', dir, error: String(err?.message ?? err) }
+  }
+
+  const items = []
+  const broken = []
+  const ignored = []
+  // readdir 的顺序不保证：先排序，让 broken / ignored 这两个「报告用」的数组也逐次一致。
+  for (const name of [...names].sort(cmp)) {
+    if (!name.endsWith(CONFLICT_FILE_SUFFIX)) {
+      ignored.push(name)
+      continue
+    }
+    const id = name.slice(0, -CONFLICT_FILE_SUFFIX.length)
+    if (normalizeConflictId(id) === null) {
+      broken.push(name)
+      continue
+    }
+    let text
+    try {
+      text = await readFile(join(dir, name), 'utf8')
+    } catch {
+      broken.push(name)
+      continue
+    }
+    const parsed = parseConflictText(text)
+    if (!parsed.ok) {
+      broken.push(name)
+      continue
+    }
+    items.push({ ...parsed.record, id })
+  }
+
+  // 新的在前（队列的第一眼应该是最新那条）；没有 at 的排在后面，同档按 id 排，保证顺序确定。
+  items.sort((a, b) => cmp(String(b.at ?? ''), String(a.at ?? '')) || cmp(a.id, b.id))
+  return { ok: true, items, broken, ignored, dir }
+}
+
+/**
+ * 改状态并落盘。
+ *
+ * 状态机见 `CONFLICT_TRANSITIONS`：`open` 只能去 `resolved` / `dismissed`，那两个之间可以互转，
+ * **都不许回到 `open`**（要重开就新建一条）。同状态重复点是**幂等**的 —— 界面上连点两下
+ * 不该报错，也不重写文件。
+ *
+ * @returns {Promise<{ok:true, record:object} | {ok:false, code:'invalid'|'invalid_transition'|'missing'|'malformed'|'io_error', error?}>}
+ */
+export async function resolveConflict(id, status, opts) {
+  const cid = normalizeConflictId(id)
+  if (cid === null) return { ok: false, code: 'invalid', error: `冲突 id 非法：${JSON.stringify(id)}` }
+  if (!CONFLICT_STATUSES.includes(status)) {
+    return { ok: false, code: 'invalid', error: `未知状态：${JSON.stringify(status)}` }
+  }
+
+  const read = await readConflict(cid, opts)
+  if (!read.ok) return { ok: false, code: read.code, error: read.error }
+
+  const from = read.record.status
+  if (from === status) return { ok: true, record: read.record }
+  const allowed = CONFLICT_TRANSITIONS[from] ?? []
+  if (!allowed.includes(status)) {
+    return {
+      ok: false,
+      code: 'invalid_transition',
+      error: `${from} → ${status} 不被允许（已判定过的记录不许回到 open，要重开请新建一条）`,
+    }
+  }
+
+  const next = { ...read.record, status }
+  const written = await writeConflict(next, opts)
+  if (!written.ok) return { ok: false, code: written.code, error: written.error }
+  return { ok: true, record: next }
+}
+
+/**
+ * 删一条（清理）。
+ *
+ * 刻意**不看状态**：拦截「删掉一条还没处理的冲突」是面板的确认动作，不是数据层的事 ——
+ * 数据层再拦一道只会让「用户明确要删」变成删不掉。文件不存在 → `missing`。
+ *
+ * @returns {Promise<{ok:true, path:string} | {ok:false, code:'invalid'|'missing'|'io_error', path?, error}>}
+ */
+export async function removeConflict(id, opts) {
+  const cid = normalizeConflictId(id)
+  if (cid === null) return { ok: false, code: 'invalid', error: `冲突 id 非法：${JSON.stringify(id)}` }
+
+  const path = conflictPathFor(cid, opts && typeof opts === 'object' ? opts.stateRoot : undefined)
+  try {
+    await unlink(path)
+  } 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) }
+  }
+  return { ok: true, path }
+}

package/lib/memory/observe.js

@@ -49,6 +49,11 @@
  * - `dir` = **规范化后的绝对路径**，只在「值指向记忆目录里的一个目录（含记忆目录本身）」时给出。
  */
 
+// 路径身份判据**抽到 paths.js 共用**：写入门（write-gate.js）要回答同一个问题
+// 「这个路径在不在记忆目录里」。两处各写一份迟早漂成两套判据，而漂移的后果不是报错，
+// 是「看起来很勤快、实际判错了对象」。注意 paths.js 同样不依赖 node:path。
+import { canonicalPathOf, isSameOrInside, fileNameOf, isRootLike } from './paths.js'
+
 /** 认得的读工具 → 取路径的参数名。表是**数据**：调用方与测试都直接读它，不写第二份分支。 */
 export const READ_TOOLS = Object.freeze({ read: 'file_path', grep: 'path', glob: 'path' })
 
@@ -76,80 +81,6 @@ 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 }

package/lib/memory/paths.js

@@ -0,0 +1,103 @@
+/**
+ * sage-mem 记忆层 —— **路径身份**的唯一基准（归一 + 包含判定）。
+ *
+ * 为什么要有这个文件：观测（`observe.js`）与写入门（`write-gate.js`）都要回答同一个问题 ——
+ * 「这个路径在不在记忆目录里」。两处各写一份，迟早漂成两套判据；而那类漂移的后果不是报错，
+ * 是**看起来很勤快、实际判错了对象**（`access.js` 的「扫 A 目录写 B 台账」就是这一类）。
+ * 与 `naming.js`（文件名身份基准）同一个思路，只是这里管的是路径。
+ *
+ * ⚠️ **判据只依赖输入的形状，绝不依赖 `path.sep` / `path.resolve`。**
+ * `path.resolve` 在 Windows 上把 `\` 当分隔符、在 Linux 上不当，于是同一份输入在两个平台上
+ * 得到不同结论 —— 而记忆目录是会被同步 / 拷贝 / 备份还原的。本仓库已经因此被 Linux CI 抓过
+ * 一次（`safeName` 的 `basename` 判据），不要再犯同一类。
+ */
+
+/**
+ * 把路径归一成规范形式；**不是绝对路径就返回 null**（调用方一律按「不认」处理）。
+ *
+ * 规则：只接受绝对路径（`/…`、`//server/share…`、`X:/…`）→ `\` 与 `/` **一律**当分隔符 →
+ * 折叠 `.`、连续分隔符与逐段回退 `..`（绝对路径在根上的 `..` 是空操作）→ 盘符小写 →
+ * 其余**大小写敏感**。不做磁盘解析，所以符号链接意义上的「真实位置」不保证被还原。
+ */
+export 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`。
+ *
+ * 判据是「父目录 + 分隔符」，不是裸字符串前缀 —— 裸前缀正是那个经典陷阱。
+ */
+export function isSameOrInside(parent, child) {
+  if (parent === child) return true
+  const boundary = parent.endsWith('/') ? parent : `${parent}/`
+  return child.startsWith(boundary)
+}
+
+/** 规范路径的最后一段（要文件名而不是路径时用它）。 */
+export function fileNameOf(canon) {
+  const cut = canon.lastIndexOf('/')
+  return cut < 0 ? canon : canon.slice(cut + 1)
+}
+
+/**
+ * 根目录不算记忆目录。
+ *
+ * 拿根（`/`、`//`、`X:/`）做包含判定，等于把整块盘都算成记忆 —— 一条配置写错就能把台账
+ * 灌满「读了别处」的记录，或者把整个盘的写入都套上守卫。宁可不判。
+ */
+export function isRootLike(canon) {
+  return canon === '/' || canon === '//' || /^[a-z]:\/$/.test(canon)
+}
+
+/**
+ * 一步到位：这个路径是不是**记忆目录里的**条目（含目录本身时 `includeSelf` 决定）。
+ *
+ * 三条拒绝理由都返回 `{ok:false, why}` 而不是抛 —— 调用方在事件回调里，抛出去会打断
+ * 宿主的写入链路。
+ *
+ * @returns {{ok:true, canon:string, name:string} | {ok:false, why:string}}
+ */
+export function memoryPathOf(raw, memoryDir, opts = {}) {
+  const canon = canonicalPathOf(raw)
+  if (canon === null) return { ok: false, why: '不是绝对路径（相对路径的真实落点取决于运行时状态，不猜）' }
+  const root = canonicalPathOf(memoryDir)
+  if (root === null) return { ok: false, why: '记忆目录本身不是绝对路径' }
+  if (isRootLike(root)) return { ok: false, why: '记忆目录是文件系统根：不做包含判定' }
+  if (!isSameOrInside(root, canon)) return { ok: false, why: '路径不在记忆目录内' }
+  if (canon === root) return opts.includeSelf ? { ok: true, canon, name: '' } : { ok: false, why: '目标是记忆目录本身' }
+  return { ok: true, canon, name: fileNameOf(canon) }
+}

package/lib/memory/write-gate.js

@@ -0,0 +1,193 @@
+/**
+ * sage-mem 记忆层 —— 写入门：给记忆目录的写入补上**版本守卫**。
+ *
+ * ## 它为什么存在
+ *
+ * 宿主的 `fs/write-intent` / `fs/edit-intent` 会**在写入之前**问插件一次：「这次写入按什么
+ * 意图做」。没有插件回答时，一次「读-改-写」之间只要有人插进来写过，后写的那个就**静默**
+ * 把前一个覆盖掉 —— 谁也不报错，谁也不知情。
+ *
+ * 本模块的回答是：目标在记忆目录内、且我们已经知道它的当前版本时，把这次写入钉在
+ * `replaceIfVersion(当前版本)` 上。于是并发写入不再互踩，而是由宿主报出 `FS_STALE_VERSION`，
+ * 交给上层（冲突队列 / 人）决定怎么办。
+ *
+ * ## ⚠️ 两个事件都**没有「拒绝」这个动作**
+ *
+ * 它们是**单槽意图决策**：只能决定写入**意图**（`createIfAbsent` / `replaceIfVersion`）或编辑
+ * **守卫**（`{version}`），不能阻止写入。所以这里**没有 deny、没有 null、没有抛错**——
+ * 只有「给意图」「给守卫」和「不管」（返回 `undefined`）。唯一的失败信号是宿主自己报的
+ * `FS_STALE_VERSION`，我们只需保证它报得出来。
+ *
+ * ## ⚠️ 这个事件只覆盖「工具发起的写入」（真实 headless 宿主实测）
+ *
+ * 宿主对这两个事件的派发范围比直觉窄：
+ *
+ * - **模型调内置 `write` / `edit`** 时派发（实测 `fs/write-intent = 1`：模型用 `write` 写了一个
+ *   临时文件；监听器不需要声明 `inject` 也能收到，与 sage-mem 主插件的处境一致）。
+ * - **插件自己调 `ctx.fs.writeText` / `editText` 时一次都不派发**（实测 0）。所以 autodream
+ *   那类**插件内部写入不经过这里**，本模块也不假装能兜底它 —— 那条路由调用方自己传
+ *   `expected`（`lib/autodream-tools.js` 就是这么做的）。
+ *
+ * 由此两条硬结论：
+ *
+ * 1. 这道门**确实拦得到**「模型直接改记忆文件」的写入 —— 这是它存在的意义，不是空想。
+ * 2. 宿主的派发范围是**整个盘**（实测那一次的目标就在记忆目录之外），所以 `facts.memoryPath`
+ *    的过滤是**唯一**一道屏障：没有它，我们就会去干涉整个盘的写入。这就是判定表把
+ *    `outside_memory` 排在第一位、且必须返回 `undefined` 的原因。
+ *
+ * ⚠️ **集成侧的放行方式**：本模块给出 `undefined`（不管）时，监听器应当 `return next()` 把链
+ * 放下去，**不要只计数不返回** —— 实测 `ctx.on(waterfallEvent, () => count++)` 会让宿主拿到
+ * `undefined` 后去读它的 `.contexts`，整轮对话崩在 `Cannot read properties of undefined
+ * (reading 'contexts')`。本模块不做订阅，只算结论。
+ *
+ * ## 判定表（顺序即优先级）
+ *
+ * | 条件 | reason | 返回 |
+ * |---|---|---|
+ * | 不是记忆目录里的路径（含目录本身、相对路径、根目录） | `outside_memory` | `undefined` |
+ * | 调用方自己已经给了意图 / 守卫 | `caller_wins` | **原样透传**（同一个对象，不复制不改写） |
+ * | 明确知道目标不存在（`exists === false`） | `created` | 写入：`createIfAbsent`；编辑：无守卫 |
+ * | 不确知存在（`exists` 缺失 / 非布尔）且拿不到版本 | `no_version` | 写入：`createIfAbsent`；编辑：无守卫 |
+ * | 存在且有版本 | `guarded` | 写入：`replaceIfVersion(版本)`；编辑：`{version: 版本}` |
+ * | 其余（存在但没有可用的版本等） | `unknown` | `undefined`（**不猜**） |
+ *
+ * ## 三个容易做反的地方（都写进了断言）
+ *
+ * 1. **`outside_memory` 判在最前面，连「调用方给了什么」都不看。**
+ *    单槽的含义是「第一个返回值的监听器拥有决策权」——所以在目录外**返回任何值**（哪怕只是
+ *    原样回传调用方的意图）都会把这个槽占掉，后面的监听器再没有机会。只有返回 `undefined`
+ *    才是字面意义上的「整个盘的其它写入完全不受影响」。目录内才轮到「尊重调用方」。
+ * 2. **存在但没有版本 → `unknown`，绝不退化成 `createIfAbsent`。**
+ *    这两件事的行为完全不同：`replaceIfVersion` 是「覆盖这份内容，除非它已经变了」，
+ *    `createIfAbsent` 是「只在它不存在时才写」。退化等于把一次覆盖悄悄变成一次「已存在就失败」，
+ *    而调用方拿到的理由会是错的。
+ * 3. **版本是不透明值**：不解析、不比较大小、不当数字用，只做「是不是非空字符串」的形状检查
+ *    然后**原样**放进意图里。宿主给什么就是什么。
+ *
+ * ## ⚠️ `exists` 必须是**观测到的**事实，不是回落值（接线实测踩到过）
+ *
+ * `exists !== true` 那条分支给的是 `createIfAbsent` —— 它是这里唯一不可能**静默覆盖**的意图，
+ * 但目标其实存在时它是一次**误拦**：写入必然失败，而调用方（模型）拿到的是一个它无从理解的
+ * 错误，它本来只是想改一份自己刚读过的记忆。
+ *
+ * 生产接线踩到的正是这里：原来写成 `exists: !!info`，于是「没有 `fs` 服务 / stat 抛错」这种
+ * **探不到**被压成了 `false` —— 一个看起来像事实的回落值，与 `access.js` 那次「扫 A 目录写 B
+ * 台账」属于同一类错误。
+ *
+ * 所以：`exists: false` 只允许表示「**明确探到不存在**」（stat 的 ENOENT）。**探不到**不是
+ * `false`，是「不知道」—— 那种情况**不要调用本模块**，接线应自行短路成「不碰」（生产路径
+ * `lib/index.js` 就是这么做的：探不到就把调用方的意图原样交回）。判定表对「调用方没给
+ * `exists`」仍然有确定的答案（`no_version`，见下），但那是**契约的确定性**，不是鼓励拿
+ * 「不知道」去换一个意图。
+ *
+ * `facts.toolWrite`（是否来自内置 `write` / `edit` 工具）**不参与判定**：判据只有四个
+ * 「在不在目录内 / 确不确知存在 / 有没有版本 / 调用方给没给」。把「谁在写」也变成分支，
+ * 就是同一件事的第二套判据。它留在 facts 里供调用方记录与排查。
+ *
+ * 路径判据一律走 `paths.js`（与 `observe.js` 同一个函数），**本模块不写第二份**。
+ */
+
+import { memoryPathOf } from './paths.js'
+
+export const GATE_REASONS = Object.freeze([
+  'outside_memory', // 目标不在记忆目录内 → 不管
+  'no_version', // 目标不存在且拿不到版本 → createIfAbsent
+  'created', // 目标不存在 → createIfAbsent
+  'guarded', // 目标存在 → replaceIfVersion(version)
+  'caller_wins', // 调用方自己已经给了意图/守卫 → 原样透传（**尊重调用方**）
+  'unknown', // 信息不足 → 返回 undefined（不猜）
+])
+
+/** 目标位置的三种结论：在目录内 / 不在目录内 / 说不清。 */
+function locationOf(facts) {
+  const mp = facts.memoryPath
+  // 主契约：调用方已经把 paths.js 的 memoryPathOf 结果算好了。只认带布尔 ok 的对象，
+  // 免得一个形状不对的字段被当成「不在目录内」（那是把一个错误悄悄读成一个结论）。
+  if (mp && typeof mp === 'object' && typeof mp.ok === 'boolean') {
+    return { inside: mp.ok === true }
+  }
+  // 便捷入口：只给了原始路径就现算 —— 仍然走 paths.js 的**同一个** memoryPathOf，
+  // 所以两条路不可能判出两个结果（这正是把判据抽出去的目的）。
+  if (typeof facts.path === 'string' && facts.path !== '') {
+    return { inside: memoryPathOf(facts.path, facts.memoryDir).ok === true }
+  }
+  return { unknown: true }
+}
+
+/**
+ * 核心判定：把 facts 压成「给什么 / 为什么」。
+ *
+ * 两个公开函数（写入意图、编辑守卫）共用它，是为了让 reason 的含义在两条路上完全一致 ——
+ * 分成两份实现，迟早出现「同一个事实在写入侧叫 created、在编辑侧叫 unknown」这种漂移。
+ *
+ * @returns {{reason:string, caller?:*, create?:boolean, version?:string}}
+ */
+function gate(facts) {
+  if (!facts || typeof facts !== 'object') return { reason: 'unknown' }
+
+  const where = locationOf(facts)
+  if (where.unknown) return { reason: 'unknown' }
+  // 先判位置，理由见文件头第 1 条：目录外返回任何值都会占掉单槽。
+  if (!where.inside) return { reason: 'outside_memory' }
+
+  // 尊重调用方：他给了就原样透传，我们只是**补充**守卫的，不覆盖他的意图。
+  // `null` 与 `undefined` 一起当「没给」—— 宿主的契约里「没给」就是 undefined。
+  if (facts.caller !== undefined && facts.caller !== null) {
+    return { reason: 'caller_wins', caller: facts.caller }
+  }
+
+  // 只认严格的 `exists === true` 为「确知存在」；缺失 / 非布尔一律按「不确知」处理（不猜）。
+  if (facts.exists !== true) {
+    // 「明确不存在」与「不确知存在」给不同 reason：前者是确定的事实，后者是信息不足，
+    // 但两者都只能给 createIfAbsent —— 它是这里唯一**不可能静默覆盖**的意图。
+    // ⚠️ 正因为这个分支会 createIfAbsent，接线**不许**把「探不到」写成 `exists: false`
+    // （那是误拦，见文件头那节）；`no_version` 是给「调用方确实没给这个字段」的确定答案。
+    return facts.exists === false ? { reason: 'created', create: true } : { reason: 'no_version', create: true }
+  }
+
+  // 版本是不透明的非空字符串。空串 / 非字符串一律当「拿不到版本」：拿一个形状不对的东西
+  // 去构造 replaceIfVersion，只会换来宿主一句看不懂的报错。
+  const version = typeof facts.version === 'string' && facts.version !== '' ? facts.version : null
+  if (version === null) return { reason: 'unknown' }
+  return { reason: 'guarded', version }
+}
+
+/**
+ * 决定一次**整份写入**的意图。纯函数：只吃已观测到的事实，不读盘、不看时钟、不抛。
+ *
+ * @param {object} facts `{memoryPath, exists, version, caller, toolWrite?, path?, memoryDir?}`
+ * @returns {{intent: {kind:'createIfAbsent'}|{kind:'replaceIfVersion',version:string}|undefined, reason:string}}
+ *   `undefined` = 不管 / 不猜（**不是拒绝**：宿主照它自己的默认继续）。
+ */
+export function decideWriteIntent(facts) {
+  try {
+    const d = gate(facts)
+    if (d.reason === 'caller_wins') return { intent: d.caller, reason: d.reason }
+    if (d.create) return { intent: { kind: 'createIfAbsent' }, reason: d.reason }
+    if (d.reason === 'guarded') return { intent: { kind: 'replaceIfVersion', version: d.version }, reason: d.reason }
+    return { intent: undefined, reason: d.reason }
+  } catch {
+    // 调用方的 facts 可能来自带抛错 getter 的对象。写入门在宿主的写入链路上，
+    // 抛出去会把一次正常写入炸掉 —— 任何意外都退化成「不管」，让写入按默认语义走。
+    return { intent: undefined, reason: 'unknown' }
+  }
+}
+
+/**
+ * 决定一次**编辑**的守卫。与 `decideWriteIntent` 同一张判定表，只是输出改成一个版本守卫。
+ *
+ * 编辑没有「创建」这个动作，所以 `created` / `no_version` 两条在这里都返回**无守卫**
+ * （`undefined`）—— 文件不存在时该不该创建由宿主与调用方决定，不是我们替它决定。
+ *
+ * @returns {{guard: {version:string}|undefined, reason:string}}
+ */
+export function decideEditGuard(facts) {
+  try {
+    const d = gate(facts)
+    if (d.reason === 'caller_wins') return { guard: d.caller, reason: d.reason }
+    if (d.reason === 'guarded') return { guard: { version: d.version }, reason: d.reason }
+    return { guard: undefined, reason: d.reason }
+  } catch {
+    return { guard: undefined, reason: 'unknown' }
+  }
+}

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.18",
+  "version": "0.9.20",
   "type": "module",
   "main": "lib/index.js",
   "exports": {