@anionex/dsh-turn-rewind 0.1.2 → 0.2.0

package/README.md

@@ -32,7 +32,7 @@ Rewind appears as an icon-only third action under each user message, after its t
 
 ![Turn Rewind action under a user message](docs/assets/turn-rewind-action.png)
 
-Opening it shows the affected files and offers two choices: restore the files and restart from before that message, or restore only the files:
+Opening it shows the affected files and offers three choices: restore the files and restart from before that message, restore only the files, or rewind only the messages and leave the files untouched:
 
 ![Turn Rewind review dialog](docs/assets/turn-rewind-dialog.png)
 
@@ -107,22 +107,25 @@ When the profile also provides the DSH Agent service, the plugin captures a hidd
 
 ## User flow
 
-In the Web profile, each direct user message gains a compact, icon-only **Rewind** action after its timestamp and native Copy control. The tooltip reads “Return to before sending this message.” Opening Rewind checks the saved file state, shows a concise preview with a “view all files” action, and offers two modes:
+In the Web profile, each direct user message gains a compact, icon-only **Rewind** action after its timestamp and native Copy control. The tooltip reads “Return to before sending this message.” Opening Rewind checks the saved file state, shows a concise preview with a “view all files” action, and offers three modes:
 
 | Mode | Code | Conversation |
 | --- | --- | --- |
-| **Restore files and restart** (default) | Restores the project files after automatically backing up their current state. | Creates and opens a Session ending before the selected message, then puts that message's text back in the composer. |
+| **Restore files and restart** (default when files changed) | Restores the project files after automatically backing up their current state. | Creates and opens a Session ending before the selected message, then puts that message's text back in the composer. |
 | **Restore files only** | Restores the project files after automatically backing up their current state. | Leaves the current Session open and unchanged. |
+| **Rewind messages only** (default when no checkpoint or no file changes) | Leaves the project files exactly as they are. | Creates and opens a Session ending before the selected message, then puts that message's text back in the composer. |
 
-The dialog itself is the confirmation: there is no duplicate checkbox. It describes each file as restoring an earlier version, finding a deleted file, removing a later-added file, or restoring permissions/type. If the project files already match the state before the selected message, Turn Rewind performs no action and directs the user to the native **Branch** button for conversation-only branching.
+The dialog itself is the confirmation: there is no duplicate checkbox. It describes each file as restoring an earlier version, finding a deleted file, removing a later-added file, or restoring permissions/type. **Rewind messages only** is always available — including when the checkpoint for that message is missing, was skipped (for example after disabling automatic checkpoints), or the project files already match the saved state — because it never touches the worktree. It is not blocked by other running Agents in the same worktree.
 
 Before mutation, Turn Rewind rechecks the selected files and repository state, then creates an automatic backup. Changes made after preview invalidate the operation. Any running Agent using the same worktree, including the source Session, blocks restoration; idle Sessions do not block. A reviewed HEAD or branch difference does not block restoration: commits, refs, branch, and index remain unchanged, so restored content may appear as ordinary uncommitted changes against the current HEAD. An in-progress Git operation still blocks. If child creation fails after “restore and restart,” Change Ledger automatically restores the pre-operation files from the backup.
 
-DSH Session logs are append-only, so “restart” creates a new Session instead of truncating the original. For the first message, the Host creates a blank Session in the same working directory; for later messages, it forks at the previous completed `turn/end`. A child may reuse an ancestor's prompt checkpoint only while both the selected `user/message` and its exact `turn/start` remain inside every durable `seedLength` fence. Direct child checkpoints take priority and sibling checkpoints never mix. **Branch** creates only a conversation branch and keeps project files unchanged; **Turn Rewind** always restores project files, optionally followed by a new conversation with the selected prompt restored to the composer. The original Session is always retained.
+DSH Session logs are append-only, so “restart” creates a new Session instead of truncating the original. For the first message, the Host creates a blank Session in the same working directory; for later messages, it forks at the previous completed `turn/end`. A child may reuse an ancestor's prompt checkpoint only while both the selected `user/message` and its exact `turn/start` remain inside every durable `seedLength` fence. Direct child checkpoints take priority and sibling checkpoints never mix. **Turn Rewind** always treats the two dimensions independently: the two restore modes change project files (optionally followed by a new conversation), while **Rewind messages only** reuses the same fork lifecycle without touching files. The original Session is always retained.
 
 ## Configuration
 
