dsh-rewind-plugin 0.15.0 → 0.15.1

package/docs/compat/diagnostics.md

@@ -1,83 +0,0 @@
-# Browser diagnostics
-
-[简体中文](diagnostics.zh.md)
-
-Every browser-side diagnostic this plugin emits is routed through one small,
-level-filtered channel, so an anomaly surfaces under a single console filter.
-The channel is deliberately narrow: it records only genuine internal anomalies
-the plugin itself detects as off-contract — **not** the normal-path facts the
-user already sees on screen, which carry no attribution.
-
-## Always-on anomaly alerts
-
-`error` and `warn` are always printed (no switch, no configuration) so a fault
-surfaces even for a user who never configured anything:
-
-| Level | Meaning |
-| --- | --- |
-| `error` | Unexpected/breaking failure (e.g. the settings card fails to register) |
-| `warn` | Recoverable anomaly guard (e.g. a rewind command/refill throws, a waited-on outcome never settles, an unmet session binding) |
-
-These cases are rare, cheap, and off-contract. Normal-path detail (which
-branch a refill took, whether a write matched, which rows a rewind cut) is
-deliberately **not** logged: it re-states what the user already sees and adds
-nothing to attribution.
-
-## Scopes
-
-Diagnostics are printed as `[dsh-rewind:<scope>] ...`. The scope names the
-subsystem an anomaly belongs to, so a report can be captured with a single
-console filter:
-
-| Scope | What an anomaly here means |
-| --- | --- |
-| `boot` | Startup identity — `loaded v<version> (build <hash>)`, gated by the verbose switch (see below). Confirms the running bundle matches a fix. |
-| `refill` | The composer refill after a rewind (command/wait/refill throws, a rejected or unmatched command, an outcome that never settles) |
-| `preview` | The `/rewind preview` impact probe behind the mode popover (command rejected/unmatched/threw, an outcome that never settles) |
-| `portals` | Per-message button mount issues (e.g. no session binding) |
-| `retract` | The pending-steering retract path (the remove lost the race, or the remove threw) |
-| `settings` | The snapshot-cleanup settings card |
-
-## Verbose switch
-
-The `info`/`debug` levels are gated by `localStorage['dsh-rewind.debug']`, read
-once per call and filtered by namespace. Two gated lines remain: the `boot`
-startup identity line and the `retract` lost-race line. Both are deliberately
-**off** by default (a normal user's console stays clean, and neither is an
-anomaly), so a reporter enables the scope to see them:
-
-```js
-// Just the startup identity line.
-localStorage['dsh-rewind.debug'] = 'dsh-rewind:boot'
-
-// Or everything (avoids needing an exact scope).
-localStorage['dsh-rewind.debug'] = 'dsh-rewind*'
-```
-
-Reload (`F5`) after setting it. To switch it off:
-
-```js
-delete localStorage['dsh-rewind.debug']
-```
-
-The `error`/`warn` anomaly alerts are **not** gated by this switch — they are
-always printed.
-
-## Capturing a report
-
-1. Reproduce once on the affected page.
-2. In DevTools, filter the Console for `dsh-rewind` and copy the output
-   (with the plugin version and the DSH/kernel version).
-
-The `error`/`warn` anomaly alerts require no setup — they always print. To also
-capture the startup identity line (`boot`) — useful for ruling out a stale
-bundle / un-restarted host — enable the verbose switch first (see above), then
-reload.
-
-## Notes
-
-- This diagnostic surface is an aid for maintainers and cooperating reporters,
-  **not** a stable public interface; its exact keys and output may change
-  without notice.
-- It is scoped to one browser origin and one browser; capture where the problem
-  actually occurs.

package/docs/compat/diagnostics.zh.md

