dsh-rewind-plugin 0.5.0 → 0.6.0

package/docs/snapshot-auto-cleanup.zh.md

@@ -1,42 +1,57 @@
-# 快照自动清理
+# 快照清理
 
-回退插件为每次被跟踪的文件修改写入一份磁盘 `before` 备份，并按其锚点消息分组。快照在**同一会话**内去重、且保留最近 100 组锚点，但跨**已不再活跃的会话**时存储仍会无界增长。`snapshot-auto-cleanup` 是**可选**的全局策略（默认关闭）：把**长期不活跃**（失活超过可配置阈值）的会话快照**整目录**移除。
+插件会在每次修改文件前保存一份备份，方便你把代码回退到之前的状态。这些备份叫**快照**，按消息分组、按会话存放。
 
-它只会移除**长期不活跃**会话的整个快照目录，绝不触碰活动会话的快照、绝不触碰对话日志，也保留仍在阈值内的快照数据。
+`/snapshot-auto-cleanup` 帮你管理这些快照——既可以回收旧会话占用的磁盘，也可以清空**当前**会话、让它从"现在"重新开始记录回退历史。
+
+## 它能做什么
+
+**自动清理**（默认关闭）：插件会记住哪些会话你已不再使用，并定期移除它们的快照以节省磁盘。它**绝不**触碰你当前活跃的会话，也**绝不**触碰你的对话。
+
+**手动：**即使自动清理是关闭的，你也可以自己执行清理：
+
+- `/snapshot-auto-cleanup run [--apply]` — 先预演，再真正移除你已有一阵子没用的会话的快照。
+- `/snapshot-auto-cleanup run --current [--apply]` — 先预演，再真正清空**当前**会话的快照。这会让它从"现在"重新开始记录回退历史（你的对话不受影响）。若此刻有正在进行中的回合，插件会先暂停它，再清空。
 
 ## 命令
 
 ```
-/snapshot-auto-cleanup                 查看状态（是否开启、max-age、配置路径）
-/snapshot-auto-cleanup on|off          开启/关闭自动清理
-/snapshot-auto-cleanup max-age <天数>  设置失活阈值（正整数）
-/snapshot-auto-cleanup run             预演：列出将移除哪些会话
-/snapshot-auto-cleanup run --apply     真正移除这些会话
+/snapshot-auto-cleanup                       查看当前设置
+/snapshot-auto-cleanup on|off                开启/关闭自动清理
+/snapshot-auto-cleanup max-age <天数>        会话失活多少天后移除其快照
+/snapshot-auto-cleanup run                   预演：看自动清理会移除什么
+/snapshot-auto-cleanup run --apply           真正移除这些快照
+/snapshot-auto-cleanup run --current         预演：看清空本会话快照会怎样
+/snapshot-auto-cleanup run --current --apply 真正清空本会话快照
 ```
 
-`run` 是手动逃生舱，无论自动清理是否为 `on` 都能用；默认只预演，加 `--apply` 才执行。
+`run` 一开始总是预演；加 `--apply` 才真正执行。`run` 无论自动清理是否开启都能用。
 
-## 配置文件
+## 设置
 
-策略持久化到 `~/.dsh/snapshot-cleanup.json`：
+设置保存在 `<dsh home>/snapshot-cleanup.json`：
 
 ```json
 { "enabled": false, "maxAgeDays": 30 }
 ```
 
 - `enabled` — 是否运行自动清理（默认 `false`）。
-- `maxAgeDays` — 失活多少天后移除某**长期不活跃**会话的快照目录（默认 `30`；`0`/负数会被拒绝，因此损坏的配置不可能导致"删除一切"）。
+- `maxAgeDays` — 会话失活多少天后移除其快照（默认 `30`）。只接受正数，因此一个损坏的设置永远不可能"删掉一切"。
+
+你可以用环境变量 `DSH_SNAPSHOT_CLEANUP_CONFIG` 指向别的文件。该文件只在运行 `/snapshot-auto-cleanup` 时写入；文件缺失按安全默认值（关闭）处理。
+
+## 自动清理何时运行
+
+自动清理每次运行（宿主启动）**最多检查一次**，发生在首次活动时（你发出一条消息或某次工具调用完成），且仅在**已开启**且距上次检查**已满 24 小时**时才执行。这个 24 小时时钟会写入 `<dsh home>/snapshot-cleanup-last-sweep.json`，重启不会重置。它后台运行，从不阻塞你在做的事。
 
-可用环境变量 `DSH_SNAPSHOT_CLEANUP_CONFIG` 覆盖路径。该文件只由 `/snapshot-auto-cleanup` 命令写入。文件缺失按安全默认（关闭）处理；缺失或损坏会令一次清扫**fail-closed**（不删任何东西）并写入警告，再次运行命令时会有所提示。
+想让改动立即生效，请用 `run`；自动清理要到下次运行才会采用新设置。
 
-## 运行时机
+## 安全
 
-24 小时窗口锚定在**持久化**的上次清扫时间（`~/.dsh/snapshot-cleanup-last-sweep.json`）上，因此宿主重启不会重置：自动清扫在**每次运行只检查一次**，于某个窗口的首次会话活动（一条用户消息或一次工具调用完成）时执行，且仅在**已启用**且距上次清扫 **>=24 小时**时才清理。它后台运行，从不阻塞触发它的活动。由于每次运行只检查一次，想让改动立即生效最好用 `/snapshot-auto-cleanup run`；手动编辑配置文件（或在本次运行的首次活动之后才开启）会到下次运行才生效。
+- 只会移除回退用的**快照**（那份文件备份）。你的对话绝不会被动到，插件也绝不改写或删除你的会话历史。
+- 自动清理**永不**移除你**当前活跃**会话的快照——只清理已失活超过阈值的会话。
+- `run --current` 会清空当前会话的快照。这对该会话的文件回退历史是**不可逆**的：你无法回退到清空之前的代码状态，但你的对话保持完整，会话会从"现在"开始重新记录快照。
 
