dsh-rewind-plugin 0.14.0-beta.2 → 0.14.0

package/README.en.md

@@ -37,7 +37,7 @@ Check your local DSH version, then find the matching plugin version in
 **Command line**:
 
 ```sh
-dsh plugin --profile web add dsh-rewind-plugin@<version>
+dsh plugin --profile <name> add dsh-rewind-plugin@<version>
 ```
 
 **Graphical interface**: the **Plugins** page in the sidebar → **Add plugin** → enter `dsh-rewind-plugin@<version>` → install → restart DSH and refresh the browser.
@@ -91,7 +91,7 @@ auto-cleanup switch and the idle-day cutoff), or use the
 
 ```sh
 # Uninstall the plugin
-dsh plugin --profile web remove dsh-rewind-plugin
+dsh plugin --profile <name> remove dsh-rewind-plugin
 
 # To also delete local data
 rm -rf <dsh home>/rewind-snapshots
@@ -131,10 +131,10 @@ The whole design rests on two principles, simple but deliberate: **the conversat
 
 The file half follows Claude Code's checkpoint semantics — **partial tracking + before-write backup, plus a re-scan of tracked files at each message**, not a whole-tree snapshot. This trade-off saves space, and it's actually more complete:
 
-- **Before-write backup**: tracks only the write-class tools (`write`, `edit`) — backs up the original content before a write and records/tracks the files it touches; it never backs up the whole workspace, so it's lightweight.
+- **Before-write backup**: tracks only the write-class tools (`write`, `edit`) — backs up the original content before a write and records/tracks the files it touches; it never backs up the whole workspace, so it's lightweight; **a single file that is too large is not backed up**.
 - **External changes count too**: at every user-message boundary the plugin re-checks all tracked files — external changes such as a command run or a manual edit are recorded as well and restored by a later rewind. "Lightweight" but not "incomplete".
 - **Unchanged-not-recorded**: an entry is written only when something changed — at the message-boundary re-check, an unchanged file is never backed up (no record); at before-write time, when the new content matches the path's prior record, only a **link to it** (`ref`) is stored instead of a copy.
-- **Accurate restore**: backups are the sole standard, checked against the real disk — **only files that actually differ are touched**: modified files restored, newly created files deleted, deleted files recovered. Backups are stored byte for byte, so the restored result matches the backups exactly, with no "ghost impact".
+- **Accurate restore**: backups are the sole standard, checked against the real disk — **only files that actually differ are touched**. Backups are stored byte for byte, so the restored result matches the backups exactly, with no "ghost impact". There is a limit, though: [File-rewind tracking boundary](docs/compat/tracking-boundary.md).
 - **Safety and integrity**: paths are sanitized so nothing ever escapes the backup root; symlinks / hard links are skipped so one restore can't clobber another name of the same file; a per-file failure never aborts the pass; backups and the restore journal are written atomically and kept across restarts, so a half-applied restore after a crash can be continued or rolled back.
 
 > **Design highlight**: this checkpoint's light footprint comes from **recording only what was actually touched and really changed** — before-write backup makes it restorable, unchanged-not-recorded and content-as-link drop the repetition; only the files that differ are touched at restore time.

package/README.md

@@ -36,7 +36,7 @@ DeepSeek Harness 插件：**一键就地回退对话到任意更早的用户消
 **命令行**：
 
 ```sh
-dsh plugin --profile web add dsh-rewind-plugin@<版本>
+dsh plugin --profile <name> add dsh-rewind-plugin@<版本>
 ```
 
 **图形界面**：侧栏「插件」页 →「添加插件」→ 填 `dsh-rewind-plugin@<版本>` → 安装 → 重启 DSH 并刷新浏览器。
@@ -79,7 +79,7 @@ dsh plugin --profile web add dsh-rewind-plugin@<版本>
 
 ```sh
 # 卸载插件
-dsh plugin --profile web remove dsh-rewind-plugin
+dsh plugin --profile <name> remove dsh-rewind-plugin
 
 # 如需同时删除本地数据
 rm -rf <dsh home>/rewind-snapshots
@@ -118,10 +118,10 @@ rm <dsh home>/snapshot-cleanup-last-sweep.json
 
 文件部分对齐 Claude Code 的检查点语义——**局部追踪、写前备份 + 每条消息重扫已跟踪文件**，而不是整树快照。这项取舍既省空间，又更完整：
 
-- **写前备份**：只追踪写类工具（`write`、`edit`），写前**备份原内容**，并**记录、追踪**被处理的文件——从不备份整个工作区，因此轻量。
+- **写前备份**：只追踪写类工具（`write`、`edit`），写前**备份原内容**，并**记录、追踪**被处理的文件——从不备份整个工作区，因此轻量；**单个文件过大时不备份**。
 - **外部变更也追**：每条用户消息边界，插件重新检查所有已跟踪文件——命令执行、手动修改等外部变更同样被记录，回退时一并还原。这让「轻量」却不「残缺」。
 - **不变不存**：记录只在有变化时发生——消息边界重扫时无变更的**不备份**（不留记录）；写前备份时若与前一条记录一致，只存指向它的链接（`ref`）而非复制内容。
-- **还原准确**：以备份为唯一标准，对照真实磁盘，只动真正不一致的文件——被改过的还原、被新建的删除、被删除的恢复；备份逐字节存储。还原结果与备份一致，无“幽灵影响”。
+- **还原准确**：以备份为唯一标准，对照真实磁盘，只动真正不一致的文件；备份逐字节存储。还原结果与备份一致，无“幽灵影响”。但存在限制：[文件回退的追踪边界](docs/compat/tracking-boundary.zh.md)。
 - **安全与完整性**：路径经安全化处理，绝不越出备份根目录；符号/硬链接跳过，避免透过一次还原误伤同名的另一份文件；单个文件失败绝不中止整轮还原；备份与还原日志均原子写落盘（跨重启仍在），断电或崩溃后的半还原可续做或回滚。
 
 > **设计点睛**：这套检查点的「轻」，来自**只记录被工具动过、且确实变化的文件**——写前备份保证可还原，不变不存与存链接压掉重复；还原时再对照真实磁盘，只动不一致的文件。

package/SECURITY.md

