@theseus-whale/dsh-continuity 0.0.0-stage → 4.12.2

package/src/mood.mjs

@@ -0,0 +1,133 @@
+/**
+ * mood 层：只负责“找出带情绪的句子”和“决定注入哪几条”，不做强度自评。
+ *
+ * 设计约束（来自外部意见 + 自锁审查）：
+ * 1. 不做模型自评强度：只记录“出现了哪些情绪词 + 原句”，强度不进来路不明的分数；
+ * 2. 调度用行为数据：最近没被注入过的优先（LRU），引用次数只用于“提升为判据层”，不回流权重；
+ * 3. 存储永不删：注入名额有限（≤2），记录只追加；
+ * 4. 冷却：同一条注入后 COOLDOWN_HOURS 内不再注入。
+ */
+
+/**
+ * 情绪词：**只收多字词与少数强信号单字**。
+ * 工程语料里的“压缩/累积/崩溃/困境/沉默”都会撞上单字，所以单字只留极少数。
+ */
+export const MARKER_GROUPS = {
+  agitation: ["烦死", "很烦", "太烦", "焦躁", "急躁", "烦躁", "受不了", "摆烂", "火大", "憋屈"],
+  fatigue: ["太累", "好累", "很累", "撑不住", "没劲", "疲惫", "困死了"],
+  heavy: ["难受", "低落", "沮丧", "心里堵", "闷得慌", "丧"],
+  fear: ["发怵", "慌", "不安", "害怕", "担心"],
+  bright: ["高兴", "开心", "舒服", "松了口气", "欣慰", "爽", "轻松"],
+  warmth: ["感动", "温暖", "暖", "温柔", "舍不得", "珍惜"],
+  anger: ["生气", "愤怒", "气死", "怒"],
+};
+
+const ALL_MARKERS = Object.values(MARKER_GROUPS).flat();
+
+/** 第一人称：有“我”的句子才算自己的状态，不是转述别人。 */
+const FIRST_PERSON = /(^|[^你他她])我|自己|心里|咱们/;
+
+/**
+ * 质量闸：只收“像自己状态”的句子。
+ *  - 命中 ≥2 个情绪标记；或
+ *  - 命中 1 个且句子含第一人称。
+ * 返回 false 的句子不进库（宁可漏，不制造干扰）。
+ */
+export function shouldRecord(hit) {
+  const markers = hit?.markers ?? [];
+  if (markers.length >= 2) return true;
+  if (markers.length === 1) return FIRST_PERSON.test(String(hit?.excerpt ?? ""));
+  return false;
+}
+
+const SENTENCE_SPLIT = /[。！？!?；;\n]/;
+/** 讨论 mood 机制本身的句子不算情绪（否则自指会刷屏）。 */
+const META_RE = /mood|情绪词|markers?|lexicon|心境|情绪改变|multi-char|singles?|technical|词表|命中率/i;
+
+/**
+ * 从一段文本（reasoning 或正文）里找情绪标记。
+ * 返回 { markers, groups, excerpt }；excerpt 取第一个命中所在句，≤80 字。
+ */
+export function extractMood(text) {
+  const src = String(text ?? "");
+  if (src.length === 0) return { markers: [], groups: [], excerpt: "" };
+  const sentences = src.split(SENTENCE_SPLIT).map((s) => s.trim()).filter(Boolean);
+  const markers = [];
+  const groups = new Set();
+  let excerpt = "";
+  for (const sentence of sentences) {
+    if (META_RE.test(sentence)) continue;
+    const hit = ALL_MARKERS.filter((m) => sentence.includes(m));
+    if (hit.length === 0) continue;
+    for (const m of hit) if (!markers.includes(m)) markers.push(m);
+    for (const [group, list] of Object.entries(MARKER_GROUPS)) {
+      if (list.some((m) => sentence.includes(m))) groups.add(group);
+    }
+    if (excerpt.length === 0) excerpt = sentence.slice(0, 80);
+  }
+  return { markers, groups: [...groups], excerpt };
+}
+
+/**
+ * 解析 mood 事件日志（JSONL）：
+ *   {"type":"mood","seq":123,"at":"...","markers":["烦"],"excerpt":"..."}
+ *   {"type":"injected","seq":123,"at":"..."}
+ *   {"type":"cited","seq":123,"at":"..."}
+ * 返回 [{ seq, at, excerpt, cited, lastInjectedAt }]
+ */
+export function parseMoodLog(lines) {
+  const entries = new Map();
+  for (const line of lines ?? []) {
+    if (!line || line.trim().length === 0) continue;
+    let row;
+    try { row = JSON.parse(line); } catch { continue; }
+    const seq = Number(row?.seq);
+    if (!Number.isInteger(seq)) continue;
+    if (row.type === "mood") {
+      const cur = entries.get(seq) ?? { seq, at: row.at, excerpt: row.excerpt ?? "", markers: row.markers ?? [], origin: row.origin ?? null, cited: false, lastInjectedAt: null };
+      entries.set(seq, cur);
+    } else if (row.type === "injected") {
+      const cur = entries.get(seq);
+      if (cur) cur.lastInjectedAt = row.at ?? null;
+    } else if (row.type === "cited") {
+      const cur = entries.get(seq);
+      if (cur) cur.cited = true;
+    }
+  }
+  return [...entries.values()];
+}
+
+/**
+ * 选出本次要注入的条目。
+ * 规则（全部可测，无自评）：
+ *  - 只选表达层（未被引用过）的条目；被引用过的条目已提升为“判据”，不再以“想起”的形式出现；
+ *  - 冷却：距上次注入 < COOLDOWN_HOURS 的不选；
+ *  - 过期：距上次被碰（创建/注入/引用）超过 MAX_AGE_DAYS 的，不再注入（记录保留）；
+ *  - 排序：从没注入过的优先，其次最久没注入的最先（LRU）；同序按时间早的优先。
+ */
+export function selectMood(entries, options = {}) {
+  const nowMs = options.nowMs ?? Date.now();
+  const quota = Number(options.quota ?? 2);
+  const cooldownHours = Number(options.cooldownHours ?? 6);
+  const maxAgeDays = Number(options.maxAgeDays ?? 7);
+  const hour = 3600 * 1000;
+  const day = 24 * hour;
+
+  const eligible = [];
+  for (const e of entries ?? []) {
+    if (e.cited) continue; // 已提升为判据，不走表达层注入
+    const created = Date.parse(e.at ?? "") || 0;
+    const injected = e.lastInjectedAt ? Date.parse(e.lastInjectedAt) || 0 : null;
+    const lastTouched = Math.max(created, injected ?? 0);
+    if (nowMs - lastTouched > maxAgeDays * day) continue; // 过期不再打扰
+    if (injected !== null && nowMs - injected < cooldownHours * hour) continue; // 冷却
+    eligible.push({ ...e, injected });
+  }
+  eligible.sort((a, b) => {
+    if (a.injected === null && b.injected !== null) return -1;
+    if (a.injected !== null && b.injected === null) return 1;
+    if (a.injected !== b.injected) return (a.injected ?? 0) - (b.injected ?? 0);
+    return (Date.parse(a.at ?? "") || 0) - (Date.parse(b.at ?? "") || 0);
+  });
+  return eligible.slice(0, Math.max(0, quota));
+}

