dsh-rewind-plugin 0.5.0 → 0.6.1

package/README.en.md

@@ -11,7 +11,7 @@ Conversation rewind for DeepSeek Harness: **rewind the conversation to any earli
 A deliberately focused plugin with one job: **rewind to any user message, no matter how far back, in place** — and conveniently **restore the files it changed** along the way.
 
 - **Rewinding is time-travel** — the target message and everything after it (agent replies, tool calls) are withdrawn from the model context *and* the rendered transcript at once, with no new session and no window switch; the target's text is offered back in the composer so you can edit and re-send it — **truly seamless and convenient by design**.
-- **Lightweight workspace backup** — Claude Code-aligned behavior: only file-writing tools are tracked, a lightweight before-backup is **persisted on disk**, and your git repository is never touched or relied on. One lightweight plugin gives you a **complete** agentic rewind capability.
+- **Lightweight workspace backup** — Claude Code-aligned behavior: tracks files edited by the write-class tools, and external changes to **already-tracked** files are restorable too. Selective tracking, before-write backup, store only on change. One lightweight plugin gives you a **complete** agentic rewind capability.
 - **Privacy-first** — the plugin never deletes or rewrites the session log (append-only) and never actually deletes any of your conversation; file restores stay inside the plugin's own backup directory. Full security model: [SECURITY.md](SECURITY.md).
 - **A complete test system** — unit, probe, and end-to-end host verification, covering compatibility probing, log replay, resume, cross-restart and other scenarios; maintained continuously as the harness evolves to ensure feature stability.
 
@@ -40,7 +40,7 @@ dsh plugin --profile web add dsh-rewind-plugin
 
 ## Usage
 
-1. Find the user message you want to rewind to in the conversation, or type `/rewind` to open the candidate picker.
+1. Find the user message you want to rewind to in the conversation, or type `/rewind` (or its alias `/undo`) to open the candidate picker.
 2. **Select it.** A small popover offers the two modes ("conversation and code" is only shown when there are restorable changes after the target).
 3. The rewind takes effect immediately: the conversation returns to how it looked at the target message, and the withdrawn message's text is filled back into the composer — edit and re-send.
 
@@ -56,6 +56,21 @@ dsh plugin --profile web add dsh-rewind-plugin
 
 </details>
 
+## Snapshot management
+
+Snapshots (the before-write backups) are stored under `<dsh home>/rewind-snapshots/`
+(`~/.dsh/rewind-snapshots/` when `$DSH_HOME` is unset). For the **same session**,
+the plugin deduplicates snapshots by content (an unchanged file is stored as a link)
+and keeps the newest 100 anchor groups. **Deleting that directory manually** only
+clears the file backups (chat rewinds are unaffected) and the plugin rebuilds them
+automatically.
+
+A **global auto-cleanup** (off by default) removes the snapshot directories of
+**long-inactive** sessions, leaving the active session and chat log untouched. Use
+`/snapshot-auto-cleanup` to **view, configure, and run** it; the settings live in
+`<dsh home>/snapshot-cleanup.json` and the last-sweep time in
+`<dsh home>/snapshot-cleanup-last-sweep.json`. See: [Snapshot cleanup](docs/snapshot-auto-cleanup.md).
+
 ## Why it stands out
 
 Compared with the common approaches, here is the trade-off this plugin makes on "rewind":
@@ -140,7 +155,7 @@ withdrew should consume the stable, locale-independent helpers exported from
 
 ## Security
 
-This plugin only appends rewind-marker events to the session log; it never deletes or rewrites logged history. Workspace files are written only when you choose "conversation and code"; backups and restores stay under `~/.dsh/rewind-snapshots/`. It never touches your git repository, makes no network requests, and accesses no credentials. Delete `~/.dsh/rewind-snapshots/` to wipe file backups only (chat rewinds are unaffected); the plugin rebuilds automatically. Full security model: [SECURITY.md](SECURITY.md).
+This plugin only appends rewind-marker events to the session log; it never deletes or rewrites logged history. Workspace files are written only when you choose "conversation and code"; backups and restores stay under `<dsh home>/rewind-snapshots/`. It never touches your git repository, makes no network requests, and accesses no credentials. Delete `~/.dsh/rewind-snapshots/` to wipe file backups only (chat rewinds are unaffected); the plugin rebuilds automatically. For sessions you've left inactive for a long time, a global auto-cleanup (off by default) can remove their snapshot directory in whole, leaving the active session and the chat log untouched. Full security model: [SECURITY.md](SECURITY.md).
 
 ## Development
 

package/README.md

@@ -11,7 +11,7 @@ DeepSeek Harness 插件：**一键就地回退对话到任意更早的用户消
 刻意聚焦、保持极简，只做一件事：**就地回退到任意远的用户消息**，还能**顺手还原改过的文件**。
 
 - **回退 = 时间回溯**——目标消息及其之后的全部内容（agent 回复、工具调用）同时从**模型上下文**和**渲染对话**中撤回，不新建会话、不切换窗口；目标消息文本会回填输入框，改完可重发。**在原理上就真正无感、便捷**。
