dsh-compact-relay 0.4.1 → 0.5.0

package/lib/core/handoff-guard.js

@@ -0,0 +1,219 @@
+/**
+ * 交接线保命判定 —— 纯函数，零依赖（0.4.2）。
+ *
+ * 背景（0.4.1 遗留的三个洞，见 docs/0.4.2-implementation-plan.md）：
+ * 1. 交接提醒线仍是配置值（默认 60%），换到实际触发线更低的模型（如 55%）时，
+ *    DSH 会先自己压历史，dcr 的交接提醒来不及；
+ * 2. 服务端保存校验只看配置阈值（80%），手改设置文件能设到 70%；
+ * 3. 旧值不跟随当前模型，除设置页一行 warning 外没有其它可见提示。
+ *
+ * 0.4.2 规则（范围定稿）：
+ *   交接提醒线 ≤ 实际触发线 − 5pp（HANDOFF_MARGIN_PP），向下取整到整数百分位。
+ *   - 实际触发线来自 state.native.ratio（按当前路由模型实时算，见 core/native-line.js）；
+ *   - 实际线算不出时：运行时不告警、不阻断；服务端保存退回配置阈值防呆（0.4.1 行为）；
+ *   - DSH 原生自动压缩关闭时不存在「被抢先压缩」的截止线，不判定；
+ *   - 只告警 / 拒绝，绝不静默改写用户配置。
+ *
+ * 本模块只做判定与文案，不做 IO：服务端 `lib/actions/settings.js` 直接 import，
+ * 客户端由 `scripts/build-client.mjs` 的 `/* @inline core/handoff-guard.js *\/`
+ * 内联进 `lib/client.js`（同一份判定，避免 UI 与后台两套口径）。
+ */
+
+/** 交接线相对实际触发线至少留 5 个百分点（1M 窗口 ≈ 50K tokens 缓冲）。 */
+export const HANDOFF_MARGIN_PP = 5;
+
+/** 实际线算不出、退回配置阈值防呆时的余量（0.4.1 口径：最高 = 配置阈值 −1pp）。 */
+export const FALLBACK_MARGIN_PP = 1;
+
+/** cap 的绝对上限（避免算出 96%+ 这种没有意义的上限）。 */
+export const HANDOFF_LIMIT_DEFAULT = 0.95;
+
+const EPS = 1e-9;
+
+/**
+ * 合法窗口比例：必须是 0<r<1 的有限数。
+ * @param {unknown} value
+ * @returns {number|null}
+ */
+function ratioOf(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 && value < 1 ? value : null;
+}
+
+/**
+ * 比例 → 百分数数字（一位小数，整数不带小数）：0.678 → 67.8，0.62 → 62。
+ * @param {number|null} ratio
+ * @returns {number|null}
+ */
+function percentOf(ratio) {
+  if (ratio === null) return null;
+  const percent = ratio * 100;
+  return Math.abs(percent - Math.round(percent)) < 0.05 ? Math.round(percent) : Number(percent.toFixed(1));
+}
+
+/**
+ * 比例 → 百分数文本（用于文案）：0.678 → '67.8'，0.62 → '62'。
+ * @param {number|null} ratio
+ * @returns {string}
+ */
+function percentText(ratio) {
+  if (ratio === null) return '';
+  const percent = ratio * 100;
+  return Math.abs(percent - Math.round(percent)) < 0.05 ? String(Math.round(percent)) : percent.toFixed(1);
+}
+
+/**
+ * 只算交接线上限：参考线 − marginPp，向下取整到整数百分位，再夹到 limit。
+ *
+ * 浮点安全：`0.62 − 0.05` 在二进制里可能是 0.5700000000000001 / 0.5699999999999999，
+ * 直接 floor 会把 57 变成 56，所以加 EPS 再 floor。
+ *
+ * @param {number|null} referenceRatio 参考线（实际触发线或配置阈值），非法时返回 null
+ * @param {{marginPp?:number, limit?:number}} [options]
+ * @returns {number|null} 例如 0.62；参考线太小（减完 ≤0）时返回 null
+ */
+export function handoffCapOf(referenceRatio, { marginPp = HANDOFF_MARGIN_PP, limit = HANDOFF_LIMIT_DEFAULT } = {}) {
+  const reference = ratioOf(referenceRatio);
+  if (reference === null) return null;
+  const margin = (Number.isFinite(marginPp) ? marginPp : HANDOFF_MARGIN_PP) / 100;
+  const max = Number.isFinite(limit) && limit > 0 && limit < 1 ? limit : HANDOFF_LIMIT_DEFAULT;
+  // 向下取整到整数百分位（例如 62.8 → 0.62），不是四舍五入。
+  const cap = Math.floor((reference - margin) * 100 + EPS) / 100;
+  if (!(cap > 0)) return null;
+  return Math.min(cap, max);
+}
+
+/** 「重算目标 ≤ 压缩线」时的补充提示（保持「交接线 > 压缩线」现有约束）。 */
+function compactConflictText(capPercent, compactRatio) {
+  return `按实际线重算目标 ${capPercent}% 不高于压缩线 ${percentText(compactRatio)}%，请先把压缩线降到 ${capPercent}% 以下。`;
+}
+
+/**
+ * 判定「当前交接线是否会在 DSH 原生压缩之后」。
+ *
+ * @param {object} [input]
+ * @param {number|null} [input.actualRatio] 当前模型实际触发线（state.native.ratio）；算不出/关闭时 null
+ * @param {number|null} [input.configuredRatio] 配置阈值（native.thresholdRatio），兜底用
+ * @param {number|null} [input.handoffRatio] 当前交接提醒线（thresholds.handoffRatio）
+ * @param {number|null} [input.compactRatio] 压缩提醒线（thresholds.compactRatio），判重算冲突
+ * @param {boolean} [input.autoEnabled] DSH 原生自动压缩是否开启（false → 不判定，交接线无截止线）
+ * @param {number} [input.limit] cap 绝对上限，默认 0.95
+ * @param {'none'|'configured'} [input.fallback]
+ *   'none'（运行时默认）：实际线算不出就不判定（不告警、不阻断）；
+ *   'configured'（服务端保存默认）：实际线算不出时按配置阈值 −1pp 防呆（0.4.1 行为）。
+ * @returns {{
+ *   source:'actual'|'configured'|null,
+ *   actualRatio:number|null, actualPercent:number|null,
+ *   configuredRatio:number|null, configuredPercent:number|null,
+ *   handoffRatio:number|null, handoffPercent:number|null,
+ *   compactRatio:number|null, compactPercent:number|null,
+ *   cap:number|null, capPercent:number|null,
+ *   ok:boolean, severity:'ok'|'warn'|'late'|'unknown',
+ *   reason:'ok'|'late'|'margin'|'fallback'|'no-reference'|'invalid-handoff'|'no-cap',
+ *   message:string, target:number|null, compactConflict:boolean
+ * }}
+ */
+export function handoffGuard({
+  actualRatio = null,
+  configuredRatio = null,
+  handoffRatio = null,
+  compactRatio = null,
+  autoEnabled = true,
+  limit = HANDOFF_LIMIT_DEFAULT,
+  fallback = 'none',
+} = {}) {
+  const actual = ratioOf(actualRatio);
+  const configured = ratioOf(configuredRatio);
+  const handoff = ratioOf(handoffRatio);
+  const compact = ratioOf(compactRatio);
+  const neutral = {
+    source: null,
+    actualRatio: actual,
+    actualPercent: percentOf(actual),
+    configuredRatio: configured,
+    configuredPercent: percentOf(configured),
+    handoffRatio: handoff,
+    handoffPercent: percentOf(handoff),
+    compactRatio: compact,
+    compactPercent: percentOf(compact),
+    cap: null,
+    capPercent: null,
+    ok: true,
+    severity: 'unknown',
+    reason: 'no-reference',
+    message: '',
+    target: null,
+    compactConflict: false,
+  };
+  // 原生自动压缩关着：DSH 不会自己压，不存在「提醒来不及」的截止线。
+  if (autoEnabled === false) return neutral;
+
+  /** 带 cap 的结果骨架（cap 已是整数百分位，×100 即整数）。 */
+  const withCap = (source, cap) => {
+    const capPercent = cap === null ? null : Math.round(cap * 100);
+    return {
+      ...neutral,
+      source,
+      cap,
+      capPercent,
+      target: source === 'actual' ? cap : null,
+      compactConflict: cap !== null && compact !== null && cap <= compact + EPS,
+    };
+  };
+
+  // 1) 实际触发线可用：唯一口径（−5pp），不再叠加「配置阈值 −1pp」。
+  if (actual !== null) {
+    const cap = handoffCapOf(actual, { limit });
+    if (cap === null) return { ...withCap('actual', null), reason: 'no-cap' };
+    const base = withCap('actual', cap);
+    if (handoff === null) return { ...base, reason: 'invalid-handoff' };
+    const conflict = base.compactConflict ? compactConflictText(base.capPercent, compact) : '';
+    // 等于实际触发线也算「晚」：DSH 会在同一位置自己压历史，提醒来不及。
+    if (handoff > actual - EPS) {
+      return {
+        ...base,
+        ok: false,
+        severity: 'late',
+        reason: 'late',
+        message:
+          `交接线已晚：当前模型实际触发 ${percentText(actual)}%，交接线 ${percentText(handoff)}% 会在原生压缩之后` +
+          `（DSH 会先压历史）；最高可设 ${base.capPercent}%。${conflict}`,
+      };
+    }
+    if (handoff > cap + EPS) {
+      return {
+        ...base,
+        ok: false,
+        severity: 'warn',
+        reason: 'margin',
+        message:
+          `交接线偏晚：当前模型实际触发 ${percentText(actual)}%，交接线 ${percentText(handoff)}% ` +
+          `距原生压缩不足 ${HANDOFF_MARGIN_PP} 个百分点；最高可设 ${base.capPercent}%。${conflict}`,
+      };
+    }
+    return { ...base, ok: true, severity: 'ok', reason: 'ok' };
+  }
+
+  // 2) 实际线算不出 + 服务端保存：退回配置阈值防呆（0.4.1 行为，兼容旧客户端）。
+  if (fallback === 'configured' && configured !== null) {
+    const cap = handoffCapOf(configured, { marginPp: FALLBACK_MARGIN_PP, limit });
+    if (cap === null) return { ...withCap('configured', null), reason: 'no-cap' };
+    const base = withCap('configured', cap);
+    if (handoff === null) return { ...base, reason: 'invalid-handoff' };
+    if (handoff > cap + EPS) {
+      return {
+        ...base,
+        ok: false,
+        severity: 'warn',
+        reason: 'fallback',
+        message:
+          `「交接提醒线」必须低于 DSH 原生自动压缩线（配置阈值 ${percentText(configured)}%），` +
+          `否则原生压缩会先动手；最高只能设到 ${base.capPercent}%。` +
+          '想设更高请先在设置里关闭「DSH 原生自动压缩」。',
+      };
+    }
+    return { ...base, ok: true, severity: 'ok', reason: 'ok' };
+  }
+
+  // 3) 运行时且算不出：不告警、不阻断。
+  return neutral;
+}

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