@@ -175,7 +175,7 @@ transcript.
   distinct cases follow:
   1. **Sensitive / personal-information files** (e.g. a `.env` file, which may
      sit inside the workspace) the model may read or edit are backed up and
-     restorable.
+     restorable, unless the file is over the size cap.
   2. **Files outside the session workspace** the model is allowed to touch are
      likewise backed up and restored.
   In both cases the plugin introduces no authority of its own — DSH already

package/docs/compat/audit.md

@@ -58,7 +58,7 @@ legacy branch).
 - **agent-loop cancellation**: `finally` guarantees step/turn closure; the rewind force-stop path leaves no dangling frame.
 - **settings card (`0.1.7-alpha.1`)**: the card declares `configForms` as a module-level inject (the web profile always composes `ui-settings`), stages through the harness's own `SettingsFormModel` + `SettingsForm`, and registers into `plugins.bundle.config` keyed by the bundle package name; it reads that shared per-entry form's snapshot and writes through its revision-fenced `mutate`, disposing the model's subscription with the fiber. The host half declares the bundle's page policy (`configure({ auto: false }, ctx.fiber)` inside a `ctx.inject(['settings'])` child, per the dsh-settings README), opting the entry out of a client-built schema page. Pins: `verify:host` (`the bundle declares its own config page`), `tests/client-settings-card.test.ts` (staged plan, refusal, subscription release), `tests/client-lifecycle.test.ts`.
 - **client session ownership (`0.1.6-alpha.2`)**: `SessionListState.current` / `currentAddress` are gone; main-view ownership is read from the row's `retainedBy.mainView` label — what `ui-workspace` retains the open session with. Pin: `tests/client-refill.test.ts`.
-- **client pending input (`0.1.6-alpha.2`)**: `SessionSnapshot.queue` and the host `queue-mirror` are gone; pending steering rows come from the session's own `inbox` projection, and only USER-sourced `next-step` rows are retractable (the removed mapping was `source.kind === 'user' ? 'steering' : 'context'`). Pins: `tests/pending.test.ts`, `tests/client-retract.test.ts`.
+- **client pending input (`0.1.6-alpha.2`)**: `SessionSnapshot.queue` and the host `queue-mirror` are gone; pending steering rows come from the session's own `inbox` projection, and only USER-sourced `next-step` rows are retractable (the removed mapping was `source.kind === 'user' ? 'steering' : 'context'`). The rendered bubble also stays the client's own submission echo until the durable node arrives (`ChatView.pendingInputs` merges the Host occurrence into that echo by `rpcId`; `QueueDock` mirrors only `next-turn`), so the occurrence lands with NO DOM mutation — the portal refresh therefore follows the `inbox` face's own `subscribe` beside the DOM observer. Pins: `tests/pending.test.ts`, `tests/client-retract.test.ts`, `tests/client-portal-refresh.test.ts`.
 - **client settings slot (`0.1.6-alpha.2`)**: `settings.plugin.item` is gone; the configuration form registers into `plugins.bundle.config`, keyed by the bundle package name. Pin: `tests/client-contract.test.ts`.
 - **`agent/created` lifecycle guard**: the session-format reconcile runs on the alpha line's `agent/created` (fire-and-forget); pin: `verify-host` 4e dispatches it.
 - **marker vs `/compact`**: the checkpoint shape is unchanged on this line — a `user/message` replace (`surfaceOp {replace, startSeq, endSeq}` + `sourceEventSeqs`); `assistant/message` still cannot carry `sourceEventSeqs`.
@@ -79,6 +79,7 @@ legacy branch).
 - **Rewind leaves plan mode untouched**: `/plan text` is two independent actions (enter plan mode + steer the message). Rewinding the message undoes only the message — the log-only `plan/mode` state stays active, and the user leaves plan mode with `/plan off`, which still commits after a rewind (the marker creates no open turn). Pin: `verify-host` plan checks (`plan rewind leaves plan mode active`, `/plan off after rewind turns plan mode off`), `tests/hidden.test.ts` `messageTextAt`.
 - **Bundle card metadata is declared by the plugin, not by the manager (`0.1.7-alpha.1`)**: the manager still titles a bundle with `shortName(pkg.name)` and its raw `package.json` description when nothing else is declared, but it now reads plugin-owned resources first — `locale/<lang>.json` (`meta.title`/`meta.description`) through the package exports map, and an `icon` file relative to the manifest. This plugin declares both, so its card shows an icon and copy that follows the active language; only the fallback description remains mixed-language. Pin: `tests/package-layout.test.ts` (icon path/media/size and both dictionaries).
 - **Synchronous Session history reads are deprecated** on this line (`snapshotEvents` / `eventAt` / `ownEvents`): existing calls may remain, new calls are prohibited. The plugin keeps its existing reads (turn anchor + candidate listing); the migration path is a `ctx.sessionProjections` projection unit or the async paged history read this line has not shipped yet — not a plugin-side index.
+- **A peer version range is never enforced at runtime**, and a physical copy nearer than the host still wins (upstream profile-resolution lookup order: "a peer version range is not an additional resolver filter"; "a nearer physical candidate wins"). So the `@deepseek-ai/schemastery` peer floor *is* the availability guarantee for `.volatile()` (#40): a plugin directory or linked checkout left holding an older copy (e.g. the pre-3.18.2 devDependency) shadows the host's 3.18.4 and fails the top-level `Config` evaluation before the plugin loads. Floor pinned at `^3.18.4`.
 
 ## Upstream (harness) issues and the plugin's no-compensation stance
 

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 | 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.
+
+## 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 | 文件扩充 | `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。
+
+## 背景
+
+本文最初为 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)

package/lib/client.js

@@ -249,9 +249,9 @@ var CLASS = {
   guardHint: "dsh-rewind-guard-hint"
 };
 var REWIND_ICON_SVG = [
-  '<svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">',
-  '  <path d="M6.5 2.5 2.5 6.5l4 4" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>',
-  '  <path d="M2.5 6.5h7a4 4 0 0 1 4 4v1.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/>',
+  '<svg width="15" height="15" viewBox="0 0 16 16" fill="none" aria-hidden="true">',
+  '  <path d="M6.5 2.5 2.5 6.5l4 4" stroke="currentColor" stroke-width="1.25" stroke-linecap="round" stroke-linejoin="round"/>',
+  '  <path d="M2.5 6.5h7a4 4 0 0 1 4 4v1.5" stroke="currentColor" stroke-width="1.25" stroke-linecap="round"/>',
   "</svg>"
 ].join("");
 var STYLE = `
@@ -263,7 +263,7 @@ var STYLE = `
   height: 28px;
   padding: 6px;
   border: none;
