dsh-recall-plugin 2.4.7 → 2.4.8

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 本文件格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循语义化版本。
 
+## [2.4.8] - 2026-10-03
+
+撤回完成事件/回调（issue #19，方案见 [docs/plans/completed/plan-recall-event.md](docs/plans/completed/plan-recall-event.md)）：撤回到达终态时广播 cordis 事件 `dsh-recall/complete` / `dsh-recall/failed`，供同宿主任意插件监听（如长时记忆插件清理被撤回回合的记忆）。纯增量 opt-in：不订阅的插件零感知，撤回链路行为逐字节不变（事件发送失败、监听器抛错、下游慢执行均不影响主流程）。
+
+### 新增
+
+- **事件契约（`src/types/events.ts`，单一事实源）**：`dsh-recall/complete`（`sessionId`/`childSessionId`/`scope`/`cutSeq`/`messageId`/`root`/`count`/`chatReverted`/`archiveRequested`/`time`，`version: 1`）与 `dsh-recall/failed`（`stage: 'execute' | 'fork'`/`sessionId`/`messageId`/`scope`/`cutSeq`/`root`/`code?`/`error`/`time`）。首发即稳定公共契约（非 experimental）：新增字段走 minor，破坏性变更走 major 且 `version` 升 2。payload 不含消息正文；事件名与契约文件的绑定由 `tests/types/events-contract.test.ts` 编译期双向断言维持（host 产物因 build-host 逐文件转译不覆盖 `types/`，事件名在 routes-core 本地字面量声明）。
+- **host `notify` 端点（routes-core.ts）**：client 撤回终态上报的接缝——校验（缺 `status`/`sessionId`/`messageId` 复用 `RECALL_BAD_TYPE`，不加新错误码）→ `resolveRoot` 尽力 enrich（失败落 `null` 不阻断）→ `queueMicrotask` + try/catch 调 `ctx.emit`（下游抛错/慢执行不反噬端点）→ 恒 `{ ok: true }`。不进串行队列（零 git 操作）、不依赖 store（避开 lineage-record 的 NO_STORE 早退会吞事件的缺陷）；index.ts 以闭包注入 `emitEvent: (e, p) => ctx.emit(e, p)` 保持 ctx 不解构纪律。verify-host 端点白名单同步至 13 项（未同步时两处断言红灯，反向验证实测）。
+- **client 终态上报（recall-node.ts + util.ts）**：`buildRecallNotify` 纯函数按语义决策表组装载荷（六场景矩阵单测直钉），`executeRecall` 五处上报点 fire-and-forget（`.catch` 静默）——execute 拒（透传 `code`）/ execute 抛 → `failed(stage:'execute')`；fork 抛错/返空 → `failed(stage:'fork')`（**绝不发 complete**，防下游误清该回合记忆）；撤回链完整走完 → `complete`（`chatReverted` 为对话是否真回退的判据）。STALE 自动重预览是中间态，不上报。版本错位容错：旧 host 无此端点时上报静默失败（404），撤回不受影响；旧版 client 从不上报。
+- **README 双语「事件契约」章节**：事件名、payload 字段表、语义要点（STALE 不发、fork 失败只发 failed、`(sessionId, messageId, cutSeq)` 三元组幂等、隐私面）、semver 演进规则与版本错位矩阵、可直接粘贴的监听示例。
+
+### 测试
+
+- `tests/unit/routes-notify.test.js`（11 例）：参数校验缺失码 / root enrich 成功·抛错·返空 / emit 异步广播与 payload 字段 / 监听器抛错仍恒 `ok:true` 且 `recordError` 留痕 / `stage`-`code` 语义。
+- `tests/unit/recall-notify.test.js`（8 例）：`buildRecallNotify` 规格第一节六场景 + scope 透传与字段兜底。
+- `tests/client/recall-node.test.ts` 追加 7 例：五处接线点的调用时机与载荷（含 STALE 不发 notify、上报失败静默不反噬主链）。
+- `tests/types/events-contract.test.ts`：事件名字面量钉死、payload 形状断言、host 本地常量 ↔ 契约常量双向绑定、notify 端点返回类型双向绑定。基线 478 → 497（39 文件），client 83 → 90。
+
 ## [2.4.7] - 2026-09-30
 
 质量加固专项批次（[docs/plans/completed/plan-quality-hardening.md](docs/plans/completed/plan-quality-hardening.md) A1–A8，八项分四波：质量基建 → 数据安全 → 测试基建 → i18n）。2026-09-30 该计划连同 `plan-warmup-unhandled-rejection` 已归档到 `docs/plans/completed/`（活体冒烟第九节 R-1〜R-6 全过）。

package/README.en.md

