dsh-rewind-plugin 0.12.0 → 0.12.1

package/README.en.md

@@ -47,8 +47,8 @@ dsh plugin --profile web add dsh-rewind-plugin@<version>
 ## Usage
 
 1. Find the user message you want to rewind to in the conversation, or type `/rewind` (or its alias `/undo`) to open the candidate picker.
-2. **Select it.** A small popover offers the two modes ("conversation and code" is only shown when there are restorable changes after the target).
-3. The rewind takes effect immediately: the conversation returns to how it looked at the target message, and the withdrawn message's text is filled back into the composer — edit and re-send.
+2. **Select it.** A small popover offers the two modes — "conversation only" or "conversation and code".
+3. The rewind takes effect immediately: the conversation returns to how it looked at the target message, and the target message's text is filled back into the composer — edit and re-send.
 
 **Keyboard**: both the candidate picker and the mode popover support ↑↓ to move, Enter to confirm, Esc to cancel/back.
 
@@ -56,20 +56,19 @@ dsh plugin --profile web add dsh-rewind-plugin@<version>
 <summary><b>Edge notes</b></summary>
 
 - Rewinds can be repeated — with no limit on stage or count.
-- A rewind itself **cannot be undone**, but the withdrawn content stays in the session log and can be recovered by manually editing it.
+- A rewind itself **cannot be undone**, but the withdrawn content stays in the session log.
 - **Interruptions rewind too** — a `steering` interruption message the model hasn't read yet is also a valid rewind target.
-- **A rewind interrupts the running turn** — to execute the rewind safely.
+- **A rewind interrupts the running turn** — to ensure the rewind runs safely.
 
 </details>
 
 ## Snapshot management
 
 Snapshots (the before-write backups) are stored under `<dsh home>/rewind-snapshots/`
-(`~/.dsh/rewind-snapshots/` when `$DSH_HOME` is unset). For the **same session**,
-the plugin deduplicates snapshots by content (an unchanged file is stored as a link)
-and keeps the newest 100 anchor groups. **Deleting that directory manually** only
-clears the file backups (chat rewinds are unaffected) and the plugin rebuilds them
-automatically.
+(the default is `~/.dsh/rewind-snapshots/`). For the **same session**, the plugin
+deduplicates snapshots by content and keeps the newest 100 anchor groups.
+**Deleting that directory manually** only clears the file backups (chat rewinds are
+unaffected) and the plugin rebuilds them automatically.
 
 A **global auto-cleanup** (off by default) removes the snapshot directories of
 long-inactive sessions, leaving the active session and chat log untouched. Configure
@@ -101,57 +100,44 @@ Compared with the common approaches, here is the trade-off this plugin makes on
 | Dimension | Common approach | This plugin |
 | --- | --- | --- |
 | Conversation rewind | Fork / branch a new conversation | **In-place rewind** — no new session, no window switch |
-| File restore | No restore feature / git-managed or whole-tree snapshot | **Lightweight before-backups** — auto-captured before writes, one-click restore (aligned with Claude Code) |
+| File restore | No restore feature / git-managed or whole-tree snapshot | **Lightweight before-backups** — auto-captured before writes, one-click restore |
 | Dependencies | Often needs a Git repo or a full snapshot engine | **None** — no git required, works on any directory |
-| Storage footprint | Whole-tree snapshots take space | **Lightweight** — only files touched by write tools are stored, persisted on disk |
+| Storage footprint | Whole-tree snapshots take space | **Lightweight** — nothing is stored unless it changed, and only files touched by write tools are tracked |
 
 ## How it works
 
-The whole design rests on two principles, simple but deliberate: **the conversation half "masks, never deletes", and the file half "backs up before the write, reconciles against the real disk before restoring."** It shares lineage with Claude Code's checkpointing — Claude Code's file history is also per-file records plus a re-scan of tracked files at every message, not a whole-tree snapshot. This plugin brings the same semantics to dsh, and makes them lighter and more robust.
+The whole design rests on two principles, simple but deliberate: **the conversation half "masks, never deletes"**, using DSH's native "hide + replace" mechanism; **the file half "partial tracking, lightweight before-write backup"**, following Claude Code's checkpoint semantics.
 
 ### 1. Conversation rewind: a single "mask", not a delete
 
-`append-only` is a hard rule: the session log only grows and is never rewritten — the foundation of auditability and privacy. A rewind never touches history; it makes a single move: append **one content-empty marker message** to the end of the log and use it to "mask + replace" everything after the target message, so the model and the UI see only the part before it.
+`append-only` is a hard rule: the session log only grows and is never rewritten — the foundation of auditability and privacy. A rewind never touches history; it makes a single move: append **one "empty message" marker** to the end of the log and use it to "mask + replace" everything after the target message, so the model and the UI see only the part before it.
 
