dsh-rewind-plugin 0.4.1 → 0.5.0

package/SECURITY.md

@@ -0,0 +1,154 @@
+# Security model
+
+This document is the security model of **dsh-rewind** — how the plugin treats
+untrusted input, what it is allowed to mutate, and how it survives crashes.
+It is derived from the implementation (`src/index.ts`, `src/snapshot.ts`); if
+this document and the code ever disagree, the code wins and this document is
+a bug.
+
+## Trusted boundary
+
+The plugin runs in the DSH host process and therefore holds the host user's
+filesystem authority — it reads and writes files with plain `node:fs`. The
+following are treated as **untrusted inputs**:
+
+- **Model arguments** — the `file_path` / `path` / `command` fields of write,
+  `edit`, and `str_replace_editor` tool calls (they name the paths the
+  checkpoint store records).
+- **Session log contents** — events are parsed structurally; a hostile or
+  malformed id must never escape the store root.
+- **Current worktree state** — restore planning reconciles against the live
+  disk, which may have been changed by anything.
+- **Concurrent external modifications** — a restore never assumes the disk
+  still matches its records.
+
+The DSH host (and its other plugins) is trusted; this plugin does not
+re-verify the host's own authority boundaries.
+
+## Mutation gates
+
+The plugin **automatically captures** before-backups of tracked mutations, but
+**never automatically applies** one. A workspace restore happens only through
+an explicit user-invoked `/rewind @<seq> both` (the per-message ↶ button or the
+command channel), and only when all of the following hold:
+
+1. **A validated target**: `planRewind` accepts only a `user/message` seq that
+   is currently on the session surface (`parseRewindTarget` → `RewindPlan`).
+2. **A fresh plan**: the plan is derived from the current `events` + `surface`
+   at execution time — never cached across events.
+3. **Committed backups exist**: every planned action comes from a committed
+   checkpoint entry anchored at or after the target.
+4. **Live-disk reconciliation**: `planRestore` compares each entry against the
+   current disk and plans only actions that would actually change it — an
+   already-matching state is a no-op (restores are idempotent).
+5. **Exclusive execution**: a per-session in-flight guard rejects concurrent
+   rewinds; a running turn is force-cancelled (`keepInbox`) and quiescence is
+   awaited before the surface is cut.
+6. **Session binding**: the restore reads/writes only the store of the rewound
+   session (paths are resolved display paths the session's own tools touched).
+
+**Concurrency scope**: the in-flight guard above only serializes concurrent
+*rewinds* of one session; it does not stop other processes from modifying the
+workspace. `planRestore` reconciles against the live disk at plan time, but
+there is no re-validation between planning and applying — a file changed by
+another process in that window is overwritten by the restore. The rescue state
+is captured at apply start, so `rollbackRestore` still returns the workspace
+to exactly the apply-start state, and per-file failures are reported rather
+than hidden.
+
+A failed gate fails closed: an invalid target, a missing store, an absent
+backup, or a cancelled invocation aborts the rewind with an error.
+
+**Automatic store deletion (opt-in)**: unrelated to restores, an enabled
+`snapshot-auto-cleanup` background sweep deletes whole session directories of
+**long-inactive** sessions (default off — the store is otherwise only mutated by
+an explicit rewind apply). It is confined to the store root, uses `lstat` (so it
+never follows a symlink out of the root), skips the active session, and never
+touches the conversation log. When disabled (the default), no automatic deletion
+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
+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`).
+
+## Filesystem containment
+
+- **Store root**: `~/.dsh/rewind-snapshots/` by default (`DSH_REWIND_SNAPSHOT_DIR`
+  overrides it). The store never overlaps the workspace; deleting it only
+  removes file backups and the store rebuilds from scratch.
+- **Path sanitization**: session ids and call ids are scrubbed to
+  `[a-zA-Z0-9._-]` (`safeSessionId` / `safeFileId`) before joining the store
+  root; `.` and `..` bare values are replaced — hostile ids cannot traverse
+  out of the root.
+- **Never written through links**: symlinked and hard-linked paths
+  (`lstat().nlink > 1`) are skipped and reported, never restored — a symlink
+  would redirect the write outside the checkpoint, and a hard link would
+  clobber every other name of the same inode (e.g. pnpm-installed files).
+- **Restores name only recorded paths**: the store contains resolved display
+  paths of the session's own write-class tool calls (plus boundary re-checks
+  over that same tracked set) — a restore can never write an arbitrary path.
+- **Path resolution rule**: relative paths resolve against the session
+  workspace cwd, mirroring the fs tools' own rule (`src/session-cwd.ts`).
+- **Bounded backups**: `prune` keeps the newest 100 anchor groups per session
+  (`MAX_ANCHOR_GROUPS`), so backup accumulation cannot grow the store without
+  bound (the exact cap is pinned in `docs/format.md`). Across sessions, the
+  opt-in `pruneStale` sweep removes whole **long-inactive** session directories
+  (measured by the newest member being idle past `maxAgeDays`); it uses `lstat`
+  (no symlink following), skips dot-prefixed temp files, and never targets the
+  active session (`keepActiveId`).
+
+## Crash safety
+
+- **Atomic commits**: every JSON write (checkpoint entries, restore journals)
+  goes to a sibling temp file and is renamed over the target. A host crash
+  mid-write can leave only an inert `<target>.tmp` — never a readable
+  half-written file — and readers never pick up temp files.
+- **Journaled restores**: before mutating anything, the restore captures each
+  planned path's pre-restore ("rescue") state and persists an intent journal,
+  then marks each action done as it is applied. A crash at any point leaves
+  the journal on disk.
+- **Disk is truth**: after a restart, `reconcileRestores` re-derives from the
+  real disk which paths already match the goal (restored) and which are
+  pending; `continueRestore` finishes the interrupted op, `rollbackRestore`
+  undoes it to the exact pre-restore state. A journal whose goal is already
+  reached auto-heals to its terminal state.
+- **Fail-loud vs fail-soft**: a corrupt **journal** is reported
+  `recovery-required` — never silently dropped (dropping it would erase the
+  interrupted restore's recovery record). Corrupt **checkpoint entries** are
+  silently ignored (they only lose one backup, not the recovery path).
+- **Journal IO never fails the restore**: if the journal cannot be written the
+  restore proceeds with pre-journal semantics (crash safety degrades,
+  behavior does not).
+
+## Explicit non-goals
+
+- This plugin does **not** sandbox other processes or stop them from changing
+  files concurrently.
+- It does **not** provide confidentiality or tamper resistance against the
+  same operating-system user: state files are created with the process
+  default permissions (no special modes are set — a standard umask applies),
+  and the host user remains trusted.
+- It does **not** touch git (no refs, index, or worktree operations), makes
+  **no network requests**, and does **not** access credentials.
+- It does **not** roll back whole-log state: telemetry, search, and `/export`
+  still see the withdrawn messages (documented behavior, not a bug).
+- It does **not** restore files written by a cancelled tool call that never
+  committed a backup.
+- **Subagent session edits are not tracked** (Claude Code alignment): a
+  subagent runs its own session, so the files it changes are not backed up and
+  cannot be restored by a rewind of the parent session.
+
+## Reporting
+
+Report a vulnerability through the repository's GitHub security channel or to
+a repository maintainer. Include: the plugin version/commit, the DSH
+(`@deepseek-ai/*`) version, the platform, and a minimal reproduction — and
+whether the failure happened before or after workspace mutation.

package/docs/README.md

@@ -0,0 +1,29 @@
+# Docs
+
+Documentation lives under `docs/`, organized by concern. Everything here is
+maintainer-facing unless the purpose column says otherwise. This file is the
+index/navigation entry point.
+
+## Index
+
+| Path | Purpose | Audience |
+| --- | --- | --- |
+| `architecture.md` | Module layering, rewind/checkpoint pipelines, compatibility strategy, roadmap | maintainers |
+| `format.md` | Durable on-disk format spec (checkpoint entries + restore journals) | maintainers |
+| `harness-reference.md` | DeepSeek Harness interface reference + plugin source layout | 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 |
+| `release/release.md` | Release workflow & DSH peer-version alignment (`.zh` mirror) | maintainers |
+
+Repo-root docs outside `docs/`: `SECURITY.md` (security model) and
+`CONTRIBUTING.md` (contribution guide).
+
+## Conventions
+
+- Bilingual docs use the `.md` / `.zh.md` file split (e.g. `contract/client-contract.md`
+  + `contract/client-contract.zh.md`, `release/release.md` + `release/release.zh.md`).
+- `compat/audit.md` is the single source of truth for compatibility conclusions;
+  other docs link to it instead of restating them.
+- Cross-links are relative so the whole `docs/` directory stays relocatable — and it
+  ships intact in the npm tarball via the `docs` entry in `files` (`package.json`).

package/docs/architecture.md

@@ -0,0 +1,128 @@
+# Architecture
+
+How dsh-rewind is built: module layering, the rewind pipeline, the checkpoint
+pipeline, the compatibility strategy, and the roadmap. The module map below is
+the same one in `AGENTS.md`; this document adds the wiring between the
+modules. The durable on-disk format is specified separately in
+`docs/format.md`, the security model in `SECURITY.md`.
+
+## Purpose
+
+One thing: rewind a conversation **in place** to any earlier user message —
+never forking a session or switching windows — with an optional Claude-Code-
+style workspace file restore (`both` mode). No network, no git operations, no
+credentials access.
+
+## Module layering
+
+```
+src/
+├── index.ts          host plugin: /rewind command + checkpoint pipeline
+├── rewind.ts         pure planning: target parsing, surface-range plan,
+│                     candidate listing, marker turn/step math
+├── snapshot.ts       checkpoint store: disk before-backups, journaled restore,
+│                     reconcile / continue / rollback, bounded prune
+├── session-cwd.ts    session working-directory resolution (fs-tools rule)
+└── client/           browser half: per-message ↶ button (portal bridge),
+                     mode popover, hidden-span computation, candidate parsing,
+                     locales, styles
+```
+
+Two dependency rules keep the design testable:
+
+1. **`rewind.ts` is pure** — no I/O, no `Session` dependency; everything
+   derives from the event log + ordered surface, so the whole planning layer
+   is unit-testable without a host.
+2. **`snapshot.ts` is host-independent** — it talks to the disk through plain
+   `node:fs` plus injected seams (`DiskProbe`, `DeleteFile`, a test-only
+   `crash` hook), so the store is testable without the harness.
+
+The client never reads the DOM to derive rewind state; it consumes the host's
+machine channels (see [Compatibility strategy](#compatibility-strategy)).
+
+## Rewind pipeline
+
+```
+↶ button / /rewind @<seq> both
+  → handleRewind: parseRewindTarget + planRewind (target must be a
+    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)
+  → 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
+    with the target message's text
+```
+
+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`).
+- **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.
+
+## Checkpoint pipeline (Claude Code before-backup model)
+
+```
+tools/execute        captureBefore: for write / edit / str_replace_editor
+                     (mutating commands only), read the file's BEFORE state;
+                     subagent edits are NOT tracked (Claude Code alignment).
+tools/post-execute   commitEntry: anchor = latest user/message seq; skip
+                     failed calls; write the before-backup to the store.
+session/event        user/message boundary: reconcileTracked re-reads every
+  (user/message)     tracked file and records a new before-backup for any
+                     whose disk state changed since last seen — external
+                     edits/deletions enter the record this way.
+prune                keeps the newest 100 anchor groups per session, storing
+                     identical before-content as in-place links that are
+                     materialized before their group is dropped, and recycles
+                     terminal restore journals.
+pruneStale            cross-session auto-cleanup (default off): whole
+                     long-inactive session dirs past the cutoff are removed;
+                     the active session is never targeted.
+```
+
+## Compatibility strategy
+
+- **Peer ranges as OR-union of DSH rc tuples** (`^0.1.0-rc.6 || ^0.1.1-rc.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`.
+- **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
+  rewind + `/compact` chain (the full check suite).
+- **Stable machine channels for third parties**: `dsh-rewind-plugin/client`
+  exports the pure hidden-span computation; withdrawn rows carry
+  `data-dsh-rewind-hidden`; both are semver-protected
+  (`docs/contract/client-contract.md`). DOM coupling is minimized to a small
+  set of marked rows plus a structurally-typed slot registration.
+
+## Roadmap
+
+Ideas under consideration, not commitments:
+
+- **Multi-process identity/lock**: the current in-flight guard is
+  per-process; a cross-process exclusive lock (like the change-ledger
+  competitors) would cover multiple host processes on one worktree.
+- **Lazy-commit UX**: an explicit confirm-then-apply step (a pending state)
+  to reduce mis-touch risk on in-window rewinds, which are inherently less
+  reversible than forked branches.
+- **Locale expansion**: client/host copy is zh/en today; the copy layer
+  (`src/locales.ts`, `src/client/locales.ts`) is already keyed for more.
+- **Composer re-send polish**: the target text is already refilled after a
+  rewind; a first-class "edit and re-send" affordance is a small extension.

package/docs/compat/tracking-boundary.md

@@ -0,0 +1,103 @@
+# File-rewind tracking boundary
+
+> Behavioral note — this is **not** a bug. The plugin's file rewind deliberately
+> tracks only the model's dedicated editing tools, and applies an additional
+> boundary (message-boundary re-check) to registered files. Written for issue
+> [#5](https://github.com/SiriLee/dsh-rewind/issues/5); aligned with Claude Code's
+> checkpoint semantics. [中文](tracking-boundary.zh.md)
+
+## One-line summary
+
+Rewind **always** restores files edited with the dedicated editing tools
+(`write` / `edit` / `str_replace_editor`) because the plugin snapshots them
+before the edit. Command-line (or hand) edits are covered **only when the file
+was previously registered** by an editing tool in the same conversation — and,
+in that case, the change itself is recorded, but rewinding to a boundary inside
+an unchanged interval is only as precise as the next recorded state (see
+[Rewind precision](#rewind-precision-for-a-registered-file-changed-outside-editing-tools)).
+
+## How file changes are classified
+
+**Editing tools** (create/overwrite, edit lines, insert): each call tells the
+plugin *which file* it will change, so the plugin snapshots the file's current
+content **before** the edit and can restore it on rewind. This path is
+deterministic — using them always yields a restorable rewind.
+
+**Command-line or manual edits**: PowerShell (`pwsh`) writes on Windows, `sed -i`
+on Linux, or saving a file by hand. These do **not** tell the plugin which file
+is being touched, so there is nothing to snapshot beforehand.
+
+Command/manual edits are nevertheless covered in one case: if the file was
+**previously registered** by an editing tool in this conversation, the plugin
+re-checks registered files at each user-message boundary and records a change it
+sees, so those files restore on rewind too.
+
+## When a rewind is not available
+
+These are cases where there is **no recorded pre-change state at all** (as
+opposed to the precision gap in the next section, where a state exists but an
+intermediate message's exact value is lost):
+
+1. **The model edits the file with a command on its first touch, and the file
+   was never registered.** No snapshot, no registration — nothing was recorded
+   around the change, so there is nothing to restore from. Every rewind target
+   reports no restorable change for this file.
+2. **The file was manually edited before the model's first editing-tool change.**
+   The plugin's first snapshot is taken at the editing-tool call, so rewind can
+   return the file only to its state *after* the manual edit, not before it.
+
+Both stem from a deliberate **lightweight** trade-off. Supporting command edits
+in every case would require scanning the whole workspace and classifying what
+arbitrary commands changed — costly, error-prone, hard to maintain. Instead the
+plugin registers only the editing tools that hand it an exact path, and relies
+on the message-boundary re-check as its lightweight safety net. The cost is that
+unregistered files' command edits are not recorded; the benefit is a simple,
+reliable, maintainable plugin — the same behavior Claude Code exhibits.
+
+## Rewind precision for a registered file changed outside editing tools
+
+A registered file's snapshots come only from (a) an editing tool's before-capture
+and (b) the boundary's change-detection. So a message is a *recording point* for
+a file only when the file's state differs from its most recent recorded state;
+rewinding to message *M* restores each file to the earliest entry at/after *M*.
+
+If the file was **unchanged** at *M* (relative to its last record), then *M* is
+**not** a recording point. If the file is later changed by a command/manual
+edit, the earliest entry at/after *M* is the one that recorded the **post-change**
+state — so rewinding to *M* restores that post-change state, not the state the
+file actually held at *M*:
+
+```
+message 1   write sets f = "X"        records before=null (file created)
+message 2   boundary records f = "X"  (null → X)
+            a command changes f "X" → "Y"
+message 3   boundary records f = "Y"  (X → Y)
+rewind to message 2 → restores "X"    (correct: f was "X" at message 2)
+```
+
+Now insert one *unchanged* message, and the precision gap appears:
+
+```
+message 1   write sets f = "X"        records before=null (file created)
+message 2   boundary records f = "X"  (null → X)
+message 3   reply, f still "X"        NOT a recording point (unchanged)
+            a command changes f "X" → "Y"
+message 4   boundary records f = "Y"  (X → Y)
+rewind to message 3 → restores "Y"    (wrong: f was "X" at message 3)
+```
+
+Message 2 is a recording point, so rewinding to it recovers the pre-change state
+`X`; message 3 is not, so its exact state is lost once the command changes the
+file. Only recording every registered file at every message — even when nothing
+changed — would close this, at the cost of a per-message file per registered
+file. The plugin avoids that to stay lightweight (see
+[Position](#position)). Claude Code's checkpoints behave the same way.
+
+## Position
+
+Making command edits restorable in the *unregistered-first-touch* case would
+mean repeatedly backing up the entire workspace, or depending on a Git working
+tree — both heavy, and at odds with the plugin's lightweight-snapshot design.
+Git is already the right tool for workspace-change management. The plugin's
+position is to favor **fast, conversation-scoped rewinds**, so this capability
+is deliberately not adopted.

package/docs/compat/tracking-boundary.zh.md

@@ -0,0 +1,55 @@
+# 文件回退的追踪边界
+
+> 行为说明——这**不是 bug**。插件的文件回退**有意只追踪模型的专用编辑工具**，并对**已登记文件**额外施加一层边界（消息边界复查）。为 issue [#5](https://github.com/SiriLee/dsh-rewind/issues/5) 编写；与 Claude Code 的 checkpoint 语义保持一致。 [English](tracking-boundary.md)
+
+## 一句话概括
+
+回退**始终能还原**用专用编辑工具（`write` / `edit` / `str_replace_editor`）编辑过的文件，因为插件会在编辑前对其快照。**命令行（或手动）编辑**仅当该文件在同一会话中**先前已被某个编辑工具登记**时才会被覆盖——此时变更本身会被记录，但回退到"未变区间中间的边界"时，只能精确到**下一处被记录的状态**（见[已登记文件被编辑工具之外的方式改动时的回退精度](#已登记文件被编辑工具之外的方式改动时的回退精度)）。
+
+## 文件变更的分类
+
+**编辑工具**（创建/覆盖、按行编辑、插入）：每次调用都会告诉插件*将要改动哪个文件*，因此插件会在编辑前对文件的当前内容**快照**，回退时能还原。这条路径是**确定性**的——用了就一定可还原。
+
+**命令行或手动编辑**：Windows 上的 PowerShell（`pwsh`）写入、Linux 上的 `sed -i`，或手动保存文件。它们**不告诉**插件动了哪个文件，所以**没有可预先快照的对象**。
+
+命令/手动编辑仍有一种情况会被覆盖：若该文件在本会话中**先前被某个编辑工具登记过**，插件会在每个用户消息边界复查已登记文件并记录它看到的变更，因此这类文件也能在回退时还原。
+
+## 何时无法回退
+
+这类是**完全没有记录到"变更前"状态**（有别于下一节的"精度缺口"——那是有记录、但某个中间消息的精确值丢失）：
+
+1. **模型第一次触达时用命令编辑，且该文件从未被登记。** 无快照、无登记——变更前后都没有记录，无从还原；回退到任何消息对该文件都报告"无变更可恢复"。
+2. **文件在模型第一次编辑工具改动前就被手动编辑过。** 插件的首个快照是在编辑工具调用时拍的，因此回退只能把文件还原到手动编辑**之后**的状态，而非**之前**。
+
+两者都来自**刻意求轻**的取舍。要覆盖各种命令编辑，就得扫描整个工作区、并分类任意命令改了什么——代价高、易错、难维护。插件只登记会交出手确切路径的编辑工具，并以消息边界复查作为轻量安全网。代价是未登记文件的命令编辑不被记录；收益是简单、可靠、易维护——与 Claude Code 相同。
+
+## 已登记文件被编辑工具之外的方式改动时的回退精度
+
+已登记文件的快照只来自：(a) 编辑工具的 before 捕获，(b) 边界复查的变更检测。所以**只有"文件状态相对上次记录发生变化"的那条消息才是记录点**；回退到消息 *M* 会把各文件还原到 *M* 之后**最早**的那条记录。
+
+若文件在 *M* 处**未变**（相对上次记录），则 *M* **不是记录点**。若随后文件被命令/手动编辑改掉，*M* 之后最早的那条记录是**变更后**状态——于是回退到 *M* 会还原成**变更后**状态，而非 *M* 时刻文件**真实**的状态：
+
+```
+消息 1   write 设 f="X"        记录 before=null（文件新建）
+消息 2   边界记录 f="X"        （null→X）
+        命令把 f "X"→"Y"
+消息 3   边界记录 f="Y"        （X→Y）
+回退到消息 2 → 还原成 "X"     （正确：消息 2 时 f 是 "X"）
+```
+
+插入一条**未变**消息，精度缺口才显现：
+
+```
+消息 1   write 设 f="X"        记录 before=null（文件新建）
+消息 2   边界记录 f="X"        （null→X）
+消息 3   回复，f 仍="X"        不是记录点（未变）
+        命令把 f "X"→"Y"
+消息 4   边界记录 f="Y"        （X→Y）
+回退到消息 3 → 还原成 "Y"     （错：消息 3 时 f 实际是 "X"）
+```
+
+消息 2 是记录点，所以回退它能恢复**变更前**状态 `X`；消息 3 不是记录点，一旦文件被命令改掉，它那刻的精确状态就丢了。要关闭这个缺口，就得让每条边界都是快照——每条消息都记录每个已登记文件（哪怕没变）——代价是**每条消息×每个文件都写一个文件**。插件**刻意不做**，以保持轻量（见[定位](#定位)）。Claude Code 的 checkpoint 同样如此。
+
+## 定位
+
+要把"未登记首触即命令编辑"的情形也做成可还原，意味着对整个工作区反复备份，或依赖 Git 工作树——都笨重，且与插件"轻量快照"的设计相悖。Git 才是管理工作区变更的正确工具。插件的定位是**快速、会话内回退**，因此**刻意不采纳**该能力。

package/docs/compat/troubleshooting.md

@@ -0,0 +1,41 @@
+# Troubleshooting
+
+[简体中文](troubleshooting.zh.md)
+
+## History load failure: `…turn-tail… received an update before its start Match`
+
+Rewinds from `≤ 0.2.4` collided with the next real turn's `turn/start`, so reopening the session showed
+
+```
+Failed to load history: conversation Context …:turn-tail… received an update before its start Match (internal)
+```
+
+and the history vanished. Rewinds from `0.2.5` on no longer collide; already-corrupted sessions need an offline repair (the log is append-only). The repair tool (`dsh-rewind-repair`) is no longer shipped from v0.4.0 — install a pre-v0.4.0 release to get it (fully quit dsh web / host first, then):
+
+```sh
+npm exec --yes --package=dsh-rewind-plugin@0.3.3 -- dsh-rewind-repair
+npm exec --yes --package=dsh-rewind-plugin@0.3.3 -- dsh-rewind-repair -- --dry-run  # preview only
+```
+
+It only rewrites the marker events' `data.turn` (seqs, order, and zstd frame structure intact) and backs up the original file before writing — safe to run repeatedly. From a source checkout of a pre-v0.4.0 tag: `node scripts/repair-markers.mjs` (identical flags).
+
+## Known compatibility boundaries
+
+Behavioral notes — none of these is a crash — verified by the compatibility
+probe suites; the audit [audit.md](audit.md) is the source of truth and lists
+the probes that pin each one:
+
+- Session stats / telemetry do **not** roll back with a rewind.
+- Withdrawn messages stay **searchable and exported** (`/export` and full-text
+  search read the raw log).
+- Session titles may **regenerate** (title derives from the current surface).
+- Files written by a **cancelled tool call** (write happened, no snapshot
+  commit) cannot be restored by "conversation and code".
+
+**R-OPENSTEP** (harness-side, plugin does not guard): a session log carrying an
+*unclosed* `step/start` (a crash before the agent loop's `finally` closed the
+step) makes later step activity break token-meter replay, so `/compact` can
+fail after a rewind. Harness `0.1.1-rc.2` fixes the crash path on load
+(`interruptedTurnClosers`); a plugin-side up-front rejection was tried and
+**reverted** (`177ec14`, false positives on real logs). Deep analysis:
+[audit.md](audit.md) → R-OPENSTEP.

package/docs/{troubleshooting.zh.md → compat/troubleshooting.zh.md}

@@ -12,3 +12,18 @@ npm exec --yes --package=dsh-rewind-plugin@0.3.3 -- dsh-rewind-repair -- --dry-r
 ```
 
 工具只改写标记事件的 `data.turn`（保持 seq / 顺序 / zstd 帧结构不变），改前自动备份原文件——可安全重复运行。源码方式：v0.4.0 之前的 tag 下 `node scripts/repair-markers.mjs`（参数相同）。
+
+## 已知兼容边界
+
+以下均为**预期行为而非崩溃**（探针钉住，完整依据见 [audit.md](audit.md) 事实源）：
+
+- 会话统计 / 遥测**不回退**（折叠的是完整日志）；
+- 被撤回的消息**仍可搜索、可导出**（`/export` 与全文搜索基于原始日志）；
+- 会话标题可能**重新生成**（标题由当前 surface 派生）；
+- 被**取消的工具调用**写入的文件（无快照提交）无法由「回退对话和代码」恢复。
+
+**R-OPENSTEP**（harness 侧，插件不设守卫）：日志中存在*未闭合* `step/start`
+（agent 循环的 `finally` 闭合 step 前崩溃）时，后续 step 活动会破坏 token-meter
+重放，回退后 `/compact` 可能报错。harness `0.1.1-rc.2` 已在加载时自动闭合
+（`interruptedTurnClosers`）；插件曾实现前置拒绝但已回退（`177ec14`，真实日志
+误判）。深入分析：[audit.md](audit.md) → R-OPENSTEP。