dsh-rewind-plugin 0.20.0-alpha.4 → 0.21.0

package/README.en.md

@@ -15,7 +15,7 @@ A deliberately focused plugin with one job: **rewind to any user message, no mat
 
 - **In-place rewind, no new session** — the target message and everything after it (replies, tool calls) are withdrawn from the model context *and* the rendered transcript, and the target's text is filled back into the composer for editing and re-sending. It all happens inside the original session: no new branch, no leftover copy.
 - **Conversation and files rewind together** — Claude Code-aligned behavior: files edited by the write tools are tracked and restored by the same rewind, and external changes to already-tracked files are restorable too. **Partial tracking, before-write backup, store only on change**, with no git dependency.
-- **Safety guarantees** — the session log only ever appends rewind markers and is never deleted or rewritten; file backup and restore are hardened; tests are comprehensive, and maintenance continues across DSH upgrades. Security model: [SECURITY.md](SECURITY.md).
+- **Safety guarantees** — the session log only ever appends rewind markers and is never deleted or rewritten; file backup and restore are hardened; tests are comprehensive, and maintenance continues across DSH upgrades. Security model: [docs/security-model.md](docs/security-model.md).
 
 ## Preview
 
@@ -34,19 +34,17 @@ Every user message carries a **↶ rewind** button in its action row. Clicking i
 
 ## Install
 