-- The marker is **canonical** — the plugin **replicates** `/compact`'s "hide + replace": `/compact` compresses a span of history into a summary, while `/rewind` swaps in an empty marker message. Because it's canonical, the harness's own log replay, `/compact` compaction, and resume preflight all recognize it and never mistake it for a real message.
-- The replacement is **imperceptible** — the model ignores the empty marker, with no effect (verified empirically). Together with the plugin's UI handling, what you and the model see is exactly how the conversation looked at the target — truly "in place".
-- Because this is **masking, not deleting**, every withdrawn event stays in the log — auditable, traceable, viewable, and in principle manually recoverable.
+- **One and the same log** — the append happens only in the current session's log: no new session, no new branch, so no residue or copy is left behind;
+- **The marker is canonical** — the same "hide + replace" as the official `/compact`: `/compact` compresses a span of history into a summary, while `/rewind` swaps in an "empty message" marker. Because it is canonical, DSH's log replay, compaction, and resume preflight all recognize it and never mistake it for a real message;
+- **The replacement is imperceptible** — the model ignores the marker, with no effect (verified empirically). Together with the plugin's UI handling, what you and the model see is exactly how the conversation looked at the target;
+- **Content is preserved** — because this is "masking, not deleting", the withdrawn content stays in the log — auditable, traceable, and in principle manually recoverable.
 
-> **Design highlight**: the entire conversation rewind is **a single append**. It's deterministic, auditable, and — because the log was never broken — a "clean" time-travel. Minimal action, complete semantics. The compatibility subtleties with the harness (replicating `/compact`, the empty-message mask) are where this plugin is genuinely professional — each is pinned by a dedicated probe test.
+> **Design highlight**: the entire conversation rewind is **a single append**. It's deterministic, auditable, and — because the log was never broken — a "clean" time-travel. Minimal action, complete semantics. The compatibility subtleties with DSH (replicating `/compact`, the empty-message mask) are where this plugin is genuinely professional.
 
-### 2. File restore: lightweight checkpointing, "back up before the change"
+### 2. File restore: lightweight checkpointing, "before-write backup"
 
 The file half follows Claude Code's checkpoint semantics — **partial tracking + before-write backup, plus a re-scan of tracked files at each message**, not a whole-tree snapshot. This trade-off saves space, and it's actually more complete:
 
 - **Before-write backup**: tracks only the write-class tools (`write`, `edit`) — backs up the original content before a write and records/tracks the files it touches; it never backs up the whole workspace, so it's lightweight.
 - **External changes count too**: at every user-message boundary the plugin re-checks all tracked files — external changes such as a command run or a manual edit are recorded as well and restored by a later rewind. "Lightweight" but not "incomplete".
-- **Unchanged-not-recorded, identical-content-as-link**: an entry is written only when something changed — at the message-boundary re-check, an unchanged file is never backed up (no record); at before-write time, when the new content matches the path's prior record, only a **link to it** (`ref`) is stored instead of a copy. Repeated writes cost almost nothing, and a link is materialized before its group is evicted — never left dangling.
-- **Reconcile against the real disk before restoring**: restore takes each path's **earliest** record, then reads the live file and compares — **only files that actually differ are touched**: modified files are written back to the earliest backup, files created after the target are deleted, already-matching files are skipped. Repeated rewinds are therefore **idempotent with zero side effects** and never produce "ghost impact".
-- **Safety boundary**: symlinks / hard links are skipped so one restore can't clobber another name of the same file; paths are sanitized so nothing ever escapes the backup root; a per-file failure never aborts the pass.
-
-> **Design highlight**: this checkpoint's light footprint comes from **recording only what was actually touched and really changed** — before-write backup makes it restorable, unchanged-not-recorded and content-as-link drop the repetition; which files to touch is decided against the real disk at restore time.
-
-### Design highlights
-
-| Design | Why it matters |
-| --- | --- |
-| A single append is a whole rewind | Minimal action, maximal semantics; the log is never mutated |
-| Mask, never delete | History is always auditable and in principle recoverable |
-| Before-backup, grouped by turn, persisted on disk | Space-efficient, survives restarts, Claude Code-aligned |
-| Identical content stored as a link (dedup) | Hundreds of repeated writes cost almost nothing; links are materialized before their group is evicted, never left dangling |
-| Session-level auto-cleanup | Removes only long-inactive sessions' snapshots; the active session and the chat log are never touched |
-| Reconcile against the real disk before restoring | Idempotent, zero side effects, no collateral damage |
-| Empty-message mask + replicating `/compact` | Deeply compatible with the host, pinned by probe tests |
-| Crash safety (atomic writes + restore journal) | Continue or roll back cleanly after a crash |
-| Pure-function planning + probed store | Fully unit-testable without a host; test-driven |
+- **Unchanged-not-recorded**: an entry is written only when something changed — at the message-boundary re-check, an unchanged file is never backed up (no record); at before-write time, when the new content matches the path's prior record, only a **link to it** (`ref`) is stored instead of a copy.
+- **Accurate restore**: backups are the sole standard, checked against the real disk — **only files that actually differ are touched**: modified files restored, newly created files deleted, deleted files recovered. Backups are stored byte for byte, so the restored result matches the backups exactly, with no "ghost impact".
+- **Safety and integrity**: paths are sanitized so nothing ever escapes the backup root; symlinks / hard links are skipped so one restore can't clobber another name of the same file; a per-file failure never aborts the pass; backups and the restore journal are written atomically and kept across restarts, so a half-applied restore after a crash can be continued or rolled back.
+
+> **Design highlight**: this checkpoint's light footprint comes from **recording only what was actually touched and really changed** — before-write backup makes it restorable, unchanged-not-recorded and content-as-link drop the repetition; only the files that differ are touched at restore time.
 
 ## What it deliberately does NOT do
 
 This plugin deliberately stays lightweight and focused on one thing — "conversation rewind". The following are **out of its scope**:
 
