dsh-rewind-plugin 0.8.0-alpha.1 → 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,10 +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` keeps ticks for withdrawn messages, and hovering shows the withdrawn text. Only a display difference; no functional impact.
-6. **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.
+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,10 +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` 新增右侧导轨，为已撤回消息保留刻度，悬浮显示已撤回正文。仅显示差异，无功能影响。
-6. **回退重显系统提示词**——DSH `v0.1.2` 回退重发消息时，与 `/compact` 一样重显“系统提示词”组件。仅显示差异，无功能影响。
+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)
 
 ```

package/docs/compat/audit.md

@@ -41,30 +41,30 @@ legacy branch).
 |---|---|---|
 | 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 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).
@@ -101,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
@@ -135,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/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

@@ -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

package/docs/release/release.md

@@ -49,11 +49,9 @@ The line being released determines the branch and the bump:
 
 Each release is `git push <branch>` followed by `git push <branch> --tags`.
 
-- The tag is the **lightweight `npm version` tag** (on the `chore: release …`
-  commit). Push it as-is — **do not** create the tag or the release beforehand
-  with `gh release create <tag>`: that tags the remote's current `main` head, so
-  an unpushed version bump leaves the tag on the wrong commit and the
-  tag/version match check fails.
+- The release commit is **`chore: release vX.Y.Z`**; the **lightweight `vX.Y.Z`
+  tag** sits on it. Do **not** create tag/release first with `gh release create
+  <tag>` (it tags the remote `main` head and breaks the tag/version match).
 - **Before bumping, manually confirm there is no newer DSH version the plugin
   has not been verified against** (a pre-release can ship in DSH Desktop
   without being on npm; see docs/compat/audit.md).
@@ -100,11 +98,15 @@ appended) when DSH releases a new tuple.
 independent of the host; a release declares its DSH line through the peer
 constraint (a single companion tuple), never through the plugin version.
 
-| Plugin version | DSH line | Notes |
+| Plugin version | DSH line | Role (example) |
 | --- | --- | --- |
 | `0.7.x` | `0.1.1` + `0.1.2` (broad) | frozen / EOL |
-| `0.8.x` | `0.1.2-rc.1` (single) | current stable |
-| `0.9.x` | `0.1.3` (single) | next line |
+| `0.8.x` | `0.1.2-rc.1` (single) | current line |
+| `0.9.x` | `0.1.3` (single) | following line |
+
+The rows are illustrative — the DSH line a release targets is the peer
+constraint, and its npm dist-tag is derived from the version (see above), so
+this model does not track the plugin's own version number.
 
 **Versioning.** A DSH version-line break is a MAJOR bump (incompatible with the
 prior DSH line). Within a line, MINOR/PATCH remain compatible.

package/docs/release/release.zh.md

@@ -46,10 +46,9 @@ npm publish --access public
 
 每次发布为 `git push <分支>`，再 `git push <分支> --tags`。
 
-- tag 即 `npm version` 生成的**轻量 tag**（落在 `chore: release …` 提交上）。
-  直接原样 push 即可——**不要**用 `gh release create <tag>` 事先建 tag 或
-  release：它会给远端当前 `main` 的 HEAD 打 tag，若版本 bump 尚未 push，tag
-  就会落在错误提交上，导致 tag/版本一致性校验失败。
+- 发布提交为 **`chore: release vX.Y.Z`**，**轻量 `vX.Y.Z` tag** 落在该提交上。
+  **不要**用 `gh release create <tag>` 事先建 tag/release（会打到远端 `main`
+  HEAD，导致 tag/版本校验失败）。
 - **升版前手动确认**：确认无插件未针对其验证过的更新 DSH 版本（pre-release
   可能只随 Desktop 捆绑、而不发到 npm；见 docs/compat/audit.md）。
 - workflow 校验 tag 与 `package.json` 版本一致，跑 typecheck + 测试 + 完整
@@ -86,11 +85,14 @@ DSH 仍在 rc 阶段，npm 的 prerelease 匹配规则要求 peer 范围与宿
 **一个发布对准一条 DSH 版本线。** 插件自身版本号与宿主解耦；某发布所对准的
 DSH 线由 peer 约束（单一 companion 元组）声明，而非插件版本号。
 
-| 插件版本 | DSH 线 | 说明 |
+| 插件版本 | DSH 线 | 角色（示例） |
 | --- | --- | --- |
 | `0.7.x` | `0.1.1` + `0.1.2`（广兼容） | 冻结 / EOL |
-| `0.8.x` | `0.1.2-rc.1`（单线） | 当前稳定 |
-| `0.9.x` | `0.1.3`（单线） | 下一线 |
+| `0.8.x` | `0.1.2-rc.1`（单线） | 当前线 |
+| `0.9.x` | `0.1.3`（单线） | 后续线 |
+
+各行仅为示例——某个发布对准的 DSH 线由 peer 约束声明，其 npm dist-tag 按版本号
+派生（见上文），因此本模型不跟随插件自身版本号变化。
 
 **版本号。** DSH 版本线破坏性变更 ＝ MAJOR 升版（与更早 DSH 线向后不兼容）。
 同一线内 MINOR/PATCH 保持向后兼容。

package/docs/rewind-fix.md

@@ -0,0 +1,80 @@
+# Rewind-marker update guide
+
+> English | [中文](rewind-fix.zh.md)
+
+## Applies to
+
+- **DSH**: `0.1.2-rc.1`
+- **dsh-rewind**: `0.9.0-alpha.1`
+
+## Background
+
+`/rewind` appends a **marker** to the session log, telling DSH "everything from this screen onward is withdrawn". Aged plugin versions used a "ghost step frame" for this; the current version uses a more canonical, functionally-equivalent shape — a content-empty `user/message` that replaces the content after the target (see the [README](../README.en.md), the "How it works" section).
+
+The next DSH line (`v0.1.3`) will reject the old shape, so **sessions rewound by an older plugin may fail to open after an upgrade**. That's why the plugin ships `/dsh-rewind-fix`: it translates those old markers into the new shape and makes the sessions usable again. The new shape is also fully compatible with older DSH versions.
+
+## Warnings
+
+1. **It directly edits the session log** — it rewrites old rewind markers into the new format. The design already handles the common cases safely (**multiple web windows**, **exit / restart**, **switching sessions**, **power loss**): it only touches **closed** sessions, locks and **backs up** each one before writing, **rolls back** on failure, and is **idempotent** (safe to re-run). It changes the marker only — it deletes no conversation content and **loses no information**.
+
+2. **It resets the matching snapshot backups** — the format update renumbers event seqs, so a session that was **updated** has its snapshot backups (the lightweight backups used to **restore files** for "conversation and code") no longer match, and the plugin **clears** them. This only affects **file restore** (those sessions can't use snapshots to restore files); backups start recording fresh. Sessions that weren't updated keep their snapshots.
+
+## Steps
+
+### Step 1 · Confirm your versions
+
+First confirm your DSH and plugin versions are in the "Applies to" range — it's a prerequisite. If either is out of range, the tool may be unavailable or behave differently. You can just ask the AI for your current DSH and dsh-rewind plugin versions and check they're in range.
+
+### Step 2 · Back up manually (optional)
+
+The command rewrites session files and clears some snapshots, so a backup is a good idea. The default data directory is `~/.dsh` (if you've set `$DSH_HOME`, use its value):
+```sh
+cp -r ~/.dsh/sessions          ~/.dsh/sessions.backup
+cp -r ~/.dsh/rewind-snapshots  ~/.dsh/rewind-snapshots.backup
+```
+Or copy them anywhere convenient.
+
+### Step 3 · Start a new session, or pick one that was never rewound
+
+The command only handles **closed** sessions, and it can't run on itself. So:
+- **Start a new session** — ideally send any message first to initialize the window so you can see the command's progress and output.
+- Or pick a session that was **never rewound** (one that needs no update).
+
+Then run the command **in this new session**, and it will update the old sessions that need it.
+
+> ⚠️ Don't run it in a session that itself needs updating and is currently open — the command skips this session, and any other currently-open/in-use session.
+
+### Step 4 · Preview the update scope
+
+Type `/dsh-rewind-fix` in the composer and send it. It only scans, doesn't write — it reports how many sessions were scanned, how many will be updated, how many skipped, and how many failed. Confirm those are what you expect before moving on.
+```
+/dsh-rewind-fix
+```
+
+### Step 5 · Execute
+
+Once you're sure, re-enter the command with `--apply` to actually run it:
+```
+/dsh-rewind-fix --apply
+```
+This really rewrites the session logs and updates the old markers, and **may take a few minutes**. Please let it finish — **don't switch to another session window or close DSH** while it runs: a session you switch to is **safely skipped** (no corruption, but it won't be updated this pass and you'll need to re-run). A session that fails stays as it was, unharmed, and can be updated again later. Sessions that are updated also get their matching **snapshot backups cleared**, so file restore to earlier messages is no longer available for them.
+
+### Step 6 · Restart DSH and preview again (optional)
+
+After the run, restart DSH, then **preview once more**:
+```
+/dsh-rewind-fix
+```
+If it says there are no more sessions to update, the markers are all current and the old sessions will open normally.
+
+### Step 7 · Delete the backup after confirming (optional)
+
+Use it for a while, and once everything works, delete the backup from step 2:
+```sh
+rm -rf ~/.dsh/sessions.backup ~/.dsh/rewind-snapshots.backup
+```
+
+## Notes
+
+- The session logs are still v0 format; when DSH's later `v0 → v1 → v2` migration (in `v0.1.3`) arrives, if you've completed the `rewind` marker update, the markers themselves won't block it.
+- Some sessions may still be blocked by an **unclosed turn** (a turn that was interrupted/cancelled and never wrote `turn/end`). Per the empirical analysis these are widespread and **unrelated to rewind** — they're a DSH-side issue and this tool doesn't handle them. **So updating the markers doesn't guarantee you can upgrade to the next DSH line.**

package/docs/rewind-fix.zh.md

@@ -0,0 +1,80 @@
+# 回退标记更新指南
+
+> [English](rewind-fix.md) | 中文
+
+## 适配
+
+- **DSH**：`0.1.2-rc.1`
+- **dsh-rewind**：`0.9.0-alpha.1`
+
+## 背景
+
+`/rewind` 回退会往会话日志追加一条**标记**，告诉 DSH 从某一屏往后都算「已撤回」。旧版插件用的是「幽灵步骤框架」写法；新版本已换成更规范且功能一致的形态——一条内容为空的 `user/message`，把目标之后的内容整体替换掉（原理见 [README](../README.md) 的「原理」一节）。
+
+新一代 DSH（`v0.1.3`）会拒绝旧写法，所以**用旧版插件回退过的会话，升级后可能打不开**。因此本插件提供了 `/dsh-rewind-fix` 便捷命令，把这些旧标记「翻译」成新格式，让会话重新可用。新格式同样对旧版本 DSH 完全兼容。
+
+## 警告
+
+1. **会直接编辑会话日志** —— 把旧回退标记更新为新格式。设计上对**多个网页窗口、退出重启、切换会话、关机断电**等场景都已做安全处理：只处理**已关闭**的会话，写前加锁+备份、失败自动回滚、可重复运行（**幂等**）；只动标记本身，不删任何对话内容、**无信息丢失**。
+
+2. **会重置对应的快照备份** —— 格式更新会改变事件序号，**被更新过的会话**，其用于「回退对话和代码」时**还原文件**的对应快照备份将不再匹配，因此会被插件**清除**。这只影响**文件还原**，备份会重新开始记录；没被更新的会话快照不变。
+
+## 操作步骤
+
+### 第一步 · 确认版本
+
+先确认你当前的 DSH 与插件版本落在「适配」范围里——这是前提。版本不符时，工具可能不可用或行为不符。你可以直接问 AI「当前的 DSH 与 dsh-rewind 插件版本」，并确认是否在「适配」范围内。
+
+### 第二步 · 手动备份（可选）
+
+命令会改写会话文件、删掉部分快照，稳妥起见先备份一下。默认数据目录是 `~/.dsh`（若你设置了 `$DSH_HOME`，请用它的值）：
+```sh
+cp -r ~/.dsh/sessions          ~/.dsh/sessions.backup
+cp -r ~/.dsh/rewind-snapshots  ~/.dsh/rewind-snapshots.backup
+```
+或者复制到任意合适的位置。
+
+### 第三步 · 新建会话，或选一个从未回退过的会话
+
+命令只处理已关闭的会话，而且不能在自己身上运行——建议你：
+- **新建一个会话**，先随便发一条消息初始化窗口，确保能看到命令执行过程和结果
+- 选择一个**从未回退过**（不需要更新）的会话
+
+然后在**这个新会话窗口里**运行命令，去更新那些需要处理的旧会话。
+
+> ⚠️ 别在「本身就需要更新、且正开着」的会话里运行——命令会跳过本会话，以及任何正被打开/使用的会话。
+
+### 第四步 · 预览更新范围
+
+在编辑区域输入 `/dsh-rewind-fix` 并发送。它只扫描、不写盘，会告诉你：扫描了几个会话、其中几个将被更新、几个跳过、几个失败。确认是你预期的那几项，再进下一步。
+```
+/dsh-rewind-fix
+```
+
+### 第五步 · 执行
+
+确认无误后，重新输入命令并加 `--apply` 真正执行：
+```
+/dsh-rewind-fix --apply
+```
+这一步会真的改动会话日志、把旧标记更新成新格式，**可能需要几分钟**。请耐心等它跑完，**不要中途切换会话窗口**或关闭 DSH——被切到的会话会被**安全地跳过**（不损坏，但这次不会更新，需重新执行）。更新失败的会话保持原状态不变、无破坏，可重新进行更新。被更新的会话会同时**清掉对应的文件快照备份**，更早消息回退时文件还原不可用。
+
+### 第六步 · 重启 DSH，再预览确认（可选）
+
+执行完后重启一下 DSH，然后**再跑一次预览**：
+```
+/dsh-rewind-fix
+```
+如果提示已经没有待更新的会话，说明标记已全部更新到位，旧会话就能正常打开了。
+
+### 第七步 · 确认正常后删除备份（可选）
+
+继续使用一段时间，确认一切功能正常后，删掉第二步拷贝的备份即可：
+```sh
+rm -rf ~/.dsh/sessions.backup ~/.dsh/rewind-snapshots.backup
+```
+
+## 补充说明
+
+- 当前会话日志仍为 v0 格式；DSH 后续（`v0.1.3`）的 `v0 → v1 → v2` 迁移到来时，如果你完成了 `rewind` 标记更新，标记本身就不会阻断它。
+- 个别会话还可能因**未闭合的 turn**（某次回合被打断/取消、没写 `turn/end`）等问题而卡住迁移——根据实测分析，这些问题普遍存在，**与 rewind 无关**，属 DSH 侧自身问题，本工具不处理。**所以更新完标记并不保证一定能升到下一 DSH 线。**

package/lib/client.js

@@ -1333,7 +1333,7 @@ function createRewindBridge(deps) {
 }
 
 // src/client/build-info.ts
-var PLUGIN_VERSION = true ? "0.8.0-alpha.1" : "dev";
+var PLUGIN_VERSION = true ? "0.9.0-alpha.1" : "dev";
 var BUILD_HASH = true ? "ca24fc4e" : "dev";
 
 // src/client/locales.ts