dsh-compact-relay 0.4.2 → 0.5.1

package/lib/dsh/handoff-archive.js

@@ -0,0 +1,225 @@
+/**
+ * 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));
+}
+
+/**
+ * 宿主侧栏置顶集合（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 里的一行（成功/失败都不丢信息）。
+ * 成功时明确告诉用户恢复入口；失败时固定写「归档失败，不影响交接」。
+ * @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') {
+    // 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'}；不自动停止任务，旧会话仍在列表里）。`;
+  }
+  if (status === 'unavailable') {
+    return '旧会话归档失败，不影响交接（当前宿主没有 workspace 归档接口；旧会话仍在列表里）。';
+  }
+  if (status === 'unknown') {
+    return '旧会话归档失败，不影响交接（宿主里找不到该会话）。';
+  }
+  return '旧会话归档失败，不影响交接（旧会话仍在列表里）。';
+}

package/lib/dsh/native-compaction.js

@@ -71,6 +71,9 @@ const CONFIG_RE = /^(\s*)config\s*:\s*(?:#.*)?$/;
 const AUTO_RE = /^auto\s*:\s*(true|false)\s*(?:#.*)?$/;
 const RATIO_RE = /^thresholdRatio\s*:\s*['"]?([0-9.]+)['"]?\s*(?:#.*)?$/;
 const HEADROOM_RE = /^headroomTokens\s*:\s*['"]?(\d+)['"]?\s*(?:#.*)?$/;
+/** 0.5.1 批 2：保留近期尾部的两种写法（compaction-basic 的 retainRatio / retainTokens）。 */
+const RETAIN_RATIO_RE = /^retainRatio\s*:\s*['"]?([0-9.]+)['"]?\s*(?:#.*)?$/;
+const RETAIN_TOKENS_RE = /^retainTokens\s*:\s*['"]?(\d+)['"]?\s*(?:#.*)?$/;
 /** modelPolicies 列表项里的键（- provider: x / model: y / thresholdRatio: 0.5 / headroomTokens: 4096）。 */
 const POLICY_PROVIDER_RE = /^provider\s*:\s*['"]?([^'"#\s]+)['"]?\s*(?:#.*)?$/;
 const POLICY_MODEL_RE = /^model\s*:\s*['"]?([^'"#\s]+)['"]?\s*(?:#.*)?$/;
@@ -196,6 +199,23 @@ export function parseCompactionOverride(text) {
       if (Number.isInteger(value) && value >= 0) override.headroomTokens = value;
     }
   }
+  // 0.5.1 批 2：原生压缩保留尾部预算（预判「会覆盖哪些 pin」用；不改原生行为）。
+  const retainRatioIndex = findDirectChild(lines, entry, config, RETAIN_RATIO_RE);
+  if (retainRatioIndex >= 0) {
+    const match = RETAIN_RATIO_RE.exec(lines[retainRatioIndex].trim());
+    if (match !== null) {
+      const value = Number(match[1]);
+      if (Number.isFinite(value) && value >= 0 && value < 1) override.retainRatio = value;
+    }
+  }
+  const retainTokensIndex = findDirectChild(lines, entry, config, RETAIN_TOKENS_RE);
+  if (retainTokensIndex >= 0) {
+    const match = RETAIN_TOKENS_RE.exec(lines[retainTokensIndex].trim());
+    if (match !== null) {
+      const value = Number(match[1]);
+      if (Number.isInteger(value) && value >= 0) override.retainTokens = value;
+    }
+  }
   return override;
 }
 
@@ -230,7 +250,14 @@ export function parseModelPolicies(text) {
   let current = null;
   const flush = () => {
     if (current === null) return;
-    if (current.thresholdRatio !== undefined || current.headroomTokens !== undefined) policies.push(current);
+    if (
+      current.thresholdRatio !== undefined ||
+      current.headroomTokens !== undefined ||
+      current.retainRatio !== undefined ||
+      current.retainTokens !== undefined
+    ) {
+      policies.push(current);
+    }
     current = null;
   };
   for (let index = start + 1; index < entry.end; index += 1) {
@@ -253,9 +280,18 @@ export function parseModelPolicies(text) {
     const trimmed = line.trim();
     const ratioMatch = RATIO_RE.exec(trimmed);
     const headMatch = HEADROOM_RE.exec(trimmed);
+    const retainRatioMatch = RETAIN_RATIO_RE.exec(trimmed);
+    const retainTokensMatch = RETAIN_TOKENS_RE.exec(trimmed);
     const providerMatch = POLICY_PROVIDER_RE.exec(trimmed);
     const modelMatch = POLICY_MODEL_RE.exec(trimmed);
-    if (ratioMatch !== null || headMatch !== null || providerMatch !== null || modelMatch !== null) {
+    if (
+      ratioMatch !== null ||
+      headMatch !== null ||
+      retainRatioMatch !== null ||
+      retainTokensMatch !== null ||
+      providerMatch !== null ||
+      modelMatch !== null
+    ) {
       if (current === null) current = { provider: null, model: null };
       if (ratioMatch !== null) {
         const value = Number(ratioMatch[1]);
@@ -263,6 +299,12 @@ export function parseModelPolicies(text) {
       } else if (headMatch !== null) {
         const value = Number(headMatch[1]);
         if (Number.isInteger(value) && value >= 0) current.headroomTokens = value;
+      } else if (retainRatioMatch !== null) {
+        const value = Number(retainRatioMatch[1]);
+        if (Number.isFinite(value) && value >= 0 && value < 1) current.retainRatio = value;
+      } else if (retainTokensMatch !== null) {
+        const value = Number(retainTokensMatch[1]);
+        if (Number.isInteger(value) && value >= 0) current.retainTokens = value;
       } else if (providerMatch !== null) current.provider = providerMatch[1];
       else current.model = modelMatch[1];
       continue;
@@ -286,8 +328,13 @@ export function parseModelPolicies(text) {
 export function resolveNativePolicy(nativeCfg, route) {
   const globalRatio = Number.isFinite(nativeCfg?.thresholdRatio) ? nativeCfg.thresholdRatio : NATIVE_DEFAULTS.thresholdRatio;
   const globalHeadroom = Number.isFinite(nativeCfg?.headroomTokens) ? nativeCfg.headroomTokens : NATIVE_HEADROOM_DEFAULT;
+  // 0.5.1 批 2：保留尾部预算（不配置 = undefined，由 core/native-line 按宿主默认比值算）。
+  const globalRetain = {
+    ...(Number.isFinite(nativeCfg?.retainRatio) ? { retainRatio: nativeCfg.retainRatio } : {}),
+    ...(Number.isInteger(nativeCfg?.retainTokens) ? { retainTokens: nativeCfg.retainTokens } : {}),
+  };
   if (route === null || route === undefined || typeof route.provider !== 'string' || typeof route.model !== 'string') {
-    return { thresholdRatio: globalRatio, headroomTokens: globalHeadroom, overridden: false };
+    return { thresholdRatio: globalRatio, headroomTokens: globalHeadroom, overridden: false, ...globalRetain };
   }
   const list = Array.isArray(nativeCfg?.modelPolicies) ? nativeCfg.modelPolicies : [];
   const hit = list.find(
@@ -297,11 +344,17 @@ export function resolveNativePolicy(nativeCfg, route) {
       (policy.model === route.model || policy.model === `${route.provider}/${route.model}` || policy.model === null || policy.model === undefined) &&
       (policy.provider === undefined || policy.provider === null || policy.provider === route.provider),
   );
-  if (hit === undefined) return { thresholdRatio: globalRatio, headroomTokens: globalHeadroom, overridden: false };
+  if (hit === undefined) return { thresholdRatio: globalRatio, headroomTokens: globalHeadroom, overridden: false, ...globalRetain };
+  const routeRetain = {
+    ...(Number.isFinite(hit.retainRatio) ? { retainRatio: hit.retainRatio } : {}),
+    ...(Number.isInteger(hit.retainTokens) ? { retainTokens: hit.retainTokens } : {}),
+  };
   return {
     thresholdRatio: Number.isFinite(hit.thresholdRatio) ? hit.thresholdRatio : globalRatio,
     headroomTokens: Number.isFinite(hit.headroomTokens) ? hit.headroomTokens : globalHeadroom,
     overridden: true,
+    ...globalRetain,
+    ...routeRetain,
   };
 }
 
@@ -331,6 +384,9 @@ export function readNativeCompaction(profileDir = resolveProfileDir()) {
     thresholdRatio: override.thresholdRatio ?? NATIVE_DEFAULTS.thresholdRatio,
     // 0.4 P2-3：真实触发线要用的余量与路由级覆盖（additive 字段，老调用方不受影响）。
     headroomTokens: override.headroomTokens ?? NATIVE_HEADROOM_DEFAULT,
+    // 0.5.1 批 2：保留尾部预算（未配置时 undefined，由 nativeRetainTokensOf 按宿主默认比值算）。
+    ...(override.retainRatio === undefined ? {} : { retainRatio: override.retainRatio }),
+    ...(override.retainTokens === undefined ? {} : { retainTokens: override.retainTokens }),
     modelPolicies: parseModelPolicies(text),
     override,
     file,

package/lib/dsh/relay-chain.js

@@ -0,0 +1,238 @@
+/**
+ * 完整交接链的服务端读取（0.5.1 DCR-05）。
+ *
+ * 背景：0.5.1 批 3 的「完整交接链」由客户端逐级 GET `/api/compact-relay-state?sessionId=父id`。
+ * 宿主对**没加载进内存**的会话返回 `sessionId:null`（readState 的 target 为 null），
+ * 客户端只能停在断点。重启后祖先会话通常都没加载，因此「只显示 1 层」是常态而非例外。
+ *
+ * 宿主实证（DeepSeek Harness 0.2.1-rc.3 app.asar）：
+ *   - `@deepseek-ai/dsh-session-persistence`：根服务 `ctx.sessionPersistence`
+ *     - `stat(id)` → `{header, revision, sizeBytes?}`，**不读事件日志**；
+ *     - `open(id, 'read')` → 只读 handle（不创建 live Session、不写任何状态），
+ *       `handle.read()` → `{events, eventState}`，`handle.close()` 释放。
+ *   - `@deepseek-ai/dsh-session-persistence-jsonl` 对**已归档**会话同样可读：归档只改
+ *     Workspace registry 的集合，不动持久化文件。
+ *
+ * 所以整条链可以完全在服务端按「header + 日志尾部」读出来，不需要加载祖先会话。
+ * 这里只是只读读取：不 append、不 open 写句柄、不改归档/置顶/标题。
+ *
+ * 链接形状与客户端原逐级逻辑一致：
+ *   - 每一行（祖先）的 ordinal/baseTitle/scheme 来自**子会话的入站 relay 记录**；
+ *   - 交接单 path 优先用这条入站记录自己的 path，缺了再向父会话日志里找
+ *     `childId===子id && ordinal===该跳序号` 的出站记录补（0.3/0.4 老记录没写 path）；
+ *   - 父会话自己的入站记录（或 DCR-02 老链的 header+标题兜底）继续往更早走。
+ */
+import { RELAY_RECORD_TYPE } from '../core/relay.js';
+import { legacyRelayChainOf, normalizeRelayRecord, relayChainOf, relayInboundRecordOf } from './relay.js';
+import { liveSessionOf, sessionLog } from './session-view.js';
+import { sourceTitleOf } from './sessions.js';
+
+/** 最多回看 8 层（与客户端 MAX_CHAIN_HOPS 同口径：防成环、防无限链）。 */
+export const MAX_CHAIN_HOPS = 8;
+
+/** 取宿主 sessionPersistence 服务；旧宿主/headless 测试没有 → null。 */
+function sessionPersistenceOf(ctx) {
+  try {
+    const service =
+      typeof ctx?.get === 'function' ? ctx.get('sessionPersistence') : ctx?.sessionPersistence;
+    if (service === null || service === undefined) return null;
+    if (typeof service.open !== 'function') return null;
+    return service;
+  } catch {
+    return null;
+  }
+}
+
+function isNotFoundError(error) {
+  return (
+    error !== null &&
+    typeof error === 'object' &&
+    (error.name === 'SessionPersistenceNotFoundError' || error.code === 'session/persistence-not-found')
+  );
+}
+
+/** 只读打开一个**未加载**的会话；返回 header + 完整事件日志（不进入 ctx.sessions）。 */
+async function readStoredSession(ctx, sessionId) {
+  const persistence = sessionPersistenceOf(ctx);
+  if (persistence === null) return { unsupported: true };
+  let handle = null;
+  try {
+    let snapshot;
+    if (typeof persistence.stat === 'function') {
+      snapshot = await persistence.stat(sessionId);
+      if (snapshot === null || snapshot === undefined) return { missing: true };
+    }
+    handle = await persistence.open(sessionId, 'read');
+    const result = await handle.read();
+    const events = Array.isArray(result?.events) ? result.events : [];
+    const header =
+      snapshot !== null && typeof snapshot === 'object' && snapshot.header !== null && typeof snapshot.header === 'object'
+        ? snapshot.header
+        : handle?.header;
+    return { id: sessionId, header: header ?? null, events, live: false };
+  } catch (error) {
+    if (isNotFoundError(error)) return { missing: true };
+    return { error: error instanceof Error ? error.message : String(error) };
+  } finally {
+    if (handle !== null) {
+      try {
+        await handle.close();
+      } catch {
+        /* 只读句柄释放失败不影响读取结果 */
+      }
+    }
+  }
+}
+
+/**
+ * 会话的链读取素材：优先 live（内存里最新，刚写入未落盘的记录也在），
+ * 否则只读持久化日志。
+ * @returns {Promise<{id:string, header:object|null, events:Array, live:boolean, session?:object}|{missing:true}|{error:string}|{unsupported:true}>}
+ */
+async function sessionInfoOf(ctx, sessionId) {
+  const live = liveSessionOf(ctx, sessionId);
+  if (live !== undefined && live !== null) {
+    return {
+      id: sessionId,
+      header: live.header !== null && typeof live.header === 'object' ? live.header : null,
+      events: sessionLog(live),
+      live: true,
+      session: live,
+    };
+  }
+  return readStoredSession(ctx, sessionId);
+}
+
+/** 会话当前标题（老链兜底合成用）：live 走标题服务，持久化日志取最后一条 session/title。 */
+function titleOf(ctx, info) {
+  if (info.live === true && info.session !== undefined) {
+    const title = sourceTitleOf(ctx, info.session);
+    if (title !== undefined) return title;
+  }
+  const events = Array.isArray(info.events) ? info.events : [];
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index];
+    if (event?.type === 'session/title' && typeof event.data?.title === 'string' && event.data.title.length > 0) {
+      return event.data.title;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * 这一层会话「自己的入站链」：优先 relay 记录；0.5.0 之前的老链没有记录时，
+ * 用 header.parentSession + 标题（「交接第 N 次」/「历史 N」）兜底合成。
+ * 合成条件与 readState 完全一致（排除 subagent / fork / 干净标题），见 relay.js。
+ */
+function chainCursorOf(ctx, info) {
+  const inbound = relayInboundRecordOf({ id: info.id, log: info.events });
+  if (inbound !== null) return relayChainOf(inbound);
+  const legacy = legacyRelayChainOf({
+    session: { id: info.id, header: info.header },
+    title: titleOf(ctx, info),
+  });
+  return legacy === null ? null : relayChainOf(legacy);
+}
+
+/**
+ * 父会话日志里「交给 childId 的那一跳」的出站记录（用于补交接单 path）。
+ * 必须同时校验 childId + ordinal：父会话后来可能又交接给了下一代。
+ */
+function outboundRecordFor(info, childId, ordinal) {
+  const events = Array.isArray(info.events) ? info.events : [];
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index];
+    if (event?.type !== RELAY_RECORD_TYPE) continue;
+    const record = normalizeRelayRecord(event.data);
+    if (record !== null && record.childId === childId && record.ordinal === ordinal) return record;
+  }
+  return null;
+}
+
+/** 行投影：只下发客户端画一行需要的字段（与旧逐级 GET 的 row 形状一致）。 */
+function rowOf(sessionId, cursor, path) {
+  return {
+    sessionId,
+    ordinal: cursor.ordinal,
+    baseTitle: cursor.baseTitle ?? null,
+    scheme: cursor.scheme ?? null,
+    path: path ?? null,
+  };
+}
+
+/**
+ * 一次读出整条交接链（最多 8 层）。
+ *
+ * 不加载任何祖先会话：未加载的会话从持久化日志读 header/事件；已加载的直接用内存日志。
+ * 读不到某一层时返回**已读到的行** + `unreadable`（不是把整块清空），客户端据此显示
+ * 「上一层会话未打开」+「打开并继续」入口。
+ *
+ * @param {object} ctx 根上下文
+ * @param {{sessionId?:string, maxHops?:number}} [options]
+ * @returns {Promise<{
+ *   ok:true,
+ *   sessionId:string,
+ *   rows:Array<{sessionId:string, ordinal:number|null, baseTitle:string|null, scheme:string|null, path:string|null}>,
+ *   done:boolean,
+ *   capped:boolean,
+ *   unreadable:{sessionId:string, reason:'not-found'|'error'}|null
+ * } | {ok:false, code:string, message:string}>}
+ */
+export async function readRelayChain(ctx, { sessionId, maxHops = MAX_CHAIN_HOPS } = {}) {
+  if (typeof sessionId !== 'string' || sessionId.length === 0) {
+    return { ok: false, code: 'bad-session', message: '缺少 sessionId' };
+  }
+  if (sessionPersistenceOf(ctx) === null) {
+    return { ok: false, code: 'unsupported', message: '当前宿主没有 sessionPersistence，无法在不加载会话的情况下读取接力链' };
+  }
+
+  const start = await sessionInfoOf(ctx, sessionId);
+  if (start?.unsupported === true) {
+    return { ok: false, code: 'unsupported', message: '当前宿主没有 sessionPersistence，无法在不加载会话的情况下读取接力链' };
+  }
+  if (start?.missing === true) {
+    return { ok: false, code: 'not-found', message: '宿主持久化里找不到这个会话' };
+  }
+  if (start?.error !== undefined) {
+    return { ok: false, code: 'read-failed', message: `读取会话日志失败：${start.error}` };
+  }
+
+  const limit = Number.isInteger(maxHops) && maxHops > 0 ? Math.min(MAX_CHAIN_HOPS, maxHops) : MAX_CHAIN_HOPS;
+  let cursor = chainCursorOf(ctx, start);
+  let childId = sessionId;
+  const rows = [];
+  const seen = new Set([sessionId]);
+  const partial = (unreadable) => ({
+    ok: true,
+    sessionId,
+    rows,
+    done: false,
+    capped: false,
+    unreadable,
+  });
+
+  while (cursor !== null && cursor.parentId !== null) {
+    if (rows.length >= limit) {
+      return { ok: true, sessionId, rows, done: true, capped: true, unreadable: null };
+    }
+    const parentId = cursor.parentId;
+    // 链路成环/自指：去重后停在最后一条真实会话，不再重复列同一层。
+    if (seen.has(parentId)) {
+      return { ok: true, sessionId, rows, done: true, capped: false, unreadable: null };
+    }
+    const info = await sessionInfoOf(ctx, parentId);
+    if (info?.missing === true) return partial({ sessionId: parentId, reason: 'not-found' });
+    if (info?.error !== undefined) return partial({ sessionId: parentId, reason: 'error' });
+    if (info?.unsupported === true) {
+      return { ok: false, code: 'unsupported', message: '当前宿主没有 sessionPersistence，无法在不加载会话的情况下读取接力链' };
+    }
+
+    const outbound = outboundRecordFor(info, childId, cursor.ordinal);
+    rows.push(rowOf(parentId, cursor, cursor.path ?? outbound?.path ?? null));
+    seen.add(parentId);
+    childId = parentId;
+    cursor = chainCursorOf(ctx, info);
+  }
+
+  return { ok: true, sessionId, rows, done: true, capped: false, unreadable: null };
+}