sage-mem 2.1.10 → 2.1.12

package/README.md

@@ -12,7 +12,7 @@
 
 **Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.**
 
-**Current release: `2.1.10`** — 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.12`** — the npm badge above is the dynamic source of truth. **Contract baseline: `1.0.0`** — the first stable release, whose public commitments, the capability boundaries and the list of things it explicitly cannot do are frozen in the
 [frozen contract](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md).
 
 If it is useful to you, a Star is the most direct feedback.

package/README.zh.md

@@ -14,7 +14,7 @@
 
 > File-based cross-session memory for DeepSeek Harness — every memory is a plain markdown file you can open, edit and delete. No database, no worker, no port.
 
-**当前发布版本：`2.1.10`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
+**当前发布版本：`2.1.12`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
 [契约冻结](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md)。
 
 如果它对你有用，给个 Star 是最直接的反馈。

package/lib/index.js

@@ -1,15 +1,13 @@
 /**
  * sage-mem — 文件式记忆插件。记忆存在本地 markdown 目录（frontmatter + 正文，4 类），不是数据库。
- * host 侧三件事：① 按问题检索注入：system-prompt/assemble 时扫 memory 目录、按双字匹配选相关文件，
- * 读全文注入 system prompt，让 agent 第一轮就「想起」；② TypertRemoteService：给设置页「记忆管理」
- * 提供文件列表/读/写/删；③ autodream（自动做梦）：可选的记忆整理，见 lib/autodream.js。
- *
- * 写入靠 AGENTS.md 的「记忆使用」规则引导 agent 自己判断 + 用文件工具写 memory 目录——透明、可检查、
- * 防膨胀。无 worker、无 SQLite、无端口。旧 worker 版见 git 分支 `sqlite-worker`。
+ * host 侧三件事：① 注入（assemble 时扫目录、按双字匹配选文件，读全文注入 system prompt）；
+ * ② TypertRemoteService（设置页 / 面板的文件读写删）；③ autodream（可选的记忆整理，见 lib/autodream.js）。
+ * 写入靠 AGENTS.md 的「记忆使用」规则引导 agent 自己判断 + 用文件工具写；透明、可检查、防膨胀。
+ * 无 worker / 无 SQLite / 无端口；旧 worker 版见 git 分支 `sqlite-worker`。
  */
 
 import { AutodreamEngine, DEFAULT_CONFIG, auditMemoryDir } from './autodream.js'
-import { LIMIT_SPECS, MAX_BASELINE, MAX_CHARS_PER_FILE, MAX_FILE_BYTES, MAX_RESULTS, MAX_SESSION_BYTES, MEMORY_DIR, RECALL_DISCIPLINE, RESERVED_FILES, SESSIONS_ROOT, STALE_DAYS, STATE_ROOT } from './memory/config.js'
+import { LIMIT_SPECS, MAX_BASELINE, MAX_CHARS_PER_FILE, MAX_FILE_BYTES, MAX_RESULTS, MAX_SESSION_BYTES, MEMORY_DIR, RECALL_DISCIPLINE, RESERVED_FILES, SESSIONS_ROOT, STALE_DAYS, STARTUP_LIMIT_DIAGNOSTICS, STATE_ROOT, resolveLimits } from './memory/config.js'
 import { INDEX_FILE_KEY, SESSION_LOG_KEY, isPlainMdName } from './shared/md-name.js'
 import { parseAliases, parseBaseline, parseBaselinePriority, parseFrontmatter, parseTags } from './memory/frontmatter.js'
 import { ageDays, bigrams, score, selectBaseline, selectRelevant } from './memory/retrieval.js'
@@ -21,13 +19,13 @@ 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'
 import { join } from 'node:path'
 import { checkUpdate as checkUpdateImpl } from './update.js'
-import { autodreamConfigSnapshot, clampInt, MAX_RAW_BYTES, parseUiPatch, pendingLimits, pendingUi, rawName, readReservedFile, readSettingsFile, RESERVED_FILE, SETTINGS_FILE } from './settings.js'
+import { autodreamConfigSnapshot, clampInt, MAX_RAW_BYTES, parseUiPatch, pendingUi, rawName, readReservedFile, readSettingsFileDetailed, RESERVED_FILE, SETTINGS_FILE } from './settings.js'
 import { createRecallInjector, createSessionInjectState, readRecallDebug } from './recall/index.js'
 import { mountAutodream, mountMemoryTools, mountObserve, mountWriteGate } from './assembly/index.js'
 
@@ -81,10 +79,8 @@ export class MemoryGateway extends TypertRemoteService {
   }
 
   /**
-   * 查有没有新版本（面板进入时静默调一次）。
-   *
-   * 实现全在 `lib/update.js`：**当前版本运行时读自己的 `package.json`**（不内联常量 ——
-   * 内联会在「构建早于 bump」时停留在旧版本，插件于是永远对自己报「有新版本」）；
+   * 查有没有新版本（面板进入时静默调一次）。实现全在 `lib/update.js`：版本运行时读自己的
+   * `package.json`（不内联常量 —— 内联会在「构建早于 bump」时停在旧版本、永远报有新版本）；
    * 查不到一律降级为「不提示」，绝不在界面上冒红条。
    */
   async checkUpdate() {
@@ -92,11 +88,10 @@ export class MemoryGateway extends TypertRemoteService {
   }
 
   /**
-   * 最近几次注入尝试的账（1.7.0 面板「工具 → 注入调试」的唯一数据源）。
-   *
-   * **只读、不落盘**：数据是注入链在 `SAGE_MEM_DEBUG=1` 时记进进程内存的环形缓冲
-   * （见 `lib/recall/debug.js`）；开关关着时返回 `{ enabled: false, records: [] }`，
-   * 面板据此不显示入口。不提供「清空 / 修改」能力 —— 一份账记下来就是那一刻的事实。
+   * 最近几次注入尝试的账（1.7.0 面板「工具 → 注入调试」的唯一数据源）。**只读、不落盘**：
+   * 数据是注入链在 `SAGE_MEM_DEBUG=1` 时记进进程内存的环形缓冲（见 `lib/recall/debug.js`）；
+   * 开关关着时返回 `{ enabled: false, records: [] }`，面板据此不显示入口。不提供清空 / 修改
+   * 能力 —— 一份账记下来就是那一刻的事实。
    */
   async recallDebug() {
     return readRecallDebug()
@@ -104,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 {
@@ -114,19 +111,15 @@ 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)),
       }
     })
   }
 
   /**
-   * 读单个记忆文件全文。
-   *
-   * 过闸门再读：名字在记忆目录里**不等于**内容住在记忆目录里 —— 符号链接 / 目录联接 /
-   * 硬链接都能让一次「读自己的记忆」变成读别人的文件，而读到的内容会被注入模型上下文。
-   *
-   * 2.1.2（Q02）：返回值多一个 `revision`（正文字节的 sha256）。保存时把它带回来，
-   * 盘上版本变了就拒绝覆盖（见 `memory/write-protocol.js`）。
+   * 读单个记忆文件全文。过闸门再读：名字在记忆目录里**不等于**内容住在记忆目录里 ——
+   * 符号链接 / 目录联接 / 硬链接都能让一次「读自己的记忆」变成读别人的文件，而内容会进模型上下文。
+   * 2.1.2（Q02）：返回值多一个 `revision`（正文字节 sha256）；保存时带回来，盘上版本变了就拒绝覆盖。
    */
   async readFile(name) {
     const safe = safeName(name)
@@ -143,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' /
@@ -227,9 +213,8 @@ export class MemoryGateway extends TypertRemoteService {
     const res = await archiveMemory(MEMORY_DIR, name, reason)
     if (!res.ok) return { ok: false, error: res.error }
     /**
-     * ⚠️ `unindexed` / `indexError` 必须**原样透出去**（2026-10-12 复审 R11 的配套）：
-     * 归档本身成功、索引却没摘掉时，这正是用户该被告知的那件事 —— 底下那句
-     * 「索引没摘」在面板上要看得见，不能只活在 host 的返回值里被 strict 剥掉。
+     * ⚠️ `unindexed` / `indexError` 必须**原样透出去**（2026-10-12 复审 R11 的配套）：归档成功、
+     * 索引却没摘掉时，这正是用户该被告知的那件事 —— 面板上要看得见，不能只活在 host 返回值里被 strict 剥掉。
      */
     return {
       ok: true,
@@ -257,15 +242,11 @@ export class MemoryGateway extends TypertRemoteService {
   }
 
   /**
-   * 列出归档区的全部记忆（面板的「已归档」区）。
-   *
-   * 与 `listFiles()` 分开、形状也不同：`listFiles` 只列活动记忆、多一个字段都会破坏
-   * 界面与断言依赖的形状；归档条目额外带 `archivedAt` / `archivedReason` / `revision`。
-   * 旧版 autodream 工具直接移文件、不写留痕，所以前两个字段可能是空串。
-   *
-   * `revision` 是**内容身份**（2026-10-31 外部审查 Q07）：归档代次 + 正文 revision。
-   * 删除确认必须把它交回来 —— `archivedAt` 只是展示时间，同一分钟内不可区分，
-   * 拿它当版本会让「A 改成同时间戳的 B」和「同分钟重新归档」的旧确认删掉新内容。
+   * 列出归档区的全部记忆（面板的「已归档」区）。与 `listFiles()` 分开、形状也不同：那个只列
+   * 活动记忆（多一个字段都会破坏界面与断言依赖的形状）；归档条目额外带 `archivedAt` /
+   * `archivedReason` / `revision`。旧版 autodream 工具直接移文件、不写留痕，所以前两个可能是空串。
+   * `revision` 是**内容身份**（2026-10-31 外部审查 Q07）：归档代次 + 正文 revision，删除确认必须原样交回 ——
+   * `archivedAt` 只是展示时间，同一分钟内不可区分，拿它当版本会让旧确认删掉新内容。
    */
   async listArchived() {
     const files = await scanArchived(this.ctx)
@@ -422,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,
@@ -434,26 +417,27 @@ 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,
     }
   }
 
   /**
-   * 面板上的注入设置（5 项上限 + 保留名保护名单）。
-   *
-   * ⚠️ **这 5 个常量是模块加载时读的**：面板改完要**重启 DSH** 才生效。所以这里同时给出
-   * 「当前生效值」`limits` 与「待生效值」`pendingLimits`，外加 `restartRequired` ——
-   * 界面才能诚实地说「改好了，重启后生效」，而不是让用户以为立刻生效又看不到变化。
+   * 面板上的注入设置（5 项上限 + 保留名保护名单）。⚠️ **这 5 个常量是模块加载时读的**：面板改完
+   * 要**重启 DSH** 才生效。所以这里同时给出「当前生效值」`limits`、「待生效值」`pendingLimits` 与
+   * `restartRequired` —— 界面才能诚实地说「改好了，重启后生效」，而不是让用户以为立刻生效。
    */
   async getSettings() {
-    const file = await readSettingsFile()
+    const fileRead = await readSettingsFileDetailed()
     const limits = {
       maxResults: MAX_RESULTS,
       maxChars: MAX_CHARS_PER_FILE,
@@ -461,19 +445,31 @@ export class MemoryGateway extends TypertRemoteService {
       maxSessionBytes: MAX_SESSION_BYTES,
       staleDays: STALE_DAYS,
     }
-    const pending = pendingLimits(file)
+    // Q04：pending 与**启动解析**共用 `resolveLimits` 这一份判据（持久设置 > 环境变量 > 默认）。
+    const pending = resolveLimits(fileRead.data?.limits)
+    // 坏设置给明确诊断、不静默回默认：启动期那份 + 这次读文件的问题 + 逐项非法/越界说明，去重后一起给。
+    const limitDiagnostics = [...new Set([
+      ...STARTUP_LIMIT_DIAGNOSTICS,
+      ...(fileRead.error ? [fileRead.error] : []),
+      ...pending.diagnostics,
+    ])]
+    if (limitDiagnostics.length > 0) {
+      warnLog(this.ctx, `上限设置有问题（本次仍按环境变量/默认值生效）：${limitDiagnostics.join('；')}`)
+    }
     const reservedExtra = await readReservedFile()
     // 模块加载时那份「用户声明的保护名」（RESERVED_FILES 里抠掉两个内置名）
     const activeExtra = [...RESERVED_FILES].filter((n) => n !== INDEX_FILE_KEY && n !== SESSION_LOG_KEY)
     const norm = (list) => JSON.stringify([...list].map((s) => String(s).toLowerCase()).sort())
     const restartRequired =
-      JSON.stringify(limits) !== JSON.stringify(pending) || norm(activeExtra) !== norm(reservedExtra)
+      JSON.stringify(limits) !== JSON.stringify(pending.limits) || norm(activeExtra) !== norm(reservedExtra)
     return {
       limits,
-      pendingLimits: pending,
+      pendingLimits: pending.limits,
       restartRequired,
+      // Q04 的诊断出口：面板据此说明「你保存的值没生效，原因是 X」；宿主侧先如实给出，别让问题只能靠猜。
+      limitDiagnostics,
       // 1.8.0：客户端行为（侧栏入口开关）。**不参与** restartRequired —— 改完立刻生效。
-      ui: pendingUi(file),
+      ui: pendingUi(fileRead.data),
       // 生效的保护名单（含两个内置名）+ 用户声明的那部分原文（面板编辑的是后者）
       reserved: [...new Set([INDEX_FILE_KEY, SESSION_LOG_KEY, ...reservedExtra.map((s) => s.toLowerCase())])],
       reservedExtra,
@@ -526,7 +522,13 @@ export class MemoryGateway extends TypertRemoteService {
 
     await mkdir(STATE_ROOT, { recursive: true })
     if (limitsPatch || uiPatch !== null) {
-      const current = await readSettingsFile()
+      const currentRead = await readSettingsFileDetailed()
+      // 坏文件上不写：没有可合并的旧值，整份重写会把用户手改的内容静默吞掉。
+      // 明确拒绝、让用户先修文件，比「保存成功但别的设置都没了」诚实。
+      if (currentRead.error) {
+        return { ok: false, error: `sage-mem: ${currentRead.error}；请先修复或删除它再保存（不会静默覆盖）` }
+      }
+      const current = currentRead.data
       const mergedLimits = { ...(current?.limits ?? {}), ...nextLimits }
       // ui 只覆盖这次给出的键；没给就沿用文件里的有效值（坏值 / 缺失一律按默认「开」）
       const mergedUi = { ...pendingUi(current), ...(uiPatch ?? {}) }

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

@@ -18,6 +18,15 @@ export const MEMORY_DIR = process.env.SAGE_MEM_DIR || join(homedir(), '.sage-mem
  */
 export const SESSIONS_ROOT = process.env.DSH_HOME ? join(process.env.DSH_HOME, 'sessions') : ''
 
+/**
+ * 状态根：配置、锁表、台账、冲突、检查点、快照都住在这里。
+ *
+ * `SAGE_MEM_STATE_DIR` 显式覆写优先；没设时跟着记忆目录走（它的上一层 + `.sage-mem`）。
+ * ⚠️ Q09：**所有子模块都必须从这里取**，不许各自 `dirname(memoryDir)` + 拼 `.sage-mem` ——
+ * 那样覆写只对一部分模块生效，面板与引擎会各读一套配置。
+ */
+export const STATE_ROOT = process.env.SAGE_MEM_STATE_DIR || join(dirname(MEMORY_DIR), '.sage-mem')
+
 /** 读一个整数型环境变量并在范围内收敛；取不到或非法就用默认值。 */
 export function envInt(name, dflt, lo, hi) {
   // ⚠️ 必须先 trim：`Number('   ')` 是 **0** 而不是 NaN，于是纯空格的值会被
@@ -41,20 +50,110 @@ export const LIMIT_SPECS = {
   maxSessionBytes: { env: 'SAGE_MEM_MAX_SESSION_BYTES', dflt: 60 * 1024, lo: 4096, hi: 512 * 1024 },
   staleDays: { env: 'SAGE_MEM_STALE_DAYS', dflt: 1, lo: 0, hi: 365 },
 }
-const fromSpec = (spec) => envInt(spec.env, spec.dflt, spec.lo, spec.hi)
+/**
+ * 单项上限的**唯一**校验：非法返回 `undefined`，合法返回收敛到 `[lo, hi]` 的整数。 *
+ * 与 `envInt()` 同一套语义，区别只在「非法」的出口由调用方决定（环境变量回落默认、
+ * 持久设置回落环境变量并留诊断）。**必须先 trim**：`Number('   ')` 是 0 而不是 NaN，
+ * 不 trim 的话纯空格会被当成「用户填了 0」。
+ */
+export function parseLimitValue(raw, spec) {
+  if (typeof raw === 'number') {
+    return Number.isFinite(raw) ? Math.max(spec.lo, Math.min(spec.hi, Math.round(raw))) : undefined
+  }
+  if (typeof raw !== 'string') return undefined
+  const text = raw.trim()
+  if (text === '') return undefined
+  const n = Number(text)
+  if (!Number.isFinite(n)) return undefined
+  return Math.max(spec.lo, Math.min(spec.hi, Math.round(n)))
+}
+
+/**
+ * 五项上限的**单一解析器**：持久设置 > 环境变量 > 内置默认。
+ *
+ * 为什么必须只有这一份（Q04）：旧实现里「启动生成的常量」只读环境变量，而面板的
+ * `pendingLimits` 另写一套读 settings.json —— 于是 UI 永远显示「待重启」，
+ * 重启却永远不会加载它。两处共用本函数后，优先级与校验不可能再各说一套。
+ *
+ * 诊断不静默：持久值不是数字 → 回落环境变量/默认并说明；越界 → 收敛到边界并说明。
+ * 缺失（`hasOwnProperty` 为假）是正常状态，不产生诊断。
+ *
+ * @param {object|null|undefined} saved — `settings.json` 的 `limits` 段
+ * @param {object} [env] — 默认 `process.env`（测试可注入，避免污染进程环境）
+ * @returns {{limits: Record<string, number>, diagnostics: string[]}}
+ */
+export function resolveLimits(saved, env = process.env) {
+  const limits = {}
+  const diagnostics = []
+  const savedObj = saved && typeof saved === 'object' && !Array.isArray(saved) ? saved : null
+  for (const [key, spec] of Object.entries(LIMIT_SPECS)) {
+    const hasSaved = savedObj !== null && Object.prototype.hasOwnProperty.call(savedObj, key)
+    let note = ''
+    if (hasSaved) {
+      const value = parseLimitValue(savedObj[key], spec)
+      if (value !== undefined) {
+        if (String(savedObj[key]).trim() !== String(value)) {
+          note = `settings.json 的 ${key}=${JSON.stringify(savedObj[key])} 不是 [${spec.lo}, ${spec.hi}] 内的整数，已收敛为 ${value}`
+        }
+        limits[key] = value
+        if (note) diagnostics.push(note)
+        continue
+      }
+      note = `settings.json 的 ${key}=${JSON.stringify(savedObj[key])} 不是有效数字，已回落环境变量/默认值`
+      diagnostics.push(note)
+    }
+    const envValue = parseLimitValue(env?.[spec.env], spec)
+    limits[key] = envValue === undefined ? spec.dflt : envValue
+  }
+  return { limits, diagnostics }
+}
+
+/**
+ * 启动期同步读 `<状态根>/settings.json`（模块常量只能同步取）。
+ *
+ * 「文件不存在」是正常状态（还未从面板保存过）；坏 JSON / 不是对象 / 读不动都返回
+ * 一条诊断 —— **不静默回落默认**是 Q04 的验收项之一。
+ */
+export function readSettingsFileSync(stateRoot = STATE_ROOT) {
+  const file = join(stateRoot, 'settings.json')
+  let text
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch (err) {
+    if (err?.code === 'ENOENT') return { file, data: null, diagnostics: [] }
+    return { file, data: null, diagnostics: [`读 ${file} 失败（${err?.code || err?.message}），本次按环境变量/默认值生效`] }
+  }
+  try {
+    const parsed = JSON.parse(text)
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { file, data: null, diagnostics: [`${file} 不是 JSON 对象，本次按环境变量/默认值生效`] }
+    }
+    return { file, data: parsed, diagnostics: [] }
+  } catch (err) {
+    return { file, data: null, diagnostics: [`${file} 解析失败（${err?.message ?? err}），本次按环境变量/默认值生效`] }
+  }
+}
+
+/**
+ * 启动期一次性解析的结果。**面板与引擎看到的是同一份**（`getSettings` 的 pending
+ * 走同一个 `resolveLimits`，只是输入换了下一次读到的文件内容）。
+ */
+const STARTUP_SETTINGS = readSettingsFileSync()
+const STARTUP_LIMITS = resolveLimits(STARTUP_SETTINGS.data?.limits)
+export const STARTUP_LIMIT_DIAGNOSTICS = [...STARTUP_SETTINGS.diagnostics, ...STARTUP_LIMITS.diagnostics]
 
 /**
  * 一次注入最多带几条记忆。
  *
  * 5 → 10：**记忆条数 ÷ 注入名额 ≈ 命中率上限**，名额 5 时那个上限低到
  * 的根因就在这个比值上。名额翻倍是提升召回最直接的一手，代价是每轮多约 7.5K
- * 字符的上下文。**这个数字该由实测决定**，所以留了 SAGE_MEM_MAX_RESULTS 覆写口
- * （比较两档的命中率与 token 账单，别拍脑袋）。
+ * 字符的上下文。**这个数字该由实测决定**，所以留了设置页（`settings.json`）与
+ * `SAGE_MEM_MAX_RESULTS` 两个覆写口（优先级：设置页 > 环境变量 > 默认值）。
  */
-export const MAX_RESULTS = fromSpec(LIMIT_SPECS.maxResults)
+export const MAX_RESULTS = STARTUP_LIMITS.limits.maxResults
 
 /** 单条记忆注入的字符上限。 */
-export const MAX_CHARS_PER_FILE = fromSpec(LIMIT_SPECS.maxChars)
+export const MAX_CHARS_PER_FILE = STARTUP_LIMITS.limits.maxChars
 
 /**
  * baseline 名额。
@@ -63,7 +162,7 @@ export const MAX_CHARS_PER_FILE = fromSpec(LIMIT_SPECS.maxChars)
  * 而 baseline 恰恰是短问题、恢复会话时唯一的兜底。现在放到 8，
  * 排序见下面「按显式优先级排，不按文件名」那段。
  */
-export const MAX_BASELINE = fromSpec(LIMIT_SPECS.maxBaseline)
+export const MAX_BASELINE = STARTUP_LIMITS.limits.maxBaseline
 
 /**
  * 单会话累计注入字节上限 —— 到顶以后这个会话就不再注入新的记忆。
@@ -77,7 +176,7 @@ export const MAX_BASELINE = fromSpec(LIMIT_SPECS.maxBaseline)
  * 60 KB 是与 CC 对齐的起点、不是实测出来的数字 —— 留了 SAGE_MEM_MAX_SESSION_BYTES
  * 覆写口，量过再定。
  */
-export const MAX_SESSION_BYTES = fromSpec(LIMIT_SPECS.maxSessionBytes)
+export const MAX_SESSION_BYTES = STARTUP_LIMITS.limits.maxSessionBytes
 
 /**
  * 状态卡预留占总预算的比例，以及它的上下夹逼区间。
@@ -108,7 +207,7 @@ export const CONTENT_BUDGET = MAX_SESSION_BYTES - STATUS_RESERVE
  * 推理，相对天数才会。为什么需要它：陈旧记忆被当事实引用时，「引用」这个动作
  * 本身会让它显得更权威、而不是更可疑。
  */
-export const STALE_DAYS = fromSpec(LIMIT_SPECS.staleDays)
+export const STALE_DAYS = STARTUP_LIMITS.limits.staleDays
 
 /**
  * 注入文本开头的引用纪律 —— **必须独立成节，不能压成一条 bullet**。
@@ -144,8 +243,6 @@ export const RECALL_DISCIPLINE = [
  * 而拿 'memory.md' 去 has() 是查不到的 —— 曾经就是这个漏洞：表单里填 memory.md
  * 就能整份覆盖索引，deleteFile 还能不可逆删掉它）。
  */
-export const STATE_ROOT = process.env.SAGE_MEM_STATE_DIR || join(dirname(MEMORY_DIR), '.sage-mem')
-
 /**
  * 2.0.0：有效性过滤（`invalid_at`）与矛盾抑制的总开关（设计稿 §11.2 Q8）。
  *

package/lib/memory/lock.js

@@ -9,11 +9,20 @@
  *
  * 锁表按 `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 { createWriteQueue, writeFileAtomic } from './util.js'
 
 /** 锁表文件：状态根下，与记忆文件分开。 */
 export function lockFileOf(memoryDir) {
@@ -21,24 +30,83 @@ export function lockFileOf(memoryDir) {
 }
 
 /**
- * 读锁表。读不到 / 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 +114,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/lib/settings.js

@@ -6,7 +6,7 @@
  */
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { LIMIT_SPECS, STATE_ROOT } from './memory/config.js'
+import { LIMIT_SPECS, STATE_ROOT, resolveLimits } from './memory/config.js'
 import { MAX_RAW_BYTES } from './shared/limits.js'
 import { isPlainMdName } from './shared/md-name.js'
 export { LIMIT_SPECS, MAX_RAW_BYTES }
@@ -53,30 +53,46 @@ export function parseUiPatch(ui) {
   return { ok: true, patch: Object.keys(patch).length ? patch : null }
 }
 
-/** 读 `<状态根>/settings.json`；缺失、坏 JSON、不是对象都当「没设置」。 */
-export async function readSettingsFile() {
+/**
+ * 读 `<状态根>/settings.json`，并把「为什么没读到」说清楚。
+ *
+ * 缺失是正常状态（`data:null, error:''`）；坏 JSON / 不是对象返回 `error` ——
+ * Q04 要求坏设置给明确诊断，而不是让调用方一律看到 `null`、分不清「没设置过」
+ * 与「文件被我改坏了」。启动期的同步版本在 `memory/config.js`（语义一致）。
+ */
+export async function readSettingsFileDetailed() {
+  let text
   try {
-    const parsed = JSON.parse(await readFile(SETTINGS_FILE, 'utf8'))
-    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null
-  } catch {
-    return null
+    text = await readFile(SETTINGS_FILE, 'utf8')
+  } catch (err) {
+    if (err?.code === 'ENOENT') return { data: null, error: '' }
+    return { data: null, error: `读 settings.json 失败（${err?.code || err?.message}）` }
+  }
+  let parsed
+  try {
+    parsed = JSON.parse(text)
+  } catch (err) {
+    return { data: null, error: `settings.json 解析失败（${err?.message ?? err}）` }
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { data: null, error: 'settings.json 不是 JSON 对象' }
   }
+  return { data: parsed, error: '' }
 }
 
-/** 待生效的 5 项上限：`settings.json` > 环境变量 > 内置默认。 */
+/** 读 `<状态根>/settings.json`；缺失、坏 JSON、不是对象都当「没设置」（要区分请用上面那个）。 */
+export async function readSettingsFile() {
+  return (await readSettingsFileDetailed()).data
+}
+
+/**
+ * 待生效的 5 项上限：`settings.json` > 环境变量 > 内置默认。
+ *
+ * ⚠️ 判据**只有** `config.js` 的 `resolveLimits` 一份（Q04 的根因就是这里另写了一套）：
+ * 启动生成常量与面板算 pending 必须共用同一份校验与优先级，否则 UI 会一直喊「待重启」。
+ */
 export function pendingLimits(fileObj) {
-  const out = {}
-  const saved = fileObj?.limits && typeof fileObj.limits === 'object' ? fileObj.limits : {}
-  for (const [key, spec] of Object.entries(LIMIT_SPECS)) {
-    const fromFile = Number(saved[key])
-    if (Number.isFinite(fromFile)) {
-      out[key] = clampInt(fromFile, spec)
-      continue
-    }
-    const raw = process.env[spec.env]
-    out[key] = clampInt(raw === undefined || raw === '' ? NaN : Number(raw), spec)
-  }
-  return out
+  return resolveLimits(fileObj?.limits).limits
 }
 
 /** 读 `<状态根>/reserved.json`（用户声明的保护名单）。**保留原始大小写**，好让 get 读回一致。 */

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