package/src/peer-tool.mjs

@@ -0,0 +1,63 @@
+import { peerAgents, parsePeerPayload, peerMessage } from './peer.mjs';
+
+/**
+ * Preset-scoped peer reply tool. It is the agent-facing wrapper around the same
+ * exact-target lookup and `agent.followup` used by the loopback route. It never
+ * falls back to the active session and never appends a raw session event.
+ */
+export function createPeerTool({ agents = peerAgents } = {}) {
+  return {
+    name: 'peer_message',
+    description: [
+      'Send one user message to one live DSH session by exact session id.',
+      'Use it to reply to a peer or send a direct note; the target must already be live.',
+      'It returns queued/next-turn with the delivery id, not the target\'s reply.',
+    ].join(' '),
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['to', 'text'],
+      properties: {
+        to: {
+          type: 'string',
+          description: 'Exact live session id, e.g. session-<uuid>. Required; there is no active or newest fallback.',
+        },
+        text: {
+          type: 'string',
+          description: 'Message body. It is prefixed with [from] before delivery.',
+        },
+        from: {
+          type: 'string',
+          description: 'Optional display name used in the [from] prefix. Default: Continuity.',
+        },
+      },
+    },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: String(value ?? '') }],
+    },
+    timeoutMs: 30_000,
+    isConcurrencySafe: () => false,
+    async execute(args) {
+      const input = args !== null && typeof args === 'object' ? args : {};
+      const parsed = parsePeerPayload({
+        ...input,
+        from: typeof input.from === 'string' && input.from.trim().length > 0 ? input.from : 'Continuity',
+      });
+      if (!parsed.ok) throw new Error(`peer_message: ${parsed.error}`);
+      const target = agents.get(parsed.to);
+      if (target === null || typeof target.followup !== 'function') {
+        throw new Error(`peer_message: target-not-live (${parsed.to})`);
+      }
+      const message = peerMessage(parsed);
+      await target.followup(message);
+      return JSON.stringify({
+        ok: true,
+        to: parsed.to,
+        from: parsed.from,
+        queued: 'next-turn',
+        id: message.id,
+      });
+    },
+  };
+}

