sage-mem 0.6.3 → 0.7.0

package/lib/{dream-audit.js → autodream-audit.js}

@@ -1,8 +1,8 @@
 /**
- * sage-mem dream — 记忆目录审计（六查）。
+ * sage-mem autodream — 记忆目录审计（七查）。
  *
- * 把 `sage-memory` 技能里的审计清单搬到 host 侧，让 dream 每次跑完都能自证
- * 没把记忆改坏：
+ * 审计清单内置在 host 侧，让 autodream 每次跑完都能自证
+ * 没把记忆改坏（七项，外加「读不动」单列一类）：
  *   1. 索引悬空 —— MEMORY.md 指向不存在的文件
  *   2. 漏索引   —— 存在但没进索引的记忆文件
  *   3. type 与前缀不一致（分类看 type，前缀骗不了它）
@@ -10,7 +10,7 @@
  *   5. 双链断链 —— [[目标]] 找不到对应文件或 frontmatter name
  *   6. 未加引号值里的「空格+#」—— 会被 YAML 当注释吞掉，解析不报错但描述残缺
  *
- * **纯只读**：不修任何东西。修哪条、怎么修，由 dream agent 或人决定。
+ * **纯只读**：不修任何东西。修哪条、怎么修，由 autodream agent 或人决定。
  *
  * 这一份解析是 sage-mem host 半 parseFrontmatter 的同源精简版，故意不共用：
  * 那边带着一长串历史坑的注释与行为（baseline、type 回落），审计只读不写，
@@ -26,7 +26,7 @@ const INDEX_FILE = 'MEMORY.md'
 /**
  * 非记忆条目：不是四类记忆、也不该套「type 与前缀一致」这条规则。
  *
- * session-log.md 是追加型流水（本机已 390+ KB），逐会话的账本而不是一条记忆；
+ * session-log.md 是追加型流水，逐会话的账本而不是一条记忆；
  * 它没有 `user_/feedback_/project_/reference_` 前缀，扫进来只会白白读一大坨
  * 再报一条假问题（2026-09-27 实测：报出 `session-log.md type=reference`）。
  * 同理 MEMORY.md 是索引本身，只作为链接来源读，不作为被审对象。
@@ -98,7 +98,7 @@ async function readDirSnapshot(dir) {
 }
 
 /**
- * 六查主入口。
+ * 七查主入口。
  * @param {string} dir — 记忆根目录
  * @returns {Promise<object>} 结构化审计结果（problems 是六项之和）
  */