-- **轻量工作区备份**——行为对齐 Claude Code：只跟踪写文件的工具，写前做轻量备份并**落盘持久化**，不依赖、也不触碰 git 仓库。一个轻型插件，即拥有**完备的智能体回退能力**。
+- **轻量工作区备份**——对齐 Claude Code：追踪写类工具编辑过的文件，**已跟踪文件的外部变更也能还原**。局部追踪、写前备份、不变不存。一个轻型插件，即拥有**完备的智能体回退能力**。
 - **信息安全优先**——插件从不删改会话日志（append-only），从不真正删除你的任何对话；文件还原限定在插件自己的备份目录。完整安全模型：[SECURITY.md](SECURITY.md)。
 - **完备测试系统**——单元、探针、端到端主机验证，覆盖兼容性探测、日志重放、续接、跨重启等场景；随 harness 升级持续维护，确保功能稳定。
 
@@ -40,7 +40,7 @@ dsh plugin --profile web add dsh-rewind-plugin
 
 ## 使用
 
-1. 在对话中找到要回退的那条用户消息，或输入 `/rewind` 打开候选列表选择。
+1. 在对话中找到要回退的那条用户消息，或输入 `/rewind`（或其别名 `/undo`）打开候选列表选择。
 2. **选中它。** 小浮层提供两种模式（「回退对话和代码」仅在目标之后有可还原的变更时显示）。
 3. 回退立即生效：对话回到目标消息当时的样子，被撤回消息的文本自动填入输入框——改完直接重发。
 
@@ -58,9 +58,9 @@ dsh plugin --profile web add dsh-rewind-plugin
 
 ## 存储管理
 
-快照（写前备份）存储于 `~/.dsh/rewind-snapshots/`。插件对**同一会话**的快照做内容去重（内容未变则存为链接）并保留最近 100 组锚点；**手动删除该目录**仅清除文件备份（对话回退不受影响），插件会自动重建。
+快照（写前备份）存储于 `<dsh home>/rewind-snapshots/`（未设 `$DSH_HOME` 时即 `~/.dsh/rewind-snapshots/`）。插件对**同一会话**的快照做内容去重（内容未变则存为链接）并保留最近 100 组锚点；**手动删除该目录**仅清除文件备份（对话回退不受影响），插件会自动重建。
 
-另提供**全局自动清理**（默认关闭）：把**长期不活跃**的会话快照整目录移除，不影响活动会话与对话日志。用 `/snapshot-auto-cleanup` 命令**查看与设置**，配置写入 `~/.dsh/snapshot-cleanup.json`。详见：[快照自动清理](docs/snapshot-auto-cleanup.zh.md)。
+另提供**全局自动清理**（默认关闭）：把**长期不活跃**的会话快照整目录移除，不影响活动会话与对话日志。用 `/snapshot-auto-cleanup` 命令**查看、设置和运行**，配置写入 `<dsh home>/snapshot-cleanup.json`；最近一次自动清扫的时间记录在 `<dsh home>/snapshot-cleanup-last-sweep.json`。详见：[快照自动清理](docs/snapshot-auto-cleanup.zh.md)。
 
 ## 本插件的优势
 

package/SECURITY.md

@@ -81,9 +81,11 @@ and is repaired offline (see `docs/compat/troubleshooting.md`).
 
 ## Filesystem containment
 
-- **Store root**: `~/.dsh/rewind-snapshots/` by default (`DSH_REWIND_SNAPSHOT_DIR`
-  overrides it). The store never overlaps the workspace; deleting it only
-  removes file backups and the store rebuilds from scratch.
+- **Store root**: `<harness home>/rewind-snapshots/` by default (resolved via
+  `resolveDshHome`, so `~/.dsh/...` when `DSH_HOME` is unset); the `snapshotDir`
+  config, then `DSH_REWIND_SNAPSHOT_DIR` env, override it. The store never
+  overlaps the workspace; deleting it only removes file backups and the store
+  rebuilds from scratch.
 - **Path sanitization**: session ids and call ids are scrubbed to
   `[a-zA-Z0-9._-]` (`safeSessionId` / `safeFileId`) before joining the store
   root; `.` and `..` bare values are replaced — hostile ids cannot traverse
@@ -136,6 +138,10 @@ and is repaired offline (see `docs/compat/troubleshooting.md`).
   same operating-system user: state files are created with the process
   default permissions (no special modes are set — a standard umask applies),
   and the host user remains trusted.
+- It does **not** exclude paths from the store: recording and restore mirror the
+  paths the model's file tools touched, so a sensitive file (e.g. `.env`) the
+  model may read or edit will be backed up and restorable. Keeping one out is
+  a **DSH model-permission** concern (a per-path deny), not a rewind feature.
 - It does **not** touch git (no refs, index, or worktree operations), makes
   **no network requests**, and does **not** access credentials.
 - It does **not** roll back whole-log state: telemetry, search, and `/export`

package/docs/README.md

@@ -11,6 +11,7 @@ index/navigation entry point.
 | `architecture.md` | Module layering, rewind/checkpoint pipelines, compatibility strategy, roadmap | maintainers |
 | `format.md` | Durable on-disk format spec (checkpoint entries + restore journals) | maintainers |
 | `harness-reference.md` | DeepSeek Harness interface reference + plugin source layout | maintainers |
+| `snapshot-auto-cleanup.md` | Global snapshot auto-cleanup policy and command (`.zh` mirror) | users / maintainers |
 | `contract/client-contract.md` | Rewind visibility contract for third-party DOM plugins (`.zh` mirror) | integrators |
 | `compat/audit.md` | Compatibility audit: verified surfaces, recorded findings, probe matrix | maintainers |
 | `compat/troubleshooting.md` | Known issues & repair steps (`.zh` mirror) | users / maintainers |

