@modusensus/dsh-mneme 0.8.4 → 0.8.6

package/src/store.js

@@ -18,6 +18,7 @@ CREATE TABLE IF NOT EXISTS memories (
   last_accessed_at  TEXT,
   _full_content     TEXT,
   evidence    TEXT,
+  doc_path    TEXT,
   created_at  TEXT NOT NULL,
   updated_at  TEXT NOT NULL
 );
@@ -47,7 +48,7 @@ CREATE TABLE IF NOT EXISTS dream_runs (
   summary_stored INTEGER NOT NULL DEFAULT 0,
   receipt        TEXT NOT NULL,
   policy_epoch   INTEGER NOT NULL DEFAULT 0,  -- 裁决规则版本：规则升级后旧裁决降级为历史证据
-  run_type       TEXT NOT NULL DEFAULT 'auto', -- auto | sleep：睡眠周期的审计区分
+  run_type       TEXT NOT NULL DEFAULT 'auto', -- auto | sleep | organize：周期审计的类别区分
   skipped        TEXT                     -- JSON: degraded 轮被跳过的逐条明细（index/action/ids/error）
 );
 CREATE INDEX IF NOT EXISTS idx_dream_runs_created ON dream_runs(created_at);
@@ -196,6 +197,14 @@ CREATE TABLE IF NOT EXISTS llm_audit_logs (
 CREATE INDEX IF NOT EXISTS idx_llm_audit_timestamp ON llm_audit_logs(timestamp);
 CREATE INDEX IF NOT EXISTS idx_llm_audit_source ON llm_audit_logs(trigger_source);
 
+-- autoSummarize 的增量蒸馏游标：按 session.id 持久化最近一次成功消费的事件序。
+-- 游标是蒸馏窗口的恢复事实，不与 user_settings 或记忆内容混用。
+CREATE TABLE IF NOT EXISTS distill_cursors (
+  session_id TEXT PRIMARY KEY,
+  last_seq   INTEGER NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
 -- entity gene (v0.3.0): named entities mentioned across memories, with
 -- time-boxed attributes (valid_from → valid_until) and typed relations.
 -- Attributes follow the snapshot style: saveAttr invalidates the previous
@@ -268,7 +277,10 @@ CREATE TABLE IF NOT EXISTS mirror_state (
 // Exported for API-layer type validation (standalone API POST /memories and
 // the /status byType breakdown); the set itself stays the single source of
 // truth for what store.save accepts.
-export const TYPES = new Set(["preference", "project", "decision", "history", "summary", "pattern", "rejected_solution", "pitfall", "constraint"]);
+export const TYPES = new Set(["preference", "project", "decision", "history", "summary", "pattern", "rejected_solution", "pitfall", "constraint",
+  // #230：agent 产长文档的指针行（摘要 + doc_path + evidence）。铸造口唯一
+  // （registerDocument）——saveWithDedupe/updateMemory 另有守卫拒绝旁路铸造。
+  "document"]);
 
 // Epistemic status: what kind of evidence a memory rests on. Defaults to
 // 'subjective' so legacy rows (and rows without any signal) stay compatible.
@@ -400,6 +412,7 @@ function toRow(row) {
     source: row.source ?? undefined,
     content_history: parseJsonArray(row.content_history),
     evidence: parseJsonArray(row.evidence),
+    doc_path: row.doc_path ?? undefined,
     quality_score: row.quality_score !== null && row.quality_score !== undefined ? Number(row.quality_score) : undefined,
     epistemic_status: row.epistemic_status ?? "subjective",
     agent_scope: row.agent_scope ?? undefined,
@@ -674,6 +687,8 @@ export function createStore(path) {
   // 叙述条证据链（#164 对齐）：[{memory_id, op, at}] JSON 数组——叙述/模式类
   // 记忆回链其支撑原子记忆，写入前与候选集求交防模型捏造。
   addColumn("memories", "evidence", "ALTER TABLE memories ADD COLUMN evidence TEXT");
+  // #230：document 指针行的文件定位。只有 registerDocument 写它，普通行恒 NULL。
+  addColumn("memories", "doc_path", "ALTER TABLE memories ADD COLUMN doc_path TEXT");
   addColumn("memories", "epistemic_status", "ALTER TABLE memories ADD COLUMN epistemic_status TEXT NOT NULL DEFAULT 'subjective'");
   addColumn("memories", "content_history", "ALTER TABLE memories ADD COLUMN content_history TEXT");
   addColumn("memories", "quality_score", "ALTER TABLE memories ADD COLUMN quality_score REAL");
@@ -782,6 +797,37 @@ export function createStore(path) {
     return ts;
   }
 
+  /** 返回指定会话持久化的 autoSummarize 游标；不存在时返回 undefined。 */
+  function getDistillCursor(sessionId) {
+    if (typeof sessionId !== "string" || sessionId.length === 0) return undefined;
+    const row = db.prepare(
+      "SELECT session_id, last_seq, updated_at FROM distill_cursors WHERE session_id = ?"
+    ).get(sessionId);
+    return row
+      ? { session_id: row.session_id, last_seq: Number(row.last_seq), updated_at: row.updated_at }
+      : undefined;
+  }
+
+  /**
+   * 单调持久化会话游标。调用方若同时写入记忆，必须放在外层 SQLite 事务内。
+   */
+  function setDistillCursor(sessionId, lastSeq) {
+    if (typeof sessionId !== "string" || sessionId.length === 0) {
+      throw new TypeError("setDistillCursor: sessionId must be a non-empty string");
+    }
+    if (!Number.isSafeInteger(lastSeq)) {
+      throw new TypeError("setDistillCursor: lastSeq must be a safe integer");
+    }
+    db.prepare(`
+      INSERT INTO distill_cursors (session_id, last_seq, updated_at)
+      VALUES (?, ?, ?)
+      ON CONFLICT(session_id) DO UPDATE SET
+        last_seq = MAX(distill_cursors.last_seq, excluded.last_seq),
+        updated_at = excluded.updated_at
+    `).run(sessionId, lastSeq, nowIso());
+    return getDistillCursor(sessionId);
+  }
+
   function count(type, { minImportance = null, source = null, includeForgotten = false, includeArchived = false, onlyArchived = false, depositedOnly = false, updatedFrom = null, updatedTo = null, occurredFrom = null, occurredTo = null, visibility = null } = {}) {
     const clauses = [];
     const params = [];
@@ -863,7 +909,28 @@ export function createStore(path) {
     return toRow(row);
   }
 
+  // #230 写入权分离（存储层唯一铸造口，CodeRabbit 复核最终形态）：document
+  // 行只能经 saveDocument 铸造，通用 save 整类拒绝。doc_path 是任意调用方
+  // 都能捏造的字符串——「必带 doc_path」挡不住绕过注册校验（flag 闸 / 文件
+  // 存在 / 路径归一化 / evidence 可见性 / scope 匹配 / supersede 探测）的直
+  // 铸，必须整类拒绝；受控通道是独立方法而不是隐藏旗标（旗标可被载荷携带，
+  // 方法名在 DI 合同里可审计）。
   function save(memory) {
+    if (memory?.type === "document") {
+      throw new Error("document rows are minted only via store.saveDocument (registerDocument)");
+    }
+    return insertMemoryRow(memory);
+  }
+
+  function saveDocument(memory) {
+    // 指针行结构不变量：doc_path 是 document 的存在依据（无指针 = 死行）。
+    if (!(typeof memory?.doc_path === "string" && memory.doc_path.trim())) {
+      throw new Error("document rows are pointer rows: doc_path is required");
+    }
+    return insertMemoryRow(memory);
+  }
+
+  function insertMemoryRow(memory) {
     const id = memory.id ?? randomUUID();
     const type = memory.type;
     if (!TYPES.has(type)) throw new Error(`invalid memory type: ${type}`);
@@ -874,6 +941,7 @@ export function createStore(path) {
     const tags = JSON.stringify(memory.tags ?? []);
     const importance = Number.isInteger(memory.importance) ? memory.importance : 3;
     const evidence = Array.isArray(memory.evidence) ? JSON.stringify(memory.evidence) : null;
+    const docPath = typeof memory.doc_path === "string" && memory.doc_path.trim() ? memory.doc_path : null;
     const embedding = Array.isArray(memory.embedding) && memory.embedding.length
       ? JSON.stringify(memory.embedding)
       : null;
@@ -884,8 +952,8 @@ export function createStore(path) {
       : inferEpistemicStatus(memory);
     runAtomically(() => {
       db.prepare(
-        `INSERT INTO memories (id, type, title, content, tags, importance, forgotten, archived, source, content_history, quality_score, embedding, epistemic_status, agent_scope, workspace_scope, agent_scope_source, workspace_scope_source, scope_decided_at, sensitivity, occurred_at, evidence, created_at, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+        `INSERT INTO memories (id, type, title, content, tags, importance, forgotten, archived, source, content_history, quality_score, embedding, epistemic_status, agent_scope, workspace_scope, agent_scope_source, workspace_scope_source, scope_decided_at, sensitivity, occurred_at, evidence, doc_path, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
       ).run(
         id,
         type,
@@ -907,6 +975,7 @@ export function createStore(path) {
         normalizeScopeText(memory.sensitivity),
         normalizeOccurredAt(memory.occurred_at),
         evidence,
+        docPath,
         now,
         now
       );
@@ -924,6 +993,12 @@ export function createStore(path) {
     if (!existing) throw new Error(`memory not found: ${id}`);
     const type = patch.type ?? existing.type;
     if (!TYPES.has(type)) throw new Error(`invalid memory type: ${type}`);
+    // #230：type 不许改入/改出 document——铸造与退役都只经 registerDocument
+    // （摘要修复走同 type 的 content/title 更新，doc_path 不在本 UPDATE 的
+    // SET 里，天然保持不变）。
+    if ((existing.type === "document") !== (type === "document")) {
+      throw new Error("memory type cannot be changed to or from 'document' (registerDocument is the only mint path)");
+    }
     if (patch.tags !== undefined && !Array.isArray(patch.tags)) {
       throw new Error("tags must be an array");
     }
@@ -1015,6 +1090,11 @@ export function createStore(path) {
     if (!existing) throw new Error(`memory not found: ${id}`);
     const type = patch.type ?? existing.type;
     if (!TYPES.has(type)) throw new Error(`invalid memory type: ${type}`);
+    // 同 update：document 类型转换在这里同样封死（CAS 路径绕过 updateMemory
+    // 的 service 守卫，必须在存储层兜住）。
+    if ((existing.type === "document") !== (type === "document")) {
+      throw new Error("memory type cannot be changed to or from 'document' (registerDocument is the only mint path)");
+    }
     if (patch.tags !== undefined && !Array.isArray(patch.tags)) {
       throw new Error("tags must be an array");
     }
@@ -1135,11 +1215,15 @@ export function createStore(path) {
   // Live memories that have not been touched since `cutMs` (never-touched ones
   // fall back to created_at). Ordered by last access ascending — the coldest
   // first. Used by sleep phase 2 to pick archival-demotion candidates.
+  // #230: document pointer rows are excluded — they are heat-immune by design
+  // (λ=0) and their "unread" state is normal (full text lives outside the DB),
+  // so the cold scan must never demote/archive them for lacking access.
   function getUnrecalledSince(cutMs, { limit = 500 } = {}) {
     const cutIso = new Date(cutMs).toISOString();
     const rows = db.prepare(
       `SELECT * FROM memories
        WHERE forgotten = 0 AND archived = 0
+         AND type <> 'document'
          AND (last_accessed_at IS NULL OR last_accessed_at < ?)
        ORDER BY COALESCE(last_accessed_at, created_at) ASC, id
        LIMIT ?`
@@ -1147,13 +1231,20 @@ export function createStore(path) {
     return rows.map(toRow);
   }
 
-  function list({ type, limit = 50, offset = 0, order = "importance", includeForgotten = false, includeArchived = false, onlyArchived = false, depositedOnly = false, minImportance = null, source = null, updatedFrom = null, updatedTo = null, occurredFrom = null, occurredTo = null, visibility = null } = {}) {
+  function list({ type, excludeTypes = null, limit = 50, offset = 0, order = "importance", includeForgotten = false, includeArchived = false, onlyArchived = false, depositedOnly = false, minImportance = null, source = null, updatedFrom = null, updatedTo = null, occurredFrom = null, occurredTo = null, visibility = null } = {}) {
     const clauses = [];
     const params = [];
     if (type) {
       clauses.push("type = ?");
       params.push(type);
     }
+    // #230：整类排除必须在 LIMIT 之前做——sleep 的模式扫描池（limit 200 +
+    // sleepPatternMinMemories 门槛）若先截断后过滤，document 行一多就会把
+    // 普通记忆挤出窗口，池子被饿空。
+    if (Array.isArray(excludeTypes) && excludeTypes.length) {
+      clauses.push(`type NOT IN (${excludeTypes.map(() => "?").join(", ")})`);
+      params.push(...excludeTypes);
+    }
     // Optional server-side filters: importance floor and exact source match.
     // Both stay out of the query when unset so existing callers are unaffected.
     if (minImportance != null) {
@@ -1227,15 +1318,20 @@ export function createStore(path) {
         "(id IN (SELECT record_id FROM receipt_chain WHERE kind IN ('merge', 'update') AND verdict = 'live') OR source = 'dream')"
       );
     }
+    // limit == null = 无界（#230 注册器的精确 supersede 全量扫描用——同路径/
+    // 同标题判定不允许窗口截断）。其余调用传数字，走 sanitizePage 默认档。
+    const unbounded = limit == null;
     const { limit: lim, offset: off } = sanitizePage(limit, offset, 50);
     const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
     // "chrono" is pure newest-first — the stable order paged browsing (month
     // tree, infinite scroll) needs; importance ordering would interleave
     // months across pages.
     const orderBy = order === "chrono" ? "updated_at DESC, id DESC" : "importance DESC, updated_at DESC, id";
-    const rows = db.prepare(
-      `SELECT * FROM memories ${where} ORDER BY ${orderBy} LIMIT ? OFFSET ?`
-    ).all(...params, lim, off);
+    const rows = unbounded
+      ? db.prepare(`SELECT * FROM memories ${where} ORDER BY ${orderBy}`).all(...params)
+      : db.prepare(
+          `SELECT * FROM memories ${where} ORDER BY ${orderBy} LIMIT ? OFFSET ?`
+        ).all(...params, lim, off);
     return rows.map(toRow);
   }
 
@@ -1436,6 +1532,22 @@ export function createStore(path) {
     return rows.map(toDreamRun);
   }
 
+  // Issue #89：上次实际开跑时刻（epoch ms），从审计表恢复——调度器的 lastRunAt
+  // 只活在内存里，进程重启即归零，闸门对新实例放行 → 重启后立刻连发。审计表
+  // 本来就逐 run 落库（failed/degraded 也算 run），直接读它就是事实源，零迁移。
+  function lastDreamRunAt(runType = null) {
+    const row = runType
+      ? db.prepare(
+          "SELECT created_at FROM dream_runs WHERE run_type = ? ORDER BY created_at DESC, id LIMIT 1"
+        ).get(runType)
+      : db.prepare(
+          "SELECT created_at FROM dream_runs ORDER BY created_at DESC, id LIMIT 1"
+        ).get();
+    if (!row?.created_at) return 0;
+    const ms = Date.parse(row.created_at);
+    return Number.isFinite(ms) ? ms : 0;
+  }
+
   /**
    * Latest ruling-rule version seen on the audit trail. policy_epoch is a config
    * value stamped onto each run by the caller; reading the newest row's epoch
@@ -2368,6 +2480,9 @@ export function createStore(path) {
     count,
     getById,
     save,
+    // document 唯一铸造口（#230 写入权分离）：registerDocument 专用，通用
+    // save/update/CAS 均拒绝 document 创建或类型转换。
+    saveDocument,
     update,
     compareAndUpdate,
     remove,
@@ -2387,6 +2502,7 @@ export function createStore(path) {
     needsEmbedding,
     searchVector,
     saveDreamRun,
+    lastDreamRunAt,
     getDreamRun,
     listDreamRuns,
     getLatestPolicyEpoch,
@@ -2401,6 +2517,8 @@ export function createStore(path) {
     getRecallEval,
     listRecallEvals,
     saveLlmAudit,
+    getDistillCursor,
+    setDistillCursor,
     listLlmAudits,
     countLlmAudits,
     getLlmAuditStats,

package/src/summarize.js

@@ -256,13 +256,136 @@ function enqueueDistill(task, intervalMs = 0) {
   return run;
 }
 
-export function createSummarizer(ctx, service, config) {
+// Issue #239（第 4 项，错峰队列）：高峰时段解析与判定。纯函数、可单测——排程判断
+// 不绑死真实时钟，测试才能确定性地覆盖跨零点、多段、星期过滤与非法写法。
+// spec 语法：`[<星期> ]<时段>[,<时段>...]`，星期前缀可省（省 = 每天）：
+//   "09:00-18:00"                        每天 09:00-18:00
+//   "mon-fri 08:00-12:00,14:00-18:00"    工作日两段（ISO 1=周一…7=周日，也认 mon..sun）
+//   "sat,sun 23:00-06:00"                周末跨零点段
+// 时间取宿主本地时区。任一写法非法 → 整串视为未配置（返回 null）：排程是省钱手段，
+// 绝不该因为写错格式把蒸馏停掉。
+const DAY_NAMES = { mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6, sun: 7 };
+
+function parseDayToken(token) {
+  const days = new Set();
+  const normalize = (value) => (/^\d$/.test(value) ? Number(value) : DAY_NAMES[value] ?? null);
+  for (const piece of token.split(",")) {
+    const matched = /^([a-z]{3}|\d)(?:-([a-z]{3}|\d))?$/.exec(piece.trim().toLowerCase());
+    if (!matched) return null;
+    const from = normalize(matched[1]);
+    const to = matched[2] === undefined ? from : normalize(matched[2]);
+    if (from === null || to === null || from < 1 || from > 7 || to < 1 || to > 7) return null;
+    // 支持跨周环绕（fri-mon）：从 from 起逐天推进到 to，最多绕一圈。
+    for (let day = from; ; day = (day % 7) + 1) {
+      days.add(day);
+      if (day === to) break;
+    }
+  }
+  return days.size > 0 ? [...days].sort((a, b) => a - b) : null;
+}
+
+/** JS 的 getDay() 是 0=周日…6=周六；这里统一成 ISO（1=周一…7=周日）。 */
+function isoDay(date) {
+  const day = date.getDay();
+  return day === 0 ? 7 : day;
+}
+
+export function parsePeakSpec(spec) {
+  if (typeof spec !== "string" || spec.trim() === "") return null;
+  let rest = spec.trim();
+  let days = null;
+  // 星期前缀 = 第一个空白之前的部分，但**头段含冒号就不是前缀**（那是时段本身，
+  // 例如 "09:00-12:00, 14:00-18:00" 里的逗号空格）。前缀解析失败一律按未配置处理，
+  // 不做猜测——宁可不省，也不能误停。
+  const sep = rest.search(/\s/);
+  if (sep > 0) {
+    const head = rest.slice(0, sep);
+    if (!head.includes(":")) {
+      days = parseDayToken(head);
+      if (days === null) return null;
+      rest = rest.slice(sep).trim();
+    }
+  }
+  const windows = [];
+  for (const part of rest.split(",")) {
+    const matched = /^\s*(\d{1,2}):(\d{2})\s*-\s*(\d{1,2}):(\d{2})\s*$/.exec(part);
+    if (!matched) return null;
+    const [sh, sm, eh, em] = [Number(matched[1]), Number(matched[2]), Number(matched[3]), Number(matched[4])];
+    if (sh > 23 || eh > 23 || sm > 59 || em > 59) return null;
+    const start = sh * 60 + sm;
+    const end = eh * 60 + em;
+    if (start === end) return null;
+    windows.push({ start, end });
+  }
+  return windows.length > 0 ? { days, windows } : null;
+}
+
+/**
+ * 该时刻是否落在高峰内。跨零点段（start > end）按「窗口所属的那一天」认星期：
+ * `mon-fri 23:00-06:00` 的周六 02:00 属于周五开的那个窗口，仍算高峰。
+ */
+export function isInPeakWindow(date, spec) {
+  const parsed = parsePeakSpec(spec);
+  if (!parsed) return false;
+  const minutes = date.getHours() * 60 + date.getMinutes();
+  const today = isoDay(date);
+  const yesterday = today === 1 ? 7 : today - 1;
+  const allowed = (day) => !parsed.days || parsed.days.includes(day);
+  return parsed.windows.some(({ start, end }) => {
+    if (start < end) return minutes >= start && minutes < end && allowed(today);
+    return (minutes >= start && allowed(today)) || (minutes < end && allowed(yesterday));
+  });
+}
+
+/**
+ * 高峰内则返回「距当前最近的一个高峰结束时刻」（择时补跑用），否则 null。
+ * 落在多个时段重叠处时取最早结束的那个——早跑不亏，晚跑才亏。
+ */
+export function nextOffPeakAt(date, spec) {
+  const parsed = parsePeakSpec(spec);
+  if (!parsed) return null;
+  const minutes = date.getHours() * 60 + date.getMinutes();
+  const today = isoDay(date);
+  const yesterday = today === 1 ? 7 : today - 1;
+  const allowed = (day) => !parsed.days || parsed.days.includes(day);
+  let bestDelta = null;
+  const consider = (delta) => {
+    if (bestDelta === null || delta < bestDelta) bestDelta = delta;
+  };
+  for (const { start, end } of parsed.windows) {
+    if (start < end) {
+      if (minutes >= start && minutes < end && allowed(today)) consider(end - minutes);
+      continue;
+    }
+    if (minutes >= start && allowed(today)) consider((1440 - minutes) + end);
+    else if (minutes < end && allowed(yesterday)) consider(end - minutes);
+  }
+  if (bestDelta === null) return null;
+  const at = new Date(date.getTime());
+  at.setSeconds(0, 0);
+  at.setMinutes(at.getMinutes() + bestDelta);
+  return at;
+}
+
+export function createSummarizer(ctx, service, config, deps = {}) {
   if (!config.autoSummarize) return { dispose: () => {} };
 
+  // Issue #239（第 4 项）：时钟与定时器可注入——排程不绑死真实时钟，测试才能确定性
+  // 覆盖「高峰顺延 → 非高峰补跑」。房型同 dream/sleep.js 的注入参数。
+  const now = typeof deps.now === "function" ? deps.now : () => Date.now();
+  const setTimer = typeof deps.setTimeoutFn === "function" ? deps.setTimeoutFn : setTimeout;
+  const clearTimer = typeof deps.clearTimeoutFn === "function" ? deps.clearTimeoutFn : clearTimeout;
+
   const inFlight = new Map();
   // Issue #127：per-session 上一次实际开跑时刻（最小间隔闸门用）。与 inFlight
   // 同生命周期，dispose 时一并清空。
   const lastRunAt = new Map();
+  // Issue #239：per-session 已发起的蒸馏次数（有界检查点用）。只在实际发起 LLM
+  // 调用时自增，因此被零 LLM 预判挡下的窗口不消耗预算。
+  const runsUsed = new Map();
+  // Issue #239（第 4 项）：每会话最多挂一个待补跑定时器（错峰队列用）；dispose 时
+  // 一并清理，避免插件卸载后还留着一个会调模型的定时器。
+  const deferredRuns = new Map();
   // Issue #210：只在一次蒸馏完整成功后记录已消费的最后事件 seq。
   const lastDistilledSeq = new Map();
   let disposed = false;
@@ -282,7 +405,52 @@ export function createSummarizer(ctx, service, config) {
     }
   }
 
-  async function summarize(session, triggerEvent) {
+  function persistCursor(sessionId, nextSeq) {
+    if (!Number.isFinite(nextSeq)) return;
+    if (typeof service.setDistillCursor !== "function") {
+      // 第三方宿主拿旧版 service 构造时没有持久化游标能力：降级为内存游标
+      // （#274 之前的行为），本进程内不重复蒸馏，重启后窗口重放由
+      // saveWithDedupe 三元组兜底。方法存在但抛错仍向上传播——那是
+      // 「写失败须回滚」的恰一次语义，不能吞（见 summarize.test.js 回滚用例）。
+      ctx.logger?.warn?.("dsh-mneme: service.setDistillCursor unavailable, distill cursor falls back to in-memory");
+      return;
+    }
+    service.setDistillCursor(sessionId, nextSeq);
+  }
+
+  function commitCursor(sessionId, nextSeq) {
+    persistCursor(sessionId, nextSeq);
+    if (Number.isFinite(nextSeq)) lastDistilledSeq.set(sessionId, nextSeq);
+  }
+
+  /**
+   * Issue #239（第 4 项）：把这一轮蒸馏推迟到最近的「高峰结束」时刻。每会话只挂
+   * 一个定时器（重复触发不叠加）；被 summarizePeakMaxDeferMinutes 截断时到点照跑
+   * （bypassPeak），长高峰不会把蒸馏饿死。定时器 unref——不阻止宿主退出。
+   */
+  function scheduleDeferredRun(session) {
+    if (disposed || deferredRuns.has(session.id)) return;
+    const at = nextOffPeakAt(new Date(now()), config.summarizePeakHours ?? "");
+    if (!at) return;
+    const maxDeferMs = (config.summarizePeakMaxDeferMinutes ?? 0) * 60000;
+    let delay = Math.max(0, at.getTime() - now());
+    const capped = maxDeferMs > 0 && delay > maxDeferMs;
+    if (capped) delay = maxDeferMs;
+    const timer = setTimer(() => {
+      deferredRuns.delete(session.id);
+      if (disposed) return;
+      // 不传触发事件：补跑要蒸的是「累积后的整窗」（从上次成功游标到最新事件），
+      // 拿老 triggerEvent 反而会把窗口卡在它那个 seq 上。
+      summarize(session, undefined, { bypassPeak: capped }).catch((error) => {
+        if (disposed || error?.name === "AbortError") return;
+        ctx.logger?.warn?.(`dsh-mneme: deferred summarization failed: ${String(error)}`);
+      });
+    }, delay);
+    timer?.unref?.();
+    deferredRuns.set(session.id, timer);
+  }
+
+  async function summarize(session, triggerEvent, opts = {}) {
     if (disposed || inFlight.has(session.id)) return;
 
     const header = session.requestHeader?.()?.config;
@@ -308,6 +476,37 @@ export function createSummarizer(ctx, service, config) {
       });
       return;
     }
+    // Issue #239（有界检查点）：每会话 run 预算。放在间隔门之后，两者都命中时
+    // 先报间隔——间隔是「刚刚跑过」，预算是「额度用尽」，前者信息量更大。skip
+    // 仍写审计（沿用间隔门的 error_message 口径），否则「为什么不再蒸馏了」对
+    // 用户不可观测。prevRuns 在这里捕获、finally 里按 aborted 回滚（同 lastRunAt）。
+    // 游标刻意不消费：预算是「这个会话先不再蒸馏了」，把窗口留在原地，日后调高
+    // 额度（或宿主重启）仍能蒸馏到它；这与 window-too-small 主动消费游标相反——
+    // 后者是「这些事件不值得蒸馏」，留着只会每个 turn/end 重评一次。
+    // Issue #239（第 4 项，错峰队列）：高峰期不调模型——只登记一行 skip 审计并择时
+    // 补跑。游标刻意不消费：窗口继续累积，留到非高峰一次性蒸馏（批量比逐轮碎蒸更
+    // 省）。被 maxDefer 截断后到点仍处高峰时，由 opts.bypassPeak 放行。
+    if (!opts.bypassPeak && isInPeakWindow(new Date(now()), config.summarizePeakHours ?? "")) {
+      writeAudit({
+        timestamp: new Date(now()).toISOString(),
+        model_id: route ? `${route.provider}:${route.model}` : "unknown",
+        status: "skipped",
+        error_message: "peak-hours"
+      });
+      scheduleDeferredRun(session);
+      return;
+    }
+    const prevRuns = runsUsed.get(session.id);
+    const maxRuns = config.summarizeMaxRunsPerSession ?? 0;
+    if (maxRuns > 0 && (prevRuns ?? 0) >= maxRuns) {
+      writeAudit({
+        timestamp: new Date().toISOString(),
+        model_id: route ? `${route.provider}:${route.model}` : "unknown",
+        status: "skipped",
+        error_message: "max-runs-per-session"
+      });
+      return;
+    }
     const controller = new AbortController();
     inFlight.set(session.id, controller);
     // audit state for the compression call. null = no audit for this run
@@ -319,7 +518,10 @@ export function createSummarizer(ctx, service, config) {
     let abortedRun = false;
     try {
       if (!route) return;
-      const previousSeq = lastDistilledSeq.get(session.id);
+      const persistedCursor = typeof service.getDistillCursor === "function"
+        ? service.getDistillCursor(session.id)
+        : undefined;
+      const previousSeq = persistedCursor?.last_seq ?? lastDistilledSeq.get(session.id);
       const triggerSeq = eventSeq(triggerEvent);
       // 只读取上次成功游标之后、当前 turn/end 之前的事件。旧版 snapshotEvents
       // 即使忽略范围参数，collectMessages 仍会按事件 seq 二次过滤。
@@ -338,13 +540,37 @@ export function createSummarizer(ctx, service, config) {
       if (!collected.messages.length) {
         // 没有可蒸馏的公开文本也算成功消费当前事件窗口，避免每个 turn/end
         // 都重新扫描同一批无内容事件；没有 seq 时则不提交不可验证的游标。
-        if (Number.isFinite(nextSeq)) lastDistilledSeq.set(session.id, nextSeq);
+        commitCursor(session.id, nextSeq);
         return;
       }
       const messages = collected.messages;
-      // 只有真正准备发起一次 LLM 蒸馏时才占用最小间隔；失败路径仍按原语义
-      // 占用，aborted 则由 finally 回滚。
+      // Issue #239（成本感知级联第一级）：零 LLM 预判。窗口内可蒸馏文本不足阈值
+      // 时直接跳过——短窗口交给模型的产出多是泛泛而谈，代价却是一次完整调用。
+      // 判定纯规则（字符数），无模型参与；被挡下的窗口照常消费游标，否则每个
+      // turn/end 都会重新评估同一段短文本。skip 原因进审计，作为后续按真实负载
+      // 决定下一级规则的依据。
+      const minWindowChars = config.summarizeMinWindowChars ?? 0;
+      if (minWindowChars > 0) {
+        const distillChars = messages.reduce(
+          (total, message) => total + (Array.isArray(message.content) ? message.content : [])
+            .reduce((n, part) => n + (typeof part?.text === "string" ? part.text.length : 0), 0),
+          0
+        );
+        if (distillChars < minWindowChars) {
+          commitCursor(session.id, nextSeq);
+          writeAudit({
+            timestamp: new Date().toISOString(),
+            model_id: route ? `${route.provider}:${route.model}` : "unknown",
+            status: "skipped",
+            error_message: "window-too-small"
+          });
+          return;
+        }
+      }
+      // 只有真正准备发起一次 LLM 蒸馏时才占用最小间隔与 run 预算；失败路径仍按
+      // 原语义占用（调用确实发生过），aborted 则由 finally 回滚。
       lastRunAt.set(session.id, Date.now());
+      runsUsed.set(session.id, (prevRuns ?? 0) + 1);
 
       if (config?.llmAudit?.enabled !== false && typeof service.saveLlmAudit === "function") {
         audit = {
@@ -385,8 +611,11 @@ export function createSummarizer(ctx, service, config) {
                 text += chunk.text ?? chunk.delta ?? "";
               }
               if (chunk.type === "usage" && audit) {
-                const i = chunk.input_tokens ?? chunk.inputTokens ?? chunk.prompt_tokens ?? chunk.promptTokens;
-                const o = chunk.output_tokens ?? chunk.outputTokens ?? chunk.completion_tokens ?? chunk.completionTokens;
+                // 同 dream.js：真实协议是 {type:"usage", usage:TokenUsage}，用量不在
+                // chunk 顶层；顶层读取只作为把用量平铺的替身兜底。
+                const usage = chunk.usage ?? chunk;
+                const i = usage.input_tokens ?? usage.inputTokens ?? usage.prompt_tokens ?? usage.promptTokens;
+                const o = usage.output_tokens ?? usage.outputTokens ?? usage.completion_tokens ?? usage.completionTokens;
                 if (Number.isFinite(i)) audit.inputTokens = i;
                 if (Number.isFinite(o)) audit.outputTokens = o;
               }
@@ -504,7 +733,11 @@ export function createSummarizer(ctx, service, config) {
               ...(dup ? { _mergeInto: dup.memory.id } : {})
             });
           }
+          persistCursor(session.id, nextSeq);
         });
+      } else {
+        // 空数组是合法成功：没有记忆写入，但本次事件窗口仍然应被持久消费。
+        persistCursor(session.id, nextSeq);
       }
       if (audit && (capped > 0 || deduped > 0)) {
         audit.metadata = {
@@ -516,12 +749,22 @@ export function createSummarizer(ctx, service, config) {
       // 记忆写入和解析都成功后才提交窗口；流失败、中止、解析失败或写入异常
       // 都会在此之前退出，从而保留窗口供下一次重试。
       if (Number.isFinite(nextSeq)) lastDistilledSeq.set(session.id, nextSeq);
+    } catch (error) {
+      if (audit) {
+        audit.status = "error";
+        audit.errorMessage = String(error?.message ?? error);
+      }
+      throw error;
     } finally {
       // Issue #127：aborted（会话关闭 / 插件 dispose）不占间隔，避免误伤该会话的
       // 下一次蒸馏；其余情况（含失败）的打点保留，与 dreamMinIntervalMinutes 一致。
       if (abortedRun || controller.signal.aborted) {
         if (prevClaim === undefined) lastRunAt.delete(session.id);
         else lastRunAt.set(session.id, prevClaim);
+        // Issue #239：aborted 同样不占 run 预算——调用没有真正发生，占了会误伤
+        // 该会话后续的蒸馏（与上面的间隔回滚同一口径）。
+        if (prevRuns === undefined) runsUsed.delete(session.id);
+        else runsUsed.set(session.id, prevRuns);
       }
       if (audit) {
         try {
@@ -566,6 +809,8 @@ export function createSummarizer(ctx, service, config) {
       if (disposed) return;
       disposed = true;
       unsubscribe?.();
+      for (const timer of deferredRuns.values()) clearTimer(timer);
+      deferredRuns.clear();
       for (const controller of inFlight.values()) controller.abort();
       inFlight.clear();
       lastRunAt.clear();