dsh-compact-relay 0.5.0 → 0.5.1

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/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/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) {

package/lib/dsh/handoff-archive.js

@@ -151,6 +151,41 @@ export async function archiveHandoffSource(ctx, sessionId, { log, attempts = 2,
   return failed(isActiveError(lastError) ? 'active' : 'failed', activityKindsOf(lastError));
 }
 
+/**
+ * 宿主侧栏置顶集合（0.5.1 批 2）。
+ *
+ * 宿主实证（`@deepseek-ai/dsh-workspace/lib/index.js`）：`WorkspaceRegistry`
+ * - `get pinnedSessionIds()`：registry 全局置顶集合，pin 顺序（最近置顶在前）；
+ * - `pinSession(id)` / `unpinSession(id)`；
+ * - 置顶与归档互斥：`archiveSession` 在**同一次写盘**里把该 id 从 pinnedSessionIds 移除
+ *   （源码注释「Archiving drops the session's pin in the same durable write」）。
+ * 所以「归档会取消置顶」不是本插件的推测，是宿主真实行为；这里只读判断，
+ * 不替用户 unpin/pin。拿不到/形状异常 → null（不猜 false）。
+ * @param {object} ctx
+ * @returns {string[]|null}
+ */
+export function pinnedSessionIdsOf(ctx) {
+  try {
+    const registry = ctx?.get?.('workspaceRegistry');
+    const ids = registry?.pinnedSessionIds;
+    return Array.isArray(ids) ? ids.filter((id) => typeof id === 'string') : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 旧会话当前是否在侧栏置顶。
+ * @param {object} ctx
+ * @param {string} sessionId
+ * @returns {boolean|null} null = 宿主没提供可读的置顶集合
+ */
+export function isSessionPinned(ctx, sessionId) {
+  if (typeof sessionId !== 'string' || sessionId.length === 0) return null;
+  const ids = pinnedSessionIdsOf(ctx);
+  return ids === null ? null : ids.includes(sessionId);
+}
+
 /**
  * 归档结果 → 交接完成 message 里的一行（成功/失败都不丢信息）。
  * 成功时明确告诉用户恢复入口；失败时固定写「归档失败，不影响交接」。
@@ -160,11 +195,22 @@ export async function archiveHandoffSource(ctx, sessionId, { log, attempts = 2,
 export function handoffArchiveNoteOf(result) {
   const status = result !== null && typeof result === 'object' ? result.status : 'failed';
   if (status === 'archived') {
-    return '旧会话已归档（可在新会话输入框上方「已接力自 …」→「恢复旧会话」找回；侧栏视图选「全部会话」也能取消归档）。';
+    // 0.5.1 DCR-04：指向宿主真实的视图标签/动作文案（实测 dsh-client-ui-workspace：
+    // viewOptions 三选一里是「全部对话（显示已归档）」，会话行动作是「取消归档」；
+    // 宿主没有「全部会话」这个视图）。
+    return '旧会话已归档（可在新会话输入框上方「已接力自 …」→「恢复旧会话」找回；侧栏视图选「全部对话（显示已归档）」，再对该会话点「取消归档」）。';
   }
   if (status === 'already') {
     return '旧会话此前已在归档中（可在新会话输入框上方「已接力自 …」→「恢复旧会话」找回）。';
   }
+  // 0.5.1 批 2：用户显式关掉归档（handoff archive:false）。
+  if (status === 'skipped') {
+    return '按你的选择，旧会话未归档（仍在列表里；侧栏置顶保持不变）。';
+  }
+  // 0.5.1 批 2：旧会话在侧栏置顶，未经确认不归档（宿主归档会同时取消置顶）。
+  if (status === 'pinned') {
+    return '旧会话已置顶，本次未自动归档（归档会取消置顶；如要归档，可在交接确认里选「交接并归档（取消置顶）」，或先取消置顶）。';
+  }
   const kinds = Array.isArray(result?.activityKinds) && result.activityKinds.length > 0 ? result.activityKinds.join('/') : null;
   if (status === 'active') {
     return `旧会话归档失败，不影响交接（仍有任务在跑：${kinds ?? 'active'}；不自动停止任务，旧会话仍在列表里）。`;