@a9i5k4/dsh-auto-memory 2.5.3 → 3.0.1

package/lib/skill-export.js

@@ -0,0 +1,239 @@
+/**
+ * M9-3 Skill 导出层（procedure → SKILL.md 目录束）。
+ *
+ * ★ 2026-09-19 用户拍板（三项）：
+ *   ⑪-1 形态：`SKILL.md` + **附上过程中用到的程序**（如 `.py`），且 SKILL.md 里
+ *        必须明写：这些程序**只是参考性的** —— 若当前做的事情与之前**根本不同**，
+ *        可以用来**迁移**，**不能直接运行**。
+ *   ⑪-2 时机：**晋升为 `active` 后自动导出**。
+ *   ⑪-3 目录：**用户级**（软件层面，可跨项目迁移）；但导出物**必须标注适用于哪个项目**，
+ *        项目不一样时**只作参考，不能直接用**。
+ *
+ * 本模块是**纯渲染层**（无 IO、无状态），便于直接单测：
+ *   - `renderSkillMarkdownPre(procedure, opts)` → SKILL.md 文本
+ *   - `skillDirNamePre(procedure)` → 目录名（稳定、可预测）
+ *   - `SKILL_USAGE_NOTICE_V1` → 使用约束条款（导出物必须原样包含）
+ *
+ * 设计纪律（与 procedure 引擎同源）：
+ *   ① **不新增状态源** —— 导出物是 procedure 的**派生物**，不是新的事实来源；
+ *   ② **不自动执行任何导出的程序** —— 程序是**参考资料**，不是可调用入口；
+ *   ③ 全部 fail-soft，但**返回可观察结果**（ok/reason），不静默。
+ */
+
+// ★ T7-b（2026-09-20）：纯计算依赖，用于给「纯中文标题」生成稳定的 ASCII 目录名。
+//   node 内建模块，不引入外部依赖、不做 IO、不持有状态 —— 与本模块「纯渲染层」定位不冲突。
+import { createHash } from 'node:crypto'
+
+/** 导出物的使用约束条款 —— **必须原样出现在每个 SKILL.md 中**（用户 ⑪-1 硬要求）。 */
+export const SKILL_USAGE_NOTICE_V1 = [
+  '> **⚠️ 使用约束（必读）**',
+  '>',
+  '> 本技能由 **dsh-auto-memory** 从一次真实工作过程**自动沉淀**而来，**不是通用最佳实践**。',
+  '>',
+  '> 1. **附带程序仅供参考**：本目录下的脚本（如 `.py`）是**当时那次工作用过的程序**，',
+  '>    **不是可直接调用的工具**。它们可能依赖当时的路径、环境变量、数据格式或版本。',
+  '> 2. **场景根本不同时 → 只做迁移，不要直接运行**：若当前任务与下方「来源」描述的场景',
+  '>    **有根本差异**，请把附带的程序**当作思路参考**，按当前场景**重写**，而不是直接执行。',
+  '> 3. **跨项目使用须先核对**：本技能的「适用项目」若与当前项目**不一致**，',
+  '>    **一律只作参考**，不得直接套用其路径、命令与判据。',
+  '> 4. **高风险步骤需人工确认**：涉及删除、发布、付费、外部发送等动作，必须先向用户复述确认。',
+].join('\n')
+
+/** SKILL.md 中必须出现的约束锚点（供套件断言，防止被后续改动悄悄删掉）。 */
+export const SKILL_NOTICE_ANCHORS_V1 = Object.freeze([
+  '使用约束（必读）',
+  '附带程序仅供参考',
+  '只做迁移，不要直接运行',
+  '跨项目使用须先核对',
+  '高风险步骤需人工确认',
+])
+
+const MAX_TITLE_LEN = 80
+
+/**
+ * 目录名 / `name:` 字段：`mem-skill-<slug>-<procId前12位>` —— 稳定、可预测、不冲突。
+ *
+ * ★ T7-b（2026-09-20 用户报「所有中文技能都叫 untitled」）修复：
+ *   **根因**：原实现 `title.replace(/[^a-z0-9]+/g,'-')` 只保留 ASCII ⇒ **纯中文标题 slug 成空串**
+ *   ⇒ 一律回落字面量 `'untitled'`。后果是每个中文技能都叫 `mem-skill-untitled-<id>`，
+ *   用户看到的技能列表名字毫无意义（实测：本机导出的
+ *   `~/.dsh/skills/mem-skill-untitled-aa2153f33507/SKILL.md`）。
+ *
+ *   **为什么不能用「保留中文」这个修法**：DSH 宿主对 skill name 是**硬校验**，不是建议 ——
+ *   `SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/`（宿主 `index.js:17`），且
+ *   `:481` 直接 `throw new Error('loaded skill has invalid name "…"')`。
+ *   ⇒ 中文进 name 会让**技能加载直接失败**（比 untitled 更糟）。故必须产出 ASCII 安全名。
+ *
+ *   **采用的修法**：slug 为空时，取标题的 **sha1 前 8 位十六进制**做 `t-<hash>` 前缀。
+ *   - ASCII 安全：`t-1a2b3c4d` 完全符合上面的 SKILL_NAME 正则；
+ *   - 稳定：同一 title ⇒ 同一 hash ⇒ 目录名不变（自动化重导出不会产生新目录）；
+ *   - 可区分：不同标题 hash 不同，不再出现「一堆 untitled」；
+ *   - 中文原文**不丢**：仍完整出现在 SKILL.md 的 `# <title>` 与 `description` 里，
+ *     用户/模型在技能列表看到的是中文标题，name 只承担「唯一标识」职责。
+ *
+ *   ⚠️ 哈希算法用 node 内建 `createHash('sha1')`（纯计算，不引入 IO/状态），
+ *   与 FNV-1a 那种"自造哈希"区分开 —— 本仓有过 sha256Hex 同名异义的教训（#86-1）。
+ */
+export function skillDirNamePre(procedure) {
+  const id = String((procedure && procedure.procedureId) || '')
+  const short = id.replace(/^proc_/, '').slice(0, 12)
+  const title = String((procedure && procedure.title) || '')
+  const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40)
+  // 纯中文（或纯符号）标题：ASCII slug 为空 ⇒ 用标题哈希代替，绝不留 'untitled'
+  const stem = slug || ('t-' + createHash('sha1').update(title, 'utf8').digest('hex').slice(0, 8))
+  return 'mem-skill-' + stem + '-' + (short || 'noid')
+}
+
+/** 一句话摘要（取步骤首条或标题）——用于 SKILL.md 的 description。 */
+/**
+ * 一句话摘要 —— 用于 SKILL.md 的 `description:` 字段。
+ *
+ * ★ T7-b（2026-09-20）修正取值优先级：**title 优先，steps[0] 兜底**（原来是反的）。
+ *   为什么反了不行：`description` 是模型在技能目录里看到的那句话，应当回答
+ *   「这个技能**是干什么的**」—— title 正是这件事；而 steps[0] 是**第一个动作**
+ *   （实测导出的描述成了「备份：Copy-Item lib/index.js …」，完全看不出技能用途）。
+ *   仅当 title 缺失时才用 steps[0] 兜底（此时有总比没有好）。
+ */
+function summaryOfPre(p) {
+  const t = String(p.title || '').trim()
+  const step = Array.isArray(p.steps) && p.steps.length ? String(p.steps[0]).trim() : ''
+  const s = t || step
+  return s.length > MAX_TITLE_LEN ? s.slice(0, MAX_TITLE_LEN - 1) + '…' : s
+}
+
+/**
+ * 渲染 SKILL.md。
+ *
+ * @param {object} procedure  procedure 记录（stage 应为 active）
+ * @param {object} opts
+ * @param {string} opts.projectName   适用项目名（**必填**，⑪-3）
+ * @param {string} opts.projectPath   项目根绝对路径（用于溯源）
+ * @param {string[]} opts.programs     附带程序文件名列表（⑪-1，仅列名）
+ * @param {string} opts.exportedAt    导出时间（ISO 字符串；缺省由调用方给）
+ * @returns {{ok:true, fileName:string, dirName:string, content:string} | {ok:false, reason:string}}
+ */
+export function renderSkillMarkdownPre(procedure, opts = {}) {
+  const p = procedure || {}
+  if (!p.procedureId) return { ok: false, reason: 'no-procedure-id' }
+  if (!p.title) return { ok: false, reason: 'no-title' }
+  const projectName = String(opts.projectName || '').trim()
+  if (!projectName) return { ok: false, reason: 'no-project-name' }   // ⑪-3 硬要求：必须标项目
+  const projectPath = String(opts.projectPath || '').trim()
+  const programs = Array.isArray(opts.programs) ? opts.programs.filter(Boolean).map(String) : []
+  const exportedAt = String(opts.exportedAt || '')
+
+  const L = []
+  L.push('---')
+  L.push('name: ' + skillDirNamePre(p))
+  L.push('description: ' + summaryOfPre(p).replace(/\r?\n/g, ' '))
+  L.push('---')
+  L.push('')
+  L.push('# ' + String(p.title).trim())
+  L.push('')
+  L.push(SKILL_USAGE_NOTICE_V1)
+  L.push('')
+
+  // ── 来源（⑪-3：必须标注适用于哪个项目）──
+  L.push('## 来源')
+  L.push('')
+  L.push('- **适用项目**：`' + projectName + '`' + (projectPath ? '（`' + projectPath + '`）' : ''))
+  L.push('- **沉淀自**：dsh-auto-memory 技能库（procedure `' + p.procedureId + '`）')
+  if (p.riskLevel) L.push('- **风险等级**：`' + p.riskLevel + '`' + (p.requiresApproval ? '（需人工批准）' : ''))
+  if (exportedAt) L.push('- **导出时间**：' + exportedAt)
+  L.push('')
+  L.push('> 若你的当前项目**不是** `' + projectName + '`，请**只作参考**，不要直接套用下方路径与命令。')
+  L.push('')
+
+  // ── 适用条件 ──
+  if (Array.isArray(p.preconditions) && p.preconditions.length) {
+    L.push('## 何时适用')
+    L.push('')
+    for (const x of p.preconditions) L.push('- ' + String(x))
+    L.push('')
+  }
+
+  // ── 步骤 ──
+  if (Array.isArray(p.steps) && p.steps.length) {
+    L.push('## 步骤')
+    L.push('')
+    p.steps.forEach((s, i) => L.push(String(i + 1) + '. ' + String(s)))
+    L.push('')
+  }
+
+  // ── 检查点 ──
+  if (Array.isArray(p.checks) && p.checks.length) {
+    L.push('## 检查点')
+    L.push('')
+    for (const x of p.checks) L.push('- [ ] ' + String(x))
+    L.push('')
+  }
+
+  // ── 成功判据 ──
+  if (Array.isArray(p.successCriteria) && p.successCriteria.length) {
+    L.push('## 成功判据')
+    L.push('')
+    for (const x of p.successCriteria) L.push('- ' + String(x))
+    L.push('')
+  }
+
+  // ── 回滚 ──
+  if (Array.isArray(p.rollback) && p.rollback.length) {
+    L.push('## 回滚')
+    L.push('')
+    for (const x of p.rollback) L.push('- ' + String(x))
+    L.push('')
+  }
+
+  // ── 附带程序（⑪-1）──
+  if (programs.length) {
+    L.push('## 附带程序（**参考性**）')
+    L.push('')
+    L.push('以下文件是**当时那次工作用过的程序**，随本技能一起导出：')
+    L.push('')
+    for (const f of programs) L.push('- `' + f + '`')
+    L.push('')
+    L.push('> **不要直接运行**。先读一遍，判断它与当前场景的差异；')
+    L.push('> 若场景根本不同，请**按当前场景迁移重写**；确需运行时，先向用户说明并确认。')
+    L.push('')
+  }
+
+  // ── 证据 ──
+  if (Array.isArray(p.sourceEpisodes) && p.sourceEpisodes.length) {
+    L.push('## 依据')
+    L.push('')
+    L.push('- 来源 episode 数：' + p.sourceEpisodes.length)
+    if (p.evidence && typeof p.evidence === 'object') {
+      const ev = p.evidence
+      const parts = []
+      if (Number.isFinite(ev.seen)) parts.push('seen=' + ev.seen)
+      if (Number.isFinite(ev.success)) parts.push('success=' + ev.success)
+      if (Number.isFinite(ev.correction)) parts.push('correction=' + ev.correction)
+      if (parts.length) L.push('- 证据统计：' + parts.join(' / '))
+    }
+    L.push('')
+  }
+
+  return { ok: true, fileName: 'SKILL.md', dirName: skillDirNamePre(p), content: L.join('\n') + '\n' }
+}
+
+/**
+ * 导出完整性校验（供套件与调用方共用）。
+ * **判据是"用户 ⑪-1/⑪-3 的硬要求"本身**，不是实现细节。
+ */
+export function validateSkillMarkdownPre(content, expect = {}) {
+  const s = String(content == null ? '' : content)
+  const problems = []
+  if (!s.trim()) problems.push('empty')
+  for (const a of SKILL_NOTICE_ANCHORS_V1) if (!s.includes(a)) problems.push('missing-notice:' + a)
+  if (!/^---\r?\n[\s\S]*?\r?\n---/.test(s)) problems.push('no-frontmatter')
+  if (!/^name:\s*\S+/m.test(s)) problems.push('no-name')
+  if (!/^description:\s*\S+/m.test(s)) problems.push('no-description')
+  if (expect.projectName && !s.includes('`' + expect.projectName + '`')) problems.push('no-project-tag')
+  // ⑪-1：附带程序必须被运行约束**包裹**，而不是只列个名。
+  // ★ 判据必须锚定属于「程序块」的形态：
+  //   顶层约束条款里也出现「不要直接运行」四字（后接 `**：`），
+  //   只用该四字做判据会**同义反复**（永远为真）——套件 [5] 组已实跑抓到这一版缺陷。
+  //   程序块独有形态 = 加粗短语**后紧跟句号**：`**不要直接运行**。`
+  if (expect.hasPrograms && !/\*\*不要直接运行\*\*。/.test(s)) problems.push('programs-not-constrained')
+  return { ok: problems.length === 0, problems }
+}

