dsh-retrace 0.4.26 → 0.4.28

package/README.md

@@ -20,8 +20,15 @@ DeepSeek Harness.
 deserves. But rewinding is not just "delete a message": DeepSeek Harness stores
 conversations in an append-only event log, so a recall only rewinds the context
 while changed **artifact files stay changed**. dsh-retrace versions the
-conversation **and its artifacts** together, and guarantees **every rewind is
-legal — never dirtying the log, never breaking /compact**.
+conversation **and its artifacts** together, and keeps **every new rewind legal** —
+it cannot dirty the log, and new markers create **no token-meter pairing debt**
+(two-segment atomic pairs land by construction).
+
+> ⚠️ **Honest scope (matches the companion contract's own note)**: sessions that
+> already contain **legacy single-segment markers** — written by older versions —
+> are **known design debt**. Before `/compact`, run the companion `check` and
+> clean them up (`fix --remove-markers`); otherwise the host's own T1 self-check
+> blocks compaction. New rewinds do not add to that debt.
 
 > 🛡️ **Write safety** · 🔍 **Deep offline checks** · 🔄 **Detect → repair → guard** — see below.
 
@@ -54,7 +61,7 @@ Full steps in [📦 Installation](#-installation).
 
 | | Capability | What it means |
 |---|---|---|
-| 🛡️ | **Write safety** | Every rewind passes a three-layer pre-write contract guard; running agents are auto-stopped (official `cancel`/`whenIdle`); turn-interval markers are wrapped in a temporary step — **rewinds never dirty the log, /compact never breaks** |
+| 🛡️ | **Write safety** | Every rewind passes a three-layer pre-write contract guard; running agents are auto-stopped (official `cancel`/`whenIdle`); turn-interval markers are wrapped in a temporary step — **new rewinds cannot dirty the log and add no token-meter pairing debt**; **legacy single-segment markers are known debt** (run the companion `check` + `fix --remove-markers` before `/compact`) |
 | 🔍 | **Deep offline checks** | Companion `dsh-log-contract` ships 30+ contract rules (token-meter pairing / cross-step references / physical order / inbox replay), validated against real corrupted-session fixtures — it finds the class of problem that makes /compact permanently fail |
 | 🔄 | **Detect → repair → guard** | A watchdog snapshots the log at the first sign of concurrent writes; offline `fix` neutralizes problem markers and clips cross-step references in place; pre-write validation stops bad events before they land |
 
@@ -298,13 +305,74 @@ Read it before filing an issue.
 - Stale peer declarations with no remaining import site removed
   (`@deepseek-ai/dsh-home-paths`, `@deepseek-ai/dsh-client-runtime`).
 
+### Host-side breaking changes that `0.4.28` adapts to — *not caused by this plugin*
+
+1. **`@deepseek-ai/dsh-session` removed the `Session.events` member** (in `0.1.5-rc.1`).
+   The class has no `events` field and no `events` getter at all any more; the supported
+   readers are `snapshotEvents(fromSeq, toSeqExclusive)` (frozen, sequence-indexed),
+   `eventAt(seq)`, `ownEvents()` and `isOwnSeq(seq)`. `0.4.28` reaches the log through a
+   compatibility accessor that prefers the new API and falls back to the old array, so it
+   runs on both host generations.
+   **Symptom before the fix:** recall and edit did nothing and surfaced the raw error
+   `TypeError: Cannot read properties of undefined (reading 'length')` — both operations
+   start by locating the target message id, and that lookup read the removed member.
+2. **The client-side session store has no `keys()`** (`ctx.sessions`). A plugin that
+   enumerates sessions with `keys()` silently sees **zero** of them: no crash, no error,
+   just safety warnings that never fire. `0.4.28` prefers the official `list()` and falls
+   back to `keys()`; it deliberately does **not** fall back to enumerating service fields,
+   because guessing produces a silent empty result as well.
+3. **The client session controller has no title accessor** — `getTitle` does not exist
+   anywhere in `@deepseek-ai/dsh-api-session-controller`, and its `getSnapshot()` carries
+   no `title`. See the plugin-side item below: this one used to *overwrite your titles*.
+
+### Plugin-side fixes in `0.4.28` (these are ours)
+
+- **The edit / recall affordances never appeared at all.** The client half read chat
+  nodes from `snapshot.chat.nodes`, a path this host build does not have — nodes live in
+  the `useChat` store (`snapshot.nodes`). Every message-level component threw while
+  rendering and was swallowed by the error boundary, so the buttons were missing, while
+  the settings entry (which reads no nodes) rendered fine. Fixed: the client half now
+  takes `useChat` from the slot contract.
+- **"Jump to message" in the version and fork views did nothing.** It resolved the target
+  anchor through `store.getSnapshot()?.chat?.nodes`, which is permanently `undefined`
+  here. It now resolves through the `useChat` snapshot injected by the view and pages
+  with the official `store.loadThrough(seq)`; when the jump cannot complete it reports a
+  **diagnosable reason** (renderer warning + host-log line) instead of failing silently.
+- **Assigning a short code could overwrite your session title.** The client composed
+  `[CODE] <current title>` locally but had no way to read the current title, so the base
+  degraded to the session-id prefix (`[XXXXXX] <session-id-prefix>`). Title tagging now goes
+  through the host route only (`setBadgeTitle`), which reads the current title from the
+  session log. Manual renames are unaffected.
+- **Host-side operation failures are logged again** (code + message + stack). They used to
+  return the message to the UI without a log line, which is why this whole class of bug
+  was hard to diagnose from outside.
+
+- **The version and fork views now explain themselves.** They used to show a title plus a row of
+  actions with **no sentence anywhere saying what a "version" or a "fork" is** (the only near-miss
+  was an empty-state line that disappears as soon as data arrives), and fork rows printed raw node
+  types. They now carry an always-visible concept sentence, a type legend, and a plain-language
+  "why" line on every row; impact text reads `旧路径的 N 条消息被替换`, not `被遮蔽 N 个节点`.
+- **Client hide-lookup no longer rescans per row.** `useSeqHidden` re-scanned the node map for every
+  row (measured **346 ms** at 2000 rows / 20 markers, **1568 ms** at 3000/30 — and that path was
+  *dead* on this host until this release made the rows render at all, so it is this fix own cost).
+  It now reuses one per-snapshot hide plan: **8.3 ms** and **18.3 ms** respectively, with the
+  predicate verified equivalent against the old one.
 ### Upgrading
 
 ```bash
-dsh plugin --profile desktop add dsh-retrace@0.4.26
+dsh plugin --profile desktop add dsh-retrace@0.4.28
 # then restart DSH — plugins are not hot-reloaded
 ```
 
+**`0.4.27` was withdrawn.** It was briefly published and then recalled — `latest` points at `0.4.26`
+again and `0.4.27` is marked deprecated. **`0.4.28` is its replacement**: it carries every fix
+`0.4.27` had, plus the two items below.
+
+**`0.4.28` needs no data migration.** The session format is unchanged (v3), no session is
+re-written, and nothing has to be re-indexed: upgrade, restart, and the two symptoms above
+are gone. If you are on a host that still provides the old members, the compatibility
+accessors keep those paths working — this build does not drop older hosts.
+
 If the app **fails to boot after an upgrade**, a single failing plugin can take the
 whole tree down, so recover first and diagnose second:
 
@@ -325,6 +393,17 @@ the **host surface**, not by semver alone.
 
 ## ⚠️ Requirements & limitations
 
+- **Optional dependency (deliberately NOT in `package.json`)**: AI summaries need
+  an `llm` service from the host (the official `@deepseek-ai/dsh-llm`, bundled
+  with DSH Desktop). The plugin takes it **dynamically** via `ctx.get('llm')`:
+  present ⇒ summaries available, absent ⇒ it degrades to **verbatim excerpts
+  only**. Install and startup are unaffected either way. Model and credentials
+  follow the session's own default selection
+  (`agentDefaultModel.currentSelection()`); the plugin adds **no configuration
+  surface of its own**. Summaries sit behind a **default-off** switch (at most one
+  small call per operation: ≤6×400 chars in, ≤200 tokens out, 5 s timeout); when
+  it is off there are **zero LLM calls**, while the verbatim excerpt (zero token
+  cost) is **always recorded**.
 - Only **user messages** can be edited; recall works on user and assistant
   messages. Tool results are shadowed along with the recalled range but are not
   themselves recall targets.
@@ -345,7 +424,8 @@ the **host surface**, not by semver alone.
 
 - Recall / edit-and-resend / regenerate, each written through a three-layer
   **pre-write contract guard** and a safe-edit path (auto-stop the agent, temp-step
-  markers) — rewinds never corrupt the log or break `/compact`.
+  markers) — new rewinds do not corrupt the log and add no `/compact` debt;
+  **legacy single-segment markers** remain known debt (see the honest note above).
 - In-session **version timeline** + **artifact rollback** (git-first, snapshot
   fallback, dry-run preview, jump-to-conversation).
 - **Fork map + session lineage** in the conversation view.
@@ -369,9 +449,10 @@ the **host surface**, not by semver alone.
 
 > Command surface: `retrace.runningState` (host RPC) + `GET|POST /api/plugins/retrace/runningState` (HTTP).
 
-**What's next** — see the [public roadmap](https://github.com/yamingmou/dsh-retrace/blob/main/docs/ROADMAP.md) for the agent
-business-layer plan (runtime guard, interruption governance, ecosystem-facing
-interfaces). This README only describes what is already shipped.
+**What's next** — the agent business-layer plan (runtime guard, interruption
+governance, ecosystem-facing interfaces) is **not published yet**: it is a plan,
+not a shipped capability. This README describes the **development line (main)**,
+which may run ahead of the latest npm release.
 
 ---
 
