dsh-compact-relay 0.4.2 → 0.5.1

package/lib/dsh/relay.js

@@ -5,7 +5,10 @@
  * 写：engine.appendPluginRecord（和压缩判断记录/pin 同一个宿主 API）。
  * 记录缺失/损坏一律当作没有（旧会话兼容），不阻断交接。
  */
-import { RELAY_RECORD_TYPE } from '../core/relay.js';
+import { RELAY_RECORD_TYPE, splitHandoffTitle } from '../core/relay.js';
+
+/** relay 记录里允许的标题方案（0.5.0 命名反转的两种新标题；legacy 不写进记录）。 */
+const RECORD_SCHEMES = new Set(['handoff-n', 'history-n']);
 
 /**
  * 合法化一条 relay 记录；不合法返回 null。
@@ -13,8 +16,14 @@ import { RELAY_RECORD_TYPE } from '../core/relay.js';
  * 0.4 P2-2（接力链元数据补全）：canonical 字段为 `parentId` / `childId` / `ordinal` / `at` / `atIso`；
  * 同时保留 0.3 的旧字段 `parentSessionId` / `index`（旧记录只读兼容，新写入两者都带）。
  *
+ * 0.4.3 F2（无痕 handoff 地基）：白名单放行可选字段 `scheme` / `titleSeq` / `historyTitle`。
+ * 旧记录没有这三个字段 → 一律读成 null；其余字段与旧记录读取语义完全不变。
+ *
+ * 0.5.0 命名反转起，父/子记录都写 `scheme`（本次链 `history-n`/`handoff-n`）与 `titleSeq`；
+ * 新链父记录另写 `historyTitle`（旧会话改名后的「历史 N」）。
+ *
  * @param {unknown} data
- * @returns {{parentId:string, childId:string, ordinal:number, at:number, atIso:string|null, parentSessionId:string, index:number, path?:string, planId?:string|null, title?:string, baseTitle?:string}|null}
+ * @returns {{parentId:string, childId:string, ordinal:number, at:number, atIso:string|null, parentSessionId:string, index:number, path?:string, planId?:string|null, title?:string, baseTitle?:string, scheme:'handoff-n'|'history-n'|null, titleSeq:number|null, historyTitle:string|null}|null}
  */
 export function normalizeRelayRecord(data) {
   if (data === null || typeof data !== 'object') return null;
@@ -43,26 +52,159 @@ export function normalizeRelayRecord(data) {
     planId: typeof data.planId === 'string' ? data.planId : null,
     ...(typeof data.title === 'string' ? { title: data.title } : {}),
     ...(typeof data.baseTitle === 'string' ? { baseTitle: data.baseTitle } : {}),
+    // 0.4.3 F2：新字段只做白名单放行，缺失/非法一律 null（不猜、不补默认值）。
+    scheme: RECORD_SCHEMES.has(data.scheme) ? data.scheme : null,
+    titleSeq: Number.isInteger(data.titleSeq) && data.titleSeq > 0 ? data.titleSeq : null,
+    historyTitle: typeof data.historyTitle === 'string' && data.historyTitle.length > 0 ? data.historyTitle : null,
   };
 }
 
 /**
- * 会话里最近一条接力链记录（没有返回 null）。
+ * 从日志尾部向前找第一条满足条件的 relay 记录（没有返回 null）。
+ *
+ * 拆出来给入站/出站两个读取器共用：只扫一遍日志，判定由调用方给（DCR-01）。
  * @param {object|undefined} session
+ * @param {(record:object)=>boolean} predicate
  * @returns {object|null}
  */