package/docs/compat/audit.md

@@ -1,137 +1,165 @@
-# 兼容性排查记录（compat-audit）
-
-> 排查方式：**测试即排查**。`tests/compat-invariants.test.ts`、`tests/compat-interop.test.ts`
-> 与 `scripts/verify-host.mjs` 中的探针，把插件的真实执行路径插入 DSH 各子系统的
-> **真实消费路径**（真实 `@deepseek-ai/*` 包），断言兼容性不变量。探针失败即发现，
-> 进入「修复 / 钉住 / 记录」闭环。
+# Compatibility audit (compat-audit)
+
+> Method: **the tests are the audit**. The probes in `tests/compat-invariants.test.ts`,
+> `tests/compat-interop.test.ts`, `tests/compat-gaps.test.ts` and
+> `scripts/verify-host.mjs` drive the plugin's real execution paths through the DSH
+> subsystems' **real consumer paths** (real `@deepseek-ai/*` packages) and assert
+> compatibility invariants. A probe failure is a finding; it enters the
+> fix/pin/record loop.
 >
-> 针对版本：npm `@deepseek-ai/*@0.1.1-rc.2`（与 `package-lock.json` 一致）；
-> 源码参考：`oss/deepseek-harness` 本地 fork。
+> Targeted version: npm `@deepseek-ai/*@0.1.1-rc.2` (matches `package-lock.json`);
+> source reference: the `oss/deepseek-harness` local fork.
 >
-> 版本适配说明：peerDependencies 采用 OR 并集（如 `^0.1.0-rc.6 || ^0.1.1-rc.2`），
-> 覆盖 DSH 已发布的 rc 元组系列。npm 的 prerelease 匹配规则要求候选与范围内比较器
-> **同 `[major, minor, patch]` 元组**，因此 DSH 每次发布新元组（如未来的 `0.1.2-rc.x`、
-> `0.2.x`）时需追加并集项；同元组内 rc 滚动（如 `0.1.1-rc.2 → rc.3`）无需动作。
-> 判断信号：`npm view @deepseek-ai/dsh version`；流程见 `scripts/check-dsh-version.mjs`。
-
-## 「完全适配」的可执行定义（不变量）
-
-| 不变量 | 含义 | 探针位置 |
+> Version alignment: `peerDependencies` use an OR-union (e.g.
+> `^0.1.0-rc.6 || ^0.1.1-rc.2`) covering each published rc tuple series. npm's
+> prerelease matching rules require a candidate to share the range comparator's
+> `[major, minor, patch]` tuple, so each new tuple series (e.g. a future
+> `0.1.2-rc.x`, `0.2.x`) requires appending a union member; rc rolling within a
+> tuple (`0.1.1-rc.2 → rc.3`) is a no-op. Signal: `npm view @deepseek-ai/dsh version`;
+> flow: `scripts/check-dsh-version.mjs`.
+>
+> Client channel (harness `0.1.2-alpha.1`, a **bundled pre-release — NOT published
+> to npm**): the plugin also reads the session chat when a DSH Desktop build ships
+> that version (`latest` on the registry is still `0.1.1-rc.2`; the alpha is only
+> in the bundled `app.asar.unpacked/node_modules/@deepseek-ai/*`). There
+> `uiConversation` exposes the chat as a per-session named `"chat"` view
+> (contributed by `dsh-client-ui-chat` through the `uiSession` slot hook) instead
+> of the session-face `chat` field. `src/client/hidden.ts` (`chatSnapshotOf`) reads
+> the session-face snapshot first (rc.2 path), then the `uiConversation` `"chat"`
+> view (alpha.1 path); both missing degrades to `undefined` (no targets, never a
+> crash). Peers are intentionally **NOT** extended for `0.1.2-alpha.1` because it is
+> not a registry version (see above); the OR-union stays
+> `^0.1.0-rc.6 || ^0.1.1-rc.2` and will gain the `0.1.2` tuple when the harness
+> publishes it. Pinned by `tests/chat-channel.test.ts` (channel precedence + the
+> alpha.1 snapshot shape) and `tests/client-dom.test.ts` (the button-target
+> pairing that consumes the chat).
+
+## Definition of "fully compatible" (invariants)
+
+| Invariant | Meaning | Probe location |
 |---|---|---|
