@modusensus/dsh-mneme 0.3.1 → 0.3.3

package/README.md

@@ -5,7 +5,7 @@
 [![npm version](https://img.shields.io/npm/v/@modusensus/dsh-mneme?color=blue&label=npm)](https://www.npmjs.com/package/@modusensus/dsh-mneme)
 [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![Awesome](https://awesome-dsh-plugin.com/badge.svg)](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
-[![tests](https://img.shields.io/badge/tests-404%20passed-success)](https://github.com/modusensus/dsh-mneme)
+[![tests](https://img.shields.io/badge/tests-429%20passed-success)](https://github.com/modusensus/dsh-mneme)
 
 > 给 DeepSeek Harness 的跨会话记忆插件：让 Agent 记住你、记住项目、自动整理记忆。**Mneme**（Μνήμη）——希腊记忆女神 Mnemosyne 之名，掌管记忆与梦境，正如 autoDream 在后台巩固记忆。
 
@@ -180,7 +180,7 @@ dsh web
 | `localEmbedBatchSize` | `8` | 本地 embedding 批大小（1-64） |
 | `ollamaBaseUrl` | `http://localhost:11434` | Ollama 服务地址 |
 | `ollamaModel` | `nomic-embed-text` | Ollama embedding 模型 |
-| `embedModelCacheDir` | 空 | 模型缓存目录（空 = transformers 默认缓存） |
+| `embedModelCacheDir` | 空 | 模型缓存目录（空 = 用户级 `~/.dsh/mneme/models`） |
 | `embedModelMirror` | `https://hf-mirror.com` | 模型下载镜像源 |
 | `vectorSearchTopK` | `20` | 向量搜索返回 Top-K |
 | `vectorSearchThreshold` | `0.65` | 向量搜索相似度阈值 |
@@ -243,7 +243,7 @@ src/
 lib/
 ├── client.js         # Web 面板（手写 ModuleLoader bundle）
 └── *.js              # src 的同步分发产物
-test/                 # 404 个 node:test 测试（含审计与三轴线压测不变量）
+test/                 # 429 个 node:test 测试（含审计与三轴线压测不变量）
 scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压测 · sync-lib.js 同步
 ```
 
@@ -252,7 +252,7 @@ scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压
 ```bash
 cd dsh-mneme
 npm install        # 安装 peer 依赖（以 devDependencies 形式，用于本地测试）
-npm test           # 运行 404 个测试
+npm test           # 运行 429 个测试
 npm run stress     # 三轴线压测：长会话检索 / 冲突仲裁 / 多 Agent 并发（离线 mock LLM）
 npm run sync       # 把 src/ 同步到 lib/（发布时由 prepack 钩子自动执行）
 ```

package/lib/api.js

@@ -268,6 +268,24 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     }
   });
 
+  // --- health: mirror sync state (F-NEW-03) ---
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/health",
+    handler(req, res) {
+      try {
+        const state = service.getMirrorHealth?.() ?? null;
+        sendJson(res, 200, {
+          mirror: state
+            ? { dirty: state.dirty === true, last_error: state.last_error ?? null, last_attempt: state.last_attempt ?? null, success_at: state.success_at ?? null }
+            : null
+        });
+      } catch {
+        sendJson(res, 500, { error: "internal" });
+      }
+    }
+  });
+
   // --- custom commands ---
   register({
     kind: "exact",

package/lib/config.js

@@ -42,7 +42,9 @@ export const Config = z.object({
   ollamaBaseUrl: z.string().default("http://localhost:11434"),
   ollamaModel: z.string().default("nomic-embed-text"),
 
-  // Model download/cache.
+  // Model download/cache. When empty (default), models are cached under the
+  // user-level path ~/.dsh/mneme/models (resolved in local-embedder/reranker);
+  // a non-empty value is used verbatim.
   embedModelCacheDir: z.string().default(""),
   embedModelMirror: z.string().default("https://hf-mirror.com"),
 

package/lib/index.js

@@ -45,6 +45,12 @@ export const apply = (ctx, config) => {
   const mirror = createMirror(memoryDir);
   const service = createService({ store, mirror, config: cfg, logger: ctx.logger });
 
+  // F-NEW-03: if the mirror sync failed last run (persisted dirty state), retry
+  // a safe re-render at boot so a stale mirror converges without needing a
+  // business write. Bounded: single attempt; on failure dirty stays for the
+  // next boot. Never throws.
+  service.recoverMirror();
+
   // Recall-layer receipt: when searchMemories runs with recordRecall=true, the
   // retrieval scene (query/mode/topK/threshold + candidates) is persisted to
   // recall_runs for audit/replay — the sibling of the dream_runs judgment trail.

package/lib/local-embedder.js

@@ -3,6 +3,9 @@
 // old embedding.js logic). All classes share one interface so the orchestrator
 // can pick a backend by provider name and degrade gracefully on failure.
 // Methods throw on error — the caller decides the fallback chain.
+import os from "node:os";
+import path from "node:path";
+
 const DEFAULT_TIMEOUT_MS = 15000;
 
 /** djb2 — stable, fast fingerprint for a provider/model string. */
@@ -47,7 +50,9 @@ export class LocalEmbedder {
     this._dimension = opts.dimension || 512;
     this.device = opts.device || "cpu";
     this.batchSize = opts.batchSize || 8;
-    this.cacheDir = String(opts.cacheDir ?? "").trim();
+    this.cacheDir =
+      String(opts.cacheDir ?? "").trim() ||
+      path.join(os.homedir(), ".dsh", "mneme", "models");
     this.useDtype = opts.useDtype || "q8";
     this.logger = opts.logger ?? null;
     // Test hook: replace the pipeline factory without touching modules.

package/lib/reranker.js

@@ -1,3 +1,6 @@
+import os from "node:os";
+import path from "node:path";
+
 // Cross-encoder re-ranker for dsh-mneme recall candidates. Uses
 // bge-reranker-base through transformers.js: tries the native `rerank` task
 // first, then the sequence-classification head (sigmoid on the logit delta),
@@ -65,7 +68,9 @@ export class LocalReranker {
     this.maxCandidates = opts.maxCandidates || 30;
     this.scoreThreshold = opts.scoreThreshold ?? 0.1;
     this.device = opts.device || "cpu";
-    this.cacheDir = String(opts.cacheDir ?? "").trim();
+    this.cacheDir =
+      String(opts.cacheDir ?? "").trim() ||
+      path.join(os.homedir(), ".dsh", "mneme", "models");
     this.logger = opts.logger ?? null;
     this.engineFactory = opts.engineFactory || defaultPipelineLoader;
     // Injectable seam: async (query, passage) => number. When set, init()

package/lib/service.js

@@ -391,8 +391,12 @@ export function createService({ store, mirror, config, onWrite, logger }) {
         const hasDiff = (patch.title !== undefined && existing.title !== patch.title)
           || (patch.content !== undefined && existing.content !== patch.content);
         if (!hasDiff) continue;
-        store.update(edit.id, patch);
+        // 人工编辑回灌后触发 re-embed（issue #3 残留修复）：向量必须与
+        // 新 title/content 一致。scheduleEmbed 为 fire-and-forget，
+        // 内部 try/catch 吞错，失败不影响主流程。
+        const merged = store.update(edit.id, patch);
         applied++;
+        scheduleEmbed(merged);
       }
     }
     if (applied) {
@@ -483,17 +487,123 @@ export function createService({ store, mirror, config, onWrite, logger }) {
    * non-forgotten memories are mirrored: forgotten entries must not reach the
    * human-editable file (a human "edit" could otherwise resurrect them).
    */
+  // syncMirror: 同步 mirror，并在失败/成功时持久记录 dirty 状态；保证自身不抛出。
+  // 失败写 store.markMirrorDirty（dirty=1 + last_error + last_attempt），成功写
+  // store.markMirrorClean（dirty=0 + last_error=null + success_at）。状态写入用
+  // try/catch 包住，避免 db 关闭等场景下 syncMirror 自身再抛出（F-NEW-03）。
   function syncMirror() {
     if (txDepth > 0 || !mirror) return; // deferred to the transaction's commit
+    const now = new Date().toISOString();
     try {
       mirror.sync(reconcileHumanEdits(store.list({ limit: 500, includeForgotten: false })));
+      // 成功：写 clean 状态
+      try {
+        store.markMirrorClean(now);
+      } catch (stateError) {
+        // markMirrorClean 失败不能影响主要同步逻辑，仅记录日志
+        logger?.warn?.("syncMirror: markMirrorClean failed:", stateError);
+      }
     } catch (error) {
+      // 同步失败：写 dirty 状态
+      const errMsg = error?.message ?? String(error);
       logger?.warn?.("syncMirror failed:", error);
+      try {
+        store.markMirrorDirty(errMsg, now);
+      } catch (stateError) {
+        // markMirrorDirty 失败同样不能向外抛出
+        logger?.warn?.("syncMirror: markMirrorDirty failed:", stateError);
+      }
+    }
+  }
+
+  // recoverMirror: 启动/手动 reconcile 时根据持久 dirty 状态决定是否恢复同步
+  // （F-NEW-03）。dirty=true → 有界重试（最多 3 次，立即重试）重跑 syncMirror
+  // 收敛镜像；某次成功（dirty 变 0）立即停止。返回 { recovered, error } 供
+  // index.js 启动 / api.js health 判断。一切 fail-safe，绝不向外抛。
+  function recoverMirror() {
+    const MAX_ATTEMPTS = 3;
+    let lastError = null;
+    let recovered = false;
+
+    try {
+      const state = store.getMirrorState();
+      if (!state?.dirty) {
+        // 本来就干净：无需恢复，视为成功
+        return { recovered: true, error: null };
+      }
+
+      // dirty 状态：最多尝试 3 次 sync
+      for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+        try {
+          syncMirror(); // syncMirror 内部已 catch，不会向外抛
+          const currentState = store.getMirrorState();
+          if (!currentState?.dirty) {
+            // 成功：镜像已收敛为 clean
+            recovered = true;
+            lastError = null;
+            break;
+          }
+          // 仍 dirty：记录最后一次错误供重试耗尽后上报
+          lastError = currentState.last_error || `Sync attempt ${attempt + 1} left mirror dirty`;
+        } catch (syncError) {
+          // syncMirror 理论不抛，fail-safe 兜底
+          const errMsg = syncError?.message ?? String(syncError);
+          logger?.warn?.("recoverMirror: sync attempt failed:", errMsg);
+          lastError = errMsg;
+        }
+      }
+
+      if (!recovered) {
+        logger?.warn?.("dsh-mneme mirror: recover failed after", MAX_ATTEMPTS, "attempts");
+      } else {
+        logger?.warn?.("dsh-mneme mirror: recovered from dirty state");
+      }
+    } catch (error) {
+      // fail-safe：任何意外异常不向外抛
+      lastError = error?.message ?? String(error);
+      logger?.warn?.("dsh-mneme mirror: recover failed with unexpected error:", error);
+    }
+
+    return { recovered, error: recovered ? null : lastError };
+  }
+
+  // getMirrorHealth: 暴露 mirror 同步健康状态，供 api.js /health 使用
+  // （F-NEW-03）。把 DB 的 dirty 0/1 转成 boolean；fail-safe，绝不向外抛。
+  function getMirrorHealth() {
+    try {
+      const state = store.getMirrorState();
+      if (!state) {
+        // 无状态行：返回安全默认值
+        return {
+          dirty: false,
+          last_error: null,
+          last_attempt: null,
+          success_at: null
+        };
+      }
+      return {
+        dirty: Boolean(state.dirty),
+        last_error: state.last_error ?? null,
+        last_attempt: state.last_attempt ?? null,
+        success_at: state.success_at ?? null
+      };
+    } catch (error) {
+      // fail-safe：状态读取失败也不向外抛
+      logger?.warn?.("getMirrorHealth failed:", error);
+      return {
+        dirty: false,
+        last_error: error?.message ?? String(error),
+        last_attempt: null,
+        success_at: null
+      };
     }
   }
 
   return {
     saveWithDedupe,
+    recoverMirror,
+    getMirrorHealth,
+    getMirrorState: () => store.getMirrorState(),
     injectCandidates,
     mergeHumanEdits,
     toApiList,

package/lib/store.js

@@ -164,6 +164,18 @@ CREATE TABLE IF NOT EXISTS entity_relations (
 CREATE INDEX IF NOT EXISTS idx_relations_from ON entity_relations(from_entity);
 CREATE INDEX IF NOT EXISTS idx_relations_to ON entity_relations(to_entity);
 CREATE INDEX IF NOT EXISTS idx_relations_type ON entity_relations(relation_type);
+
+-- mirror 渲染状态 (F-NEW-03): 单行持久记录 mirror 同步失败/成功状态，使
+-- syncMirror 失败不再只靠瞬时 console.warn —— dirty=1 提示镜像脏了需重渲染，
+-- last_error/last_attempt 记录失败原因与最近尝试，success_at 记录最近成功。
+-- 上层可据此在启动时重试、提供人工 reconcile 入口与健康状态查询。
+CREATE TABLE IF NOT EXISTS mirror_state (
+  id TEXT PRIMARY KEY,               -- 单一状态行（用 'main'）
+  dirty INTEGER NOT NULL DEFAULT 0,  -- 1=镜像脏了需重渲染
+  last_error TEXT,                   -- 最近失败原因
+  last_attempt TEXT,                 -- 最近尝试时间（ISO）
+  success_at TEXT                    -- 最近成功时间（ISO）
+);
 `;
 
 const TYPES = new Set(["preference", "project", "decision", "history", "summary"]);
@@ -323,6 +335,19 @@ function toRelation(row) {
   };
 }
 
+function toMirrorState(row) {
+  if (!row) {
+    return { dirty: false, last_error: null, last_attempt: null, success_at: null };
+  }
+  return {
+    id: row.id,
+    dirty: row.dirty === 1,
+    last_error: row.last_error,
+    last_attempt: row.last_attempt,
+    success_at: row.success_at
+  };
+}
+
 function parseJsonArray(raw) {
   try {
     const arr = JSON.parse(raw);
@@ -1084,6 +1109,69 @@ export function createStore(path) {
     ).all(entityId, entityId).map(toRelation);
   }
 
+  // --- mirror sync state (F-NEW-03) -----------------------------------------
+
+  /**
+   * Upsert the single mirror_state row (id='main'). patch accepts
+   * {dirty?, last_error?, last_attempt?, success_at?} — only the keys present
+   * on the object are written, everything else is left untouched. Returns the
+   * freshly read state row (default shape when absent).
+   */
+  function setMirrorState(patch) {
+    const ALLOWED = new Set(["dirty", "last_error", "last_attempt", "success_at"]);
+    const keys = Object.keys(patch).filter((key) =>
+      ALLOWED.has(key) && Object.prototype.hasOwnProperty.call(patch, key)
+    );
+    if (keys.length === 0) {
+      db.prepare(
+        "INSERT INTO mirror_state (id) VALUES ('main') ON CONFLICT(id) DO NOTHING"
+      ).run();
+      return getMirrorState();
+    }
+    // 列同时出现在 INSERT 与 ON CONFLICT 里（excluded.*），保证首次插入也写入
+    // patch 值，而不只是默认值；未传入的列保持不变（partial upsert）。
+    const cols = keys.join(", ");
+    const placeholders = keys.map(() => "?").join(", ");
+    const updates = keys.map((k) => `${k} = excluded.${k}`).join(", ");
+    const values = keys.map((key) =>
+      key === "dirty" ? (patch[key] ? 1 : 0) : patch[key]
+    );
+    db.prepare(
+      `INSERT INTO mirror_state (id, ${cols}) VALUES ('main', ${placeholders})
+       ON CONFLICT(id) DO UPDATE SET ${updates}`
+    ).run(...values);
+    return getMirrorState();
+  }
+
+  /** Current mirror state; default {dirty:0, last_error:null, last_attempt:null, success_at:null} when absent. */
+  function getMirrorState() {
+    const row = db.prepare("SELECT * FROM mirror_state WHERE id = 'main'").get();
+    return toMirrorState(row);
+  }
+
+  /** Convenience: mark the mirror dirty after a failed sync (dirty=1 + last_error + last_attempt). */
+  function markMirrorDirty(error, now) {
+    return setMirrorState({
+      dirty: 1,
+      last_error: error,
+      last_attempt: now ?? nowIso()
+    });
+  }
+
+  /** Convenience: mark the mirror clean after a successful sync (dirty=0 + last_error=null + success_at). */
+  function markMirrorClean(now) {
+    return setMirrorState({
+      dirty: 0,
+      last_error: null,
+      success_at: now ?? nowIso()
+    });
+  }
+
+  /** Convenience: clear only the dirty flag + last_error, leaving success_at untouched (manual reconcile / retry path). */
+  function clearMirrorDirty() {
+    return setMirrorState({ dirty: 0, last_error: null });
+  }
+
   return {
     db,
     count,
@@ -1132,6 +1220,11 @@ export function createStore(path) {
     saveRelation,
     migrateAttrsToMemory,
     getRelations,
+    setMirrorState,
+    getMirrorState,
+    markMirrorDirty,
+    markMirrorClean,
+    clearMirrorDirty,
     close() {
       db.close();
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@modusensus/dsh-mneme",
   "description": "Cross-session memory plugin for DeepSeek Harness with autoDream consolidation: SQLite store, Markdown mirrors, 6 model tools, automatic injection, session summarization, user profile/rules, custom slash commands, vector (semantic) search, and a Web GUI panel",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "license": "MIT",
   "type": "module",
   "main": "lib/index.js",

package/src/api.js

@@ -268,6 +268,24 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     }
   });
 
+  // --- health: mirror sync state (F-NEW-03) ---
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/health",
+    handler(req, res) {
+      try {
+        const state = service.getMirrorHealth?.() ?? null;
+        sendJson(res, 200, {
+          mirror: state
+            ? { dirty: state.dirty === true, last_error: state.last_error ?? null, last_attempt: state.last_attempt ?? null, success_at: state.success_at ?? null }
+            : null
+        });
+      } catch {
+        sendJson(res, 500, { error: "internal" });
+      }
+    }
+  });
+
   // --- custom commands ---
   register({
     kind: "exact",

package/src/config.js

@@ -42,7 +42,9 @@ export const Config = z.object({
   ollamaBaseUrl: z.string().default("http://localhost:11434"),
   ollamaModel: z.string().default("nomic-embed-text"),
 
-  // Model download/cache.
+  // Model download/cache. When empty (default), models are cached under the
+  // user-level path ~/.dsh/mneme/models (resolved in local-embedder/reranker);
+  // a non-empty value is used verbatim.
   embedModelCacheDir: z.string().default(""),
   embedModelMirror: z.string().default("https://hf-mirror.com"),
 

package/src/index.js

@@ -45,6 +45,12 @@ export const apply = (ctx, config) => {
   const mirror = createMirror(memoryDir);
   const service = createService({ store, mirror, config: cfg, logger: ctx.logger });
 
+  // F-NEW-03: if the mirror sync failed last run (persisted dirty state), retry
+  // a safe re-render at boot so a stale mirror converges without needing a
+  // business write. Bounded: single attempt; on failure dirty stays for the
+  // next boot. Never throws.
+  service.recoverMirror();
+
   // Recall-layer receipt: when searchMemories runs with recordRecall=true, the
   // retrieval scene (query/mode/topK/threshold + candidates) is persisted to
   // recall_runs for audit/replay — the sibling of the dream_runs judgment trail.

package/src/local-embedder.js

@@ -3,6 +3,9 @@
 // old embedding.js logic). All classes share one interface so the orchestrator
 // can pick a backend by provider name and degrade gracefully on failure.
 // Methods throw on error — the caller decides the fallback chain.
+import os from "node:os";
+import path from "node:path";
+
 const DEFAULT_TIMEOUT_MS = 15000;
 
 /** djb2 — stable, fast fingerprint for a provider/model string. */
@@ -47,7 +50,9 @@ export class LocalEmbedder {
     this._dimension = opts.dimension || 512;
     this.device = opts.device || "cpu";
     this.batchSize = opts.batchSize || 8;
-    this.cacheDir = String(opts.cacheDir ?? "").trim();
+    this.cacheDir =
+      String(opts.cacheDir ?? "").trim() ||
+      path.join(os.homedir(), ".dsh", "mneme", "models");
     this.useDtype = opts.useDtype || "q8";
     this.logger = opts.logger ?? null;
     // Test hook: replace the pipeline factory without touching modules.

package/src/reranker.js

@@ -1,3 +1,6 @@
+import os from "node:os";
+import path from "node:path";
+
 // Cross-encoder re-ranker for dsh-mneme recall candidates. Uses
 // bge-reranker-base through transformers.js: tries the native `rerank` task
 // first, then the sequence-classification head (sigmoid on the logit delta),
@@ -65,7 +68,9 @@ export class LocalReranker {
     this.maxCandidates = opts.maxCandidates || 30;
     this.scoreThreshold = opts.scoreThreshold ?? 0.1;
     this.device = opts.device || "cpu";
-    this.cacheDir = String(opts.cacheDir ?? "").trim();
+    this.cacheDir =
+      String(opts.cacheDir ?? "").trim() ||
+      path.join(os.homedir(), ".dsh", "mneme", "models");
     this.logger = opts.logger ?? null;
     this.engineFactory = opts.engineFactory || defaultPipelineLoader;
     // Injectable seam: async (query, passage) => number. When set, init()

package/src/service.js

@@ -391,8 +391,12 @@ export function createService({ store, mirror, config, onWrite, logger }) {
         const hasDiff = (patch.title !== undefined && existing.title !== patch.title)
           || (patch.content !== undefined && existing.content !== patch.content);
         if (!hasDiff) continue;
-        store.update(edit.id, patch);
+        // 人工编辑回灌后触发 re-embed（issue #3 残留修复）：向量必须与
+        // 新 title/content 一致。scheduleEmbed 为 fire-and-forget，
+        // 内部 try/catch 吞错，失败不影响主流程。
+        const merged = store.update(edit.id, patch);
         applied++;
+        scheduleEmbed(merged);
       }
     }
     if (applied) {
@@ -483,17 +487,123 @@ export function createService({ store, mirror, config, onWrite, logger }) {
    * non-forgotten memories are mirrored: forgotten entries must not reach the
    * human-editable file (a human "edit" could otherwise resurrect them).
    */
+  // syncMirror: 同步 mirror，并在失败/成功时持久记录 dirty 状态；保证自身不抛出。
+  // 失败写 store.markMirrorDirty（dirty=1 + last_error + last_attempt），成功写
+  // store.markMirrorClean（dirty=0 + last_error=null + success_at）。状态写入用
+  // try/catch 包住，避免 db 关闭等场景下 syncMirror 自身再抛出（F-NEW-03）。
   function syncMirror() {
     if (txDepth > 0 || !mirror) return; // deferred to the transaction's commit
+    const now = new Date().toISOString();
     try {
       mirror.sync(reconcileHumanEdits(store.list({ limit: 500, includeForgotten: false })));
+      // 成功：写 clean 状态
+      try {
+        store.markMirrorClean(now);
+      } catch (stateError) {
+        // markMirrorClean 失败不能影响主要同步逻辑，仅记录日志
+        logger?.warn?.("syncMirror: markMirrorClean failed:", stateError);
+      }
     } catch (error) {
+      // 同步失败：写 dirty 状态
+      const errMsg = error?.message ?? String(error);
       logger?.warn?.("syncMirror failed:", error);
+      try {
+        store.markMirrorDirty(errMsg, now);
+      } catch (stateError) {
+        // markMirrorDirty 失败同样不能向外抛出
+        logger?.warn?.("syncMirror: markMirrorDirty failed:", stateError);
+      }
+    }
+  }
+
+  // recoverMirror: 启动/手动 reconcile 时根据持久 dirty 状态决定是否恢复同步
+  // （F-NEW-03）。dirty=true → 有界重试（最多 3 次，立即重试）重跑 syncMirror
+  // 收敛镜像；某次成功（dirty 变 0）立即停止。返回 { recovered, error } 供
+  // index.js 启动 / api.js health 判断。一切 fail-safe，绝不向外抛。
+  function recoverMirror() {
+    const MAX_ATTEMPTS = 3;
+    let lastError = null;
+    let recovered = false;
+
+    try {
+      const state = store.getMirrorState();
+      if (!state?.dirty) {
+        // 本来就干净：无需恢复，视为成功
+        return { recovered: true, error: null };
+      }
+
+      // dirty 状态：最多尝试 3 次 sync
+      for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+        try {
+          syncMirror(); // syncMirror 内部已 catch，不会向外抛
+          const currentState = store.getMirrorState();
+          if (!currentState?.dirty) {
+            // 成功：镜像已收敛为 clean
+            recovered = true;
+            lastError = null;
+            break;
+          }
+          // 仍 dirty：记录最后一次错误供重试耗尽后上报
+          lastError = currentState.last_error || `Sync attempt ${attempt + 1} left mirror dirty`;
+        } catch (syncError) {
+          // syncMirror 理论不抛，fail-safe 兜底
+          const errMsg = syncError?.message ?? String(syncError);
+          logger?.warn?.("recoverMirror: sync attempt failed:", errMsg);
+          lastError = errMsg;
+        }
+      }
+
+      if (!recovered) {
+        logger?.warn?.("dsh-mneme mirror: recover failed after", MAX_ATTEMPTS, "attempts");
+      } else {
+        logger?.warn?.("dsh-mneme mirror: recovered from dirty state");
+      }
+    } catch (error) {
+      // fail-safe：任何意外异常不向外抛
+      lastError = error?.message ?? String(error);
+      logger?.warn?.("dsh-mneme mirror: recover failed with unexpected error:", error);
+    }
+
+    return { recovered, error: recovered ? null : lastError };
+  }
+
+  // getMirrorHealth: 暴露 mirror 同步健康状态，供 api.js /health 使用
+  // （F-NEW-03）。把 DB 的 dirty 0/1 转成 boolean；fail-safe，绝不向外抛。
+  function getMirrorHealth() {
+    try {
+      const state = store.getMirrorState();
+      if (!state) {
+        // 无状态行：返回安全默认值
+        return {
+          dirty: false,
+          last_error: null,
+          last_attempt: null,
+          success_at: null
+        };
+      }
+      return {
+        dirty: Boolean(state.dirty),
+        last_error: state.last_error ?? null,
+        last_attempt: state.last_attempt ?? null,
+        success_at: state.success_at ?? null
+      };
+    } catch (error) {
+      // fail-safe：状态读取失败也不向外抛
+      logger?.warn?.("getMirrorHealth failed:", error);
+      return {
+        dirty: false,
+        last_error: error?.message ?? String(error),
+        last_attempt: null,
+        success_at: null
+      };
     }
   }
 
   return {
     saveWithDedupe,
+    recoverMirror,
+    getMirrorHealth,
+    getMirrorState: () => store.getMirrorState(),
     injectCandidates,
     mergeHumanEdits,
     toApiList,