dsh-rewind-plugin 0.11.0-beta.1 → 0.12.0

package/CONTRIBUTING.md

@@ -58,9 +58,10 @@ npm run verify:host    # end-to-end host verification (full check suite)
 ## Testing expectations
 
 - Pure planning (`rewind.ts`, `hidden.ts`) → unit tests in `tests/`.
-- Store behavior (`snapshot.ts`) → `tests/snapshot.test.ts`, plus crash-safety
-  scenarios in `tests/crash-safety.test.ts` via the test-only `crash` seam
-  (`RestoreRunOptions.crash`).
+- Store behavior (`snapshot.ts`) → `tests/snapshot.test.ts` plus the focused
+  suites (`snapshot-bytes`, `snapshot-mode`, `downgrade-safety`,
+  `parent-guard`), and crash-safety scenarios in `tests/crash-safety.test.ts`
+  via the test-only `crash` seam (`RestoreRunOptions.crash`).
 - Harness interaction → the compatibility suites
   (`compat-invariants` / `compat-interop` / `compat-gaps`) and
   `scripts/verify-host.mjs`.

package/README.en.md

@@ -35,8 +35,11 @@ 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).
+
 ```sh
-dsh plugin --profile web add dsh-rewind-plugin
+dsh plugin --profile web add dsh-rewind-plugin@<version>
 ```
 
 > ⚠️ The npm name `dsh-rewind` belongs to another author's package — install with `dsh-rewind-plugin`.
@@ -77,6 +80,20 @@ cleanup** panel (the auto-cleanup switch and the idle-day cutoff), or use the
 
 <img src="assets/screenshots/cleanup-setting.png" alt="Snapshot cleanup settings: auto-cleanup and idle days" width="600">
 
+## Uninstall
+
+```sh
+# Uninstall the plugin
+dsh plugin --profile web remove dsh-rewind-plugin
+
+# To also delete local data
+rm -rf <dsh home>/rewind-snapshots
+rm <dsh home>/snapshot-cleanup-last-sweep.json
+```
+
+The plugin's auto-cleanup settings live in the settings document
+(`<dsh home>/settings.yaml`). To remove them completely, delete the key manually.
+
 ## Why it stands out
 
 Compared with the common approaches, here is the trade-off this plugin makes on "rewind":
@@ -190,7 +207,7 @@ Contributing guide: [CONTRIBUTING.md](CONTRIBUTING.md).
 Releases go out through GitHub Actions Trusted Publishing (OIDC, no stored `NPM_TOKEN`): push a `v<version>` tag and CI publishes with Sigstore provenance.
 
 ```sh
-npm version patch && git push origin main --tags
+npm version patch && git push origin <branch> --tags
 ```
 
 One-time npm-side setup and the full workflow details: [docs/release/release.md](docs/release/release.md).

package/README.md

@@ -35,8 +35,10 @@ DeepSeek Harness 插件：**一键就地回退对话到任意更早的用户消
 
 ## 安装
 
