dsh-rewind-plugin 0.4.1 → 0.5.0

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.

package/docs/{release.md → release/release.zh.md}

@@ -1,53 +1,7 @@
-# Release
-
-## 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 the same checks on every push / PR, plus
-  a `npm pack --dry-run` sanity check that the tarball carries `lib/` and
-  `LICENSE`.
-
----
-
 # 发布流程
 
+[English](release.md)
+
 ## 首次发布（手动，一次性）
 
 Trusted Publisher 要求**包已存在**才能配置，因此首个版本走本地发布：
@@ -86,8 +40,9 @@ git push origin main --tags   # 触发 .github/workflows/publish.yml
 - workflow 校验 tag 与 `package.json` 版本一致，跑 typecheck + 测试 + 完整
   构建 + 产物验证，以 `--provenance`（Sigstore）发布并创建 GitHub Release。
   **幂等**——已发布的版本会跳过。
-- CI（`.github/workflows/ci.yml`）在每次 push / PR 跑相同检查，外加
-  `npm pack --dry-run` 校验 tarball 含 `lib/` 与 `LICENSE`。
+- CI（`.github/workflows/ci.yml`）在每次 push / PR 跑 `npm run check`——
+  typecheck + 测试 + 构建 + 产物验证 + `npm pack --dry-run`，且覆盖
+  engines 两个边界版本；tarball 布局由 `tests/package-layout.test.ts` 守护。
 
 ## DSH 版本适配（peer 范围维护）
 
