@modusensus/dsh-mneme 0.3.5 → 0.3.6

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-429%20passed-success)](https://github.com/modusensus/dsh-mneme)
+[![tests](https://img.shields.io/badge/tests-443%20passed-success)](https://github.com/modusensus/dsh-mneme)
 
 > 给 DeepSeek Harness 的跨会话记忆插件：让 Agent 记住你、记住项目、自动整理记忆。**Mneme**（Μνήμη）——希腊记忆女神 Mnemosyne 之名，掌管记忆与梦境，正如 autoDream 在后台巩固记忆。
 
@@ -243,7 +243,7 @@ src/
 lib/
 ├── client.js         # Web 面板（手写 ModuleLoader bundle）
 └── *.js              # src 的同步分发产物
-test/                 # 429 个 node:test 测试（含审计与三轴线压测不变量）
+test/                 # 443 个 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           # 运行 429 个测试
+npm test           # 运行 443 个测试
 npm run stress     # 三轴线压测：长会话检索 / 冲突仲裁 / 多 Agent 并发（离线 mock LLM）
 npm run sync       # 把 src/ 同步到 lib/（发布时由 prepack 钩子自动执行）
 ```

package/lib/api.js

@@ -268,21 +268,43 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     }
   });
 
-  // --- health: mirror sync state (F-NEW-03) ---
+  // --- health: mirror sync state (F-NEW-03 / v0.3.6) ---
+  // Auth-gated; only returns a sanitized error code (never raw last_error which
+  // may leak paths/token-like strings/internal hosts). On state read failure it
+  // reports unknown/degraded (fail-closed) instead of a false dirty=false.
   register({
     kind: "exact",
     path: "/api/dsh-mneme/health",
     handler(req, res) {
+      if (!requireAuth(req, res, apiToken)) return;
+      let state = null;
       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
-        });
+        state = service.getMirrorHealth?.() ?? null;
       } catch {
-        sendJson(res, 500, { error: "internal" });
+        // read failure is itself a health signal: do not report a false clean
+        sendJson(res, 200, { mirror: { dirty: null, status: "unknown", last_error: null, last_attempt: null, success_at: null } });
+        return;
       }
+      if (!state) {
+        sendJson(res, 200, { mirror: { dirty: null, status: "unknown", last_error: null, last_attempt: null, success_at: null } });
+        return;
+      }
+      // Sanitized: boolean dirty + coarse status only; error string is mapped to
+      // a bounded code, never echoed verbatim.
+      let code = null;
+      if (state.last_error) {
+        const e = String(state.last_error);
+        code = /enospc|no space/i.test(e) ? "no-space" : /permission|eacces/i.test(e) ? "permission" : "sync-failed";
+      }
+      sendJson(res, 200, {
+        mirror: {
+          dirty: state.dirty === true,
+          status: state.dirty === true ? "degraded" : (code ? "degraded" : "ok"),
+          last_error: code,
+          last_attempt: state.last_attempt ?? null,
+          success_at: state.success_at ?? null
+        }
+      });
     }
   });
 

package/lib/service.js

@@ -110,7 +110,7 @@ export function createService({ store, mirror, config, onWrite, logger }) {
 
   /**
    * Search for memories attached to a named entity (v0.3.0 Phase 3).
-   * 合并优先级（桉桉确认）：entity_attrs.memory_id 精确关联 = 1.0 > 关键词提及 = 0.7；
+   * 合并优先级：entity_attrs.memory_id 精确关联 = 1.0 > 关键词提及 = 0.7；
    * attr 命中不覆盖，keyword 只补充召回，最后按 _score 降序取 topK。
    * @param {string} entityName
    * @param {object} [options]
@@ -511,38 +511,82 @@ export function createService({ store, mirror, config, onWrite, logger }) {
    * 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）。
+  // v0.3.6（audit peer 4 阻断）：
+  //   - 开始时 incrementGeneration 绑定本次期望轮次 gen；成功用
+  //     markMirrorCleanForGeneration(gen, now) CAS/fence 清 dirty——旧 worker
+  //     （gen 已过期）不会误清另一 worker 未恢复的故障债务；
+  //   - 失败写 markMirrorDirty（递增 desired 绑定新债务），下次 recover 恢复；
+  //   - 逐 type 用 setTypeStatus 记录部分成功/失败（type_status JSON）；
+  //   - 所有 store 状态写入各自 try/catch，失败只 warn，绝不向外抛（F-NEW-03）。
   function syncMirror() {
     if (txDepth > 0 || !mirror) return; // deferred to the transaction's commit
     const now = new Date().toISOString();
+    let gen;
     try {
-      mirror.sync(reconcileHumanEdits(store.list({ limit: 500, includeForgotten: false })));
-      // 成功：写 clean 状态
+      // 绑定本次期望轮次，必须在任何渲染之前，避免制造幽灵债务
+      const state = store.incrementGeneration();
+      gen = state.generation;
+    } catch (stateError) {
+      logger?.warn?.("syncMirror: incrementGeneration failed:", stateError);
+      return;
+    }
+    // coveredTypes 提到 try 外初始化：即使 store.list 先抛错，catch 分支也有
+    // 合法的空 Set 可迭代，保证 syncMirror 自身绝不抛（fail-safe）。
+    const coveredTypes = new Set();
+    try {
+      // 预先获取本次要覆盖的 type 集合（只调一次 store.list）
+      const list = store.list({ limit: 500, includeForgotten: false });
+      for (const memory of list) {
+        if (memory?.type && TYPE_FILE[memory.type]) {
+          coveredTypes.add(memory.type);
+        }
+      }
+
+      // 全量渲染
+      mirror.sync(reconcileHumanEdits(list));
+
+      // 成功：CAS/fence 绑定到本地 gen，旧 worker（gen 已过期）会被拦截
       try {
-        store.markMirrorClean(now);
+        store.markMirrorCleanForGeneration(gen, now);
       } catch (stateError) {
-        // markMirrorClean 失败不能影响主要同步逻辑，仅记录日志
-        logger?.warn?.("syncMirror: markMirrorClean failed:", stateError);
+        logger?.warn?.("syncMirror: markMirrorCleanForGeneration failed:", stateError);
+      }
+      // 逐 type 标记为 clean
+      for (const type of coveredTypes) {
+        try {
+          store.setTypeStatus(type, { dirty: false, applied_gen: gen, last_error: null });
+        } catch (stateError) {
+          logger?.warn?.(`syncMirror: setTypeStatus(${type}) clean failed:`, stateError);
+        }
       }
     } catch (error) {
-      // 同步失败：写 dirty 状态
       const errMsg = error?.message ?? String(error);
       logger?.warn?.("syncMirror failed:", error);
       try {
+        // 债务绑定到新的一轮（desired generation +1）
         store.markMirrorDirty(errMsg, now);
       } catch (stateError) {
-        // markMirrorDirty 失败同样不能向外抛出
         logger?.warn?.("syncMirror: markMirrorDirty failed:", stateError);
       }
+      // 逐 type 标记为 dirty（applied_gen 不动）
+      for (const type of coveredTypes) {
+        try {
+          store.setTypeStatus(type, { dirty: true, last_error: errMsg });
+        } catch (stateError) {
+          logger?.warn?.(`syncMirror: setTypeStatus(${type}) dirty failed:`, stateError);
+        }
+      }
     }
   }
 
   // recoverMirror: 启动/手动 reconcile 时根据持久 dirty 状态决定是否恢复同步
-  // （F-NEW-03）。dirty=true → 有界重试（最多 3 次，立即重试）重跑 syncMirror
-  // 收敛镜像；某次成功（dirty 变 0）立即停止。返回 { recovered, error } 供
-  // index.js 启动 / api.js health 判断。一切 fail-safe，绝不向外抛。
+  // （F-NEW-03 + v0.3.6）。触发条件不只是 dirty——还检查
+  // generation > applied_generation（有未应用的债务），这样 COMMIT→dirty 崩溃
+  // 窗口（DB 提交后、markMirrorDirty/clean 前进程退出 → dirty=false 但
+  // generation 不一致）也能被捕获。有界重试（最多 3 次）重跑 syncMirror 收敛；
+  // 某次成功后 dirty=false 且无更新债务（generation <= applied_generation）
+  // 立即停止。返回 { recovered, error } 供 index.js 启动 / api.js health 判断。
+  // 一切 fail-safe，绝不向外抛。
   function recoverMirror() {
     const MAX_ATTEMPTS = 3;
     let lastError = null;
@@ -550,24 +594,29 @@ export function createService({ store, mirror, config, onWrite, logger }) {
 
     try {
       const state = store.getMirrorState();
-      if (!state?.dirty) {
+      // 崩溃窗口检测：dirty 或 generation > applied_generation（COMMIT→dirty 窗口）
+      if (!state?.dirty && !(state.generation > state.applied_generation)) {
         // 本来就干净：无需恢复，视为成功
         return { recovered: true, error: null };
       }
 
-      // dirty 状态：最多尝试 3 次 sync
+      // 有 dirty 或有未应用债务：最多尝试 3 次 sync
       for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
         try {
           syncMirror(); // syncMirror 内部已 catch，不会向外抛
           const currentState = store.getMirrorState();
-          if (!currentState?.dirty) {
-            // 成功：镜像已收敛为 clean
+          // 成功条件：dirty 为 false 且没有更新一轮的债务
+          // （generation <= applied_generation，恢复后由 syncMirror 里
+          //   markMirrorCleanForGeneration 自动把 applied 跟上）
+          if (!currentState?.dirty && currentState.generation <= currentState.applied_generation) {
             recovered = true;
             lastError = null;
             break;
           }
-          // 仍 dirty：记录最后一次错误供重试耗尽后上报
-          lastError = currentState.last_error || `Sync attempt ${attempt + 1} left mirror dirty`;
+          // 仍 dirty 或仍有更新债务：记录最后一次错误供重试耗尽后上报。
+          // 注意：若别的 worker 又失败产生新债务（dirty 仍 true），这是"新债务"
+          // 不是本次失败，继续重试直到耗尽次数。
+          lastError = currentState.last_error || `Sync attempt ${attempt + 1} left mirror dirty or has pending debt`;
         } catch (syncError) {
           // syncMirror 理论不抛，fail-safe 兜底
           const errMsg = syncError?.message ?? String(syncError);
@@ -579,7 +628,7 @@ export function createService({ store, mirror, config, onWrite, logger }) {
       if (!recovered) {
         logger?.warn?.("dsh-mneme mirror: recover failed after", MAX_ATTEMPTS, "attempts");
       } else {
-        logger?.warn?.("dsh-mneme mirror: recovered from dirty state");
+        logger?.warn?.("dsh-mneme mirror: recovered from dirty/pending state");
       }
     } catch (error) {
       // fail-safe：任何意外异常不向外抛

package/lib/store.js

@@ -169,12 +169,20 @@ CREATE INDEX IF NOT EXISTS idx_relations_type ON entity_relations(relation_type)
 -- syncMirror 失败不再只靠瞬时 console.warn —— dirty=1 提示镜像脏了需重渲染，
 -- last_error/last_attempt 记录失败原因与最近尝试，success_at 记录最近成功。
 -- 上层可据此在启动时重试、提供人工 reconcile 入口与健康状态查询。
+-- v0.3.6: 新增 generation/applied_generation/type_status —— desired-applied
+-- 建模镜像债务：generation 是期望同步轮次，applied_generation 是已成功应用
+-- 轮次（成功清 dirty 必须 CAS/fence 到具体轮次，旧 worker 不能清新故障），
+-- type_status 逐 type 记录部分成功状态。旧库经 PRAGMA table_info 检查后
+-- ALTER 补列，幂等且不丢数据。
 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）
+  success_at TEXT,                   -- 最近成功时间（ISO）
+  generation INTEGER NOT NULL DEFAULT 0,         -- 期望的同步轮次（desired）
+  applied_generation INTEGER NOT NULL DEFAULT 0, -- 已成功应用的轮次
+  type_status TEXT                               -- JSON: 逐 type 状态 {type: {dirty, applied_gen, last_error}}
 );
 `;
 
@@ -337,14 +345,33 @@ function toRelation(row) {
 
 function toMirrorState(row) {
   if (!row) {
-    return { dirty: false, last_error: null, last_attempt: null, success_at: null };
+    return {
+      dirty: false,
+      last_error: null,
+      last_attempt: null,
+      success_at: null,
+      generation: 0,
+      applied_generation: 0,
+      type_status: {}
+    };
+  }
+  let typeStatus = {};
+  if (row.type_status) {
+    try {
+      typeStatus = JSON.parse(row.type_status) || {};
+    } catch {
+      typeStatus = {};
+    }
   }
   return {
     id: row.id,
     dirty: row.dirty === 1,
     last_error: row.last_error,
     last_attempt: row.last_attempt,
-    success_at: row.success_at
+    success_at: row.success_at,
+    generation: Number(row.generation) || 0,
+    applied_generation: Number(row.applied_generation) || 0,
+    type_status: typeStatus
   };
 }
 
@@ -377,6 +404,19 @@ export function createStore(path) {
     db.exec("ALTER TABLE dream_runs ADD COLUMN policy_epoch INTEGER NOT NULL DEFAULT 0");
   }
 
+  // Legacy mirror_state without v0.3.6 generation columns → add each missing
+  // column idempotently (old DBs open cleanly, no data loss).
+  const mirrorCols = db.prepare("PRAGMA table_info(mirror_state)").all().map((c) => c.name);
+  if (!mirrorCols.includes("generation")) {
+    db.exec("ALTER TABLE mirror_state ADD COLUMN generation INTEGER NOT NULL DEFAULT 0");
+  }
+  if (!mirrorCols.includes("applied_generation")) {
+    db.exec("ALTER TABLE mirror_state ADD COLUMN applied_generation INTEGER NOT NULL DEFAULT 0");
+  }
+  if (!mirrorCols.includes("type_status")) {
+    db.exec("ALTER TABLE mirror_state ADD COLUMN type_status TEXT");
+  }
+
   // Per-instance monotonic timestamp guard: consecutive writes within the same
   // millisecond must still produce strictly increasing timestamps (test asserts
   // updated_at != created_at). State lives in the store closure, not module scope.
@@ -1113,14 +1153,25 @@ export function createStore(path) {
 
   /**
    * 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).
+   * {dirty?, last_error?, last_attempt?, success_at?, generation?,
+   * applied_generation?, type_status?} — only the keys present on the object
+   * are written, everything else is left untouched (partial upsert). type_status
+   * is stored as JSON text (objects are serialized on write), generation /
+   * applied_generation are coerced to non-negative integers. 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)
+    const ALLOWED = new Set([
+      "dirty",
+      "last_error",
+      "last_attempt",
+      "success_at",
+      "generation",
+      "applied_generation",
+      "type_status"
+    ]);
+    const keys = Object.keys(patch).filter(
+      (key) => ALLOWED.has(key) && Object.prototype.hasOwnProperty.call(patch, key)
     );
     if (keys.length === 0) {
       db.prepare(
@@ -1130,41 +1181,78 @@ export function createStore(path) {
     }
     // 列同时出现在 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]
-    );
+    const cols = [];
+    const values = [];
+    const updates = [];
+    for (const key of keys) {
+      let value = patch[key];
+      if (key === "dirty") {
+        value = value ? 1 : 0;
+      } else if (key === "generation" || key === "applied_generation") {
+        value = Math.trunc(Number(value)) || 0;
+      } else if (key === "type_status" && value != null && typeof value !== "string") {
+        value = JSON.stringify(value);
+      }
+      cols.push(key);
+      values.push(value);
+      updates.push(`${key} = excluded.${key}`);
+    }
+    const placeholders = cols.map(() => "?").join(", ");
     db.prepare(
-      `INSERT INTO mirror_state (id, ${cols}) VALUES ('main', ${placeholders})
-       ON CONFLICT(id) DO UPDATE SET ${updates}`
+      `INSERT INTO mirror_state (id, ${cols.join(", ")}) VALUES ('main', ${placeholders})
+       ON CONFLICT(id) DO UPDATE SET ${updates.join(", ")}`
     ).run(...values);
     return getMirrorState();
   }
 
-  /** Current mirror state; default {dirty:0, last_error:null, last_attempt:null, success_at:null} when absent. */
+  /** Current mirror state; default {dirty:0, last_error:null, last_attempt:null, success_at:null, generation:0, applied_generation:0, type_status:{}} 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). */
+  /**
+   * Mark the mirror dirty after a failed sync (dirty=1 + last_error +
+   * last_attempt). v0.3.6: also bumps the desired generation so the debt is
+   * bound to a specific sync round; applied_generation is left untouched
+   * (the round was NOT applied). A stale worker that started earlier cannot
+   * clear this newer debt — only a clean fenced to a generation at least as
+   * recent as this one may.
+   */
   function markMirrorDirty(error, now) {
+    const current = getMirrorState();
     return setMirrorState({
       dirty: 1,
       last_error: error,
-      last_attempt: now ?? nowIso()
+      last_attempt: now ?? nowIso(),
+      generation: (current.generation || 0) + 1
     });
   }
 
-  /** Convenience: mark the mirror clean after a successful sync (dirty=0 + last_error=null + success_at). */
+  /**
+   * Fenced clean (CAS): mark the mirror clean for a specific generation.
+   * First records that generation `gen` has been applied
+   * (applied_generation = MAX(applied_generation, gen)), then clears dirty only
+   * when the current desired generation has not advanced past gen — a stale
+   * worker cleaning an older round must not wipe a newer failure's debt.
+   * Returns the resulting state (dirty stays set when the fence holds).
+   */
+  function markMirrorCleanForGeneration(gen, now) {
+    const current = getMirrorState();
+    const applied = Math.max(current.applied_generation || 0, gen);
+    const patch = { applied_generation: applied };
+    if (applied >= gen && (current.generation || 0) <= gen) {
+      patch.dirty = 0;
+      patch.last_error = null;
+      patch.success_at = now ?? nowIso();
+    }
+    return setMirrorState(patch);
+  }
+
+  /** Convenience: mark the mirror clean for the current desired generation (backward-compatible with pre-v0.3.6 callers). */
   function markMirrorClean(now) {
-    return setMirrorState({
-      dirty: 0,
-      last_error: null,
-      success_at: now ?? nowIso()
-    });
+    const current = getMirrorState();
+    return markMirrorCleanForGeneration(current.generation || 0, now);
   }
 
   /** Convenience: clear only the dirty flag + last_error, leaving success_at untouched (manual reconcile / retry path). */
@@ -1172,6 +1260,30 @@ export function createStore(path) {
     return setMirrorState({ dirty: 0, last_error: null });
   }
 
+  /**
+   * Record per-type mirror status (partial success bookkeeping). `status` is a
+   * partial patch {dirty?, applied_gen?, last_error?} merged into the existing
+   * entry for `type` (other types untouched). Returns the updated full state.
+   */
+  function setTypeStatus(type, status) {
+    const current = getMirrorState();
+    const statuses = current.type_status || {};
+    statuses[type] = { ...(statuses[type] || {}), ...status };
+    return setMirrorState({ type_status: JSON.stringify(statuses) });
+  }
+
+  /** Per-type mirror status map {type: {dirty, applied_gen, last_error}}, {} when unset. */
+  function getTypeStatus() {
+    const current = getMirrorState();
+    return current.type_status || {};
+  }
+
+  /** Bump the desired generation (new sync round), returning the new state. */
+  function incrementGeneration() {
+    const current = getMirrorState();
+    return setMirrorState({ generation: (current.generation || 0) + 1 });
+  }
+
   return {
     db,
     count,
@@ -1224,7 +1336,11 @@ export function createStore(path) {
     getMirrorState,
     markMirrorDirty,
     markMirrorClean,
+    markMirrorCleanForGeneration,
     clearMirrorDirty,
+    setTypeStatus,
+    getTypeStatus,
+    incrementGeneration,
     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.5",
+  "version": "0.3.6",
   "license": "MIT",
   "type": "module",
   "main": "lib/index.js",

package/src/api.js

@@ -268,21 +268,43 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     }
   });
 
-  // --- health: mirror sync state (F-NEW-03) ---
+  // --- health: mirror sync state (F-NEW-03 / v0.3.6) ---
+  // Auth-gated; only returns a sanitized error code (never raw last_error which
+  // may leak paths/token-like strings/internal hosts). On state read failure it
+  // reports unknown/degraded (fail-closed) instead of a false dirty=false.
   register({
     kind: "exact",
     path: "/api/dsh-mneme/health",
     handler(req, res) {
+      if (!requireAuth(req, res, apiToken)) return;
+      let state = null;
       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
-        });
+        state = service.getMirrorHealth?.() ?? null;
       } catch {
-        sendJson(res, 500, { error: "internal" });
+        // read failure is itself a health signal: do not report a false clean
+        sendJson(res, 200, { mirror: { dirty: null, status: "unknown", last_error: null, last_attempt: null, success_at: null } });
+        return;
       }
+      if (!state) {
+        sendJson(res, 200, { mirror: { dirty: null, status: "unknown", last_error: null, last_attempt: null, success_at: null } });
+        return;
+      }
+      // Sanitized: boolean dirty + coarse status only; error string is mapped to
+      // a bounded code, never echoed verbatim.
+      let code = null;
+      if (state.last_error) {
+        const e = String(state.last_error);
+        code = /enospc|no space/i.test(e) ? "no-space" : /permission|eacces/i.test(e) ? "permission" : "sync-failed";
+      }
+      sendJson(res, 200, {
+        mirror: {
+          dirty: state.dirty === true,
+          status: state.dirty === true ? "degraded" : (code ? "degraded" : "ok"),
+          last_error: code,
+          last_attempt: state.last_attempt ?? null,
+          success_at: state.success_at ?? null
+        }
+      });
     }
   });