-Override configuration in the profile patch layer:
+Runtime-tunable options are editable in the DSH web settings page under **Plugins → Turn Rewind** (`turn-rewind` settings namespace). Changes apply live to the next capture, restore, or deletion; they persist in the host's `settings.yaml` and override the profile patch values below. `storageDir` is deliberately not editable there: the storage root must not move while the engine holds locks and journals, so it stays a patch-layer field.
+
+Override the composition base (and `storageDir`) in the profile patch layer:
 
 ```yaml
 - id: turn-rewind
@@ -135,10 +138,20 @@ Override configuration in the profile patch layer:
     maxSnapshotBytes: 536870912
     planTtlMs: 900000
     staleLockMs: 30000
+    turnCheckpointMode: legacy   # off | git-native | legacy; "off" stops creating file checkpoints
+    turnCheckpointTimeoutMs: 5000
+    turnCheckpointMaxNewBytes: 33554432
+    turnCheckpointTrust: fast    # fast | strict
 ```
 
+Setting `turnCheckpointMode: off` (in the patch or in the settings card) stops automatic file checkpoints; every turn records a durable skip instead, and the rewind dialog still offers **Rewind messages only** for those messages.
+
 All size and user-point retention limits fail loudly. Automatic turn checkpoints have a separate per-session retention window and prune only their own oldest checkpoints; user and rescue restore points are never silently pruned. When omitted, `storageDir` resolves to `$DSH_HOME/change-ledger/v1` and falls back to `~/.dsh/change-ledger/v1`; it must not overlap the managed worktree.
 
+## Checkpoint management
+
+The same settings card includes a storage manager backed by the same-origin `/turn-rewind/manage` endpoint. It lists every workspace this storage root has ever tracked — including projects whose directory no longer exists — grouped with checkpoint counts, approximate sizes, and pending-recovery badges. Per checkpoint, per workspace, or globally (**Clear all**), it deletes unprotected restore points and garbage-collects unreferenced blobs. Restore points still referenced by an incomplete recovery journal, a running restore, or an unfinished Git-native publish are retained and reported. Git-native (v2) checkpoints live in the repository's Git object database, so their disk space is reclaimed by normal Git garbage collection; the displayed sizes are logical values.
+
 ## Recovery
 
 Before writing any path, a restore creates a rescue point and a durable operation journal. If DSH stops with a non-terminal journal, the next plugin startup marks it `interrupted` unless another live DSH process still owns that workspace lock.

package/README.zh.md

@@ -32,7 +32,7 @@ Agent / 用户 / 外部程序修改工作树
 
 ![用户消息下方的 Turn Rewind 图标](docs/assets/turn-rewind-action.png)
 
-打开后会先展示受影响文件，可选择“恢复文件并从这里继续”或“只恢复文件”：
+打开后会先展示受影响文件，可选择“恢复文件并从这里继续”“只恢复文件”或“只回溯消息（不动文件）”：
 
 ![Turn Rewind 审阅弹窗](docs/assets/turn-rewind-dialog.png)
 
@@ -105,22 +105,25 @@ dsh --profile web --dump-config | grep turn-rewind
 
 ## 使用流程
 
-在 Web Profile 中，每条用户消息下方都会在时间和原生“复制”之后显示一个紧凑、无文字的**回退**图标，提示是“恢复到发送这条消息之前”。图标使用明确的向后/撤销箭头，而不是“重试”圆形箭头。打开后会检查保存的文件状态，先显示简洁预览，需要时可“查看全部文件”，并提供两种模式：
+在 Web Profile 中，每条用户消息下方都会在时间和原生“复制”之后显示一个紧凑、无文字的**回退**图标，提示是“恢复到发送这条消息之前”。图标使用明确的向后/撤销箭头，而不是“重试”圆形箭头。打开后会检查保存的文件状态，先显示简洁预览，需要时可“查看全部文件”，并提供三种模式：
 
 | 模式 | 代码 | 对话 |
 | --- | --- | --- |
