dsh-compact-relay 0.4.2 → 0.5.0

package/lib/core/relay.js

@@ -8,6 +8,45 @@
 /** 会话日志里记录 relay 的类型（与压缩判断记录/pin 的 plugin record 同前缀）。 */
 export const RELAY_RECORD_TYPE = 'plugin:compact-relay/relay';
 
+/** 历史标题前缀（0.5.0 命名反转：历史 N：<原名>）。 */
+export const HISTORY_PREFIX = '历史';
+
+/**
+ * 会话标题的 UTF-8 字节预算 —— 与 DSH `session-title` 的默认 `maxTitleBytes` 一致。
+ *
+ * 宿主 `sessionTitle.rename()` 会按这个预算把标题从尾部截断；前缀也算预算。
+ * 插件先自己按同一口径缩 base，保证「历史 N：」前缀不会被宿主的尾部截断吃掉。
+ */
+export const MAX_TITLE_BYTES = 80;
+
+/** 「历史 N：」标题的正则；空白/半角冒号的容忍度与下面的「交接第 N 次：」一致。 */
+const HISTORY_TITLE_RE = new RegExp(`^${HISTORY_PREFIX}\\s*(\\d+)\\s*[：:]\\s*([\\s\\S]*)$`);
+
+/**
+ * 按 UTF-8 字节预算截断标题（不切坏多字节字符 / 代理对）。
+ *
+ * 与 DSH `session-title` 的 `truncateTitleUtf8` 同口径：取「能放进预算的最长前缀」，
+ * 不补省略号（补了会占预算，也会让前缀解析多一个尾巴）。
+ * maxBytes 非法/缺失时原样返回（纯函数层保持旧行为，预算只在调用方显式传入时生效）。
+ * @param {string} input
+ * @param {number} [maxBytes]
+ * @returns {string}
+ */
+export function truncateTitleUtf8(input, maxBytes) {
+  if (typeof input !== 'string') return '';
+  if (!Number.isInteger(maxBytes) || maxBytes <= 0) return input;
+  if (Buffer.byteLength(input, 'utf8') <= maxBytes) return input;
+  let used = 0;
+  let output = '';
+  for (const character of input) {
+    const bytes = Buffer.byteLength(character, 'utf8');
+    if (used + bytes > maxBytes) break;
+    output += character;
+    used += bytes;
+  }
+  return output;
+}
+
 /**
  * 标题统一格式：交接第 N 次：<原始标题>。
  * @param {number} index
@@ -19,20 +58,58 @@ export function relayTitleOf(index, baseTitle) {
   return `交接第 ${index} 次：${base}`;
 }
 
+/**
+ * 历史标题统一格式：历史 N：<原始标题>。
+ *
+ * 空格位置/全角冒号/序号写法与 relayTitleOf 完全一致（序号不补零、不换算）；
+ * 原名先 trim，空/非字符串回落「会话」。
+ *
+ * 0.5.0 可选第三参 `maxBytes`：给 UTF-8 字节预算时，**前缀先计入预算、超长只缩 base**，
+ * 保证宿主按 maxTitleBytes 截断时不会把「历史 N：」本身截掉。
+ * 不传时保持 0.4.3 的纯函数行为（不截断）。
+ * @param {number} index
+ * @param {string} [baseTitle]
+ * @param {number} [maxBytes]
+ * @returns {string}
+ */
+export function historyTitleOf(index, baseTitle, maxBytes) {
+  const base = typeof baseTitle === 'string' && baseTitle.trim().length > 0 ? baseTitle.trim() : '会话';
+  if (!Number.isInteger(maxBytes) || maxBytes <= 0) return `${HISTORY_PREFIX} ${index}：${base}`;
+  const prefix = `${HISTORY_PREFIX} ${index}：`;
+  const budget = maxBytes - Buffer.byteLength(prefix, 'utf8');
+  // 预算连 base 都放不下时只保留前缀（宿主最多再截一次前缀，至少不会切坏字符）。
+  if (budget <= 0) return prefix;
+  const fitted = truncateTitleUtf8(base, budget).trimEnd() || truncateTitleUtf8('会话', budget);
+  return `${prefix}${fitted}`;
+}
+
 /**
  * 从任意文本里剥掉现代/历史交接前缀，拿到原始标题。
  * 旧格式（「交接：」/「接棒：」可堆叠）只在读旧标题时兼容，不删除会话标题。
+ *
+ * 0.4.3 F1：返回值新增 `scheme`（只增不改，baseTitle/handedOff 的名字与语义不变）：
+ *  - 'handoff-n'：「交接第 N 次：」；
+ *  - 'history-n'：「历史 N：」；
+ *  - 'legacy'：其余（旧「交接：」/「接棒：」堆叠、无前缀、空/脏输入回落）。
  * @param {string|undefined} title
- * @returns {{baseTitle:string, handedOff:number}}
+ * @returns {{baseTitle:string, handedOff:number, scheme:'handoff-n'|'history-n'|'legacy'}}
  */
 export function splitHandoffTitle(title) {
-  if (typeof title !== 'string' || title.trim().length === 0) return { baseTitle: '会话', handedOff: 0 };
-  const modern = /^交接第\s*(\d+)\s*次[：:]\s*([\s\S]*)$/.exec(title.trim());
+  if (typeof title !== 'string' || title.trim().length === 0) {
+    return { baseTitle: '会话', handedOff: 0, scheme: 'legacy' };
+  }
+  const trimmed = title.trim();
+  const modern = /^交接第\s*(\d+)\s*次[：:]\s*([\s\S]*)$/.exec(trimmed);
   if (modern !== null) {
     const base = modern[2].trim();
-    return { baseTitle: base.length > 0 ? base : '会话', handedOff: Number.parseInt(modern[1], 10) };
+    return { baseTitle: base.length > 0 ? base : '会话', handedOff: Number.parseInt(modern[1], 10), scheme: 'handoff-n' };
+  }
+  const history = HISTORY_TITLE_RE.exec(trimmed);
+  if (history !== null) {
+    const base = history[2].trim();
+    return { baseTitle: base.length > 0 ? base : '会话', handedOff: Number.parseInt(history[1], 10), scheme: 'history-n' };
   }
-  let base = title.trim();
+  let base = trimmed;
   let handedOff = 0;
   for (;;) {
     const match = /^(?:交接|接棒)[：:]\s*/.exec(base);
@@ -41,5 +118,5 @@ export function splitHandoffTitle(title) {
     handedOff += 1;
   }
   const clean = base.trim();
-  return { baseTitle: clean.length > 0 ? clean : '会话', handedOff };
+  return { baseTitle: clean.length > 0 ? clean : '会话', handedOff, scheme: 'legacy' };
 }

package/lib/dsh/handoff-archive.js

@@ -0,0 +1,179 @@
+/**
+ * 0.5.0：交接成功后归档旧会话的宿主接缝（best effort，绝不阻断交接）。
+ *
+ * 宿主实证（DeepSeek Harness 0.2.1-rc.3 app.asar）：
+ *   - `@deepseek-ai/dsh-workspace/lib/index.js`：`WorkspaceRegistry.archiveSession(sessionId, options)`
+ *     不带 `stopActivity` 时先跑 `workspace/session-activity` waterfall；任何 provider
+ *     （运行中的 turn / subagent / job / schedule）报活都会在写盘前抛
+ *     `WorkspaceActiveSessionError`（带 `activity` 数组）。
+ *   - 带 `stopActivity: true` 时跳过活动检查、先写归档集合，再 `workspace/session-stop`
+ *     把旧会话的 turn/subagent/job/schedule 停掉。**自动交接不替用户做这个决定**：
+ *     静默取消后台任务比「旧会话多留一行」破坏性大得多，所以本插件永远不传
+ *     `stopActivity`；只对「正在收尾的 turn」做有限次等待重试，仍活跃就降级为不归档。
+ *   - `WorkspaceRegistry.unarchiveSession(sessionId)` 幂等，且不做存在性探测；
+ *     不在归档集合里的 id 直接 no-op。恢复入口可以放心重复调用。
+ *   - `archivedSessionIds` 是 registry 全局归档集合；归档不改变 workspace 成员关系，
+ *     恢复后回到原位（dsh-workspace/lib/index.js 的注释与 README 同口径）。
+ *
+ * 插件侧访问路径：`ctx.get('workspaceRegistry')`。本插件 `lib/dsh/sessions.js`
+ * 建子会话时已经用同一个服务 `create(cwd)`/`attachSession(id)`，不是新接缝。
+ */
+
+/** 宿主归档集合里是否有这个会话；服务不可用/形状异常 → null（不知道，不猜 false）。 */
+export function archivedSessionIdsOf(ctx) {
+  try {
+    const registry = ctx?.get?.('workspaceRegistry');
+    const ids = registry?.archivedSessionIds;
+    return Array.isArray(ids) ? ids : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 旧会话当前是否在归档集合里。
+ * @param {object} ctx
+ * @param {string} sessionId
+ * @returns {boolean|null} null = 宿主没提供可读的归档状态
+ */
+export function isSessionArchived(ctx, sessionId) {
+  if (typeof sessionId !== 'string' || sessionId.length === 0) return null;
+  const ids = archivedSessionIdsOf(ctx);
+  return ids === null ? null : ids.includes(sessionId);
+}
+
+/**
+ * 取 workspace registry；拿不到/没有 archiveSession 时 null。
+ * @param {object} ctx
+ * @returns {object|null}
+ */
+export function workspaceRegistryOf(ctx) {
+  try {
+    const registry = ctx?.get?.('workspaceRegistry');
+    return registry !== null && registry !== undefined && typeof registry === 'object' ? registry : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 错误里的活动族（turn/subagent/job/schedule…）；只用于提示，不参与归档决策。 */
+function activityKindsOf(error) {
+  if (error === null || typeof error !== 'object' || !Array.isArray(error.activity)) return [];
+  const kinds = [];
+  for (const entry of error.activity) {
+    const kind = entry !== null && typeof entry === 'object' ? entry.kind : undefined;
+    if (typeof kind === 'string' && kind.length > 0 && !kinds.includes(kind)) kinds.push(kind);
+  }
+  return kinds;
+}
+
+function errorMessageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function wait(ms) {
+  if (!Number.isFinite(ms) || ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isActiveError(error) {
+  if (error === null || typeof error !== 'object') return false;
+  return (
+    error.name === 'WorkspaceActiveSessionError' ||
+    error.code === 'workspace/session-active' ||
+    Array.isArray(error.activity)
+  );
+}
+
+/**
+ * 归档交接后的旧会话（best effort）。
+ *
+ * 语义：
+ *   - 已归档 → `already`（幂等；不重复写盘）；
+ *   - 成功 → `archived`；
+ *   - 旧会话还有活（turn/subagent/job/schedule）→ 等短暂的空闲重试机会，仍活跃就
+ *     `active`，**不 stopActivity**；
+ *   - 宿主没有 registry/archiveSession → `unavailable`；
+ *   - 宿主找不到会话 / 写盘失败 → `unknown` / `failed`。
+ * 任何分支都不抛错；调用方只需要把返回结果写进提示/日志。
+ *
+ * @param {object} ctx 根上下文
+ * @param {string} sessionId 旧会话 id
+ * @param {{log?:{warn?:Function}, attempts?:number, delayMs?:number}} [options]
+ * @returns {Promise<{status:'already'|'archived'|'unavailable'|'active'|'unknown'|'failed', archived:boolean, activityKinds:string[]}>}
+ */
+export async function archiveHandoffSource(ctx, sessionId, { log, attempts = 2, delayMs = 150 } = {}) {
+  const failed = (status, activityKinds = []) => ({ status, archived: false, activityKinds });
+  if (typeof sessionId !== 'string' || sessionId.length === 0) return failed('unknown');
+
+  const registry = workspaceRegistryOf(ctx);
+  if (registry === null || typeof registry.archiveSession !== 'function') {
+    log?.warn?.('compact-relay: 旧会话未归档：宿主没有 workspaceRegistry.archiveSession（交接已完成）');
+    return failed('unavailable');
+  }
+
+  // 幂等：重复交接/上一次已经归档成功时不再写盘，也不触发活动检查。
+  if (isSessionArchived(ctx, sessionId) === true) return { status: 'already', archived: true, activityKinds: [] };
+
+  const totalAttempts = Number.isInteger(attempts) && attempts > 0 ? attempts : 1;
+  let lastError = null;
+  for (let attempt = 1; attempt <= totalAttempts; attempt += 1) {
+    try {
+      await registry.archiveSession(sessionId);
+      return { status: 'archived', archived: true, activityKinds: [] };
+    } catch (error) {
+      lastError = error;
+      const active = isActiveError(error);
+      const kinds = activityKindsOf(error);
+      // 只对「还在跑」等一等：交接命令刚返回时，旧会话里可能有一个 turn 正在收尾；
+      // 默认等 150ms 再试一次，仍活跃就放弃，绝不自动 stopActivity。
+      if (active && attempt < totalAttempts) {
+        await wait(delayMs * attempt);
+        continue;
+      }
+      if (active) {
+        const label = kinds.length > 0 ? kinds.join('/') : 'active';
+        log?.warn?.(
+          `compact-relay: 旧会话 ${sessionId} 归档失败：仍有任务在跑（${label}）；不自动停止任务，旧会话保持可见（交接已完成）`,
+        );
+        return failed('active', kinds);
+      }
+      if (error !== null && typeof error === 'object' && error.name === 'WorkspaceUnknownSessionError') {
+        log?.warn?.(`compact-relay: 旧会话 ${sessionId} 归档失败：宿主里找不到该会话（${errorMessageOf(error)}）；交接已完成`);
+        return failed('unknown');
+      }
+      log?.warn?.(`compact-relay: 旧会话 ${sessionId} 归档失败：${errorMessageOf(error)}（交接已完成）`);
+      return failed('failed');
+    }
+  }
+  // 理论上循环里已经返回；留一个不抛错的兜底。
+  log?.warn?.(`compact-relay: 旧会话 ${sessionId} 归档失败：${errorMessageOf(lastError)}（交接已完成）`);
+  return failed(isActiveError(lastError) ? 'active' : 'failed', activityKindsOf(lastError));
+}
+
+/**
+ * 归档结果 → 交接完成 message 里的一行（成功/失败都不丢信息）。
+ * 成功时明确告诉用户恢复入口；失败时固定写「归档失败，不影响交接」。
+ * @param {{status:string, archived:boolean, activityKinds?:string[]}} result
+ * @returns {string}
+ */
+export function handoffArchiveNoteOf(result) {
+  const status = result !== null && typeof result === 'object' ? result.status : 'failed';
+  if (status === 'archived') {
+    return '旧会话已归档（可在新会话输入框上方「已接力自 …」→「恢复旧会话」找回；侧栏视图选「全部会话」也能取消归档）。';
+  }
+  if (status === 'already') {
+    return '旧会话此前已在归档中（可在新会话输入框上方「已接力自 …」→「恢复旧会话」找回）。';
+  }
+  const kinds = Array.isArray(result?.activityKinds) && result.activityKinds.length > 0 ? result.activityKinds.join('/') : null;
+  if (status === 'active') {
+    return `旧会话归档失败，不影响交接（仍有任务在跑：${kinds ?? 'active'}；不自动停止任务，旧会话仍在列表里）。`;
+  }
+  if (status === 'unavailable') {
+    return '旧会话归档失败，不影响交接（当前宿主没有 workspace 归档接口；旧会话仍在列表里）。';
+  }
+  if (status === 'unknown') {
+    return '旧会话归档失败，不影响交接（宿主里找不到该会话）。';
+  }
+  return '旧会话归档失败，不影响交接（旧会话仍在列表里）。';
+}

package/lib/dsh/relay.js

@@ -7,14 +7,23 @@
  */
 import { RELAY_RECORD_TYPE } from '../core/relay.js';
 
+/** relay 记录里允许的标题方案（0.5.0 命名反转的两种新标题；legacy 不写进记录）。 */
+const RECORD_SCHEMES = new Set(['handoff-n', 'history-n']);
+
 /**
  * 合法化一条 relay 记录；不合法返回 null。
  *
  * 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,6 +52,10 @@ 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,
   };
 }
 
@@ -63,6 +76,31 @@ export function relayRecordOf(session) {
   return null;
 }
 
+/**
+ * 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/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) {