dsh-rewind-plugin 0.4.1 → 0.5.0

package/lib/index.js

@@ -30,7 +30,24 @@ var en = {
   "success": "Withdrawn seq {targetSeq} and everything after it (conversation returned to earlier){restore}.",
   "noUserMessages": "This session has no rewindable user messages yet.",
   "chooseMode": "Rewind to {target}. Choose a mode:\n  /rewind {target} chat  conversation only\n  /rewind {target} both  conversation + file restore",
-  "command.description": "Rewind the conversation back to an earlier user message (optionally restoring files)"
+  "command.description": "Rewind the conversation back to an earlier user message (optionally restoring files)",
+  "cleanup.description": "Manage automatic cleanup of session snapshot backups",
+  "cleanup.inputHint": "on | off | max-age <days> | run [--apply] | status",
+  "cleanup.status": "Auto-cleanup: {state}. Max age: {days} day(s). Config: {path} ({present}).",
+  "cleanup.enabled": "enabled",
+  "cleanup.disabled": "disabled",
+  "cleanup.present": "file present",
+  "cleanup.absent": "no file \u2014 defaults",
+  "cleanup.onOk": "Auto-cleanup enabled.",
+  "cleanup.offOk": "Auto-cleanup disabled \u2014 all snapshots kept.",
+  "cleanup.maxAgeOk": "Auto-cleanup max age set to {days} day(s).",
+  "cleanup.cfgInvalid": "Snapshot cleanup config invalid: {detail}. Using the safe default (disabled).",
+  "cleanup.saveFailed": "Could not save cleanup config: {detail}.",
+  "cleanup.runDry": "Dry-run: would remove {deleted} session snapshot backup(s). Re-run with --apply to delete.",
+  "cleanup.runApply": "Removed {deleted} session snapshot backup(s), freeing {freed} bytes; {kept} kept, {remaining} bytes remain.",
+  "cleanup.runFailed": "Cleanup failed: {detail}.",
+  "cleanup.skipped": "({skipped} active session(s) skipped.)",
+  "cleanup.usage": "Usage:\n  /snapshot-auto-cleanup                 show status\n  /snapshot-auto-cleanup on|off          enable/disable auto-cleanup\n  /snapshot-auto-cleanup max-age <days>  set the idle cutoff\n  /snapshot-auto-cleanup run [--apply]   dry-run, or execute with --apply"
 };
 var zh = {
   "usage.title": "\u7528\u6CD5\uFF1A",
@@ -58,7 +75,24 @@ var zh = {
   "success": "\u5DF2\u64A4\u56DE seq {targetSeq} \u53CA\u4E4B\u540E\u5185\u5BB9\uFF08\u5BF9\u8BDD\u5DF2\u56DE\u5230\u6B64\u524D\uFF09{restore}\u3002",
   "noUserMessages": "\u5F53\u524D\u4F1A\u8BDD\u8FD8\u6CA1\u6709\u53EF\u56DE\u9000\u7684\u7528\u6237\u6D88\u606F\u3002",
   "chooseMode": "\u5C06\u56DE\u9000\u5230 {target}\u3002\u9009\u62E9\u6A21\u5F0F\uFF1A\n  /rewind {target} chat  \u4EC5\u56DE\u9000\u5BF9\u8BDD\n  /rewind {target} both  \u56DE\u9000\u5BF9\u8BDD\u5E76\u8FD8\u539F\u6587\u4EF6",
-  "command.description": "\u5728\u540C\u7A97\u53E3\u5185\u5C06\u5BF9\u8BDD\u56DE\u9000\u5230\u66F4\u65E9\u7684\u7528\u6237\u6D88\u606F\uFF08\u53EF\u540C\u65F6\u8FD8\u539F\u6587\u4EF6\uFF09"
+  "command.description": "\u5728\u540C\u7A97\u53E3\u5185\u5C06\u5BF9\u8BDD\u56DE\u9000\u5230\u66F4\u65E9\u7684\u7528\u6237\u6D88\u606F\uFF08\u53EF\u540C\u65F6\u8FD8\u539F\u6587\u4EF6\uFF09",
+  "cleanup.description": "\u7BA1\u7406\u4F1A\u8BDD\u5FEB\u7167\u5907\u4EFD\u7684\u81EA\u52A8\u6E05\u7406",
+  "cleanup.inputHint": "on | off | max-age <\u5929\u6570> | run [--apply] | status",
+  "cleanup.status": "\u81EA\u52A8\u6E05\u7406\uFF1A{state}\u3002\u6700\u5927\u4FDD\u7559\u5929\u6570\uFF1A{days} \u5929\u3002\u914D\u7F6E\uFF1A{path}\uFF08{present}\uFF09\u3002",
+  "cleanup.enabled": "\u5DF2\u5F00\u542F",
+  "cleanup.disabled": "\u5DF2\u5173\u95ED",
+  "cleanup.present": "\u5B58\u5728\u914D\u7F6E\u6587\u4EF6",
+  "cleanup.absent": "\u65E0\u6587\u4EF6\u2014\u2014\u4F7F\u7528\u9ED8\u8BA4\u503C",
+  "cleanup.onOk": "\u5DF2\u5F00\u542F\u81EA\u52A8\u6E05\u7406\u3002",
+  "cleanup.offOk": "\u5DF2\u5173\u95ED\u81EA\u52A8\u6E05\u7406\u2014\u2014\u4FDD\u7559\u5168\u90E8\u5FEB\u7167\u3002",
+  "cleanup.maxAgeOk": "\u5DF2\u5C06\u81EA\u52A8\u6E05\u7406\u7684\u6700\u5927\u4FDD\u7559\u5929\u6570\u8BBE\u4E3A {days} \u5929\u3002",
+  "cleanup.cfgInvalid": "\u5FEB\u7167\u6E05\u7406\u914D\u7F6E\u65E0\u6548\uFF1A{detail}\u3002\u5DF2\u4F7F\u7528\u5B89\u5168\u9ED8\u8BA4\u503C\uFF08\u5173\u95ED\uFF09\u3002",
+  "cleanup.saveFailed": "\u65E0\u6CD5\u4FDD\u5B58\u6E05\u7406\u914D\u7F6E\uFF1A{detail}\u3002",
+  "cleanup.runDry": "\u9884\u6F14\uFF1A\u5C06\u5220\u9664 {deleted} \u4E2A\u4F1A\u8BDD\u7684\u5FEB\u7167\u5907\u4EFD\u3002\u52A0 --apply \u6B63\u5F0F\u5220\u9664\u3002",
+  "cleanup.runApply": "\u5DF2\u5220\u9664 {deleted} \u4E2A\u4F1A\u8BDD\u7684\u5FEB\u7167\u5907\u4EFD\uFF0C\u91CA\u653E {freed} \u5B57\u8282\uFF1B\u4FDD\u7559 {kept} \u4E2A\uFF0C\u5269\u4F59 {remaining} \u5B57\u8282\u3002",
+  "cleanup.runFailed": "\u6E05\u7406\u5931\u8D25\uFF1A{detail}\u3002",
+  "cleanup.skipped": "\uFF08\u8DF3\u8FC7\u4E86 {skipped} \u4E2A\u6D3B\u52A8\u4F1A\u8BDD\u3002\uFF09",
+  "cleanup.usage": "\u7528\u6CD5\uFF1A\n  /snapshot-auto-cleanup                 \u67E5\u770B\u72B6\u6001\n  /snapshot-auto-cleanup on|off          \u5F00\u542F/\u5173\u95ED\u81EA\u52A8\u6E05\u7406\n  /snapshot-auto-cleanup max-age <\u5929\u6570>  \u8BBE\u7F6E\u5931\u6D3B\u9608\u503C\uFF08\u5929\uFF09\n  /snapshot-auto-cleanup run [--apply]   \u9884\u6F14\uFF0C\u6216\u52A0 --apply \u6267\u884C"
 };
 var HOST_DICTS = { en, zh };
 function translate(lang, key, params = {}) {
@@ -80,7 +114,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,12 +229,15 @@ 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");
 var SNAPSHOT_ROOT_ENV = "DSH_REWIND_SNAPSHOT_DIR";
 var MAX_ANCHOR_GROUPS = 100;
+function isLinkEntry(entry) {
+  return "ref" in entry;
+}
 var defaultProbe = {
   async readText(path) {
     try {
@@ -219,17 +256,42 @@ 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"));
     if (typeof parsed.path !== "string" || typeof parsed.anchorSeq !== "number") return void 0;
-    return {
+    const base = {
       callId: String(parsed.callId ?? ""),
       anchorSeq: parsed.anchorSeq,
       path: parsed.path,
-      before: typeof parsed.before === "string" ? parsed.before : null,
       time: typeof parsed.time === "number" ? parsed.time : 0
     };
+    if (typeof parsed.ref === "string") {
+      return { ...base, ref: parsed.ref };
+    }
+    return {
+      ...base,
+      before: typeof parsed.before === "string" ? parsed.before : null
+    };
   } catch {
     return void 0;
   }
@@ -242,14 +304,72 @@ async function isLinkPath(path) {
     return false;
   }
 }
+function isSafeLinkRef(ref) {
+  return /^[0-9]+\/[a-zA-Z0-9._-]+\.json$/.test(ref);
+}
+async function dirSizeAndLastActive(dir) {
+  let size = 0;
+  let lastActiveMs = 0;
+  const visit = async (current) => {
+    let st;
+    try {
+      st = await lstat(current);
+    } catch {
+      return;
+    }
+    if (st.mtimeMs > lastActiveMs) lastActiveMs = st.mtimeMs;
+    if (!st.isDirectory()) {
+      size += st.size;
+      return;
+    }
+    let names;
+    try {
+      names = await readdir(current);
+    } catch {
+      return;
+    }
+    for (const name2 of names) {
+      if (name2.startsWith(".")) continue;
+      await visit(join(current, name2));
+    }
+  };
+  await visit(dir);
+  return { size, lastActiveMs };
+}
 var SnapshotStore = class _SnapshotStore {
-  constructor(root = process.env[SNAPSHOT_ROOT_ENV] ?? DEFAULT_SNAPSHOT_ROOT) {
+  constructor(root = process.env[SNAPSHOT_ROOT_ENV] ?? DEFAULT_SNAPSHOT_ROOT, opts) {
     this.root = root;
+    this.dedup = opts?.dedup ?? true;
   }
   root;
   /** 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;
+  /** Store options; `dedup` toggles in-place content dedup (default on). */
+  dedup;
+  /**
+   * In-memory per-path "most recent entry" for content dedup, keyed by
+   * `<sessionId>\0<path>`. Each value holds the entry's effective `before`
+   * content and its own file ref, so a new record with the same content links
+   * to the immediately-prior entry (linear chain). Seeded lazily per session
+   * from the bounded on-disk window, so dedup survives a host restart.
+   */
+  lastEntry = /* @__PURE__ */ new Map();
+  /** Sessions whose dedup state has been seeded from disk this process. */
+  seededSessions = /* @__PURE__ */ new Set();
   /** Absolute path of one session's snapshot directory (id sanitized). */
   sessionDir(sessionId) {
     return join(this.root, safeSessionId(sessionId));
@@ -258,18 +378,91 @@ 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) {
+  /** Absolute file ref (relative to the session dir) of an entry. */
+  entryRefOf(sessionId, callId, anchorSeq) {
+    return `${anchorSeq}/${safeFileId(callId)}.json`;
+  }
+  /**
+   * Seed a session's dedup state from the existing (bounded) on-disk window:
+   * scan entries newest-first and record the most recent entry per path. This
+   * makes content dedup survive a host restart within the session window. A
+   * no-op after the first seed (or when `dedup` is disabled).
+   */
+  async ensureDedupSeeded(sessionId) {
+    if (!this.dedup || this.seededSessions.has(sessionId)) return;
+    this.seededSessions.add(sessionId);
+    try {
+      for (const entry of await this.entriesAfter(sessionId, 0)) {
+        const key = `${sessionId}\0${entry.path}`;
+        if (this.lastEntry.has(key)) continue;
+        const content = await this.resolveBefore(sessionId, entry);
+        this.lastEntry.set(key, { content, ref: this.entryRefOf(sessionId, entry.callId, entry.anchorSeq) });
+      }
+    } catch {
+      this.seededSessions.delete(sessionId);
+    }
+  }
+  /**
+   * Resolve an entry's effective `before` content, following a link chain to
+   * its terminal real snapshot. Refs are strictly backward in
+   * `(anchorSeq, time)`, so the chain is acyclic and finite. A dangling or
+   * cyclic link throws — callers fail per-file (never silently dropping the
+   * path from a restore).
+   */
+  async resolveBefore(sessionId, entry, seen = /* @__PURE__ */ new Set()) {
+    if (!isLinkEntry(entry)) return entry.before;
+    const key = `${entry.anchorSeq}:${entry.callId}`;
+    if (seen.has(key)) throw new Error(`link cycle at ${entry.path} (${key})`);
+    seen.add(key);
+    if (!isSafeLinkRef(entry.ref)) throw new Error(`unsafe link ref ${entry.ref} for ${entry.path}`);
+    const referenced = await readEntry(join(this.sessionDir(sessionId), entry.ref));
+    if (referenced === void 0) throw new Error(`dangling link ${entry.ref} for ${entry.path}`);
+    return this.resolveBefore(sessionId, referenced, seen);
+  }
+  /** Commit one before-backup (or an in-place dedup link) under its anchor. */
+  async recordEntry(sessionId, entry, opts) {
+    const time = Math.max(Date.now(), this.lastEntryTime + 1);
+    this.lastEntryTime = time;
+    await this.ensureDedupSeeded(sessionId);
     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 file = join(dir, `${safeFileId(entry.callId)}.json`);
+    const selfRef = this.entryRefOf(sessionId, entry.callId, entry.anchorSeq);
+    const key = `${sessionId}\0${entry.path}`;
+    const prior = this.lastEntry.get(key);
+    if (this.dedup && opts?.dedup !== false && prior !== void 0 && prior.content === entry.before) {
+      const committed = {
+        callId: entry.callId,
+        anchorSeq: entry.anchorSeq,
+        path: entry.path,
+        ref: prior.ref,
+        time
+      };
+      await writeJsonAtomic(file, committed, () => opts?.crash?.("after-temp-write"));
+      this.lastEntry.set(key, { content: prior.content, ref: selfRef });
+    } else {
+      const committed = { ...entry, time };
+      await writeJsonAtomic(file, committed, () => opts?.crash?.("after-temp-write"));
+      this.lastEntry.set(key, { content: entry.before, ref: selfRef });
+    }
     const now = Date.now();
     if (now - this.lastPruneAt >= _SnapshotStore.PRUNE_INTERVAL_MS) {
       this.lastPruneAt = now;
       await this.prune(sessionId);
     }
   }
+  /**
+   * The effective content recorded by the path's MOST RECENT entry, or
+   * undefined when the path has never been recorded (a fresh tracking sight).
+   * This is the single in-memory "last known state" the boundary uses to
+   * decide whether a tracked file changed — the same source `recordEntry`
+   * dedups against, so there is one content copy and one comparison per
+   * decision, not two. Seeding is idempotent (once per session from disk).
+   */
+  async lastKnownContent(sessionId, path) {
+    await this.ensureDedupSeeded(sessionId);
+    return this.lastEntry.get(`${sessionId}\0${path}`)?.content;
+  }
   /**
    * All committed entries anchored at or after `targetSeq`, newest first (for
    * preview ordering). The boundary is inclusive: rewinding to a message also
@@ -339,32 +532,46 @@ var SnapshotStore = class _SnapshotStore {
    * @param sessionId - session whose snapshot store to plan against.
    * @param targetSeq - rewind target; entries anchored at/after it apply.
    * @param probe - current-disk state probe (defaults to the real FS).
-   * @returns the planned actions plus the link paths that were skipped.
+   * @returns the planned actions, the link paths skipped, and per-file failures.
    */
   async planRestore(sessionId, targetSeq, probe) {
     const actions = [];
     const skipped = [];
+    const failed = [];
     for (const entry of (await this.earliestEntries(sessionId, targetSeq)).values()) {
       try {
         if (await probe.isLink(entry.path)) {
           skipped.push(entry.path);
           continue;
         }
+        let before;
+        try {
+          before = await this.resolveBefore(sessionId, entry);
+        } catch (error) {
+          failed.push({ path: entry.path, message: error instanceof Error ? error.message : String(error) });
+          continue;
+        }
         const current = await probe.readText(entry.path);
-        if (entry.before === null) {
+        if (before === null) {
           if (current !== void 0) actions.push({ path: entry.path, action: "delete" });
-        } else if (current !== entry.before) {
-          actions.push({ path: entry.path, action: "restore", before: entry.before });
+        } else if (current !== before) {
+          actions.push({ path: entry.path, action: "restore", before });
         }
       } catch (error) {
-        if (entry.before === null) {
+        let before;
+        try {
+          before = await this.resolveBefore(sessionId, entry);
+        } catch {
+          before = null;
+        }
+        if (before === null) {
           actions.push({ path: entry.path, action: "delete" });
         } else {
-          actions.push({ path: entry.path, action: "restore", before: entry.before });
+          actions.push({ path: entry.path, action: "restore", before });
         }
       }
     }
-    return { actions, skipped };
+    return { actions, skipped, failed };
   }
   /** Per-file restore impact: only actions that would actually change the disk. */
   async impactsAfter(sessionId, targetSeq, probe = defaultProbe) {
@@ -381,40 +588,441 @@ 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);
+    const { actions, skipped: skippedPaths, failed: planFailed } = await this.planRestore(sessionId, targetSeq, probe);
     skipped.push(...skippedPaths);
-    for (const action of actions) {
+    failed.push(...planFailed);
+    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.
+   *
+   * Because dedup links reference prior entries, eviction is LINK-AWARE: before
+   * deleting the oldest groups, any SURVIVING (kept-group) link whose `ref`
+   * lands on a real snapshot inside a doomed group is MATERIALIZED (rewritten
+   * as a real snapshot carrying the resolved content), so no kept link is left
+   * dangling. Links form a linear predecessor chain, so materializing the first
+   * link after each doomed real is enough — later links already point at that
+   * materialized entry (or at other kept links), requiring no rewrite.
+   *
+   * `opts.crash` is the test-only seam: a crash fired inside a materialization
+   * write (between its temp write and rename) leaves ONLY a `.tmp` — the doomed
+   * real is still on disk and the kept link still resolves, so nothing dangles
+   * and a later prune simply re-materializes.
    */
-  async prune(sessionId, keep = MAX_ANCHOR_GROUPS) {
+  async prune(sessionId, keep = MAX_ANCHOR_GROUPS, opts) {
     const sessionDir = this.sessionDir(sessionId);
     let names;
     try {
@@ -423,13 +1031,62 @@ 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;
-    for (const seq of seqs.slice(0, excess)) {
+    const doomed = new Set(seqs.slice(0, excess));
+    for (const seq of seqs.slice(excess)) {
+      const files = await readdir(this.anchorDir(sessionId, seq)).catch(() => []);
+      for (const file of files) {
+        if (!file.endsWith(".json")) continue;
+        const entry = await readEntry(join(this.anchorDir(sessionId, seq), file));
+        if (entry === void 0 || !isLinkEntry(entry)) continue;
+        if (!isSafeLinkRef(entry.ref)) continue;
+        const slash = entry.ref.indexOf("/");
+        const refAnchor = slash === -1 ? Number.NaN : Number(entry.ref.slice(0, slash));
+        if (!Number.isSafeInteger(refAnchor) || !doomed.has(refAnchor)) continue;
+        let before;
+        try {
+          before = await this.resolveBefore(sessionId, entry);
+        } catch {
+          continue;
+        }
+        const real = {
+          callId: entry.callId,
+          anchorSeq: entry.anchorSeq,
+          path: entry.path,
+          before,
+          time: entry.time
+        };
+        await writeJsonAtomic(join(this.anchorDir(sessionId, seq), file), real, () => opts?.crash?.("after-temp-write"));
+      }
+    }
+    for (const seq of doomed) {
       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 {
@@ -440,6 +1097,77 @@ var SnapshotStore = class _SnapshotStore {
       throw error;
     }
   }
+  /**
+   * Cross-session retention sweep: remove WHOLE session directories whose
+   * newest member stamp is older than `maxAgeDays` days of idle, keeping the
+   * active session (`keepActiveId`) untouched. This is the anti-growth policy
+   * for finished sessions (rewind only ever reads the active session, so a
+   * finished session's backups are provably dead weight).
+   *
+   * SAFETY:
+   *  - Only whole session directories are removed (dedup refs are
+   *    session-relative, so there is no cross-session dangling to materialize);
+   *  - the active session is never targeted (`keepActiveId`), and everything
+   *    else is protected by its own mtime — a session that is still written to
+   *    keeps scrolling its newest member stamp forward, so it is never old
+   *    enough to be pruned;
+   *  - a non-positive `maxAgeDays` throws instead of degenerating into a
+   *    mass-destructive `cutoff` in the far future;
+   *  - the walk uses `lstat` (no symlink following) and skips dot-prefixed
+   *    temp left overs, so measurement stays inside the store root.
+   *
+   * `dryRun` computes and reports exactly what would be removed without
+   * deleting anything — the `/snapshot-auto-cleanup run` preview.
+   */
+  async pruneStale(opts) {
+    const { keepActiveId, dryRun = false } = opts;
+    const maxAgeDays = opts.maxAgeDays;
+    if (!Number.isFinite(maxAgeDays) || maxAgeDays <= 0) {
+      throw new RangeError("pruneStale: maxAgeDays must be a positive finite number");
+    }
+    const cutoffMs = Date.now() - maxAgeDays * 864e5;
+    let scanned = 0;
+    let deleted = 0;
+    let freedBytes = 0;
+    let kept = 0;
+    let skippedActive = 0;
+    let remainingBytes = 0;
+    const report = () => ({ scanned, deleted, freedBytes, kept, remainingBytes, skippedActive, dryRun });
+    let names;
+    try {
+      names = await readdir(this.root);
+    } catch (error) {
+      if (error.code === "ENOENT") return report();
+      throw error;
+    }
+    for (const name2 of names) {
+      if (name2.startsWith(".")) continue;
+      const full = join(this.root, name2);
+      let st;
+      try {
+        st = await lstat(full);
+      } catch {
+        continue;
+      }
+      if (!st.isDirectory()) continue;
+      scanned++;
+      if (keepActiveId !== void 0 && safeSessionId(keepActiveId) === name2) {
+        skippedActive++;
+        remainingBytes += (await dirSizeAndLastActive(full)).size;
+        continue;
+      }
+      const { size, lastActiveMs } = await dirSizeAndLastActive(full);
+      if (lastActiveMs < cutoffMs) {
+        deleted++;
+        freedBytes += size;
+        if (!dryRun) await rm(full, { recursive: true, force: true });
+      } else {
+        kept++;
+        remainingBytes += size;
+      }
+    }
+    return report();
+  }
   /**
    * All distinct paths ever recorded for a session — the "tracked files"
    * set. Mirrors Claude Code's global `trackedFiles` collection (files stay
@@ -457,22 +1185,21 @@ var SnapshotStore = class _SnapshotStore {
 function hashPath(path) {
   return createHash("sha256").update(path).digest("hex").slice(0, 8);
 }
-async function reconcileTracked(store, sessionId, anchorSeq, tracked, states, probe = defaultProbe) {
+async function reconcileTracked(store, sessionId, anchorSeq, tracked, probe = defaultProbe) {
   let recorded = 0;
   for (const path of tracked) {
     try {
       if (await probe.isLink(path)) continue;
       const current = await probe.readText(path);
       const state = current ?? null;
-      const prev = states.get(path);
-      if (prev === void 0 || prev !== state) {
+      const last = await store.lastKnownContent(sessionId, path);
+      if (last === void 0 || last !== state) {
         await store.recordEntry(sessionId, {
           callId: `recheck-${anchorSeq}-${hashPath(path)}`,
           anchorSeq,
           path,
           before: state
-        });
-        states.set(path, state);
+        }, { dedup: false });
         recorded++;
       }
     } catch {
@@ -481,6 +1208,130 @@ async function reconcileTracked(store, sessionId, anchorSeq, tracked, states, pr
   return recorded;
 }
 
+// src/snapshot-cleanup.ts
+import { mkdir as mkdir2, readFile as readFile2, rename as rename2, writeFile as writeFile2 } from "node:fs/promises";
+import { dirname as dirname2, join as join2 } from "node:path";
+import { homedir as homedir2 } from "node:os";
+var CLEANUP_CONFIG_FILENAME = "snapshot-cleanup.json";
+var CLEANUP_CONFIG_ENV = "DSH_SNAPSHOT_CLEANUP_CONFIG";
+var DEFAULT_MAX_AGE_DAYS = 30;
+var DEFAULT_CLEANUP_CONFIG = { enabled: false, maxAgeDays: DEFAULT_MAX_AGE_DAYS };
+var AUTO_SWEEP_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+function resolveCleanupConfigPath() {
+  return process.env[CLEANUP_CONFIG_ENV] ?? join2(homedir2(), ".dsh", CLEANUP_CONFIG_FILENAME);
+}
+var STATE_FILENAME = "snapshot-cleanup-last-sweep.json";
+function resolveCleanupStatePath() {
+  return join2(dirname2(resolveCleanupConfigPath()), STATE_FILENAME);
+}
+async function loadLastSweepAt(path) {
+  try {
+    const raw = JSON.parse(await readFile2(path, "utf8"));
+    const value = raw["lastSweepAt"];
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+  } catch {
+    return 0;
+  }
+}
+async function saveLastSweepAt(path, ms) {
+  const tmp = `${path}.tmp`;
+  await mkdir2(dirname2(path), { recursive: true });
+  await writeFile2(tmp, JSON.stringify({ lastSweepAt: ms }), "utf8");
+  await rename2(tmp, path);
+}
+async function runAutoCleanupCheck(deps, sessionId) {
+  try {
+    const loaded = await loadCleanupConfig(deps.configPath);
+    if (!loaded.ok) {
+      deps.log(`[dsh-rewind] snapshot cleanup config invalid; auto-cleanup skipped: ${loaded.error}`);
+      return;
+    }
+    if (!loaded.config.enabled) return;
+    if (!shouldRunAutoSweep(await loadLastSweepAt(deps.statePath), Date.now())) return;
+    await deps.pruner.pruneStale({ keepActiveId: sessionId, maxAgeDays: loaded.config.maxAgeDays });
+    await saveLastSweepAt(deps.statePath, Date.now());
+  } catch (error) {
+    deps.log(`[dsh-rewind] snapshot auto-cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+function parseCleanupConfig(raw) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    return { ok: false, error: "config must be a JSON object" };
+  }
+  const record = raw;
+  let enabled = DEFAULT_CLEANUP_CONFIG.enabled;
+  let maxAgeDays = DEFAULT_CLEANUP_CONFIG.maxAgeDays;
+  if (record["enabled"] !== void 0) {
+    if (typeof record["enabled"] !== "boolean") return { ok: false, error: '"enabled" must be a boolean' };
+    enabled = record["enabled"];
+  }
+  if (record["maxAgeDays"] !== void 0) {
+    const value = record["maxAgeDays"];
+    if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
+      return { ok: false, error: '"maxAgeDays" must be a positive integer' };
+    }
+    maxAgeDays = value;
+  }
+  return { ok: true, config: { enabled, maxAgeDays } };
+}
+async function loadCleanupConfig(path) {
+  let text;
+  try {
+    text = await readFile2(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { ok: true, config: { ...DEFAULT_CLEANUP_CONFIG }, fromFile: false };
+    }
+    return { ok: false, error: `config file unreadable: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (error) {
+    return { ok: false, error: `config file is not valid JSON: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  const parsed = parseCleanupConfig(raw);
+  if (!parsed.ok) return { ok: false, error: parsed.error };
+  return { ok: true, config: parsed.config, fromFile: true };
+}
+async function saveCleanupConfig(path, config) {
+  if (typeof config.enabled !== "boolean" || !Number.isInteger(config.maxAgeDays) || config.maxAgeDays <= 0) {
+    throw new RangeError("invalid cleanup config: enabled must be a boolean and maxAgeDays a positive integer");
+  }
+  const tmp = `${path}.tmp`;
+  await mkdir2(dirname2(path), { recursive: true });
+  await writeFile2(tmp, JSON.stringify(config, null, 2), "utf8");
+  await rename2(tmp, path);
+}
+function parseCleanupCommand(rawInput) {
+  const parts = rawInput.trim().split(/\s+/).filter(Boolean);
+  if (parts.length === 0) return { action: "status" };
+  switch (parts[0]) {
+    case "status":
+      return parts.length === 1 ? { action: "status" } : { error: "usage: /snapshot-auto-cleanup status" };
+    case "on":
+      return parts.length === 1 ? { action: "on" } : { error: "usage: /snapshot-auto-cleanup on" };
+    case "off":
+      return parts.length === 1 ? { action: "off" } : { error: "usage: /snapshot-auto-cleanup off" };
+    case "max-age": {
+      if (parts.length !== 2) return { error: "usage: /snapshot-auto-cleanup max-age <days>" };
+      const days = Number(parts[1]);
+      if (!Number.isInteger(days) || days <= 0) return { error: '"max-age" must be a positive integer (days)' };
+      return { action: "max-age", value: days };
+    }
+    case "run": {
+      if (parts.length === 1) return { action: "run" };
+      if (parts.length === 2 && parts[1] === "--apply") return { action: "run-apply" };
+      return { error: "usage: /snapshot-auto-cleanup run [--apply]" };
+    }
+    default:
+      return { error: `unknown /snapshot-auto-cleanup subcommand "${parts[0]}"` };
+  }
+}
+function shouldRunAutoSweep(lastAtMs, nowMs) {
+  return nowMs - lastAtMs >= AUTO_SWEEP_INTERVAL_MS;
+}
+
 // src/index.ts
 var name = "dsh-rewind";
 var inject = ["commands", "tools"];
@@ -788,13 +1639,91 @@ async function handleRewind(ctx, store, fs, invocation, inflight) {
   }
   return executeRewind(ctx, store, fs, invocation, target, mode, inflight);
 }
+var autoSweepChecked = false;
+async function maybeRunAutoCleanup(ctx, store, sessionId) {
+  if (autoSweepChecked) return;
+  autoSweepChecked = true;
+  await runAutoCleanupCheck({
+    pruner: store,
+    configPath: resolveCleanupConfigPath(),
+    statePath: resolveCleanupStatePath(),
+    log: (msg) => ctx.logger.warn(msg)
+  }, sessionId);
+}
+function formatCleanupReport(report) {
+  const key = report.dryRun ? "cleanup.runDry" : "cleanup.runApply";
+  const text = t(key, {
+    deleted: report.deleted,
+    freed: report.freedBytes,
+    kept: report.kept,
+    remaining: report.remainingBytes
+  });
+  return report.skippedActive > 0 ? `${text}
+${t("cleanup.skipped", { skipped: report.skippedActive })}` : text;
+}
+async function handleSnapshotCleanup(store, invocation) {
+  const parsed = parseCleanupCommand(invocation.rawInput);
+  if ("error" in parsed) return { kind: "error", text: t("cleanup.usage") };
+  const configPath = resolveCleanupConfigPath();
+  switch (parsed.action) {
+    case "status": {
+      const loaded = await loadCleanupConfig(configPath);
+      if (!loaded.ok) return { kind: "error", text: t("cleanup.cfgInvalid", { detail: loaded.error }) };
+      return {
+        kind: "success",
+        text: t("cleanup.status", {
+          state: t(loaded.config.enabled ? "cleanup.enabled" : "cleanup.disabled"),
+          days: loaded.config.maxAgeDays,
+          path: configPath,
+          present: t(loaded.fromFile ? "cleanup.present" : "cleanup.absent")
+        })
+      };
+    }
+    case "on":
+    case "off": {
+      const loaded = await loadCleanupConfig(configPath);
+      const next = { ...loaded.ok ? loaded.config : DEFAULT_CLEANUP_CONFIG, enabled: parsed.action === "on" };
+      try {
+        await saveCleanupConfig(configPath, next);
+      } catch (error) {
+        return { kind: "error", text: t("cleanup.saveFailed", { detail: error instanceof Error ? error.message : String(error) }) };
+      }
+      return { kind: "success", text: t(parsed.action === "on" ? "cleanup.onOk" : "cleanup.offOk") };
+    }
+    case "max-age": {
+      const loaded = await loadCleanupConfig(configPath);
+      const next = { ...loaded.ok ? loaded.config : DEFAULT_CLEANUP_CONFIG, maxAgeDays: parsed.value };
+      try {
+        await saveCleanupConfig(configPath, next);
+      } catch (error) {
+        return { kind: "error", text: t("cleanup.saveFailed", { detail: error instanceof Error ? error.message : String(error) }) };
+      }
+      return { kind: "success", text: t("cleanup.maxAgeOk", { days: parsed.value }) };
+    }
+    case "run":
+    case "run-apply": {
+      const loaded = await loadCleanupConfig(configPath);
+      if (!loaded.ok) return { kind: "error", text: t("cleanup.cfgInvalid", { detail: loaded.error }) };
+      try {
+        const report = await store.pruneStale({
+          keepActiveId: invocation.agent.session.id,
+          maxAgeDays: loaded.config.maxAgeDays,
+          dryRun: parsed.action === "run"
+        });
+        if (!report.dryRun) await saveLastSweepAt(resolveCleanupStatePath(), Date.now());
+        return { kind: "success", text: formatCleanupReport(report) };
+      } catch (error) {
+        return { kind: "error", text: t("cleanup.runFailed", { detail: error instanceof Error ? error.message : String(error) }) };
+      }
+    }
+  }
+}
 function apply(ctx, config) {
-  const store = new SnapshotStore(config?.snapshotDir);
+  const store = new SnapshotStore(config?.snapshotDir, { dedup: config?.dedup });
   const pending = /* @__PURE__ */ new Map();
   const anchorCache = /* @__PURE__ */ new WeakMap();
   const inflight = /* @__PURE__ */ new Set();
   const trackedBySession = /* @__PURE__ */ new Map();
-  const statesBySession = /* @__PURE__ */ new Map();
   let fsService;
   ctx.inject(["settings"], (settingsCtx) => {
     const section = settingsCtx.settings.get(settingsNamespace("locale"));
@@ -808,6 +1737,12 @@ function apply(ctx, config) {
       description: t("command.description"),
       handler: (invocation) => handleRewind(ctx, store, fsService, invocation, inflight)
     });
+    yield ctx.commands.register({
+      name: "snapshot-auto-cleanup",
+      description: t("cleanup.description"),
+      input: { hint: t("cleanup.inputHint") },
+      handler: (invocation) => handleSnapshotCleanup(store, invocation)
+    });
   }, "dsh-rewind command");
   ctx.on("session/event", (session, event) => {
     if (event.type !== "user/message") return;
@@ -816,18 +1751,14 @@ function apply(ctx, config) {
     void (async () => {
       try {
         const sessionId = session.id;
+        void maybeRunAutoCleanup(ctx, store, sessionId);
         let tracked = trackedBySession.get(sessionId);
         if (tracked === void 0) {
           tracked = await store.trackedPaths(sessionId);
           trackedBySession.set(sessionId, tracked);
         }
         if (tracked.size === 0) return;
-        let states = statesBySession.get(sessionId);
-        if (states === void 0) {
-          states = /* @__PURE__ */ new Map();
-          statesBySession.set(sessionId, states);
-        }
-        await reconcileTracked(store, sessionId, event.seq, tracked, states);
+        await reconcileTracked(store, sessionId, event.seq, tracked);
       } catch (error) {
         ctx.logger.warn(`[dsh-rewind] boundary re-check failed: ${error instanceof Error ? error.message : String(error)}`);
       }
@@ -846,6 +1777,7 @@ function apply(ctx, config) {
     });
     scope.on("tools/post-execute", async (exec, result, next) => {
       try {
+        void maybeRunAutoCleanup(ctx, store, exec.agent?.session?.id);
         await commitEntry(store, pending, anchorCache, trackedBySession, exec, result);
       } catch (error) {
         ctx.logger.warn(`[dsh-rewind] checkpoint commit failed for ${exec.name}: ${error instanceof Error ? error.message : String(error)}`);