@kangyishuai/dsh-session-rewind 0.1.1 → 0.3.0

package/README.md

@@ -15,12 +15,24 @@ Unofficial plugin for [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/de
 Long conversations drift. A few turns later you wish you had answered a prompt differently, but starting a new session loses everything before it, and continuing keeps the unwanted turns in the context window forever. This plugin rewinds **in place**:
 
 - **Two entries.** Press `Esc` `Esc` to open the rewind dialog, or click the ↶ button in any user message's action row (next to Copy).
+- **Running turns are not a dead end.** Confirming a rewind while a turn is running cancels that turn (keeping the queue), waits for it to go idle, then re-plans against the settled history.
 - **Two scopes, chosen per rewind.** The confirmation dialog offers **Rewind conversation only** (default) and **Rewind conversation and files**. The dialog first shows a dry-run preview: how many messages and roughly how many tokens will be withdrawn, which files will be restored or moved to the trash, conflicts, and skipped files.
 - **Conversation.** The target message and everything after it are withdrawn from the model-visible context and from the transcript. The session id, title and earlier history are untouched. Nothing is deleted from the log — one marker event is appended.
 - **Files (optional).** Files changed by `write` / `edit` / `apply_patch` in the withdrawn turns are restored to their pre-change content. Files created after the target are moved to the plugin's trash instead of deleted. A rescue point of the current files is created before anything is written; failures roll back from it.
-- **Composer.** The target message's text (and images) is put back into the composer, ready to edit and send again. An existing draft is never overwritten.
+- **Composer.** The target message's text (and images) is put back into the composer, ready to edit and send again. An existing draft is never overwritten. Tick **Send this message again right after rewinding** in the confirmation dialog to retry the turn in one click (conversation-only rewinds).
 - **Rewind panel.** A new header action opens a panel with four tabs: **Withdrawn** (every message each rewind removed, searchable, copy or put back in the composer), **History** (audit of each rewind: scope, message count, tokens, file results), **Rescue points** (restore files from an earlier rescue), and **Settings** (default scope, page size, confirm-on-list, diagnostics).
 
+## Read-only agent tool
+
+The plugin also registers one **read-only** tool, `session_rewind_candidates`, so the model can reason about rewinding without performing it:
+
+| Call                                       | Result                                                                                                                                         |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `session_rewind_candidates {}`             | Newest-first list of messages this conversation can be rewound to (`query` filters, `limit` caps at 50).                                       |
+| `session_rewind_candidates { target_seq }` | Impact preview for one message: how many messages would be withdrawn, whether an unfinished tool call would be truncated, and the target text. |
+
+The tool never rewinds, never edits files and never appends to the session log — the rewind itself stays a user action (that is the point of the ADR 0006 design). Set `readOnlyTool: false` to unregister it; **Settings → Diagnostics** reports whether it registered.
+
 ## Install
 
 ```bash
@@ -49,14 +61,14 @@ Re-run `pnpm pack` + `add` after changing the code. The plugin has a host half,
 
 **What is refused**
 
-| Situation                                                                | What happens                                                                           |
-| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
-| The session has a running turn                                           | The host refuses (`session-rewind/busy`); stop the turn first and retry.               |
-| The session is a subagent child                                          | No ↶ button and no `Esc` `Esc` dialog: the Harness refuses generic session RPCs there. |
-| The target message was shadowed by compaction                            | Refused; the rewind boundary must still be in the model context.                       |
-| A file was changed outside the agent since the last recorded state       | File mode is refused with a conflict list; no file is touched.                         |
-| A file is larger than 8 MiB, a symlink, or under `.git` / `node_modules` | That file is skipped and reported; other files still proceed.                          |
-| A rewind is already running on this session                              | Refused; one at a time.                                                                |
+| Situation                                                                | What happens                                                                                                                                              |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The session has a running turn                                           | It is cancelled first (queued steering messages are dropped), then the rewind runs. Set `cancelRunning: false` to refuse instead (`session-rewind/busy`). |
+| The session is a subagent child                                          | No ↶ button and no `Esc` `Esc` dialog: the Harness refuses generic session RPCs there.                                                                    |
+| The target message was shadowed by compaction                            | Refused; the rewind boundary must still be in the model context.                                                                                          |
+| A file was changed outside the agent since the last recorded state       | File mode is refused with a conflict list; no file is touched.                                                                                            |
+| A file is larger than 8 MiB, a symlink, or under `.git` / `node_modules` | That file is skipped and reported; other files still proceed.                                                                                             |
+| A rewind is already running on this session                              | Refused; one at a time.                                                                                                                                   |
 
 ## File restore scope & safety
 

package/README.zh-CN.md

@@ -18,9 +18,21 @@
 - **每次回溯二选一**：确认框里提供「**仅回退对话**」（默认）与「**回退对话和文件**」，并先展示 dry-run 预览：将撤回多少条消息、约多少 token、哪些文件会还原/移入回收站、冲突与被跳过的文件。
 - **对话**：目标消息及其后的内容从模型上下文和渲染对话中撤回；会话 id、标题和目标之前的历史不变；日志只追加一条 marker，不删历史。
 - **文件（可选）**：被撤回轮次里由 `write` / `edit` / `apply_patch` 改过的文件还原到改动前内容；目标之后新建的文件移入插件回收站而不是删除。写入前先建救援点，失败从救援点回滚。
-- **输入框**：目标消息文本（以及图片）放回输入框，改完可直接重发；已有草稿绝不覆盖。
+- **运行中也能回退**：确认回退时如果这一轮正在跑，会先取消它（保留队列）、等它空闲，再对新历史重新求值。
+- **输入框**：目标消息文本（以及图片）放回输入框，改完可直接重发；已有草稿绝不覆盖。勾选「回退后立即重发」可一键重试这一轮（仅对话模式）。
 - **回溯面板**：会话头部新增一个入口，四个页签：**已撤回**（每次回溯撤回的全部消息，可搜索、复制、放回输入框）、**回溯记录**（审计：范围、条数、token、文件结果）、**救援点**（手动恢复文件）、**设置**（默认范围、每页数量、列表确认、诊断）。
 
+## 只读 agent 工具
+
+插件还会注册一个**只读**工具 `session_rewind_candidates`，让模型能自己判断「能退回到哪、退回去会丢什么」，但**不执行**回溯：
+
+| 调用                                       | 结果                                                                 |
+| ------------------------------------------ | -------------------------------------------------------------------- |
+| `session_rewind_candidates {}`             | 按新→旧列出可回退的消息（`query` 过滤，`limit` 上限 50）。           |
+| `session_rewind_candidates { target_seq }` | 单条消息的影响面：会撤回多少条、是否截断未完成的工具调用、目标文本。 |
+
+这个工具不回溯、不碰文件、不写会话日志——真正的回退始终由用户在界面确认（这是 ADR 0006 的设计前提）。设 `readOnlyTool: false` 可关闭；**设置 → 诊断**里能看到它是否注册成功。
+
 ## 安装
 
 ```bash
@@ -49,14 +61,14 @@ dsh plugin --profile desktop add /tmp/kangyishuai-dsh-session-rewind-*.tgz
 
 **会被拒绝的情况**
 
-| 情况                                                        | 表现                                                              |
-| ----------------------------------------------------------- | ----------------------------------------------------------------- |
-| 会话有正在运行的回合                                        | 宿主返回 `session-rewind/busy`；先停止回合再回溯。                |
-| 子代理会话                                                  | 没有 ↶ 按钮，`Esc` `Esc` 也不弹框：宿主拒绝对这类会话的通用 RPC。 |
-| 目标消息已被 compaction 遮蔽                                | 拒绝；回溯边界必须仍在模型上下文里。                              |
-| 文件在上次记录后被外部修改                                  | 文件模式整体拒绝并列出冲突文件；一个文件都不动。                  |
-| 文件超过 8 MiB、是符号链接、或在 `.git` / `node_modules` 下 | 该文件跳过并报告，其余文件继续。                                  |
-| 同一会话已有回溯在执行                                      | 拒绝；一次只允许一个。                                            |
+| 情况                                                        | 表现                                                                                                                      |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| 会话有正在运行的回合                                        | 先取消该回合并等到 idle（队列里未投递的插话会被丢弃），再回溯；设 `cancelRunning: false` 则仍返回 `session-rewind/busy`。 |
+| 子代理会话                                                  | 没有 ↶ 按钮，`Esc` `Esc` 也不弹框：宿主拒绝对这类会话的通用 RPC。                                                         |
+| 目标消息已被 compaction 遮蔽                                | 拒绝；回溯边界必须仍在模型上下文里。                                                                                      |
+| 文件在上次记录后被外部修改                                  | 文件模式整体拒绝并列出冲突文件；一个文件都不动。                                                                          |
+| 文件超过 8 MiB、是符号链接、或在 `.git` / `node_modules` 下 | 该文件跳过并报告，其余文件继续。                                                                                          |
+| 同一会话已有回溯在执行                                      | 拒绝；一次只允许一个。                                                                                                    |
 
 ## 文件还原的范围与安全
 

package/lib/agent-settle.js

@@ -0,0 +1,108 @@
+// @ts-check
+// 回溯前把运行中的回合停下来：取消（保留 inbox）→ 等 idle → 丢弃尚未投递的 steering。
+// 纯逻辑 + 注入 wait，便于用假 agent 单测；不 import 任何宿主包。
+//
+// DSH 0.2.2-rc.1 的 Agent 形状：
+//   - agent.status: "idle" | "running"
+//   - agent.cancel(cause, { keepInbox })：keepInbox 时不清空队列
+//   - agent.whenIdle(): Promise<void>（回合结束后 resolve）
+//   - agent.inbox.nextStep: 待投递的插话消息；agent.inbox.remove(id)
+
+/** 默认等待 idle 的超时（毫秒）。 */
+export const DEFAULT_CANCEL_TIMEOUT_MS = 15_000;
+
+/**
+ * @typedef {object} SettleResult
+ * @property {boolean} cancelled 是否发起过取消
+ * @property {boolean} idle 是否最终空闲
+ * @property {string[]} droppedSteering 丢弃的插话消息 id
+ */
+
+/**
+ * 等待 agent 空闲；优先用宿主提供的 whenIdle，否则轮询 status。
+ * @param {any} agent
+ * @param {number} timeoutMs
+ * @param {(ms: number) => Promise<void>} sleep
+ * @returns {Promise<boolean>}
+ */
+async function waitForIdle(agent, timeoutMs, sleep) {
+  const timeout = new Promise((resolve) => {
+    void sleep(timeoutMs).then(() => resolve(false));
+  });
+  if (typeof agent?.whenIdle === "function") {
+    try {
+      const idle = Promise.resolve(agent.whenIdle()).then(
+        () => true,
+        () => false,
+      );
+      return await Promise.race([idle, timeout]);
+    } catch (_error) {
+      return false;
+    }
+  }
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (agent?.status === "idle") return true;
+    await sleep(100);
+  }
+  return agent?.status === "idle";
+}
+
+/**
+ * 丢弃 next-step（尚未投递的插话）消息。
+ * @param {any} agent
+ * @returns {string[]}
+ */
+function dropPendingSteering(agent) {
+  /** @type {string[]} */
+  const dropped = [];
+  try {
+    const pending = agent?.inbox?.nextStep;
+    if (!pending || typeof agent?.inbox?.remove !== "function") return dropped;
+    for (const message of [...pending]) {
+      if (message && typeof message.id === "string" && message.id !== "") {
+        try {
+          agent.inbox.remove(message.id);
+          dropped.push(message.id);
+        } catch (_error) {
+          /* 单条失败不影响其余 */
+        }
+      }
+    }
+  } catch (_error) {
+    /* inbox 形状不符时放弃丢弃 */
+  }
+  return dropped;
+}
+
+/**
+ * 停下运行中的回合并等待空闲。已经空闲时是 no-op。
+ * @param {any} agent
+ * @param {{timeoutMs?: number, sleep?: (ms: number) => Promise<void>}} [options]
+ * @returns {Promise<SettleResult>}
+ */
+export async function settleAgent(agent, options = {}) {
+  if (!agent || agent.status === "idle")
+    return { cancelled: false, idle: true, droppedSteering: [] };
+  const timeoutMs =
+    typeof options.timeoutMs === "number" &&
+    Number.isFinite(options.timeoutMs) &&
+    options.timeoutMs > 0
+      ? options.timeoutMs
+      : DEFAULT_CANCEL_TIMEOUT_MS;
+  const sleep =
+    typeof options.sleep === "function"
+      ? options.sleep
+      : (/** @type {number} */ ms) => new Promise((resolve) => setTimeout(resolve, ms));
+  try {
+    if (typeof agent.cancel === "function") agent.cancel({ kind: "user" }, { keepInbox: true });
+  } catch (_error) {
+    /* 取消失败时仍尝试等待 idle；超时会交给调用方报错 */
+  }
+  const idle = await waitForIdle(agent, timeoutMs, sleep);
+  return {
+    cancelled: true,
+    idle,
+    droppedSteering: idle ? dropPendingSteering(agent) : [],
+  };
+}

