dsh-rewind-plugin 0.20.0-alpha.1 → 0.20.0-alpha.3

package/README.en.md

@@ -1,7 +1,7 @@
 # dsh-rewind
 
-Conversation rewind for DeepSeek Harness: **rewind the conversation to any earlier user message in one click, in the same window** —<br />
-no new branch, no window switch, with optional workspace-file restore (full Claude Code `/rewind` semantics).
+Conversation rewind for DeepSeek Harness: **rewind the conversation to any earlier user message in one click, in the same window**.<br />
+No new branch, no window switch, with optional workspace-file restore — the full Claude Code `/rewind` semantics.
 
 English | [中文](README.md)
 
@@ -9,7 +9,7 @@ English | [中文](README.md)
 [![npm downloads](https://img.shields.io/npm/dt/dsh-rewind-plugin.svg)](https://www.npmjs.com/package/dsh-rewind-plugin)
 [![tests](https://img.shields.io/endpoint?url=https%3A%2F%2Fgist.githubusercontent.com%2FSiriLee%2Fdb3b9260351c2b26eb3d201c2ed29df1%2Fraw%2Fbadge.json)](https://github.com/SiriLee/dsh-rewind/actions/workflows/ci.yml)
 
-![Back to any earlier message: the ↶ rewind button and the conversation-only / conversation-and-files mode popover](docs/preview.svg)
+![Rewind to an earlier message, with optional file restore](docs/preview.svg)
 
 A deliberately focused plugin with one job: **rewind to any user message, no matter how far back, in place** — and conveniently **restore the files it changed** along the way.
 
@@ -43,15 +43,11 @@ Check your local DSH version, then find the matching plugin version in
 dsh plugin --profile <name> add dsh-rewind-plugin@<version>
 ```
 
-**Graphical interface**: the **Plugins** page in the sidebar → **Add plugin** → enter `dsh-rewind-plugin@<version>` → install → restart DSH and refresh the browser.
+**Graphical interface**: the **Plugins** page in the sidebar → **Add plugin** → enter `dsh-rewind-plugin@<version>` → install → restart DSH.
 
 <img src="assets/screenshots/add-plugin.png" width="600" alt="Add plugin dialog: enter dsh-rewind-plugin@version in the field"><br>
 <sub>The screenshot is an example only — use the version that matches your DSH version.</sub>
 
-**Updating**: the command line overwrites the installed version directly; the
-graphical interface rejects a re-install, so uninstall the old version first,
-then install the new one.
-
 > [!WARNING]
 > The npm name `dsh-rewind` belongs to another author's package — install with `dsh-rewind-plugin`.
 
@@ -66,8 +62,8 @@ then install the new one.
 <details>
 <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.
+- **The withdrawn content is preserved** — it stays in the session log and can be inspected in the **Trajectory** panel; you can also disable the plugin to show it again (display only).
+- **A rewind cannot be undone in place** — to carry the content forward, first disable the plugin so the withdrawn content shows again, then click **Branch into a new conversation** on the message just before the rewind; the new conversation's context will include it.
 - **Interruptions rewind too** — a `steering` message the model hasn't read yet is also a valid rewind target, and withdrawing it does not interrupt the current run.
 - **Rewinding a read message interrupts the running turn** — to ensure the rewind runs safely.
 
@@ -79,17 +75,16 @@ then install the new one.
 switched off in this plugin's configuration card. When off, no new snapshots
 are created; file changes made while off cannot be restored. Snapshots (the
 before-write backups) are stored under `<dsh home>/rewind-snapshots/`
-(the default is `~/.dsh/rewind-snapshots/`). For the **same session**, the plugin
-deduplicates snapshots by content and keeps the newest 100 anchor groups.
+(the default is `~/.dsh/rewind-snapshots/`).
 **Deleting that directory manually** only clears the file backups (chat rewinds are
-unaffected); the plugin can rebuild them automatically.
+unaffected); the plugin can rebuild that directory automatically.
 
-A **global auto-cleanup** (off by default) removes the snapshot directories of
+A **snapshot auto-cleanup** (off by default) removes the snapshot directories of
 long-inactive sessions, leaving the active session and chat log untouched. Configure
 and review it on the **Plugins** page, in this plugin's configuration card (the
 auto-cleanup switch and the idle-day cutoff), or use the
 `/snapshot-auto-cleanup` command to **view, configure, and run** it. See:
-[Snapshot cleanup](docs/snapshot-auto-cleanup.md).
+[Snapshot auto-cleanup](docs/snapshot-auto-cleanup.md).
 
 <img src="assets/screenshots/plugin-setting.png" alt="Plugin configuration card: snapshot backups and auto cleanup" width="600">
 
@@ -104,19 +99,19 @@ rm -rf <dsh home>/rewind-snapshots
 rm <dsh home>/snapshot-cleanup-last-sweep.json
 ```
 
-The plugin's auto-cleanup settings live in the current Profile's plugin
-configuration. To remove them completely, delete this plugin entry's configuration.
+The plugin's configuration entries are stored in the current Profile's config
+file `cordis.patch.yml`. To clean up completely, delete the corresponding entries
+manually.
 
-## Why it stands out
+## What this plugin changes
 
-Compared with the common approaches, here is the trade-off this plugin makes on "rewind":
+Compared with the default behavior:
 
-| Dimension | Common approach | This plugin |
+| Dimension | Default behavior | 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 |
-| 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** — nothing is stored unless it changed, and only files touched by write tools are tracked |
+| Conversation rewind | Branch into a new conversation | **In-place rewind** — no new session branch, no window switch, no leftover session copies, and rewinding is more convenient |
+| File restore | Manual restore / Git management | **One-click restore** — lightweight before-write backups; optionally restore files together with the conversation, fitting agent workflows |
+| Restore dependencies | Often needs a Git repository or a full snapshot engine | **None** — no Git repository and no code project required; works in any directory |
 
 ## How it works
 
@@ -131,7 +126,7 @@ The whole design rests on two principles, simple but deliberate: **the conversat
 - **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 DSH (replicating `/compact`, the empty-message mask) are where this plugin is genuinely professional.
+> **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.
 
 ### 2. File restore: lightweight checkpointing, "before-write backup"
 
@@ -155,8 +150,9 @@ This plugin deliberately stays lightweight and focused on one thing — "convers
 
 ## Compatibility
 
-- Node.js `^22.19.0 || >=24.0.0`.
-- Compatibility definition, verification method, and version alignment: see [docs/compat/audit.md](docs/compat/audit.md); supported DSH versions are declared by `package.json` `engines.dsh`.
+- Node.js `>=24.9.0`.
+- Supported DSH versions are declared by `package.json` `engines.dsh`.
+- Compatibility definition, verification method, and version alignment: see [docs/compat/audit.md](docs/compat/audit.md).
 
 > [!WARNING]
 > This project and DeepSeek Harness are both in developer preview. Pin exact
@@ -164,16 +160,17 @@ This plugin deliberately stays lightweight and focused on one thing — "convers
 
 ## Known issues
 
-1. **Exported logs are complete** — a rewind only removes messages from the model context and the view; the exported session log (`/export`) still contains **withdrawn messages**. This plugin cannot alter exports.
+1. **Exported logs are complete** — `/export` exports the whole session log (raw JSONL), **withdrawn content included**; this plugin cannot alter exports.
 2. **Lightweight file rewind has a cost** — in specific cases not all changes can be rewound. Consistent with Claude Code. See: [File-rewind tracking boundary](docs/compat/tracking-boundary.md).
-3. **The turn-rail shows rewound turns** — the right-side rail added in DSH `v0.1.2` keeps ticks for withdrawn messages, and hovering shows the withdrawn text. Only a display difference; no functional impact.
+3. **Turn navigation keeps rewound turns** — the right-side turn navigation keeps an "unloaded" tick for each rewound turn, and hovering previews the withdrawn content. Only a display difference; no functional impact.
+4. **A far rewind may show a blank transcript** — when the target predates the loaded history, the conversation area goes blank; click **Load earlier** to page back until the history appears.
 
 > [!NOTE]
 > Browser diagnostics are available; see [Browser diagnostics](docs/compat/diagnostics.md).
 
 ## 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 files"; 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).
+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 files"; 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 snapshot 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
 
@@ -186,7 +183,7 @@ npm run build          # esbuild: lib/index.js (host ESM) + lib/client.js (loade
 node scripts/verify-host.mjs   # end-to-end verification of the built artifact
 ```
 
-`prepare` runs the full build, so git installs and `npm pack` / `npm publish` always produce a complete `lib/` and the `LICENSE`.
+`prepack` runs the full build, so `npm pack` / `npm publish` always ship a complete `lib/`. Install from npm or a packed tarball — a git checkout has no built `lib/`.
 
 Maintainers: the module map and harness interface reference live in [docs/harness-reference.md](docs/harness-reference.md).
 

package/README.md

@@ -1,7 +1,7 @@
 # dsh-rewind
 
-DeepSeek Harness 插件：**一键就地回退对话到任意更早的用户消息**——<br />
-同窗口内完成，不新建分支、不换窗口，可一并还原工作区文件（完整 Claude Code `/rewind` 语义）。
+DeepSeek Harness 插件：**一键就地回退对话到任意更早的用户消息**。<br />
+同窗口内完成，不新建分支、不换窗口，可一并还原工作区文件——即完整的 Claude Code `/rewind` 语义。
 
 [English](README.en.md) | 中文
 
@@ -9,7 +9,7 @@ DeepSeek Harness 插件：**一键就地回退对话到任意更早的用户消
 [![npm downloads](https://img.shields.io/npm/dt/dsh-rewind-plugin.svg)](https://www.npmjs.com/package/dsh-rewind-plugin)
 [![tests](https://img.shields.io/endpoint?url=https%3A%2F%2Fgist.githubusercontent.com%2FSiriLee%2Fdb3b9260351c2b26eb3d201c2ed29df1%2Fraw%2Fbadge.json)](https://github.com/SiriLee/dsh-rewind/actions/workflows/ci.yml)
 
-![回到任意更早的消息：消息旁的 ↶ 回退按钮与「仅回退对话 / 回退对话和文件」模式选择浮层](docs/preview.zh.svg)
+![回退到更早的消息，可选一并还原文件](docs/preview.zh.svg)
 
 刻意聚焦、保持极简，只做一件事：**就地回退到任意远的用户消息**，还能**顺手还原改过的文件**。
 
@@ -42,13 +42,11 @@ DeepSeek Harness 插件：**一键就地回退对话到任意更早的用户消
 dsh plugin --profile <name> add dsh-rewind-plugin@<版本>
 ```
 
-**图形界面**：侧栏「插件」页 →「添加插件」→ 填 `dsh-rewind-plugin@<版本>` → 安装 → 重启 DSH 并刷新浏览器。
+**图形界面**：侧栏「插件」页 →「添加插件」→ 填 `dsh-rewind-plugin@<版本>` → 安装 → 重启 DSH。
 
 <img src="assets/screenshots/add-plugin.png" width="600" alt="「添加插件」弹窗：在输入框填入 dsh-rewind-plugin@版本号"><br>
 <sub>图片仅为示例，请以实际适配版本号为准。</sub>
 
-**更新**：命令行可直接覆盖安装；图形界面会拒绝重复安装，需先卸载旧版本，再装新版本。
-
 > [!WARNING]
 > npm 上的 `dsh-rewind` 属于其他作者，请用 `dsh-rewind-plugin` 安装。
 
@@ -63,8 +61,8 @@ dsh plugin --profile <name> add dsh-rewind-plugin@<版本>
 <details>
 <summary><b>边界说明</b></summary>
 
-- 回退可以反复进行——没有阶段或次数限制。
-- 回退本身**无法撤销**，但被撤回的内容仍保留在会话日志中。
+- **回退内容完整保存**——被撤回的内容仍在日志中，可在「轨迹」面板查看；也可禁用插件让它们重新显示（仅界面）。
+- **回退无法原地撤销**——但可以先禁用插件让被撤回的内容重新显示，再在回退前的位置上点「在新对话中分支」，新会话的上下文即可包含这些内容。
 - **插话也能回退**——模型尚未读取的 `steering` 插话消息，同样可作为回退目标，不会打断当前生成。
 - **回退已读消息会打断当前正在运行的回合**——确保回退的安全执行。
 
@@ -72,9 +70,9 @@ dsh plugin --profile <name> add dsh-rewind-plugin@<版本>
 
 ## 存储管理
 
-**快照备份**（默认开启）：用于文件还原；可在本插件的配置卡片中关闭。关闭后不再创建新的快照，关闭期间的文件改动无法还原。快照存储于 `<dsh home>/rewind-snapshots/`（默认 `~/.dsh/rewind-snapshots/`）。手动删除该目录仅清除文件备份（对话回退不受影响），插件可自动重建。
+**快照备份**（默认开启）：用于文件还原；可在本插件的配置卡片中关闭。关闭后不再创建新的快照，关闭期间的文件改动无法还原。快照存储于 `<dsh home>/rewind-snapshots/`（默认 `~/.dsh/rewind-snapshots/`）。手动删除该目录仅清除文件备份，对话回退不受影响，插件可自动重建。
 
-**全局自动清理**（默认关闭）：把长期不活跃的会话快照整目录移除，不影响活动会话与对话日志。可在配置卡片查看与配置（自动清理开关、失活天数），也可用 `/snapshot-auto-cleanup` 命令查看、设置和运行。详见：[快照自动清理](docs/snapshot-auto-cleanup.zh.md)。
+**快照自动清理**（默认关闭）：把长期不活跃的会话快照整目录移除，不影响活动会话与对话日志。可在配置卡片查看与配置（自动清理开关、失活天数），也可用 `/snapshot-auto-cleanup` 命令查看、设置和运行。详见：[快照自动清理](docs/snapshot-auto-cleanup.zh.md)。
 
 <img src="assets/screenshots/plugin-setting.png" alt="插件配置卡片：快照备份与自动清理" width="600">
 
@@ -89,18 +87,17 @@ rm -rf <dsh home>/rewind-snapshots
 rm <dsh home>/snapshot-cleanup-last-sweep.json
 ```
 
-插件的自动清理设置保存在当前 Profile 的插件配置中。如需彻底清理，可手动删除对应条目。
+本插件的配置项保存在当前 Profile 的配置文件 `cordis.patch.yml` 中。如需彻底清理，可手动删除对应条目。
 
-## 本插件的优势
+## 本插件的作用
 
-和常见的几种做法相比，本插件在"回退"这件事上的取舍：
+相较于默认行为，本插件带来的变化：
 
-| 维度 | 常见做法 | 本插件 |
+| 维度 | 默认行为 | 本插件 |
 | --- | --- | --- |
-| 对话回退 | Fork 分支新建对话 | **就地回退**——不新建会话、不切窗口，便捷回退 |
-| 文件还原 | 无还原功能 / git 管理或完整快照 | **写前轻量备份**——写文件前自动存原内容，一键还原 |
-| 依赖 | 常依赖 Git 仓库或完整快照引擎 | **无依赖**——不依赖 git，普通目录即可用 |
-| 存储开销 | 整树快照占空间大 | **轻量**——不变不存，且只追踪写类工具改动过的文件 |
+| 对话回退 | 新建分支对话 | **就地回退**——不用新建会话分支、不切窗口，也不产生残留会话副本，回退更便捷 |
+| 文件还原 | 手动还原 / Git 管理 | **一键还原**——写前轻量备份，回退对话时可选一并还原文件，贴合 Agent 工作流 |
+| 还原依赖 | 常依赖 Git 仓库或完整快照引擎 | **无依赖**——不依赖 Git 仓库，也不要求是代码项目，普通目录即可用 |
 
 ## 原理
 
@@ -115,7 +112,7 @@ rm <dsh home>/snapshot-cleanup-last-sweep.json
 - **替换内容无感**——模型对标记忽略、无感（实测验证）。配合插件对界面显示的处理，模型和你看到的对话就是目标消息当时的样子；
 - **记录完整保留**——因为是「遮蔽」而非「删除」，被撤回的内容完整留在日志里，可审计、可追溯，原则上也能手动恢复。
 
-> **设计点睛**：整个对话回退就是**一条**追加。它确定、可审计，且因为日志从未被破坏，回溯是「干净的」——用最小的动作，实现最完整的语义。那些与 DSH 内部的兼容细节（对 `/compact` 的复刻、空消息的遮蔽）正是插件的专业所在。
+> **设计点睛**：整个对话回退就是**一条**追加。它确定、可审计，且因为日志从未被破坏，回溯是「干净的」——用最小的动作，实现最完整的语义。
 
 ### 2. 文件还原：轻量检查点，「写前备份」
 
@@ -131,7 +128,7 @@ rm <dsh home>/snapshot-cleanup-last-sweep.json
 
 ## 明确不做的事
 
-本插件刻意保持轻量、聚焦"对话回退"这一件事，以下场景**不属于它的职责**：
+本插件刻意保持轻量、聚焦「对话回退」这一件事，以下场景**不属于它的职责**：
 
 - **整树 / Git 级快照**——只跟踪写类工具编辑 + 已跟踪文件的外部改动，从未被工具碰过的文件不还原。需要工作树级的完整快照回退时，请交给更专业的快照工具（git）。
 - **子代理的编辑**——不追踪，子代理会话内也不提供回退（同 Claude Code）：子代理运行在自己的会话里，其备份无法由父会话的回退还原，因此也不会为子会话保留备份。
@@ -139,8 +136,9 @@ rm <dsh home>/snapshot-cleanup-last-sweep.json
 
 ## 兼容性
 
-- Node.js `^22.19.0 || >=24.0.0`。
-- 兼容性定义、验证方法与版本对齐详见 [docs/compat/audit.md](docs/compat/audit.md)；支持的 DSH 版本由 `package.json` 的 `engines.dsh` 声明。
+- Node.js `>=24.9.0`。
+- 支持的 DSH 版本由 `package.json` 的 `engines.dsh` 声明。
+- 兼容性定义、验证方法与版本对齐详见 [docs/compat/audit.md](docs/compat/audit.md)。
 
 > [!WARNING]
 > 本项目与 DeepSeek Harness 均处于开发者预览阶段。可复现环境请 pin 精确版本，
@@ -148,16 +146,17 @@ rm <dsh home>/snapshot-cleanup-last-sweep.json
 
 ## 已知问题
 
-1. **导出的日志是完整内容**——回退只是把消息从模型上下文和视图中移除，`/export` 导出的会话日志包含**已撤回的消息**。本插件无法改动导出。
+1. **导出的日志是完整内容**——`/export` 导出整个会话日志（原始 JSONL），包含**已撤回的内容**；本插件无法改动导出。
 2. **轻量文件回退存在代价**——特定情况可能无法回退所有修改。行为与 Claude Code 一致。详见：[文件回退的追踪边界](docs/compat/tracking-boundary.zh.md)。
-3. **导轨显示已回退轮次**——DSH `v0.1.2` 新增右侧导轨，为已撤回消息保留刻度，悬浮显示已撤回正文。仅显示差异，无功能影响。
+3. **轮次导航保留已回退轮次**——右侧轮次导航为已回退轮次保留「未加载」刻度，悬浮可预览已撤回内容。仅显示差异，无功能影响。
+4. **较远回退可能显示空白**——回退目标早于已加载的历史时，对话区会显示空白；需点击「加载更早」往前翻，才能看到历史对话。
 
 > [!NOTE]
 > 本插件提供浏览器端诊断输出；详见 [浏览器诊断](docs/compat/diagnostics.zh.md)。
 
 ## 安全
 
-本插件只向会话日志追加回退标记事件，从不删除或改写已记录的历史。工作区文件仅在「回退对话和文件」时被改写，备份存储于 `<dsh home>/rewind-snapshots/`；还原以备份为唯一来源。不触碰你的 git 仓库，无网络请求，不访问任何凭据。对**长期不活跃**的会话，另有默认关闭的全局自动清理可整目录移除其快照，不影响活动会话与对话日志。完整安全模型：[SECURITY.md](SECURITY.md)。
+本插件只向会话日志追加回退标记事件，从不删除或改写已记录的历史。工作区文件仅在「回退对话和文件」时被改写，备份存储于 `<dsh home>/rewind-snapshots/`；还原以备份为唯一来源。不触碰你的 git 仓库，无网络请求，不访问任何凭据。对**长期不活跃**的会话，另有默认关闭的快照自动清理可整目录移除其快照，不影响活动会话与对话日志。完整安全模型：[SECURITY.md](SECURITY.md)。
 
 ## 开发
 
@@ -170,7 +169,7 @@ npm run build          # esbuild：lib/index.js（host ESM）+ lib/client.js（l
 node scripts/verify-host.mjs   # 端到端验证构建产物
 ```
 
-`prepare` 执行完整构建，所以 git 安装与 `npm pack` / `npm publish` 总会产出完整的 `lib/` 与 `LICENSE`。
+`prepack` 在打包前执行完整构建，所以 `npm pack` / `npm publish` 总会产出完整的 `lib/`。请从 npm 或打好的 tarball 安装——git 检出的源码里没有构建好的 `lib/`。
 
 维护者：模块地图与 harness 接口参考见 [docs/harness-reference.md](docs/harness-reference.md)
 

package/lib/client.js

@@ -108,27 +108,30 @@ function messageTextAt(chat, seq) {
   }
   return void 0;
 }
+function imageRefsOf(content) {
+  const images = [];
+  for (const block of content ?? []) {
+    if (block.type !== "image") continue;
+    const attachment = block.attachment;
+    if (typeof attachment?.attachmentId !== "string" || typeof attachment.mediaType !== "string") continue;
+    images.push({
+      attachmentId: attachment.attachmentId,
+      mediaType: attachment.mediaType,
+      bytes: typeof attachment.bytes === "number" ? attachment.bytes : void 0,
+      width: typeof attachment.width === "number" ? attachment.width : void 0,
+      height: typeof attachment.height === "number" ? attachment.height : void 0,
+      name: typeof attachment.name === "string" ? attachment.name : void 0
+    });
+  }
+  return images;
+}
 function messageAttachmentsAt(chat, seq) {
   if (chat === void 0) return void 0;
   for (const node of chatNodesOf(chat)) {
     if (node.kind !== "user" && node.kind !== "steering") continue;
     const data = node.data;
     if (data.seq !== seq) continue;
-    const images = [];
-    for (const block of data.content ?? []) {
-      if (block.type !== "image") continue;
-      const attachment = block.attachment;
-      if (typeof attachment?.attachmentId !== "string" || typeof attachment.mediaType !== "string") continue;
-      images.push({
-        attachmentId: attachment.attachmentId,
-        mediaType: attachment.mediaType,
-        bytes: typeof attachment.bytes === "number" ? attachment.bytes : void 0,
-        width: typeof attachment.width === "number" ? attachment.width : void 0,
-        height: typeof attachment.height === "number" ? attachment.height : void 0,
-        name: typeof attachment.name === "string" ? attachment.name : void 0
-      });
-    }
-    return images;
+    return imageRefsOf(data.content);
   }
   return void 0;
 }
@@ -1089,6 +1092,7 @@ function steeringItemsOf(nextStep) {
       id: item.id,
       text,
       attachments: attachmentsCountOf(item.content),
+      images: imageRefsOf(item.content),
       preview: previewOf(text)
     };
   });
@@ -1402,6 +1406,7 @@ function RewindPortals({ sessionId, sessionOf, chatOf, isMainViewSession, watchC
         sessionId,
         sessionOf,
         setComposerText,
+        restoreImages,
         t
       },
       target.key
@@ -1463,8 +1468,9 @@ function composerText() {
   if (surface === null) return "";
   return surface.textContent ?? "";
 }
-async function retractPending(session, itemId, text, setComposerText) {
+async function retractPending(session, itemId, text, setComposerText, restoreImages) {
   const steering = steeringItemsOf(inboxOf(session)?.["next-step"]);
+  const images = steering.find((item) => item.id === itemId)?.images ?? [];
   let removedTarget = false;
   for (const id of retractSpan(steering, itemId)) {
     let accepted = false;
@@ -1478,11 +1484,19 @@ async function retractPending(session, itemId, text, setComposerText) {
     if (!accepted) break;
     if (id === itemId) removedTarget = true;
   }
-  if (removedTarget && text !== null && text !== "" && composerText().trim() === "") {
+  if (!removedTarget) return;
+  if (images.length > 0 && restoreImages !== void 0) {
+    try {
+      await restoreImages(session.sessionId, images);
+    } catch (error) {
+      rewindLog.warn("retract", `image restore for ${itemId} threw`, error);
+    }
+  }
+  if (text !== null && text !== "" && composerText().trim() === "") {
     setComposerText(session.sessionId, text);
   }
 }
-function RetractButton({ target, sessionId, sessionOf, setComposerText, t }) {
+function RetractButton({ target, sessionId, sessionOf, setComposerText, restoreImages, t }) {
   const onClick = (event) => {
     event.stopPropagation();
     const session = sessionOf(sessionId);
@@ -1494,7 +1508,7 @@ function RetractButton({ target, sessionId, sessionOf, setComposerText, t }) {
       t,
       retract: { itemId: target.itemId, text: target.text },
       onRetract: () => {
-        void retractPending(session, target.itemId, target.text, setComposerText);
+        void retractPending(session, target.itemId, target.text, setComposerText, restoreImages);
       }
     });
   };
@@ -1576,9 +1590,9 @@ async function candidatesOverRpc(connection, sessionId) {
 }
 
 // src/client/build-info.ts
-var PLUGIN_VERSION = true ? "0.20.0-alpha.1" : "dev";
+var PLUGIN_VERSION = true ? "0.20.0-alpha.3" : "dev";
 var PLUGIN_PACKAGE = "dsh-rewind-plugin";
-var BUILD_HASH = true ? "fa33ad17" : "dev";
+var BUILD_HASH = true ? "46008907" : "dev";
 
 // src/client/locales.ts
 var en = {

package/lib/index.js

@@ -650,10 +650,13 @@ function refToSource(raw, sessionDir) {
   if (typeof ref.text === "string") return textSourceOf(ref.text);
   return void 0;
 }
+function sessionRelativeRef(sessionDir, file) {
+  return relative(sessionDir, file).split(sep).join("/");
+}
 function sourceToRef(source, sessionDir, entryPath) {
   if (source === null) return null;
   if (source.kind === "blob") {
-    const blob = relative(sessionDir, source.path);
+    const blob = sessionRelativeRef(sessionDir, source.path);
     if (!isSafeBackupRef(blob)) throw new Error(`unsafe backup ref ${blob} for ${entryPath}`);
     return { blob };
   }
@@ -996,7 +999,7 @@ var SnapshotStore = class _SnapshotStore {
    * the call id would produce a dangling reference.
    */
   refOfRead(sessionId, entry) {
-    if (entry.file !== void 0) return relative(this.sessionDir(sessionId), entry.file);
+    if (entry.file !== void 0) return sessionRelativeRef(this.sessionDir(sessionId), entry.file);
     return this.entryRefOf(sessionId, entry.callId, entry.anchorSeq);
   }
   /** Drop every in-memory trace of one session (its directory is gone). */
@@ -2064,7 +2067,7 @@ var SnapshotStore = class _SnapshotStore {
       for (const action of journal.actions) {
         const source = action.before;
         if (source === null || source.kind !== "blob") continue;
-        const ref = relative(sessionDir, source.path);
+        const ref = sessionRelativeRef(sessionDir, source.path);
         if (!isSafeBackupRef(ref)) continue;
         const anchor = refAnchorOf(ref);
         if (Number.isSafeInteger(anchor)) pinned.add(anchor);

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

@@ -103,6 +103,25 @@ export interface MessageImageRef {
     readonly height?: number;
     readonly name?: string;
 }
+/** One wire content block that may carry a durable image reference. */
+export interface ImageBlockLike {
+    readonly type?: string;
+    readonly attachment?: {
+        readonly attachmentId?: unknown;
+        readonly mediaType?: unknown;
+        readonly bytes?: unknown;
+        readonly width?: unknown;
+        readonly height?: unknown;
+        readonly name?: unknown;
+    };
+}
+/**
+ * Image references carried by a message's content blocks, in order.
+ * Malformed and non-image blocks are skipped; `file` blocks are not restorable.
+ * @param content - one message's content blocks.
+ * @returns the image references, in message order.
+ */
+export declare function imageRefsOf(content: readonly ImageBlockLike[] | undefined): readonly MessageImageRef[];
 /**
  * The durable image references of the human message at `seq` in the chat
  * snapshot, in message order. The composer-refill counterpart of

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

@@ -17,6 +17,7 @@
  *
  * @module dsh-rewind/client/pending
  */
+import { type ImageBlockLike, type MessageImageRef } from './hidden.ts';
 /** One rendered pending-steering bubble row (only the fields matching reads). */
 export interface PendingRow {
     /** The bubble's message text, excluding the actions container (see module doc). */
@@ -24,8 +25,8 @@ export interface PendingRow {
     /** Message-attachment blocks the row renders; compared against the item's count. */
     readonly attachments: number;
 }
-/** One wire content block of an inbox row (only the fields the derivation reads). */
-export interface InboxBlockLike {
+/** One wire content block of an inbox row. */
+export interface InboxBlockLike extends ImageBlockLike {
     /** Wire block type (`text` | `image` | `file` | …). */
     readonly type: string;
     /** The block's text, on a `text` block. */
@@ -59,6 +60,8 @@ export interface PendingSteeringItem {
     readonly text: string | null;
     /** Non-text blocks (image/file/…) the message carries, in prompt order. */
     readonly attachments: number;
+    /** Image references the message carries, in prompt order. */
+    readonly images: readonly MessageImageRef[];
     /** Space-collapsed preview with image/file blocks excluded (the harness QueueDock rule). */
     readonly preview: string;
 }

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

@@ -280,9 +280,8 @@ export declare function composerText(): string;
  *
  * 1. Remove the target and its future (steering only; queued stays) through
  *    the session's own `updateQueue` channel, oldest first.
- * 2. Put the target's text back in the composer ONLY when the target was
- *    actually removed and the composer is empty (Claude Code's auto-restore
- *    guard, so a draft the user is typing is never clobbered).
+ * 2. Put the target's own images back, then its text when the composer is
+ *    empty (the empty-composer guard, so a draft is never clobbered).
  *
  * The realistic failure is `queue-item-not-found`: a step boundary claimed
  * the whole next-step batch a moment ago, so the message is now durable and
@@ -290,7 +289,7 @@ export declare function composerText(): string;
  * removed then, and the composer is NOT refilled — refilling would invite a
  * duplicate send of a message the model has already received.
  */
-export declare function retractPending(session: SessionFace, itemId: string, text: string | null, setComposerText: (sessionId: string, text: string) => boolean): Promise<void>;
+export declare function retractPending(session: SessionFace, itemId: string, text: string | null, setComposerText: (sessionId: string, text: string) => boolean, restoreImages?: (sessionId: string, images: readonly MessageImageRef[]) => Promise<void>): Promise<void>;
 /**
  * Build the slot-entry component for the plugin apply(): a tiny bridge that
  * injects the apply-time capabilities (session resolution, locale, rewind

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-rewind-plugin",
-  "version": "0.20.0-alpha.1",
+  "version": "0.20.0-alpha.3",
   "description": "In-window conversation rewind with workspace file restore",
   "icon": "./assets/icon.svg",
   "keywords": [
@@ -17,6 +17,9 @@
     "url": "git+https://github.com/SiriLee/dsh-rewind.git"
   },
   "homepage": "https://github.com/SiriLee/dsh-rewind#readme",
+  "bugs": {
+    "url": "https://github.com/SiriLee/dsh-rewind/issues"
+  },
   "license": "MIT",
   "engines": {
     "node": ">=24.9.0",
@@ -70,7 +73,7 @@
     "verify:host": "node scripts/verify-host.mjs",
     "verify:previews": "node scripts/verify-preview-assets.mjs",
     "check": "npm run typecheck && npm run build && npm test && node scripts/verify-host.mjs && npm pack --dry-run",
-    "prepare": "npm run build"
+    "prepack": "npm run build"
   },
   "publishConfig": {
     "access": "public"