@@ -1,61 +0,0 @@
-# 浏览器诊断
-
-[English](diagnostics.md)
-
-本插件在浏览器端输出的所有诊断信息都经由同一条分级通道，因此异常可在单个控制台过滤器下浮现。该通道**刻意收窄**：只记录插件自身检测到的、偏离预期契约的真实内部异常——**不记录**用户早已在屏幕上看到、且无归因价值的普通路径事实。
-
-## 常开的异常告警
-
-`error` 与 `warn` **总是打印**（无需开关、无需配置），即使从未配置的用户也能看到故障：
-
-| 级别 | 含义 |
-| --- | --- |
-| `error` | 意外/破坏性故障（如设置卡片注册失败） |
-| `warn` | 可恢复的异常护栏（如回退命令/回填抛出异常、等待的结果始终未落定、会话绑定缺失） |
-
-这些情形少见、廉价、且偏离契约。普通路径的细节（回填走了哪个分支、写入是否匹配、回退切断哪些行）则**刻意不记录**：它们重复用户已经看到的现象，对归因毫无增量。
-
-## 作用域
-
-诊断以 `[dsh-rewind:<scope>] ...` 形式打印。`scope` 标明异常所属子系统，因此可用单个控制台过滤器抓取报告：
-
-| scope | 这里的异常含义 |
-| --- | --- |
-| `boot` | 启动身份行——`loaded v<version> (build <hash>)`，由详细输出开关控制（见下）。用于确认运行中的 bundle 是否匹配某个修复。 |
-| `refill` | 回退后的输入框回填（命令/等待/回填抛出异常、命令被拒绝或未匹配、等待的结果始终未落定） |
-| `preview` | 模式气泡背后的 `/rewind preview` 影响探测（命令被拒绝/未匹配/抛出异常、等待的结果始终未落定） |
-| `portals` | 每条消息按钮的挂载问题（如无会话绑定） |
-| `retract` | 插话撤回路径（remove 竞争失败，或 remove 抛错） |
-| `settings` | 快照清理设置卡片 |
-
-## 详细输出开关
-
-`info`/`debug` 级别受 `localStorage['dsh-rewind.debug']` 控制，每次调用读取并按命名空间过滤。仅剩两条受控行：`boot` 启动身份行与 `retract` 竞争失败行。两者**默认关闭**（普通用户控制台保持干净，且都不是异常），排查者需先开启对应作用域才能看到：
-
-```js
-// 仅启动身份行。
-localStorage['dsh-rewind.debug'] = 'dsh-rewind:boot'
-
-// 或全部开启（省去精确 scope）。
-localStorage['dsh-rewind.debug'] = 'dsh-rewind*'
-```
-
-设置后刷新（`F5`）。关闭：
-
-```js
-delete localStorage['dsh-rewind.debug']
-```
-
-`error`/`warn` 异常告警**不受**该开关控制——它们总是打印。
-
-## 采集一段报告
-
-1. 在出问题的页面上复现一次。
-2. 在 DevTools 里把 Console 按 `dsh-rewind` 过滤，复制输出（连同插件版本、DSH/内核版本）。
-
-`error`/`warn` 异常告警无需任何设置——它们总是打印。若要同时采集启动身份行（`boot`，用于排除「旧 bundle / 宿主未重启」），请先开启详细输出开关（见上），再刷新。
-
-## 备注
-
-- 该诊断表面是维护者与配合排查者使用的工具，**不是**稳定公开接口；其具体键与输出可能不经通知而改变。
-- 它受单个浏览器 origin、单个浏览器限定；请在实际出问题的地方采集。

package/docs/compat/tracking-boundary.md

@@ -1,217 +0,0 @@
-# File-rewind tracking boundary
-
-> 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 | the edit grows it past the cap | `A` → `G1` | `A` (differs from the previous backup `null`) |
-| 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.
-
-## See also
-
-[SECURITY.md](../../SECURITY.md) · [Snapshot auto-cleanup](../snapshot-auto-cleanup.md)

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

