dsh-rewind-plugin 0.4.2 → 0.5.0

package/docs/architecture.md

@@ -0,0 +1,128 @@
+# Architecture
+
+How dsh-rewind is built: module layering, the rewind pipeline, the checkpoint
+pipeline, the compatibility strategy, and the roadmap. The module map below is
+the same one in `AGENTS.md`; this document adds the wiring between the
+modules. The durable on-disk format is specified separately in
+`docs/format.md`, the security model in `SECURITY.md`.
+
+## Purpose
+
+One thing: rewind a conversation **in place** to any earlier user message —
+never forking a session or switching windows — with an optional Claude-Code-
+style workspace file restore (`both` mode). No network, no git operations, no
+credentials access.
+
+## Module layering
+
+```
+src/
+├── index.ts          host plugin: /rewind command + checkpoint pipeline
+├── rewind.ts         pure planning: target parsing, surface-range plan,
+│                     candidate listing, marker turn/step math
+├── snapshot.ts       checkpoint store: disk before-backups, journaled restore,
+│                     reconcile / continue / rollback, bounded prune
+├── session-cwd.ts    session working-directory resolution (fs-tools rule)
+└── client/           browser half: per-message ↶ button (portal bridge),
+                     mode popover, hidden-span computation, candidate parsing,
+                     locales, styles
+```
+
+Two dependency rules keep the design testable:
+
+1. **`rewind.ts` is pure** — no I/O, no `Session` dependency; everything
+   derives from the event log + ordered surface, so the whole planning layer
+   is unit-testable without a host.
+2. **`snapshot.ts` is host-independent** — it talks to the disk through plain
+   `node:fs` plus injected seams (`DiskProbe`, `DeleteFile`, a test-only
+   `crash` hook), so the store is testable without the harness.
+
+The client never reads the DOM to derive rewind state; it consumes the host's
+machine channels (see [Compatibility strategy](#compatibility-strategy)).
+
+## Rewind pipeline
+
+```
+↶ button / /rewind @<seq> both
+  → handleRewind: parseRewindTarget + planRewind (target must be a
+    user/message currently on the surface)
+  → agent.cancel({ keepInbox: true }) if running; waitForAgentIdle
+  → dropPendingSteering (next-step inbox only; queued messages untouched)
+  → append ghost step frame: step/start (turn = last started turn,
+    step = that turn's next unused number) … marker … step/end
+  → marker = empty assistant/message with
+    surfaceOp { op: 'replace', start, end } over every surface node
+    after the target (+ sourceEventSeqs = shadowed seqs)
+  → if mode 'both': store.restoreAfter(targetSeq) + syncRestoreObservations
+  → result text carries machine tokens (impact=<n>, restore:/delete: lines)
+  → client: hides withdrawn rows (data-dsh-rewind-hidden), refills composer
+    with the target message's text
+```
+
+Key invariants:
+
+- **The log is append-only.** The marker is the *only* mutation: it cuts the
+  model-visible surface, never the raw history (search/export still see it).
+- **The marker is empty** (`content: []`, derives to `null` in the model
+  context) so it renders nothing and enters no model context.
+- **The ghost step frame exists for the token-meter**: replay requires every
+  `assistant/message` inside an open step of the same `(turn, step)`; a bare
+  marker appended while idle would throw on the next `measure()` and silently
+  break `/compact`. The turn/step numbers are chosen so they can never collide
+  with a future real turn (`markerTurnOf` / `markerStepOf` — see
+  `src/rewind.ts`).
+- **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.
+
+## Checkpoint pipeline (Claude Code before-backup model)
+
+```
+tools/execute        captureBefore: for write / edit / str_replace_editor
+                     (mutating commands only), read the file's BEFORE state;
+                     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.
+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.
+pruneStale            cross-session auto-cleanup (default off): whole
+                     long-inactive session dirs past the cutoff are removed;
+                     the active session is never targeted.
+```
+
+## Compatibility strategy
+
+- **Peer ranges as OR-union of DSH rc tuples** (`^0.1.0-rc.6 || ^0.1.1-rc.2`):
+  npm's prerelease rules require the peer range to share the host's
+  `[major, minor, patch]` tuple; `scripts/check-dsh-version.mjs` detects when
+  a new tuple requires appending. See `docs/release/release.md`.
+- **Test-driven investigation**: `tests/compat-invariants.ts` /
+  `compat-interop` / `compat-gaps` probe harness behavior and pin findings in
+  `docs/compat/audit.md`; `scripts/verify-host.mjs` runs a real end-to-end
+  rewind + `/compact` chain (the full check suite).
+- **Stable machine channels for third parties**: `dsh-rewind-plugin/client`
+  exports the pure hidden-span computation; withdrawn rows carry
+  `data-dsh-rewind-hidden`; both are semver-protected
+  (`docs/contract/client-contract.md`). DOM coupling is minimized to a small
+  set of marked rows plus a structurally-typed slot registration.
+
+## Roadmap
+
+Ideas under consideration, not commitments:
+
+- **Multi-process identity/lock**: the current in-flight guard is
+  per-process; a cross-process exclusive lock (like the change-ledger
+  competitors) would cover multiple host processes on one worktree.
+- **Lazy-commit UX**: an explicit confirm-then-apply step (a pending state)
+  to reduce mis-touch risk on in-window rewinds, which are inherently less
+  reversible than forked branches.
+- **Locale expansion**: client/host copy is zh/en today; the copy layer
+  (`src/locales.ts`, `src/client/locales.ts`) is already keyed for more.
+- **Composer re-send polish**: the target text is already refilled after a
+  rewind; a first-class "edit and re-send" affordance is a small extension.

package/docs/compat/tracking-boundary.md

@@ -0,0 +1,103 @@
+# File-rewind tracking boundary
+
+> Behavioral note — this is **not** a bug. The plugin's file rewind deliberately
+> tracks only the model's dedicated editing tools, and applies an additional
+> boundary (message-boundary re-check) to registered files. Written for issue
+> [#5](https://github.com/SiriLee/dsh-rewind/issues/5); aligned with Claude Code's
+> checkpoint semantics. [中文](tracking-boundary.zh.md)
+
+## 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
+[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
+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.
+
+**Command-line or manual edits**: PowerShell (`pwsh`) writes on Windows, `sed -i`
+on Linux, or saving a file by hand. These do **not** tell the plugin which file
+is being touched, so there is nothing to snapshot beforehand.
+
+Command/manual edits are nevertheless covered in one case: if the file was
+**previously registered** by an editing tool in this conversation, the plugin
+re-checks registered files at each user-message boundary and records a change it
+sees, so those files restore on rewind too.
+
+## When a rewind is not available
+
+These are cases where there is **no recorded pre-change state at all** (as
+opposed to the precision gap in the next section, where a state exists but an
+intermediate message's exact value is lost):
+
+1. **The model edits the file with a command on its first touch, and the file
+   was never registered.** No snapshot, no registration — nothing was recorded
+   around the change, so there is nothing to restore from. Every rewind target
+   reports no restorable change for this file.
+2. **The file was manually edited before the model's first editing-tool change.**
+   The plugin's first snapshot is taken at the editing-tool call, so rewind can
+   return the file only to its state *after* the manual edit, not before it.
+
+Both stem from a deliberate **lightweight** trade-off. Supporting command edits
+in every case would require scanning the whole workspace and classifying what
+arbitrary commands changed — costly, error-prone, hard to maintain. Instead the
+plugin registers only the editing tools that hand it an exact path, and relies
+on the message-boundary re-check as its lightweight safety net. The cost is that
+unregistered files' command edits are not recorded; the benefit is a simple,
+reliable, maintainable plugin — the same behavior Claude Code exhibits.
+
+## Rewind precision for a registered file changed outside editing tools
+
+A registered file's snapshots come only from (a) an editing tool's before-capture
+and (b) the boundary's change-detection. So a message is a *recording point* for
+a file only when the file's state differs from its most recent recorded state;
+rewinding to message *M* restores each file to the earliest entry at/after *M*.
+
+If the file was **unchanged** at *M* (relative to its last record), then *M* is
+**not** a recording point. If the file is later changed by a command/manual
+edit, the earliest entry at/after *M* is the one that recorded the **post-change**
+state — so rewinding to *M* restores that post-change state, not the state the
+file actually held at *M*:
+
+```
+message 1   write sets f = "X"        records before=null (file created)
+message 2   boundary records f = "X"  (null → X)
+            a command changes f "X" → "Y"
+message 3   boundary records f = "Y"  (X → Y)
+rewind to message 2 → restores "X"    (correct: f was "X" at message 2)
+```
+
+Now insert one *unchanged* message, and the precision gap appears:
+
+```
+message 1   write sets f = "X"        records before=null (file created)
+message 2   boundary records f = "X"  (null → X)
+message 3   reply, f still "X"        NOT a recording point (unchanged)
+            a command changes f "X" → "Y"
+message 4   boundary records f = "Y"  (X → Y)
+rewind to message 3 → restores "Y"    (wrong: f was "X" at message 3)
+```
+
+Message 2 is a recording point, so rewinding to it recovers the pre-change state
+`X`; message 3 is not, so its exact state is lost once the command changes the
+file. Only recording every registered file at every message — even when nothing
+changed — would close this, at the cost of a per-message file per registered
+file. The plugin avoids that to stay lightweight (see
+[Position](#position)). Claude Code's checkpoints behave the same way.
+
+## Position
+
+Making command edits restorable in the *unregistered-first-touch* case would
+mean repeatedly backing up the entire workspace, or depending on a Git working
+tree — both heavy, and at odds with the plugin's lightweight-snapshot design.
+Git is already the right tool for workspace-change management. The plugin's
+position is to favor **fast, conversation-scoped rewinds**, so this capability
+is deliberately not adopted.

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

@@ -0,0 +1,55 @@
+# 文件回退的追踪边界
+
+> 行为说明——这**不是 bug**。插件的文件回退**有意只追踪模型的专用编辑工具**，并对**已登记文件**额外施加一层边界（消息边界复查）。为 issue [#5](https://github.com/SiriLee/dsh-rewind/issues/5) 编写；与 Claude Code 的 checkpoint 语义保持一致。 [English](tracking-boundary.md)
+
+## 一句话概括
+
+回退**始终能还原**用专用编辑工具（`write` / `edit` / `str_replace_editor`）编辑过的文件，因为插件会在编辑前对其快照。**命令行（或手动）编辑**仅当该文件在同一会话中**先前已被某个编辑工具登记**时才会被覆盖——此时变更本身会被记录，但回退到"未变区间中间的边界"时，只能精确到**下一处被记录的状态**（见[已登记文件被编辑工具之外的方式改动时的回退精度](#已登记文件被编辑工具之外的方式改动时的回退精度)）。
+
+## 文件变更的分类
+
+**编辑工具**（创建/覆盖、按行编辑、插入）：每次调用都会告诉插件*将要改动哪个文件*，因此插件会在编辑前对文件的当前内容**快照**，回退时能还原。这条路径是**确定性**的——用了就一定可还原。
+
+**命令行或手动编辑**：Windows 上的 PowerShell（`pwsh`）写入、Linux 上的 `sed -i`，或手动保存文件。它们**不告诉**插件动了哪个文件，所以**没有可预先快照的对象**。
+
+命令/手动编辑仍有一种情况会被覆盖：若该文件在本会话中**先前被某个编辑工具登记过**，插件会在每个用户消息边界复查已登记文件并记录它看到的变更，因此这类文件也能在回退时还原。
+
+## 何时无法回退
+
+这类是**完全没有记录到"变更前"状态**（有别于下一节的"精度缺口"——那是有记录、但某个中间消息的精确值丢失）：
+
+1. **模型第一次触达时用命令编辑，且该文件从未被登记。** 无快照、无登记——变更前后都没有记录，无从还原；回退到任何消息对该文件都报告"无变更可恢复"。
+2. **文件在模型第一次编辑工具改动前就被手动编辑过。** 插件的首个快照是在编辑工具调用时拍的，因此回退只能把文件还原到手动编辑**之后**的状态，而非**之前**。
+
+两者都来自**刻意求轻**的取舍。要覆盖各种命令编辑，就得扫描整个工作区、并分类任意命令改了什么——代价高、易错、难维护。插件只登记会交出手确切路径的编辑工具，并以消息边界复查作为轻量安全网。代价是未登记文件的命令编辑不被记录；收益是简单、可靠、易维护——与 Claude Code 相同。
+
+## 已登记文件被编辑工具之外的方式改动时的回退精度
+
+已登记文件的快照只来自：(a) 编辑工具的 before 捕获，(b) 边界复查的变更检测。所以**只有"文件状态相对上次记录发生变化"的那条消息才是记录点**；回退到消息 *M* 会把各文件还原到 *M* 之后**最早**的那条记录。
+
+若文件在 *M* 处**未变**（相对上次记录），则 *M* **不是记录点**。若随后文件被命令/手动编辑改掉，*M* 之后最早的那条记录是**变更后**状态——于是回退到 *M* 会还原成**变更后**状态，而非 *M* 时刻文件**真实**的状态：
+
+```
+消息 1   write 设 f="X"        记录 before=null（文件新建）
+消息 2   边界记录 f="X"        （null→X）
+        命令把 f "X"→"Y"
+消息 3   边界记录 f="Y"        （X→Y）
+回退到消息 2 → 还原成 "X"     （正确：消息 2 时 f 是 "X"）
+```
+
+插入一条**未变**消息，精度缺口才显现：
+
+```
+消息 1   write 设 f="X"        记录 before=null（文件新建）
+消息 2   边界记录 f="X"        （null→X）
+消息 3   回复，f 仍="X"        不是记录点（未变）
+        命令把 f "X"→"Y"
+消息 4   边界记录 f="Y"        （X→Y）
+回退到消息 3 → 还原成 "Y"     （错：消息 3 时 f 实际是 "X"）
+```
+
+消息 2 是记录点，所以回退它能恢复**变更前**状态 `X`；消息 3 不是记录点，一旦文件被命令改掉，它那刻的精确状态就丢了。要关闭这个缺口，就得让每条边界都是快照——每条消息都记录每个已登记文件（哪怕没变）——代价是**每条消息×每个文件都写一个文件**。插件**刻意不做**，以保持轻量（见[定位](#定位)）。Claude Code 的 checkpoint 同样如此。
+
+## 定位
+
+要把"未登记首触即命令编辑"的情形也做成可还原，意味着对整个工作区反复备份，或依赖 Git 工作树——都笨重，且与插件"轻量快照"的设计相悖。Git 才是管理工作区变更的正确工具。插件的定位是**快速、会话内回退**，因此**刻意不采纳**该能力。

package/docs/compat/troubleshooting.md

@@ -0,0 +1,41 @@
+# Troubleshooting
+
+[简体中文](troubleshooting.zh.md)
+
+## History load failure: `…turn-tail… received an update before its start Match`
+
+Rewinds from `≤ 0.2.4` collided with the next real turn's `turn/start`, so reopening the session showed
+
+```
+Failed to load history: conversation Context …:turn-tail… received an update before its start Match (internal)
+```
+
+and the history vanished. Rewinds from `0.2.5` on no longer collide; already-corrupted sessions need an offline repair (the log is append-only). The repair tool (`dsh-rewind-repair`) is no longer shipped from v0.4.0 — install a pre-v0.4.0 release to get it (fully quit dsh web / host first, then):
+
+```sh
+npm exec --yes --package=dsh-rewind-plugin@0.3.3 -- dsh-rewind-repair
+npm exec --yes --package=dsh-rewind-plugin@0.3.3 -- dsh-rewind-repair -- --dry-run  # preview only
+```
+
+It only rewrites the marker events' `data.turn` (seqs, order, and zstd frame structure intact) and backs up the original file before writing — safe to run repeatedly. From a source checkout of a pre-v0.4.0 tag: `node scripts/repair-markers.mjs` (identical flags).
+
+## Known compatibility boundaries
+
+Behavioral notes — none of these is a crash — verified by the compatibility
+probe suites; the audit [audit.md](audit.md) is the source of truth and lists
+the probes that pin each one:
+
+- Session stats / telemetry do **not** roll back with a rewind.
+- Withdrawn messages stay **searchable and exported** (`/export` and full-text
+  search read the raw log).
+- Session titles may **regenerate** (title derives from the current surface).
+- Files written by a **cancelled tool call** (write happened, no snapshot
+  commit) cannot be restored by "conversation and code".
+
+**R-OPENSTEP** (harness-side, plugin does not guard): a session log carrying an
+*unclosed* `step/start` (a crash before the agent loop's `finally` closed the
+step) makes later step activity break token-meter replay, so `/compact` can
+fail after a rewind. Harness `0.1.1-rc.2` fixes the crash path on load
+(`interruptedTurnClosers`); a plugin-side up-front rejection was tried and
+**reverted** (`177ec14`, false positives on real logs). Deep analysis:
+[audit.md](audit.md) → R-OPENSTEP.

package/docs/{troubleshooting.zh.md → compat/troubleshooting.zh.md}

@@ -12,3 +12,18 @@ npm exec --yes --package=dsh-rewind-plugin@0.3.3 -- dsh-rewind-repair -- --dry-r
 ```
 
 工具只改写标记事件的 `data.turn`（保持 seq / 顺序 / zstd 帧结构不变），改前自动备份原文件——可安全重复运行。源码方式：v0.4.0 之前的 tag 下 `node scripts/repair-markers.mjs`（参数相同）。
+
+## 已知兼容边界
+
+以下均为**预期行为而非崩溃**（探针钉住，完整依据见 [audit.md](audit.md) 事实源）：
+
+- 会话统计 / 遥测**不回退**（折叠的是完整日志）；
+- 被撤回的消息**仍可搜索、可导出**（`/export` 与全文搜索基于原始日志）；
+- 会话标题可能**重新生成**（标题由当前 surface 派生）；
+- 被**取消的工具调用**写入的文件（无快照提交）无法由「回退对话和代码」恢复。
+
+**R-OPENSTEP**（harness 侧，插件不设守卫）：日志中存在*未闭合* `step/start`
+（agent 循环的 `finally` 闭合 step 前崩溃）时，后续 step 活动会破坏 token-meter
+重放，回退后 `/compact` 可能报错。harness `0.1.1-rc.2` 已在加载时自动闭合
+（`interruptedTurnClosers`）；插件曾实现前置拒绝但已回退（`177ec14`，真实日志
+误判）。深入分析：[audit.md](audit.md) → R-OPENSTEP。

package/docs/format.md

@@ -0,0 +1,150 @@
+# Durable format
+
+The on-disk format of the dsh-rewind checkpoint store, pinned as a spec. The
+implementation is `src/snapshot.ts`; this document is the reference for what
+readers may rely on and what a future incompatible change must do. If the code
+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.
+
+```
+<root>/
+└── <sessionId>/                        # safeSessionId(sessionId)
+    ├── <anchorSeq>/                    # decimal seq of the anchoring user/message
+    │   └── <callId>.json               # one committed before-backup
+    └── restore-journal-<opId>.json     # one restore-op journal
+```
+
+- `sessionId` is sanitized to `[a-zA-Z0-9._-]`; the bare values `.` and `..`
+  are replaced (`safeSessionId`) so a hostile id cannot traverse out of the
+  root.
+- `callId` is sanitized to `[a-zA-Z0-9._-]` (`safeFileId`).
+- `<anchorSeq>` is a decimal integer; directories with non-integer names are
+  ignored by readers.
+- Journal files are recognized by the `restore-journal-` prefix; everything
+  else ending in `.json` under the session dir is treated as a checkpoint
+  entry.
+
+## Checkpoint entry
+
+One JSON file per before-backup, named `<callId>.json`:
+
+```ts
+interface CheckpointEntry {
+  callId: string      // the tool call that mutated the file
+  anchorSeq: number   // seq of the user message anchoring the turn of the change
+  path: string        // resolved display path (absolute)
+  before: string | null // full content before the change; null = file was created
+  time: number        // epoch ms, strictly increasing within a store instance
+}
+```
+
+Semantics:
+
+- **`before` is the pre-edit state**: `null` means the call created the file.
+- **`anchorSeq` ties the backup to a user message**: rewinding to message N
+  applies every entry anchored at or after N (the boundary is inclusive).
+- **`time` is the ordering key within an anchor group**: it is monotonic per
+  store instance (bumped past the previous commit), so same-millisecond
+  commits stay capture-ordered and a re-read always picks the same "earliest"
+  entry per path.
+- Synthetic re-check entries (external edits/deletions seen at a user-message
+  boundary) use `callId = recheck-<anchorSeq>-<sha256(path) first 8 hex>`.
+
+### Dedup link entry
+
+A tracked file that records the same `before` content as its immediately-prior
+entry for that path is stored as a **link** instead of a full copy: the entry
+carries a `ref` (the `<anchorSeq>/<callId>.json` of that prior entry) and omits
+`before`, so identical content is never duplicated across entries. A reader
+resolves the `ref` back to the terminal real snapshot; `before: null` still
+means "the file was created". A `ref` is validated as a single-level,
+`<digits>/<callId>.json` relative reference (no traversal) so a corrupt or
+hostile ref cannot escape the store root when followed. Because links reference
+prior entries, `prune` materializes a surviving link whose `ref` lands on a
+group it is about to drop before deleting that group, so no kept link is left
+dangling.
+
+Real entries (with `before`) are unchanged and read identically before and
+after this addition; a link entry is a distinct kind that lacks `before`.
+
+## Restore journal
+
+One JSON file per restore operation, written **before any mutation** and
+updated as the pass applies:
+
+```ts
+interface RestoreJournal {
+  version: 1
+  id: string                    // `op-<base36 ms>-<random>`; file name suffix
+  sessionId: string
+  targetSeq: number             // rewind target the restore belongs to
+  startedAt: number             // epoch ms
+  finishedAt?: number           // set on a terminal state
+  state: 'running' | 'rollback-running' | 'completed' | 'rolled-back' | 'recovery-required'
+  actions: RestoreJournalAction[]
+  rollbackError?: string        // set when a rollback pass failed partway
+}
+
+interface RestoreJournalAction {
+  path: string
+  action: 'restore' | 'delete'  // restore = write `before` back; delete = unlink
+  before: string | null         // target content for restore; null for delete
+  rescue: string | null         // pre-restore disk state; null = file was absent
+  rescueError?: string          // set when the rescue capture failed (rollback skips it)
+  done: boolean                 // true once the action's fs op completed and was marked
+  failed?: string               // per-action failure message (the pass never aborts)
+}
+```
+
+States: `running` and `rollback-running` are non-terminal; a host restart turns
+them into `interrupted` (or `recovery-required` when the journal is corrupt or
+a rollback could not complete). `completed` / `rolled-back` are terminal.
+
+## Write guarantees
+
+- **Atomicity**: every JSON write serializes to a sibling `<target>.tmp` and
+  renames over the target. A crash between the two steps leaves only the temp
+  file — never a readable half-written target — and readers ignore temp files
+  (they do not end in `.json`). The next write of the same target overwrites
+  a leftover temp.
+- **Journal before mutation**: the rescue state of every planned path is
+  captured and the intent journal persisted atomically BEFORE the first fs
+  mutation; each action is marked `done` as it is applied.
+- **Disk is truth**: after a restart, reconciliation compares the real disk
+  against each action's goal (the restore target for `running` journals, the
+  rescue state for `rollback-running` / `recovery-required` ones). A path
+  whose disk already matches is marked done without being touched.
+- **Bounded storage**: `prune` keeps the newest 100 anchor groups per session
+  (`MAX_ANCHOR_GROUPS`), materializing any surviving dedup link that references
+  a group being dropped before deleting whole anchor directories; it also
+  recycles terminal journals (`completed` / `rolled-back`). Non-terminal and
+  corrupt journals are always kept. Across sessions, `pruneStale` removes whole
+  long-inactive session directories whose newest member stamp is older than a
+  configurable idle cutoff (default off), so the store root does not grow
+  without bound either.
+
+## Validation and failure policy
+
+- **Entries**: a missing or malformed entry is read as `undefined` (silently
+  skipped) — losing one backup, never the recovery path.
+- **Journals**: a corrupt or schema-invalid journal **fails loud** —
+  `reconcileRestores` reports it as `recovery-required` and never drops it,
+  because dropping it would silently erase the interrupted restore's recovery
+  record.
+- **Journal IO**: best-effort by design — if a journal cannot be written, the
+  restore proceeds with pre-journal semantics (crash safety degrades,
+  behavior does not).
+
+## Versioning policy
+
+The journal schema is `version: 1`. Checkpoint entries currently carry no
+version field. A future incompatible format must either bump the journal
+`version` (readers reject unknown values — there is no best-effort fallback or
+legacy coercion) or move the state root (e.g. `rewind-snapshots/v2`) and ship
+an explicit migration tool. Old-format data is never silently re-interpreted.

package/docs/harness-reference.md

@@ -21,7 +21,7 @@
 
 Compatibility probes against these subsystems (test-driven investigation, the
 `compat-invariants` / `compat-interop` vitest suites + the `verify-host` real
-`/compact` chain): [compat-audit.md](compat-audit.md).
+`/compact` chain): [compat/audit.md](compat/audit.md).
 
 Also under `docs/` at the repo root: `persistence-catalog.md` (full
 `SessionEventMap`), `tool-catalog.md` (tool inventory), `config-catalog.md`
@@ -45,6 +45,10 @@ Also under `docs/` at the repo root: `persistence-catalog.md` (full
 
 ## Plugin source layout
 
+The module map below duplicates `AGENTS.md` (`Layout at a glance`), which is
+the canonical source; this block only adds the finer-grained client-side files
+and packaging entries.
+
 ```
 src/index.ts            host plugin: /rewind command + checkpoint pipeline (tools/execute|post-execute)
 src/rewind.ts           pure planning: target resolution, surface range, candidate listing
@@ -56,9 +60,9 @@ src/client/hidden.ts    withdrawn-span computation (hiddenSeqsOf), pure
 src/client/locales.ts   zh / en copy (LocaleNamespaceMap)
 src/client/styles.ts    injected styles (dsh design tokens)
 scripts/build.mjs       esbuild: lib/index.js (host ESM) + lib/client.js (loader closure) + .d.ts
-scripts/verify-host.mjs end-to-end host verification (18 checks)
+scripts/verify-host.mjs end-to-end host verification (full check suite)
 tests/                  vitest suites (rewind / snapshot / hidden / session-cwd / integration)
-docs/                   maintainer docs: harness reference, troubleshooting, release steps
+docs/                   maintainer docs: contract/, compat/, release/ subdirectories
 assets/screenshots/     UI screenshots
 cordis.patch.yml        bundle patch (mounts the dual-face plugin row)
 package.json            dsh.bundle + dsh.client manifests, optional peerDependencies

package/docs/release/release.md

@@ -0,0 +1,69 @@
+# Release
+
+[简体中文](release.zh.md)
+
+## First release (manual, one-time)
+
+Trusted Publisher can only be configured once the package exists, so the first
+version is published locally:
+
+```sh
+npm login
+npm publish --access public
+```
+
+- If prompted for `EOTP`: complete the browser auth link the CLI prints, or
+  retry with a 6-digit code — `npm publish --otp=<code>`.
+- The first version carries no provenance (local path) — acceptable; every CI
+  release after that publishes with Sigstore/SLSA provenance automatically.
+
+## Configure Trusted Publisher (npmjs.com, one-time)
+
+Open `https://www.npmjs.com/package/dsh-rewind-plugin` → package **settings** →
+**Trusted Publisher**:
+
+| Field | Value |
+| --- | --- |
+| Provider | GitHub Actions |
+| Organization or user | `SiriLee` |
+| Repository | `dsh-rewind` (the GitHub repo, not the npm name) |
+| Workflow filename | `publish.yml` |
+| Environment | empty |
+| Allowed actions | `npm publish` |
+
+## Subsequent releases (CI, automatic)
+
+```sh
+npm version patch
+git push origin main --tags   # triggers .github/workflows/publish.yml
+```
+
+- 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
+  published version is skipped.
+- CI (`.github/workflows/ci.yml`) runs `npm run check` — typecheck + tests +
+  build + artifact verification + a `npm pack --dry-run` — on every push / PR
+  across both Node engines boundary versions; the tarball layout is guarded by
+  `tests/package-layout.test.ts`.
+
+## DSH version alignment (peer range maintenance)
+
+DSH is still in rc; npm's prerelease matching rules require a peer range to
+share the host version's `[major, minor, patch]` tuple. So `peerDependencies`
+uses an OR-union covering every published rc tuple series
+(e.g. `^0.1.0-rc.6 || ^0.1.1-rc.2`), extended as DSH releases new tuples.
+
+- **When to update**: only when DSH releases a new tuple
+  (`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).
+- **Update steps**: append `|| ^<new-tuple>-rc.<n>` to every
+  `@deepseek-ai/dsh-*` peer → bump devDependencies to the latest → `npm
+  install` → `npm run check` → release.
+- **After DSH goes final**: final releases are not bound by the prerelease
+  tuple rule, so the peers can converge to a single stable range (e.g.
+  `^0.1.x`); this section can then be deleted.