@@ -123,17 +123,30 @@ export async function auditMemoryDir(dir) {
   const linkKeys = new Set()
 
   const contents = new Map()
+  /**
+   * 读不动的文件（权限、被占用、编码坏）。
+   *
+   * **绝不抛**：`run()` 把「运行前审计」当作开工前置，裸抛一个 EPERM 会让
+   * 「有个文件读不了」升级成「自动整理整个停摆」，而且报出来的是宿主内部的原文。
+   * 它们单列一类，**不参与**后面每一项检查 —— 免得被戴上「没 frontmatter」「CRLF」的帽子
+   */
+  const unreadable = []
   for (const f of files) {
-    contents.set(f, await readFile(join(dir, f), 'utf8'))
+    try {
+      contents.set(f, await readFile(join(dir, f), 'utf8'))
+    } catch {
+      unreadable.push(f)
+    }
   }
-  for (const f of files) {
+  const readable = files.filter((f) => contents.has(f))
+  for (const f of readable) {
     const meta = parseFrontmatterLite(contents.get(f))
     if (meta.name) linkKeys.add(meta.name.trim())
   }
-  for (const f of files) linkKeys.add(f)
-  for (const f of files) linkKeys.add(f.replace(/\.md$/, ''))
+  for (const f of readable) linkKeys.add(f)
+  for (const f of readable) linkKeys.add(f.replace(/\.md$/, ''))
 
-  for (const f of entries) {
+  for (const f of readable) {
     const raw = contents.get(f)
     if (raw.includes('\r')) crlf.push(f)
     const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/)
@@ -166,7 +179,8 @@ export async function auditMemoryDir(dir) {
     crlf.length +
     brokenLinks.length +
     hashHazards.length +
-    noFrontmatter.length
+    noFrontmatter.length +
+    unreadable.length
 
   return {
     dir,
@@ -180,12 +194,13 @@ export async function auditMemoryDir(dir) {
     brokenLinks,
     hashHazards,
     noFrontmatter: noFrontmatter.map((file) => ({ file })),
+    unreadable: unreadable.map((file) => ({ file })),
     problems,
   }
 }
 
 /**
- * 把审计结果压成给模型看的短文本（dream 工具返回值 / 报告附录都用它）。
+ * 把审计结果压成给模型看的短文本（autodream 工具返回值 / 报告附录都用它）。
  * @param {object} report — auditMemoryDir 的返回值
  * @param {number} [limit] — 每个分项最多列几条
  * @returns {string}
@@ -207,5 +222,8 @@ export function formatAudit(report, limit = 12) {
   section('双链断链', report.brokenLinks, (r) => `${r.file} -> [[${r.target}]]`)
   section('未加引号的「空格+#」', report.hashHazards, (r) => `${r.file} :: ${r.line}`)
   section('无 frontmatter', report.noFrontmatter, (r) => r.file)
+  // 读不动的单列，且排最后：它不是「这条记忆写错了」，是「我没读到它」——
+  // 别让模型以为去改改 frontmatter 就能好。
+  section('读不动（权限/占用/编码，不参与上面各项检查）', report.unreadable ?? [], (r) => r.file)
   return lines.join('\n')
 }

package/lib/{dream-prompt.js → autodream-prompt.js}

@@ -1,14 +1,16 @@
 /**
- * sage-mem dream — 提示词。
+ * sage-mem autodream — 提示词。
  *
  * 四阶段结构：定位 → 收集 → 整合 → 修剪与索引。两个非显然的取舍：
  *
- *   1. **写记忆的规范必须写进 prompt 里。** sage-mem 的规范本来在 `sage-memory`
- *      技能里，但 dream 是一次独立调用、不一定带着那份技能。所以四类前缀、
- *      `type` 一致性、YAML 两个静默陷阱、保留名这些**必须**出现在 prompt 里，
- *      否则模型会照着「看起来像」的方式写坏。
+ *   1. **写记忆的规范必须随 prompt 自带。** autodream 是一次独立调用，带不上外部的
+ *      技能文档。所以四类前缀、`type` 一致性、YAML 两个静默陷阱、受保护文件名这些
+ *      **必须**出现在 prompt 里，否则模型会照着「看起来像」的方式写坏。
  *   2. **按模式分叉。** 「只出报告」不是靠一句「请不要写」约束的——那一趟根本
- *      没有写工具（见 dream-tools.js）。所以 prompt 只说它有什么、该产出什么形状。
+ *      没有写工具（见 autodream-tools.js）。所以 prompt 只说它有什么、该产出什么形状。
+ *
+ * ⚠️ 这里**不许出现任何具体的记忆文件名**（除了使用者通过 `reserved.json` 自己声明的）。
+ * 那段文字会发给每一个使用者的模型；把作者的记忆主题编进去就是泄漏
  */
 
 /** 让 prompt 里的日期对人可读：模型算相对日期时不会写错。 */
@@ -20,13 +22,19 @@ function today(ms) {
 
 /**
  * 系统提示：身份 + 记忆系统的约定 + 这一趟的权限边界。
- * @param {{apply:boolean, withSessions:boolean}} opts
+ * @param {{apply:boolean, withSessions:boolean, reservedFiles?:string[]}} opts
+ *   `reservedFiles` 是**使用者自己声明**的受保护文件名（来自 `<状态根>/reserved.json`）。
+ *   由运行时注入而不是写死在这里——见文件头那条警告。
  * @returns {string}
  */
-export function buildDreamSystemPrompt(opts) {
+export function buildAutodreamSystemPrompt(opts) {
   const { apply, withSessions } = opts
+  const reserved = Array.isArray(opts.reservedFiles) ? opts.reservedFiles.filter(Boolean) : []
+  const reservedNote = reserved.length
+    ? `- **不许改动的文件**（使用者指定的保护名单）：${reserved.map((f) => `\`${f}\``).join('、')} —— 这些多半是手写单副本、人工维护的重要记忆，一个字都不要动`
+    : '- 有些记忆是使用者手写单副本、人工维护的；本次没有额外指定保护名单，遇到明显「成篇手写、结构不像流水」的记忆请保守处理'
   const modeLine = apply
-    ? '本次是**改写模式**：你有写工具，可以直接改记忆文件。运行前已经把整个 memory 目录快照了一份，改坏能整体回退——但这只保证「可恢复」，不保证「改得对」。宁可少改，不要乱动。'
+    ? '本次是**改写模式**：你有写工具，可以直接改记忆文件。运行前已经把整个 memory 目录快照了一份（这就是回滚点），改坏能整体退回去——但这只保证「可恢复」，不保证「改得对」。宁可少改，不要乱动。\n\n**每一次写入都请写清 `reason`。** 这一趟是无人值守跑的，人只能靠这份缘由判断你改得对不对。写清「为什么改这条、改成了什么」，不要写「整理优化」这种没有信息量的话。缺了**不会被拒绝**——改动照样生效——但整理声明里会把那条标成「未自述」，用宿主能追溯到的信息顶替。'
     : '本次是**只读模式**：你没有任何写工具。把所有发现写成建议清单，写进你最后的回复里——要具体到「哪个文件、改成什么」，不要泛泛而谈。'
 
   return `你是 sage-mem（一个文件式跨会话记忆系统）的整理进程。你的记忆不是数据库，是一个装着 markdown 文件的目录，靠 frontmatter 分类、靠双字组匹配检索。你要做的是一次反思性通读，把最近的经历沉淀成耐久、有条理的记忆。
@@ -57,7 +65,7 @@ ${modeLine}
 **几个特殊文件：**
 - \`MEMORY.md\` —— 索引。它是一份索引用，每条一行 \`- [标题](文件.md) — 一句话\`，**不要把记忆内容写进去**
 - \`session-log.md\` —— 追加型流水账，**不是一条记忆**，不进检索、不进列表、不要当记忆改
-- \`project_heartscape.md\` / \`project_self-cognition.md\` —— 手写单副本、人工维护，改动它们要格外小心
+${reservedNote}
 - \`archive/\` —— 归档区，不在检索范围内。归档 = 把文件移进去，**可人工捞回**；这里没有真删除
 
 **硬标准：靠读代码 / git / 系统提示能推出来的东西不要存。** 存的是推不出来的上下文。写之前先问一句「下一个我会真的用得上这条吗」。${withSessions ? '' : '\n\n**本次输入源不含会话记录**，所以你没有 search_sessions 工具。手上的材料就是记忆目录本身。'}`
@@ -72,7 +80,7 @@ ${modeLine}
  * @param {{memoryDir:string, apply:boolean, hoursSince:number, sessionCount:number, now:number}} opts
  * @returns {string}
  */
-export function buildDreamUserPrompt(opts) {
+export function buildAutodreamUserPrompt(opts) {
   const { memoryDir, apply, hoursSince, sessionCount, now } = opts
   const stage4 = apply
     ? `- 更新 \`MEMORY.md\` 索引，让它保持是索引而不是内容堆：
@@ -80,9 +88,9 @@ export function buildDreamUserPrompt(opts) {
   - 移除指向已归档 / 已不存在文件的指针
   - 补上新写的重要记忆
   - 两条记忆互相矛盾时，把错的那条改对`
-    : `- 给出 \`MEMORY.md\` 该增删哪些行的**具体清单**（照抄要改成的那行文本）`
+    : `- 给出 \`MEMORY.md\` 该增删哪些行的**具体清单**（逐字给出要改成的那行文本）`
 
-  return `# Dream：一次记忆整理
+  return `# Autodream：一次记忆整理
 
 今天：${today(now)}
 记忆目录：\`${memoryDir}\`
@@ -109,7 +117,7 @@ export function buildDreamUserPrompt(opts) {
 
 对每件值得记住的事，改写或新建一条记忆。**合并新信息进已有文件**，不要为一点新东西新开一个文件。被推翻的事实改在源头，而不是在后面追加一句「其实不是这样」。
 
-${apply ? '你有写工具，直接落盘。' : '你没有写工具，把每条改动写成「文件 → 具体改成什么」的形式。'}
+${apply ? '你有写工具，直接落盘。**每次 `write_memory` / `archive_memory` 都必须带 `reason`**（一句话：为什么动这条、动成了什么）。这一趟的每次改动都会被记进「整理声明」，人要照着它核对。' : '你没有写工具，把每条改动写成「文件 → 具体改成什么 → 为什么」的形式。'}
 
 ## 阶段 4 — 修剪与索引
 

package/lib/{dream-tools.js → autodream-tools.js}

@@ -1,23 +1,33 @@
 /**
- * sage-mem dream — 交给 dream 模型的工具集，以及它们的 host 侧执行器。
+ * sage-mem autodream — 交给 autodream 模型的工具集，以及它们的 host 侧执行器。
  *
  * 这一层是**安全边界**，不是提示词。常见做法是「让模型随便请求、宿主逐个裁决」；
  * 这里换了个更硬的写法 —— **模型只能看见这几个工具**，
  * 而每个工具的宿主实现只认 memory 目录顶层的 `.md` 文件名。模型想越界
  * （写别的目录、动子目录、写非 md、路径穿越）不是「被拒绝」，是**没有这个能力**。
  *
- * 还有一条刻意的不对称：
+ * 还有两条刻意的不对称：
  *   - 「只出报告」模式下，写工具**根本不注册** —— 不是让模型别写，是它没有手。
  *   - 删除也不是删除：archive_memory 把文件移进 `archive/`，可人工捞回。
  *     memory 目录不在任何版本控制下、unlink 没有回收站，所以不留真删这条路径。
  *
+ * **每一次写操作都必须留下「改了什么、为什么」**：
+ *   - `write_memory` 的 `reason` **强烈建议**但不强制：缺了照样写入，声明里标成「未自述」
+ *     并用宿主能追溯到的信息（第几轮 / 操作 / 字节变化）顶替。**硬拒的代价是丢掉一次
+ *     本来正确的修正**，那比缺一句解释更糟（2026-10-01 由参考设计调研推翻硬拒方案）。
+ *   - `archive_memory` 的 `reason` 仍**必填**：归档是不可逆的退役动作，必须有人能说清为什么。
+ *   - 每次成功写入/归档都产出一条结构化 `change`（前后指纹 + 缘由 + 缘由来源 + 字节差），
+ *     由 `changes()` 交给上层落成「整理声明」。**回滚也靠它**：只有知道动过哪几个文件、
+ *     动之前长什么样，才谈得上把文件级回滚做准。
+ *
  * 模型与宿主对同一份数据的理解必须一致：`list_memory` 的字段顺序、
- * `write_memory` 的 frontmatter 规范都直接抄 sage-mem 的既有约定，不另造一套。
+ * `write_memory` 的 frontmatter 规范都沿用 sage-mem 的既有约定，不另造一套。
  */
 
 import { readFile, readdir, writeFile, rename, stat, mkdir } from 'node:fs/promises'
 import { join, basename } from 'node:path'
-import { auditMemoryDir, formatAudit, parseFrontmatterLite } from './dream-audit.js'
+import { createHash } from 'node:crypto'
+import { auditMemoryDir, formatAudit, parseFrontmatterLite } from './autodream-audit.js'
 
 /** 单次 read_memory 返回的正文上限（字符）。超过就截断并明确告诉模型。 */
 const READ_LIMIT = 20000
@@ -32,7 +42,7 @@ const INDEX_FILE = 'memory.md'
 /**
  * 非记忆条目：不进 list_memory。
  *
- * session-log.md 是追加型流水（本机已 390+ KB），不是一条记忆 —— 列出来既
+ * session-log.md 是追加型流水，不是一条记忆 —— 列出来既
  * 占掉模型一大块注意力，又诱导它去「整理」一份流水账。2026-09-27 冒烟测试
  * 逮到的就是这条：它出现在了 list_memory 的输出里。
  */
@@ -42,7 +52,7 @@ const NON_ENTRY_FILES = new Set(['session-log.md'])
  * 把一个模型给的文件名收敛成 memory 目录顶层的一个真实路径。
  *
  * 返回 null 表示「这个请求不合法」——调用方一律当成工具执行失败回给模型，
- * 不抛异常打断整个 dream（模型写错一次文件名不该毁掉整趟整理）。
+ * 不抛异常打断整个 autodream（模型写错一次文件名不该毁掉整趟整理）。
  *
  * @param {string} memoryDir — 记忆根目录
  * @param {unknown} raw — 模型给的 file 参数
@@ -60,8 +70,24 @@ export function safeMemoryPath(memoryDir, raw) {
   return join(memoryDir, base)
 }
 
-/** ISO 时间 → 本地 `YYYY-MM-DD HH:mm`（报告与列表里给人看）。 */
-function localStamp(ms) {
+/**
+ * 把模型给的文件名解析成**磁盘上的真实名字**。
+ *
+ * 为什么必须有这一步：NTFS 不区分大小写 —— 模型写 `A.md` 而盘上是 `a.md` 时，
+ * 读写命中的是**同一个文件**。但变更记录、快照清单、回滚时用的都是「模型给的那个名字」，
+ * 于是回滚会去快照里找一个不存在的 `A.md`，**明明有原版却退不回去**，
+ * 而且留痕还写着「回滚点里没有这一版，可能已被别的整理改过」——理由是错的。
+ *
+ * 文件不存在时按原样返回（新建场景）。
+ */
+async function resolveRealName(memoryDir, base) {
+  const lower = base.toLowerCase()
+  const entries = await readdir(memoryDir, { withFileTypes: true }).catch(() => [])
+  const hit = entries.find((e) => e.isFile() && e.name.toLowerCase() === lower)
+  return hit ? hit.name : base
+}
+
+/** ISO 时间 → 本地 `YYYY-MM-DD HH:mm`（报告与列表里给人看）。 */function localStamp(ms) {
   const d = new Date(ms)
   const p = (n) => String(n).padStart(2, '0')
   return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`
@@ -177,7 +203,7 @@ async function searchSessions(sessionsRoot, query, limit, sinceMs) {
         if (total > SEARCH_LIMIT || hits.length > limit) break
       }
     } catch {
-      // 单个会话读不动就跳过：dream 不该因为一个坏文件整体失败。
+      // 单个会话读不动就跳过：autodream 不该因为一个坏文件整体失败。
     }
     if (total > SEARCH_LIMIT || hits.length > limit) break
   }
@@ -189,11 +215,11 @@ async function searchSessions(sessionsRoot, query, limit, sinceMs) {
 const str = (description) => ({ type: 'string', description })
 
 /**
- * 组装这一趟 dream 能用的工具定义。
+ * 组装这一趟 autodream 能用的工具定义。
  * @param {{apply: boolean, withSessions: boolean}} opts
  * @returns {Array<{name:string,description:string,parameters:object}>}
  */
-export function dreamToolSchemas(opts) {
+export function autodreamToolSchemas(opts) {
   const tools = [
     {
       name: 'list_memory',
@@ -206,7 +232,7 @@ export function dreamToolSchemas(opts) {
       description: '读一条记忆的全文（frontmatter + 正文）。文件名要和 list_memory 返回的完全一致。',
       parameters: {
         type: 'object',
-        properties: { file: str('记忆文件名，例如 feedback_autonomy-boundary.md') },
+        properties: { file: str('记忆文件名，例如 feedback_example.md') },
         required: ['file'],
         additionalProperties: false,
       },
@@ -239,12 +265,17 @@ export function dreamToolSchemas(opts) {
       {
         name: 'write_memory',
         description:
-          '写入或整体覆盖一条记忆文件（frontmatter + 正文）。只允许 memory 目录顶层的 .md。整合新信息时优先改写已有文件，不要新建近似重复的文件。',
+          '写入或整体覆盖一条记忆文件（frontmatter + 正文）。只允许 memory 目录顶层的 .md。整合新信息时优先改写已有文件，不要新建近似重复的文件。**reason 请尽量填写**：这些改动会连同缘由一起写进整理声明，人要靠它判断这次自动整理干得对不对；缺了不会被拒绝，但声明里会把那条标成「未自述」。',
         parameters: {
           type: 'object',
           properties: {
-            file: str('记忆文件名，例如 project_dsh-migration.md'),
+            file: str('记忆文件名，例如 project_example.md'),
             content: str('完整文件内容，必须以 --- 开头的 YAML frontmatter 起始'),
+            reason: str(
+              '强烈建议填。一句话说清为什么改这条、改了什么（例如「合并了重复的部署记录，删掉被推翻的旧路径」）。' +
+                '缺了**不会**被拒绝——改动照样生效——但整理声明会把这条标成「未自述」，用宿主能追溯到的信息' +
+                '（第几轮 / 什么操作 / 字节变化）顶替。硬拒的代价是丢掉一次本来正确的修正，那比缺一句解释更糟。',
+            ),
           },
           required: ['file', 'content'],
           additionalProperties: false,
@@ -269,24 +300,96 @@ export function dreamToolSchemas(opts) {
   return tools
 }
 
+/**
+ * 一条记忆文件当前的指纹。不存在时返回 `exist:false`（这不算错——新建文件的第一步）。
+ *
+ * 为什么留 sha256 而不只留体积：回滚前的「这文件还是我改完那一版吗」需要能判等，
+ * 体积相同内容不同的情况在 markdown 里太常见了。
+ */
+async function fileFingerprint(full) {
+  try {
+    const buf = await readFile(full)
+    return { exist: true, bytes: buf.length, sha256: createHash('sha256').update(buf).digest('hex') }
+  } catch (err) {
+    if (err?.code === 'ENOENT') return { exist: false, bytes: 0, sha256: null }
+    throw err
+  }
+}
+
+/** 缘由的最短长度：比这更短的基本都是「整理了一下」这种没有信息量的敷衍。 */
+const MIN_REASON_CHARS = 4
+
 /**
  * 造一个工具执行器。返回的 run() 永远解析成字符串（失败信息也回给模型），
- * 不抛异常 —— 模型拿到错误描述才能自己改，而不是让整趟 dream 崩掉。
+ * 不抛异常 —— 模型拿到错误描述才能自己改，而不是让整趟 autodream 崩掉。
  *
  * @param {{memoryDir:string, sessionsRoot:string, apply:boolean, withSessions:boolean}} opts
- * @returns {(name:string, args:object) => Promise<string>}
+ * @returns {{run:(name:string, args:object)=>Promise<string>, touchedFiles:()=>string[], changes:()=>object[], warnings:()=>string[]}}
  */
 export function createToolRunner(opts) {
   const { memoryDir, sessionsRoot, apply, withSessions } = opts
   let listCache = null
   let auditCache = null
   const touched = []
+  /** 结构化变更清单——「整理声明」与「文件级回滚」共用这一份数据。 */
+  const changes = []
+  /** 被拒绝的写操作（归档没给 reason 之类）：**改动没有发生**，声明里单列一节。 */
+  const warnings = []
+  /**
+   * 提示（advisory）：**改动发生了**，只是有话要说（例如模型没自述缘由）。
+   *
+   * 与 warnings 分开是必须的：两者在「到底改没改」上完全相反，混在一个数组里渲染出去，
+   * 就会出现「标题写着『未能落地的改动』、正文却告诉你『改动已经生效』」这种自相矛盾
+   */
+  const notes = []
+  let seq = 0
+  /** 当前处在 agent 循环的第几轮——未自述缘由时用它追溯「哪一步干的」。 */
+  let currentStep = 0
+
+  /**
+   * 记一条变更。seq 是本次运行内的序号，从 1 开始。
+   * @param {'create'|'update'|'archive'} op
+   * @param {'model'|'auto'} reasonSource — model = 模型自述；auto = 宿主追溯（模型没给）
+   */
+  function changeRecord(op, file, reason, before, after, reasonSource = 'model') {
+    seq += 1
+    const at = Date.now()
+    changes.push({
+      seq,
+      at,
+      atHuman: localStamp(at),
+      step: currentStep || null,
+      file,
+      op,
+      reason,
+      reasonSource,
+      before,
+      after,
+      deltaBytes: after.bytes - before.bytes,
+    })
+  }
 
   return {
-    /** dream 报告要写「改了哪些文件」，由这里记录。 */
+    /** 报告要写「改了哪些文件」，由这里记录。 */
     touchedFiles() {
       return [...touched]
     },
+    /** 结构化变更清单（含缘由与前后指纹）。 */
+    changes() {
+      return changes.map((c) => ({ ...c }))
+    },
+    /** 被拒绝的写操作说明（改动没有发生）。 */
+    warnings() {
+      return [...warnings]
+    },
+    /** 提示（改动发生了，但有话要说）。 */
+    notes() {
+      return [...notes]
+    },
+    /** agent 循环每进一轮调一次，供未自述缘由时追溯来源。 */
+    setStep(n) {
+      currentStep = Math.max(0, Math.round(Number(n) || 0))
+    },
 
     async run(name, args) {
       const a = args && typeof args === 'object' ? args : {}
@@ -301,8 +404,10 @@ export function createToolRunner(opts) {
             return `记忆目录：${memoryDir}\n共 ${listCache.length} 条（按修改时间由新到旧）：\n\n${lines.join('\n')}`
           }
           case 'read_memory': {
-            const full = safeMemoryPath(memoryDir, a.file)
-            if (!full) return `错误：文件名不合法（只能是 memory 目录顶层的 .md 文件名）：${String(a.file)}`
+            const validated = safeMemoryPath(memoryDir, a.file)
+            if (!validated) return `错误：文件名不合法（只能是 memory 目录顶层的 .md 文件名）：${String(a.file)}`
+            // 统一落到磁盘上的真实名字：NTFS 大小写不敏感，`A.md` 与 `a.md` 是同一个文件。
+            const full = join(memoryDir, await resolveRealName(memoryDir, basename(validated)))
             const content = await readFile(full, 'utf8').catch((err) => {
               if (err?.code === 'ENOENT') return null
               throw err
@@ -318,29 +423,55 @@ export function createToolRunner(opts) {
             return formatAudit(auditCache, 20)
           }
           case 'search_sessions': {
-            if (!withSessions) return '错误：本次 dream 的输入源不包含会话记录，search_sessions 不可用。'
+            if (!withSessions) return '错误：本次 autodream 的输入源不包含会话记录，search_sessions 不可用。'
             const lim = Number.isFinite(a.limit) ? Math.max(1, Math.min(60, Number(a.limit))) : 20
             return await searchSessions(sessionsRoot, a.query, lim, 0)
           }
           case 'write_memory': {
             if (!apply) return '错误：当前是「只出报告」模式，没有写权限。请把改动写进你的最终回复。'
-            const full = safeMemoryPath(memoryDir, a.file)
-            if (!full) return `错误：文件名不合法（只能是 memory 目录顶层的 .md 文件名）：${String(a.file)}`
+            const validated = safeMemoryPath(memoryDir, a.file)
+            if (!validated) return `错误：文件名不合法（只能是 memory 目录顶层的 .md 文件名）：${String(a.file)}`
+            // 落盘前先解析成磁盘真实名字，否则变更记录与快照清单会各记一个名字，
+            // 文件级回滚就找不到原版（RB-9）。
+            const full = join(memoryDir, await resolveRealName(memoryDir, basename(validated)))
             if (typeof a.content !== 'string' || !a.content.trim()) return '错误：content 为空。'
             if (!/^---\r?\n/.test(a.content)) {
               return '错误：内容必须以 `---` 开头的 YAML frontmatter 起始。参考 list_memory 里已有文件的写法。'
             }
             if (a.content.length > 512 * 1024) return `错误：内容过大（${a.content.length} 字符）。`
+            const reason = typeof a.reason === 'string' ? a.reason.trim() : ''
+            const selfReported = reason.length >= MIN_REASON_CHARS
+            const before = await fileFingerprint(full)
             await writeFile(full, a.content, 'utf8')
+            const after = await fileFingerprint(full)
+            if (!selfReported) {
+              // **不拒绝。** 一次改写缺了缘由，拒掉的代价是这条修正彻底丢失——而它可能
+              // 正是这趟整理最该做的事。「照写 + 标未自述 + 用宿主能追溯到的信息顶替」
+              // 既保住了改动，也让声明里一眼看得出哪些缘由是模型自己说的。
+              notes.push(`${basename(full)} 的改动模型没有自述缘由，声明里已标「未自述」并附追溯信息`)            }
+            changeRecord(
+              before.exist ? 'update' : 'create',
+              basename(full),
+              selfReported ? reason : '',
+              before,
+              after,
+              selfReported ? 'model' : 'auto',
+            )
             touched.push(basename(full))
             listCache = null
             auditCache = null
-            return `已写入 ${basename(full)}（${a.content.length} 字符）。`
+            return `已写入 ${basename(full)}（${a.content.length} 字符）${before.exist ? '' : '（新建）'}。`
           }
           case 'archive_memory': {
             if (!apply) return '错误：当前是「只出报告」模式，没有归档权限。请把建议写进你的最终回复。'
-            const full = safeMemoryPath(memoryDir, a.file)
-            if (!full) return `错误：文件名不合法：${String(a.file)}`
+            const validated = safeMemoryPath(memoryDir, a.file)
+            if (!validated) return `错误：文件名不合法：${String(a.file)}`
+            const full = join(memoryDir, await resolveRealName(memoryDir, basename(validated)))
+            const reason = typeof a.reason === 'string' ? a.reason.trim() : ''
+            if (reason.length < MIN_REASON_CHARS) {
+              warnings.push(`拒绝对 ${basename(full)} 的归档：模型没给 reason（或太短）`)
+              return '错误：archive_memory 必须给 reason —— 一句话说明为什么这条该退役。请带上 reason 重发。'
+            }
             const exists = await stat(full).catch(() => null)
             if (!exists) return `错误：没有这个文件：${basename(full)}`
             const archiveDir = join(memoryDir, ARCHIVE_DIR)
@@ -348,11 +479,13 @@ export function createToolRunner(opts) {
             const target = join(archiveDir, basename(full))
             const clash = await stat(target).catch(() => null)
             if (clash) return `错误：archive/ 里已有同名文件（${basename(full)}），请先人工处理，避免覆盖。`
+            const before = await fileFingerprint(full)
             await rename(full, target)
+            changeRecord('archive', basename(full), reason, before, { exist: false, bytes: 0, sha256: null })
             touched.push(`${basename(full)} → archive/`)
             listCache = null
             auditCache = null
-            return `已归档 ${basename(full)}（原因：${String(a.reason || '未写')}）。`
+            return `已归档 ${basename(full)}（原因：${reason}）。`
           }
           default:
             return `错误：没有这个工具：${name}`