-- **Whole-tree / Git-level snapshots** — only write-class tool edits plus external changes to already-tracked files are backed up; files never touched by a tool are not restored. For whole-worktree snapshot rollback, use a dedicated snapshot tool (or your git).
-- **Subagent edits** — not tracked (same as Claude Code): a subagent runs its own session, so its backups could never be restored by a rewind of the parent session.
-- **Fork / branch rewind** — the harness already provides this ("branch in new chat"); no need to reinvent it.
+- **Whole-tree / Git-level snapshots** — only write-class tool edits plus external changes to already-tracked files are backed up; files never touched by a tool are not restored. For a worktree-level full snapshot rollback, use a more specialized snapshot tool (git).
+- **Subagent edits** — not tracked, and no rewind inside a subagent session (same as Claude Code): a subagent runs its own session, so its backups could never be restored by a rewind of the parent session, and none are kept for one.
+- **Fork / branch rewind** — DSH already provides this ("branch in new chat"); no need to reinvent the wheel.
 
 ## Compatibility
 
@@ -183,7 +169,7 @@ withdrew should consume the stable, locale-independent helpers exported from
 
 ## Security
 
-This plugin only appends rewind-marker events to the session log; it never deletes or rewrites logged history. Workspace files are written only when you choose "conversation and code"; backups are stored under `<dsh home>/rewind-snapshots/`; restores draw only from those backups. It never touches your git repository, makes no network requests, and accesses no credentials. Delete `~/.dsh/rewind-snapshots/` to wipe file backups only (chat rewinds are unaffected); the plugin rebuilds automatically. For sessions you've left inactive for a long time, a global auto-cleanup (off by default) can remove their snapshot directory in whole, leaving the active session and the chat log untouched. Full security model: [SECURITY.md](SECURITY.md).
+This plugin only appends rewind-marker events to the session log; it never deletes or rewrites logged history. Workspace files are written only when you choose "conversation and code"; backups are stored under `<dsh home>/rewind-snapshots/`; restores draw only from those backups. It never touches your git repository, makes no network requests, and accesses no credentials. For sessions you've left inactive for a long time, a global auto-cleanup (off by default) can remove their snapshot directory in whole, leaving the active session and the chat log untouched. Full security model: [SECURITY.md](SECURITY.md).
 
 ## Development
 

package/README.md

@@ -46,8 +46,8 @@ dsh plugin --profile web add dsh-rewind-plugin@<版本>
 ## 使用
 
 1. 在对话中找到要回退的那条用户消息，或输入 `/rewind`（或其别名 `/undo`）打开候选列表选择。
-2. **选中它。** 小浮层提供两种模式（「回退对话和代码」仅在目标之后有可还原的变更时显示）。
-3. 回退立即生效：对话回到目标消息当时的样子，被撤回消息的文本自动填入输入框——改完直接重发。
+2. **选中它。** 小浮层提供两种模式——「仅回退对话」或「回退对话和代码」。
+3. 回退立即生效：对话回到目标消息当时的样子，目标消息的文本自动回填输入框——改完直接重发。
 
 **键盘操作**：候选列表与模式浮层均支持 ↑↓ 移动、Enter 确认、Esc 取消/返回。
 
@@ -55,15 +55,15 @@ dsh plugin --profile web add dsh-rewind-plugin@<版本>
 <summary><b>边界说明</b></summary>
 
 - 回退可以反复进行——没有阶段或次数限制。
-- 回退本身**无法撤销**，但被撤回的内容仍保留在会话日志中，可手动编辑日志恢复。
+- 回退本身**无法撤销**，但被撤回的内容仍保留在会话日志中。
 - **插话也能回退**——模型尚未读取的 `steering` 插话消息，同样可作为回退目标。
-- **回退会打断当前正在运行的回合**——确保回退安全执行。
+- **回退会打断当前正在运行的回合**——确保回退的安全执行。
 
 </details>
 
 ## 存储管理
 
-快照（写前备份）存储于 `<dsh home>/rewind-snapshots/`（未设 `$DSH_HOME` 时即 `~/.dsh/rewind-snapshots/`）。插件对**同一会话**的快照做内容去重（内容未变则存为链接）并保留最近 100 组锚点；**手动删除该目录**仅清除文件备份（对话回退不受影响），插件会自动重建。
+快照（写前备份）存储于 `<dsh home>/rewind-snapshots/`（默认 `~/.dsh/rewind-snapshots/`）。插件对**同一会话**的快照做内容去重并保留最近 100 组锚点；**手动删除该目录**仅清除文件备份（对话回退不受影响），插件会自动重建。
 
 另提供**全局自动清理**（默认关闭）：把长期不活跃的会话快照整目录移除，不影响活动会话与对话日志。可在 `设置→插件→插件配置→快照清理` 面板查看与配置（自动清理开关、失活天数），也可用 `/snapshot-auto-cleanup` 命令查看、设置和运行。详见：[快照自动清理](docs/snapshot-auto-cleanup.zh.md)。
 
