dsh-rewind-plugin 0.11.0 → 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

@@ -207,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

@@ -168,7 +168,7 @@ rm <dsh home>/snapshot-cleanup-last-sweep.json
 
 ## 安全
 
-本插件只向会话日志追加回退标记事件，从不删除或改写已记录的历史。工作区文件仅在「回退对话和代码」时被改写，备份存储于 `~/.dsh/rewind-snapshots/`；还原以备份为唯一来源。不触碰你的 git 仓库，无网络请求，不访问任何凭据。对**长期不活跃**的会话，另有默认关闭的全局自动清理可整目录移除其快照，不影响活动会话与对话日志。完整安全模型：[SECURITY.md](SECURITY.md)。
+本插件只向会话日志追加回退标记事件，从不删除或改写已记录的历史。工作区文件仅在「回退对话和代码」时被改写，备份存储于 `<dsh home>/rewind-snapshots/`；还原以备份为唯一来源。不触碰你的 git 仓库，无网络请求，不访问任何凭据。对**长期不活跃**的会话，另有默认关闭的全局自动清理可整目录移除其快照，不影响活动会话与对话日志。完整安全模型：[SECURITY.md](SECURITY.md)。
 
 ## 开发
 
@@ -192,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`，或手动保存文件。它们**不告诉**插件动了哪个文件，所以**没有可预先快照的对象**。
 

package/docs/format.md

@@ -16,63 +16,105 @@ Deleting the root only removes file backups; the store rebuilds from scratch.
 ```
 <root>/
 └── <sessionId>/                        # safeSessionId(sessionId)
+    ├── store                           # store-format marker ("2")
+    ├── format                          # DSH session-format marker (session.header.version)
     ├── <anchorSeq>/                    # decimal seq of the anchoring user/message
-    │   └── <callId>.json               # one committed before-backup
-    └── restore-journal-<opId>.json     # one restore-op journal
+    │   ├── <base>.json                 # one committed before-backup (metadata)
+    │   └── <base>.before               # its raw byte sidecar (the before content)
+    ├── .pending/                       # captures staged but not yet committed
+    │   └── <base>.before
+    ├── rescue/<opId>/<n>.before        # one pre-restore ("rescue") copy per op
+    └── 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`).
+- `callId` is sanitized to `[a-zA-Z0-9._-]` (`safeFileId`) and extended with an
+  8-hex digest of the unsanitized id — `<base>` is
+  `<safeFileId(callId)>-<sha256(callId)[0..8]>`, so two call ids that sanitize
+  to the same name (e.g. `a:b` / `a_b`) cannot collide. Readers never infer a
+  name: every reference names its file, so pre-digest (released v1) names keep
+  resolving.
 - `<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 entries are read from those numeric directories only
+  (`<anchorSeq>/<base>.json`). Neither marker is `.json`, and a stray `.json` in
+  the session root is ignored.
+- Journal files are recognized by the `journal-` prefix (current format) or the
+  released `restore-journal-` prefix (read-only compatibility).
+- `store` is the session's store-format marker (a decimal version, written
+  atomically); a missing marker means the released v1 string format. `format` is
+  the DSH **session**-format marker the snapshots were anchored under (see
+  `docs/snapshot-auto-cleanup.md`) — the two are independent.
 
 ## Checkpoint entry
 
-One JSON file per before-backup, named `<callId>.json`:
+One JSON file per before-backup, named `<base>.json` next to its `<base>.before`
+sidecar:
 
 ```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
+interface CheckpointEntryJson {   // one `<base>.json`
+  store: 2              // on-disk store format (absent/1 = the released v1 string format)
+  callId: string        // the tool call that mutated the file
+  file: string          // resolved display path (absolute)
+  parent?: string       // realpath of the file's directory at commit time (the location pin)
+  blob: string | null   // sibling sidecar file name; null = the file was created
+  size: number          // byte length of the sidecar (0 when `blob` is null)
+  mode?: number         // permission bits, applied when content is restored
+  lossy?: true          // recorded from v1 content that had already lost bytes
+  time: number          // epoch ms, strictly increasing within a store instance
 }
 ```
 
