dsh-rewind-plugin 0.1.10 → 0.2.0

package/README.md

@@ -2,19 +2,20 @@
 
 DeepSeek Harness 插件：**同一会话窗口的 in-place 对话回退**（Claude Code `/rewind` 语义）。主交互为**用户消息旁的「回退」按钮**，点击后选择回退模式；命令仅作辅助。
 
-> 状态：v0.1.10 已实现并发布（`dsh-rewind-plugin`，npm + GitHub Actions Trusted Publishing）。交互以 Claude Code 行为为参考，并贴合 dsh Web 实际 UI（利用现有 DOM 锚点与运行时快照，纯插件、不改仓库核心）。
+> 状态：v0.2.0 已实现（`dsh-rewind-plugin`，npm + GitHub Actions Trusted Publishing）。交互以 Claude Code 行为为参考，并贴合 dsh Web 实际 UI（利用现有 DOM 锚点与运行时快照，纯插件、不改仓库核心）。
 
-## 实现状态（v0.1.10）
+## 实现状态（v0.2.0）
 
-- ✅ host 端 `/rewind` 命令（手动单动作：不接受参数、撤回最近一条；参数化形式保留为按钮内部调用）
-- ✅ host 端变更台账（`tools/execute` 捕获 before、`tools/post-execute` 提交），按会话隔离
+- ✅ host 端 `/rewind` 命令（参数化形式作为 ↶ 按钮的内部调用通道；手动输入由 client 拦截）
+- ✅ **Claude Code 式 checkpoint 文件回退**：`tools/execute` 捕获写前备份、`tools/post-execute` 按消息分组**落盘**提交（`~/.dsh/rewind-snapshots`），重启后仍可还原
 - ✅ **与其他审批类插件共存**：捕获在 around-dispatch 阶段，`tools/pre-execute` 被 `ask` 短路（如 dsh-edit-approval）后批准仍能记录；被拒绝的调用不留 pending 残留
-- ✅ **路径按会话 cwd 解析**（复刻 `dsh-tool-fs` 的 session-cwd 规则），相对路径台账/还原指向真实文件；台账记录解析后的 display path
+- ✅ **路径按会话 cwd 解析**（复刻 `dsh-tool-fs` 的 session-cwd 规则），相对路径备份/还原指向真实文件；记录解析后的 display path
 - ✅ **fs 服务动态获取**（`ctx.inject(['fs'])`）：fs 后挂载也不失效，无 fs 部署时命令仍可用
 - ✅ 同窗口 in-place 回退：追加空内容标记 + `surfaceOp: replace` 替换目标及之后全部 surface（真实 `dsh-session` 集成测试通过）
-- ✅ client 端「回退」按钮（MutationObserver 注入用户消息行操作区）+ 模式选择浮层（含 both 模式影响清单确认）+ 手动 `/rewind` 参数拦截
-- ✅ 测试：纯函数单测 + 真实 `dsh-session` 集成测试 + `verify-host` 端到端（14 项，含审批短路/会话 cwd 场景）
-- ⏳ 二期：快捷键、git-first 快照式文件回退
+- ✅ **还原走 `node:fs` 直写**（不经 fs 服务）：文件内容真正落盘；符号链接跳过并警告
+- ✅ client 端「回退」按钮（MutationObserver 注入用户消息行操作区）+ 模式选择浮层（含 both 模式影响清单确认）+ 手动 `/rewind` 输入拦截
+- ✅ 测试：纯函数单测 + 真实 `dsh-session` 集成测试 + `verify-host` 端到端（18 项，含审批短路/会话 cwd/新建文件删除/重启持久化场景）
+- ⏳ 二期：快捷键、bash/外部修改的快照覆盖（整树快照）
 
 ## 安装
 
@@ -68,24 +69,24 @@ git push --tags      # push v<version> tag → 触发 .github/workflows/publish.
 
 - 每条用户消息 hover 出现「↶ 回退」按钮：点击 → 选择「仅回退对话」或
   「回退对话和代码」（后者先展示影响清单再确认）。
-- **回退 = 撤回（时间回溯）**：对**任意**用户消息回退（按钮，或 `/rewind` 撤回最近一条），
+- **回退 = 撤回（时间回溯）**：对**任意**用户消息回退（使用消息旁的 ↶ 按钮），
   效果是**撤回该消息及它之后的所有内容**（含 agent 回复、工具调用）——对话界面与
   Agent 上下文都回到这条消息发送之前；**该消息的文本自动填入输入框（编辑区）**，
   可直接修改后重发。命令结果提示"已撤回 seq N 及之后内容"。
-- 手动 `/rewind` **不接受参数**：直接撤回最近一条用户消息（内容填回输入框可修改重发）；
-  回退到更早的消息请用该消息旁的 ↶ 按钮（参数化命令保留为按钮内部调用）。
+- **手动 `/rewind` 不支持**：在输入框手动输入 `/rewind`（含裸命令）会被 client 拦截并
+  提示改用按钮——`/rewind` 命令仅作为按钮的内部调用通道存在。
 - **回退后前端与 Agent 一致**：回退标记是空内容消息（deriveMessages 会跳过，模型
   上下文无任何标记噪音）；client 端隐藏被撤回范围内的消息行与 `/rewind` 命令结果，
   可见对话即"撤回点之前的内容"。会话日志（append-only 审计）不受影响。
 
-## 已知限制（v0.1）
+## 已知限制（v0.2）
 
-- 台账只覆盖插件运行期间、经 `write` / `edit` / `str_replace_editor` 的变更；
-  bash 或外部程序的修改无法还原（二期可加 git-first 快照层）。台账按会话有界
-  （每会话保留最近 2000 条，最旧先丢弃）。
-- 文件删除走 `processPath` 直删（本地 backend）；sandbox/远程 backend 下还原
+- checkpoint 只覆盖**插件运行期间、经 `write` / `edit` / `str_replace_editor` 的变更**；
+  bash 或外部程序的修改无法还原（与 Claude Code 相同的限制，二期可加整树快照层）。
+  备份按消息分组**落盘**（每会话保留最近 100 组，最旧先清理），dsh 重启不丢失。
+- 文件删除/还原走真实路径直删直写（本地 backend）；sandbox/远程 backend 下路径解析
   可能受限。
-- 回退本身可再回退（标记进入日志），但文件还原动作不再重新入台账。
+- 回退本身可再回退（标记进入日志），但文件还原动作不再记录新备份。
 - 回退按钮只出现在**当前会话**渲染的用户消息行上（DOM 注入范围即当前视图）；
   subagent/分屏等非当前会话的对话需要先切到该会话再回退。
 
@@ -93,10 +94,10 @@ git push --tags      # push v<version> tag → 触发 .github/workflows/publish.
 
 社区 rewind 类插件（`dsh-recall-plugin`、`dsh-checkpoint-rewind`、`dsh-turn-rewind`）均为 **fork 路线**（回退 = fork 出新会话，用户切换会话继续），且没有「仅回退对话 / 对话+代码」的选项。本插件提供：**在当前会话窗口内**改写模型上下文 + 可选还原工作区文件。
 
-## 交互设计（按钮两步；手动命令为单动作）
+## 交互设计（按钮两步；手动命令不支持）
 
 按钮流程遵循两步：**第一步选择要回退到的 user 消息，第二步选择回退模式**。手动
-`/rewind` 命令不参与两步流程——它不接受参数，只撤回最近一条消息。
+`/rewind` 命令不支持输入——client 端在输入框拦截所有手动 `/rewind` 并提示改用按钮。
 
 ### 1. 用户消息旁的「回退」按钮（主入口）
 
@@ -109,16 +110,11 @@ git push --tags      # push v<version> tag → 触发 .github/workflows/publish.
 - 选「回退对话和代码」时，浮层内先显示将受影响的内容清单（将还原/删除的文件名与数量），确认后执行。
 - 执行结果以一条对话内消息呈现（如「已回退到 seq N，移除 M 条上下文；还原 2 个文件」）。
 
-### 2. 命令（辅助入口，仅支持手动撤回最近一条）
+### 2. 命令（仅作按钮内部通道，不支持手动输入）
 
-```
-/rewind   撤回最近一条用户消息（不接受参数；内容填回输入框可修改重发）
-```
-
-- 手动 `/rewind` 是**单动作**：不接受任何参数，直接撤回最近一条用户消息（对话回到
-  上一条消息之前）。参数化形式（`@seq chat|both`、`preview`）仍存在于 host 端，
-  但**仅供 ↶ 按钮内部调用**——client 端会在输入框拦截带参数的手动 `/rewind` 并提示
-  改用按钮。回退到更早的消息请使用该消息旁的「回退」按钮。
+- **手动输入 `/rewind`（含裸命令）会被 client 端在输入框直接拦截**，并提示改用消息旁
+  的 ↶ 按钮。`/rewind` 命令仅作为按钮的内部调用通道存在
+  （`/rewind @seq chat|both`、`/rewind preview @seq both`）。
 - UI 按钮与命令共享同一套 host 端回退逻辑（`/rewind @seq <mode>`）。
 
 ## 回退机制（host 端，全部公开 API）
