dsh-retrace 0.4.10 → 0.4.12

package/README.md

@@ -2,11 +2,9 @@
 
 # 🧭 dsh-retrace
 
-**Retrace · 回溯** — Recall · Edit-and-resend · Regenerate, plus **in-conversation
-versioning**: a timeline of every rewind, artifact rollback, and a fork map of the
-paths your conversation explored (roadmap). A Harness enhancement plugin for the
-[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web GUI and
-Desktop app (both share the same Web frontend).
+**Recall · Edit-and-resend · Regenerate**, plus **write-safe** in-conversation
+versioning — the **Agent business layer (production-grade guarantees)** for
+DeepSeek Harness.
 
 [![npm version](https://img.shields.io/npm/v/dsh-retrace)](https://www.npmjs.com/package/dsh-retrace)
 [![npm downloads](https://img.shields.io/npm/dm/dsh-retrace)](https://www.npmjs.com/package/dsh-retrace)
@@ -18,113 +16,73 @@ Desktop app (both share the same Web frontend).
 
 </div>
 
-> ## ⚡ Install in one minute
->
-> **Option A — one command (recommended):** with DeepSeek Harness's `dsh` CLI:
->
-> ```sh
-> dsh plugin --profile desktop add dsh-retrace   # DSH Desktop
-> # or: dsh plugin --profile web add dsh-retrace  # standalone Web
-> ```
->
-> **Option B — downloaded this repo as ZIP (or handing this link to an AI):**
-> unpack it and run `dsh plugin --profile desktop add <folder>` — or install
-> straight from GitHub, no unpacking:
->
-> ```sh
-> dsh plugin --profile desktop add github:yamingmou/dsh-retrace
-> ```
->
-> Follow [📦 Installation](#-installation) → *Manual install* for the exact
-> file-edit steps.
->
-> **Option C — no command line at all:** install the community plugin market
-> once, then install dsh-retrace from its UI:
->
-> ```sh
-> dsh plugin --profile desktop add dshmarket   # one time
-> ```
->
-> Restart, then **Settings → Plugin Market** → search **dsh-retrace** →
-> **Install** (one click). The market lists plugins from the curated
-> [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
-> registry; dsh-retrace is listed there.
->
-> > ⚠️ **Restart required after install.** Quit and reopen **DSH Desktop**
-> > (or restart the `dsh` process for a standalone Web deployment) — a running
-> > app keeps the previous bundle in memory and will not hot-reload it.
->
-> Hover any assistant reply → **↩ / ↻**; any user message → **✎** — that's it.
-
-DeepSeek Harness stores every conversation as an **append-only event log**, so there is
-no built-in "undo". `dsh-retrace` brings back the three moves every chat deserves —
-**撤回 (recall)**, **编辑重发 (edit-and-resend)**, **重新生成 (regenerate)** — and then
-goes further: because a recall only rewinds the **context**, while files the agent
-already changed stay changed, retrace versions your conversation **and its artifacts**
-in one place.
-
-Recall / edit **remove the target messages from the conversation view and the model
-context** — that is exactly the effect you see. What stays untouched is the underlying
-**durable transcript**: it remains append-only, old events are never rewritten or deleted,
-and the plugin merely appends one valid replacement event (the same `replace` primitive
-the built-in compaction uses) to rewind the surface — so the log keeps a full audit trail
-of every rewind. On top of that trail, retrace records version boundaries, touched files
-and (optionally) git state, and lets you roll back artifacts or jump back to any point
-in the conversation — all **inside the same session**, no session-switching.
-
-> ✅ **Timeline + artifact rollback are live (0.4.x)** — recall / edit /
-> regenerate, the version timeline, artifact rollback (git-first, snapshot
-> fallback), jump-to-conversation and marker pre-write validation (three-layer
-> contract guard) are all in. The fork map (P2) is in progress per [PLAN.md](./PLAN.md).
+**Recall / edit-and-resend / regenerate** — the three moves every conversation
+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**.
+
+> 🛡️ **Write safety** · 🔍 **Deep offline checks** · 🔄 **Detect → repair → guard** — see below.
 
 ---
 
-## ✨ Features
+## ⚡ One-minute install
 
-| Action | Where | What happens |
-| --- | --- | --- |
-| **↩ 撤回** (recall) | hover any assistant reply, or the row under any user message | Removes the **whole exchange round** (the input **and** the agent's output, tool rows included) from both the model context and the conversation view; the input text is echoed into the composer so you can re-ask or re-edit immediately. A small transient notice marks the rewind and disappears once you keep typing. |
-| **✎ 编辑重发** (edit & re-send) | row under any user message | The edited round is rewound and the new text is re-sent. By default **only the edited round** is replaced — earlier history stays visible; the optional "fresh conversation" setting rewinds the whole surface (earlier messages then leave the model context, and stay visible in the view as a marker notice by default). A collapsed **"original input"** reference sits right under the new message — click to expand, configurable off. |
-| **↻ 重新生成** (regenerate) | hover any assistant reply | The reply (and everything after it) is rewound and hidden, then the original prompt is re-sent so the agent answers again. |
+> Requires DeepSeek Harness with the `dsh` CLI. **Restart DSH after install** (a running app does not hot-reload).
 
-**Versioning & rollback (live in 0.4.x)** — every rewind is also recorded as a **version**:
+```sh
+dsh plugin --profile desktop add dsh-retrace    # DSH Desktop
+# or Web: dsh plugin --profile web add dsh-retrace
+# or GitHub: dsh plugin --profile desktop add github:yamingmou/dsh-retrace
+# or ZIP: dsh plugin --profile desktop add ~/plugins/dsh-retrace
+```
 
-- 🕘 **Timeline** — a **Versions** tab in the conversation view (on par with the official 对话/轨迹 tabs, since 0.4.2): every version (type, time, message count, file-change badges, summary), pushed live via `session/projection` (no polling), windowed for long histories; event inspection reuses the official Trajectory ledger.
-- ↩️ **Artifact rollback** — each version offers **context-only / artifacts-only / both** rollback with a dry-run preview; git-first (commit-free checkout of the listed paths) with content-addressed snapshot fallback. The rollback itself is recorded as a new version (`restore`) — rollback of a rollback.
-- 🧭 **Jump-to-conversation** — one click from a version to that point in the conversation (auto-loads earlier history, anchor highlight).
-- 🧹 **Bounded storage** — file snapshots keep the most recent N versions (default 50); a throttled background sweep prunes snapshots of truncated versions, keeping long sessions bounded.
+**No command line?** Install the community plugin market once, then find
+**dsh-retrace** in **Settings → Plugin Market** and install it with one click:
 
-**Why it's different**
+```sh
+dsh plugin --profile desktop add dshmarket    # one time
+```
 
-- 🎯 **Whole-round recall** — one click removes the input *and* its output (including tool rows), not just a single bubble.
-- 🖥️ **Web + Desktop** — the same plugin covers both surfaces of DeepSeek Harness.
-- 🔒 **Removed from view & context, not from the log** — recalled/edited messages disappear from the conversation view and the model context, while the durable transcript is never rewritten or deleted; the plugin only appends valid, typed session events (the same `replace` primitive the built-in compaction uses), so the log keeps a full audit trail.
-- 🧠 **View ⇄ context in sync** — the conversation view always reflects exactly what the agent sees.
-- ⚡ **Try in 30 seconds** — the dynamic form installs in your current session with no rebuild.
+After the restart, hover any assistant reply → **↩ / ↻**; any user message → **✎**.
+Full steps in [📦 Installation](#-installation).
 
 ---
 
-## 🚀 Quick start
+## 🛡️ Production-grade guarantees (all live in 0.4.x)
 
-The one-line install is at the top of this page (**⚡ Install in one minute**).
-This section covers the same ground with more detail.
+| | 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** |
+| 🔍 | **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 |
 
-> Requires DeepSeek Harness with the `dsh` CLI. Installs the plugin as a profile
-> bundle and automatically rebuilds the Web client:
+---
 
-```sh
-# DSH Desktop (desktop profile)
-dsh plugin --profile desktop add dsh-retrace
+## ✨ Features
 
-# standalone Web (`dsh web` / web profile)
-dsh plugin --profile web add dsh-retrace
-```
+| Action | Where | What happens |
+| --- | --- | --- |
+| **↩ Recall** | hover any assistant reply, or the row under any user message | Removes the **whole exchange round** (the input **and** the agent's output, tool rows included) from both the model context and the conversation view; the input text is echoed into the composer so you can re-ask or re-edit immediately. A small transient notice marks the rewind and disappears once you keep typing. |
+| **✎ Edit & re-send** | row under any user message | The edited round is rewound and the new text is re-sent. By default **only the edited round** is replaced — earlier history stays visible; the optional "fresh conversation" setting rewinds the whole surface (earlier messages then leave the model context, and stay visible in the view as a marker notice by default). A collapsed **"original input"** reference sits right under the new message — click to expand, configurable off. |
+| **↻ Regenerate** | hover any assistant reply | The reply (and everything after it) is rewound and hidden, then the original prompt is re-sent so the agent answers again. |
+
+**Versioning & rollback (live in 0.4.x)** — every rewind is also recorded as a **version**:
+
+| | What | |
+|---|---|---|
+| 🕘 | **Timeline** | a **Versions** tab in the conversation view: every version (type, time, message count, file-change badges), pushed live via `session/projection` (no polling), windowed for long histories |
+| ↩️ | **Artifact rollback** | **context-only / artifacts-only / both** with dry-run preview; git-first + content-addressed snapshot fallback; the rollback is itself a new version (`restore`) |
+| 🧭 | **Jump-to-conversation** | one click from a version to that point in the conversation (auto-loads history, anchor highlight) |
+| 🧹 | **Bounded storage** | snapshots keep the most recent N versions (default 50); throttled background sweep prunes truncated ones |
 
-> ⚠️ **Restart after install.** A running app keeps the previously loaded bundle
-> in memory, so **quit and reopen DSH Desktop** (or restart the `dsh` process for
-> a standalone Web deployment) before the plugin activates.
+**Why it's different** (the interaction layer — the guarantees above are the storage layer):
 
-After the restart, hover any assistant reply, or any user message, and use ↩ / ✎ / ↻.
+- 🎯 **Whole-round recall** — removes the input *and* its output (tool rows included), not just a single bubble.
+- 🖥️ **Web + Desktop** — one plugin, both DeepSeek Harness surfaces.
+- 🧠 **View ⇄ context in sync** — the conversation view always reflects exactly what the agent sees.
+- ⚡ **Try in 30 seconds** — the dynamic form installs in your current session with no rebuild.
 
 ---
 
@@ -265,13 +223,13 @@ The dynamic host registers the same operations behind the package-private
    rewound `session.deriveMessages()`.
 3. **Client** (`lib/client.js`) registers:
    - a `user-actions` conversation node under every user message
-     (编辑 / 撤回 row with an inline editor); recall echoes the text into the
+     (an edit/recall row with an inline editor); recall echoes the text into the
      composer,
    - the `recall-marker` node renderer: a notice row that injects CSS hiding
      every shadowed message row from the flow (view and model context stay in
      sync), plus the optional original-input comparison block,
    - the `retrace` entry in the `conversation.chat.assistant-actions`
-     strip (撤回 / 重新生成),
+     strip (recall / regenerate),
    - preference toggles and the retention limit under Settings → General.
 
 > Two different layers are at play: the **durable transcript** (append-only; old
@@ -302,16 +260,21 @@ The dynamic host registers the same operations behind the package-private
 
 ## 🗺️ Roadmap
 
-Built per [PLAN.md](./PLAN.md):
+**What's in today (0.4.x):**
+
+- 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`.
+- In-session **version timeline** + **artifact rollback** (git-first, snapshot
+  fallback, dry-run preview, jump-to-conversation).
+- **Fork map + session lineage** in the conversation view.
+- **Real-time watchdog** — snapshots the log at the first sign of concurrent writes.
+- Companion **`dsh-log-contract`**: 30+ offline contract rules + in-place repair
+  (`fix --neutralize` / `--clip-crossstep`) for sessions that would fail `/compact`.
 
-- **P1 — Timeline & artifact rollback** ✅ *shipped in 0.4.x*: an in-session version
-  timeline (messages, thinking, touched files), artifact snapshots (git-first,
-  snapshot-fallback, opt-in), rollback with dry-run preview, and jump-to-conversation
-  navigation.
-- **P2 — Fork map** 🔨 *in progress*: a flow graph of the conversation's turns with fork
-  points at every rewind, thinking flow per turn, branch-intent cards, and version
-  comparison.
-- More locales beyond 简体中文 / English.
+**What's next** — see the [public roadmap](./docs/ROADMAP.md) for the agent
+business-layer plan (runtime guard, interruption governance, ecosystem-facing
+interfaces). This README only describes what is already shipped.
 
 ---
 
@@ -359,6 +322,15 @@ 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](./docs/ROADMAP.md) for the framework-agnostic layer and how
+dsh-retrace is its DeepSeek Harness implementation. Companion components:
+
+- [**dsh-log-contract**](https://github.com/yamingmou/dsh-log-contract) — the
+  business layer's "doctor": 30+ offline contract rules + in-place repair
+  (`fix --neutralize` / `--clip-crossstep`). Installed automatically as a
+  dependency; also published standalone for direct use.
+
 > **Install straight from GitHub** (no npm registry needed — handy when you
 > hand this repo's link to an AI or want the latest commit):
 >
@@ -389,24 +361,27 @@ DeepSeek Harness community.
 MIT
 
 
-## 🧭 会话日志考古（retrace CLI）
+## 🧭 Session archaeology (`retrace` CLI)
 
-DSH 会话日志持久化了每次工具调用的完整输入输出——数据资产与审计资产。
-`retrace` CLI 提供只读考古能力（复用 dsh-log-contract 0.3.0 的契约与提取）：
+Every tool call's full input/output is persisted in the session log — a data and
+audit asset. The `retrace` CLI provides read-only archaeology (reusing
+dsh-log-contract's contracts and extraction):
 
 ```sh
-retrace index <session>                        # 工具调用索引（A1）
-retrace query <session> --cmd "seed-scale"     # 按命令正则查输出（A1）
-retrace extract <session> --pattern "seed-scale" --out ./found   # 导出输出（A2）
-retrace file-history <session> <path>          # 文件 write/edit 历史版本（A3）
-retrace file-diff <session> <path> 0 5         # 两版本行级 diff（A3）
-retrace lineage <session>                      # 会话 parent 链谱系（A4）
+retrace index <session>                        # tool-call index (A1)
+retrace query <session> --cmd "seed-scale"     # search outputs by command regex (A1)
+retrace extract <session> --pattern "seed-scale" --out ./found   # export outputs (A2)
+retrace file-history <session> <path>          # write/edit history of a file (A3)
+retrace file-diff <session> <path> 0 5         # line diff between two versions (A3)
+retrace lineage <session>                      # parent-chain lineage (A4)
 ```
 
-<session> 为完整日志路径或 sessionId（自动在 ~/.dsh/sessions 查找）。全部只读。
+`<session>` is a full log path or a sessionId (auto-looked-up under
+`~/.dsh/sessions`). All read-only.
 
-**分叉图里的会话谱系（A4,UI）**：Fork map 视图头部展示当前会话的
-`parentSession` 接续链（当前会话 → 父 → 根,`←` 方向）。数据来自
-`GET /api/plugins/retrace/lineage?sessionId=`（只读 header 遍历,带环保护）,
-与 CLI `retrace lineage` 同一语义。这样"这个会话是从哪个会话接着干/分叉出来的"
-在界面上一眼可见——也是分叉图拓扑的元数据源。
+**Session lineage in the fork map (A4, UI)**: the Fork map view header shows the
+current session's `parentSession` chain (session → parent → root, `←` direction).
+Data comes from `GET /api/plugins/retrace/lineage?sessionId=` (read-only header
+walk with cycle protection), the same semantics as the CLI `retrace lineage` —
+so "which session did this one continue/fork from" is visible at a glance, and
+serves as the fork-topology metadata source.

package/README.zh.md

@@ -2,10 +2,8 @@
 
 # 🧭 dsh-retrace
 
-**Retrace · 回溯** —— 在 **撤回 · 编辑重发 · 重新生成** 之上，更进一步：
-为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 对话提供
-**单会话内的版本化**——每一次回退的时间线、产物回退，以及对话走过的分叉路径图（路线图）。
-同时支持 **Web 端** 与 **桌面客户端**（两者共用同一套 Web 前端）。
+**撤回 · 编辑重发 · 重新生成**，加上**写安全**的会话版本化 —— DeepSeek Harness 的
+**Agent 业务层（生产级保证）** 实现。
 
 [![npm version](https://img.shields.io/npm/v/dsh-retrace)](https://www.npmjs.com/package/dsh-retrace)
 [![npm downloads](https://img.shields.io/npm/dm/dsh-retrace)](https://www.npmjs.com/package/dsh-retrace)
@@ -17,54 +15,46 @@
 
 </div>
 
-> ## ⚡ 一分钟安装
->
-> **方式 A —— 一条命令（推荐）：** 需要带 `dsh` CLI 的 DeepSeek Harness：
->
-> ```sh
-> dsh plugin --profile desktop add dsh-retrace   # DSH 桌面版
-> # 或：dsh plugin --profile web add dsh-retrace  # 独立 Web 部署
-> ```
->
-> **方式 B —— 从 GitHub 下载了 ZIP（或把本仓库链接直接丢给 AI）？** 解压到固定位置
-> （如 `~/plugins/dsh-retrace`）后执行 `dsh plugin --profile desktop add ~/plugins/dsh-retrace`；
-> 或**直接从 GitHub 安装，无需解压**：
->
-> ```sh
-> dsh plugin --profile desktop add github:yamingmou/dsh-retrace
-> ```
->
-> 更详细的文件级步骤见 [📦 安装](#-安装) → *手动安装*。
->
-> **方式 C —— 完全没有命令行？** 先装一次社区插件市场，再从市场 UI 一键安装
-> dsh-retrace：
->
-> ```sh
-> dsh plugin --profile desktop add dshmarket   # 只需一次
-> ```
->
-> 重启后进入 **设置 → Plugin Market** → 搜索 **dsh-retrace** → **安装**（一键）。
-> 市场收录自 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
-> 精选目录，dsh-retrace 已在其中。
->
-> > ⚠️ **安装后必须重启。** 运行中的应用不会热加载 bundle，请**退出并重新打开
-> > DSH Desktop**（独立 Web 部署则重启 `dsh` 进程）后插件才会生效。
->
-> 重启后悬停任意助手回复 → **↩ / ↻**；任意用户消息 → **✎**，即可使用。
+**撤回 / 编辑重发 / 重新生成** —— 每个会话都该有的三个操作。但回退不只是「撤掉一条
+消息」：DeepSeek Harness 把对话存在 append-only 事件日志里，撤回只回退上下文，改过的
+**产物文件不会自动还原**。dsh-retrace 把对话**和它的产物**一起版本化，并且保证
+**每次回退都合法、不弄脏日志、不破坏 /compact**。
+
+> 🛡️ **写安全** · 🔍 **深层体检** · 🔄 **检测→修复→守护** —— 详见下方「生产级保证」。
+
+---
+
+## ⚡ 一分钟安装
+
+> 需要带 `dsh` CLI 的 DeepSeek Harness；装完**重启 DSH** 生效（运行中的应用不会热加载）。
+
+```sh
+dsh plugin --profile desktop add dsh-retrace    # DSH 桌面版
+# 或 Web 部署：dsh plugin --profile web add dsh-retrace
+# 或从 GitHub 直装：dsh plugin --profile desktop add github:yamingmou/dsh-retrace
+# 或从 ZIP 解压后：dsh plugin --profile desktop add ~/plugins/dsh-retrace
+```
+
+**没有命令行？** 先装一次社区插件市场，再在 **设置 → Plugin Market** 搜
+**dsh-retrace** 一键安装：
+
+```sh
+dsh plugin --profile desktop add dshmarket    # 只需一次
+```
+
+重启后，悬停任意助手回复 → **↩ / ↻**；任意用户消息 → **✎**。详细步骤见
+[📦 安装](#-安装)。
 
-DeepSeek Harness 的对话是「只追加（append-only）」的事件日志，本身没有撤销能力。
-`dsh-retrace` 先为对话补上聊天本该有的三个操作 —— **撤回**、**编辑重发**、
-**重新生成**；再往前一步：撤回只回退了**上下文**，而智能体已经改过的**产物文件**
-不会自动还原——retrace 把对话**和它的产物**放在一起做版本化。
+---
+---
 
-撤回/编辑后，目标消息会**从对话视图和模型上下文中移除**——你看到的「删除」正是这个
-效果。但底层的**持久化日志不会被改写或删除**：它始终保持只追加，旧事件原样保留，
-插件只是在日志末尾追加一条合法的替换事件（与内置压缩使用的 `replace` 原语一致）来
-回退对话表面，因此日志保留每一次回退的完整审计痕迹。在这条痕迹之上，retrace 记录
-版本边界、触碰文件与（可选的）git 状态，支持产物回退与跳转到对话任意位置——全部
-发生在**同一会话内**，不换会话。
+## 🛡️ 生产级保证（0.4.x 全部已上线）
 
-> ✅ **时间线 + 产物回退已上线（0.4.x）** —— 撤回/编辑/重新生成、版本时间线、产物回退（git 优先 + 快照兜底）、跳转对话、marker 写前校验均已可用；分叉图（P2）按 [PLAN.md](./PLAN.md) 推进中。
+| | 能力 | 说明 |
+|---|---|---|
+| 🛡️ | **写安全** | 每次回退过三层写前契约校验；运行中的 agent 自动停止（官方 `cancel`/`whenIdle`）；轮次间 marker 用临时 step 包裹 —— **回退永不弄脏日志，/compact 永不失效** |
+| 🔍 | **深层体检** | 配套 `dsh-log-contract` 30+ 条契约规则（token-meter 配对 / 跨 step 引用 / 物理序 / inbox 重放），用真实损坏会话当测试集 —— 能找出让 /compact 永久失效的那类问题 |
+| 🔄 | **检测→修复→守护** | 看门狗在并发写入第一时间快照日志；离线 `fix` 原地中和问题 marker、裁剪跨 step 引用；写前校验在坏事件落盘前拦住 |
 
 ---
 
@@ -78,44 +68,24 @@ DeepSeek Harness 的对话是「只追加（append-only）」的事件日志，
 
 **版本化与回退（0.4.x 已上线）** —— 每次回退都会被记录为一个**版本**：
 
-- 🕘 **时间线** —— 会话视图新增「版本」Tab（与官方「对话/轨迹」平级，0.4.2 起）：展示每个版本（类型/时间/消息数/文件变更徽标/摘要），经 `session/projection` 推送帧实时更新（零轮询），大列表窗口化渲染；事件原文查看复用官方「轨迹」台账。
-- ↩️ **产物回退** —— 每个版本支持 仅对话 / 仅产物 / 两者 三种回退范围，先干跑预览再执行；git 优先（commit-free checkout 清单路径）+ 内容寻址快照兜底。回退本身记录为新版本（`restore`），可以再回退。
-- 🧭 **跳转对话** —— 从时间线一键跳转到对话对应位置（自动翻页加载更早历史 + 锚点高亮）。
-- 🧹 **存储有界** —— 文件快照只保留最近 N 个版本（默认 50）；节流后台扫掠回收被截断版本的快照，长会话不膨胀。
+| | 能力 | 说明 |
+|---|---|---|
+| 🕘 | **时间线** | 「版本」Tab（与官方「对话/轨迹」平级）：每个版本的类型/时间/消息数/文件变更徽标，经 `session/projection` 推送帧实时更新（零轮询），大列表窗口化 |
+| ↩️ | **产物回退** | 仅对话 / 仅产物 / 两者，先干跑预览再执行；git 优先 + 内容寻址快照兜底；回退本身是新版本（`restore`），可以再回退 |
+| 🧭 | **跳转对话** | 从时间线一键跳转到对应位置（自动翻页加载更早历史 + 锚点高亮） |
+| 🧹 | **存储有界** | 快照只保留最近 N 个版本（默认 50）；节流后台扫掠回收被截断版本 |
+
+**为什么与众不同**（交互层差异——上面的保证是存储层）：
 
 **为什么与众不同**
 
 - 🎯 **整轮撤回** —— 一键移除输入 *和* 它的输出（含工具行），而不只是单条气泡。
 - 🖥️ **Web + Desktop 双端** —— 同一插件覆盖 DeepSeek Harness 两种界面。
-- 🔒 **删除的是视图与上下文，不是日志** —— 被撤回/编辑的消息从对话视图和模型上下文中
-  消失，但持久化日志从不被改写或删除；插件只追加合法、带类型的会话事件（与内置压缩
-  使用的 `replace` 原语一致），日志保留完整审计痕迹。
 - 🧠 **视图 ⇄ 上下文同步** —— 对话视图永远反映智能体真正看到的内容。
 - ⚡ **30 秒上手** —— 动态插件形式无需重建即可在当前会话试用。
 
 ---
 
-## 🚀 快速开始
-
-页首的 **⚡ 一分钟安装** 是最短路径；本节给出同样内容的更详细说明。
-
-> 需要带 `dsh` CLI 的 DeepSeek Harness。以 profile bundle 方式安装，并自动重建 Web 客户端：
-
-```sh
-# DSH Desktop（desktop profile）
-dsh plugin --profile desktop add dsh-retrace
-
-# 独立 Web 部署（`dsh web` / web profile）
-dsh plugin --profile web add dsh-retrace
-```
-
-> ⚠️ **安装后需要重启。** 运行中的应用仍在内存中保留之前加载的 bundle，请**退出并
-> 重新打开 DSH Desktop**（独立 Web 部署则重启 `dsh` 进程）后插件才会生效。
-
-重启后，悬停任意助手回复或用户消息，即可使用 ↩ / ✎ / ↻。
-
----
-
 ## 📦 安装
 
 ### 1. Profile bundle（推荐）
@@ -265,11 +235,15 @@ Client 半区会依据包内 `dsh.client` 元数据被自动打包进 Web 客户
 
 ## 🗺️ 路线图
 
-按 [PLAN.md](./PLAN.md) 推进：
+**当前已具备（0.4.x）：**
 
-- **P1 — 时间线与产物回退** ✅ 已上线（0.4.x）：单会话内的版本时间线（版本/消息/思考/工具节点），产物快照（git 优先 + 快照兜底，可开关），带干跑预览的回退，以及跳转到对话位置；marker 写前校验（三层契约）守护日志。
-- **P2 — 分叉图** 🔨 推进中：对话回合的流程分叉图，每次回退都是分叉点，逐回合思考流，分支意图卡、版本对比。
-- 支持更多语言（当前：简体中文 / English）。
+- 撤回 / 编辑重发 / 重新生成——每次回退都过**三层写前校验**与安全编辑路径（自动停 agent、临时 step 包裹 marker），**不会损坏日志、不会破坏 /compact**。
+- 单会话**版本时间线** + **产物回退**（git 优先 + 快照兜底、干跑预览、跳转对话）。
+- 对话视图内的**分叉图** + **会话谱系**。
+- **实时看门狗**——并发写入第一时间快照日志。
+- 配套 **`dsh-log-contract`**：30+ 条离线契约规则 + 原地修复（`fix --neutralize` / `--clip-crossstep`），能处理会让 /compact 永久失败的会话。
+
+**未来计划**——见 [公开路线图](./docs/ROADMAP.md)（agent 业务层规划：运行时守护、中断治理、生态开放接口）。本 README 只描述已上线的能力。
 
 ---
 
@@ -316,6 +290,13 @@ npm pack --dry-run    # 校验发布文件清单
 
 收录于 [dsh-plugin topic](https://github.com/topics/dsh-plugin)。
 
+**Agent 业务层（生产级保证）** 的一部分——见 [公开路线图](./docs/ROADMAP.md)
+（框架无关的业务层定义，dsh-retrace 是它在 DeepSeek Harness 上的实现）。配套组件：
+
+- [**dsh-log-contract**](https://github.com/yamingmou/dsh-log-contract) —— 业务层的
+  「医生」：30+ 条离线契约规则 + 原地修复（`fix --neutralize` / `--clip-crossstep`）。
+  作为依赖自动安装，也独立发布供直接使用。
+
 > **直接从 GitHub 安装**（无需 npm registry —— 适合把本仓库链接丢给 AI，或想装最新提交）：
 >
 > ```sh
@@ -341,3 +322,27 @@ DeepSeek Harness 插件生态的精选总览见
 ## 📄 License
 
 MIT
+
+---
+
+## 🧭 会话日志考古（retrace CLI）
+
+DSH 会话日志持久化了每次工具调用的完整输入输出——数据资产与审计资产。
+`retrace` CLI 提供只读考古能力（复用 dsh-log-contract 的契约与提取）：
+
+```sh
+retrace index <session>                        # 工具调用索引（A1）
+retrace query <session> --cmd "seed-scale"     # 按命令正则查输出（A1）
+retrace extract <session> --pattern "seed-scale" --out ./found   # 导出输出（A2）
+retrace file-history <session> <path>          # 文件 write/edit 历史版本（A3）
+retrace file-diff <session> <path> 0 5         # 两版本行级 diff（A3）
+retrace lineage <session>                      # 会话 parent 链谱系（A4）
+```
+
+<session> 为完整日志路径或 sessionId（自动在 ~/.dsh/sessions 查找）。全部只读。
+
+**分叉图里的会话谱系（A4, UI）**：Fork map 视图头部展示当前会话的
+`parentSession` 接续链（当前会话 → 父 → 根,`←` 方向）。数据来自
+`GET /api/plugins/retrace/lineage?sessionId=`（只读 header 遍历,带环保护）,
+与 CLI `retrace lineage` 同一语义。这样「这个会话是从哪个会话接着干/分叉出来的」
+在界面上一眼可见——也是分叉图拓扑的元数据源。

package/lib/badge.js

@@ -0,0 +1,65 @@
+/**
+ * dsh-retrace — lib/badge.js
+ *
+ * 会话短码（identity badge）——2026-08-31 用户指定的小功能。
+ *
+ * 需求：与人交互时需要稳定的会话识别符（标题会变、session id 太长）。
+ * 解法：**从 session id（唯一值）确定性导出短码**——不依赖全量扫描、
+ * 不依赖外部短码表、插件运行时自算即可。同一 session id 永远得到同一短码。
+ *
+ * 与 `会话短码表.json`（工作区+序号语义格式 dx023dx001）的关系：
+ * - 外部表 = 人工维护的语义短码（线名/父子关系可读），由修复线维护；
+ * - 本模块 = 插件自算的确定性短码（人机交互兜底），任何环境可复现；
+ * - 两者并存：铭牌优先显示外部语义短码（若可查），否则用本模块兜底。
+ *
+ * 算法：FNV-1a 64-bit（uuid 段）→ base36 → 固定 10 位（补 0）。
+ * - 10 位纯字母数字（36^10 ≈ 3.6e15 空间，会话规模下碰撞可忽略）；
+ * - 只依赖 id 本身，无状态、无 IO、纯函数（可测试、可在 client/host 复用）。
+ */
+
+/** 提取 id 中的 uuid 段（hex），无匹配则退回 hex 清洗。 */
+export function uuidOf(id) {
+  const text = String(id ?? '')
+  const m = text.match(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i)
+  if (m) return m[0].replace(/-/g, '').toLowerCase()
+  const cleaned = text.replace(/[^0-9a-f]/gi, '').toLowerCase()
+  return cleaned.length >= 8 ? cleaned.slice(0, 32) : ''
+}
+
+/** FNV-1a 64-bit（BigInt，避免精度丢失）。 */
+export function fnv1a64(text) {
+  let hash = 0xcbf29ce484222325n
+  const prime = 0x100000001b3n
+  const mask = 0xffffffffffffffffn
+  for (let i = 0; i < text.length; i++) {
+    hash ^= BigInt(text.charCodeAt(i))
+    hash = (hash * prime) & mask
+  }
+  return hash
+}
+
+const BASE36 = '0123456789abcdefghijklmnopqrstuvwxyz'
+
+/** BigInt → base36 字符串。 */
+export function toBase36(value) {
+  if (value < 0n) value = -value
+  if (value === 0n) return '0'
+  let out = ''
+  let v = value
+  while (v > 0n) {
+    out = BASE36[Number(v % 36n)] + out
+    v /= 36n
+  }
+  return out
+}
+
+/**
+ * 会话短码：uuid 段 → FNV-1a 64 → base36 → 固定 10 位（补 0 截断）。
+ * @param {string} sessionId - 会话 id（`session-<uuid>` 或裸 uuid）。
+ * @returns {string} 10 位短码；无法提取 uuid 时返回空串（调用方自行兜底）。
+ */
+export function sessionBadge(sessionId) {
+  const uuid = uuidOf(sessionId)
+  if (uuid.length === 0) return ''
+  return toBase36(fnv1a64(uuid)).padStart(10, '0').slice(0, 10)
+}

package/lib/client.bundle.js

@@ -32,6 +32,44 @@ __export(client_exports, {
 });
 module.exports = __toCommonJS(client_exports);
 var import_react = require("react");
+
+// lib/badge.js
+function uuidOf(id) {
+  const text = String(id ?? "");
+  const m = text.match(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i);
+  if (m) return m[0].replace(/-/g, "").toLowerCase();
+  const cleaned = text.replace(/[^0-9a-f]/gi, "").toLowerCase();
+  return cleaned.length >= 8 ? cleaned.slice(0, 32) : "";
+}
+function fnv1a64(text) {
+  let hash = 0xcbf29ce484222325n;
+  const prime = 0x100000001b3n;
+  const mask = 0xffffffffffffffffn;
+  for (let i = 0; i < text.length; i++) {
+    hash ^= BigInt(text.charCodeAt(i));
+    hash = hash * prime & mask;
+  }
+  return hash;
+}
+var BASE36 = "0123456789abcdefghijklmnopqrstuvwxyz";
+function toBase36(value) {
+  if (value < 0n) value = -value;
+  if (value === 0n) return "0";
+  let out = "";
+  let v = value;
+  while (v > 0n) {
+    out = BASE36[Number(v % 36n)] + out;
+    v /= 36n;
+  }
+  return out;
+}
+function sessionBadge(sessionId) {
+  const uuid = uuidOf(sessionId);
+  if (uuid.length === 0) return "";
+  return toBase36(fnv1a64(uuid)).padStart(10, "0").slice(0, 10);
+}
+
+// lib/client.js
 var name = "dsh-retrace";
 var inject = ["slots", "locale", "conversationEvents"];
 var NS = "retrace";
@@ -139,7 +177,9 @@ var zh = {
   "fork.lineageThis": "\u5F53\u524D\u4F1A\u8BDD",
   "fork.lineageParent": "\u7236\u4F1A\u8BDD",
   "fork.lineageRoot": "\u6839\u4F1A\u8BDD",
-  "fork.lineageEmpty": "\u672C\u4F1A\u8BDD\u6CA1\u6709\u7236\u4F1A\u8BDD\uFF08\u72EC\u7ACB\u6839\u4F1A\u8BDD\uFF09\u3002"
+  "fork.lineageEmpty": "\u672C\u4F1A\u8BDD\u6CA1\u6709\u7236\u4F1A\u8BDD\uFF08\u72EC\u7ACB\u6839\u4F1A\u8BDD\uFF09\u3002",
+  "fork.badge": "\u4F1A\u8BDD\u77ED\u7801",
+  "fork.badgeHint": "\u77ED\u7801\u7531\u4F1A\u8BDD\u552F\u4E00 id \u786E\u5B9A\u6027\u5BFC\u51FA\uFF0C\u6C38\u4E0D\u53D8\uFF08\u6807\u9898\u4F1A\u53D8\uFF09\u3002"
 };
 var en = {
   "action.edit": "Edit",
@@ -233,7 +273,9 @@ var en = {
   "fork.lineageThis": "This session",
   "fork.lineageParent": "Parent session",
   "fork.lineageRoot": "Root session",
-  "fork.lineageEmpty": "This session has no parent (standalone root)."
+  "fork.lineageEmpty": "This session has no parent (standalone root).",
+  "fork.badge": "Session badge",
+  "fork.badgeHint": "A stable shortcode derived from the session id (titles change, badges never do)."
 };
 var SURFACE_TYPES = /* @__PURE__ */ new Set(["user/message", "assistant/message", "tool/result"]);
 function isReplacementSurfaceEvent(event) {
@@ -931,6 +973,10 @@ var CSS = `
 .dsh-rt-fork-lineage-id{font-family:var(--dsw-font-mono);font-size:11px;line-height:16px;color:var(--dsw-alias-label-primary);min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
 .dsh-rt-fork-lineage-arrow{font-size:11px;line-height:16px;color:var(--dsw-alias-label-caption);flex:none}
 .dsh-rt-fork-lineage-empty{font-size:11px;line-height:16px;color:var(--dsw-alias-label-caption);border:1px solid var(--dsw-alias-border-l2);border-radius:8px;padding:6px 8px;flex:none}
+.dsh-rt-fork-badge{display:flex;align-items:center;gap:8px;border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-elevated);border-radius:8px;padding:6px 8px;flex:none;min-width:0}
+.dsh-rt-fork-badge-tag{font-size:11px;font-weight:500;line-height:16px;color:var(--dsw-alias-label-secondary);flex:none}
+.dsh-rt-fork-badge-code{font-family:var(--dsw-font-mono);font-size:12px;font-weight:600;line-height:16px;color:var(--dsw-alias-state-info-primary);flex:none}
+.dsh-rt-fork-badge-id{font-family:var(--dsw-font-mono);font-size:11px;line-height:16px;color:var(--dsw-alias-label-caption);min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
 `;
 var JUMP_PAGE_BUDGET = 24;
 function switchToViewTab(viewId) {
@@ -1136,7 +1182,9 @@ function RetraceView({ sessionId, useProjection, t, actions, store }) {
   };
   const ROW_H = 64;
   const list = versions ?? [];
-  const visible = list.slice(Math.max(0, Math.floor(scrollTop / ROW_H) - 2), Math.min(list.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2));
+  const visibleStart = Math.max(0, Math.floor(scrollTop / ROW_H) - 2);
+  const visibleEnd = Math.min(list.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2);
+  const visible = list.slice(visibleStart, visibleEnd);
   (0, import_react.useEffect)(() => {
     if (list.length === 0) return void 0;
     return bindListHeight(document.querySelector(".dsh-rt-view .dsh-rt-timeline-list"));
@@ -1175,11 +1223,11 @@ function RetraceView({ sessionId, useProjection, t, actions, store }) {
       onScroll: (event) => setScrollTop(event.target.scrollTop)
     }, [
       (0, import_react.createElement)("div", { key: "spacer", style: { height: `${list.length * ROW_H}px`, position: "relative" } }, [
-        visible.map((record) => (0, import_react.createElement)(VersionRow, {
+        visible.map((record, i) => (0, import_react.createElement)(VersionRow, {
           key: record.versionId,
           record,
           t,
-          top: list.indexOf(record) * ROW_H,
+          top: (visibleStart + i) * ROW_H,
           onPreview: () => requestPreview(record),
           onTrajectory: () => switchToViewTab("trajectory"),
           onJump: () => jump(record.boundarySeq)
@@ -1301,10 +1349,9 @@ function ForkView({ sessionId, useProjection, t, actions, store }) {
     return bindListHeight(document.querySelector(".dsh-rt-view .dsh-rt-fork-list"));
   }, [nodes.length]);
   const ROW_H = 56;
-  const visible = nodes.slice(
-    Math.max(0, Math.floor(scrollTop / ROW_H) - 2),
-    Math.min(nodes.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2)
-  );
+  const visibleStart = Math.max(0, Math.floor(scrollTop / ROW_H) - 2);
+  const visibleEnd = Math.min(nodes.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2);
+  const visible = nodes.slice(visibleStart, visibleEnd);
   return (0, import_react.createElement)("div", { className: "dsh-rt-view" }, [
     (0, import_react.createElement)("div", { key: "head", className: "dsh-rt-timeline-head" }, [
       (0, import_react.createElement)("span", { key: "title", className: "dsh-rt-timeline-title" }, t("fork.title")),
@@ -1315,6 +1362,12 @@ function ForkView({ sessionId, useProjection, t, actions, store }) {
         onClick: refresh
       }, t("fork.refresh"))
     ]),
+    // 会话铭牌（2026-08-31）：短码 = 从 session id 确定性导出，永不变（标题会变）。
+    sessionId && (0, import_react.createElement)("div", { key: "badge", className: "dsh-rt-fork-badge", title: t("fork.badgeHint") }, [
+      (0, import_react.createElement)("span", { key: "tag", className: "dsh-rt-fork-badge-tag" }, t("fork.badge")),
+      (0, import_react.createElement)("code", { key: "code", className: "dsh-rt-fork-badge-code" }, `[${sessionBadge(sessionId)}]`),
+      (0, import_react.createElement)("span", { key: "id", className: "dsh-rt-fork-badge-id" }, sessionId)
+    ]),
     Array.isArray(lineage) && lineage.length > 1 && (0, import_react.createElement)("div", { key: "lineage", className: "dsh-rt-fork-lineage" }, [
       (0, import_react.createElement)("div", { key: "lt", className: "dsh-rt-fork-spine-label" }, t("fork.lineage")),
       lineage.map((hop, i) => (0, import_react.createElement)("div", {
@@ -1326,6 +1379,7 @@ function ForkView({ sessionId, useProjection, t, actions, store }) {
           { key: "tag", className: "dsh-rt-fork-lineage-tag" },
           i === 0 ? t("fork.lineageThis") : i === lineage.length - 1 ? t("fork.lineageRoot") : t("fork.lineageParent")
         ),
+        (0, import_react.createElement)("code", { key: "badge", className: "dsh-rt-fork-badge-code" }, `[${sessionBadge(hop.id)}]`),
         (0, import_react.createElement)("span", { key: "id", className: "dsh-rt-fork-lineage-id" }, hop.id),
         i < lineage.length - 1 && (0, import_react.createElement)("span", { key: "arrow", className: "dsh-rt-fork-lineage-arrow" }, "\u2190")
       ]))
@@ -1341,13 +1395,13 @@ function ForkView({ sessionId, useProjection, t, actions, store }) {
       onScroll: (event) => setScrollTop(event.target.scrollTop)
     }, [
       (0, import_react.createElement)("div", { key: "spacer", style: { height: `${nodes.length * ROW_H}px`, position: "relative" } }, [
-        visible.map((node) => (0, import_react.createElement)(ForkRow, {
+        visible.map((node, i) => (0, import_react.createElement)(ForkRow, {
           key: node.seq,
           node,
           boundary: boundaryBySeq.get(node.seq),
           markerText: markerBySeq.get(node.seq),
           t,
-          top: nodes.indexOf(node) * ROW_H,
+          top: (visibleStart + i) * ROW_H,
           onJump: () => jumpToAnchor(store, node.seq)
         }))
       ])

package/lib/client.js

@@ -16,6 +16,7 @@
  * `/api/plugins/retrace/*` registered by the Host half.
  */
 import { createElement, useEffect, useState } from 'react'
+import { sessionBadge } from './badge.js'
 
 export const name = 'dsh-retrace'
 export const inject = ['slots', 'locale', 'conversationEvents']
@@ -148,6 +149,8 @@ const zh = {
   'fork.lineageParent': '父会话',
   'fork.lineageRoot': '根会话',
   'fork.lineageEmpty': '本会话没有父会话（独立根会话）。',
+  'fork.badge': '会话短码',
+  'fork.badgeHint': '短码由会话唯一 id 确定性导出，永不变（标题会变）。',
 }
 /** English dictionary, checked complete against the zh key set. */
 const en = {
@@ -243,6 +246,8 @@ const en = {
   'fork.lineageParent': 'Parent session',
   'fork.lineageRoot': 'Root session',
   'fork.lineageEmpty': 'This session has no parent (standalone root).',
+  'fork.badge': 'Session badge',
+  'fork.badgeHint': 'A stable shortcode derived from the session id (titles change, badges never do).',
 }
 
 // ---------------------------------------------------------------------------
@@ -1164,6 +1169,10 @@ const CSS = `
 .dsh-rt-fork-lineage-id{font-family:var(--dsw-font-mono);font-size:11px;line-height:16px;color:var(--dsw-alias-label-primary);min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
 .dsh-rt-fork-lineage-arrow{font-size:11px;line-height:16px;color:var(--dsw-alias-label-caption);flex:none}
 .dsh-rt-fork-lineage-empty{font-size:11px;line-height:16px;color:var(--dsw-alias-label-caption);border:1px solid var(--dsw-alias-border-l2);border-radius:8px;padding:6px 8px;flex:none}
+.dsh-rt-fork-badge{display:flex;align-items:center;gap:8px;border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-elevated);border-radius:8px;padding:6px 8px;flex:none;min-width:0}
+.dsh-rt-fork-badge-tag{font-size:11px;font-weight:500;line-height:16px;color:var(--dsw-alias-label-secondary);flex:none}
+.dsh-rt-fork-badge-code{font-family:var(--dsw-font-mono);font-size:12px;font-weight:600;line-height:16px;color:var(--dsw-alias-state-info-primary);flex:none}
+.dsh-rt-fork-badge-id{font-family:var(--dsw-font-mono);font-size:11px;line-height:16px;color:var(--dsw-alias-label-caption);min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
 `
 
 const JUMP_PAGE_BUDGET = 24
@@ -1485,7 +1494,11 @@ function RetraceView({ sessionId, useProjection, t, actions, store }) {
   // ---- windowed list (uniform rows, zero-dep) ----
   const ROW_H = 64
   const list = versions ?? []
-  const visible = list.slice(Math.max(0, Math.floor(scrollTop / ROW_H) - 2), Math.min(list.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2))
+  // 2026-08-30 渲染卡死修复（与 ForkView 同）：带起始索引切片，渲染用索引算 top——
+  // 原 `list.indexOf(record)` 是 O(N²)（每可见行线性查找），大会话渲染风暴。
+  const visibleStart = Math.max(0, Math.floor(scrollTop / ROW_H) - 2)
+  const visibleEnd = Math.min(list.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2)
+  const visible = list.slice(visibleStart, visibleEnd)
 
   // Same view-area height trap as the fork list (see bindListHeight).
   useEffect(() => {
@@ -1534,11 +1547,11 @@ function RetraceView({ sessionId, useProjection, t, actions, store }) {
       onScroll: (event) => setScrollTop(event.target.scrollTop),
     }, [
       createElement('div', { key: 'spacer', style: { height: `${list.length * ROW_H}px`, position: 'relative' } }, [
-        visible.map((record) => createElement(VersionRow, {
+        visible.map((record, i) => createElement(VersionRow, {
           key: record.versionId,
           record,
           t,
-          top: list.indexOf(record) * ROW_H,
+          top: (visibleStart + i) * ROW_H,
           onPreview: () => requestPreview(record),
           onTrajectory: () => switchToViewTab('trajectory'),
           onJump: () => jump(record.boundarySeq),
@@ -1702,11 +1715,14 @@ function ForkView({ sessionId, useProjection, t, actions, store }) {
   }, [nodes.length])
 
   // ---- windowed list (uniform rows, zero-dep; same as the versions view) ----
+  // 2026-08-30 渲染卡死修复：visible 改为带起始索引的切片，渲染时直接用索引算
+  // top——原实现 `nodes.indexOf(node)` 在每次渲染对每个可见节点做 O(N) 线性查找
+  // （2047 节点 × ~15 可见行 = 每次渲染 ~30K 次比较，React 重渲染风暴 → 转圈、
+  // Renderer CPU 27.7%，526f1835 打开卡死）。其他会话节点少不触发，仅大会话暴露。
   const ROW_H = 56
-  const visible = nodes.slice(
-    Math.max(0, Math.floor(scrollTop / ROW_H) - 2),
-    Math.min(nodes.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2),
-  )
+  const visibleStart = Math.max(0, Math.floor(scrollTop / ROW_H) - 2)
+  const visibleEnd = Math.min(nodes.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2)
+  const visible = nodes.slice(visibleStart, visibleEnd)
 
   return createElement('div', { className: 'dsh-rt-view' }, [
     createElement('div', { key: 'head', className: 'dsh-rt-timeline-head' }, [
@@ -1719,6 +1735,13 @@ function ForkView({ sessionId, useProjection, t, actions, store }) {
       }, t('fork.refresh')),
     ]),
 
+    // 会话铭牌（2026-08-31）：短码 = 从 session id 确定性导出，永不变（标题会变）。
+    sessionId && createElement('div', { key: 'badge', className: 'dsh-rt-fork-badge', title: t('fork.badgeHint') }, [
+      createElement('span', { key: 'tag', className: 'dsh-rt-fork-badge-tag' }, t('fork.badge')),
+      createElement('code', { key: 'code', className: 'dsh-rt-fork-badge-code' }, `[${sessionBadge(sessionId)}]`),
+      createElement('span', { key: 'id', className: 'dsh-rt-fork-badge-id' }, sessionId),
+    ]),
+
     Array.isArray(lineage) && lineage.length > 1 && createElement('div', { key: 'lineage', className: 'dsh-rt-fork-lineage' }, [
       createElement('div', { key: 'lt', className: 'dsh-rt-fork-spine-label' }, t('fork.lineage')),
       lineage.map((hop, i) => createElement('div', {
@@ -1727,6 +1750,7 @@ function ForkView({ sessionId, useProjection, t, actions, store }) {
       }, [
         createElement('span', { key: 'tag', className: 'dsh-rt-fork-lineage-tag' },
           i === 0 ? t('fork.lineageThis') : (i === lineage.length - 1 ? t('fork.lineageRoot') : t('fork.lineageParent'))),
+        createElement('code', { key: 'badge', className: 'dsh-rt-fork-badge-code' }, `[${sessionBadge(hop.id)}]`),
         createElement('span', { key: 'id', className: 'dsh-rt-fork-lineage-id' }, hop.id),
         i < lineage.length - 1 && createElement('span', { key: 'arrow', className: 'dsh-rt-fork-lineage-arrow' }, '←'),
       ])),
@@ -1745,13 +1769,13 @@ function ForkView({ sessionId, useProjection, t, actions, store }) {
       onScroll: (event) => setScrollTop(event.target.scrollTop),
     }, [
       createElement('div', { key: 'spacer', style: { height: `${nodes.length * ROW_H}px`, position: 'relative' } }, [
-        visible.map((node) => createElement(ForkRow, {
+        visible.map((node, i) => createElement(ForkRow, {
           key: node.seq,
           node,
           boundary: boundaryBySeq.get(node.seq),
           markerText: markerBySeq.get(node.seq),
           t,
-          top: nodes.indexOf(node) * ROW_H,
+          top: (visibleStart + i) * ROW_H,
           onJump: () => jumpToAnchor(store, node.seq),
         })),
       ]),

package/lib/dynamic-client.js

@@ -38,6 +38,44 @@ return {
       });
       module.exports = __toCommonJS(client_exports);
       var import_react = require("react");
+      
+      // lib/badge.js
+      function uuidOf(id) {
+        const text = String(id ?? "");
+        const m = text.match(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i);
+        if (m) return m[0].replace(/-/g, "").toLowerCase();
+        const cleaned = text.replace(/[^0-9a-f]/gi, "").toLowerCase();
+        return cleaned.length >= 8 ? cleaned.slice(0, 32) : "";
+      }
+      function fnv1a64(text) {
+        let hash = 0xcbf29ce484222325n;
+        const prime = 0x100000001b3n;
+        const mask = 0xffffffffffffffffn;
+        for (let i = 0; i < text.length; i++) {
+          hash ^= BigInt(text.charCodeAt(i));
+          hash = hash * prime & mask;
+        }
+        return hash;
+      }
+      var BASE36 = "0123456789abcdefghijklmnopqrstuvwxyz";
+      function toBase36(value) {
+        if (value < 0n) value = -value;
+        if (value === 0n) return "0";
+        let out = "";
+        let v = value;
+        while (v > 0n) {
+          out = BASE36[Number(v % 36n)] + out;
+          v /= 36n;
+        }
+        return out;
+      }
+      function sessionBadge(sessionId) {
+        const uuid = uuidOf(sessionId);
+        if (uuid.length === 0) return "";
+        return toBase36(fnv1a64(uuid)).padStart(10, "0").slice(0, 10);
+      }
+      
+      // lib/client.js
       var name = "dsh-retrace";
       var inject = ["slots", "locale", "conversationEvents"];
       var NS = "retrace";
@@ -145,7 +183,9 @@ return {
         "fork.lineageThis": "\u5F53\u524D\u4F1A\u8BDD",
         "fork.lineageParent": "\u7236\u4F1A\u8BDD",
         "fork.lineageRoot": "\u6839\u4F1A\u8BDD",
-        "fork.lineageEmpty": "\u672C\u4F1A\u8BDD\u6CA1\u6709\u7236\u4F1A\u8BDD\uFF08\u72EC\u7ACB\u6839\u4F1A\u8BDD\uFF09\u3002"
+        "fork.lineageEmpty": "\u672C\u4F1A\u8BDD\u6CA1\u6709\u7236\u4F1A\u8BDD\uFF08\u72EC\u7ACB\u6839\u4F1A\u8BDD\uFF09\u3002",
+        "fork.badge": "\u4F1A\u8BDD\u77ED\u7801",
+        "fork.badgeHint": "\u77ED\u7801\u7531\u4F1A\u8BDD\u552F\u4E00 id \u786E\u5B9A\u6027\u5BFC\u51FA\uFF0C\u6C38\u4E0D\u53D8\uFF08\u6807\u9898\u4F1A\u53D8\uFF09\u3002"
       };
       var en = {
         "action.edit": "Edit",
@@ -239,7 +279,9 @@ return {
         "fork.lineageThis": "This session",
         "fork.lineageParent": "Parent session",
         "fork.lineageRoot": "Root session",
-        "fork.lineageEmpty": "This session has no parent (standalone root)."
+        "fork.lineageEmpty": "This session has no parent (standalone root).",
+        "fork.badge": "Session badge",
+        "fork.badgeHint": "A stable shortcode derived from the session id (titles change, badges never do)."
       };
       var SURFACE_TYPES = /* @__PURE__ */ new Set(["user/message", "assistant/message", "tool/result"]);
       function isReplacementSurfaceEvent(event) {
@@ -937,6 +979,10 @@ return {
       .dsh-rt-fork-lineage-id{font-family:var(--dsw-font-mono);font-size:11px;line-height:16px;color:var(--dsw-alias-label-primary);min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
       .dsh-rt-fork-lineage-arrow{font-size:11px;line-height:16px;color:var(--dsw-alias-label-caption);flex:none}
       .dsh-rt-fork-lineage-empty{font-size:11px;line-height:16px;color:var(--dsw-alias-label-caption);border:1px solid var(--dsw-alias-border-l2);border-radius:8px;padding:6px 8px;flex:none}
+      .dsh-rt-fork-badge{display:flex;align-items:center;gap:8px;border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-elevated);border-radius:8px;padding:6px 8px;flex:none;min-width:0}
+      .dsh-rt-fork-badge-tag{font-size:11px;font-weight:500;line-height:16px;color:var(--dsw-alias-label-secondary);flex:none}
+      .dsh-rt-fork-badge-code{font-family:var(--dsw-font-mono);font-size:12px;font-weight:600;line-height:16px;color:var(--dsw-alias-state-info-primary);flex:none}
+      .dsh-rt-fork-badge-id{font-family:var(--dsw-font-mono);font-size:11px;line-height:16px;color:var(--dsw-alias-label-caption);min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
       `;
       var JUMP_PAGE_BUDGET = 24;
       function switchToViewTab(viewId) {
@@ -1142,7 +1188,9 @@ return {
         };
         const ROW_H = 64;
         const list = versions ?? [];
-        const visible = list.slice(Math.max(0, Math.floor(scrollTop / ROW_H) - 2), Math.min(list.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2));
+        const visibleStart = Math.max(0, Math.floor(scrollTop / ROW_H) - 2);
+        const visibleEnd = Math.min(list.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2);
+        const visible = list.slice(visibleStart, visibleEnd);
         (0, import_react.useEffect)(() => {
           if (list.length === 0) return void 0;
           return bindListHeight(document.querySelector(".dsh-rt-view .dsh-rt-timeline-list"));
@@ -1181,11 +1229,11 @@ return {
             onScroll: (event) => setScrollTop(event.target.scrollTop)
           }, [
             (0, import_react.createElement)("div", { key: "spacer", style: { height: `${list.length * ROW_H}px`, position: "relative" } }, [
-              visible.map((record) => (0, import_react.createElement)(VersionRow, {
+              visible.map((record, i) => (0, import_react.createElement)(VersionRow, {
                 key: record.versionId,
                 record,
                 t,
-                top: list.indexOf(record) * ROW_H,
+                top: (visibleStart + i) * ROW_H,
                 onPreview: () => requestPreview(record),
                 onTrajectory: () => switchToViewTab("trajectory"),
                 onJump: () => jump(record.boundarySeq)
@@ -1307,10 +1355,9 @@ return {
           return bindListHeight(document.querySelector(".dsh-rt-view .dsh-rt-fork-list"));
         }, [nodes.length]);
         const ROW_H = 56;
-        const visible = nodes.slice(
-          Math.max(0, Math.floor(scrollTop / ROW_H) - 2),
-          Math.min(nodes.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2)
-        );
+        const visibleStart = Math.max(0, Math.floor(scrollTop / ROW_H) - 2);
+        const visibleEnd = Math.min(nodes.length, Math.ceil(scrollTop / ROW_H) + Math.ceil(640 / ROW_H) + 2);
+        const visible = nodes.slice(visibleStart, visibleEnd);
         return (0, import_react.createElement)("div", { className: "dsh-rt-view" }, [
           (0, import_react.createElement)("div", { key: "head", className: "dsh-rt-timeline-head" }, [
             (0, import_react.createElement)("span", { key: "title", className: "dsh-rt-timeline-title" }, t("fork.title")),
@@ -1321,6 +1368,12 @@ return {
               onClick: refresh
             }, t("fork.refresh"))
           ]),
+          // 会话铭牌（2026-08-31）：短码 = 从 session id 确定性导出，永不变（标题会变）。
+          sessionId && (0, import_react.createElement)("div", { key: "badge", className: "dsh-rt-fork-badge", title: t("fork.badgeHint") }, [
+            (0, import_react.createElement)("span", { key: "tag", className: "dsh-rt-fork-badge-tag" }, t("fork.badge")),
+            (0, import_react.createElement)("code", { key: "code", className: "dsh-rt-fork-badge-code" }, `[${sessionBadge(sessionId)}]`),
+            (0, import_react.createElement)("span", { key: "id", className: "dsh-rt-fork-badge-id" }, sessionId)
+          ]),
           Array.isArray(lineage) && lineage.length > 1 && (0, import_react.createElement)("div", { key: "lineage", className: "dsh-rt-fork-lineage" }, [
             (0, import_react.createElement)("div", { key: "lt", className: "dsh-rt-fork-spine-label" }, t("fork.lineage")),
             lineage.map((hop, i) => (0, import_react.createElement)("div", {
@@ -1332,6 +1385,7 @@ return {
                 { key: "tag", className: "dsh-rt-fork-lineage-tag" },
                 i === 0 ? t("fork.lineageThis") : i === lineage.length - 1 ? t("fork.lineageRoot") : t("fork.lineageParent")
               ),
+              (0, import_react.createElement)("code", { key: "badge", className: "dsh-rt-fork-badge-code" }, `[${sessionBadge(hop.id)}]`),
               (0, import_react.createElement)("span", { key: "id", className: "dsh-rt-fork-lineage-id" }, hop.id),
               i < lineage.length - 1 && (0, import_react.createElement)("span", { key: "arrow", className: "dsh-rt-fork-lineage-arrow" }, "\u2190")
             ]))
@@ -1347,13 +1401,13 @@ return {
             onScroll: (event) => setScrollTop(event.target.scrollTop)
           }, [
             (0, import_react.createElement)("div", { key: "spacer", style: { height: `${nodes.length * ROW_H}px`, position: "relative" } }, [
-              visible.map((node) => (0, import_react.createElement)(ForkRow, {
+              visible.map((node, i) => (0, import_react.createElement)(ForkRow, {
                 key: node.seq,
                 node,
                 boundary: boundaryBySeq.get(node.seq),
                 markerText: markerBySeq.get(node.seq),
                 t,
-                top: nodes.indexOf(node) * ROW_H,
+                top: (visibleStart + i) * ROW_H,
                 onJump: () => jumpToAnchor(store, node.seq)
               }))
             ])

package/lib/http.js

@@ -81,8 +81,8 @@ function sendError(res, error) {
 }
 
 /** Route one request. `seam` is the versioning seam (lib/versioning.js). */
-export function createRetraceHttpHandler(ctx, { sessions, agents, seam, rollback, log = () => {} }) {
-  const api = createEditorApi(ctx, sessions, agents, log)
+export function createRetraceHttpHandler(ctx, { sessions, agents, seam, rollback, hooks = {}, log = () => {} }) {
+  const api = createEditorApi(ctx, sessions, agents, log, hooks)
 
   function handleVersions(req, res, sessionId, config) {
     seam.setConfig(sessionId, config)

package/lib/index.js

@@ -25,6 +25,8 @@ import { createVersioningSeam } from './versioning.js'
 import { createRollbackExecutor } from './rollback.js'
 import { createMarkerGuard } from './prewrite-guard.js'
 import { createWatchdog } from './watchdog.js'
+import { attachExitWarning } from './interrupt-guard.js'
+import { sessionBadge } from './badge.js'
 
 export const name = 'dsh-retrace'
 export const inject = ['sessions', 'agents', 'webServer', 'fs', 'subprocess', 'sandboxPolicy']
@@ -52,6 +54,7 @@ export function apply(ctx) {
     agents: ctx.agents,
     seam,
     rollback,
+    hooks,
     log,
   })
 
@@ -78,6 +81,11 @@ export function apply(ctx) {
       harness.handle('retrace.recall', (args) => api.recall(args)),
       harness.handle('retrace.editAndResend', (args) => api.editAndResend(args)),
       harness.handle('retrace.regenerate', (args) => api.regenerate(args)),
+      // 会话短码（2026-08-31）：session id → 确定性 10 位短码，人机交互识别用。
+      harness.handle('retrace.sessionBadge', (args) => {
+        const sessionId = String(args?.sessionId ?? '')
+        return { ok: true, value: { sessionId, badge: sessionBadge(sessionId) } }
+      }),
     ]
     return () => disposers.forEach((dispose) => dispose())
   })()
@@ -85,9 +93,13 @@ export function apply(ctx) {
   // R1 实时看门狗：轮询文件尾部 seq vs 内存长度，捕获并发写入/旧光标回放现场。
   const watchdog = createWatchdog(ctx, log)
 
+  // R4 中断轮次治理：退出/重载时对未闭合 turn 会话提示（只检测不写事件）。
+  const warnUnclosed = attachExitWarning(ctx, log)
+
   ctx.effect(() => () => {
     disposeRoute()
     disposeHarness()
     watchdog.dispose()
+    warnUnclosed()
   }, 'dsh-retrace: transports')
 }

package/lib/interrupt-guard.js

@@ -0,0 +1,89 @@
+/**
+ * dsh-retrace · lib/interrupt-guard.js
+ *
+ * R4 中断轮次治理（2026-08-30 任务书 §4）。
+ *
+ * 目标：退出/关闭会话前对「未闭合 turn」的会话提示用户，避免误以为任务
+ * 已干净结束。
+ *
+ * 设计（按实现方案 §R4，铁律「先核实官方 turn 关闭路径」）：
+ *   - 官方 `dsh-agent-loop/lib/index.js:620` 在 finally 块保证 `turn/end`
+ *     必然写入（含 reason.kind='error' 的中断）——正常退出/中断路径不会
+ *     留下未闭合 turn；
+ *   - 未闭合 turn 只出现在「崩溃 / 强杀 / 断电」场景：有 turn/start 无
+ *     turn/end（interrupted/aborted 是官方正常闭合，不在此列）；
+ *   - 因此本守卫**只检测 + 提示，绝不自动写 turn/end**（与官方持久化竞态
+ *     会引入双写；且插件不应在运行期补写持久化事件——铁律「插件内不要
+ *     删除/重编号持久化事件」的同类约束）。
+ *
+ * 检测函数：
+ *   unclosedTurns(session) → { turn, state: 'open' }[]
+ *     扫描 session.events：turn/start 开、turn/end 关；尾部仍开 = 未闭合。
+ */
+
+/**
+ * 扫描会话，找未闭合的轮次。
+ * @param {object} session - DSH session 对象（session.events 为事件数组）。
+ * @returns {Array<{turn: number, state: 'open'}>}
+ *
+ * ⚠️ 判定（2026-08-31 独立审查修正）：只报**真正未闭合**的轮次——有
+ * turn/start 且尾部没有对应 turn/end（崩溃/强杀现场）。
+ * turn/end 的 reason.kind 为 'interrupted'/'aborted' 是官方**正常闭合**
+ * （用户主动中断，agent-loop finally 保证写入），archive 实测 69 会话中
+ * 666 aborted + 126 interrupted 全是正常闭合、真 open 只 10 个——把它们
+ * 当"未闭合"会在每次退出对 91% 会话打误导性 warning。
+ */
+export function unclosedTurns(session) {
+  const events = Array.isArray(session?.events) ? session.events : []
+  const found = []
+  let openTurn = null
+  for (const event of events) {
+    if (!event || typeof event !== 'object') continue
+    if (event.type === 'turn/start') {
+      openTurn = event.data?.turn
+    } else if (event.type === 'turn/end') {
+      openTurn = null
+    }
+  }
+  // 尾部仍有未闭合 turn（崩溃/强杀现场）
+  if (openTurn !== null) {
+    found.push({ turn: openTurn, state: 'open' })
+  }
+  return found
+}
+
+/**
+ * 挂载退出前提示：在插件 dispose 时对「当前 attach 且有未闭合轮次」的会话
+ * 记录一条 warning（非阻断）。调用方（apply 的 ctx.effect 清理）负责在
+ * 退出/重载时触发。
+ *
+ * 不做客户端弹窗（非阻断提示由宿主 UI 在会话内呈现——本插件只负责检测与
+ * 日志；客户端时间线渲染未闭合轮次的提示属 UI 层，后续可扩展）。
+ * @param {object} ctx - cordis ctx。
+ * @param {(line: string) => void} log - 日志函数。
+ * @param {() => Array<object>} [sessionList] - 活跃会话列表（默认 ctx.sessions）。
+ */
+export function attachExitWarning(ctx, log, sessionList) {
+  return () => {
+    const sessions = typeof sessionList === 'function' ? sessionList() : ctx?.sessions
+    if (!sessions || typeof sessions !== 'object') return
+    const ids = typeof sessions.keys === 'function' ? [...sessions.keys()] : Object.keys(sessions)
+    for (const id of ids) {
+      const session = typeof sessions.get === 'function' ? sessions.get(id) : sessions[id]
+      if (!session) continue
+      const unclosed = unclosedTurns(session)
+      if (unclosed.length === 0) continue
+      const summary = unclosed.map((u) => `turn ${u.turn} (${u.state})`).join(', ')
+      log(`retrace-interrupt-guard: 会话 ${id} 存在未闭合轮次 ${summary}——中断未干净收尾，重启后可能触发旧光标回放；建议退出前先体检（dsh-log-contract check）`)
+    }
+  }
+}
+
+/**
+ * 在给定会话上运行检测（供 CLI/测试直接调用）。
+ * @param {object} session - 会话对象或 { events: [...] }。
+ * @returns {Array<{turn: number, state: string}>}
+ */
+export function detectUnclosed(session) {
+  return unclosedTurns(session)
+}

package/lib/prewrite-guard.js

@@ -32,6 +32,45 @@
  */
 import { editorError } from './host-core.js'
 
+/**
+ * 回档幅度阈值（快照点守卫，2026-08-31 c2d05ce9 事故闭环）。
+ *
+ * 业务语义（生产级运行保障，见 工程-生产级运行时/快照点与回档机制-设计-20260831.md）：
+ * - 一次编辑/撤回/重发遮蔽的 surface 节点占比 > 本阈值 = **回档请求**——
+ *   等于把生产基线大幅改写 → 拒绝落盘，引导从快照点创建官方分支；
+ * - 与 client 侧 SHADOW_SAFETY_RATIO（0.4）同源：UI 降级判定与写前拦截共用同一阈值；
+ * - 阈值可通过 createMarkerGuard({ rollbackRatio }) 覆盖（测试/未来配置）。
+ */
+export const ROLLBACK_RATIO = 0.4
+
+/**
+ * 短会话豁免阈值（2026-08-31 独立审查问题 B）：surface 节点 ≤ 6（≈ 3 轮）
+ * 的会话不做回档幅度拦截——否则 1-2 轮新会话编辑/撤回/重发 100% 被拒，
+ * 现有功能回归。事故防御针对大会话的「编辑早期消息遮蔽几十轮」，短会话无此风险。
+ */
+export const ROLLBACK_MIN_SURFACE = 6
+
+/**
+ * 该 marker 是否来自 rollback（restore op）——rollback 本身就是「从快照点
+ * 回档」的官方机制，不应再被回档幅度守卫拦截（否则大范围回档永远不可用，
+ * 且错误文案引导「打分支」而插件内无此操作 = 死路）。2026-08-31 独立审查问题 A。
+ */
+export function isRestoreMarker(envelope) {
+  const id = envelope?.data?.message?.id
+  return typeof id === 'string' && id.startsWith('retrace-restore-')
+}
+
+/** 计算一次 replace 的遮蔽占比（0..1）。无 surface/无 sourceEventSeqs/短会话 → 0（不拦截）。 */
+export function rollbackShareOf(session, envelope) {
+  if (!session || !envelope) return 0
+  const shadowed = Array.isArray(envelope.sourceEventSeqs) ? envelope.sourceEventSeqs.length : 0
+  if (shadowed <= 0) return 0
+  const surfaceNodes = session.surface?.nodes
+  const total = Array.isArray(surfaceNodes) ? surfaceNodes.length : 0
+  if (total <= ROLLBACK_MIN_SURFACE) return 0 // 短会话豁免（问题 B）
+  return shadowed / total
+}
+
 /** R2 —— T1 折叠自检：与 dsh-token-meter/_foldEvent 及 checks.js T1 同语义。 */
 export function tokenMeterFoldOk(events) {
   // 与 checks.js:372 同语义：无任何 step/start 的日志（极早期格式/简化夹具）
@@ -61,7 +100,7 @@ export function tokenMeterFoldOk(events) {
  * @param {(sessionId: string) => boolean} [options.enabled] 门控（默认恒 true）。
  * @returns {{ validateMarkerAppend(session, envelope): Promise<void> }}
  */
-export function createMarkerGuard({ log = () => {}, prewriterFactory, enabled = () => true } = {}) {
+export function createMarkerGuard({ log = () => {}, prewriterFactory, enabled = () => true, rollbackRatio = ROLLBACK_RATIO } = {}) {
   let factory = prewriterFactory ?? null
   return {
     /**
@@ -72,6 +111,27 @@ export function createMarkerGuard({ log = () => {}, prewriterFactory, enabled =
      */
     async validateMarkerAppend(session, envelope) {
       if (typeof enabled === 'function' && enabled(session?.id) === false) return { t1Ok: true }
+      // 快照点守卫（2026-08-31 c2d05ce9 事故闭环）：回档请求（遮蔽 > 阈值）
+      // 拒绝落盘——生产基线不支持原地大幅改写，引导从快照点创建官方分支。
+      // 在契约校验之前独立检查（业务规则，与合法性正交）；host 层强制，UI 绕过也拦。
+      // 豁免（2026-08-31 独立审查）：restore（rollback 回档本身合法）与短会话（≤3 轮）。
+      if (
+        envelope?.surfaceOp?.op === 'replace' &&
+        Array.isArray(envelope.sourceEventSeqs) &&
+        !isRestoreMarker(envelope)
+      ) {
+        const share = rollbackShareOf(session, envelope)
+        if (share > rollbackRatio) {
+          const pct = Math.round(share * 100)
+          log(
+            `retrace: rollback guard — replace shadows ${envelope.sourceEventSeqs.length}/${session?.surface?.nodes?.length ?? '?'} surface nodes (${pct}% > ${Math.round(rollbackRatio * 100)}%); refusing in-place rewrite; guide user to fork a branch from the snapshot point`,
+          )
+          throw editorError(
+            'rollback-guide',
+            `此操作将回档到较早的快照点（遮蔽 ${pct}% 的对话）。生产基线不支持原地大幅改写；请从快照点创建会话分支，在新分支中继续——原会话完整保留。`,
+          )
+        }
+      }
       if (factory === null) {
         try {
           factory = (await import('dsh-log-contract')).createPreWriter

package/package.json

@@ -1,10 +1,17 @@
 {
   "name": "dsh-retrace",
   "description": "Retrace · 回溯 — Recall, edit-and-resend, regenerate, and conversation/artifact versioning (timeline, rollback, fork map) for DeepSeek Harness — Web and Desktop",
-  "version": "0.4.10",
+  "version": "0.4.12",
+  "packageManager": "pnpm@11.7.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
+  "scripts": {
+    "build": "node scripts/generate-dynamic.mjs && node scripts/build-client.mjs",
+    "check": "node scripts/check-syntax.mjs && node scripts/check-dynamic.mjs",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm check && pnpm build && pnpm test"
+  },
   "exports": {
     ".": {
       "default": "./lib/index.js"
@@ -95,10 +102,5 @@
   },
   "bin": {
     "retrace": "bin/retrace.mjs"
-  },
-  "scripts": {
-    "build": "node scripts/generate-dynamic.mjs && node scripts/build-client.mjs",
-    "check": "node scripts/check-syntax.mjs && node scripts/check-dynamic.mjs",
-    "test": "vitest run"
   }
-}
+}