@anionex/dsh-turn-rewind 0.1.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, dsh-external
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,182 @@
+# DSH Turn Rewind
+
+[![X (Twitter)](https://img.shields.io/badge/-@anion__ex-000000?style=flat-square&logo=x&logoColor=white)](https://x.com/anion_ex)
+
+[中文说明](README.zh.md)
+
+Message-anchored project-file recovery for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), with an option to restart from the restored request.
+
+**Turn Rewind** is the user-facing feature, repository, and Profile Bundle name. **Change Ledger** is the durable restore engine underneath it: the `ctx.changeLedger` service, on-disk format, and storage path keep that name because they describe the reusable snapshot and recovery layer rather than the Web action alone.
+
+Change Ledger gives a DSH session an explicit safety boundary around workspace mutations:
+
+```text
+create restore point
+        ↓
+agent / user / external tools modify the worktree
+        ↓
+preview exact path-level drift
+        ↓
+review a full or selective restore plan
+        ↓
+press the final restore button in the rewind dialog
+        ↓
+create rescue point → restore → verify
+```
+
+It never commits, stashes, resets, switches branches, edits the Git index, or decides automatically that a change should be reverted.
+
+## Preview
+
+Rewind appears as an icon-only third action under each user message, after its timestamp and native Copy action:
+
+![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:
+
+![Turn Rewind review dialog](docs/assets/turn-rewind-dialog.png)
+
+## Why it has a Change Ledger engine
+
+A diff button can show current changes, but it does not own a durable restore lifecycle. Change Ledger owns:
+
+- content-addressed restore-point manifests;
+- Git worktree, HEAD, branch, and in-progress-operation fences;
+- stale-plan detection between review and mutation;
+- exact two-step confirmation plus DSH human approval;
+- automatic pre-restore rescue points;
+- post-restore hash verification;
+- rollback after a failed restore;
+- startup reconciliation of interrupted restore journals;
+- a public `ctx.changeLedger` service that other plugins can consume.
+
+The durable format is documented in [docs/FORMAT.md](docs/FORMAT.md). The security and failure model is documented in [SECURITY.md](SECURITY.md).
+
+## Safety contract
+
+- **Explicit only:** nothing is restored automatically — every restore starts from the user pressing the final button in the Web dialog, or from an explicit call through the service API.
+- **Read before write:** the dialog preview generates an expiring, session-bound plan from the current tree and changes no files.
+- **Human gate:** the dialog's reviewed impact plus the final restore button is the human decision; direct mutation requests without a live session-bound plan pair fail closed.
+- **Rescue before mutation:** every restore captures the current eligible tree as a durable rescue point before changing a path.
+- **No silent omission:** unsupported submodules, sparse checkouts, oversized files, aggregate limits, and unsupported file types fail point creation.
+- **No path escape:** every durable path is canonical and workspace-relative; restore refuses symlink parents and non-empty directory replacement.
+- **No stale overwrite:** selected paths and the reviewed HEAD/branch/operation fence are checked again at apply time. Any relevant post-review change invalidates the plan.
+- **No Git control-plane mutation:** the index, branch, HEAD, stash, and commits remain untouched.
+
+## Scope
+
+Version `0.1` intentionally supports normal Git worktrees only:
+
+- tracked files, including currently missing tracked paths;
+- untracked files not excluded by `.gitignore` or other standard Git excludes;
+- regular files, binary or text;
+- symbolic links;
+- executable and other portable permission bits.
+
+The following are rejected or deliberately outside the snapshot:
+
+- sparse checkouts;
+- submodule gitlinks (create a restore point inside each submodule instead);
+- ignored files;
+- special files, sockets, devices, and named pipes;
+- extended attributes, ACLs, ownership, timestamps, and hard-link topology;
+- the Git index and repository metadata;
+- non-Git directories.
+
+If an ignored or otherwise unmanaged file occupies a path that restoration would replace, the restore fails rather than deleting it.
+
+## Install
+
+Build the checked-out plugin, then add it to each DSH profile that should expose the service:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm run check
+
+dsh plugin --profile web add @anionex/dsh-turn-rewind
+dsh plugin --profile headless add @anionex/dsh-turn-rewind
+
+dsh --profile web --dump-config | grep turn-rewind
+```
+
+Restart a running profile after changing its bundle list.
+
+The package is a DSH Profile Bundle. `package.json` declares `dsh.bundle.patch`, and `cordis.patch.yml` mounts `@anionex/dsh-turn-rewind` without a DSH core patch.
+
+When the profile also provides the DSH Agent service, the plugin captures a hidden checkpoint in the first `agent/pre-step` waterfall before the Agent processes the opening user message. Capture failures are reported but do not reject the user's turn; the corresponding message simply has no usable rewind point. In Web profiles, the same-origin `/turn-rewind` endpoint resolves the selected `user/message` sequence, exposes a paged file preview, mints a short-lived session-bound restore plan, and delegates child creation to DSH's official Host create/fork lifecycle. It never restores files automatically.
+
+## 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:
+
+| 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 only** | Restores the project files after automatically backing up their current state. | Leaves the current Session open and unchanged. |
+
+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.
+
+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.
+
+## Configuration
+
+Override configuration in the profile patch layer:
+
+```yaml
+- id: turn-rewind
+  config:
+    storageDir: ~/.dsh/change-ledger/v1
+    maxRestorePoints: 50
+    maxTurnCheckpointsPerSession: 30
+    maxFiles: 20000
+    maxFileBytes: 16777216
+    maxSnapshotBytes: 536870912
+    planTtlMs: 900000
+    staleLockMs: 30000
+```
+
+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.
+
+## 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.
+
+Recovery uses the public `ctx.changeLedger` service API: `listRecovery` finds the operation's `rescuePointId`, `inspect` reviews that rescue point, then `planRestore`/`applyRestore` handle the affected paths. Rescue points remain ordinary, inspectable restore points until explicitly deleted.
+
+## Public service
+
+Other Cordis plugins can inject `changeLedger` and call the same lifecycle through the structured service API:
+
+```ts
+export const inject = ['changeLedger']
+
+export async function apply(ctx: Context) {
+  const point = await ctx.changeLedger.create({
+    cwd: '/absolute/git/worktree',
+    sessionId: 'session-id',
+    label: 'before refactor',
+  })
+  // point.id is a durable restore-point id.
+}
+```
+
+The complete exported types are available from `@anionex/dsh-turn-rewind/format`; the engine is available from `@anionex/dsh-turn-rewind/core` for non-Cordis tests and trusted integrations.
+
+## Development
+
+```sh
+pnpm install --frozen-lockfile
+pnpm run check
+```
+
+The test suite creates real temporary Git repositories and covers full/selective restore, stale plans, ignored-path collision refusal, HEAD drift, rescue rollback, crash reconciliation, active-lock preservation, durable-state integrity, symlinks, size limits, sparse checkouts, submodules, deletion, and blob garbage collection.
+
+## About
+
+DSH Turn Rewind is maintained by [anionex](https://anionex.me/). If you would like to follow my future work, [follow me on X](https://x.com/anion_ex) or [GitHub](https://github.com/Anionex).
+
+## License
+
+BSD-3-Clause. See [LICENSE](LICENSE).

package/README.zh.md

@@ -0,0 +1,180 @@
+# DSH Turn Rewind
+
+[![X (Twitter)](https://img.shields.io/badge/-@anion__ex-000000?style=flat-square&logo=x&logoColor=white)](https://x.com/anion_ex)
+
+[English](README.md)
+
+为 DeepSeek Harness 提供 Turn 级项目文件恢复，并可选择从恢复后的这一轮继续新对话。
+
+**Turn Rewind** 是用户看到的功能名、仓库名和 Profile Bundle 名。**Change Ledger** 是底层持久恢复引擎；`ctx.changeLedger` 服务、磁盘格式和存储路径继续保留这个名字，因为它们描述的是可复用的快照与恢复层，而不只是 Web 上的回退按钮。
+
+它给 DSH Session 增加一条明确的安全边界：
+
+```text
+创建恢复点
+    ↓
+Agent / 用户 / 外部程序修改工作树
+    ↓
+预览逐路径变化
+    ↓
+审阅全部或部分恢复计划
+    ↓
+在回退弹窗中按下最终恢复按钮
+    ↓
+先建救援点 → 恢复 → 哈希验证
+```
+
+插件**不会**自动 commit、stash、reset、切分支、修改 Git index，也不会替用户判断某项改动“应该回滚”。
+
+## 效果预览
+
+每条用户消息下方依次显示时间、DSH 原生“复制”和第三个纯图标“回退”：
+
+![用户消息下方的 Turn Rewind 图标](docs/assets/turn-rewind-action.png)
+
+打开后会先展示受影响文件，可选择“恢复文件并从这里继续”或“只恢复文件”：
+
+![Turn Rewind 审阅弹窗](docs/assets/turn-rewind-dialog.png)
+
+## 为什么底层需要 Change Ledger
+
+普通 Git 面板可以展示当前 diff，但不拥有完整、持久的恢复生命周期。Change Ledger 独立负责：
+
+- 内容寻址的恢复点 manifest；
+- Git worktree、HEAD、分支和进行中 Git 操作的状态围栏；
+- 从审阅到执行之间的 stale plan 检测；
+- 短期确认码与 DSH 人工批准双门槛；
+- 每次恢复前自动建立救援点；
+- 恢复后的内容哈希验证；
+- 恢复失败后的自动回滚；
+- DSH 重启时对未完成操作日志进行对账；
+- 可供其他插件依赖的 `ctx.changeLedger` 公共服务。
+
+持久格式见 [docs/FORMAT.md](docs/FORMAT.md)，安全与故障模型见 [SECURITY.md](SECURITY.md)。
+
+## 安全契约
+
+- **只做显式操作：**任何恢复都不会自动发生——每一次恢复都从用户在 Web 弹窗中按下最终按钮开始，或来自对服务 API 的显式调用。
+- **先读后写：**弹窗预览基于当前工作树生成短期、会话绑定的计划，不修改任何文件。
+- **人工门禁：**弹窗中审阅受影响文件并按下最终恢复按钮就是人的决定；没有实时会话绑定计划对的直接修改请求一律 fail closed。
+- **先救援再修改：**恢复任何文件前，先持久化当前 eligible tree 的救援点。
+- **不静默漏文件：**遇到 submodule、sparse checkout、超限文件、总量超限或特殊文件类型时，创建恢复点直接失败。
+- **不允许路径逃逸：**所有持久路径必须是规范的工作树相对路径；恢复拒绝穿过 symlink 父目录，也拒绝覆盖非空目录。
+- **不覆盖审阅后的新变化：**执行时重新检查所选路径，以及审阅过的 HEAD、分支和 Git 操作状态；任何相关变化都会使计划失效。
+- **不碰 Git 控制面：**index、分支、HEAD、stash 和 commit 均保持原样。
+
+## 支持范围
+
+`0.1` 只支持普通 Git worktree：
+
+- tracked 文件，包括恢复点创建时已经缺失的 tracked 路径；
+- 未被 `.gitignore` 或 Git 标准 excludes 忽略的 untracked 文件；
+- 文本和二进制普通文件；
+- 符号链接；
+- 可执行位等可移植权限位。
+
+下列对象会被拒绝或明确排除：
+
+- sparse checkout；
+- submodule gitlink（应分别进入每个 submodule 建恢复点）；
+- ignored 文件；
+- socket、设备、FIFO 等特殊文件；
+- 扩展属性、ACL、所有者、时间戳和 hard-link 拓扑；
+- Git index 和仓库元数据；
+- 非 Git 目录。
+
+如果 ignored 或其他未受管理的文件占据了待恢复路径，插件会拒绝恢复，不会递归删除它。
+
+## 安装
+
+```sh
+pnpm install --frozen-lockfile
+pnpm run check
+
+dsh plugin --profile web add @anionex/dsh-turn-rewind
+dsh plugin --profile headless add @anionex/dsh-turn-rewind
+
+dsh --profile web --dump-config | grep turn-rewind
+```
+
+修改 Profile Bundle 后需要重启对应 DSH 进程。
+
+本仓库是标准 DSH Profile Bundle：`package.json` 声明 `dsh.bundle.patch`，`cordis.patch.yml` 直接挂载 `@anionex/dsh-turn-rewind`，不修改 DSH 主仓库。
+
+当 Profile 同时提供 DSH Agent 服务时，插件会在每轮第一次 `agent/pre-step`、Agent 开始处理用户消息之前保存隐藏文件状态。保存失败只会让该消息无法回退，不会拦住用户这一轮。Web Profile 还会提供同源 `/turn-rewind` 接口：根据所选 `user/message` 序号找到对应状态，分页返回文件预览，生成短期、会话绑定的恢复授权，并把新对话创建交给 DSH 官方 Host create/fork 生命周期。插件绝不会自动恢复文件。
+
+## 使用流程
+
+在 Web Profile 中，每条用户消息下方都会在时间和原生“复制”之后显示一个紧凑、无文字的**回退**图标，提示是“恢复到发送这条消息之前”。图标使用明确的向后/撤销箭头，而不是“重试”圆形箭头。打开后会检查保存的文件状态，先显示简洁预览，需要时可“查看全部文件”，并提供两种模式：
+
+| 模式 | 代码 | 对话 |
+| --- | --- | --- |
+| **恢复文件并从这里继续**（默认） | 自动备份当前状态后恢复项目文件。 | 创建一个从这里开始的新会话（当前对话会保留）。 |
+| **只恢复文件** | 自动备份当前状态后恢复项目文件。 | 当前 Session 保持原位且内容不变。 |
+
+弹窗和最终主按钮就是确认流程，不再要求重复勾选。文件会按实际结果显示为“恢复之前的版本”“找回文件”“移除后来新增的文件”“恢复文件权限”或“恢复之前的文件类型”。如果项目文件已经是发送所选消息之前的状态，Turn Rewind 不会退化为“分支新对话”，而是提示无需恢复并引导用户使用原生的**分支新对话**按钮。
+
+真正修改前，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 始终保留。
+
+## 配置
+
+在 Profile 的 patch 层覆盖：
+
+```yaml
+- id: turn-rewind
+  config:
+    storageDir: ~/.dsh/change-ledger/v1
+    maxRestorePoints: 50
+    maxTurnCheckpointsPerSession: 30
+    maxFiles: 20000
+    maxFileBytes: 16777216
+    maxSnapshotBytes: 536870912
+    planTtlMs: 900000
+    staleLockMs: 30000
+```
+
+所有容量与用户恢复点数量限制都采用 fail loud。自动 Turn 检查点使用独立的每会话保留窗口，并且只清理自己最旧的检查点；用户和救援恢复点永远不会被静默删除。未配置时，`storageDir` 使用 `$DSH_HOME/change-ledger/v1`，未设置 `DSH_HOME` 时回退到 `~/.dsh/change-ledger/v1`；它不得与被管理 worktree 重叠。
+
+## 故障恢复
+
+任何路径写入前，插件都会先创建救援点和持久 operation journal。如果 DSH 在非终态操作期间退出，下次启动会把该操作标记为 `interrupted`；如果另一个仍存活的 DSH 进程持有工作树锁，则不会误判其操作。
+
+恢复通过公开的 `ctx.changeLedger` 服务 API 进行：用 `listRecovery` 找到操作的 `rescuePointId`，用 `inspect` 审阅该救援点，再对相关路径走 `planRestore`/`applyRestore`。救援点在被显式删除前始终是普通、可检查的恢复点。
+
+## 公共服务
+
+其他 Cordis 插件可以注入 `changeLedger`，直接调用结构化 API：
+
+```ts
+export const inject = ['changeLedger']
+
+export async function apply(ctx: Context) {
+  const point = await ctx.changeLedger.create({
+    cwd: '/absolute/git/worktree',
+    sessionId: 'session-id',
+    label: 'before refactor',
+  })
+  // point.id 是持久恢复点 ID。
+}
+```
+
+完整格式类型从 `@anionex/dsh-turn-rewind/format` 导出；可信集成和测试可以从 `@anionex/dsh-turn-rewind/core` 使用独立 Engine。
+
+## 开发
+
+```sh
+pnpm install --frozen-lockfile
+pnpm run check
+```
+
+测试会创建真实的临时 Git 仓库，覆盖全部/部分恢复、stale plan、ignored 路径冲突拒绝、HEAD 变化、救援回滚、崩溃对账、活动锁保护、持久状态完整性、symlink、容量限制、sparse checkout、submodule、删除和 blob GC。
+
+## 关于
+
+DSH Turn Rewind 由 [anionex](https://anionex.me/) 维护。如果你想了解我后续的更多工作，欢迎在 [X](https://x.com/anion_ex) 或 [GitHub](https://github.com/Anionex) 关注我。
+
+## 许可证
+
+BSD-3-Clause，见 [LICENSE](LICENSE)。

package/SECURITY.md

@@ -0,0 +1,53 @@
+# Security model
+
+## Trusted boundary
+
+The plugin runs in the DSH host process and therefore has the host user's filesystem authority. It treats model arguments, durable state, current worktree contents, and concurrent external changes as untrusted inputs.
+
+## Mutation gates
+
+Workspace restoration requires all of the following:
+
+1. an existing durable restore point;
+2. a fresh in-memory plan generated from the current tree;
+3. an exact short-lived confirmation value;
+4. the same DSH session when the plan was session-bound;
+5. an explicit human decision: the Web rewind dialog's reviewed impact plus final restore button for a direct browser action, or an equivalent human approval path implemented by a trusted service-API consumer;
+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.
+
+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.
+
+Restore-and-restart restores files first, then creates the conversation child. If child creation fails, the adapter immediately applies the first restore's rescue point to compensate the file change. If compensation also fails, the ordinary durable restore journals and rescue points remain available for manual recovery rather than hiding a partial outcome. Any running Agent using the same canonical worktree, including the source Session, blocks Web restoration before mutation and is rechecked at apply time; idle Agents do not create a concurrent writer risk. A reviewed HEAD or branch difference is allowed because restoration never moves refs, HEAD, the branch, or the index; a changed or newly active Git operation remains blocked.
+
+An absent or expired confirmation fails closed at apply time: the engine applies a restore only when the confirmation exactly matches a fresh session-bound plan.
+
+## Filesystem containment
+
+- State storage and the managed worktree may not overlap.
+- Manifest paths are validated before joining them to the canonical worktree root.
+- Existing parent components are checked with `lstat`; symlink parents are rejected.
+- A regular file, symlink, or special file omitted by Git's current eligible-path inventory is never overwritten as though it were absent.
+- Added paths are removed individually. Recursive deletion is never used for worktree content.
+- A directory is removed only when empty. Unmanaged contents therefore block restoration.
+- Blobs are SHA-256 verified before use and size-checked against their manifest entry.
+
+## Concurrency and crashes
+
+Each canonical worktree has an exclusive owner-only lock file with PID, timestamp, and nonce. A second live DSH process does not reconcile or take over an active restore. Locks whose owner no longer exists become reclaimable after `staleLockMs`.
+
+Restore journals are written before worktree mutation. A failed restore attempts rollback from the rescue point without honoring a newly aborted caller signal, because leaving a partial mutation is less safe than completing rollback. If rollback also fails, the journal becomes `recovery-required` and preserves both diagnostics and the rescue point.
+
+## Explicit non-goals
+
+- This plugin does not sandbox other processes or prevent them from changing files concurrently.
+- It does not restore Git index entries, refs, commits, stash state, ignored files, submodules, or repository operation metadata.
+- It does not preserve extended attributes, ACLs, ownership, timestamps, or hard-link identity.
+- It does not provide confidentiality or tamper resistance against the same operating-system user. State files are owner-only by default, but the host user remains trusted.
+- It automatically captures bounded, hidden checkpoints before the first step of newly observed DSH turns when the rewind adapter is active; it never automatically applies one. User and rescue restore points remain explicit.
+
+## Reporting
+
+Report a vulnerability through the private repository's GitHub security channel or to a repository maintainer. Include the plugin commit, platform, Git version, DSH snapshot, reproduction repository shape, and whether the failure happened before or after workspace mutation.

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# Mount Turn Rewind and its Change Ledger service into a DSH profile.
+- insert:
+    - id: turn-rewind
+      name: '@anionex/dsh-turn-rewind'

package/docs/FORMAT.md

@@ -0,0 +1,101 @@
+# Change Ledger durable format v1
+
+The state root defaults to `$DSH_HOME/change-ledger/v1`, falling back to `~/.dsh/change-ledger/v1`. It must not overlap a managed worktree.
+
+```text
+v1/
+└── workspaces/
+    └── <sha256(canonical-worktree-path)>/
+        ├── lock.json
+        ├── manifests/
+        │   └── rp_<time>_<random>.json
+        ├── operations/
+        │   └── op_<time>_<random>.json
+        └── blobs/
+            └── <first-two-hex>/
+                └── <sha256>
+```
+
+Every JSON write uses a sibling temporary file followed by rename. Blob publication writes and fsyncs a sibling temporary file, then creates the final content-addressed name through an atomic hard link. Existing blobs are read back and hash-verified.
+
+## Restore-point manifest
+
+```ts
+interface RestorePointManifestV1 {
+  version: 1
+  id: `rp_${string}`
+  kind: 'user' | 'rescue' | 'turn'
+  workspace: string
+  repository: {
+    root: string
+    commonDir: string
+    head?: string
+    branch?: string
+    operation?: string
+    stagedPaths: string[]
+  }
+  sessionId?: string
+  label?: string
+  parentRestorePoint?: string
+  turn?: number
+  turnStartSeq?: number
+  turnEndSeq?: number
+  createdAt: number
+  treeHash: string
+  fileCount: number
+  totalBytes: number
+  entries: Record<string, FileEntry | SymlinkEntry>
+  restoreCount: number
+  lastRestoredAt?: number
+}
+
+interface FileEntry {
+  kind: 'file'
+  blob: string
+  size: number
+  mode: number
+}
+
+interface SymlinkEntry {
+  kind: 'symlink'
+  target: string
+  mode: number
+}
+```
+
+`turn` manifests are automatic, hidden checkpoints used by the Web rewind surface. New checkpoints require `sessionId`, `turn`, and the inclusive `turnStartSeq` observed before the Agent enters its first step. Version-1 checkpoints written by the earlier assistant-tail implementation may instead carry `turnEndSeq`; readers preserve them for format compatibility, but prompt-anchored Web rewind never binds them to a user message. Exactly one turn boundary is required, and turn metadata is rejected on `user` and `rescue` manifests. Malformed or partially anchored turn manifests fail closed.
+
+Entry keys are canonical Git-style relative paths using `/`. Absolute paths, empty segments, `.` segments, `..` segments, and NUL bytes are rejected before filesystem resolution.
+
+`treeHash` is SHA-256 over every sorted path and its complete type/content/mode signature. Readers recompute it from validated entries and reject mismatches. Regular-file blobs are SHA-256 addressed and verified on every restore read.
+
+## Restore operation
+
+```ts
+interface RestoreOperationV1 {
+  version: 1
+  id: `op_${string}`
+  workspace: string
+  restorePointId: string
+  rescuePointId: string
+  sessionId?: string
+  paths: string[]
+  startedAt: number
+  finishedAt?: number
+  state:
+    | 'running'
+    | 'rollback-running'
+    | 'completed'
+    | 'rolled-back'
+    | 'interrupted'
+    | 'recovery-required'
+  error?: string
+  rollbackError?: string
+}
+```
+
+`running` and `rollback-running` are non-terminal. Startup changes them to `interrupted` only when the workspace has no live lock owner. Terminal journals remain as local audit evidence; restore-point deletion never removes an incomplete journal's referenced point.
+
+## Compatibility
+
+Readers reject unknown `version` values and malformed durable data. There is no best-effort fallback, path normalization, or legacy coercion. A future incompatible format must use a new state-root version and an explicit migration tool.

package/docs/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,56 @@
+# Turn Rewind 对齐计划
+
+## 目标
+
+让 Web 端 Rewind 以用户消息为锚点：用户点击消息下方的回退图标，就能查看并恢复“发送这条消息之前”的项目文件，并可选择在新对话里重新开始。产品语义对齐 Claude Code，同时保留 Change Ledger 对完整工作树、自动备份、失败回滚和持久恢复的支持。
+
+## 已实现内容
+
+### 1. 用户消息锚点
+
+- 回退图标从 Assistant 回复操作栏移到用户消息下方，排在时间和“复制”之后，无文字显示。
+- 提示和弹窗标题统一为“回到发送这条消息之前”。
+- 客户端按 `user/message` 的 `seq` 请求预览，不再用 Assistant Turn 尾部作为入口。
+- 新对话创建后，会把所选用户消息的文字放回输入框。
+
+### 2. 消息发送前保存文件
+
+- 在每轮第一次 `agent/pre-step` 中、调用 `next()` 之前保存文件状态。
+- 保存点精确绑定 `turn/start`，保证语义是 Agent 尚未处理这条用户消息。
+- 同一工作树的保存操作串行执行。
+- 保存失败会记录错误，但不会阻断用户 Turn；失败的消息不会伪造可用状态，也不会在 Turn 结束后重试并错误标记当前文件。
+
+### 3. 恢复与重新开始
+
+- **恢复文件并重新开始：**先恢复文件，再创建新对话，并把原消息文字放回输入框。
+- **只恢复文件：**只改项目文件，当前对话保持不变。
+- 第一条消息之前没有完整 Turn，使用 Host `session.create` 在同一目录创建空 Session。
+- 后续消息使用 Host `session.fork`，边界是所选消息之前的上一条 `turn/end`。
+- 原 Session 始终保留；只分支对话、文件不变的需求继续由原生“分支新对话”负责。
+
+### 4. Git 状态处理
+
+- HEAD 前进或当前分支变化不再直接阻止恢复；预览说明影响后，以 `allowHeadChange` 生成恢复计划。
+- 恢复不会撤销 commit、切换分支、移动 HEAD 或修改 index；恢复结果可以表现为当前 HEAD 上的未提交修改。
+- 合并、变基、cherry-pick 等 Git 操作状态变化继续阻止恢复。
+- 预览后 HEAD、分支、Git 操作或所选文件再次变化，现有计划仍会失效。
+
+### 5. 并发、分叉与失败处理
+
+- 同一工作树只要存在正在运行的 Agent，包括来源 Session 自己，就阻止 Web 恢复；idle Session 不阻止。
+- 子 Session 先使用自己的保存点，再沿祖先查找；兄弟分支互不混用。
+- 祖先复用要求所选 `user/message` 和对应 `turn/start` 在每一层都低于 `seedLength`，并且边界完全一致。
+- 父 Session 缺失、分叉循环或边界不一致时安全失败。
+- 恢复前创建自动备份；创建新对话失败时，立即用备份补偿恢复前的文件状态。
+
+### 6. 持久格式兼容
+
+- 新 Turn 保存点写入 `turnStartSeq`。
+- 旧版 `turnEndSeq` manifest 仍可读取，避免破坏格式版本 1，但不会被绑定到新的用户消息入口。
+- `turn` manifest 必须且只能携带一种 Turn 边界。
+
+## 最终功能边界
+
+- **分支新对话（Branch）：**从现有对话创建分支，项目文件保持不变。
+- **Turn Rewind：**恢复到发送所选用户消息之前的项目文件，并可选择创建新对话重新开始。
+- **Change Ledger：**提供持久保存、差异预览、短期恢复计划、自动备份、原子恢复、失败回滚和重启对账，不在普通用户主流程中暴露底层术语。