dsh-rewind-plugin 0.4.0 → 0.4.2

package/docs/harness-reference.md

@@ -12,6 +12,16 @@
 - [commands.md](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/subsystems/commands.md) — command registration (`ctx.commands.register`, `CommandInvocation`, `CommandResult`)
 - [tools.md](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/subsystems/tools.md) — tool execution seam (`tools/pre-execute` / `tools/post-execute`, `ToolExecution`)
 - [session-query.md](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/subsystems/session-query.md) — session query / `foldSurface` read-only interfaces
+- [token-meter.md](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/subsystems/token-meter.md) — replay-aware token meter (`TokenMeter.measure`, surface pricing)
+- [compaction.md](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/subsystems/compaction.md) — compaction seam / `compaction/*` events / `BasicCompactionEngine` (`summarize()` hook)
+- [session-projection.md](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/subsystems/session-projection.md) — projection registry (`SessionProjectionRegistry.snapshot/checkpoint`)
+- [session-stats](https://github.com/deepseek-ai/deepseek-harness/blob/main/packages/session/session-stats) — whole-log stats projection (folds ALL events; rewind does not roll back counts)
+- [session-title.md](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/subsystems/session-title.md) — durable title state (`foldSessionTitle`)
+- [goal.md](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/subsystems/goal.md) — goal fold (`foldGoal`) and round admission
+
+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).
 
 Also under `docs/` at the repo root: `persistence-catalog.md` (full
 `SessionEventMap`), `tool-catalog.md` (tool inventory), `config-catalog.md`

package/docs/release.md

@@ -88,3 +88,21 @@ git push origin main --tags   # 触发 .github/workflows/publish.yml
   **幂等**——已发布的版本会跳过。
 - CI（`.github/workflows/ci.yml`）在每次 push / PR 跑相同检查，外加
   `npm pack --dry-run` 校验 tarball 含 `lib/` 与 `LICENSE`。
+
+## DSH 版本适配（peer 范围维护）
+
+DSH 仍在 rc 阶段，npm 的 prerelease 匹配规则要求 peer 范围与宿主版本
+**同 `[major, minor, patch]` 元组**才能匹配。因此 peerDependencies 采用
+OR 并集覆盖 DSH 已发布的每个 rc 元组系列（如 `^0.1.0-rc.6 || ^0.1.1-rc.2`），
+并随 DSH 发版追加。
+
+- **何时需要更新**：仅当 DSH 发布新元组（`0.1.1 → 0.1.2 → 0.2.x`）时；
+  同元组内 rc 滚动（`0.1.1-rc.2 → rc.3`）无需动作。DSH 所有包同版本发布，
+  `npm view @deepseek-ai/dsh version` 即权威信号。
+- **自动检测**：`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` → 发版。
+- **正式版后收敛**：DSH 发布 final 版本后，正式版不受 prerelease 元组规则
+  限制，peer 可收敛为稳定的 `^0.1.x` 单范围，此节即可删除。

package/docs/troubleshooting.md

@@ -18,3 +18,27 @@ npm exec --yes --package=dsh-rewind-plugin@0.3.3 -- dsh-rewind-repair -- --dry-r
 ```
 
 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 verified by the compatibility probe suites
+([compat-audit.md](compat-audit.md)) — none of these is a crash:
+
+- **Session stats / telemetry do not roll back**: whole-log folds count the
+  withdrawn turns, and telemetry records the rewind's marker and ghost-step
+  frame under the reused turn. Expected whole-log semantics.
+- **Withdrawn messages stay searchable and exported**: rewind cuts only the
+  model-visible surface; full-text search and `/export` still see the raw log.
+- **Session titles may regenerate** after a rewind (title derives from the
+  current surface).
+- **Files written by a cancelled tool call** (write happened, no result, 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 any later step activity break token-meter replay (and
+`/compact`). Harness `0.1.1-rc.2` fixes the crash path on load
+(`interruptedTurnClosers` closes leftover step/turn boundaries). A plugin-side
+up-front rejection was implemented and **reverted** (false positives broke the
+rewind feature on real session logs, `177ec14`); the residual runtime-produced
+risk is accepted. Tracked in the compat-audit.

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`;