+A dedup link (see below) carries `callId`, `file`, `ref`, `time` and an
+optional `parent` instead of `blob` and `size`.
+
 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).
+- **`blob` is the pre-edit state**: a string names the sidecar holding the exact
+  before bytes (copied raw, never through a JS string, so binary and non-UTF-8
+  files round-trip byte-exactly); `null` means the call created the file — valid
+  only with `size: 0` and never with `lossy`. The name is an invariant: it must
+  equal the entry's own file name minus `.json` plus `.before`.
+- **`anchorSeq` is the parent directory**, deliberately not a field of the
+  entry: rewinding to message N applies every entry anchored at or after N (the
+  boundary is inclusive).
+- **`parent` is the location pin**: the `realpath` of `dirname(file)` at commit
+  time. A restore refuses the path when its directory no longer resolves there.
+  Only the path's FINAL component is checked for links (`lstat().nlink > 1` or a
+  symlink; see `SECURITY.md`), so a repointed ancestor directory would otherwise
+  redirect the write — or the unlink of a recorded creation — outside the
+  recorded location. Absent means "no pin" and falls back to the final-component
+  check alone.
 - **`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.
+- **`mode` never decides an action** (a mode-only difference is a no-op); it is
+  applied, best-effort, only when content is written back.
+- **`lossy` marks a record that had already lost bytes** (v1 content that was
+  decoded lossily, or a materialized link to one): it is comparable but never
+  written back, so a lossy record can never overwrite a live file.
 - 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`.
+entry for that path is stored as a **link** instead of a second byte copy: the
+entry carries a `ref` (the `<anchorSeq>/<base>.json` of that prior entry) and
+omits `blob`/`size`, so identical content is never duplicated across entries. A
+reader resolves the `ref` back to the terminal real snapshot; `blob: null` (i.e.
+a recorded creation) still means "the file was created". A `ref` is validated as
+a single-level, `<digits>/<file>.json` relative reference (no traversal) so a
+corrupt or hostile ref cannot escape the store root when followed; because refs
+name the actual file, a link may point at a released-v1 entry. 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; the materialized entry keeps the bytes and the link's own
+location pin, but not the referent's `mode` (a link records no permissions of
+its own).
 
 ## Restore journal
 
@@ -80,8 +122,10 @@ One JSON file per restore operation, written **before any mutation** and
 updated as the pass applies:
 
 ```ts
+type ByteRef = { blob: string } | { text: string }   // session-relative byte file, or inline text
+
 interface RestoreJournal {
-  version: 1
+  version: 2
   id: string                    // `op-<base36 ms>-<random>`; file name suffix
   sessionId: string
   targetSeq: number             // rewind target the restore belongs to
@@ -94,20 +138,32 @@ interface RestoreJournal {
 
 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
+  action: 'restore' | 'delete'  // restore = write the content back; delete = unlink
+  before: ByteRef | null        // target content for restore; null for delete
+  rescue: ByteRef | null        // pre-restore disk state; null = file was absent
+  mode?: number                 // recorded target permissions
+  rescueMode?: number           // recorded pre-restore permissions
+  parent?: string               // checkpoint-time location pin (see the entry)
   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)
 }
 ```
 
+A `{blob}` reference is safe and session-relative: `<anchorSeq>/<base>.before`
+(an entry sidecar) or `rescue/<opId>/<n>.before` (a rescue copy), validated on
+both write and read so a corrupt or hostile journal can never point a restore or
+a rollback outside the store. `{text}` refs carry content that has no sidecar:
+released-v1 entry content, or a legacy journal's inline strings.
+
 States: `running` and `rollback-running` are non-terminal; `completed` /
