sage-mem 2.1.11 → 2.1.13

package/README.md

@@ -12,7 +12,7 @@
 
 **Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.**
 
-**Current release: `2.1.11`** — 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.13`** — 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.
@@ -420,6 +420,8 @@ The two things are moved **differently**, spelled out:
 
 Value semantics: **out-of-range values are clamped to the boundary, illegal values (including pure whitespace) fall back to the default.**
 
+**Scope of the state root, and migration (spelled out since 2.1.13).** `SAGE_MEM_STATE_DIR` is the **single** state root: settings, autodream configuration and reports, the lock table, the access ledger, the conflict queue, task checkpoints, rollback snapshots and its index all live under it, and every module (including the autodream engine and the lock table) resolves it from the same value instead of re-deriving `<parent of the memory directory>/.sage-mem`. **Changing the state root does not migrate old data**: the new root wins, the old `.sage-mem` is left untouched but no longer read, and startup prints one line naming what is still in the old root. Move it by hand if you want to keep it.
+
 ### What the Settings Page Can Change
 
 The panel can change the five caps above (written to `<state directory>/settings.json`, precedence **settings page > environment variable > built-in default**), as well as reserved names (file names that are protected and that the settings page may not write or delete, written to `<state directory>/reserved.json`). **Some items take effect only after restarting DSH**, and the panel writes out both the value in effect now and the value after restart.

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.11`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
+**当前发布版本：`2.1.13`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
 [契约冻结](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md)。
 
 如果它对你有用，给个 Star 是最直接的反馈。
@@ -420,6 +420,8 @@ sage-mem 给记忆目录的写入加了**版本守卫**：写入前记下当前
 
 取值语义：**越界夹到边界，非法值（含纯空格）回落默认。**
 
+**状态根的范围与迁移（2.1.13 起写清）**：`SAGE_MEM_STATE_DIR` 是**唯一的状态根** —— 设置、自动做梦配置与报告、锁表、访问台账、冲突队列、任务检查点、回滚快照、台账都在它下面，插件内所有模块（含自动做梦引擎与锁表）都从同一个值解析，不再各自按记忆目录的父目录去拼。**更改状态根不会自动迁移旧数据**：新根优先、旧的 `.sage-mem` 原样保留但不再读取，启动时会打印一行提示点名旧根里还有哪些数据；要保留请手动移动。
+
 ### 设置页里能改的
 
 面板可改上面五个上限（写入 `<状态目录>/settings.json`，优先级 **设置页 > 环境变量 > 内置默认**），以及保留名（受保护、设置页不许写删的文件名，写入 `<状态目录>/reserved.json`）。**部分项要重启 DSH 才生效**，面板上会写清「当前生效 / 重启后」。

package/lib/assembly/autodream-mount.js

@@ -6,11 +6,16 @@
  * 这是本插件唯一一处「降级而不是失败」的设计，理由就在这里。
  */
 import { warnLog } from '../memory/util.js'
