dsh-compact-relay 0.5.0 → 0.5.2

package/lib/dsh/handoff-archive.js

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

package/lib/dsh/handoff-writer.js

@@ -49,7 +49,7 @@ export async function generateHandoffDoc({ ctx, engine, agent, maxTokens, inputT
   const prefix = surfaceMessages(session);
   if (prefix.length === 0) throw actionError('handoff', '这个会话还没有可交接的内容（没有模型可见的消息）');
 
-  // 同摘要器：不继承 reasoningEffort（max 思考会把输出上限吃光）；是否传 off 由模型能力决定。
+  // reasoningEffort 由 prepareModelCall 决定：优先沿用主请求档位（cache 对齐）；拿不到 header 才回退「支持 off 就 off」。
   const controls = cacheAlignedControls(session, target);
   let lastProblems = [];
 

package/lib/dsh/model-task.js

@@ -5,8 +5,8 @@
  * 两个任务不是同一种产物（一个压成六段摘要、一个写九段交接单，校验/重试规则
  * 也不同），所以**不合并重试循环**；但下面四件事完全一样、以前各写一遍：
  *   1. 前置：会话存在性 → 解析 provider/model 路由 → 窗口预算预检 → 推理档位；
- *   2. cache 对齐参数：复用上次请求的 temperature/stop，但**绝不继承 reasoningEffort**
- *      （2026-10-19 真机坑：会话最后请求是 max 思考，摘要沿用 max → maxTokens 被思考吃光）；
+ *   2. cache 对齐参数：复用上次请求的 temperature/stop；reasoningEffort 由
+ *      prepareModelCall 显式决定（2026-10-27 起优先沿用主请求的档位，见下）；
  *   3. 单次流式调用 + finishProblem 归一（超限/工具调用/中断）；
  *   4. 成功结果的公共元信息（provider/model/maxTokens/attempts/usage）。
  *
@@ -14,7 +14,7 @@
  */
 import { actionError } from '../core/errors.js';
 import { assertBudget, callStream, reasoningEffortFor } from './llm-call.js';
-import { cacheControls, routeOf } from './route.js';
+import { cacheControls, cacheEffortOf, routeOf } from './route.js';
 import { finishProblem } from './stream.js';
 
 /**
@@ -33,7 +33,7 @@ import { finishProblem } from './stream.js';
  * @param {string} input.code 动作错误码
  * @param {string} input.noSessionMessage 会话不存在时的用户可见错误文案
  * @param {string} input.noTargetMessage 拿不到 provider/model 时的用户可见错误文案
- * @returns {Promise<{target:{provider:string, model:string}, reasoningEffort:'off'|undefined}>}
+ * @returns {Promise<{target:{provider:string, model:string}, reasoningEffort:string|undefined}>}
  */
 export async function prepareModelCall({
   ctx,
@@ -53,18 +53,22 @@ export async function prepareModelCall({
 
   // 架构 A2：调模型前先做窗口预算预检；超窗直接报 budget，不白等一次失败请求。
   await assertBudget({ ctx, target, inputTokens, maxTokens, label });
-  // P2-5：只有模型目录明确支持 off 才传；非推理/不支持 off 的模型交给 adapter 默认。
-  const reasoningEffort = await reasoningEffortFor(ctx, target);
+  // 2026-10-27 P1 取证：reasoningEffort 会切换 provider 的 thinking 开关，是缓存前缀的
+  // 断点。摘要/交接单回放的是主请求的前缀，所以默认**沿用主请求的档位**（cache 对齐）；
+  // 只有拿不到 header（无请求头 / 模型已切走）时，才退回旧策略：
+  // P2-5 的「模型目录支持 off 就 off」（省思考 token；这是从 P1 之前的行为，保留作兜底）。
+  const headerEffort = cacheEffortOf(session, target);
+  const reasoningEffort = headerEffort !== undefined ? headerEffort : await reasoningEffortFor(ctx, target);
 
   return { target, reasoningEffort };
 }
 
 /**
- * cache 对齐参数：复用上次请求的 temperature/stop，**不要继承 reasoningEffort**。
+ * cache 对齐参数：复用上次请求的 temperature/stop；reasoningEffort 不从这里拿。
  *
- * 2026-10-19 真机踩的坑：会话最后请求是 reasoningEffort=max，摘要调用沿用 max，
- * 思考 token 把 maxTokens(4096) 吃光 → finish=max-tokens → 「摘要在输出上限处被截断」。
- * 摘要/交接单本身都不需要长思考，是否固定 off 由模型能力决定（见 prepareModelCall）。
+ * reasoningEffort 由 prepareModelCall 决定（2026-10-27 起优先与主请求一致，保证缓存命中）。
+ * 2026-10-19 的旧坑（max 思考把 maxTokens 吃光）已由「summary/handoff.maxTokens 提到
+ * 16K + 保留截断重试」兜住，不再是「一律 off」的理由。
  *
  * @param {object} session
  * @param {{provider:string, model:string}} target

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 };
+}

package/lib/dsh/relay.js

@@ -5,7 +5,7 @@
  * 写：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']);
@@ -60,22 +60,126 @@ export function normalizeRelayRecord(data) {
 }
 
 /**
- * 会话里最近一条接力链记录（没有返回 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 下发）。
  *

package/lib/dsh/route.js

@@ -51,6 +51,25 @@ export function routeOf(ctx, session, agent) {
   return asRoute(agent?.options);
 }
 
+
+/**
+ * 复用「上一条真实请求」的推理档位（cache 对齐用）。
+ *
+ * 2026-10-27 P1 取证：摘要/交接单回放的是上一条主请求的前缀，但 reasoningEffort
+ * 会切换 provider 的 thinking 开关；一旦与主请求不同，缓存前缀会在第一条
+ * assistant 消息的渲染处断开（生产实测命中 2–5%，隔离 A/B：off 74.0% vs max 96.9%）。
+ * 所以只要 header 里的 provider/model 与本次目标一致，就原样沿用它的 reasoningEffort。
+ *
+ * @param {object} session
+ * @param {{provider: string, model: string}} target
+ * @returns {string|undefined}
+ */
+export function cacheEffortOf(session, target) {
+  const config = session?.requestHeader?.()?.config;
+  if (config === undefined || config.provider !== target.provider || config.model !== target.model) return undefined;
+  return typeof config.reasoningEffort === 'string' && config.reasoningEffort.length > 0 ? config.reasoningEffort : undefined;
+}
+
 /**
  * 复用上次真实请求的采样控制参数，让附带调用尽量贴近它的前缀缓存。
  * @param {object} session