dsh-compact-relay 0.5.0 → 0.5.2

package/lib/actions/force-archive.js

@@ -0,0 +1,113 @@
+/**
+ * 0.5.2 L 项：**强制归档旧会话**（显式用户确认后才停止后台任务）。
+ *
+ * 背景：自动归档（`dsh/handoff-archive.js:archiveHandoffSource`）在旧会话还有
+ * turn/subagent/job/schedule 时**故意不归档**（`status:'active'`）—— 静默杀后台任务
+ * 比「旧会话多留一行」破坏性大得多。但这也意味着「旧会话一直有任务在跑」时用户
+ * 没有清理出路（0.5.x 补丁计划 P4）。这里补的就是那条**显式**出路：
+ *
+ *   - 只有 `confirmStop === true`（用户在二次确认里点过「强制归档（停止任务）」）
+ *     才会调用 `workspaceRegistry.archiveSession(sessionId, { stopActivity: true })`；
+ *   - 没有确认 → 直接拒绝（不静默降级成普通归档，也不静默停止任务）；
+ *   - 旧会话在侧栏置顶时要求 `confirmUnpin === true`（宿主归档会在同一次写盘里
+ *     取消置顶），否则返回 `pinned` + 现有置顶文案，**不归档**；
+ *   - 失败抛可读错误（`code:'force-archive'`），不吞、不假装成功。
+ *
+ * 宿主实证（`@deepseek-ai/dsh-workspace/lib/index.js`）：
+ *   - `archiveSession(id)` 先跑 `workspace/session-activity` waterfall，有 provider
+ *     报活就抛 `WorkspaceActiveSessionError`（带 `activity` 数组）；
+ *   - `archiveSession(id, { stopActivity:true })` 跳过活动检查、先写归档集合，再
+ *     `workspace/session-stop` 停止旧会话的 turn/subagent/job/schedule；
+ *   - 归档与置顶互斥：同一笔写盘会把该 id 从 `pinnedSessionIds` 移除。
+ */
+import { actionError } from '../core/errors.js';
+import {
+  archivedSessionIdsOf,
+  handoffArchiveNoteOf,
+  isSessionArchived,
+  isSessionPinned,
+  workspaceRegistryOf,
+} from '../dsh/handoff-archive.js';
+
+function errorMessageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * 强制归档旧会话（会停止它上面正在跑的 turn / subagent / job / schedule）。
+ *
+ * 返回值（全部 `ok:true`；失败一律抛 `actionError('force-archive', …)`）：
+ *   - `status:'archived'`  刚写入归档集合（已停止任务）；
+ *   - `status:'already'`   之前就已经归档（幂等，不再写盘、不再停任务）；
+ *   - `status:'pinned'`    已置顶且未确认取消置顶 —— **没有归档**，note 是现有置顶文案。
+ * 三种情况的 `note` 都复用 `handoffArchiveNoteOf`（与交接自动归档同一套告知文案）。
+ *
+ * @param {{ctx:object, log?:{warn?:Function}}} deps
+ * @param {{sessionId:string, confirmStop:boolean, confirmUnpin?:boolean}} input
+ *   sessionId 是**旧会话** id（不是当前会话）；confirmStop 必须是 true（二次确认的凭证）。
+ * @returns {Promise<{ok:true, status:'archived'|'already'|'pinned', archived:boolean, note:string, archivedSessionIds:string[]|null}>}
+ */
+export async function forceArchiveSession(deps, { sessionId, confirmStop, confirmUnpin } = {}) {
+  if (typeof sessionId !== 'string' || sessionId.length === 0) {
+    throw actionError('force-archive', '缺少要强制归档的会话 id');
+  }
+  // 防御性：HTTP 层与客户端都要求显式确认；动作层再挡一次，避免任何调用方误传。
+  if (confirmStop !== true) {
+    throw actionError('force-archive', '强制归档会停止旧会话上正在跑的任务，需要显式确认（confirmStop:true）');
+  }
+
+  const registry = workspaceRegistryOf(deps.ctx);
+  if (registry === null || typeof registry.archiveSession !== 'function') {
+    throw actionError('force-archive', '当前 DSH 宿主没有 Workspace 归档接口，无法强制归档旧会话');
+  }
+
+  // 幂等：已在归档集合里就什么都不做（尤其不能再 stopActivity 一次）。
+  if (isSessionArchived(deps.ctx, sessionId) === true) {
+    return {
+      ok: true,
+      status: 'already',
+      archived: true,
+      note: handoffArchiveNoteOf({ status: 'already', archived: true }),
+      archivedSessionIds: archivedSessionIdsOf(deps.ctx),
+    };
+  }
+
+  // 置顶保护：归档会取消置顶（宿主在同一笔写盘里做），必须用户单独确认；
+  // 读不到置顶集合（null）时不猜 —— 按「未置顶」继续，由宿主自己决定。
+  if (confirmUnpin !== true && isSessionPinned(deps.ctx, sessionId) === true) {
+    deps.log?.warn?.(
+      `compact-relay: 旧会话 ${sessionId} 在侧栏置顶，未确认取消置顶前不强制归档（归档会取消置顶）`,
+    );
+    return {
+      ok: true,
+      status: 'pinned',
+      archived: false,
+      // 0.5.2 审查 P1-3：本场景没有「交接确认」可点，不能复用交接流程的 pinned 文案。
+      note: '旧会话已置顶，本次未归档（归档会取消置顶）；确认「仍然归档（取消置顶）」后才会归档并可恢复。',
+      archivedSessionIds: archivedSessionIdsOf(deps.ctx),
+    };
+  }
+
+  try {
+    // 唯一允许传 stopActivity 的地方：用户已确认「会停止旧会话上正在跑的任务」。
+    await registry.archiveSession(sessionId, { stopActivity: true });
+  } catch (error) {
+    deps.log?.warn?.(`compact-relay: 强制归档旧会话 ${sessionId} 失败：${errorMessageOf(error)}`);
+    const unknown = error !== null && typeof error === 'object' && error.name === 'WorkspaceUnknownSessionError';
+    throw actionError(
+      'force-archive',
+      unknown
+        ? `强制归档失败：宿主里找不到这个会话（${errorMessageOf(error)}）`
+        : `强制归档失败：${errorMessageOf(error)}`,
+      error,
+    );
+  }
+
+  return {
+    ok: true,
+    status: 'archived',
+    archived: true,
+    note: handoffArchiveNoteOf({ status: 'archived', archived: true }),
+    archivedSessionIds: archivedSessionIdsOf(deps.ctx),
+  };
+}