+import { resolvePaths } from '../memory/config.js'
 
 /** @param {object} ctx @param {{AutodreamEngine:Function, AutodreamGateway:Function, memoryDir:string, sessionsRoot:string, reservedFiles:string[]}} deps */
 export function mountAutodream(ctx, { AutodreamEngine, AutodreamGateway, memoryDir, sessionsRoot, reservedFiles }) {
   try {
-    const engine = new AutodreamEngine(ctx, { memoryDir, sessionsRoot, reservedFiles })
+    // Q09：路径组在 `config.js` 里**一次**解析，这里显式把 stateRoot 交给引擎 ——
+    // 旧实现让引擎从 memoryDir 的父目录重拼 `.sage-mem`，于是 SAGE_MEM_STATE_DIR 只对
+    // 配置模块生效，面板与引擎各读一套（审查实测 engineRoot 指向默认根）。
+    const paths = resolvePaths({ memoryDir, sessionsRoot })
+    const engine = new AutodreamEngine(ctx, { ...paths, reservedFiles })
     new AutodreamGateway(ctx, engine)
     engine.start()
     // 卸载时把定时器与锁收干净。effect 拿不到就交给 unref 兜底（不阻止进程退出）。

package/lib/autodream/engine.js

@@ -40,7 +40,9 @@ import { countSessionsSince, newRunId, stampHuman } from './util.js'
 import { flushAccess, ledgerFileFor, pickArchiveCandidates, readAccessLedger } from '../memory/access.js'
 import { archiveMemory } from '../memory/archive.js'
 import { scanMemoryFiles } from '../memory/scan.js'
-import { dirname, join } from 'node:path'
+import { resolveStateRoot } from '../memory/config.js'
+import { basename, dirname, join } from 'node:path'
+import { stat } from 'node:fs/promises'
 
 import * as gateMod from './gate.js'
 import * as llmloopMod from './llm-loop.js'
@@ -86,7 +88,18 @@ export class AutodreamEngine {
     this.version = opts.version
     /** 使用者自己声明的受保护文件名（`<状态根>/reserved.json`）——注入 prompt，绝不写死。 */
     this.reservedFiles = Array.isArray(opts.reservedFiles) ? opts.reservedFiles : []
-    this.stateRoot = join(dirname(this.memoryDir), STATE_DIR)
+    /**
+     * 状态根（Q09）：装配方**显式传入**（`config.js` 的 `resolvePaths()` 一次解析）；
+     * 直接构造引擎（单测 / 旧调用方）时按 `resolveStateRoot()` 派生 —— 两条路同一判据，
+     * 不再在这里 `dirname(memoryDir)` 重拼 `.sage-mem`。
+     */
+    this.stateRoot = typeof opts.stateRoot === 'string' && opts.stateRoot !== ''
+      ? opts.stateRoot
+      : resolveStateRoot(this.memoryDir)
+    /** 旧状态根：只有「本次状态根 ≠ 按记忆目录派生的那个」时才存在（迁移提示用）。 */
+    const derivedStateRoot = join(dirname(this.memoryDir), STATE_DIR)
+    this.legacyStateRoot = this.stateRoot === derivedStateRoot ? '' : derivedStateRoot
+    this._legacyStateReported = false
     this.home = join(this.stateRoot, FEATURE_DIR)
     this.configPath = join(this.stateRoot, 'autodream.json')
     this.legacyConfigPath = join(this.stateRoot, LEGACY_STATE_FILE)
@@ -128,7 +141,37 @@ export class AutodreamEngine {
   // ────────────────────────────── 配置与状态 ──────────────────────────────
 
   // ── 配置与状态：实现在 lib/autodream/settings.js ──
-  async load() { return settingsMod.load.call(this) }
+  async load() {
+    const state = await settingsMod.load.call(this)
+    // 启动检查 / 面板打开都会走到 load()：在这里提示一次「旧状态根还有数据」。
+    await this.checkLegacyStateRoot()
+    return state
+  }
+
+  /**
+   * Q09 的旧目录规则：**不自动迁移 + 启动提示一次**。
+   *
+   * 为什么不做自动迁移：状态根下住着配置、锁表、台账、冲突、检查点、快照六类数据，
+   * 自动搬移任何一类出错都可能让「锁」或「回滚点」在用户不知情时消失 —— 那是比
+   * 「旧数据暂时看不见」严重得多的损失。所以规则写成：**新状态根优先、旧数据留在原位、
+   * 明确告诉用户手动搬**。README 的措辞由 Lead 统一改，G4 只在报告里给出建议口径。
+   */
+  async checkLegacyStateRoot() {
+    if (this._legacyStateReported || !this.legacyStateRoot) return
+    this._legacyStateReported = true
+    const legacy = this.legacyStateRoot
+    const markers = ['autodream.json', LEGACY_STATE_FILE, 'locked.json', 'access.json', 'settings.json', FEATURE_DIR, 'tasks', 'conflicts']
+    const found = []
+    for (const name of markers) {
+      if (await stat(join(legacy, name)).then(() => true, () => false)) found.push(basename(name))
+    }
+    if (found.length === 0) return
+    this.log('warn',
+      `检测到旧状态根 ${legacy} 仍有数据（${found.join(' / ')}），而本次状态根是 ${this.stateRoot}` +
+      '（SAGE_MEM_STATE_DIR 覆写）。本版不自动迁移：旧数据留在原位、不再读取 —— ' +
+      '需要保留请手动把要用的文件移到新状态根。')
+  }
+
   async persist() { return settingsMod.persist.call(this) }
   async getConfig() { return settingsMod.getConfig.call(this) }
   async setConfig(patch) { return settingsMod.setConfig.call(this, patch) }

package/lib/index.js

@@ -19,7 +19,7 @@ import { readSnapshot, writeSnapshot } from './memory/write-protocol.js'
 import { archiveMemory, archivedRevisionOf, deleteArchivedMemory, restoreMemory } from './memory/archive.js'
 import { flushAccess, pickArchiveCandidates, readAccessLedger } from './memory/access.js'
 import { serializeByKey, warnLog, writeFileAtomic } from './memory/util.js'
-import { readLockSet, setLocked as setLockedImpl } from './memory/lock.js'
+import { readLockState, setLocked as setLockedImpl } from './memory/lock.js'
 import { openMemoryFolder } from './memory/open-folder.js'
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
 import { mkdir, unlink, writeFile } from 'node:fs/promises'
@@ -99,7 +99,9 @@ export class MemoryGateway extends TypertRemoteService {
 
   /** 列出 memory 目录全部记忆文件（文件名 + 类型 + 描述 + 大小 + 自定义标签 + 是否锁定）。 */
   async listFiles() {
-    const [files, locked] = await Promise.all([scanMemoryFiles(this.ctx, ''), readLockSet(MEMORY_DIR)])
+    const [files, lockState] = await Promise.all([scanMemoryFiles(this.ctx, ''), readLockState(MEMORY_DIR)])
+    // Q05：锁表坏了也照样列文件，但不假装「都没锁」；逐条 locked 只有布尔，未知只能靠日志。
+    if (lockState.status === 'unknown') warnLog(this.ctx, `锁表不可读，列表里的锁定状态未知（不是「都没锁」）：${lockState.reason}`)
     return files.map(f => {
       const meta = parseFrontmatter(f.content)
       return {
@@ -109,7 +111,7 @@ export class MemoryGateway extends TypertRemoteService {
         size: f.content.length,
         tags: meta.tags,
         // 锁定状态跟着每条一起给：卡片上的「锁定 / 已锁定」按钮要据此渲染
-        locked: locked.has(nameKey(f.file)),
+        locked: lockState.status === 'unknown' ? false : lockState.locked.has(nameKey(f.file)),
       }
     })
   }
@@ -134,18 +136,11 @@ export class MemoryGateway extends TypertRemoteService {
   }
 
   /**
-   * 写（新增或覆盖）单个记忆文件。
-   *
-   * 三道闸：保留名不可写、内容必须是字符串、体积有上限；落盘走原子写。
+   * 写（新增或覆盖）单个记忆文件。三道闸：保留名不可写、内容必须是字符串、体积有上限；落盘走原子写。
    * 拒绝一律返回 { ok: false, error }（不是抛异常）——设置页的调用方按 ok 判定。
-   *
-   * 2.1.2（Q02）：可选第三参 `opts`
-   *   · `{ expectedRevision }`：读快照时拿到的 revision；盘上对不上 → `{ok:false, code:'stale_revision'}`，
-   *     当前内容逐字节不变（面板保留草稿，提示重新应用）；
-   *   · `{ create: true }`：新建语义（createIfAbsent）。撞名 → `{ok:false, code:'already_exists'}`，
-   *     **绝不**覆盖已有正文；
-   *   · 不传 `opts`：旧调用方照旧覆盖，但会落一条 warn（additive 契约里只保留兼容，不保留静默）。
-   * 成功时回 `revision`（落盘后的新版本），调用方可以直接拿它继续保存。
+   * 2.1.2（Q02）新增可选第三参 `opts`：`{ expectedRevision }` 对不上 → `stale_revision`（当前内容逐字节
+   * 不变，面板保留草稿）；`{ create: true }` 撞名 → `already_exists`（绝不覆盖）；不传 opts 走旧行为但落
+   * 一条 warn（additive 契约只保留兼容，不保留静默）。成功时回 `revision`（落盘后的新版本）。
    */
   async writeFile(name, content, opts) {
     // 保留名判定放在最前面、且以 nameKey 归一：'memory.md' / 'MEMORY.MD' /
@@ -408,11 +403,13 @@ export class MemoryGateway extends TypertRemoteService {
 
   async archiveCandidates() {
     await flushAccess(MEMORY_DIR)
-    const [ledger, files, locked] = await Promise.all([
+    const [ledger, files, lockState] = await Promise.all([
       readAccessLedger(),
       scanMemoryFiles(this.ctx, ''),
-      readLockSet(MEMORY_DIR),
+      readLockState(MEMORY_DIR),
     ])
+    // Q05：锁表不可读时如实标记（候选清单仍可看，自动归档由 archiveMemory 直接拒绝）。
+    if (lockState.status === 'unknown') warnLog(this.ctx, `锁表不可读，候选清单的锁定状态未知（自动归档会拒绝执行）：${lockState.reason}`)
     const cfg = await autodreamConfigSnapshot()
     const thresholds = {
       project: cfg.archiveAfterDaysProject,
@@ -420,14 +417,17 @@ export class MemoryGateway extends TypertRemoteService {
       user: cfg.archiveAfterDaysUser,
     }
     // 锁表交给候选计算：锁上的记忆一个都不选（用户对**单条**记忆说的话优先于阈值）。
-    const candidates = pickArchiveCandidates(files, ledger, { thresholds, locked })
+    const candidates = pickArchiveCandidates(files, ledger, { thresholds, locked: lockState.locked })
     return {
       count: candidates.length,
       candidates,
       autoArchive: cfg.autoArchive,
       thresholds,
       // 面板要显示「哪些锁着」，所以把锁表也带回去（已按 nameKey 归一）
-      locked: [...locked],
+      locked: [...lockState.locked],
+      // Q05：保护状态未知时明确标出来，不把「不知道」渲染成「都没锁」。
+      lockedUnknown: lockState.status === 'unknown',
+      lockedError: lockState.reason,
     }
   }
 

package/lib/memory/archive.js

@@ -19,7 +19,7 @@ import { ARCHIVE_DIR_NAME, addArchiveMeta, inspectDir, inspectMemoryEntry, local
 import { isReserved, nameKey, safeName } from './naming.js'
 import { revisionOf } from './chunks.js'
 import { retireTaken, returnSource, takeOverSource, writeFileAtomic, writeFileExclusive } from './util.js'
-import { isLocked } from './lock.js'
+import { readLockState } from './lock.js'
 import { ensureIndexEntry, dropIndexEntry } from './index-file.js'
 import { mkdir, readFile, rm, stat } from 'node:fs/promises'
 import { basename, join } from 'node:path'
@@ -54,8 +54,20 @@ export async function archiveMemory(memoryDir, name, reason, at = localStamp())
   /**
    * 「锁定」优先于一切：锁上的记忆**自动与手动都不许归档**。
    * 放在最前面判 —— 名字合法之后立刻拒绝，不读目录、不算理由。
+   *
+   * ⚠️ 2.1.12（Q05）：锁表读不出来时**不猜**。旧实现把「保护状态未知」当成空表，
+   * 于是坏表会让受保护的记忆照常被移走。现在未知 = 拒绝归档（危险操作暂停），
+   * 错误码 `lock-unknown` 让调用方/报告能说清是「锁表坏了」而不是「文件有问题」。
    */
-  if (await isLocked(memoryDir, safe)) {
+  const lock = await readLockState(memoryDir)
+  if (lock.status === 'unknown') {
+    return {
+      ok: false,
+      code: 'lock-unknown',
+      error: `sage-mem: 锁表不可读（${lock.reason}），无法确认这条记忆是否受保护，拒绝归档：${safe}`,
+    }
+  }
+  if (lock.locked.has(nameKey(safe))) {
     return { ok: false, code: 'locked', error: `sage-mem: locked, refusing to archive: ${safe}（先在界面里解锁）` }
   }
   const src = join(memoryDir, safe)

package/lib/memory/config.js

@@ -22,11 +22,37 @@ export const SESSIONS_ROOT = process.env.DSH_HOME ? join(process.env.DSH_HOME, '
  * 状态根：配置、锁表、台账、冲突、检查点、快照都住在这里。
  *
  * `SAGE_MEM_STATE_DIR` 显式覆写优先；没设时跟着记忆目录走（它的上一层 + `.sage-mem`）。
- * ⚠️ Q09：**所有子模块都必须从这里取**，不许各自 `dirname(memoryDir)` + 拼 `.sage-mem` ——
- * 那样覆写只对一部分模块生效，面板与引擎会各读一套配置。
+ * ⚠️ Q09：**所有子模块都必须经 `resolveStateRoot()` / `resolvePaths()` 取**，不许各自
+ * `dirname(memoryDir)` + 拼 `.sage-mem` —— 那样覆写只对一部分模块生效，面板与引擎会各读一套。
  */
-export const STATE_ROOT = process.env.SAGE_MEM_STATE_DIR || join(dirname(MEMORY_DIR), '.sage-mem')
+export function resolveStateRoot(memoryDir = MEMORY_DIR) {
+  // 默认记忆目录直接用装配期算好的 STATE_ROOT（含 SAGE_MEM_STATE_DIR 覆写）；
+  // 调用方显式传了**别的**目录（autodream 单测 / 多库场景）时，状态跟着那个目录走 ——
+  // 否则一个全局环境变量会把互不相关的记忆库的锁表 / 快照全灌进同一个目录。
+  if (memoryDir === MEMORY_DIR) return process.env.SAGE_MEM_STATE_DIR || join(dirname(MEMORY_DIR), '.sage-mem')
+  return join(dirname(memoryDir), '.sage-mem')
+}
+
+/**
+ * **装配时一次解析**的路径组（Q09）。
+ *
+ * 三个路径只在这里算一次，然后显式传给子模块 —— 引擎、锁表、台账、冲突、检查点、快照
+ * 不能再各自重拼。可显式覆写（测试 / 多库）：
+ *   - `memoryDir` 给了就用它；没给用模块常量
+ *   - `stateRoot` 给了就用它；否则按 `resolveStateRoot(memoryDir)` 派生
+ *   - `sessionsRoot` 给了（含空串）就用它；否则用模块常量
+ */
+export function resolvePaths(overrides = {}) {
+  const memoryDir = overrides.memoryDir || MEMORY_DIR
+  const stateRoot = typeof overrides.stateRoot === 'string' && overrides.stateRoot !== ''
+    ? overrides.stateRoot
+    : resolveStateRoot(memoryDir)
+  const sessionsRoot = overrides.sessionsRoot !== undefined ? overrides.sessionsRoot : SESSIONS_ROOT
+  return { memoryDir, stateRoot, sessionsRoot }
+}
 
+export const PATHS = Object.freeze(resolvePaths())
+export const STATE_ROOT = PATHS.stateRoot
 /** 读一个整数型环境变量并在范围内收敛；取不到或非法就用默认值。 */
 export function envInt(name, dflt, lo, hi) {
   // ⚠️ 必须先 trim：`Number('   ')` 是 **0** 而不是 NaN，于是纯空格的值会被

package/lib/memory/lock.js

@@ -9,36 +9,112 @@
  *
  * 锁表按 `nameKey()` 归一存放：NTFS 不区分大小写，`User_Persona.MD` 与 `user_persona.md`
  * 是同一个文件 —— 锁必须认得出这一点（与保留名保护同一套判据）。
+ *
+ * ── 2.1.12（外部审查 Q05）──────────────────────────────────────────────
+ * 旧实现两处硬伤，都已修：
+ *   1. 整文件 read-modify-write **没有排队**：两个并发上锁各自读到旧表，后写的把先写的
+ *      盖掉，而两边都报成功。原子 rename 只保证「不写半截」，不负责「合并两处修改」。
+ *      现在按锁表路径分键复用 `util.js` 的 `createWriteQueue()` 串行 RMW。
+ *   2. 读任何异常都返回空 Set —— 「保护状态未知」与「确实没有锁」因此无法区分，
+ *      自动归档会把**受保护**的记忆当成没锁继续删。现在只有 ENOENT 算「确实没有锁」；
+ *      坏 JSON / 权限失败 / 路径是目录……一律 `status:'unknown'`，危险操作据此暂停。
  */
 import { mkdir, readFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { nameKey } from './naming.js'
-import { writeFileAtomic } from './util.js'
+import { resolveStateRoot } from './config.js'
+import { createWriteQueue, writeFileAtomic } from './util.js'
 
-/** 锁表文件：状态根下，与记忆文件分开。 */
-export function lockFileOf(memoryDir) {
-  return join(dirname(memoryDir), '.sage-mem', 'locked.json')
+/**
+ * 锁表文件：状态根下，与记忆文件分开。
+ *
+ * ⚠️ Q09：状态根必须经 `config.js` 的 `resolveStateRoot()` 解析（尊重 `SAGE_MEM_STATE_DIR`），
+ * 不许在这里 `dirname(memoryDir)` + 拼 `.sage-mem` —— 旧写法让「状态目录覆写」只对一部分
+ * 模块生效，于是面板读的锁表与引擎写的是两份。装配期显式给了 `stateRoot` 就用它。
+ */
+export function lockFileOf(memoryDir, stateRoot) {
+  const root = typeof stateRoot === 'string' && stateRoot !== '' ? stateRoot : resolveStateRoot(memoryDir)
+  return join(root, 'locked.json')
 }
 
 /**
- * 读锁表。读不到 / JSON 坏 / 不是对象 / 值不是 `true` → 一律当空表。
- * **绝不抛**：锁表坏了最坏是「锁没生效」，不该升级成「读不了记忆」。
+ * 锁表的**进程内串行队列**，按锁表路径分键（不同记忆目录互不阻塞）。
+ *
+ * ⚠️ 边界与 `util.js` 的说明一致：进程内串行，不是跨进程文件锁。真实并发（面板 remote、
+ * 模型工具、归档策略）都在同一个插件进程里；同时开两个 DSH 实例写同一个记忆目录时仍可能
+ * 丢一次 —— 那要另加文件锁，本版明确不做。
  */
-export async function readLockSet(memoryDir) {
+const lockQueues = new Map()
+function lockQueueFor(file) {
+  let queue = lockQueues.get(file)
+  if (!queue) {
+    queue = createWriteQueue()
+    lockQueues.set(file, queue)
+  }
+  return queue
+}
+
+/**
+ * 读锁表**原始对象**，区分「确实没有」与「不知道」。
+ *
+ * @returns {Promise<{status:'ok'|'missing'|'unknown', table:object, reason:string}>}
+ */
+async function readLockTable(memoryDir) {
+  let text
   try {
-    const parsed = JSON.parse(await readFile(lockFileOf(memoryDir), 'utf8'))
-    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return new Set()
-    const out = new Set()
-    for (const [k, v] of Object.entries(parsed)) {
-      if (v === true) out.add(nameKey(k))
-    }
-    return out
-  } catch {
-    return new Set()
+    text = await readFile(lockFileOf(memoryDir), 'utf8')
+  } catch (err) {
+    // 只有 ENOENT 可以当空表：文件不存在 = 一次锁都没上过。
+    if (err?.code === 'ENOENT') return { status: 'missing', table: {}, reason: '' }
+    return { status: 'unknown', table: {}, reason: `读锁表失败（${err?.code || err?.message}）` }
+  }
+  let parsed
+  try {
+    parsed = JSON.parse(text)
+  } catch (err) {
+    return { status: 'unknown', table: {}, reason: `锁表不是合法 JSON（${err?.message ?? err}）` }
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { status: 'unknown', table: {}, reason: '锁表不是 JSON 对象' }
+  }
+  return { status: 'ok', table: parsed, reason: '' }
+}
+
+/**
+ * 读锁状态 —— **安全路径唯一该用的读口**。
+ *
+ *   - `{status:'ok', locked:Set}`：读到有效表（可能为空）
+ *   - `{status:'missing', locked:Set()}`：锁表不存在 = 确实没有锁
+ *   - `{status:'unknown', locked:Set(), reason}`：保护状态**未知**，自动归档必须暂停
+ *
+ * ⚠️ `unknown` 时返回的 `locked` 是**空集合**，但它不表示「没有锁」；调用方必须先看
+ * `status`，拿它当空表用就是把 Q05 原样放回去。
+ */
+export async function readLockState(memoryDir) {
+  const read = await readLockTable(memoryDir)
+  if (read.status === 'unknown') return { status: 'unknown', locked: new Set(), reason: read.reason }
+  const out = new Set()
+  for (const [k, v] of Object.entries(read.table)) {
+    if (v === true) out.add(nameKey(k))
   }
+  return { status: read.status, locked: out, reason: '' }
 }
 
-/** 这条记忆锁上了吗。 */
+/**
+ * 兼容出口：只要集合的调用方用这个。
+ *
+ * 与 `readLockState` 的差别只有一条：`unknown` 时**抛** `LOCK_TABLE_UNKNOWN`，而不是
+ * 返回空 Set —— 返回空 Set 正是「坏表当全解锁」这个 bug 的入口。缺文件仍返回空 Set。
+ */
+export async function readLockSet(memoryDir) {
+  const state = await readLockState(memoryDir)
+  if (state.status === 'unknown') {
+    throw Object.assign(new Error(`sage-mem: ${state.reason}`), { code: 'LOCK_TABLE_UNKNOWN', reason: state.reason })
+  }
+  return state.locked
+}
+
+/** 这条记忆锁上了吗。`unknown` 时抛错（调用方不能把「不知道」当成「没锁」）。 */
 export async function isLocked(memoryDir, name) {
   return (await readLockSet(memoryDir)).has(nameKey(name))
 }
@@ -46,23 +122,29 @@ export async function isLocked(memoryDir, name) {
 /**
  * 上锁 / 解锁。
  *
- * 读-改-写：两张并发的锁操作理论上会互相覆盖（丢一次锁）。这里**不引入锁**：
- * 代价是「同时锁两条记忆时可能少一条」，而这远轻于给一个状态文件加一套锁 ——
- * 重按一次就好，用户看得见结果。
+ * RMW 全程在**按锁表路径分键的进程内队列**里：读最新表 → 改一项 → 原子写回。
+ * 并发的不同文件因此逐条合并，不再互相覆盖。
+ *
+ * 坏表上**拒绝写入**（`{ok:false, code:'lock-table-unknown'}`），而不是把表重置成空表 ——
+ * 后者会静默抹掉用户的全部保护状态，比「这次没锁上」严重得多。
  */
 export async function setLocked(memoryDir, name, locked) {
   const key = nameKey(name)
   const file = lockFileOf(memoryDir)
-  let table = {}
-  try {
-    const parsed = JSON.parse(await readFile(file, 'utf8'))
-    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) table = parsed
-  } catch {
-    table = {}
-  }
-  if (locked) table[key] = true
-  else delete table[key]
-  await mkdir(dirname(file), { recursive: true })
-  await writeFileAtomic(file, JSON.stringify(table, null, 2) + '\n')
-  return { ok: true, file: name, locked: !!locked }
+  return lockQueueFor(file)(async () => {
+    const read = await readLockTable(memoryDir)
+    if (read.status === 'unknown') {
+      return {
+        ok: false,
+        code: 'lock-table-unknown',
+        error: `sage-mem: 锁表不可读（${read.reason}），本次没有写入，也不会把它重置成空表：${name}`,
+      }
+    }
+    const table = { ...read.table }
+    if (locked) table[key] = true
+    else delete table[key]
+    await mkdir(dirname(file), { recursive: true })
+    await writeFileAtomic(file, JSON.stringify(table, null, 2) + '\n')
+    return { ok: true, file: name, locked: !!locked }
+  })
 }

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