@modusensus/dsh-mneme 0.8.6 → 0.8.8

package/src/document-index.js

@@ -0,0 +1,94 @@
+// dsh-mneme/src/document-index.js
+// documentDir 的索引（issue #296 第二批）。`<documentDir>/index.md` 整文件机器所有，
+// 可从库随时重建：内容里没有任何「生成时间」，所以删掉再同步一次得到逐字节相同的
+// 文件（test/document-dir.test.js 钉住这一条）。
+//
+// 与镜像侧 documents.md 的分工（#296 第 2 节表格）：这里是 document 子系统自己的
+// 索引（id + 标题 + 定位 + managed 标记），那份是带 frontmatter 的镜像只读视图
+// （多一个摘要首句）。两份都只列指针行，都不含正文——正文永远在 doc_path 指向的
+// 文件里，那是 agent 的东西。
+import { readFileSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { STR } from "./lang.js";
+import { isManagedDocumentPath } from "./document.js";
+
+function oneLine(text) {
+  return String(text ?? "").replace(/\s+/g, " ").trim();
+}
+
+/**
+ * @param {string} dir resolved documentDir (see resolveDocumentDir)
+ * @param {"zh"|"en"} language instance language, same as the mirror
+ */
+export function createDocumentIndex(dir, language = "zh") {
+  const filePath = join(dir, "index.md");
+
+  /**
+   * Render the whole file from the given rows. Sorted updated_at DESC, id ASC:
+   * the same store state must always render the same bytes (rebuildable).
+   */
+  function render(memories) {
+    const items = (memories ?? []).slice().sort((a, b) => {
+      if (a.updated_at !== b.updated_at) return a.updated_at < b.updated_at ? 1 : -1;
+      return a.id < b.id ? -1 : 1;
+    });
+    const lines = [STR.documentIndexHeader[language]()];
+    for (const m of items) {
+      const where = isManagedDocumentPath(dir, m.doc_path) ? "managed" : "external";
+      // doc_path 理论上必带（store.saveDocument 是唯一铸造口），缺了就只写定位
+      // 标记，不编造路径。
+      const path = m.doc_path ? ` · \`${oneLine(m.doc_path)}\`` : "";
+      lines.push(`- \`${m.id}\` **${oneLine(m.title)}** · ${where}${path}`);
+    }
+    return `${lines.join("\n")}\n`;
+  }
+
+  /**
+   * Ensure the directory exists (recursive). Never throws: callers warn and move
+   * on — a managed directory that cannot be created must not fail plugin boot.
+   */
+  function ensure() {
+    try {
+      mkdirSync(dir, { recursive: true });
+      return { ok: true };
+    } catch (error) {
+      return { ok: false, error: error?.message ?? String(error) };
+    }
+  }
+
+  /**
+   * Write the index if it changed. Never throws: a failed index write must not
+   * fail the business write that triggered it (same fail-safe shape as
+   * mirror.sync). Returns { ok, changed } or { ok: false, error }.
+   */
+  function sync(memories) {
+    const text = render(memories);
+    let prev = null;
+    try { prev = readFileSync(filePath, "utf8"); } catch { /* first write */ }
+    if (prev === text) return { ok: true, changed: false };
+    const ready = ensure();
+    if (!ready.ok) return { ok: false, error: ready.error };
+    try {
+      writeFileSync(filePath, text, "utf8");
+      return { ok: true, changed: true };
+    } catch (error) {
+      return { ok: false, error: error?.message ?? String(error) };
+    }
+  }
+
+  /**
+   * Drop the index file (闸关时用）。闸关意味着 document 子系统整体退出，留一份
+   * 陈旧索引会列出已归档、已遗忘的指针行——正是 documents.md 在闸关时被镜像删掉
+   * 要避免的那种「看着还在、其实已关」的视图。删掉不从库取数，O(1)，也不抛。
+   */
+  function remove() {
+    try {
+      rmSync(filePath, { force: true });
+      return { ok: true };
+    } catch (error) {
+      return { ok: false, error: error?.message ?? String(error) };
+    }
+  }
+
+  return { filePath, render, sync, ensure, remove };
+}

package/src/document.js

@@ -13,7 +13,7 @@
 
 import { statSync } from "node:fs";
 import { homedir } from "node:os";
-import { isAbsolute, resolve } from "node:path";
+import { isAbsolute, resolve, sep } from "node:path";
 import { scopeKeyOf } from "./scope.js";
 import { cosineSimilarity } from "./dream/clustering.js";
 
@@ -23,26 +23,71 @@ import { cosineSimilarity } from "./dream/clustering.js";
 // 新版判成「无近重复」，留下两行活跃摘要漂移——supersede 探测必须全时段。
 const DOCUMENT_MIN_SIM = 0.92;
 const CANDIDATE_LIMIT = 200;
+const DOCUMENT_DIR_NAME = "documents";
+
+/**
+ * 解析 managed 文档目录（#296 第二批）。`configured` 为空 = 跟随 memoryDir 的
+ * `<memoryDir>/documents/`；`~` / `~/` / `~\` 展开到用户 home；相对路径落在
+ * memoryDir 下（本键自己的规则：memoryDir 的相对路径原样留着走 cwd 语义）；
+ * 绝对路径归一化后原样用。纯函数，路径解析集中在 index.js 调用一次。
+ */
+export function resolveDocumentDir(memoryDir, configured = "") {
+  const raw = String(configured ?? "").trim();
+  if (!raw) return resolve(memoryDir, DOCUMENT_DIR_NAME);
+  if (raw === "~" || raw.startsWith("~/") || raw.startsWith("~\\")) {
+    return resolve(homedir(), raw.slice(2));
+  }
+  return isAbsolute(raw) ? resolve(raw) : resolve(memoryDir, raw);
+}
+
+/**
+ * 这个路径是不是落在 managed 目录里（`documentDir` 内 = mneme 管的树，`index.md`
+ * 与镜像 md 同权；之外 = 只登记指针行、正文一个字节都不碰）。比较前两边都归一化，
+ * Windows 上大小写不敏感（文件系统就是），否则 `C:\a\documents\x.md` 与
+ * `c:\A\Documents\x.md` 会被判成两类。
+ */
+export function isManagedDocumentPath(dir, path) {
+  if (!dir || !path) return false;
+  const norm = (p) => (process.platform === "win32" ? String(p).toLowerCase() : String(p));
+  const base = norm(resolve(dir));
+  const target = norm(resolve(path));
+  const prefix = base.endsWith(sep) ? base : base + sep;
+  return target === base || target.startsWith(prefix);
+}
 
 // 追加到被取代行正文的指针注记。刻意不带语言分支：id 是跨语言稳定键（用户
 // 对 tag/章节名建议用英文同理——指针性内容不翻译）；可追溯链 = 注记里的新行
 // id + 旧行 content_history 里的旧摘要（source=superseded）。
 const supersededByPointer = (id) => `\n\n[superseded by ${id}]`;
 
+// 升格吸收不碰的类型（#275 拍板 5 的边界）：吸收的对象是「原子条」，而下面这两种
+// 行各有自己的生命周期，被归档会各自留下第二行——
+//   document：本体是磁盘上的文件。归档它等于替用户撤下外档；而且 supersede 探测
+//     只看活跃行（store.list 默认排除归档），同一 path 下次注册会在旧行还挂着
+//     「新版本」语义时再铸一行，指针注记与 content_history 记账也走不到。
+//   summary：dream 总览与叙述按 source 身份去重、并按注入档位常驻。归档它会让下一
+//     次做梦把它当不存在（候选集同样只取活跃行），于是库里多出一行同源总览。
+// 口径是保守方向的：拿不准的行一律不吸收——少做一步没有代价，收错一步是内容事故。
+const ABSORB_EXEMPT_TYPES = new Set(["document", "summary"]);
+
 /**
  * Build the document registrar. Injected deps are service.js closure members
  * (store / embedQuery / transaction / finalize) so this module stays free of
  * service-internal wiring; `finalize` is the single write epilogue (mirror
  * sync + notify + re-embed) so callers never duplicate it.
  *
- * @returns {(payload: object) => Promise<object>}
+ * `pinnedTypes` 是注入的 #249 逐字保真池（service.js 的 PINNED_MEMORY_TYPES）：
+ * 这里不 import 它在 service.js 里，是因为 service.js 反向 import 本模块——
+ * 方向反了会成环。
+ *
+ * @returns {(payload: object, opts?: object) => Promise<object>}
  *   `{ action: "created"|"superseded", memory, superseded?, evidence_kept,
- *      evidence_dropped, degraded }`
+ *      evidence_dropped, evidence_archived, degraded }`
  * @throws flag 关 / 路径非法或文件缺失 / title 或 summary 为空 / evidence 全部
  *   捏造 / 仅 vector 近重复（疑似重复外档，交 agent 裁决而不是静默二选一）。
  */
-export function createDocumentRegistrar({ store, config, embedQuery, pushContentHistory, transaction, finalize }) {
-  return async function registerDocument(payload, { hiddenEvidenceIds = [] } = {}) {
+export function createDocumentRegistrar({ store, config, embedQuery, pushContentHistory, transaction, finalize, pinnedTypes }) {
+  return async function registerDocument(payload, { hiddenEvidenceIds = [], archiveEvidence = true } = {}) {
     // opt-in 总闸（#230 对齐 #228 形态）：关 = 注册入口整体不存在，错误信息
     // 指回配置键，agent 能准确转告用户去开。
     if (config?.documentMemoryEnabled !== true) {
@@ -90,15 +135,14 @@ export function createDocumentRegistrar({ store, config, embedQuery, pushContent
     const hidden = new Set((Array.isArray(hiddenEvidenceIds) ? hiddenEvidenceIds : []).map((id) => String(id)));
     const kept = [];
     const dropped = [];
+    // 存在但已归档的引用另记一份：它可能是被上一版文档升格吸收走的行（见下方
+    // supersede 目标探测后的「认回」），不能一律按「不可用」处理。
+    const archivedRefs = new Set();
     for (const id of wanted) {
       const row = hidden.has(id) ? null : store.getById(id);
+      if (row?.archived) archivedRefs.add(id);
       (row && !row.archived ? kept : dropped).push(id);
     }
-    if (wanted.length > 0 && kept.length === 0) {
-      throw new Error(
-        `registerDocument: all ${wanted.length} evidence ids are unknown, archived or out of scope — fabricated evidence is rejected`
-      );
-    }
 
     const title = String(payload?.title ?? "").trim();
     if (!title) throw new Error("registerDocument: title is required");
@@ -131,6 +175,25 @@ export function createDocumentRegistrar({ store, config, embedQuery, pushContent
       .filter((m) => scopeMatches(m));
     const explicitTarget = scopeMatched.find((m) => samePath(m.doc_path, expanded))
       ?? scopeMatched.find((m) => m.title.trim() === title);
+    // 升格吸收过的引用认回（#275 拍板 5 的配套）：evidence 行在文档注册成功后就翻了
+    // archived，于是「同一份文档出新版、evidence 照旧」这一最常规的路径会整批落在
+    // dropped——那会被下面的捏造判据误报成「证据都是编的」。口径：已归档行仍可为
+    // **吸收它的那份文档**背书（loser.evidence 就是它吸收走的名单），不为别的文档
+    // 背书；捏造与跨 scope 照旧拒绝。
+    if (explicitTarget) {
+      const own = new Set(explicitTarget.evidence ?? []);
+      for (const id of archivedRefs) {
+        if (!own.has(id)) continue;
+        const at = dropped.indexOf(id);
+        if (at >= 0) dropped.splice(at, 1);
+        kept.push(id);
+      }
+    }
+    if (wanted.length > 0 && kept.length === 0) {
+      throw new Error(
+        `registerDocument: all ${wanted.length} evidence ids are unknown, archived or out of scope — fabricated evidence is rejected`
+      );
+    }
     if (!explicitTarget) {
       // vector 档：embedder 不可用/向量缺失一律跳过——去重是增强不是写入依赖
       // （findSessionDuplicate 同原则）。probe 用 title+summary，与行向量
@@ -206,7 +269,25 @@ export function createDocumentRegistrar({ store, config, embedQuery, pushContent
         store.setArchived(loser.id, true);
         superseded = store.getById(loser.id);
       }
-      return { created, superseded };
+      // #275 拍板 5（#230 验收口径的补丁）：升格吸收的 evidence 行随之退出活跃面——
+      // 一次吸收 20 条，库里就是「21 行不是 1 行」。四条口径：①与本行同一事务（要么
+      // 都成、要么都不成）；②pinned（constraint / preference，即 #249 的逐字保真池）
+      // 永不自动归档——升格不能绕过它；③自有生命周期的类型（document / summary，见
+      // ABSORB_EXEMPT_TYPES）不吸收，吸收的是原子条；④只翻标志位、内容与审计全留
+      // （可恢复），opt-out 走 archiveEvidence。
+      // pinnedTypes 拿不到就不做这一步：宁可少做，也不能把保真池当普通行收走。
+      let evidenceArchived = 0;
+      if (archiveEvidence && pinnedTypes && typeof pinnedTypes.has === "function") {
+        for (const id of kept) {
+          // 事务内重读：期间被别的进程归档/遗忘的行不重复计数，也不误伤 pinned。
+          const row = store.getById(id);
+          if (!row || row.archived || row.forgotten) continue;
+          if (pinnedTypes.has(row.type) || ABSORB_EXEMPT_TYPES.has(row.type)) continue;
+          store.setArchived(id, true);
+          evidenceArchived += 1;
+        }
+      }
+      return { created, superseded, evidenceArchived };
     });
     finalize(result.superseded ? [result.created, result.superseded] : [result.created]);
     return {
@@ -215,6 +296,7 @@ export function createDocumentRegistrar({ store, config, embedQuery, pushContent
       ...(result.superseded ? { superseded: result.superseded } : {}),
       evidence_kept: kept.length,
       evidence_dropped: dropped.length,
+      evidence_archived: result.evidenceArchived,
       degraded: dropped.length > 0
     };
   };

package/src/dream.js

@@ -2,6 +2,12 @@ import { validateDecisions, applyDecisions } from "./dream/decisions.js";
 import { clusterMemories, findPotentialConflicts, cosineSimilarity } from "./dream/clustering.js";
 import { clusterByTag, intersectEvidence } from "./dream/narratives.js";
 import { scopeKeyOf } from "./scope.js";
+// Issue #239（第 4 项）镜像到巩固：错峰时段解析与「最近的高峰结束时刻」从独立的
+// 零依赖模块 peak-hours.js 取（该模块从 summarize.js 抽出，PR #320 review）——
+// 不另写一份解析器，两份实现漂移会让「同一个时段串在两处行为不同」，那比没有
+// 这个功能更糟。此前直接 import summarize.js，#316 后 summarize 反向依赖 dream
+// （withEffortFallback 复用），会成真循环，故抽模块。
+import { isInPeakWindow, nextOffPeakAt } from "./peak-hours.js";
 import { createHash, randomUUID } from "node:crypto";
 import { STR, langOf } from "./lang.js";
 export { validateDecisions, applyDecisions, withEffortFallback, describeStreamFailure, resolveDreamEffort, resolveRoute };
@@ -341,6 +347,9 @@ async function runAuditedLlm(ctx, service, config, spec, body) {
  * accepted → reasoning capped; rejected → provider default (old behavior),
  * logged so the rejection is observable.
  */
+// Issue #315：effort 拒收判别式的单一来源。summarize 的流失败以 aborted 结果
+// 返回，需在折叠成 undefined 前用同一甄别（各处手写会漂移）。
+export const EFFORT_REJECT_RE = /reasoning[\s_]*effort|UNSUPPORTED_REASONING_EFFORT/i;
 async function withEffortFallback(ctx, effort, attempt, fallback, getStreamError) {
   if (!effort || effort === "none") return attempt();
   try {
@@ -351,17 +360,20 @@ async function withEffortFallback(ctx, effort, attempt, fallback, getStreamError
       // on the chunk's failure reason here or the retry below is dead code
       // for the stream path.
       const reason = String(getStreamError?.() ?? "");
-      if (/reasoning[\s_]*effort|UNSUPPORTED_REASONING_EFFORT/i.test(reason)) {
+      if (EFFORT_REJECT_RE.test(reason)) {
         ctx.logger?.warn?.(`dsh-mneme dream: reasoningEffort "${effort}" rejected via stream (${reason}); retrying without it`);
         return fallback();
       }
     }
     return result;
   } catch (error) {
+    // dispose/取消中止直接放行，绝不能被误判成 effort 拒收而触发 fallback
+    //（取消后重打一次不带 effort 的调用是浪费，且可能掩盖真实的取消意图）。
+    if (error?.name === "AbortError") throw error;
     const message = String(error?.message ?? error);
     // matches both "reasoning effort" (natural language) and the bare
     // "UNSUPPORTED_REASONING_EFFORT" error code (underscore).
-    if (!/reasoning[\s_]*effort/i.test(message)) throw error;
+    if (!EFFORT_REJECT_RE.test(message)) throw error;
     ctx.logger?.warn?.(`dsh-mneme dream: reasoningEffort "${effort}" rejected (${message}); retrying without it`);
     return fallback();
   }
@@ -744,8 +756,16 @@ export async function maintainIndexAfterDream(decisions, service, semantic) {
   if (embedder.modelHash) vectorIndex.markModel?.(embedder.modelHash, embedder.dimension);
 }
 
-export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChars = 5000, delayMs = 2000, minIntervalMs = 0, logger, semantic = null, lastRunAtSeed = 0 }) {
+// Issue #292：连续失败退避的间隔封顶（30 分钟）。封顶只拦指数「增长」，不把
+// 用户配得比这更大的 dreamMinIntervalMinutes 基数压小（见 effectiveMinIntervalMs）。
+const FAILURE_BACKOFF_CAP_MS = 30 * 60 * 1000;
+
+export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChars = 5000, delayMs = 2000, minIntervalMs = 0, failureBackoff = false, logger, semantic = null, lastRunAtSeed = 0, peakHours = "", peakMaxDeferMinutes = 120, auditPeakSkip = null, now = () => Date.now(), setTimeoutFn = setTimeout, clearTimeoutFn = clearTimeout }) {
   let pendingTimer = null;
+  // Issue #239（第 4 项）镜像到巩固：高峰顺延定时器。与 pendingTimer 分开——两者
+  // 语义不同（一个是「马上要跑」，一个是「等出高峰再跑」），合成一个变量会让
+  // maybeSchedule 的守卫在顺延期间把新的写入触发误当成「已有待跑」而吞掉。
+  let deferTimer = null;
   let running = false;
   let disposed = false;
   let baseline = { count: 0, chars: 0 };
@@ -755,6 +775,21 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
   // lastRunAtSeed：调用方从 dream_runs 审计表读出的上次开跑时刻——
   // 内存变量进程重启即归零，闸门对新实例放行 → 重启后立刻连发（#89 根因）。
   let lastRunAt = lastRunAtSeed;
+  // Issue #292（#135 派生）：同会话内连续失败计数。失败（onRun 抛错或返回
+  // ok:false）+1，成功清零；无返回结果的 run（no-op 桩）视为完成且无失败，
+  // 不动计数。纯内存变量、宿主重启归零——跨重启的冷却由 lastRunAtSeed（#291）
+  // 持久化负责，两者不重叠。
+  let consecutiveFailures = 0;
+
+  // Issue #292：有效最小间隔 = 基数 × 2^连续失败数，封顶 30 分钟。退避关闭或
+  // 尚无失败时逐字节返回基数（默认关 = 行为与现状一致）。基数 0 无闸可翻倍
+  // （本键不自己产生间隔）；封顶取 max(基数, cap)，指数再大也不会把用户配的
+  // 大基数压小。2^N 溢出成 Infinity 由 Math.min 兜到 cap，无需另设上限位数。
+  function effectiveMinIntervalMs() {
+    if (!failureBackoff || consecutiveFailures <= 0) return minIntervalMs;
+    const cap = Math.max(minIntervalMs, FAILURE_BACKOFF_CAP_MS);
+    return Math.min(minIntervalMs * 2 ** consecutiveFailures, cap);
+  }
 
   function shouldTrigger(service) {
     const memories = service.all().filter((m) => !m.archived && m.type !== "summary" && m.type !== "document");
@@ -766,51 +801,115 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
   }
 
   function maybeSchedule(service) {
-    if (disposed || running || pendingTimer) return false;
-    // Issue #89（请求 2）：最小触发间隔闸门。
-    if (minIntervalMs > 0 && Date.now() - lastRunAt < minIntervalMs) return false;
+    if (disposed || running || pendingTimer || deferTimer) return false;
+    // Issue #89（请求 2）：最小触发间隔闸门。#292 退避开启时改用指数放大的
+    // 有效间隔：连续失败越多，下次放行越晚（恒定失败的模型不再按固定节奏连发，
+    // 只会越打越稀）。失败 run 本就占用间隔（lastRunAt 在开跑时刷新，见 #89），
+    // 这里放大的是同一道闸，不新增任何状态面。间隔内的触发静默跳过：没有调用
+    // 发生，也就没有可审计的对象（与 #89 口径一致，不写审计行）。
+    if (minIntervalMs > 0 && now() - lastRunAt < effectiveMinIntervalMs()) return false;
     const { trigger, count, chars } = shouldTrigger(service);
     if (!trigger) return false;
-    pendingTimer = setTimeout(() => {
+    // Issue #239（第 4 项，错峰队列）镜像到巩固：命中高峰就不调模型。与蒸馏的差别
+    // 在于巩固是**全局单实例**（蒸馏按会话各挂一个定时器），所以这里只需要一个
+    // deferTimer，且不需要 deferredRuns 那套按会话去重。
+    // baseline 刻意不刷新：阈值继续累积，留到非高峰一次性巩固（一次大 run 比多次
+    // 小 run 省）。审计只登记一行 skip——「为什么不再做梦了」必须对用户可观测。
+    if (isInPeakWindow(new Date(now()), peakHours)) {
+      try {
+        auditPeakSkip?.({ count, chars });
+      } catch (error) {
+        // 记账是 best-effort：写审计行失败只 warn，绝不反噬调度本身。
+        logger?.warn?.(`dsh-mneme dream: peak-hours audit failed: ${String(error)}`);
+      }
+      scheduleDeferredRun(service);
+      return false;
+    }
+    pendingTimer = setTimeoutFn(() => {
       pendingTimer = null;
-      running = true;
-      lastRunAt = Date.now();
-      // Defer the onRun invocation so a synchronous throw cannot escape the
-      // timer callback (which would crash the process) and skip the teardown.
-      // Errors are logged, never swallowed silently. inFlight lets dispose()
-      // await the running consolidation before the caller closes the store.
-      inFlight = Promise.resolve()
-        .then(() => (onRun ? onRun() : Promise.resolve({ ok: true, skipped: true })))
-        .then((result) => {
-          // Refresh the baseline only for a successful run (design §5.3: an
-          // LLM failure must not move the baseline, so the next write can
-          // immediately re-trigger a retry). A `{ok:false}` result or a throw
-          // keeps the old baseline. A run that reports nothing is treated as
-          // completed without failure (no-op hooks / minimal test doubles).
-          if (result && result.ok) {
-            try {
-              baseline = shouldTrigger(service);
-            } catch (error) {
-              // Store closed mid-flight: keep the last known baseline.
-              logger?.warn?.(`dsh-mneme dream: baseline refresh failed: ${String(error)}`);
-            }
-          }
-        })
-        .catch((error) => {
-          logger?.warn?.(`dsh-mneme dream: run failed: ${error?.message ?? error}`);
-          // Failed runs do not refresh the baseline.
-        })
-        .finally(() => {
-          running = false;
-          inFlight = null;
-        });
+      startRun(service);
     }, delayMs);
     return true;
   }
 
+  /**
+   * Issue #239：高峰内择时补跑——挂到「距当前最近的一个高峰结束时刻」，被
+   * peakMaxDeferMinutes 截断时到点照跑（bypassPeak），长高峰不会把巩固饿死。
+   * 定时器 unref：不阻止宿主退出。重复触发不叠加（deferTimer 已在 maybeSchedule
+   * 的守卫里，这里再判一次以防从其它路径进来）。
+   */
+  function scheduleDeferredRun(service) {
+    if (disposed || deferTimer) return;
+    const at = nextOffPeakAt(new Date(now()), peakHours);
+    if (!at) return;
+    const maxDeferMs = (peakMaxDeferMinutes ?? 0) * 60000;
+    let delay = Math.max(0, at.getTime() - now());
+    const capped = maxDeferMs > 0 && delay > maxDeferMs;
+    if (capped) delay = maxDeferMs;
+    deferTimer = setTimeoutFn(() => {
+      deferTimer = null;
+      if (disposed) return;
+      // 截断放行时仍在高峰：不再重新顺延（否则长高峰里会无限顺延，等于把巩固
+      // 关掉）。直接开跑，与蒸馏的 bypassPeak 同口径。
+      if (!capped && isInPeakWindow(new Date(now()), peakHours)) {
+        // 理论上到点已出高峰；时钟跳变/时段串被改小可能落回高峰内，此时再顺延一次。
+        scheduleDeferredRun(service);
+        return;
+      }
+      logger?.info?.(`dsh-mneme dream: peak-hours deferred run firing (capped=${capped}, delayMs=${delay})`);
+      startRun(service);
+    }, delay);
+    deferTimer.unref?.();
+  }
+
+  /**
+   * 真正开跑。抽出来是因为两条路径都要用：写入触发的正常路径，与高峰顺延后的
+   * 补跑路径。onRun 的调用刻意放在 Promise 里——同步抛出的异常若逃出 timer 回调
+   * 会直接崩掉进程并跳过收尾。inFlight 让 dispose() 能等完这一轮再关库。
+   */
+  function startRun(service) {
+    running = true;
+    lastRunAt = now();
+    inFlight = Promise.resolve()
+      .then(() => (onRun ? onRun() : Promise.resolve({ ok: true, skipped: true })))
+      .then((result) => {
+        // Refresh the baseline only for a successful run (design §5.3: an
+        // LLM failure must not move the baseline, so the next write can
+        // immediately re-trigger a retry). A `{ok:false}` result or a throw
+        // keeps the old baseline. A run that reports nothing is treated as
+        // completed without failure (no-op hooks / minimal test doubles).
+        if (result && result.ok) {
+          consecutiveFailures = 0; // Issue #292：成功清零，下次触发回到基数间隔
+          try {
+            baseline = shouldTrigger(service);
+          } catch (error) {
+            // Store closed mid-flight: keep the last known baseline.
+            logger?.warn?.(`dsh-mneme dream: baseline refresh failed: ${String(error)}`);
+          }
+        } else if (result) {
+          // Issue #292：ok:false（LLM 失败 / 空体 / 整单拒绝）计入连败；degraded
+          // 的 run 走 ok:true（LLM 本身成功了，只是决策被部分应用）→ 算成功、清零。
+          // 退避关闭时该计数没有消费者，行为与此前逐字节一致。
+          consecutiveFailures += 1;
+        }
+        // result 为空（no-op 桩 / 最小测试替身）＝完成且无失败：基线与连败计数都不动。
+      })
+      .catch((error) => {
+        logger?.warn?.(`dsh-mneme dream: run failed: ${error?.message ?? error}`);
+        // Failed runs do not refresh the baseline.
+        consecutiveFailures += 1; // Issue #292：抛错同样计入连败
+      })
+      .finally(() => {
+        running = false;
+        inFlight = null;
+      });
+  }
+
   async function dispose() {
     disposed = true;
-    if (pendingTimer) { clearTimeout(pendingTimer); pendingTimer = null; }
+    if (pendingTimer) { clearTimeoutFn(pendingTimer); pendingTimer = null; }
+    // Issue #239：高峰顺延定时器同样要清，否则进程关闭后仍会触发一次巩固。
+    if (deferTimer) { clearTimeoutFn(deferTimer); deferTimer = null; }
     // An in-flight run is left to complete naturally (its LLM calls are
     // already paid for and aborting would discard the work). Await it so the
     // caller can close the store only after every write has landed.

package/src/guide.js

@@ -42,3 +42,21 @@ export const TOOL_GUIDE = {
     " Save only durable, cross-session value (a preference, a decision with its rationale, an engineering constraint, " +
     "a pitfall with its root cause). Trivial single-turn work does not belong here, and when unsure, do not save."
 };
+
+/**
+ * #249 N3 的降级路径：宿主若不提供可挂钩的压缩前时机，双落点里的「注入」那一半就没
+ * 有触发者。此时不把功能算作失败，而是把规则交给 agent 自判压力（§4.4 点名的降级
+ * 形态）。落点是工具描述——常驻文本、不进每轮上下文，零注入成本。
+ *
+ * 英文单一正本，理由同 TOOL_GUIDE（见文件头）。字段名用存储与注入那一侧的口径
+ * （`current_work` / `next_step` / open question，#249 §6.2）；规格 §4.4 里的
+ * Current Work / Next Step / Critical Context 是**宿主压缩模板**的字段名，不是这里的。
+ */
+export const CONTINUITY_TOOL_RULE = {
+  memory_save:
+    " If this session's context is about to be compacted, first save a continuity note with this same tool " +
+    "(type: project, title: one stable title for this line of work, e.g. \"continuity: <topic>\"): current_work (what you " +
+    "are doing now), next_step, and any open question. Keep it to those fields, and reuse that same title for later " +
+    "updates: the store merges rows of the same type + title (the merge appends to the note instead of replacing it), " +
+    "so a fresh title each time just leaves a trail of near-duplicate project rows."
+};