@@ -89,57 +89,44 @@ rm <dsh home>/snapshot-cleanup-last-sweep.json
 | 维度 | 常见做法 | 本插件 |
 | --- | --- | --- |
 | 对话回退 | Fork 分支新建对话 | **就地回退**——不新建会话、不切窗口，便捷回退 |
-| 文件还原 | 无还原功能 / git 管理或完整快照 | **写前轻量备份**——写文件前自动存原内容，一键还原（对齐 Claude Code） |
+| 文件还原 | 无还原功能 / git 管理或完整快照 | **写前轻量备份**——写文件前自动存原内容，一键还原 |
 | 依赖 | 常依赖 Git 仓库或完整快照引擎 | **无依赖**——不依赖 git，普通目录即可用 |
-| 存储开销 | 整树快照占空间大 | **轻量**——只存被写工具改动过的文件，落盘持久化 |
+| 存储开销 | 整树快照占空间大 | **轻量**——不变不存，且只追踪写类工具改动过的文件 |
 
 ## 原理
 
-整套设计只有两条主线，核心哲学朴素却克制：**对话部分「只遮蔽、不删除」，文件部分「改前先备份，还原时对照真实磁盘」**。机制与 Claude Code 的 checkpointing 同源——Claude Code 的文件历史也是逐文件记录 + 每条消息重扫已跟踪文件，并非整树快照；本插件把同一套语义落在 dsh 上，并做得更轻、更稳。
+整套设计只有两条主线，核心哲学朴素却克制：**对话部分「只遮蔽、不删除」**，使用 DSH 原生的「隐藏 + 替换」机制；**文件部分「局部追踪，写前轻量备份」**，参考 Claude Code 的检查点语义。
 
 ### 1. 对话回退：一次「遮蔽」，而不是「删除」
 
-`append-only` 是铁律：会话日志只追加、从不改写——这是可审计与信息安全的地基。回退从不动历史，它只做一步：往日志末尾追加一条**内容为空的标记消息**，把目标消息之后的全部内容「遮蔽 + 替换」掉，让模型和界面都只看得到目标之前的部分。
+`append-only` 是铁律：会话日志只追加、从不改写——这是可审计与信息安全的地基。回退从不动历史，它只做一步：往日志末尾追加一条 **“空消息”标记**，把目标消息之后的全部内容「遮蔽 + 替换」掉，让模型和界面都只看得到目标之前的部分。
 
-- **标记是规范的**——插件复刻 `/compact` 标准的「隐藏 + 替换」：`/compact` 把一段历史压缩成摘要，`/rewind` 则换成一条空标记消息。由于其规范性，harness 的日志重放、`/compact` 压缩、续接检查都能正确识别它，绝不会把它误认为真实对话；
-- **替换内容无感**——模型对空标记忽略、无感（实测验证）。配合插件对界面显示的处理，模型和你看到的对话就是目标消息当时的样子，真正的「就地」；
-- 因为是「遮蔽」而非「删除」，**被撤回的每一条事件都完整留在日志里**，可审计、可追溯、可查看，原则上也随时能手动恢复。
+- **同一份日志**——只在当前会话的日志做简单追加，不新建会话、不新建分支，因此不会留下残留和副本；
+- **标记是规范的**——采用与官方 `/compact` 相同的「隐藏 + 替换」：`/compact` 把一段历史压缩成摘要，`/rewind` 则换成一条“空消息”标记。由于其规范性，DSH 的日志重放、压缩、续接检查都能正确识别它，绝不会把它误认为真实对话；
+- **替换内容无感**——模型对标记忽略、无感（实测验证）。配合插件对界面显示的处理，模型和你看到的对话就是目标消息当时的样子；
+- **记录完整保留**——因为是「遮蔽」而非「删除」，被撤回的内容完整留在日志里，可审计、可追溯，原则上也能手动恢复。
 
-> **设计点睛**：整个对话回退就是**一条**追加。它确定、可审计，且因为日志从未被破坏，回溯是「干净的」——用最小的动作，实现最完整的语义。那些与 harness 内部的兼容细节（对 `/compact` 的复刻、空消息的遮蔽）正是插件的专业所在，每一条都由专门的探针测试固化。
+> **设计点睛**：整个对话回退就是**一条**追加。它确定、可审计，且因为日志从未被破坏，回溯是「干净的」——用最小的动作，实现最完整的语义。那些与 DSH 内部的兼容细节（对 `/compact` 的复刻、空消息的遮蔽）正是插件的专业所在。
 
-### 2. 文件还原：轻量检查点，「改前备份」
+### 2. 文件还原：轻量检查点，「写前备份」
 
 文件部分对齐 Claude Code 的检查点语义——**局部追踪、写前备份 + 每条消息重扫已跟踪文件**，而不是整树快照。这项取舍既省空间，又更完整：
 
 - **写前备份**：只追踪写类工具（`write`、`edit`），写前**备份原内容**，并**记录、追踪**被处理的文件——从不备份整个工作区，因此轻量。
 - **外部变更也追**：每条用户消息边界，插件重新检查所有已跟踪文件——命令执行、手动修改等外部变更同样被记录，回退时一并还原。这让「轻量」却不「残缺」。
