sage-mem 2.1.9 → 2.1.11

package/README.md

@@ -12,7 +12,7 @@
 
 **Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.**
 
-**Current release: `2.1.9`** — 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.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
 [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.9`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
+**当前发布版本：`2.1.11`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
 [契约冻结](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md)。
 
 如果它对你有用，给个 Star 是最直接的反馈。

package/lib/client.js

@@ -6051,23 +6051,22 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 			function createIndexSkeleton() {
 				setError(null);
 				setNotice("");
-				if (!remote || typeof remote.readRaw !== "function" || typeof remote.writeRaw !== "function") {
+				if (!remote || typeof remote.writeRaw !== "function") {
 					setError(t("error.noRaw"));
 					return;
 				}
 				setBusy(true);
-				// 先读再写：**已有索引绝不覆盖**。readRaw 对不存在的文件会 reject，正好当探针。
-				remote.readRaw("MEMORY.md").then(function () {
+				// 2.1.10（Q10）：只调**一个意图接口**（writeRaw 的 createIfAbsent）：
+				// 服务端负责「全新安装、memory 目录还不存在」时先建父目录；
+				// 已有索引 → 明确回 already_exists（逐字节不动）。绝不再「先读一次、读失败就当
+				// 可以覆盖」—— 读失败也可能是权限错误，而那正是会顶掉一份真索引的路。
+				remote.writeRaw("MEMORY.md", INDEX_SKELETON, { create: true }).then(function (res) {
+					const out = unwrap(res);
 					setBusy(false);
-					setNotice(t("notice.indexExists"));
-				}, function () {
-					return remote.writeRaw("MEMORY.md", INDEX_SKELETON).then(function (res) {
-						const out = unwrap(res);
-						setBusy(false);
-						if (out && out.ok === false) { setError(out.error || t("error.skeletonFailed")); return; }
-						setNotice(t("notice.indexCreated"));
-						load();
-					});
+					if (out && out.code === "already_exists") { setNotice(t("notice.indexExists")); return; }
+					if (out && out.ok === false) { setError(out.error || t("error.skeletonFailed")); return; }
+					setNotice(t("notice.indexCreated"));
+					load();
 				}).catch(function (e) {
 					setBusy(false);
 					setError(String((e && e.message) || e));

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'
@@ -27,7 +25,7 @@ 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()
@@ -120,13 +115,9 @@ export class MemoryGateway extends TypertRemoteService {
   }
 
   /**
-   * 读单个记忆文件全文。
-   *
-   * 过闸门再读：名字在记忆目录里**不等于**内容住在记忆目录里 —— 符号链接 / 目录联接 /
-   * 硬链接都能让一次「读自己的记忆」变成读别人的文件，而读到的内容会被注入模型上下文。
-   *
-   * 2.1.2（Q02）：返回值多一个 `revision`（正文字节的 sha256）。保存时把它带回来，
-   * 盘上版本变了就拒绝覆盖（见 `memory/write-protocol.js`）。
+   * 读单个记忆文件全文。过闸门再读：名字在记忆目录里**不等于**内容住在记忆目录里 ——
+   * 符号链接 / 目录联接 / 硬链接都能让一次「读自己的记忆」变成读别人的文件，而内容会进模型上下文。
+   * 2.1.2（Q02）：返回值多一个 `revision`（正文字节 sha256）；保存时带回来，盘上版本变了就拒绝覆盖。
    */
   async readFile(name) {
     const safe = safeName(name)
@@ -227,9 +218,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 +247,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)
@@ -446,14 +432,12 @@ export class MemoryGateway extends TypertRemoteService {
   }
 
   /**
-   * 面板上的注入设置（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/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/write-protocol.js

@@ -22,6 +22,8 @@
  */
 
 import { createHash } from 'node:crypto'
+import { mkdir } from 'node:fs/promises'
+import { dirname } from 'node:path'
 import { readVerified } from './scan.js'
 import { warnLog, writeFileAtomic, writeFileExclusive } from './util.js'
 
@@ -70,6 +72,10 @@ export async function writeSnapshot(target, content, gate, opts, meta) {
   if (o.create === true) {
     if (gate?.ok) return rejected(ERR_ALREADY_EXISTS, `sage-mem: ${name} 已经存在，新建不会覆盖它（要改正文请打开它）`)
     try {
+      // 2.1.10（Q10）：createIfAbsent 也负责「全新安装、父目录还不存在」这一种：
+      // writeFileExclusive 的临时文件落在同一目录，目录不在就会 ENOENT（审查实测）。
+      // 只建父目录、绝不动目标文件 —— 「建立索引骨架」这个意图由调用方一次说清。
+      await mkdir(dirname(target), { recursive: true })
       await writeFileExclusive(target, content)
     } catch (err) {
       if (err?.code === 'EEXIST') return rejected(ERR_ALREADY_EXISTS, `sage-mem: ${name} 刚刚被别的写入建出来了，新建没有覆盖它`)

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