-| I1 日志可重放 | rewind 后日志过 token-meter 重放、`Session.create`（resume preflight 同款校验）均不抛 | `compat-invariants` I1、`verify-host` 12/13 |
-| I2 surface 一致 | 切割后 surface 无重复节点、节点存在于日志、被撤目标不再回到 surface、`deriveMessages()` 合法 | `compat-invariants` I2 |
-| I3 step/turn 结构合法 | 客户端 turn-tail 顺序、step/start 唯一、step/end 与 assistant/message 均有配对 step/start、无幽灵 turn | `compat-invariants` I3、`helpers.assertTurnTailOrdering` |
-| I4 折叠服务安全 | stats / title / goal / projection 对含 marker 日志折叠不抛且值可预测 | `compat-invariants` I4 |
-| I5 compact 互操作 | 取消 turn 遗留的 tool-call 被 rewind 遮蔽后配对恢复平衡；跨 checkpoint 的 rewind 明确拒绝；rewind 后 compact 事务合法 | `compat-interop` I5、`verify-host` 12/14 |
-| I6 工具管线正确 | before-快照捕获/提交/恢复正确（既有 `snapshot.test.ts` + `verify-host` 4-8）；取消时序不悬挂 | `verify-host` 4-8、15 |
-| I7 客户端顺序合法 | 含工具 turn、rewind marker、幽灵 step 的日志满足客户端 builder 顺序 | `compat-interop` I7 |
-| I8 运行时安全 | rewind/compact 组合不留下悬空 step/turn 帧 | `verify-host` 15 |
-
-## 发现的兼容性问题
-
-### R-OPENSTEP：日志存在未闭合 step 时，rewind 会破坏 token-meter 重放（**harness 侧问题；插件守卫已尝试并回退**）
-
-> **根因（harness 侧）**：崩溃遗留的未闭合 step 会让 token-meter 重放拒绝任何后续
-> step 活动。DSH `0.1.1-rc.2` 已在加载时用 `interruptedTurnClosers`
-> （`dsh-session/repair`）自动闭合崩溃遗留的 step/turn/tool 边界——**崩溃路径已根治**。
+| I1 log replayability | A rewound log passes token-meter replay and `Session.create` (the resume-preflight validation) without throwing | `compat-invariants` I1, `verify-host` 12/13 |
+| I2 surface consistency | After a cut, the surface has no duplicate nodes, every node exists in the log, the withdrawn target never returns to the surface, and `deriveMessages()` is legal | `compat-invariants` I2 |
+| I3 step/turn structure | Client turn-tail ordering, unique `step/start`, every `step/end` and `assistant/message` has a paired `step/start`, no ghost turns | `compat-invariants` I3, `helpers.assertTurnTailOrdering` |
+| I4 fold-service safety | stats / title / goal / projection fold a marker-bearing log without throwing, with predictable values | `compat-invariants` I4 |
+| I5 compact interop | A tool-call orphaned by a cancelled turn is pair-balanced once shadowed by a rewind; a rewind across a compaction checkpoint is explicitly refused; a rewind-then-compact transaction stays legal | `compat-interop` I5, `verify-host` 12/14 |
+| I6 tool pipeline | before-snapshot capture/commit/restore is correct (existing `snapshot.test.ts` + `verify-host` 4–8); cancellation timing never hangs | `verify-host` 4–8, 15 |
+| I7 client ordering | A log carrying tool turns, rewind markers, and ghost steps satisfies the client builder ordering | `compat-interop` I7 |
+| I8 runtime safety | `rewind`/`compact` combinations never leave a dangling step/turn frame | `verify-host` 15 |
+
+## Verified-compatible surfaces (probes pass)
+
+- **token-meter replay** (marker + ghost-step frames + multiple rewinds + interleaved real turns + compact stacking).
+- **compaction transactions**: `toolPairingBalancedBefore/After` stays balanced after a marker cut; the real `/compact` command (`command-compact` + `compaction-basic`, stub summarizer) can land `compaction/start…end` on top of a rewind marker and stay replayable; `/compact` is a legal no-op on a small surface.
+- **resume replay**: `Session.create(id, events)` replays a rewind/compact-bearing log.
+- **session-stats**: a ghost-step frame adds one step but no phantom turn (reuses the turn number).
+- **session-title / goal fold**: a marker does not disturb `foldSessionTitle` / `foldGoal`.
+- **client ordering**: turn-tail ordering + `step/start` uniqueness hold for tool turns + marker logs.
+- **rewind across a compact checkpoint**: `RewindError('not-on-surface')` refuses cleanly, no crash.
+- **plan-mode**: `hasOpenTurn` pairs only `turn/start`/`turn/end`; a marker produces no `turn/start`, so a rewind during active plan is unaffected (static review confirmed).
+- **agent-loop cancellation**: `finally` guarantees step/turn closure; the rewind force-stop path leaves no dangling frame.
+
+## Known behavior boundaries (deterministic differences, non-crash, documented)
+
+- **session-stats / session-telemetry fold the full log**: post-rewind stats do **not** rewind — `turns`/`steps`/`llmMs` still include withdrawn content; telemetry reports the marker and ghost-step frames one-by-one (under the reused old turn). This is the intended "fold the full log" semantics, pinned by probe.
+- **token-meter usage anchor briefly reverts** (G3): after a rewind, the baseline falls back to the heuristic `estimated` until the next real-usage call restores it. Confirmed expected behavior (a marker inherently carries no usage); pinned by `compat-gaps` G3.
+- **Withdrawn content stays searchable/exportable**: session-query full-text and `/export` read the raw log; a rewind cuts only the surface, so withdrawn messages remain (declared in the README).
+- **Session title auto-regeneration**: the title derives from the surface, so an automatically-derived title may change after a rewind.
+- **Files written but uncommitted in a cancelled turn**: a `both` rewind cannot restore them (tool side-effect timing; same as Claude Code).
+- **Attachment files left after a message is shadowed**: attachment storage is not cleaned with the surface (`dsh-attachment-local` not installed, not automatically verified).
+
+## Upstream (harness) issues and the plugin's no-compensation stance
+
+The plugin treats these as harness-side defects it does not compensate for. Each entry records the harness issue, its current status, and the plugin's stance, so a future maintainer does not "fix the wrong direction."
+
+### RU-I18N: host-side locale preference is not reliably readable at command registration (harness-side structural timing defect; plugin reads once, never retries)
+
+- **Root cause (harness-side)**: the plugin resolves `activeLocale` in an
+  `ctx.inject(['settings'])` callback that reads `settings.get(settingsNamespace('locale')).preference`
+  **once, with no retry** (`src/index.ts`). `dsh-client-locale`'s host half
+  registers that `locale` settings section **through its own `ctx.inject(['settings'])`**
+  (`packages/client/locale/src/index.ts`). Both callbacks wait only on `settings` and are
+  independent of each other, so cordis makes **no ordering guarantee** between the
+  section registration and the plugin's read.
+- **Observed failure**: a probe confirmed that when the plugin's read runs, `settings.get('locale')`
+  returns `undefined` (the section is not yet registered), so `activeLocale` stays at the
+  default `'en'` and — because the read is one-shot — is never corrected. The result is that
+  **all host-side `t()` output (runtime messages and command descriptions alike) renders in
+  English**, regardless of the user's language preference.
+- **Not a user-config problem**: `settings.yaml` correctly carries `locale.preference: zh`;
+  reading it directly works. The defect is purely the host-side read racing the section
+  registration.
+- **Plugin stance**: no compensation. The plugin does not add a lazy re-read, a retry loop, or a
+  post-locale description re-registration as a workaround, because the guarantee belongs to the
+  harness (make the locale preference available before plugin registration, or support per-locale
+  command descriptions). The plugin's `t()` design is retained; localized host output is treated
+  as an upstream capability to be restored when the harness provides it. (Command descriptions
+  are English for **every** host command — system plugins also pass raw English `description`
+  strings, e.g. `/goal` — so this behavior is consistent with the ecosystem, not a plugin
+  deviation.)
+
+### R-OPENSTEP: an unclosed `step` in the log lets a rewind break token-meter replay (harness-side; plugin guard attempted and reverted)
+
+> **Root cause (harness-side)**: an unclosed step left by a crash makes token-meter replay
+> reject any later step activity. DSH `0.1.1-rc.2` now auto-closes crash-left step/turn/tool
+> boundaries at load via `interruptedTurnClosers` (`dsh-session`, consumed by
+> `session-persistence/src/coordinator.ts`) — **the crash path is fixed**.
 >