-- **不变不存、同内容存链接**：记录只在有变化时发生——消息边界重扫时无变更的不备份（不留记录）；写前备份时若与前一条记录一致，只存**指向它的链接**（`ref`）而非复制内容。重复写入几乎不占空间，链接也先落地、绝不悬空。
-- **还原时对照真实磁盘**：先取每条路径的**最早**记录，再实时读取文件当前内容与之比对——**只操作真正不一致的文件**：改过的写回最早期内容、目标之后新建的删除、已经一致的跳过。重复回退因此**零副作用、幂等**，不会出现「幽灵影响」。
-- **安全边界**：符号/硬链接跳过，避免透过一个还原误伤另一个名字；路径经安全化处理，**绝不越出备份根目录**；单个文件失败绝不中止整轮还原。
+- **不变不存**：记录只在有变化时发生——消息边界重扫时无变更的**不备份**（不留记录）；写前备份时若与前一条记录一致，只存指向它的链接（`ref`）而非复制内容。
+- **还原准确**：以备份为唯一标准，对照真实磁盘，只动真正不一致的文件——被改过的还原、被新建的删除、被删除的恢复；备份逐字节存储。还原结果与备份一致，无“幽灵影响”。
+- **安全与完整性**：路径经安全化处理，绝不越出备份根目录；符号/硬链接跳过，避免透过一次还原误伤同名的另一份文件；单个文件失败绝不中止整轮还原；备份与还原日志均原子写落盘（跨重启仍在），断电或崩溃后的半还原可续做或回滚。
 
 > **设计点睛**：这套检查点的「轻」，来自**只记录被工具动过、且确实变化的文件**——写前备份保证可还原，不变不存与存链接压掉重复；还原时再对照真实磁盘，只动不一致的文件。
 
-### 设计亮点一览
-
-| 设计 | 为什么值得 |
-| --- | --- |
-| 一次追加即一次回退 | 极小动作、极大语义，且日志从不被破坏 |
-| 只遮蔽、不删除 | 历史永远可审计，原则上可恢复 |
-| 改前备份 + 按轮分组 + 落盘 | 省空间、跨重启、对齐 Claude Code |
-| 同内容存为链接（去重） | 上百次重复写入几乎不占空间；淘汰组前先落地链接，绝不悬空 |
-| 会话级自动清理 | 只移除长期不活跃会话的快照，活动会话与对话日志永不触及 |
-| 对照真实磁盘再还原 | 幂等、零副作用、不误伤 |
-| 空消息遮蔽 + 对 `/compact` 的复刻 | 与宿主深度兼容，且被探针测试固化 |
-| 崩溃安全（原子写 + 还原日志） | 断电/崩溃后仍可续做或回滚 |
-| 纯函数规划 + 注入探针的存储 | 无需宿主即可单测，测试驱动 |
-
 ## 明确不做的事
 
 本插件刻意保持轻量、聚焦"对话回退"这一件事，以下场景**不属于它的职责**：
 
-- **整树 / Git 级快照**——只跟踪写类工具编辑 + 已跟踪文件的外部改动，从未被工具碰过的文件不还原。需要 Git 工作树级的完整快照回退时，请交给专门的快照工具（或你的 git）。
-- **子代理的编辑**——不追踪（同 Claude Code）：子代理运行在自己的会话里，其备份无法由父会话的回退还原，只会在磁盘上残留。
-- **fork / 分支回退**——harness 已内置「在新对话中分支」，不重复造轮子。
+- **整树 / Git 级快照**——只跟踪写类工具编辑 + 已跟踪文件的外部改动，从未被工具碰过的文件不还原。需要工作树级的完整快照回退时，请交给更专业的快照工具（git）。
+- **子代理的编辑**——不追踪，子代理会话内也不提供回退（同 Claude Code）：子代理运行在自己的会话里，其备份无法由父会话的回退还原，因此也不会为子会话保留备份。
+- **fork / 分支回退**——DSH 已内置「在新对话中分支」，不重复造轮子。
 
 ## 兼容性
 

package/SECURITY.md

@@ -190,7 +190,8 @@ transcript.
   committed a backup.
 - **Subagent session edits are not tracked** (Claude Code alignment): a
   subagent runs its own session, so the files it changes are not backed up and
-  cannot be restored by a rewind of the parent session.
+  cannot be restored by a rewind of the parent session; the plugin keeps no
+  snapshot for a subagent session and offers no rewind inside one.
 
 ## Reporting
 

package/docs/architecture.md

@@ -107,7 +107,10 @@ the `0.9.x` line) and is **removed in the `0.10.x` line**.
 tools/execute        captureBefore: for write / edit, stage a raw byte copy of
                      the file's BEFORE state into the store's .pending/
                      (node:fs copyFile, never through a string);
-                     subagent edits are NOT tracked (Claude Code alignment).
+                     subagent sessions are NOT tracked and get no rewind
+                     surface at all (Claude Code alignment — the Harness
+                     refuses generic Session RPCs for a subagent-owned
+                     identity, so /rewind cannot execute there).
 tools/post-execute   commitEntry: anchor = latest user/message seq; skip
                      failed calls; publish the staged bytes as the entry's
                      sidecar and write the metadata beside them — including