@@ -129,30 +125,35 @@ git push --tags      # push v<version> tag → 触发 .github/workflows/publish.
 - 效果：当前窗口上下文从目标点重新开始；**不产生新会话、不切换窗口**；原始日志完整保留（append-only 审计不变），仅不再进入模型上下文。
 - 依赖：`@deepseek-ai/dsh-session`（`Session.append`、`foldSurface`）、`@deepseek-ai/dsh-llm`（`createUserMessage`）、`@deepseek-ai/dsh-commands`（命令注册）、`@deepseek-ai/dsh-agent`（`Agent.status` idle 守卫）。
 
-### 4. 文件回退：变更台账
+### 4. 文件回退：Claude Code 式 checkpoint（写前备份，按消息分组落盘）
 
-- 在 `tools/execute`（around-dispatch 阶段）读取目标文件 before，`tools/post-execute` 记录
-  `{ 消息锚点 seq, 文件路径(解析后), before, after }`。捕获放在 execute 而非
-  pre-execute：**审批类插件（如 dsh-edit-approval）在 `tools/pre-execute` 返回 `ask`
-  会短路后续监听器**，但批准后 dispatch 阶段必然执行——共存的写操作照样入台账；
-  被拒绝的调用不 dispatch，不会留下 pending 残留。
+- 在 `tools/execute`（around-dispatch 阶段）读取目标文件**写前备份**（before；文件不存在记
+  为「新建」），`tools/post-execute` 将备份按**当前轮用户消息 seq（锚点）**落盘提交到
+  `~/.dsh/rewind-snapshots/<会话>/<锚点 seq>/`。捕获放在 execute 而非 pre-execute：
+  **审批类插件（如 dsh-edit-approval）在 `tools/pre-execute` 返回 `ask` 会短路后续监听器**，
+  但批准后 dispatch 阶段必然执行——共存的写操作照样入备份；被拒绝的调用不 dispatch，
+  不会留下残留。
 - 相对路径按**会话 cwd** 解析（与 `dsh-tool-fs` 同规则，`src/session-cwd.ts`），
-  台账记录解析后的 display path，preview/还原始终指向真实文件。
-- 回退「对话和代码」时，把目标点之后发生的变更**逆序还原**（内容写回 before、新建文件删除）。
-- 边界（已知限制）：台账只覆盖**插件运行期间、经写类工具**的变更；bash 命令或外部程序的修改不在台账内，无法还原（二期可加 git-first 快照层）。
+  备份记录解析后的 display path，preview/还原始终指向真实文件。
+- 回退「对话和代码」到消息 N 时：对锚点 ≥ N 的每条备份取**该文件最早一条**——内容写回
+  before、新建文件删除（与 Claude Code 的 rewind 语义一致）。恢复用 `node:fs` 直写真实
+  文件，不经过 fs 服务；符号链接跳过并在结果中提示。
+- 持久化：备份在磁盘上，**dsh 重启后仍可还原**；每会话保留最近 100 个消息分组，最旧先清理。
+- 边界（已知限制）：只覆盖**插件运行期间、经写类工具**的变更；bash 命令或外部程序的修改
+  不在备份内，无法还原（与 Claude Code 相同的限制，二期可加整树快照层）。
 
 ### 5. 安全守卫
 
 - agent 运行中（LLM 思考/输出）执行回退时**自动强制停止**当前回合（`cancel({kind:'user'})`），
   等待 quiescence 后回退；停止超时/失败则中止并报错。无需先手动停止。
 - 文件还原是破坏性操作：UI 选择「对话和代码」时需经影响清单确认；命令路径用 `preview` 先行查看。
-- 回退本身可再回退（回退动作同样进入台账/日志）。
+- 回退本身可再回退（回退动作同样进入会话日志），但文件还原动作不再记录新备份。
 
 ## 客户端实现要点（纯插件，无源码补丁）
 
 - 按钮注入锚点：用户行 `[data-chat-flow-kind="user"]`（行容器 `data-chat-anchor-key` 为节点 key）；用 MutationObserver 跟踪新增行。
 - 消息 seq 获取：从行元素的 `data-chat-anchor-key` → 运行时快照 `session.getSnapshot().chat.nodes.get(key)` → `UserMessageNode.seq`（DOM 只用于定位，数据取自 runtime，不解析 DOM 文本）。
-- **按钮两步选择浮层**：点击消息旁按钮时，客户端接管交互——目标即该消息，第二步展示模式选项（仅回退对话 / 回退对话和代码 / 取消）；确认后调 `session.command('/rewind @<seq> <mode>')` 执行。**手动 `/rewind` 不经过浮层**：它不接受参数，直接撤回最近一条消息；client 端在输入框拦截带参数的手动 `/rewind` 并提示改用按钮。
+- **按钮两步选择浮层**：点击消息旁按钮时，客户端接管交互——目标即该消息，第二步展示模式选项（仅回退对话 / 回退对话和代码 / 取消）；确认后调 `session.command('/rewind @<seq> <mode>')` 执行。**手动 `/rewind` 被 client 整体拦截**（含裸命令）：输入框 guard 阻止提交并提示改用按钮；`/rewind` 命令仅作为按钮内部调用通道存在。
 - 执行结果以命令节点出现在对话中。
 - 注入按钮与「在新对话中分支」等官方操作并排，样式遵循 dsh 设计 token。
 
@@ -161,22 +162,22 @@ git push --tags      # push v<version> tag → 触发 .github/workflows/publish.
 - 快捷键（esc+esc 回退等）——独立的快捷键插件，二期。
 - 压缩（`/compact`）——官方已有。
 - fork/分支回退——官方已有（「在新对话中分支」）。
-- 快照式文件回退（git-first）——二期（台账方案先行）。
+- 快照式文件回退（整树/git-first，覆盖 bash 与外部修改）——二期（checkpoint 方案先行）。
 
 ## 目录结构（实际）
 
 ```
-src/index.ts           host 插件：/rewind 命令 + tools/execute|post-execute 台账（fs 动态注入）
+src/index.ts           host 插件：/rewind 命令 + tools/execute|post-execute checkpoint（fs 动态注入）
 src/rewind.ts          planRewind 纯函数（目标解析、surface 范围计算、候选列表）
-src/ledger.ts          变更台账（记录、查询、逆序还原、影响清单；按会话 cwd 解析）
+src/snapshot.ts        checkpoint 存储（写前备份按消息分组落盘、还原/删除/影响清单、有界清理）
 src/session-cwd.ts     会话 cwd 解析（复刻 dsh-tool-fs 规则，可单测）
 src/client/index.ts    client 插件：消息行「回退」按钮 + 模式选择浮层
 src/client/popover.ts  浮层 DOM（含 both 模式影响清单确认）
 src/client/locales.ts  zh/en 文案（LocaleNamespaceMap 合并）
 src/client/styles.ts   注入样式（dsh 设计 token）
 scripts/build.mjs      esbuild 构建：lib/index.js（host ESM）+ lib/client.js（loader 闭包）
-scripts/verify-host.mjs  端到端验证（真实 cordis + dsh-session，14 项断言）
-tests/                 rewind/ledger 单测 + 真实 dsh-session 集成测试
+scripts/verify-host.mjs  端到端验证（真实 cordis + dsh-session + 真实临时文件，18 项断言）
+tests/                 rewind/snapshot 单测 + 真实 dsh-session 集成测试
 cordis.patch.yml       bundle patch（插入 dsh-rewind-plugin 一行，双面）
 package.json           dsh.bundle + dsh.client 声明、optional peerDependencies
 ```

package/lib/client.js