-`rolled-back` are terminal. A restart never rewrites the journal — a
-reconciliation *reports* a still non-terminal op as `interrupted` (or
-`recovery-required` when the journal is corrupt or a rollback could not
-complete), while the journal itself stays `running` / `rollback-running`.
+`rolled-back` are terminal. Reconciliation *reports* a still non-terminal op as
+`interrupted` (or `recovery-required` when the journal is corrupt or a rollback
+could not complete), while the journal itself stays `running` /
+`rollback-running`. A journal read back from a legacy file (`restore-journal-`
+prefix, `version: 1`, inline strings) is rewritten IN PLACE as `version: 2` once
+a redo or rollback pass completes, so the same op never leaves two divergent
+versions on disk.
 
 ## Write guarantees
 
@@ -116,9 +172,29 @@ complete), while the journal itself stays `running` / `rollback-running`.
   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.
+- **Bytes before metadata**: a checkpoint commit places the sidecar first
+  (a staged capture is `rename`d out of `.pending/`; other sources are written
+  temp-then-rename) and only then publishes the entry JSON, so a crash can
+  leave an unreferenced sidecar but never an entry whose bytes are missing.
+  A sidecar that is missing or shorter than `size` is a per-file failure, never
+  a silent "the file was created".
+- **Pinned location**: every record this build writes — entry, link and journal
+  action — carries where the tracked file's directory resolved at commit time
+  (the `parent` pin, best-effort), and a restore re-checks it before touching the
+  path — the initial pass, a post-restart `continueRestore` and a
+  `rollbackRestore` alike (the journal carries the pin). A directory that
+  resolves elsewhere is refused and reported, so a restore can never write or
+  unlink outside the recorded location; a record with no pin (released-v1 data,
+  or a commit whose parent could not be resolved) falls back to the
+  final-component link check alone. A parent chain that is GONE is still
+  recreated — the plugin restores files whose directory was deleted — but only
+  while its nearest surviving ancestor resolves inside the pin. A stable
+  symlinked ancestor is never refused: both sides of the comparison are
+  `realpath`s.
 - **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.
+  captured as a raw byte copy and the intent journal — references only —
+  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
@@ -126,32 +202,62 @@ complete), while the journal itself stays `running` / `rollback-running`.
 - **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.
+  recycles terminal journals (`completed` / `rolled-back`) together with their
+  `rescue/<opId>/` bytes, and collects `.pending/` captures older than 24 h that
+  no commit consumed. A group a non-terminal journal still references is pinned
+  — evicting it would make "continue finishes the interrupted op" impossible —
+  so the effective window may exceed `keep` until that op is resolved.
+  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.
+- **Entries**: a missing, malformed, or self-contradictory entry is read as
+  `undefined` (silently skipped) — losing one backup, never the recovery path.
+  Contradictions are never guessed at: a `blob: null` with `size !== 0` or with
+  `lossy`, a `blob` that is not this entry's sidecar name, and a non-string
+  `before` in a v1 record are all corruption, and guessing an entry's kind is
+  how a restore turns into a delete. An absent or malformed `parent` is not
+  corruption: it means "no pin", so the entry falls back to the released
+  final-component rule. Two cases are *not* silent skips: an entry
+  whose `store` is newer than this build fails the whole operation closed (see
+  Versioning), and a record whose sidecar is missing or too short is a per-file
+  failure that the restore reports — never a delete of the live file.
 - **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.
