dsh-rewind-plugin 0.7.5 → 0.9.0-alpha.1

package/README.en.md

@@ -8,6 +8,9 @@ Conversation rewind for DeepSeek Harness: **rewind the conversation to any earli
 
 > English | [中文](README.md)
 
+> [!WARNING]
+> For the upcoming DSH line (v0.1.3), users who want the latest DSH should move to the new plugin (`>=0.9.0-alpha.1`) and update their session logs — see the [update guide](docs/rewind-fix.md).
+
 A deliberately focused plugin with one job: **rewind to any user message, no matter how far back, in place** — and conveniently **restore the files it changed** along the way.
 
 - **Rewinding is time-travel** — the target message and everything after it (agent replies, tool calls) are withdrawn from the model context *and* the rendered transcript at once, with no new session and no window switch; the target's text is offered back in the composer so you can edit and re-send it — **truly seamless and convenient by design**.
@@ -91,13 +94,13 @@ The whole design rests on two principles, simple but deliberate: **the conversat
 
 ### 1. Conversation rewind: a single "mask", not a delete
 
-`append-only` is a hard rule: the session log only grows and is never rewritten — the foundation of auditability and privacy. A rewind never touches history; it makes a single move: append **one empty-content message marker** to the end of the log and use it to "mask out" everything after the target message, so the model and the UI see only the part before it.
+`append-only` is a hard rule: the session log only grows and is never rewritten — the foundation of auditability and privacy. A rewind never touches history; it makes a single move: append **one content-empty marker message** to the end of the log and use it to "mask + replace" everything after the target message, so the model and the UI see only the part before it.
 
-- The marker is **empty** — it never enters the model context and never renders as conversation content; what you and the model see is exactly how the conversation looked at the target. True "in place".
-- Because this is **masking, not deleting**, every withdrawn event stays in the log — auditable, traceable, and in principle manually recoverable.
-- The marker is deeply **aware of dsh internals**: it reuses the **last-started turn** number (never "last turn + 1") and carries its own **ghost step frame**. So the harness's own log replay, `/compact`, and resume preflight all recognize it and never mistake it for a real message.
+- The marker is **canonical** — the plugin **replicates** `/compact`'s "hide + replace": `/compact` compresses a span of history into a summary, while `/rewind` swaps in an empty user message. Because it's canonical, the harness's own log replay, `/compact` compaction, and resume preflight all recognize it and never mistake it for a real message.
+- The replacement is **empty** — the model fully ignores the empty message, with no effect (verified theoretically and empirically). Together with the plugin's UI handling, what you and the model see is exactly how the conversation looked at the target — truly "in place".
+- Because this is **masking, not deleting**, every withdrawn event stays in the log — auditable, traceable, viewable, and in principle manually recoverable.
 
-> **Design highlight**: the entire conversation rewind is **a single append**. It's deterministic, auditable, and — because the log was never broken — a "clean" time-travel. Minimal action, complete semantics. The compatibility subtleties with the harness (ghost step frame, reused turn number) are where this plugin is genuinely professional — each is pinned by a dedicated probe test.
+> **Design highlight**: the entire conversation rewind is **a single append**. It's deterministic, auditable, and — because the log was never broken — a "clean" time-travel. Minimal action, complete semantics. The compatibility subtleties with the harness (replicating `/compact`, the empty-message mask) are where this plugin is genuinely professional — each is pinned by a dedicated probe test.
 
 ### 2. File restore: lightweight checkpointing, "back up before the change"
 
@@ -121,7 +124,7 @@ The file half follows Claude Code's checkpoint semantics — **partial tracking
 | Identical content stored as a link (dedup) | Hundreds of repeated writes cost almost nothing; links are materialized before their group is evicted, never left dangling |
 | Session-level auto-cleanup | Removes only long-inactive sessions' snapshots; the active session and the chat log are never touched |
 | Reconcile against the real disk before restoring | Idempotent, zero side effects, no collateral damage |
-| Ghost step frame + reused turn number | Deeply compatible with the host, pinned by probe tests |
+| Empty-message mask + replicating `/compact` | Deeply compatible with the host, pinned by probe tests |
 | Crash safety (atomic writes + restore journal) | Continue or roll back cleanly after a crash |
 | Pure-function planning + probed store | Fully unit-testable without a host; test-driven |
 
@@ -154,9 +157,9 @@ withdrew should consume the stable, locale-independent helpers exported from
 
 1. **Exported logs are complete** — a rewind only removes messages from the model context and the view; the exported session log (`/export`) still contains **withdrawn messages**. This plugin cannot alter exports.
 2. **Lightweight file rewind has a cost** — in specific cases not all changes can be rewound. Consistent with Claude Code. See: [File-rewind tracking boundary](docs/compat/tracking-boundary.md).
