dsh-rewind-plugin 0.4.2 → 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 = {}) {
@@ -201,6 +235,9 @@ 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 {
@@ -242,13 +279,19 @@ 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;
   }
@@ -261,9 +304,42 @@ 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). */
@@ -282,6 +358,18 @@ var SnapshotStore = class _SnapshotStore {
    * 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));
@@ -290,26 +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 (atomic write). */
+  /** 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 };
-    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 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
@@ -379,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) {
@@ -436,8 +603,9 @@ var SnapshotStore = class _SnapshotStore {
     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);
+    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++) {
@@ -840,8 +1008,21 @@ var SnapshotStore = class _SnapshotStore {
    * 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 {
@@ -854,7 +1035,34 @@ var SnapshotStore = class _SnapshotStore {
     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 });
     }
   }
@@ -889,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
@@ -906,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 {
@@ -930,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"];
@@ -1237,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"));
@@ -1257,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;
@@ -1265,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)}`);
       }
@@ -1295,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)}`);