-| **恢复文件并从这里继续**（默认） | 自动备份当前状态后恢复项目文件。 | 创建一个从这里开始的新会话（当前对话会保留）。 |
+| **恢复文件并从这里继续**（文件有变化时的默认） | 自动备份当前状态后恢复项目文件。 | 创建一个从这里开始的新会话（当前对话会保留）。 |
 | **只恢复文件** | 自动备份当前状态后恢复项目文件。 | 当前 Session 保持原位且内容不变。 |
+| **只回溯消息（不动文件）**（无检查点或文件无变化时的默认） | 项目文件保持当前状态，不做任何修改。 | 创建一个从这里开始的新会话，并把原消息文字填入输入框。 |
 
-弹窗和最终主按钮就是确认流程，不再要求重复勾选。文件会按实际结果显示为“恢复之前的版本”“找回文件”“移除后来新增的文件”“恢复文件权限”或“恢复之前的文件类型”。如果项目文件已经是发送所选消息之前的状态，Turn Rewind 不会退化为“分支新对话”，而是提示无需恢复并引导用户使用原生的**分支新对话**按钮。
+弹窗和最终主按钮就是确认流程，不再要求重复勾选。文件会按实际结果显示为“恢复之前的版本”“找回文件”“移除后来新增的文件”“恢复文件权限”或“恢复之前的文件类型”。**只回溯消息**始终可用——即使该消息没有保存检查点、检查点被跳过（例如在设置里关闭了自动检查点），或项目文件已经与保存状态一致——因为它完全不触碰工作区，也不会被同一工作区中其他运行中的 Agent 阻止。
 
 真正修改前，Turn Rewind 会再次检查所选文件和项目版本状态，并先创建自动备份。预览后出现的新变化会让本次恢复失效。同一工作树只要还有正在运行的 Agent（包括当前来源 Session），恢复就会被阻止；仅处于空闲状态的 Session 不会阻止恢复。已经审阅过的 HEAD 或分支变化不会阻止恢复：commit、分支、HEAD 和 index 都保持不变，恢复后的内容可能表现为当前 HEAD 上的未提交修改。Git 正在合并、变基等操作时仍会阻止。如果“恢复文件并从这里继续”在创建新对话时失败，Change Ledger 会自动从备份恢复操作前的文件。
 
-DSH Session 日志只追加不改写，因此“恢复文件并从这里继续”会创建新 Session，而不是截断原对话。选中第一条消息时，Host 会在同一目录创建空 Session；选中后续消息时，会在上一轮 `turn/end` 处分叉。只有所选 `user/message` 和对应的精确 `turn/start` 都低于每一层持久 `seedLength` 时，子 Session 才能复用祖先保存的状态；子 Session 自己的状态优先，兄弟分支绝不混用。**分支新对话**只创建对话分支且保持项目文件不变；**Turn Rewind**一定恢复项目文件，再由用户决定是否创建新对话并把原消息文字填入新对话的输入框。原 Session 始终保留。
+DSH Session 日志只追加不改写，因此“恢复文件并从这里继续”和“只回溯消息”都会创建新 Session，而不是截断原对话。选中第一条消息时，Host 会在同一目录创建空 Session；选中后续消息时，会在上一轮 `turn/end` 处分叉。只有所选 `user/message` 和对应的精确 `turn/start` 都低于每一层持久 `seedLength` 时，子 Session 才能复用祖先保存的状态；子 Session 自己的状态优先，兄弟分支绝不混用。**Turn Rewind** 的两个维度彼此独立：两个“恢复文件”模式会修改项目文件（可选随后创建新对话），而**只回溯消息**复用同一分叉生命周期但完全不碰文件。原 Session 始终保留。
 
 ## 配置
 
-在 Profile 的 patch 层覆盖：
+运行时可调选项可以直接在 DSH Web 设置页的**插件 → Turn Rewind**卡片（`turn-rewind` 设置命名空间）中修改，修改对下一次捕获、恢复或删除即时生效，并持久化到宿主 `settings.yaml`，优先级高于下方 patch 层配置。`storageDir` 刻意不在此处暴露：存储根目录在引擎持有锁与 journal 时不可移动，只能通过 patch 层配置。
+
+在 Profile 的 patch 层覆盖组合基线（以及 `storageDir`）：
 
 ```yaml
 - id: turn-rewind
@@ -133,10 +136,20 @@ DSH Session 日志只追加不改写，因此“恢复文件并从这里继续
     maxSnapshotBytes: 536870912
     planTtlMs: 900000
     staleLockMs: 30000
+    turnCheckpointMode: legacy   # off | git-native | legacy；off 表示不创建文件检查点
+    turnCheckpointTimeoutMs: 5000
+    turnCheckpointMaxNewBytes: 33554432
+    turnCheckpointTrust: fast    # fast | strict
 ```
 