-export function relayRecordOf(session) {
+function latestRelayRecordWhere(session, predicate) {
   const log = session?.log;
   if (!Array.isArray(log)) return null;
   for (let index = log.length - 1; index >= 0; index -= 1) {
     const event = log[index];
     if (event?.type !== RELAY_RECORD_TYPE) continue;
     const record = normalizeRelayRecord(event.data);
-    if (record !== null) return record;
+    if (record !== null && predicate(record)) return record;
   }
   return null;
 }
 
+/**
+ * 会话里最近一条接力链记录（没有返回 null）。
+ *
+ * **语义保持不变**（0.5.1 DCR-01 有意不改）：这是「最近一条记录」，出站/入站都可能。
+ * `readState.relay` 与 `handoffTitlePlanOf` 的链号递增都依赖它（下一次交接要看最近
+ * 一跳，可能是本会话交接出去的那条）。
+ * @param {object|undefined} session
+ * @returns {object|null}
+ */
+export function relayRecordOf(session) {
+  return latestRelayRecordWhere(session, () => true);
+}
+
+/**
+ * 本会话的**入站**接力记录：`childId === session.id` 的最新一条（没有返回 null）。
+ *
+ * 0.5.1 DCR-01：祖先会话再次交接后，日志最新一条变成出站记录（childId=下一代），
+ * 旧实现把它当链信息下发给客户端 → 客户端的「是不是本会话的入站记录」判定不成立
+ * → 接力条消失。接力条要看的永远是「我是被谁交接出来的」，所以按 childId 认。
+ * @param {object|undefined} session
+ * @returns {object|null}
+ */
+export function relayInboundRecordOf(session) {
+  const id = session?.id;
+  if (typeof id !== 'string' || id.length === 0) return null;
+  return latestRelayRecordWhere(session, (record) => record.childId === id);
+}
+
+/**
+ * 本会话的**出站**接力记录：`childId !== session.id` 的最新一条（没有返回 null）。
+ *
+ * 0.5.1 DCR-01：作为 `readState.next` 下发（只加不改），供「父→子」入口与
+ * 「子会话向父会话补交接单 path」使用；接力条本身不看它。
+ * @param {object|undefined} session
+ * @returns {object|null}
+ */
+export function relayOutboundRecordOf(session) {
+  const id = session?.id;
+  if (typeof id !== 'string' || id.length === 0) return null;
+  return latestRelayRecordWhere(session, (record) => record.childId !== id);
+}
+
+/**
+ * 会话头是否具备「可能是一条老链」的血缘（DCR-02 的前置条件，不看标题）。
+ *
+ * 单独导出是为了让 `readState` 在**没有入站记录**时先做这道便宜的判断，只有可能
+ * 是老链才去读标题服务（普通根会话占多数，不该为每条状态读多打一次标题查找）。
+ *
+ * @param {object|undefined} session
+ * @returns {string|null} `header.parentSession`（合法时），否则 null
+ */
+export function legacyChainParentIdOf(session) {
+  const header = session?.header;
+  if (header === null || typeof header !== 'object') return null;
+  const parentId = typeof header.parentSession === 'string' ? header.parentSession : '';
+  if (parentId.length === 0) return null;
+  // subagent 会话有 parentSession（指向派它的父会话），但它不在人看的接力链上。
+  if (header.origin === 'subagent') return null;
+  // fork（isSeeded=true）继承的是前缀快照，血缘也不是「交接」。
+  if (header.isSeeded === true) return null;
+  return parentId;
+}
+
+/**
+ * 0.5.1 DCR-02：0.5.0 之前生成的老链没有 relay record —— 用会话头 + 标题合成只读 chain。
+ *
+ * 为什么需要：0.4.x 只在**父会话**日志里写记录，子会话自己没有记录；升级到 0.5.0 后
+ * 这些老链会话 `chain=null`，接力条永远不显示。这里只做**只读兜底**（不写日志、
+ * 不改任何记录），条件全部满足才合成：
+ *   1. `header.parentSession` 是非空字符串（宿主血缘字段）；
+ *   2. `header.origin !== 'subagent'`（subagent 会话不是交接链）；
+ *   3. `header.isSeeded !== true`（宿主 `isSeeded` = fork 继承前缀，不是交接出来的）；
+ *   4. 会话标题能解析出链号（`splitHandoffTitle(...).handedOff > 0`）——
+ *      老链子会话标题是「交接第 N 次：X」；干净标题说明不是交接出来的会话，不猜。
+ *
+ * 合成链不带 `path`：老链的交接单路径只写在父会话记录里，客户端缺 path 时会按
+ * 入站记录向父会话只读回查（`loadParentPath`）。带 `synthesized:true` 只是给
+ * 调试/测试一个明确标记（客户端投影忽略未知字段）。
+ *
+ * @param {{session?:object, title?:string}} input session 会话；title 当前标题（读不到传 undefined）
+ * @returns {{ordinal:number, baseTitle:string, parentId:string, childId:string, scheme:'handoff-n'|'history-n', synthesized:true}|null}
+ */
+export function legacyRelayChainOf({ session, title } = {}) {
+  const parentId = legacyChainParentIdOf(session);
+  if (parentId === null) return null;
+  const childId = typeof session?.id === 'string' && session.id.length > 0 ? session.id : null;
+  if (childId === null) return null;
+  const split = splitHandoffTitle(title);
+  if (!(split.handedOff > 0)) return null;
+  return {
+    ordinal: split.handedOff,
+    baseTitle: split.baseTitle,
+    parentId,
+    childId,
+    // 老链只有「交接第 N 次」；标题是「历史 N」时仍是新链形态（record 丢了）——
+    // legacy 堆叠（「交接：」）按旧链展示（客户端文案只区分 history-n / 其它）。
+    scheme: split.scheme === 'history-n' ? 'history-n' : 'handoff-n',
+    synthesized: true,
+  };
+}
+
+/**
+ * 0.5.0 F4：把一条 relay 记录投影成只读的「接力链节点」（交给 readState 下发）。
+ *
+ * 只是投影，不是解析：字段全部取自记录本身，不读标题、不补默认序号、不猜 scheme。
+ *   - 记录里没有的字段 → null（0.4 及更早的记录没有 scheme/baseTitle）；
+ *   - path 与记录写法一致：有才带，没有就不出现这个键（不塞 null 占位）；
+ *   - 不是对象 → null（表示「没有链信息」，客户端按无链接口处理）。
+ *
+ * @param {object|null|undefined} record normalizeRelayRecord 的返回值
+ * @returns {{ordinal:number|null, baseTitle:string|null, parentId:string|null, childId:string|null, scheme:'handoff-n'|'history-n'|null, path?:string}|null}
+ */
+export function relayChainOf(record) {
+  if (record === null || typeof record !== 'object') return null;
+  const text = (value) => (typeof value === 'string' && value.length > 0 ? value : null);
+  const path = text(record.path);
+  return {
+    ordinal: Number.isInteger(record.ordinal) && record.ordinal > 0 ? record.ordinal : null,
+    baseTitle: text(record.baseTitle),
+    parentId: text(record.parentId),
+    childId: text(record.childId),
+    scheme: text(record.scheme),
+    ...(path === null ? {} : { path }),
+  };
+}
+
 /**
  * 写一条 relay 记录；失败只返回 false（交给调用方决定是否告警），不影响交接结果。
  * @param {{appendPluginRecord?: Function}} engine

package/lib/dsh/session-view.js

@@ -6,7 +6,7 @@
  */
 import { latestCompressHint } from '../core/compress-hint.js';
 import { latestPinnedSeqs } from '../core/pins.js';
-import { scanCompactionLog } from './compaction-pair.js';
+import { isCommittedCompaction, scanCompactionLog } from './compaction-pair.js';
 
 /**
  * 0.4 BUG-013：checkpoint 判定的默认实现（漏传第二个参数时也不再静默失效）。
@@ -68,23 +68,29 @@ export function firstCompactableIdx(session) {
  *
  * 以前数所有 compaction/summary，事务在 summary 之后失败会留下「幽灵摘要」，
  * 把 advice 提前推到交接、6 次后提前打开合并旧摘要模式。
- * 现在按 compactionId 配对：summary + 无 error 的 end + 覆盖该 summary 的 replace 才算一次；
- * 没有 compactionId 的旧日志（或外部夹具）按旧口径计数，保证兼容。
+ * 现在按 compactionId 配对：summary + 无 error 的 end + 覆盖该 summary 的 replace 才算一次。
+ *
+ * 0.5.1 D01：**口径与 `dsh/compaction-log.collectCompactions` 合并**（唯一实现
+ * `compaction-pair.isCommittedCompaction`）。以前的宽松分支（没有 compactionId 的
+ * 旧日志直接 +1、不看 replace）会与面板的 committed 打架 —— 同一份日志
+ * countSummaries=1 / committed=false。现在旧日志同样要求 replace。
  */
 export function countSummaries(session) {
-  // 配对扫描（summary/end/replace）与 dsh/compaction-log 共用，口径见 compaction-pair.js。
+  // 配对扫描 + 「已提交」判定都与 dsh/compaction-log 共用（见 compaction-pair.js）。
   const { summaries, ends, replaceByCoveredSeq } = scanCompactionLog(sessionLog(session));
   let count = 0;
   for (const summary of summaries) {
     const id = summary.data?.compactionId;
-    if (typeof id !== 'string') {
+    const hasId = typeof id === 'string';
+    if (
+      isCommittedCompaction({
+        compactionId: hasId ? id : null,
+        end: hasId ? ends.get(id) : undefined,
+        replace: replaceByCoveredSeq.get(summary.seq),
+      })
+    ) {
       count += 1;
-      continue;
     }
-    const end = ends.get(id);
-    if (end === undefined || end.error !== undefined) continue;
-    if (!replaceByCoveredSeq.has(summary.seq)) continue;
-    count += 1;
   }
   return count;
 }

package/lib/dsh/sessions.js

@@ -12,15 +12,25 @@
  *   childAgent.followup(交接单)  → 消息成为新会话第一条消息并启动 turn
  *     （DSH 0.2 里没有 turn/start 的会话在界面上是「空白 Hero」，不会显示
  *       历史；followup 让交接内容真的显示出来。失败则退回纯 append。）
+ *   childSession 写 relay 记录  → 子会话自带链号（ordinal/baseTitle/scheme/titleSeq）
+ *     与交接单 path（0.5.0：调用方把已落盘的交接单文件路径传进来；子会话的
+ *     「查看交接单」不再依赖回查父会话）
  *
  * 全部失败点都做「能降级就降级、不能降级就带 childId 报错」，绝不静默。
  */
 import { randomUUID } from 'node:crypto';
 import { actionError } from '../core/errors.js';
-import { relayTitleOf, splitHandoffTitle } from '../core/relay.js';
+import {
+  MAX_TITLE_BYTES,
+  historyTitleOf,
+  relayTitleOf,
+  splitHandoffTitle,
+  truncateTitleUtf8,
+} from '../core/relay.js';
 import { HANDOFF_PREAMBLE } from '../core/prompts.js';
+import { localIso } from './diag-counters.js';
 import { cacheControls, routeOf } from './route.js';
-import { relayRecordOf } from './relay.js';
+import { relayRecordOf, writeRelayRecord } from './relay.js';
 
 /** 插件在消息 source 上的标识。 */
 export const PLUGIN_NAME = 'compact-relay';
@@ -29,6 +39,11 @@ function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
+/** 标题比较用的宿主口径折叠（连续空白 → 单空格 + trim）。 */
+function sameNormalizedTitle(left, right) {
+  return left.replace(/\s+/gu, ' ').trim() === right.replace(/\s+/gu, ' ').trim();
+}
+
 /**
  * 读原会话的 agent preset id（0.2 里优先会话头，其次 projection）。
  * @param {object} ctx
@@ -68,29 +83,81 @@ export function sourceTitleOf(ctx, session) {
 }
 
 /**
- * 下一次交接的标题计划：序号 + 原始标题。
+ * 按 scheme 组装标题计划（纯函数，不读 ctx）。
+ *
+ * - `handoff-n`（旧链）：保持「交接第 N 次：<原名>」原样，旧链一个字符不改；
+ * - `history-n`（0.5.0 新链）：新会话继承干净原名，旧会话由调用方改名「历史 N：<原名>」。
+ *   两个标题都按 `MAX_TITLE_BYTES` 先缩 base（前缀计入预算），避免宿主截断吃掉前缀。
+ * @param {'handoff-n'|'history-n'} scheme
+ * @param {number} index
+ * @param {string} baseTitle
+ * @param {boolean} viaRecord
+ * @returns {{index:number, baseTitle:string, title:string, historyTitle:string|null, scheme:'handoff-n'|'history-n', viaRecord:boolean}}
+ */
+function titlePlanOf(scheme, index, baseTitle, viaRecord) {
+  if (scheme === 'handoff-n') {
+    return {
+      index,
+      baseTitle,
+      title: relayTitleOf(index, baseTitle),
+      historyTitle: null,
+      scheme,
+      viaRecord,
+    };
+  }
+  const base = typeof baseTitle === 'string' && baseTitle.trim().length > 0 ? baseTitle.trim() : '会话';
+  const fitted = truncateTitleUtf8(base, MAX_TITLE_BYTES).trimEnd() || '会话';
+  return {
+    index,
+    baseTitle: base,
+    // 新会话标题 = 原名（不带序号）；旧会话标题 = 历史 N：原名。
+    title: fitted,
+    historyTitle: historyTitleOf(index, base, MAX_TITLE_BYTES),
+    scheme,
+    viaRecord,
+  };
+}
+
+/**
+ * 下一次交接的标题计划：序号 + 原始标题 + 本次链用哪种命名方案。
  *
- * A5：优先读父会话里的 relay 记录（结构化数据，不依赖标题文案）；
- * 没有记录（旧会话/首次交接）才回退到标题解析（兼容「交接第 N 次：」与历史堆叠前缀）。
+ * 序号优先读会话自己的 relay 记录（结构化数据，不依赖标题文案；新链子会话标题
+ * 继承原名后标题里已没有链号）。没有记录才回退标题解析：
+ *   - `历史 N：` → 继续新链（record 丢失时靠标题兜底）；
+ *   - `交接第 N 次：` / 旧「交接：」「接棒：」堆叠 → 旧链，保持旧命名（链级 cutover）；
+ *   - 干净标题（无前缀）→ 新链，本次为第 1 次；
+ *   - 标题读不到 → 保守按旧链处理（不生成可能与旧链混合的新标题）。
+ *
+ * 记录存在时方案以记录为准（`scheme='history-n'` 才走新链；0.3/0.4 旧记录
+ * scheme 为 null → 旧链，不迁移）。
  * @param {object} ctx
  * @param {object} session
- * @returns {{index:number, baseTitle:string, title:string, viaRecord:boolean}}
+ * @returns {{index:number, baseTitle:string, title:string, historyTitle:string|null, scheme:'handoff-n'|'history-n', viaRecord:boolean}}
  */
 export function handoffTitlePlanOf(ctx, session) {
+  const currentTitle = sourceTitleOf(ctx, session);
+  const split = splitHandoffTitle(currentTitle);
   const record = relayRecordOf(session);
   if (record !== null) {
-    const fallback = splitHandoffTitle(sourceTitleOf(ctx, session));
-    const baseTitle = typeof record.baseTitle === 'string' && record.baseTitle.length > 0 ? record.baseTitle : fallback.baseTitle;
+    const baseTitle = typeof record.baseTitle === 'string' && record.baseTitle.length > 0 ? record.baseTitle : split.baseTitle;
     const index = (Number.isInteger(record.ordinal) ? record.ordinal : record.index) + 1;
-    return { index, baseTitle, title: relayTitleOf(index, baseTitle), viaRecord: true };
+    const scheme = record.scheme === 'history-n' ? 'history-n' : 'handoff-n';
+    return titlePlanOf(scheme, index, baseTitle, true);
   }
-  const split = splitHandoffTitle(sourceTitleOf(ctx, session));
   const index = split.handedOff + 1;
-  return { index, baseTitle: split.baseTitle, title: relayTitleOf(index, split.baseTitle), viaRecord: false };
+  const scheme =
+    currentTitle === undefined
+      ? 'handoff-n'
+      : split.scheme === 'history-n' || (split.scheme === 'legacy' && split.handedOff === 0)
+        ? 'history-n'
+        : 'handoff-n';
+  return titlePlanOf(scheme, index, split.baseTitle, false);
 }
 
 /**
- * 给新会话起个可辨识的标题：交接第 N 次：<原题>。
+ * 给新会话起可辨识的标题。
+ * - 旧链：交接第 N 次：<原题>；
+ * - 新链（0.5.0 命名反转）：直接继承干净原名。
  * 具体序号/原题由 handoffTitlePlanOf 决定（优先 relay 记录，其次标题解析）。
  * @param {object} ctx
  * @param {object} session
@@ -100,6 +167,93 @@ export function childTitleOf(ctx, session) {
   return handoffTitlePlanOf(ctx, session).title;
 }
 
+/**
+ * 0.5.0 命名反转：把旧会话改名「历史 N：<原名>」。
+ *
+ * 只在 scheme='history-n' 的**新链**上执行；旧链（handoff-n）原样返回，一个字符不改
+ * （链级 cutover）。调用方必须在子会话建好之后调用：改名是可见副作用，任何失败都只
+ * warn、不阻断交接（子会话已经可用）。
+ *
+ * 幂等 guard：当前标题已经是本次目标（或宿主按更小预算截断后的同一前缀）时跳过，
+ * 同一链重复执行不会重复 append rename，也不会叠成「历史 2：历史 1：X」。
+ *
+ * 改名成功后 `await ctx.sessions.flush(session)` 收窄持久化窗口（宿主 rename 是同步写日志，
+ * flush 失败也只 warn）。
+ *
+ * @param {object} ctx
+ * @param {object} session 旧会话（rename 要求 live；手动 /handoff 时它正是当前会话）
+ * @param {{index:number, baseTitle:string, scheme?:'handoff-n'|'history-n', maxBytes?:number, log?:{warn?:Function}}} input
+ * @returns {Promise<{renamed:boolean, title:string|null, titleSeq:number|null, reason:'old-chain'|'unavailable'|'already'|'failed'|null}>}
+ */
+export async function renameHistoryOf(
+  ctx,
+  session,
+  { index, baseTitle, scheme = 'history-n', maxBytes = MAX_TITLE_BYTES, log } = {},
+) {
+  const result = { renamed: false, title: null, titleSeq: null, reason: null };
+  if (scheme !== 'history-n') {
+    result.reason = 'old-chain';
+    return result;
+  }
+
+  const target = historyTitleOf(index, baseTitle, maxBytes);
+  result.title = target;
+  const sessionId = session?.id ?? '';
+
+  let titles;
+  try {
+    titles = ctx?.get?.('sessionTitle');
+  } catch {
+    titles = undefined;
+  }
+  if (titles === undefined || titles === null || typeof titles.rename !== 'function') {
+    result.reason = 'unavailable';
+    log?.warn?.(
+      `compact-relay: 旧会话 ${sessionId} 改名「${target}」失败：sessionTitle 服务不可用（交接已完成，标题保持原样）`,
+    );
+    return result;
+  }
+
+  // 幂等 guard：读得到当前标题时，已是本次目标就跳过（含宿主按更小预算截断的前缀）。
+  // 按宿主 `session-title` 的口径折叠空白再比：宿主会把连续空白压成一个空格，
+  // 不折叠的话同一目标会被误判成「还没改」而重复 append。
+  try {
+    const current = titles.get?.(session)?.title;
+    if (typeof current === 'string' && current.length > 0) {
+      const parsed = splitHandoffTitle(current);
+      const sameHistory = parsed.scheme === 'history-n' && parsed.handedOff === index;
+      if (sameNormalizedTitle(current, target) || (sameHistory && target.startsWith(current))) {
+        result.reason = 'already';
+        return result;
+      }
+    }
+  } catch {
+    /* 读不到当前标题就继续 rename（rename 自己会校验 live/空标题） */
+  }
+
+  let renamed;
+  try {
+    renamed = titles.rename(session, target);
+  } catch (error) {
+    result.reason = 'failed';
+    log?.warn?.(
+      `compact-relay: 旧会话 ${sessionId} 改名「${target}」失败：${errorMessage(error)}（交接已完成，标题保持原样）`,
+    );
+    return result;
+  }
+
+  // 与子会话 rename 一样：快照里的 eventSeq 是链记录要的序号，取不到就留 null（不猜）。
+  if (Number.isInteger(renamed?.eventSeq) && renamed.eventSeq > 0) result.titleSeq = renamed.eventSeq;
+  result.renamed = true;
+
+  try {
+    await ctx?.sessions?.flush?.(session);
+  } catch (error) {
+    log?.warn?.(`compact-relay: 旧会话 ${sessionId} 改名后落盘失败：${errorMessage(error)}`);
+  }
+  return result;
+}
+
 /**
  * 解析子会话要挂的 agent preset，并装配 setup（系统提示/工具/技能组成）。
  * 与官方 composeAgent 同构；preset 解析失败时退回默认 preset。
@@ -176,10 +330,12 @@ export function childAgentOptionsOf(ctx, session, agent) {
  * @param {object} [input.agent] 原 Agent
  * @param {string} input.doc 交接单正文（已含元信息头）
  * @param {string} input.title 新会话标题
+ * @param {string} [input.path] 交接单文件路径（已落盘；传进子会话 relay 记录，拿不到就不写这个键）
+ * @param {object} [input.plan] handoffTitlePlanOf 的结果（不传则现场计算；串起文档/双写记录用同一份）
  * @param {{warn?: Function}} [input.log]
  * @returns {Promise<{childId: string, title: string, workspaceAttached: boolean, started: boolean, docSeq?: number}>}
  */
-export async function createHandoffSession({ ctx, engine, session, agent, doc, title, log }) {
+export async function createHandoffSession({ ctx, engine, session, agent, doc, title, path, plan, log }) {
   if (session === undefined) throw actionError('handoff', '没有可交接的会话');
 
   const childId = `session-${randomUUID()}`;
@@ -228,10 +384,16 @@ export async function createHandoffSession({ ctx, engine, session, agent, doc, t
   }
 
   // 2) 可辨识标题（sessionTitle 服务可选）。
+  //    0.4.4 F3：rename 返回的是折叠后的标题快照（DSH 0.2 形如
+  //    { title, messageSeqs, source, eventSeq, updatedAt }），不是日志事件。
+  //    记下快照里的 eventSeq 供子会话 relay 记录使用；旧宿主/替身没有 eventSeq
+  //    就留 null（不猜）。eventSeq=0 也不收：relay 白名单只认正整数序号。
+  let titleSeq = null;
   try {
     const titles = ctx.get?.('sessionTitle');
     if (titles !== undefined && titles !== null && typeof titles.rename === 'function') {
-      titles.rename(childSession, title);
+      const renamed = titles.rename(childSession, title);
+      if (Number.isInteger(renamed?.eventSeq) && renamed.eventSeq > 0) titleSeq = renamed.eventSeq;
     }
   } catch (error) {
     log?.warn?.(`compact-relay: 新会话 ${childId} 改标题失败：${errorMessage(error)}`);
@@ -271,7 +433,36 @@ export async function createHandoffSession({ ctx, engine, session, agent, doc, t
     }
   }
 
-  // 4) 尽力落盘：新会话的事件尽快持久化，重启后不丢。
+  // 4) 子会话自己带一条接力链记录（自带链号，不再靠标题解析）。
+  //    0.5.0 会把旧会话改名「历史 N：<原名>」、新会话继承原名；那时子会话标题里
+  //    没有「交接第 N 次」，splitHandoffTitle 会算出 handedOff=0，第 2 次交接序号
+  //    就会重复。所以 ordinal/baseTitle/scheme/titleSeq 必须落在子会话自己的日志里。
+  //    写点：followup 之后（新会话首条可见消息仍是交接单）、flush 之前（重启不丢）；
+  //    走 plugin record 通道：ignorable，不进模型上下文、不算 token。
+  //    scheme 与父记录同源（本次链是 handoff-n 还是 history-n），titleSeq 是**子会话**
+  //    rename 返回的 eventSeq；父记录由 lib/actions/handoff.js 另外写，这里只写子会话。
+  //    0.5.0 补：交接单已由调用方落盘，path 一并写进子记录 —— 接力条在子会话里直接
+  //    拿到「查看交接单」的路径，父会话未加载/已归档时不再退化为「暂无交接单」。
+  //    path 拿不到（旧调用方/失败）就不写这个键，不猜、不写空串。
+  const titlePlan = plan ?? handoffTitlePlanOf(ctx, session);
+  const relayAt = Date.now();
+  const relayWrote = writeRelayRecord(engine, childSession, {
+    parentId: session.id,
+    childId,
+    ordinal: titlePlan.index,
+    baseTitle: titlePlan.baseTitle,
+    title,
+    scheme: titlePlan.scheme,
+    titleSeq,
+    ...(typeof path === 'string' && path.length > 0 ? { path } : {}),
+    at: relayAt,
+    atIso: localIso(new Date(relayAt)),
+  });
+  if (!relayWrote) {
+    log?.warn?.(`compact-relay: 新会话 ${childId} 接力链记录写入失败（下次从该会话交接将回退到标题解析）`);
+  }
+
+  // 5) 尽力落盘：新会话的事件尽快持久化，重启后不丢（含上面那条接力链记录）。
   try {
     await ctx.sessions?.flush?.(childSession);
   } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-compact-relay",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "DeepSeek Harness 上下文指示器插件：提供容量监控、压缩预览与确认、九段式交接单生成及消息锁定功能。 · Context indicator for DSH: preview-then-confirm compaction, 9-section session handoff, and pinned messages.",
   "type": "module",
   "main": "lib/index.js",
@@ -53,7 +53,7 @@
     "node": ">=22"
   },
   "scripts": {
-    "test": "node scripts/build-client.mjs --check && node --check lib/client.js && node test/smoke.mjs && node test/handoff.mjs && node test/plugin-load.mjs && node test/contract.mjs && node test/compact-log.mjs && node test/compress-cue.mjs && node test/state-passive.mjs && node test/native-compaction.mjs && node test/markdown-lite.mjs && node test/diagnostics.mjs && node test/pin-contract.mjs && node test/ledger.mjs && node test/handoff-p2.mjs && node test/native-line.mjs && node test/handoff-guard.mjs && node test/settings-ux.mjs",
+    "test": "node scripts/build-client.mjs --check && node --check lib/client.js && node test/smoke.mjs && node test/handoff.mjs && node test/plugin-load.mjs && node test/contract.mjs && node test/compact-log.mjs && node test/compress-cue.mjs && node test/state-passive.mjs && node test/native-compaction.mjs && node test/markdown-lite.mjs && node test/clip.mjs && node test/diagnostics.mjs && node test/pin-contract.mjs && node test/ledger.mjs && node test/handoff-p2.mjs && node test/relay-title-scheme.mjs && node test/relay-chain.mjs && node test/relay-chain-endpoint.mjs && node test/handoff-naming.mjs && node test/native-line.mjs && node test/handoff-guard.mjs && node test/settings-ux.mjs && node test/pin-health.mjs && node test/archive.mjs && node test/relay-bar.mjs",
     "test:e2e": "node test/e2e/smoke.mjs",
     "test:e2e:settings": "node test/e2e/settings-ui.mjs",
     "test:e2e:settings-ux": "node test/e2e/settings-ux.mjs",