dsh-retrace 0.4.27 → 0.4.29

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.29
 # 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.
@@ -406,19 +439,26 @@ the **host surface**, not by semver alone.
 | 🛡️ | **Running-work detection** | every session is scanned for live work: agent running, queued inbox items, background jobs, unclosed turns |
 | 📋 | **Running banner** | sessions with live work show a persistent in-page banner (short session code + reasons), so you can see it before quitting |
 | ⚠️ | **Exit prompt** | on plugin dispose (app exit / reload) a Chinese notice lists each running session and why it is considered busy — it only warns, it never cancels your running agent |
-| 🔒 | **Page-close interception (Web)** | `beforeunload` interception: a strong confirm when work is running (details modal, `[仍关闭]` = confirm-and-go), a light confirm otherwise |
-| 🔎 | **Query surface** | `retrace.runningState` (host RPC) + `GET|POST /api/plugins/retrace/runningState` (HTTP) — same shape on both transports |
-
-> Desktop note: the Electron shell destroys the window on quit, so the page-level
-> `beforeunload` hook cannot fire there and the host exposes no plugin quit-veto seam —
-> Desktop is covered by the running banner plus the dispose notice; Web gets the full
-> interception.
+| 🔒 | **Page-close interception (web browsers)** | `beforeunload` interception, armed only where the host reports a native confirm dialog: a strong confirm when work is running (details modal, `[仍关闭]` = confirm-and-go), a light confirm otherwise |
+| 🔎 | **Query surface** | `retrace.runningState` (host RPC) + `GET|POST /api/plugins/retrace/runningState` (HTTP) — same shape on both transports; the all-sessions shape also carries the host-reported page surface (`surface` / `quitVeto`) |
+
+> Desktop note: quit entry points differ by version/platform, and the DSH Desktop Electron
+> shell we inspected has no `will-prevent-unload` handler (0 hits across the packaged 2.0.9
+> `app.asar`). Where the entry does reach the page — the external report's DSH Desktop 0.9.0 /
+> Windows — the page `beforeunload` veto is **swallowed silently**: no dialog, no feedback, and
+> the exit looks stuck (only a force-quit works). Where it does not — the 2.0.9 shell we
+> inspected routes the tray item through `requestQuit(0) → window.destroy() → app.exit(0)` — the
+> quit is unaffected either way. The page cannot tell which case it is in, so desktop **never**
+> arms the native gate; it relies on the running banner plus the dispose notice. The gate is
+> armed only where the host reports that the page really surfaces a native dialog
+> (`quitVeto: true`, i.e. browser pages).
 
 > 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 +506,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 优先 + 快照兜底、干跑预览、跳转对话）。
 - 对话视图内的**分叉图** + **会话谱系**。
 - **实时看门狗**——并发写入第一时间快照日志。
@@ -313,13 +326,18 @@ dsh plugin --profile desktop add dsh-retrace@0.4.26
 | 🛡️ | **运行中检测** | 逐会话扫描运行中工作：agent 正在跑 / inbox 排队 / 后台 jobs / 未闭合轮 |
 | 📋 | **运行中横幅** | 有运行中工作的会话显示页面常驻横幅（会话短码 + 原因），退出前可见 |
 | ⚠️ | **退出提示** | 插件 dispose（应用退出/重载）时中文提示列出每个运行中会话与原因——只提示，绝不代你取消 agent |
-| 🔒 | **页面关闭拦截（Web）** | `beforeunload` 拦截：有运行中任务强确认（明细模态，`[仍关闭]` 即确认离开），无任务轻确认 |
-| 🔎 | **查询面** | `retrace.runningState`（host RPC）+ `GET|POST /api/plugins/retrace/runningState`（HTTP），两入口同形状 |
+| 🔒 | **页面关闭拦截（普通浏览器）** | `beforeunload` 拦截，只在宿主回报会弹原生确认框的页面上武装：有运行中任务强确认（明细模态，`[仍关闭]` 即确认离开），无任务轻确认 |
+| 🔎 | **查询面** | `retrace.runningState`（host RPC）+ `GET|POST /api/plugins/retrace/runningState`（HTTP），两入口同形状；全会话形状另带宿主判定的承载面（`surface` / `quitVeto`） |
 
-> 桌面说明：Electron 宿主退出时销毁窗口，页面 `beforeunload` 不会触发，宿主也未暴露
-> 插件可用的退出否决点——桌面侧由运行中横幅 + dispose 提示覆盖；Web 端拦截完整生效。
+> 桌面说明：**退出入口随版本/平台而变**，而我们检查的 Electron 壳没有处理 `will-prevent-unload`
+> （装好的 2.0.9 `app.asar` 全文检索 0 命中）。**会走到该入口的那类版本**（外部报告所在的
+> DSH Desktop 0.9.0 / Windows）上，页面 `beforeunload` 否决被**静默吞掉**：不弹界面、不给
+> 反馈，表现为退出卡住（只能强退）；**不走该入口的版本**（我们检查的 2.0.9：托盘项走
+> `requestQuit(0) → window.destroy() → app.exit(0)`）上，退出本来就不受影响。页面里分不出
+> 自己属于哪一类，因此**桌面端一律不武装**原生门，保护由运行中横幅 + dispose 提示承担；
+> 只有宿主回报"这个页面会弹原生确认框"（`quitVeto: true`，即普通浏览器页）时才武装。
 