-3. **Rewinds from `≤ v0.2.4`** — sessions rewound with these versions may **fail to load history** after more conversation. Install a v0.3.3-or-earlier release and use its bundled repair tool ([docs/compat/troubleshooting.md](docs/compat/troubleshooting.md)).
-4. **Rewinds from `≤ v0.3.3`** — compaction (`/compact`) is unavailable for those sessions. Newer versions are compatible; for affected old sessions, start a new session.
-5. **The turn-rail shows rewound turns** — the right-side rail added in DSH `v0.1.2-alpha.1` keeps ticks for withdrawn messages: clicking does not jump and hovering shows the withdrawn text. Only a display difference; no functional impact.
+3. **The turn-rail shows rewound turns** — the right-side rail added in DSH `v0.1.2` keeps ticks for withdrawn messages, and hovering shows the withdrawn text. Only a display difference; no functional impact.
+4. **The system prompt is re-displayed after a rewind** — in DSH `v0.1.2`, rewinding and resending a message shows the "System prompt" component again, just like `/compact`. Only a display difference; no functional impact.
+5. **Old rewind markers are no longer compatible** — DSH `v0.1.3` rejects the rewind markers from the old plugin (≤ 0.8.0). The new version resolves this and provides an in-session update. See the [update guide](docs/rewind-fix.md).
 
 > [!NOTE]
 > Browser diagnostics are available; see [Browser diagnostics](docs/compat/diagnostics.md).

package/README.md

@@ -8,6 +8,9 @@ DeepSeek Harness 插件：**一键就地回退对话到任意更早的用户消
 
 > [English](README.en.md) | 中文
 
+> [!WARNING]
+> 为了适配未来版本（DSH v0.1.3），期望使用最新版 DSH 的用户，请尽早使用新版插件（`>=0.9.0-alpha.1`）。并更新你的会话日志，详见：[更新指南](docs/rewind-fix.zh.md)
+
 刻意聚焦、保持极简，只做一件事：**就地回退到任意远的用户消息**，还能**顺手还原改过的文件**。
 
 - **回退 = 时间回溯**——目标消息及其之后的全部内容（agent 回复、工具调用）同时从**模型上下文**和**渲染对话**中撤回，不新建会话、不切换窗口；目标消息文本会回填输入框，改完可重发。**在原理上就真正无感、便捷**。
@@ -81,13 +84,13 @@ dsh plugin --profile web add dsh-rewind-plugin
 
 ### 1. 对话回退：一次「遮蔽」，而不是「删除」
 
-`append-only` 是铁律：会话日志只追加、从不改写——这是可审计与信息安全的地基。回退从不动历史，它只做一步：往日志末尾追加**一条内容为空的消息标记**，用它把目标消息之后的全部内容「遮蔽」掉，让模型和界面都只看得到目标之前的部分。
+`append-only` 是铁律：会话日志只追加、从不改写——这是可审计与信息安全的地基。回退从不动历史，它只做一步：往日志末尾追加一条**内容为空的标记消息**，把目标消息之后的全部内容「遮蔽 + 替换」掉，让模型和界面都只看得到目标之前的部分。
 
-- 标记本身是**空的**——不进入模型上下文、不渲染成任何对话内容，模型和你看到的对话就是目标消息当时的样子，真正的「就地」；
-- 因为是「遮蔽」而非「删除」，**被撤回的每一条事件都完整留在日志里**，可审计、可追溯，原则上也随时能手动恢复；
-- 标记非常「懂」dsh——它复用**最后一个已开始的回合**的编号（而不是「最后回合 + 1」），并自带一个独立的**幽灵步骤框架**。于是 harness 自己的日志重放、`/compact` 压缩、续接检查都能正确识别它，绝不会把它误认为真实对话。
+- **标记是规范的**——插件复刻 `/compact` 标准的「隐藏 + 替换」：`/compact` 把一段历史压缩成摘要，`/rewind` 则换成一条空用户消息。由于其规范性，harness 的日志重放、`/compact` 压缩、续接检查都能正确识别它，绝不会把它误认为真实对话；
+- **替换内容是空的**——模型对空消息完全忽略、无感（理论 + 实测验证）。配合插件对界面显示的处理，模型和你看到的对话就是目标消息当时的样子，真正的「就地」；
+- 因为是「遮蔽」而非「删除」，**被撤回的每一条事件都完整留在日志里**，可审计、可追溯、可查看，原则上也随时能手动恢复。
 
-> **设计点睛**：整个对话回退就是**一条**追加。它确定、可审计，且因为日志从未被破坏，回溯是「干净的」——用最小的动作，实现最完整的语义。那些与 harness 内部的兼容细节（幽灵步骤框架、复用回合号）正是插件的专业所在，每一条都由专门的探针测试固化。
+> **设计点睛**：整个对话回退就是**一条**追加。它确定、可审计，且因为日志从未被破坏，回溯是「干净的」——用最小的动作，实现最完整的语义。那些与 harness 内部的兼容细节（对 `/compact` 的复刻、空消息的遮蔽）正是插件的专业所在，每一条都由专门的探针测试固化。
 
 ### 2. 文件还原：轻量检查点，「改前备份」
 
@@ -111,7 +114,7 @@ dsh plugin --profile web add dsh-rewind-plugin
 | 同内容存为链接（去重） | 上百次重复写入几乎不占空间；淘汰组前先落地链接，绝不悬空 |
 | 会话级自动清理 | 只移除长期不活跃会话的快照，活动会话与对话日志永不触及 |
 | 对照真实磁盘再还原 | 幂等、零副作用、不误伤 |