package/lib/state-commit.js

@@ -0,0 +1,245 @@
+/**
+ * 统一状态提交契约（state_commit_v1）—— P1 主体（2026-09-15）。
+ *
+ * 依据：`docs/internal/DESIGN-P1-STATE-COMMIT-20260915.md`（已获用户批准）§2.1 / §2.2 / §2.3，
+ *       `MASTER-PLAN-3.0.md` Phase 1、`TODO-GRAPH.html` 卡 V2-P1。
+ *
+ * **一句话目标**：把「谁在写、写的什么版本、写完算不算数」收敛成**一个提交边界**。
+ *
+ * **三条硬规则（本模块是它们的唯一实现点）**：
+ *   1. **miv 是内容身份 + 状态清单摘要**（哈希，**不递增、不比较**）。
+ *      任何代码不得写 `if (miv > lastMiv)` —— 它不是版本序。
+ *   2. **`boardId` 在工作区内稳定、不含 sessionId**：由 `sha256(workspaceKey + '|' + scope)` 派生。
+ *      接续后新窗口换 sessionId，若 boardId 跟着变，图就会被当成两块，共享语义直接崩。
+ *   3. **必须废弃的口径**：白板 `index.json` 的 `rebuilt_at` **不得当版本序** ——
+ *      它是时间戳，重建时间变而内容没变时它会变 ⇒ 用它当版本序会造成**假失效 + 真混版**。
+ *      断言 T1-5c 专门钉死这一条。
+ *
+ * **边界（不在本模块做）**：
+ *   - 不加长期编辑锁、不按会话分片（卡内明确否决）——并发靠「队列串行 + 边界内比较」。
+ *   - 不解析白板格式（KICKOFF §3.4：白板线拥有 `parseWhiteboardPre`）。
+ *   - `atomicReplace` 不是 CAS，本模块不给它加语义；提交校验必须发生在**队列内部**。
+ *
+ * S9 合规：零 IO、零外部依赖（只用 node:crypto）、纯函数、无网络/无 LLM/无子进程/无 await。
+ * UTF-8 无 BOM。
+ */
+import { createHash } from 'node:crypto'
+
+export const STATE_COMMIT_VERSION_PRE = 'state_commit_v1'
+
+/** miv 前缀（与 `shadow-retrieval.js:144` 既有口径一致：`idx_` + first32hex）。 */
+export const MIV_PREFIX_PRE = 'idx_'
+
+/**
+ * 三种状态的**命名隔离**（卡内要求"三种状态不能混"）。
+ * 三者**不得互转**：记忆有效状态是"条目还算不算数"，任务进度是"活干完没有"，
+ * 归档位置是"东西放哪儿"。`archived` 一词两义的问题以独立常量解决，**映射由白板线适配器负责**。
+ */
+export const MEMORY_STATUS_PRE = Object.freeze(['current', 'superseded', 'retracted'])
+export const TASK_STATE_PRE = Object.freeze(['open', 'done', 'passed'])
+export const ARCHIVE_STATE_PRE = Object.freeze(['active', 'archived'])
+
+/** 提交单据必填字段（缺任一 ⇒ fail-closed 拒绝，不猜测）。 */
+export const COMMIT_REQUIRED_V1 = Object.freeze(['workspaceKey', 'boardId', 'txId', 'actor'])
+
+/** 冲突/拒绝原因码 → 可读中文。 */
+export const COMMIT_REASONS_V1 = Object.freeze({
+  'not-object': '传入的不是对象',
+  'missing-field': '提交单据缺必填字段',
+  'invalid-writes': 'writes 形状非法（必须是数组）',
+  'digest-mismatch': '提交前摘要不匹配（外部编辑或并发写）',
+  'state-version-mismatch': '状态版本不匹配（外部变更或并发提交）',
+  'actor-invalid': 'actor 形状非法（需 { sessionId, kind }）',
+})
+
+/** 原因码 → 可读中文（未知码原样返回）。 */
+export function describeCommitReasonPre(code) {
+  const k = String(code == null ? '' : code)
+  return COMMIT_REASONS_V1[k] || k || '未知原因'
+}
+
+function asNonEmptyString(v) {
+  if (typeof v !== 'string') return null
+  const t = v.trim()
+  return t ? t : null
+}
+
+function canonicalJson(v) {
+  // 稳定键序序列化（避免插入顺序导致同内容不同哈希）
+  if (v === null || typeof v !== 'object') return JSON.stringify(v)
+  if (Array.isArray(v)) return '[' + v.map(canonicalJson).join(',') + ']'
+  const keys = Object.keys(v).sort()
+  return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonicalJson(v[k])).join(',') + '}'
+}
+
+function sha256HexPre(text) {
+  return createHash('sha256').update(String(text), 'utf8').digest('hex')
+}
+
+/**
+ * **miv 单源**（P1 步 2）：`memoryIndexVersionPre(projection)`。
+ *
+ * ⚠️ **与既有实现的边界（2026-09-15 施工期核实，必须分清）**：
+ *   本函数算的是 **"状态清单摘要"口径**的 miv —— 输入是**规范化投影**
+ *   （`{records:[{id,status,l0?}], boardCards?}`），用于「同一份快照」的**身份判定**，
+ *   以及 pinned 状态进入摘要（状态变了 miv 必变）。
+ *   它**不替换**契约 §8 的 `shadow-retrieval.js:145 memoryIndexVersion(sources)` ——
+ *   那个吃的是 **source tuples**（scope/sourceRef/epoch/version/fileDigest），是**建索引**侧的真源。
+ *   两者**输入不同、用途不同**，不可互相替换；本函数是"提交边界侧"的口径，
+ *   且**刻意保持与 §8 相同的前缀与长度**（`idx_` + 32 hex），使二者在外部看来同形。
+ *
+ * ⚠️ 本函数**不负责**收敛 `index.js:4188 tierCurrentMivPre()`（那处的缓存/指纹语义属 T0-2 已交付内容），
+ *    P1 不动它 —— 见设计稿 §2.2 边界说明。任何"用本函数替换 tier 自造版"的改动都**不在 P1 范围**。
+ *
+ * 输入：`{ records: [{id, status, l0?}], boardCards?: [{id, status}], scope? }`
+ * 输出：`'idx_' + first32hex(sha256(canonical))`
+ *
+ * canonical 构成（按 id 升序，换行拼接，无尾随空白）：
+ *   每条 → `<id>\t<status>\t<contentDigest>`；`contentDigest` = 内容摘要（无内容时取空串）。
+ *   `boardCards` 若给出，追加在 records 之后（同样排序）—— 白板卡片状态变化也进摘要。
+ *
+ * ⚠️ **不递增、不比较**。这是哈希身份。`rebuilt_at`（时间戳）**不得**参与本函数，也不得
+ *    被任何调用方当作版本序使用 —— 见文件头第 3 条硬规则。
+ */
+export function memoryIndexVersionPre(projection) {
+  const o = projection && typeof projection === 'object' ? projection : {}
+  const records = Array.isArray(o.records) ? o.records : []
+  const boardCards = Array.isArray(o.boardCards) ? o.boardCards : []
+  const tuples = []
+  for (const r of records) {
+    if (!r || typeof r !== 'object') continue
+    const id = asNonEmptyString(r.id)
+    if (!id) continue
+    const status = asNonEmptyString(r.status) || ''
+    const contentDigest = r.l0 == null ? '' : sha256HexPre(canonicalJson(r.l0)).slice(0, 16)
+    tuples.push([id, status, contentDigest])
+  }
+  for (const c of boardCards) {
+    if (!c || typeof c !== 'object') continue
+    const id = asNonEmptyString(c.id)
+    if (!id) continue
+    tuples.push(['board:' + id, asNonEmptyString(c.status) || '', ''])
+  }
+  tuples.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+  const canonical = tuples.map((t) => t.join('\t')).join('\n')
+  return MIV_PREFIX_PRE + sha256HexPre(canonical).slice(0, 32)
+}
+
+/**
+ * **boardId 派生**（卡内硬约束）：工作区内稳定、**不含 sessionId**。
+ *
+ * ⚠️ 入参**只接受 workspaceKey 与 scope**。刻意不接收 sessionId/agent 对象 ——
+ *    从签名上就杜绝"顺手把会话号掺进去"这个错误。
+ */
+export function boardIdPre(workspaceKey, scope) {
+  const ws = asNonEmptyString(workspaceKey)
+  if (!ws) return null
+  const sc = asNonEmptyString(scope) || 'Workspace'
+  return 'board_' + sha256HexPre(ws + '|' + sc).slice(0, 24)
+}
+
+/**
+ * 构造并校验提交单据（P1 步 1）。
+ *
+ * 形状：`{ workspaceKey, boardId, txId, expectedDigest?, expectedStateVersion?,
+ *          actor: { sessionId, contSeq?, kind }, writes: [{ path, content, expectedDigest? }],
+ *          stateChanges?: [{ target, from, to }] }`
+ *
+ * **fail-closed**：缺必填字段 / actor 形状非法 / writes 非数组 ⇒ `{ok:false}`，不猜测、不补默认值。
+ *
+ * **向后兼容（T1-8）**：`expectedStateVersion` 与 `expectedDigest` 均为**可选**；
+ * 不传时下游行为必须与本契约引入前**逐字节一致**（该校验由调用方在队列内执行）。
+ */
+export function buildStateCommitPre(input) {
+  const o = input && typeof input === 'object' ? input : null
+  if (!o) return { ok: false, reason: 'not-object', detail: describeCommitReasonPre('not-object') }
+
+  const missing = []
+  const workspaceKey = asNonEmptyString(o.workspaceKey)
+  if (!workspaceKey) missing.push('workspaceKey')
+  const boardId = asNonEmptyString(o.boardId)
+  if (!boardId) missing.push('boardId')
+  const txId = asNonEmptyString(o.txId)
+  if (!txId) missing.push('txId')
+
+  const actor = o.actor && typeof o.actor === 'object' ? o.actor : null
+  const actorSession = actor ? asNonEmptyString(actor.sessionId) : null
+  const actorKind = actor ? asNonEmptyString(actor.kind) : null
+  if (!actor || !actorSession || !actorKind) {
+    return { ok: false, reason: 'actor-invalid', detail: describeCommitReasonPre('actor-invalid'), missing: actor ? ['actor.sessionId', 'actor.kind'] : ['actor'] }
+  }
+  if (missing.length) {
+    return { ok: false, reason: 'missing-field', detail: describeCommitReasonPre('missing-field'), missing }
+  }
+
+  if (o.writes !== undefined && !Array.isArray(o.writes)) {
+    return { ok: false, reason: 'invalid-writes', detail: describeCommitReasonPre('invalid-writes') }
+  }
+
+  const commit = {
+    schemaVersion: STATE_COMMIT_VERSION_PRE,
+    workspaceKey,
+    boardId,
+    txId,
+    actor: {
+      sessionId: actorSession,
+      contSeq: Number.isFinite(Number(actor.contSeq)) ? Number(actor.contSeq) : undefined,
+      kind: actorKind,
+    },
+    writes: Array.isArray(o.writes) ? o.writes : [],
+    stateChanges: Array.isArray(o.stateChanges) ? o.stateChanges : [],
+  }
+  // 可选字段：仅在显式给出时带上（保证"不传 = 行为不变"）
+  if (o.expectedDigest != null) commit.expectedDigest = String(o.expectedDigest)
+  if (o.expectedStateVersion != null) commit.expectedStateVersion = String(o.expectedStateVersion)
+  return { ok: true, commit }
+}
+
+/**
+ * 冲突描述（卡内 T1-7C 要求：拒绝信息必须带**当前版本 + 冲突目标**，不静默覆盖）。
+ * 纯函数：只组装信息，不做 IO。
+ */
+export function commitConflictPre(commit, observed) {
+  const c = commit && typeof commit === 'object' ? commit : {}
+  const ob = observed && typeof observed === 'object' ? observed : {}
+  const expected = c.expectedStateVersion != null ? String(c.expectedStateVersion) : (c.expectedDigest != null ? String(c.expectedDigest) : '(none)')
+  const actual = ob.stateVersion != null ? String(ob.stateVersion) : (ob.fileDigest != null ? String(ob.fileDigest) : '(unknown)')
+  const target = ob.target != null ? String(ob.target) : (Array.isArray(c.writes) && c.writes[0] && c.writes[0].path ? String(c.writes[0].path) : '(unknown)')
+  const who = c.actor && c.actor.sessionId ? String(c.actor.sessionId) : '(unknown)'
+  const contSeq = c.actor && c.actor.contSeq != null ? '@' + String(c.actor.contSeq) : ''
+  const which = ob.kind === 'state-version' ? 'state-version-mismatch' : 'digest-mismatch'
+  return {
+    ok: false,
+    reason: which,
+    detail: describeCommitReasonPre(which),
+    // 可见冲突三要素：期望值 / 实测值 / 冲突目标（+ 谁）
+    expected,
+    observed: actual,
+    target,
+    txId: c.txId != null ? String(c.txId) : '',
+    boardId: c.boardId != null ? String(c.boardId) : '',
+    actor: who + contSeq,
+    text: '[提交被拒] tx=' + (c.txId != null ? String(c.txId) : '(none)')
+      + ' 目标=' + target
+      + ' 期望=' + expected + ' 实测=' + actual
+      + ' 冲突方=' + who + contSeq,
+  }
+}
+
+/** 成功回执：提交边界返回的可观测凭据（含 miv —— 快照侧据此判"同一份"）。 */
+export function commitReceiptPre(commit, result) {
+  const c = commit && typeof commit === 'object' ? commit : {}
+  const r = result && typeof result === 'object' ? result : {}
+  return {
+    schemaVersion: STATE_COMMIT_VERSION_PRE,
+    ok: true,
+    txId: c.txId != null ? String(c.txId) : '',
+    boardId: c.boardId != null ? String(c.boardId) : '',
+    workspaceKey: c.workspaceKey != null ? String(c.workspaceKey) : '',
+    digest: r.digest != null ? String(r.digest) : '',
+    stateVersion: r.stateVersion != null ? String(r.stateVersion) : '',
+    miv: r.miv != null ? String(r.miv) : '',
+    at: Number.isFinite(Number(r.at)) ? Number(r.at) : Date.now(),
+    actor: c.actor && c.actor.sessionId ? String(c.actor.sessionId) : '',
+  }
+}

