dsh-retrace 0.4.9 → 0.4.11

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,73 +16,73 @@ Desktop app (both share the same Web frontend).
 
 </div>
 
-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)
 
-> Requires DeepSeek Harness with the `dsh` CLI. Installs the plugin as a profile
-> bundle and automatically rebuilds the Web client:
+| | 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 |
 
-```sh
-# DSH Desktop (desktop profile)
-dsh plugin --profile desktop add dsh-retrace
+---
 
-# standalone Web (`dsh web` / web profile)
-dsh plugin --profile web add dsh-retrace
-```
+## ✨ Features
+
+| 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**:
 
-> ⚠️ **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.
+| | 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 |
 
-That's it — after the restart, hover any assistant reply, or any user message,
-and use ↩ / ✎ / ↻.
+**Why it's different** (the interaction layer — the guarantees above are the storage layer):
+
+- 🎯 **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.
 
 ---
 
@@ -105,14 +103,17 @@ dsh plugin --profile <name> add dsh-retrace
 > deployment) to load the plugin. To uninstall:
 > `dsh plugin --profile <name> remove dsh-retrace` (then restart again).
 
-It also shows up in [dsh-market](https://github.com/dsh-market/dsh-market) for
-one-click install from inside Settings (same restart applies).
-
 ### 2. Manual install (no `dsh` CLI)
 
 The same result with plain file edits and `pnpm` — exactly the steps
 `dsh plugin add` performs for you:
 
+> **Downloaded this repo as a ZIP?** Unpack it somewhere stable (e.g.
+> `~/plugins/dsh-retrace`), then either
+> `dsh plugin --profile desktop add ~/plugins/dsh-retrace`, or follow the
+> steps below with the dependency line pointing at the folder:
+> `"dsh-retrace": "file:~/plugins/dsh-retrace"`.
+
 1. Open the profile manifest (defaults: `~/.dsh/profiles/desktop` on DSH
    Desktop, `~/.dsh/profiles/web` for standalone Web) and add **both** the
    dependency and the bundle-layer entry:
@@ -148,6 +149,9 @@ The same result with plain file edits and `pnpm` — exactly the steps
 For local development, point the dependency at a checkout instead of the
 registry: `"dsh-retrace": "file:/path/to/dsh-retrace"` — or let
 `dsh` do it: `dsh plugin --profile <name> add /path/to/dsh-retrace`.
+For the latest GitHub commit without a release: use
+`"dsh-retrace": "github:yamingmou/dsh-retrace"` (standard pnpm git
+dependency syntax) in the same `dependencies` block, then `pnpm install`.
 
 ### 3. npm package + composition (classic)
 
@@ -219,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
@@ -256,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.
 
 ---
 
@@ -311,10 +320,32 @@ and the [issue tracker](https://github.com/yamingmou/dsh-retrace/issues).
 
 ## 📚 Ecosystem
 
-Listed on the [dsh-plugin topic](https://github.com/topics/dsh-plugin) and
-installable from [dsh-market](https://github.com/dsh-market/dsh-market). For a
-curated overview of the DeepSeek Harness plugin ecosystem, see
-[awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin).
+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):
+>
+> ```sh
+> dsh plugin --profile desktop add github:yamingmou/dsh-retrace
+> # or with pnpm directly into a profile:
+> cd ~/.dsh/profiles/desktop && pnpm add github:yamingmou/dsh-retrace
+> ```
+>
+> Then restart DSH Desktop as usual. The `dsh-log-contract` dependency is
+> pulled in automatically.
+
+A curated overview of the DeepSeek Harness plugin ecosystem lives at
+[awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
+(third-party listing — verify availability before relying on it).
 
 ---
 
@@ -330,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,19 +15,46 @@
 
 </div>
 
-DeepSeek Harness 的对话是「只追加（append-only）」的事件日志，本身没有撤销能力。
-`dsh-retrace` 先为对话补上聊天本该有的三个操作 —— **撤回**、**编辑重发**、
-**重新生成**；再往前一步：撤回只回退了**上下文**，而智能体已经改过的**产物文件**
-不会自动还原——retrace 把对话**和它的产物**放在一起做版本化。
+**撤回 / 编辑重发 / 重新生成** —— 每个会话都该有的三个操作。但回退不只是「撤掉一条
+消息」：DeepSeek Harness 把对话存在 append-only 事件日志里，撤回只回退上下文，改过的
+**产物文件不会自动还原**。dsh-retrace 把对话**和它的产物**一起版本化，并且保证
+**每次回退都合法、不弄脏日志、不破坏 /compact**。
 
-撤回/编辑后，目标消息会**从对话视图和模型上下文中移除**——你看到的「删除」正是这个
-效果。但底层的**持久化日志不会被改写或删除**：它始终保持只追加，旧事件原样保留，
-插件只是在日志末尾追加一条合法的替换事件（与内置压缩使用的 `replace` 原语一致）来
-回退对话表面，因此日志保留每一次回退的完整审计痕迹。在这条痕迹之上，retrace 记录
-版本边界、触碰文件与（可选的）git 状态，支持产物回退与跳转到对话任意位置——全部
-发生在**同一会话内**，不换会话。
+> 🛡️ **写安全** · 🔍 **深层体检** · 🔄 **检测→修复→守护** —— 详见下方「生产级保证」。
 
-> ✅ **时间线 + 产物回退已上线（0.4.x）** —— 撤回/编辑/重新生成、版本时间线、产物回退（git 优先 + 快照兜底）、跳转对话、marker 写前校验均已可用；分叉图（P2）按 [PLAN.md](./PLAN.md) 推进中。
+---
+
+## ⚡ 一分钟安装
+
+> 需要带 `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    # 只需一次
+```
+
+重启后，悬停任意助手回复 → **↩ / ↻**；任意用户消息 → **✎**。详细步骤见
+[📦 安装](#-安装)。
+
+---
+---
+
+## 🛡️ 生产级保证（0.4.x 全部已上线）
+
+| | 能力 | 说明 |
+|---|---|---|
+| 🛡️ | **写安全** | 每次回退过三层写前契约校验；运行中的 agent 自动停止（官方 `cancel`/`whenIdle`）；轮次间 marker 用临时 step 包裹 —— **回退永不弄脏日志，/compact 永不失效** |
+| 🔍 | **深层体检** | 配套 `dsh-log-contract` 30+ 条契约规则（token-meter 配对 / 跨 step 引用 / 物理序 / inbox 重放），用真实损坏会话当测试集 —— 能找出让 /compact 永久失效的那类问题 |
+| 🔄 | **检测→修复→守护** | 看门狗在并发写入第一时间快照日志；离线 `fix` 原地中和问题 marker、裁剪跨 step 引用；写前校验在坏事件落盘前拦住 |
 
 ---
 
@@ -43,42 +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（推荐）
@@ -94,13 +101,14 @@ dsh plugin --profile <name> add dsh-retrace
 > `dsh` 进程）来加载插件。卸载：`dsh plugin --profile <name> remove
 > dsh-retrace`（卸载后同样需要重启）。
 
-同时可在 [dsh-market](https://github.com/dsh-market/dsh-market) 里一键安装
-（安装后同样需要重启）。
-
 ### 2. 手动安装（不依赖 `dsh` CLI）
 
 用纯文件编辑 + `pnpm` 装进同一个 profile —— 也就是 `dsh plugin add` 帮你做的那些步骤：
 
+> **从 GitHub 下载了 ZIP？** 解压到固定位置（如 `~/plugins/dsh-retrace`），
+> 然后执行 `dsh plugin --profile desktop add ~/plugins/dsh-retrace`；或按下面步骤，
+> 把依赖行指向该文件夹：`"dsh-retrace": "file:~/plugins/dsh-retrace"`。
+
 1. 打开 profile 清单（默认位置：DSH Desktop 为 `~/.dsh/profiles/desktop`，
    独立 Web 为 `~/.dsh/profiles/web`），同时加入依赖**和** bundle 层条目：
 
@@ -227,11 +235,15 @@ Client 半区会依据包内 `dsh.client` 元数据被自动打包进 Web 客户
 
 ## 🗺️ 路线图
 
-按 [PLAN.md](./PLAN.md) 推进：
+**当前已具备（0.4.x）：**
+
+- 撤回 / 编辑重发 / 重新生成——每次回退都过**三层写前校验**与安全编辑路径（自动停 agent、临时 step 包裹 marker），**不会损坏日志、不会破坏 /compact**。
+- 单会话**版本时间线** + **产物回退**（git 优先 + 快照兜底、干跑预览、跳转对话）。
+- 对话视图内的**分叉图** + **会话谱系**。
+- **实时看门狗**——并发写入第一时间快照日志。
+- 配套 **`dsh-log-contract`**：30+ 条离线契约规则 + 原地修复（`fix --neutralize` / `--clip-crossstep`），能处理会让 /compact 永久失败的会话。
 
-- **P1 — 时间线与产物回退** ✅ 已上线（0.4.x）：单会话内的版本时间线（版本/消息/思考/工具节点），产物快照（git 优先 + 快照兜底，可开关），带干跑预览的回退，以及跳转到对话位置；marker 写前校验（三层契约）守护日志。
-- **P2 — 分叉图** 🔨 推进中：对话回合的流程分叉图，每次回退都是分叉点，逐回合思考流，分支意图卡、版本对比。
-- 支持更多语言（当前：简体中文 / English）。
+**未来计划**——见 [公开路线图](./docs/ROADMAP.md)（agent 业务层规划：运行时守护、中断治理、生态开放接口）。本 README 只描述已上线的能力。
 
 ---
 
@@ -276,9 +288,28 @@ npm pack --dry-run    # 校验发布文件清单
 
 ## 📚 生态
 
-收录于 [dsh-plugin topic](https://github.com/topics/dsh-plugin)，可在
-[dsh-market](https://github.com/dsh-market/dsh-market) 一键安装。DeepSeek Harness
-插件生态的精选总览见 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)。
+收录于 [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
+> dsh plugin --profile desktop add github:yamingmou/dsh-retrace
+> # 或直接用 pnpm 装进 profile：
+> cd ~/.dsh/profiles/desktop && pnpm add github:yamingmou/dsh-retrace
+> ```
+>
+> 然后照常重启 DSH Desktop。`dsh-log-contract` 依赖会自动带上。
+
+DeepSeek Harness 插件生态的精选总览见
+[awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
+（第三方收录，使用前请自行确认可用性）。
 
 ---
 
@@ -291,3 +322,27 @@ npm pack --dry-run    # 校验发布文件清单
 ## 📄 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/client.bundle.js

@@ -1136,7 +1136,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 +1177,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 +1303,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")),
@@ -1341,13 +1342,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

@@ -1485,7 +1485,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 +1538,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 +1706,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' }, [
@@ -1745,13 +1752,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

@@ -1142,7 +1142,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 +1183,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 +1309,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")),
@@ -1347,13 +1348,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/dynamic-host.js

@@ -121,13 +121,19 @@ return {
         content: [],
         source: { kind: 'model', provider: model.provider, model: model.model },
       }
-      // R2 路径一（2026-08-30 事故闭环）：有打开的 step（回合中编辑）时，marker 携带
-      // 该 step 的 turn/step —— token-meter 配对通过，不产生 T1 违规、不刷屏。
-      // 无打开 step（轮次间编辑，常态）才回退 turn:null（配合 markerT1Broken 标注）。
+      // R2 根治（2026-08-30 事故闭环 v2）：
+      // - 有打开的 step（回合中编辑）：marker 携带该 step 的 turn/step → token-meter 配对通过；
+      // - 无打开 step（轮次间编辑，常态）：**自动开一个临时 step 包裹 marker**
+      //   （step/start → marker → step/end，turn 用 nextTurn，step 恒 1）。
+      //   官方 token-meter 要求 assistant/message 必须有打开的 step（lib/index.js:590，
+      //   stepStart===void 0 即抛）——turn-null 或伪造 turn/step 都过不了；
+      //   临时 step 是唯一能让轮次间 marker 合法化的形态（foldSurface/token-meter/客户端
+      //   Location boundary 三层验证全过）。不再产生 turn-null marker → 不再刷屏。
       const openStep = findOpenStep(session)
+      const nextTurn = nextTurnOf(session)
       const data = {
-        turn: openStep ? openStep.turn : null,
-        step: openStep ? openStep.step : null,
+        turn: openStep ? openStep.turn : nextTurn,
+        step: openStep ? openStep.step : 1,
         message: marker,
         editor: {
           targetSeq,
@@ -139,11 +145,20 @@ return {
       if (typeof validate === 'function') {
         const result = await validate(session, { type: 'assistant/message', data, surfaceOp, sourceEventSeqs })
         if (result && result.t1Ok === false) {
-          // R2：标注该 marker 会破坏 /compact（不阻断编辑）。
+          // 理论上临时 step 后 T1 恒通过；残留 fallback 标注（防御）。
           data.editor.markerT1Broken = true
         }
       }
-      return session.append('assistant/message', data, { surfaceOp, sourceEventSeqs })
+      // 轮次间编辑：开临时 step 包裹（marker 前后成对，token-meter 需要打开的 step）
+      const openedStep = openStep === null
+      if (openedStep) {
+        session.append('step/start', { turn: nextTurn, step: 1 })
+      }
+      const markerEvent = session.append('assistant/message', data, { surfaceOp, sourceEventSeqs })
+      if (openedStep) {
+        session.append('step/end', { turn: nextTurn, step: 1 })
+      }
+      return markerEvent
     }
     
     /**
@@ -164,6 +179,20 @@ return {
       return open
     }
     
+    /**
+     * 下一个 turn 号：scan 最大 turn（turn/start、step/start、assistant/message、user/message
+     * 的 data.turn 中取最大）+1。无任何 turn 时从 1 起。
+     */
+    function nextTurnOf(session) {
+      const events = Array.isArray(session?.events) ? session.events : []
+      let max = 0
+      for (const event of events) {
+        const t = event?.data?.turn
+        if (typeof t === 'number' && Number.isSafeInteger(t) && t > max) max = t
+      }
+      return max + 1
+    }
+    
     function createEditorApi(ctx, sessions, agents, log = () => {}, hooks = {}) {
       /** One in-flight op per session; later ops wait for the earlier one. */
       const locks = new Map()

package/lib/host-core.js

@@ -112,13 +112,19 @@ export async function appendEditorMarker(session, span, op, targetSeq, originalT
     content: [],
     source: { kind: 'model', provider: model.provider, model: model.model },
   }
-  // R2 路径一（2026-08-30 事故闭环）：有打开的 step（回合中编辑）时，marker 携带
-  // 该 step 的 turn/step —— token-meter 配对通过，不产生 T1 违规、不刷屏。
-  // 无打开 step（轮次间编辑，常态）才回退 turn:null（配合 markerT1Broken 标注）。
+  // R2 根治（2026-08-30 事故闭环 v2）：
+  // - 有打开的 step（回合中编辑）：marker 携带该 step 的 turn/step → token-meter 配对通过；
+  // - 无打开 step（轮次间编辑，常态）：**自动开一个临时 step 包裹 marker**
+  //   （step/start → marker → step/end，turn 用 nextTurn，step 恒 1）。
+  //   官方 token-meter 要求 assistant/message 必须有打开的 step（lib/index.js:590，
+  //   stepStart===void 0 即抛）——turn-null 或伪造 turn/step 都过不了；
+  //   临时 step 是唯一能让轮次间 marker 合法化的形态（foldSurface/token-meter/客户端
+  //   Location boundary 三层验证全过）。不再产生 turn-null marker → 不再刷屏。
   const openStep = findOpenStep(session)
+  const nextTurn = nextTurnOf(session)
   const data = {
-    turn: openStep ? openStep.turn : null,
-    step: openStep ? openStep.step : null,
+    turn: openStep ? openStep.turn : nextTurn,
+    step: openStep ? openStep.step : 1,
     message: marker,
     editor: {
       targetSeq,
@@ -130,11 +136,20 @@ export async function appendEditorMarker(session, span, op, targetSeq, originalT
   if (typeof validate === 'function') {
     const result = await validate(session, { type: 'assistant/message', data, surfaceOp, sourceEventSeqs })
     if (result && result.t1Ok === false) {
-      // R2：标注该 marker 会破坏 /compact（不阻断编辑）。
+      // 理论上临时 step 后 T1 恒通过；残留 fallback 标注（防御）。
       data.editor.markerT1Broken = true
     }
   }
-  return session.append('assistant/message', data, { surfaceOp, sourceEventSeqs })
+  // 轮次间编辑：开临时 step 包裹（marker 前后成对，token-meter 需要打开的 step）
+  const openedStep = openStep === null
+  if (openedStep) {
+    session.append('step/start', { turn: nextTurn, step: 1 })
+  }
+  const markerEvent = session.append('assistant/message', data, { surfaceOp, sourceEventSeqs })
+  if (openedStep) {
+    session.append('step/end', { turn: nextTurn, step: 1 })
+  }
+  return markerEvent
 }
 
 /**
@@ -155,6 +170,20 @@ export function findOpenStep(session) {
   return open
 }
 
+/**
+ * 下一个 turn 号：scan 最大 turn（turn/start、step/start、assistant/message、user/message
+ * 的 data.turn 中取最大）+1。无任何 turn 时从 1 起。
+ */
+export function nextTurnOf(session) {
+  const events = Array.isArray(session?.events) ? session.events : []
+  let max = 0
+  for (const event of events) {
+    const t = event?.data?.turn
+    if (typeof t === 'number' && Number.isSafeInteger(t) && t > max) max = t
+  }
+  return max + 1
+}
+
 export function createEditorApi(ctx, sessions, agents, log = () => {}, hooks = {}) {
   /** One in-flight op per session; later ops wait for the earlier one. */
   const locks = new Map()

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.9",
+  "version": "0.4.11",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",