package/lib/actions/handoff.js

@@ -17,6 +17,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { clipCodeUnits } from '../core/clip.js';
 import { actionError } from '../core/errors.js';
 import { pinAnchorOf } from '../core/pin-anchors.js';
 import { handoffFileName, renderHandoffDoc } from '../core/handoff-doc.js';
@@ -29,12 +30,13 @@ import { buildSiteSnapshot } from '../dsh/site-info.js';
 import { generateHandoffDoc } from '../dsh/handoff-writer.js';
 import { buildHandoffProgramSections } from '../core/handoff-facts.js';
 import { checkHandoffReadiness } from '../core/readiness.js';
+import { parentRelayRecordOf } from '../core/relay-record.js';
 import { changedFilesOf } from '../dsh/session-files.js';
 import { errorCodeOf, localIso } from '../dsh/diag-counters.js';
 import { surfaceMessages } from '../dsh/prefix.js';
 import { handoffTitlePlanOf, createHandoffSession, renameHistoryOf, sourceTitleOf } from '../dsh/sessions.js';
 import { writeRelayRecord } from '../dsh/relay.js';
-import { archiveHandoffSource, handoffArchiveNoteOf } from '../dsh/handoff-archive.js';
+import { archiveHandoffSource, handoffArchiveNoteOf, isSessionPinned } from '../dsh/handoff-archive.js';
 import { withLock } from './lock.js';
 import { beginInflight, cancelErrorOf, combinedSignal, finishInflight } from './support.js';
 
