@kangyishuai/dsh-session-rewind 0.2.0 → 0.4.0

package/README.md

@@ -16,11 +16,23 @@ Long conversations drift. A few turns later you wish you had answered a prompt d
 
 - **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.
+- **State-change warnings.** If the withdrawn range changed session state that lives outside the transcript — plan mode, goal, todo list, model selection, permission/sandbox presets, agent preset, scheduled tasks, working directory — the dialog lists it and says that rewinding does not roll that state back.
 - **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. 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).
+- **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** (a timeline of each rewind and each rescue-point file restore, newest first: 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
 

package/README.zh-CN.md

@@ -18,9 +18,21 @@
 - **每次回溯二选一**：确认框里提供「**仅回退对话**」（默认）与「**回退对话和文件**」，并先展示 dry-run 预览：将撤回多少条消息、约多少 token、哪些文件会还原/移入回收站、冲突与被跳过的文件。
 - **对话**：目标消息及其后的内容从模型上下文和渲染对话中撤回；会话 id、标题和目标之前的历史不变；日志只追加一条 marker，不删历史。
 - **文件（可选）**：被撤回轮次里由 `write` / `edit` / `apply_patch` 改过的文件还原到改动前内容；目标之后新建的文件移入插件回收站而不是删除。写入前先建救援点，失败从救援点回滚。
+- **状态变更提示**：如果要撤回的区间里改过会话状态（plan 模式、goal、待办、模型选择、权限/沙箱预设、智能体预设、定时任务、工作目录），确认框会列出来并明确说明——回溯只撤回对话，**不会**回滚这些状态。
 - **运行中也能回退**：确认回退时如果这一轮正在跑，会先取消它（保留队列）、等它空闲，再对新历史重新求值。
 - **输入框**：目标消息文本（以及图片）放回输入框，改完可直接重发；已有草稿绝不覆盖。勾选「回退后立即重发」可一键重试这一轮（仅对话模式）。
-- **回溯面板**：会话头部新增一个入口，四个页签：**已撤回**（每次回溯撤回的全部消息，可搜索、复制、放回输入框）、**回溯记录**（审计：范围、条数、token、文件结果）、**救援点**（手动恢复文件）、**设置**（默认范围、每页数量、列表确认、诊断）。
+- **回溯面板**：会话头部新增一个入口，四个页签：**已撤回**（每次回溯撤回的全部消息，可搜索、复制、放回输入框）、**回溯记录**（时间线：每次回溯与每次救援点恢复，新在上；范围、条数、token、文件结果）、**救援点**（手动恢复文件）、**设置**（默认范围、每页数量、列表确认、诊断）。
+
+## 只读 agent 工具
+
+插件还会注册一个**只读**工具 `session_rewind_candidates`，让模型能自己判断「能退回到哪、退回去会丢什么」，但**不执行**回溯：
+
+| 调用                                       | 结果                                                                 |
+| ------------------------------------------ | -------------------------------------------------------------------- |
+| `session_rewind_candidates {}`             | 按新→旧列出可回退的消息（`query` 过滤，`limit` 上限 50）。           |
+| `session_rewind_candidates { target_seq }` | 单条消息的影响面：会撤回多少条、是否截断未完成的工具调用、目标文本。 |
+
+这个工具不回溯、不碰文件、不写会话日志——真正的回退始终由用户在界面确认（这是 ADR 0006 的设计前提）。设 `readOnlyTool: false` 可关闭；**设置 → 诊断**里能看到它是否注册成功。
 
 ## 安装
 

package/lib/client.js

@@ -72,6 +72,20 @@ window.__ModuleLoader__.load({
       "confirm.resendHint":
         "适合「重试这一轮」：回退后自动把原文发出去，想改内容就在输入框里编辑后再发。",
       "confirm.openToolCall": "目标之后有未完成的工具调用，回溯会截断它",
+      "confirm.stateChanges": "这段区间里改过会话状态：{list}；回溯只撤回对话，不会回滚这些状态",
+      "confirm.stateHint": "如需一并回退 plan/goal/待办等状态，请手动调整。",
+      "state.planMode": "计划模式",
+      "state.goal": "目标（goal）",
+      "state.todo": "待办清单",
+      "state.model": "模型选择",
+      "state.permission": "权限预设",
+      "state.sandbox": "沙箱模式",
+      "state.agentPreset": "智能体预设",
+      "state.schedule": "定时任务",
+      "state.workingDirectory": "工作目录",
+      "state.separator": "、",
+      "timeline.kindRescue": "文件恢复",
+      "timeline.rescueMeta": "从救援点恢复 {restored} 个文件 · {id}",
       "toast.done": "已回退到此处，原消息已放回输入框",
       "toast.draft": "已回退；输入框已有内容，未覆盖",
       "toast.noComposer": "已回退，但未找到输入框",
@@ -202,6 +216,21 @@ window.__ModuleLoader__.load({
       "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.",
+      "confirm.stateChanges":
+        "Session state changed inside this range: {list}. Rewinding only withdraws messages; these stay as they are.",
+      "confirm.stateHint": "Adjust plan/goal/todo state by hand if you need it rolled back too.",
+      "state.planMode": "plan mode",
+      "state.goal": "goal",
+      "state.todo": "todo list",
+      "state.model": "model selection",
+      "state.permission": "permission preset",
+      "state.sandbox": "sandbox mode",
+      "state.agentPreset": "agent preset",
+      "state.schedule": "scheduled task",
+      "state.workingDirectory": "working directory",
+      "state.separator": ", ",
+      "timeline.kindRescue": "File restore",
+      "timeline.rescueMeta": "Restored {restored} file(s) from rescue {id}",
       "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.",
@@ -691,7 +720,25 @@ window.__ModuleLoader__.load({
      * @param {any} value
      * @returns {any}
      */
-    function normalizePreview(value) {
+    /** 会话状态变更提示（plan/goal/todo/模型…）。 @param {any} value */
+    function normalizeStateChanges(value) {
+      /** @type {any[]} */
+      let out = [];
+      let source = Array.isArray(value) ? value : [];
+      for (let i = 0; i < source.length; i += 1) {
+        let item = source[i];
+        if (!item || typeof item !== "object") continue;
+        if (typeof item.labelKey !== "string") continue;
+        out.push({
+          type: typeof item.type === "string" ? item.type : "",
+          labelKey: item.labelKey,
+          count: typeof item.count === "number" && item.count > 0 ? item.count : 1,
+        });
+      }
+      return out;
+    }
+
+    function normalizePreview(/** @type {any} */ value) {
       let source = value && typeof value === "object" ? value : {};
       let target = source.target && typeof source.target === "object" ? source.target : {};
       let chat = source.chat && typeof source.chat === "object" ? source.chat : {};
@@ -731,6 +778,7 @@ window.__ModuleLoader__.load({
           crossesOpenToolCall: chat.crossesOpenToolCall === true,
           reachable: chat.reachable !== false,
         },
+        stateChanges: normalizeStateChanges(source.stateChanges ?? chat.stateChanges),
         files: normalizeFiles(source.files),
         warnings: warnings,
       };
@@ -965,8 +1013,13 @@ window.__ModuleLoader__.load({
           : typeof entry.id === "number"
             ? String(entry.id)
             : "";
+      let action = typeof entry.action === "string" ? entry.action : "";
+      let kind =
+        action === "rescue-restore" ? "rescue-restore" : entry.mode === "both" ? "both" : "chat";
       return {
         id: id,
+        action: action,
+        kind: kind,
         time: typeof entry.time === "number" ? entry.time : null,
         targetSeq: typeof entry.targetSeq === "number" ? entry.targetSeq : null,
         markerSeq: typeof entry.markerSeq === "number" ? entry.markerSeq : null,
@@ -989,6 +1042,12 @@ window.__ModuleLoader__.load({
         if (entry.id === "") continue;
         out.push(entry);
       }
+      // 时间线按时间倒序（新在上）；缺时间戳的排最后。
+      out.sort((/** @type {any} */ left, /** @type {any} */ right) => {
+        let l = typeof left.time === "number" ? left.time : -1;
+        let r = typeof right.time === "number" ? right.time : -1;
+        return r - l;
+      });
       return out;
     }
 
@@ -1928,6 +1987,27 @@ window.__ModuleLoader__.load({
             h("div", { key: "tool", className: "dsh-srw-warn" }, t("confirm.openToolCall")),
           );
         }
+        // 区间里改过的会话状态：回溯只切模型上下文，不会回滚这些设置。
+        let stateChanges = Array.isArray(preview.stateChanges) ? preview.stateChanges : [];
+        if (stateChanges.length > 0) {
+          let labels = stateChanges
+            .map((/** @type {any} */ item) =>
+              item.count > 1 ? `${t(item.labelKey)} ×${item.count}` : t(item.labelKey),
+            )
+            .join(t("state.separator"));
+          blocks.push(
+            h(
+              "div",
+              { key: "state", className: "dsh-srw-warn", "data-rewind-state": "true" },
+              t("confirm.stateChanges", { list: labels }),
+            ),
+            h(
+              "div",
+              { key: "state-hint", className: "dsh-srw-option-hint" },
+              t("confirm.stateHint"),
+            ),
+          );
+        }
         blocks.push(
           h(ModePicker, {
             key: "modes",
@@ -2307,12 +2387,14 @@ window.__ModuleLoader__.load({
       if (data.entries.length === 0) {
         return h("div", { className: "dsh-srw-dim" }, t("audit.empty"));
       }
+      // 时间线：竖线 + 节点。回溯事件与「从救援点恢复文件」放在同一条轴上，按时间倒序。
       return h(
         "div",
-        { className: "dsh-srw-cuts" },
+        { className: "dsh-srw-timeline" },
         data.entries.map((/** @type {any} */ entry) => {
           let expanded = data.expanded && data.expanded[entry.id] === true;
           let files = entry.files;
+          let isRescueRestore = entry.kind === "rescue-restore";
           /** @type {any[]} */
           let pathGroups = [];
           if (files) {
@@ -2334,70 +2416,86 @@ window.__ModuleLoader__.load({
             (/** @type {any} */ sum, /** @type {any} */ group) => sum + group.paths.length,
             0,
           );
+          let badge = isRescueRestore ? t("timeline.kindRescue") : t(modeLabelKey(entry.mode));
+          let meta = isRescueRestore
+            ? t("timeline.rescueMeta", {
+                restored: files ? files.restored.length : 0,
+                id: entry.rescueId || "",
+              })
+            : t("audit.meta", {
+                mode: t(modeLabelKey(entry.mode)),
+                n: entry.removedCount,
+                tokens: formatCount(entry.tokens),
+              });
           return h(
             "div",
-            { key: entry.id, className: "dsh-srw-cut" },
+            {
+              key: entry.id,
+              className: "dsh-srw-tl-node",
+              "data-kind": isRescueRestore ? "rescue-restore" : entry.mode,
+            },
+            h("span", { className: "dsh-srw-tl-dot", "aria-hidden": "true" }),
             h(
               "div",
-              { className: "dsh-srw-cut-head" },
-              h("span", { className: "dsh-srw-strong" }, formatDateTime(entry.time) || entry.id),
-              h("span", { className: "dsh-srw-badge" }, t(modeLabelKey(entry.mode))),
+              { className: "dsh-srw-tl-card" },
               h(
-                "span",
-                { className: "dsh-srw-time" },
-                t("audit.meta", {
-                  mode: t(modeLabelKey(entry.mode)),
-                  n: entry.removedCount,
-                  tokens: formatCount(entry.tokens),
-                }),
+                "div",
+                { className: "dsh-srw-tl-head" },
+                h("span", { className: "dsh-srw-strong" }, formatDateTime(entry.time) || entry.id),
+                h("span", { className: "dsh-srw-badge" }, badge),
               ),
-            ),
-            files
-              ? h(
-                  "div",
-                  { className: "dsh-srw-audit-files" },
-                  t("audit.files", {
-                    restored: files.restored.length,
-                    trashed: files.trashed.length,
-                    skipped: files.skipped.length,
-                    failed: files.failed.length,
-                  }),
-                )
-              : null,
-            files?.rescueId
-              ? h("div", { className: "dsh-srw-dim" }, t("audit.rescueId", { id: files.rescueId }))
-              : null,
-            h(
-              "div",
-              { className: "dsh-srw-item-actions dsh-srw-audit-actions" },
-              pathCount > 0
+              h("div", { className: "dsh-srw-time" }, meta),
+              files
                 ? h(
-                    LinkBtn,
-                    { onClick: () => api.toggleAuditPaths(entry.id) },
-                    expanded ? t("audit.pathsLess") : t("audit.paths", { n: pathCount }),
+                    "div",
+                    { className: "dsh-srw-audit-files" },
+                    t("audit.files", {
+                      restored: files.restored.length,
+                      trashed: files.trashed.length,
+                      skipped: files.skipped.length,
+                      failed: files.failed.length,
+                    }),
                   )
                 : null,
-              h(LinkBtn, { onClick: () => api.copyJson(entry) }, t("audit.copyJson")),
-            ),
-            expanded
-              ? h(
-                  "div",
-                  { className: "dsh-srw-paths" },
-                  pathGroups.map((/** @type {any} */ group) =>
-                    group.paths.map((/** @type {any} */ path) =>
-                      h(
-                        "div",
-                        {
-                          key: `${group.kind}:${path}`,
-                          className: "dsh-srw-path",
-                          "data-kind": group.kind,
-                        },
-                        h("span", { className: "dsh-srw-path-name", title: path }, path),
+              files?.rescueId
+                ? h(
+                    "div",
+                    { className: "dsh-srw-dim" },
+                    t("audit.rescueId", { id: files.rescueId }),
+                  )
+                : null,
+              h(
+                "div",
+                { className: "dsh-srw-item-actions dsh-srw-audit-actions" },
+                pathCount > 0
+                  ? h(
+                      LinkBtn,
+                      { onClick: () => api.toggleAuditPaths(entry.id) },
+                      expanded ? t("audit.pathsLess") : t("audit.paths", { n: pathCount }),
+                    )
+                  : null,
+                h(LinkBtn, { onClick: () => api.copyJson(entry) }, t("audit.copyJson")),
+              ),
+              expanded
+                ? h(
+                    "div",
+                    { className: "dsh-srw-paths" },
+                    pathGroups.map((/** @type {any} */ group) =>
+                      group.paths.map((/** @type {any} */ path) =>
+                        h(
+                          "div",
+                          {
+                            key: `${group.kind}:${path}`,
+                            className: "dsh-srw-path",
+                            "data-kind": group.kind,
+                          },
+                          h("span", { className: "dsh-srw-path-name", title: path }, path),
+                        ),
                       ),
                     ),
-                  ),
-                )
-              : null,
+                  )
+                : null,
+            ),
           );
         }),
       );
@@ -3004,6 +3102,16 @@ window.__ModuleLoader__.load({
           ".dsh-srw-tab[data-active=true]{color:var(--dsw-alias-label-primary,inherit);border-bottom-color:var(--dsw-alias-brand-primary,#4f7cff);}",
           ".dsh-srw-tab-body{display:flex;flex-direction:column;gap:10px;}",
           ".dsh-srw-cuts{display:flex;flex-direction:column;gap:12px;}",
+          // 时间线：竖线 + 圆点 + 卡片
+          ".dsh-srw-timeline{display:flex;flex-direction:column;gap:0;position:relative;}",
+          ".dsh-srw-tl-node{position:relative;display:flex;gap:12px;padding:0 0 14px 0;}",
+          ".dsh-srw-tl-node::before{content:'';position:absolute;left:5px;top:14px;bottom:0;width:1px;background:var(--dsw-alias-border-secondary,rgba(128,128,128,.35));}",
+          ".dsh-srw-tl-node:last-child{padding-bottom:0;}",
+          ".dsh-srw-tl-node:last-child::before{display:none;}",
+          ".dsh-srw-tl-dot{flex:none;width:11px;height:11px;margin-top:4px;border-radius:50%;background:var(--dsw-alias-brand-primary,#4f7cff);box-shadow:0 0 0 2px var(--dsw-alias-bg-primary,transparent);}",
+          ".dsh-srw-tl-node[data-kind='rescue-restore'] .dsh-srw-tl-dot{background:var(--dsw-alias-label-secondary,GrayText);}",
+          ".dsh-srw-tl-card{display:flex;flex-direction:column;gap:4px;min-width:0;flex:1;}",
+          ".dsh-srw-tl-head{display:flex;gap:8px;align-items:baseline;flex-wrap:wrap;}",
           ".dsh-srw-cut{display:flex;flex-direction:column;gap:4px;}",
           ".dsh-srw-cut-head{display:flex;gap:8px;align-items:baseline;flex-wrap:wrap;}",
           ".dsh-srw-strong{font-weight:600;}",
@@ -4426,6 +4534,7 @@ window.__ModuleLoader__.load({
         normalizePathList: normalizePathList,
         normalizeFiles: normalizeFiles,
         normalizePreview: normalizePreview,
+        normalizeStateChanges: normalizeStateChanges,
         fileModeState: fileModeState,
         effectiveMode: effectiveMode,
         conflictPathsOf: conflictPathsOf,

package/lib/service.js

@@ -29,6 +29,8 @@ import {
 } from "./operations.js";
 import { findOrphans, pruneOrphans } from "./orphans.js";
 import { cutsOf, hasOpenToolCalls, listCandidatesPage, targetContent } from "./plan.js";
+import { stateChangeSummary } from "./state-changes.js";
+import { describeToolImpact, installRewindTool, listToolCandidates } from "./tool.js";
 
 /**
  * 在 decorator 语法不可用（V8 装饰器关闭）的运行时里登记一个 Remote 方法。
@@ -162,6 +164,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();
   }
@@ -398,6 +412,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]
@@ -412,6 +478,8 @@ export class SessionRewindService extends TypertRemoteService {
       const tokens = this.estimateTokens(events, plan.shadowedSeqs);
       const target = targetContent(targetEvent);
       const subtitle = target.text.replace(/\s+/gu, " ").trim();
+      // 被撤回区间里改过的会话状态（plan/goal/todo/模型…）：回溯不会回滚它们，只提示。
+      const stateChanges = stateChangeSummary(events, plan.surfaceStart, plan.surfaceEnd);
       /** @type {any} */
       let files = {
         available: false,
@@ -476,7 +544,9 @@ export class SessionRewindService extends TypertRemoteService {
           tokens,
           crossesOpenToolCall: hasOpenToolCalls(events, plan.targetSeq),
           reachable: true,
+          stateChanges,
         },
+        stateChanges,
         files,
         warnings,
       };
@@ -787,6 +857,37 @@ export class SessionRewindService extends TypertRemoteService {
         throw new RewindRequestError(ERROR_CODES.rescueNotFound, "a rescue id is required");
       }
       const result = await this.store.restoreRescue({ sessionId, cwd, rescueId });
+      // 审计：时间线里要把「从救援点恢复文件」和回溯事件放在同一条轴上。
+      try {
+        await this.store.appendAudit({
+          version: 1,
+          action: "rescue-restore",
+          id:
+            typeof this.store.newAuditId === "function"
+              ? this.store.newAuditId()
+              : `rr-${Date.now()}`,
+          time: Date.now(),
+          sessionId,
+          rescueId,
+          mode: "files",
+          targetSeq: null,
+          markerSeq: null,
+          removedCount: null,
+          tokens: null,
+          files: {
+            restored: result.restored ?? [],
+            trashed: [],
+            skipped: [],
+            failed: result.failed ?? [],
+            rescueId: result.safetyRescueId ?? null,
+          },
+          requestedBy: "ui",
+        });
+      } catch (error) {
+        this.ctx?.logger?.warn?.(
+          `session-rewind: rescue-restore audit failed: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
       if (Array.isArray(result.failed) && result.failed.length > 0) {
         const error = new RewindRequestError(
           ERROR_CODES.filesFailed,
@@ -837,6 +938,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/state-changes.js

@@ -0,0 +1,71 @@
+// @ts-check
+// 「被撤回区间里改过哪些会话状态」的提示。
+//
+// 为什么需要：回溯只替换**模型可见的 surface**，日志与会话状态投影不动。所以区间里的
+// `plan/mode`、`goal/change`、`todo/write` 这类状态事件在回溯后仍然生效——用户很容易误以为
+// 「退回去就等于那些设置也退回去了」。这里只做事实提示，不做任何回滚。
+//
+// 未知事件类型一律忽略（AGENTS.md 约定 1：不写死内部实现，遇到不认识的保留）。
+
+/** 已知的会话状态事件 → 文案键。 */
+export const STATE_EVENT_LABELS = Object.freeze({
+  "plan/mode": "state.planMode",
+  "goal/change": "state.goal",
+  "todo/write": "state.todo",
+  "model/selection": "state.model",
+  "permission/preset": "state.permission",
+  "sandbox/mode": "state.sandbox",
+  "agent-preset/selected": "state.agentPreset",
+  "schedule/change": "state.schedule",
+  "working-directory/change": "state.workingDirectory",
+});
+
+/**
+ * @typedef {object} StateChange
+ * @property {string} type 事件类型
+ * @property {string} labelKey 文案键（`state.*`）
+ * @property {number} count 次数
+ * @property {number} firstSeq 第一次出现的 seq
+ */
+
+/**
+ * 扫描 [fromSeq, toSeq] 区间里的会话状态事件，按出现顺序聚合。
+ * @param {any[]} events
+ * @param {number} fromSeq 含
+ * @param {number} toSeq 含；传 `Number.MAX_SAFE_INTEGER` 表示到日志末尾
+ * @returns {StateChange[]}
+ */
+export function collectStateChanges(events, fromSeq, toSeq) {
+  const source = Array.isArray(events) ? events : [];
+  const start = typeof fromSeq === "number" ? fromSeq : 0;
+  const end = typeof toSeq === "number" ? toSeq : Number.MAX_SAFE_INTEGER;
+  /** @type {Map<string, StateChange>} */
+  const groups = new Map();
+  for (const event of source) {
+    if (!event || typeof event.seq !== "number") continue;
+    if (event.seq < start || event.seq > end) continue;
+    const type = event.type;
+    if (typeof type !== "string") continue;
+    const labelKey = /** @type {Record<string, string>} */ (STATE_EVENT_LABELS)[type];
+    if (labelKey === undefined) continue;
+    const existing = groups.get(type);
+    if (existing) existing.count += 1;
+    else groups.set(type, { type, labelKey, count: 1, firstSeq: event.seq });
+  }
+  return [...groups.values()].sort((left, right) => left.firstSeq - right.firstSeq);
+}
+
+/**
+ * 给提示用的简短摘要（不含本地化文案，只出 key 与次数）。
+ * @param {any[]} events
+ * @param {number} fromSeq
+ * @param {number} toSeq
+ * @returns {Array<{type: string, labelKey: string, count: number}>}
+ */
+export function stateChangeSummary(events, fromSeq, toSeq) {
+  return collectStateChanges(events, fromSeq, toSeq).map((item) => ({
+    type: item.type,
+    labelKey: item.labelKey,
+    count: item.count,
+  }));
+}

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

@@ -122,6 +122,20 @@
     "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"
+    "toast.resent": ", and the message was sent again",
+    "confirm.stateChanges": "Session state changed inside this range: {list}. Rewinding only withdraws messages; these stay as they are.",
+    "confirm.stateHint": "Adjust plan/goal/todo state by hand if you need it rolled back too.",
+    "state.planMode": "plan mode",
+    "state.goal": "goal",
+    "state.todo": "todo list",
+    "state.model": "model selection",
+    "state.permission": "permission preset",
+    "state.sandbox": "sandbox mode",
+    "state.agentPreset": "agent preset",
+    "state.schedule": "scheduled task",
+    "state.workingDirectory": "working directory",
+    "state.separator": ", ",
+    "timeline.kindRescue": "File restore",
+    "timeline.rescueMeta": "Restored {restored} file(s) from rescue {id}"
   }
 }

package/locale/zh.json

@@ -122,6 +122,20 @@
     "toast.stoppedTurn": "，已停止运行中的回合",
     "confirm.resend": "回退后立即重发这条消息",
     "confirm.resendHint": "适合「重试这一轮」：回退后自动把原文发出去，想改内容就在输入框里编辑后再发。",
-    "toast.resent": "，已重发这条消息"
+    "toast.resent": "，已重发这条消息",
+    "confirm.stateChanges": "这段区间里改过会话状态：{list}；回溯只撤回对话，不会回滚这些状态",
+    "confirm.stateHint": "如需一并回退 plan/goal/待办等状态，请手动调整。",
+    "state.planMode": "计划模式",
+    "state.goal": "目标（goal）",
+    "state.todo": "待办清单",
+    "state.model": "模型选择",
+    "state.permission": "权限预设",
+    "state.sandbox": "沙箱模式",
+    "state.agentPreset": "智能体预设",
+    "state.schedule": "定时任务",
+    "state.workingDirectory": "工作目录",
+    "state.separator": "、",
+    "timeline.kindRescue": "文件恢复",
+    "timeline.rescueMeta": "从救援点恢复 {restored} 个文件 · {id}"
   }
 }

package/package.json

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