dsh-compact-relay 0.5.0 → 0.5.2

package/lib/core/clip.js

@@ -0,0 +1,92 @@
+/**
+ * 文本截断的两个共享口径（0.5.1 D03）—— 消掉散在 6 处的「切一刀加省略号」。
+ *
+ * 为什么只有两个函数：评审把现有截断按**单位**归成三类 ——
+ *   1. UTF-16 码元（`String.prototype.slice`）：0.4/0.5 的既有实现，逐字节兼容用；
+ *   2. 码点（`Array.from`）：0.6 新写的两份逻辑相同「不切坏 emoji」，收在这里；
+ *   3. UTF-8 字节：那是宿主 `session-title` 的 `maxTitleBytes` 契约克隆
+ *      （`core/relay.js:truncateTitleUtf8`），语义是"按宿主预算缩标题"，**不是**
+ *      展示层截断，按评审结论不并进来（0.5.2 S3 再迁 `dsh/title-budget.js`）。
+ *
+ * 省略号预算必须显式，因为现网有两种既有输出：
+ *   - 'inside'（默认）：省略号算进上限，结果长度 ≤ max —— 旧 `slice(0, max-1) + '…'`；
+ *   - 'append'：省略号额外多 1 字符 —— `dsh/compaction-log` 的预览既有输出（201 字符
+ *     上限），`previewTruncated` 依赖它，合并时**必须保留**；
+ *   - false：不补省略号。
+ *
+ * 纯函数、零依赖（可被 client bundle 内联）。非字符串一律返回 ''（调用方本来都先做
+ * 了 typeof 判断，这里只是兜底不抛错）；max 非法（undefined/NaN）时原样返回 —— 不猜预算。
+ */
+
+/** 省略号：与本项目其它文案一致，用单个 U+2026（不是三个点）。 */
+const ELLIPSIS = '…';
+
+/**
+ * 归一化上限：非法 → null（调用方原样返回）；小数向下取整；负数按 0 处理。
+ * @param {unknown} max
+ * @returns {number|null}
+ */
+function limitOf(max) {
+  if (typeof max !== 'number' || !Number.isFinite(max)) return null;
+  return Math.max(0, Math.trunc(max));
+}
+
+/**
+ * 按预算切一段 + 省略号（长度/切片方式由调用方给：码点数组或码元字符串）。
+ * @param {string} text 原文本
+ * @param {number} limit 归一化后的上限
+ * @param {'inside'|'append'|false} ellipsis 省略号预算
+ * @param {(text:string)=>number} lengthOf 按目标单位算长度
+ * @param {(text:string, count:number)=>string} slice 按目标单位取前缀
+ * @returns {string}
+ */
+function cut(text, limit, ellipsis, lengthOf, slice) {
+  const length = lengthOf(text);
+  if (length <= limit) return text;
+  if (ellipsis === 'append') return `${slice(text, limit)}${ELLIPSIS}`;
+  if (ellipsis === false) return slice(text, limit);
+  // 'inside'（默认）：省略号占一个单位；limit=0 时只剩省略号（与旧实现一致）。
+  return `${slice(text, Math.max(0, limit - 1))}${ELLIPSIS}`;
+}
+
+/**
+ * 按**码点**截断（emoji / 代理对不会被切半）。展示层优先用它。
+ * @param {string} text
+ * @param {number} max 上限（按码点计）
+ * @param {{ellipsis?:'inside'|'append'|false}} [options]
+ * @returns {string}
+ */
+export function clipChars(text, max, { ellipsis = 'inside' } = {}) {
+  if (typeof text !== 'string') return '';
+  const limit = limitOf(max);
+  if (limit === null || text.length === 0) return text;
+  const charsOf = (value) => Array.from(value);
+  return cut(
+    text,
+    limit,
+    ellipsis,
+    (value) => charsOf(value).length,
+    (value, count) => charsOf(value).slice(0, count).join(''),
+  );
+}
+
+/**
+ * 按**UTF-16 码元**截断（`String.prototype.slice`，0.4/0.5 的既有行为逐字节兼容）。
+ * 注意：代理对（emoji）可能被切在中间 —— 需要「不切半」时用 clipChars。
+ * @param {string} text
+ * @param {number} max 上限（按码元计，即 `String.length`）
+ * @param {{ellipsis?:'inside'|'append'|false}} [options]
+ * @returns {string}
+ */
+export function clipCodeUnits(text, max, { ellipsis = 'inside' } = {}) {
+  if (typeof text !== 'string') return '';
+  const limit = limitOf(max);
+  if (limit === null || text.length === 0) return text;
+  return cut(
+    text,
+    limit,
+    ellipsis,
+    (value) => value.length,
+    (value, count) => value.slice(0, count),
+  );
+}