-## 安全与边界
+## 已知限制
 
-- 只移除**长期不活跃**会话的整目录；活动会话与对话日志永不触碰。
-- "不活跃"以 mtime 判定：仍在写入的会话会不断把"最新成员"时间戳往后推，因此永远到不了可被清理的失活阈值。
-- 去重 `ref` 链接是会话内相对的，所以移除整目录不会让别处产生悬空链接。
-- 权衡：开启自动清理后，某个长时间闲置才被重新打开的会话，只能从剩余（最近 100 组）锚点回退，旧快照已不存在；对话日志永不受影响。
-- 手动删除整个存储目录依然安全（下次捕获时自动重建）；自动清理只是把这种删除限定到长期不活跃的会话。
+插件每个会话只保留**最近 100 条消息**的快照。若你在一个很长的会话里多次回退或压缩，这 100 个名额常会被"已经无法再回退到"的消息占满，你可能无法回退到想要的位置。（Claude Code 也是同样行为。）想恢复到一个干净状态，运行 `/snapshot-auto-cleanup run --current --apply` 清空当前会话、重新开始。

package/lib/client.js

@@ -986,8 +986,7 @@ var zh = {
   "popover.impact.restore": "\u8FD8\u539F {path}",
   "popover.impact.delete": "\u5220\u9664 {path}",
   "popover.confirm": "\u786E\u8BA4\u56DE\u9000",
-  "popover.back": "\u8FD4\u56DE",
-  "guard.hint": "/rewind \u624B\u52A8\u8F93\u5165\u4E0D\u63A5\u53D7\u53C2\u6570\uFF0C\u8BF7\u76F4\u63A5\u8F93\u5165 /rewind \u6253\u5F00\u56DE\u9000\u83DC\u5355"
+  "popover.back": "\u8FD4\u56DE"
 };
 var en = {
   "button.aria": "Rewind to this message",
@@ -1013,8 +1012,7 @@ var en = {
   "popover.impact.restore": "Restore {path}",
   "popover.impact.delete": "Delete {path}",
   "popover.confirm": "Confirm rewind",
-  "popover.back": "Back",
-  "guard.hint": "/rewind takes no typed arguments \u2014 enter /rewind to open the rewind picker."
+  "popover.back": "Back"
 };
 
 // src/client/index.ts
@@ -1069,8 +1067,7 @@ function apply(ctx) {
       const card = textarea?.closest("[data-composer-card]");
       return card ?? textarea ?? document.body;
     };
-    yield commandUi.decorate({
-      name: "rewind",
+    const rewindPopupSpec = {
       // The picker exists exactly while the surface has a reachable user
       // message: a fresh session (no candidates) falls through to the host
       // command, which fails with "no user messages" — matching the harness's
@@ -1105,66 +1102,12 @@ function apply(ctx) {
           });
         }
       }
-    });
-    const PARAM_REWIND = /^\s*\/rewind\s+\S+/i;
-    const composerTextarea = () => document.querySelector(COMPOSER_SELECTOR2);
-    const hasParamRewindDraft = () => {
-      const textarea = composerTextarea();
-      return textarea !== null && PARAM_REWIND.test(textarea.value);
-    };
-    let guardHintEl = null;
-    let guardHintTimer;
-    const showGuardHint = () => {
-      if (guardHintEl !== null) guardHintEl.remove();
-      if (guardHintTimer !== void 0) window.clearTimeout(guardHintTimer);
-      const textarea = composerTextarea();
-      if (textarea === null) return;
-      const card = textarea.closest("[data-composer-card]");
-      const hint = document.createElement("div");
-      hint.className = "dsh-rewind-guard-hint";
-      hint.setAttribute("role", "status");
-      hint.textContent = t("guard.hint");
-      document.body.appendChild(hint);
-      const rect = card instanceof HTMLElement ? card.getBoundingClientRect() : textarea.getBoundingClientRect();
-      hint.style.left = `${Math.round(rect.left)}px`;
-      hint.style.bottom = `${Math.round(window.innerHeight - rect.top + 8)}px`;
-      guardHintEl = hint;
-      guardHintTimer = window.setTimeout(() => {
-        hint.remove();
-        if (guardHintEl === hint) guardHintEl = null;
-        guardHintTimer = void 0;
-      }, 3200);
-    };
-    const onParamRewindSubmit = (event) => {
-      if (!hasParamRewindDraft()) return;
-      event.preventDefault();
-      event.stopPropagation();
-      showGuardHint();
-    };
-    const onKeyDownGuard = (event) => {
-      if (event.key !== "Enter" || event.shiftKey || event.isComposing) return;
-      onParamRewindSubmit(event);
     };
