dsh-rewind-plugin 0.14.0-beta.1 → 0.14.0-beta.3

package/docs/compat/tracking-boundary.md

@@ -1,103 +1,220 @@
 # 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`) 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, line edits): 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.
+> When it rewinds files, the plugin **writes back only content it actually backed
+> up**: a file changed by a write-class tool (`write`, `edit`) can always be restored
+> exactly, while a stretch of state that **was not backed up** makes the restore
+> **incomplete** — it prefers to do nothing rather than guess.
+>
+> This document describes how it works, the two known limitations that follow, and
+> why they are accepted. All of it is a **deliberate trade-off** (matching Claude
+> Code's checkpoint semantics), not a defect.
+
+## 1. The two modes of file change
+
+A file in DSH can change in exactly two ways, and the plugin observes them very
+differently.
+
+**The model calls a write-class tool** (`write`, `edit`): the call's arguments carry
+the exact path, so the plugin can capture the file's current content **before** the
+write lands. This path is deterministic — once handled, the file is certainly
+restorable.
+
+**An external edit** (a command-line Bash, a PowerShell write, a build script
+rewriting files, or saving by hand in an editor): nothing declares the modified path
+to the plugin, so **there is no object to capture in advance**; the plugin can only
+discover it after the fact.
+
+## 2. How it works
+
+### One backup = the state when one message began
+
+The plugin does not store the workspace's current state; it stores **state
+transitions**. Every backup answers one question:
+
+> **What was this file when that message began?**
+
+Its content has two forms: `null` means the file **did not exist** (a restore then
+deletes it), otherwise it is a full copy. Together these backups are the session's
+**snapshot** (grouped by message). A backup belongs to **the user message that
+triggered it**; within a single message's turn, every write-class tool call leaves a
+backup of its own, and a restore takes the **earliest** of them.
+
+### Where backups come from: the tracked list
+
+The plugin does not scan the workspace; it follows one **tracked list**: a file joins
+it as soon as a write-class tool handles it **once**; from then on, every new user
+message makes the plugin re-check the files **on that list**; a file that never joins
+it has no backup at all.
+
+Backups come from two sources:
+
+- **Before-write backup**: when the model calls a write-class tool, the plugin takes
+  the current content **before** the change lands and stores it under **the user
+  message that started this turn**;
+- **Message-boundary re-check**: when a new message arrives, if a file on the list
+  now differs from its **latest backup**, the current content is recorded as **that
+  message's** backup. This is the only way an external edit gets backed up.
+
+### Two cases where no backup is produced
+
+- **Unchanged, not stored**: when the boundary re-check finds the disk identical to
+  the latest backup, this re-check writes nothing; if a write-class tool edits that
+  file later in the same turn, that before-write backup is still recorded. A message
+  that changed no file therefore produces no backup of its own.
+- **Over the cap, not stored**: before writing a backup, if a single file is found to
+  exceed the size cap (8 MiB by default, adjustable via `DSH_REWIND_MAX_FILE_BYTES`,
+  `0` disables it), the plugin **refuses the backup**; until that file is back under
+  the cap, no new backup is written for it (the earlier backups remain).
+
+### Restore: backups are the only standard
+
+A restore reads nothing else in the workspace and infers nothing:
+
+1. **Find the backup**: per file, take the **earliest** backup at or after the
+   **target message**; when the target message has no backup of its own, look toward
+   the later messages for the earliest one.
+2. **Compare with the disk**: if it matches the current disk content, nothing is
+   done; otherwise the backup's content is written back (a `null` backup deletes the
+   file).
+
+Looking toward later messages works because "unchanged, not stored" means the target
+message began from the same state as its latest backup — so the earliest later backup
+holds exactly that state (the premise being that nothing between the target message
+and that backup went unrecorded; see limitation 2). Conversely, the nearest backup
+*before* the target is not used because it may predate a **coverage gap** (limitation
+2, case 3): writing it back would overwrite the current file with an older version.
+**Restore less rather than write something wrong.**
+
+### An example
+
+| Msg | In the turn | File content | Backup: what it was when that message began |
+| :---: | --- | :---: | --- |
+| 1 | `write` creates it | `—` → `A` | `null` (the file did not exist before the write; backed up before the write and added to tracking) |
+| 2 | — | `A` | `A` (the disk differs from the previous backup `null`) |
+| 3 | — | `A` | (none: identical to the latest backup, and nothing was edited in this turn, unchanged, not stored) |
+| 4 | `edit` | `A` → `B` | `A` (the content before that edit, a before-write backup) |
+| 5 | `bash` rewrite | `B` → `C` | `B` (msg 4's edit had already taken effect, so the disk held `B` when msg 5 arrived) |
+
+The disk now holds `C`. Rewinding gives: target 1 → the backup is `null`, the file is
+deleted; target 2 → `A`; target 3 → no backup of its own, so looking toward later
+messages finds msg 4's `A`, exactly the state msg 3 began from; target 4 → `A`;
+target 5 → `B`.
+
+## 3. Known limitations
+
+Both limitations share one root cause: **a stretch of state was not backed up**.
+Limitation 1 results in **no restore at all**, limitation 2 in an **incomplete
+restore**.
+
+### Limitation 1: history that never entered tracking — no restore
+
+**Being handled by a write-class tool is the prerequisite for a file to join the
+tracked list and produce backups.** Before that, every external edit it went through
+has no backup, and neither source will write one for it. Two cases:
+
+**Nothing in the session ever handled it.** Rewinding to any message can only report
+"no restorable changes" for that file.
+
+**Something handled it later (the more common case).** Backups exist only from that
+moment on, so earlier history cannot be restored — in the example below, `v0` is
+history the plugin has never seen:
+
+| Msg | In the turn | File content | Backup: what it was when that message began |
+| :---: | --- | :---: | --- |
+| 1 | — | `v0` | (none: the file has not joined the tracked list) |
+| 2 | a manual edit | `v0` → `v1` | (none: as above) |
+| 3 | a manual edit | `v1` → `v2` | (none: as above) |
+| 4 | `edit`, the first time it is handled | `v2` → `v3` | `v2` (before-write backup: the file joins the tracked list at this moment) |
+| 5 | — | `v3` | `v3` (the disk differs from the previous backup `v2`) |
+
+Rewinding to msg 5 → `v3`; to msg 4 → `v2`; and **rewinding to msg 1, 2 or 3 also
+gives `v2`** — the earliest backup after them is msg 4's `v2`. `v2` really is the
+content at the moment the file was first handled, but what those three messages began
+from was `v0`, `v0` and `v1`; the plugin never saw them and cannot restore them.
+
+### Limitation 2: a stretch of state that was not backed up — an incomplete restore
+
+Both "unchanged, not stored" and "over the cap, not stored" leave a stretch of state
+without a backup. When the target message has no backup of its own, the plugin looks
+toward later messages for the backup; as soon as an **unrecorded change** happened
+between the target and that backup, what it takes is no longer the state the target
+message began from. The three cases below stack one more scenario each.
+
+**Case 1: the change does not belong to any message yet**
+
+| Msg | In the turn | File content | Backup |
+| :---: | --- | :---: | --- |
+| 1 | `write` creates it | `—` → `A` | `null` |
+| 2 | — | `A` | `A` (differs from the previous backup `null`) |
+| 3 | — | `A` | (none: identical to the previous backup, and nothing was edited in this turn) |
+| (after) | a manual edit | `A` → `X` | (none: no new message has claimed it yet) |
+
+Rewinding to msg 3: neither it nor anything later has a backup, the plugin does not
+know the file changed, so it **does nothing and the file stays at `X`** (msg 3
+actually began with `A`). To recover `A`, rewind to msg 2 — the backup under it is
+`A`. A later message only makes the state **at that time** (`X`) rewindable; the `A`
+msg 3 began from still cannot come back.
+
+**Case 2: what is backed up is the state after the change**
+
+| Msg | In the turn | File content | Backup |
+| :---: | --- | :---: | --- |
+| 1 | `write` creates it | `—` → `A` | `null` |
+| 2 | — | `A` | `A` (differs from the previous backup `null`) |
+| 3 | — | `A` | (none: identical to the latest backup) |
+| 4 | a command changes it to `B` | `A` → `B` | (none: the disk was still `A` when msg 4 arrived) |
+| 5 | — | `B` | `B` (differs from the previous backup `A`) |
+
+Rewinding to msg 3 or 4: neither has a backup of its own, so looking toward later
+messages finds msg 5's `B` — the state **after** the change, while they began with
+`A`. The disk matches that backup, so the plugin does nothing and the file stays at
+`B`; if the file changed again afterwards, the plugin writes `B` (overwriting
+whatever is newer); and if the change in msg 4's turn had been a command **deleting**
+the file, msg 5's backup would be `null` and rewinding to 3 or 4 would **delete the
+current file**. The difference from case 1 is that a message followed this change and
+recorded the state after it — in case 1 nothing was recorded at all.
+
+**Case 3: the file exceeded the cap while it changed**
+
+| Msg | In the turn | File content | Backup |
+| :---: | --- | :---: | --- |
+| 1 | `write` creates it | `—` → `A` | `null` |
+| 2 | `edit` | `A` → `G1` | `A` (a before-write backup) |
+| 3 | a write-class tool or an external edit | `G1` → `G2` | (none: over the cap, not backed up) |
+| 4 | shrinks back to `B` | `G2` → `B` | (none: still over the cap on arrival, so the re-check skipped it) |
+| 5 | `edit` | `B` → `X` | `B` (a before-write backup; tracking resumes) |
+
+In the "small → big → small" scenario the stretch over the cap has no backup at all —
+a **coverage gap**. Rewinding to msg 3 or 4 finds msg 5's `B`, so the plugin writes
+`B`; the "big" state they began from falls inside the gap and can never be restored.
+And if the file is currently over the cap, **no** target touches it: it prefers to do
+nothing rather than write back an older backup.
+
+## 4. Why these limitations are accepted
+
+Removing **limitation 1** would require the plugin to know which files an arbitrary
+command or external edit modified. Neither route works: having every external writer
+declare itself (neither `sed`, nor build scripts, nor editors will), or tracking the
+whole workspace and taking a whole-tree snapshot before every change — enormous in
+volume, and precise workspace-level history is exactly the job of dedicated snapshot
+tools such as Git. The plugin only does lightweight rewinding aimed at Agent tooling,
+so this limitation stays.
+
+Removing **limitation 2** would mean giving up "unchanged, not stored" and "over the
+cap, not stored": every message boundary would have to record **every** tracked file
+(changed or not), and large files would be backed up in full again and again. That
+cost has two layers: storage grows linearly with the conversation, and messages that
+change no file are the overwhelming majority; and every backup reads and writes a
+whole file, so a very large one saturates disk IO (which is exactly why the per-file
+cap exists).
+
+What the two limitations buy is: lightweight, predictable, and **only ever writing
+back content it actually backed up, never a guess**. For precise workspace-level
+history, use Git.
+
+## Background
+
+This document was originally written for issue
+[#5](https://github.com/SiriLee/dsh-rewind/issues/5) and completed for issue
+[#39](https://github.com/SiriLee/dsh-rewind/issues/39). See also:
+[SECURITY.md](../../SECURITY.md) · [Snapshot auto-cleanup](../snapshot-auto-cleanup.md)

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

@@ -1,55 +1,131 @@
 # 文件回退的追踪边界
 
-> 行为说明——这**不是 bug**。插件的文件回退**有意只追踪模型的专用编辑工具**，并对**已登记文件**额外施加一层边界（消息边界复查）。为 issue [#5](https://github.com/SiriLee/dsh-rewind/issues/5) 编写；与 Claude Code 的 checkpoint 语义保持一致。 [English](tracking-boundary.md)
+> 回退文件时，插件**只写回它确实备份过的内容**：被写类工具改动过的文件始终可以精确还原；而某一段状态**没有被备份**时，还原就会**不充分**——它宁可不动，也不猜测。
+>
+> 本文说明它的原理、由此产生的两项已知限制，以及为什么接受它们。这些都是**有意取舍**（与 Claude Code 的检查点语义一致），不是缺陷。
 
-## 一句话概括
+## 一、文件变更的两种模式
 
-回退**始终能还原**用专用编辑工具（`write` / `edit`）编辑过的文件，因为插件会在编辑前对其快照。**命令行（或手动）编辑**仅当该文件在同一会话中**先前已被某个编辑工具登记**时才会被覆盖——此时变更本身会被记录，但回退到"未变区间中间的边界"时，只能精确到**下一处被记录的状态**（见[已登记文件被编辑工具之外的方式改动时的回退精度](#已登记文件被编辑工具之外的方式改动时的回退精度)）。
+文件在 DSH 中只有两种变化途径，插件对二者的可观测性完全不同。
 
-## 文件变更的分类
+**模型调用写类工具**（`write`、`edit`）：调用参数给出了确切的文件路径，插件能在文件被覆盖**之前**捕获它的当前内容。这条路径是确定性的——一经处理，这个文件就一定可以还原。
 
-**编辑工具**（创建/覆盖、按行编辑）：每次调用都会告诉插件*将要改动哪个文件*，因此插件会在编辑前对文件的当前内容**快照**，回退时能还原。这条路径是**确定性**的——用了就一定可还原。
+**外部编辑**（命令行 Bash、PowerShell 写入、构建脚本改写，或手动在编辑器里保存）：没有任何环节向插件声明被修改的路径，**不存在可以提前捕获的对象**，只能事后发现。
 
-**命令行或手动编辑**：Windows 上的 PowerShell（`pwsh`）写入、Linux 上的 `sed -i`，或手动保存文件。它们**不告诉**插件动了哪个文件，所以**没有可预先快照的对象**。
+## 二、原理
 
-命令/手动编辑仍有一种情况会被覆盖：若该文件在本会话中**先前被某个编辑工具登记过**，插件会在每个用户消息边界复查已登记文件并记录它看到的变更，因此这类文件也能在回退时还原。
+### 一份备份 = 一条消息开始时的状态
 
-## 何时无法回退
+插件不保存"工作区当前状态"，保存的是**状态转变**。每份备份只回答一个问题：
 
-这类是**完全没有记录到"变更前"状态**（有别于下一节的"精度缺口"——那是有记录、但某个中间消息的精确值丢失）：
+> **这条消息开始时，这个文件是什么？**
 
-1. **模型第一次触达时用命令编辑，且该文件从未被登记。** 无快照、无登记——变更前后都没有记录，无从还原；回退到任何消息对该文件都报告"无变更可恢复"。
-2. **文件在模型第一次编辑工具改动前就被手动编辑过。** 插件的首个快照是在编辑工具调用时拍的，因此回退只能把文件还原到手动编辑**之后**的状态，而非**之前**。
+内容有两种形态：`null` 表示文件**不存在**（还原时表现为删除），另一种则是完整副本。这些备份合起来就是这个会话的**快照**（按消息分组存放）。备份归属于**触发它的那条用户消息**；同一条消息的回合里，每次写类工具调用都会留下一份备份，还原时取其中**最早**的一份。
 
-两者都来自**刻意求轻**的取舍。要覆盖各种命令编辑，就得扫描整个工作区、并分类任意命令改了什么——代价高、易错、难维护。插件只登记会交出手确切路径的编辑工具，并以消息边界复查作为轻量安全网。代价是未登记文件的命令编辑不被记录；收益是简单、可靠、易维护——与 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"）
-```
+### 两种不产生备份的情形
 
-插入一条**未变**消息，精度缺口才显现：
+- **不变不存**：边界复查发现磁盘与最近一份备份一致时，这次复查不写备份；若本回合稍后写类工具改动了该文件，那份写前备份照常记录。所以"没有改动文件的消息"自己不产生备份。
+- **超量不存**：准备写备份之前若发现单个文件超过体积上限（默认 8 MiB，可用 `DSH_REWIND_MAX_FILE_BYTES` 调整，设为 `0` 关闭），插件**拒绝备份**；这个文件在回到限制以下之前不会产生新的备份（旧备份仍在）。
 
-```
-消息 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 同样如此。
+还原不读工作区的其他内容，也不做推断：
 
-## 定位
+1. **找备份**：对每个文件，取**目标消息及其之后最早**的一份备份；目标消息自己没有备份时，就向更晚的消息找最早的那一份。
+2. **与磁盘比对**：一致 → 不做任何操作；不一致 → 写回备份的内容（`null` → 删除该文件）。
 
-要把"未登记首触即命令编辑"的情形也做成可还原，意味着对整个工作区反复备份，或依赖 Git 工作树——都笨重，且与插件"轻量快照"的设计相悖。Git 才是管理工作区变更的正确工具。插件的定位是**快速、会话内回退**，因此**刻意不采纳**该能力。
+向更晚的消息找，是因为"不变不存"意味着目标消息开始时的状态与最近一份备份相同——更晚消息的最早备份，记的正是那一刻的状态（前提是目标消息之后、那份备份之前没有未被记录的改动，见限制二）。反过来，不取"目标消息之前最近"的那份备份，是因为它可能早于一个**缺口**（限制二·表现 3）：写回它等于用更旧的版本覆盖当前文件。**宁可少还原，也不写错内容。**
+
+### 示例
+
+| 消息 | 回合内发生 | 文件内容 | 备份：这条消息开始时是什么 |
+| :---: | --- | :---: | --- |
+| 1 | `write` 新建 | `—` → `A` | `null`（落盘前文件不存在，写前备份并加入追踪） |
+| 2 | — | `A` | `A`（磁盘与上一份备份 `null` 不一致） |
+| 3 | — | `A` | （无：与最近一份备份一致，且本轮未编辑，不变不存） |
+| 4 | `edit` | `A` → `B` | `A`（本次编辑之前的内容，写前备份） |
+| 5 | `bash` 改写 | `B` → `C` | `B`（消息 5 到达时磁盘已是 `B`，消息 4 的编辑已生效） |
+
+磁盘当前是 `C`。回退结果：目标 1 → 备份为 `null`，删除文件；目标 2 → `A`；目标 3 → 自己没有备份，向更晚的消息找到消息 4 的 `A`，正是消息 3 开始时的状态；目标 4 → `A`；目标 5 → `B`。
+
+## 三、已知限制
+
+两项限制的根因相同：**某一段状态没有被备份**。限制一的结果是**无法还原**，限制二的结果是**还原不充分**。
+
+### 限制一：没有进入追踪的历史 —— 无法还原
+
+**"被写类工具处理过"是文件加入追踪列表、产生备份的前提。** 在此之前，它经历的所有外部编辑都没有备份，两个来源也都不会为它写备份。两种情形：
+
+**整个会话都没有处理过它。** 回退到任何消息，插件对该文件都只能报告"没有可还原的改动"。
+
+**后来处理过它（更常见）。** 从那一刻起才有备份，更早的历史无法还原——下面例子里 `v0` 是插件从未见过的历史：
+
+| 消息 | 回合内发生 | 文件内容 | 备份：这条消息开始时是什么 |
+| :---: | --- | :---: | --- |
+| 1 | — | `v0` | （无：文件还没有加入追踪列表） |
+| 2 | 手动编辑 | `v0` → `v1` | （无：同上） |
+| 3 | 手动编辑 | `v1` → `v2` | （无：同上） |
+| 4 | `edit` 首次处理 | `v2` → `v3` | `v2`（写前备份：这一刻文件才加入追踪列表） |
+| 5 | — | `v3` | `v3`（磁盘与上一份备份 `v2` 不一致） |
+
+回退到消息 5 → `v3`；消息 4 → `v2`；而**回退到消息 1、2、3 也都会得到 `v2`**——它们之后最早的备份就是消息 4 的 `v2`。`v2` 确实是"首次处理那一刻"的内容，但这三条消息开始时的真实内容分别是 `v0`、`v0`、`v1`，插件从未见过，无法还原。
+
+### 限制二：有一段状态没有被备份 —— 还原不充分
+
+"不变不存"与"超量不存"都会让某一段状态没有备份。目标消息自己没有备份时，插件按"向更晚的消息找"取备份；一旦目标之后、那份备份之前发生过**未被记录的改动**，取到的就不是目标消息开始时的状态。三种表现依次叠加更多场景。
+
+**表现 1：变更还没有归属到任何消息**
+
+| 消息 | 回合内发生 | 文件内容 | 备份 |
+| :---: | --- | :---: | --- |
+| 1 | `write` 新建 | `—` → `A` | `null` |
+| 2 | — | `A` | `A`（与上一份备份 `null` 不一致） |
+| 3 | — | `A` | （无：与上一份备份一致，且本轮未编辑） |
+| （之后） | 手动修改文件 | `A` → `X` | （无：还没有新消息来认领它） |
+
+回退到消息 3：它自己及其之后都没有备份，插件不知道文件变过，于是**不做任何操作，文件停在 `X`**（消息 3 开始时其实是 `A`）。要取回 `A`，回退到消息 2——它名下的备份就是 `A`。之后再来的消息只会让**当时**的状态（`X`）变得可回退，消息 3 开始时的 `A` 仍然回不来。
+
+**表现 2：记下的是变更之后的状态**
+
+| 消息 | 回合内发生 | 文件内容 | 备份 |
+| :---: | --- | :---: | --- |
+| 1 | `write` 新建 | `—` → `A` | `null` |
+| 2 | — | `A` | `A`（与上一份备份 `null` 不一致） |
+| 3 | — | `A` | （无：与最近一份备份一致） |
+| 4 | 命令把文件改成 `B` | `A` → `B` | （无：消息 4 到达时磁盘还是 `A`） |
+| 5 | — | `B` | `B`（与上一份备份 `A` 不一致） |
+
+回退到消息 3 或 4：它们自己没有备份，向更晚的消息找到消息 5 的 `B`——那是变更**之后**的状态，而它们开始时是 `A`。此时磁盘与备份一致，插件不做任何操作，文件停在 `B`；若此后文件又变过，插件会把文件写成 `B`（覆盖比它更新的内容）；若消息 4 的回合里是命令**删除**文件，消息 5 的备份就是 `null`，回退到 3 或 4 会**删除当前文件**。与表现 1 的差别在于：这次变更之后还有消息，它把变更后的状态记了下来——表现 1 里则一条都没记。
+
+**表现 3：变更期间文件超过上限**
+
+| 消息 | 回合内发生 | 文件内容 | 备份 |
+| :---: | --- | :---: | --- |
+| 1 | `write` 新建 | `—` → `A` | `null` |
+| 2 | `edit` | `A` → `G1` | `A`（写前备份） |
+| 3 | 写类工具或外部修改 | `G1` → `G2` | （无：超过上限，不备份） |
+| 4 | 缩回 `B` | `G2` → `B` | （无：消息到达时仍超限，跳过复查） |
+| 5 | `edit` | `B` → `X` | `B`（写前备份，重新追踪） |
+
+"小 → 大 → 小"的场景中，超过上限的那一段没有任何备份，是一个**缺口**。回退到消息 3、4 时取到的是消息 5 的 `B`——插件会把文件写成 `B`；它们开始时的"大"状态落在缺口里，永远无法还原。若磁盘当前仍然超过上限，**任何**目标都不会动这个文件：宁可不动，也不写回一份更旧的备份。
+
+## 四、为什么接受这些限制
+
+**限制一**要消除，得让插件知道任意命令、外部编辑动了哪些文件。两条路都不通：一是让所有外部写入主动申报——`sed`、构建脚本、编辑器都不会这么做；二是全量追踪整个工作区、每次改动前做整树快照——体量极大，而工作区级的精确历史正是 Git 这类专业快照工具的职责。插件只做面向 Agent 工具的轻量回退，因此保留这条限制。
+
+**限制二**要消除，必须放弃"不变不存"与"超量不存"：每个消息边界都要记录**每个**被追踪文件（即使一点没变），大文件也会被反复完整备份。代价有两层——存储量随对话长度线性增长，而未改动文件的消息占绝大多数；以及每次备份都要完整读写文件，文件很大时会把磁盘 IO 打满（单文件上限正是为此而设）。
+
+两项限制换来的是：轻量、可预测，以及**只写它确实备份过的内容、绝不做任何猜测**。需要工作区级别的精确历史时，请使用 Git。
+
+## 背景
+
+本文最初为 issue [#5](https://github.com/SiriLee/dsh-rewind/issues/5) 编写，并为 issue [#39](https://github.com/SiriLee/dsh-rewind/issues/39) 进行完善。相关：[SECURITY.md](../../SECURITY.md) · [快照自动清理](../snapshot-auto-cleanup.zh.md)