-> **插件守卫（已尝试并回退）**：曾实现 `hasOpenStep` + `planRewind` 前置拒绝
-> （`open-step`），但在**真实会话日志上产生误判**（正常回退被拒、GUI 验证功能缺失），
-> 已 revert（`177ec14`）。结论：**插件不设守卫**，接受残余风险（运行中第三方插件
-> 产生未闭合 step 时，rewind 可能破坏 /compact——该日志本身已异常，继续对话同样触发）。
-> 根治方向在 harness（token-meter 对未闭合 step 的恢复），不在插件。
+> **Plugin guard (attempted and reverted)**: a `hasOpenStep` + `planRewind` pre-refusal was
+> implemented (`open-step`) but misjudged on **real session logs** (normal rewinds refused, GUI
+> verification broken), and was reverted (`177ec14`). Conclusion: **the plugin sets no guard**,
+> accepting residual risk (an unclosed step produced by a third-party plugin can break
+> `/compact` — that log is already abnormal, and continuing the conversation triggers the same).
+> The fix direction is in the harness (token-meter recovery for unclosed steps), not the plugin.
 
-#### 未闭合 `step/start` 的具体触发情况（源码确认）
+#### Concrete `step/start` trigger paths (source-confirmed)
 
-全仓**只有一处** append `step/start`：`packages/core/agent-loop/src/agent.ts:279`（官方包内
-无其他生产者；`session/end-seed` 等修复只做 torn-write 截断，不处理逻辑未闭合）。
+The tree has exactly **one** `append('step/start')` producer: `packages/core/agent-loop/src/agent.ts:279`
+(no other producer inside the official packages; `session/end-seed` etc. only truncate torn writes,
+not logically-unclosed steps).
 
-| # | 触发路径 | 现实性 | 依据 |
+| # | Trigger path | Plausibility | Basis |
 |---|---|---|---|