@@ -124,7 +127,9 @@ prune                keeps the newest 100 anchor groups per session, storing
                      and recycles terminal restore journals.
 pruneStale            cross-session auto-cleanup (default off): whole
                      long-inactive session dirs past the cutoff are removed;
-                     the active session is never targeted.
+                     the active session is never targeted (a subagent's tool
+                     result never triggers the sweep — it owns no dir and would
+                     claim that exemption).
 ```
 
 ## Compatibility strategy

package/docs/compat/diagnostics.md

@@ -32,7 +32,8 @@ console filter:
 | Scope | What an anomaly here means |
 | --- | --- |
 | `boot` | Startup identity — `loaded v<version> (build <hash>)`, gated by the verbose switch (see below). Confirms the running bundle matches a fix. |
-| `refill` | The composer refill after a rewind (command/wait/refill throws, an outcome that never settles) |
+| `refill` | The composer refill after a rewind (command/wait/refill throws, a rejected or unmatched command, an outcome that never settles) |
+| `preview` | The `/rewind preview` impact probe behind the mode popover (command rejected/unmatched/threw, an outcome that never settles) |
 | `portals` | Per-message button mount issues (e.g. no session binding) |
 | `settings` | The snapshot-cleanup settings card |
 | `hiding` | **Reserved** — no active alert at present. If a future row-hiding diagnostic is added, it belongs in this region. |

package/docs/compat/diagnostics.zh.md

@@ -22,7 +22,8 @@
 | scope | 这里的异常含义 |
 | --- | --- |
 | `boot` | 启动身份行——`loaded v<version> (build <hash>)`，由详细输出开关控制（见下）。用于确认运行中的 bundle 是否匹配某个修复。 |
-| `refill` | 回退后的输入框回填（命令/等待/回填抛出异常、等待的结果始终未落定） |
+| `refill` | 回退后的输入框回填（命令/等待/回填抛出异常、命令被拒绝或未匹配、等待的结果始终未落定） |
+| `preview` | 模式气泡背后的 `/rewind preview` 影响探测（命令被拒绝/未匹配/抛出异常、等待的结果始终未落定） |
 | `portals` | 每条消息按钮的挂载问题（如无会话绑定） |
 | `settings` | 快照清理设置卡片 |
 | `hiding` | **保留区**——当前无活跃告警。若未来新增行隐藏诊断，应归属此区域。 |

package/lib/client.js

@@ -167,6 +167,48 @@ function rewindOptionsFromCandidates(candidates, t) {
   }));
 }
 
+// src/client/log.ts
+var NS = "dsh-rewind";
+var DEBUG_KEY = "dsh-rewind.debug";
+var ALWAYS_ON = /* @__PURE__ */ new Set(["error", "warn"]);
+function switchValue() {
+  try {
+    return window.localStorage.getItem(DEBUG_KEY) ?? "";
+  } catch {
+    return "";
+  }
+}
+function matches(value, ns) {
+  for (const entry of value.split(",")) {
+    const part = entry.trim();
+    if (part === "") continue;
+    if (part === "*" || part === `${NS}*`) return true;
+    if (part.endsWith("*")) {
+      if (ns.startsWith(part.slice(0, -1))) return true;
+    } else if (ns === part) {
+      return true;
+    }
+  }
+  return false;
+}
+function tag(scope) {
+  return `[${NS}:${scope}]`;
+}
+function log(level, scope, message, data) {
+  if (ALWAYS_ON.has(level)) {
+    console[level](tag(scope), message, data);
+    return;
+  }
+  if (!matches(switchValue(), `${NS}:${scope}`)) return;
+  console.info(tag(scope), message, data);
+}
+var rewindLog = {
+  error: (scope, message, data) => log("error", scope, message, data),
+  warn: (scope, message, data) => log("warn", scope, message, data),
+  info: (scope, message, data) => log("info", scope, message, data),
+  debug: (scope, message, data) => log("debug", scope, message, data)
+};
+
 // src/client/styles.ts
 var CLASS = {
   button: "dsh-rewind-btn",
@@ -663,8 +705,21 @@ function isPreviewFor(node, seq) {
 }
 async function previewImpact(session, chatOf, seq, watch) {
   const known = knownCommandSeqs(session, chatOf, (node) => isPreviewFor(node, seq));
-  const result = await session.command(`/rewind preview @${seq} both`);
-  if (!result.ok || result.value?.matched !== true) return null;
+  let result;
+  try {
+    result = await session.command(`/rewind preview @${seq} both`);
+  } catch (error) {
+    rewindLog.warn("preview", `preview command threw for @${seq}`, error);
+    return { kind: "error", text: error instanceof Error ? error.message : String(error) };
+  }
+  if (!result.ok) {
+    rewindLog.warn("preview", `preview command rejected for @${seq}`, result.error);
+    return { kind: "error", text: `${result.error.code}: ${result.error.message}` };
+  }
+  if (result.value?.matched !== true) {
+    rewindLog.warn("preview", `preview command was not matched for @${seq}`);
+    return { kind: "error", text: "the rewind command is not registered on this host" };
+  }
   return waitForCommand(session, chatOf, (node) => isPreviewFor(node, seq) && !known.has(node.seq), 8e3, watch);
 }
 function el(tag2, className, text) {
@@ -912,13 +967,13 @@ function openPopover(opts) {
     impactOutcome = outcome;
     if (outcome !== null && outcome.kind === "success") {
       bothState = { state: hasFileImpact(outcome.text) ? "hasChanges" : "noChanges" };
-    } else if (outcome !== null && outcome.kind === "error") {
-      bothState = { state: "error", message: outcome.text ?? "unknown error" };
+    } else {
+      bothState = { state: "error", message: outcome?.text ?? "preview command timed out" };
     }
     renderModes();
     shell.position();
   })().catch(() => {
-    bothState = { state: "hasChanges" };
+    bothState = { state: "error", message: "unexpected error" };
     renderModes();
     shell.position();
   });
@@ -948,48 +1003,6 @@ function retractSpan(steering, targetId) {
   return steering.slice(index).map((item) => item.id);
 }
 
-// src/client/log.ts
-var NS = "dsh-rewind";
-var DEBUG_KEY = "dsh-rewind.debug";
-var ALWAYS_ON = /* @__PURE__ */ new Set(["error", "warn"]);
-function switchValue() {
-  try {
-    return window.localStorage.getItem(DEBUG_KEY) ?? "";
-  } catch {
-    return "";
-  }
-}
-function matches(value, ns) {
-  for (const entry of value.split(",")) {
-    const part = entry.trim();
-    if (part === "") continue;
-    if (part === "*" || part === `${NS}*`) return true;
-    if (part.endsWith("*")) {
-      if (ns.startsWith(part.slice(0, -1))) return true;
-    } else if (ns === part) {
-      return true;
-    }
-  }
-  return false;
-}
-function tag(scope) {
-  return `[${NS}:${scope}]`;
-}
-function log(level, scope, message, data) {
-  if (ALWAYS_ON.has(level)) {
-    console[level](tag(scope), message, data);
-    return;
-  }
-  if (!matches(switchValue(), `${NS}:${scope}`)) return;
-  console.info(tag(scope), message, data);
-}
-var rewindLog = {
-  error: (scope, message, data) => log("error", scope, message, data),
-  warn: (scope, message, data) => log("warn", scope, message, data),
-  info: (scope, message, data) => log("info", scope, message, data),
-  debug: (scope, message, data) => log("debug", scope, message, data)
-};
-
 // src/client/portals.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
 function fillComposerEditable(text) {
@@ -1041,7 +1054,12 @@ async function runRewindAndFill(session, seq, mode, currentSessionId, chatOf, wa
     rewindLog.warn("refill", `rewind command threw, skipping refill @${seq}`, error);
     return;
   }
-  if (!result.ok || result.value?.matched !== true) {
+  if (!result.ok) {
+    rewindLog.warn("refill", `rewind command rejected for @${seq}`, result.error);
+    return;
+  }
+  if (result.value?.matched !== true) {
+    rewindLog.warn("refill", `rewind command was not matched for @${seq}`);
     return;
   }
   let outcome;
@@ -1130,6 +1148,13 @@ function collectTargets(chat, hiddenSeqs) {
   }
   return targets;
 }
+function isRewindInertSession(snapshot) {
+  return snapshot.subagent !== null && snapshot.subagent !== void 0;
+}
+function collectDurableTargets(snapshot, chat, hiddenSeqs) {
+  if (chat === void 0 || isRewindInertSession(snapshot)) return [];
+  return collectTargets(chat, hiddenSeqs);
+}
 function bubbleTextOf(row) {
   const clone = row.cloneNode(true);
   clone.lastElementChild?.remove();
@@ -1205,7 +1230,7 @@ function RewindPortals({ sessionId, sessionOf, chatOf, currentSessionId, watchCh
           hidden.current.delete(seat);
         }
       }
-      const durable = chat === void 0 ? [] : collectTargets(chat, hiddenSeqs);
+      const durable = collectDurableTargets(snapshot, chat, hiddenSeqs);
       const next = [...durable, ...collectPendingTargets(snapshot)];
       setTargets((current) => sameTargets(current, next) ? current : next);
     };
@@ -1345,8 +1370,8 @@ function createRewindBridge(deps) {
 }
 
 // src/client/build-info.ts
-var PLUGIN_VERSION = true ? "0.12.0" : "dev";
-var BUILD_HASH = true ? "d770983e" : "dev";
+var PLUGIN_VERSION = true ? "0.12.1" : "dev";
+var BUILD_HASH = true ? "248f750a" : "dev";
 
 // src/client/locales.ts
 var zh = {
@@ -1705,6 +1730,7 @@ function apply(ctx) {
     const commandUi = ctx.get("commandUi");
     const hasCandidates = (sessionId) => {
       const face = sessionId === void 0 ? void 0 : sessionOf(sessionId);
+      if (face === void 0 || isRewindInertSession(face.getSnapshot())) return false;
       const chat = chatOf(face);
       return chat !== void 0 && rewindCandidatesOfChat(chat).length > 0;
     };

package/lib/index.js

@@ -2248,6 +2248,10 @@ function shouldRunAutoSweep(lastAtMs, nowMs) {
 var name = "dsh-rewind";
 var inject = ["commands", "tools"];
 var TRACKED_TOOLS = /* @__PURE__ */ new Set(["write", "edit"]);
+function isSubagentSession(session) {
+  const header = session.header;
+  return header.origin === "subagent" || (header.delegationDepth ?? 0) > 0;
+}
 var activeLocale = "en";
 var cleanupStore;
 function t(key, params) {
@@ -2306,8 +2310,7 @@ function isNotFoundError(error) {
 async function captureBefore(fs, store, exec, pending) {
   if (!TRACKED_TOOLS.has(exec.name)) return;
   const session = exec.agent?.session;
-  const header = session?.header;
-  if (header !== void 0 && (header.origin === "subagent" || (header.delegationDepth ?? 0) > 0)) return;
+  if (session !== void 0 && isSubagentSession(session)) return;
   const path = mutationPathOf(exec);
   if (path === void 0) return;
   const cwd = execSessionCwd(exec, path);
@@ -2751,7 +2754,7 @@ function apply(ctx, config) {
   }, "dsh-rewind command");
   ctx.on("agent/session-start", ({ agent }) => {
     const session = agent.session;
-    if (session.header.origin === "subagent" || (session.header.delegationDepth ?? 0) > 0) return;
+    if (isSubagentSession(session)) return;
     void (async () => {
       try {
         store.setFormatVersion(session.header.version);
@@ -2772,8 +2775,7 @@ function apply(ctx, config) {
   }, { global: true });
   ctx.on("session/event", (session, event) => {
     if (event.type !== "user/message") return;
-    const header = session.header;
-    if (header.origin === "subagent" || (header.delegationDepth ?? 0) > 0) return;
+    if (isSubagentSession(session)) return;
     void (async () => {
       try {
         const sessionId = session.id;
@@ -2803,7 +2805,10 @@ function apply(ctx, config) {
     });
     scope.on("tools/post-execute", async (exec, result, next) => {
       try {
-        void maybeRunAutoCleanup(ctx, store, exec.agent?.session?.id, dshHome);
+        const session = exec.agent?.session;
+        if (session !== void 0 && !isSubagentSession(session)) {
+          void maybeRunAutoCleanup(ctx, store, 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/portals.d.ts

@@ -163,6 +163,40 @@ export declare function actionsContainerOf(row: HTMLElement | undefined): HTMLEl
  * is otherwise only reachable through a full React portal render.
  */
 export declare function collectTargets(chat: HiddenChat, hiddenSeqs: ReadonlySet<number>): readonly PortalTarget[];
+/**
+ * The session-kind slice the durable-target gate reads — the session
+ * snapshot's `subagent` cell, the Harness's own runtime signal for a
+ * direct-subagent (child) session. Typed structurally so the plugin never
+ * imports the session-controller snapshot contract.
+ */
+export interface SessionKindLike {
+    /** Non-null exactly while this Session is addressed as a subagent child. */
+    readonly subagent: unknown;
+}
+/**
+ * Whether a session is rewind-inert: a direct-subagent (child) session.
+ *
+ * The Harness refuses every generic Session RPC for a subagent-owned identity
+ * (`session/agent-busy`, "use subagent delivery for this child session"), so
+ * `/rewind` can never execute there — the command's own admission is the
+ * refusal, before any handler runs. A wired-up ↶ button in such a session is
+ * therefore dead UI that closes its popover and does nothing
+ * (SiriLee/dsh-rewind#26). This mirrors the Harness's own slash-command
+ * directory (which returns no commands for an addressed child), the pending
+ * path's `collectPendingTargets` gate, and the Host's `isSubagentSession`
+ * skips: a child session gets no rewind surface and records no snapshot.
+ */
+export declare function isRewindInertSession(snapshot: SessionKindLike): boolean;
+/**
+ * Collect the durable (sent-message) rewind targets of one session: none at all
+ * for a rewind-inert subagent session, otherwise `collectTargets`' DOM→target
+ * pairing. Kept separate from `collectTargets` so the session-kind gate is a
+ * pure, directly testable decision.
+ * @param snapshot - the session snapshot carrying the `subagent` cell.
+ * @param chat - the session's chat snapshot, or undefined while unavailable.
+ * @param hiddenSeqs - anchor seqs withdrawn by previous rewinds.
+ */
+export declare function collectDurableTargets(snapshot: SessionKindLike, chat: HiddenChat | undefined, hiddenSeqs: ReadonlySet<number>): readonly PortalTarget[];
 interface RewindPortalsProps extends RewindBridgeDeps {
     readonly sessionId: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-rewind-plugin",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "DSH 插件：真正便捷无感的同窗口内对话回退，从不新建分支；自带轻量工作区备份，可一并还原文件（完整 Claude Code /rewind 语义）。 · DSH plugin: genuinely effortless in-window conversation rewind — never forking a new session; ships a lightweight workspace backup that restores files together with the rewind (full Claude Code /rewind semantics).",
   "keywords": [
     "deepseek-harness",