package/lib/index.js

@@ -80,7 +80,7 @@ var RewindError = class extends Error {
   code;
 };
 var CANDIDATE_PREVIEW_CHARS = 80;
-var DEFAULT_CANDIDATE_LIMIT = 50;
+var DEFAULT_CANDIDATE_LIMIT = 100;
 function markerTurnOf(events) {
   let lastStarted = 0;
   for (const event of events) {
@@ -195,7 +195,7 @@ function execSessionCwd(exec, requestedPath) {
 
 // src/snapshot.ts
 import { createHash } from "node:crypto";
-import { lstat, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 var DEFAULT_SNAPSHOT_ROOT = join(homedir(), ".dsh", "rewind-snapshots");
@@ -219,6 +219,25 @@ function safeSessionId(sessionId) {
   const safe = sessionId.replace(/[^a-zA-Z0-9._-]/g, "_");
   return safe === ".." || safe === "." ? "session" : safe;
 }
+async function writeJsonAtomic(file, data, afterTempWrite) {
+  const tmp = `${file}.tmp`;
+  await writeFile(tmp, JSON.stringify(data), "utf8");
+  afterTempWrite?.();
+  await rename(tmp, file);
+}
+var RESTORE_JOURNAL_STATES = /* @__PURE__ */ new Set(["running", "rollback-running", "completed", "rolled-back", "recovery-required"]);
+function isRestoreJournal(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  if (typeof v.id !== "string" || typeof v.sessionId !== "string" || typeof v.targetSeq !== "number") return false;
+  if (typeof v.state !== "string" || !RESTORE_JOURNAL_STATES.has(v.state)) return false;
+  if (!Array.isArray(v.actions)) return false;
+  return v.actions.every((action) => {
+    if (typeof action !== "object" || action === null) return false;
+    const a = action;
+    return typeof a.path === "string" && (a.action === "restore" || a.action === "delete") && (typeof a.before === "string" || a.before === null) && (typeof a.rescue === "string" || a.rescue === null) && typeof a.done === "boolean";
+  });
+}
 async function readEntry(file) {
   try {
     const parsed = JSON.parse(await readFile(file, "utf8"));
@@ -250,6 +269,19 @@ var SnapshotStore = class _SnapshotStore {
   /** Debounce window for the per-commit prune (keeps the readdir+sort off the hot path). */
   static PRUNE_INTERVAL_MS = 1e3;
   lastPruneAt = 0;
+  /**
+   * Monotonic entry clock. Date.now() has 1ms precision, so back-to-back
+   * commits in the same millisecond would TIE on the entry `time` field and
+   * entriesAfter's (anchorSeq, time) sort would fall back to the readdir
+   * order — filesystem-dependent, so a re-read could pick the WRONG "earliest"
+   * version for a path. Bumping past the previous commit keeps the capture
+   * order reproducible after a re-read. The read-modify-write below is
+   * synchronous (before the first await), so concurrent commits can never
+   * observe the same value. Across restarts wall-clock monotonicity holds
+   * (restart gaps dwarf 1ms); a backwards NTP step is the only way to break
+   * it, and even then the in-process order still holds.
+   */
+  lastEntryTime = 0;
   /** Absolute path of one session's snapshot directory (id sanitized). */
   sessionDir(sessionId) {
     return join(this.root, safeSessionId(sessionId));
@@ -258,12 +290,20 @@ var SnapshotStore = class _SnapshotStore {
   anchorDir(sessionId, anchorSeq) {
     return join(this.sessionDir(sessionId), String(anchorSeq));
   }
-  /** Commit one before-backup under its turn's anchor group. */
-  async recordEntry(sessionId, entry) {
+  /** Commit one before-backup under its turn's anchor group (atomic write). */
+  async recordEntry(sessionId, entry, opts) {
+    const time = Math.max(Date.now(), this.lastEntryTime + 1);
+    this.lastEntryTime = time;
     const dir = this.anchorDir(sessionId, entry.anchorSeq);
     await mkdir(dir, { recursive: true });
-    const committed = { ...entry, time: Date.now() };
-    await writeFile(join(dir, `${safeFileId(entry.callId)}.json`), JSON.stringify(committed), "utf8");
+    const committed = { ...entry, time };
+    await writeJsonAtomic(
+      join(dir, `${safeFileId(entry.callId)}.json`),
+      committed,
+      // Test-only crash seam: fire after the temp write so a "half-written"
+      // crash leaves no committed entry behind.
+      () => opts?.crash?.("after-temp-write")
+    );
     const now = Date.now();
     if (now - this.lastPruneAt >= _SnapshotStore.PRUNE_INTERVAL_MS) {
       this.lastPruneAt = now;
@@ -381,38 +421,425 @@ var SnapshotStore = class _SnapshotStore {
    * the backup; a delete whose file is ALREADY absent is a silent no-op (not
    * a failure — the target state is already reached). Failures are per-file
    * and never abort the pass.
+   *
+   * The pass is journaled for crash safety: the pre-restore ("rescue") state
+   * of every planned path is captured and an intent journal persisted BEFORE
+   * any mutation, then each action is marked done as it is applied. A host
+   * crash at any point leaves the journal on disk; after a restart
+   * {@link reconcileRestores} reports where the restore stopped,
+   * {@link continueRestore} finishes it and {@link rollbackRestore} undoes it
+   * back to the exact pre-restore state. Journal IO itself never fails the
+   * restore (it degrades to a journal-less pass).
    */
-  async restoreAfter(sessionId, targetSeq, deleteFile, probe = defaultProbe) {
+  async restoreAfter(sessionId, targetSeq, deleteFile, probe = defaultProbe, opts) {
     const restored = [];
     const deleted = [];
     const skipped = [];
     const failed = [];
     const { actions, skipped: skippedPaths } = await this.planRestore(sessionId, targetSeq, probe);
     skipped.push(...skippedPaths);
-    for (const action of actions) {
+    if (actions.length === 0) return { restored, deleted, skipped, failed };
+    const journal = await this.beginRestore(sessionId, targetSeq, actions, probe);
+    for (let i = 0; i < actions.length; i++) {
+      const action = actions[i];
+      opts?.crash?.("before-action", i);
+      const journalAction = journal.actions[i];
+      let applied;
       try {
-        if (action.action === "delete") {
-          try {
-            await deleteFile(action.path);
-          } catch (error) {
-            if (error.code !== "ENOENT") throw error;
-            continue;
-          }
-          deleted.push(action.path);
-        } else {
-          await mkdir(dirname(action.path), { recursive: true });
-          await writeFile(action.path, action.before, "utf8");
-          restored.push(action.path);
+        applied = await this.applyActionToDisk(action.action, action.path, action.action === "restore" ? action.before : null, deleteFile);
+        if (applied === "enoent") {
+          journalAction.done = true;
+          await this.saveJournal(journal);
+          continue;
         }
       } catch (error) {
-        failed.push({ path: action.path, message: error instanceof Error ? error.message : String(error) });
+        journalAction.failed = error instanceof Error ? error.message : String(error);
+        await this.saveJournal(journal);
+        failed.push({ path: action.path, message: journalAction.failed });
+        continue;
       }
+      opts?.crash?.("after-action", i);
+      journalAction.done = true;
+      await this.saveJournal(journal);
+      if (applied === "restored") restored.push(action.path);
+      else deleted.push(action.path);
+    }
+    if (failed.length === 0) {
+      journal.state = "completed";
+      journal.finishedAt = Date.now();
     }
+    await this.saveJournal(journal);
     return { restored, deleted, skipped, failed };
   }
+  /** Prefix of one restore-op journal file inside the session dir. */
+  static JOURNAL_PREFIX = "restore-journal-";
+  /** Absolute path of one restore-op journal file. */
+  journalPath(sessionId, opId) {
+    return join(this.sessionDir(sessionId), `${_SnapshotStore.JOURNAL_PREFIX}${safeFileId(opId)}.json`);
+  }
+  /**
+   * Best-effort journal persist: journal IO failures are non-fatal by design —
+   * a restore must never fail because its audit journal could not be written.
+   * reconcileRestores() re-derives the true state from the disk, so a missing
+   * or stale journal only loses the trail, never the recovery ability.
+   */
+  async saveJournal(journal) {
+    try {
+      await writeJsonAtomic(this.journalPath(journal.sessionId, journal.id), journal);
+    } catch {
+    }
+  }
+  /**
+   * Journal one restore pass before mutating anything: capture the rescue
+   * (pre-restore) state of every planned path and persist the intent
+   * atomically. Returns the in-memory journal; a persist failure degrades to
+   * a journal-less restore (non-fatal, see {@link saveJournal}).
+   */
+  async beginRestore(sessionId, targetSeq, actions, probe) {
+    const sessionDir = this.sessionDir(sessionId);
+    try {
+      await this.pruneTerminalJournals(sessionDir, await readdir(sessionDir));
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    const journalActions = [];
+    for (const action of actions) {
+      let rescue = null;
+      let rescueError;
+      try {
+        rescue = await probe.readText(action.path) ?? null;
+      } catch (error) {
+        rescueError = error instanceof Error ? error.message : String(error);
+      }
+      const journalAction = {
+        path: action.path,
+        action: action.action,
+        before: action.action === "restore" ? action.before : null,
+        rescue,
+        done: false
+      };
+      if (rescueError !== void 0) journalAction.rescueError = rescueError;
+      journalActions.push(journalAction);
+    }
+    const journal = {
+      version: 1,
+      id: `op-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`,
+      sessionId,
+      targetSeq,
+      startedAt: Date.now(),
+      state: "running",
+      actions: journalActions
+    };
+    await this.saveJournal(journal);
+    return journal;
+  }
+  /**
+   * Read one journal by op id; undefined when it does not exist. A corrupt
+   * journal THROWS (fail-loud): unlike checkpoint entries, silently dropping
+   * a journal would silently erase the interrupted restore's recovery record.
+   */
+  async readJournal(sessionId, opId) {
+    const file = this.journalPath(sessionId, opId);
+    let text;
+    try {
+      text = await readFile(file, "utf8");
+    } catch (error) {
+      if (error.code === "ENOENT") return void 0;
+      throw error;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch (error) {
+      throw new Error(`restore journal ${file} is corrupt: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isRestoreJournal(parsed)) throw new Error(`restore journal ${file} failed schema validation`);
+    return parsed;
+  }
+  /**
+   * Every journal file of a session — valid ones plus corrupt ones with their
+   * error — so reconciliation can report corruption instead of dropping it.
+   */
+  async listJournals(sessionId) {
+    const sessionDir = this.sessionDir(sessionId);
+    let names;
+    try {
+      names = await readdir(sessionDir);
+    } catch (error) {
+      if (error.code === "ENOENT") return { journals: [], corrupt: [] };
+      throw error;
+    }
+    const journals = [];
+    const corrupt = [];
+    for (const name2 of names) {
+      if (!name2.startsWith(_SnapshotStore.JOURNAL_PREFIX) || !name2.endsWith(".json")) continue;
+      try {
+        const parsed = JSON.parse(await readFile(join(sessionDir, name2), "utf8"));
+        if (!isRestoreJournal(parsed)) {
+          corrupt.push({ file: name2, message: "journal failed schema validation" });
+          continue;
+        }
+        journals.push(parsed);
+      } catch (error) {
+        corrupt.push({ file: name2, message: error instanceof Error ? error.message : String(error) });
+      }
+    }
+    return { journals, corrupt };
+  }
+  /**
+   * Execute ONE fs mutation with exactly the pre-journal semantics: a delete
+   * runs through the injected deleteFile (ENOENT tolerated — the file is
+   * already absent, i.e. the target state is reached), a restore is a plain
+   * writeFile with a recursive mkdir of the parent. Returns how the outcome
+   * should record it.
+   */
+  async applyActionToDisk(kind, path, content, deleteFile) {
+    if (kind === "delete") {
+      try {
+        await deleteFile(path);
+        return "deleted";
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+        return "enoent";
+      }
+    }
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content, "utf8");
+    return "restored";
+  }
+  /**
+   * Reconcile the session's restore journals against the real disk — the
+   * "host restart" account: for every interrupted op, report which paths
+   * already match its goal (restored) and which are still pending, and expose
+   * any recorded failures. Journals whose goal is already fully reached on
+   * disk (e.g. a later rewind completed the work) are auto-healed to their
+   * terminal state and not reported. A corrupt journal is reported
+   * `recovery-required` — never silently dropped.
+   *
+   * @param sessionId - session whose journals to reconcile.
+   * @param probe - current-disk state probe (defaults to the real FS).
+   * @returns one report per non-terminal journal still needing attention.
+   */
+  async reconcileRestores(sessionId, probe = defaultProbe) {
+    const { journals, corrupt } = await this.listJournals(sessionId);
+    const reports = [];
+    for (const bad of corrupt) {
+      reports.push({
+        opId: bad.file.slice(_SnapshotStore.JOURNAL_PREFIX.length, -".json".length),
+        state: "recovery-required",
+        journalState: "recovery-required",
+        targetSeq: 0,
+        startedAt: 0,
+        restored: [],
+        pending: [],
+        failed: [],
+        corrupt: bad.message
+      });
+    }
+    for (const journal of journals) {
+      if (journal.state === "completed" || journal.state === "rolled-back") continue;
+      const report = await this.reconcileJournal(journal, probe);
+      if (report !== void 0) reports.push(report);
+    }
+    return reports.sort((a, b) => a.startedAt - b.startedAt || a.opId.localeCompare(b.opId));
+  }
+  /**
+   * Reconcile ONE non-terminal journal against the real disk. Returns
+   * undefined when the op's goal is already fully reached (auto-heals to the
+   * terminal state); otherwise a report of restored/pending/failed paths.
+   * For `running` journals the goal is the restore target; for
+   * `rollback-running` / `recovery-required` journals it is the rescue
+   * (pre-restore) state.
+   */
+  async reconcileJournal(journal, probe) {
+    const rollbackPhase = journal.state === "rollback-running" || journal.state === "recovery-required";
+    const restored = [];
+    const pending = [];
+    const failed = [];
+    let allReached = true;
+    for (const action of journal.actions) {
+      if (action.failed !== void 0) {
+        failed.push({ path: action.path, message: action.failed });
+        allReached = false;
+        continue;
+      }
+      let reached;
+      try {
+        const state = await probe.readText(action.path) ?? null;
+        const goal = rollbackPhase ? action.rescue : action.action === "delete" ? null : action.before;
+        reached = state === goal;
+      } catch {
+        reached = false;
+      }
+      if (reached) restored.push(action.path);
+      else pending.push(action.path);
+      if (!reached) allReached = false;
+    }
+    if (allReached && failed.length === 0) {
+      if (rollbackPhase) journal.state = "rolled-back";
+      else journal.state = "completed";
+      journal.finishedAt = Date.now();
+      await this.saveJournal(journal);
+      return void 0;
+    }
+    return {
+      opId: journal.id,
+      state: journal.state === "recovery-required" ? "recovery-required" : "interrupted",
+      journalState: journal.state,
+      targetSeq: journal.targetSeq,
+      startedAt: journal.startedAt,
+      restored,
+      pending,
+      failed,
+      ...journal.rollbackError === void 0 ? {} : { rollbackError: journal.rollbackError }
+    };
+  }
+  /**
+   * 补做 (redo) an interrupted restore: finish the op by applying every action
+   * whose disk state does not yet match its goal — the restore target for
+   * `running` journals. Actions are decided by the REAL disk (the same "disk
+   * is truth" rule as reconciliation), so a crash between an fs op and its
+   * done-mark is completed deterministically and a path the user already
+   * fixed is marked done without being rewritten. Failed actions are retried;
+   * a re-failure re-records the failure. The journal becomes `completed` once
+   * every action reaches the target.
+   */
+  async continueRestore(sessionId, opId, deleteFile, probe = defaultProbe, opts) {
+    const journal = await this.readJournal(sessionId, opId);
+    if (journal === void 0) throw new Error(`restore journal ${opId} not found for session ${sessionId}`);
+    if (journal.state !== "running") {
+      throw new Error(`restore journal ${opId} is in state ${journal.state}; only a running restore can be continued`);
+    }
+    const restored = [];
+    const deleted = [];
+    const failed = [];
+    for (let i = 0; i < journal.actions.length; i++) {
+      const action = journal.actions[i];
+      opts?.crash?.("before-action", i);
+      let reached;
+      try {
+        const state = await probe.readText(action.path) ?? null;
+        reached = state === (action.action === "delete" ? null : action.before);
+      } catch {
+        reached = false;
+      }
+      if (reached) {
+        action.done = true;
+        delete action.failed;
+        await this.saveJournal(journal);
+        continue;
+      }
+      let applied;
+      try {
+        applied = await this.applyActionToDisk(action.action, action.path, action.action === "restore" ? action.before : null, deleteFile);
+        if (applied === "enoent") {
+          action.done = true;
+          await this.saveJournal(journal);
+          continue;
+        }
+      } catch (error) {
+        action.failed = error instanceof Error ? error.message : String(error);
+        await this.saveJournal(journal);
+        failed.push({ path: action.path, message: action.failed });
+        continue;
+      }
+      opts?.crash?.("after-action", i);
+      action.done = true;
+      delete action.failed;
+      await this.saveJournal(journal);
+      if (applied === "restored") restored.push(action.path);
+      else deleted.push(action.path);
+    }
+    if (journal.actions.every((action) => action.done) && !journal.actions.some((action) => action.failed !== void 0)) {
+      journal.state = "completed";
+      journal.finishedAt = Date.now();
+      await this.saveJournal(journal);
+    }
+    return { restored, deleted, skipped: [], failed };
+  }
+  /**
+   * 回滚 (roll back) an interrupted restore: undo every action whose disk
+   * state does not match its rescue (pre-restore) record, returning the
+   * workspace to the exact state it had before the restore started. Decided
+   * by the REAL disk, so actions the crash left applied-but-unmarked are
+   * undone too, and a path already back at its rescue state is skipped —
+   * the pass is idempotent across crashes (a retry finishes the remaining
+   * actions). The journal moves `running` → `rollback-running` → `rolled-back`;
+   * a failed undo leaves it `recovery-required` (retryable), and paths whose
+   * rescue capture failed are reported and left untouched.
+   */
+  async rollbackRestore(sessionId, opId, deleteFile, probe = defaultProbe, opts) {
+    const journal = await this.readJournal(sessionId, opId);
+    if (journal === void 0) throw new Error(`restore journal ${opId} not found for session ${sessionId}`);
+    if (journal.state === "completed" || journal.state === "rolled-back") {
+      throw new Error(`restore journal ${opId} is already ${journal.state}`);
+    }
+    if (journal.state !== "rollback-running") {
+      journal.state = "rollback-running";
+      await this.saveJournal(journal);
+    }
+    const restored = [];
+    const deleted = [];
+    const failed = [];
+    let rollbackFailed = false;
+    for (let i = 0; i < journal.actions.length; i++) {
+      const action = journal.actions[i];
+      if (action.rescueError !== void 0) {
+        journal.rollbackError = `rescue unavailable for ${action.path}: ${action.rescueError}`;
+        journal.state = "recovery-required";
+        await this.saveJournal(journal);
+        failed.push({ path: action.path, message: journal.rollbackError });
+        rollbackFailed = true;
+        continue;
+      }
+      opts?.crash?.("before-action", i);
+      let reached;
+      try {
+        const state = await probe.readText(action.path) ?? null;
+        reached = state === action.rescue;
+      } catch {
+        reached = false;
+      }
+      if (reached) {
+        action.done = false;
+        await this.saveJournal(journal);
+        continue;
+      }
+      let applied;
+      try {
+        applied = await this.applyActionToDisk(action.rescue === null ? "delete" : "restore", action.path, action.rescue, deleteFile);
+        if (applied === "enoent") {
+          action.done = false;
+          await this.saveJournal(journal);
+          continue;
+        }
+      } catch (error) {
+        journal.rollbackError = error instanceof Error ? error.message : String(error);
+        journal.state = "recovery-required";
+        await this.saveJournal(journal);
+        failed.push({ path: action.path, message: journal.rollbackError });
+        rollbackFailed = true;
+        continue;
+      }
+      opts?.crash?.("after-action", i);
+      action.done = false;
+      await this.saveJournal(journal);
+      if (applied === "restored") restored.push(action.path);
+      else deleted.push(action.path);
+    }
+    if (!rollbackFailed) {
+      journal.state = "rolled-back";
+      journal.finishedAt = Date.now();
+      await this.saveJournal(journal);
+    }
+    return { restored, deleted, skipped: [], failed };
+  }
   /**
    * Drop the session's oldest anchor groups beyond `keep` (default
-   * {@link MAX_ANCHOR_GROUPS}), deleting their whole directories.
+   * {@link MAX_ANCHOR_GROUPS}), deleting their whole directories. Also
+   * recycles terminal restore journals (see {@link pruneTerminalJournals}),
+   * so the per-commit cap bounds BOTH the checkpoint entries and the journal
+   * accumulation.
    */
   async prune(sessionId, keep = MAX_ANCHOR_GROUPS) {
     const sessionDir = this.sessionDir(sessionId);
@@ -423,6 +850,7 @@ var SnapshotStore = class _SnapshotStore {
       if (error.code === "ENOENT") return;
       throw error;
     }
+    await this.pruneTerminalJournals(sessionDir, names);
     const seqs = names.map(Number).filter((seq) => Number.isSafeInteger(seq)).sort((a, b) => a - b);
     const excess = seqs.length - keep;
     if (excess <= 0) return;
@@ -430,6 +858,27 @@ var SnapshotStore = class _SnapshotStore {
       await rm(this.anchorDir(sessionId, seq), { recursive: true, force: true });
     }
   }
+  /**
+   * Recycle terminal restore journals (`completed` / `rolled-back`): once an
+   * op finished, its journal's before + rescue content is dead weight that
+   * would otherwise accumulate without bound (one journal per both-mode
+   * rewind). Non-terminal journals (crashed ops awaiting reconcile /
+   * continue / rollback) and unclassifiable (corrupt) ones are ALWAYS kept —
+   * a recovery record that cannot be classified is never destroyed.
+   */
+  async pruneTerminalJournals(sessionDir, names) {
+    for (const name2 of names) {
+      if (!name2.startsWith(_SnapshotStore.JOURNAL_PREFIX) || !name2.endsWith(".json")) continue;
+      const file = join(sessionDir, name2);
+      try {
+        const parsed = JSON.parse(await readFile(file, "utf8"));
+        if (parsed.state === "completed" || parsed.state === "rolled-back") {
+          await rm(file, { force: true });
+        }
+      } catch {
+      }
+    }
+  }
   /** True when a path exists on disk (used by tests and diagnostics). */
   async exists(path) {
     try {

package/lib/types/client/candidates.d.ts

@@ -18,11 +18,12 @@ export declare const PREVIEW_CHARS = 80;
 /**
  * Default cap on how many user messages the rewind picker lists (newest kept).
  *
- * A fixed 10 made long sessions look "incomplete" (only the newest 10 shown).
- * 50 keeps the picker scrollable/searchable via the popupSelect shell while
- * covering far longer sessions; callers can still pass an explicit `limit`.
+ * Matches the snapshot store's MAX_ANCHOR_GROUPS (100), so the picker shows
+ * every anchor group that can still restore file backups; 100 stays
+ * scrollable/searchable via the popupSelect shell, and callers can still
+ * pass an explicit `limit`.
  */
-export declare const DEFAULT_CANDIDATE_LIMIT = 50;
+export declare const DEFAULT_CANDIDATE_LIMIT = 100;
 /** One selectable rewind target. */
 export interface RewindCandidate {
     /** Absolute log seq of the `user/message` event. */

package/lib/types/index.d.ts

@@ -26,7 +26,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 export { SnapshotStore } from './snapshot.ts';
-export type { CheckpointEntry, FileImpact, RestoreOutcome } from './snapshot.ts';
+export type { CheckpointEntry, FileImpact, RestoreOutcome, RestoreJournal, RestoreJournalState, RestoreReconcileReport } from './snapshot.ts';
 export declare const name = "dsh-rewind";
 export declare const inject: string[];
 /** Plugin config: optional override of the checkpoint store root. */