@@ -102,7 +57,6 @@ OR 并集覆盖 DSH 已发布的每个 rc 元组系列（如 `^0.1.0-rc.6 || ^0.
 - **自动检测**：`node scripts/check-dsh-version.mjs` 对比 npm 最新版本与
   peer 覆盖的元组，输出是否需追加（exit 0 无需动作，exit 1 需要）。
 - **更新步骤**：给每个 `@deepseek-ai/dsh-*` peer 追加 `|| ^<新元组>-rc.<n>`
-  → devDependencies 同步升到最新 → `npm install` → `npm run typecheck` /
-  `npm test` / `npm run verify:host` → 发版。
+  → devDependencies 同步升到最新 → `npm install` → `npm run check` → 发版。
 - **正式版后收敛**：DSH 发布 final 版本后，正式版不受 prerelease 元组规则
   限制，peer 可收敛为稳定的 `^0.1.x` 单范围，此节即可删除。

package/docs/snapshot-auto-cleanup.md

@@ -0,0 +1,71 @@
+# Snapshot auto-cleanup
+
+The rewind store writes one on-disk `before` backup per tracked file change,
+grouped by its anchor message. Snapshots are deduped within a session and capped
+at the newest 100 anchor groups, but across sessions that are no longer active
+the store can
+still grow without bound. `snapshot-auto-cleanup` is an OPTIONAL global policy
+(off by default) that removes the whole snapshot directory of a session that has
+been **long-inactive** — untouched past a configurable idle cutoff.
+
+It only ever removes the whole snapshot **directory** of a long-inactive session.
+It never touches the active session's snapshots, never touches the conversation
+log, and leaves snapshot data within the idle cutoff alone.
+
+## Commands
+
+```
+/snapshot-auto-cleanup                  show status (enabled, max-age, config path)
+/snapshot-auto-cleanup on|off           enable/disable the automatic sweep
+/snapshot-auto-cleanup max-age <days>   set the idle cutoff (positive integer)
+/snapshot-auto-cleanup run              dry-run: list what would be removed
+/snapshot-auto-cleanup run --apply      actually remove those sessions
+```
+
+`run` is a manual escape hatch and works whether or not the automatic cleanup is
+`on`. `run` defaults to a dry-run; add `--apply` to execute.
+
+## Config file
+
+The policy is persisted to `~/.dsh/snapshot-cleanup.json`:
+
+```json
+{ "enabled": false, "maxAgeDays": 30 }
+```
+
+- `enabled` — whether the automatic sweeps run (default `false`).
+- `maxAgeDays` — how many idle days before a long-inactive session's snapshot dir is
+  removed (default `30`; `0`/negative are rejected, so a broken config can never
+  delete everything).
+
+Override the path with the `DSH_SNAPSHOT_CLEANUP_CONFIG` environment variable.
+The file is written only by the `/snapshot-auto-cleanup` command. A missing file
+reads as the safe default (off); a missing or corrupt file makes a sweep
+**fail-closed** (delete nothing) and log a warning, and is surfaced when you run
+the command again.
+
+## When it runs
+
+The 24h window is anchored on a **persisted** last-sweep time
+(`~/.dsh/snapshot-cleanup-last-sweep.json`), so a host restart does not reset
+it: the auto-sweep checks **once per process run**, on the first session
+activity of a window (a user message or a completed tool call), and cleans only
+when enabled **and** >=24h since the last sweep. It runs in the background and
+never blocks the activity that triggered it. Because the check happens once per
+run, a change that takes effect immediately is best applied with
+`/snapshot-auto-cleanup run`; editing the config file by hand (or enabling after
+the run's first activity) takes effect on the next run.
+
+## Safety and boundaries
+
+- Removes only whole **long-inactive** session dirs; the active session and the
+  conversation log are never touched.
+- "Inactive" is judged by mtime: a session still being written to keeps scrolling
+  its newest member stamp forward, so it is never old enough to be pruned.
+- Dedup `ref` links are session-relative, so removing a whole dir cannot dangle a
+  link elsewhere.
+- Trade-off: enabling auto-cleanup means a session resumed after a long idle gap
+  will rewind only from its remaining (newest 100) anchors; its old snapshots are
+  gone. The conversation log is never affected.
+- Deleting the whole store dir manually stays safe (it is recreated on the next
+  capture); auto-cleanup just scopes that removal to long-inactive sessions.

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

@@ -0,0 +1,42 @@
+# 快照自动清理
+
+回退插件为每次被跟踪的文件修改写入一份磁盘 `before` 备份，并按其锚点消息分组。快照在**同一会话**内去重、且保留最近 100 组锚点，但跨**已不再活跃的会话**时存储仍会无界增长。`snapshot-auto-cleanup` 是**可选**的全局策略（默认关闭）：把**长期不活跃**（失活超过可配置阈值）的会话快照**整目录**移除。
+
+它只会移除**长期不活跃**会话的整个快照目录，绝不触碰活动会话的快照、绝不触碰对话日志，也保留仍在阈值内的快照数据。
+
+## 命令
+
+```
+/snapshot-auto-cleanup                 查看状态（是否开启、max-age、配置路径）
+/snapshot-auto-cleanup on|off          开启/关闭自动清理
+/snapshot-auto-cleanup max-age <天数>  设置失活阈值（正整数）
+/snapshot-auto-cleanup run             预演：列出将移除哪些会话
+/snapshot-auto-cleanup run --apply     真正移除这些会话
+```
+
+`run` 是手动逃生舱，无论自动清理是否为 `on` 都能用；默认只预演，加 `--apply` 才执行。
+
+## 配置文件
+
+策略持久化到 `~/.dsh/snapshot-cleanup.json`：
+
+```json
+{ "enabled": false, "maxAgeDays": 30 }
+```
+
+- `enabled` — 是否运行自动清理（默认 `false`）。
+- `maxAgeDays` — 失活多少天后移除某**长期不活跃**会话的快照目录（默认 `30`；`0`/负数会被拒绝，因此损坏的配置不可能导致"删除一切"）。
+
+可用环境变量 `DSH_SNAPSHOT_CLEANUP_CONFIG` 覆盖路径。该文件只由 `/snapshot-auto-cleanup` 命令写入。文件缺失按安全默认（关闭）处理；缺失或损坏会令一次清扫**fail-closed**（不删任何东西）并写入警告，再次运行命令时会有所提示。
+
+## 运行时机
+
+24 小时窗口锚定在**持久化**的上次清扫时间（`~/.dsh/snapshot-cleanup-last-sweep.json`）上，因此宿主重启不会重置：自动清扫在**每次运行只检查一次**，于某个窗口的首次会话活动（一条用户消息或一次工具调用完成）时执行，且仅在**已启用**且距上次清扫 **>=24 小时**时才清理。它后台运行，从不阻塞触发它的活动。由于每次运行只检查一次，想让改动立即生效最好用 `/snapshot-auto-cleanup run`；手动编辑配置文件（或在本次运行的首次活动之后才开启）会到下次运行才生效。
+
+## 安全与边界
+
+- 只移除**长期不活跃**会话的整目录；活动会话与对话日志永不触碰。
+- "不活跃"以 mtime 判定：仍在写入的会话会不断把"最新成员"时间戳往后推，因此永远到不了可被清理的失活阈值。
+- 去重 `ref` 链接是会话内相对的，所以移除整目录不会让别处产生悬空链接。
+- 权衡：开启自动清理后，某个长时间闲置才被重新打开的会话，只能从剩余（最近 100 组）锚点回退，旧快照已不存在；对话日志永不受影响。
+- 手动删除整个存储目录依然安全（下次捕获时自动重建）；自动清理只是把这种删除限定到长期不活跃的会话。

package/lib/client.js

@@ -92,7 +92,7 @@ function hiddenSeqsOf(snap) {
 
 // src/client/candidates.ts
 var PREVIEW_CHARS = 80;
-var DEFAULT_CANDIDATE_LIMIT = 50;
+var DEFAULT_CANDIDATE_LIMIT = 100;
 function messagePreviewOf(message) {
   const text = message.content.map((block) => block.type === "text" && typeof block.text === "string" ? block.text : "").join("").replace(/\s+/g, " ").trim();
   return text.length <= PREVIEW_CHARS ? text : `${text.slice(0, PREVIEW_CHARS - 1)}\u2026`;