@@ -7,13 +7,12 @@
 ![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-blue)
 ![Build](https://img.shields.io/badge/pure%20JS-green)
 
-[![DSH](https://img.shields.io/badge/DSH-0.2.0--rc.1-blue)](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.0-rc.1)
+[![DSH](https://img.shields.io/badge/DSH-0.2.0--rc.2-blue)](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.0-rc.2)
 ![DSH](https://img.shields.io/badge/DSH-Desktop-blue)
----
+
 Under any message you've sent, click "↶ Recall" — **your workspace files and the conversation history roll back to just before that message was sent**.
----
 
-Files and conversation roll back together: as each message is sent, the workspace is first snapshotted into an independent shadow git repository, and a recall uses it to restore files to their state before that message; the conversation is rewound through DSH's official `sessions.fork` to the turn boundary before it, with the original session archived and recoverable. After a recall, the message's text and attachments are placed back into the input box, ready to edit and resend. Snapshots never touch your project's own git and live under `$DSH_HOME` by default. The main boundary: snapshots are created only **when a message is sent** — messages from before the plugin was enabled have no snapshot and show no recall button.
+As each message is sent, the workspace is first snapshotted into an independent shadow git repository (your project's own git is never touched); a recall restores files from that snapshot and rewinds the conversation through DSH's official `sessions.fork` to the turn boundary before the message, with the original session archived and recoverable. The recalled message's text and attachments are placed back into the input box, ready to edit and resend. Snapshot storage lives under `$DSH_HOME` by default. The main boundary: snapshots are created only **when a message is sent** — messages from before the plugin was enabled have no snapshot and show no recall button.
 
 [Changelog](CHANGELOG.md)
 
@@ -27,6 +26,7 @@ Files and conversation roll back together: as each message is sent, the workspac
 - [Configuration](#configuration)
 - [Snapshot Maintenance & Cleanup](#snapshot-maintenance--cleanup)
 - [How It Works](#how-it-works)
+- [Event Contract (for same-host plugins)](#event-contract-for-same-host-plugins)
 - [Local Development (without publishing)](#local-development-without-publishing)
 - [License](#license)
 
@@ -45,26 +45,26 @@ Files and conversation roll back together: as each message is sent, the workspac
 Abilities with a version in parentheses require that version or later; the rest have no special version requirement.
 
 - **Files + conversation, rolled back together**: recalling isn't just about chat history — files the agent modified go back to their original state too; immune to your project's `.gitattributes` conversion, with byte-level fidelity for line endings and binary content (2.1.1+).
-- **Just want a fresh conversation? Leave the files alone** (2.3.24+): the confirmation panel offers a recall-scope choice — the default "Roll back files & conversation" is the full rollback; picking "Conversation only" keeps your project files byte-for-byte untouched (no safety snapshot either) and rewinds only the conversation, ideal when you dislike the reply but the file changes are exactly what you want.
+- **Just want a fresh conversation? Leave the files alone** (2.3.24+): the confirmation panel offers a recall-scope choice — the default "Roll back files & conversation" is the full rollback; "Conversation only" keeps your project files byte-for-byte untouched (no safety snapshot either), ideal when you dislike the reply but the file changes are exactly what you want.
 - **Never touches your project's own git, and keeps it clean**: snapshots live in an independent shadow git repository — branches, staging area, and uncommitted changes are untouched; storage stays under `$DSH_HOME` regardless of the session's sandbox permission (workspace-write / read-only sessions work as usual), falling back to an in-project `.dsh-recall-snapshots` only when home itself is unwritable.
-- **See the list before you act — and change your mind as often as you like**: recall first shows the list of files that will change (modified / restored / deleted); nothing runs until you confirm. After a recall you can recall again to an even earlier point, and files overwritten during a recall always remain recoverable (up to 500 snapshots per workspace by default).
-- **Resend right after a recall** (2.3.15+): a recall places the message's text and attachments back into the input box — images and files return as well, so you can edit and send again without picking the attachments over.
-- **A guarded recall path** (2.0+; auto-rescue 2.1+): recall is refused while an agent is running, and a new snapshot after the preview forces a fresh preview; a "pre-rollback" safety snapshot is taken before every recall, a failed rollback is rescued automatically, and a failed rescue gives you a copy-paste-ready manual recovery command.
-- **Disk-friendly, self-maintaining**: snapshots use git delta compression and large files are skipped automatically (threshold configurable); periodic lossless `git gc`, session-deletion cleanup, and optional cleanup by cap or retention age — plus a **workspace → session → snapshot** tree manager on the settings page with search and per-level deletion.
+- **See the list before you act — and change your mind as often as you like**: recall first shows the list of files that will change (modified / restored / deleted); nothing runs until you confirm. After a recall you can recall again to an even earlier point, and files overwritten during a recall always remain recoverable.
+- **Resend right after a recall** (2.3.15+): the message's text and attachments (images, files) return to the input box, so you can edit and send again without picking the attachments over.
+- **A guarded recall path** (2.0+; auto-rescue 2.1+): a new snapshot after the preview forces a fresh preview; a "pre-rollback" safety snapshot is taken before every recall, a failed rollback is rescued automatically, and a failed rescue gives you a copy-paste-ready manual recovery command.
+- **Disk-friendly, self-maintaining**: snapshots use git delta compression and large files are skipped automatically (threshold configurable); periodic lossless `git gc`, session-deletion cleanup, and cleanup by cap or retention age — plus a **workspace → session → snapshot** tree manager on the settings page with search and per-level deletion.
 - **Failures speak up and heal** (self-healing 2.1+): failures are classified by root cause (git missing / disk full / permission denied / lock conflict / directory conflict) with actionable guidance (the same fault only bothers you once per 10 minutes; reasons land in the settings card's "Recent errors"); leftover objects are pruned, 3 consecutive failures trigger exponential backoff, concurrent instances yield via heartbeats, and unindexable paths are skipped with a notice instead of failing the whole snapshot (they are neither restored nor deleted on recall).
 
 ## Known Limitations
 
 Boundaries accepted by design and edge cases not yet covered — worth checking before you rely on them.
 
-- Snapshots are created **when a message is sent**; messages from before the plugin was enabled have no snapshot and show no recall button.
+- Snapshots are created **when a message is sent**: messages from before the plugin was enabled have no snapshot and show no recall button.
 - Snapshots are **best-effort**: there is a 0.5–1.5 second window between the message arriving and `git add` (on Windows, a single PowerShell start alone costs about 0.4s). If a trivial task finishes editing files inside that window, the snapshot captures the turn's own changes — the file rollback then becomes a no-op (the preview panel reports "0 files will change") while the conversation rollback is unaffected.
 - The first user message of a session cannot roll back the conversation (files only), because fork requires an earlier turn boundary.
 - Recall cannot be initiated while an agent is running in the target workspace (by design — stop the agent first).
 - Supports Windows (PowerShell 5.1/7 + git CLI) and Linux/macOS (bash + git CLI). Windows is thoroughly verified on real machines; Linux has been fully tested on WSL2 (Ubuntu 26.04, bash 5.3 + git 2.53), including Chinese paths, home fallback, session cleanup, and gc; the macOS side is written to be bash 3.2 compatible but has not been tested on real hardware yet.
-- Nested git repositories inside the workspace (subdirectories with their own `.git`) cannot be indexed: the snapshot proceeds for everything else (fail-open, with a toast listing the skipped paths), but their contents do not participate in recalls.
+- Nested git repositories inside the workspace (subdirectories with their own `.git`) cannot be indexed: the snapshot proceeds for everything else (fail-open, with a notice listing the skipped paths), but their contents do not participate in recalls.
 - Extreme cases like filenames containing newlines/TAB are beyond the diff list's parsing capability (negligible probability).
-- **Interplay with dsh-routing-suite (progressive tool-disclosure router)**: if you also run the router-standard preset, a recall forks a new session via `sessions.fork`, which resets the router's stage to its default (the tool surface temporarily narrows). Symptoms, root cause and the fix are documented in [docs/routing-interplay.md](docs/routing-interplay.md) (Chinese).
+- **Interplay with dsh-routing-suite (progressive tool-disclosure router)**: if you also run its router-standard preset, a recall forks a new session via `sessions.fork`, which resets the router's stage to its default (the tool surface temporarily narrows). Symptoms, root cause and the fix are documented in [docs/routing-interplay.md](docs/routing-interplay.md) (Chinese).
 
 ## Installation
 
@@ -72,35 +72,59 @@ Prerequisites:
 
 - git CLI: without it the recall button won't appear (a notice shows at the top of the page); DSH itself keeps running.
 - Shell: PowerShell 5.1 / 7 on Windows; bash on Linux/macOS.
-- DSH version: `0.1.2-alpha.1` through `0.2.0-rc.1`. peerDependencies open a window per minor line (`>=0.1.2-alpha.1 <0.1.3 || >=0.1.3-alpha.1 <0.1.4 || >=0.1.5-alpha.1 <0.1.6 || >=0.1.6-alpha.1 <0.1.7 || >=0.1.7-alpha.1 <0.1.8 || >=0.2.0-rc.1 <0.2.1`, consistent with the `dsh.compatibility.dshReleases` declaration): each line is anchored at its first verified version with an upper bound at the next minor, so later prereleases/releases within a verified line are admitted without touching the peer declaration, while unverified new minor lines remain blocked (the 0.2.0 line needs its own tuple — npm's prerelease gate only admits a prerelease from a comparator with the same tuple, so the existing `<0.1.8` segment cannot admit `0.2.0-rc.1`).
-- **0.1.7-alpha.1 is a breaking release** (`ShellExecutor.run`/`start` became `execute().result()`, and the settings surface became `SettingsForms`, addressed by profile entry id with `.volatile()` marked fields); the plugin ships **both seams side by side** — the same release works on every 0.1.2–0.1.6 line and on 0.1.7, with unchanged behaviour on older DSH versions.
+- DSH version: `0.1.2-alpha.1` through `0.2.0-rc.2`; later versions within a verified minor line are admitted automatically, while unverified new minor lines are blocked by the startup compatibility gate (window mechanics in the fold below).
+- **0.1.7-alpha.1 is a breaking release** (the shell execution and settings interfaces changed); the plugin ships both seams side by side — the same release works on every 0.1.2–0.1.6 line and on 0.1.7+, with unchanged behaviour on older DSH versions.
 - `0.1.1-rc.2` and earlier are not supported: their client runtime lacks the `sessions`/`workspaces`/`uiWorkspace` services, so the plugin UI silently fails to render.
 
-Install & verify:
+<details>
+<summary>peer window mechanics (read before upgrading dsh)</summary>
+
+peerDependencies open a window per minor line, consistent with the `dsh.compatibility.dshReleases` declaration:
 
-- Official DSH plugin command: install and auto-mount into the web profile
-```powershell
-dsh plugin --profile web add dsh-recall-plugin
-```
-- Or install directly from git:
-```powershell
-dsh plugin --profile web add github:limbo947/dsh-recall-plugin
 ```
-- Restart the DSH process (pick whichever matches how you start it)
-```powershell
-dsh web                      # run in the foreground
-pm2 restart <your-dsh-name>  # if managed by pm2
+>=0.1.2-alpha.1 <0.1.3 || >=0.1.3-alpha.1 <0.1.4 || >=0.1.5-alpha.1 <0.1.6 || >=0.1.6-alpha.1 <0.1.7 || >=0.1.7-alpha.1 <0.1.8 || >=0.2.0-rc.1 <0.2.1
 ```
 
-**Verify**: after restarting, hard-refresh the page (Ctrl+Shift+R) and hover over any user message sent after the plugin was enabled — the "↶" appearing next to the copy button means it works. No button? Nine times out of ten the DSH process wasn't restarted, or git CLI isn't on PATH.
+Each line is anchored at its first verified version with an upper bound at the next minor, so later prereleases/releases within a verified line are admitted without touching the peer declaration. The 0.2.0 line needs its own tuple: npm's prerelease gate only admits a prerelease from a comparator with the same tuple, so the existing `<0.1.8` segment cannot admit `0.2.0-rc.1`.
+
+</details>
+
+Install & verify:
+
+- Official DSH plugin command (pick the profile for your frontend); installs and auto-mounts into that profile:
+
+  ```powershell
+  dsh plugin --profile web add dsh-recall-plugin      # Web UI
+  dsh plugin --profile desktop add dsh-recall-plugin  # Desktop
+  ```
+
+- Or install directly from git:
+
+  ```powershell
+  dsh plugin --profile web add github:limbo947/dsh-recall-plugin
+  ```
+
+- Restart the DSH process (pick whichever matches how you start it):
+
+  ```powershell
+  dsh web                      # run in the foreground
+  pm2 restart <your-dsh-name>  # if managed by pm2
+  ```
+
+- **Verify**: after restarting, hard-refresh the page (Ctrl+Shift+R) and hover over any user message sent after the plugin was enabled — the "↶" appearing next to the copy button means it works. No button? Nine times out of ten the DSH process wasn't restarted, or git CLI isn't on PATH.
+- **Uninstall** (removes both the dependency and the mount layer):
 
-**Uninstall**: `dsh plugin --profile web remove dsh-recall-plugin` (removes both the dependency and the mount layer). Snapshot data is kept under `dsh-recall-snapshots/` in home; delete that directory manually if you want it fully gone.
+  ```powershell
+  dsh plugin --profile web remove dsh-recall-plugin
+  ```
+
+  Snapshot data is kept under `dsh-recall-snapshots/` in home; delete that directory manually if you want it fully gone.
 
 ## Usage
 
-A full recall of one user message sent after the plugin was enabled goes like this.
+A full recall of one user message sent after the plugin was enabled goes like this:
 
-1. Hover over any user message sent **after the plugin was enabled** (including steering messages inserted while the agent is running) — "↶ Recall" appears to the left of the copy button.
+1. Hover over the message (including steering messages inserted while the agent is running) — "↶ Recall" appears to the left of the copy button.
 2. Click it → the confirmation panel shows the list of files that will change (modified / restored / deleted), plus a scope choice: "Roll back files & conversation" (default) or "Conversation only" (files stay as they are).
 3. Click "Confirm rollback" (or "Confirm conversation recall") → files are restored to their state before that message was sent (files are untouched in conversation-only mode); the view switches to a new session (that message and everything after it is removed), while the original session is archived and can be recovered anytime.
 
@@ -127,14 +151,14 @@ The settings card also offers "Restore defaults" (one-click reset of all fields)
 
 Every UI surface the plugin draws itself (recall button and confirmation panel, toasts, the three settings cards, the snapshot manager tree, recent errors) is bilingual and driven by `locale` — switch it in the "Interface" group of the config card; saving applies immediately (the settings page switches at once, chat-side wording follows on the next page reload).
 
-Two explicit v1 limits: (1) field descriptions rendered by the host's own settings form (i.e. the `Schema.description()` texts) stay in Chinese — the plugin cannot localize those; the plugin's own config card is unaffected. (2) For host-side errors that carry dynamic detail (a failed rollback's rescue outcome, a specific validation reason, a raw exception), the panel and "Recent errors" show the host text verbatim instead of a localized short phrase — we prefer mixed-language output over swallowing the detail you need to troubleshoot.
+Two explicit limits: (1) field descriptions rendered by the host's own settings form (i.e. the `Schema.description()` texts) stay in Chinese — the plugin cannot localize those; the plugin's own config card is unaffected. (2) Host-side errors that carry dynamic detail (a failed rollback's rescue outcome, a specific validation reason, a raw exception) are shown verbatim in the panel and "Recent errors" instead of a localized short phrase — we prefer mixed-language output over swallowing the detail you need to troubleshoot.
 
 ## Snapshot Maintenance & Cleanup
 
 The plugin manages disk usage automatically — no manual housekeeping needed:
 
-- **Periodic gc**: every 50 snapshots or 24 hours since the last gc (whichever comes first, thresholds configurable), `git gc` runs in the background to pack loose objects. This is lossless — every snapshot remains recallable. The throttle token lives in `gc.stamp` inside the shadow repository, so restarting DSH does not reset the cycle.
-- **Cap & retention**: up to 500 snapshots per workspace by default (oldest pruned beyond the cap); optionally set `retentionDays` for age-based retention. The two triggers work independently and can both be adjusted or disabled in the config card.
+- **Periodic gc**: every 50 snapshots or 24 hours since the last gc (whichever comes first, thresholds configurable), `git gc` runs in the background to pack loose objects — lossless, every snapshot remains recallable. The throttle token lives in `gc.stamp` inside the shadow repository, so restarting DSH does not reset the cycle.
+- **Cap & retention**: up to 500 snapshots per workspace by default (oldest pruned beyond the cap), plus optional age-based retention via `retentionDays`; the two triggers work independently and can both be adjusted or disabled in the config card.
 - **Session-deletion cleanup**: once a session is permanently deleted (its log gone from disk), the next maintenance pass automatically removes all of its snapshots and frees the space. **Archiving is not deletion** — logs of sessions archived by the recall feature itself still exist, so their snapshots are kept and recoverable from the archive. The check is conservative: a session that is merely cold (not in memory) is never cleaned, and when the log's state cannot be verified, it is left alone.
 - **User-defined exclusions**: open the "**Settings → Plugin Config → Recall Plugin**" card (collapsed by default; click the header to expand) to edit snapshot exclusions visually — type a path or pattern and press Enter to add it, one-click append for common patterns (`dist/`, `*.log`, `.env`, …), and saved changes take effect on the very next snapshot/recall, no restart needed. Alternatively, edit `$DSH_HOME/dsh-recall-snapshots/exclude.txt` directly (or `~/.dsh/dsh-recall-snapshots/exclude.txt` when unset; UTF-8): one gitignore-style pattern per line, lines starting with `#` are comments — both paths edit the same configuration. For example:
 
@@ -146,7 +170,7 @@ The plugin manages disk usage automatically — no manual housekeeping needed:
   ```
 
   This applies to all projects (when home is unwritable and a workspace falls back to in-project storage, it gets its own independent exclusion config, listed as a separate card in the settings tab). New exclusions only affect future snapshots; **when recalling to an earlier snapshot, files that weren't excluded at that time are still restored** (returning to the state as it was — that's exactly what recall means). To fully purge a directory that already made it into snapshots, manually delete the corresponding hash directory under `dsh-recall-snapshots/` in home.
-- **Tree-view snapshot manager**: open "**Settings → Plugin Config → Recall Plugin → Snapshot Manager**" to see the tree list — first level workspace (folder name), second level session (session title, recall chains grouped into version families), third level snapshot (time + message content summary, hover for the full content). Search and "load more" are supported; workspace and session nodes expand/collapse; every level has a delete button on its right, with a confirmation before deletion. Deleting a workspace = clearing all snapshots of that workspace; deleting a session = clearing all snapshots of that session within that workspace; deleting a leaf = removing just that single snapshot; a confirmed "Delete all" button sits at the top.
+- **Tree-view snapshot manager**: open "**Settings → Plugin Config → Recall Plugin → Snapshot Manager**" for a three-level tree — workspace (folder name) → session (session title, recall chains grouped into version families) → snapshot (time + message content summary, hover for the full content). Search and "load more" are supported; workspace and session nodes expand/collapse; every level has a delete button on its right, with a confirmation before deletion — deleting a workspace clears all of its snapshots, deleting a session clears all of that session's snapshots, deleting a leaf removes just that single snapshot; a confirmed "Delete all" button sits at the top.
 
 ## How It Works
 
@@ -163,6 +187,63 @@ When each user message is sent (before the agent touches any files), the workspa
 
 - The format and version-compatibility rules for every file in the store directory (index, recall chain, format marker, intent journal, etc.) live in [docs/format.md](docs/format.md).
 
+## Event Contract (for same-host plugins)
+
+When a recall reaches its terminal state, the plugin broadcasts two public cordis events (2.4.8+). Any plugin on the same host can subscribe — for example, a long-term-memory plugin can purge memories written by the recalled turn:
+
+```js
+// inside a same-host plugin
+ctx.on('dsh-recall/complete', (e) => {
+  if (e.chatReverted) memory.purgeTurn(e.root, e.sessionId, e.cutSeq)
+})
+ctx.on('dsh-recall/failed', (e) => {
+  if (e.stage === 'fork') log.warn('files reverted but the conversation did not', e)
+})
+```
+
+`dsh-recall/complete` — recall succeeded:
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `version` | `1` | Contract version (see evolution rules below) |
+| `sessionId` | `string` | The original session being recalled |
+| `childSessionId` | `string \| null` | The forked session; `null` for a files-only recall |
+| `scope` | `'both' \| 'session-only'` | Recall scope |
+| `cutSeq` | `number \| null` | Conversation cut point; `null` when the message was the session's first |
+| `messageId` | `string` | ID of the recalled message (snapshot primary key) |
+| `root` | `string \| null` | Workspace root path; `null` if host resolution failed |
+| `count` | `number` | Number of files reverted (always `0` for `session-only`) |
+| `chatReverted` | `boolean` | Whether the conversation actually reverted (downstream gate, see below) |
+| `archiveRequested` | `boolean` | Whether archiving of the original session was initiated (fire-and-forget, not completion) |
+| `time` | `number` | When the host received the report (ms) |
+
+`dsh-recall/failed` — recall failed:
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `version` | `1` | Contract version |
+| `stage` | `'execute' \| 'fork'` | Failure stage: file revert rejected/errored, or files reverted but conversation revert failed |
+| `sessionId` | `string \| null` | The original session being recalled |
+| `messageId` | `string` | ID of the recalled message |
+| `scope` | `'both' \| 'session-only'` | Recall scope |
+| `cutSeq` | `number \| null` | Cut point known to the client (may not have been used) |
+| `root` | `string \| null` | Workspace root path; `null` if resolution failed |
+| `code` | `string?` | Only for `stage='execute'`: host error code (`AGENT_BUSY` / `NO_SNAPSHOT` / …) |
+| `error` | `string` | Error description |
+| `time` | `number` | When the host received the report (ms) |
+
+Semantics every consumer should know:
+
+- **Only terminal states emit events.** The "preview went stale, auto re-previewing" (STALE) path is an intermediate state and emits nothing; neither does a cancelled/closed panel.
+- **A fork failure emits `failed(stage:'fork')` and never `complete`** — at that point files are reverted but the conversation is not; emitting `complete` would make downstream purge memories of a still-intact conversation. Gate "the conversation actually reverted" on `complete.chatReverted` (a files-only `complete` has `chatReverted:false`).
+- For `failed(stage:'execute')` originating from an exception (rather than a guard rejection), **whether files were reverted is unknown** — treat it conservatively.
+- Retries/repeated recalls may emit multiple events for the same `(sessionId, messageId, cutSeq)` triple; downstream should deduplicate on it.
+- Payloads contain no message bodies — only IDs / seq / paths — and are visible only to plugins on the same host.
+
+Versioning: shipped as a stable public contract from day one (not experimental). Additive changes ride minor releases; breaking changes ride a major release with `version` bumped to `2`, so downstream can branch on it.
+
+Version skew: an old plugin frontend (<2.4.8) never reports, so events never fire; a new frontend with an old host (<2.4.8) gets a missing endpoint and silently ignores it — recall itself is unaffected.
+
 ## Local Development (without publishing)
 
 Point the profile's dependency for this package at your clone via `link:`; DSH loads the built `lib/` artifacts from the workspace (source lives in `src/`), so run `npm run build` after editing `src/`, then restart DSH — no copying or publishing needed:
@@ -181,8 +262,8 @@ Note: all source lives in `src/` (host in `src/host/`, browser side in `src/clie
 
 ### Tests
 
-- `npm test`: pure-logic unit tests (vitest, 37 files / 476 cases, no DSH dependency, runs identically in CI and locally) — config parsing, snapshot parsers, rescue orchestration, error classification, the disk-format guard, the recall intent journal, i18n dictionaries plus a missing-key scan, script-template same-name-export contract, shell execution dual-channel split and failure grading, settings bridge across both generations, client pure functions, published-package layout, snapshot index persistence, storage caps and retention, etc.;
-- `npm run test:client`: client component tests (vitest + jsdom, 6 files / 82 cases, runs in CI) — the recall node main chain (preview→execute→fork→refill), snapshot-manager tree and delete flows, config/exclude card error paths, the logger switch matrix, and the zh/en rendering chains; assertions pin behaviour and structure only (className / aria / request payloads), never literal copy;
+- `npm test`: pure-logic unit tests (vitest, 39 files / 497 cases, no DSH dependency, runs identically in CI and locally) — config parsing, snapshot parsers, rescue orchestration, error classification, the disk-format guard, the recall intent journal, recall terminal-event payload assembly, i18n dictionaries plus a missing-key scan, script-template same-name-export contract, shell execution dual-channel split and failure grading, settings bridge across both generations, client pure functions, published-package layout, snapshot index persistence, storage caps and retention, etc.;
+- `npm run test:client`: client component tests (vitest + jsdom, 6 files / 90 cases, runs in CI) — the recall node main chain (preview→execute→fork→refill) and terminal-event reporting, snapshot-manager tree and delete flows, config/exclude card error paths, the logger switch matrix, and the zh/en rendering chains; assertions pin behaviour and structure only (className / aria / request payloads), never literal copy;
 - `npm run test:probe`: official-API field probes (requires a local dsh installation; **must run after any dsh upgrade**) — pins fields like `renderMessageImages`/`node`/`cwd`, `atSeq`/`increaseTitle` and the fork-cut anchors of `sessions.fork`, `listSessions` record shape, `AgentRegistry`, the shell execution seam (`execute`/`ShellExecution.result`), the settings surface (`SettingsForms`/profile entry id/volatile gate) plus `loader/volatile-update` and the `Fiber.entry` shape, and goes red on violation;
 - `npm run verify:host`: assembly gate (requires a local dsh installation) — boots the plugin with a real cordis context in two passes (legacy settings stub and a modern-face-only stub), asserting inject declarations, endpoint registration, Config schema, teardown cleanliness and settings-face dispatch, catching assembly regressions before release;
 - `npm run build`: full host+client build (mandatory after any `src/` change); `npm run check:dsh`: dsh version inspection (pre-release).

package/README.md

@@ -5,12 +5,11 @@
 [![npm version](https://img.shields.io/npm/v/dsh-recall-plugin?style=flat-square&label=npm&color=3178C6)](https://www.npmjs.com/package/dsh-recall-plugin)
 [![npm downloads](https://img.shields.io/npm/dm/dsh-recall-plugin?style=flat-square&label=downloads&color=1F883D)](https://www.npmjs.com/package/dsh-recall-plugin)
 ![License](https://img.shields.io/badge/license-MIT-blue)
-[![DSH](https://img.shields.io/badge/DSH-0.2.0--rc.1-blue)](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.0-rc.1)
----
+[![DSH](https://img.shields.io/badge/DSH-0.2.0--rc.2-blue)](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.0-rc.2)
+
 在任意一条你发过的消息下方点「↶ 撤回」——**工作区文件和对话历史一起回到那条消息发出之前的状态**。
----
 
-文件与对话一起回退：每条消息发送时，工作区先被快照进一个独立的影子 git 仓库，撤回时用它把文件恢复到消息发出之前；对话通过 DSH 官方的 `sessions.fork` 切到该消息之前的 turn 边界，原会话归档保留、随时可找回。撤回后，这条消息的文本与附件自动放回输入框，改完即可重发。快照全程不触碰项目自身的 git，存储默认落在 `$DSH_HOME` 下。最主要的边界：快照只在**消息发送时**创建，插件启用前的历史消息没有快照、不显示撤回按钮。
+每条消息发送时，工作区先被快照进一个独立的影子 git 仓库（不碰项目自身的 git）；撤回时按快照恢复文件，并经 DSH 官方 `sessions.fork` 把对话切回该消息之前的 turn 边界，原会话归档保留、随时可找回。被撤回消息的文本与附件自动放回输入框，改完即可重发。快照存储默认落在 `$DSH_HOME` 下。最主要的边界：快照只在**消息发送时**创建，插件启用前的历史消息没有快照、不显示撤回按钮。
 
 [更新日志](CHANGELOG.md)
 
@@ -24,6 +23,7 @@
 - [配置项](#配置项)
 - [快照维护与清理](#快照维护与清理)
 - [工作原理](#工作原理)
+- [事件契约（供同宿主插件监听）](#事件契约供同宿主插件监听)
 - [本地开发（无需发布）](#本地开发无需发布)
 - [License](#license)
 
@@ -42,26 +42,26 @@
 带括号版本号的能力需要该版本或更高；其余无特殊版本要求。
 
 - **文件 + 对话，整段回退**：撤回的不只是聊天记录，agent 改过的文件也一并回到原样；不受项目 `.gitattributes` 转换影响，换行与二进制内容字节级保真（2.1.1+）。
-- **只想重来对话？文件可以不动**（2.3.24+）：确认面板里可二选一撤回范围——默认「回退文件与对话」为完整回退；选「仅撤回对话」则项目文件一个字节都不动（也不打安全快照）、只回退对话，适合对生成结果不满意、但文件改动正是想要内容的场景。
-- **不碰你项目自己的 git，目录保持干净**：快照存在独立的影子 git 仓库里，分支、暂存区、未提交改动统统不受影响；存储默认落在 `$DSH_HOME` 下，与会话的沙箱权限无关（workspace-write / read-only 照常工作），仅当 home 不可写才降级到项目内 `.dsh-recall-snapshots`。
-- **先看清单再动手，可反复后悔**：撤回前展示将变更的文件清单（修改 / 恢复 / 删除），确认后才执行；撤回后还能再撤到更早，被覆盖的文件一直找得回来（默认每工作区保留 500 条）。
-- **撤回完就能重发**（2.3.15+）：撤回会把这条消息的文本与附件一起放回输入框——图片、文件原样回来，改完直接发送，不必重新挑一遍附件。
-- **撤回全程有防护**（2.0+，救援 2.1+）：agent 运行中拒绝撤回，预览后出现新快照会强制重新预览；执行前自动打「回退前」安全快照，回退失败自动救援，救援失败给出可直接复制执行的手动恢复命令。
-- **磁盘友好、自动维护**：快照走 git delta 增量压缩，大文件自动跳过（阈值可配）；定期无损 `git gc`，会话删除联动清理，可按条数与保留天数自动清理；设置页提供**工作区 → 会话 → 快照**三级树形管理，支持搜索与分级删除。
-- **失败不静默、能自愈**（自愈 2.1+）：失败按根因分类（git 缺失 / 磁盘满 / 无权限 / 锁冲突 / 目录冲突）给出可行动提示，同类故障 10 分钟只打扰一次，失败原因进设置卡片「最近错误」；自动清理残骸、连续 3 次失败指数退避、多实例按心跳互让；无法索引的路径跳过并告知，不中断整条快照（撤回时也不触碰它们）。
+- **只想重来对话？文件可以不动**（2.3.24+）：确认面板可二选一撤回范围——默认「回退文件与对话」为完整回退；「仅撤回对话」则项目文件一个字节都不动（也不打安全快照），适合对回复不满意、但文件改动正是想要内容的场景。
+- **不碰项目自身的 git，目录保持干净**：快照存在独立的影子 git 仓库，分支、暂存区、未提交改动统统不受影响；存储默认落在 `$DSH_HOME` 下、与会话沙箱权限无关（workspace-write / read-only 照常工作），仅当 home 不可写才降级到项目内 `.dsh-recall-snapshots`。
+- **先看清单再动手，可反复后悔**：撤回前展示将变更的文件清单（修改 / 恢复 / 删除），确认后才执行；撤回后还能再撤到更早，被覆盖的文件一直找得回来。
+- **撤回完就能重发**（2.3.15+）：消息的文本与附件（图片、文件）一起放回输入框，改完直接发送，不必重新挑一遍附件。
+- **撤回全程有防护**（2.0+，救援 2.1+）：预览后出现新快照会强制重新预览；执行前自动打「回退前」安全快照，回退失败自动救援，救援失败给出可直接复制执行的手动恢复命令。
+- **磁盘友好、自动维护**：快照走 git delta 增量压缩，大文件自动跳过（阈值可配）；定期无损 `git gc`、会话删除联动清理、按条数与保留天数自动清理；设置页提供**工作区 → 会话 → 快照**三级树形管理，支持搜索与分级删除。
+- **失败不静默、能自愈**（自愈 2.1+）：失败按根因分类（git 缺失 / 磁盘满 / 无权限 / 锁冲突 / 目录冲突）给出可行动提示，同类故障 10 分钟只打扰一次，原因进设置卡片「最近错误」；自动清理残骸、连续 3 次失败指数退避、多实例按心跳互让；无法索引的路径跳过并告知，不中断整条快照（撤回时也不触碰它们）。
 
 ## 已知限制
 
 设计上接受的边界与尚未覆盖的极端情形，使用前值得先确认。
 
-- 快照在**消息发送时**创建，插件启用前的历史消息没有快照，不显示撤回按钮。
-- 快照是**尽力捕获**：从收到消息到 `git add` 之间有约 0.5–1.5 秒窗口（Windows 上仅一次 PowerShell 启动就占约 0.4 秒）。秒级完成的琐碎任务若在这个窗口内改完文件，该快照会连带捕获本轮改动——撤回时文件回退成为空操作（预览面板显示「共 0 个文件将变更」），对话回退不受影响。
+- 快照在**消息发送时**创建：插件启用前的历史消息没有快照，不显示撤回按钮。
+- 快照是**尽力捕获**：从收到消息到 `git add` 之间有约 0.5–1.5 秒窗口（Windows 上仅一次 PowerShell 启动就占约 0.4 秒）。秒级任务若在这个窗口内改完文件，该快照会连带捕获本轮改动——撤回时文件回退成为空操作（预览面板显示「共 0 个文件将变更」），对话回退不受影响。
 - 会话第一条用户消息无法回退对话（仅文件回退），因为 fork 需要更早的 turn 边界。
 - 目标工作区的 agent 正在运行时无法发起撤回（防护设计，先停止 agent 再撤回）。
 - 支持 Windows（PowerShell 5.1/7 + git CLI）与 Linux/macOS（bash + git CLI）。Windows 真机验证充分；Linux 已在 WSL2（Ubuntu 26.04，bash 5.3 + git 2.53）实测全流程（含中文路径、home 降级、会话清理、gc）；macOS 侧脚本按 bash 3.2 兼容编写，尚未真机实测。
-- 工作区内嵌套的其他 git 仓库（子目录自带 `.git`）无法索引：快照对其余部分照常（fail-open，页面会提示跳过了哪些路径），但其内容不参与回退。
-- 文件名含换行/TAB 的极端情形不在 diff 清单的解析能力内（概率可忽略）。
-- **与 dsh-routing-suite（渐进式工具披露路由）的交互**：若同时启用 dsh-routing-suite 的 router-standard 预设，撤回会经 `sessions.fork` 出新会话，导致路由阶段重置为默认（工具面临时收窄）。现象、成因与解决方案见 [docs/routing-interplay.md](docs/routing-interplay.md)。
+- 工作区内嵌套的其他 git 仓库（子目录自带 `.git`）无法索引：其余部分快照照常（fail-open，页面会提示跳过了哪些路径），但其内容不参与回退。
+- 文件名含换行/TAB 的极端情形超出 diff 清单的解析能力（概率可忽略）。
+- **与 dsh-routing-suite（渐进式工具披露路由）的交互**：同时启用其 router-standard 预设时，撤回经 `sessions.fork` 出新会话会把路由阶段重置为默认（工具面临时收窄）。现象、成因与解决方案见 [docs/routing-interplay.md](docs/routing-interplay.md)。
 
 ## 安装
 
@@ -69,37 +69,59 @@
 
 - git CLI：未安装时撤回按钮不出现（页面顶部会提示安装 git），不影响 DSH 运行。
 - shell：Windows 上 PowerShell 5.1 / 7 均可；Linux/macOS 需 bash。
-- DSH 版本：`0.1.2-alpha.1` 至 `0.2.0-rc.1`。peerDependencies 按 minor 版本线开窗（`>=0.1.2-alpha.1 <0.1.3 || >=0.1.3-alpha.1 <0.1.4 || >=0.1.5-alpha.1 <0.1.6 || >=0.1.6-alpha.1 <0.1.7 || >=0.1.7-alpha.1 <0.1.8 || >=0.2.0-rc.1 <0.2.1`，与 `dsh.compatibility.dshReleases` 声明一致）：每条线以首个核验版本为下限、上界开到下一 minor，同线内后续 prerelease/正式版自动放行、无需改 peer 声明；未核验的新 minor 线仍被拦截（0.2.0 线必须显式开窗——npm 的 prerelease 门槛要求同 tuple 且带 prerelease 的比较器，既有 `<0.1.8` 段放行不了 `0.2.0-rc.1`）。
-- **0.1.7-alpha.1 是破坏性版本**（`ShellExecutor` 的 `run`/`start` 换成 `execute().result()`；settings 面换成 `SettingsForms`、按 profile 条目 id 寻址并要求字段标 `.volatile()`），插件采用**双分支共存适配**——同一次发布同时兼容 0.1.2–0.1.6 各线与 0.1.7，老版本 DSH 上行为不变。
+- DSH 版本：`0.1.2-alpha.1` 至 `0.2.0-rc.2`；已核验 minor 线内的后续版本自动放行，未核验的新 minor 线会被启动期兼容门禁拦截（开窗机制见下方折叠块）。
+- **0.1.7-alpha.1 是破坏性版本**（shell 执行与 settings 面接口更换），插件内置双分支共存适配：同一发布同时兼容 0.1.2–0.1.6 各线与 0.1.7+，老版本 DSH 上行为不变。
 - `0.1.1-rc.2` 及更早不支持：那条线的客户端运行时没有 `sessions`/`workspaces`/`uiWorkspace` 服务，插件 UI 会静默不渲染。
 
-安装与验证：
+<details>
+<summary>peer 版本开窗机制（升级 dsh 前可看）</summary>
 
-- DSH 官方插件命令：安装并自动挂载进profile
+peerDependencies 按 minor 版本线开窗，与 `dsh.compatibility.dshReleases` 声明一致：
 
-Web UI
-```
-dsh plugin --profile web add dsh-recall-plugin
 ```
-Desktop
-```
-dsh plugin --profile desktop add dsh-recall-plugin
+>=0.1.2-alpha.1 <0.1.3 || >=0.1.3-alpha.1 <0.1.4 || >=0.1.5-alpha.1 <0.1.6 || >=0.1.6-alpha.1 <0.1.7 || >=0.1.7-alpha.1 <0.1.8 || >=0.2.0-rc.1 <0.2.1
 ```
+
+每条线以首个核验版本为下限、上界开到下一 minor，同线内后续 prerelease/正式版自动放行、无需改 peer 声明。0.2.0 线必须显式开窗：npm 的 prerelease 门槛要求同 tuple 且带 prerelease 的比较器，既有 `<0.1.8` 段放行不了 `0.2.0-rc.1`。
+
+</details>
+
+安装与验证：
+
+- 官方命令安装（按所用前端选 profile），安装后自动挂载进该 profile：
+
+  ```powershell
+  dsh plugin --profile web add dsh-recall-plugin      # Web UI
+  dsh plugin --profile desktop add dsh-recall-plugin  # Desktop
+  ```
+
 - 也可从 git 直接安装：
-```powershell
-dsh plugin --profile web add github:limbo947/dsh-recall-plugin
-```
+
+  ```powershell
+  dsh plugin --profile web add github:limbo947/dsh-recall-plugin
+  ```
+
+- 重启 DSH 进程（按你的启动方式选择）：
+
+  ```powershell
+  dsh web                      # 前台运行
+  pm2 restart <你的-dsh-名称>  # pm2 托管时
+  ```
 
 - 验证：重启后硬刷新页面（Ctrl+Shift+R），悬停任意一条插件启用后发送的用户消息——复制按钮旁出现「↶」即生效。没有按钮？九成是没重启 DSH 进程，或 git CLI 不在 PATH 里。
+- 卸载（同时移除依赖与挂载）：
 
-- 卸载：同时移除依赖与挂载，快照数据保留在 home 下 `dsh-recall-snapshots/`，想彻底清除手动删掉该目录即可。
-```powershell
-dsh plugin --profile web remove dsh-recall-plugin
-```
+  ```powershell
+  dsh plugin --profile web remove dsh-recall-plugin
+  ```
+
+  快照数据保留在 home 下 `dsh-recall-snapshots/`，想彻底清除手动删掉该目录即可。
 
 ## 使用
 
-1. 鼠标悬停任意**插件启用后发送**的用户消息（含 agent 运行中插入的转向指令消息），复制按钮左侧出现「↶ 撤回」。
+对一条插件启用后发送的用户消息做完整撤回，流程如下：
+
+1. 鼠标悬停该消息（含 agent 运行中插入的转向指令消息），复制按钮左侧出现「↶ 撤回」。
 2. 点击 → 确认面板展示将变更的文件清单（修改 / 恢复 / 删除），并可选撤回范围：「回退文件与对话」（默认）或「仅撤回对话」（文件保持当前状态）。
 3. 点「确认回退」（或「确认撤回对话」）→ 文件恢复到该消息发送前的状态（仅撤回对话时文件不动）；视图切到新会话（该消息及之后的对话移除），原会话归档、随时可找回。
 
@@ -124,17 +146,17 @@ dsh plugin --profile web remove dsh-recall-plugin
 
 ### 界面语言
 
-插件自绘的界面（撤回按钮与确认面板、toast 提示、设置卡片三张卡、快照管理树、最近错误）全部双语，由 `locale` 控制，在配置卡片的「界面」分组里下拉切换、保存即生效（设置页立刻切换；聊天页的会话文案在下次刷新页面后跟进）。
+插件自绘的界面（撤回按钮与确认面板、toast 提示、设置卡片三张卡、快照管理树、最近错误）全部双语，由 `locale` 控制：在配置卡片的「界面」分组下拉切换、保存即生效（设置页立刻切换；聊天页的会话文案在下次刷新页面后跟进）。
 
-两处 v1 明示限制：① 宿主官方设置表单自己渲染的字段说明（即 `Schema.description()` 文本）仍是中文，插件无法本地化——插件自绘的配置卡片不受影响；② 错误面板与「最近错误」里，万一出现「宿主侧带动态细节的错误」（如回退失败的救援结果、具体校验失败原因、原始异常文本），会原样展示宿主返回的中文/英文原文而不再套本地化短句——宁可中英混排也不吞掉排障需要的细节。
+两项明示限制：① 宿主官方设置表单自己渲染的字段说明（即 `Schema.description()` 文本）仍是中文，插件无法本地化——插件自绘的配置卡片不受影响；② 带动态细节的宿主侧错误（回退失败的救援结果、具体校验失败原因、原始异常文本）在错误面板与「最近错误」里原样展示宿主返回的中文/英文原文，不套本地化短句——宁可中英混排，也不吞掉排障需要的细节。
 
 ## 快照维护与清理
 
 插件自动控制磁盘占用，无需手动管理：
 
-- **定期 gc**：每 50 条快照或距上次 gc 24 小时（先到先触发，阈值可配），后台执行 `git gc` 把 loose 对象压成 pack。无损操作——所有快照照常可回退。节流凭据写在影子仓库内的 `gc.stamp`，重启 DSH 不会重置周期。
-- **条数上限与保留天数**：每工作区快照默认上限 500 条（超限清最旧）；也可按 `retentionDays` 设保留天数，两者独立触发、都可在配置卡片调整或关闭。
-- **会话删除联动清理**：会话被彻底删除（会话日志从磁盘消失）后，下一次维护会自动删除该会话的全部快照并释放空间。**归档不算删除**——撤回功能自己归档的原会话日志仍在，快照保留、随时可从归档找回。判断很保守：会话只是冷着（不内存里）不会误清；无法核实日志状态时宁可不清。
+- **定期 gc**：每 50 条快照或距上次 gc 24 小时（先到先触发，阈值可配），后台执行 `git gc` 把 loose 对象压成 pack——无损操作，所有快照照常可回退。节流凭据写在影子仓库内的 `gc.stamp`，重启 DSH 不会重置周期。
+- **条数上限与保留天数**：每工作区默认上限 500 条（超限清最旧），`retentionDays` 按保留天数清理；两者独立触发，都可在配置卡片调整或关闭。
+- **会话删除联动清理**：会话被彻底删除（会话日志从磁盘消失）后，下一次维护会自动删除该会话的全部快照并释放空间。**归档不算删除**——撤回功能归档的原会话日志仍在，快照保留、随时可从归档找回。判断很保守：会话只是冷着（不在内存）不会误清；无法核实日志状态时宁可不清。
 - **用户自定义排除**：打开「**设置 → 插件配置 → 撤回插件**」卡片（默认收起，点卡片头展开）即可可视化编辑快照排除项——输入路径或模式回车即加、常用模式（`dist/`、`*.log`、`.env` 等）一键追加、保存后下一次快照/回退立即生效，无需重启。也可以直接编辑 `$DSH_HOME/dsh-recall-snapshots/exclude.txt`（未设置时为 `~/.dsh/dsh-recall-snapshots/exclude.txt`；UTF-8）：一行一条 gitignore 风格 pattern（`#` 开头为注释），两种方式编辑的是同一份配置。例如：
 
   ```gitignore
@@ -145,7 +167,7 @@ dsh plugin --profile web remove dsh-recall-plugin
   ```
 
   对所有项目生效（home 不可写而降级到项目内存储时，该工作区有独立的排除配置，设置页会分卡片列出）。新增排除只影响之后的快照；**回退到更早的快照时，当时尚未排除的文件仍会被恢复**（回到当时的状态，这正是回退语义）。想彻底清掉已进快照的目录，可手动删除 home 下 `dsh-recall-snapshots/` 里对应项目的哈希目录。
-- **树形快照管理**：打开「**设置 → 插件配置 → 撤回插件 → 快照管理**」可看到树形列表——第一级工作区（文件夹名）、第二级会话（会话标题，撤回链聚成版本家族）、第三级快照（时间 + 消息内容摘要，悬停看完整内容）。支持搜索与「加载更多」；工作区和会话节点可展开/折叠；每一级右侧都有删除按钮，删除前会二次确认。删除工作区 = 清掉该工作区全部快照；删除会话 = 清掉该工作区内该会话的全部快照；删除叶子 = 只删那一条快照；顶部另有带确认的「全部删除」。
+- **树形快照管理**：打开「**设置 → 插件配置 → 撤回插件 → 快照管理**」可看到三级树——工作区（文件夹名）→ 会话（会话标题，撤回链聚成版本家族）→ 快照（时间 + 消息内容摘要，悬停看完整内容）。支持搜索与「加载更多」，工作区与会话节点可展开/折叠；每一级右侧都有删除按钮，删除前二次确认——删工作区 = 清掉该工作区全部快照，删会话 = 清掉该会话全部快照，删叶子 = 只删那一条；顶部另有带确认的「全部删除」。
 
 ## 工作原理
 
@@ -162,6 +184,63 @@ dsh plugin --profile web remove dsh-recall-plugin
 
 - 存储目录里每个文件（索引、撤回链、格式标记、意图记录等）的格式与版本兼容约定见 [docs/format.md](docs/format.md)。
 
+## 事件契约（供同宿主插件监听）
+
+撤回到达终态时，插件经 cordis 事件广播两个公开事件（2.4.8+），同宿主任意插件可直接监听——例如长时记忆插件据此清理「被撤回回合」写入的记忆：
+
+```js
+// 同宿主插件内
+ctx.on('dsh-recall/complete', (e) => {
+  if (e.chatReverted) memory.purgeTurn(e.root, e.sessionId, e.cutSeq)
+})
+ctx.on('dsh-recall/failed', (e) => {
+  if (e.stage === 'fork') log.warn('文件已回退但对话未回退', e)
+})
+```
+
+`dsh-recall/complete`——撤回成功终态：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `version` | `1` | 契约版本（演进规则见下） |
+| `sessionId` | `string` | 被撤回的原会话 |
+| `childSessionId` | `string \| null` | fork 出的新会话；纯文件回退时为 `null` |
+| `scope` | `'both' \| 'session-only'` | 撤回范围 |
+| `cutSeq` | `number \| null` | 对话回退切点；该消息是会话首条时为 `null` |
+| `messageId` | `string` | 被撤回消息 ID（快照主键） |
+| `root` | `string \| null` | 工作区根路径；host 解析失败为 `null` |
+| `count` | `number` | 回退文件数（`session-only` 恒 `0`） |
+| `chatReverted` | `boolean` | 对话是否真的回退（下游清理判据，见下） |
+| `archiveRequested` | `boolean` | 原会话归档是否已发起（fire-and-forget，不代表已落定） |
+| `time` | `number` | host 收到上报的时间（ms） |
+
+`dsh-recall/failed`——撤回失败终态：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `version` | `1` | 契约版本 |
+| `stage` | `'execute' \| 'fork'` | 失败阶段：文件回退被拒/异常，或文件已回退但对话回退失败 |
+| `sessionId` | `string \| null` | 被撤回的原会话 |
+| `messageId` | `string` | 被撤回消息 ID |
+| `scope` | `'both' \| 'session-only'` | 撤回范围 |
+| `cutSeq` | `number \| null` | client 已知的对话切点（可能尚未使用） |
+| `root` | `string \| null` | 工作区根路径；解析失败为 `null` |
+| `code` | `string?` | 仅 `stage='execute'`：透传 host 错误码（`AGENT_BUSY` / `NO_SNAPSHOT` 等） |
+| `error` | `string` | 错误描述 |
+| `time` | `number` | host 收到上报的时间（ms） |
+
+语义要点（下游必读）：
+
+- **只有终态才发事件**。撤回确认后「预览已过期、自动重新拉清单」（STALE）是中间态，不发任何事件；用户取消、面板关闭同样不发。
+- **fork 失败只发 `failed(stage:'fork')`，绝不发 `complete`**——此刻文件已回退但对话未回退，若发 `complete` 会导致下游误清该回合记忆。判断「对话确实回退了」请以 `complete` 事件的 `chatReverted` 为准（纯文件回退的 `complete` 是 `chatReverted:false`）。
+- `failed(stage:'execute')` 若来自执行异常（而非护栏拒绝），**文件是否已回退不确定**，下游宜保守处理。
+- 重复撤回/重试可能对同一 `(sessionId, messageId, cutSeq)` 三元组多次发事件，下游按三元组做幂等。
+- payload 不含消息正文，只有 ID / seq / 路径；事件只对同宿主插件可见。
+
+版本演进：首发即稳定公共契约（非 experimental）。新增字段（additive）走 minor；破坏性变更走 major 且 `version` 升 `2`，下游可按 `version` 分流。
+
+版本错位：旧版插件前端（<2.4.8）不上报、事件永不触发；新版前端 + 旧版 host（<2.4.8）时上报端点不存在，前端静默忽略，撤回功能不受任何影响。
+
 ## 本地开发（无需发布）
 
 把 profile 对本包的依赖改成 `link:` 指向克隆目录；DSH 加载的是工作区 `lib/` 构建产物（源码在 `src/`），改 `src/` 后先 `npm run build` 再重启 DSH 生效，无需复制或发布：
@@ -180,8 +259,8 @@ pnpm install
 
 ### 测试
 
-- `npm test`：纯逻辑单测（vitest，37 个文件 476 例，无 DSH 依赖，CI 与本地同跑）——配置解析、快照解析器、救援编排、错误分类、磁盘格式守卫、操作意图 journal、i18n 词典与 key 漏配扫描、脚本模板同名导出契约、执行通道双分支与失败分级、settings 双代桥接、客户端纯函数、发布包内容布局、快照索引持久化、存储上限与保留天数等；
-- `npm run test:client`：client 组件测试（vitest + jsdom，6 个文件 82 例，CI 同跑）——撤回节点主链（preview→execute→fork→回填）、快照管理树与删除流、配置/排除卡片错误路径、logger 开关矩阵、zh/en 双语渲染链；断言只锁行为与结构（className / aria / 请求载荷），不锁文案字面量；
+- `npm test`：纯逻辑单测（vitest，39 个文件 497 例，无 DSH 依赖，CI 与本地同跑）——配置解析、快照解析器、救援编排、错误分类、磁盘格式守卫、操作意图 journal、撤回终态事件上报组装、i18n 词典与 key 漏配扫描、脚本模板同名导出契约、执行通道双分支与失败分级、settings 双代桥接、客户端纯函数、发布包内容布局、快照索引持久化、存储上限与保留天数等；
+- `npm run test:client`：client 组件测试（vitest + jsdom，6 个文件 90 例，CI 同跑）——撤回节点主链（preview→execute→fork→回填）与终态事件上报、快照管理树与删除流、配置/排除卡片错误路径、logger 开关矩阵、zh/en 双语渲染链；断言只锁行为与结构（className / aria / 请求载荷），不锁文案字面量；
 - `npm run test:probe`：官方 API 字段探针（依赖本机 dsh 安装；dsh 升级后本地必跑）——钉住 `renderMessageImages`/`node`/`cwd`、`sessions.fork` 的 `atSeq`/`increaseTitle` 与切点锚点、`listSessions` 记录结构、`AgentRegistry`、shell 执行接缝（`execute`/`ShellExecution.result`）、settings 面（`SettingsForms`/profile 条目 id/volatile 门槛）与 `loader/volatile-update`/`Fiber.entry` 形状等字段，违反即红；
 - `npm run verify:host`：装配门禁（依赖本机 dsh 安装）——用真实 cordis 起插件跑两个 pass（旧面桩 + 只给新面的桩），断言 inject 声明、端点注册、Config schema、卸载清理与 settings 面分派，装配回归发版前即可拦截；
 - `npm run build`：host+client 全量打包（改任何 `src/` 后必跑）；`npm run check:dsh`：dsh 版本巡检（发布前）。

package/lib/client.js

@@ -820,6 +820,33 @@
       return "/api/recall/" + name;
     }
   }
+  function buildRecallNotify(base, o) {
+    if (o.outcome === "complete") {
+      return {
+        status: "complete",
+        sessionId: base.sessionId,
+        messageId: base.messageId,
+        scope: base.scope,
+        cutSeq: o.cutSeq,
+        childSessionId: o.childSessionId,
+        count: o.count,
+        chatReverted: o.chatReverted,
+        archiveRequested: o.archiveRequested
+      };
+    }
+    const stage = o.outcome === "fork-failed" ? "fork" : "execute";
+    const code = o.outcome === "execute-rejected" && typeof o.code === "string" && o.code ? o.code : void 0;
+    return {
+      status: "failed",
+      stage,
+      sessionId: base.sessionId,
+      messageId: base.messageId,
+      scope: base.scope,
+      cutSeq: o.cutSeq,
+      ...code ? { code } : {},
+      error: typeof o.error === "string" && o.error ? o.error : String(o.error || "recall failed")
+    };
+  }
   function useAutoDismissMessage(React, state, setState) {
     React.useEffect(() => {
       if (!state.message || state.error || state.busy) return;
@@ -1432,6 +1459,7 @@
         if (recall.stage !== "confirm") return;
         const changes = recall.changes || [];
         const previewCut = typeof recall.cutSeq === "number" ? recall.cutSeq : null;
+        const notifyBase = { sessionId: String(sessionId || ""), messageId, scope };
         const previewTotal = typeof recall.total === "number" ? recall.total : changes.length;
         const attachmentFiles = pluginConfig.refillDraft && attachmentRefs.length > 0 && sessionId ? preloadAttachmentFiles(sessionId, attachmentRefs) : null;
         setRecall({ stage: "executing", changes });
@@ -1458,12 +1486,20 @@
               });
               return;
             }
+            api("notify", buildRecallNotify(notifyBase, {
+              outcome: "execute-rejected",
+              cutSeq: previewCut,
+              code: res && typeof res.code === "string" ? res.code : void 0,
+              error: messageFor(res, "")
+            })).catch(() => {
+            });
             setRecall({ stage: "error", message: messageFor(res, t("fallback.rollback")) });
             return;
           }
           const cutSeq = typeof res.cutSeq === "number" ? res.cutSeq : previewCut;
           let chatReverted = false;
           let chatError = "";
+          let archiveRequested = false;
           let fillTarget = sessionId;
           if (cutSeq !== null && sessionsSvc && typeof sessionsSvc.fork === "function") {
             try {
@@ -1477,15 +1513,20 @@
                 api("lineage-record", { childId, parentId: sessionId }).catch(() => {
                 });
                 if (pluginConfig.archiveOriginal && workspacesSvc && typeof workspacesSvc.archiveSession === "function") {
+                  archiveRequested = true;
                   workspacesSvc.archiveSession(sessionId, { stopActivity: true }).catch((error) => {
                     recallNodeLog.warn("archive original session failed:", error);
                   });
                 }
               } else {
                 chatError = t("recall.chat.noChild");
+                api("notify", buildRecallNotify(notifyBase, { outcome: "fork-failed", cutSeq, error: chatError })).catch(() => {
+                });
               }
             } catch (error) {
               chatError = String(error);
+              api("notify", buildRecallNotify(notifyBase, { outcome: "fork-failed", cutSeq, error: chatError })).catch(() => {
+              });
             }
           }
           if (pluginConfig.refillDraft) {
@@ -1494,8 +1535,21 @@
           }
           setHasSnapshot(false);
           setRecall({ stage: "done", count: typeof res.count === "number" ? res.count : changes.length, chatReverted, chatError });
+          if (chatError === "") {
+            api("notify", buildRecallNotify(notifyBase, {
+              outcome: "complete",
+              cutSeq,
+              childSessionId: chatReverted ? String(fillTarget || "") || null : null,
+              count: typeof res.count === "number" ? res.count : changes.length,
+              chatReverted,
+              archiveRequested
+            })).catch(() => {
+            });
+          }
         }).catch((error) => {
           setRecall({ stage: "error", message: String(error) });
+          api("notify", buildRecallNotify(notifyBase, { outcome: "execute-threw", cutSeq: previewCut, error: String(error) })).catch(() => {
+          });
         });
       };
       const closePanel = () => {

package/lib/index.js

@@ -267,7 +267,10 @@ function apply(ctx, config) {
     DEFAULTS,
     rescueRollback,
     intentJournal,
-    E
+    E,
+    // issue #19 撤回终态事件广播：闭包注入保持 ctx 不解构纪律，routes 域
+    // 不直接持有 ctx；单测可注入桩断言事件名与 payload
+    emitEvent: (event, payload) => ctx.emit(event, payload)
   };
   const endpoints = {
     ...createRoutesCore(deps),

package/lib/routes-core.js

@@ -1,8 +1,10 @@
 import { ENV_HINTS } from "./diagnostics.js";
 import { parseTreeId } from "./snapshots.js";
 import { buildArtifactRootSegment, buildRootNotice } from "./exclude-patterns.js";
+const RECALL_EVENT_COMPLETE_HOST = "dsh-recall/complete";
+const RECALL_EVENT_FAILED_HOST = "dsh-recall/failed";
 function createRoutesCore(deps) {
-  const { rt, snaps, state, cfg, supported, enqueue, agentBusy, rescueRollback, intentJournal, E } = deps;
+  const { rt, snaps, state, cfg, supported, enqueue, agentBusy, rescueRollback, intentJournal, emitEvent, E } = deps;
   return {
     "init": async (args) => {
       if (!supported) {
@@ -159,9 +161,73 @@ function createRoutesCore(deps) {
       if (!store) return { ok: false, code: E.RECALL_NO_STORE, message: "\u5FEB\u7167\u5B58\u50A8\u4E0D\u53EF\u7528" };
       await snaps.recordLineage(root, childId, parentId);
       return { ok: true };
+    },
+    // issue #19：client 撤回终态上报 → cordis 事件广播（dsh-recall/complete
+    // | dsh-recall/failed）。不进串行队列（零 git 操作）、不依赖 store——
+    // lineage-record 的 NO_STORE 早退在这里是缺陷（原会话已归档时解析不到
+    // store 会吞掉事件），端点只做 enrich 与转发。恒 { ok: true }：事件
+    // 发送失败不影响撤回主流程（client 侧 fire-and-forget，连响应都不等）。
+    "notify": async (args) => {
+      const status = args && args.status;
+      const sessionId = args && args.sessionId ? String(args.sessionId) : "";
+      const messageId = args && args.messageId ? String(args.messageId) : "";
+      if (status !== "complete" && status !== "failed" || !sessionId || !messageId) {
+        return { ok: false, code: E.RECALL_BAD_TYPE, message: "\u64A4\u56DE\u4E0A\u62A5\u7F3A\u5C11\u5FC5\u8981\u53C2\u6570" };
+      }
+      const scope = args && args.scope === "session-only" ? "session-only" : "both";
+      const cutSeq = args && typeof args.cutSeq === "number" ? args.cutSeq : null;
+      let root = null;
+      try {
+        root = await rt.resolveRoot(sessionId) || null;
+      } catch {
+        root = null;
+      }
+      let eventName;
+      let payload;
+      if (status === "complete") {
+        eventName = RECALL_EVENT_COMPLETE_HOST;
+        payload = {
+          version: 1,
+          sessionId,
+          childSessionId: args && args.childSessionId ? String(args.childSessionId) : null,
+          scope,
+          cutSeq,
+          messageId,
+          root,
+          count: args && typeof args.count === "number" ? args.count : 0,
+          chatReverted: Boolean(args && args.chatReverted),
+          archiveRequested: Boolean(args && args.archiveRequested),
+          time: Date.now()
+        };
+      } else {
+        eventName = RECALL_EVENT_FAILED_HOST;
+        const code = args && typeof args.code === "string" && args.code ? args.code : void 0;
+        payload = {
+          version: 1,
+          stage: args && args.stage === "fork" ? "fork" : "execute",
+          sessionId,
+          messageId,
+          scope,
+          cutSeq,
+          root,
+          ...code ? { code } : {},
+          error: args && typeof args.error === "string" && args.error ? args.error : "unknown recall failure",
+          time: Date.now()
+        };
+      }
+      queueMicrotask(() => {
+        try {
+          emitEvent(eventName, payload);
+        } catch (error) {
+          rt.recordError("recall event emit failed: " + String(error));
+        }
+      });
+      return { ok: true };
     }
   };
 }
 export {
+  RECALL_EVENT_COMPLETE_HOST,
+  RECALL_EVENT_FAILED_HOST,
   createRoutesCore
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-recall-plugin",
-  "version": "2.4.7",
+  "version": "2.4.8",
   "description": "在 DSH 中撤回自己发过的消息：工作区文件与对话历史一起回到那条消息发出之前，消息的文本与附件自动放回输入框，改完即可重发。文件走独立影子 git 快照（不碰项目自身的 git），对话走官方 sessions.fork，原会话归档可找回。",
   "icon": "assets/icon.svg",
   "type": "module",