@@ -419,9 +500,9 @@ and the [issue tracker](https://github.com/yamingmou/dsh-retrace/issues).
 
 Listed on the [dsh-plugin topic](https://github.com/topics/dsh-plugin).
 
-Part of the **Agent business layer (production-grade guarantees)** — see the
-[public roadmap](https://github.com/yamingmou/dsh-retrace/blob/main/docs/ROADMAP.md) for the framework-agnostic layer and how
-dsh-retrace is its DeepSeek Harness implementation. Companion components:
+Part of the **Agent business layer (production-grade guarantees)** — the
+framework-agnostic layer that dsh-retrace implements on DeepSeek Harness.
+Companion components:
 
 - [**dsh-log-contract**](https://github.com/yamingmou/dsh-log-contract) — the
   business layer's "doctor": 30+ offline contract rules + in-place repair

package/README.zh.md

@@ -17,8 +17,13 @@
 
 **撤回 / 编辑重发 / 重新生成** —— 每个会话都该有的三个操作。但回退不只是「撤掉一条
 消息」：DeepSeek Harness 把对话存在 append-only 事件日志里，撤回只回退上下文，改过的
-**产物文件不会自动还原**。dsh-retrace 把对话**和它的产物**一起版本化，并且保证
-**每次回退都合法、不弄脏日志、不破坏 /compact**。
+**产物文件不会自动还原**。dsh-retrace 把对话**和它的产物**一起版本化，并保证
+**每一次新的回退都合法**——不会弄脏日志，新写入的 marker **不产生 token-meter 配对债**
+（两段原子对按构造即通过）。
+
+> ⚠️ **诚实的边界（与配套契约自己的说明一致）**：**旧版本留下的单段 marker** 是
+> **已知设计债**。压缩前请用配套 `check` 体检并 `fix --remove-markers` 清理，否则宿主的
+> T1 自检会挡住 `/compact`。新的回退不会增加这笔债。
 
 > 🛡️ **写安全** · 🔍 **深层体检** · 🔄 **检测→修复→守护** —— 详见下方「生产级保证」。
 
@@ -51,7 +56,7 @@ dsh plugin --profile desktop add dshmarket    # 只需一次
 
 | | 能力 | 说明 |
 |---|---|---|
-| 🛡️ | **写安全** | 每次回退过三层写前契约校验；运行中的 agent 自动停止（官方 `cancel`/`whenIdle`）；轮次间 marker 用临时 step 包裹 —— **回退永不弄脏日志，/compact 永不失效** |
+| 🛡️ | **写安全** | 每次回退过三层写前契约校验；运行中的 agent 自动停止（官方 `cancel`/`whenIdle`）；轮次间 marker 用临时 step 包裹 —— **新的回退不会弄脏日志**，新 marker **不产生 token-meter 配对债**；**旧单段 marker 是已知设计债**（压缩前先 `check` + `fix --remove-markers`） |
 | 🔍 | **深层体检** | 配套 `dsh-log-contract` 30+ 条契约规则（token-meter 配对 / 跨 step 引用 / 物理序 / inbox 重放），用真实损坏会话当测试集 —— 能找出让 /compact 永久失效的那类问题 |
 | 🔄 | **检测→修复→守护** | 看门狗在并发写入第一时间快照日志；离线 `fix` 原地中和问题 marker、裁剪跨 step 引用；写前校验在坏事件落盘前拦住 |
 
@@ -287,6 +292,14 @@ dsh plugin --profile desktop add dsh-retrace@0.4.26
 
 ## ⚠️ 要求与限制
 
+- **可选依赖（不写进 `package.json`）**：AI 摘要需要宿主提供 `llm` 服务
+  （官方 `@deepseek-ai/dsh-llm`，随 DSH Desktop 内置）。插件用
+  `ctx.get('llm')` **动态取用**：有就用，缺失即降级为**只给逐字原文**，
+  安装/启动不受影响。模型与凭据沿用会话自身的默认模型选择
+  （`agentDefaultModel.currentSelection()`），插件**不新增任何配置面**。
+  摘要是**默认关闭**的开关（每次操作至多 1 次小调用，输入 ≤6×400 字、
+  输出 ≤200 token、5 秒超时），关闭时**零 LLM 调用**；而逐字原文
+  （`excerpt`）零 token 成本，**始终产出**。
 - 只有**用户消息**可以编辑；撤回同时适用于用户与助手消息。工具结果会随区间一并
   被阴影化，但不能单独作为撤回目标。
 - 智能体必须**空闲**：回复流式输出时需先点击 ⏹ 停止，再撤回或编辑；否则 Host
@@ -301,7 +314,7 @@ dsh plugin --profile desktop add dsh-retrace@0.4.26
 
 **当前已具备（0.4.x）：**
 
-- 撤回 / 编辑重发 / 重新生成——每次回退都过**三层写前校验**与安全编辑路径（自动停 agent、临时 step 包裹 marker），**不会损坏日志、不会破坏 /compact**。
+- 撤回 / 编辑重发 / 重新生成——每次回退都过**三层写前校验**与安全编辑路径（自动停 agent、临时 step 包裹 marker），**新的回退不会损坏日志、不新增 `/compact` 债**；**旧单段 marker 需要压缩前清理**（配套 `check` + `fix --remove-markers`）。
 - 单会话**版本时间线** + **产物回退**（git 优先 + 快照兜底、干跑预览、跳转对话）。
 - 对话视图内的**分叉图** + **会话谱系**。
 - **实时看门狗**——并发写入第一时间快照日志。
@@ -319,7 +332,7 @@ dsh plugin --profile desktop add dsh-retrace@0.4.26
 > 桌面说明：Electron 宿主退出时销毁窗口，页面 `beforeunload` 不会触发，宿主也未暴露
 > 插件可用的退出否决点——桌面侧由运行中横幅 + dispose 提示覆盖；Web 端拦截完整生效。
 
-**未来计划**——见 [公开路线图](https://github.com/yamingmou/dsh-retrace/blob/main/docs/ROADMAP.md)（agent 业务层规划：运行时守护、中断治理、生态开放接口）。本 README 只描述已上线的能力。
+**未来计划**——agent 业务层规划（运行时守护、中断治理、生态开放接口）**尚未发布**，此节是**计划**而非已上线能力。本 README 描述的是**开发线（main）**，可能领先于 npm 上最新发布版。
 
 ---
 
@@ -366,8 +379,8 @@ npm pack --dry-run    # 校验发布文件清单
 
 收录于 [dsh-plugin topic](https://github.com/topics/dsh-plugin)。
 
-**Agent 业务层（生产级保证）** 的一部分——见 [公开路线图](https://github.com/yamingmou/dsh-retrace/blob/main/docs/ROADMAP.md)
-（框架无关的业务层定义，dsh-retrace 是它在 DeepSeek Harness 上的实现）。配套组件：
+**Agent 业务层（生产级保证）** 的一部分——即 dsh-retrace 在 DeepSeek Harness 上实现的
+那层框架无关的业务层定义。配套组件：
 
 - [**dsh-log-contract**](https://github.com/yamingmou/dsh-log-contract) —— 业务层的
   「医生」：30+ 条离线契约规则 + 原地修复（`fix --neutralize` / `--clip-crossstep`）。

package/bin/retrace.mjs

@@ -2,7 +2,7 @@
 /**
  * dsh-retrace · bin/retrace.mjs
  *
- * 会话日志考古 CLI（任务书 A1-A4）——只读，不写任何日志。
+ * 会话日志考古 CLI——只读，不写任何日志。
  *
  *   retrace index <session> [--json]
  *       工具调用索引：调用数 / 配对率 / 孤儿数 / 命令分布（A1）

package/lib/adapter/contract.js

@@ -80,7 +80,7 @@ const isPlainObject = (value) => typeof value === 'object' && value !== null &&
  * 带着更大的 seq 插进被遮蔽区间的位置,于是「位置在前、seq 更大」是合法形态。
  * 官方 `replacementRange`(dsh-session)只按 `indexOf(start) <= indexOf(end)` 的
  * **位置**判定,与 seq 数值大小无关;要求 start <= end 会把真实会话上的合法 span
- * 误判为契约违规(真实数据实测:1360270 → 1360265 的跨度是正常写入)。
+ * 误判为契约违规(现场实测:位置序 span 的 seq 数值非单调属正常写入)。
  * 真正可判定的是:两端都是当前面上的节点 → 位置连续段 → 首尾一致(见下)。
  */
 export function assertSpanShape(span, contract = 'Span.shape') {

package/lib/adapter/dsh-writer.js

@@ -39,6 +39,8 @@ import { editorError, editorId, lastModelSource } from '../host-core.js'
 import { assertContract, assertSpanShape, assertMarkerShape, assertAuditShape, runtimeSurfaceOpShape, contractViolation } from './contract.js'
 // 载体形状/文案的唯一真相(纯模块零 import;生成动态件时与 contract 一同 inline)。
 import { AUDIT_EVENT_TYPE, CARRIER_EVENT_TYPE, CARRIER_SOURCE_KIND, TRACE_TEXT } from '../marker-carrier.js'
+// Host event-view compatibility (new host: snapshotEvents/eventAt; old host: events array).
+import { sessionEvents, eventAt, nextAppendSeq } from '../host-compat.js'
 
 /**
  * 第 2 段的 content(留痕 + 可解释载体)。
@@ -99,12 +101,13 @@ function resolveMeter(meter) {
  */
 function priceByNode({ service, deriveMessage, session, seqs }) {
   if (typeof deriveMessage !== 'function' || typeof service.estimateMessage !== 'function') return null
-  const events = Array.isArray(session?.events) ? session.events : null
-  if (!events) return null
+  // 无事件视图(既无 snapshotEvents 也无 events 数组)→ 该来源不可用(null,不再是静默空)。
+  const hasEventView = typeof session?.snapshotEvents === 'function' || Array.isArray(session?.events)
+  if (!hasEventView) return null
   let tokens = 0
   const missing = []
   for (const seq of seqs) {
-    const event = Number.isSafeInteger(seq) ? events[seq] : undefined
+    const event = Number.isSafeInteger(seq) ? eventAt(session, seq) : undefined
     let price = null
     if (event !== undefined && event !== null) {
       try {
@@ -251,14 +254,24 @@ export function createDshMarkerWriter({ validateMarker, log = () => {}, meter, d
         ? { op: 'replace', startSeq: span.start, endSeq: span.end }
         : { op: 'replace', start: span.start, end: span.end }
       const shadowed = Array.isArray(span.shadowedSeqs) ? span.shadowedSeqs.slice() : []
-      // ── 写前断言(在任何 append 之前;seq 是唯一无法提前得知的字段)──
-      // ② 第 2 段:先按「被遮蔽段」预演一次(审计 seq 未定);第 1 段落盘后再用
-      //    **真实**审计 seq 复核一次(见 assertMarkerShape 的 auditSeq 选项)。
-      const preview = { seq: 0, type: CARRIER_EVENT_TYPE, data, surfaceOp, sourceEventSeqs: shadowed.slice() }
-      assertMarkerShape(preview, 'dshAdapter.writeMarker.marker(preview)', { runtimeShape: opShape })
-      // 写前校验钩子**两阶段**(见 prewrite-guard):
-      // 阶段 pre = 落盘前只跑业务闸(回档幅度等,不依赖 seq)⇒ 拒绝时**零写入**;
-      // 阶段 post = 第 1 段已落盘、第 2 段未落盘,跑完整契约校验(审计 seq 真实存在)。
+      // ── 写前断言/校验(全部在任何 append 之前)──
+      // 两段结构**成对**(判据 = lib/marker-carrier.js:15 形状 / :23 sourceEventSeqs
+      // 首元素 = 第 1 段 seq / :32 同一读法)。任何在第 1 段落盘**之后**才失败的校验
+      // 都会留下孤儿审计行(2026-09-14 真机:seq 26032/26033 —— 官方 shadow-price
+      // claim 无人消费 ⇒ contextPressure.surfaceTokens 漂移)。
+      // 故把完整契约校验**前移**:审计段按它将被写入的位置合成进事件表,与载体一起校验。
+      // seq 是唯一无法提前得知的字段:交给 validateMarker 的信封**不带 seq**
+      // ——`createPreWriter.validateAppend` 只在 `candidate.seq === undefined` 时按
+      // nextSeq 赋值;带伪造 seq(历史硬编码 0)会被判 E2/S6/S8(见 marker-append-seq 测试)。
+      // `assertMarkerShape` 仍用 `seq: 0` 的**形状副本**(只要求 seq 是非负安全整数)。
+      const carrierEnvelope = (seqs) => ({ type: CARRIER_EVENT_TYPE, data, surfaceOp, sourceEventSeqs: seqs })
+      const withShapeSeq = (envelope) => ({ seq: 0, ...envelope })
+      const preview = carrierEnvelope(shadowed.slice())
+      assertMarkerShape(withShapeSeq(preview), 'dshAdapter.writeMarker.marker(preview)', { runtimeShape: opShape })
+      // 写前校验钩子三态(见 prewrite-guard):
+      //   pre  = 落盘前只跑业务闸(回档幅度等,不依赖 seq)⇒ 拒绝时**零写入**;
+      //   pair = **计划中的两段**(审计 + 载体)整体跑完整契约校验 ⇒ 拒绝时**零写入**;
+      //   post = 兼容旧调用方的"第 1 段已落盘"形态(本 writer 已不使用)。
       // 业务闸先于「取令牌价」:业务拒绝的错误码不该被定价路径的内部错误盖掉。
       if (typeof validateMarker === 'function') {
         await validateMarker(session, preview, { phase: 'pre' })
@@ -283,35 +296,48 @@ export function createDshMarkerWriter({ validateMarker, log = () => {}, meter, d
       // ① 第 1 段:官方词表把 `compaction/prune` 的 data 定为精确三成员
       //    (无 optional/opaque)⇒ 形状不合规一律在写盘前拦下。
       assertAuditShape({ seq: 0, type: AUDIT_EVENT_TYPE, data: auditData }, 'dshAdapter.writeMarker.audit(preview)')
-      // 第 1 段先写:两段都须引用更早 seq,且关联方向只能是「第 2 段 → 第 1 段」。
-      let auditSeq = appendAudit(session, auditData)
-      // 第 2 段:首元素 = 审计 seq,其后是**全部**被遮蔽节点(官方 provenance 硬要求
-      // 「须列全被遮蔽的面节点」)。
-      let envelope = { seq: 0, type: CARRIER_EVENT_TYPE, data, surfaceOp, sourceEventSeqs: [auditSeq, ...shadowed] }
-      assertMarkerShape(envelope, 'dshAdapter.writeMarker.marker', { runtimeShape: opShape, auditSeq })
-      if (typeof validateMarker === 'function') {
-        await validateMarker(session, envelope, { phase: 'post', auditSeq })
+      // ── pair 校验:两段作为整体,在任何 append 之前 ──────────────────────────
+      // 计划中的审计 seq = 当前追加位;校验后**同步复核**(到 appendAudit 之间无 await),
+      // 并发 append 使预言过期时重跑校验;连续漂移则零写入报错(不留孤儿)。
+      let plannedAuditSeq = nextAppendSeq(session)
+      let pairValidated = typeof validateMarker !== 'function'
+      for (let attempt = 0; attempt < 3 && !pairValidated; attempt++) {
+        const pairEnvelope = carrierEnvelope([plannedAuditSeq, ...shadowed])
+        assertMarkerShape(withShapeSeq(pairEnvelope), 'dshAdapter.writeMarker.marker(pair)', { runtimeShape: opShape, auditSeq: plannedAuditSeq })
+        await validateMarker(session, pairEnvelope, { phase: 'pair', audit: auditData, auditSeq: plannedAuditSeq })
+        const live = nextAppendSeq(session)
+        if (live === plannedAuditSeq) pairValidated = true
+        else plannedAuditSeq = live
+      }
+      if (!pairValidated) {
+        throw editorError(
+          'marker-pair-race',
+          'Concurrent appends kept moving the log tail while validating the two-segment marker; nothing was written. Retry.',
+        )
       }
+      // ── 同步段:审计 + 载体,中间没有任何 await ────────────────────────────
       // 官方 shadow-price 协议要求 claim 与 replace **紧邻**(surface-projection:
       // "producers append the metering event and the replacement synchronously
-      // adjacent, so a surviving claim always prices the very next event")。上面两次
-      // `await` 之间可能有并发 append 落盘 ⇒ claim 被顶掉 ⇒ 官方 fold 以 **0 增量**
-      // 折叠(不抛、静默)。在同步段复核相邻性,被顶掉就重挂一条审计段
-      // (旧段留在日志里:log-only,不遮蔽任何节点)。
+      // adjacent, so a surviving claim always prices the very next event")。旧流程在
+      // 两段之间有一次 post 校验 await ⇒ 并发 append 可能顶掉 claim;现在校验全部前移,
+      // 两段在同一同步段内落盘,相邻性由结构成立(rearmClaim 仅作兜底)。
+      const auditSeq = appendAudit(session, auditData)
+      if (auditSeq !== plannedAuditSeq) {
+        throw editorError(
+          'marker-pair-race',
+          `Audit segment landed at seq ${auditSeq} but the two-segment marker was validated at ${plannedAuditSeq}; nothing further was written. Retry.`,
+        )
+      }
       const reArmed = rearmClaim(session, span, auditSeq, shadowedTokenCount, log)
-      if (reArmed !== auditSeq) {
-        auditSeq = reArmed
-        envelope = { seq: 0, type: CARRIER_EVENT_TYPE, data, surfaceOp, sourceEventSeqs: [auditSeq, ...shadowed] }
-        assertMarkerShape(envelope, 'dshAdapter.writeMarker.marker', { runtimeShape: opShape, auditSeq })
-        // 重挂之后**不再 await**:任何 await 都会重新打开刚被顶掉的窗口,相邻性靠
-        // "同步段内无并发落盘"成立。post 校验已针对重挂前那条同形状、同价、seq 更小的
-        // 审计段跑过 ⇒ 这里只记一行说明(不再重跑,以免再次被顶掉)。
-        log(`retrace: 已重挂审计段 seq ${auditSeq}(post 校验针对重挂前的审计段跑过:同形状、同价、seq 更小)`)
+      const finalAuditSeq = reArmed === auditSeq ? auditSeq : reArmed
+      if (finalAuditSeq !== auditSeq) {
+        log(`retrace: 已重挂审计段 seq ${finalAuditSeq}(并发顶掉;旧段留在日志里,log-only,不遮蔽任何节点)`)
       }
-      // 第 2 段落盘。契约边界:可抛断言已全部完成(审计段是合法的 log-only 事件,
-      // 即便此后极端失败也不影响会话可构造性——见负控制实测:只写第 1 段不遮蔽任何
-      // 节点,官方链也照常接受)。
-      return session.append(CARRIER_EVENT_TYPE, data, { surfaceOp, sourceEventSeqs: [auditSeq, ...shadowed] })
+      // 第 2 段落盘(首元素 = 审计 seq,其后是全部被遮蔽节点)。
+      const carrier = session.append(CARRIER_EVENT_TYPE, data, { surfaceOp, sourceEventSeqs: [finalAuditSeq, ...shadowed] })
+      // ── 写后对账:两段成对(判据见 lib/marker-carrier.js:23/:32)──
+      assertPairing(session, finalAuditSeq, carrier)
+      return carrier
     },
   }
 }
@@ -328,7 +354,7 @@ function appendAudit(session, auditData) {
 
 /** 日志末尾事件的 seq(会话对象无 events 视图时 null ⇒ 跳过相邻性复核)。 */
 function tailSeqOf(session) {
-  const events = session?.events
+  const events = sessionEvents(session)
   if (!Array.isArray(events) || events.length === 0) return null
   const last = events[events.length - 1]
   return Number.isSafeInteger(last?.seq) ? last.seq : null
@@ -348,3 +374,30 @@ function rearmClaim(session, span, auditSeq, shadowedTokenCount, log) {
     shadowedTokenCount,
   })
 }
+
+/**
+ * 写后对账:第 2 段与第 1 段**成对**。
+ *
+ * 判据取自契约本身(`lib/marker-carrier.js`):
+ *   - `:15` 形状 = 第 1 段先写、第 2 段后写,两者都引用更早 seq;
+ *   - `:23` 第 2 段 `sourceEventSeqs = [<第 1 段 seq>, …全部被遮蔽节点]`;
+ *   - `:32` 关联读法(判据):第 2 段 `sourceEventSeqs` **首元素 = 第 1 段 seq**。
+ * 不满足 ⇒ 显式失败(marker-pair-unpaired),不静默返回半写结果。
+ * @param {object} session
+ * @param {number} auditSeq - 第 1 段(审计)seq
+ * @param {object} carrier - 第 2 段(载体)事件
+ */
+function assertPairing(session, auditSeq, carrier) {
+  const auditEvent = eventAt(session, auditSeq)
+  const first = Array.isArray(carrier?.sourceEventSeqs) ? carrier.sourceEventSeqs[0] : undefined
+  const paired = first === auditSeq
+    && Number.isSafeInteger(carrier?.seq)
+    && carrier.seq === auditSeq + 1
+    && auditEvent?.type === AUDIT_EVENT_TYPE
+  if (!paired) {
+    throw editorError(
+      'marker-pair-unpaired',
+      `Marker segments are not paired: carrier.seq=${String(carrier?.seq)} sourceEventSeqs[0]=${String(first)} audit seq=${auditSeq} (event type=${String(auditEvent?.type ?? 'missing')}). An orphan audit segment may remain in the log () — do not ignore.`,
+    )
+  }
+}

package/lib/adapter/dsh.js

@@ -4,7 +4,7 @@
  * DSH 平台适配器(2026-09-01)——实现 EventReader 接口。
  *
  * 职责:从 DSH 会话文件(session.jsonl.zstd)读全量事件——可靠事实,
- * 不依赖 host 内存视图(DSH 2.0.3 host 的 session.events 可能稀疏/窗口化)。
+ * 不依赖 host 内存视图(DSH 2.0.3 host 的事件视图可能稀疏/窗口化)。
  *
  * 换架构时:业务层(message-list.js/守卫)零改动,新平台实现自己的 EventReader
  * (读自己的日志格式 → 同样的通用事件结构)。
@@ -12,8 +12,7 @@
 // 会话文件定位($DSH_HOME/sessions → ~/dsh-v3/sessions → ~/.dsh/sessions;两种文件名
 // 都认、同目录并存取 mtime 新者)收敛到 lib/platform/session-paths.js 单一实现——
 // 此前本文件与 watchdog/archaeology-cli 各写一份硬编码,基座换代时口径必然分叉。
-import { homedir } from 'node:os'
-import { sessionFilePath, activeSessionsRoot, listSessionFiles } from '../platform/session-paths.js'
+import { sessionFilePath, activeSessionsRoot, listSessionFiles, workspaceAbbr } from '../platform/session-paths.js'
 // 官方 foldSurface:重放得与写入端完全一致的 surface nodes(replace 插 marker、
 // 遮蔽移除节点 → nodes 非 seq 单调;span 计算必须用它,否则 start/end indexOf
 // 会 not found/倒置 → S4/S8 拒 → 撤回死锁)。peerDep 提供。
@@ -215,7 +214,7 @@ export function computeSpan(events, target, mode = 'round') {
  * 文件侧「目标同一轮的前置 user 原文」——regenerate
  * 重发文本的唯一可靠来源。
  *
- * 为什么必须算在文件侧:host 内存 session.events 是窗口化/稀疏视图(带 undefined 洞),
+ * 为什么必须算在文件侧:host 内存事件视图是窗口化/稀疏视图(带 undefined 洞),
  * regenerate 在内存里「向前找最近的前置 user」会越过洞(洞里正是该轮 user)或越过被
  * 遮蔽区间,选到**更早轮**的 user → 重发错文本 + marker targetSeq 指向错轮。round span
  * 的起点在文件全量 events + 官方 foldSurface nodes 上就是目标同一轮的轮首 user
@@ -286,7 +285,7 @@ export const dshAdapter = {
   },
   /**
    * 从文件全量事件算某 turn 内的最大 step 号(情形② marker step 分配用)。
-   * 绕开 host 窗口化 session.events(稀疏内存视图可能看不到 turn 内全部 step,
+   * 绕开 host 窗口化事件视图(稀疏内存视图可能看不到 turn 内全部 step,
    * 算小 → 新 step 号与窗口外既有 step 冲突 = step key 冲突白屏)。
    * 失败返回 null(调用方 fallback 内存扫描)。
    * @param {string} [filePath] 可选:直接指定会话文件路径(测试注入)。
@@ -294,38 +293,16 @@ export const dshAdapter = {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// 语义短码推导(2026-09-02)——工作区 createdAt 序号 + 父链,与修复线
+// 语义短码推导(2026-09-02)——工作区 createdAt 序号 + 父链,与外部工具
 // 短码表生成器同规则(表的新鲜版,不冲突)。
 // 短码 = 工作区2 + 序号3 + 父工作区2 + 父序号3;根父 = FF000。
 // 只读会话文件帧1(header),全量 ~110 会话 ≈ 30ms,懒加载缓存。
 // ─────────────────────────────────────────────────────────────────────────────
 
 /**
- * 工作区目录名 → 2 位缩写。
- *
- * 会话目录名是**工作区绝对路径**把 `/` 换成 `-`、首尾再各加 `--`
- * （`/Users/<user>/proj` → `--Users-<user>-proj--`）。缩写口径：先剥掉
- * **机器相关前缀**（用户 home），再剥掉平台前缀（Users、home、Volumes 等），
- * 最后取剩下前两段的首字母；只有一段时取其前两个字符。
- *
- * ⚠️ 这里**不得**写死任何具体用户名 —— 旧实现硬编码了某一台机器的用户名，
- * 换台机器就会把工作区缩写算错（进而是错误的短码）。home 由 `os.homedir()`
- * 推出，因此本函数在任何机器上自洽。
+ * 工作区目录名 → 2 位缩写：实现见 `lib/platform/session-paths.js`（单一真相；
+ * 短码侧 `lib/identity/shortcode.js` 与本文件的推导器共用同一份，避免换机器分叉）。
  */
-function workspaceAbbr(workspace) {
-  const raw = String(workspace ?? '')
-  const encoded = raw.replace(/^--/, '').replace(/--$/, '')
-  let rest = encoded
-  const homeEnc = homedir().replace(/\//g, '-').replace(/^-+/, '').replace(/-+$/, '')
-  if (homeEnc && (rest === homeEnc || rest.startsWith(homeEnc + '-'))) {
-    rest = rest.slice(homeEnc.length).replace(/^-+/, '')
-  } else {
-    rest = rest.replace(/^-*(?:Users|home|Volumes|private|var|tmp)-/i, '')
-  }
-  const parts = rest.split('-').filter(Boolean)
-  if (parts.length >= 2) return (parts[0][0] + parts[1][0]).toLowerCase()
-  return (parts[0] ?? encoded).slice(0, 2).toLowerCase()
-}
 
 /** 派生短码表:扫活动基座各工作区会话 header,按 createdAt 排序编号,含父链。 */
 export async function deriveBadgeTable(opts = {}) {

package/lib/archaeology-cli.js

@@ -1,7 +1,7 @@
 /**
  * dsh-retrace · lib/archaeology-cli.js
  *
- * 会话日志考古 CLI 的核心逻辑（任务书 dsh-会话日志考古-插件任务与方法.md A1-A4）。
+ * 会话日志考古 CLI 的核心逻辑(只读索引 / 查询 / 抽取 / 文件历史 / 谱系)。
  * 与 dsh-log-contract 的 archaeology.js 分工：B 侧提供 extract/audit 纯函数，
  * 本模块提供 A 侧的文件版本考古（write/edit 重放）与谱系（parent 链）。
  * **只读不写**（纪律 §8.1）。

package/lib/badge.js

@@ -8,7 +8,7 @@
  * 不依赖外部短码表、插件运行时自算即可。同一 session id 永远得到同一短码。
  *
  * 与 `会话短码表.json`(工作区 2 位 + 序号 3 位)的关系：
- * - 外部表 = 人工维护的语义短码（线名/父子关系可读），由修复线维护；
+ * - 外部表 = 人工维护的语义短码（线名/父子关系可读），由外部工具维护；
  * - 本模块 = 插件自算的确定性短码（人机交互兜底），任何环境可复现；
  * - 两者并存：铭牌优先显示外部语义短码（若可查），否则用本模块兜底。
  *

package/lib/boundary-derive.js

@@ -0,0 +1,107 @@
+/**
+ * dsh-retrace — lib/boundary-derive.js
+ *
+ * READ-SIDE derivation of the boundary digest ("what did this boundary throw
+ * away?") for boundaries that have NO stored artifact record.
+ *
+ * Why this exists (real-machine finding 2026-09-15): the digest artifact
+ * (`<pluginDataHome()>/dsh-retrace/summaries/<sessionId>.jsonl`) is written at
+ * OPERATION time and only started shipping with the summary feature, so every
+ * boundary that predates it has no record — the read point then rendered one
+ * bare line (`替换 / 9-1 16:30 / 当时共 2241 条消息`) with no content at all.
+ * The discarded ORIGINALS are still in the session log, so the digest can be
+ * recomputed on read.
+ *
+ * Authority order: a STORED record always wins. The stored digest was built at
+ * operation time, when the replaced window was still on the surface; once
+ * compaction removes those events, the log can no longer reproduce it. This
+ * module is the fallback, never an override.
+ *
+ * Pure (no imports beyond two pure siblings, no I/O): the caller passes an
+ * `eventAt(seq)` accessor, so the host seam, the HTTP route and the tests all
+ * drive the same rule and a test can hand it a plain Map.
+ */
+import { makeWhat } from './boundary-what.js'
+import { classifyBoundaryKind, replacedSeqsOfBoundary } from './version-index.js'
+
+/**
+ * Derive one digest record per version that has no stored artifact line.
+ *
+ * @param {object} input
+ * @param {Array<{boundarySeq:number, versionId?:string}>} input.versions - the
+ *   boundaries to derive for (normally "our" boundaries only; a host-side
+ *   replacement is skipped even if it is passed in).
+ * @param {(seq:number)=>object|undefined} input.eventAt - one event by exact seq.
+ * @param {Set<number>} [input.boundarySeqs] - the boundary seqs used to SLIM
+ *   `discardedSeqs` (same convention as the write side: membership only ever
+ *   asks about another boundary's seq, `discardedCount` keeps the exact |S|).
+ *   Defaults to the passed `versions`.
+ * @returns {object[]} derived artifact-shaped records (`derived: true`)
+ */
+/** 这一档属于哪一轮（人读）：载体事件 → 被替换段里第一个带 turn 的事件 → null。 */
+export function turnOfBoundary(event, spanEvents = []) {
+  // 实测：撤回/编辑/重发的"载体"事件常常不带 `data.turn`，被它替换掉的那一段才
+  // 带 ⇒ 先看载体，再在被替换段里取第一个可用 turn。都取不到就 null（调用方整段
+  // 省略，不编造"第 ? 轮"）。
+  const usable = (value) => (Number.isSafeInteger(value) && value > 0 ? value : null)
+  const own = usable(event?.data?.turn) ?? usable(event?.turn)
+  if (own !== null) return own
+  for (const spanEvent of spanEvents) {
+    const found = usable(spanEvent?.data?.turn) ?? usable(spanEvent?.turn)
+    if (found !== null) return found
+  }
+  return null
+}
+
+export function deriveBoundaryRecords({ versions, eventAt, boundarySeqs = null } = {}) {
+  const list = Array.isArray(versions) ? versions : []
+  if (typeof eventAt !== 'function') return []
+  const boundarySet = boundarySeqs instanceof Set
+    ? boundarySeqs
+    : new Set(list.map((version) => version?.boundarySeq).filter((seq) => Number.isSafeInteger(seq)))
+  const out = []
+  for (const version of list) {
+    const boundarySeq = version?.boundarySeq
+    if (!Number.isSafeInteger(boundarySeq)) continue
+    const event = eventAt(boundarySeq)
+    if (event === undefined || event === null) continue
+    const kind = classifyBoundaryKind(event)
+    // Host-origin surface replacement (a tool result re-rendered by the host):
+    // never a read point of ours, so never given a digest.
+    if (kind === 'replace') continue
+    // The EXACT removed set: the carrier's own citation minus its audit guide
+    // item (never a numeric window — see lib/boundary-tree.js).
+    const removed = replacedSeqsOfBoundary(event, null)
+    const spanEvents = removed.map((seq) => eventAt(seq)).filter((spanEvent) => spanEvent !== undefined)
+    // 轮次：载体自身常不带 turn（实测），被替换的那一段才带 ⇒ 用它的 turn 告诉
+    // 用户"这一轮的输入"是哪一轮；都取不到就省略（不编造）。
+    const turn = turnOfBoundary(event, spanEvents)
+    const what = makeWhat({
+      op: kind,
+      at: event.time,
+      spanEvents,
+      // The EXACT seq list is passed explicitly: when compaction already ate the
+      // originals, `makeWhat` still lists them (role `unknown`, empty excerpt) and
+      // reports `replacedMore`, so the row keeps saying "丢弃了 N 条消息" instead
+      // of collapsing to a content-free line.
+      replacedSeqs: removed,
+      // The action's own NEW text is NOT reconstructible here: the carrier keeps
+      // only the archive notice (measured: every carrier's second segment reads
+      // "（此处内容已被撤回…）"), and the live continuation is a different node.
+      // Leaving it empty keeps the client from printing a misleading 延续 line.
+      newText: '',
+    })
+    out.push({
+      boundarySeq,
+      turn,
+      versionId: typeof version.versionId === 'string' ? version.versionId : `v${boundarySeq}`,
+      kind,
+      at: typeof event.time === 'number' ? event.time : undefined,
+      what,
+      discardedSeqs: removed.filter((seq) => boundarySet.has(seq)),
+      discardedCount: removed.length,
+      derived: true,
+    })
+  }
+  return out
+}