package/lib/client.js

@@ -45,6 +45,7 @@ window.__ModuleLoader__.load({
       "dialog.cancel": "取消",
       "dialog.confirm": "开始回退",
       "dialog.executing": "正在回退…",
+      "dialog.settling": "正在停止当前回合并回退…",
       "dialog.loading": "正在读取…",
       "dialog.empty": "没有可回溯的消息。",
       "dialog.previewLoading": "正在计算影响面…",
@@ -65,7 +66,11 @@ window.__ModuleLoader__.load({
       "confirm.pathsLess": "收起路径",
       "confirm.skipped": "{n} 个文件被跳过",
       "confirm.conflictsTitle": "冲突文件（前 5 个）",
-      "confirm.busy": "当前回合仍在运行，请先停止后再回退",
+      "confirm.busy": "当前回合仍在运行：回退时会先停止它，队列中未投递的插话会被丢弃",
+      "confirm.settling": "正在停止当前回合…",
+      "confirm.resend": "回退后立即重发这条消息",
+      "confirm.resendHint":
+        "适合「重试这一轮」：回退后自动把原文发出去，想改内容就在输入框里编辑后再发。",
       "confirm.openToolCall": "目标之后有未完成的工具调用，回溯会截断它",
       "toast.done": "已回退到此处，原消息已放回输入框",
       "toast.draft": "已回退；输入框已有内容，未覆盖",
@@ -73,6 +78,8 @@ window.__ModuleLoader__.load({
       "toast.rewound": "已回退 {n} 条消息（约 {tokens} token）",
       "toast.rewoundFiles": "，还原 {restored} 个文件、移入回收站 {trashed} 个",
       "toast.rewoundFailed": "，{n} 个文件处理失败",
+      "toast.resent": "，已重发这条消息",
+      "toast.stoppedTurn": "，已停止运行中的回合",
       "toast.draftKept": "；输入框已有内容，未覆盖",
       "toast.noComposerSuffix": "；未找到输入框",
       "toast.view": "查看",
@@ -166,6 +173,7 @@ window.__ModuleLoader__.load({
       "dialog.cancel": "Cancel",
       "dialog.confirm": "Start rewind",
       "dialog.executing": "Rewinding…",
+      "dialog.settling": "Stopping the running turn, then rewinding…",
       "dialog.loading": "Loading…",
       "dialog.empty": "No messages to rewind to.",
       "dialog.previewLoading": "Computing the impact…",
@@ -187,8 +195,15 @@ window.__ModuleLoader__.load({
       "confirm.pathsLess": "Hide paths",
       "confirm.skipped": "{n} file(s) skipped",
       "confirm.conflictsTitle": "Conflicting files (first 5)",
-      "confirm.busy": "The turn is still running; stop it before rewinding.",
+      "confirm.busy":
+        "The turn is still running: rewinding stops it first and drops any queued steering messages.",
+      "confirm.settling": "Stopping the running turn…",
+      "confirm.resend": "Send this message again right after rewinding",
+      "confirm.resendHint":
+        "Use this to retry a turn; to change the text, edit it in the composer instead.",
       "confirm.openToolCall": "An unfinished tool call follows the target; rewinding truncates it.",
+      "toast.stoppedTurn": ", and the running turn was stopped",
+      "toast.resent": ", and the message was sent again",
       "toast.done": "Rewound. The original message is back in the composer.",
       "toast.draft": "Rewound. The composer already had content, so it was kept.",
       "toast.noComposer": "Rewound, but no composer was found.",
@@ -1139,6 +1154,11 @@ window.__ModuleLoader__.load({
         text: text,
         images: imageRefsOf(source),
         files: filesReceiptOf(source.files),
+        cancelledTurn: source.cancelledTurn === true,
+        droppedSteering:
+          typeof source.droppedSteering === "number" && source.droppedSteering > 0
+            ? source.droppedSteering
+            : 0,
       };
     }
 
@@ -1960,8 +1980,37 @@ window.__ModuleLoader__.load({
         }
       }
 
+      // 「回退后立即重发」：仅对话模式提供（文件模式先还原文件，语义不同）。
+      if (state.rewindMode !== "both" && state.previewLoading !== true) {
+        blocks.push(
+          h(
+            "div",
+            { key: "resend", className: "dsh-srw-setting" },
+            h(
+              "label",
+              { className: "dsh-srw-check" },
+              h("input", {
+                type: "checkbox",
+                "data-rewind-resend": "true",
+                checked: state.resend === true,
+                onChange: (/** @type {any} */ event) => {
+                  if (event?.target) api.setResend(event.target.checked === true);
+                },
+              }),
+              h("span", null, t("confirm.resend")),
+            ),
+            h("div", { className: "dsh-srw-option-hint" }, t("confirm.resendHint")),
+          ),
+        );
+      }
       if (state.busy) {
-        blocks.push(h("div", { key: "busy", className: "dsh-srw-warn" }, t("confirm.busy")));
+        blocks.push(
+          h(
+            "div",
+            { key: "busy", className: "dsh-srw-warn" },
+            state.executing === true ? t("confirm.settling") : t("confirm.busy"),
+          ),
+        );
       }
       if (state.errorKey) {
         blocks.push(
@@ -2077,8 +2126,8 @@ window.__ModuleLoader__.load({
 
       let footer;
       if (confirmMode) {
-        let disabled =
-          state.busy === true || state.executing === true || state.previewLoading === true;
+        // v2.1：运行中的回合不再阻止执行——宿主会先取消并等到 idle 再回溯。
+        let disabled = state.executing === true || state.previewLoading === true;
         let executing = state.executing === true || state.loading === true;
         footer = h(
           Fragment,
@@ -2091,7 +2140,11 @@ window.__ModuleLoader__.load({
               disabled: disabled,
               onClick: () => api.doRewind(),
             },
-            executing ? t("dialog.executing") : t("dialog.confirm"),
+            executing
+              ? state.busy === true
+                ? t("dialog.settling")
+                : t("dialog.executing")
+              : t("dialog.confirm"),
           ),
         );
       } else {
@@ -2720,7 +2773,7 @@ window.__ModuleLoader__.load({
         } else if (state.mode === "confirm" && event.key === "Enter") {
           event.preventDefault();
           event.stopPropagation();
-          if (!state.busy && !state.executing && !state.previewLoading) api.doRewind();
+          if (!state.executing && !state.previewLoading) api.doRewind();
         }
         return;
       }
@@ -3059,6 +3112,7 @@ window.__ModuleLoader__.load({
         previewErrorParams: null,
         rewindMode: "chat",
         showAllPaths: false,
+        resend: false,
         busy: false,
         executing: false,
         loading: false,
@@ -3182,6 +3236,32 @@ window.__ModuleLoader__.load({
       }
 
       /** 回填输入框；返回 'ok' | 'draft' | 'none'。 */
+      /** 复用刚回填的 draft 直接提交（「回退后立即重发」）。 @param {any} sessionId */
+      function submitComposer(/** @type {any} */ sessionId) {
+        try {
+          let conversation = safeGet(ctx, "conversation");
+          let scope =
+            ctx.sessions && typeof ctx.sessions.scope === "function"
+              ? ctx.sessions.scope(sessionId)
+              : undefined;
+          if (!conversation?.input || typeof conversation.input.for !== "function") return false;
+          if (scope === undefined) return false;
+          let facade = conversation.input.for(scope);
+          if (!facade) return false;
+          if (facade.actions && typeof facade.actions.submit === "function") {
+            facade.actions.submit();
+            return true;
+          }
+          if (typeof facade.submit === "function") {
+            facade.submit("queue");
+            return true;
+          }
+          return false;
+        } catch (_error) {
+          return false;
+        }
+      }
+
       function fillComposer(/** @type {any} */ sessionId, /** @type {any} */ text) {
         let facade;
         try {
@@ -3298,6 +3378,7 @@ window.__ModuleLoader__.load({
           previewLoading: false,
           previewErrorKey: null,
           previewErrorParams: null,
+          resend: false,
           busy: false,
           executing: false,
           loading: false,
@@ -3393,6 +3474,7 @@ window.__ModuleLoader__.load({
           previewErrorParams: null,
           rewindMode: effectiveMode(prefs.defaultMode, null),
           showAllPaths: false,
+          resend: false,
           busy: busy,
           executing: false,
           loading: false,
@@ -3435,6 +3517,11 @@ window.__ModuleLoader__.load({
       }
 
       /** 确认框里切换回退范围。 */
+      /** 「回退后立即重发」勾选。 @param {boolean} value */
+      function setResend(/** @type {any} */ value) {
+        patch({ resend: value === true });
+      }
+
       function setRewindMode(/** @type {any} */ mode) {
         patch({ rewindMode: mode === "both" ? "both" : "chat" });
       }
@@ -3461,6 +3548,7 @@ window.__ModuleLoader__.load({
           previewLoading: false,
           previewErrorKey: null,
           previewErrorParams: null,
+          resend: false,
           busy: false,
           executing: false,
           loading: false,
@@ -3479,6 +3567,7 @@ window.__ModuleLoader__.load({
           previewLoading: false,
           previewErrorKey: null,
           previewErrorParams: null,
+          resend: false,
           busy: false,
           executing: false,
           loading: false,
@@ -3531,6 +3620,8 @@ window.__ModuleLoader__.load({
         let state = store.getSnapshot();
         if (state?.executing) return;
         let wasConfirm = state?.mode === "confirm";
+        // 仅对话模式下才有「回退后立即重发」。
+        let resend = wasConfirm && state?.resend === true && mode !== "both";
         /** @type {any} */
         let busyState = {
           origin: origin,
@@ -3550,7 +3641,7 @@ window.__ModuleLoader__.load({
           mode: mode === "both" ? "both" : "chat",
         })
           .then((/** @type {any} */ value) => {
-            handleRewindSuccess(sessionId, target, value);
+            handleRewindSuccess(sessionId, target, value, resend);
           })
           .catch((/** @type {any} */ error) => {
             handleRewindFailure(sessionId, target, origin, wasConfirm, error);
@@ -3562,6 +3653,7 @@ window.__ModuleLoader__.load({
         /** @type {any} */ sessionId,
         /** @type {any} */ target,
         /** @type {any} */ value,
+        /** @type {boolean} */ resend,
       ) {
         let summary = rewindSummaryOf(value);
         cutStore.add(sessionId, {
@@ -3583,6 +3675,12 @@ window.__ModuleLoader__.load({
             text += t("toast.rewoundFailed", { n: summary.files.failed.length });
           }
         }
+        if (summary.cancelledTurn) text += t("toast.stoppedTurn");
+        let resent = false;
+        if (resend === true && outcome === "ok") {
+          resent = submitComposer(sessionId);
+          if (resent) text += t("toast.resent");
+        }
         if (outcome === "draft") text += t("toast.draftKept");
         else if (outcome === "none") text += t("toast.noComposerSuffix");
         patch({
@@ -3593,6 +3691,7 @@ window.__ModuleLoader__.load({
           previewLoading: false,
           previewErrorKey: null,
           previewErrorParams: null,
+          resend: false,
           busy: false,
           executing: false,
           loading: false,
@@ -3655,8 +3754,8 @@ window.__ModuleLoader__.load({
       function doRewind() {
         let state = store.getSnapshot();
         if (state?.mode !== "confirm" || !state.target) return;
-        if (state.executing === true || state.busy === true || state.previewLoading === true)
-          return;
+        // 运行中的回合不再由客户端拒绝：宿主会先取消并等到 idle 再回溯（v2.1）。
+        if (state.executing === true || state.previewLoading === true) return;
         executeRewind(state.sessionId, state.target, state.rewindMode, state.origin || "row");
       }
 
@@ -4069,6 +4168,7 @@ window.__ModuleLoader__.load({
         pick: pick,
         doRewind: doRewind,
         setRewindMode: setRewindMode,
+        setResend: setResend,
         togglePathList: togglePathList,
         setListSearch: setListSearch,
         loadOlderCandidates: loadOlderCandidates,

package/lib/operations.js

@@ -124,12 +124,16 @@ function surfaceNodesOf(session) {
  *
  * - not-found：没有 live session（agent 也没有）；
  * - inert：子代理会话（`header.origin === "subagent"` 或 `delegationDepth > 0`）；
- * - busy：agent 存在且 `status !== "idle"`（v1 不主动打断运行中的回合）。
+ * - busy：agent 存在且 `status !== "idle"`，且调用方不允许运行中的会话。
+ *
+ * 只读操作（候选列表、预览、幽灵历史）传 `allowRunning: true`：它们不改日志，
+ * 运行中也能安全求值；真正写日志的 rewind 会先停下回合再重新求值。
  * @param {ServiceDeps} deps
  * @param {any} sessionId
+ * @param {{allowRunning?: boolean}} [options]
  * @returns {ResolvedSession}
  */
-export function resolveSession(deps, sessionId) {
+export function resolveSession(deps, sessionId, options = {}) {
   if (deps.available !== true) {
     throw new RewindRequestError(
       ERROR_CODES.failed,
@@ -158,7 +162,12 @@ export function resolveSession(deps, sessionId) {
       `session "${sessionId}" is a subagent session and cannot be rewound`,
     );
   }
-  if (agent !== undefined && agent !== null && agent.status !== "idle") {
+  if (
+    options.allowRunning !== true &&
+    agent !== undefined &&
+    agent !== null &&
+    agent.status !== "idle"
+  ) {
     throw new RewindRequestError(
       ERROR_CODES.busy,
       `session "${sessionId}" is not idle; stop the running turn before rewinding`,
@@ -218,7 +227,8 @@ function throwPlanError(planError) {
  * @returns {{sessionId: string, candidates: any[], nextCursor: number | null}}
  */
 export function candidatesResponse(deps, request) {
-  const { session, sessionId } = resolveSession(deps, request?.sessionId);
+  // 只读：运行中的会话也能列候选（客户端据此让用户选择「停止并回退」）。
+  const { session, sessionId } = resolveSession(deps, request?.sessionId, { allowRunning: true });
   const page = listCandidatesPage(snapshotEventsOf(session), surfaceNodesOf(session), {
     limit: request?.limit,
     cursor: request?.cursor,
@@ -250,6 +260,8 @@ export function candidatesResponse(deps, request) {
  * @returns {{targetSeq: number, markerSeq: number, removedCount: number, text: string, target: {text: string, images: any[]}}}
  */
 export function rewindResponse(deps, request) {
+  // 严格模式：这个 helper 代表「append 时会话必须已 idle」。生产路径
+  // （SessionRewindService#executeRewind）会先停下运行中的回合再走到这里。
   const { session, sessionId } = resolveSession(deps, request?.sessionId);
   const targetSeq = request?.targetSeq;
   if (!isEventSeq(targetSeq)) {
@@ -336,8 +348,8 @@ export function appendRewindMarker(session, plan, deps, extra = {}) {
  * @param {any} request `{ sessionId, targetSeq }`
  * @returns {{session: any, sessionId: string, plan: import("./plan.js").RewindPlan, targetEvent: any}}
  */
-export function resolveRewindTarget(deps, request) {
-  const { session, sessionId } = resolveSession(deps, request?.sessionId);
+export function resolveRewindTarget(deps, request, options = {}) {
+  const { session, sessionId } = resolveSession(deps, request?.sessionId, options);
   const targetSeq = request?.targetSeq;
   if (!isEventSeq(targetSeq)) {
     throw new RewindRequestError(
@@ -358,6 +370,6 @@ export function resolveRewindTarget(deps, request) {
  * @returns {{session: any, events: any[]}}
  */
 export function sessionEvents(deps, sessionId) {
-  const { session } = resolveSession(deps, sessionId);
+  const { session } = resolveSession(deps, sessionId, { allowRunning: true });
   return { session, events: snapshotEventsOf(session) };
 }

package/lib/service.js

@@ -14,6 +14,7 @@ import { createUserMessage } from "@deepseek-ai/dsh-llm";
 import { deriveEventMessage, isAppendSurfaceEvent } from "@deepseek-ai/dsh-session/surface";
 import { estimateMessage } from "@deepseek-ai/dsh-token-meter/estimate";
 import { Remote, RemoteError, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+import { settleAgent } from "./agent-settle.js";
 import { installFileTracking } from "./file-tracking.js";
 import { createFileStore } from "./files.js";
 import { collectGhost } from "./ghost.js";
@@ -23,10 +24,12 @@ import {
   ERROR_CODES,
   RewindRequestError,
   resolveRewindTarget,
+  resolveSession,
   sessionEvents,
 } from "./operations.js";
 import { findOrphans, pruneOrphans } from "./orphans.js";
 import { cutsOf, hasOpenToolCalls, listCandidatesPage, targetContent } from "./plan.js";
+import { describeToolImpact, installRewindTool, listToolCandidates } from "./tool.js";
 
 /**
  * 在 decorator 语法不可用（V8 装饰器关闭）的运行时里登记一个 Remote 方法。
@@ -160,6 +163,18 @@ export class SessionRewindService extends TypertRemoteService {
     this._store = null;
     this.installFileTracking();
     this.installCommand();
+    // 只读 agent 工具：让模型自己看清候选与影响面（绝不执行回溯）。
+    this.readOnlyToolInstalled = false;
+    if (this.config.readOnlyTool !== false) {
+      installRewindTool({
+        ctx: this.ctx,
+        logger: this.ctx?.logger ?? console,
+        host: { call: (sessionId, request) => this.toolPayload(sessionId, request) },
+        onInstalled: () => {
+          this.readOnlyToolInstalled = true;
+        },
+      });
+    }
     // 启动时清一次已删除会话的残留数据（失败只告警，不阻塞插件）。
     if (this.config.cleanupOrphans !== false) void this.cleanupOrphans();
   }
@@ -396,6 +411,58 @@ export class SessionRewindService extends TypertRemoteService {
     }
   }
 
+  /**
+   * 只读工具的数据面：候选列表 / 单条影响面。绝不写日志。
+   * @param {string} sessionId
+   * @param {{query?: string, limit?: number, targetSeq?: number}} [request]
+   * @returns {Promise<any>}
+   */
+  async toolPayload(sessionId, request) {
+    try {
+      const deps = this.deps();
+      const { session } = sessionEvents(deps, sessionId);
+      const events = session.snapshotEvents();
+      const nodes = Array.isArray(session.surface?.nodes) ? session.surface.nodes : [];
+      if (typeof request?.targetSeq === "number") {
+        const impact = describeToolImpact(events, nodes, request.targetSeq);
+        if (impact.ok !== true)
+          return { ok: true, value: { kind: "error", session_id: sessionId, error: impact.error } };
+        return {
+          ok: true,
+          value: {
+            kind: "impact",
+            session_id: sessionId,
+            impact: {
+              target_seq: impact.targetSeq,
+              removed_messages: impact.removedCount,
+              crosses_open_tool_call: impact.crossesOpenToolCall,
+              text: impact.text,
+            },
+          },
+        };
+      }
+      const listed = listToolCandidates(events, nodes, {
+        ...(typeof request?.query === "string" ? { query: request.query } : {}),
+        ...(typeof request?.limit === "number" ? { limit: request.limit } : {}),
+      });
+      return {
+        ok: true,
+        value: {
+          kind: "list",
+          session_id: sessionId,
+          total: listed.total,
+          candidates: listed.items.map((item) => ({
+            seq: item.seq,
+            ...(typeof item.time === "number" ? { time: item.time } : {}),
+            preview: item.preview,
+          })),
+        },
+      };
+    } catch (error) {
+      return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+  }
+
   /**
    * 回溯预览（dry-run）：不写任何东西。
    * @param {{sessionId?: string, targetSeq?: number}} [request]
@@ -403,7 +470,9 @@ export class SessionRewindService extends TypertRemoteService {
   async preview(request) {
     try {
       const deps = this.deps();
-      const { session, sessionId, plan, targetEvent } = resolveRewindTarget(deps, request);
+      const { session, sessionId, plan, targetEvent } = resolveRewindTarget(deps, request, {
+        allowRunning: true,
+      });
       const events = session.snapshotEvents();
       const tokens = this.estimateTokens(events, plan.shadowedSeqs);
       const target = targetContent(targetEvent);
@@ -504,15 +573,36 @@ export class SessionRewindService extends TypertRemoteService {
    */
   async executeRewind(input) {
     const deps = this.deps();
-    const resolved = resolveRewindTarget(deps, input);
-    const { session, sessionId, plan, targetEvent } = resolved;
-    const agent = deps.getAgent(sessionId);
+    // 先按「允许运行中」解析，拿到 agent；运行中的回合必须先停下，否则 surface 会在
+    // 我们求值与 append 之间继续增长，marker 的 replace 范围就失效了。
+    const pre = resolveSession(deps, input.sessionId, { allowRunning: true });
+    const agent = pre.agent;
+    /** @type {{cancelledTurn: boolean, droppedSteering: number}} */
+    const settle = { cancelledTurn: false, droppedSteering: 0 };
     if (agent !== undefined && agent !== null && agent.status !== "idle") {
-      throw new RewindRequestError(
-        ERROR_CODES.busy,
-        `session "${sessionId}" is not idle; stop the running turn before rewinding`,
-      );
+      if (this.config.cancelRunning === false) {
+        throw new RewindRequestError(
+          ERROR_CODES.busy,
+          `session "${input.sessionId}" is not idle; stop the running turn before rewinding`,
+        );
+      }
+      const outcome = await settleAgent(agent, {
+        ...(typeof this.config.cancelTimeoutMs === "number"
+          ? { timeoutMs: this.config.cancelTimeoutMs }
+          : {}),
+      });
+      settle.cancelledTurn = outcome.cancelled;
+      settle.droppedSteering = outcome.droppedSteering.length;
+      if (!outcome.idle) {
+        throw new RewindRequestError(
+          ERROR_CODES.busy,
+          `session "${input.sessionId}" did not become idle after cancelling the running turn`,
+        );
+      }
     }
+    // 停稳之后重新求值：取消前的快照可能已经被这一轮追加的事件改变。
+    const resolved = resolveRewindTarget(deps, input);
+    const { session, sessionId, plan, targetEvent } = resolved;
     if (this.inflight.has(sessionId)) {
       throw new RewindRequestError(
         ERROR_CODES.failed,
@@ -618,6 +708,9 @@ export class SessionRewindService extends TypertRemoteService {
         auditId,
         target: targetContent(targetEvent),
         files,
+        // v2.1：执行时是否为了回溯而停下了运行中的回合。
+        cancelledTurn: settle.cancelledTurn,
+        droppedSteering: settle.droppedSteering,
       };
       try {
         await this.store.appendAudit({
@@ -631,6 +724,8 @@ export class SessionRewindService extends TypertRemoteService {
           tokens,
           files,
           requestedBy: input.requestedBy,
+          cancelledTurn: settle.cancelledTurn,
+          droppedSteering: settle.droppedSteering,
         });
       } catch (error) {
         this.ctx?.logger?.warn?.(
@@ -807,6 +902,15 @@ export class SessionRewindService extends TypertRemoteService {
     } catch (error) {
       push("审计日志", false, error instanceof Error ? error.message : String(error));
     }
+    push(
+      "只读工具",
+      this.config.readOnlyTool === false ? true : this.readOnlyToolInstalled === true,
+      this.config.readOnlyTool === false
+        ? "disabled by config"
+        : this.readOnlyToolInstalled === true
+          ? "enabled"
+          : "not registered",
+    );
     try {
       const orphans = await findOrphans({ dataRoot: this.dataRoot });
       const count = orphans.sessionIds.length + orphans.trashIds.length + orphans.rescueIds.length;

package/lib/tool.js

@@ -0,0 +1,254 @@
+// @ts-check
+// 只读 agent 工具 `session_rewind_candidates`：让模型自己看清「能退回到哪几步、退回去会丢什么」。
+//
+// 设计约束：
+//   - 只读：绝不写日志、绝不执行回溯。真正的回退仍由用户点确认框触发（ADR 0006）。
+//   - 不 import 宿主包（defineTool 在 @deepseek-ai/dsh-tools 里，插件不能依赖）；这里直接
+//     构造 registry 需要的普通对象，`parameters` 与 `output.schema` 都是标准 JSON Schema。
+//   - 形状不符就静默跳过：老版本没有 `tools` 服务时，插件其余功能照常工作。
+import { hasOpenToolCalls, listCandidatesPage, planRewind } from "./plan.js";
+
+/** 工具名（小写下划线，符合宿主 run_code 之外的自定义工具习惯）。 */
+export const TOOL_NAME = "session_rewind_candidates";
+
+/** 一次最多列多少条候选。 */
+export const TOOL_MAX_LIMIT = 50;
+/** 默认条数。 */
+export const TOOL_DEFAULT_LIMIT = 10;
+
+/**
+ * 把面向模型的省略描述压成一行。
+ * @param {string} text
+ * @param {number} max
+ * @returns {string}
+ */
+function oneLine(text, max) {
+  const flat = String(text ?? "")
+    .replace(/\s+/gu, " ")
+    .trim();
+  return flat.length <= max ? flat : `${flat.slice(0, Math.max(max - 1, 1))}…`;
+}
+
+/**
+ * 列出可回退的候选消息。
+ * @param {any[]} events
+ * @param {number[]} surfaceNodes
+ * @param {{query?: string, limit?: number}} [options]
+ * @returns {{sessionId?: string, total: number, items: Array<{seq: number, time: number, preview: string, text: string}>}}
+ */
+export function listToolCandidates(events, surfaceNodes, options = {}) {
+  const limit =
+    Number.isSafeInteger(options.limit) && Number(options.limit) > 0
+      ? Math.min(Number(options.limit), TOOL_MAX_LIMIT)
+      : TOOL_DEFAULT_LIMIT;
+  const page = listCandidatesPage(events, surfaceNodes, {
+    limit,
+    q: typeof options.query === "string" ? options.query : "",
+  });
+  return {
+    total: page.candidates.length,
+    items: page.candidates.map((candidate) => ({
+      seq: candidate.seq,
+      time: candidate.time,
+      preview: oneLine(candidate.preview ?? candidate.text ?? "", 160),
+      text: String(candidate.text ?? ""),
+    })),
+  };
+}
+
+/**
+ * 评估「退回到这条消息」的影响面：撤回多少条消息、有没有未完成的工具调用。
+ * @param {any[]} events
+ * @param {number[]} surfaceNodes
+ * @param {number} targetSeq
+ * @returns {{ok: true, targetSeq: number, removedCount: number, crossesOpenToolCall: boolean, text: string} | {ok: false, error: string}}
+ */
+export function describeToolImpact(events, surfaceNodes, targetSeq) {
+  const plan = planRewind(events, surfaceNodes, targetSeq);
+  if ("error" in plan) return { ok: false, error: String(plan.error?.code ?? plan.error) };
+  return {
+    ok: true,
+    targetSeq,
+    removedCount: plan.shadowedSeqs.length,
+    crossesOpenToolCall: hasOpenToolCalls(events, targetSeq),
+    // planRewind 已经把目标消息的文本拼好（`user/message` 的 data 本身就是 message）。
+    text: typeof plan.text === "string" ? plan.text : "",
+  };
+}
+
+/**
+ * 构造工具定义（不依赖宿主 defineTool）。
+ * @param {{call: (sessionId: string, request: any) => Promise<any>}} host
+ * @returns {any}
+ */
+export function createRewindToolDefinition(host) {
+  return {
+    name: TOOL_NAME,
+    description:
+      "List the user messages this conversation can be rewound to, or preview the impact of rewinding to one of them. Read-only: it never rewinds, never edits files and never appends to the session log. The user performs the actual rewind from the UI.",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        query: {
+          type: "string",
+          description: "Optional case-insensitive substring filter over message text.",
+        },
+        limit: {
+          type: "integer",
+          description: `How many candidates to return (default ${TOOL_DEFAULT_LIMIT}, max ${TOOL_MAX_LIMIT}; clamped).`,
+        },
+        target_seq: {
+          type: "integer",
+          description:
+            "Preview the impact of rewinding to this message sequence instead of listing candidates.",
+        },
+      },
+    },
+    output: {
+      // 标准 JSON Schema（宿主的受支持子集）：`required` 必须是字符串数组，
+      // 不接受 defineTool 那种 `required: true` 的属性级写法。
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        required: ["kind"],
+        properties: {
+          kind: { type: "string", enum: ["list", "impact", "error"] },
+          session_id: { type: "string" },
+          total: { type: "integer" },
+          candidates: {
+            type: "array",
+            items: {
+              type: "object",
+              additionalProperties: false,
+              required: ["seq"],
+              properties: {
+                seq: { type: "integer" },
+                time: { type: "integer" },
+                preview: { type: "string" },
+              },
+            },
+          },
+          impact: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              target_seq: { type: "integer" },
+              removed_messages: { type: "integer" },
+              crosses_open_tool_call: { type: "boolean" },
+              text: { type: "string" },
+            },
+          },
+          error: { type: "string" },
+        },
+      },
+      /**
+       * @param {any} _args
+       * @param {any} value
+       * @returns {any[]}
+       */
+      render: (_args, value) => {
+        const lines = [];
+        if (value?.error) {
+          lines.push(`Rewind preview failed: ${value.error}`);
+        } else if (value?.kind === "impact" && value.impact) {
+          lines.push(
+            `Rewinding to message #${value.impact.target_seq} would withdraw ${value.impact.removed_messages} message(s) from the model context.`,
+          );
+          if (value.impact.crosses_open_tool_call) {
+            lines.push(
+              "Warning: an unfinished tool call follows this message; rewinding truncates it.",
+            );
+          }
+          if (value.impact.text) lines.push(`Target message: ${oneLine(value.impact.text, 400)}`);
+          lines.push("The user must confirm the rewind in the UI; this tool does not perform it.");
+        } else {
+          const candidates = Array.isArray(value?.candidates) ? value.candidates : [];
+          if (candidates.length === 0) {
+            lines.push("No messages can be rewound to in this conversation.");
+          } else {
+            lines.push(
+              `Messages this conversation can be rewound to (${candidates.length} shown):`,
+            );
+            for (const item of candidates) {
+              lines.push(`- #${item.seq}: ${oneLine(item.preview, 160)}`);
+            }
+            lines.push(
+              "Call again with target_seq to preview the impact of one message. Rewinding itself is a user action in the UI.",
+            );
+          }
+        }
+        return [{ type: "text", text: lines.join("\n") }];
+      },
+    },
+    /**
+     * @param {any} args
+     * @param {any} exec
+     * @returns {Promise<any>}
+     */
+    async execute(args, exec) {
+      const sessionId = exec?.agent?.session?.id;
+      if (typeof sessionId !== "string" || sessionId === "") {
+        return { kind: "error", error: "no active session" };
+      }
+      try {
+        const payload = await host.call(sessionId, {
+          query: typeof args?.query === "string" ? args.query : undefined,
+          limit: typeof args?.limit === "number" ? args.limit : undefined,
+          targetSeq: typeof args?.target_seq === "number" ? args.target_seq : undefined,
+        });
+        if (payload?.ok !== true) {
+          return { kind: "error", error: String(payload?.error ?? "unavailable") };
+        }
+        return payload.value;
+      } catch (error) {
+        return {
+          kind: "error",
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    },
+  };
+}
+
+/**
+ * 注册只读工具。`tools` 服务缺失或注册失败时静默跳过。
+ * @param {{ctx: any, host: {call: (sessionId: string, request: any) => Promise<any>}, logger?: any, onInstalled?: () => void}} input
+ * @returns {boolean} 是否注册成功（`tools` 服务就绪时会返回 true）
+ */
+export function installRewindTool(input) {
+  const { ctx, host, logger, onInstalled } = input;
+  const install = (/** @type {any} */ scope) => {
+    try {
+      const tools = scope?.tools ?? scope?.get?.("tools");
+      if (!tools || typeof tools.register !== "function") return;
+      const definition = createRewindToolDefinition(host);
+      const disposer = tools.register(definition);
+      scope?.effect?.(() => disposer, "session-rewind: read-only tool");
+      if (typeof onInstalled === "function") onInstalled();
+      return true;
+    } catch (error) {
+      logger?.warn?.(
+        `session-rewind: failed to register ${TOOL_NAME}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return false;
+    }
+  };
+  try {
+    if (typeof ctx.inject === "function") {
+      ctx.inject(["tools"], install);
+      return true;
+    }
+    const tools = ctx.get?.("tools");
+    if (tools && typeof tools.register === "function") {
+      install({ tools, effect: ctx.effect?.bind(ctx) });
+      return true;
+    }
+    return false;
+  } catch (error) {
+    logger?.warn?.(
+      `session-rewind: cannot install ${TOOL_NAME}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    return false;
+  }
+}

package/locale/en.json

@@ -28,7 +28,7 @@
     "confirm.pathsLess": "Hide paths",
     "confirm.skipped": "{n} file(s) skipped",
     "confirm.conflictsTitle": "Conflicting files (first 5)",
-    "confirm.busy": "The turn is still running; stop it before rewinding.",
+    "confirm.busy": "The turn is still running: rewinding stops it first and drops any queued steering messages.",
     "confirm.openToolCall": "An unfinished tool call follows the target; rewinding truncates it.",
     "toast.done": "Rewound. The original message is back in the composer.",
     "toast.draft": "Rewound. The composer already had content, so it was kept.",
@@ -116,6 +116,12 @@
     "relative.justNow": "just now",
     "relative.minutes": "{n} min ago",
     "relative.hours": "{n} h ago",
-    "relative.days": "{n} d ago"
+    "relative.days": "{n} d ago",
+    "dialog.settling": "Stopping the running turn, then rewinding…",
+    "confirm.settling": "Stopping the running turn…",
+    "toast.stoppedTurn": ", and the running turn was stopped",
+    "confirm.resend": "Send this message again right after rewinding",
+    "confirm.resendHint": "Use this to retry a turn; to change the text, edit it in the composer instead.",
+    "toast.resent": ", and the message was sent again"
   }
 }

package/locale/zh.json

@@ -28,7 +28,7 @@
     "confirm.pathsLess": "收起路径",
     "confirm.skipped": "{n} 个文件被跳过",
     "confirm.conflictsTitle": "冲突文件（前 5 个）",
-    "confirm.busy": "当前回合仍在运行，请先停止后再回退",
+    "confirm.busy": "当前回合仍在运行：回退时会先停止它，队列中未投递的插话会被丢弃",
     "confirm.openToolCall": "目标之后有未完成的工具调用，回溯会截断它",
     "toast.done": "已回退到此处，原消息已放回输入框",
     "toast.draft": "已回退；输入框已有内容，未覆盖",
@@ -116,6 +116,12 @@
     "relative.justNow": "刚刚",
     "relative.minutes": "{n} 分钟前",
     "relative.hours": "{n} 小时前",
-    "relative.days": "{n} 天前"
+    "relative.days": "{n} 天前",
+    "dialog.settling": "正在停止当前回合并回退…",
+    "confirm.settling": "正在停止当前回合…",
+    "toast.stoppedTurn": "，已停止运行中的回合",
+    "confirm.resend": "回退后立即重发这条消息",
+    "confirm.resendHint": "适合「重试这一轮」：回退后自动把原文发出去，想改内容就在输入框里编辑后再发。",
+    "toast.resent": "，已重发这条消息"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kangyishuai/dsh-session-rewind",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "In-place conversation rewind for DSH: withdraw a user message and everything after it, then refill the composer",
   "keywords": [
     "dsh",