@a9i5k4/dsh-auto-memory 3.0.1 → 3.1.0

package/lib/hub-io.js

@@ -0,0 +1,217 @@
+/**
+ * M8 记忆中枢（Memory Hub）持久化 IO —— **带健康度记账的 io 适配器**（#110，2026-09-22）。
+ *
+ * ── 背景（为什么需要这个模块）──
+ * hub 三店（episodes / facts / procedures）的 `io` 由 index.js 内联的 `hubIo()` 提供，
+ * 旧实现三个方法各自 `catch (_) {}` 把异常**吞在适配器这一层**：
+ *
+ *   1. 上层三店在 A-8 里写好的 `try { io.save(snapshot()) } catch (e) { … ok:false … }`
+ *      **永远走不到 catch 分支** ⇒ store 照样返回 `{ ok:true, persisted:true }`，
+ *      `persistFailures` 恒为 0、`lastPersistError` 恒为 null ⇒ 三条线全绿而磁盘没写上。
+ *   2. 用户侧表现为「记忆看着存上了，重启清零」，日志、计数、面板三处都拿不到信号。
+ *
+ * 现在把这段逻辑从 index.js 提出来，语义收紧为三条：
+ *   · `save` / `clear` 失败**照原样抛出**（把「写不进去就是写不进去」交还调用方，
+ *     让 A-8 既有的 try/catch 真正生效），**同时**记一次健康度；
+ *   · `load` 保持「无文件 / 损坏 → 返回 null（空启动）」的既有控制流不变，只追加可观测性；
+ *   · 每次失败都写进 health（errno → 中文人话 + 累计计数 + 时间戳），由
+ *     `hubIoHealthSnapshotPre()` 投影给 debugInfo / 诊断面板。
+ *
+ * 边界（与既有纪律一致）：
+ *   · 只做记账与转发，**不改变** 落盘格式、原子性策略（tmp + rename）与任何调用方契约；
+ *   · 不引入时钟依赖以外的副作用；`onError` 回调抛错不得影响主路径（自身 try/catch 包住）；
+ *   · 不做 unlink/copy 回退：调用方各自保留自己的原子性策略（同 `fs-retry.js` 的边界声明）。
+ */
+
+import { mkdirSync, writeFileSync, renameSync, readFileSync, rmSync } from 'node:fs'
+import path from 'node:path'
+
+/** errno → 人话。口径：暴露给前端/工具的原因必须人能看懂，不能只甩机器码。 */
+export const HUB_IO_ERRNO_MESSAGES_V1 = Object.freeze({
+  EACCES: '权限被拒绝（目标目录不可写）',
+  EPERM: '操作被系统拒绝（权限或安全策略拦截，Windows 下也常见于文件被占用）',
+  ENOSPC: '磁盘空间不足',
+  EROFS: '目标位于只读位置',
+  EBUSY: '文件被其它进程占用',
+  ENOENT: '路径不存在（父目录缺失）',
+  EISDIR: '该名字被一个目录占着，不是文件',
+  ENOTDIR: '路径中间有一段不是目录',
+  EEXIST: '临时文件已存在',
+  ENAMETOOLONG: '路径过长',
+  EMFILE: '进程打开的文件过多',
+  EIO: '底层读写错误（磁盘或驱动）',
+})
+
+/** 把任意异常翻成一句人话（带 errno 便于排障；无 code 时回落 message）。 */
+export function explainHubIoErrorPre(e) {
+  const code = e && e.code ? String(e.code) : ''
+  const mapped = code ? HUB_IO_ERRNO_MESSAGES_V1[code] : ''
+  if (mapped) return mapped + '（' + code + '）'
+  if (code) return '文件系统错误 ' + code
+  return String((e && e.message) || e || '未知错误')
+}
+
+/** 新建一份健康度台账（纯内存，零 IO）。 */
+export function createHubIoHealthPre() {
+  return { errors: 0, lastError: null, lastErrorAt: 0, saves: 0, loads: 0, clears: 0, byFile: {} }
+}
+
+/**
+ * 记一次失败，并调用 `onError(key, message)`（节流由调用方决定，本模块不持有定时器）。
+ * @returns {string} 人话原因
+ */
+function notePre(health, name, op, e, onError) {
+  const now = Date.now()
+  const human = explainHubIoErrorPre(e)
+  health.errors += 1
+  health.lastError = name + ' ' + op + ' 失败：' + human
+  health.lastErrorAt = now
+  const key = name + ':' + op
+  const rec = health.byFile[key] || { count: 0, lastError: null, lastErrorAt: 0 }
+  rec.count += 1
+  rec.lastError = human
+  rec.lastErrorAt = now
+  health.byFile[key] = rec
+  if (typeof onError === 'function') {
+    try { onError(key, 'M8 hub 持久化失败 —— ' + health.lastError + '（累计 ' + health.errors + ' 次）') } catch (_) { /* 记账不得影响主路径 */ }
+  }
+  return human
+}
+
+/**
+ * 造一个 hub io 适配器工厂。
+ * @param {{dir:string, health?:object, onError?:Function, fsApi?:object}} opts
+ *        `fsApi` 注入点仅供测试（故障注入），缺省用 node:fs 同步 API。
+ * @returns {(name:string) => {save:Function, load:Function, clear:Function}}
+ */
+export function createHubIoPre(opts = {}) {
+  const dir = String(opts.dir || '')
+  const health = opts.health || createHubIoHealthPre()
+  const onError = opts.onError
+  const api = opts.fsApi || null
+  const mk = (api && api.mkdirSync) || mkdirSync
+  const wf = (api && api.writeFileSync) || writeFileSync
+  const rn = (api && api.renameSync) || renameSync
+  const rf = (api && api.readFileSync) || readFileSync
+  const rm = (api && api.rmSync) || rmSync
+
+  // ★#110（2026-09-22）：**批内合并落盘**（消除写放大）。
+  //   背景：hub 一次喂数会连续写同一份快照 N 次（每行判据 upsert 一次 ⇒ 一次整份写盘）。
+  //   做法：批内只记「最后一次的整份数据」，批末统一原子落盘。**语义无损**——每份快照都是全量，
+  //   最后一次即最终状态；store 的内存态始终最新，落盘只是它的投影。
+  //   明确声明的代价：批未落盘时进程被杀，本批持久化会丢。这批是「机器切出来的流程观察行」，
+  //   源头 judgement-shadow 文件仍在、可重放，**不涉及用户数据**。
+  //   失败**不静默**：逐文件记 health（含 errno 人话）并走 onError；返回值把 ok/written/errors 交出去。
+  let batchDepth = 0
+  const pendingWrites = new Map() // filePath → { name, data }
+
+  function atomicWrite(file, name, data) {
+    mk(dir, { recursive: true })
+    const tmp = file + '.tmp'
+    wf(tmp, JSON.stringify(data), 'utf8')
+    rn(tmp, file)
+  }
+  function flushPendingPre() {
+    let written = 0
+    let ok = true
+    for (const [file, rec] of pendingWrites) {
+      try { atomicWrite(file, rec.name, rec.data); written++ } catch (e) { ok = false }
+    }
+    pendingWrites.clear()
+    return { ok, written, errors: health.errors }
+  }
+
+  const factory = (name) => {
+    const file = path.join(dir, String(name))
+    return {
+      /**
+       * 原子写（tmp + rename）。失败**记健康度后原样抛出** —— 上层 A-8 的 try/catch 依赖这一点。
+       * 批内（beginBatch 之后 endBatch 之前）改为**只登记不落盘**，批末一次写。
+       */
+      save(data) {
+        health.saves += 1
+        if (batchDepth > 0) { pendingWrites.set(file, { name, data }); return }
+        try {
+          atomicWrite(file, name, data)
+        } catch (e) {
+          notePre(health, name, 'save', e, onError)
+          throw e
+        }
+      },
+      /**
+       * 读取。保持既有语义：无文件 / 损坏一律返回 null（空启动，fail closed 幂等恢复）；
+       * 只有「非 ENOENT 的读取失败」与「JSON 解析失败」才记健康度。
+       */
+      load() {
+        health.loads += 1
+        let raw
+        try {
+          raw = rf(file, 'utf8')
+        } catch (e) {
+          if (!(e && e.code === 'ENOENT')) notePre(health, name, 'load', e, onError)
+          return null
+        }
+        try {
+          return JSON.parse(raw)
+        } catch (e) {
+          notePre(health, name, 'parse', e, onError)
+          return null
+        }
+      },
+      /** 删除。失败**记健康度后原样抛出**（残留快照会在下次 load 时"复活"已清空的数据）。 */
+      clear() {
+        health.clears += 1
+        // 批内 clear 必须先取消该文件的待写，否则批末会把刚删掉的快照又写回来。
+        pendingWrites.delete(file)
+        try { rm(file, { force: true }) } catch (e) { notePre(health, name, 'clear', e, onError); throw e }
+      },
+    }
+  }
+  // ── 批控制（挂在工厂函数上，调用方：`hubIo.beginBatch()` / `hubIo.endBatch()`）──
+  factory.beginBatch = () => { batchDepth += 1; return batchDepth }
+  factory.endBatch = () => {
+    if (batchDepth > 0) batchDepth -= 1
+    if (batchDepth > 0) return { ok: true, written: 0, errors: health.errors, deferred: true }
+    return flushPendingPre()
+  }
+  factory.flushBatch = () => flushPendingPre()
+  factory.batchPending = () => pendingWrites.size
+  return factory
+}
+
+/**
+ * 健康度只读投影（供 debugInfo / 诊断面板）。
+ * 纪律：只出计数 + 人话原因 + 时间戳，**无路径、无原文**；任何异常都不得打断诊断。
+ */
+export function hubIoHealthSnapshotPre(health) {
+  const empty = { errors: 0, lastError: null, lastErrorAt: null, saves: 0, loads: 0, clears: 0, byFile: {}, verdict: 'ok', summary: '三层记忆已正常落盘（本轮无写入失败）' }
+  try {
+    if (!health || typeof health !== 'object') return empty
+    const byFile = {}
+    const src = (health.byFile && typeof health.byFile === 'object') ? health.byFile : {}
+    for (const k of Object.keys(src)) {
+      const r = src[k] || {}
+      byFile[k] = {
+        count: Number(r.count) || 0,
+        lastError: r.lastError ? String(r.lastError) : null,
+        lastErrorAt: Number(r.lastErrorAt) || null,
+      }
+    }
+    const errors = Number(health.errors) || 0
+    return {
+      errors,
+      lastError: health.lastError ? String(health.lastError) : null,
+      lastErrorAt: Number(health.lastErrorAt) || null,
+      saves: Number(health.saves) || 0,
+      loads: Number(health.loads) || 0,
+      clears: Number(health.clears) || 0,
+      byFile,
+      verdict: errors === 0 ? 'ok' : 'io-error',
+      summary: errors === 0
+        ? '三层记忆已正常落盘（本轮无写入失败）'
+        : '三层记忆有 ' + errors + ' 次落盘/读取失败，最近一次：' + String(health.lastError || '') + '。记忆可能只在内存里，重启会丢。',
+    }
+  } catch (_) {
+    return empty
+  }
+}