-    const onClickGuard = (event) => {
-      if (event.button !== 0 || !hasParamRewindDraft()) return;
-      const target = event.target;
-      if (!(target instanceof Element)) return;
-      const button = target.closest("button");
-      if (button === null) return;
-      const card = button.closest("[data-composer-card]");
-      if (card === null) return;
-      const all = card.querySelectorAll("button");
-      if (all[all.length - 1] !== button) return;
-      if (button.querySelector("rect") !== null) return;
-      onParamRewindSubmit(event);
-    };
-    document.addEventListener("keydown", onKeyDownGuard, true);
-    document.addEventListener("click", onClickGuard, true);
+    for (const name2 of ["rewind", "undo"]) {
+      yield commandUi.decorate({ name: name2, ...rewindPopupSpec });
+    }
+    const composerTextarea = () => document.querySelector(COMPOSER_SELECTOR2);
     yield () => {
-      document.removeEventListener("keydown", onKeyDownGuard, true);
-      document.removeEventListener("click", onClickGuard, true);
-      if (guardHintEl !== null) guardHintEl.remove();
-      if (guardHintTimer !== void 0) window.clearTimeout(guardHintTimer);
       style.remove();
     };
   }, "dsh-rewind client lifecycle");

package/lib/index.js

@@ -8,7 +8,7 @@ var en = {
   "usage.title": "Usage:",
   "usage.noArgs": "  /rewind                       (no args) withdraw the most recent user message",
   "usage.seq": "  /rewind @<seq> chat|both      rewind to the given message (chat = conversation only / both = conversation + files)",
-  "usage.blocked": "  Manual /rewind input is intercepted; use the \u21B6 button next to a message",
+  "usage.blocked": "  /rewind or /undo               open the rewind picker",
   "describeTarget.seq": "seq {seq}",
   "describeTarget.index": "message {index}",
   "plan.rewinding": "Rewind to seq {targetSeq}, removing {count} node(s) from the model context (conversation log kept).",
@@ -32,7 +32,7 @@ var en = {
   "chooseMode": "Rewind to {target}. Choose a mode:\n  /rewind {target} chat  conversation only\n  /rewind {target} both  conversation + file restore",
   "command.description": "Rewind the conversation back to an earlier user message (optionally restoring files)",
   "cleanup.description": "Manage automatic cleanup of session snapshot backups",
-  "cleanup.inputHint": "on | off | max-age <days> | run [--apply] | status",
+  "cleanup.inputHint": "on | off | max-age <days> | run [--apply] [--current]",
   "cleanup.status": "Auto-cleanup: {state}. Max age: {days} day(s). Config: {path} ({present}).",
   "cleanup.enabled": "enabled",
   "cleanup.disabled": "disabled",
@@ -41,19 +41,24 @@ var en = {
   "cleanup.onOk": "Auto-cleanup enabled.",
   "cleanup.offOk": "Auto-cleanup disabled \u2014 all snapshots kept.",
   "cleanup.maxAgeOk": "Auto-cleanup max age set to {days} day(s).",
-  "cleanup.cfgInvalid": "Snapshot cleanup config invalid: {detail}. Using the safe default (disabled).",
+  "cleanup.cfgInvalid": 'Snapshot cleanup config invalid: {detail}. Nothing was executed; use "on|off|max-age" to reset the config.',
   "cleanup.saveFailed": "Could not save cleanup config: {detail}.",
-  "cleanup.runDry": "Dry-run: would remove {deleted} session snapshot backup(s). Re-run with --apply to delete.",
+  "cleanup.runDry": "Dry-run: would remove {deleted} session snapshot backup(s), freeing {freed} bytes. Re-run with --apply to delete.",
   "cleanup.runApply": "Removed {deleted} session snapshot backup(s), freeing {freed} bytes; {kept} kept, {remaining} bytes remain.",
   "cleanup.runFailed": "Cleanup failed: {detail}.",
   "cleanup.skipped": "({skipped} active session(s) skipped.)",
-  "cleanup.usage": "Usage:\n  /snapshot-auto-cleanup                 show status\n  /snapshot-auto-cleanup on|off          enable/disable auto-cleanup\n  /snapshot-auto-cleanup max-age <days>  set the idle cutoff\n  /snapshot-auto-cleanup run [--apply]   dry-run, or execute with --apply"
+  "cleanup.clearDry": "Dry-run: would clear {entries} snapshot(s) of the current session, freeing {bytes} bytes. Re-run with --apply to delete.",
+  "cleanup.clearApply": "Cleared {entries} snapshot(s) of the current session, freeing {bytes} bytes. This session now records snapshots fresh from its current state.",
+  "cleanup.clearActive": "Could not clear session {sessionId}: the session is still running and could not be stopped. Try again once it is idle.",
+  "cleanup.clearCancelled": "Clear cancelled.",
+  "cleanup.clearFailed": "Could not clear session {sessionId}: {detail}.",
+  "cleanup.usage": "Usage:\n  /snapshot-auto-cleanup                 show status\n  /snapshot-auto-cleanup on|off          enable/disable auto-cleanup\n  /snapshot-auto-cleanup max-age <days>  set the idle cutoff\n  /snapshot-auto-cleanup run [--apply]   dry-run, or execute with --apply\n  /snapshot-auto-cleanup run --current [--apply]   dry-run/clear this session's snapshots"
 };
 var zh = {
   "usage.title": "\u7528\u6CD5\uFF1A",
   "usage.noArgs": "  /rewind                       \uFF08\u65E0\u53C2\u6570\uFF09\u64A4\u56DE\u6700\u8FD1\u4E00\u6761\u7528\u6237\u6D88\u606F",
   "usage.seq": "  /rewind @<seq> chat|both      \u56DE\u9000\u5230\u6307\u5B9A\u6D88\u606F\uFF08chat \u4EC5\u5BF9\u8BDD / both \u5BF9\u8BDD+\u6587\u4EF6\uFF09",
-  "usage.blocked": "  \u624B\u52A8\u8F93\u5165 /rewind \u4F1A\u88AB\u62E6\u622A\uFF0C\u8BF7\u4F7F\u7528\u6D88\u606F\u65C1\u7684\u300C\u56DE\u9000\u300D\u6309\u94AE",
+  "usage.blocked": "  /rewind \u6216 /undo               \u6253\u5F00\u56DE\u9000\u9009\u62E9\u9762\u677F",
   "describeTarget.seq": "seq {seq}",
   "describeTarget.index": "\u7B2C {index} \u6761\u6D88\u606F",
   "plan.rewinding": "\u5C06\u56DE\u9000\u5230 seq {targetSeq}\uFF0C\u4ECE\u6A21\u578B\u4E0A\u4E0B\u6587\u79FB\u9664 {count} \u4E2A\u8282\u70B9\uFF08\u5BF9\u8BDD\u65E5\u5FD7\u4FDD\u7559\uFF09\u3002",
@@ -77,7 +82,7 @@ var zh = {
   "chooseMode": "\u5C06\u56DE\u9000\u5230 {target}\u3002\u9009\u62E9\u6A21\u5F0F\uFF1A\n  /rewind {target} chat  \u4EC5\u56DE\u9000\u5BF9\u8BDD\n  /rewind {target} both  \u56DE\u9000\u5BF9\u8BDD\u5E76\u8FD8\u539F\u6587\u4EF6",
   "command.description": "\u5728\u540C\u7A97\u53E3\u5185\u5C06\u5BF9\u8BDD\u56DE\u9000\u5230\u66F4\u65E9\u7684\u7528\u6237\u6D88\u606F\uFF08\u53EF\u540C\u65F6\u8FD8\u539F\u6587\u4EF6\uFF09",
   "cleanup.description": "\u7BA1\u7406\u4F1A\u8BDD\u5FEB\u7167\u5907\u4EFD\u7684\u81EA\u52A8\u6E05\u7406",
-  "cleanup.inputHint": "on | off | max-age <\u5929\u6570> | run [--apply] | status",
+  "cleanup.inputHint": "on | off | max-age <\u5929\u6570> | run [--apply] [--current]",
   "cleanup.status": "\u81EA\u52A8\u6E05\u7406\uFF1A{state}\u3002\u6700\u5927\u4FDD\u7559\u5929\u6570\uFF1A{days} \u5929\u3002\u914D\u7F6E\uFF1A{path}\uFF08{present}\uFF09\u3002",
   "cleanup.enabled": "\u5DF2\u5F00\u542F",
   "cleanup.disabled": "\u5DF2\u5173\u95ED",
@@ -86,13 +91,18 @@ var zh = {
   "cleanup.onOk": "\u5DF2\u5F00\u542F\u81EA\u52A8\u6E05\u7406\u3002",
   "cleanup.offOk": "\u5DF2\u5173\u95ED\u81EA\u52A8\u6E05\u7406\u2014\u2014\u4FDD\u7559\u5168\u90E8\u5FEB\u7167\u3002",
   "cleanup.maxAgeOk": "\u5DF2\u5C06\u81EA\u52A8\u6E05\u7406\u7684\u6700\u5927\u4FDD\u7559\u5929\u6570\u8BBE\u4E3A {days} \u5929\u3002",
-  "cleanup.cfgInvalid": "\u5FEB\u7167\u6E05\u7406\u914D\u7F6E\u65E0\u6548\uFF1A{detail}\u3002\u5DF2\u4F7F\u7528\u5B89\u5168\u9ED8\u8BA4\u503C\uFF08\u5173\u95ED\uFF09\u3002",
+  "cleanup.cfgInvalid": "\u5FEB\u7167\u6E05\u7406\u914D\u7F6E\u65E0\u6548\uFF1A{detail}\u3002\u672A\u6267\u884C\u4EFB\u4F55\u64CD\u4F5C\uFF1B\u8BF7\u7528\u300Con|off|max-age\u300D\u91CD\u8BBE\u914D\u7F6E\u4EE5\u4FEE\u590D\u3002",
   "cleanup.saveFailed": "\u65E0\u6CD5\u4FDD\u5B58\u6E05\u7406\u914D\u7F6E\uFF1A{detail}\u3002",
-  "cleanup.runDry": "\u9884\u6F14\uFF1A\u5C06\u5220\u9664 {deleted} \u4E2A\u4F1A\u8BDD\u7684\u5FEB\u7167\u5907\u4EFD\u3002\u52A0 --apply \u6B63\u5F0F\u5220\u9664\u3002",
+  "cleanup.runDry": "\u9884\u6F14\uFF1A\u5C06\u5220\u9664 {deleted} \u4E2A\u4F1A\u8BDD\u7684\u5FEB\u7167\u5907\u4EFD\uFF0C\u91CA\u653E {freed} \u5B57\u8282\u3002\u52A0 --apply \u6B63\u5F0F\u5220\u9664\u3002",
   "cleanup.runApply": "\u5DF2\u5220\u9664 {deleted} \u4E2A\u4F1A\u8BDD\u7684\u5FEB\u7167\u5907\u4EFD\uFF0C\u91CA\u653E {freed} \u5B57\u8282\uFF1B\u4FDD\u7559 {kept} \u4E2A\uFF0C\u5269\u4F59 {remaining} \u5B57\u8282\u3002",
   "cleanup.runFailed": "\u6E05\u7406\u5931\u8D25\uFF1A{detail}\u3002",
   "cleanup.skipped": "\uFF08\u8DF3\u8FC7\u4E86 {skipped} \u4E2A\u6D3B\u52A8\u4F1A\u8BDD\u3002\uFF09",
-  "cleanup.usage": "\u7528\u6CD5\uFF1A\n  /snapshot-auto-cleanup                 \u67E5\u770B\u72B6\u6001\n  /snapshot-auto-cleanup on|off          \u5F00\u542F/\u5173\u95ED\u81EA\u52A8\u6E05\u7406\n  /snapshot-auto-cleanup max-age <\u5929\u6570>  \u8BBE\u7F6E\u5931\u6D3B\u9608\u503C\uFF08\u5929\uFF09\n  /snapshot-auto-cleanup run [--apply]   \u9884\u6F14\uFF0C\u6216\u52A0 --apply \u6267\u884C"
+  "cleanup.clearDry": "\u9884\u6F14\uFF1A\u5C06\u6E05\u9664\u5F53\u524D\u4F1A\u8BDD\u7684 {entries} \u4E2A\u5FEB\u7167\uFF0C\u91CA\u653E {bytes} \u5B57\u8282\u3002\u52A0 --apply \u6B63\u5F0F\u5220\u9664\u3002",
+  "cleanup.clearApply": "\u5DF2\u6E05\u9664\u5F53\u524D\u4F1A\u8BDD\u7684 {entries} \u4E2A\u5FEB\u7167\uFF0C\u91CA\u653E {bytes} \u5B57\u8282\u3002\u8BE5\u4F1A\u8BDD\u5DF2\u91CD\u7F6E\u4E3A\u4ECE\u5F53\u524D\u72B6\u6001\u91CD\u65B0\u8BB0\u5F55\u5FEB\u7167\u3002",
+  "cleanup.clearActive": "\u65E0\u6CD5\u6E05\u9664\u4F1A\u8BDD {sessionId}\uFF1A\u4F1A\u8BDD\u4ECD\u5728\u8FD0\u884C\u4E14\u672A\u80FD\u505C\u6B62\uFF0C\u8BF7\u5F85\u5176\u7A7A\u95F2\u540E\u91CD\u8BD5\u3002",
+  "cleanup.clearCancelled": "\u6E05\u7A7A\u5DF2\u53D6\u6D88\u3002",
+  "cleanup.clearFailed": "\u65E0\u6CD5\u6E05\u9664\u4F1A\u8BDD {sessionId}\uFF1A{detail}\u3002",
+  "cleanup.usage": "\u7528\u6CD5\uFF1A\n  /snapshot-auto-cleanup                 \u67E5\u770B\u72B6\u6001\n  /snapshot-auto-cleanup on|off          \u5F00\u542F/\u5173\u95ED\u81EA\u52A8\u6E05\u7406\n  /snapshot-auto-cleanup max-age <\u5929\u6570>  \u8BBE\u7F6E\u5931\u6D3B\u9608\u503C\uFF08\u5929\uFF09\n  /snapshot-auto-cleanup run [--apply]   \u9884\u6F14\uFF0C\u6216\u52A0 --apply \u6267\u884C\n  /snapshot-auto-cleanup run --current [--apply]  \u9884\u6F14/\u6E05\u9664\u672C\u4F1A\u8BDD\u5FEB\u7167"
 };
 var HOST_DICTS = { en, zh };
 function translate(lang, key, params = {}) {
@@ -231,8 +241,9 @@ function execSessionCwd(exec, requestedPath) {
 import { createHash } from "node:crypto";
 import { lstat, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { homedir } from "node:os";
-var DEFAULT_SNAPSHOT_ROOT = join(homedir(), ".dsh", "rewind-snapshots");
+import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
+var SNAPSHOT_DIR_NAME = "rewind-snapshots";
+var DEFAULT_SNAPSHOT_ROOT = join(resolveDshHome(), SNAPSHOT_DIR_NAME);
 var SNAPSHOT_ROOT_ENV = "DSH_REWIND_SNAPSHOT_DIR";
 var MAX_ANCHOR_GROUPS = 100;
 function isLinkEntry(entry) {
@@ -337,11 +348,6 @@ async function dirSizeAndLastActive(dir) {
   return { size, lastActiveMs };
 }
 var SnapshotStore = class _SnapshotStore {
-  constructor(root = process.env[SNAPSHOT_ROOT_ENV] ?? DEFAULT_SNAPSHOT_ROOT, opts) {
-    this.root = root;
-    this.dedup = opts?.dedup ?? true;
-  }
-  root;
   /** Debounce window for the per-commit prune (keeps the readdir+sort off the hot path). */
   static PRUNE_INTERVAL_MS = 1e3;
   lastPruneAt = 0;
@@ -360,6 +366,8 @@ var SnapshotStore = class _SnapshotStore {
   lastEntryTime = 0;
   /** Store options; `dedup` toggles in-place content dedup (default on). */
   dedup;
+  /** Resolved checkpoint store root (absolute); see the constructor's fallback. */
+  root;
   /**
    * In-memory per-path "most recent entry" for content dedup, keyed by
    * `<sessionId>\0<path>`. Each value holds the entry's effective `before`
@@ -370,6 +378,10 @@ var SnapshotStore = class _SnapshotStore {
   lastEntry = /* @__PURE__ */ new Map();
   /** Sessions whose dedup state has been seeded from disk this process. */
   seededSessions = /* @__PURE__ */ new Set();
+  constructor(root, opts) {
+    this.dedup = opts?.dedup ?? true;
+    this.root = root ?? process.env[SNAPSHOT_ROOT_ENV] ?? join(resolveDshHome(opts?.dshHome), SNAPSHOT_DIR_NAME);
+  }
   /** Absolute path of one session's snapshot directory (id sanitized). */
   sessionDir(sessionId) {
     return join(this.root, safeSessionId(sessionId));
@@ -1181,6 +1193,103 @@ var SnapshotStore = class _SnapshotStore {
     }
     return paths;
   }
+  /**
+   * Summarize a session's on-disk footprint for a clear dry-run: anchor-group
+   * count, committed checkpoint-entry count, restore-journal count, and total
+   * bytes. Walks with `lstat` (never follows a symlink, so a hostile symlink
+   * cannot escape the store root or inflate the measurement) and skips
+   * dot-prefixed temp leftovers and non-`.json` members — they are never
+   * checkpoint entries.
+   */
+  async sessionStats(sessionId) {
+    const sessionDir = this.sessionDir(sessionId);
+    let names;
+    try {
+      names = await readdir(sessionDir);
+    } catch (error) {
+      if (error.code === "ENOENT") return { anchorGroups: 0, entries: 0, journals: 0, bytes: 0 };
+      throw error;
+    }
+    let anchorGroups = 0;
+    let entries = 0;
+    let journals = 0;
+    let bytes = 0;
+    for (const name2 of names) {
+      if (name2.startsWith(".")) continue;
+      const full = join(sessionDir, name2);
+      let st;
+      try {
+        st = await lstat(full);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) {
+        if (!Number.isSafeInteger(Number(name2))) continue;
+        anchorGroups++;
+        let files;
+        try {
+          files = await readdir(full);
+        } catch {
+          continue;
+        }
+        for (const file of files) {
+          if (!file.endsWith(".json")) continue;
+          entries++;
+          const fileSt = await lstat(join(full, file)).catch(() => void 0);
+          if (fileSt !== void 0) bytes += fileSt.size;
+        }
+      } else if (name2.startsWith(_SnapshotStore.JOURNAL_PREFIX) && name2.endsWith(".json")) {
+        journals++;
+        bytes += st.size;
+      }
+    }
+    return { anchorGroups, entries, journals, bytes };
+  }
+  /**
+   * Remove a session's ENTIRE snapshot directory — every anchor group, every
+   * checkpoint entry, and every restore journal — and reset the store's
+   * in-memory dedup state so the session starts recording fresh from the
+   * current workspace state. This is the manual "get rid of this session's
+   * records NOW" action on the ACTIVE session the user is driving (it is never
+   * targetable by id; that is a directory-manipulation concern the user can do
+   * directly).
+   *
+   * SEMANTICS — clearing is an explicit abandonment: issuing the command means
+   * the user accepts that this session's snapshot archive goes away. It is
+   * therefore NOT gated on the state of any restore journal. A clear and a
+   * restore are both slash commands the host runs to completion for an agent,
+   * so they never interleave — any non-terminal journal present on disk is a
+   * stale orphan from a previous (crashed) process, and discarding it is the
+   * correct, safe resolution of that abandoned restore.
+   *
+   * SAFETY (this module's real concern is the plugin's ongoing BEHAVIOR, not
+   * losing snapshots):
+   *  - Only the session dir is removed; dedup refs are session-relative, so
+   *    there is no cross-session dangling to materialize (the same rationale as
+   *    {@link pruneStale}'s whole-dir removal).
+   *  - The in-memory dedup state (`lastEntry` / `seededSessions`) is ALWAYS
+   *    reset on an apply — even when the dir was already empty. A stale
+   *    in-memory entry (e.g. a session whose dir was removed out-of-band) would
+   *    otherwise link a later `recordEntry` to a deleted prior entry, leaving a
+   *    dangling ref that breaks restore resolution. This is the primary
+   *    correctness guarantee.
+   *
+   * `dryRun` computes the report without touching disk or memory.
+   */
+  async clearSession(sessionId, opts) {
+    const dryRun = opts?.dryRun ?? false;
+    const stats = await this.sessionStats(sessionId);
+    if (!dryRun) {
+      if (stats.anchorGroups > 0 || stats.journals > 0) {
+        await rm(this.sessionDir(sessionId), { recursive: true, force: true });
+      }
+      this.seededSessions.delete(sessionId);
+      for (const key of this.lastEntry.keys()) {
+        if (key.startsWith(`${sessionId}\0`)) this.lastEntry.delete(key);
+      }
+    }
+    return { sessionId, ...stats, dryRun };
+  }
 };
 function hashPath(path) {
   return createHash("sha256").update(path).digest("hex").slice(0, 8);
@@ -1211,18 +1320,18 @@ async function reconcileTracked(store, sessionId, anchorSeq, tracked, probe = de
 // src/snapshot-cleanup.ts
 import { mkdir as mkdir2, readFile as readFile2, rename as rename2, writeFile as writeFile2 } from "node:fs/promises";
 import { dirname as dirname2, join as join2 } from "node:path";
-import { homedir as homedir2 } from "node:os";
+import { resolveDshHome as resolveDshHome2 } from "@deepseek-ai/dsh-home-paths";
 var CLEANUP_CONFIG_FILENAME = "snapshot-cleanup.json";
 var CLEANUP_CONFIG_ENV = "DSH_SNAPSHOT_CLEANUP_CONFIG";
 var DEFAULT_MAX_AGE_DAYS = 30;
 var DEFAULT_CLEANUP_CONFIG = { enabled: false, maxAgeDays: DEFAULT_MAX_AGE_DAYS };
 var AUTO_SWEEP_INTERVAL_MS = 24 * 60 * 60 * 1e3;
-function resolveCleanupConfigPath() {
-  return process.env[CLEANUP_CONFIG_ENV] ?? join2(homedir2(), ".dsh", CLEANUP_CONFIG_FILENAME);
+function resolveCleanupConfigPath(dshHome) {
+  return process.env[CLEANUP_CONFIG_ENV] ?? join2(resolveDshHome2(dshHome), CLEANUP_CONFIG_FILENAME);
 }
 var STATE_FILENAME = "snapshot-cleanup-last-sweep.json";
-function resolveCleanupStatePath() {
-  return join2(dirname2(resolveCleanupConfigPath()), STATE_FILENAME);
+function resolveCleanupStatePath(dshHome) {
+  return join2(dirname2(resolveCleanupConfigPath(dshHome)), STATE_FILENAME);
 }
 async function loadLastSweepAt(path) {
   try {
@@ -1319,10 +1428,21 @@ function parseCleanupCommand(rawInput) {
       if (!Number.isInteger(days) || days <= 0) return { error: '"max-age" must be a positive integer (days)' };
       return { action: "max-age", value: days };
     }
+    case "run-apply":
+      return { error: 'the "run-apply" abbreviation was removed; use "run --apply"' };
     case "run": {
-      if (parts.length === 1) return { action: "run" };
-      if (parts.length === 2 && parts[1] === "--apply") return { action: "run-apply" };
-      return { error: "usage: /snapshot-auto-cleanup run [--apply]" };
+      let apply2 = false;
+      let current = false;
+      for (const rawFlag of parts.slice(1)) {
+        if (rawFlag === "--apply") {
+          apply2 = true;
+        } else if (rawFlag === "--current") {
+          current = true;
+        } else {
+          return { error: `unknown /snapshot-auto-cleanup run flag "${rawFlag}"` };
+        }
+      }
+      return { action: "run", target: current ? "current" : "rules", apply: apply2 };
     }
     default:
       return { error: `unknown /snapshot-auto-cleanup subcommand "${parts[0]}"` };
@@ -1640,13 +1760,13 @@ async function handleRewind(ctx, store, fs, invocation, inflight) {
   return executeRewind(ctx, store, fs, invocation, target, mode, inflight);
 }
 var autoSweepChecked = false;
-async function maybeRunAutoCleanup(ctx, store, sessionId) {
+async function maybeRunAutoCleanup(ctx, store, sessionId, dshHome) {
   if (autoSweepChecked) return;
   autoSweepChecked = true;
   await runAutoCleanupCheck({
     pruner: store,
-    configPath: resolveCleanupConfigPath(),
-    statePath: resolveCleanupStatePath(),
+    configPath: resolveCleanupConfigPath(dshHome),
+    statePath: resolveCleanupStatePath(dshHome),
     log: (msg) => ctx.logger.warn(msg)
   }, sessionId);
 }
@@ -1661,10 +1781,10 @@ function formatCleanupReport(report) {
   return report.skippedActive > 0 ? `${text}
 ${t("cleanup.skipped", { skipped: report.skippedActive })}` : text;
 }
-async function handleSnapshotCleanup(store, invocation) {
+async function handleSnapshotCleanup(store, invocation, dshHome, trackedBySession) {
   const parsed = parseCleanupCommand(invocation.rawInput);
   if ("error" in parsed) return { kind: "error", text: t("cleanup.usage") };
-  const configPath = resolveCleanupConfigPath();
+  const configPath = resolveCleanupConfigPath(dshHome);
   switch (parsed.action) {
     case "status": {
       const loaded = await loadCleanupConfig(configPath);
@@ -1700,17 +1820,20 @@ async function handleSnapshotCleanup(store, invocation) {
       }
       return { kind: "success", text: t("cleanup.maxAgeOk", { days: parsed.value }) };
     }
-    case "run":
-    case "run-apply": {
+    case "run": {
+      const apply2 = parsed.apply;
+      if (parsed.target === "current") {
+        return handleClearCurrent(store, invocation, apply2, trackedBySession);
+      }
       const loaded = await loadCleanupConfig(configPath);
       if (!loaded.ok) return { kind: "error", text: t("cleanup.cfgInvalid", { detail: loaded.error }) };
       try {
         const report = await store.pruneStale({
           keepActiveId: invocation.agent.session.id,
           maxAgeDays: loaded.config.maxAgeDays,
-          dryRun: parsed.action === "run"
+          dryRun: !apply2
         });
-        if (!report.dryRun) await saveLastSweepAt(resolveCleanupStatePath(), Date.now());
+        if (!report.dryRun) await saveLastSweepAt(resolveCleanupStatePath(dshHome), Date.now());
         return { kind: "success", text: formatCleanupReport(report) };
       } catch (error) {
         return { kind: "error", text: t("cleanup.runFailed", { detail: error instanceof Error ? error.message : String(error) }) };
@@ -1718,8 +1841,39 @@ async function handleSnapshotCleanup(store, invocation) {
     }
   }
 }
+function formatClearReport(report) {
+  const key = report.dryRun ? "cleanup.clearDry" : "cleanup.clearApply";
+  return t(key, {
+    entries: report.entries,
+    bytes: report.bytes
+  });
+}
+async function handleClearCurrent(store, invocation, apply2, trackedBySession) {
+  const { agent } = invocation;
+  const sessionId = agent.session.id;
+  if (apply2) {
+    if (agent.status !== "idle") {
+      agent.cancel({ kind: "user" }, { keepInbox: true });
+      const stopped = await waitForAgentIdle(agent, invocation.signal);
+      if (!stopped) {
+        return { kind: "error", text: t("cleanup.clearActive", { sessionId }) };
+      }
+    }
+    if (invocation.signal.aborted) {
+      return { kind: "error", text: t("cleanup.clearCancelled") };
+    }
+  }
+  try {
+    const report = await store.clearSession(sessionId, { dryRun: !apply2 });
+    if (!report.dryRun) trackedBySession.delete(sessionId);
+    return { kind: "success", text: formatClearReport(report) };
+  } catch (error) {
+    return { kind: "error", text: t("cleanup.clearFailed", { detail: error instanceof Error ? error.message : String(error), sessionId }) };
+  }
+}
 function apply(ctx, config) {
-  const store = new SnapshotStore(config?.snapshotDir, { dedup: config?.dedup });
+  const dshHome = config?.dshHome;
+  const store = new SnapshotStore(config?.snapshotDir, { dedup: config?.dedup, dshHome });
   const pending = /* @__PURE__ */ new Map();
   const anchorCache = /* @__PURE__ */ new WeakMap();
   const inflight = /* @__PURE__ */ new Set();
@@ -1732,16 +1886,22 @@ function apply(ctx, config) {
     }
   });
   ctx.effect(function* () {
+    const rewindHandler = (invocation) => handleRewind(ctx, store, fsService, invocation, inflight);
     yield ctx.commands.register({
       name: "rewind",
       description: t("command.description"),
-      handler: (invocation) => handleRewind(ctx, store, fsService, invocation, inflight)
+      handler: rewindHandler
+    });
+    yield ctx.commands.register({
+      name: "undo",
+      description: t("command.description"),
+      handler: rewindHandler
     });
     yield ctx.commands.register({
       name: "snapshot-auto-cleanup",
       description: t("cleanup.description"),
       input: { hint: t("cleanup.inputHint") },
-      handler: (invocation) => handleSnapshotCleanup(store, invocation)
+      handler: (invocation) => handleSnapshotCleanup(store, invocation, dshHome, trackedBySession)
     });
   }, "dsh-rewind command");
   ctx.on("session/event", (session, event) => {
@@ -1751,7 +1911,7 @@ function apply(ctx, config) {
     void (async () => {
       try {
         const sessionId = session.id;
-        void maybeRunAutoCleanup(ctx, store, sessionId);
+        void maybeRunAutoCleanup(ctx, store, sessionId, dshHome);
         let tracked = trackedBySession.get(sessionId);
         if (tracked === void 0) {
           tracked = await store.trackedPaths(sessionId);
@@ -1777,7 +1937,7 @@ function apply(ctx, config) {
     });
     scope.on("tools/post-execute", async (exec, result, next) => {
       try {
-        void maybeRunAutoCleanup(ctx, store, exec.agent?.session?.id);
+        void maybeRunAutoCleanup(ctx, store, exec.agent?.session?.id, dshHome);
         await commitEntry(store, pending, anchorCache, trackedBySession, exec, result);
       } catch (error) {
         ctx.logger.warn(`[dsh-rewind] checkpoint commit failed for ${exec.name}: ${error instanceof Error ? error.message : String(error)}`);

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

@@ -1,7 +1,7 @@
 /**
- * dsh-rewind client half: the `/rewind` command decoration, the
- * parameterized-input guard, the locale registration, and the session-scoped
- * portal bridge that renders the per-message ↶ rewind button (see
+ * dsh-rewind client half: the `/rewind` command decoration, the locale
+ * registration, and the session-scoped portal bridge that renders the
+ * per-message ↶ rewind button (see
  * `portals.tsx` for the button itself).
  *
  * The button is NOT injected by hand into the DOM anymore: the plugin
@@ -14,15 +14,15 @@
  * drift.
  *
  * The text-driven flow is the harness's STANDARD command decoration
- * (`ctx.commandUi.decorate`): a bare `/rewind` — picked from the slash-menu
- * completion, or typed in full and Entered — opens the harness's own
- * popupSelect shell (search, ↑↓/Enter, Esc) listing the rewind candidates
- * instead of executing the command. Picking one continues the SAME flow as
- * the ↶ button: the mode popover, both-impact confirmation, execution, row
- * hiding and the composer refill (`runRewindAndFill`). The parameterized
- * forms (`/rewind @<seq> chat|both`, `/rewind preview …`) stay internal
- * channels the ↶ button and the popover drive through `session.command`; a
- * hand-typed parameterized line is stopped with a hint.
+ * (`ctx.commandUi.decorate`): a bare `/rewind` (or its alias `/undo`) —
+ * picked from the slash-menu completion, or typed in full and Entered —
+ * opens the harness's own popupSelect shell (search, ↑↓/Enter, Esc) listing
+ * the rewind candidates instead of executing the command. Picking one
+ * continues the SAME flow as the ↶ button: the mode popover, both-impact
+ * confirmation, execution, row hiding and the composer refill
+ * (`runRewindAndFill`). The parameterized forms (`/rewind @<seq> chat|both`,
+ * `/rewind preview …`) stay internal channels the ↶ button and the popover
+ * drive through `session.command`.
  *
  * @module dsh-rewind/client
  */

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

@@ -25,7 +25,6 @@ export declare const zh: {
     'popover.impact.delete': string;
     'popover.confirm': string;
     'popover.back': string;
-    'guard.hint': string;
 };
 /** The rewind namespace key union. */
 export type RewindKey = keyof typeof zh;
@@ -61,5 +60,4 @@ export declare const en: {
     'popover.impact.delete': string;
     'popover.confirm': string;
     'popover.back': string;
-    'guard.hint': string;
 };