dsh-rewind-plugin 0.4.2 → 0.6.0

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/audit.md

@@ -0,0 +1,149 @@
+# Compatibility audit (compat-audit)
+
+> Method: **the tests are the audit**. The probes in `tests/compat-invariants.test.ts`,
+> `tests/compat-interop.test.ts`, `tests/compat-gaps.test.ts` and
+> `scripts/verify-host.mjs` drive the plugin's real execution paths through the DSH
+> subsystems' **real consumer paths** (real `@deepseek-ai/*` packages) and assert
+> compatibility invariants. A probe failure is a finding; it enters the
+> fix/pin/record loop.
+>
+> Targeted version: npm `@deepseek-ai/*@0.1.1-rc.2` (matches `package-lock.json`);
+> source reference: the `oss/deepseek-harness` local fork.
+>
+> Version alignment: `peerDependencies` use an OR-union (e.g.
+> `^0.1.0-rc.6 || ^0.1.1-rc.2`) covering each published rc tuple series. npm's
+> prerelease matching rules require a candidate to share the range comparator's
+> `[major, minor, patch]` tuple, so each new tuple series (e.g. a future
+> `0.1.2-rc.x`, `0.2.x`) requires appending a union member; rc rolling within a
+> tuple (`0.1.1-rc.2 → rc.3`) is a no-op. Signal: `npm view @deepseek-ai/dsh version`;
+> flow: `scripts/check-dsh-version.mjs`.
+
+## Definition of "fully compatible" (invariants)
+
+| Invariant | Meaning | Probe location |
+|---|---|---|
+| 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` |
+| 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 |
+| 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).
+- **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-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**: `hasOpenTurn` pairs only `turn/start`/`turn/end`; a marker produces no `turn/start`, so a rewind during active plan is unaffected (static review confirmed).
+- **agent-loop cancellation**: `finally` guarantees step/turn closure; the rewind force-stop path leaves no dangling frame.
+
+## 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.
+- **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).
+- **Attachment files left after a message is shadowed**: attachment storage is not cleaned with the surface (`dsh-attachment-local` not installed, not automatically verified).
+
+## Upstream (harness) issues and the plugin's no-compensation stance
+
+The plugin treats these as harness-side defects it does not compensate for. Each entry records the harness issue, its current status, and the plugin's stance, so a future maintainer does not "fix the wrong direction."
+
+### RU-I18N: host-side locale preference is not reliably readable at command registration (harness-side structural timing defect; plugin reads once, never retries)
+
+- **Root cause (harness-side)**: the plugin resolves `activeLocale` in an
+  `ctx.inject(['settings'])` callback that reads `settings.get(settingsNamespace('locale')).preference`
+  **once, with no retry** (`src/index.ts`). `dsh-client-locale`'s host half
+  registers that `locale` settings section **through its own `ctx.inject(['settings'])`**
+  (`packages/client/locale/src/index.ts`). Both callbacks wait only on `settings` and are
+  independent of each other, so cordis makes **no ordering guarantee** between the
+  section registration and the plugin's read.
+- **Observed failure**: a probe confirmed that when the plugin's read runs, `settings.get('locale')`
+  returns `undefined` (the section is not yet registered), so `activeLocale` stays at the
+  default `'en'` and — because the read is one-shot — is never corrected. The result is that
+  **all host-side `t()` output (runtime messages and command descriptions alike) renders in
+  English**, regardless of the user's language preference.
+- **Not a user-config problem**: `settings.yaml` correctly carries `locale.preference: zh`;
+  reading it directly works. The defect is purely the host-side read racing the section
+  registration.
+- **Plugin stance**: no compensation. The plugin does not add a lazy re-read, a retry loop, or a
+  post-locale description re-registration as a workaround, because the guarantee belongs to the
+  harness (make the locale preference available before plugin registration, or support per-locale
+  command descriptions). The plugin's `t()` design is retained; localized host output is treated
+  as an upstream capability to be restored when the harness provides it. (Command descriptions
+  are English for **every** host command — system plugins also pass raw English `description`
+  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)
+
+> **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
+> boundaries at load via `interruptedTurnClosers` (`dsh-session`, consumed by
+> `session-persistence/src/coordinator.ts`) — **the crash path is fixed**.
+>
+> **Plugin guard (attempted and reverted)**: a `hasOpenStep` + `planRewind` pre-refusal was
+> implemented (`open-step`) but misjudged on **real session logs** (normal rewinds refused, GUI
+> verification broken), and was reverted (`177ec14`). Conclusion: **the plugin sets no guard**,
+> accepting residual risk (an unclosed step produced by a third-party plugin can break
+> `/compact` — that log is already abnormal, and continuing the conversation triggers the same).
+> The fix direction is in the harness (token-meter recovery for unclosed steps), not the plugin.
+
+#### Concrete `step/start` trigger paths (source-confirmed)
+
+The tree has exactly **one** `append('step/start')` producer: `packages/core/agent-loop/src/agent.ts:279`
+(no other producer inside the official packages; `session/end-seed` etc. only truncate torn writes,
+not logically-unclosed steps).
+
+| # | Trigger path | Plausibility | Basis |
+|---|---|---|---|
+| P1 | **Abnormal process termination**: `step/start` is batched to disk (write-behind, `maxDelayMs` per batch) → the step is mid-execution (LLM stream/tool, seconds to minutes) → SIGKILL / OOM-kill / power loss / WSL hard-close → `step/end` (in `finally`, only runs while the process is alive) is never persisted | **Most realistic** | `agent.ts:292` finally; write-behind batching; torn-write fix truncates only a half-written line |
+| P2 | **Third-party plugin bug**: only the official agent-loop produces one, but external plugins may `session.append('step/start', …)` and never close it | possible | public `Session.append` |
+| P3 | **Manual session-file editing**: edit `~/.dsh/…/session.jsonl[.zstd]` (zstd needs decompress/recompress; plaintext config edits directly) | possible but laborious | `persistence-jsonl/format.ts` (`JsonlCompression = 'zstd' \| 'none'`) |
+| P4 | **append itself failing**: `append('step/end')` in `finally` throws (payload is plain numbers, nearly impossible) | theoretical | `agent.ts:292` |
+
+**Amplifier (rewind is not the only trigger)**: after a crash resume, agent-loop `turn()` opens a
+new turn at `phase.turn + 1` (`agent.ts:251-255`) **without closing the leftover step** — so
+"continue the conversation" (a new `step/start`) trips the same token-meter check. Scope:
+
+- **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."
+
+## Uncovered boundaries (need an additional e2e layer; non-blocking)
+
+- Real LLM streaming and auto title generation (L2 stubbed).
+- Real SQLite index lifetime (`dsh-session-query-sqlite` not installed; native deps).
+- Actual browser rendering replay (the client contract's logic layer is covered by `client-contract.test.ts`).
+- Real JSONL persistence round-trip (`dsh-session-persistence-jsonl` depends on native `koffi`; the round-trip validates the harness's own zstd/JSON codec, the plugin is not party to it, not worth the cost, not installed).
+- `session-reference`'s `SessionReferenceResolver.prepare` needs a full session-query service; its data base (current-surface projection) is already covered by the G1 probe (`foldSurface`).
+- telemetry pipeline (`dsh-session-telemetry-otel`) and the attachment provider (`dsh-attachment-local`).
+- Running workflow/jobs cancelled by a rewind: the tool contract requires observing `exec.signal` and settling (`packages/core/tools/src/index.ts`); a rewind triggers the harness's standard cancel, not plugin-specific — statically confirmed, real workflows untested.
+
+## Audit matrix (subsystem × invariant)
+
+| DSH subsystem | I1 | I2 | I3 | I4 | I5 | I6 | I7 | I8 |
+|---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
+| Session core (append/surface/deriveMessages) | ✓ | ✓ | ✓ | — | ✓ | — | ✓ | ✓ |
+| token-meter | ✓ | — | ✓ | — | ✓ | — | — | — |
+| compaction (transaction/command/tool-pairing) | ✓ | — | — | — | ✓ | — | — | ✓ |
+| session-stats / projection | — | — | ✓ | ✓ | — | — | — | — |
+| session-title | — | — | — | ✓ | — | — | — | — |
+| goal | — | — | — | ✓ | — | — | — | — |
+| resume / session-query replay | ✓ | — | ✓ | — | — | — | ✓ | — |
+| tool pipeline (snapshot/restore) | — | — | — | — | — | ✓ | — | ✓ |
+| client ordering | — | — | ✓ | — | — | — | ✓ | — |
+| plan-mode | — | — | — | — | — | — | — | ✓ (static) |
+
+✓ = probe passes; — = not applicable. RU-I18N and R-OPENSTEP are upstream issues the plugin
+does not compensate for (see above); G3 is a confirmed-non-defect behavior pinned in
+`compat-gaps.test.ts` (G1 surface classification via `foldSurface` and G2 projection checkpoint
+both pass).

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。