@@ -1,131 +0,0 @@
-# 文件回退的追踪边界
-
-> 回退文件时，插件**只写回它确实备份过的内容**：被写类工具改动过的文件始终可以精确还原；而某一段状态**没有被备份**时，还原就会**不充分**——它宁可不动，也不猜测。
->
-> 本文说明它的原理、由此产生的两项已知限制，以及为什么接受它们。这些都是**有意取舍**（与 Claude Code 的检查点语义一致），不是缺陷。
-
-## 一、文件变更的两种模式
-
-文件在 DSH 中只有两种变化途径，插件对二者的可观测性完全不同。
-
-**模型调用写类工具**（`write`、`edit`）：调用参数给出了确切的文件路径，插件能在文件被覆盖**之前**捕获它的当前内容。这条路径是确定性的——一经处理，这个文件就一定可以还原。
-
-**外部编辑**（命令行 Bash、PowerShell 写入、构建脚本改写，或手动在编辑器里保存）：没有任何环节向插件声明被修改的路径，**不存在可以提前捕获的对象**，只能事后发现。
-
-## 二、原理
-
-### 一份备份 = 一条消息开始时的状态
-
-插件不保存"工作区当前状态"，保存的是**状态转变**。每份备份只回答一个问题：
-
-> **这条消息开始时，这个文件是什么？**
-
-内容有两种形态：`null` 表示文件**不存在**（还原时表现为删除），另一种则是完整副本。这些备份合起来就是这个会话的**快照**（按消息分组存放）。备份归属于**触发它的那条用户消息**；同一条消息的回合里，每次写类工具调用都会留下一份备份，还原时取其中**最早**的一份。
-
-### 备份从哪里来：追踪列表
-
-插件不扫描整个工作区，只认一张**追踪列表**：文件被写类工具处理**一次**即加入；此后每条新的用户消息到达时，只复查名单里的文件；不在名单里的文件没有任何备份。
-
-备份有两个来源：
-
-- **写前备份**：模型调用写类工具时，在改动落盘**之前**取当前内容，记在**触发这一轮的那条用户消息**名下；
-- **消息边界复查**：新消息到达时，若名单里某个文件当前的磁盘内容与**最近一份备份**不一致，就把当前内容记为**这条消息**的备份。这是外部编辑唯一的入口。
-
-### 两种不产生备份的情形
-
-- **不变不存**：边界复查发现磁盘与最近一份备份一致时，这次复查不写备份；若本回合稍后写类工具改动了该文件，那份写前备份照常记录。所以"没有改动文件的消息"自己不产生备份。
-- **超量不存**：准备写备份之前若发现单个文件超过体积上限（默认 8 MiB，可用 `DSH_REWIND_MAX_FILE_BYTES` 调整，设为 `0` 关闭），插件**拒绝备份**；这个文件在回到限制以下之前不会产生新的备份（旧备份仍在）。
-
-### 还原：只依据备份
-
-还原不读工作区的其他内容，也不做推断：
-
-1. **找备份**：对每个文件，取**目标消息及其之后最早**的一份备份；目标消息自己没有备份时，就向更晚的消息找最早的那一份。
-2. **与磁盘比对**：一致 → 不做任何操作；不一致 → 写回备份的内容（`null` → 删除该文件）。
-
-向更晚的消息找，是因为"不变不存"意味着目标消息开始时的状态与最近一份备份相同——更晚消息的最早备份，记的正是那一刻的状态（前提是目标消息之后、那份备份之前没有未被记录的改动，见限制二）。反过来，不取"目标消息之前最近"的那份备份，是因为它可能早于一个**缺口**（限制二·表现 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 | 文件扩充 | `A` → `G1` | `A`（与上一份备份 `null` 不一致） |
-| 3 | 写类工具或外部修改 | `G1` → `G2` | （无：超过上限，不备份） |
-| 4 | 缩回 `B` | `G2` → `B` | （无：消息到达时仍超限，跳过复查） |
-| 5 | `edit` | `B` → `X` | `B`（写前备份，重新追踪） |
-
-"小 → 大 → 小"的场景中，超过上限的那一段没有任何备份，是一个**缺口**。回退到消息 3、4 时取到的是消息 5 的 `B`——插件会把文件写成 `B`；它们开始时的"大"状态落在缺口里，永远无法还原。若磁盘当前仍然超过上限，**任何**目标都不会动这个文件：宁可不动，也不写回一份更旧的备份。
-
-## 四、为什么接受这些限制
-
-**限制一**要消除，得让插件知道任意命令、外部编辑动了哪些文件。两条路都不通：一是让所有外部写入主动申报——`sed`、构建脚本、编辑器都不会这么做；二是全量追踪整个工作区、每次改动前做整树快照——体量极大，而工作区级的精确历史正是 Git 这类专业快照工具的职责。插件只做面向 Agent 工具的轻量回退，因此保留这条限制。
-
-**限制二**要消除，必须放弃"不变不存"与"超量不存"：每个消息边界都要记录**每个**被追踪文件（即使一点没变），大文件也会被反复完整备份。代价有两层——存储量随对话长度线性增长，而未改动文件的消息占绝大多数；以及每次备份都要完整读写文件，文件很大时会把磁盘 IO 打满（单文件上限正是为此而设）。
-
-两项限制换来的是：轻量、可预测，以及**只写它确实备份过的内容、绝不做任何猜测**。需要工作区级别的精确历史时，请使用 Git。
-
-## 相关
-
-[SECURITY.md](../../SECURITY.md) · [快照自动清理](../snapshot-auto-cleanup.zh.md)

package/docs/contract/client-contract.md