+  record. A `ref` with a traversal, absolute, or unknown-root segment counts as
+  corrupt.
 - **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` (currently descriptive — `isRestoreJournal`
-validates shape, not version). Checkpoint entries carry no version field. A
-future incompatible format should either make readers reject an unknown
-`version` (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.
+The format is versioned twice: a session-level `store` marker (the value is the
+current `CURRENT_STORE_VERSION`, 2) and a self-describing field on every record
+(`store` on entries, `version` on journals). A missing `store` marker (or `1`)
+means the released v1 string format, which is still read but never migrated. A
+`store` **above** the current version fails the whole operation closed — no file
+restore and no new entry written into a store a newer build owns (an explicit
+clear or the age-based sweep is not version-gated) — while the conversation
+rewind itself keeps working (it does not depend on snapshots). A journal whose
+`version` is present but neither 1 nor 2 is corrupt and is reported
+`recovery-required` (see Validation).
+
+Because compatibility is not safe in both directions, the byte format reuses
+none of v1's path/state keys (`path`, `anchorSeq`, `before`) and does not carry
+`anchorSeq` (it equals the parent directory). A released v1 build therefore
+rejects each such entry instead of reading it as "the file was created", so a
+downgrade cannot delete workspace files; that field-name contract is pinned by
+`tests/downgrade-safety.test.ts`. Compatibility means reading old data, not
+repairing it: bytes the v1 build had already lost cannot be recovered.
+
+A future incompatible format should raise the marker/version (readers already
+fail closed above their own version) or move the state root and ship an explicit
+migration tool. Old-format data is never silently re-interpreted.
 
 ## Cleanup policy persistence
 

package/docs/snapshot-auto-cleanup.md

@@ -50,19 +50,17 @@ The auto-cleanup switch and the idle-day cutoff live in the **dsh-settings confi
 
 ## When automatic cleanup runs
 
-Automatic cleanup checks at most **once per run** (a restart lets it check again),
-on the first session activity (a message you send or a tool call that finishes),
-and only when it's enabled and at least 24 hours have passed since the last
-check. The 24-hour clock is saved to `<dsh home>/snapshot-cleanup-last-sweep.json`,
-so restarting doesn't reset it. It runs in the background and never blocks
-what you're doing.
-
-If you want a change to take effect right away, use `run`; automatic cleanup
-picks up a fresh setting on the next run.
+When it's enabled, automatic cleanup runs in the background at most **once a
+day** — and only after 24 hours have passed since the last cleanup. The clock is
+saved to `<dsh home>/snapshot-cleanup-last-sweep.json`, so restarting the host
+can't make it run early. To clean up right now instead of waiting, use
+`/snapshot-auto-cleanup run`.
 
 ## Safety
 
-- Only rewind **snapshots** (the file backups) are ever removed. Your
+- Only rewind **snapshots** are ever removed: a session's snapshot directory
+  holds the before-write file backups plus their bookkeeping (staged captures,
+  rescue copies, restore journals), and that is all the cleanup touches. Your
   conversation is never touched, and the plugin never rewrites or deletes your
   session history.
 - Automatic cleanup never removes your **active** session's snapshots — only

package/docs/snapshot-auto-cleanup.zh.md

@@ -38,13 +38,11 @@
 
 ## 自动清理何时运行
 
-自动清理每次运行（宿主启动）**最多检查一次**，发生在首次活动时（你发出一条消息或某次工具调用完成），且仅在**已开启**且距上次检查**已满 24 小时**时才执行。这个 24 小时时钟会写入 `<dsh home>/snapshot-cleanup-last-sweep.json`，重启不会重置。它后台运行，从不阻塞你在做的事。
-
-想让改动立即生效，请用 `run`；自动清理要到下次运行才会采用新设置。
+开启后，自动清理在后台运行，**一天最多一次**——且距上次清理已满 24 小时才会执行。这个时钟保存在 `<dsh home>/snapshot-cleanup-last-sweep.json`，所以重启宿主也不会让它提前运行。想立刻清理而不等待，用 `/snapshot-auto-cleanup run`。
 
 ## 安全
 
-- 只会移除回退用的**快照**（那份文件备份）。你的对话绝不会被动到，插件也绝不改写或删除你的会话历史。
+- 只会移除回退用的**快照**：一个会话的快照目录里只有写前文件备份及其附属记录（暂存副本、救援副本、还原日志），清理也只动这些。你的对话绝不会被动到，插件也绝不改写或删除你的会话历史。
 - 自动清理**永不**移除你**当前活跃**会话的快照——只清理已失活超过阈值的会话。
 - `run --current` 会清空当前会话的快照。这对该会话的文件回退历史是**不可逆**的：你无法回退到清空之前的代码状态，但你的对话保持完整，会话会从"现在"开始重新记录快照。