-**未来计划**——见 [公开路线图](https://github.com/yamingmou/dsh-retrace/blob/main/docs/ROADMAP.md)（agent 业务层规划：运行时守护、中断治理、生态开放接口）。本 README 只描述已上线的能力。
+**未来计划**——agent 业务层规划（运行时守护、中断治理、生态开放接口）**尚未发布**，此节是**计划**而非已上线能力。本 README 描述的是**开发线（main）**，可能领先于 npm 上最新发布版。
 
 ---
 
@@ -366,8 +384,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/boot-pin.js

@@ -0,0 +1,94 @@
+/**
+ * dsh-retrace — lib/boot-pin.js
+ *
+ * 启动批量 pin 的**重试调度**（唯一职责:什么时候再跑一次)。
+ *
+ * 从 lib/index.js 迁出的理由(2026-09-18 外部 issue #1:桌面端托盘退出死锁):
+ * 原实现是内联的递归 `setTimeout`,句柄被丢弃、既不 `unref` 也不在 dispose 里清。
+ * 宿主是 Node 侧 —— 一条 30s 递归(最多 20 次 ≈ 启动后 10 分钟)会把宿主事件循环
+ * 钉住,退出/关机流程得等它跑完(桌面端退不掉的两个拖累之一,另一个见
+ * lib/watchdog.js)。
+ *
+ * 与 lib/watchdog.js 同款:定时器创建/销毁可注入(`schedule` / `unschedule`),
+ * 于是"句柄有没有 unref""dispose 有没有撤销"能被用例直接捕获,不靠 review。
+ * 职责边界:本模块只决定"何时重试";"重试做什么"由 `run()` 注入(装配点传
+ * pinAllResident),"现在有没有可处理的会话"由 `hasResidentSessions()` 注入。
+ * 本模块零 import、零宿主服务引用(可单测,也进得了动态件 realm)。
+ */
+
+/** 默认重试上限(对齐 0.4.19 的启动窗口:20 × 30s ≈ 启动后 10 分钟)。 */
+export const BOOT_PIN_MAX_ATTEMPTS = 20
+/** 默认重试间隔。 */
+export const BOOT_PIN_DELAY_MS = 30_000
+
+/**
+ * 建启动重试链。
+ * @param {object} options
+ * @param {() => Promise<any>} options.run 实际执行体(返回值里的 `value.total` 用于日志)。
+ * @param {() => boolean} options.hasResidentSessions 现在有没有可处理的会话。
+ * @param {(line: string) => void} [options.log] 诊断日志。
+ * @param {number} [options.maxAttempts] 重试上限(含首跑)。
+ * @param {number} [options.delayMs] 重试间隔。
+ * @param {(cb: () => void, ms: number) => unknown} [options.schedule] 定时器创建
+ *   (默认全局 setTimeout;返回的句柄上若有 `unref` 会被调用)。
+ * @param {(handle: unknown) => void} [options.unschedule] 定时器销毁(默认全局 clearTimeout)。
+ * @returns {{ dispose(): void }} dispose = 停止重试链 + 撤掉挂着的定时器(幂等)。
+ */
+export function createBootPinRetry({
+  run,
+  hasResidentSessions,
+  log = () => {},
+  maxAttempts = BOOT_PIN_MAX_ATTEMPTS,
+  delayMs = BOOT_PIN_DELAY_MS,
+  schedule = (cb, ms) => setTimeout(cb, ms),
+  unschedule = (handle) => clearTimeout(handle),
+} = {}) {
+  if (typeof run !== 'function') throw new TypeError('createBootPinRetry: run must be a function')
+  if (typeof hasResidentSessions !== 'function') throw new TypeError('createBootPinRetry: hasResidentSessions must be a function')
+
+  let timer = null
+  let disposed = false
+
+  /** 挂下一次(序号 = next)。序号到顶就不挂,链自然收尾。 */
+  function arm(next) {
+    if (disposed || next >= maxAttempts) return
+    timer = schedule(() => {
+      timer = null
+      step(next + 1)
+    }, delayMs)
+    // 宿主是 Node 侧:不 unref ⇒ 这条 30s 递归把事件循环钉到启动后 10 分钟,
+    // 退出/关机被它拖住。unref 后宿主该退就退(会话仍在时事件循环自有别的句柄撑着)。
+    if (timer && typeof timer.unref === 'function') timer.unref()
+  }
+
+  function step(current) {
+    if (disposed) return
+    const finish = () => arm(current)
+    if (!hasResidentSessions()) {
+      finish()
+      return
+    }
+    Promise.resolve()
+      .then(() => run())
+      .then((result) => {
+        log(`retrace: bootPin(${current}) → ${result?.value?.total ?? 0} 个驻留会话标题已处理`)
+      })
+      .catch((error) => {
+        log(`retrace: bootPin error: ${String(error).slice(0, 160)}`)
+      })
+      .then(finish)
+  }
+
+  step(0)
+
+  return {
+    /** 停止重试链并撤掉挂着的定时器(重复调用安全)。 */
+    dispose() {
+      disposed = true
+      if (timer !== null) {
+        unschedule(timer)
+        timer = null
+      }
+    },
+  }
+}

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