+确认本机 DSH 版本后，在 [Release](https://github.com/SiriLee/dsh-rewind/releases) 找到适配的插件版本。
+
 ```sh
-dsh plugin --profile web add dsh-rewind-plugin
+dsh plugin --profile web add dsh-rewind-plugin@<版本>
 ```
 
 > ⚠️ npm 上的 `dsh-rewind` 属于其他作者，请用 `dsh-rewind-plugin` 安装。
@@ -67,6 +69,19 @@ dsh plugin --profile web add dsh-rewind-plugin
 
 <img src="assets/screenshots/cleanup-setting.png" alt="快照清理设置：自动清理与失活天数" width="600">
 
+## 卸载
+
+```sh
+# 卸载插件
+dsh plugin --profile web remove dsh-rewind-plugin
+
+# 如需同时删除本地数据
+rm -rf <dsh home>/rewind-snapshots
+rm <dsh home>/snapshot-cleanup-last-sweep.json
+```
+
+插件的自动清理设置保存在设置文档（`<dsh home>/settings.yaml`）中。如需彻底清理，可手动删除对应键。
+
 ## 本插件的优势
 
 和常见的几种做法相比，本插件在"回退"这件事上的取舍：
@@ -153,7 +168,7 @@ dsh plugin --profile web add dsh-rewind-plugin
 
 ## 安全
 
-本插件只向会话日志追加回退标记事件，从不删除或改写已记录的历史。工作区文件仅在「回退对话和代码」时被改写，备份存储于 `~/.dsh/rewind-snapshots/`；还原以备份为唯一来源。不触碰你的 git 仓库，无网络请求，不访问任何凭据。对**长期不活跃**的会话，另有默认关闭的全局自动清理可整目录移除其快照，不影响活动会话与对话日志。完整安全模型：[SECURITY.md](SECURITY.md)。
+本插件只向会话日志追加回退标记事件，从不删除或改写已记录的历史。工作区文件仅在「回退对话和代码」时被改写，备份存储于 `<dsh home>/rewind-snapshots/`；还原以备份为唯一来源。不触碰你的 git 仓库，无网络请求，不访问任何凭据。对**长期不活跃**的会话，另有默认关闭的全局自动清理可整目录移除其快照，不影响活动会话与对话日志。完整安全模型：[SECURITY.md](SECURITY.md)。
 
 ## 开发
 
@@ -177,7 +192,7 @@ node scripts/verify-host.mjs   # 端到端验证构建产物
 通过 GitHub Actions Trusted Publishing（OIDC，无存储 `NPM_TOKEN`）发布：推送 `v<版本>` tag，CI 即带 Sigstore provenance 发布。
 
 ```sh
-npm version patch && git push origin main --tags
+npm version patch && git push origin <branch> --tags
 ```
 
 一次性 npm 侧配置与完整流程：见 [docs/release/release.zh.md](docs/release/release.zh.md)。

package/SECURITY.md

@@ -12,9 +12,8 @@ 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` / `path` / `command` fields of write,
-  `edit`, and `str_replace_editor` tool calls (they name the paths the
-  checkpoint store records).
+- **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
@@ -57,7 +56,13 @@ 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.
+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
@@ -68,7 +73,9 @@ 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.
+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
 
@@ -91,29 +98,49 @@ transcript.
   `[a-zA-Z0-9._-]` (`safeSessionId` / `safeFileId`) before joining the store
   root; `.` and `..` bare values are replaced — hostile ids cannot traverse
   out of the root.
-- **Never written through links**: symlinked and hard-linked paths
-  (`lstat().nlink > 1`) are skipped and reported, never restored — 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).
+- **Never written through a link or a moved directory**: two checks guard a
+  tracked path before any write or unlink. (1) A path whose last component is a
+  symlink or a hard link (`lstat().nlink > 1`) is skipped and reported, never
+  restored — 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). (2) 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
   workspace cwd, mirroring the fs tools' own rule (`src/session-cwd.ts`).
 - **Bounded backups**: `prune` keeps the newest 100 anchor groups per session
-  (`MAX_ANCHOR_GROUPS`), so backup accumulation cannot grow the store without
-  bound (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 `maxAgeDays`); it uses `lstat`
-  (no symlink following), skips dot-prefixed temp files, and never targets the
-  active session (`keepActiveId`).
+  (`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 `maxAgeDays`); it uses `lstat` (no symlink following),
+  skips dot-prefixed temp files, and never targets the active session
+  (`keepActiveId`).
 
 ## Crash safety
 
-- **Atomic commits**: 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.
+- **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
@@ -126,7 +153,9 @@ transcript.
 - **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).
+  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).
@@ -136,9 +165,11 @@ transcript.
 - 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: state files are created with the process
-  default permissions (no special modes are set — a standard umask applies),
-  and the host user remains trusted.
+  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:

package/docs/architecture.md

@@ -81,7 +81,8 @@ Key invariants:
   on it, so the marker is appended while idle, outside any turn, as one event.
 - **Restore is reconciled against the live disk** (`planRestore`), so repeated
   rewinds are idempotent and a rewind whose target state already matches is a
-  no-op.
+  no-op. A path whose directory no longer resolves to its commit-time location
+  is skipped and reported, never written through (see `SECURITY.md`).
 
 ### Marker format history
 
@@ -103,19 +104,24 @@ the `0.9.x` line) and is **removed in the `0.10.x` line**.
 ## Checkpoint pipeline (Claude Code before-backup model)
 
 ```
-tools/execute        captureBefore: for write / edit
-                     (mutating commands only), read the file's BEFORE state;
+tools/execute        captureBefore: for write / edit, stage a raw byte copy of
+                     the file's BEFORE state into the store's .pending/
+                     (node:fs copyFile, never through a string);
                      subagent edits are NOT tracked (Claude Code alignment).
 tools/post-execute   commitEntry: anchor = latest user/message seq; skip
-                     failed calls; write the before-backup to the store.
+                     failed calls; publish the staged bytes as the entry's
+                     sidecar and write the metadata beside them — including
+                     where the directory resolved (`realpath`), the location
+                     pin a restore re-checks.
 session/event        user/message boundary: reconcileTracked re-reads every
   (user/message)     tracked file and records a new before-backup for any
                      whose disk state changed since last seen — external
                      edits/deletions enter the record this way.
 prune                keeps the newest 100 anchor groups per session, storing
                      identical before-content as in-place links that are
-                     materialized before their group is dropped, and recycles
-                     terminal restore journals.
+                     materialized before their group is dropped, never dropping
+                     a group a non-terminal restore journal still references,
+                     and recycles terminal restore journals.
 pruneStale            cross-session auto-cleanup (default off): whole
                      long-inactive session dirs past the cutoff are removed;
                      the active session is never targeted.

package/docs/compat/audit.md

@@ -45,7 +45,7 @@ version's shape only (no `Session.events` / `[data-time-hover-root]` /
 | I3 step/turn structure | Client turn-tail ordering, unique `step/start` (real turns), no ghost turns; the `user/message` rewind marker adds no step frame | `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 |