package/src/peer.mjs

@@ -0,0 +1,144 @@
+/**
+ * Target-addressed peer delivery on the Host's existing loopback web server.
+ *
+ * This is deliberately not the Coo pet bridge: that bridge owns one socket and
+ * routes to `agents.owner`, so switching the active session changes its target.
+ * Here `to` is a session id, lookup is exact, and a missing target is a refusal.
+ * Nothing in this module appends a session event directly; the only write path
+ * is the live agent's `followup`, which is validated by the Host.
+ */
+import { userMessage } from './threads.mjs';
+
+export const PEER_PATH = '/dsh-continuity/peer';
+export const PEER_BODY_LIMIT = 16 * 1024;
+export const PEER_TEXT_LIMIT = 8_000;
+export const PEER_FROM_LIMIT = 32;
+
+/** Live main agents, keyed by their session id. Subagents are never targets. */
+export class LiveAgents {
+  #byId = new Map();
+
+  add(id, agent) {
+    const key = typeof id === 'string' ? id.trim() : '';
+    if (key.length === 0 || key.length > 200) return false;
+    if (!agent || typeof agent !== 'object' || typeof agent.followup !== 'function') return false;
+    if (agent.session?.parent) return false;
+    this.#byId.set(key, agent);
+    return true;
+  }
+
+  remove(id) {
+    const key = typeof id === 'string' ? id.trim() : '';
+    if (key.length === 0) return;
+    this.#byId.delete(key);
+  }
+
+  get(id) {
+    return typeof id === 'string' ? this.#byId.get(id) ?? null : null;
+  }
+
+  get size() {
+    return this.#byId.size;
+  }
+}
+
+/** The one registry shared by the Host route and the continuity-preset tool. */
+export const peerAgents = new LiveAgents();
+
+/** Validate the JSON body. `to` is mandatory; there is intentionally no default. */
+export function parsePeerPayload(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return { ok: false, error: 'body-must-be-a-json-object' };
+  }
+  const to = typeof payload.to === 'string' ? payload.to.trim() : '';
+  if (to.length === 0) return { ok: false, error: 'to-required' };
+  if (to.length > 200 || !/^session-[A-Za-z0-9_-]+$/.test(to)) {
+    return { ok: false, error: 'to-must-be-a-session-id' };
+  }
+  const text = typeof payload.text === 'string' ? payload.text.trim() : '';
+  if (text.length === 0) return { ok: false, error: 'text-required' };
+  if (text.length > PEER_TEXT_LIMIT) return { ok: false, error: 'text-too-long' };
+  const rawFrom = typeof payload.from === 'string' ? payload.from : '';
+  const from = rawFrom.replace(/[\u0000-\u001f\u007f]/g, '').trim().slice(0, PEER_FROM_LIMIT) || '创';
+  return { ok: true, to, from, text };
+}
+
+/** A real user-role message with a fresh id and source.kind, not a raw append. */
+export function peerMessage({ from, text }) {
+  const message = userMessage(`[${from}] ${text}`);
+  message.source = { ...message.source, peer: true, peerFrom: String(from ?? '') };
+  return message;
+}
+
+function isLoopback(address) {
+  const value = typeof address === 'string' ? address : '';
+  return /^(?:::1|::ffff:127\.|127\.)/i.test(value);
+}
+
+function sendJson(res, status, payload) {
+  const text = JSON.stringify(payload);
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'content-length': Buffer.byteLength(text),
+  });
+  res.end(text);
+}
+
+/** HTTP handler shared by the Host route and the tests. */
+export async function handlePeerRequest(req, res, { agents, log = console } = {}) {
+  if (req.method !== 'POST') {
+    res.writeHead(405, { allow: 'POST' });
+    res.end();
+    return;
+  }
+  if (!isLoopback(req.socket?.remoteAddress)) {
+    sendJson(res, 403, { ok: false, error: 'loopback-only' });
+    return;
+  }
+  let raw = '';
+  try {
+    for await (const chunk of req) {
+      raw += chunk;
+      if (raw.length > PEER_BODY_LIMIT) {
+        sendJson(res, 413, { ok: false, error: 'body-too-large' });
+        return;
+      }
+    }
+  } catch {
+    sendJson(res, 400, { ok: false, error: 'body-read-failed' });
+    return;
+  }
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    sendJson(res, 400, { ok: false, error: 'invalid-json' });
+    return;
+  }
+  const parsed = parsePeerPayload(payload);
+  if (!parsed.ok) {
+    sendJson(res, 400, { ok: false, error: parsed.error });
+    return;
+  }
+  const target = agents?.get?.(parsed.to) ?? null;
+  if (target === null || typeof target.followup !== 'function') {
+    sendJson(res, 404, { ok: false, error: 'target-not-live', to: parsed.to });
+    return;
+  }
+  const message = peerMessage(parsed);
+  try {
+    await target.followup(message);
+  } catch (error) {
+    log?.warn?.(`[dsh-continuity] peer followup failed: ${error?.message ?? error}`);
+    sendJson(res, 502, { ok: false, error: 'followup-failed', message: String(error?.message ?? error) });
+    return;
+  }
+  sendJson(res, 200, {
+    ok: true,
+    to: parsed.to,
+    from: parsed.from,
+    queued: 'next-turn',
+    id: message.id,
+  });
+}

