@modusensus/dsh-mneme 0.3.0 → 0.3.2

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/entities/extractor.js

@@ -140,7 +140,7 @@ async function resolveEntity(entity, store) {
   return created.id;
 }
 
-export async function extractEntities(memory, { store, config, callLLM }) {
+export async function extractEntities(memory, { store, config, callLLM, logger }) {
   try {
     if (!memory || !memory.content) {
       return { ok: false, error: "Invalid memory: missing content" };
@@ -181,7 +181,7 @@ export async function extractEntities(memory, { store, config, callLLM }) {
         resolvedEntities.push({ ...entity, entity_id: entityId });
       } catch (err) {
         skipCount++;
-        console.warn(`[extractor] Failed to resolve entity "${entity.name}":`, err.message);
+        logger?.warn?.(`[extractor] Failed to resolve entity "${entity.name}":`, err.message);
       }
     }
     
@@ -201,7 +201,7 @@ export async function extractEntities(memory, { store, config, callLLM }) {
           attrs.push(saved);
         } catch (err) {
           skipCount++;
-          console.warn(`[extractor] Failed to save attr "${attr.key}" for entity "${entity.name}":`, err.message);
+          logger?.warn?.(`[extractor] Failed to save attr "${attr.key}" for entity "${entity.name}":`, err.message);
         }
       }
     }
@@ -224,7 +224,7 @@ export async function extractEntities(memory, { store, config, callLLM }) {
         savedRelations.push(saved);
       } catch (err) {
         skipCount++;
-        console.warn(`[extractor] Failed to save relation "${rel.from} -> ${rel.to}":`, err.message);
+        logger?.warn?.(`[extractor] Failed to save relation "${rel.from} -> ${rel.to}":`, err.message);
       }
     }
     

package/lib/index.js

@@ -43,7 +43,13 @@ export const apply = (ctx, config) => {
     store.deleteOldFailures(new Date(Date.now() - 90 * 86400000).toISOString());
   } catch { /* non-fatal */ }
   const mirror = createMirror(memoryDir);