package/lib/core/config-schema.js

@@ -62,8 +62,8 @@ export const CONFIG_FIELDS = Object.freeze([
   field(['thresholds', 'maxSummaries'], { label: '摘要份数上限', kind: 'positiveInt', default: 6, editable: true, view: true }),
   field(['contextWindowFallback'], { label: '兜底窗口', kind: 'positiveInt', default: 1_000_000 }),
   field(['retention', 'recentTailTokens'], { label: '保留近期原文', kind: 'nonNegativeInt', default: 40_000, editable: true, view: true }),
-  field(['summary', 'maxTokens'], { label: '摘要输出上限', kind: 'positiveInt', default: 8_192 }),
-  field(['handoff', 'maxTokens'], { label: '交接单输出上限', kind: 'positiveInt', default: 8_192 }),
+  field(['summary', 'maxTokens'], { label: '摘要输出上限', kind: 'positiveInt', default: 16_384 }),
+  field(['handoff', 'maxTokens'], { label: '交接单输出上限', kind: 'positiveInt', default: 16_384 }),
   field(['timeouts', 'llmMs'], { label: '模型调用超时', kind: 'positiveInt', default: 180_000 }),
   field(['dev', 'testRangeNodes'], { label: '测试取段条数', kind: 'positiveInt', default: 4 }),
   field(['handoffDir'], {

package/lib/core/errors.js

@@ -3,6 +3,7 @@
  *
  * 命令、HTTP、工具三个入口都用这里的文案，不各写一套。
  */
+import { clipCodeUnits } from './clip.js';
 
 /** 已知失败类别 → 一句话。 */
 const MESSAGES = Object.freeze({
@@ -46,7 +47,8 @@ export function errorText(error) {
     // 只对 summary 附带原因（其它 code 的 message 是内部措辞）；截断防止把整段
     // 模型输出/校验清单倒给用户，原因本身也是中文可读的。
     if (code === 'summary' && error instanceof Error && typeof error.message === 'string' && error.message.length > 0) {
-      const detail = error.message.length > 140 ? `${error.message.slice(0, 139)}…` : error.message;
+      // 0.5.1 D03：截断收口到 core/clip（原来是手写 slice(0,139)+'…'）。
+      const detail = clipCodeUnits(error.message, 140);
       return `${base}原因：${detail}`;
     }
     return base;

package/lib/core/native-line.js

@@ -23,6 +23,33 @@
 /** compaction-basic 的 headroomTokens 默认值（源码：?? 65536）。 */
 export const NATIVE_HEADROOM_DEFAULT = 65536;
 
+/**
+ * compaction-basic 的 retainRatio 默认值（0.2.1-rc.3 源码：DEFAULT_RETAIN_RATIO = .16）。
+ *
+ * 只用于「预判原生压缩范围」：宿主没有把生效默认值暴露给插件，这里跟随
+ * 0.2.1-rc.3 的源码常量。用户显式配置 retainRatio/retainTokens 时以配置为准。
+ */
+export const NATIVE_RETAIN_RATIO_DEFAULT = 0.16;
+
+/**
+ * 原生压缩的「保留近期尾部」预算（compaction-basic 的 retainTokens）：
+ *   显式 retainTokens → 直接用；
+ *   否则 floor(messageBudgetTokens × retainRatio)，messageBudget = 窗口 − 输出预留。
+ * 与宿主 resolveCompactSpec 同口径。
+ *
+ * @param {{contextWindow:number|null, reservedCompletionTokens?:number, retainRatio?:number, retainTokens?:number}} input
+ * @returns {number|null} 算不出返回 null
+ */
+export function nativeRetainTokensOf({ contextWindow, reservedCompletionTokens = 0, retainRatio, retainTokens } = {}) {
+  if (!Number.isFinite(contextWindow) || contextWindow <= 0) return null;
+  if (Number.isInteger(retainTokens) && retainTokens >= 0) return retainTokens;
+  const reserved = Number.isFinite(reservedCompletionTokens) && reservedCompletionTokens >= 0 ? reservedCompletionTokens : 0;
+  const budget = contextWindow - reserved;
+  if (budget <= 0) return null;
+  const ratio = Number.isFinite(retainRatio) && retainRatio >= 0 && retainRatio < 1 ? retainRatio : NATIVE_RETAIN_RATIO_DEFAULT;
+  return Math.floor(budget * ratio);
+}
+
 /**
  * 计算真实触发线。
  *

package/lib/core/native-pin-risk.js

@@ -0,0 +1,106 @@
+/**
+ * 0.5.1 批 2：预判「下一次 DSH 原生自动压缩会覆盖哪些锁定消息」—— 纯函数，零依赖。
+ *
+ * 宿主 `@deepseek-ai/dsh-compaction-basic` 的选段（0.2.1-rc.3 源码）：
+ *
+ *   const firstIdx = systemHead(session, surface[0]) === undefined ? 0 : 1;
+ *   let accumulated = 0, keepFromIdx = nodes.length;
+ *   for (let i = nodes.length - 1; i >= 0; i--) {
+ *     accumulated += nodes[i].tokens;
+ *     keepFromIdx = i;
+ *     if (accumulated >= retainTokens) break;
+ *   }
+ *   if (keepFromIdx <= firstIdx) return null;
+ *   while (keepFromIdx > firstIdx && !toolPairingBalancedBefore(session, surface[keepFromIdx])) keepFromIdx -= 1;
+ *   if (keepFromIdx <= firstIdx) return null;
+ *   return { start: surface[firstIdx], end: surface[keepFromIdx - 1] };
+ *
+ * 本模块只复刻「选段」这一段，不执行任何压缩；配对平衡用调用方传入的
+ * `engine.toolPairingBalancedBefore`，与宿主同口径（缺回调时跳过该步，宁少报不多报）。
+ *
+ * 触发条件（由 actions/state 判断）：原生自动压缩开启、当前压力 ≥ 真实触发线。
+ * 宿主在 step boundary 才真正压；用户看到预警时还有机会先 /handoff 或解锁。
+ *
+ * @module core/native-pin-risk
+ */
+import { tokenOf } from './tokens.js';
+
+function isSeq(value) {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
+
+function normalizeNodes(nodes) {
+  return Array.isArray(nodes)
+    ? nodes.filter((node) => node !== null && typeof node === 'object' && isSeq(node.seq))
+    : [];
+}
+
+/**
+ * 复刻宿主的保留尾部 + 配对平衡选段，返回会被压缩的 seq 范围。
+ *
+ * @param {object} input
+ * @param {number[]} input.pinnedSeqs 当前仍 live 的锁定 seq
+ * @param {{seq:number, tokens?:number, heuristicTokens?:number}[]} input.nodes 当前 surface 节点（含 token 定价）
+ * @param {number} [input.firstIdx] 第一个允许被压的下标（system head 存在时为 1）
+ * @param {number} [input.retainTokens] 原生保留尾部预算（compaction-basic 的 retainTokens）
+ * @param {(seq:number)=>boolean} [input.isBalancedBefore] 该 seq 之前切一刀是否工具配对平衡
+ * @returns {{count:number, seqs:number[], startSeq:number, endSeq:number}|null}
+ *   null = 没有可压范围 / 没有 pin（无需预警）
+ */
+export function nativePinnedRiskOf({ pinnedSeqs, nodes, firstIdx = 0, retainTokens = 0, isBalancedBefore } = {}) {
+  const pinned = Array.isArray(pinnedSeqs) ? pinnedSeqs.filter(isSeq) : [];
+  if (pinned.length === 0) return null;
+  const list = normalizeNodes(nodes);
+  if (list.length === 0) return null;
+
+  const startIdx = Math.max(0, Math.min(Number.isInteger(firstIdx) ? firstIdx : 0, list.length));
+  if (startIdx >= list.length) return null;
+  const budget = Number.isFinite(retainTokens) && retainTokens > 0 ? retainTokens : 0;
+
+  // 与宿主逐字同序：永远至少保留最后一条（accumulated 在第一轮就 >= 0）。
+  let accumulated = 0;
+  let keepFromIdx = list.length;
+  for (let index = list.length - 1; index >= 0; index -= 1) {
+    accumulated += tokenOf(list[index]);
+    keepFromIdx = index;
+    if (accumulated >= budget) break;
+  }
+  if (keepFromIdx <= startIdx) return null;
+
+  if (typeof isBalancedBefore === 'function') {
+    let rewind = 0;
+    while (keepFromIdx > startIdx && rewind < list.length) {
+      const seq = list[keepFromIdx].seq;
+      let balanced = false;
+      try {
+        balanced = isBalancedBefore(seq) === true;
+      } catch {
+        balanced = true; // 判定失败时按「可切」处理：宁少报（不破坏配对）也不多报
+      }
+      if (balanced) break;
+      keepFromIdx -= 1;
+      rewind += 1;
+    }
+  }
+  if (keepFromIdx <= startIdx) return null;
+
+  const rangeStart = list[startIdx];
+  const rangeEnd = list[keepFromIdx - 1];
+  const inRange = (seq) => {
+    // surface 顺序不一定按 seq 单调（压缩后 checkpoint 插在旧尾部前），按成员判定。
+    for (let index = startIdx; index < keepFromIdx; index += 1) {
+      if (list[index].seq === seq) return true;
+    }
+    return false;
+  };
+  const seqs = pinned.filter(inRange);
+  if (seqs.length === 0) return null;
+  return {
+    count: seqs.length,
+    seqs,
+    startSeq: rangeStart.seq,
+    endSeq: rangeEnd.seq,
+  };
+}
+
+export default nativePinnedRiskOf;

package/lib/core/pin-anchors.js

@@ -8,6 +8,7 @@
  *
  * 只做展示：摘要截断到一句（默认 60 字符，不贴原文全文），不读全量历史、不调模型。
  */
+import { clipCodeUnits } from './clip.js';
 
 /** 事件类型 → 中文角色标签（唯一来源）。 */
 export const ROLE_LABELS = Object.freeze({
@@ -58,7 +59,8 @@ export function messageSnippetOf(event, maxChars = 60) {
   const text = messageTextOf(event);
   if (text.length === 0) return '';
   const limit = Number.isInteger(maxChars) && maxChars > 1 ? maxChars : 60;
-  return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+  // 0.5.1 D03：截断收口到 core/clip（码元口径 = 旧行为逐字节兼容；emoji 切半问题随 S1 换 clipChars）。
+  return clipCodeUnits(text, limit);
 }
 
 /**

package/lib/core/pin-health.js

@@ -0,0 +1,112 @@
+/**
+ * 0.5.1 批 2：pin 失效判定（C 方案）—— 纯函数，零依赖。
+ *
+ * 背景：DSH 原生自动压缩（compaction-basic）按自己的保留尾部策略选段，
+ * 不认本插件的 pin；被它压掉的锁定消息会从 surface 消失。过去的实现用
+ * `livePinnedSeqs` 把「快照里有、surface 上没有」的 pin 直接过滤掉 —— 界面上
+ * 这些 pin 就**凭空消失**了，用户以为锁还生效，其实原文已经被压走。
+ *
+ * C 方案：不假装还在（不画到环上、不算进 live 计数），也不消失 ——
+ * 用 `pins.stale = { count, seqs }` 在悬停卡/菜单里明确写「已失效」。
+ *
+ * 失效原因只读日志判定（不猜）：
+ *   - 找到覆盖该 seq 的 `user/message(replace)` 事件；
+ *   - 顺着它的 `sourceEventSeqs[0]` 找 `compaction/start`；
+ *   - 原生自动压缩的 start 带 `turn`（非 null，宿主 compaction-basic 的
+ *     automatic pressure 路径 `owner = entryState.openTurn`）；
+ *   - 其它压缩（本插件 /bc、宿主 /compact、compactNow）的 start `turn: null`，
+ *     不论有没有 sourceCommandId 都归到 other（可以确定「被压缩带走」，只是不冒充原生）；
+ *   - 没有 replace 证据（撤销/分支/历史被改写）→ unknown，不冒充压缩。
+ *
+ * @module core/pin-health
+ */
+import { normalizePinnedSeqs } from './pins.js';
+
+/** 失效原因枚举（mixed = 多条 pin 的原因不一致）。 */
+export const PIN_STALE_CAUSES = Object.freeze(['native', 'other', 'unknown']);
+
+function isSeq(value) {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
+
+/**
+ * 扫描日志：被 replace 覆盖的 seq → replace 事件；compaction/start seq → data。
+ * @param {object[]} log
+ * @returns {{replaceByCoveredSeq:Map<number,object>, startBySeq:Map<number,object>}}
+ */
+function scanCompactionEvidence(log) {
+  const replaceByCoveredSeq = new Map();
+  const startBySeq = new Map();
+  for (const event of Array.isArray(log) ? log : []) {
+    if (event === null || typeof event !== 'object') continue;
+    if (event.type === 'compaction/start' && Number.isInteger(event.seq)) {
+      startBySeq.set(event.seq, event.data);
+      continue;
+    }
+    if (event.type !== 'user/message' || !Array.isArray(event.sourceEventSeqs)) continue;
+    for (const seq of event.sourceEventSeqs) {
+      if (typeof seq === 'number' && Number.isFinite(seq)) replaceByCoveredSeq.set(seq, event);
+    }
+  }
+  return { replaceByCoveredSeq, startBySeq };
+}
+
+/**
+ * 一条失效 pin 的归因。
+ * @param {number} seq
+ * @param {{replaceByCoveredSeq:Map<number,object>, startBySeq:Map<number,object>}} evidence
+ * @returns {'native'|'other'|'unknown'}
+ */
+function staleCauseOf(seq, evidence) {
+  const replace = evidence.replaceByCoveredSeq.get(seq);
+  if (replace === undefined) return 'unknown';
+  const startSeq = Array.isArray(replace.sourceEventSeqs) ? replace.sourceEventSeqs[0] : undefined;
+  const start = Number.isInteger(startSeq) ? evidence.startBySeq.get(startSeq) : undefined;
+  if (start === undefined || start === null || typeof start !== 'object') return 'unknown';
+  // 原生自动压缩：宿主 compaction-basic 把事件包在 turn 里（turn = openTurn 的 seq）。
+  if (typeof start.turn === 'number' && Number.isInteger(start.turn)) return 'native';
+  // 其它压缩：turn=null（插件菜单动作 / 宿主手动压缩 / compactNow）。
+  // 有 start 证据就说明「被压缩带走」，不因为缺 sourceCommandId 退化成 unknown。
+  return 'other';
+}
+
+/**
+ * 计算 pin 快照相对当前 surface 的健康状态。
+ *
+ * @param {object} input
+ * @param {number[]} input.pinnedSeqs pin 快照集合（latestPinnedSeqs(日志)）
+ * @param {number[]} input.surfaceSeqs 当前 surface 的 seq（升序）
+ * @param {object[]} [input.log] 会话事件日志（用于归因；缺失时全部算 unknown）
+ * @returns {{live:number[], stale:number[], cause:'native'|'other'|'unknown'|'mixed'|null, causes:{native:number,other:number,unknown:number}}}
+ */
+export function pinHealthOf({ pinnedSeqs, surfaceSeqs, log } = {}) {
+  const pinned = normalizePinnedSeqs(pinnedSeqs);
+  const liveSet = new Set((Array.isArray(surfaceSeqs) ? surfaceSeqs : []).filter(isSeq));
+  const live = pinned.filter((seq) => liveSet.has(seq));
+  const stale = pinned.filter((seq) => !liveSet.has(seq));
+  const causes = { native: 0, other: 0, unknown: 0 };
+  if (stale.length === 0) return { live, stale, cause: null, causes };
+
+  const evidence = scanCompactionEvidence(log);
+  for (const seq of stale) causes[staleCauseOf(seq, evidence)] += 1;
+
+  const present = PIN_STALE_CAUSES.filter((cause) => causes[cause] > 0);
+  const cause = present.length === 1 ? present[0] : 'mixed';
+  return { live, stale, cause, causes };
+}
+
+/**
+ * 失效原因的展示文案（宿主与客户端共用一份口径；客户端只传 counts）。
+ *
+ * @param {{native?:number, other?:number, unknown?:number}} [causes]
+ * @returns {string}
+ */
+export function staleCauseTextOf(causes) {
+  const native = Number.isInteger(causes?.native) ? causes.native : 0;
+  const other = Number.isInteger(causes?.other) ? causes.other : 0;
+  const unknown = Number.isInteger(causes?.unknown) ? causes.unknown : 0;
+  if (native > 0 && other === 0 && unknown === 0) return '随原生压缩移除';
+  if (native === 0 && other > 0 && unknown === 0) return '随压缩移除';
+  if (native === 0 && other === 0 && unknown > 0) return '随历史变化失效';
+  return '随压缩或历史变化失效';
+}

package/lib/core/relay-record.js

@@ -0,0 +1,128 @@
+/**
+ * 接力链 record 的**唯一构造点**（0.5.2 S2）。
+ *
+ * 为什么要有这个模块：0.5.1 之前父记录在 `actions/handoff.js` 手写 13–14 个键、
+ * 子记录在 `dsh/sessions.js` 手写 9–10 个键 —— 两个写点各拼一份，加字段要改两处，
+ * 漏一处就是静默降级（读侧 `normalizeRelayRecord` 对缺失/非法字段一律当没有）。
+ * 现在「一条 record 长什么样」只有这一处实现，两个写点只负责传语义参数。
+ *
+ * ⚠️ **这是 record 的字节契约，不是普通的对象字面量，不许「统一美化」**：
+ *   1. 键的**插入顺序**就是 `JSON.stringify` 的顺序（会话日志是 JSONL）。父/子两套
+ *      顺序**故意不同**，都必须逐字节保留 —— `test/contract-golden.mjs` 锁住了顺序；
+ *   2. 父记录多写 0.3 旧字段 `parentSessionId` / `index`（canonical 是 `parentId` /
+ *      `ordinal`，新写入双写，旧记录仍按旧名可读）；
+ *   3. 父记录写 `planId`（可能为 **null**）；子记录**没有**这个键；
+ *   4. 父记录 `historyTitle` **条件写入**（改名没真的生效就不写这个键，不能记一个
+ *      不存在的标题）；子记录没有这个键；
+ *   5. 父/子 `path` 都是**条件写入**（`typeof path === 'string' && path.length > 0`）：
+ *      子记录在旧调用方/落盘失败时拿不到交接单，就不写键、不写空串；父记录的调用方
+ *      保证交接单已落盘（`path.join(handoffDir, handoffFileName(...))`，必然非空），
+ *      所以父记录实际总是带 path —— golden 里有断言；
+ *   6. 父/子都写 `titleSeq`，**即使为 null**（不是「省略 null」的统一策略：
+ *      0.4.x 记录没有这个键，0.5.0 起显式写 null 表示「拿不到宿主 eventSeq」）。
+ *
+ * 纯函数：不读文件/环境/时间，不 import 任何 `node:` 模块；`atIso` 由调用方按本地
+ * 时区口径算好传进来（core 不依赖 dsh 层），保证可在浏览器侧内联（build-client）。
+ */
+
+/** record 的两个角色（写点只有这两个：交接的父会话、新建的子会话）。 */
+export const RELAY_RECORD_ROLES = Object.freeze(['parent', 'child']);
+
+/**
+ * 按角色产出一条 relay record（唯一构造）。
+ *
+ * 两个角色共用的字段：`parentId` / `childId` / `ordinal` / `title` / `baseTitle` /
+ * `scheme` / `titleSeq` / `at` / `atIso`（`title` 是本次新会话标题）。
+ *
+ * @param {object} input
+ * @param {'parent'|'child'} input.role 父记录（旧会话日志）还是子记录（新会话日志）
+ * @param {string} input.parentId 父会话 id（写 `parentId`，parent 另写 `parentSessionId`）
+ * @param {string} input.childId 子会话 id
+ * @param {number} input.ordinal 链号（parent 另写 `index`）
+ * @param {string} input.title 本次新会话标题
+ * @param {string} input.baseTitle 链上原始标题（不带序号前缀）
+ * @param {'handoff-n'|'history-n'} input.scheme 本次链的命名方案
+ * @param {number|null} [input.titleSeq] 本次 rename 的宿主 eventSeq（拿不到就是 null）
+ * @param {string} [input.path] 交接单路径（非空字符串才写键）
+ * @param {string|null} [input.planId] 压缩计划 id（**仅 parent**；null 表示这次没压缩）
+ * @param {string} [input.historyTitle] 旧会话改名后的「历史 N」标题（**仅 parent**，且只在改名生效时传）
+ * @param {number} input.at 记录时间（epoch ms）
+ * @param {string} input.atIso 记录时间（本地 ISO，含时区偏移）
+ * @returns {object} 可直接交给 `engine.appendPluginRecord` 的 record
+ */
+export function relayRecordOfForm({
+  role,
+  parentId,
+  childId,
+  ordinal,
+  baseTitle,
+  title,
+  scheme,
+  titleSeq = null,
+  path,
+  planId,
+  historyTitle,
+  at,
+  atIso,
+} = {}) {
+  if (role === 'parent') {
+    return {
+      parentId,
+      childId,
+      ordinal,
+      at,
+      atIso,
+      // 0.3 旧字段双写（旧记录只读兼容）；顺序与 0.5.1 手写写法逐字节一致。
+      parentSessionId: parentId,
+      index: ordinal,
+      ...(typeof path === 'string' && path.length > 0 ? { path } : {}),
+      planId: planId ?? null,
+      title,
+      baseTitle,
+      scheme,
+      titleSeq,
+      // 改名真的生效（renamed / already）时调用方才传 historyTitle；空串也当没有。
+      ...(typeof historyTitle === 'string' && historyTitle.length > 0 ? { historyTitle } : {}),
+    };
+  }
+  if (role === 'child') {
+    return {
+      parentId,
+      childId,
+      ordinal,
+      baseTitle,
+      title,
+      scheme,
+      titleSeq,
+      // 旧调用方/落盘失败拿不到交接单 → 不写这个键（不猜、不写空串）。
+      ...(typeof path === 'string' && path.length > 0 ? { path } : {}),
+      at,
+      atIso,
+    };
+  }
+  // 角色是代码常量，传错属于开发期错误（不是用户输入），直接抛。
+  throw new TypeError(`relayRecordOfForm: 未知 role「${String(role)}」（只认 ${RELAY_RECORD_ROLES.join(' / ')}）`);
+}
+
+/**
+ * 父记录（写在**旧会话**日志里；子会话建好、旧会话改名之后）。
+ *
+ * 多写 0.3 旧字段 `parentSessionId` / `index` 和 `planId`，可选 `historyTitle`。
+ * @param {Omit<Parameters<typeof relayRecordOfForm>[0], 'role'>} input
+ * @returns {object}
+ */
+export function parentRelayRecordOf(input = {}) {
+  return relayRecordOfForm({ ...input, role: 'parent' });
+}
+
+/**
+ * 子记录（写在**新会话**日志里；`followup` 之后、`flush` 之前）。
+ *
+ * 只写 canonical 字段 + `titleSeq` + 条件 `path`；不写 `parentSessionId` / `index` /
+ * `planId` / `historyTitle`（这些是父会话侧的旧字段/审计字段）。
+ * @param {Omit<Parameters<typeof relayRecordOfForm>[0], 'role'>} input
+ * @returns {object}
+ */
+export function childRelayRecordOf(input = {}) {
+  return relayRecordOfForm({ ...input, role: 'child' });
+}

package/lib/dsh/compaction-log.js

@@ -4,13 +4,16 @@
  * 数据本来就在日志里：compaction/start → summary → user/message(replace) → end。
  * 这里只配对、不写任何东西；面板/接口用 `collectCompactions()`。
  *
- * 「已提交」的判定（和 session-view.countSummaries 同口径）：
- *   1. 有覆盖该 summary 的 replace（replace 的 sourceEventSeqs 含 summary.seq）；
- *   2. 有同 compactionId 的 end，且 end 没有 error；
- *   3. 没有 compactionId 的旧日志按旧口径（有 replace 即算）。
+ * 「已提交」的判定与 `dsh/session-view.countSummaries` **同一份实现**
+ * （`compaction-pair.isCommittedCompaction`，0.5.1 D01 合并）：
+ *   1. 必须有覆盖该 summary 的 replace（replace 的 sourceEventSeqs 含 summary.seq）——
+ *      没有 compactionId 的旧日志也一样；
+ *   2. 有 compactionId 时，还要求同 id 的 end 存在且没有 error。
  */
 import { sessionLog } from './session-view.js';
-import { scanCompactionLog } from './compaction-pair.js';
+import { isCommittedCompaction, scanCompactionLog } from './compaction-pair.js';
+
+import { clipCodeUnits } from '../core/clip.js';
 
 const DEFAULT_LIMIT = 10;
 const MAX_LIMIT = 50;
@@ -41,10 +44,13 @@ function flatten(value) {
   return text.replace(/\s+/gu, ' ').trim();
 }
 
-/** 摘要正文预览（超长截断，保留省略号）。 */
+/** 摘要正文预览（超长截断，保留省略号）。
+ *
+ * 0.5.1 D03：收口到 core/clip；`ellipsis:'append'` 显式保留「最多 200 字 + 省略号（多 1 字符）」
+ * 的既有输出（`previewTruncated` 与 diff 端点都依赖它，合并时不能改成 200）。
+ */
 function previewOf(value, max = PREVIEW_CHARS) {
-  const text = flatten(value);
-  return text.length <= max ? text : `${text.slice(0, max)}…`;
+  return clipCodeUnits(flatten(value), max, { ellipsis: 'append' });
 }
 
 /** 日志事件里可用的时间戳（不同版本字段可能不同）。 */
@@ -105,7 +111,8 @@ export function collectCompactions(session, options = {}) {
       seq: typeof summary.seq === 'number' ? summary.seq : null,
       compactionId,
       at: atOf(summary),
-      committed: replace !== undefined && (compactionId === null ? true : end !== undefined && end.error === undefined),
+      // 0.5.1 D01：与 countSummaries 共用唯一判定（无 id 也要求 replace）。
+      committed: isCommittedCompaction({ compactionId, end, replace }),
       open: compactionId !== null && end === undefined,
       error: end?.error ?? null,
       replaceSeq: typeof replace?.seq === 'number' ? replace.seq : null,

package/lib/dsh/compaction-pair.js

@@ -8,7 +8,7 @@
  * 以前两处各自 for 一遍日志、各自建 summaries / ends / replace 索引，键名和过滤
  * 条件还不完全一样（countSummaries 用 replacedSeqs Set，compaction-log 用
  * replaceByCoveredSeq Map）——只要一处改配对规则，另一处就静默漂移。
- * 现在扫描只在这里做一次，两个消费方各自保留自己的「已提交」判定。
+ * 现在扫描与「已提交」判定都只在这里做一次（0.5.1 D01：判定也合并）。
  *
  * 只读：不写日志、不碰 session 内部结构。
  */
@@ -46,3 +46,29 @@ export function scanCompactionLog(log) {
 
   return { summaries, ends, replaceByCoveredSeq };
 }
+
+/**
+ * 一次压缩是否「已提交」（D01：唯一口径）。
+ *
+ * 0.5.1 之前两个消费方各写一遍，而且在**没有 `compactionId` 的旧日志**上答案不同：
+ *   - `dsh/compaction-log.collectCompactions`：所有 summary 都要求 replace；
+ *   - `dsh/session-view.countSummaries`：没有 id 的 summary 直接 +1，不看 replace。
+ * 同一份日志于是出现「countSummaries=1 / committed=false」的幽灵压缩。现在统一按
+ * 严格版：**没有 id 也必须被 replace 覆盖**（没有 id 无法配对 end，只能要求 replace）。
+ *
+ * 有 id 时还要求同 id 的 end 存在且没有 error（失败事务的 summary 是幽灵摘要，不算）。
+ *
+ * @param {{compactionId?:string|null, end?:object, replace?:object|null}} input
+ *   compactionId：summary.data.compactionId（旧日志没有 → null/undefined）
+ *   end：同 id 的 compaction/end data（没有 → undefined）
+ *   replace：覆盖 summary.seq 的 user/message(replace) 事件（没有 → undefined）
+ * @returns {boolean}
+ */
+export function isCommittedCompaction({ compactionId, end, replace } = {}) {
+  // 1) 无论有没有 compactionId，都必须有一条覆盖该 summary 的 replace。
+  if (replace === undefined || replace === null) return false;
+  // 2) 旧日志没有 id：无法配对 end，replace 即算已提交（0.4 兼容口径）。
+  if (typeof compactionId !== 'string' || compactionId.length === 0) return true;
+  // 3) 新日志：还要求 end 存在且不是失败 end。
+  return end !== undefined && end !== null && end.error === undefined;
+}

package/lib/dsh/diag-counters.js

@@ -11,6 +11,8 @@
  * 单例在 lib/index.js 装配到 `deps.diag`；actions 通过 `deps.diag.*` 埋点。
  */
 
+import { clipCodeUnits } from '../core/clip.js';
+
 /** 耗时样本上限（最近 20 次）。 */
 export const LATENCY_SAMPLE_LIMIT = 20;
 /** 错误码条目上限（按 code+phase 聚合后的条数）。 */
@@ -51,7 +53,8 @@ function normalizeToken(value, maxChars) {
   if (typeof value !== 'string') return null;
   const trimmed = value.replace(/\s+/gu, ' ').trim();
   if (trimmed.length === 0) return null;
-  return trimmed.length > maxChars ? `${trimmed.slice(0, Math.max(0, maxChars - 1))}…` : trimmed;
+  // 0.5.1 D03：截断收口到 core/clip（码元口径，行为不变）。
+  return clipCodeUnits(trimmed, maxChars);
 }
 
 /**

package/lib/dsh/diagnostics.js

@@ -13,6 +13,7 @@
  * 三道清洗里只有「正则兜底」会改内容，且只把命中串替换成 `[REDACTED]`、只把数量写进
  * `json.redactions`（可选字段，不保留原文）。
  */
+import { clipCodeUnits } from '../core/clip.js';
 import { localIso } from './diag-counters.js';
 
 /** 产物 schema 版本（客户端/issue 模板以此识别格式）。 */
@@ -81,7 +82,8 @@ function pickText(value, maxChars) {
   if (typeof value !== 'string') return null;
   const trimmed = value.replace(/\s+/gu, ' ').trim();
   if (trimmed.length === 0) return null;
-  return trimmed.length > maxChars ? `${trimmed.slice(0, Math.max(0, maxChars - 1))}…` : trimmed;
+  // 0.5.1 D03：截断收口到 core/clip（码元口径，行为不变）。
+  return clipCodeUnits(trimmed, maxChars);
 }
 
 function pickInt(value) {