-| 幽灵步骤框架 + 复用回合号 | 与宿主深度兼容，且被探针测试固化 |
+| 空消息遮蔽 + 对 `/compact` 的复刻 | 与宿主深度兼容，且被探针测试固化 |
 | 崩溃安全（原子写 + 还原日志） | 断电/崩溃后仍可续做或回滚 |
 | 纯函数规划 + 注入探针的存储 | 无需宿主即可单测，测试驱动 |
 
@@ -141,9 +144,9 @@ dsh plugin --profile web add dsh-rewind-plugin
 
 1. **导出的日志是完整内容**——回退只是把消息从模型上下文和视图中移除，`/export` 导出的会话日志包含**已撤回的消息**。本插件无法改动导出。
 2. **轻量文件回退存在代价**——特定情况可能无法回退所有修改。行为与 Claude Code 一致。详见：[文件回退的追踪边界](docs/compat/tracking-boundary.zh.md)。
-3. **v0.2.4 及更早版本**回退过的会话，继续对话后可能加载历史失败。可安装 v0.3.3 及之前版本的随附修复工具处理（[完整步骤](docs/compat/troubleshooting.zh.md)）。
-4. **v0.3.3 及更早版本**回退过的会话，压缩对话（compact）不可用。新版本已兼容；受影响的旧会话建议新建会话。
-5. **导轨显示已回退轮次**——DSH `v0.1.2-alpha.1` 新增的右侧导轨，会为已撤回消息保留刻度：点击不跳转、悬浮显示已撤回正文。仅显示差异，无功能影响。
+3. **导轨显示已回退轮次**——DSH `v0.1.2` 新增右侧导轨，为已撤回消息保留刻度，悬浮显示已撤回正文。仅显示差异，无功能影响。
+4. **回退重显系统提示词**——DSH `v0.1.2` 回退重发消息时，与 `/compact` 一样重显“系统提示词”组件。仅显示差异，无功能影响。
+5. **旧回退标记不再兼容**——DSH `v0.1.3` 拒绝旧版插件（≤ 0.8.0）的回退标记。新版本已解决，并提供会话更新功能。详见：[更新指南](docs/rewind-fix.zh.md)。
 
 > [!NOTE]
 > 本插件提供浏览器端诊断输出；详见 [浏览器诊断](docs/compat/diagnostics.zh.md)。

package/SECURITY.md

@@ -70,14 +70,13 @@ runs.
 ## Conversation integrity
 
 The session log is **append-only** — the plugin never deletes or rewrites
-recorded history. A rewind appends a single marker event: an **empty**
-`assistant/message` whose `surfaceOp` replaces every surface node after the
-target. The raw log (audit trail, search, `/export`) is untouched — only the
+recorded history. A rewind appends a single marker event (an **empty**
+`user/message`) whose `surfaceOp` replaces every surface node after the target.
+The raw log (audit trail, search, `/export`) is untouched — only the
 model-visible surface is cut, so the next request derives its context from the
-target onward. The marker sits inside a ghost `step/start … step/end` frame so
-the harness token-meter replay keeps accepting the log; a malformed marker
-(duplicated turn/step, dangling open step) is what earlier versions produced
-and is repaired offline (see `docs/compat/troubleshooting.md`).
+target onward. The marker is empty, so it carries no untrusted text into the
+model context; the client hides the `[target, marker]` span from the rendered
+transcript.
 
 ## Filesystem containment
 

package/docs/README.md

@@ -12,9 +12,10 @@ index/navigation entry point.
 | `format.md` | Durable on-disk format spec (checkpoint entries + restore journals) | maintainers |
 | `harness-reference.md` | DeepSeek Harness interface reference + plugin source layout | maintainers |
 | `snapshot-auto-cleanup.md` | Global snapshot auto-cleanup policy and command (`.zh` mirror) | users / maintainers |
+| `rewind-fix.md` | Migrate old rewind markers (A/B→C) with `/dsh-rewind-fix` (`.zh` mirror) | users / maintainers |
 | `contract/client-contract.md` | Rewind visibility contract for third-party DOM plugins (`.zh` mirror) | integrators |
 | `compat/audit.md` | Compatibility audit: verified surfaces, recorded findings, probe matrix | maintainers |
-| `compat/troubleshooting.md` | Known issues & repair steps (`.zh` mirror) | users / maintainers |
+| `compat/tracking-boundary.md` | Which files a rewind restores: the tracking boundary (`.zh` mirror) | users / maintainers |
 | `compat/diagnostics.md` | Browser diagnostics (anomaly alerts; verbose switch gates the startup identity line) (`.zh` mirror) | users / maintainers |
 | `release/release.md` | Release workflow & DSH peer-version alignment (`.zh` mirror) | maintainers |
 

package/docs/architecture.md