-  const service = createService({ store, mirror, config: cfg });
+  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
@@ -196,7 +202,7 @@ export const apply = (ctx, config) => {
       return text;
     };
     service.setEntityExtractor((memory) =>
-      extractEntities(memory, { store, config: cfg, callLLM: streamEntityText })
+      extractEntities(memory, { store, config: cfg, callLLM: streamEntityText, logger: ctx.logger })
         .catch((err) => {
           ctx.logger?.warn?.(`[dsh-mneme] entity extraction failed: ${String(err)}`);
           return { ok: false, error: String(err) };

package/lib/service.js

@@ -3,7 +3,7 @@ import { TYPE_FILE } from "./mirror.js";
 
 const INJECT_TYPES = new Set(["preference", "project", "decision", "summary"]);
 
-export function createService({ store, mirror, config, onWrite }) {
+export function createService({ store, mirror, config, onWrite, logger }) {
   // Optional dream scheduler hook, installed via setDreamHook after creation
   // (the scheduler holds a reference back to the service, so it cannot be
   // passed in the constructor). Fired on the same write events as onWrite.
@@ -56,10 +56,10 @@ export function createService({ store, mirror, config, onWrite }) {
     if (!config.entityExtractionEnabled || !entityExtractor) return;
     try {
       entityExtractor(memory).catch((err) => {
-        console.warn("entity extraction failed:", err);
+        logger?.warn?.("entity extraction failed:", err);
       });
     } catch (err) {
-      console.warn("entity extraction failed:", err);
+      logger?.warn?.("entity extraction failed:", err);
     }
   }
 
@@ -306,7 +306,7 @@ export function createService({ store, mirror, config, onWrite }) {
       try {
         syncMirror();
       } catch (error) {
-        console.warn("syncMirror failed after transaction:", error);
+        logger?.warn?.("syncMirror failed after transaction:", error);
       }
       notifyWrite();
     }
@@ -483,17 +483,123 @@ export function createService({ store, mirror, config, onWrite }) {
    * 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) {
-      console.warn("syncMirror failed:", 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.0",
+  "version": "0.3.2",
   "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/entities/extractor.js

@@ -140,7 +140,7 @@ async function resolveEntity(entity, store) {
   return created.id;
 }
 
-export async function extractEntities(memory, { store, config, callLLM }) {
+export async function extractEntities(memory, { store, config, callLLM, logger }) {
   try {
     if (!memory || !memory.content) {
       return { ok: false, error: "Invalid memory: missing content" };
@@ -181,7 +181,7 @@ export async function extractEntities(memory, { store, config, callLLM }) {
         resolvedEntities.push({ ...entity, entity_id: entityId });
       } catch (err) {
         skipCount++;
-        console.warn(`[extractor] Failed to resolve entity "${entity.name}":`, err.message);
+        logger?.warn?.(`[extractor] Failed to resolve entity "${entity.name}":`, err.message);
       }
     }
     
@@ -201,7 +201,7 @@ export async function extractEntities(memory, { store, config, callLLM }) {
           attrs.push(saved);
         } catch (err) {
           skipCount++;
-          console.warn(`[extractor] Failed to save attr "${attr.key}" for entity "${entity.name}":`, err.message);
+          logger?.warn?.(`[extractor] Failed to save attr "${attr.key}" for entity "${entity.name}":`, err.message);
         }
       }
     }
@@ -224,7 +224,7 @@ export async function extractEntities(memory, { store, config, callLLM }) {
         savedRelations.push(saved);
       } catch (err) {
         skipCount++;
-        console.warn(`[extractor] Failed to save relation "${rel.from} -> ${rel.to}":`, err.message);
+        logger?.warn?.(`[extractor] Failed to save relation "${rel.from} -> ${rel.to}":`, err.message);
       }
     }
     

package/src/index.js

@@ -43,7 +43,13 @@ export const apply = (ctx, config) => {
     store.deleteOldFailures(new Date(Date.now() - 90 * 86400000).toISOString());
   } catch { /* non-fatal */ }
   const mirror = createMirror(memoryDir);
-  const service = createService({ store, mirror, config: cfg });
+  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
@@ -196,7 +202,7 @@ export const apply = (ctx, config) => {
       return text;
     };
     service.setEntityExtractor((memory) =>
-      extractEntities(memory, { store, config: cfg, callLLM: streamEntityText })
+      extractEntities(memory, { store, config: cfg, callLLM: streamEntityText, logger: ctx.logger })
         .catch((err) => {
           ctx.logger?.warn?.(`[dsh-mneme] entity extraction failed: ${String(err)}`);
           return { ok: false, error: String(err) };

package/src/service.js

@@ -3,7 +3,7 @@ import { TYPE_FILE } from "./mirror.js";
 
 const INJECT_TYPES = new Set(["preference", "project", "decision", "summary"]);
 
-export function createService({ store, mirror, config, onWrite }) {
+export function createService({ store, mirror, config, onWrite, logger }) {
   // Optional dream scheduler hook, installed via setDreamHook after creation
   // (the scheduler holds a reference back to the service, so it cannot be
   // passed in the constructor). Fired on the same write events as onWrite.
@@ -56,10 +56,10 @@ export function createService({ store, mirror, config, onWrite }) {
     if (!config.entityExtractionEnabled || !entityExtractor) return;
     try {
       entityExtractor(memory).catch((err) => {
-        console.warn("entity extraction failed:", err);
+        logger?.warn?.("entity extraction failed:", err);
       });
     } catch (err) {
-      console.warn("entity extraction failed:", err);
+      logger?.warn?.("entity extraction failed:", err);
     }
   }
 
@@ -306,7 +306,7 @@ export function createService({ store, mirror, config, onWrite }) {
       try {
         syncMirror();
       } catch (error) {
-        console.warn("syncMirror failed after transaction:", error);
+        logger?.warn?.("syncMirror failed after transaction:", error);
       }
       notifyWrite();
     }
@@ -483,17 +483,123 @@ export function createService({ store, mirror, config, onWrite }) {
    * 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) {
-      console.warn("syncMirror failed:", 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,