@@ -45,10 +45,10 @@ var zh = {
   "popover.cancel": "\u53D6\u6D88",
   "popover.impact.loading": "\u6B63\u5728\u83B7\u53D6\u5F71\u54CD\u6E05\u5355\u2026",
   "popover.impact.failed": "\u65E0\u6CD5\u83B7\u53D6\u5F71\u54CD\u6E05\u5355\uFF1A{message}",
-  "popover.impact.none": "\u76EE\u6807\u4E4B\u540E\u6CA1\u6709\u53F0\u8D26\u8BB0\u5F55\u7684\u5199\u7C7B\u53D8\u66F4\uFF0C\u65E0\u9700\u8FD8\u539F\u6587\u4EF6\u3002",
+  "popover.impact.none": "\u76EE\u6807\u4E4B\u540E\u6CA1\u6709\u8DDF\u8E2A\u5230\u7684\u5199\u7C7B\u53D8\u66F4\uFF0C\u65E0\u9700\u8FD8\u539F\u6587\u4EF6\u3002",
   "popover.confirm": "\u786E\u8BA4\u56DE\u9000",
   "popover.back": "\u8FD4\u56DE",
-  "guard.hint": "/rewind \u4E0D\u63A5\u53D7\u53C2\u6570\uFF0C\u53EA\u80FD\u64A4\u56DE\u6700\u8FD1\u4E00\u6761\u6D88\u606F\uFF1B\u56DE\u9000\u5230\u66F4\u65E9\u6D88\u606F\u8BF7\u7528\u8BE5\u6D88\u606F\u65C1\u7684 \u21B6 \u6309\u94AE"
+  "guard.hint": "/rewind \u547D\u4EE4\u4E0D\u652F\u6301\u624B\u52A8\u8F93\u5165\uFF0C\u8BF7\u4F7F\u7528\u6D88\u606F\u65C1\u7684 \u21B6 \u56DE\u9000\u6309\u94AE"
 };
 var en = {
   "button.aria": "Rewind to this message",
@@ -62,10 +62,10 @@ var en = {
   "popover.cancel": "Cancel",
   "popover.impact.loading": "Fetching impact list\u2026",
   "popover.impact.failed": "Could not fetch the impact list: {message}",
-  "popover.impact.none": "No ledger-recorded file changes after the target; nothing to restore.",
+  "popover.impact.none": "No tracked file changes after the target; nothing to restore.",
   "popover.confirm": "Confirm rewind",
   "popover.back": "Back",
-  "guard.hint": "/rewind takes no parameters \u2014 it only withdraws the most recent message. To rewind to an earlier message, use the \u21B6 button on that message."
+  "guard.hint": "/rewind cannot be typed manually \u2014 use the \u21B6 button on a message to rewind."
 };
 
 // src/client/styles.ts
@@ -564,11 +564,11 @@ function apply(ctx) {
         if (fillComposer(text)) filled.add(target);
       }
     };
-    const REWIND_WITH_ARGS = /^\s*\/rewind\s+\S/i;
+    const MANUAL_REWIND = /^\s*\/rewind(?:\s|$)/i;
     const composerTextarea = () => document.querySelector(COMPOSER_SELECTOR);
     const hasBlockedRewindDraft = () => {
       const textarea = composerTextarea();
-      return textarea !== null && REWIND_WITH_ARGS.test(textarea.value);
+      return textarea !== null && MANUAL_REWIND.test(textarea.value);
     };
     let guardHintEl = null;
     let guardHintTimer;

package/lib/index.js

@@ -2,101 +2,6 @@
 import { createAssistantMessage } from "@deepseek-ai/dsh-llm";
 import { unlink } from "node:fs/promises";
 