+| I6 tool pipeline | before-snapshot capture/commit/restore is correct (existing `snapshot.test.ts` + `verify-host` 4–8) for the tracked tools `write` / `edit` — `str_replace_editor` is an optional DSH package that stopped being a default tool in DSH 0.1.3, so it is not tracked; cancellation timing never hangs | `verify-host` 4–8, 15 |
 | I7 client ordering | A log carrying tool turns and rewind markers (a single `user/message` replace) satisfies the client builder ordering | `compat-interop` I7 |
 | I8 runtime safety | `rewind`/`compact` combinations never leave a dangling step/turn frame | `verify-host` 15 |
 

package/docs/compat/tracking-boundary.md

@@ -9,16 +9,16 @@
 ## One-line summary
 
 Rewind **always** restores files edited with the dedicated editing tools
-(`write` / `edit` / `str_replace_editor`) because the plugin snapshots them
-before the edit. Command-line (or hand) edits are covered **only when the file
-was previously registered** by an editing tool in the same conversation — and,
-in that case, the change itself is recorded, but rewinding to a boundary inside
-an unchanged interval is only as precise as the next recorded state (see
+(`write` / `edit`) because the plugin snapshots them before the edit.
+Command-line (or hand) edits are covered **only when the file was previously
+registered** by an editing tool in the same conversation — and, in that case,
+the change itself is recorded, but rewinding to a boundary inside an unchanged
+interval is only as precise as the next recorded state (see
 [Rewind precision](#rewind-precision-for-a-registered-file-changed-outside-editing-tools)).
 
 ## How file changes are classified
 
-**Editing tools** (create/overwrite, edit lines, insert): each call tells the
+**Editing tools** (create/overwrite, line edits): each call tells the
 plugin *which file* it will change, so the plugin snapshots the file's current
 content **before** the edit and can restore it on rewind. This path is
 deterministic — using them always yields a restorable rewind.

package/docs/compat/tracking-boundary.zh.md

@@ -4,11 +4,11 @@
 
 ## 一句话概括
 
-回退**始终能还原**用专用编辑工具（`write` / `edit` / `str_replace_editor`）编辑过的文件，因为插件会在编辑前对其快照。**命令行（或手动）编辑**仅当该文件在同一会话中**先前已被某个编辑工具登记**时才会被覆盖——此时变更本身会被记录，但回退到"未变区间中间的边界"时，只能精确到**下一处被记录的状态**（见[已登记文件被编辑工具之外的方式改动时的回退精度](#已登记文件被编辑工具之外的方式改动时的回退精度)）。
+回退**始终能还原**用专用编辑工具（`write` / `edit`）编辑过的文件，因为插件会在编辑前对其快照。**命令行（或手动）编辑**仅当该文件在同一会话中**先前已被某个编辑工具登记**时才会被覆盖——此时变更本身会被记录，但回退到"未变区间中间的边界"时，只能精确到**下一处被记录的状态**（见[已登记文件被编辑工具之外的方式改动时的回退精度](#已登记文件被编辑工具之外的方式改动时的回退精度)）。
 
 ## 文件变更的分类
 
-**编辑工具**（创建/覆盖、按行编辑、插入）：每次调用都会告诉插件*将要改动哪个文件*，因此插件会在编辑前对文件的当前内容**快照**，回退时能还原。这条路径是**确定性**的——用了就一定可还原。
+**编辑工具**（创建/覆盖、按行编辑）：每次调用都会告诉插件*将要改动哪个文件*，因此插件会在编辑前对文件的当前内容**快照**，回退时能还原。这条路径是**确定性**的——用了就一定可还原。
 
 **命令行或手动编辑**：Windows 上的 PowerShell（`pwsh`）写入、Linux 上的 `sed -i`，或手动保存文件。它们**不告诉**插件动了哪个文件，所以**没有可预先快照的对象**。