+把 `turnCheckpointMode` 设为 `off`（patch 层或设置卡均可）后，插件不再为每条消息自动创建文件检查点，而是记录持久跳过标记；回退弹窗对这些消息仍然提供**只回溯消息**。
+
 所有容量与用户恢复点数量限制都采用 fail loud。自动 Turn 检查点使用独立的每会话保留窗口，并且只清理自己最旧的检查点；用户和救援恢复点永远不会被静默删除。未配置时，`storageDir` 使用 `$DSH_HOME/change-ledger/v1`，未设置 `DSH_HOME` 时回退到 `~/.dsh/change-ledger/v1`；它不得与被管理 worktree 重叠。
 
+## 检查点管理
+
+同一张设置卡内置存储管理器，由同源 `/turn-rewind/manage` 端点支撑。它列出该存储根下跟踪过的所有工作区——包括目录已被删除的项目——并按项目分组显示检查点数量、近似占用和待处理恢复徽标。支持按单个检查点、按项目或全局（一键清空）删除未受保护的恢复点并回收不再引用的 blob。仍被未完成的恢复 journal、进行中的恢复或未完成的 Git-native publish 引用的恢复点会被保留并明确报告。Git-native（v2）检查点内容存放在仓库的 Git 对象库中，其磁盘空间由 Git 自身的垃圾回收释放；界面显示的大小为逻辑值。
+
 ## 故障恢复
 
 任何路径写入前，插件都会先创建救援点和持久 operation journal。如果 DSH 在非终态操作期间退出，下次启动会把该操作标记为 `interrupted`；如果另一个仍存活的 DSH 进程持有工作树锁，则不会误判其操作。

package/SECURITY.md

@@ -16,7 +16,9 @@ Workspace restoration requires all of the following:
 6. still-fresh selected-path hashes and the exact reviewed HEAD/branch/operation fence under the workspace lock;
 7. a durable rescue point and operation journal.
 
-The Web rewind adapter obtains the same session-bound plan and exact confirmation from a same-origin preview request, then sends both only after the user reviews the affected files and presses the final restore button. Direct mutation requests without that live plan pair fail closed. Conversation-only branching is deliberately absent and remains the responsibility of DSH's native Branch action.
+The Web rewind adapter obtains the same session-bound plan and exact confirmation from a same-origin preview request, then sends both only after the user reviews the affected files and presses the final restore button. Direct mutation requests without that live plan pair fail closed. Message-only rewind (`mode: "messages"`) deliberately requires no restore plan: it never mutates the worktree, so there is nothing to gate or rescue. It re-resolves the selected message boundary server-side, revalidates the exact `turn/start` and previous `turn/end` against the live session, and fails closed with `PLAN_STALE` when the boundary no longer matches.
+
+The storage-management endpoint (`/turn-rewind/manage`, same-origin like the rewind endpoint) only deletes the plugin's own durable state: manifest deletion runs under the workspace lock when the recorded repository still exists, skips every restore point referenced by an incomplete recovery journal, a running restore, or an unfinished Git-native publish, and garbage-collects only blobs no remaining manifest references. It never touches worktree content and never requires a worktree to exist on disk.
 
 Restore-and-restart verifies that the durable checkpoint still names the exact `turn/start` before the selected `user/message`. A forked Session may resolve that checkpoint through its parent lineage only while both event sequences remain below every durable `seedLength` and every ancestor contains the same message and turn boundary. A direct checkpoint wins over an inherited checkpoint, sibling checkpoints are isolated, and malformed or missing lineage fails closed. The first message restarts through Host `session.create`; later messages fork at the previous completed `turn/end`. The Host owns seed creation, model-target inheritance, persistence, and Workspace attachment. The original append-only Session remains intact.