sage-mem 2.1.12 → 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.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
+**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.12`** —— 顶部 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/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

@@ -22,11 +22,19 @@
 import { mkdir, readFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { nameKey } from './naming.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')
 }
 
 /**

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