@@ -17,15 +17,20 @@ credentials access.
 
 ```
 src/
-├── index.ts          host plugin: /rewind command + checkpoint pipeline
-├── rewind.ts         pure planning: target parsing, surface-range plan,
-│                     candidate listing, marker turn/step math
+├── index.ts          host plugin: /rewind, /undo, /snapshot-auto-cleanup,
+│                     /dsh-rewind-fix commands + checkpoint pipeline
+├── rewind.ts         pure planning: target parsing, surface-range plan, candidate listing
+├── rewind-fix.ts     /dsh-rewind-fix orchestration (repair pipeline, locks, rollback)
+├── rewind-marker-repair.ts  pure legacy-marker transform (A/B → C)
+├── session-log-io.ts session-log zstd codec + lossless re-encoder (rewind-fix write-back)
 ├── snapshot.ts       checkpoint store: disk before-backups, journaled restore,
 │                     reconcile / continue / rollback, bounded prune
+├── snapshot-cleanup.ts  cleanup policy + dsh-settings persistence + auto-sweep throttle
 ├── session-cwd.ts    session working-directory resolution (fs-tools rule)
+├── locales.ts        host i18n (t() renderer, HostKey)
 └── client/           browser half: per-message ↶ button (portal bridge),
                      mode popover, hidden-span computation, candidate parsing,
-                     locales, styles
+                     pending interaction, locales, styles
 ```
 
 Two dependency rules keep the design testable:
@@ -48,11 +53,9 @@ machine channels (see [Compatibility strategy](#compatibility-strategy)).
     user/message currently on the surface)
   → agent.cancel({ keepInbox: true }) if running; waitForAgentIdle
   → dropPendingSteering (next-step inbox only; queued messages untouched)
-  → append ghost step frame: step/start (turn = last started turn,
-    step = that turn's next unused number) … marker … step/end
-  → marker = empty assistant/message with
-    surfaceOp { op: 'replace', start, end } over every surface node
-    after the target (+ sourceEventSeqs = shadowed seqs)
+  → append the rewind marker = an empty user/message with surfaceOp
+    { op: 'replace', start, end } over every surface node after the
+    target (+ sourceEventSeqs = shadowed seqs)          [a single event]
   → if mode 'both': store.restoreAfter(targetSeq) + syncRestoreObservations
   → result text carries machine tokens (impact=<n>, restore:/delete: lines)
   → client: hides withdrawn rows (data-dsh-rewind-hidden), refills composer
@@ -63,18 +66,32 @@ Key invariants:
 
 - **The log is append-only.** The marker is the *only* mutation: it cuts the
   model-visible surface, never the raw history (search/export still see it).
-- **The marker is empty** (`content: []`, derives to `null` in the model
-  context) so it renders nothing and enters no model context.
-- **The ghost step frame exists for the token-meter**: replay requires every
-  `assistant/message` inside an open step of the same `(turn, step)`; a bare
-  marker appended while idle would throw on the next `measure()` and silently
-  break `/compact`. The turn/step numbers are chosen so they can never collide
-  with a future real turn (`markerTurnOf` / `markerStepOf` — see
-  `src/rewind.ts`).
+- **The marker is empty** (`content: []`) and carries the dsh-rewind plugin
+  source. It is a `user/message`, the only surface type that can cite the
+  shadowed seqs (`sourceEventSeqs`) — `assistant/message` can no longer carry
+  them (v2). It derives to itself, so it stays as a present-but-empty user
+  turn at the surface tail rather than entering model context as content.
+- **No ghost step frame is needed**: the token-meter step machine ignores
+  `user/message`, and the session invariant imposes no open-turn requirement
+  on it, so the marker is appended while idle, outside any turn, as one event.
 - **Restore is reconciled against the live disk** (`planRestore`), so repeated
   rewinds are idempotent and a rewind whose target state already matches is a
   no-op.
 
+### Marker format history
+
+The rewind marker is written as form C (an empty `user/message` with a
+`surfaceOp.replace` over the shadowed range and `sourceEventSeqs`). Earlier
+plugin versions wrote shapes a newer harness no longer accepts:
+
+- **form A** — a bare `assistant/message(turn=N, step=0)` with no frame.
+- **form B** — a ghost turn frame: `[step/start][assistant/message][step/end]`
+  inside a closed turn.
+
+A/B became unreadable once v2 reserved surface `replace` to a node that cites
+`sourceEventSeqs` (`assistant/message` can no longer carry them). `/dsh-rewind-fix`
+rewrites form A/B in closed sessions to form C so a newer harness accepts the log.
+
 ## Checkpoint pipeline (Claude Code before-backup model)
 
 ```
@@ -98,10 +115,11 @@ pruneStale            cross-session auto-cleanup (default off): whole
 
 ## Compatibility strategy
 
-- **Peer ranges as OR-union of DSH version tuples** (`^0.1.0-rc.6 || ^0.1.1-rc.2 || ^0.1.2-alpha.2`):
-  npm's prerelease rules require the peer range to share the host's
-  `[major, minor, patch]` tuple; `scripts/check-dsh-version.mjs` detects when
-  a new tuple requires appending. See `docs/release/release.md`.
+- **Peer ranges as one tuple per DSH line** (`^0.1.2-rc.1`): npm's prerelease
+  rules require the peer range to share the host's `[major, minor, patch]`
+  tuple, so a new DSH tuple replaces the peer tuple (the single-line model);
+  `scripts/check-dsh-version.mjs` flags when a new tuple arrives. See
+  `docs/release/release.md`.
 - **Test-driven investigation**: `tests/compat-invariants.ts` /
   `compat-interop` / `compat-gaps` probe harness behavior and pin findings in
   `docs/compat/audit.md`; `scripts/verify-host.mjs` runs a real end-to-end

package/docs/compat/audit.md

@@ -7,35 +7,33 @@
 > compatibility invariants. A probe failure is a finding; it enters the
 > fix/pin/record loop.
 >
-> Targeted version: npm `@deepseek-ai/*@0.1.1-rc.2` (matches `package-lock.json`).
+> Targeted version: npm `@deepseek-ai/*@0.1.2-rc.1` (matches `package-lock.json`).
 > Source reference: the upstream [github.com/deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness).
 >
-> Version alignment: `peerDependencies` use an OR-union (e.g.
-> `^0.1.0-rc.6 || ^0.1.1-rc.2 || ^0.1.2-alpha.2`) covering each published tuple series. npm's
-> prerelease matching rules require a candidate to share the range comparator's
-> `[major, minor, patch]` tuple, so appending is needed only for a genuinely new
-> tuple (e.g. a future `0.2.x`); any prerelease within the SAME tuple (alpha → rc)
-> is a no-op. Signal: `npm view @deepseek-ai/dsh version`;
+> Version alignment: `peerDependencies` use one tuple per DSH line
+> (e.g. `^0.1.2-rc.1`). npm's prerelease matching rules require a candidate to
+> share the range comparator's `[major, minor, patch]` tuple, so a new DSH tuple
+> replaces the peer tuple (single-line model); any prerelease within the SAME
+> tuple is a no-op. Signal: `npm view @deepseek-ai/dsh version`;
 > flow: `scripts/check-dsh-version.mjs` (it reads the `latest` dist-tag only; a
-> `-alpha` prerelease published under another tag, e.g. `0.1.2-alpha.2` under
-> `alpha`, is a manual pre-release check).
+> prerelease published under another tag is a manual pre-release check).
 >
-> `0.1.2-alpha.1` was never published to npm, so the peer OR-union is declared only from `0.1.2-alpha.2`; the plugin code still supports the `alpha.1`+ client.
->
-> `0.1.2-alpha.2` … `0.1.2-alpha.5` and `0.1.2-rc.1` verified-compatible; `rc.1` is
-> source-identical to `alpha.5`. They share the `0.1.2` tuple, so the single
-> `^0.1.2-alpha.2` peer member covers all six. `rc.2` (`latest`) stays the primary
-> baseline; verified: rc.2, alpha.2, alpha.3, alpha.4, alpha.5, rc.1.
+> The plugin targets a single DSH version line (`0.1.2-rc.1`); compatibility
+> with earlier lines is not kept.
+
+### Single channel (`0.1.2-rc.1`)
 
-### Channeled seams (version × channel)
+The plugin targets one DSH channel. Each seam below reads the 0.1.2-rc.1 shape
+only (no `Session.events` / `[data-time-hover-root]` / `<textarea>` / face-`chat`
+legacy branch).
 
-| Seam | rc.2 (`0.1.1-rc.2`) | alpha.2 / alpha.3 | alpha.4 / alpha.5 / rc.1 |
-| --- | --- | --- | --- |
-| Host session log (`eventsOf`) | `Session.events` | `Session.events` | `session.snapshotEvents()` |
-| Client chat snapshot (`chatSnapshotOf`) | session-face `chat` field | `uiConversation` `chat` view | `uiConversation` `chat` view |
-| Client composer refill (`writeComposer`) | `<textarea>` DOM write | `conversation.input.setDraft` | `conversation.input.setDraft` |
-| Client settings card | nested `ctx.inject(['settingsScope'])` | nested `ctx.inject(['settingsScope'])` | nested `ctx.inject(['settingsScope'])` |
-| Client seat-button DOM (`actionsContainerOf`) | `[data-time-hover-root]` | `[data-actions-reveal]` | structural locate of the copy-`<button>` container |
+| Seam | 0.1.2-rc.1 implementation |
+| --- | --- |
+| Host session log | `session.snapshotEvents()` |
+| Client chat snapshot | `uiConversation` `chat` view (`chatSnapshotOf`) |
+| Client composer refill | `conversation.input.setDraft` facade |
+| Client settings card | nested `ctx.inject(['settingsScope'])` |
+| Client seat-button DOM | structural locate of the copy-`<button>` container (`actionsContainerOf`) |
 
 ## Definition of "fully compatible" (invariants)
 
@@ -43,30 +41,30 @@
 |---|---|---|
 | I1 log replayability | A rewound log passes token-meter replay and `Session.create` (the resume-preflight validation) without throwing | `compat-invariants` I1, `verify-host` 12/13 |
 | I2 surface consistency | After a cut, the surface has no duplicate nodes, every node exists in the log, the withdrawn target never returns to the surface, and `deriveMessages()` is legal | `compat-invariants` I2 |
-| I3 step/turn structure | Client turn-tail ordering, unique `step/start`, every `step/end` and `assistant/message` has a paired `step/start`, no ghost turns | `compat-invariants` I3, `helpers.assertTurnTailOrdering` |
+| I3 step/turn structure | Client turn-tail ordering, unique `step/start` (real turns), no ghost turns; the `user/message` rewind marker adds no step frame | `compat-invariants` I3, `helpers.assertTurnTailOrdering` |
 | I4 fold-service safety | stats / title / goal / projection fold a marker-bearing log without throwing, with predictable values | `compat-invariants` I4 |
 | I5 compact interop | A tool-call orphaned by a cancelled turn is pair-balanced once shadowed by a rewind; a rewind across a compaction checkpoint is explicitly refused; a rewind-then-compact transaction stays legal | `compat-interop` I5, `verify-host` 12/14 |
 | I6 tool pipeline | before-snapshot capture/commit/restore is correct (existing `snapshot.test.ts` + `verify-host` 4–8); cancellation timing never hangs | `verify-host` 4–8, 15 |
-| I7 client ordering | A log carrying tool turns, rewind markers, and ghost steps satisfies the client builder ordering | `compat-interop` I7 |
+| I7 client ordering | A log carrying tool turns and rewind markers (a single `user/message` replace) satisfies the client builder ordering | `compat-interop` I7 |
 | I8 runtime safety | `rewind`/`compact` combinations never leave a dangling step/turn frame | `verify-host` 15 |
 
 ## Verified-compatible surfaces (probes pass)
 
-- **token-meter replay** (marker + ghost-step frames + multiple rewinds + interleaved real turns + compact stacking).
+- **token-meter replay** (the empty `user/message` marker + multiple rewinds + interleaved real turns + compact stacking).
 - **compaction transactions**: `toolPairingBalancedBefore/After` stays balanced after a marker cut; the real `/compact` command (`command-compact` + `compaction-basic`, stub summarizer) can land `compaction/start…end` on top of a rewind marker and stay replayable; `/compact` is a legal no-op on a small surface.
 - **resume replay**: `Session.create(id, events)` replays a rewind/compact-bearing log.
-- **session-stats**: a ghost-step frame adds one step but no phantom turn (reuses the turn number).
+- **session-stats**: the `user/message` marker adds no step (the step count stays at the real turns' steps), no phantom turn.
 - **session-title / goal fold**: a marker does not disturb `foldSessionTitle` / `foldGoal`.
 - **client ordering**: turn-tail ordering + `step/start` uniqueness hold for tool turns + marker logs.
 - **rewind across a compact checkpoint**: `RewindError('not-on-surface')` refuses cleanly, no crash.
-- **plan-mode**: a marker reuses the last started turn (no phantom turn); a rewind never touches the log-only `plan/mode` state (plan mode stays active; the user leaves it with `/plan off`) and the log stays replayable (`compat-invariants` I1/I3 marker + `plan/mode` probe, `verify-host`).
+- **plan-mode**: the marker is a turn-less `user/message` (no phantom turn); a rewind never touches the log-only `plan/mode` state (plan mode stays active; the user leaves it with `/plan off`) and the log stays replayable (`compat-invariants` I1/I3 marker + `plan/mode` probe, `verify-host`).
 - **agent-loop cancellation**: `finally` guarantees step/turn closure; the rewind force-stop path leaves no dangling frame.
-- **settings-card cross-version reach**: the Snapshot cleanup card must be registered through a **nested** `ctx.inject(['settingsScope'], …)` — naming `settingsScope` in the module-level inject unmounts the whole client plugin on rc.2 (card and rewind button disappear). It uses only the rc.2↔alpha-common scope subset (`getSnapshot().value` + `set`), never the alpha-only `mutate`.
+- **settings-card registration**: the Snapshot cleanup card must be registered through a **nested** `ctx.inject(['settingsScope'], …)` — naming `settingsScope` in the module-level inject would keep the whole client plugin unmounted on a host without that service (card and rewind button would disappear). It reads `getSnapshot().value` + `set`, never the `mutate` write API.
 
 ## Known behavior boundaries (deterministic differences, non-crash, documented)
 
-- **session-stats / session-telemetry fold the full log**: post-rewind stats do **not** rewind — `turns`/`steps`/`llmMs` still include withdrawn content; telemetry reports the marker and ghost-step frames one-by-one (under the reused old turn). This is the intended "fold the full log" semantics, pinned by probe.
-- **token-meter usage anchor briefly reverts** (G3): after a rewind, the baseline falls back to the heuristic `estimated` until the next real-usage call restores it. Confirmed expected behavior (a marker inherently carries no usage); pinned by `compat-gaps` G3.
+- **session-stats / session-telemetry fold the full log**: post-rewind stats do **not** rewind — `turns`/`steps`/`llmMs` still include withdrawn content; the empty `user/message` marker is folded as a present-but-empty user turn (it adds no step). This is the intended "fold the full log" semantics, pinned by probe.
+- **token-meter usage anchor stays stable** (G3): the empty `user/message` marker carries no usage, but because it is not an `assistant/message`, the baseline anchor does not drop to a heuristic estimate — it stays `usage` across a rewind. Pinned by `compat-gaps` G3.
 - **Withdrawn content stays searchable/exportable**: session-query full-text and `/export` read the raw log; a rewind cuts only the surface, so withdrawn messages remain (declared in the README).
 - **Session title auto-regeneration**: the title derives from the surface, so an automatically-derived title may change after a rewind.
 - **Files written but uncommitted in a cancelled turn**: a `both` rewind cannot restore them (tool side-effect timing; same as Claude Code).
@@ -80,7 +78,7 @@ The plugin treats these as harness-side defects it does not compensate for. Each
 ### RU-I18N: host-side locale preference is not reliably readable at command registration (harness-side structural timing defect; plugin reads once, never retries)
 
 - **Root cause (harness-side)**: the plugin resolves `activeLocale` in an
-  `ctx.inject(['settings'])` callback that reads `settings.get(settingsNamespace('locale')).preference`
+  `ctx.inject(['settings'])` callback that reads `settings.get('locale').preference`
   **once, with no retry** (`src/index.ts`). `dsh-client-locale`'s host half
   registers that `locale` settings section **through its own `ctx.inject(['settings'])`**
   (`packages/client/locale/src/index.ts`). Both callbacks wait only on `settings` and are
@@ -103,7 +101,7 @@ The plugin treats these as harness-side defects it does not compensate for. Each
   strings, e.g. `/goal` — so this behavior is consistent with the ecosystem, not a plugin
   deviation.)
 
-### R-OPENSTEP: an unclosed `step` in the log lets a rewind break token-meter replay (harness-side; plugin guard attempted and reverted)
+### R-OPENSTEP (rewind part resolved): an unclosed `step` in the log breaks token-meter replay; the rewind no longer compounds it
 
 > **Root cause (harness-side)**: an unclosed step left by a crash makes token-meter replay
 > reject any later step activity. DSH `0.1.1-rc.2` now auto-closes crash-left step/turn/tool
@@ -137,7 +135,7 @@ new turn at `phase.turn + 1` (`agent.ts:251-255`) **without closing the leftover
 - **The conversation itself is unaffected** (the request path does not call `tokenMeter.measure`; only compaction-basic does tree-wide).
 - **Manual `/compact` fails permanently** (`compactNow`'s first `measure()` throws the raw error).
 - **Automatic compaction silently stays disabled** (the `agent/pre-step` hook catches and warns; the conversation continues).
-- **rewind's role**: if the user rewinds first (rather than continuing), the ghost `step/start` becomes the first trip-wire, and the plugin has no defensive detection — upgrading a "locally abnormal log" into a "user-visible `/compact` failure."
+- **rewind's role (resolved)**: the v2 `user/message` rewind marker appends no `step/start`, so a rewind no longer introduces the first trip-wire and the R-OPENSTEP rewind amplifier is closed. The harness-side root cause (an unclosed step after a crash, tripped by continuing the conversation) remains.
 
 ## Uncovered boundaries (need an additional e2e layer; non-blocking)
 

package/docs/contract/client-contract.md

@@ -21,7 +21,7 @@ the plugin itself uses (it never reads the DOM or host copy):
 ```ts
 import { hiddenSeqsOf, type HiddenChat } from 'dsh-rewind-plugin/client'
 
-const chat = session.getSnapshot().chat // rc.2 source; 0.1.2-rc.1 uses the uiConversation "chat" view
+const chat = uiConversation.binding(sessionId).target('chat')?.getSnapshot() // the 0.1.2-rc.1 "chat" view
 const hidden = hiddenSeqsOf(chat as HiddenChat) // Set<number> of anchor seqs
 ```
 

package/docs/contract/client-contract.zh.md

@@ -20,7 +20,7 @@
 ```ts
 import { hiddenSeqsOf, type HiddenChat } from 'dsh-rewind-plugin/client'
 
-const chat = session.getSnapshot().chat // rc.2 来源；0.1.2-rc.1 用 uiConversation "chat" 视图
+const chat = uiConversation.binding(sessionId).target('chat')?.getSnapshot() // 0.1.2-rc.1 的 "chat" 视图
 const hidden = hiddenSeqsOf(chat as HiddenChat) // 被隐藏的 anchor seq 集合
 ```
 

package/docs/format.md

@@ -103,9 +103,11 @@ interface RestoreJournalAction {
 }
 ```
 
-States: `running` and `rollback-running` are non-terminal; a host restart turns
-them into `interrupted` (or `recovery-required` when the journal is corrupt or
-a rollback could not complete). `completed` / `rolled-back` are terminal.
+States: `running` and `rollback-running` are non-terminal; `completed` /
+`rolled-back` are terminal. A restart never rewrites the journal — a
+reconciliation *reports* a still non-terminal op as `interrupted` (or
+`recovery-required` when the journal is corrupt or a rollback could not
+complete), while the journal itself stays `running` / `rollback-running`.
 
 ## Write guarantees
 
@@ -144,11 +146,12 @@ a rollback could not complete). `completed` / `rolled-back` are terminal.
 
 ## Versioning policy
 
-The journal schema is `version: 1`. Checkpoint entries currently carry no
-version field. A future incompatible format must either bump the journal
-`version` (readers reject unknown values — there is no best-effort fallback or
-legacy coercion) or move the state root (e.g. `rewind-snapshots/v2`) and ship
-an explicit migration tool. Old-format data is never silently re-interpreted.
+The journal schema is `version: 1` (currently descriptive — `isRestoreJournal`
+validates shape, not version). Checkpoint entries carry no version field. A
+future incompatible format should either make readers reject an unknown
+`version` (there is no best-effort fallback or legacy coercion) or move the
+state root (e.g. `rewind-snapshots/v2`) and ship an explicit migration tool.
+Old-format data is never silently re-interpreted.
 
 ## Cleanup policy persistence
 

package/docs/harness-reference.md

@@ -39,8 +39,8 @@ Also under `docs/` at the repo root: `persistence-catalog.md` (full
 | `tools/pre-execute` / `execute` / `post-execute` | [packages/core/tools/src/index.ts](https://github.com/deepseek-ai/deepseek-harness/blob/main/packages/core/tools/src/index.ts) |
 | Client DOM anchors (`data-chat-flow-kind` / `data-chat-anchor-key`) | [packages/client/ui-conversation/src/client/chat/ChatNodeSeat.tsx](https://github.com/deepseek-ai/deepseek-harness/blob/main/packages/client/ui-conversation/src/client/chat/ChatNodeSeat.tsx) |
 | User bubble rendering | [packages/client/ui-conversation/src/client/chat/MessageItem.tsx](https://github.com/deepseek-ai/deepseek-harness/blob/main/packages/client/ui-conversation/src/client/chat/MessageItem.tsx) |
-| Client `SessionFace` (`command` / `cancel`) | [packages/client/runtime/src/client/contract/session.ts](https://github.com/deepseek-ai/deepseek-harness/blob/main/packages/client/runtime/src/client/contract/session.ts) |
-| Client `PendingWait` (`respond`) | [packages/client/runtime/src/client/sessions/pending.ts](https://github.com/deepseek-ai/deepseek-harness/blob/main/packages/client/runtime/src/client/sessions/pending.ts) |
+| Client `SessionFace` (`command` / `cancel`) | [packages/api/session-controller/src/client/contract/session.ts](https://github.com/deepseek-ai/deepseek-harness/blob/main/packages/api/session-controller/src/client/contract/session.ts) |
+| Client pending interaction (SessionPendingInteraction) | [packages/client/ui-session/src/client/index.ts](https://github.com/deepseek-ai/deepseek-harness/blob/main/packages/client/ui-session/src/client/index.ts) |
 
 ## Plugin source layout
 
@@ -49,16 +49,29 @@ the canonical source; this block only adds the finer-grained client-side files
 and packaging entries.
 
 ```
-src/index.ts            host plugin: /rewind command + checkpoint pipeline (tools/execute|post-execute)
+src/index.ts            host plugin: /rewind|/undo|/snapshot-auto-cleanup|/dsh-rewind-fix
+                        + checkpoint pipeline (tools/execute|post-execute)
 src/rewind.ts           pure planning: target resolution, surface range, candidate listing
+src/rewind-fix.ts       /dsh-rewind-fix orchestration (repair pipeline, locks, rollback)
+src/rewind-marker-repair.ts  pure legacy-marker transform (A/B → C)
+src/session-log-io.ts   session-log zstd codec + lossless re-encoder (rewind-fix write-back)
 src/snapshot.ts         checkpoint store (disk before-backups, restore/preview, bounded prune)
+src/snapshot-cleanup.ts cleanup policy + dsh-settings persistence + auto-sweep throttle
 src/session-cwd.ts      session-cwd resolution (fs-tools rule)
-src/client/index.ts     client plugin: /rewind command decoration + per-message ↶ button portals
+src/locales.ts          host i18n (t() renderer, HostKey)
+src/client/index.ts     client plugin: /rewind command decoration + per-message ↶ button portals;
+                        re-exports the client contract (hiddenSeqsOf / targetSeqOfArgs / HiddenChat)
 src/client/popover.ts   mode-selection popover (both-mode impact confirm)
 src/client/hidden.ts    withdrawn-span computation (hiddenSeqsOf), pure
+src/client/candidates.ts  rewind candidate listing (rewindCandidatesOf), pure
+src/client/pending.ts   pending-steering bubble ↔ queue-mirror matching, pure
 src/client/locales.ts   zh / en copy (LocaleNamespaceMap)
 src/client/styles.ts    injected styles (dsh design tokens)
+src/client/build-info.ts  client build identity (__DSH_REWIND_VERSION__ / __DSH_REWIND_BUILD__)
+src/client/log.ts       client logger (namespaced, dsh-rewind.debug-gated)
 scripts/build.mjs       esbuild: lib/index.js (host ESM) + lib/client.js (loader closure) + .d.ts
+scripts/check-dsh-version.mjs  DSH peer-tuple check (latest dist-tag vs peers)
+scripts/update-badge.mjs       regenerate the tests badge (CI only)
 scripts/verify-host.mjs end-to-end host verification (full check suite)
 tests/                  vitest suites (rewind / snapshot / hidden / session-cwd / integration)
 docs/                   maintainer docs: contract/, compat/, release/ subdirectories