-Check your local DSH version, then find the matching plugin version in
-[Releases](https://github.com/SiriLee/dsh-rewind/releases).
-
 **Command line**:
 
 ```sh
-dsh plugin --profile <name> add dsh-rewind-plugin@<version>
+dsh plugin --profile <name> add dsh-rewind-plugin
 ```
 
-**Graphical interface**: the **Plugins** page in the sidebar → **Add plugin** → enter `dsh-rewind-plugin@<version>` → install → restart DSH.
+**Graphical interface**: the **Plugins** page in the sidebar → **Add plugin** → enter `dsh-rewind-plugin` → install → restart DSH.
+
+<img src="assets/screenshots/add-plugin.png" width="600" alt="Add plugin dialog: enter dsh-rewind-plugin in the field"><br>
 
-<img src="assets/screenshots/add-plugin.png" width="600" alt="Add plugin dialog: enter dsh-rewind-plugin@version in the field"><br>
-<sub>The screenshot is an example only — use the version that matches your DSH version.</sub>
+The default install is `latest`, which targets the latest stable DSH release. If you are on an older or alpha DSH version, find the matching plugin version on the [Releases](https://github.com/SiriLee/dsh-rewind/releases) page and install that version explicitly.
 
 > [!WARNING]
 > The npm name `dsh-rewind` belongs to another author's package — install with `dsh-rewind-plugin`.
@@ -130,21 +128,21 @@ The whole design rests on two principles, simple but deliberate: **the conversat
 
 ### 2. File restore: lightweight checkpointing, "before-write backup"
 
-The file half follows Claude Code's checkpoint semantics — **partial tracking + before-write backup, plus a re-scan of tracked files at each message**, not a whole-tree snapshot. This trade-off saves space, and it's actually more complete:
+The file half follows Claude Code's checkpoint semantics — **partial tracking + before-write backup, plus a re-scan of tracked files at each message**, not a whole-tree snapshot. This trade-off saves space while still covering external changes to tracked files:
 
 - **Before-write backup**: tracks only the write-class tools (`write`, `edit`) — backs up the original content before a write and records/tracks the files it touches; it never backs up the whole workspace, so it's lightweight; **a single file that is too large is not backed up**.
 - **External changes count too**: at every user-message boundary the plugin re-checks all tracked files — external changes such as a command run or a manual edit are recorded as well and restored by a later rewind. "Lightweight" but not "incomplete".
 - **Unchanged-not-recorded**: an entry is written only when something changed — at the message-boundary re-check, an unchanged file is never backed up (no record); at before-write time, when the new content matches the path's prior record, only a **link to it** (`ref`) is stored instead of a copy.
-- **Accurate restore**: backups are the sole standard, checked against the real disk — **only files that actually differ are touched**. Backups are stored byte for byte, so the restored result matches the backups exactly, with no "ghost impact". There is a limit, though: [File-rewind tracking boundary](docs/compat/tracking-boundary.md).
+- **Accurate restore**: backups are the sole standard, checked against the real disk — **only files that actually differ are touched**. Backups are stored byte for byte, so the restored result matches the backups exactly, with no "ghost impact". Coverage is bounded by design: [File-rewind tracking boundary](docs/compat/tracking-boundary.md).
 - **Safety and integrity**: paths are sanitized so nothing ever escapes the backup root; symlinks / hard links are skipped so one restore can't clobber another name of the same file; a per-file failure never aborts the pass; backups and the restore journal are written atomically and kept across restarts, so a half-applied restore after a crash can be continued or rolled back.
 
 > **Design highlight**: this checkpoint's light footprint comes from **recording only what was actually touched and really changed** — before-write backup makes it restorable, unchanged-not-recorded and content-as-link drop the repetition; only the files that differ are touched at restore time.
 
-## What it deliberately does NOT do
+## Scope and division of labour
 
-This plugin deliberately stays lightweight and focused on one thing — "conversation rewind". The following are **out of its scope**:
+This plugin deliberately stays lightweight and focused on one thing — "conversation rewind". The following are **out of its scope**, and each has a better owner (see [design boundaries](docs/boundaries.md)):
 
-- **Whole-tree / Git-level snapshots** — only write-class tool edits plus external changes to already-tracked files are backed up; files never touched by a tool are not restored. For a worktree-level full snapshot rollback, use a more specialized snapshot tool (git).
+- **Whole-tree / Git-level snapshots** — only write-class tool edits plus external changes to already-tracked files are backed up; files never touched by a tool are not restored. Workspace history — any file, any moment — belongs to Git; the agent already uses it, and the plugin does not rebuild that layer. For a worktree-level full snapshot rollback, use Git or the snapshot tool the project already uses.
 - **Subagent edits** — not tracked, and no rewind inside a subagent session (same as Claude Code): a subagent runs its own session, so its backups could never be restored by a rewind of the parent session, and none are kept for one.
 - **Fork / branch rewind** — DSH already provides this ("branch in new chat"); no need to reinvent the wheel.
 
@@ -158,19 +156,17 @@ This plugin deliberately stays lightweight and focused on one thing — "convers
 > This project and DeepSeek Harness are both in developer preview. Pin exact
 > versions in reproducible environments and review the behavior notes above.
 
-## Known issues
+## Known limitations
 
-1. **Exported logs are complete** — `/export` exports the whole session log (raw JSONL), **withdrawn content included**; this plugin cannot alter exports.
-2. **Lightweight file rewind has a cost** — in specific cases not all changes can be rewound. Consistent with Claude Code. See: [File-rewind tracking boundary](docs/compat/tracking-boundary.md).
-3. **Turn navigation keeps rewound turns** — the right-side turn navigation keeps an "unloaded" tick for each rewound turn, and hovering previews the withdrawn content. Only a display difference; no functional impact.
-4. **A far rewind may show a blank transcript** — when the target predates the loaded history, the conversation area goes blank; click **Load earlier** to page back until the history appears.
+1. **Turn navigation keeps rewound turns** — the right-side turn navigation keeps an "unloaded" tick for each rewound turn, and hovering previews the withdrawn content. Only a display difference; no functional impact.
+2. **A far rewind may show a blank transcript** — when the target predates the loaded history, the conversation area goes blank; click **Load earlier** to page back until the history appears.
 
 > [!NOTE]
 > Browser diagnostics are available; see [Browser diagnostics](docs/compat/diagnostics.md).
 
 ## Security
 
-This plugin only appends rewind-marker events to the session log; it never deletes or rewrites logged history. Workspace files are written only when you choose "conversation and files"; backups are stored under `<dsh home>/rewind-snapshots/`; restores draw only from those backups. It never touches your git repository, makes no network requests, and accesses no credentials. For sessions you've left inactive for a long time, a snapshot auto-cleanup (off by default) can remove their snapshot directory in whole, leaving the active session and the chat log untouched. Full security model: [SECURITY.md](SECURITY.md).
+This plugin only appends rewind-marker events to the session log; it never deletes or rewrites logged history. Workspace files are written only when you choose "conversation and files"; backups are stored under `<dsh home>/rewind-snapshots/`; restores draw only from those backups. It never touches your git repository, makes no network requests, and accesses no credentials. For sessions you've left inactive for a long time, a snapshot auto-cleanup (off by default) can remove their snapshot directory in whole, leaving the active session and the chat log untouched. Full security model: [docs/security-model.md](docs/security-model.md); to report a vulnerability, see [SECURITY.md](SECURITY.md).
 
 ## Development
 
@@ -185,7 +181,7 @@ node scripts/verify-host.mjs   # end-to-end verification of the built artifact
 
 `prepack` runs the full build, so `npm pack` / `npm publish` always ship a complete `lib/`. Install from npm or a packed tarball — a git checkout has no built `lib/`.
 
-Maintainers: the module map and harness interface reference live in [docs/harness-reference.md](docs/harness-reference.md).
+Maintainers: the source layout and architecture are in [docs/architecture.md](docs/architecture.md); the harness interface reference is in [docs/harness-reference.md](docs/harness-reference.md).
 
 Contributing guide: [CONTRIBUTING.md](CONTRIBUTING.md).
 

package/README.md

@@ -15,7 +15,7 @@ DeepSeek Harness 插件：**一键就地回退对话到任意更早的用户消
 
 - **就地消息回退**——目标消息及其之后的内容同时从**模型上下文**和**渲染对话**中撤回，目标消息文本自动回填输入框。始终在原会话内完成，不新建分支、不残留副本。
 - **轻量备份还原**——对齐 Claude Code：追踪写类工具编辑过的文件，回退时一并还原，已跟踪文件的外部变更也能还原。**局部追踪、写前备份、不变不存**，不依赖 git。
-- **安全保障**——会话日志仅追加回退标记，从不删改；文件备份与还原经安全加固；**完备测试**，随 DSH 升级长期维护。安全模型：[SECURITY.md](SECURITY.md)。
+- **安全保障**——会话日志仅追加回退标记，从不删改；文件备份与还原经安全加固；**完备测试**，随 DSH 升级长期维护。安全模型：[docs/security-model.md](docs/security-model.md)。
 
 ## 效果预览
 
@@ -34,18 +34,17 @@ DeepSeek Harness 插件：**一键就地回退对话到任意更早的用户消
 
 ## 安装
 
-确认本机 DSH 版本后，在 [Release](https://github.com/SiriLee/dsh-rewind/releases) 找到适配的插件版本。
-
 **命令行**：
 
 ```sh
-dsh plugin --profile <name> add dsh-rewind-plugin@<版本>
+dsh plugin --profile <name> add dsh-rewind-plugin
 ```
 
-**图形界面**：侧栏「插件」页 →「添加插件」→ 填 `dsh-rewind-plugin@<版本>` → 安装 → 重启 DSH。
+**图形界面**：侧栏「插件」页 →「添加插件」→ 填 `dsh-rewind-plugin` → 安装 → 重启 DSH。
+
+<img src="assets/screenshots/add-plugin.png" width="600" alt="「添加插件」弹窗：在输入框填入 dsh-rewind-plugin"><br>
 
-<img src="assets/screenshots/add-plugin.png" width="600" alt="「添加插件」弹窗：在输入框填入 dsh-rewind-plugin@版本号"><br>
-<sub>图片仅为示例，请以实际适配版本号为准。</sub>
+默认安装 `latest`，它适配 DSH 最新稳定版本。若使用的是旧版或内测版 DSH，请在 [Releases](https://github.com/SiriLee/dsh-rewind/releases) 页面找到适配的插件版本，并指定版本安装。
 
 > [!WARNING]
 > npm 上的 `dsh-rewind` 属于其他作者，请用 `dsh-rewind-plugin` 安装。
@@ -116,23 +115,23 @@ rm <dsh home>/snapshot-cleanup-last-sweep.json
 
 ### 2. 文件还原：轻量检查点，「写前备份」
 
-文件部分对齐 Claude Code 的检查点语义——**局部追踪、写前备份 + 每条消息重扫已跟踪文件**，而不是整树快照。这项取舍既省空间，又更完整：
+文件部分对齐 Claude Code 的检查点语义——**局部追踪、写前备份 + 每条消息重扫已跟踪文件**，而不是整树快照。这项取舍省空间，也让已跟踪文件的外部改动同样可还原：
 
 - **写前备份**：只追踪写类工具（`write`、`edit`），写前**备份原内容**，并**记录、追踪**被处理的文件——从不备份整个工作区，因此轻量；**单个文件过大时不备份**。
 - **外部变更也追**：每条用户消息边界，插件重新检查所有已跟踪文件——命令执行、手动修改等外部变更同样被记录，回退时一并还原。这让「轻量」却不「残缺」。
 - **不变不存**：记录只在有变化时发生——消息边界重扫时无变更的**不备份**（不留记录）；写前备份时若与前一条记录一致，只存指向它的链接（`ref`）而非复制内容。
-- **还原准确**：以备份为唯一标准，对照真实磁盘，只动真正不一致的文件；备份逐字节存储。还原结果与备份一致，无“幽灵影响”。但存在限制：[文件回退的追踪边界](docs/compat/tracking-boundary.zh.md)。
+- **还原准确**：以备份为唯一标准，对照真实磁盘，只动真正不一致的文件；备份逐字节存储。还原结果与备份一致，无“幽灵影响”。覆盖范围按设计限定：[文件回退的追踪边界](docs/compat/tracking-boundary.zh.md)。
 - **安全与完整性**：路径经安全化处理，绝不越出备份根目录；符号/硬链接跳过，避免透过一次还原误伤同名的另一份文件；单个文件失败绝不中止整轮还原；备份与还原日志均原子写落盘（跨重启仍在），断电或崩溃后的半还原可续做或回滚。
 
 > **设计点睛**：这套检查点的「轻」，来自**只记录被工具动过、且确实变化的文件**——写前备份保证可还原，不变不存与存链接压掉重复；还原时再对照真实磁盘，只动不一致的文件。
 
-## 明确不做的事
+## 范围与分工
 
-本插件刻意保持轻量、聚焦「对话回退」这一件事，以下场景**不属于它的职责**：
+本插件刻意保持轻量、聚焦「对话回退」这一件事，以下场景**不属于它的职责**，各自有更合适的归属（见[设计边界](docs/boundaries.zh.md)）：
 
-- **整树 / Git 级快照**——只跟踪写类工具编辑 + 已跟踪文件的外部改动，从未被工具碰过的文件不还原。需要工作树级的完整快照回退时，请交给更专业的快照工具（git）。
+- **整树 / Git 级快照**——只跟踪写类工具编辑 + 已跟踪文件的外部改动，从未被工具碰过的文件不还原。工作区历史（任意文件、任意时刻）归 Git；Agent 本来就在用 Git，插件不重复造这层。需要工作树级的完整快照回退时，请交给 Git 或项目自选的快照工具。
 - **子代理的编辑**——不追踪，子代理会话内也不提供回退（同 Claude Code）：子代理运行在自己的会话里，其备份无法由父会话的回退还原，因此也不会为子会话保留备份。
-- **fork / 分支回退**——DSH 已内置「在新对话中分支」，不重复造轮子。
+- **fork / 分支回退**——DSH 已内置「在新对话中分支」功能，不重复造轮子。
 
 ## 兼容性
 
@@ -144,19 +143,17 @@ rm <dsh home>/snapshot-cleanup-last-sweep.json
 > 本项目与 DeepSeek Harness 均处于开发者预览阶段。可复现环境请 pin 精确版本，
 > 并阅读上述行为说明。
 
-## 已知问题
+## 已知限制
 
-1. **导出的日志是完整内容**——`/export` 导出整个会话日志（原始 JSONL），包含**已撤回的内容**；本插件无法改动导出。
-2. **轻量文件回退存在代价**——特定情况可能无法回退所有修改。行为与 Claude Code 一致。详见：[文件回退的追踪边界](docs/compat/tracking-boundary.zh.md)。
-3. **轮次导航保留已回退轮次**——右侧轮次导航为已回退轮次保留「未加载」刻度，悬浮可预览已撤回内容。仅显示差异，无功能影响。
-4. **较远回退可能显示空白**——回退目标早于已加载的历史时，对话区会显示空白；需点击「加载更早」往前翻，才能看到历史对话。
+1. **轮次导航保留已回退轮次**——右侧轮次导航为已回退轮次保留「未加载」刻度，悬浮可预览已撤回内容。仅显示差异，无功能影响。
+2. **较远回退可能显示空白**——回退目标早于已加载的历史时，对话区会显示空白；需点击「加载更早」往前翻，才能看到历史对话。
 
 > [!NOTE]
 > 本插件提供浏览器端诊断输出；详见 [浏览器诊断](docs/compat/diagnostics.zh.md)。
 
 ## 安全
 
-本插件只向会话日志追加回退标记事件，从不删除或改写已记录的历史。工作区文件仅在「回退对话和文件」时被改写，备份存储于 `<dsh home>/rewind-snapshots/`；还原以备份为唯一来源。不触碰你的 git 仓库，无网络请求，不访问任何凭据。对**长期不活跃**的会话，另有默认关闭的快照自动清理可整目录移除其快照，不影响活动会话与对话日志。完整安全模型：[SECURITY.md](SECURITY.md)。
+本插件只向会话日志追加回退标记事件，从不删除或改写已记录的历史。工作区文件仅在「回退对话和文件」时被改写，备份存储于 `<dsh home>/rewind-snapshots/`；还原以备份为唯一来源。不触碰你的 git 仓库，无网络请求，不访问任何凭据。对**长期不活跃**的会话，另有默认关闭的快照自动清理可整目录移除其快照，不影响活动会话与对话日志。完整安全模型：[docs/security-model.md](docs/security-model.md)；漏洞报告政策见 [SECURITY.md](SECURITY.md)。
 
 ## 开发
 
@@ -171,7 +168,7 @@ node scripts/verify-host.mjs   # 端到端验证构建产物
 
 `prepack` 在打包前执行完整构建，所以 `npm pack` / `npm publish` 总会产出完整的 `lib/`。请从 npm 或打好的 tarball 安装——git 检出的源码里没有构建好的 `lib/`。
 
-维护者：模块地图与 harness 接口参考见 [docs/harness-reference.md](docs/harness-reference.md)
+维护者：源码布局与架构见 [docs/architecture.md](docs/architecture.md)，harness 接口参考见 [docs/harness-reference.md](docs/harness-reference.md)。
 
 贡献指南：[CONTRIBUTING.md](CONTRIBUTING.md)
 

package/SECURITY.md

@@ -1,206 +1,80 @@
-# Security model
-
-This document is the security model of **dsh-rewind** — how the plugin treats
-untrusted input, what it is allowed to mutate, and how it survives crashes.
-It is derived from the implementation (`src/index.ts`, `src/snapshot.ts`); if
-this document and the code ever disagree, the code wins and this document is
-a bug.
-
-## Trusted boundary
-
-The plugin runs in the DSH host process and therefore holds the host user's
-filesystem authority — it reads and writes files with plain `node:fs`. The
-following are treated as **untrusted inputs**:
-
-- **Model arguments** — the `file_path` field of `write` / `edit` tool calls
-  (it names the paths the checkpoint store records).
-- **Session log contents** — events are parsed structurally; a hostile or
-  malformed id must never escape the store root.
-- **Current worktree state** — restore planning reconciles against the live
-  disk, which may have been changed by anything.
-- **Concurrent external modifications** — a restore never assumes the disk
-  still matches its records.
-
-The DSH host (and its other plugins) is trusted; this plugin does not
-re-verify the host's own authority boundaries.
-
-## Mutation gates
-
-When `fileCheckpointingEnabled` is on, the plugin **automatically captures**
-before-backups of tracked mutations, but **never automatically applies** one.
-A workspace restore happens only through an explicit user-invoked
-`/rewind-plugin @<seq> both` (the per-message ↶ button or the command channel),
-and only when all of the following hold:
-
-1. **A validated target**: `planRewind` accepts only a `user/message` seq that
-   is currently on the session surface (`parseRewindTarget` → `RewindPlan`).
-2. **A fresh plan**: the plan is derived from the current `events` + `surface`
-   at execution time — never cached across events.
-3. **Committed backups exist**: every planned action comes from a committed
-   checkpoint entry anchored at or after the target.
-4. **Live-disk reconciliation**: `planRestore` compares each entry against the
-   current disk and plans only actions that would actually change it — an
-   already-matching state is a no-op (restores are idempotent).
-5. **Exclusive execution**: a per-session in-flight guard rejects concurrent
-   rewinds; a running turn is force-cancelled (`keepInbox`) and quiescence is
-   awaited before the surface is cut.
-6. **Session binding**: the restore reads/writes only the store of the rewound
-   session (paths are resolved display paths the session's own tools touched).
-
-**Concurrency scope**: the in-flight guard above only serializes concurrent
-*rewinds* of one session; it does not stop other processes from modifying the
-workspace. `planRestore` reconciles against the live disk at plan time, but
-there is no re-validation between planning and applying — a file changed by
-another process in that window is overwritten by the restore. The rescue state
-is captured at apply start, so `rollbackRestore` still returns the workspace
-to exactly the apply-start state, and per-file failures are reported rather
-than hidden.
-
-A failed gate fails closed: an invalid target, a missing store, an absent
-backup, or a cancelled invocation aborts the rewind with an error. A store
-written by a **newer** build is one of those gates: it is refused as a whole —
-no partial restore and no new entry written into it, and the automatic
-format-change clear below is skipped — while the conversation rewind itself
-still works. An explicit clear (`run --current --apply`) or the age-based sweep,
-being a user-directed deletion of whole session directories, is deliberately not
-version-gated.
-
-**Automatic store deletion**: two things delete session snapshots. The opt-in
-`snapshot-auto-cleanup` sweep (default off) removes the whole directories of
-**long-inactive** sessions, unrelated to restores. Separately, a session's
-snapshots are cleared automatically when the conversation log's session format
-has changed (a DSH upgrade), because those backups are anchored to message
-positions that no longer line up. Both stay confined to the store root, use
-`lstat` (so they never follow a symlink out of the root), the sweep never targets
-the active session, and neither touches the conversation log. When auto-cleanup
-is disabled (the default), only the format-change clear runs, and only for an
-affected session. The store-format guard runs before that clear, so a session
-whose store is **newer** than this build understands is not cleared by it (see
-`docs/format.md`).
-
-## Conversation integrity
-
-The session log is **append-only** — the plugin never deletes or rewrites
-recorded history. A rewind appends a single marker event (a `user/message` whose
-content is the constant `(empty message)` placeholder) whose `surfaceOp`
-replaces every surface node after the target. The raw log (audit trail, search,
-`/export`) is untouched — only the model-visible surface is cut, so the next
-request derives its context from the target onward. The marker's content is a
-constant, so it carries no untrusted text into the model context; the client
-hides the `[target, marker]` span from the rendered transcript.
-
-## Filesystem containment
-
-- **Store root**: `<dsh home>/rewind-snapshots/` by default (resolved via
-  `resolveDshHome`, so `$DSH_HOME` feeds the base and `~/.dsh` is the fallback);
-  the `snapshotDir` config overrides the whole path. The plugin reads no
-  environment variable of its own. Deleting the root 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
-  out of the root.
-- **Links and moved directories are refused**: two checks guard a tracked path.
-  (1) Planning skips a path whose last component is a symlink or a hard link
-  (`lstat().nlink > 1`) and reports it, never restoring it — a symlink would
-  redirect the write outside the checkpoint, and a hard link would clobber every
-  other name of the same inode (e.g. pnpm-installed files); a link swapped in
-  after planning is not re-checked. (2) At apply time, every record this build
-  writes — entry, link and
-  journal action — carries the `realpath` of the file's directory at commit time
-  (the location pin; best-effort, and absent on released-v1 data or a commit
-  whose parent could not be resolved), and a restore re-checks it before
-  touching the path, including a post-restart continue or rollback, which reads
-  the pin from the journal: a directory that no longer resolves there (a
-  repointed or moved ancestor) is refused and reported instead of writing
-  outside the recorded location, while data with no pin falls back to check (1)
-  alone. A parent chain that
-  is gone is still recreated (files whose directory was deleted are restorable),
-  but only while its nearest surviving ancestor resolves inside the pin. A
-  stable symlinked ancestor resolves identically on both sides, so a symlinked
-  workspace or temp root is never a false skip. This matches Claude Code's
-  checkpoint behavior since v2.1.216.
-- **Restores name only recorded paths**: the store contains resolved display
-  paths of the session's own write-class tool calls (plus boundary re-checks
-  over that same tracked set) — a restore can never write an arbitrary path.
-- **Path resolution rule**: relative paths resolve against the session's current
-  working directory, read from the same service the fs tools resolve through.
-- **Bounded backups**: `prune` keeps the newest 100 anchor groups per session
-  (`MAX_ANCHOR_GROUPS`), except groups a non-terminal restore journal still
-  references (pinned so the op can be finished), so backup accumulation stays
-  bounded by the cap plus the number of unresolved journals (the exact cap is
-  pinned in `docs/format.md`). Across sessions, the opt-in `pruneStale` sweep
-  removes whole **long-inactive** session directories (measured by the newest
-  member being idle past the configured `autoCleanupMaxAgeDays`); it uses
-  `lstat` (no symlink following), skips dot-prefixed temp files, and never
-  targets the active session (`keepActiveId`).
-
-## Crash safety
-
-- **Ordered commits**: a checkpoint commit places the before-sidecar (a raw
-  byte copy) before publishing the entry JSON, so a crash can leave an
-  unreferenced sidecar but never an entry whose bytes are missing. Every JSON
-  write (checkpoint entries, restore journals) goes to a sibling temp file and
-  is renamed over the target: a host crash mid-write can leave only an inert
-  `<target>.tmp` — never a readable half-written file — and readers never pick
-  up temp files.
-- **Journaled restores**: before mutating anything, the restore captures each
-  planned path's pre-restore ("rescue") state and persists an intent journal,
-  then marks each action done as it is applied. A crash at any point leaves
-  the journal on disk.
-- **Disk is truth**: an interrupted op keeps its journal on disk, and the store's
-  recovery API re-derives the true state from the real disk — `reconcileRestores`
-  reports which paths already match the goal (restored) and which are pending,
-  `continueRestore` finishes the op, `rollbackRestore` undoes it to the exact
-  pre-restore state, and a journal whose goal is already reached auto-heals to
-  its terminal state. The plugin never runs them on its own: an interrupted op
-  stays interrupted until an explicit caller resumes or undoes it.
-- **Fail-loud vs fail-soft**: a corrupt **journal** is reported
-  `recovery-required` — never silently dropped (dropping it would erase the
-  interrupted restore's recovery record). Corrupt **checkpoint entries** are
-  silently ignored (they only lose one backup, not the recovery path), and a
-  record whose sidecar is missing or truncated fails only that file — never a
-  delete of the live file.
-- **Journal IO never fails the restore**: if the journal cannot be written the
-  restore proceeds with pre-journal semantics (crash safety degrades,
-  behavior does not).
-
-## Explicit non-goals
-
-- This plugin does **not** sandbox other processes or stop them from changing
-  files concurrently.
-- It does **not** provide confidentiality or tamper resistance against the
-  same operating-system user: **store** files are created with the process
-  default permissions (a standard umask applies), and the host user remains
-  trusted. Restored **workspace** files do carry their recorded permission
-  bits: a content restore reapplies them (`chmod`, best-effort), while a mode
-  difference on its own never triggers a restore.
-- It does **not** exclude paths from the store, and it never oversteps: the
-  plugin only adds backup/restore on top of permissions DSH already holds. Two
-  distinct cases follow:
-  1. **Sensitive / personal-information files** (e.g. a `.env` file, which may
-     sit inside the workspace) the model may read or edit are backed up and
-     restorable, unless the file is over the size cap.
-  2. **Files outside the session workspace** the model is allowed to touch are
-     likewise backed up and restored.
-  In both cases the plugin introduces no authority of its own — DSH already
-  granted the read/edit; the plugin merely records a before-backup and can
-  restore it. Keeping a path 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`
-  still see the withdrawn messages (documented behavior, not a bug).
-- It does **not** restore files written by a cancelled tool call that never
-  committed a backup.
-- **Subagent session edits are not tracked** (Claude Code alignment): a
-  subagent runs its own session, so the files it changes are not backed up and
-  cannot be restored by a rewind of the parent session; the plugin keeps no
-  snapshot for a subagent session and offers no rewind inside one.
-
-## Reporting
-
-Report a vulnerability through the repository's GitHub security channel or to
-a repository maintainer. Include: the plugin version/commit, the DSH
-(`@deepseek-ai/*`) version, the platform, and a minimal reproduction — and
-whether the failure happened before or after workspace mutation.
+# Security Policy
+
+## Supported versions
+
+Only the latest stable release receives security fixes.
+
+| Version | Supported |
+| --- | --- |
+| Latest stable `0.x` release | Yes |
+| Earlier stable releases | No — upgrade to the latest release |
+| `alpha` / `rc` pre-releases | No — published for testing only |
+
+## Reporting a vulnerability
+
+Report privately through GitHub's private vulnerability reporting:
+**[Report a vulnerability](https://github.com/SiriLee/dsh-rewind/security/advisories/new)**
+— or open **Security** → **Report a vulnerability** from the repository. It
+creates a private advisory that only you and the maintainer can see.
+
+Please do not open a public issue, pull request, or discussion for a
+vulnerability before a fix has been released.
+
+Include as much of the following as you can:
+
+- the plugin version or commit;
+- the DeepSeek Harness version (`@deepseek-ai/*` packages);
+- the platform and Node.js version;
+- a minimal reproduction: configuration, steps, and the relevant log output;
+- whether the failure happened before or after a workspace file was mutated.
+
+If the problem is in DSH itself or in another plugin, report it to that project.
+
+## What to expect
+
+- We aim to acknowledge a report within 7 days, with a first assessment
+  (in scope / out of scope / need more information) within a further 7 days.
+- The report stays private while a fix is developed, and you are kept updated in
+  the advisory.
+- We ask for up to 90 days before public disclosure; the advisory can be
+  published earlier once a fix is ready and you agree.
+- With your consent, the published advisory credits you, and it enters the
+  GitHub Advisory Database so `npm audit` and Dependabot can flag affected
+  installs.
+- If the report is not a vulnerability, or is out of scope, we explain why and
+  close the advisory.
+
+## Scope
+
+**In scope** — behavior that breaks a guarantee in the security model:
+
+- a restore that writes outside the paths and locations the session recorded, or
+  that runs without an explicit user action;
+- path traversal, or a symlink/hard-link escape, through a session id, a store
+  entry, or restore planning;
+- rewriting, deleting, or truncating the session log, or otherwise changing
+  recorded history;
+- a restore crossing sessions, or touching a path the session's own tools did
+  not record;
+- a crash or a corrupt journal that loses a live file, or that silently drops a
+  recovery journal;
+- a hostile session-log entry or tool argument escaping the containment that
+  document describes.
+
+**Out of scope**:
+
+- attackers who already have the same OS account, the host process, or the
+  workspace: the host user is trusted, and store files use the process umask;
+- vulnerabilities in DSH or other plugins — report them upstream;
+- actions the model is allowed to take under DSH's permission model (for
+  example, editing a `.env` file), unless they escape that model;
+- behavior the security model explicitly lists as a non-goal.
+
+## Security model
+
+The guarantees, the containment rules, and the explicit non-goals are
+documented at
+**https://github.com/SiriLee/dsh-rewind/blob/main/docs/security-model.md**.
+
+Reporters are welcome to test those claims: a mismatch between that document and
+the code is itself worth reporting.