package/lib/index.js

@@ -49,6 +49,8 @@ import { createFactStorePre } from './fact-store.js'
 import { createProcedureStorePre } from './procedure-store.js'
 import { exportSkillForPre, resolveSkillsRootPre } from './skill-export-host.js'
 import { createMemoryHubPre } from './memory-hub.js'
+// ★#110（2026-09-22）：hub 持久化 IO 适配器与其健康度投影（原本内联在本文件里、失败被静默吞掉）。
+import { createHubIoPre, createHubIoHealthPre, hubIoHealthSnapshotPre } from './hub-io.js'
 import { pickConsolidationTextPre } from './intent-clean.js'
 // T1-3（2026-09-19）：hubFlushTick 写入前的**内容卫生门**复用 ⑨ 同源清洗器。
 // 必须独占一行（本仓契约守卫以字面量断言既有 import 行，禁止为排版合并）。
@@ -542,7 +544,19 @@ const DEFAULT_CONFIG = {
   pythonBackendEnabled: false,
   /** 推理 trace 观察器(2026-08-26 裁定默认开:监听目标是模型思维链,闭源概括式 CoT 同样纳入)。 */
   reasoningObserverEnabled: true,
-  /** Procedure 自动晋升。 */
+  /** ★ B-2 修复(2026-09-22)：**技能注入/唤起总闸**，语义纠正后的正确键（默认 **true**）。
+   *  取证：旧键 `procedurePromotionEnabled` 名字叫「技能固化与晋升」，但它的两个消费者
+   *  都与"晋升"无关 —— context-host.js:537（技能是否**注入上下文**）、
+   *  activation-host.js:330（**主动唤起**这条臂开不开）；真正的晋升由 store 门限 +
+   *  路由动作决定。旧键默认 false ⇒ 新用户装完"技能永不生效"且无任何提示。
+   *  ⚠️ 解析口径统一走 `lib/procedure-switch.js` 的 `resolveProcedureInjectEnabledPre`，
+   *  不得在本文件或其它文件里各自 inline 判断（否则又是一次口径漂移）。 */
+  procedureInjectEnabled: true,
+  /** 已弃用：语义错配的旧键，保留为**兼容别名**。
+   *  新键缺省时按本键取值（老用户显式关掉的不翻面）；两键都缺省才取 true。
+   *  设置页已改为操作新键，本键仅作读取回退，不再新增写入入口。
+   *  注：**不新增 `procedureAutoPromoteEnabled`** —— 全仓无任何自动晋升代码路径
+   *  （`applyAutomaticTransitions` 只导出零调用，见 BUGLIST P2-4），建了就是死配置。 */
   procedurePromotionEnabled: false,
   /** ★T10（2026-09-20）：**机械 procedure 切片**开关。
    *  背景（用户 2026-09-20 报「白板/审批里的技能名与内容看不懂」）：
@@ -563,6 +577,12 @@ const DEFAULT_CONFIG = {
   episodicMinSegments: 2,
   /** episodic: 保留的最多 episode 数(超出按时间淘汰)。默认 256。 */
   episodicRetention: 256,
+  /** ★#110（2026-09-22，用户拍板 1000）：facts 保留上限。超出按「撤销优先 → 最旧优先」淘汰，
+   *  重要项(pinned / user-memory / explicit / confidence≥0.8)最后才删。<=0 表示不限。 */
+  factRetentionMax: 1000,
+  /** ★#102（2026-09-22）：工作区发现上限。旧的硬编码 30 会把第 31 个起的工作区**静默丢弃**
+   *  （跨区检索/注入索引/总览一起少项）。现按「最近会话 mtime」降序截断，默认 200。 */
+  workspaceDiscoverMax: 200,
   /** procedure: 晋升所需跨会话多样性(≥N 个独立 session)。默认 3(M-04 元代码)。 */
   procedureMinSessions: 3,
   /** procedure: 晋升所需成功次数(≥N)。默认 2(一次成功不足以证明可靠)。 */
@@ -2499,7 +2519,18 @@ class MemoryEngine {
     // 保留调用方刚写入的富条目(rebuild 只是补倒排, 正文预览以已有条目为准)
     fresh.entries = entries
     await mkdir(sideDir, { recursive: true })
-    await writeFile(path.join(sideDir, 'index.json'), JSON.stringify(fresh, null, 2), 'utf8')
+    // ★2026-09-22：改**原子写**（tmp + 有界重试 rename）。
+    //   旧实现是裸 `await writeFile(index.json, …)` —— 这份索引 235 KB，写入过程**不是原子的**：
+    //   面板/工具恰在此时读，读到的要么是零字节、要么是半截 JSON ⇒ `JSON.parse` 失败 ⇒ 看板/白板
+    //   **整块空白**，写完才恢复（用户实测：「白板不见了 → 过了一会儿又出现了」）。时间戳可对：
+    //   索引在 09-22 00:52:10 被整份重写，同一秒宿主诊断 `…-diagnose.log` 连出 6 条
+    //   `ctx-host degrade: index-not-ready(commit)` —— 就是这段「不可读窗口」。
+    //   rename 在同目录内是原子替换；Windows 上读侧句柄争用会抛 EPERM/EBUSY，
+    //   故复用 #48 的 `retryRename`（有界退避，且不做 unlink/copy 回退以免破坏原子性）。
+    const idxPath = path.join(sideDir, 'index.json')
+    const tmpPath = idxPath + '.tmp'
+    await writeFile(tmpPath, JSON.stringify(fresh, null, 2), 'utf8')
+    await retryRename(tmpPath, idxPath)
     return fresh
   }
 
@@ -2522,7 +2553,17 @@ class MemoryEngine {
     const sideDir = path.join(projectDir, 'handoff')
     const docs = await this._collectWhiteboardDocsPre(projectDir).catch(() => [])
     const index = rebuildSidecarIndexPre(this.wbWsKeyPre(projectDir), docs)
-    try { await mkdir(sideDir, { recursive: true }); await writeFile(path.join(sideDir, 'index.json'), JSON.stringify(index, null, 2), 'utf8') } catch (_) {}
+    try {
+      await mkdir(sideDir, { recursive: true })
+      // ★2026-09-22：与 `_writeSidecarIndexPre` 同一口径 —— **重建路径也必须原子替换**。
+      //   这里同样是整份索引（实测 235 KB）裸写；而重建恰恰是在「索引缺失/损坏」时被触发的，
+      //   此刻面板正等着读这份文件 ⇒ 裸写期间的读者拿到半截 JSON，白板依旧整块空白。
+      //   （本处由守卫 `smoke-test-board-index-atomic-pre.mjs` 抓出：它断言「全仓不得再有裸写 index.json」。）
+      const rIdx = path.join(sideDir, 'index.json')
+      const rTmp = rIdx + '.tmp'
+      await writeFile(rTmp, JSON.stringify(index, null, 2), 'utf8')
+      await retryRename(rTmp, rIdx)
+    } catch (_) {}
     return index
   }
 
@@ -6603,28 +6644,44 @@ class MemoryEngine {
 
   /** 扫描 ~/.dsh/sessions 下所有会话,提取去重后的工作区路径。 */
   async discoverWorkspaces() {
-    const out = new Map()
+    // ★#102（2026-09-22）：解除「硬编码 30 且静默截断」。
+    //   旧实现：`if (out.size >= 30) return` —— 上限写死、按**目录遍历顺序**取前 30，
+    //   第 31 个工作区起被**静默丢弃**（跨区检索 / 注入索引 / 工作区总览一起少项，且无任何信号）。
+    //   现在：① 上限走配置 `workspaceDiscoverMax`（默认 200，非法值回落默认）；
+    //        ② 以「该工作区最近一次会话文件的 mtime」为活跃度，按新→旧排序后再截断 ——
+    //           即便真到上限，丢掉的也是**最久没用过**的，而不是碰巧排在后面的；
+    //        ③ 仅保留一个 5×上限的遍历安全阀，防止 sessions 目录异常膨胀时无限走盘。
+    const capRaw = Number(this.config && this.config.workspaceDiscoverMax)
+    const cap = (Number.isFinite(capRaw) && capRaw >= 1) ? Math.floor(capRaw) : 200
+    const walkLimit = cap * 5
+    const out = new Map() // cwd → 最近会话文件 mtimeMs
     const sessionsDir = path.join(dshHome(), 'sessions')
     const walk = async (dir, depth) => {
       if (depth > 4) return
       let entries
       try { entries = await readdir(dir, { withFileTypes: true }) } catch (e) { return }
       for (const en of entries) {
-        if (out.size >= 30) return
-        if (en.isDirectory()) await walk(path.join(dir, en.name), depth + 1)
-        else if (en.isFile() && (en.name.endsWith('.jsonl.zstd') || en.name.endsWith('.jsonl'))) {
-          try {
-            const first = await this.readFirstLine(path.join(dir, en.name))
-            if (first) {
-              const h = JSON.parse(first)
-              if (h && typeof h.cwd === 'string' && h.cwd) out.set(h.cwd, true)
-            }
-          } catch (e) {}
-        }
+        if (out.size >= walkLimit) return
+        if (en.isDirectory()) { await walk(path.join(dir, en.name), depth + 1); continue }
+        if (!en.isFile() || !(en.name.endsWith('.jsonl.zstd') || en.name.endsWith('.jsonl'))) continue
+        const full = path.join(dir, en.name)
+        try {
+          const first = await this.readFirstLine(full)
+          if (!first) continue
+          const h = JSON.parse(first)
+          if (!h || typeof h.cwd !== 'string' || !h.cwd) continue
+          let mt = 0
+          try { mt = (await stat(full)).mtimeMs } catch (e) {}
+          const prev = out.get(h.cwd) || 0
+          if (mt > prev) out.set(h.cwd, mt)
+        } catch (e) {}
       }
     }
     await walk(sessionsDir, 0)
-    return Array.from(out.keys())
+    return Array.from(out.entries())
+      .sort((a, b) => b[1] - a[1])       // 活跃度降序（mtime 新→旧）
+      .slice(0, cap)
+      .map((e) => e[0])
   }
 
   /** 读取某工作区的近期记忆(最近5天日志 + 项目笔记头部),无 .dsh-memory 返回 null。 */
@@ -6775,6 +6832,52 @@ class MemoryEngine {
     return Object.assign({}, snap, { verdict })
   }
 
+  // ---------- ★#110（2026-09-22）：hub 持久化 IO 健康度视图 ----------
+  /**
+   * 返回三层记忆（episodes/facts/procedures）落盘 IO 的健康度投影。
+   *
+   * **为什么需要**：hub 三店的 `io` 由 `hubIo()` 提供，旧实现 save/clear 内 `catch (_) {}`
+   * 把异常吞在这一层 ⇒ 上层三店（A-8 之后）的 `try { io.save() } catch` 永远不触发、
+   * 返回值恒为 `{ok:true, persisted:true}` ⇒ 「写不进去」在**任何**出口都不可见。
+   * 现在失败会照抛并同时记进 `_hubIoHealth`，本方法就是它的只读投影。
+   *
+   * 纪律：与 `_degradeViewSnapshot` / `_quotaViewSnapshot` 同款 —— 只出计数 + 人话原因 + 时间戳，
+   * **无路径、无原文**；任何异常都不得打断 debugInfo（全程 try/catch，失败返回空计数）。
+   */
+  _hubIoViewSnapshot() {
+    return hubIoHealthSnapshotPre(this._hubIoHealth)
+  }
+  /**
+   * 事实保留上限淘汰台账的只读投影（★P0-3 / 2026-09-22）。
+   *
+   * **为什么不能只用 stats**：`getStats()`（fact-store.js:824）返回的是累计计数，
+   * 而 `lastPrune` 是闭包变量、只经 `getLastPrune()`（:832）单独暴露 ⇒
+   * 「最近一次淘汰发生在什么时候、当时上限多少、超出多少」只有它能给。
+   *
+   * 纪律：与 `_hubIoViewSnapshot` / `_degradeViewSnapshot` 同款 —— 只出聚合数 + 时间戳，
+   * **无事实正文、无路径**；任何异常都不得打断 debugInfo（全程 try/catch，失败返回 null）。
+   * `protected > 0` 表示已轮到删「重要项」⇒ 上限设得过低，前端据此给告警色与指引。
+   */
+  _factsPruneViewSnapshot() {
+    try {
+      const st = this._factStore
+      if (!st) return null
+      const last = typeof st.getLastPrune === 'function' ? st.getLastPrune() : null
+      const limit = typeof st.retentionLimit === 'function' ? st.retentionLimit() : null
+      if (!last && limit === null) return null
+      return {
+        pruned: Number(last && last.pruned) || 0,
+        protected: Number(last && last.protected) || 0,
+        limit: limit === null || limit === undefined
+          ? (last && last.limit !== undefined ? last.limit : null)
+          : limit,
+        over: Number(last && last.over) || 0,
+        oldestAt: (last && last.oldestAt) || null,
+        at: (last && last.at) || null,
+      }
+    } catch (_) { return null }
+  }
+
   /** 把降级台账与配额测量**合并写入同一状态文件**（读驱动写；失败返回 false，不抛）。 */
   _persistObservabilityPre(snap, quota) {
     let persisted = false
@@ -6880,6 +6983,14 @@ class MemoryEngine {
         //   回答用户那两个问题：「配额太少（内容进不来）」还是「配额多了（白花 token）」。
         //   判定默认 `insufficient-data`（样本不足**不猜**），符合用户「基于长期观察」的要求。
         quota: this._quotaViewSnapshot(),
+        // ★#110（2026-09-22）：hub 三层记忆持久化 IO 健康度。与既有最小投影同一出口、同一纪律
+        //   （只出计数 + 人话原因 + 时间戳，**无路径、无原文**）。回答的问题：
+        //   「记忆到底写进磁盘了没有」——此前 save 失败被静默吞掉，面板/日志/返回值三处都看不出来。
+        hubIo: this._hubIoViewSnapshot(),
+        // ★P0-3（2026-09-22）：事实保留上限淘汰台账 —— 与既有最小投影同一出口、同一纪律
+        //   （只出聚合计数与时间戳，**无事实正文、无路径**）。此前 getLastPrune/retentionLimit
+        //   在双侧零调用方 ⇒「事实被悄悄淘汰了」在界面上无处可查。
+        factsPrune: this._factsPruneViewSnapshot(),
         runtimes: this.runtimes.values().map((rt) => ({
           key: rt.key,
           sessionId: rt.sessionId,
@@ -9135,20 +9246,33 @@ export function apply(ctx, config) {
   // (此前 io 缺省 no-op → 重启清零)。落盘为快照整体写,数据量有界(episodes≤retention/facts/过程中)。
   {
     const hubDir = path.join(dshHome(), 'memory', 'hub')
-    const hubIo = (name) => {
-      const f = path.join(hubDir, name)
-      return {
-        save(data) {
-          try { mkdirSync(hubDir, { recursive: true }); const tmp = f + '.tmp'; writeFileSync(tmp, JSON.stringify(data), 'utf8'); renameSync(tmp, f) } catch (_) {}
-        },
-        load() { try { return JSON.parse(readFileSync(f, 'utf8')) } catch (_) { return null } },
-        clear() { try { rmSync(f, { force: true }) } catch (_) {} },
-      }
-    }
+    // ★#110（2026-09-22）：hub 持久化 IO 失败**可见化**（实现已抽到 `hub-io.js`，本处只做接线）。
+    //   旧实现三个方法各自 `catch (_) {}` 静默吞异常，后果有两层：
+    //   ① 异常在**适配器这一层**就被吃掉 ⇒ 三店 A-8 的 `try { io.save() } catch` 永远走不到 catch 分支
+    //      ⇒ store 照样报 `{ok:true, persisted:true}`，上层统计与返回值全是绿的；
+    //   ② 用户侧表现为「记忆看着存上了，重启清零」，日志、计数、面板三处都拿不到信号。
+    //   现在：save/clear 失败**照原样抛出**（让 A-8 的既有 try/catch 真正生效）+ 每次失败记账到
+    //   `engine._hubIoHealth`（人话原因 + 累计次数 + 时间），经 debugInfo().associativeMemory.hubIo
+    //   与诊断日志（节流 5 分钟/键）输出；load 的「无文件/损坏 → null（空启动）」语义不变。
+    const hubIoHealth = createHubIoHealthPre()
+    engine._hubIoHealth = hubIoHealth
+    const hubIo = createHubIoPre({
+      dir: hubDir,
+      health: hubIoHealth,
+      onError: (key, msg) => diagThrottled('hubIo:' + key, msg),
+    })
+    // ★#110：把 io 工厂挂到 engine，供 hub 喂数循环做**批内合并落盘**（`beginBatch` / `endBatch`）。
+    //   喂数循环在另一个块作用域里，拿不到本块的 `hubIo` 局部变量，只能走 engine 这条既有通道。
+    engine._hubIoFactory = hubIo
+    // ★P0-3（2026-09-22）：事实库此前是**内联**创建在下面的 stores 字面量里、engine 上无引用。
+    //   这里提到局部常量并单独挂一份，供 debugInfo() 的只读投影（factsPrune）使用。
+    //   不改任何既有行为：stores.facts 仍是同一个实例，只是有了名字。
+    const factStore = createFactStorePre({ config: { maxFacts: Number(engine.config.factRetentionMax) || 1000 }, io: hubIo('facts.json') })
+    engine._factStore = factStore
     engine._memoryHub = createMemoryHubPre({
       stores: {
         episodic: createEpisodicStorePre({ config: { minSegments: Number(engine.config.episodicMinSegments) || 2, retention: Number(engine.config.episodicRetention) || 256 }, io: hubIo('episodes.json') }),
-        facts: createFactStorePre({ io: hubIo('facts.json') }),
+        facts: factStore,
         procedures: createProcedureStorePre({
           // 2026-08-30 修复:gates 用 getter 活读 engine.config——挂载(apply 同步)时
           // engine.config 尚未 loadConfig,静态读会冻结 DEFAULT(3/2),设置页改门槛永不生效
@@ -9156,7 +9280,7 @@ export function apply(ctx, config) {
             // 0 值合法(验证用);仅非有限负值回退默认——不可用 || 0 会 falsy 穿透
             get minSessionDiversity() { const v = Number(engine.config.procedureMinSessions); return (Number.isFinite(v) && v >= 0) ? v : 3 },
             get minSuccessCount() { const v = Number(engine.config.procedureMinSuccess); return (Number.isFinite(v) && v >= 0) ? v : 2 },
-            get maxCorrectionRate() { return Number(engine.config.procedureCorrectionCap) || 0.3 },
+            get maxCorrectionRate() { const v = Number(engine.config.procedureCorrectionCap); return (Number.isFinite(v) && v >= 0) ? v : 0.3 },
             get maxContradictions() { return 0 },
             get highRiskRequiresApproval() { return engine.config.procedureHighRiskApproval !== false },
           },
@@ -9263,20 +9387,33 @@ export function apply(ctx, config) {
         // 异步富化+喂送(不阻塞 tick);单行失败静默
         void (async () => {
           let fed = 0
-          for (const row of newRows) {
-            try {
-              const src = Array.isArray(row.sourceIds) ? row.sourceIds[0] : null
-              if (src) {
-                const rec = await hubCorpusLookup(src)
-                if (rec) {
-                  row.subject = String(rec.heading || rec.text || '').split('\n')[0].slice(0, 30)
-                  row.predicate = '记录要点'
-                  row.object = String(rec.text || '').slice(0, 120)
+          // ★#110（2026-09-22）：批内合并落盘 —— 旧实现每行一次 upsert ⇒ **一次整份快照写盘**，
+          //   一批 N 行就是 N 次写放大。这里用 hubIo 的批控制把整批收敛成「批末最多一次/文件」。
+          //   批末一定 flush（finally），任何一行抛错也不会把已接受的改动留在内存不落盘。
+          const ioFactory = engine._hubIoFactory
+          try {
+            if (ioFactory && typeof ioFactory.beginBatch === 'function') ioFactory.beginBatch()
+            for (const row of newRows) {
+              try {
+                const src = Array.isArray(row.sourceIds) ? row.sourceIds[0] : null
+                if (src) {
+                  const rec = await hubCorpusLookup(src)
+                  if (rec) {
+                    row.subject = String(rec.heading || rec.text || '').split('\n')[0].slice(0, 30)
+                    row.predicate = '记录要点'
+                    row.object = String(rec.text || '').slice(0, 120)
+                  }
                 }
-              }
-              const r = hub.ingestJudgement(row)
-              if (r && r.consumed) fed++
-            } catch (_) {}
+                const r = hub.ingestJudgement(row)
+                if (r && r.consumed) fed++
+              } catch (_) {}
+            }
+          } finally {
+            if (ioFactory && typeof ioFactory.endBatch === 'function') {
+              const b = ioFactory.endBatch()
+              if (b && b.written) diag('hub feed batch: ' + b.written + ' 份快照批量落盘（合并 ' + newRows.length + ' 行喂入）')
+              if (b && b.ok === false) diag('hub feed batch: 有快照落盘失败 —— 原因见 hubIo 健康度（debugInfo().associativeMemory.hubIo）')
+            }
           }
           if (fed) diag('hub feed: +' + fed + '/' + newRows.length + ' rows consumed')
         })()
@@ -10150,7 +10287,13 @@ export function apply(ctx, config) {
         else { engine.state.latestHandoffText = '# 交接账本 · ' + engine.memToday() + ' ' + nowHm() + '\n\n' + ((r && r.clean) || writeH); engine.state.loadedAt = Date.now() }
         return (args.kind === 'plan'
           ? '白板 PLAN.md 已更新' + (r.archived ? '(旧版已归档: ' + r.archived + ')' : '(首建)') + ': ' + r.path
-          : '交接账本已写入: ' + r.path) + '\n请在本轮回复正文向用户转述本次更新要点。'
+          : '交接账本已写入: ' + r.path)
+          // ★ 2026-09-21 bugfix(A-2):handoff 此前**静默截断** —— sanitizeForWrite 超限时是
+          //   「截断 + truncated:true」返回 ok(:8625-8628),而本分支接住了 gateH 却从不外显该标志
+          //   (对照 note 分支 :10184 会拼提示)。账本四段固定以「进度与下一步」结尾,截断恰好砍掉它,
+          //   模型却收到「已写入」⇒ 跨窗口续命材料无声缩水。现与 note 分支对齐。
+          + (gateH.truncated ? '\n⚠ 账本超长已截断到 ' + writeH.length + ' 字符(上限 ' + (args.kind === 'plan' ? 200000 : 8000) + '),尾部「进度与下一步」可能已丢失 —— 请精简后重写。' : '')
+          + '\n请在本轮回复正文向用户转述本次更新要点。'
       }
       const replace = args.action === 'replace'
       // 写闸门: append 单条上限 8000 字; replace(整篇重写)放行到 20 万字, 但同样经受乱码/复读/重复块质量闸门
@@ -10383,8 +10526,26 @@ export function apply(ctx, config) {
         // —— action=activate：模型授权跳统计门 → 晋升 → 激活 → 导出 SKILL.md ——
         const pr = procs.promote(pid, {}, { authorizedBy: 'model' })
         if (!pr || !pr.ok || pr.decision !== 'promote') {
+          // ★ B-1 配套(用户 2026-09-22 方针①「模型友好」+ ②「原因要人能看懂」)：
+          //   旧文案只甩 decision + reasonCodes 机器码，模型读完不知道下一步该做什么，
+          //   遇到 high-risk 就以为"卡死了"。现在补一层**人话解释 + 可执行的下一步**，
+          //   机器码原样保留（便于日志/前端复用），模型据此能自己决定是补 successCriteria、
+          //   还是提示用户去「记忆中枢」点「批准」。
+          const codes = ((pr && pr.reasonCodes) || []).map(String)
+          const EXPLAIN = {
+            'high-risk-awaiting-approval': '该条被标为高风险，需要**用户在「记忆中枢」页签点「批准」**后才能晋升（批准只解这一道门，其余门槛不变）。你可以告诉用户这条待批准。',
+            'no-success-criteria': '缺少 successCriteria ⇒ 结构上无法晋升。请用 memory_procedure 补写「怎么算跑通」再调 action=activate。',
+            'observation-only': '这条是纯 episode 观察行（没有 steps/successCriteria），设计上不参与晋升；请改为写入一条真正的技能条目。',
+            'has-correction': '该条存在纠正记录（maxContradictions=0）⇒ 先解决矛盾，不要强推。',
+          }
+          const c3 = codes[0]
+          const human = EXPLAIN[c3] || (codes.find((c) => EXPLAIN[c]) ? EXPLAIN[codes.find((c) => EXPLAIN[c])] : '')
+          const corrCode = codes.find((c) => c.startsWith('correction-rate-'))
           return out + '\n未激活：晋升未通过（decision=' + String((pr && pr.decision) || '?') +
-            ' reasonCodes=' + JSON.stringify((pr && pr.reasonCodes) || []) + '）。条目仍在审批列表。'
+            ' reasonCodes=' + JSON.stringify(codes) + '）。条目仍在审批列表。' +
+            (human ? '\n→ ' + human : '') +
+            (corrCode ? '\n→ 纠正率超过当前上限（' + corrCode + '）：说明该条历史执行里被纠正过，先改进流程再重试。' : '') +
+            (codes.includes('diversity-below-3') ? '\n→ 跨会话证据不足（需要至少 3 个不同会话的成功记录）：继续在别的会话里用一次，或由用户手动晋升。' : '')
         }
         const ar = procs.activate(pid)
         if (!ar || !ar.ok) return out + '\n已晋升但激活失败：' + String((ar && ar.reason) || 'unknown')
@@ -10897,11 +11058,29 @@ export function apply(ctx, config) {
             // 不绕过任何 gate;每次动作进 diagnose 审计。
             const procs = hub.stores && hub.stores.procedures
             const pid = String((body && body.procedureId) || '')
-            if (['promote', 'activate', 'deprecate', 'pin'].includes(action)) {
+            // ★ B-1 修复(2026-09-22)：白名单补 `approve`。
+            //   旧白名单只有 promote/activate/deprecate/pin，而高风险条目建候选时恒 `approved:false`
+            //   （procedure-store.js:235）且全仓无任何代码能置真，promote 只会返回 decision:'ask'
+            //   ⇒ 高风险条目的晋升是**死路**。现在把"人来确认"这只手补上：approve 只解一道门，
+            //   其余五道结构门（已弃用 / 观察型 / 缺 successCriteria / 纠正率超限 / 存在纠正）照旧拦。
+            // ★B（2026-09-22）：白名单补 `force-promote`（人工**强制晋升**）。
+            //   动机（有数据证据）：只读投影 evaluatePromotion 对盘上 30 条**全部**返回 keep，
+            //   ⇒ 按 A-9 的门控，界面上一个可点的晋升按钮都没有（"手动通道看起来被关掉了"）。
+            //   其中「只被 diversity/success 两道统计门拦住」的行（实际 14 条里绝大多数）
+            //   在语义上是可以人工越过的 —— promote() 的 `if (!authorizedBy)` 正是为这场景留的口子。
+            if (['promote', 'force-promote', 'approve', 'activate', 'deprecate', 'pin'].includes(action)) {
               if (!procs) return writeJson(res, 200, { ok: false, reason: 'no-procedure-store' })
               if (!pid) return writeJson(res, 400, { error: 'procedureId required' })
               let r
-              if (action === 'promote') r = procs.promote(pid)
+              if (action === 'approve') r = procs.approve(pid, 'user')
+              else if (action === 'promote') r = procs.promote(pid)
+              // ★B（2026-09-22）：人工强制晋升 —— `authorizedBy:'user'`。
+              //   · 只越过 diversity / success 两道**统计门**；
+              //   · 结构门（deprecated / observationOnly / no-success-criteria / has-correction /
+              //     correction-rate / 高风险待批准）**照旧拦** —— 与 T4 冻结的"授权语义"逐字一致；
+              //   · 留痕：晋升成功会写 `p.authorizedBy = 'user'`，reasonCodes 记 `user-authorized`，
+              //     与模型授权（`model-authorized`）在审计面可区分。
+              else if (action === 'force-promote') r = procs.promote(pid, {}, { authorizedBy: 'user' })
               else if (action === 'activate') {
                 r = procs.activate(pid)
                 // ★ ⑪-2（用户 2026-09-19 拍板）：晋升为 active 后**自动导出** SKILL.md。

package/lib/intent-clean-safe.js

@@ -143,7 +143,7 @@ function looksEncodingCorruptedPre(trimmed) {
  * 判据是**标记短语**（任意位置），不要求行首 —— 这正是它区别于 F1/F2 的地方：
  * F1/F2 判「整行是信封」，F5 判「行内夹带信封」。
  */
-const RUNTIME_RESIDUE_RE = /Current DSH file policy|Current runtime context|Approval prompts are disabled in this session|\[Retrieved memory ref|Verify against the current user request|If a reference hints at what you need|Reason:\s*fv2 lane=|Score:\s*[0-9.]+ \(rank \d+\/\d+\)/i
+const RUNTIME_RESIDUE_RE = /Current DSH file policy|Current runtime context|Approval prompts are disabled in this session|\[Retrieved memory ref|Verify against the current user request|If a reference hints at what you need|Reason:\s*fv2 lane=|Score:\s*[0-9.]+ \(rank \d+\/\d+\)|^\s*(?:Reference|Source|Reason)\s*:\s*-\s*\d{1,2}:\d{2}\s*\[kind:|^\s*\d{1,2}:\d{2}\s*\[kind:[a-z]+\]|^\s*\[kind:[a-z]+\]/im
 
 /** F5：行内是否夹带运行时信封痕迹（不做清洗，只做判定）。 */
 export function looksRuntimeResiduePre(text) {