package/src/policy.mjs

@@ -0,0 +1,170 @@
+/**
+ * Pure band-controller policy. No DSH imports, no I/O, no side effects:
+ * the adapter and its tests both call these functions.
+ *
+ * The policy answers one question per turn: "how many tokens should this
+ * compaction pass remove?" It does not decide *what* to remove; the engine
+ * chooses the oldest balanced range (or a prune set) and does it.
+ */
+
+/**
+ * Cache-first band: one pass at the high water mark moves the oldest contiguous
+ * range toward `low`, so the number of prefix rewrites is minimised. The pass is
+ * bounded by `maxPerBatch` and by the protected tail; with a fixed baseline the
+ * effective floor can be above `low` (protect + baseline). `setpoint === high`
+ * is deliberate: the proportional band would otherwise add smaller passes
+ * between them, and every pass invalidates the provider's cached suffix. The
+ * default hard cap is 515k of the 1,048k window: high 60% W starts the drain,
+ * low 40% W is the target, and emergency 65% W is the 515k last-resort trigger.
+ * The high→emergency gap is 5% W (39,628), deliberately above minAction 24k.
+ *
+ * Measured on the 53-pass Continuity session: 698,108 tokens were removed in
+ * total; at this band a pass is ~158k, so the same history is ~5 passes, not 53.
+ */
+export const CACHE_FIRST_POLICY = Object.freeze({
+  /** `setpoint === high`: no proportional pass fires before the drain. */
+  setpoint: 0.60,
+  /** Above this fraction, start a pass whose budget targets `low` (upper bound). */
+  high: 0.60,
+  /** Target request when above `high`; effective floor is protect + baseline. */
+  low: 0.40,
+  /** Above this fraction, ignore `maxPerBatch` and drain to `emergencyTo`. */
+  emergency: 0.65,
+  /** Drain target; below `high` so one emergency does not chain into band-high. */
+  emergencyTo: 0.42,
+  /** Proportional gain (only used by the gradual variant). */
+  k: 0.4,
+  /** Hard cap on tokens folded in one pass: enough to drain high→low. */
+  maxPerBatch: 190000,
+  /** Do nothing below this many tokens: avoids rewriting the prefix for a sliver. */
+  minAction: 24000,
+  /** Never fold below this fraction of the window (recent verbatim tail). */
+  protect: 0.30,
+});
+
+/**
+ * Same water marks with a proportional zone between 50% and 60%. Smoother
+ * average context, but each proportional pass is another prefix invalidation;
+ * use only when cache hit rate is not the priority.
+ */
+export const CACHE_GRADUAL_POLICY = Object.freeze({
+  ...CACHE_FIRST_POLICY,
+  setpoint: 0.50,
+});
+
+/** The engine default. Kept as a named alias for existing callers/tests. */
+export const DEFAULT_POLICY = CACHE_FIRST_POLICY;
+
+const NAMES = Object.keys(DEFAULT_POLICY);
+
+/** Coerce partial config into a complete, validated policy. */
+export function resolvePolicy(overrides = {}) {
+  if (overrides == null || typeof overrides !== 'object' || Array.isArray(overrides)) {
+    throw new TypeError('policy must be an object');
+  }
+  const unknown = Object.keys(overrides).filter((key) => !NAMES.includes(key));
+  if (unknown.length) throw new TypeError(`unknown policy key: ${unknown.join(', ')}`);
+  const policy = { ...DEFAULT_POLICY };
+  for (const [key, value] of Object.entries(overrides)) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      throw new TypeError(`policy.${key} must be a finite number`);
+    }
+    if (value < 0) throw new TypeError(`policy.${key} must be >= 0`);
+    policy[key] = value;
+  }
+  for (const key of ['setpoint', 'high', 'low', 'emergency', 'emergencyTo', 'protect']) {
+    if (policy[key] > 1) throw new TypeError(`policy.${key} must be <= 1`);
+  }
+  if (!(policy.low < policy.high && policy.high <= policy.emergency && policy.emergency <= 1)) {
+    throw new TypeError('policy must satisfy low < high <= emergency <= 1');
+  }
+  if (!(policy.setpoint > policy.low && policy.setpoint <= policy.high)) {
+    throw new TypeError('policy must satisfy low < setpoint <= high');
+  }
+  if (policy.emergencyTo >= policy.emergency) {
+    throw new TypeError('policy.emergencyTo must be below policy.emergency');
+  }
+  if (policy.maxPerBatch <= 0) throw new TypeError('policy.maxPerBatch must be > 0');
+  if (policy.minAction < 0) throw new TypeError('policy.minAction must be >= 0');
+  return Object.freeze(policy);
+}
+
+/**
+ * Calibrate `protect` once, at the first band-high trigger, from the
+ * triggering request's pre-fold baseline. The value is frozen for the session;
+ * later drift is reported, never re-applied.
+ */
+export function calibrateProtect({
+  low,
+  windowTokens,
+  baselineTokens,
+  marginRatio = 0.01,
+  min = 0.10,
+  max = 0.20,
+} = {}) {
+  const values = [low, windowTokens, baselineTokens, marginRatio, min, max];
+  if (values.some((value) => !Number.isFinite(value)) || windowTokens <= 0) return null;
+  const marginTokens = marginRatio * windowTokens;
+  const raw = (low * windowTokens - baselineTokens - marginTokens) / windowTokens;
+  const protect = Math.min(max, Math.max(min, raw));
+  return {
+    protect,
+    raw,
+    marginTokens,
+    baselineTokens,
+    clamped: protect !== raw,
+  };
+}
+
+/**
+ * Plan one pass.
+ *
+ * @param {{ estTokens: number, windowTokens: number, policy?: object }} input
+ *   `estTokens` is the measured context occupancy; `windowTokens` is the
+ *   model's usable window after the output reserve.
+ * @returns {{ budget: number, reason: 'invalid'|'below-setpoint'|'deadband'|'setpoint'|'band-high'|'emergency'|'protected', target: number|null }}
+ */
+export function planFold({ estTokens, windowTokens, policy = DEFAULT_POLICY }) {
+  const p = policy;
+  if (!Number.isFinite(estTokens) || !Number.isFinite(windowTokens) || windowTokens <= 0) {
+    return { budget: 0, reason: 'invalid', target: null };
+  }
+  if (estTokens <= p.setpoint * windowTokens) {
+    return { budget: 0, reason: 'below-setpoint', target: p.setpoint * windowTokens };
+  }
+
+  let budget;
+  let reason;
+  let target;
+  if (estTokens > p.emergency * windowTokens) {
+    target = p.emergencyTo * windowTokens;
+    budget = estTokens - target;
+    reason = 'emergency';
+  } else if (estTokens > p.high * windowTokens) {
+    target = p.low * windowTokens;
+    budget = estTokens - target;
+    reason = 'band-high';
+  } else {
+    target = p.setpoint * windowTokens;
+    budget = p.k * (estTokens - target);
+    reason = 'setpoint';
+  }
+
+  // Never fold into the protected recent window.
+  const foldable = Math.max(0, estTokens - p.protect * windowTokens);
+  budget = Math.min(budget, foldable);
+  if (reason !== 'emergency') budget = Math.min(budget, p.maxPerBatch);
+
+  if (budget <= 0) return { budget: 0, reason: 'protected', target };
+  if (reason !== 'emergency' && budget < p.minAction) {
+    return { budget: 0, reason: 'deadband', target };
+  }
+  return { budget, reason, target };
+}
+
+/** True when the band is above its setpoint but the deadband is withholding action. */
+export function shouldWait({ estTokens, windowTokens, policy = DEFAULT_POLICY }) {
+  return planFold({ estTokens, windowTokens, policy }).reason === 'deadband';
+}
+
+export default DEFAULT_POLICY;

