dsh-rewind-plugin 0.8.0-alpha.1 → 0.9.0-alpha.2

package/README.en.md

@@ -1,5 +1,8 @@
 # dsh-rewind
 
+> [!WARNING]
+> **Planning to use DSH `0.1.3`? Upgrade to the latest plugin (`>= 0.9.0-alpha.1`) as soon as possible and run `/dsh-rewind-fix` to update old rewind markers** ([update guide](docs/rewind-fix.md)).
+
 Conversation rewind for DeepSeek Harness: **rewind the conversation to any earlier user message in one click, in the same window** — no new branch, no window switch, with optional workspace-file restore (full Claude Code `/rewind` semantics).
 
 [![npm version](https://img.shields.io/npm/v/dsh-rewind-plugin.svg)](https://www.npmjs.com/package/dsh-rewind-plugin)
@@ -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

@@ -1,5 +1,8 @@
 # dsh-rewind
 
+> [!WARNING]
+> **计划使用 DSH `0.1.3` 的用户：请尽早升级到最新插件（`>= 0.9.0-alpha.1`），并运行 `/dsh-rewind-fix` 更新旧回退标记**（[更新指南](docs/rewind-fix.zh.md)）。
+
 DeepSeek Harness 插件：**一键就地回退对话到任意更早的用户消息**——同窗口内完成，不新建分支、不换窗口，可一并还原工作区文件（完整 Claude Code `/rewind` 语义）。
 
 [![npm version](https://img.shields.io/npm/v/dsh-rewind-plugin.svg)](https://www.npmjs.com/package/dsh-rewind-plugin)
@@ -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,88 @@
+# 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
+
+`dsh-rewind` rewinds **within the same session** — it never forks a branch. It also follows the conservative policy of **deleting no history** (the session log is an append-only audit trail): it only **appends a marker**, telling DSH "the model-visible conversation continues from this message; everything after it is rolled back". Older plugin versions wrote that **rewind marker** as a "ghost step frame", which worked reliably on DSH v0.1.2-rc.1 and earlier.
+
+But DSH v0.1.3 (alpha) introduces a stricter **session-format validation**. We discovered ahead of time that the **rewind markers** written by older plugin versions **cannot be validated** under those stricter checks, so **a session rewound with `/rewind` may fail to open** when that line ships.
+
+The plugin is prepared in two parts, both shipped in the new version:
+
+1. **New rewind markers use the new shape** (forward) — this is a **correct, low-risk**, long-term change (see the [README](../README.en.md), the "How it works" section), and the new shape is fully compatible with **both old and new** DSH.
+
+2. **The `/dsh-rewind-fix` command** (backward) — for **already-existing** old sessions, the plugin ships a convenient update command that translates those old markers into the new shape so the sessions are usable again.
+
+This document covers mainly the **update command**.
+
+## 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.**