@@ -97,13 +99,15 @@ async function collectHandoffFacts(deps, agent) {
  * 不记 message（message 可能带交接单路径/会话内容）。行为与文案不变。
  *
  * @param {{ctx:object, cfg:object, lock:object, engine:object, log?:object, diag?:object}} deps
- * @param {{agent:object, signal?:AbortSignal, commandId?:string, edits?:Record<string,string>}} input
+ * @param {{agent:object, signal?:AbortSignal, commandId?:string, edits?:Record<string,string>, archive?:boolean, confirmUnpin?:boolean}} input
  *   edits 只允许 `{约束?:string, 下一步?:string}`（P2-1；非法字段抛 code='edits'）
+ *   archive 默认 true（0.5.0 行为）；false = 只交接不归档
+ *   confirmUnpin 默认 false：旧会话在侧栏置顶时，必须显式确认才归档（归档会取消置顶）
  */
-export async function handoff(deps, { agent, signal, commandId, edits } = {}) {
+export async function handoff(deps, { agent, signal, commandId, edits, archive, confirmUnpin } = {}) {
   const startedAt = Date.now();
   try {
-    const outcome = await runHandoff(deps, { agent, signal, commandId, edits });
+    const outcome = await runHandoff(deps, { agent, signal, commandId, edits, archive, confirmUnpin });
     deps.diag?.bumpAction('handoff', true);
     return outcome;
   } catch (error) {
@@ -118,9 +122,9 @@ export async function handoff(deps, { agent, signal, commandId, edits } = {}) {
 /**
  * 交接流程本体。
  * @param {{ctx:object, cfg:object, lock:object, engine:object, log?:object}} deps
- * @param {{agent:object, signal?:AbortSignal, commandId?:string}} input
+ * @param {{agent:object, signal?:AbortSignal, commandId?:string, edits?:object, archive?:boolean, confirmUnpin?:boolean}} input
  */
-async function runHandoff(deps, { agent, signal, commandId, edits }) {
+async function runHandoff(deps, { agent, signal, commandId, edits, archive, confirmUnpin }) {
   if (agent === undefined || agent === null) throw actionError('handoff', '当前没有打开的会话，无法交接');
   const session = agent.session;
   if (session === undefined) throw actionError('handoff', '没有活动会话，无法交接');
@@ -260,29 +264,32 @@ async function runHandoff(deps, { agent, signal, commandId, edits }) {
       });
 
       // A5：把接力链写成父会话里的结构化记录；写失败不阻断交接（标题解析仍可兜底）。
-      // 0.4 P2-2：canonical 字段 parentId/childId/ordinal/at/atIso 补齐；旧字段 parentSessionId/index 保留兼容。
-      // 0.5.0：父/子记录都写 scheme（本次链的命名方案）+ titleSeq（各自 rename 的 eventSeq）；
-      // 新链父记录再写 historyTitle（旧会话改名后的标题），供审计/幂等核对。
+      // 0.5.2 S2：形状（含 0.3 旧字段双写、planId、条件写入的 historyTitle、**键顺序**）
+      // 全部由 core/relay-record 的唯一构造器负责，这里只传语义参数。
+      // historyTitle 只在改名真的生效（renamed / already）时传；失败/服务不可用时
+      // 不能记一个不存在的标题 —— 构造器对空/非字符串一律不写这个键。
       const relayAt = Date.now();
-      const relayWrote = writeRelayRecord(deps.engine, session, {
-        parentId: session.id,
-        childId: created.childId,
-        ordinal: titlePlan.index,
-        at: relayAt,
-        atIso: localIso(new Date(relayAt)),
-        parentSessionId: session.id,
-        index: titlePlan.index,
-        path: file,
-        planId: compactOutcome?.planId ?? null,
-        title: titlePlan.title,
-        baseTitle: titlePlan.baseTitle,
-        scheme: titlePlan.scheme,
-        titleSeq: historyRename.titleSeq,
-        // historyTitle 只在改名真的生效时写；失败/服务不可用时不能记一个不存在的标题。
-        ...(titlePlan.scheme === 'history-n' && (historyRename.renamed || historyRename.reason === 'already')
-          ? { historyTitle: historyRename.title }
-          : {}),
-      });
+      const relayWrote = writeRelayRecord(
+        deps.engine,
+        session,
+        parentRelayRecordOf({
+          parentId: session.id,
+          childId: created.childId,
+          ordinal: titlePlan.index,
+          at: relayAt,
+          atIso: localIso(new Date(relayAt)),
+          path: file,
+          planId: compactOutcome?.planId,
+          title: titlePlan.title,
+          baseTitle: titlePlan.baseTitle,
+          scheme: titlePlan.scheme,
+          titleSeq: historyRename.titleSeq,
+          historyTitle:
+            titlePlan.scheme === 'history-n' && (historyRename.renamed || historyRename.reason === 'already')
+              ? historyRename.title
+              : undefined,
+        }),
+      );
       if (!relayWrote) deps.log?.warn?.('compact-relay: 接力链记录写入失败，下次交接将回退到标题解析');
       // renameHistoryOf 的 flush 发生在父记录之前；这里再 flush 一次，保证旧会话的
       // 「历史 N」标题与这条父记录一起落盘（失败只 warn，不影响交接结果）。
@@ -293,28 +300,36 @@ async function runHandoff(deps, { agent, signal, commandId, edits }) {
       }
 
       // 0.5.0：交接成功后自动归档旧会话（让列表只剩新会话）。
+      // 0.5.1 批 2：archive:false = 只交接不归档；旧会话在侧栏置顶时必须显式
+      // confirmUnpin 才归档（宿主归档会在同一次写盘里取消置顶 —— dsh-workspace 源码）。
       // 顺序要求：子会话已建好、旧会话已改名、父记录已 flush —— 全部完成之后才归档；
       // 归档失败只 warn + 在返回文案里说明，绝不回滚/阻断交接。
       // 不传 stopActivity：自动流程不替用户取消旧会话里仍在跑的 turn/subagent/job/schedule；
       // 只对收尾中的 turn 做有限等待重试，仍活跃就保留可见并提示（宁可多一行，不静默杀任务）。
-      let archive;
-      try {
-        archive = await archiveHandoffSource(deps.ctx, session.id, { log: deps.log });
-      } catch (error) {
-        // archiveHandoffSource 设计上不抛；这里再兜一层，任何替身/内核异常都不影响交接结果。
-        deps.log?.warn?.(`compact-relay: 旧会话归档异常：${error instanceof Error ? error.message : String(error)}（交接已完成）`);
-        archive = { status: 'failed', archived: false, activityKinds: [] };
+      const archiveRequested = archive !== false;
+      let archiveResult;
+      if (!archiveRequested) {
+        archiveResult = { status: 'skipped', archived: false, activityKinds: [] };
+      } else if (isSessionPinned(deps.ctx, session.id) === true && confirmUnpin !== true) {
+        archiveResult = { status: 'pinned', archived: false, activityKinds: [] };
+        deps.log?.warn?.(
+          `compact-relay: 旧会话 ${session.id} 在侧栏置顶，未确认前不自动归档（归档会取消置顶；交接已完成）`,
+        );
+      } else {
+        try {
+          archiveResult = await archiveHandoffSource(deps.ctx, session.id, { log: deps.log });
+        } catch (error) {
+          // archiveHandoffSource 设计上不抛；这里再兜一层，任何替身/内核异常都不影响交接结果。
+          deps.log?.warn?.(`compact-relay: 旧会话归档异常：${error instanceof Error ? error.message : String(error)}（交接已完成）`);
+          archiveResult = { status: 'failed', archived: false, activityKinds: [] };
+        }
       }
-      const archiveNote = handoffArchiveNoteOf(archive);
+      const archiveNote = handoffArchiveNoteOf(archiveResult);
 
       // BUG-004：失败原因可能是「摘要模型调用了工具」这类可操作信息，以前只写「日志有记录」
       // （用户看不到 host 日志）；这里带上短原因 + 可手动 /bc 的建议。
-      const briefWarning =
-        compactWarning === null
-          ? ''
-          : compactWarning.length > 120
-            ? `${compactWarning.slice(0, 119)}…`
-            : compactWarning;
+      // 0.5.1 D03：截断收口到 core/clip（原手写 120 字预算，文案不变）。
+      const briefWarning = compactWarning === null ? '' : clipCodeUnits(compactWarning, 120);
       const compactNote =
         compactOutcome !== null && compactOutcome.compacted === true
           ? `已将 ${compactOutcome.shadowedSeqs.length} 条旧会话压成 1 条摘要；`
@@ -347,7 +362,7 @@ async function runHandoff(deps, { agent, signal, commandId, edits }) {
         readiness,
         started: created.started,
         // 0.5.0：归档结果结构化返回（HTTP 暂不下发；客户端看 message/接力条状态即可）。
-        archive: { status: archive.status, archived: archive.archived === true },
+        archive: { status: archiveResult.status, archived: archiveResult.archived === true },
         message:
           `交接完成：${compactNote}` +
           `交接单已存至 ${file}；` +

package/lib/actions/pin.js

@@ -176,16 +176,17 @@ export function listPins(deps, { agent } = {}) {
 }
 
 /**
- * 菜单用：有锁定就清空，没有就锁最近一轮。
+ * 菜单用：有锁定（含全部已失效的快照）就清空，没有就锁最近一轮。
  *
- * P3-03：判断必须和 readState 的展示同口径（`livePinnedSeqs`）。只看日志里的最新
- * 快照时，快照 seq 已被压缩/清屏带走的场景会让菜单显示「锁定重要消息」（未锁），
- * 点下去却走 unpinAll → 用户看到的是「明明没锁却被解锁」。
+ * 0.5.1 批 2：菜单在「全部 pin 已被原生压缩带走」时显示「解除失效锁定（N 条）」，
+ * 所以这里必须按**快照**判定：快照非空 → unpinAll，不能因为 live=0 就反过来新锁
+ * 一条（按钮文案与动作会完全相反）。`pinLastTurn`/`pinByIndex` 内部仍只带 live
+ * 集合进新快照，顺手清掉过期 seq。
  * @param {{engine:object}} deps
  * @param {{agent:object}} input
  */
 export function togglePin(deps, { agent } = {}) {
   const session = agent?.session;
-  if (session === null || session === undefined) throw actionError('pin', '没有活动会话');
-  return livePinnedSeqs(session).length > 0 ? unpinAll(deps, { agent }) : pinLastTurn(deps, { agent });
+  if (session === null || session === undefined) throw actionError('pin', '当前没有活动会话');
+  return latestPinnedSeqs(sessionLog(session)).length > 0 ? unpinAll(deps, { agent }) : pinLastTurn(deps, { agent });
 }

package/lib/actions/relay-chain.js

@@ -0,0 +1,17 @@
+/**
+ * 完整交接链（只读）动作层 —— HTTP 适配层与 dsh 读取器之间的薄包装。
+ *
+ * 0.5.1 DCR-05：客户端点「完整交接链」时一次取回整条链；服务端按需只读持久化日志，
+ * **不把祖先会话加载进 ctx.sessions**（宿主对未加载会话的 readState 返回 sessionId:null，
+ * 逐级 GET 会停在断点）。读取细节见 dsh/relay-chain.js。
+ */
+import { readRelayChain } from '../dsh/relay-chain.js';
+
+/**
+ * @param {{ctx:object}} deps
+ * @param {{sessionId?:string}} [input]
+ * @returns {ReturnType<typeof readRelayChain>}
+ */
+export function readCompactRelayChain(deps, { sessionId } = {}) {
+  return readRelayChain(deps?.ctx, { sessionId });
+}

package/lib/actions/state.js

@@ -6,15 +6,19 @@
  */
 import { paletteForBothSchemes } from '../core/colors.js';
 import { adviceFor, ratioOf, thresholdsForWindow } from '../core/policy.js';
+import { nativePinnedRiskOf } from '../core/native-pin-risk.js';
+import { pinHealthOf } from '../core/pin-health.js';
+import { latestPinnedSeqs } from '../core/pins.js';
 import { tokenOf } from '../core/tokens.js';
 import { measurePressure, routeBudgetOf } from '../dsh/pressure.js';
 import { selectCompactableRange } from '../dsh/select-range.js';
-import { compressHint as compressHintOf, countSummaries, lastCheckpointSurfaceSeq, livePinnedSeqs, liveSessionOf, pickAgent, surfaceSeqs } from '../dsh/session-view.js';
+import { compressHint as compressHintOf, countSummaries, firstCompactableIdx, lastCheckpointSurfaceSeq, liveSessionOf, pickAgent, sessionLog, surfaceSeqs } from '../dsh/session-view.js';
 import { compressHintIsActive } from '../core/compress-hint.js';
 import { readNativeCompaction, resolveNativePolicy } from '../dsh/native-compaction.js';
-import { nativeLineOf } from '../core/native-line.js';
-import { relayChainOf, relayRecordOf } from '../dsh/relay.js';
-import { isSessionArchived } from '../dsh/handoff-archive.js';
+import { nativeLineOf, nativeRetainTokensOf } from '../core/native-line.js';
+import { legacyChainParentIdOf, legacyRelayChainOf, relayChainOf, relayInboundRecordOf, relayOutboundRecordOf, relayRecordOf } from '../dsh/relay.js';
+import { isSessionArchived, isSessionPinned, workspaceRegistryOf } from '../dsh/handoff-archive.js';
+import { sourceTitleOf } from '../dsh/sessions.js';
 
 /**
  * 动作层统一解析「这次动作作用在哪个 agent」：只认显式 sessionId，
@@ -96,10 +100,20 @@ export async function readState(deps, { sessionId, agent } = {}) {
   const compactRangeReason = compactRange !== null && !hasLiveAgent ? 'no_agent' : null;
 
   // M6：钉住集合（菜单显示「清除钉住（N 条）」，也能在无 agent 时读 live session）。
-  const pinnedSeqs = target === null ? [] : livePinnedSeqs(target.session);
+  // 0.5.1 批 2（C 方案）：pin 快照 vs 当前 surface ——
+  //   live  = 还在 surface 上（环/计数/解锁仍按这些）；
+  //   stale = 快照里有、surface 上没了（原生压缩/其它压缩/历史变化带走）——
+  //           单独下发，界面标「已失效」，既不假装还在，也不凭空消失。
+  const surface = target === null ? [] : surfaceSeqs(target.session);
+  const events = target === null ? [] : sessionLog(target.session);
+  const pinHealth =
+    target === null || surface.length === 0
+      ? // 没有 surface（会话刚打开/尚未回放）时不能把全部 pin 判成失效：那是「还不知道」。
+        { live: [], stale: [], cause: null, causes: { native: 0, other: 0, unknown: 0 } }
+      : pinHealthOf({ pinnedSeqs: latestPinnedSeqs(events), surfaceSeqs: surface, log: events });
+  const pinnedSeqs = pinHealth.live;
   // 0.3.1：锁定消息在 surface 里的相对位置（0–1，方案 A：消息在历史中的位置），
   // 指示灯环上按位置画锁定块；多个锁定按位置从早到晚排序。
-  const surface = target === null ? [] : surfaceSeqs(target.session);
   const surfaceIndex = new Map(surface.map((seq, index) => [seq, index]));
   const pinMarks = pinnedSeqs
     .filter((seq) => surfaceIndex.has(seq))
@@ -145,16 +159,96 @@ export async function readState(deps, { sessionId, agent } = {}) {
     }
   }
 
-  // A5 / 0.5.0 F4：接力链记录只读一次。`relay` 是旧字段（原样下发，一个不改）；
-  // `chain` 是它的只读投影，链号/原题/父子/scheme/path 直接给出，客户端不再自己解析。
-  // 没有记录 → 两者都是 null；旧记录没有的字段 → chain 里为 null（不猜）。
+  // 0.5.1 批 2：预判「下一次原生自动压缩会覆盖哪些锁定消息」——事前提示。
+  //
+  // 宿主信号：原生自动压缩只在 step boundary 触发（pressure ≥ 真实触发线后），
+  // 选段 = `selectCompactableRange(session, measurement, retainTokens)`：从第一个非
+  // system 节点起，逐字保留尾部 retainTokens，再按工具配对平衡回退。这里用同一份
+  // 定价节点（measured.nodes）+ 同一套保留预算复刻该范围，只读、不触发任何压缩。
+  //
+  // 只在「自动压缩开着 + 已到真实触发线 + 节点定价与 surface 对齐」时预警；
+  // 算不出/对不齐就返回 null（宁可不报，也不误报会覆盖）。
+  let pinRisk = null;
+  if (
+    target !== null &&
+    pinnedSeqs.length > 0 &&
+    nativeCfg.autoEnabled !== false &&
+    nativeLine !== null &&
+    nativeLine.ok === true &&
+    Number.isFinite(measured.tokens) &&
+    measured.tokens >= nativeLine.thresholdTokens &&
+    nativeBudget !== null &&
+    Array.isArray(measured.nodes) &&
+    measured.nodes.length === surface.length &&
+    measured.nodes.every((node, index) => node?.seq === surface[index])
+  ) {
+    const retainTokens = nativeRetainTokensOf({
+      contextWindow: nativeBudget.contextWindow,
+      reservedCompletionTokens: nativeBudget.reservedCompletionTokens,
+      retainRatio: nativePolicy.retainRatio,
+      retainTokens: nativePolicy.retainTokens,
+    });
+    if (retainTokens !== null) {
+      const risk = nativePinnedRiskOf({
+        pinnedSeqs,
+        nodes: measured.nodes,
+        firstIdx: firstCompactableIdx(target.session),
+        retainTokens,
+        isBalancedBefore: (seq) => {
+          try {
+            return deps.engine?.toolPairingBalancedBefore?.(target.session, seq) === true;
+          } catch {
+            return true; // 判定失败时按「可切」处理：只影响预警范围，不会真的压
+          }
+        },
+      });
+      if (risk !== null) pinRisk = { count: risk.count, seqs: risk.seqs };
+    }
+  }
+
+  //
+  // `relay` 是旧字段：日志里**最近一条**记录（出站/入站都可能）——语义一个字节不改，
+  // 下一次交接的链号递增（handoffTitlePlanOf）也依赖它。
+  // `chain` 改成「本会话入站记录」（childId===本会话）的只读投影：祖先会话再次交接后，
+  // 最近的记录变成出站（childId=下一代），旧实现照它下发 → 客户端「是不是本会话入站」
+  // 判定不成立 → 接力条消失（DCR-01）。没有入站记录时（DCR-02）用会话头
+  // header.parentSession + 标题兜底合成只读链（排除 subagent 会话与 fork 出来的会话），
+  // 让 0.5.0 之前生成、子会话没有记录的老链也能显示接力条。
   const relay = target === null ? null : relayRecordOf(target.session);
-  const chain = relay === null ? null : relayChainOf(relay);
+  const inbound = target === null ? null : relayInboundRecordOf(target.session);
+  const chain =
+    target === null
+      ? null
+      : inbound !== null
+        ? relayChainOf(inbound)
+        : // DCR-02：只有会话头看起来像老链时才去读标题（普通会话不付这次查找开销）。
+          legacyChainParentIdOf(target.session) === null
+          ? null
+          : legacyRelayChainOf({ session: target.session, title: sourceTitleOf(deps.ctx, target.session) });
+  // DCR-01：`next` = 本会话最近一条**出站**记录的只读投影（只加不改）。接力条不看它，
+  // 但「父→子入口」与「子会话向父会话补交接单 path」需要出站那一跳的信息。
+  const next = target === null ? null : relayChainOf(relayOutboundRecordOf(target.session));
   // 0.5.0：旧会话是否已被自动归档（接力条据此显示「恢复旧会话」）。这是宿主
-  // registry 的独立状态，不塞进 chain（chain 仍然只是 relay 记录的纯投影）。
+  // registry 的独立状态，不塞进 chain（chain 仍然只是链投影）。
+  // 0.5.1 DCR-01：用**入站** parentId 查（出站记录里的父会话是本会话自己，会查错）。
   // 拿不到 registry/归档集合 → null（不知道，客户端按「可尝试恢复」处理）。
   const parentArchived =
     chain === null || chain.parentId === null ? null : isSessionArchived(deps.ctx, chain.parentId);
+  // 0.5.1 批 3：出站记录的目标会话（下一代）是否已在归档集合里。父会话侧的「去新会话」
+  // 用它决定要不要先 unarchive（宿主拒绝打开归档会话；unarchive 幂等）。
+  // 和 parentArchived 完全对称：各查各的 id，读不到 → null（不猜 false）。
+  const nextArchived = next === null || next.childId === null ? null : isSessionArchived(deps.ctx, next.childId);
+  // 0.5.2 L 项：链上父会话（旧会话）是否在侧栏置顶 —— 强制归档的二次确认要提前说明
+  // 「归档会取消置顶」（宿主在同一笔写盘里 unpin）。没有父会话/读不到 → null（不猜）。
+  const parentPinned = chain === null || chain.parentId === null ? null : isSessionPinned(deps.ctx, chain.parentId);
+  // 0.5.1 DCR-03：宿主有没有「恢复归档会话」的接缝（HTTP recover 动作调的就是它）。
+  // 客户端拿不到 ctx.uiWorkspace.unarchiveSession 时据此隐藏「恢复旧会话」死入口。
+  // 0.5.2 L 项：`forceArchive` = 宿主有没有 archiveSession（接力条据此显示「强制归档旧会话」；
+  // 缺这个接缝时隐藏入口——点了必然失败）。
+  const capabilities = {
+    unarchive: typeof workspaceRegistryOf(deps.ctx)?.unarchiveSession === 'function',
+    forceArchive: typeof workspaceRegistryOf(deps.ctx)?.archiveSession === 'function',
+  };
 
   return {
     revision: ++stateRevision,
@@ -166,7 +260,19 @@ export async function readState(deps, { sessionId, agent } = {}) {
     summaries,
     advice,
     level: advice === 'none' ? 'idle' : advice,
-    pins: { count: pinnedSeqs.length, seqs: pinnedSeqs.slice(-20), marks: pinMarks },
+    // 0.5.1 批 2：stale = 快照里有、surface 上已没有的 pin（被压缩/历史变化带走）。
+    // `count` 仍是 live 集合（老客户端语义不变）；`stale` / `atRisk` 只加不改。
+    pins: {
+      count: pinnedSeqs.length,
+      seqs: pinnedSeqs.slice(-20),
+      marks: pinMarks,
+      stale: {
+        count: pinHealth.stale.length,
+        seqs: pinHealth.stale.slice(-20),
+        ...pinHealth.causes,
+      },
+      atRisk: pinRisk,
+    },
     compactRange,
     // 0.3.5：compactRange 非 null 但无活 agent 时为 'no_agent'，其它情况 null。
     compactRangeReason,
@@ -178,12 +284,28 @@ export async function readState(deps, { sessionId, agent } = {}) {
     settingsError: deps.settings?.error ?? null,
     // A5：最近一次交接的接力链记录（没有就是 null）。0.5.0 F4：旧字段原样保留。
     relay,
-    // 0.5.0 F4：同一条记录的只读链投影 {ordinal, baseTitle, parentId, childId, scheme, path?}；
-    // 只加不改：老客户端忽略它，新客户端不再解析标题。没有记录 → null。
+    // 0.5.0 F4 / 0.5.1 DCR-01：本会话**入站**记录的只读链投影
+    // {ordinal, baseTitle, parentId, childId, scheme, path?}；老链（无记录）可能是
+    // header 兜底合成的（多一个 synthesized:true）。没有链信息 → null。
     chain,
-    // 0.5.0：链上父会话当前是否在 workspace 归档集合里（true/false）；没有父会话或
-    // 宿主没有可读的归档状态 → null。只加不改。
+    // 0.5.1 DCR-01：最近一条**出站**记录的只读投影（本会话交接给下一代那一跳）。
+    // 只加不改：老客户端忽略；接力条不用它。没有出站记录 → null。
+    next,
+    // 0.5.0：链上父会话（入站 parentId）当前是否在 workspace 归档集合里（true/false）；
+    // 没有父会话或宿主没有可读的归档状态 → null。只加不改。
     parentArchived,
+    // 0.5.1 批 3：出站目标（next.childId）是否在同一归档集合里。父会话侧「去新会话」
+    // 据此先恢复再切；没有出站记录或读不到归档集合 → null。只加不改。
+    nextArchived,
+    // 0.5.2 L 项：入站父会话（旧会话）是否在侧栏置顶。强制归档的二次确认用它在
+    // 「会停止后台任务」之外再说明「归档会取消置顶」；没有父会话/读不到 → null（不猜）。
+    parentPinned,
+    // 0.5.1 批 2：本会话（agent.session，不是 agent.id）是否在侧栏置顶。
+    // 交接前客户端据此弹「归档会取消置顶」确认；读不到置顶集合 → null（不猜）。
+    sessionPinned: target === null || target.session === undefined ? null : isSessionPinned(deps.ctx, target.session.id),
+    // 0.5.1 DCR-03：宿主能力位（能不能恢复归档会话 / 能不能强制归档）。老客户端忽略；
+    // 新客户端在缺 `unarchive` 能力时隐藏恢复入口，缺 `forceArchive` 时隐藏强制归档入口。
+    capabilities,
     // 0.3.1：模型判断的「适合压缩」断点位置（没有或已失效为 null）。
     compressHint: activeHint,
     // 0.3.1：DSH 原生自动压缩（环上的报警最高阈值 / 设置页开关的数据源）。