-| P1 | **进程非优雅终止**：`step/start` 经 write-behind 批量落盘（`session-persistence/src/write-behind.ts`，`maxDelayMs` 后写一批）→ step 执行中（LLM 流式/工具，秒级到分钟级）→ SIGKILL / OOM-kill / 断电 / WSL 强关 → `step/end`（在 `finally`，进程活着才执行）未落盘 | **最现实** | `agent.ts:292` finally；write-behind 批量；torn-write 修复只截断写一半的行 |
-| P2 | **第三方插件 bug**：官方包只有 agent-loop 一个生产者，但外部插件可任意 `session.append('step/start', …)` 不闭合 | 可能 | 公开 `Session.append` |
-| P3 | **手工编辑会话文件**：改 `~/.dsh/…/session.jsonl[.zstd]`（zstd 需解压/重压；plaintext 配置可直接改） | 可能但费事 | `persistence-jsonl/format.ts`（`JsonlCompression = 'zstd' \| 'none'`） |
-| P4 | **append 自身故障**：`finally` 里 `append('step/end')` 抛错（payload 是纯数字，几乎不可能） | 理论 | `agent.ts:292` |
-
-**放大机制（rewind 不是唯一触发者）**：崩溃后 resume，agent-loop `turn()` 直接
-`phase.turn + 1` 开新 turn（`agent.ts:251-255`），**不闭合遗留 step**——所以「继续对话」
-（新 `step/start`）同样踩中 token-meter 校验。影响范围精确界定：
-
-- **对话本身不受影响**（请求路径不调用 `tokenMeter.measure`，全仓仅 compaction-basic 调用）；
-- **手动 `/compact` 永久报错**（`compactNow` 首步 `measure()` 抛原始错误）；
-- **自动压缩永久静默失效**（`agent/pre-step` 钩子 catch 后仅 warn，对话继续）；
-- **rewind 的角色**：若用户先 rewind（而非继续对话），幽灵 step/start 成为第一个踩中者，
-  且插件无防御性检测——把「局部异常日志」升级为「用户可感知的 /compact 失效」。
-
-### G3（已确认：合理行为，非缺陷）：rewind 让 token-meter 的 usage 锚点短暂失效
-
-- **机制**：rewind 的 marker 是日志最后一条 `assistant/message` 且无 `usage`，token-meter
-  的 `_sync` 重放以它收尾，把 `MeasurementAnchor.baseline` 从 provider 实测 `usage` 覆盖为
-  启发式 `estimated`——直到下一条带 usage 的真实消息才恢复（探针验证了完整链条：
-  `usage → rewind → estimated → 真实 turn → usage`）。
-- **定性（已确认）**：marker 语义上就是空消息，不携带 usage 是正确的；锚点短暂退回估算
-  是该语义的自然结果，且短暂、自愈、不破坏功能。**属于预期行为，不修复**。
-- **探针**：`tests/compat-gaps.test.ts` → `G3`（钉住该行为，防止未来 harness 变更改变它）。
-
-## 已验证兼容的面（探针通过）
-
-- **token-meter 重放**（含 marker + 幽灵 step 帧 + 多次 rewind + 交错真实 turn + compact 叠加）。
-- **compaction 事务**：`toolPairingBalancedBefore/After` 对 marker 切割后的 surface 恒平衡；
-  真实 `/compact` 命令（`command-compact` + `compaction-basic`，stub summarizer）可在 rewind
-  marker 之上落地 `compaction/start…end` 并保持可重放；小 surface 时 `/compact` 合法 no-op。
-- **resume 重放**：`Session.create(id, events)` 对含 rewind/compact 的日志重放通过。
-- **session-stats**：ghost step 帧只 +1 step、不新增 phantom turn（复用 turn 号）。
-- **session-title / goal fold**：marker 不干扰 `foldSessionTitle` / `foldGoal`。
-- **客户端顺序**：turn-tail ordering + step/start 唯一性对工具 turn + marker 日志成立。
-- **跨 compact checkpoint 的 rewind**：`RewindError('not-on-surface')` 明确拒绝，不崩溃。
-- **plan-mode**：`hasOpenTurn` 只配对 `turn/start`/`turn/end`，marker 不产生 `turn/start`，
-  激活 plan 期间 rewind 无影响（静态审查确认）。
-- **agent-loop 取消**：`finally` 保证 step/turn 闭合，rewind 的 force-stop 路径不悬挂帧。
-
-## 已知边界（行为差异，非崩溃，文档化）
-
-- **session-stats / session-telemetry 折叠完整日志**：rewind 后统计**不回退**——`turns` /
-  `steps` / `llmMs` 仍含被撤内容；telemetry 逐条上报 marker 与幽灵 step 帧（归入被复用
-  的旧 turn）。这是「折叠完整日志」的预期语义，探针钉住该行为。
-- **token-meter usage 锚点短暂失效**（G3）：rewind 后 baseline 退回启发式 `estimated`，
-  下一条真实 usage 调用恢复（探针钉住）。
-- **被撤内容仍可搜索、可导出**：session-query 全文搜索与 `/export` 基于原始日志，
-  rewind 只切 surface，被撤消息仍在其中（README 已声明）。
-- **session-title 自动重生成**：标题由 surface 派生，rewind 后自动标题可能变化。
-- **取消 turn 中已写盘但未提交快照的文件**：rewind both 无法恢复（工具副作用时序，
-  Claude Code 同限制）。
-- **附件消息被遮蔽后文件残留**：attachment 存储不随 surface 清理（`dsh-attachment-local`
-  未装，未自动化验证）。
-
-## 未覆盖边界（需要额外端到端层，不阻塞）
-
-- 真实 LLM 流式与自动标题生成（L2 stub 化）。
-- 真实 SQLite 索引生命周期（`dsh-session-query-sqlite` 未安装、含原生依赖）。
-- 浏览器端实际渲染 replay（客户端契约已由 `client-contract.test.ts` 覆盖逻辑层）。
-- 真实 JSONL 持久化往返（`dsh-session-persistence-jsonl` 依赖 native `koffi`；往返验证的是
-  harness 自身 zstd/JSON 编解码，插件不参与，价值/成本不划算，未安装）。
-- session-reference 的 `SessionReferenceResolver.prepare` 需完整 session-query 服务；其数据
-  基础（current-surface 投影）已由 G1 探针（`foldSurface` 转换）覆盖。
-- telemetry 管道（`dsh-session-telemetry-otel`）与附件 provider（`dsh-attachment-local`）。
-- 运行中的 workflow/jobs 被 rewind 取消：工具契约要求 observe `exec.signal` 并 settle
-  （`packages/core/tools/src/index.ts`），rewind 触发的是 harness 标准取消，非插件特有——
-  静态确认，未实测真实 workflow。
-
-## 排查矩阵（子系统 × 不变量）
-
-| DSH 子系统 | I1 | I2 | I3 | I4 | I5 | I6 | I7 | I8 |
+| P1 | **Abnormal process termination**: `step/start` is batched to disk (write-behind, `maxDelayMs` per batch) → the step is mid-execution (LLM stream/tool, seconds to minutes) → SIGKILL / OOM-kill / power loss / WSL hard-close → `step/end` (in `finally`, only runs while the process is alive) is never persisted | **Most realistic** | `agent.ts:292` finally; write-behind batching; torn-write fix truncates only a half-written line |
+| P2 | **Third-party plugin bug**: only the official agent-loop produces one, but external plugins may `session.append('step/start', …)` and never close it | possible | public `Session.append` |
+| P3 | **Manual session-file editing**: edit `~/.dsh/…/session.jsonl[.zstd]` (zstd needs decompress/recompress; plaintext config edits directly) | possible but laborious | `persistence-jsonl/format.ts` (`JsonlCompression = 'zstd' \| 'none'`) |
+| P4 | **append itself failing**: `append('step/end')` in `finally` throws (payload is plain numbers, nearly impossible) | theoretical | `agent.ts:292` |
+
+**Amplifier (rewind is not the only trigger)**: after a crash resume, agent-loop `turn()` opens a
+new turn at `phase.turn + 1` (`agent.ts:251-255`) **without closing the leftover step** — so
+"continue the conversation" (a new `step/start`) trips the same token-meter check. Scope:
+
+- **The conversation itself is unaffected** (the request path does not call `tokenMeter.measure`; only compaction-basic does tree-wide).
+- **Manual `/compact` fails permanently** (`compactNow`'s first `measure()` throws the raw error).
+- **Automatic compaction silently stays disabled** (the `agent/pre-step` hook catches and warns; the conversation continues).
+- **rewind's role**: if the user rewinds first (rather than continuing), the ghost `step/start` becomes the first trip-wire, and the plugin has no defensive detection — upgrading a "locally abnormal log" into a "user-visible `/compact` failure."
+
+## Uncovered boundaries (need an additional e2e layer; non-blocking)
+
+- Real LLM streaming and auto title generation (L2 stubbed).
+- Real SQLite index lifetime (`dsh-session-query-sqlite` not installed; native deps).
+- Actual browser rendering replay (the client contract's logic layer is covered by `client-contract.test.ts`).
+- Real JSONL persistence round-trip (`dsh-session-persistence-jsonl` depends on native `koffi`; the round-trip validates the harness's own zstd/JSON codec, the plugin is not party to it, not worth the cost, not installed).
+- `session-reference`'s `SessionReferenceResolver.prepare` needs a full session-query service; its data base (current-surface projection) is already covered by the G1 probe (`foldSurface`).
+- telemetry pipeline (`dsh-session-telemetry-otel`) and the attachment provider (`dsh-attachment-local`).
+- Running workflow/jobs cancelled by a rewind: the tool contract requires observing `exec.signal` and settling (`packages/core/tools/src/index.ts`); a rewind triggers the harness's standard cancel, not plugin-specific — statically confirmed, real workflows untested.
+
+## Audit matrix (subsystem × invariant)
+
+| DSH subsystem | I1 | I2 | I3 | I4 | I5 | I6 | I7 | I8 |
 |---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
-| 会话内核（append/surface/deriveMessages） | ✓ | ✓ | ✓ | — | ✓ | — | ✓ | ✓ |
+| Session core (append/surface/deriveMessages) | ✓ | ✓ | ✓ | — | ✓ | — | ✓ | ✓ |
 | token-meter | ✓ | — | ✓ | — | ✓ | — | — | — |
-| compaction（事务/命令/tool-pairing） | ✓ | — | — | — | ✓ | — | — | ✓ |
+| compaction (transaction/command/tool-pairing) | ✓ | — | — | — | ✓ | — | — | ✓ |
 | session-stats / projection | — | — | ✓ | ✓ | — | — | — | — |
 | session-title | — | — | — | ✓ | — | — | — | — |
 | goal | — | — | — | ✓ | — | — | — | — |
-| resume / session-query 重放 | ✓ | — | ✓ | — | — | — | ✓ | — |
-| 工具管线（快照/恢复） | — | — | — | — | — | ✓ | — | ✓ |
-| 客户端顺序 | — | — | ✓ | — | — | — | ✓ | — |
-| plan-mode | — | — | — | — | — | — | — | ✓（静态） |
-
-✓ = 探针通过；— = 不适用。R-OPENSTEP 见上（harness 已修、插件不设守卫）。G3 见「已知边界」。
-缺口探针 `tests/compat-gaps.test.ts`：G1 surface 分类（`foldSurface` current/shadowed/log-only）
-与 G2 projection checkpoint 均验证通过；G3 钉住 token-meter baseline 行为差异。
+| resume / session-query replay | ✓ | — | ✓ | — | — | — | ✓ | — |
+| tool pipeline (snapshot/restore) | — | — | — | — | — | ✓ | — | ✓ |
+| client ordering | — | — | ✓ | — | — | — | ✓ | — |
+| plan-mode | — | — | — | — | — | — | — | ✓ (static) |
+
+✓ = probe passes; — = not applicable. RU-I18N and R-OPENSTEP are upstream issues the plugin
+does not compensate for (see above); G3 is a confirmed-non-defect behavior pinned in
+`compat-gaps.test.ts` (G1 surface classification via `foldSurface` and G2 projection checkpoint
+both pass).

package/docs/format.md

@@ -7,10 +7,11 @@ and this spec disagree, the code wins and this spec is a bug.
 
 ## State root
 
-The store root defaults to `~/.dsh/rewind-snapshots/` (the dsh data
-directory), overridable via the `DSH_REWIND_SNAPSHOT_DIR` environment
-variable. It is a sibling of the workspace, never a subtree of it. Deleting
-the root only removes file backups; the store rebuilds from scratch.
+The store root defaults to `<harness home>/rewind-snapshots/` — the dsh data
+directory (`~/.dsh/rewind-snapshots/` when `DSH_HOME` is unset) — overridable in
+order by the `snapshotDir` plugin config, then the `DSH_REWIND_SNAPSHOT_DIR`
+environment variable. It is a sibling of the workspace, never a subtree of it.
+Deleting the root only removes file backups; the store rebuilds from scratch.
 
 ```
 <root>/

package/docs/harness-reference.md

@@ -54,7 +54,7 @@ src/index.ts            host plugin: /rewind command + checkpoint pipeline (tool
 src/rewind.ts           pure planning: target resolution, surface range, candidate listing
 src/snapshot.ts         checkpoint store (disk before-backups, restore/preview, bounded prune)
 src/session-cwd.ts      session-cwd resolution (fs-tools rule)
-src/client/index.ts     client plugin: per-message ↶ button + manual /rewind guard
+src/client/index.ts     client plugin: /rewind command decoration + per-message ↶ button portals
 src/client/popover.ts   mode-selection popover (both-mode impact confirm)
 src/client/hidden.ts    withdrawn-span computation (hiddenSeqsOf), pure
 src/client/locales.ts   zh / en copy (LocaleNamespaceMap)

package/docs/release/release.md

@@ -38,6 +38,9 @@ npm version patch
 git push origin main --tags   # triggers .github/workflows/publish.yml
 ```
 
+- **Before bumping, manually confirm there is no newer DSH version the plugin
+  has not been verified against** (a pre-release can ship in DSH Desktop
+  without being on npm, e.g. `0.1.2-alpha.1`; see docs/compat/audit.md).
 - The workflow verifies the tag matches `package.json`, runs typecheck + tests +
   a full build + artifact verification, publishes with `--provenance`
   (Sigstore), and creates a GitHub Release. It is **idempotent** — an already
@@ -58,9 +61,11 @@ uses an OR-union covering every published rc tuple series
   (`0.1.1 → 0.1.2 → 0.2.x`); rc rolling within a tuple (`0.1.1-rc.2 → rc.3`)
   needs nothing. All `@deepseek-ai/*` packages release together;
   `npm view @deepseek-ai/dsh version` is the authoritative signal.
-- **Automatic detection**: `node scripts/check-dsh-version.mjs` compares the
-  latest npm version against the tuples the peers cover and reports whether an
-  extension is needed (exit 0 = nothing to do, exit 1 = update).
+- **Published-tuple check (optional)**: `node scripts/check-dsh-version.mjs`
+  compares the latest npm version against the tuples the peers cover (exit 0 =
+  nothing to do, exit 1 = update). It reads npm published versions only; a
+  newer-but-unpublished pre-release is a manual pre-release check — see the
+  "Before bumping" step above.
 - **Update steps**: append `|| ^<new-tuple>-rc.<n>` to every
   `@deepseek-ai/dsh-*` peer → bump devDependencies to the latest → `npm
   install` → `npm run check` → release.

package/docs/release/release.zh.md

@@ -37,6 +37,7 @@ npm version patch
 git push origin main --tags   # 触发 .github/workflows/publish.yml
 ```
 
+- **升版前手动确认**：确认无插件未针对其验证过的更新 DSH 版本（pre-release 可能只随 Desktop 捆绑、而不发到 npm，如 `0.1.2-alpha.1`；见 docs/compat/audit.md）。
 - workflow 校验 tag 与 `package.json` 版本一致，跑 typecheck + 测试 + 完整
   构建 + 产物验证，以 `--provenance`（Sigstore）发布并创建 GitHub Release。
   **幂等**——已发布的版本会跳过。
@@ -54,8 +55,9 @@ OR 并集覆盖 DSH 已发布的每个 rc 元组系列（如 `^0.1.0-rc.6 || ^0.
 - **何时需要更新**：仅当 DSH 发布新元组（`0.1.1 → 0.1.2 → 0.2.x`）时；
   同元组内 rc 滚动（`0.1.1-rc.2 → rc.3`）无需动作。DSH 所有包同版本发布，
   `npm view @deepseek-ai/dsh version` 即权威信号。
-- **自动检测**：`node scripts/check-dsh-version.mjs` 对比 npm 最新版本与
-  peer 覆盖的元组，输出是否需追加（exit 0 无需动作，exit 1 需要）。
+- **已发布元组检查（可选）**：`node scripts/check-dsh-version.mjs` 用 npm 最新版本
+  对比 peer 覆盖的元组（exit 0 无需动作，exit 1 需要）。它**只读 npm 已发布版本**；
+  更新的未发布 pre-release 走**手动发布前检查**——见上文"升版前手动确认"。
 - **更新步骤**：给每个 `@deepseek-ai/dsh-*` peer 追加 `|| ^<新元组>-rc.<n>`
   → devDependencies 同步升到最新 → `npm install` → `npm run check` → 发版。
 - **正式版后收敛**：DSH 发布 final 版本后，正式版不受 prerelease 元组规则