package/lib/storage-manage.js

@@ -116,6 +116,12 @@ export function createStorageManagerPre(opts = {}) {
   /** 读取既有 sidecar(尽力而为):用于 rebuildSidecar 继承 epoch/version,避免无谓的 epoch 漂移。 */
   function readSidecarPrev(file) {
     try {
+      // ★ issue #55 修复（2026-09-18，2026-09-19 补回）：函数体内**自行活读** docStore。
+      //   旧写法直接引用闭包里的 `docStore`，但该名只在 `repair`/`deleteMemory` 内部局部声明
+      //   ⇒ 本函数作用域内**未定义** ⇒ 每次调用抛 ReferenceError ⇒ 被下方 `catch (_)` 吞掉
+      //   ⇒ **恒返回 null** ⇒ `rebuildSidecar` 拿不到 prev ⇒ epoch 漂移、fresh 被翻成 stale。
+      //   必须走 `docStoreOf()` 工厂活读（getter 语义：memoryAnchorEnabled 后续生效也能拿到）。
+      const docStore = docStoreOf()
       if (!docStore || typeof docStore.sidecarPath !== 'function') return null
       const sp = docStore.sidecarPath(file)
       if (!sp) return null

package/lib/subagent-gc.js

@@ -23,6 +23,7 @@ import { readdir, stat, rename, mkdir, access } from 'node:fs/promises'
 import { readFile } from 'node:fs/promises'
 import { zstdDecompressSync } from 'node:zlib'
 import path from 'node:path'
+import { retryRename } from './fs-retry.js'
 
 /** 本插件 spawn 的子代理 label 前缀(runSubagent 的 label 参数)。 */
 export const PLUGIN_LABEL_PREFIX = 'auto-memory-'
@@ -258,14 +259,9 @@ export async function recycleSessions(opts = {}) {
       if (await exists(destDir)) { out.skipped.push({ sid: c.sid, reason: 'backup-exists' }); continue }
       if (!apply) { out.moved.push({ sid: c.sid, label: c.label, sizeBytes: c.sizeBytes, to: destDir, dryRun: true }); out.bytes += c.sizeBytes; continue }
       await mkdir(path.dirname(destDir), { recursive: true })
-      // Windows 下 rename 对被占用目录抛 EPERM(宿主/杀软句柄未释放)→ 短退避重试,仍失败则跳过等下次
-      let renamed = false
-      let lastErr = null
-      for (const delay of [0, 250, 800, 2000]) {
-        if (delay) await new Promise((r) => setTimeout(r, delay))
-        try { await rename(c.dir, destDir); renamed = true; break } catch (e) { lastErr = e }
-      }
-      if (!renamed) throw lastErr
+      // Windows 下 rename 对被占用目录抛 EPERM(宿主/杀软句柄未释放)⇒ 复用统一的有界退避重试
+      // (issue #48:退避语义此前在本文件与 index.js 各写一份,口径漂移风险高)。
+      await retryRename(c.dir, destDir, { fs: { rename }, delays: [0, 250, 800, 2000] })
       out.moved.push({ sid: c.sid, label: c.label, sizeBytes: c.sizeBytes, to: destDir })
       out.bytes += c.sizeBytes
       if (projcacheRoot) {