@@ -1,58 +0,0 @@
-# Client contract — rewind visibility
-
-How third-party DOM plugins learn **which transcript rows a rewind withdrew**.
-This is the only sanctioned answer to that question; anything not listed here
-is internal and may change without notice.
-
-## Stability tiers
-
-| Channel | Stability | Consumers |
-| --- | --- | --- |
-| `/rewind` command `args` `@<seq>` | ✅ stable, semver-protected | machine |
-| `outcome.sourceEventSeq` (marker log seq) | ✅ stable, semver-protected | machine |
-| `data-dsh-rewind-hidden` attribute | ✅ stable name; observational only | DOM plugins |
-| `outcome.text` | ❌ **not** stable — human copy, never parse | — |
-
-## The sanctioned machine channel
-
-`dsh-rewind-plugin/client` exports the pure, locale-independent computation
-the plugin itself uses (it never reads the DOM or host copy):
-
-```ts
-import { hiddenSeqsOf, type HiddenChat } from 'dsh-rewind-plugin/client'
-
-const chat = uiConversation.binding(sessionId).target('chat')?.getSnapshot() // the `uiConversation` "chat" view
-const hidden = hiddenSeqsOf(chat as HiddenChat) // Set<number> of anchor seqs
-```
-
-`hiddenSeqsOf` hides every internal probe row (`preview` / `__candidates`),
-every successful executed `/rewind` row, and every message inside its
-`[target, marker]` span (each rewind cuts one span; spans stay separate).
-`targetSeqOfArgs` is exported for consumers that only need the target from a
-command's `args`. Reuse these instead of re-deriving the logic (cf.
-dsh-chat-timeline#6).
-
-## DOM attribute
-
-Each withdrawn row carries `data-dsh-rewind-hidden="true"` while hidden,
-removed on un-hide. The same attribute also lands on a step/process GROUP shell
-— the view container around a turn's process rows, which is not itself a message
-— when every member it holds is withdrawn. Contract:
-
-- The **attribute name** is stable; treat the value as opaque.
-- It is **observational only** — rewind hides via `style.display`; the
-  attribute records the cause, not the mechanism. Do not write it, and do
-  not expect it on rows outside rewind's control (third-party own elements).
-
-## Explicit non-contract
-
-`outcome.text` is human-facing copy. Its wording changes freely with
-localization; parsing it is a bug. The `impact=<n>` trailer on preview text
-is machine-readable and stable but outside this contract's scope.
-
-## Maintenance rules
-
-- Any change to the meaning of `@<seq>` / `sourceEventSeq` /
-  `data-dsh-rewind-hidden` updates this document in the same PR.
-- Breaking a listed stability tier is a minor/major version bump.
-- `scripts/build.mjs` asserts the export surface on every build.

package/docs/contract/client-contract.zh.md

@@ -1,54 +0,0 @@
-# 客户端契约 — 回退可见性
-
-第三方 DOM 插件如何获知**哪些转录行被回退撤回**。这是该问题的唯一权威
-答案；未在此列出的内容均属内部实现，可随时变更，恕不另行通知。
-
-## 稳定性分级
-
-| 通道 | 稳定性 | 适用方 |
-| --- | --- | --- |
-| `/rewind` 命令 `args` 中的 `@<seq>` | ✅ 稳定，受 semver 保护 | 机器 |
-| `outcome.sourceEventSeq`（marker 日志 seq） | ✅ 稳定，受 semver 保护 | 机器 |
-| `data-dsh-rewind-hidden` 属性 | ✅ 属性名稳定；仅观测性 | DOM 插件 |
-| `outcome.text` | ❌ **不**稳定 — 人类可读文案，禁止解析 | — |
-
-## 唯一机器通道
-
-`dsh-rewind-plugin/client` 导出插件自身所用的纯函数计算，与本地化无关
-（不读取 DOM，也不解析 host 文案）：
-
-```ts
-import { hiddenSeqsOf, type HiddenChat } from 'dsh-rewind-plugin/client'
-
-const chat = uiConversation.binding(sessionId).target('chat')?.getSnapshot() // `uiConversation` 的 "chat" 视图
-const hidden = hiddenSeqsOf(chat as HiddenChat) // 被隐藏的 anchor seq 集合
-```
-
-`hiddenSeqsOf` 隐藏所有内部探针行（`preview` / `__candidates`）、所有成功
-执行的 `/rewind` 行，以及每条回退 `[target, marker]` 区间内的消息（每次
-回退切一条区间，区间互不合并）。只需从命令 `args` 取 target 时，可用同样
-导出的 `targetSeqOfArgs`。请复用这些实现，勿自行重写（参见
-dsh-chat-timeline#6）。
-
-## DOM 属性
-
-每条被撤回的行在隐藏期间带有 `data-dsh-rewind-hidden="true"`，取消隐藏时
-移除。契约如下：
-
-- **属性名**稳定；值视为不透明。
-- 仅**观测性**标记 — rewind 通过 `style.display` 隐藏，该属性记录的是
-  原因而非机制。不要写它；也不要在 rewind 控制范围之外（第三方自建元素）
-  期望它存在。
-
-## 明确非契约
-
-`outcome.text` 是面向人类用户的文案，措辞随本地化自由变更，解析它即视为
-bug。preview 文案中的 `impact=<n>` 尾注是机器可读且稳定的，但不属于本
-契约范围。
-
-## 维护规则
-
-- 任何改变 `@<seq>` / `sourceEventSeq` / `data-dsh-rewind-hidden` 语义的
-  改动，必须在同一 PR 中更新本文档。
-- 破坏已承诺的稳定性分级属于 minor/major 版本变更。
-- `scripts/build.mjs` 在每次构建时断言导出面。