-// src/session-cwd.ts
-import { canonicalPath } from "@deepseek-ai/dsh-sandbox";
-var PARENT_PATH_SEGMENT = /(?:^|[\\/])\.\.(?:[\\/]|$)/;
-function sessionCwd(cwd, requestedPath) {
-  if (cwd === void 0 || !PARENT_PATH_SEGMENT.test(cwd) && !PARENT_PATH_SEGMENT.test(requestedPath)) return cwd;
-  return canonicalPath(cwd);
-}
-function execSessionCwd(exec, requestedPath) {
-  return sessionCwd(exec.agent?.session.header.cwd, requestedPath);
-}
-
-// src/ledger.ts
-var MAX_LEDGER_ENTRIES = 2e3;
-var RewindLedger = class {
-  entries = [];
-  /** Record one committed mutation, dropping the oldest entry when over the cap. */
-  record(entry) {
-    this.entries.push(entry);
-    if (this.entries.length > MAX_LEDGER_ENTRIES) this.entries.shift();
-  }
-  /**
-   * All entries anchored at or after `targetSeq`, newest first. The boundary
-   * is inclusive: rewinding to a message also reverts the changes its own
-   * turn caused (the rewind cut removes that turn's assistant response and
-   * tool calls), so only changes anchored at earlier messages survive.
-   */
-  changesAfter(targetSeq) {
-    const after = [];
-    for (let i = this.entries.length - 1; i >= 0; i--) {
-      const entry = this.entries[i];
-      if (entry.anchorSeq >= targetSeq) after.push(entry);
-    }
-    return after;
-  }
-  /**
-   * Unique per-file impact for preview. A file whose earliest affected change
-   * created it (`before === undefined`) is deleted on restore; any other file
-   * is written back to its pre-target content.
-   */
-  impactsAfter(targetSeq) {
-    const byPath = /* @__PURE__ */ new Map();
-    for (const entry of this.entries) {
-      if (entry.anchorSeq < targetSeq) continue;
-      if (byPath.has(entry.path)) continue;
-      byPath.set(entry.path, { path: entry.path, action: entry.before === void 0 ? "delete" : "restore" });
-    }
-    return [...byPath.values()];
-  }
-  /**
-   * Reverse every change anchored at or after `targetSeq`. Each entry writes
-   * its pre-change content back; a file that did not exist before the target
-   * is deleted instead. Failures are collected per file and never abort the pass.
-   * @param fs - the filesystem service (resolve/readText/writeText/processPath).
-   * @param deleteFile - backend-appropriate file deletion by process path.
-   * @param targetSeq - the rewind target; only later changes are reverted.
-   * @param options - session workspace cwd (relative ledger paths resolve
-   *   against it, mirroring the fs tools) and an optional abort signal.
-   */
-  async restoreAfter(fs, deleteFile, targetSeq, options = {}) {
-    const restored = [];
-    const deleted = [];
-    const failed = [];
-    const restoredSet = /* @__PURE__ */ new Set();
-    const deletedSet = /* @__PURE__ */ new Set();
-    for (const entry of this.changesAfter(targetSeq)) {
-      try {
-        const cwd = sessionCwd(options.cwd, entry.path);
-        const target = await fs.resolve(entry.path, {
-          ...cwd !== void 0 ? { cwd } : {},
-          signal: options.signal
-        });
-        if (entry.before === void 0) {
-          await deleteFile(fs.processPath(target));
-          if (!deletedSet.has(entry.path)) {
-            deletedSet.add(entry.path);
-            deleted.push(entry.path);
-          }
-        } else {
-          await fs.writeText(target, entry.before, void 0, options.signal);
-          if (!restoredSet.has(entry.path)) {
-            restoredSet.add(entry.path);
-            restored.push(entry.path);
-          }
-        }
-      } catch (error) {
-        failed.push({
-          path: entry.path,
-          message: error instanceof Error ? error.message : String(error)
-        });
-      }
-    }
-    return { restored, deleted, failed };
-  }
-};
-
 // src/rewind.ts
 var RewindError = class extends Error {
   constructor(code, message) {
@@ -179,6 +84,180 @@ function planRewind(events, surface, target) {
   };
 }
 
+// src/session-cwd.ts
+import { canonicalPath } from "@deepseek-ai/dsh-sandbox";
+var PARENT_PATH_SEGMENT = /(?:^|[\\/])\.\.(?:[\\/]|$)/;
+function sessionCwd(cwd, requestedPath) {
+  if (cwd === void 0 || !PARENT_PATH_SEGMENT.test(cwd) && !PARENT_PATH_SEGMENT.test(requestedPath)) return cwd;
+  return canonicalPath(cwd);
+}
+function execSessionCwd(exec, requestedPath) {
+  return sessionCwd(exec.agent?.session.header.cwd, requestedPath);
+}
+
+// src/snapshot.ts
+import { mkdir, readFile, readdir, rm, writeFile, lstat } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+var DEFAULT_SNAPSHOT_ROOT = join(homedir(), ".dsh", "rewind-snapshots");
+var SNAPSHOT_ROOT_ENV = "DSH_REWIND_SNAPSHOT_DIR";
+var MAX_ANCHOR_GROUPS = 100;
+function safeFileId(callId) {
+  return callId.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+async function readEntry(file) {
+  try {
+    const parsed = JSON.parse(await readFile(file, "utf8"));
+    if (typeof parsed.path !== "string" || typeof parsed.anchorSeq !== "number") return void 0;
+    return {
+      callId: String(parsed.callId ?? ""),
+      anchorSeq: parsed.anchorSeq,
+      path: parsed.path,
+      before: typeof parsed.before === "string" ? parsed.before : null,
+      time: typeof parsed.time === "number" ? parsed.time : 0
+    };
+  } catch {
+    return void 0;
+  }
+}
+async function isSymbolicLink(path) {
+  try {
+    return (await lstat(path)).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+var SnapshotStore = class {
+  constructor(root = process.env[SNAPSHOT_ROOT_ENV] ?? DEFAULT_SNAPSHOT_ROOT) {
+    this.root = root;
+  }
+  root;
+  /** Absolute path of one anchor group directory. */
+  anchorDir(sessionId, anchorSeq) {
+    return join(this.root, sessionId, String(anchorSeq));
+  }
+  /** Commit one before-backup under its turn's anchor group. */
+  async recordEntry(sessionId, entry) {
+    const dir = this.anchorDir(sessionId, entry.anchorSeq);
+    await mkdir(dir, { recursive: true });
+    const committed = { ...entry, time: Date.now() };
+    await writeFile(join(dir, `${safeFileId(entry.callId)}.json`), JSON.stringify(committed), "utf8");
+    await this.prune(sessionId);
+  }
+  /**
+   * All committed entries anchored at or after `targetSeq`, newest first (for
+   * preview ordering). The boundary is inclusive: rewinding to a message also
+   * reverts the changes its own turn caused (the rewind cut removes that
+   * turn's assistant response and tool calls), so only entries anchored at
+   * earlier messages survive.
+   */
+  async entriesAfter(sessionId, targetSeq) {
+    const sessionDir = join(this.root, sessionId);
+    let names;
+    try {
+      names = await readdir(sessionDir);
+    } catch (error) {
+      if (error.code === "ENOENT") return [];
+      throw error;
+    }
+    const entries = [];
+    for (const name2 of names) {
+      const anchorSeq = Number(name2);
+      if (!Number.isSafeInteger(anchorSeq) || anchorSeq < targetSeq) continue;
+      const files = await readdir(this.anchorDir(sessionId, anchorSeq)).catch(() => []);
+      for (const file of files) {
+        if (!file.endsWith(".json")) continue;
+        const entry = await readEntry(join(this.anchorDir(sessionId, anchorSeq), file));
+        if (entry !== void 0) entries.push(entry);
+      }
+    }
+    return entries.sort((a, b) => b.anchorSeq - a.anchorSeq || b.time - a.time);
+  }
+  /** Per-file restore impact for the earliest entry at/after the target. */
+  async impactsAfter(sessionId, targetSeq) {
+    const earliest = /* @__PURE__ */ new Map();
+    for (const entry of await this.entriesAfter(sessionId, targetSeq)) {
+      const current = earliest.get(entry.path);
+      if (current === void 0 || entry.anchorSeq < current.anchorSeq || entry.anchorSeq === current.anchorSeq && entry.time < current.time) {
+        earliest.set(entry.path, entry);
+      }
+    }
+    return [...earliest.values()].sort((a, b) => a.path.localeCompare(b.path)).map((entry) => ({
+      path: entry.path,
+      action: entry.before === null ? "delete" : "restore"
+    }));
+  }
+  /**
+   * Restore the workspace to the target message's checkpoint: for every path
+   * with entries anchored at or after it, apply the EARLIEST entry — write the
+   * before content back, or delete the file when it was created after the
+   * target. Symbolic links are skipped (reported, never written through).
+   * Failures are per-file and never abort the pass.
+   */
+  async restoreAfter(sessionId, targetSeq, deleteFile) {
+    const restored = [];
+    const deleted = [];
+    const skipped = [];
+    const failed = [];
+    const earliest = /* @__PURE__ */ new Map();
+    for (const entry of await this.entriesAfter(sessionId, targetSeq)) {
+      const current = earliest.get(entry.path);
+      if (current === void 0 || entry.anchorSeq < current.anchorSeq || entry.anchorSeq === current.anchorSeq && entry.time < current.time) {
+        earliest.set(entry.path, entry);
+      }
+    }
+    for (const entry of earliest.values()) {
+      try {
+        if (await isSymbolicLink(entry.path)) {
+          skipped.push(entry.path);
+          continue;
+        }
+        if (entry.before === null) {
+          await deleteFile(entry.path);
+          deleted.push(entry.path);
+        } else {
+          await writeFile(entry.path, entry.before, "utf8");
+          restored.push(entry.path);
+        }
+      } catch (error) {
+        failed.push({ path: entry.path, message: error instanceof Error ? error.message : String(error) });
+      }
+    }
+    return { restored, deleted, skipped, failed };
+  }
+  /**
+   * Drop the session's oldest anchor groups beyond `keep` (default
+   * {@link MAX_ANCHOR_GROUPS}), deleting their whole directories.
+   */
+  async prune(sessionId, keep = MAX_ANCHOR_GROUPS) {
+    const sessionDir = join(this.root, sessionId);
+    let names;
+    try {
+      names = await readdir(sessionDir);
+    } catch (error) {
+      if (error.code === "ENOENT") return;
+      throw error;
+    }
+    const seqs = names.map(Number).filter((seq) => Number.isSafeInteger(seq)).sort((a, b) => a - b);
+    const excess = seqs.length - keep;
+    if (excess <= 0) return;
+    for (const seq of seqs.slice(0, excess)) {
+      await rm(this.anchorDir(sessionId, seq), { recursive: true, force: true });
+    }
+  }
+  /** True when a path exists on disk (used by tests and diagnostics). */
+  async exists(path) {
+    const { stat } = await import("node:fs/promises");
+    try {
+      await stat(path);
+      return true;
+    } catch (error) {
+      if (error.code === "ENOENT") return false;
+      throw error;
+    }
+  }
+};
+
 // src/index.ts
 var name = "dsh-rewind";
 var inject = ["commands", "tools"];
@@ -234,9 +313,9 @@ async function captureBefore(fs, exec, pending) {
   const target = await resolveTarget(fs, path, cwd, exec.signal);
   if (target === void 0) return;
   const before = await readTextOrUndefined(fs, target, exec.signal);
-  pending.set(`${exec.agent?.id ?? "anon"}:${exec.callId}`, { path: target.displayPath, cwd, before });
+  pending.set(`${exec.agent?.id ?? "anon"}:${exec.callId}`, { path: target.displayPath, before });
 }
-async function commitEntry(fs, ledgerFor, pending, exec, result) {
+async function commitEntry(store, pending, exec, result) {
   const key = `${exec.agent?.id ?? "anon"}:${exec.callId}`;
   const capture = pending.get(key);
   if (capture === void 0) return;
@@ -246,20 +325,11 @@ async function commitEntry(fs, ledgerFor, pending, exec, result) {
   if (agent === void 0) return;
   const anchorSeq = anchorSeqOf(agent.session);
   if (anchorSeq === void 0) return;
-  const target = await resolveTarget(fs, capture.path, capture.cwd, exec.signal);
-  if (target === void 0) return;
-  let after;
-  try {
-    after = await readTextOrUndefined(fs, target, exec.signal) ?? "";
-  } catch {
-    return;
-  }
-  ledgerFor(agent.session).record({
-    toolName: exec.name,
+  await store.recordEntry(agent.session.id, {
+    callId: exec.callId,
     anchorSeq,
     path: capture.path,
-    before: capture.before,
-    after
+    before: capture.before ?? null
   });
 }
 function buildMarker() {
@@ -290,7 +360,7 @@ function formatPlan(plan, files) {
       lines.push(`  ${file.action === "restore" ? "\u8FD8\u539F" : "\u5220\u9664"} ${file.path}`);
     }
   } else {
-    lines.push("\u76EE\u6807\u4E4B\u540E\u6CA1\u6709\u53F0\u8D26\u8BB0\u5F55\u7684\u5199\u7C7B\u53D8\u66F4\uFF0C\u65E0\u9700\u8FD8\u539F\u6587\u4EF6\u3002");
+    lines.push("\u76EE\u6807\u4E4B\u540E\u6CA1\u6709\u5FEB\u7167\u8BB0\u5F55\u7684\u5199\u7C7B\u53D8\u66F4\uFF0C\u65E0\u9700\u8FD8\u539F\u6587\u4EF6\u3002");
   }
   return lines.join("\n");
 }
@@ -313,7 +383,7 @@ async function waitForAgentIdle(agent, signal, timeoutMs = 15e3) {
   }
   return true;
 }
-async function executeRewind(ctx, ledger, invocation, rawTarget, mode) {
+async function executeRewind(ctx, store, invocation, rawTarget, mode) {
   const { agent } = invocation;
   if (agent.status !== "idle") {
     agent.cancel({ kind: "user" });
@@ -343,18 +413,13 @@ async function executeRewind(ctx, ledger, invocation, rawTarget, mode) {
   }
   let restore = "";
   if (mode === "both") {
-    const fs = ctx.get("fs", false);
-    if (fs === void 0) {
-      restore = "\uFF1B\u672A\u627E\u5230\u6587\u4EF6\u7CFB\u7EDF\u670D\u52A1\uFF0C\u672A\u8FD8\u539F\u6587\u4EF6\uFF08\u53EF\u4EC5\u7528 chat \u6A21\u5F0F\u56DE\u9000\u5BF9\u8BDD\uFF09";
-    } else {
-      const outcome = await ledger.restoreAfter(fs, (processPath) => unlink(processPath), plan.targetSeq, {
-        // Relative ledger paths resolve against the session workspace, exactly
-        // as the fs tools resolve them (per-entry in src/ledger.ts).
-        cwd: agent.session.header.cwd,
-        signal: invocation.signal
-      });
-      restore = `\uFF1B\u8FD8\u539F ${outcome.restored.length} \u4E2A\u6587\u4EF6\u3001\u5220\u9664 ${outcome.deleted.length} \u4E2A\u6587\u4EF6${renderFailures(outcome.failed)}`;
-    }
+    const outcome = await store.restoreAfter(agent.session.id, plan.targetSeq, (path) => unlink(path));
+    const parts = [];
+    if (outcome.restored.length > 0) parts.push(`\u8FD8\u539F ${outcome.restored.length} \u4E2A\u6587\u4EF6`);
+    if (outcome.deleted.length > 0) parts.push(`\u5220\u9664 ${outcome.deleted.length} \u4E2A\u6587\u4EF6`);
+    if (outcome.skipped.length > 0) parts.push(`\u8DF3\u8FC7 ${outcome.skipped.length} \u4E2A\u7B26\u53F7\u94FE\u63A5`);
+    restore = parts.length > 0 ? `\uFF1B${parts.join("\u3001")}` : "\uFF1B\u76EE\u6807\u4E4B\u540E\u6CA1\u6709\u53EF\u8FD8\u539F\u7684\u5199\u7C7B\u53D8\u66F4";
+    restore += renderFailures(outcome.failed);
   }
   return {
     kind: "success",
@@ -374,7 +439,7 @@ function rewindErrorResult(error) {
   }
   throw error;
 }
-async function handleRewind(ctx, ledger, invocation) {
+async function handleRewind(ctx, store, invocation) {
   const session = invocation.agent.session;
   const input = invocation.rawInput.trim();
   if (input === "") {
@@ -382,7 +447,7 @@ async function handleRewind(ctx, ledger, invocation) {
     if (candidates.length === 0) {
       return { kind: "error", text: "\u5F53\u524D\u4F1A\u8BDD\u8FD8\u6CA1\u6709\u53EF\u56DE\u9000\u7684\u7528\u6237\u6D88\u606F\u3002" };
     }
-    return executeRewind(ctx, ledger, invocation, `@${candidates[0].seq}`, "chat");
+    return executeRewind(ctx, store, invocation, `@${candidates[0].seq}`, "chat");
   }
   const parts = input.split(/\s+/);
   if (parts[0] === "preview") {
@@ -394,7 +459,7 @@ async function handleRewind(ctx, ledger, invocation) {
     } catch (error) {
       return rewindErrorResult(error);
     }
-    const impacts = ledger.impactsAfter(plan.targetSeq);
+    const impacts = await store.impactsAfter(session.id, plan.targetSeq);
     return { kind: "success", text: formatPlan(plan, impacts) };
   }
   const target = parts[0];
@@ -412,24 +477,16 @@ async function handleRewind(ctx, ledger, invocation) {
   /rewind ${target} both  \u56DE\u9000\u5BF9\u8BDD\u5E76\u8FD8\u539F\u6587\u4EF6`
     };
   }
-  return executeRewind(ctx, ledger, invocation, target, mode);
+  return executeRewind(ctx, store, invocation, target, mode);
 }
-function apply(ctx) {
-  const ledgers = /* @__PURE__ */ new Map();
-  const ledgerFor = (session) => {
-    let ledger = ledgers.get(session.id);
-    if (ledger === void 0) {
-      ledger = new RewindLedger();
-      ledgers.set(session.id, ledger);
-    }
-    return ledger;
-  };
+function apply(ctx, config) {
+  const store = new SnapshotStore(config?.snapshotDir);
   const pending = /* @__PURE__ */ new Map();
   ctx.effect(function* () {
     yield ctx.commands.register({
       name: "rewind",
       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",
-      handler: (invocation) => handleRewind(ctx, ledgerFor(invocation.agent.session), invocation)
+      handler: (invocation) => handleRewind(ctx, store, invocation)
     });
   }, "dsh-rewind command");
   ctx.inject(["fs"], (scope) => {
@@ -444,15 +501,16 @@ function apply(ctx) {
     });
     scope.on("tools/post-execute", async (exec, result, next) => {
       try {
-        await commitEntry(fs, ledgerFor, pending, exec, result);
+        await commitEntry(store, pending, exec, result);
       } catch (error) {
-        ctx.logger.warn(`[dsh-rewind] ledger commit failed for ${exec.name}: ${error instanceof Error ? error.message : String(error)}`);
+        ctx.logger.warn(`[dsh-rewind] checkpoint commit failed for ${exec.name}: ${error instanceof Error ? error.message : String(error)}`);
       }
       return next();
     });
   });
 }
 export {
+  SnapshotStore,
   apply,
   inject,
   name

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

@@ -16,10 +16,10 @@
  * before executing. Execution always goes through `session.command(...)`, the
  * same host path the `/rewind` command uses.
  *
- * Manual composer input of `/rewind` is deliberately restricted (the guard
- * below): it takes no parameters — a bare `/rewind` withdraws the most recent
- * message, and any `/rewind <args>` line is blocked with a hint pointing at
- * the per-message button.
+ * Manual composer input of `/rewind` is deliberately blocked (the guard
+ * below): the command exists only as the per-message button's internal
+ * channel, so any `/rewind` line typed by hand — bare or with arguments — is
+ * stopped with a hint pointing at the button.
  *
  * @module dsh-rewind/client
  */

package/lib/types/index.d.ts

@@ -1,35 +1,58 @@
 /**
- * dsh-rewind host half: the `/rewind` command and the write-class change
- * ledger, composed as one dual-face bundle row (the browser half lives in
- * `src/client/`).
+ * dsh-rewind host half: the `/rewind` command and the Claude-Code-style
+ * checkpoint store, composed as one dual-face bundle row (the browser half
+ * lives in `src/client/`).
  *
  * Rewind mechanism: planning is pure (`src/rewind.ts`); execution appends a
- * marker `user/message` into the session log whose `surfaceOp` replaces every
- * surface node after the target message with the marker. The append-only log
- * (and the rendered transcript) is untouched — only the model-visible surface
- * is cut, so the next request derives its context from the target onward.
- * Mode `both` additionally reverses every ledger-recorded file change that
- * followed the target.
+ * marker `assistant/message` into the session log whose `surfaceOp` replaces
+ * every surface node after the target message with the marker. The
+ * append-only log (and the rendered transcript) is untouched — only the
+ * model-visible surface is cut, so the next request derives its context from
+ * the target onward.
+ *
+ * File restore (mode `both`) follows Claude Code's checkpointing: the plugin
+ * backs up each tracked write-class edit BEFORE it happens (at the
+ * `tools/execute` around-dispatch stage, so an approval short-circuit cannot
+ * skip the capture and a denied call never records), commits the backup under
+ * the turn's anchor message seq at `tools/post-execute`, and a rewind to
+ * message N restores every backup anchored at or after N — modified files are
+ * written back to their pre-edit content, files created after N are deleted.
+ * Backups persist on disk under the dsh data directory (newest 100 message
+ * groups per session), so restores work after a host restart, and they
+ * read/write the real file system with plain `node:fs` — independent of the
+ * fs service. See `src/snapshot.ts`.
  *
  * @module dsh-rewind
  */
 import type { Context } from '@deepseek-ai/cordis';
+export { SnapshotStore } from './snapshot.ts';
+export type { CheckpointEntry, FileImpact, RestoreOutcome } from './snapshot.ts';
 export declare const name = "dsh-rewind";
 export declare const inject: string[];
+/** Plugin config: optional override of the checkpoint store root. */
+export interface RewindConfig {
+    /** Checkpoint store root (defaults to `~/.dsh/rewind-snapshots`). */
+    readonly snapshotDir?: string;
+}
 /**
- * Register the `/rewind` command and the tools-pipeline ledger hooks.
+ * Register the `/rewind` command and the checkpoint pipeline (before-capture
+ * at `tools/execute`, disk commit at `tools/post-execute`).
  *
- * The command is fs-independent and registers immediately. The ledger needs
- * `fs`, so its hooks mount through a dynamic `ctx.inject(['fs'])` — they take
- * effect whenever the fs service becomes available (and never fail the
- * plugin's load when a deployment has no fs).
+ * The command is fs-independent and registers immediately. The checkpoint
+ * pipeline needs `fs` to resolve tracked paths to their real display paths,
+ * so it mounts through a dynamic `ctx.inject(['fs'])` — it takes effect
+ * whenever the fs service becomes available (and never fails the plugin's
+ * load when a deployment has no fs; without it, no entries are recorded and
+ * `both` restores report "no tracked changes").
  *
  * Capture runs in `tools/execute` (the around-dispatch stage), NOT in
  * `tools/pre-execute`: a pre-execute `{ kind: 'ask' }` short-circuit from
  * another plugin (e.g. dsh-edit-approval) skips later pre-execute listeners,
  * and a denied call never dispatches — so approved calls are still captured,
- * denied calls never leave a pending entry behind.
+ * denied calls never leave a pending entry behind. Entries are committed to
+ * disk at `tools/post-execute` under the turn's anchor message seq.
  *
  * @param ctx - context carrying `commands`, `tools`, and an optional `fs`.
+ * @param config - optional override of the checkpoint store root.
  */
-export declare function apply(ctx: Context): void;
+export declare function apply(ctx: Context, config?: RewindConfig): void;

package/lib/types/session-cwd.d.ts

@@ -1,5 +1,5 @@
 /**
- * Session-cwd resolution for ledger reads/restores, mirroring the fs tools'
+ * Session-cwd resolution for snapshot tracking reads, mirroring the fs tools'
  * own rule (`@deepseek-ai/dsh-tool-fs/session-cwd.ts`): relative paths
  * resolve against the calling agent's session workspace
  * (`exec.agent.session.header.cwd`), not the server's launch dir.

package/lib/types/snapshot.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Checkpoint store — the Claude Code style file-rewind backing for dsh-rewind.
+ *
+ * Claude Code's checkpointing (see README) works like this: it creates a
+ * BACKUP of a file BEFORE every tracked modification, groups those backups by
+ * the user message they belong to (a "checkpoint"), and rewinding to a
+ * checkpoint restores every backup recorded at or after it — modified files
+ * are written back to their pre-edit content, files created after the target
+ * are deleted. This module is the same design, persisted on disk:
+ *
+ * - `tools/execute` captures the BEFORE state of each tracked write/edit call
+ *   (or "created" when the file did not exist) — the capture happens at the
+ *   around-dispatch stage, so an approval `ask` short-circuit cannot skip it
+ *   and a denied call never records.
+ * - The entry is committed to disk at `tools/post-execute` under the turn's
+ *   anchor seq: `<root>/<sessionId>/<anchorSeq>/<callId>.json`, carrying the
+ *   path and the before content (`before: null` = the file was created).
+ * - Because entries live on disk under the dsh data directory, they survive a
+ *   host restart, are bounded (the newest 100 anchor groups per session are
+ *   kept), and restores read/write the real file system with plain `node:fs`
+ *   — independent of the fs service.
+ *
+ * Restore semantics (identical to Claude Code): for every path with entries
+ * anchored at or after the target message, apply the EARLIEST entry — write
+ * the before content back, or delete the file when that entry recorded a
+ * creation. Symbolic links are skipped and reported, never written through.
+ *
+ * @module dsh-rewind/snapshot
+ */
+/** Default store root: the dsh data directory. */
+export declare const DEFAULT_SNAPSHOT_ROOT: string;
+/** Environment variable overriding the store root (tests, exotic homes). */
+export declare const SNAPSHOT_ROOT_ENV = "DSH_REWIND_SNAPSHOT_DIR";
+/** Number of newest anchor groups (user messages) kept per session. */
+export declare const MAX_ANCHOR_GROUPS = 100;
+/** One committed before-backup, keyed by tool call. */
+export interface CheckpointEntry {
+    readonly callId: string;
+    /** Seq of the user message anchoring the turn in which the change happened. */
+    readonly anchorSeq: number;
+    /** Resolved display path (absolute) of the tracked file. */
+    readonly path: string;
+    /** Full content before the change; null when the file was created. */
+    readonly before: string | null;
+    /** Epoch ms the entry was committed (stable ordering within a group). */
+    readonly time: number;
+}
+/** Per-file restore impact preview (`/rewind preview @seq both`). */
+export interface FileImpact {
+    readonly path: string;
+    /** `restore` = write the before content back; `delete` = remove the file. */
+    readonly action: 'restore' | 'delete';
+}
+/** Outcome of one restore pass. */
+export interface RestoreOutcome {
+    readonly restored: readonly string[];
+    readonly deleted: readonly string[];
+    readonly skipped: readonly string[];
+    readonly failed: readonly {
+        path: string;
+        message: string;
+    }[];
+}
+/** Deletes one file by its real path (node:fs, bypassing the fs service). */
+export type DeleteFile = (path: string) => Promise<void>;
+/**
+ * On-disk checkpoint store. Every write goes straight through `node:fs`, so a
+ * restore reliably lands on the real file system.
+ */
+export declare class SnapshotStore {
+    readonly root: string;
+    constructor(root?: string);
+    /** Absolute path of one anchor group directory. */
+    anchorDir(sessionId: string, anchorSeq: number): string;
+    /** Commit one before-backup under its turn's anchor group. */
+    recordEntry(sessionId: string, entry: Omit<CheckpointEntry, 'time'>): Promise<void>;
+    /**
+     * All committed entries anchored at or after `targetSeq`, newest first (for
+     * preview ordering). The boundary is inclusive: rewinding to a message also
+     * reverts the changes its own turn caused (the rewind cut removes that
+     * turn's assistant response and tool calls), so only entries anchored at
+     * earlier messages survive.
+     */
+    entriesAfter(sessionId: string, targetSeq: number): Promise<CheckpointEntry[]>;
+    /** Per-file restore impact for the earliest entry at/after the target. */
+    impactsAfter(sessionId: string, targetSeq: number): Promise<FileImpact[]>;
+    /**
+     * Restore the workspace to the target message's checkpoint: for every path
+     * with entries anchored at or after it, apply the EARLIEST entry — write the
+     * before content back, or delete the file when it was created after the
+     * target. Symbolic links are skipped (reported, never written through).
+     * Failures are per-file and never abort the pass.
+     */
+    restoreAfter(sessionId: string, targetSeq: number, deleteFile: DeleteFile): Promise<RestoreOutcome>;
+    /**
+     * Drop the session's oldest anchor groups beyond `keep` (default
+     * {@link MAX_ANCHOR_GROUPS}), deleting their whole directories.
+     */
+    prune(sessionId: string, keep?: number): Promise<void>;
+    /** True when a path exists on disk (used by tests and diagnostics). */
+    exists(path: string): Promise<boolean>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-rewind-plugin",
-  "version": "0.1.10",
+  "version": "0.2.0",
   "description": "DeepSeek Harness plugin: in-place conversation rewind in the same session window (Claude Code /rewind semantics) with optional workspace file restore",
   "keywords": [
     "deepseek-harness",

package/scripts/verify-host.mjs

@@ -2,49 +2,58 @@
 /**
  * Host-half verification: boots the built plugin (`lib/index.js`) on a real
  * cordis context with a real dsh-session, then drives the `/rewind` command
- * handler and the tools-pipeline ledger events end to end — no model, no UI.
+ * handler and the checkpoint pipeline end to end — no model, no UI. Files are
+ * real files under a temporary directory, so a restore is verified against
+ * actual on-disk content, and the checkpoint store root is overridden to that
+ * temporary directory.
  *
  * Run: `npm run build && node scripts/verify-host.mjs`
  *
  * What it proves:
  *  1. the plugin registers a `rewind` command on the ctx;
  *  2. `/rewind` (no args) withdraws the most recent user message;
- *  3. `/rewind @<seq> chat` (the button's call form) cuts the surface in-place (log untouched);
- *  4. the ledger captures through `tools/execute` (NOT pre-execute): a
- *     pre-execute `ask` short-circuit still gets captured after approval, and
- *     a denied call never captures (no pending leak);
- *  5. relative file paths resolve against the session cwd (fs-tools rule);
- *  6. `/rewind preview @<seq> both` reports the file impact;
- *  7. `/rewind @<seq> both` restores the file and reports it.
+ *  3. `/rewind @<seq> chat` cuts the surface in-place (log untouched);
+ *  4. a successful write through the tools pipeline commits a before-backup
+ *     under the turn's anchor seq;
+ *  5. a denied call never commits (no phantom entry in the store);
+ *  6. relative file paths resolve against the session cwd (fs-tools rule);
+ *  7. `/rewind preview @<seq> both` reports the checkpoint impact;
+ *  8. `/rewind @<seq> both` restores the real file to its pre-edit content
+ *     and deletes files created after the target;
+ *  9. a running agent is force-stopped before the rewind (not refused);
+ * 10. a cancel that never quiesces aborts the rewind (timeout path).
  */
 import { Context } from '@deepseek-ai/cordis'
 import { FileSystem, FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
 import { createAssistantMessage, createUserMessage } from '@deepseek-ai/dsh-llm'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import { mkdtemp, mkdir, rm, writeFile, readFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { apply as applyRewind } from '../lib/index.js'
 
 const aborted = () => new AbortController().signal
 
-/** In-memory fs double with session-cwd resolution (resolve/readText/writeText/processPath). */
+const tmpRoot = await mkdtemp(join(tmpdir(), 'dsh-rewind-verify-'))
+const wsDir = join(tmpRoot, 'ws')
+const snapRoot = join(tmpRoot, 'snapshots')
+await mkdir(wsDir, { recursive: true })
+
+/** Real-filesystem fs double: resolve returns the real display path. */
 class FakeFs extends FileSystem {
-  files = new Map()
   async resolve(path, opts = {}) {
     const displayPath = opts?.cwd !== undefined && !path.startsWith('/') ? join(opts.cwd, path) : path
     return { targetKey: FsTargetKey(displayPath), displayPath }
   }
   processPath(target) { return target.displayPath }
-  async readText(target) {
-    const content = this.files.get(target.displayPath)
-    if (content === undefined) throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' })
-    return content
+  async readText(target) { return readFile(target.displayPath, 'utf8') }
+  async writeText(target, content) { await writeFile(target.displayPath, content, 'utf8'); return { operation: 'update', version: FsVersion('v'), before: null, after: content } }
+  async stat(target) {
+    try { await readFile(target.displayPath); return { version: FsVersion('v'), type: 'file' } } catch { return undefined }
   }
-  async writeText(target, content) { this.files.set(target.displayPath, content); return { operation: 'update', version: FsVersion('v'), before: null, after: content } }
-  async stat(target) { return this.files.has(target.displayPath) ? { version: FsVersion('v'), type: 'file' } : undefined }
 }
 
 const fs = new FakeFs(new Context())
-fs.files.set('/workspace/a.txt', 'original content')
 
 const user = text => createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } })
 const assistant = text => createAssistantMessage({ content: [{ type: 'text', text }], source: { provider: 'test', model: 'test' } })
@@ -73,10 +82,20 @@ ctx.provide('commands', {
   },
 })
 ctx.provide('fs', fs)
-applyRewind(ctx)
+applyRewind(ctx, { snapshotDir: snapRoot })
 
 const call = (agentOf, rawInput) => registered.handler({ commandId: Symbol('cid'), agent: agentOf, rawInput, signal: aborted() })
 
+/** Simulate one tracked tool call: before-capture, dispatch writes the file, post-execute commits. */
+async function runWrite(agentOf, callId, filePath, content) {
+  const exec = { callId, name: 'write', arguments: { file_path: filePath, content }, agent: agentOf, signal: aborted() }
+  await ctx.waterfall('tools/execute', exec, async () => {
+    await fs.writeText({ targetKey: FsTargetKey(filePath), displayPath: filePath }, content)
+    return { isError: false, content: [] }
+  })
+  await ctx.waterfall('tools/post-execute', exec, { isError: false, content: [] }, async () => ({ kind: 'accept' }))
+}
+
 let failures = 0
 const check = (name, ok, detail) => {
   console.log(`${ok ? 'ok  ' : 'FAIL'} ${name}${ok ? '' : ` — ${detail}`}`)
@@ -106,74 +125,82 @@ check('rewind chat succeeds', chatResult.kind === 'success', chatResult.text)
 check('surface cut to [0,1,marker] (target withdrawn)', after.length === 3 && after[0] === 0 && after[1] === 1 && after[2] > 3, `before ${JSON.stringify(before)} -> after ${JSON.stringify(after)}`)
 check('log stays append-only (5 events)', paramSession.events.length === 5, `events=${paramSession.events.length}`)
 
-const writeExec = (callId, filePath, content) => ({
-  callId, name: 'write', arguments: { file_path: filePath, content }, agent, signal: aborted(),
-})
-
-// 4. a pre-execute `ask` short-circuit (dsh-edit-approval) must not skip the
-//    capture: capture happens in tools/execute, which runs after approval.
+// 4. a tracked write commits a before-backup; rewinding both restores the
+//    real file and deletes files created after the target
 {
-  const exec = writeExec('c1', '/workspace/a.txt', 'rewritten')
-  // Another plugin asks at pre-execute; the user then allows it.
-  const gate = await ctx.waterfall('tools/pre-execute', exec, async () => ({ kind: 'ask', reason: 'approve me' }))
-  check('pre-execute gate asks', gate.kind === 'ask', JSON.stringify(gate))
-  // Approved → dispatch stage runs: capture fires here.
-  await ctx.waterfall('tools/execute', exec, async () => ({ isError: false, content: [] }))
-  await fs.writeText({ targetKey: FsTargetKey('/workspace/a.txt'), displayPath: '/workspace/a.txt' }, 'rewritten')
-  await ctx.waterfall('tools/post-execute', exec, { isError: false, content: [] }, async () => ({ kind: 'accept' }))
-  check('file mutated on disk', fs.files.get('/workspace/a.txt') === 'rewritten', fs.files.get('/workspace/a.txt'))
+  const aPath = join(wsDir, 'a.txt')
+  await writeFile(aPath, 'original content', 'utf8')
+  // The next user message anchors the turn that will edit a.txt (seq 5).
+  session.append('user/message', user('third question'), { surfaceOp: 'append' })
+  const anchorSeq = 5
+  await runWrite(agent, 'c1', aPath, 'rewritten') // before-capture: 'original content'
+  const createdPath = join(wsDir, 'created.txt')
+  await runWrite(agent, 'c2', createdPath, 'new') // file did not exist: before-capture = created
+  await writeFile(aPath, 'v3', 'utf8') // later edit lands after the backups
+
+  const preview = await call(agent, `preview @${anchorSeq} both`)
+  check('preview reports the file impact', preview.kind === 'success' && preview.text.includes(aPath) && preview.text.includes('还原'), preview.text)
+
+  const both = await call(agent, `@${anchorSeq} both`)
+  check('rewind both succeeds', both.kind === 'success' && both.text.includes('还原 1 个文件') && both.text.includes('删除 1 个文件'), both.text)
+  check('modified file restored to pre-edit content', await readFile(aPath, 'utf8') === 'original content', await readFile(aPath, 'utf8'))
+  let createdGone = false
+  try { await readFile(createdPath, 'utf8') } catch { createdGone = true }
+  check('created file deleted', createdGone, `exists=${!createdGone}`)
 }
 
-// 5. a denied call never captures (no pending leak: nothing recorded after it)
+// 5. a denied call never commits (no phantom entry)
 {
-  const exec = writeExec('c2', '/workspace/a.txt', 'denied write')
-  const gate = await ctx.waterfall('tools/pre-execute', exec, async () => ({ kind: 'deny', reason: 'no' }))
-  check('pre-execute gate denies', gate.kind === 'deny', JSON.stringify(gate))
-  // Denied calls do not dispatch: post-execute must record nothing for c2.
+  const deniedPath = join(wsDir, 'denied.txt')
+  await writeFile(deniedPath, 'x', 'utf8')
+  const exec = { callId: 'c3', name: 'write', arguments: { file_path: deniedPath, content: 'denied write' }, agent, signal: aborted() }
+  await ctx.waterfall('tools/pre-execute', exec, async () => ({ kind: 'deny', reason: 'no' }))
   await ctx.waterfall('tools/post-execute', exec, { isError: true, error: { message: 'denied', info: { name: 'x', code: 'y' } }, content: [] }, async () => ({ kind: 'accept' }))
+  const preview = await call(agent, 'preview @5 both')
+  check('denied call is not in the impact list', !preview.text.includes(deniedPath), preview.text)
 }
 
 // 6. relative paths resolve against the session cwd (fs-tools rule)
 {
-  const cwdSession = buildSession('verify-cwd', '/workspace')
+  const cwdSession = buildSession('verify-cwd', wsDir)
   const cwdAgent = { id: cwdSession.id, session: cwdSession, status: 'idle' }
-  fs.files.set('/workspace/rel.txt', 'relative original')
-  const exec = { callId: 'c3', name: 'write', arguments: { file_path: 'rel.txt', content: 'relative new' }, agent: cwdAgent, signal: aborted() }
-  await ctx.waterfall('tools/execute', exec, async () => ({ isError: false, content: [] }))
-  await fs.writeText({ targetKey: FsTargetKey('/workspace/rel.txt'), displayPath: '/workspace/rel.txt' }, 'relative new')
-  await ctx.waterfall('tools/post-execute', exec, { isError: false, content: [] }, async () => ({ kind: 'accept' }))
-  // Rewind to seq 2 in the cwd session must report the cwd-resolved path.
-  const preview = await call(cwdAgent, 'preview @2 both')
-  check('preview resolves relative path via session cwd', preview.kind === 'success' && preview.text.includes('/workspace/rel.txt'), preview.text)
-  const both = await call(cwdAgent, '@2 both')
-  check('both restores cwd-resolved file', both.kind === 'success' && fs.files.get('/workspace/rel.txt') === 'relative original', both.text)
+  const relPath = join(wsDir, 'rel.txt')
+  await writeFile(relPath, 'relative original', 'utf8')
+  cwdSession.append('user/message', user('relative question'), { surfaceOp: 'append' })
+  await runWrite(cwdAgent, 'c4', 'rel.txt', 'relative new') // relative path
+
+  const preview = await call(cwdAgent, 'preview @4 both')
+  check('relative path resolved via session cwd', preview.kind === 'success' && preview.text.includes(relPath), preview.text)
+  const both = await call(cwdAgent, '@4 both')
+  check('both restores cwd-resolved file', both.kind === 'success' && await readFile(relPath, 'utf8') === 'relative original', both.text)
 }
 
-// 7. preview reports the impact (rewind to seq 0 — still on the surface after
-//    the earlier withdraw — reverts the anchor-0 write)
-const previewResult = await call(agent, 'preview @0 both')
-check('preview shows file impact', previewResult.kind === 'success' && previewResult.text.includes('/workspace/a.txt'), previewResult.text)
-
-// 8. both mode restores the file
-const bothResult = await call(agent, '@0 both')
-check('rewind both restores file', bothResult.kind === 'success' && bothResult.text.includes('还原 1 个文件'), bothResult.text)
-check('file content restored', fs.files.get('/workspace/a.txt') === 'original content', fs.files.get('/workspace/a.txt'))
-
-// 9. a running agent is force-stopped before the rewind (not refused)
-const runningSession = buildSession('verify-running')
-const running = {
-  ...{ id: runningSession.id, session: runningSession, status: 'idle' }, status: 'running',
-  cancel: () => { cancelled = true; running.status = 'idle' },
+// 7. preview on a message with no recorded changes reports none
+{
+  const cleanSession = buildSession('verify-norec')
+  const cleanAgent = { id: cleanSession.id, session: cleanSession, status: 'idle' }
+  const previewResult = await call(cleanAgent, 'preview @2 both')
+  check('preview with no entries reports no changes', previewResult.kind === 'success' && previewResult.text.includes('无需还原文件'), previewResult.text)
 }
-let cancelled = false
-const runningResult = await registered.handler({ commandId: Symbol('cid'), agent: running, rawInput: '@2 chat', signal: aborted() })
-check('running agent is cancelled first', cancelled === true, `cancelled=${cancelled}`)
-check('rewind succeeds after stop', runningResult.kind === 'success', runningResult.text)
 
-// 9b. a cancel that never quiesces aborts the rewind (timeout path)
-const stuck = { ...{ id: runningSession.id, session: runningSession, status: 'idle' }, status: 'running', cancel: () => {} }
-const stuckResult = await registered.handler({ commandId: Symbol('cid'), agent: stuck, rawInput: '@2 chat', signal: aborted() })
-check('stuck agent aborts rewind', stuckResult.kind === 'error', stuckResult.text)
+// 8. a running agent is force-stopped before the rewind (not refused)
+{
+  const runningSession = buildSession('verify-running')
+  let cancelled = false
+  const running = { id: runningSession.id, session: runningSession, status: 'running', cancel: () => { cancelled = true; running.status = 'idle' } }
+  const runningResult = await call(running, '@2 chat')
+  check('running agent is cancelled first', cancelled === true, `cancelled=${cancelled}`)
+  check('rewind succeeds after stop', runningResult.kind === 'success', runningResult.text)
+}
+
+// 9. a cancel that never quiesces aborts the rewind (timeout path)
+{
+  const stuckSession = buildSession('verify-stuck')
+  const stuck = { id: stuckSession.id, session: stuckSession, status: 'running', cancel: () => {} }
+  const stuckResult = await call(stuck, '@2 chat')
+  check('stuck agent aborts rewind', stuckResult.kind === 'error', stuckResult.text)
+}
 
+await rm(tmpRoot, { recursive: true, force: true })
 console.log(failures === 0 ? '\nverify-host: all checks passed' : `\nverify-host: ${failures} check(s) FAILED`)
 process.exit(failures === 0 ? 0 : 1)

package/lib/types/ledger.d.ts

@@ -1,88 +0,0 @@
-/**
- * In-memory change ledger: records every write-class tool mutation that
- * happened while the plugin was running, so a "rewind conversation and code"
- * can reverse the changes that followed a target message.
- *
- * Scope (v0.1): the ledger covers only `write` / `edit` / `str_replace_editor`
- * mutations observed through the tools pipeline while the plugin is loaded.
- * Changes made by bash or external programs are not recorded and cannot be
- * restored; a git-first snapshot layer is a v2 option.
- *
- * @module dsh-rewind/ledger
- */
-import type { FileSystem } from '@deepseek-ai/dsh-fs';
-/** One recorded write-class mutation. */
-export interface LedgerEntry {
-    /** Tool that made the change: `write` | `edit` | `str_replace_editor`. */
-    readonly toolName: string;
-    /** Seq of the user message anchoring the turn in which the change happened. */
-    readonly anchorSeq: number;
-    /** Display path (model/UI-facing), as resolved at record time. */
-    readonly path: string;
-    /** Full file content before the change; undefined when the file was created. */
-    readonly before: string | undefined;
-    /** Full file content after the change. */
-    readonly after: string;
-}
-/** Unique per-file impact of rewinding past a target message. */
-export interface FileImpact {
-    readonly path: string;
-    /** `restore` = the file existed before the target; `delete` = created after it. */
-    readonly action: 'restore' | 'delete';
-}
-/** Result of one reverse restore pass. */
-export interface RestoreOutcome {
-    readonly restored: readonly string[];
-    readonly deleted: readonly string[];
-    readonly failed: readonly {
-        path: string;
-        message: string;
-    }[];
-}
-/** Deletes one file by its process path (the host supplies the backend-appropriate delete). */
-export type DeleteFile = (processPath: string) => Promise<void>;
-/**
- * Per-session cap on recorded entries. The ledger is intentionally bounded so
- * an extremely long session cannot grow one entry list without limit; the
- * oldest entries are dropped first, so rewinds to very early messages in a
- * pathological session may lose the earliest file history (a declared
- * tradeoff, see README).
- */
-export declare const MAX_LEDGER_ENTRIES = 2000;
-/**
- * Append-only change ledger. Entries are recorded in commit order; a rewind
- * replays them in reverse for the affected range. Bounded per session to
- * {@link MAX_LEDGER_ENTRIES} (oldest dropped first).
- */
-export declare class RewindLedger {
-    private readonly entries;
-    /** Record one committed mutation, dropping the oldest entry when over the cap. */
-    record(entry: LedgerEntry): void;
-    /**
-     * All entries anchored at or after `targetSeq`, newest first. The boundary
-     * is inclusive: rewinding to a message also reverts the changes its own
-     * turn caused (the rewind cut removes that turn's assistant response and
-     * tool calls), so only changes anchored at earlier messages survive.
-     */
-    changesAfter(targetSeq: number): readonly LedgerEntry[];
-    /**
-     * Unique per-file impact for preview. A file whose earliest affected change
-     * created it (`before === undefined`) is deleted on restore; any other file
-     * is written back to its pre-target content.
-     */
-    impactsAfter(targetSeq: number): readonly FileImpact[];
-    /**
-     * Reverse every change anchored at or after `targetSeq`. Each entry writes
-     * its pre-change content back; a file that did not exist before the target
-     * is deleted instead. Failures are collected per file and never abort the pass.
-     * @param fs - the filesystem service (resolve/readText/writeText/processPath).
-     * @param deleteFile - backend-appropriate file deletion by process path.
-     * @param targetSeq - the rewind target; only later changes are reverted.
-     * @param options - session workspace cwd (relative ledger paths resolve
-     *   against it, mirroring the fs tools) and an optional abort signal.
-     */
-    restoreAfter(fs: FileSystem, deleteFile: DeleteFile, targetSeq: number, options?: {
-        cwd?: string;
-        signal?: AbortSignal;
-    }): Promise<RestoreOutcome>;
-}