dsh-retrace 0.4.27 → 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,12 +305,12 @@ 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.27` adapts to — *not caused by this plugin*
+### 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.27` reaches the log through a
+   `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
@@ -311,14 +318,14 @@ Read it before filing an issue.
    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.27` prefers the official `list()` and falls
+   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.27` (these are ours)
+### 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
@@ -333,21 +340,35 @@ Read it before filing an issue.
   **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] 668f9166-648c-4c`). Title tagging now goes
+  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.27
+dsh plugin --profile desktop add dsh-retrace@0.4.28
 # then restart DSH — plugins are not hot-reloaded
 ```
 
-**`0.4.27` needs no data migration.** The session format is unchanged (v3), no session is
+**`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.
@@ -372,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.
@@ -392,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.
@@ -416,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.
 
 ---
 
@@ -466,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.js

@@ -293,7 +293,7 @@ export const dshAdapter = {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// 语义短码推导(2026-09-02)——工作区 createdAt 序号 + 父链,与修复线
+// 语义短码推导(2026-09-02)——工作区 createdAt 序号 + 父链,与外部工具
 // 短码表生成器同规则(表的新鲜版,不冲突)。
 // 短码 = 工作区2 + 序号3 + 父工作区2 + 父序号3;根父 = FF000。
 // 只读会话文件帧1(header),全量 ~110 会话 ≈ 30ms,懒加载缓存。

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

package/lib/boundary-now.js

@@ -0,0 +1,139 @@
+/**
+ * dsh-retrace — lib/boundary-now.js
+ *
+ * READ-SIDE "现在这条" (the counterpart that lives in the conversation TODAY).
+ *
+ * Why this exists (real-machine reading order, 2026-09-15): an entry could say
+ * WHAT it replaced ("原来的内容：…") but never WHERE it was replaced FROM. The
+ * user's words: 「这个条目，现在是什么我并不知道」. The anchor is the message the
+ * action left behind — for an edit/resend it is OUR own `retrace-resend-*` node
+ * (measured: boundary #8699 → #8706), for a regenerate it is the assistant reply
+ * the host produced afterwards.
+ *
+ * What this module deliberately does NOT do: reconstruct the round's input. The
+ * conversation itself is readable — only the REPLACED copy is ours to keep.
+ *
+ * Rules (measured on a 27k-event / 34-boundary session):
+ *  - only `edit` / `regenerate` have a counterpart. A pure `recall` retracts and
+ *    is followed by later, unrelated input — picking that would be a lie.
+ *  - the counterpart must be a LIVE node: anything a later boundary already
+ *    replaced (`shadowedSeqs`) is excluded, otherwise the entry would point at
+ *    a message that is no longer on the surface.
+ *  - the boundary's OWN carrier / audit events are never the counterpart: they
+ *    are the marker, not the new content.
+ *
+ * Pure (no I/O, no host access): the caller passes the log array and the shadowed
+ * set, so the seam, the HTTP route and the tests all drive the same rule.
+ */
+import { eventText, excerpt, roleOf } from './boundary-what.js'
+import { isReplacementSurfaceEvent, replacedSeqsOfBoundary } from './version-index.js'
+
+/** Our own resend node: written by the edit/resend op. */
+export const RESEND_ID_PREFIX = 'retrace-resend-'
+
+/** Any id we write (marker / carrier / resend / fold) — never a counterpart. */
+const OUR_ID_PREFIX = 'retrace-'
+
+/** `<id>` of a surface event, whichever slot the host used. */
+function idOf(event) {
+  const id = event?.data?.id ?? event?.data?.message?.id
+  return typeof id === 'string' ? id : ''
+}
+
+/** One counterpart candidate as the reader needs it (no raw seq shown). */
+function nowOf(event) {
+  return {
+    seq: event.seq,
+    role: roleOf(event),
+    excerpt: excerpt(eventText(event)),
+  }
+}
+
+/**
+ * Index the log once: the counterpart candidates, in ascending seq order.
+ *
+ * @param {object[]} events - the session's events (ascending seq)
+ * @param {Set<number>} [shadowedSeqs] - seqs replaced by SOME boundary (ours or
+ *   the host's). Those are off the surface and cannot be "现在这条".
+ * @returns {{resends: object[], replies: object[]}}
+ */
+export function buildNowIndex(events, shadowedSeqs = new Set()) {
+  const list = Array.isArray(events) ? events : []
+  const shadowed = shadowedSeqs instanceof Set ? shadowedSeqs : new Set()
+  const resends = []
+  const replies = []
+  for (const event of list) {
+    const seq = event?.seq
+    if (!Number.isSafeInteger(seq) || shadowed.has(seq)) continue
+    const id = idOf(event)
+    if (id.startsWith(RESEND_ID_PREFIX)) {
+      resends.push(nowOf(event))
+      continue
+    }
+    // A regenerate's counterpart is the host's new assistant reply. Our own
+    // `retrace-*` nodes are markers, never the reply itself.
+    if (event.type === 'assistant/message' && !id.startsWith(OUR_ID_PREFIX)) replies.push(nowOf(event))
+  }
+  resends.sort((a, b) => a.seq - b.seq)
+  replies.sort((a, b) => a.seq - b.seq)
+  return { resends, replies }
+}
+
+/**
+ * The counterpart of ONE boundary, or null when there is honestly none.
+ *
+ * @param {string} kind - `classifyBoundaryKind` result (`edit` / `regenerate` /
+ *   `recall` / `compaction` / `replace`)
+ * @param {number} boundarySeq
+ * @param {{resends: object[], replies: object[]}} index - from `buildNowIndex`
+ * @returns {{seq:number, role:string, excerpt:string}|null}
+ */
+export function nowOfBoundary(kind, boundarySeq, index) {
+  if (kind !== 'edit' && kind !== 'regenerate') return null
+  if (!Number.isSafeInteger(boundarySeq) || index === null || index === undefined) return null
+  const candidates = kind === 'edit' ? index.resends : index.replies
+  if (!Array.isArray(candidates)) return null
+  for (const candidate of candidates) {
+    if (Number.isSafeInteger(candidate?.seq) && candidate.seq > boundarySeq) return candidate
+  }
+  return null
+}
+
+/**
+ * Every seq that some SURFACE REPLACEMENT took off the surface (ours AND the
+ * host's). Used to keep a counterpart from pointing at a message that is no
+ * longer live.
+ *
+ * Scope = THIS PLUGIN's own replacements (`retrace-*` markers). Two things stay
+ * out, both measured on the real session:
+ *
+ *  - ordinary events that merely CITE their precursors (`tool/result` → its
+ *    `tool/call`). Counting those marked 14644 seqs "shadowed" instead of 107.
+ *  - other surface owners' bulk operations (another plugin's fold ranges, the
+ *    host's compaction checkpoints). They hide ranges from the VIEW/CONTEXT
+ *    while the messages stay in the log. Counting them made every one of the 23
+ *    real edits report "the counterpart is no longer in the log", including the
+ *    case this reading order was specified from: boundary #8699 → the resend
+ *    node #8706.
+ *
+ * Our own later replacement is different: the marker stands in that node's place
+ * for good, so that node can never be "现在这条" again.
+ *
+ * @param {object[]} events
+ * @param {(event:object)=>boolean} [isOurs] - id predicate for this plugin's
+ *   markers (defaults to the `retrace-` prefix).
+ * @returns {Set<number>}
+ */
+export function shadowedSeqsOf(events, isOurs = null) {
+  const owns = typeof isOurs === 'function' ? isOurs : (event) => idOf(event).startsWith(OUR_ID_PREFIX)
+  const shadowed = new Set()
+  if (!Array.isArray(events)) return shadowed
+  for (const event of events) {
+    if (!isReplacementSurfaceEvent(event)) continue
+    if (!owns(event)) continue
+    for (const seq of replacedSeqsOfBoundary(event, null)) {
+      if (Number.isSafeInteger(seq)) shadowed.add(seq)
+    }
+  }
+  return shadowed
+}

package/lib/boundary-tree.js

@@ -0,0 +1,126 @@
+/**
+ * dsh-retrace — lib/boundary-tree.js
+ *
+ * The read-point outline forest: "which change landed inside which discarded
+ * set". Derived from our own boundary artifact (one record per boundary, each
+ * carrying `discardedSeqs` — the exact surface nodes that operation removed),
+ * so the client can indent nested branches without touching the projection wire.
+ *
+ * RULE (frozen 2026-09-14, corrected by measurement; DO NOT change back to set
+ * inclusion):
+ *   parent(C) = the boundary B whose discarded set CONTAINS C's own event seq,
+ *   `C.seq ∈ S(B)`, choosing the SMALLEST such |S(B)|.
+ *
+ * Why NOT `S(C) ⊆ S(B)` (the rule first written into the contract): measured on
+ * a real 24k-event session, the child's discarded nodes were **already dead**
+ * when the parent replaced its range (the child ran FIRST), so
+ * `|S(child) ∩ S(parent)| = 0` for every one of the 8 links of the real 9-layer
+ * chain. The parent's set only holds the child's MARKER event seq — that node was
+ * still on the surface at that moment. Inclusion therefore yields a degenerate
+ * forest (1 parent / depth 1) instead of 14 parents / depth 9. Membership is
+ * still an EXACT SET operation: no numeric interval is ever enumerated, and no
+ * `start ≤ end` ordering is assumed — a reversed range (`[16093..15458]`, real
+ * data) never enters this module.
+ *
+ * The discarded sets may be STORED SLIMMED (`S ∩ allBoundarySeqs`, see
+ * lib/versioning.js) because membership only ever asks about another boundary's
+ * seq; `discardedCount` then carries the exact `|S|`. Both forms must yield a
+ * byte-identical tree (pinned by a test).
+ *
+ * Zero imports (pure): the host, the route and the tests all share one rule.
+ */
+
+/** Parse one record's discarded seqs into a Set (invalid entries dropped). */
+function discardedSetOf(record) {
+  const raw = record?.discardedSeqs
+  if (!Array.isArray(raw)) return null
+  const set = new Set()
+  for (const seq of raw) if (Number.isSafeInteger(seq) && seq >= 0) set.add(seq)
+  return set
+}
+
+/** Exact `|S|`: the stored `discardedCount` when present, else the set's size. */
+function discardedCountOf(record, set) {
+  return Number.isSafeInteger(record?.discardedCount) && record.discardedCount >= 0 ? record.discardedCount : set.size
+}
+
+/** Distance used to break equal-size parent candidates (nearest ancestor wins). */
+function tieBreak(childSeq, a, b) {
+  const da = Math.abs(a.seq - childSeq)
+  const db = Math.abs(b.seq - childSeq)
+  if (da !== db) return da - db
+  return a.seq - b.seq
+}
+
+/**
+ * Build the outline forest from artifact records.
+ *
+ * @param {object[]} records - artifact lines ({ boundarySeq, discardedSeqs, ... })
+ * @returns {{
+ *   tree: Record<string, {parent:number|null, children:number[], discardedCount:number}>,
+ *   maxDepth: number,
+ *   withChildren: number,
+ *   nodes: number
+ * } | null} null when no record carries a usable `discardedSeqs`
+ *   (old artifacts, or a session that never recorded one) — the caller then
+ *   OMITS the field and the client falls back to a flat list.
+ */
+export function boundaryTreeOf(records) {
+  if (!Array.isArray(records)) return null
+  // Latest record wins per boundary (the artifact is append-only).
+  const latest = new Map()
+  for (const record of records) {
+    if (!Number.isSafeInteger(record?.boundarySeq)) continue
+    latest.set(record.boundarySeq, record)
+  }
+  const entries = []
+  for (const [seq, record] of latest) {
+    const set = discardedSetOf(record)
+    if (set === null) continue
+    entries.push({ seq, set, count: discardedCountOf(record, set) })
+  }
+  if (entries.length === 0) return null
+
+  const childrenBySeq = new Map(entries.map((entry) => [entry.seq, []]))
+  const parentBySeq = new Map()
+  for (const child of entries) {
+    let best = null
+    for (const candidate of entries) {
+      if (candidate.seq === child.seq) continue
+      if (!candidate.set.has(child.seq)) continue
+      // Smallest containing set = the direct parent; an intermediate D would be
+      // smaller and would have won. Equal sizes fall back to the nearest seq.
+      if (best === null || candidate.count < best.count || (candidate.count === best.count && tieBreak(child.seq, candidate, best) < 0)) {
+        best = candidate
+      }
+    }
+    parentBySeq.set(child.seq, best === null ? null : best.seq)
+    if (best !== null) childrenBySeq.get(best.seq).push(child.seq)
+  }
+
+  const tree = {}
+  for (const entry of entries) {
+    tree[String(entry.seq)] = {
+      parent: parentBySeq.get(entry.seq) ?? null,
+      children: (childrenBySeq.get(entry.seq) ?? []).slice().sort((a, b) => a - b),
+      discardedCount: entry.count,
+    }
+  }
+
+  const depthMemo = new Map()
+  const depthOf = (seq) => {
+    if (depthMemo.has(seq)) return depthMemo.get(seq)
+    depthMemo.set(seq, 0) // cycle guard (a parent always has a larger discarded set)
+    const kids = childrenBySeq.get(seq) ?? []
+    const depth = kids.length === 0 ? 0 : 1 + Math.max(...kids.map(depthOf))
+    depthMemo.set(seq, depth)
+    return depth
+  }
+  let maxDepth = 0
+  let withChildren = 0
+  for (const entry of entries) {
+    maxDepth = Math.max(maxDepth, depthOf(entry.seq))
+    if ((childrenBySeq.get(entry.seq) ?? []).length > 0) withChildren += 1
+  }
+  return { tree, maxDepth, withChildren, nodes: entries.length }
+}