package/src/preflight.mjs

@@ -0,0 +1,113 @@
+/**
+ * save 预检（纯函数）：把“我每次 save 前要手查的几件事”合成一次计算。
+ *
+ * 输入：会话事件 + 轮标签行 + 要折叠的 seq 区间
+ * 输出：
+ *   turns            区间内出现过的轮
+ *   untaggedTurns    区间内没有轮标签的轮
+ *   tagCounts        每个标签覆盖多少条消息（用于判断“这一折是不是混了几件事”）
+ *   plan             按标签切分后的建议段（只有 >1 个标签时才有意义）
+ *   t0Candidates     区间内“没有标签且用户文本够长”的轮（新事物候选，最多 5 条）
+ */
+import { visibleText } from './t0.mjs';
+
+export function buildPreflight({ events = [], turnTagRows = [], fromSeq = 0, toSeq = 0, maxCandidates = 5 } = {}) {
+  // 没传区间时（save 不带 fromSeq/toSeq），不能把 toSeq 当 0 —— 那会把所有事件都过滤掉。
+  const effectiveTo = Number.isFinite(toSeq) && toSeq > 0 ? toSeq : Infinity;
+  const tagged = new Map();
+  for (const row of Array.isArray(turnTagRows) ? turnTagRows : []) {
+    const turn = Number(row?.turn);
+    if (Number.isInteger(turn)) tagged.set(turn, String(row?.tag ?? ''));
+  }
+
+  const turnSeqs = new Map();
+  const userText = new Map();
+  for (const event of Array.isArray(events) ? events : []) {
+    const seq = Number(event?.seq);
+    if (!Number.isInteger(seq) || seq < fromSeq || seq > effectiveTo) continue;
+    if (event?.type !== 'user/message' && event?.type !== 'assistant/message') continue;
+    const turn = Number(event?.data?.turn);
+    if (!Number.isInteger(turn)) continue;
+    const bucket = turnSeqs.get(turn) ?? [];
+    bucket.push(seq);
+    turnSeqs.set(turn, bucket);
+    if (event.type === 'user/message') {
+      const text = visibleText(event).replace(/\s+/g, ' ').trim();
+      if (text.length > 0) userText.set(turn, text);
+    }
+  }
+
+  const turns = [...turnSeqs.keys()].sort((a, b) => a - b);
+  const untaggedTurns = turns.filter((turn) => !tagged.has(turn) || tagged.get(turn) === '');
+
+  const tagCounts = new Map();
+  const planMap = new Map();
+  for (const turn of turns) {
+    const tag = tagged.get(turn) ?? '(无)';
+    const count = turnSeqs.get(turn).length;
+    tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + count);
+    const seqs = turnSeqs.get(turn);
+    const entry = planMap.get(tag) ?? { tag, from: Math.min(...seqs), to: Math.max(...seqs), count: 0, turns: 0 };
+    entry.from = Math.min(entry.from, ...seqs);
+    entry.to = Math.max(entry.to, ...seqs);
+    entry.count += count;
+    entry.turns += 1;
+    planMap.set(tag, entry);
+  }
+
+  const plan = [...planMap.values()].sort((a, b) => a.from - b.from);
+  const t0Candidates = turns
+    .filter((turn) => untaggedTurns.includes(turn) && (userText.get(turn) ?? '').length >= 20)
+    .slice(0, maxCandidates)
+    .map((turn) => ({ turn, seq: Math.min(...turnSeqs.get(turn)), head: (userText.get(turn) ?? '').slice(0, 60) }));
+
+  return {
+    turns: turns.length,
+    untaggedTurns,
+    tagCounts: Object.fromEntries([...tagCounts.entries()].sort((a, b) => b[1] - a[1])),
+    splitSuggested: tagCounts.size > 1,
+    plan,
+    t0Candidates,
+  };
+}
+
+/**
+ * 健康摘要（只读）：覆盖率 + 投影状态。
+ *
+ * 这两项以前要手跑 selfcheck；现在跟着 save 回执一起给出，失败才需动作。
+ */
+export function summarizeHealth({ events = [], threads = [], projection = null, now = Date.now() } = {}) {
+  const messageSeqs = [];
+  for (const event of Array.isArray(events) ? events : []) {
+    if (event?.type !== 'user/message' && event?.type !== 'assistant/message') continue;
+    const seq = Number(event?.seq);
+    if (Number.isInteger(seq)) messageSeqs.push(seq);
+  }
+  const ranges = [];
+  for (const thread of Array.isArray(threads) ? threads : []) {
+    for (const segment of thread?.segments ?? []) {
+      const from = Number(segment?.fromSeq);
+      const to = Number(segment?.toSeq);
+      if (Number.isInteger(from) && Number.isInteger(to)) ranges.push([from, to]);
+    }
+  }
+  let uncovered = 0;
+  for (const seq of messageSeqs) {
+    if (!ranges.some(([from, to]) => seq >= from && seq <= to)) uncovered += 1;
+  }
+  const coveragePct = messageSeqs.length === 0 ? 100 : Number(((messageSeqs.length - uncovered) / messageSeqs.length * 100).toFixed(2));
+
+  const ageMin = projection === null || typeof projection?.at !== 'string'
+    ? null
+    : Number(((now - Date.parse(projection.at)) / 60000).toFixed(1));
+
+  return {
+    coveragePct,
+    uncovered,
+    messages: messageSeqs.length,
+    projectionStage: projection?.stage ?? null,
+    projectionAgeMin: ageMin,
+    projected: Number(projection?.projected ?? 0),
+    skipped: projection?.skipped ?? {},
+  };
+}