-  border-radius: 28px;
+  border-radius: var(--dsw-radius-sm, 8px);
   background: transparent;
   color: var(--dsw-alias-label-tertiary);
   cursor: pointer;
@@ -1035,8 +1035,9 @@ function collectDurableTargets(snapshot, chat, hiddenSeqs) {
   return collectTargets(chat, hiddenSeqs);
 }
 function inboxOf(session) {
-  return session.projections.faceOf("inbox").getSnapshot();
+  return session.projections.faceOf(INBOX_PROJECTION).getSnapshot();
 }
+var INBOX_PROJECTION = "inbox";
 function bubbleTextOf(row) {
   const clone = row.cloneNode(true);
   clone.lastElementChild?.remove();
@@ -1088,9 +1089,12 @@ function RewindPortals({ sessionId, sessionOf, chatOf, isMainViewSession, watchC
   (0, import_react.useLayoutEffect)(() => {
     let active = true;
     let queued = false;
+    let unsubscribeInbox;
+    let inboxOwner;
     const refresh = () => {
       if (!active) return;
       const session = sessionOf(sessionId);
+      syncInboxSubscription(session);
       if (session === void 0) {
         setTargets([]);
         return;
@@ -1116,12 +1120,27 @@ function RewindPortals({ sessionId, sessionOf, chatOf, isMainViewSession, watchC
         refresh();
       });
     };
+    const syncInboxSubscription = (session) => {
+      if (session === inboxOwner) return;
+      unsubscribeInbox?.();
+      unsubscribeInbox = void 0;
+      inboxOwner = session;
+      if (session === void 0) return;
+      try {
+        unsubscribeInbox = session.projections.faceOf(INBOX_PROJECTION).subscribe(queueRefresh);
+      } catch (error) {
+        rewindLog.warn("portals", "inbox projection subscribe failed", error);
+      }
+    };
     refresh();
     const observer = new MutationObserver(queueRefresh);
     observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ["style"] });
     return () => {
       active = false;
       observer.disconnect();
+      unsubscribeInbox?.();
+      unsubscribeInbox = void 0;
+      inboxOwner = void 0;
     };
   }, [sessionId, sessionOf]);
   return targets.map((target) => (0, import_react_dom.createPortal)(
@@ -1252,9 +1271,9 @@ function createRewindBridge(deps) {
 }
 
 // src/client/build-info.ts
-var PLUGIN_VERSION = true ? "0.14.0-beta.2" : "dev";
+var PLUGIN_VERSION = true ? "0.14.0" : "dev";
 var PLUGIN_PACKAGE = "dsh-rewind-plugin";
-var BUILD_HASH = true ? "1afddb1d" : "dev";
+var BUILD_HASH = true ? "09b74c90" : "dev";
 
 // src/client/locales.ts
 var zh = {

package/lib/index.js

@@ -20,6 +20,9 @@ var en = {
   "plan.restore": "restore {path}",
   "plan.delete": "delete {path}",
   "plan.noChanges": "No restorable changes after the target.",
+  "plan.skip": "  not restored: {path} ({reason})",
+  "skipReason.oversized": "over the {limit} backup limit, so the recorded state predates untracked edits",
+  "uncovered.header": "{count} tracked file(s) exceed the {limit} backup limit and are not covered:",
   "error.invalidTarget": 'Cannot parse target "{raw}" (expected <index> or @<seq>)',
   "failures.suffix": "; {count} file(s) failed to restore: {list}",
   "failures.item": "{path} ({message})",
@@ -35,7 +38,8 @@ var en = {
   "success": "Withdrawn seq {targetSeq} and everything after it (conversation returned to earlier){restore}.",
   "noUserMessages": "This session has no rewindable user messages yet.",
   "chooseMode": "Rewind to {target}. Choose a mode:\n  /rewind {target} chat  conversation only\n  /rewind {target} both  conversation + file restore",
-  "command.description": "Rewind the conversation back to an earlier user message (optionally restoring files)",
+  "command.description": "Rewind the conversation and/or code to a previous point",
+  "command.undoDescription": "Alias of /rewind",
   "cleanup.description": "Manage automatic cleanup of session snapshot backups",
   "cleanup.inputHint": "on | off | max-age <days> | run [--apply] [--current]",
   "cleanup.status": "Auto-cleanup: {state}. Max age: {days} day(s).",
@@ -69,6 +73,9 @@ var zh = {
   "plan.restore": "\u8FD8\u539F {path}",
   "plan.delete": "\u5220\u9664 {path}",
   "plan.noChanges": "\u76EE\u6807\u4E4B\u540E\u6CA1\u6709\u9700\u8981\u8FD8\u539F\u7684\u53D8\u66F4\u3002",
+  "plan.skip": "  \u672A\u8FD8\u539F\uFF1A{path}\uFF08{reason}\uFF09",
+  "skipReason.oversized": "\u5DF2\u8D85\u8FC7 {limit} \u7684\u5907\u4EFD\u4E0A\u9650\uFF0C\u8BB0\u5F55\u7684\u72B6\u6001\u65E9\u4E8E\u672A\u88AB\u8DDF\u8E2A\u7684\u4FEE\u6539",
+  "uncovered.header": "{count} \u4E2A\u5DF2\u8DDF\u8E2A\u6587\u4EF6\u8D85\u8FC7 {limit} \u7684\u5907\u4EFD\u4E0A\u9650\uFF0C\u672A\u7EB3\u5165\u8BB0\u5F55\uFF1A",
   "error.invalidTarget": '\u65E0\u6CD5\u89E3\u6790\u76EE\u6807 "{raw}"\uFF08\u5E94\u4E3A <\u5E8F\u53F7> \u6216 @<seq>\uFF09',
   "failures.suffix": "\uFF1B{count} \u4E2A\u6587\u4EF6\u8FD8\u539F\u5931\u8D25\uFF1A{list}",
   "failures.item": "{path}\uFF08{message}\uFF09",
@@ -84,7 +91,8 @@ var zh = {
   "success": "\u5DF2\u64A4\u56DE seq {targetSeq} \u53CA\u4E4B\u540E\u5185\u5BB9\uFF08\u5BF9\u8BDD\u5DF2\u56DE\u5230\u6B64\u524D\uFF09{restore}\u3002",
   "noUserMessages": "\u5F53\u524D\u4F1A\u8BDD\u8FD8\u6CA1\u6709\u53EF\u56DE\u9000\u7684\u7528\u6237\u6D88\u606F\u3002",
   "chooseMode": "\u5C06\u56DE\u9000\u5230 {target}\u3002\u9009\u62E9\u6A21\u5F0F\uFF1A\n  /rewind {target} chat  \u4EC5\u56DE\u9000\u5BF9\u8BDD\n  /rewind {target} both  \u56DE\u9000\u5BF9\u8BDD\u5E76\u8FD8\u539F\u6587\u4EF6",
-  "command.description": "\u5728\u540C\u7A97\u53E3\u5185\u5C06\u5BF9\u8BDD\u56DE\u9000\u5230\u66F4\u65E9\u7684\u7528\u6237\u6D88\u606F\uFF08\u53EF\u540C\u65F6\u8FD8\u539F\u6587\u4EF6\uFF09",
+  "command.description": "\u56DE\u9000\u5BF9\u8BDD\u548C/\u6216\u4EE3\u7801\u5230\u4E4B\u524D\u7684\u67D0\u6761\u6D88\u606F",
+  "command.undoDescription": "/rewind \u7684\u522B\u540D",
   "cleanup.description": "\u7BA1\u7406\u4F1A\u8BDD\u5FEB\u7167\u5907\u4EFD\u7684\u81EA\u52A8\u6E05\u7406",
   "cleanup.inputHint": "on | off | max-age <\u5929\u6570> | run [--apply] [--current]",
   "cleanup.status": "\u81EA\u52A8\u6E05\u7406\uFF1A{state}\u3002\u6700\u5927\u4FDD\u7559\u5929\u6570\uFF1A{days} \u5929\u3002",
@@ -237,6 +245,14 @@ var PENDING_MAX_AGE_MS = 24 * 60 * 60 * 1e3;
 var COMPARE_CHUNK_BYTES = 64 * 1024;
 var REPLACEMENT_CHAR = "\uFFFD";
 var SNAPSHOT_ROOT_ENV = "DSH_REWIND_SNAPSHOT_DIR";
+var MAX_FILE_BYTES_ENV = "DSH_REWIND_MAX_FILE_BYTES";
+var DEFAULT_MAX_FILE_BYTES = 8 * 1024 * 1024;
+function maxFileBytesFromEnv() {
+  const raw = process.env[MAX_FILE_BYTES_ENV]?.trim();
+  if (raw === void 0 || raw === "") return void 0;
+  const parsed = Number(raw);
+  return Number.isInteger(parsed) ? parsed : void 0;
+}
 var MAX_ANCHOR_GROUPS = 100;
 var CURRENT_STORE_VERSION = 2;
 var UnknownStoreVersionError = class extends Error {
@@ -323,6 +339,14 @@ var defaultProbe = {
       return { kind: "failed", message: error instanceof Error ? error.message : String(error) };
     }
   },
+  async size(path) {
+    try {
+      const st = await stat(path);
+      return st.isFile() ? st.size : void 0;
+    } catch {
+      return void 0;
+    }
+  },
   isLink: isLinkPath
 };
 function safeFileId(callId) {
@@ -652,6 +676,11 @@ var SnapshotStore = class _SnapshotStore {
   lastEntryTime = 0;
   /** Store options; `dedup` toggles in-place content dedup (default on). */
   dedup;
+  /**
+   * Per-file backup cap in bytes; `<= 0` means no cap. Capture paths consult it
+   * and the restore planner refuses a pre-cap record over an over-cap file.
+   */
+  maxFileBytes;
   /** Resolved checkpoint store root (absolute); see the constructor's fallback. */
   root;
   /**
@@ -677,12 +706,25 @@ var SnapshotStore = class _SnapshotStore {
   formatVersion = null;
   constructor(root, opts) {
     this.dedup = opts?.dedup ?? true;
+    this.maxFileBytes = opts?.maxFileBytes ?? maxFileBytesFromEnv() ?? DEFAULT_MAX_FILE_BYTES;
     this.root = root ?? process.env[SNAPSHOT_ROOT_ENV] ?? join(resolveDshHome(opts?.dshHome), SNAPSHOT_DIR_NAME);
   }
   /** Absolute path of one session's snapshot directory (id sanitized). */
   sessionDir(sessionId) {
     return join(this.root, safeSessionId(sessionId));
   }
+  /**
+   * True when `size` bytes is over the per-file cap, so it must not be backed
+   * up. `undefined` (a backend that cannot report a size) answers false: the
+   * guard fails toward STORING, never toward calling a file too big on a guess.
+   */
+  isOverFileCap(size) {
+    return this.maxFileBytes > 0 && size !== void 0 && size > this.maxFileBytes;
+  }
+  /** The cap in force, for reporting (0 = unlimited). */
+  get fileCapBytes() {
+    return this.maxFileBytes;
+  }
   /** Absolute path of one anchor group directory. */
   anchorDir(sessionId, anchorSeq) {
     return join(this.sessionDir(sessionId), String(anchorSeq));
@@ -1035,6 +1077,10 @@ var SnapshotStore = class _SnapshotStore {
           skipped.push(entry.path);
           continue;
         }
+        if (probe.size !== void 0 && this.isOverFileCap(await probe.size(entry.path))) {
+          skipped.push(entry.path);
+          continue;
+        }
         if (source !== null && source.kind === "lossyText") {
           const same2 = await probe.matches(source, entry.path);
           if (same2 !== true) skipped.push(entry.path);
@@ -1888,6 +1934,21 @@ var SnapshotStore = class _SnapshotStore {
     }
     return paths;
   }
+  /**
+   * The session's recorded paths whose current size is over the cap, so no
+   * backup of that state exists. One `stat` per recorded path; a path first seen
+   * over the cap was never recorded and is therefore not listed.
+   */
+  async uncoveredPaths(sessionId, probe = defaultProbe) {
+    const sizeOf = probe.size?.bind(probe);
+    if (this.maxFileBytes <= 0 || sizeOf === void 0) return [];
+    const uncovered = [];
+    for (const path of await this.trackedPaths(sessionId)) {
+      const size = await sizeOf(path);
+      if (this.isOverFileCap(size)) uncovered.push({ path, ...size !== void 0 ? { size } : {} });
+    }
+    return uncovered;
+  }
   /**
    * Summarize a session's on-disk footprint for a clear dry-run: anchor-group
    * count, committed checkpoint-entry count (one per `.json` in an anchor
@@ -2105,6 +2166,7 @@ async function reconcileTracked(store, sessionId, anchorSeq, tracked, probe = de
   for (const path of tracked) {
     try {
       if (await probe.isLink(path)) continue;
+      if (store.isOverFileCap(await probe.size?.(path))) continue;
       const last = await store.lastKnownContent(sessionId, path);
       if (last !== void 0 && last !== null && last.kind !== "lossyText") {
         const same = await probe.matches(last, path);
@@ -2352,6 +2414,7 @@ async function captureBefore(fs, store, exec, pending) {
   });
   if (session === void 0) return;
   if (info !== void 0 && info.type !== "file") return;
+  if (info !== void 0 && store.isOverFileCap(info.size)) return;
   const key = `${exec.agent?.id ?? "anon"}:${exec.callId}`;
   if (info === void 0) {
     pending.set(key, { path: target.displayPath, backup: null });
@@ -2415,7 +2478,12 @@ function buildMarker() {
 function describeTarget(target) {
   return target.kind === "seq" ? t("describeTarget.seq", { seq: target.seq }) : t("describeTarget.index", { index: target.index });
 }
-function formatPlan(plan, files) {
+function formatBytes(bytes) {
+  if (bytes >= 1024 * 1024) return `${Math.round(bytes / (1024 * 1024))} MiB`;
+  if (bytes >= 1024) return `${Math.round(bytes / 1024)} KiB`;
+  return `${bytes} B`;
+}
+function formatPlan(plan, files, uncovered = [], maxFileBytes = 0) {
   const lines = [
     t("plan.rewinding", { targetSeq: plan.targetSeq, count: plan.shadowedSeqs.length })
   ];
@@ -2427,6 +2495,11 @@ function formatPlan(plan, files) {
   } else {
     lines.push(t("plan.noChanges"));
   }
+  if (uncovered.length > 0) {
+    lines.push(t("uncovered.header", { count: uncovered.length, limit: formatBytes(maxFileBytes) }));
+    for (const file of uncovered.slice(0, 5)) lines.push(`  ${file.path}`);
+    if (uncovered.length > 5) lines.push("  \u2026");
+  }
   lines.push(`impact=${files.length}`);
   for (const file of files) {
     lines.push(`${file.action}:${file.path}`);
@@ -2447,6 +2520,11 @@ function renderFailures(failed) {
     list: failed.map((f) => t("failures.item", { path: f.path, message: f.message })).join("\u3001")
   });
 }
+function renderSkipped(outcome, uncovered, maxFileBytes) {
+  const capped = new Set(uncovered.map((item) => item.path));
+  const limit = formatBytes(maxFileBytes);
+  return outcome.skipped.filter((path) => capped.has(path)).map((path) => t("plan.skip", { path, reason: t("skipReason.oversized", { limit }) })).join("\n");
+}
 async function resolveObservationTarget(fs, path) {
   try {
     return await fs.resolve(path);
@@ -2549,7 +2627,12 @@ async function executeRewind(ctx, store, fs, invocation, rawTarget, mode, inflig
         const parts = [];
         if (outcome.restored.length > 0) parts.push(t("restore.count", { count: outcome.restored.length }));
         if (outcome.deleted.length > 0) parts.push(t("delete.count", { count: outcome.deleted.length }));
-        if (outcome.skipped.length > 0) parts.push(t("skip.count", { count: outcome.skipped.length }));
+        if (outcome.skipped.length > 0) {
+          parts.push(t("skip.count", { count: outcome.skipped.length }));
+          const capped = await store.uncoveredPaths(agent.session.id).catch(() => []);
+          const skippedLines = renderSkipped(outcome, capped, store.fileCapBytes);
+          if (skippedLines !== "") parts.push(skippedLines);
+        }
         restore = parts.length > 0 ? `\uFF1B${parts.join("\u3001")}` : t("noRestorable");
         restore += renderFailures(outcome.failed);
       }
@@ -2602,7 +2685,8 @@ async function handleRewind(ctx, store, fs, invocation, inflight) {
     if (impacts === void 0) {
       return { kind: "error", text: t("storeUnsupported", { version: await store.readStoreVersion(session.id) ?? 0 }) };
     }
-    return { kind: "success", text: formatPlan(plan, impacts) };
+    const uncovered = await store.uncoveredPaths(session.id).catch(() => []);
+    return { kind: "success", text: formatPlan(plan, impacts, uncovered, store.fileCapBytes) };
   }
   if (parts[0] === "__candidates") {
     const candidates = listRewindCandidates(session.snapshotEvents(), session.surface.nodes);
@@ -2805,7 +2889,7 @@ function apply(ctx, config) {
     });
     yield ctx.commands.register({
       name: "undo",
-      description: t("command.description"),
+      description: t("command.undoDescription"),
       handler: rewindHandler
     });
     yield ctx.commands.register({

package/lib/types/client/portals.d.ts

@@ -284,6 +284,10 @@ interface RewindPortalsProps extends RewindBridgeDeps {
  * (one pass per mutation batch via queueMicrotask) and diffed (setState is
  * skipped when the target set is unchanged), so the plugin never runs a
  * synchronous full-transcript scan inside a commit microtask.
+ *
+ * The scan is driven by both channels its targets are made of: the DOM (rows and
+ * their actions containers) and the session's `inbox` projection (the pending
+ * occurrences — see `syncInboxSubscription`).
  */
 export declare function RewindPortals({ sessionId, sessionOf, chatOf, isMainViewSession, watchChat, t, subscribeLocale, setComposerText }: RewindPortalsProps): ReactNode;
 /** The current composer draft: the contenteditable `textContent`.

package/lib/types/client/styles.d.ts

@@ -20,7 +20,15 @@ export declare const CLASS: {
     readonly popoverGhost: 'dsh-rewind-popover-ghost';
     readonly guardHint: 'dsh-rewind-guard-hint';
 };
-/** The ↶ glyph, drawn inline so the bundle stays dependency-free. */
+/**
+ * The ↶ glyph, drawn inline so the bundle stays dependency-free.
+ *
+ * Size follows the 0.1.7 product-icon set (15px, as the neighbouring copy/branch
+ * actions in `MessageIconActions`). Stroke is 1.25 rather than upstream's
+ * `Regular` 1: ↶ is a single open stroke next to a dense outline-plus-fill copy
+ * glyph, so at 1 it reads thinned out. Rounded caps/joins stay — upstream keeps
+ * them on curved artwork.
+ */
 export declare const REWIND_ICON_SVG: string;
 /** One injected stylesheet (scoped under `.dsh-rewind-*`). */
-export declare const STYLE = "\n.dsh-rewind-btn {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  width: 28px;\n  height: 28px;\n  padding: 6px;\n  border: none;\n  border-radius: 28px;\n  background: transparent;\n  color: var(--dsw-alias-label-tertiary);\n  cursor: pointer;\n}\n.dsh-rewind-btn:hover {\n  background: var(--dsw-alias-interactive-bg-hover);\n  color: var(--dsw-alias-label-secondary);\n}\n\n.dsh-rewind-popover {\n  position: fixed;\n  z-index: 1000;\n  width: 288px;\n  padding: 12px;\n  border: 1px solid var(--dsw-alias-border-l2);\n  border-radius: 12px;\n  background: var(--dsw-specific-menu, var(--dsw-alias-bg-layer-3));\n  box-shadow: var(--dsw-shadow-lv3);\n  font-size: 14px;\n  line-height: 20px;\n  color: var(--dsw-alias-label-primary);\n}\n.dsh-rewind-popover-title {\n  font-size: 14px;\n  font-weight: 600;\n  line-height: 20px;\n}\n.dsh-rewind-popover-target {\n  margin: 4px 0 10px;\n  font-size: 12px;\n  line-height: 16px;\n  color: var(--dsw-alias-label-tertiary);\n  word-break: break-all;\n}\n.dsh-rewind-popover-option {\n  display: flex;\n  flex-direction: column;\n  gap: 2px;\n  width: 100%;\n  margin: 0 0 6px;\n  padding: 8px 10px;\n  border: 1px solid transparent;\n  border-radius: 8px;\n  background: transparent;\n  color: inherit;\n  font: inherit;\n  text-align: left;\n  cursor: pointer;\n}\n.dsh-rewind-popover-option:hover {\n  background: var(--dsw-alias-interactive-bg-hover);\n}\n/* Arrow navigation moves real focus, so the focused row carries the pointer's\n   fill and the browser ring is suppressed: in dark mode the UA two-tone ring\n   draws its dark half against the filled row and reads as a residue edge (the\n   harness Menu suppresses it the same way). */\n.dsh-rewind-popover-option:focus-visible:not(:disabled) {\n  background: var(--dsw-alias-interactive-bg-hover);\n  outline: none;\n}\n.dsh-rewind-popover-option:disabled {\n  opacity: 0.5;\n  cursor: default;\n}\n.dsh-rewind-popover-option-label {\n  font-weight: 500;\n}\n.dsh-rewind-popover-option-hint {\n  font-size: 12px;\n  line-height: 16px;\n  color: var(--dsw-alias-label-tertiary);\n}\n.dsh-rewind-popover-impact {\n  margin: 4px 0 10px;\n  padding: 8px 10px;\n  border-radius: 8px;\n  background: var(--dsw-alias-interactive-bg-hover);\n  font-size: 12px;\n  line-height: 16px;\n  color: var(--dsw-alias-label-secondary);\n  white-space: pre-wrap;\n  max-height: 160px;\n  overflow: auto;\n}\n.dsh-rewind-popover-actions {\n  display: flex;\n  justify-content: flex-end;\n  gap: 8px;\n}\n.dsh-rewind-popover-primary,\n.dsh-rewind-popover-ghost {\n  padding: 5px 12px;\n  border: none;\n  border-radius: 8px;\n  font: inherit;\n  font-size: 13px;\n  line-height: 18px;\n  cursor: pointer;\n}\n.dsh-rewind-popover-primary {\n  background: var(--dsw-alias-button-primary-fill);\n  color: var(--dsw-alias-label-primary-foreground);\n}\n.dsh-rewind-popover-primary:hover:not(:disabled) {\n  background: var(--dsw-alias-button-primary-hover);\n}\n.dsh-rewind-popover-primary:disabled {\n  opacity: 0.5;\n  cursor: default;\n}\n.dsh-rewind-popover-ghost {\n  background: transparent;\n  color: var(--dsw-alias-label-secondary);\n}\n.dsh-rewind-popover-ghost:hover {\n  background: var(--dsw-alias-interactive-bg-hover);\n}\n\n.dsh-rewind-guard-hint {\n  position: fixed;\n  z-index: 1000;\n  max-width: min(440px, calc(100vw - 24px));\n  padding: 8px 12px;\n  border: 1px solid var(--dsw-alias-border-l2);\n  border-radius: 10px;\n  background: var(--dsw-specific-menu, var(--dsw-alias-bg-layer-3));\n  box-shadow: var(--dsw-shadow-lv3);\n  font-size: 13px;\n  line-height: 18px;\n  color: var(--dsw-alias-label-primary);\n  pointer-events: none;\n}\n\n/* ---- Snapshot-cleanup configuration form ---- */\n/* The Plugins page draws the bundle's title, icon, crumb, description, and the\n   shared settings form frame (labels, save, read-only and failure lines); this\n   styles only the one control the card owns: the auto-cleanup toggle row. */\n.dsh-rewind-cleanup-permission {\n  display: grid;\n  gap: 6px;\n  padding: 12px 0;\n}\n.dsh-rewind-cleanup-toggle-row {\n  display: flex;\n  align-items: flex-start;\n  justify-content: space-between;\n  gap: 16px;\n  font-size: 13px;\n  line-height: 1.5;\n  color: var(--dsw-alias-label-primary);\n}\n.dsh-rewind-cleanup-toggle-label {\n  flex: 1;\n  min-width: 0;\n}\n.dsh-rewind-cleanup-hint {\n  margin: 0;\n  font-size: 12px;\n  line-height: 1.5;\n  color: var(--dsw-alias-label-tertiary);\n}\n";
+export declare const STYLE = "\n.dsh-rewind-btn {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  width: 28px;\n  height: 28px;\n  padding: 6px;\n  border: none;\n  border-radius: var(--dsw-radius-sm, 8px);\n  background: transparent;\n  color: var(--dsw-alias-label-tertiary);\n  cursor: pointer;\n}\n.dsh-rewind-btn:hover {\n  background: var(--dsw-alias-interactive-bg-hover);\n  color: var(--dsw-alias-label-secondary);\n}\n\n.dsh-rewind-popover {\n  position: fixed;\n  z-index: 1000;\n  width: 288px;\n  padding: 12px;\n  border: 1px solid var(--dsw-alias-border-l2);\n  border-radius: 12px;\n  background: var(--dsw-specific-menu, var(--dsw-alias-bg-layer-3));\n  box-shadow: var(--dsw-shadow-lv3);\n  font-size: 14px;\n  line-height: 20px;\n  color: var(--dsw-alias-label-primary);\n}\n.dsh-rewind-popover-title {\n  font-size: 14px;\n  font-weight: 600;\n  line-height: 20px;\n}\n.dsh-rewind-popover-target {\n  margin: 4px 0 10px;\n  font-size: 12px;\n  line-height: 16px;\n  color: var(--dsw-alias-label-tertiary);\n  word-break: break-all;\n}\n.dsh-rewind-popover-option {\n  display: flex;\n  flex-direction: column;\n  gap: 2px;\n  width: 100%;\n  margin: 0 0 6px;\n  padding: 8px 10px;\n  border: 1px solid transparent;\n  border-radius: 8px;\n  background: transparent;\n  color: inherit;\n  font: inherit;\n  text-align: left;\n  cursor: pointer;\n}\n.dsh-rewind-popover-option:hover {\n  background: var(--dsw-alias-interactive-bg-hover);\n}\n/* Arrow navigation moves real focus, so the focused row carries the pointer's\n   fill and the browser ring is suppressed: in dark mode the UA two-tone ring\n   draws its dark half against the filled row and reads as a residue edge (the\n   harness Menu suppresses it the same way). */\n.dsh-rewind-popover-option:focus-visible:not(:disabled) {\n  background: var(--dsw-alias-interactive-bg-hover);\n  outline: none;\n}\n.dsh-rewind-popover-option:disabled {\n  opacity: 0.5;\n  cursor: default;\n}\n.dsh-rewind-popover-option-label {\n  font-weight: 500;\n}\n.dsh-rewind-popover-option-hint {\n  font-size: 12px;\n  line-height: 16px;\n  color: var(--dsw-alias-label-tertiary);\n}\n.dsh-rewind-popover-impact {\n  margin: 4px 0 10px;\n  padding: 8px 10px;\n  border-radius: 8px;\n  background: var(--dsw-alias-interactive-bg-hover);\n  font-size: 12px;\n  line-height: 16px;\n  color: var(--dsw-alias-label-secondary);\n  white-space: pre-wrap;\n  max-height: 160px;\n  overflow: auto;\n}\n.dsh-rewind-popover-actions {\n  display: flex;\n  justify-content: flex-end;\n  gap: 8px;\n}\n.dsh-rewind-popover-primary,\n.dsh-rewind-popover-ghost {\n  padding: 5px 12px;\n  border: none;\n  border-radius: 8px;\n  font: inherit;\n  font-size: 13px;\n  line-height: 18px;\n  cursor: pointer;\n}\n.dsh-rewind-popover-primary {\n  background: var(--dsw-alias-button-primary-fill);\n  color: var(--dsw-alias-label-primary-foreground);\n}\n.dsh-rewind-popover-primary:hover:not(:disabled) {\n  background: var(--dsw-alias-button-primary-hover);\n}\n.dsh-rewind-popover-primary:disabled {\n  opacity: 0.5;\n  cursor: default;\n}\n.dsh-rewind-popover-ghost {\n  background: transparent;\n  color: var(--dsw-alias-label-secondary);\n}\n.dsh-rewind-popover-ghost:hover {\n  background: var(--dsw-alias-interactive-bg-hover);\n}\n\n.dsh-rewind-guard-hint {\n  position: fixed;\n  z-index: 1000;\n  max-width: min(440px, calc(100vw - 24px));\n  padding: 8px 12px;\n  border: 1px solid var(--dsw-alias-border-l2);\n  border-radius: 10px;\n  background: var(--dsw-specific-menu, var(--dsw-alias-bg-layer-3));\n  box-shadow: var(--dsw-shadow-lv3);\n  font-size: 13px;\n  line-height: 18px;\n  color: var(--dsw-alias-label-primary);\n  pointer-events: none;\n}\n\n/* ---- Snapshot-cleanup configuration form ---- */\n/* The Plugins page draws the bundle's title, icon, crumb, description, and the\n   shared settings form frame (labels, save, read-only and failure lines); this\n   styles only the one control the card owns: the auto-cleanup toggle row. */\n.dsh-rewind-cleanup-permission {\n  display: grid;\n  gap: 6px;\n  padding: 12px 0;\n}\n.dsh-rewind-cleanup-toggle-row {\n  display: flex;\n  align-items: flex-start;\n  justify-content: space-between;\n  gap: 16px;\n  font-size: 13px;\n  line-height: 1.5;\n  color: var(--dsw-alias-label-primary);\n}\n.dsh-rewind-cleanup-toggle-label {\n  flex: 1;\n  min-width: 0;\n}\n.dsh-rewind-cleanup-hint {\n  margin: 0;\n  font-size: 12px;\n  line-height: 1.5;\n  color: var(--dsw-alias-label-tertiary);\n}\n";

package/lib/types/locales.d.ts

@@ -56,6 +56,9 @@ export declare const en: {
     'plan.restore': string;
     'plan.delete': string;
     'plan.noChanges': string;
+    'plan.skip': string;
+    'skipReason.oversized': string;
+    'uncovered.header': string;
     'error.invalidTarget': string;
     'failures.suffix': string;
     'failures.item': string;
@@ -72,6 +75,7 @@ export declare const en: {
     noUserMessages: string;
     chooseMode: string;
     'command.description': string;
+    'command.undoDescription': string;
     'cleanup.description': string;
     'cleanup.inputHint': string;
     'cleanup.status': string;

package/lib/types/snapshot.d.ts

@@ -67,6 +67,15 @@
  */
 /** Environment variable overriding the store root (tests, exotic homes). */
 export declare const SNAPSHOT_ROOT_ENV = "DSH_REWIND_SNAPSHOT_DIR";
+/** Env override for the per-file backup cap (`0` = unlimited); tests set it too. */
+export declare const MAX_FILE_BYTES_ENV = "DSH_REWIND_MAX_FILE_BYTES";
+/**
+ * A regular file larger than this is NOT backed up. This plugin is a
+ * lightweight, conversation-scoped undo, not a backup system: copying a very
+ * large file on every edit is what grows the store without bound and saturates
+ * IO (issue #39). The cap is a declared limitation, not a delta scheme.
+ */
+export declare const DEFAULT_MAX_FILE_BYTES: number;
 /** Number of newest anchor groups (user messages) kept per session. */
 export declare const MAX_ANCHOR_GROUPS = 100;
 /**
@@ -208,6 +217,12 @@ export interface FileImpact {
     /** `restore` = write the before content back; `delete` = remove the file. */
     readonly action: 'restore' | 'delete';
 }
+/** A recorded path whose current on-disk size is over the backup cap. */
+export interface UncoveredPath {
+    readonly path: string;
+    /** Byte size observed on disk, when the probe could read one. */
+    readonly size?: number;
+}
 /** Outcome of one restore pass. */
 export interface RestoreOutcome {
     readonly restored: readonly string[];
@@ -352,6 +367,13 @@ export interface DiskProbe {
      * rescue area) without loading it into memory.
      */
     copy(path: string, dest: string): Promise<CopyOutcome>;
+    /**
+     * Byte size of the regular file at `path`, or `undefined` when absent or
+     * unreadable. Consulted before any content comparison so an over-cap file is
+     * skipped without being read. Optional; a missing accessor reads as "size
+     * unknown", which never counts as "too big".
+     */
+    size?(path: string): Promise<number | undefined>;
     /** True when the path is a symlink or a hard link (never planned/restored). */
     isLink(path: string): Promise<boolean>;
 }
@@ -455,6 +477,11 @@ export declare class SnapshotStore {
     private lastEntryTime;
     /** Store options; `dedup` toggles in-place content dedup (default on). */
     private readonly dedup;
+    /**
+     * Per-file backup cap in bytes; `<= 0` means no cap. Capture paths consult it
+     * and the restore planner refuses a pre-cap record over an over-cap file.
+     */
+    private readonly maxFileBytes;
     /** Resolved checkpoint store root (absolute); see the constructor's fallback. */
     readonly root: string;
     /**
@@ -481,9 +508,19 @@ export declare class SnapshotStore {
     constructor(root?: string, opts?: {
         readonly dedup?: boolean;
         readonly dshHome?: string;
+        /** Per-file backup cap in bytes; `<= 0` disables it. */
+        readonly maxFileBytes?: number;
     });
     /** Absolute path of one session's snapshot directory (id sanitized). */
     sessionDir(sessionId: string): string;
+    /**
+     * True when `size` bytes is over the per-file cap, so it must not be backed
+     * up. `undefined` (a backend that cannot report a size) answers false: the
+     * guard fails toward STORING, never toward calling a file too big on a guess.
+     */
+    isOverFileCap(size: number | undefined): boolean;
+    /** The cap in force, for reporting (0 = unlimited). */
+    get fileCapBytes(): number;
     /** Absolute path of one anchor group directory. */
     anchorDir(sessionId: string, anchorSeq: number): string;
     /** Absolute file ref (relative to the session dir) of an entry. */
@@ -868,6 +905,12 @@ export declare class SnapshotStore {
      * entries so no extra persistence is needed.
      */
     trackedPaths(sessionId: string): Promise<Set<string>>;
+    /**
+     * The session's recorded paths whose current size is over the cap, so no
+     * backup of that state exists. One `stat` per recorded path; a path first seen
+     * over the cap was never recorded and is therefore not listed.
+     */
+    uncoveredPaths(sessionId: string, probe?: DiskProbe): Promise<UncoveredPath[]>;
     /**
      * Summarize a session's on-disk footprint for a clear dry-run: anchor-group
      * count, committed checkpoint-entry count (one per `.json` in an anchor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-rewind-plugin",
-  "version": "0.14.0-beta.2",
+  "version": "0.14.0",
   "description": "In-window conversation rewind with workspace file restore · 同窗口内对话回退并可还原工作区文件",
   "icon": "./assets/icon.svg",
   "keywords": [
@@ -92,7 +92,7 @@
     "@deepseek-ai/dsh-session": "^0.1.7-rc.2",
     "@deepseek-ai/dsh-settings": "^0.1.7-rc.2",
     "@deepseek-ai/dsh-tools": "^0.1.7-rc.2",
-    "@deepseek-ai/schemastery": "^3.18.1"
+    "@deepseek-ai/schemastery": "^3.18.4"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/cordis": {
@@ -182,7 +182,7 @@
     "@deepseek-ai/dsh-tools": "0.1.7-rc.2",
     "@deepseek-ai/dsh-typert-protocol": "0.1.7-rc.2",
     "@deepseek-ai/dsh-user-questions": "0.1.7-rc.2",
-    "@deepseek-ai/schemastery": "3.18.3",
+    "@deepseek-ai/schemastery": "3.18.4",
     "@types/node": "^24.0.0",
     "@types/react": "^18.3.31",
     "@types/react-dom": "^18.3.7",